osascript-tag

A JavaScript template literal tag that executes AppleScript and other OSA (Open Scripting Architecture) scripts.

Compatible with JXA (JavaScript for Automation).

✨ Now supports ES Modules! Updated for modern Node.js with full TypeScript support.

Why?

> Every time I get a script it's a matter of trying to know what I could do with it. I see colors, imagery. It has to have a smell. It's like falling in love. You can't give a reason why.
>
> — Paul Newman

Installation

To get started, add osascript-tag to your project:

``bash
npm install osascript-tag
`

Requirements

- Node.js 14+ - This package now uses modern JavaScript features
- macOS - Required for running OSA scripts
- TypeScript 5.0+ (optional) - Full TypeScript support included

Usage

$3

Import using modern ES module syntax:

`js
import osascript, { jxa } from 'osascript-tag';

async function main() {
const result = await osascript
tell application "System Events"
return name of current user
end tell
;
console.log('Current user:', result);
}
`

$3

Still supported for backward compatibility:

`js
const osascript = require('osascript-tag');

async function main() {
const result = await osascript
tell application "iTunes"
get { artist, name } of current track
end tell
;

console.log(result); // "King Gizzard & The Lizard Wizard, This Thing"
}
`

$3

It can be used as template literal tag to asynchronously run an AppleScript within your code. It returns a promise that resolves with the output of the script, and rejects with an error if running the script was not successful.

`js
// ES Modules
import osascript from 'osascript-tag';

async function main() {
const result = await osascript
tell application "iTunes"
get { artist, name } of current track
end tell
;

console.log(result); // "King Gizzard & The Lizard Wizard, This Thing"
}
`

$3

You can interpolate values into your AppleScript code using template literals:

`js
import osascript from 'osascript-tag';

async function getAppInfo(appName) {
const result = await osascript
tell application "${appName}"
return name & " version " & version
end tell
;
return result.trim();
}

const finderInfo = await getAppInfo('Finder');
console.log(finderInfo); // "Finder version 10.15.7"
`

$3

To run a JXA (JavaScript for Automation) script, use the osascript.jxa template tag (also available as the named export: jxa) . Please note that osascript.jxa requires macOS 10.10 or greater.

`js
// ES Modules
import osascript, { jxa } from 'osascript-tag';

async function main() {
// Using osascript.jxa
await osascript.jxa
const app = Application.currentApplication();
app.includeStandardAdditions = true;
app.displayNotification("All graphics have been converted.", {
withTitle: "My Graphic Processing Script",
subtitle: "Processing is complete.",
soundName: "Glass",
});
;

// Or using the named export
await jxa
Application('System Events').currentUser.name();
;
}
`

$3

By default all calls to osascript.jxa will resolve with the stdout result as a string.

If your script, however, is expected to return parsable values, you can pass a parse option to osascript.jxa to return parsed values ready for consumption in your JavaScript code.

`js
// ES Modules
import { jxa } from 'osascript-tag';

async function main() {
const { artist, title } = await jxa({ parse: true })
const iTunes = Application('iTunes');
return {
artist: iTunes.currentTrack.artist(),
title: iTunes.currentTrack.name(),
}
;

console.log(artist); // "King Gizzard & The Lizard Wizard"
console.log(title); // "This Thing"
}
`

API

The osascript-tag can be used in one of the following ways:

ES Modules:
- import osascript from 'osascript-tag' - Default export
- import { jxa } from 'osascript-tag' - Named export for JXA

API Methods:
- osascript
- osascript(options: Options)
- osascript.jxa / jxa
- osascript.jxa(options: JXAOptions) / jxa(options: JXAOptions)

$3

Executes the given OSA script.

##### Example

`js
// ES Modules
import osascript from 'osascript-tag';

const result = await osascript
tell application "Finder"
name of every file of the desktop
end tell
;

// CommonJS (legacy)
const osascript = require('osascript-tag');
const result = await osascript...;
`

##### Arguments

1. script: string - A string repressing the AppleScript code to execute
2. ...replacements: any[] - The replacements values

##### Returns

A Promise that resolves with the script's standard output, or rejects with an error if the scripts was not successful.

$3

Executes the given OSA script with custom options.

##### Example

`js
const result = await osascript({ flags: 'so' })
tell application "Finder"
name of every file of the desktop
end tell
;
`

##### Arguments

1. options: Options - An object with the following keys:
- flags?: string - The flags used to modify the output of the script. It is a string consisting of any of the of the modifier characters e, h, o, and s. Defaults to "eh". The meanings of the modifier characters are as follows:
- h Return values in human-readable form (default).
- s Return values in recompilable source form.
- e Redirect script errors to stderr (default)
- o Redirect script errors to stdout.
- language?: string - The language of the OSA script to be executed. Defaults to "AppleScript".

##### Returns

An instance of osascript configured with the provided options.

$3

A convenient wrapper for osascript configured to run JXA.

##### Example

`js
await osascript.jxa
const app = Application.currentApplication();
app.includeStandardAdditions = true;
app.displayAlert('This is a message');
;
`

##### Returns

An instance of osascript configured to run JXA.

$3

Executes a JXA script with custom options.

##### Example

`js
const result = await osascript.jxa({ parse: true })
const app = Application('iTunes');
return {
artist: app.currentTrack.artist(),
title: app.currentTrack.name(),
};
;
`

##### Arguments

1. options: JXAOptions - An object with the following keys:
- flags?: string - The flags used to modify the output of the script. It is a string consisting of any of the of the modifier characters e, h, o, and s. Defaults to "eh". The meanings of the modifier characters are as follows:
- h Return values in human-readable form (default).
- s Return values in recompilable source form.
- e Redirect script errors to stderr (default)
- o Redirect script errors to stdout.
- parse?: boolean - A boolean indicating whether the standard output of the script is parsed for consumption in JavaScript. This uses JSON.parse under the hood. Note that setting this option to true will automatically set the flags option to "se" if not set explicitly otherwise. Defaults to false.
- argv?: any[] - An array of arguments to be passed to the script. This array will be available in the JXA script itself as a global variable argv. Please note that all values will be serialized to strings.

##### Returns

An instance of osascript` configured to run JXA with custom options.

Licence

MIT