{"id":22400380,"url":"https://github.com/7c/osascript","last_synced_at":"2025-10-19T06:11:27.044Z","repository":{"id":264176523,"uuid":"892596899","full_name":"7c/osascript","owner":"7c","description":"AppleScript/osascript wrapper for Typescript/NodeJS","archived":false,"fork":false,"pushed_at":"2024-11-22T12:18:19.000Z","size":7,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-01T05:42:49.115Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/7c.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-22T12:16:36.000Z","updated_at":"2024-11-22T12:18:23.000Z","dependencies_parsed_at":"2024-11-23T06:46:31.799Z","dependency_job_id":null,"html_url":"https://github.com/7c/osascript","commit_stats":null,"previous_names":["7c/osascript"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7c%2Fosascript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7c%2Fosascript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7c%2Fosascript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7c%2Fosascript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/7c","download_url":"https://codeload.github.com/7c/osascript/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245755682,"owners_count":20667027,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-05T08:12:47.600Z","updated_at":"2025-10-19T06:11:26.932Z","avatar_url":"https://github.com/7c.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @7c/osascript\n\nA modern TypeScript/Node.js library for executing AppleScript commands on macOS. This library provides both Promise-based execution and fire-and-forget functionality for AppleScript commands.\n\n## Features\n\n- Promise-based API with async/await support\n- Fire-and-forget execution that survives process crashes\n- Full TypeScript support with proper type definitions\n- Variable injection into AppleScript commands\n- Custom error types with detailed error information\n- Modern ES6+ syntax and patterns\n\n## Installation\n\n```bash\nnpm install https://github.com/7c/osascript --save\n```\n\n## Usage\n\n### Basic Example\n\n```typescript\nimport { execute, run } from '@7c/osascript';\n\n// Using async/await\nasync function showDialog() {\n  try {\n    const result = await execute('display dialog \"Hello World\"');\n    console.log('Dialog result:', result);\n  } catch (error) {\n    console.error('Dialog failed:', error);\n  }\n}\n\n// Fire and forget (survives process crashes)\nrun('display notification \"Background Task Complete\" with title \"Done\"');\n```\n\n### Using Variables\n\n```typescript\nimport { execute, OsaScriptOptions } from '@7c/osascript';\n\nasync function showCustomDialog() {\n  const options: OsaScriptOptions = {\n    variables: {\n      title: \"My Dialog\",\n      message: \"Choose an option\",\n      buttons: [\"OK\", \"Cancel\", \"Help\"]\n    }\n  };\n\n  try {\n    const result = await execute(`\n      tell application \"System Events\"\n        display dialog message ¬\n          with title title ¬\n          buttons buttons ¬\n          default button \"OK\"\n      end tell\n    `, options);\n    \n    console.log('User clicked:', result);\n  } catch (error) {\n    console.error('Dialog failed:', error);\n  }\n}\n```\n\n### Error Handling\n\n```typescript\nimport { execute, OsaScriptError } from '@7c/osascript';\n\nasync function handleErrors() {\n  try {\n    await execute('some invalid script');\n  } catch (error) {\n    if (error instanceof OsaScriptError) {\n      console.error('Script Error:', error.message);\n      console.error('stderr:', error.stderr);\n      console.error('exit code:', error.code);\n    }\n  }\n}\n```\n\n## API\n\n### execute()\n\nExecutes an AppleScript command and returns a Promise with the result.\n\n```typescript\nasync function execute(\n  script: string,\n  options?: OsaScriptOptions\n): Promise\u003cstring\u003e\n```\n\n#### Parameters\n\n- `script`: The AppleScript command to execute\n- `options`: (Optional) Configuration options\n  - `variables`: Variables to inject into the script\n  - `cwd`: Working directory path\n\n### executeFile()\n\nExecutes an AppleScript file and returns a Promise with the result.\n\n```typescript\nasync function executeFile(\n  path: string,\n  options?: OsaScriptOptions\n): Promise\u003cstring\u003e\n```\n\n#### Parameters\n\n- `path`: Path to the AppleScript file\n- `options`: (Optional) Configuration options\n  - `variables`: Variables to inject into the script\n  - `cwd`: Working directory path (defaults to file's directory)\n\n### run()\n\nExecutes an AppleScript command in fire-and-forget mode. The command continues running even if the Node.js process crashes.\n\n```typescript\nfunction run(\n  script: string,\n  options?: OsaScriptOptions\n): void\n```\n\n#### Parameters\n\n- `script`: The AppleScript command to execute\n- `options`: (Optional) Configuration options\n  - `variables`: Variables to inject into the script\n  - `cwd`: Working directory path\n\n### Types\n\n```typescript\ninterface OsaScriptOptions {\n  variables?: Record\u003cstring, unknown\u003e;\n  cwd?: string;\n}\n\nclass OsaScriptError extends Error {\n  readonly stderr?: string;\n  readonly code?: number;\n}\n```\n\n## Common Use Cases\n\n### System Dialogs\n\n```typescript\nimport { execute } from '@7c/osascript';\n\nasync function saveDialog() {\n  try {\n    const result = await execute(`\n      display dialog \"Save changes?\" ¬\n        buttons {\"Don't Save\", \"Cancel\", \"Save\"} ¬\n        default button \"Save\" ¬\n        cancel button \"Cancel\" ¬\n        with icon caution\n    `);\n    console.log('User chose:', result);\n  } catch (error) {\n    console.error('Dialog failed:', error);\n  }\n}\n```\n\n### System Notifications\n\n```typescript\nimport { run } from '@7c/osascript';\n\nrun(`\n  display notification \"Download complete\" ¬\n    with title \"Downloader\" ¬\n    subtitle \"File saved\" ¬\n    sound name \"Glass\"\n`);\n```\n\n### Application Control\n\n```typescript\nimport { execute } from '@7c/osascript';\n\nasync function toggleMusic() {\n  try {\n    await execute(`\n      tell application \"Music\"\n        if player state is playing then\n          pause\n        else\n          play\n        end if\n      end tell\n    `);\n  } catch (error) {\n    console.error('Failed to control Music app:', error);\n  }\n}\n```\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Credits\nThis is a TypeScript rewrite of [node-osascript](https://github.com/FWeinb/node-osascript) with modern Promise support and enhanced TypeScript features.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F7c%2Fosascript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F7c%2Fosascript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F7c%2Fosascript/lists"}