{"id":15478454,"url":"https://github.com/un-ts/synckit","last_synced_at":"2025-05-14T10:07:01.687Z","repository":{"id":38819764,"uuid":"361471817","full_name":"un-ts/synckit","owner":"un-ts","description":"Perform async work synchronously in Node.js/Bun using `worker_threads` with first-class TypeScript and Yarn P'n'P support.","archived":false,"fork":false,"pushed_at":"2025-05-01T05:29:38.000Z","size":7127,"stargazers_count":221,"open_issues_count":6,"forks_count":13,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-05T16:19:07.474Z","etag":null,"topics":["async","hacktoberfest","nodejs","pnp","sync","synchronize","synchronous","synckit","typescript","yarn"],"latest_commit_sha":null,"homepage":"https://npm.im/synckit","language":"TypeScript","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/un-ts.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null},"funding":{"github":["JounQin","1stG","rx-ts","un-ts"],"patreon":"1stG","open_collective":"unts","custom":["https://opencollective.com/1stG","https://opencollective.com/rxts","https://afdian.net/@JounQin"]}},"created_at":"2021-04-25T15:53:57.000Z","updated_at":"2025-05-01T05:29:41.000Z","dependencies_parsed_at":"2024-04-13T18:52:10.947Z","dependency_job_id":"10106b5d-1145-42a3-ab19-753c0217fb18","html_url":"https://github.com/un-ts/synckit","commit_stats":{"total_commits":134,"total_committers":12,"mean_commits":"11.166666666666666","dds":"0.32089552238805974","last_synced_commit":"42918e8b340b7b6466a5ba280b946b78735877b3"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/un-ts%2Fsynckit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/un-ts%2Fsynckit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/un-ts%2Fsynckit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/un-ts%2Fsynckit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/un-ts","download_url":"https://codeload.github.com/un-ts/synckit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252721052,"owners_count":21793746,"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":["async","hacktoberfest","nodejs","pnp","sync","synchronize","synchronous","synckit","typescript","yarn"],"created_at":"2024-10-02T04:04:28.203Z","updated_at":"2025-05-14T10:07:01.671Z","avatar_url":"https://github.com/un-ts.png","language":"TypeScript","readme":"# synckit\n\n[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/un-ts/synckit/ci.yml?branch=main)](https://github.com/un-ts/synckit/actions/workflows/ci.yml?query=branch%3Amain)\n[![Codecov](https://img.shields.io/codecov/c/github/un-ts/synckit.svg)](https://codecov.io/gh/un-ts/synckit)\n[![type-coverage](https://img.shields.io/badge/dynamic/json.svg?label=type-coverage\u0026prefix=%E2%89%A5\u0026suffix=%\u0026query=$.typeCoverage.atLeast\u0026uri=https%3A%2F%2Fraw.githubusercontent.com%2Fun-ts%2Fsynckit%2Fmain%2Fpackage.json)](https://github.com/plantain-00/type-coverage)\n[![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/un-ts/synckit)](https://coderabbit.ai)\n[![npm](https://img.shields.io/npm/v/synckit.svg)](https://www.npmjs.com/package/synckit)\n[![GitHub Release](https://img.shields.io/github/release/un-ts/synckit)](https://github.com/un-ts/synckit/releases)\n\n[![Conventional Commits](https://img.shields.io/badge/conventional%20commits-1.0.0-yellow.svg)](https://conventionalcommits.org)\n[![Renovate enabled](https://img.shields.io/badge/renovate-enabled-brightgreen.svg)](https://renovatebot.com)\n[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)\n[![Code Style: Prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)\n[![changesets](https://img.shields.io/badge/maintained%20with-changesets-176de3.svg)](https://github.com/changesets/changesets)\n\nPerform async work synchronously in Node.js/Bun using `worker_threads` with first-class TypeScript and Yarn P'n'P support.\n\n## TOC \u003c!-- omit in toc --\u003e\n\n- [Usage](#usage)\n  - [Install](#install)\n  - [API](#api)\n  - [Types](#types)\n  - [Options](#options)\n  - [Envs](#envs)\n  - [TypeScript](#typescript)\n    - [`node` (Default, Node 22.6+)](#node-default-node-226)\n    - [`bun` (Default, Bun)](#bun-default-bun)\n    - [`ts-node` (Default)](#ts-node-default)\n    - [`esbuild-register`](#esbuild-register)\n    - [`esbuild-runner`](#esbuild-runner)\n    - [`oxc`](#oxc)\n    - [`swc`](#swc)\n    - [`tsx`](#tsx)\n- [Benchmark](#benchmark)\n- [Sponsors](#sponsors)\n- [Backers](#backers)\n- [Who are using `synckit`](#who-are-using-synckit)\n- [Acknowledgements](#acknowledgements)\n- [Changelog](#changelog)\n- [License](#license)\n\n## Usage\n\n### Install\n\n```sh\n# yarn\nyarn add synckit\n\n# npm\nnpm i synckit\n```\n\n### API\n\n```js\n// runner.js\nimport { createSyncFn } from 'synckit'\n\n// the worker path must be absolute\nconst syncFn = createSyncFn(require.resolve('./worker'), {\n  tsRunner: 'tsx', // optional, can be `'node' | 'ts-node' | 'esbuild-register' | 'esbuild-runner' | 'tsx'`\n})\n\n// do whatever you want, you will get the result synchronously!\nconst result = syncFn(...args)\n```\n\n```js\n// worker.js\nimport { runAsWorker } from 'synckit'\n\nrunAsWorker(async (...args) =\u003e {\n  // do expensive work\n  return result\n})\n```\n\nYou must make sure, the `result` is serializable by [`Structured Clone Algorithm`](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm)\n\n### Types\n\n````ts\nexport interface GlobalShim {\n  moduleName: string\n  /** `undefined` means side effect only */\n  globalName?: string\n  /**\n   * 1. `undefined` or empty string means `default`, for example:\n   *\n   * ```js\n   * import globalName from 'module-name'\n   * ```\n   *\n   * 2. `null` means namespaced, for example:\n   *\n   * ```js\n   * import * as globalName from 'module-name'\n   * ```\n   */\n  named?: string | null\n  /**\n   * If not `false`, the shim will only be applied when the original\n   * `globalName` unavailable, for example you may only want polyfill\n   * `globalThis.fetch` when it's unavailable natively:\n   *\n   * ```js\n   * import fetch from 'node-fetch'\n   *\n   * if (!globalThis.fetch) {\n   *   globalThis.fetch = fetch\n   * }\n   * ```\n   */\n  conditional?: boolean\n}\n````\n\n### Options\n\n1. `execArgv` same as env `SYNCKIT_EXEC_ARGV`\n2. `globalShims`: Similar like env `SYNCKIT_GLOBAL_SHIMS` but much more flexible which can be a `GlobalShim` `Array`, see `GlobalShim`'s [definition](#types) for more details\n3. `timeout` same as env `SYNCKIT_TIMEOUT`\n4. `transferList`: Please refer Node.js [`worker_threads`](https://nodejs.org/api/worker_threads.html#:~:text=Default%3A%20true.-,transferList,-%3CObject%5B%5D%3E%20If) documentation\n5. `tsRunner` same as env `SYNCKIT_TS_RUNNER`\n\n### Envs\n\n1. `SYNCKIT_EXEC_ARGV`: List of node CLI options passed to the worker, split with comma `,`. (default as `[]`), see also [`node` docs](https://nodejs.org/api/worker_threads.html)\n2. `SYNCKIT_GLOBAL_SHIMS`: Whether to enable the default `DEFAULT_GLOBAL_SHIMS_PRESET` as `globalShims`\n3. `SYNCKIT_TIMEOUT`: `timeout` for performing the async job (no default)\n4. `SYNCKIT_TS_RUNNER`: Which TypeScript runner to be used, it could be very useful for development, could be `'node' | 'ts-node' | 'esbuild-register' | 'esbuild-runner' | 'oxc' | 'swc' | 'tsx'`, `node` or `ts-node` will be used by default accordingly, make sure you have installed them already\n\n### TypeScript\n\n#### `node` (Default, Node 22.6+)\n\nOn recent `Node` versions, you may select this runner to execute your worker file (a `.ts` file) in the native runtime.\n\nAs of `Node` v23.6, this feature is supported out of the box. For `Node` `\u003e=22.6 \u003c23.6`, this feature is supported via `--experimental-strip-types` flag. Visit the [documentation](https://nodejs.org/docs/latest/api/typescript.html#type-stripping) to learn more.\n\nWhen `synckit` detects the process to be running with supported `Node` versions (\u003e=22.6), it will execute the worker file with the `node` runner by default, you can disable this behavior by setting `--no-experimental-strip-types` flag via `NODE_OPTIONS` env or cli arg.\n\n#### `bun` (Default, Bun)\n\n[`Bun`](https://bun.sh/docs/typescript) supports `TypeScript` natively.\n\nWhen `synckit` detects the process to be running with `Bun`, it will execute the worker file with the `bun` runner by default.\n\nIn this case, `synckit` doesn't do anything to the worker itself, it just passes through the worker directly.\n\n#### `ts-node` (Default)\n\nPrior to Node v22.6, you may want to use `ts-node` to execute your worker file (a `.ts` file).\n\nIf you want to use a custom tsconfig as project instead of default `tsconfig.json`, use `TS_NODE_PROJECT` env. Please view [ts-node](https://github.com/TypeStrong/ts-node#tsconfig) for more details.\n\nIf you want to integrate with [tsconfig-paths](https://www.npmjs.com/package/tsconfig-paths), please view [ts-node](https://github.com/TypeStrong/ts-node#paths-and-baseurl) for more details.\n\n#### `esbuild-register`\n\nPlease view [`esbuild-register`][] for its document\n\n#### `esbuild-runner`\n\nPlease view [`esbuild-runner`][] for its document\n\n#### `oxc`\n\nPlease view [`@oxc-node/core`][] for its document\n\n#### `swc`\n\nPlease view [`@swc-node/register`][] for its document\n\n#### `tsx`\n\nPlease view [`tsx`][] for its document\n\n## Benchmark\n\nThe following are the benchmark results of `synckit` against other libraries with Node.js v20.19.0 on my personal MacBook Pro with 64G M1 Max:\n\n```sh\n# cjs\n┌───────────┬────────────┬──────────────┬───────────────────┬─────────────┬────────────────┬───────────────────┬────────────────────────┬───────────┬─────────────────┐\n│ (index)   │ synckit    │ sync-threads │ perf sync-threads │ deasync     │ perf deasync   │ make-synchronized │ perf make-synchronized │ native    │ perf native     │\n├───────────┼────────────┼──────────────┼───────────────────┼─────────────┼────────────────┼───────────────────┼────────────────────────┼───────────┼─────────────────┤\n│ loadTime  │ '17.26ms'  │ '1.49ms'     │ '11.57x slower'   │ '146.55ms'  │ '8.49x faster' │ '1025.77ms'       │ '59.42x faster'        │ '0.29ms'  │ '59.71x slower' │\n│ runTime   │ '143.12ms' │ '3689.15ms'  │ '25.78x faster'   │ '1221.11ms' │ '8.53x faster' │ '2842.50ms'       │ '19.86x faster'        │ '12.64ms' │ '11.33x slower' │\n│ totalTime │ '160.38ms' │ '3690.64ms'  │ '23.01x faster'   │ '1367.66ms' │ '8.53x faster' │ '3868.27ms'       │ '24.12x faster'        │ '12.93ms' │ '12.41x slower' │\n└───────────┴────────────┴──────────────┴───────────────────┴─────────────┴────────────────┴───────────────────┴────────────────────────┴───────────┴─────────────────┘\n```\n\n```sh\n# esm\n┌───────────┬────────────┬──────────────┬───────────────────┬─────────────┬────────────────┬───────────────────┬────────────────────────┬───────────┬─────────────────┐\n│ (index)   │ synckit    │ sync-threads │ perf sync-threads │ deasync     │ perf deasync   │ make-synchronized │ perf make-synchronized │ native    │ perf native     │\n├───────────┼────────────┼──────────────┼───────────────────┼─────────────┼────────────────┼───────────────────┼────────────────────────┼───────────┼─────────────────┤\n│ loadTime  │ '23.88ms'  │ '2.03ms'     │ '11.75x slower'   │ '70.95ms'   │ '2.97x faster' │ '400.24ms'        │ '16.76x faster'        │ '0.44ms'  │ '54.70x slower' │\n│ runTime   │ '139.56ms' │ '3570.12ms'  │ '25.58x faster'   │ '1150.99ms' │ '8.25x faster' │ '3484.04ms'       │ '24.96x faster'        │ '12.98ms' │ '10.75x slower' │\n│ totalTime │ '163.44ms' │ '3572.15ms'  │ '21.86x faster'   │ '1221.93ms' │ '7.48x faster' │ '3884.28ms'       │ '23.77x faster'        │ '13.42ms' │ '12.18x slower' │\n└───────────┴────────────┴──────────────┴───────────────────┴─────────────┴────────────────┴───────────────────┴────────────────────────┴───────────┴─────────────────┘\n```\n\nSee [benchmark.cjs](./benchmarks/benchmark.cjs.txt) and [benchmark.esm](./benchmarks/benchmark.esm.txt) for more details.\n\nYou can try it with running `yarn benchmark` by yourself. [Here](./benchmarks/benchmark.js) is the benchmark source code.\n\n## Sponsors and Backers\n\n[![Sponsors and Backers](https://raw.githubusercontent.com/1stG/static/master/sponsors.svg)](https://github.com/sponsors/JounQin)\n\n### Sponsors\n\n| 1stG                                                                                                                   | RxTS                                                                                                                   | UnTS                                                                                                                   |\n| ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |\n| [![1stG Open Collective sponsors](https://opencollective.com/1stG/organizations.svg)](https://opencollective.com/1stG) | [![RxTS Open Collective sponsors](https://opencollective.com/rxts/organizations.svg)](https://opencollective.com/rxts) | [![UnTS Open Collective sponsors](https://opencollective.com/unts/organizations.svg)](https://opencollective.com/unts) |\n\n### Backers\n\n| 1stG                                                                                                                | RxTS                                                                                                                | UnTS                                                                                                                |\n| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |\n| [![1stG Open Collective backers](https://opencollective.com/1stG/individuals.svg)](https://opencollective.com/1stG) | [![RxTS Open Collective backers](https://opencollective.com/rxts/individuals.svg)](https://opencollective.com/rxts) | [![UnTS Open Collective backers](https://opencollective.com/unts/individuals.svg)](https://opencollective.com/unts) |\n\n## Who are using `synckit`\n\n- [`@cspell/eslint-plugin`](https://github.com/streetsidesoftware/cspell/blob/ec04bcee0c90ff4e2a9fb5ef4421714796fb58ba/packages/cspell-eslint-plugin/package.json#L80)\n- [`astrojs-compiler-sync`](https://github.com/ota-meshi/astrojs-compiler-sync/blob/da4e86fd601755e40599d7f5121bc83d08255c42/package.json#L52)\n- [`eslint-plugin-prettier`](https://github.com/prettier/eslint-plugin-prettier/blob/ca5eb3ec11c4ae511e1da22736c73b253210b73b/package.json#L67)\n- [`eslint-plugin-prettier-vue`](https://github.com/meteorlxy/eslint-plugin-prettier-vue/blob/d3f6722303d66a2b223df2f750982e33c1143d5d/package.json#L40)\n- [`eslint-mdx`](https://github.com/mdx-js/eslint-mdx/blob/4623359cc9784d3e38bd917ed001c5d7d826f990/packages/eslint-mdx/package.json#L40)\n- [`prettier-plugin-packagejson`](https://github.com/matzkoh/prettier-plugin-packagejson/blob/eb7ade2a048d6d163cf8ef37e098ee273f72c585/package.json#L31)\n- [`jest-snapshot`](https://github.com/jestjs/jest/blob/4e7d916ec6a16de5548273c17b5d2c5761b0aebb/packages/jest-snapshot/package.json#L42)\n\n## Acknowledgements\n\nThis package is original inspired by [`esbuild`](https://github.com/evanw/esbuild) and [`sync-threads`](https://github.com/lambci/sync-threads).\n\n## Changelog\n\nDetailed changes for each release are documented in [CHANGELOG.md](./CHANGELOG.md).\n\n## License\n\n[MIT][] © [JounQin][]@[1stG.me][]\n\n[`esbuild-register`]: https://github.com/egoist/esbuild-register\n[`esbuild-runner`]: https://github.com/folke/esbuild-runner\n[`@oxc-node/core`]: https://github.com/oxc-project/oxc-node\n[`@swc-node/register`]: https://github.com/swc-project/swc-node/tree/master/packages/register\n[`tsx`]: https://github.com/esbuild-kit/tsx\n[1stG.me]: https://www.1stG.me\n[JounQin]: https://github.com/JounQin\n[MIT]: http://opensource.org/licenses/MIT\n","funding_links":["https://github.com/sponsors/JounQin","https://github.com/sponsors/1stG","https://github.com/sponsors/rx-ts","https://github.com/sponsors/un-ts","https://patreon.com/1stG","https://opencollective.com/unts","https://opencollective.com/1stG","https://opencollective.com/rxts","https://afdian.net/@JounQin"],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fun-ts%2Fsynckit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fun-ts%2Fsynckit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fun-ts%2Fsynckit/lists"}