applescript-node 1.0.1

package/dist/compiler.d.ts

@@ -0,0 +1,15 @@
+export interface CompileOptions {
+    language?: 'AppleScript' | 'JavaScript';
+    executeOnly?: boolean;
+    stayOpen?: boolean;
+    useStartupScreen?: boolean;
+    outputPath?: string;
+    bundleScript?: boolean;
+}
+export interface CompileResult {
+    success: boolean;
+    outputPath: string;
+    error?: string;
+}
+export declare function compileScript(script: string, options?: CompileOptions): Promise<CompileResult>;
+export declare function compileScriptFile(filePath: string, options?: CompileOptions): Promise<CompileResult>;

package/dist/decompiler.d.ts

@@ -0,0 +1,6 @@
+export interface DecompileResult {
+    success: boolean;
+    source?: string;
+    error?: string;
+}
+export declare function decompileScript(scriptPath: string): Promise<DecompileResult>;

package/dist/executor.d.ts

@@ -0,0 +1,97 @@
+import type { OsaScriptOptions, ScriptExecutionResult } from './types.js';
+/**
+ * ScriptExecutor - Core execution engine for AppleScript and JavaScript
+ *
+ * **IMPORTANT: Error Handling**
+ *
+ * This class implements robust error handling that is critical for production use:
+ *
+ * 1. **Type-Safe Error Extraction**: Errors from `child_process.exec` can be various types
+ *    (Error objects, ErrnoException, etc.). The error handling properly extracts:
+ *    - Error messages from Error instances or converts other types to strings
+ *    - Exit codes from ErrnoException.code (which can be string or number)
+ *    - Defaults to exit code 1 if code is missing or invalid
+ *
+ * 2. **Exit Code Handling**: The exit code extraction handles three cases:
+ *    - String codes: Parsed with parseInt (e.g., "1" -> 1)
+ *    - Number codes: Used directly
+ *    - Missing/null codes: Defaults to 1
+ *
+ * 3. **Why This Matters**: Without proper error handling:
+ *    - TypeScript would allow unsafe type assertions
+ *    - Runtime errors could occur when accessing error.code
+ *    - Exit codes might be undefined, causing downstream issues
+ *
+ * **Usage Example:**
+ * ```typescript
+ * const result = await ScriptExecutor.execute('tell app "Finder" to activate');
+ * if (!result.success) {
+ *   console.error(`Script failed with exit code ${result.exitCode}: ${result.error}`);
+ * }
+ * ```
+ *
+ * **Testing Considerations:**
+ * - Always test both success and failure paths
+ * - Mock different error types (Error, ErrnoException, etc.)
+ * - Verify exit codes are correctly extracted and defaulted
+ * - Ensure error messages are properly extracted regardless of error type
+ *
+ * @see {@link ScriptExecutionResult} for the result structure
+ * @see {@link OsaScriptOptions} for execution options
+ */
+export declare class ScriptExecutor {
+    private static buildFlags;
+    /**
+     * Execute an AppleScript or JavaScript string
+     *
+     * **Error Handling:**
+     * This method implements comprehensive error handling that safely extracts:
+     * - Error messages from any error type (Error, ErrnoException, etc.)
+     * - Exit codes with proper type checking and defaults
+     *
+     * **Important Notes:**
+     * - Script strings are automatically escaped for shell safety
+     * - Single quotes in scripts are escaped using the pattern: `'` -> `'"'"'`
+     * - Always returns a result object, never throws (errors are captured in result)
+     *
+     * @param script - The AppleScript or JavaScript code to execute
+     * @param options - Execution options (language, output format, etc.)
+     * @returns Promise resolving to execution result with success flag, output, error, and exit code
+     *
+     * @example
+     * ```typescript
+     * const result = await ScriptExecutor.execute('tell app "Finder" to get name');
+     * if (result.success) {
+     *   console.log(result.output); // "Finder"
+     * } else {
+     *   console.error(`Failed: ${result.error} (exit code: ${result.exitCode})`);
+     * }
+     * ```
+     */
+    static execute<T = string>(script: string, options?: OsaScriptOptions): Promise<ScriptExecutionResult<T>>;
+    /**
+     * Execute an AppleScript or JavaScript file
+     *
+     * **Error Handling:**
+     * Uses the same robust error handling as `execute()` method.
+     * See {@link ScriptExecutor.execute} for details on error handling patterns.
+     *
+     * **Important Notes:**
+     * - File paths are passed directly to osascript (no shell escaping needed)
+     * - File must exist and be readable
+     * - Always returns a result object, never throws
+     *
+     * @param filePath - Path to the script file (.applescript, .scpt, etc.)
+     * @param options - Execution options (language, output format, etc.)
+     * @returns Promise resolving to execution result with success flag, output, error, and exit code
+     *
+     * @example
+     * ```typescript
+     * const result = await ScriptExecutor.executeFile('./scripts/my-script.applescript');
+     * if (result.success) {
+     *   console.log(result.output);
+     * }
+     * ```
+     */
+    static executeFile<T = string>(filePath: string, options?: OsaScriptOptions): Promise<ScriptExecutionResult<T>>;
+}

package/dist/expressions.d.ts

@@ -0,0 +1,252 @@
+/**
+ * ExprBuilder provides a type-safe DSL for building AppleScript expressions.
+ * Instead of writing raw strings like: `if('counter > 10')`
+ * You can write: `if(expr => expr.gt('counter', 10))`
+ *
+ * This enables:
+ * - Type checking and autocomplete for variables in scope
+ * - Prevention of common syntax errors
+ * - Composable expressions
+ * - Self-documenting code
+ *
+ * @template TScope - Union of variable names available in the current scope.
+ *   When used within loop callbacks like `forEach`, this will include loop variables
+ *   like 'aPerson', 'aNote', etc., enabling autocomplete for them.
+ *
+ * @example
+ * // Basic usage with scoped variable
+ * .forEach('aPerson', 'every person', (b) => {
+ *   b.ifThen(
+ *     (e) => e.gt(e.count(e.property('aPerson', 'emails')), 0),
+ *     //                             ^^^^^^^^ 'aPerson' gets autocomplete!
+ *     (then_) => then_.setExpression('email', (e) =>
+ *       e.valueOfItem(1, e.property('aPerson', 'emails'))
+ *     )
+ *   );
+ * })
+ *
+ * @example
+ * // Nested loops with multiple scoped variables
+ * .forEach('anAccount', 'every account', (outer) => {
+ *   outer.forEach('aNote', 'notes of anAccount', (inner) => {
+ *     // Both 'anAccount' and 'aNote' are in scope here
+ *     inner.setExpression('accountName', (e) => e.property('anAccount', 'name'));
+ *     inner.setExpression('noteName', (e) => e.property('aNote', 'name'));
+ *   });
+ * })
+ */
+export declare class ExprBuilder<TScope extends string = never> {
+    /**
+     * Greater than comparison: left > right
+     * @param left - Variable or expression. Scoped variables (from loops) get autocomplete.
+     *   The type `TScope | (string & Record<never, never>)` provides autocomplete for scoped
+     *   variables while still accepting any string expression.
+     * @param right - Value to compare against (string or number)
+     * @returns AppleScript expression: "left > right"
+     * @example
+     * e.gt('counter', 10)  // => "counter > 10"
+     * e.gt('aPerson', 5)   // => "aPerson > 5" (with autocomplete for 'aPerson' if in scope)
+     */
+    gt(left: TScope | (string & Record<never, never>), right: string | number): string;
+    /**
+     * Less than comparison: left < right
+     * @param left - Variable or expression (scoped variables get autocomplete)
+     */
+    lt(left: TScope | (string & Record<never, never>), right: string | number): string;
+    /**
+     * Greater than or equal: left >= right
+     * @param left - Variable or expression (scoped variables get autocomplete)
+     */
+    gte(left: TScope | (string & Record<never, never>), right: string | number): string;
+    /**
+     * Less than or equal: left <= right
+     * @param left - Variable or expression (scoped variables get autocomplete)
+     */
+    lte(left: TScope | (string & Record<never, never>), right: string | number): string;
+    /**
+     * Equality comparison: left = right
+     * @param left - Variable or expression (scoped variables get autocomplete)
+     */
+    eq(left: TScope | (string & Record<never, never>), right: string | number | boolean): string;
+    /**
+     * Inequality comparison: left is not equal to right
+     * @param left - Variable or expression (scoped variables get autocomplete)
+     */
+    ne(left: TScope | (string & Record<never, never>), right: string | number | boolean): string;
+    /**
+     * Logical AND: combines multiple conditions
+     * Example: expr.and(expr.gt('x', 5), expr.lt('x', 10))
+     */
+    and(...conditions: string[]): string;
+    /**
+     * Logical OR: combines multiple conditions
+     * Example: expr.or(expr.eq('status', 'done'), expr.eq('status', 'skipped'))
+     */
+    or(...conditions: string[]): string;
+    /**
+     * Logical NOT: negates a condition
+     * Example: expr.not(expr.eq('status', 'pending'))
+     */
+    not(condition: string): string;
+    /**
+     * String length: length of str
+     * Often used in conditions like: expr.gt(expr.length('name'), 5)
+     */
+    length(str: string): string;
+    /**
+     * Property access: prop of obj
+     * @param obj - Variable name. Scoped variables (from loops) get autocomplete.
+     *   The type allows both scoped variables and arbitrary string expressions.
+     * @param prop - Property name to access
+     * @returns AppleScript expression: "prop of obj"
+     * @example
+     * e.property('aNote', 'name')      // => "name of aNote"
+     * e.property('aPerson', 'emails')  // => "emails of aPerson" (with autocomplete for 'aPerson')
+     */
+    property(obj: TScope | (string & Record<never, never>), prop: string): string;
+    /**
+     * Count: count of items
+     * Example: expr.gt(expr.count('notes'), 10)
+     */
+    count(items: string): string;
+    /**
+     * Existence check: exists item
+     * Example: expr.exists('window "Settings"')
+     */
+    exists(item: string): string;
+    /**
+     * String contains: haystack contains needle
+     * Example: expr.contains('name', '"test"')
+     */
+    contains(haystack: string, needle: string | number): string;
+    /**
+     * String starts with: str begins with prefix
+     * Example: expr.startsWith('name', '"John"')
+     */
+    startsWith(str: string, prefix: string): string;
+    /**
+     * String ends with: str ends with suffix
+     * Example: expr.endsWith('name', '"son"')
+     */
+    endsWith(str: string, suffix: string): string;
+    /**
+     * Type checking: the type of item is typeName
+     * Common types: 'text', 'number', 'list', 'record', 'boolean'
+     */
+    typeEquals(item: string, type: string): string;
+    /**
+     * Matches wildcard pattern
+     * Example: expr.matches('name', '"*Smith*"')
+     */
+    matches(str: string, pattern: string): string;
+    /**
+     * Parentheses for explicit grouping
+     * Useful when combining complex boolean expressions
+     * Example: expr.or(expr.paren(expr.and(...)), expr.eq(...))
+     */
+    paren(condition: string): string;
+    /**
+     * Create a comparison between two expressions
+     * Useful for comparing two computed properties
+     * Example: expr.compare('length of name1', '>', 'length of name2')
+     */
+    compare(left: string, operator: '>' | '<' | '>=' | '<=' | '=' | '!=', right: string): string;
+    /**
+     * Collection accessor: every element of container
+     * Example: expr.every('participant', 'aChat') => "every participant of aChat"
+     * Example: expr.every('note', 'folder "Notes"') => "every note of folder \"Notes\""
+     */
+    every(element: string, container: string): string;
+    /**
+     * Nested property accessor: chains multiple properties
+     * Example: expr.nestedProperty('aChat', 'account', 'id') => "id of account of aChat"
+     * Example: expr.nestedProperty('note', 'folder', 'name') => "name of folder of note"
+     * @param obj - Variable name (scoped variables get autocomplete)
+     */
+    nestedProperty(obj: TScope | (string & Record<never, never>), ...properties: string[]): string;
+    /**
+     * Type casting: expression as type
+     * Example: expr.asType('creation date of aNote', 'string') => "creation date of aNote as string"
+     * Example: expr.asType(expr.property('aNote', 'id'), 'text') => "id of aNote as text"
+     */
+    asType(expression: string, type: 'string' | 'text' | 'number' | 'integer' | 'list'): string;
+    /**
+     * Substring/range accessor: text start thru end of source
+     * Example: expr.text(1, 100, 'notePlaintext') => "text 1 thru 100 of notePlaintext"
+     * Example: expr.text(5, 10, 'myString') => "text 5 thru 10 of myString"
+     */
+    text(start: number, end: number, source: string): string;
+    /**
+     * Character accessor: character n of source
+     * Example: expr.character(1, 'myString') => "character 1 of myString"
+     */
+    character(index: number, source: string): string;
+    /**
+     * Item accessor: item n of collection
+     * Example: expr.item(1, 'myList') => "item 1 of myList"
+     * Example: expr.item('i', 'notes') => "item i of notes"
+     */
+    item(index: number | string, collection: string): string;
+    /**
+     * Items range: items start thru end of collection
+     * Example: expr.items(1, 5, 'myList') => "items 1 thru 5 of myList"
+     */
+    items(start: number, end: number, collection: string): string;
+    /**
+     * First item: first element of collection
+     * Example: expr.first('note', 'notes') => "first note of notes"
+     */
+    first(element: string, collection: string): string;
+    /**
+     * Last item: last element of collection
+     * Example: expr.last('note', 'notes') => "last note of notes"
+     */
+    last(element: string, collection: string): string;
+    /**
+     * Some: some element where condition
+     * Example: expr.some('note', 'notes', 'name contains "test"')
+     */
+    some(element: string, collection: string, condition: string): string;
+    /**
+     * Filter: every element where condition
+     * Example: expr.filter('note', 'notes', 'shared = true')
+     */
+    filter(element: string, collection: string, condition: string): string;
+    /**
+     * Concatenation: left & right
+     * Example: expr.concat('text 1 thru 50 of body', '"..."') => 'text 1 thru 50 of body & "..."'
+     */
+    concat(...parts: string[]): string;
+    /**
+     * Property of item accessor: property of item N of collection
+     * Example: expr.propertyOfItem('value', 1, 'emails of aPerson') => "value of item 1 of emails of aPerson"
+     * Example: expr.propertyOfItem('name', 1, 'contacts') => "name of item 1 of contacts"
+     */
+    propertyOfItem(property: string, index: number | string, collection: string): string;
+    /**
+     * Value of item accessor (common shorthand for propertyOfItem('value', ...))
+     * Example: expr.valueOfItem(1, 'emails of aPerson') => "value of item 1 of emails of aPerson"
+     * Example: expr.valueOfItem(1, 'phones of contact') => "value of item 1 of phones of contact"
+     */
+    valueOfItem(index: number | string, collection: string): string;
+}
+/**
+ * Factory function for creating an ExprBuilder with type-tracked scope.
+ * This is typically not needed as callbacks receive an ExprBuilder instance automatically.
+ *
+ * @template TScope - Union of variable names available in the current scope.
+ *   TypeScript will infer this from loop contexts automatically.
+ * @returns ExprBuilder instance with scope tracking
+ *
+ * @example
+ * // Usually you don't need to call this - use callbacks instead:
+ * .forEach('aPerson', 'every person', (b) => {
+ *   b.ifThen((e) => e.gt('counter', 10), ...) // 'e' provided automatically
+ * })
+ *
+ * @example
+ * // Manual usage (rare):
+ * const e = expr<'myVar' | 'anotherVar'>();
+ * e.property('myVar', 'name'); // 'myVar' gets autocomplete
+ */
+export declare function expr<TScope extends string = never>(): ExprBuilder<TScope>;

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import { AppleScriptBuilder } from './builder.js';
+import type { OsaScriptOptions, Prettify, ScriptBuilder, ScriptExecutionResult } from './types.js';
+export * from './builder.js';
+export * from './compiler.js';
+export * from './decompiler.js';
+export * from './executor.js';
+export * from './expressions.js';
+export * from './languages.js';
+export * from './loader.js';
+export * from './sdef.js';
+export * as sources from './sources/index.js';
+export type { AppleScriptValue, ApplicationDictionary, ApplicationTarget, Class, Command, Element, Enumeration, Enumerator, OsaScriptOptions, Parameter, Prettify, ProcessInfo, Property, PropertyExtractor, ScriptBuilder, ScriptError, ScriptExecutionResult, Suite, TypeInfo, WindowInfo, } from './types.js';
+export * from './validator.js';
+export declare const createScript: () => AppleScriptBuilder;
+export declare function runScript<TScope extends string, TReturn>(script: ScriptBuilder<TScope, TReturn>, options?: OsaScriptOptions): Promise<ScriptExecutionResult<Prettify<TReturn>>>;
+export declare function runScript<T = string>(script: string, options?: OsaScriptOptions): Promise<ScriptExecutionResult<Prettify<T>>>;
+export declare const runScriptFile: <T = string>(filePath: string, options?: OsaScriptOptions) => Promise<ScriptExecutionResult<T>>;