Registry / node-osascript

node-osascript

library2.1.0jsnpmunverified

node-osascript is a utility library for Node.js that enables the execution of AppleScript code directly from JavaScript. It facilitates bidirectional communication by allowing JavaScript variables to be injected into AppleScript and by transforming AppleScript results (lists, records, dates, numbers, booleans, strings) into their corresponding JavaScript data types using PEG.js. The current stable version is 2.1.0, last published over 8 years ago. While the release cadence is not explicitly stated, the project appears to be in a maintenance or abandoned phase given its age. Its key differentiator is the automatic, structured type conversion of AppleScript results into native JavaScript objects, simplifying data handling compared to raw `exec` calls, which typically return plain strings.

npm install node-osascript

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-OSASCRIPT

node-osascript

javascriptv2.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

osascript

✓ import osascript from 'node-osascript';

✗ const { execute } = require('node-osascript');

The package primarily exports a default object via CommonJS. For ESM contexts, a default import is typically used, or direct `require` with `createRequire` if needed for older Node.js versions or complex CJS/ESM interop.

execute

✓ const osascript = require('node-osascript'); osascript.execute('...', (err, result) => { /* ... */ });

✗ import { execute } from 'node-osascript';

The `execute` function is a method on the default exported `osascript` object, not a named export. Attempting to destructure it as a named export will result in a TypeError.

executeFile

✓ const osascript = require('node-osascript'); osascript.executeFile('path/to/script.scpt', (err, result) => { /* ... */ });

✗ import { executeFile } from 'node-osascript';

Similar to `execute`, `executeFile` is a method on the default `osascript` object. It's used for running external AppleScript files.

Demonstrates executing AppleScript with dynamically injected JavaScript variables, handling asynchronous results, and basic error trapping. This showcases the core `execute` method and variable passing.

import osascript from 'node-osascript'; async function runAppleScriptWithVariables() { const username = process.env.USER ?? 'Guest'; const message = `Hello, ${username}! The current time is now:`; const script = ` on run {message} set currentTime to (current date) as text display dialog (message & "\n" & currentTime) with title "Node-osascript Demo" buttons {"OK"} default button "OK" set dialogResult to result return "User clicked " & (button returned of dialogResult) & ". Script completed at " & currentTime end run `; try { console.log(`Executing AppleScript on behalf of ${username}...`); const [result, raw] = await new Promise((resolve, reject) => { osascript.execute(script, { message }, (err, res, rawRes) => { if (err) return reject(err); resolve([res, rawRes]); }); }); console.log("Parsed Result:", result); // e.g., "User clicked OK. Script completed at..." console.log("Raw AppleScript Output:", raw); // Full stdout from osascript } catch (error) { console.error("AppleScript execution failed:", error); if (error.code === 1) { console.error("Hint: This often means a syntax error in your AppleScript or a permission issue."); } } } runAppleScriptWithVariables();

Debug

Known issues

gotchaThis package relies on `osascript` and is therefore macOS-only. It will not function on Windows, Linux, or other operating systems.

fix

Ensure your application environment is macOS. For cross-platform desktop applications, consider alternatives like Electron's `shell.openExternal` or native OS APIs for basic tasks.

affects: >=1.0.0

gotchaThe library primarily uses a CommonJS module system (i.e., `require`). While Node.js generally supports `require` in ESM contexts, direct `import osascript from 'node-osascript'` might require specific Node.js configuration or transpilation depending on your setup and Node.js version.

fix

For older Node.js or strict ESM environments, use `const osascript = require('node-osascript');` or investigate dynamic `import()` or `createRequire` for explicit CJS interop.

affects: <=2.1.0

gotchaInjecting unsanitized user input directly into AppleScript strings can lead to command injection vulnerabilities, allowing malicious users to execute arbitrary commands.

fix

Always sanitize or escape any user-provided data before incorporating it into AppleScript strings. Prefer passing data via the `variables` object where possible, as it typically handles escaping.

affects: >=1.0.0

breakingAs a legacy library, `node-osascript` relies on older Node.js APIs and callback-based error handling. It does not natively support Promises or async/await, which are standard in modern Node.js development.

fix

Wrap `osascript.execute` and `osascript.executeFile` in a `new Promise()` to enable `async/await` usage, as demonstrated in the quickstart example. Consider newer alternatives like `@7c/osascript` for native Promise support.

affects: <=2.1.0

gotchaThe `osascript` process itself can sometimes hang or take a long time to execute. The package provides a manual `childProcess.kill()` mechanism for timeouts, which is a blunt instrument and may not gracefully handle script state.

fix

Implement robust timeout logic around your `osascript.execute` calls, using `Promise.race` with a `setTimeout` for `async/await` patterns. Be aware that killing the process might leave applications in an undesirable state.

affects: >=1.0.0

Errors

Common errors & fixes

Error: spawn osascript ENOENT

The `osascript` command-line tool, which is part of macOS, could not be found in the system's PATH. This typically happens when running on a non-macOS system, or if the PATH environment variable is misconfigured.

fix

Ensure your application is running on a macOS environment. Verify that `/usr/bin/osascript` exists and is accessible, and that `/usr/bin` is included in your system's PATH. If on a server, confirm macOS is the OS.

TypeError: osascript.execute is not a function

This usually indicates an incorrect import or require statement. The `node-osascript` package exports a single object, and `execute` is a method on that object, not a named export.

fix

Use `const osascript = require('node-osascript');` (CommonJS) or `import osascript from 'node-osascript';` (ESM) and then call `osascript.execute(...)`.

Error: Command failed: osascript ... (with AppleScript syntax error)

The AppleScript code passed to `execute` or `executeFile` contains a syntax error, or refers to an application/element that does not exist on the system.

fix

Carefully review your AppleScript for syntax errors. Test the script directly in Script Editor on macOS to debug any issues before incorporating it into your Node.js code. Ensure applications targeted by the script are installed and running.

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/FWeinb/node-osascript ↗

packagehttps://www.npmjs.com/package/node-osascript ↗