@avavilov/apple-script

Type-safe AppleScript execution library for Node.js with Zod validation. Execute AppleScript operations with full TypeScript support, automatic input/output validation, and proper error handling.

Features

- 🔒 Type-Safe: Full TypeScript support with compile-time type checking
- ✅ Validation: Input/output validation using Zod schemas
- 🎯 Declarative API: Define operations once, use everywhere
- 🔄 Queue Management: Automatic serialization of operations per application
- 🧹 Automatic Normalization: Best-effort, schema-guided normalization of rows output (numbers/booleans/arrays/tuples/objects)
- ⚡ Protocol Standardization: Consistent encoding/decoding with control characters (see the Protocol)
- 🛡️ Security: Safe parameter marshalling prevents injection attacks
- 📊 Observable: Debug hooks, result callbacks, and error handlers
- ⏱️ Timeout Control: Dual timeout system (AppleScript + Node.js)
- 🔁 Retry Logic: Configurable retry mechanism for transient failures

Note: This library is macOS-only as AppleScript is an Apple technology. For cross-platform automation, consider using tools like Playwright or Puppeteer.

Installation

``bash
npm install @avavilov/apple-script zod
`

Quick Start

`typescript
import { z } from 'zod';
import { createAppleRunner, operation } from '@avavilov/apple-script';

// Define an operation
const getCurrentURL = operation.scalar({
name: 'getCurrentURL',
input: z.object({}),
output: z.string(),
script: () =>
return URL of active tab of front window

});

// Create a runner
const runner = createAppleRunner({
appId: 'com.apple.Safari'
});

// Execute the operation
const result = await runner.run(getCurrentURL, {});
if (result.ok) {
console.log('Current URL:', result.data);
} else {
console.error('Error:', result.error.message);
}
`

Core Concepts

$3

Operations are declarative descriptions of AppleScript tasks with strict input/output contracts:

`typescript
const openURL = operation.action({
name: 'openURL',
input: z.object({
url: z.string().url()
}),
script: ({ url }) =>
try
open location ${url}
return "1"
on error
return "0"
end try

});
`

$3

#### 1. Scalar Operations
Return a single string value (see Protocol: scalar):

`typescript
const getTitle = operation.scalar({
name: 'getTitle',
input: z.object({ windowIndex: z.number() }),
output: z.string(),
script: ({ windowIndex }) =>
return title of window ${windowIndex}

});
`

#### 2. Action Operations
Return status codes (0=failure, 1=success, 2=partial) (see Protocol: action):

`typescript
const closeTab = operation.action({
name: 'closeTab',
input: z.object({ tabId: z.string() }),
script: ({ tabId }) =>
repeat with w in windows
repeat with t in tabs of w
if (id of t as text) is ${tabId} then
try
close t
return "1"
on error
return "0"
end try
end if
end repeat
end repeat
return "0"

});
`

#### 3. Rows Operations
Return tabular data as array of objects (encoded with RS/US separators; see Protocol: rows):

`typescript
const listTabs = operation.rows({
name: 'listTabs',
input: z.object({}),
output: z.array(z.object({
id: z.string(),
url: z.string(),
title: z.string()
})),
script: () =>
set rows to {}
repeat with w in windows
repeat with t in tabs of w
set end of rows to {(id of t as text), URL of t, title of t}
end repeat
end repeat
return rows

});
`

##### Rows → Objects Mapping
The runner automatically maps rows (string arrays) to objects based on:
1. mapRow function if provided (highest priority)
2. columns array if provided (explicit column names)
3. Zod schema inference from output: z.array(z.object({...}))

`typescript
// Explicit columns (recommended for clarity)
const listTabs = operation.rows({
name: 'listTabs',
columns: ['id', 'url', 'title'], // Maps row[0]→id, row[1]→url, row[2]→title
output: z.array(z.object({
id: z.coerce.number(),
url: z.string().url(),
title: z.string()
})),
script: () => ...
});

// Custom mapping function
const listTabsWithDomain = operation.rows({
name: 'listTabsWithDomain',
mapRow: ([id, url, title]) => ({
id,
title,
domain: new URL(url).hostname
}),
output: z.array(z.object({
id: z.string(),
title: z.string(),
domain: z.string()
})),
script: () => ...
});
`

Note: Row mapping happens before output validation, ensuring consistent behavior regardless of validation settings. See Troubleshooting for common issues.

##### Automatic normalization (rows)
After mapping rows to objects, the runner can automatically normalize stringly-typed values to match your output schema. This is a best-effort, schema-guided step that handles:

- numbers: "42" → 42
- booleans: "true"/"false"/"1"/"0" → true/false
- arrays: "{1, 2, 3}" or "1,2,3" → [1, 2, 3]
- tuples: "{a, b, c}" → [a, b, c]
- objects: recursively normalizes fields using the object shape

Toggles:
- Global: RunnerConfig.normalizeRows (default: true)
- Per-operation: RowsOperationDef.normalizeRows (overrides global)

Example with AppleScript-aware helper schemas:

`ts
import { z } from 'zod';
import { operation, schemas as as } from '@avavilov/apple-script';

const listTabs = operation.rows({
name: 'listTabs',
columns: ['id', 'url', 'title', 'active', 'bounds', 'indices'],
// as.record wraps number/boolean fields to accept AppleScript string representations
// and enforces strict validation by default (unknown keys are rejected)
// You may also use explicit helpers like as.boolean/as.number
output: z.array(as.record({
id: z.string(),
url: z.string().url(),
title: z.string(),
active: as.boolean, // "true" → true, "0" → false
bounds: as.array(as.number) // "{0, 0, 800, 600}" → [0, 0, 800, 600]
})).describe('List of tabs')
});

// You can disable/enable normalization:
// const runner = createAppleRunner({ appId, normalizeRows: true });
// Or per operation: operation.rows({ normalizeRows: false, ... })
`

#### 4. Sections Operations
Return grouped data with named sections (see Protocol: sections):

`typescript
const closeTabs = operation.sections({
name: 'closeTabs',
input: z.object({ ids: z.array(z.string()) }),
output: z.record(z.array(z.string())),
script: ({ ids }) =>
set closedList to {}
set notFoundList to {}
-- close tabs logic here --
return {{"closed", closedList}, {"notFound", notFoundList}}

});
`

$3

`typescript
const runner = createAppleRunner({
// Required
appId: 'com.apple.Safari',

// Timeouts
defaultTimeoutSec: 12, // AppleScript timeout
defaultControllerTimeoutMs: 15000, // Node.js timeout
timeoutByKind: {
scalar: 10,
action: 8,
rows: 15,
sections: 15
},

// Behavior
ensureAppReady: true, // Launch app if not running
validateByDefault: true, // Validate input/output
normalizeRows: true, // Normalize rows to schema (numbers/booleans/arrays/tuples/objects)
maxRetries: 2, // Retry on timeout
retryDelayMs: 1000, // Delay between retries

// Hooks
debug: ({ opName, script }) => {
console.log([${opName}] Script:, script);
},
onResult: ({ opName, tookMs }) => {
console.log([${opName}] Completed in ${tookMs}ms);
},
onError: ({ opName, error }) => {
console.error([${opName}] Failed:, error.message);
}
});
`

Note: The runner serializes operations per appId using an internal QueueManager. Each appId has its own FIFO queue. Queue semantics (microtask scheduling, clear() epoch cut-off, and the length property) apply per appId queue. See: src/queue/README.md.

Protocol Details

- Success: OK
- Error: ERR

$3

- -1712: AppleScript timeout
- -10001: Missing return value
- -10002: Invalid return type for rows
- -10003: Invalid return type for sections
- -10004: Invalid action code
- -10005: Invalid return type for scalar

Security

$3

All parameters are safely marshalled as AppleScript literals:

`typescript
// Your input
{ url: 'https://example.com', ids: ['1', '2', '3'] }

// Becomes AppleScript variables
set __ARG__url to "https://example.com"
set __ARG__ids to {"1", "2", "3"}
`

$3

String values are properly escaped:

`typescript
// Input with quotes
{ message: 'Hello "World"' }

// Safe AppleScript literal
set __ARG__message to "Hello " & quote & "World" & quote & ""
`

Advanced Usage

$3