{"id":26891720,"url":"https://github.com/hyperse-io/exec-program","last_synced_at":"2026-03-14T16:34:07.645Z","repository":{"id":241652335,"uuid":"805719527","full_name":"hyperse-io/exec-program","owner":"hyperse-io","description":"Executes a command using `file ...arguments`, supports `.ts` file with esm type module.","archived":false,"fork":false,"pushed_at":"2025-06-10T09:12:19.000Z","size":3714,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-08T17:58:26.077Z","etag":null,"topics":["bin","exec","execa","execfile","hyperse","process","run-ts-files","shell","spawn","swc-node"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyperse-io.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","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,"zenodo":null},"funding":{"github":["hyperse-net"]}},"created_at":"2024-05-25T09:16:50.000Z","updated_at":"2025-06-10T09:11:49.000Z","dependencies_parsed_at":"2024-05-29T14:12:59.025Z","dependency_job_id":"46415d67-c0fc-4693-96d7-5490e58e37c8","html_url":"https://github.com/hyperse-io/exec-program","commit_stats":null,"previous_names":["hyperse-io/exec-program"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/hyperse-io/exec-program","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperse-io%2Fexec-program","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperse-io%2Fexec-program/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperse-io%2Fexec-program/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperse-io%2Fexec-program/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperse-io","download_url":"https://codeload.github.com/hyperse-io/exec-program/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperse-io%2Fexec-program/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271020031,"owners_count":24685795,"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","status":"online","status_checked_at":"2025-08-18T02:00:08.743Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["bin","exec","execa","execfile","hyperse","process","run-ts-files","shell","spawn","swc-node"],"created_at":"2025-03-31T22:41:24.972Z","updated_at":"2025-11-03T17:43:00.190Z","avatar_url":"https://github.com/hyperse-io.png","language":"JavaScript","funding_links":["https://github.com/sponsors/hyperse-net"],"categories":[],"sub_categories":[],"readme":"# @hyperse/exec-program\n\n\u003cp align=\"left\"\u003e\n  \u003ca aria-label=\"Build\" href=\"https://github.com/hyperse-io/exec-program/actions?query=workflow%3ACI\"\u003e\n    \u003cimg alt=\"build\" src=\"https://img.shields.io/github/actions/workflow/status/hyperse-io/exec-program/ci-integrity.yml?branch=main\u0026label=ci\u0026logo=github\u0026style=flat-quare\u0026labelColor=000000\" /\u003e\n  \u003c/a\u003e\n  \u003ca aria-label=\"stable version\" href=\"https://www.npmjs.com/package/@hyperse/exec-program\"\u003e\n    \u003cimg alt=\"stable version\" src=\"https://img.shields.io/npm/v/%40hyperse%2Fexec-program?branch=main\u0026label=version\u0026logo=npm\u0026style=flat-quare\u0026labelColor=000000\" /\u003e\n  \u003c/a\u003e\n  \u003ca aria-label=\"Top language\" href=\"https://github.com/hyperse-io/exec-program/search?l=typescript\"\u003e\n    \u003cimg alt=\"GitHub top language\" src=\"https://img.shields.io/github/languages/top/hyperse-io/exec-program?style=flat-square\u0026labelColor=000\u0026color=blue\"\u003e\n  \u003c/a\u003e\n  \u003ca aria-label=\"Licence\" href=\"https://github.com/hyperse-io/exec-program/blob/main/LICENSE\"\u003e\n    \u003cimg alt=\"Licence\" src=\"https://img.shields.io/github/license/hyperse-io/ts-node-paths?style=flat-quare\u0026labelColor=000000\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nA Node.js utility for programmatically executing commands in your scripts, applications, or libraries. Unlike traditional shells, it's optimized for programmatic usage with TypeScript support.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Features](#features)\n- [API Reference](#api-reference)\n  - [runTsScript](#runtsscript)\n  - [execute](#execute)\n- [Usage Examples](#usage-examples)\n  - [Running TypeScript Files](#running-typescript-files)\n  - [Executing Commands](#executing-commands)\n  - [Unit Testing with Vitest](#unit-testing-with-vitest)\n- [Configuration](#configuration)\n\n## Installation\n\n```bash\nnpm install --save @hyperse/exec-program\n```\n\n## Features\n\n- 🚀 Execute TypeScript files directly\n- 💻 Run shell commands programmatically\n- 📘 TypeScript support out of the box\n- ⚡ Promise-based API\n- ⚙️ Configurable execution options\n- 🧪 Built-in support for unit testing\n\n## API Reference\n\n### runTsScript\n\nExecutes a TypeScript file and returns its output.\n\n```typescript\n/**\n * Process execute typescript script file using `@hyperse/ts-node`\n * @param program - The absolute typescript file path\n * @param options - The configuration of `execa` { env: { HPS_TS_NODE_PROJECT: tsconfig } }\n * @param args - The runtime argv for program\n */\ndeclare const runTsScript: \u003cT extends ExecOptions\u003e(\n  program: string,\n  args?: readonly string[],\n  options?: T\n) =\u003e ExecResultPromise\u003c{} \u0026 T\u003e;\n```\n\n### execute\n\nExecutes a shell command with specified arguments and options.\n\n```typescript\nimport { execute } from '@hyperse/exec-program';\n\n/**\n * Execute a file with arguments and options\n * @param file - The program/script to execute, as a string or file URL\n * @param args - Arguments to pass to `file` on execution.\n * @param options - Options to pass to `execa`\n * @returns A `ResultPromise` that is both:\n */\ndeclare function execute\u003cT extends ExecOptions\u003e(\n  file: string,\n  args?: readonly string[],\n  options?: T\n): ExecResultPromise\u003c{} \u0026 T\u003e;\n```\n\n## Usage Examples\n\n### Running TypeScript Files\n\n```typescript\nimport { dirname, join } from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport { runTsScript } from '@hyperse/exec-program';\n\nconst getDirname = (url: string, ...paths: string[]) =\u003e {\n  return join(dirname(fileURLToPath(url)), ...paths);\n};\n\n// Execute a TypeScript file\nconst cliPath = getDirname(import.meta.url, './cli-test.ts');\nconst { stderr, stdout } = await runTsScript(cliPath);\nconsole.log(stderr, stdout);\n```\n\n### Executing Commands\n\n```typescript\nimport { execute } from '@hyperse/exec-program';\n\n// Install npm packages\nconst { stdout, stderr } = await execute(\n  'npm',\n  ['i', '--no-save', '--no-package-lock', ...packages],\n  {\n    cwd: targetDirectory,\n    maxBuffer: TEN_MEGA_BYTE,\n    env: npmEnv,\n  }\n);\n\n// Create npm package\nawait execute('npm', ['pack', directory], {\n  cwd: uniqueDir,\n  maxBuffer: TEN_MEGA_BYTE,\n});\n```\n\n### Unit Testing with Vitest\n\n1. Configure your `tsconfig.json`:\n\n```json\n{\n  \"extends\": \"@hyperse/eslint-config-hyperse/tsconfig.base.json\",\n  \"compilerOptions\": {\n    \"baseUrl\": \"./src\",\n    \"rootDir\": \"./\",\n    \"outDir\": \"dist\",\n    \"types\": [\"vitest/globals\"],\n    \"paths\": {\n      \"@hyperse/exec-program\": [\"../src/index.js\"]\n    }\n  },\n  \"include\": [\"next-env.d.ts\", \"**/*.ts\", \"**/*.tsx\"]\n}\n```\n\n2. Create a test file (`cli-test.ts`):\n\n```typescript\nimport { runTsScript } from '@hyperse/exec-program';\n\nconsole.log(typeof runTsScript);\nconsole.log('cli...');\n```\n\n3. Write your test (`main.spec.ts`):\n\n```typescript\nimport { dirname, join } from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport { runTsScript } from '@hyperse/exec-program';\n\nconst getDirname = (url: string, ...paths: string[]) =\u003e {\n  return join(dirname(fileURLToPath(url)), ...paths);\n};\n\nconst cliPath = getDirname(import.meta.url, './cli-test.ts');\n\ndescribe('test suites of exec program', () =\u003e {\n  it('should correctly invoke cli.ts', async () =\u003e {\n    const { stderr, stdout } = await runTsScript(cliPath);\n    expect(stderr).toBe('');\n    expect(stdout).toMatch(/cli.../);\n  });\n});\n```\n\n## Configuration\n\nThe library supports various configuration options for both `runTsScript` and `execute` functions. These options allow you to customize the execution environment, working directory, and other parameters.\n\nFor detailed configuration options, please refer to the TypeScript types in the source code.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperse-io%2Fexec-program","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperse-io%2Fexec-program","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperse-io%2Fexec-program/lists"}