Perform async work synchronously in Node.js using worker_threads with first-class TypeScript and Yarn P'n'P support.
# yarn
yarn add synckit
# npm
npm i synckit// runner.js
import { createSyncFn } from 'synckit'
// the worker path must be absolute
const syncFn = createSyncFn(require.resolve('./worker'), {
tsRunner: 'tsx', // optional, can be `'node' | 'ts-node' | 'esbuild-register' | 'esbuild-runner' | 'tsx'`
})
// do whatever you want, you will get the result synchronously!
const result = syncFn(...args)// worker.js
import { runAsWorker } from 'synckit'
runAsWorker(async (...args) => {
// do expensive work
return result
})You must make sure, the result is serializable by Structured Clone Algorithm
export interface GlobalShim {
moduleName: string
/**
* `undefined` means side effect only
*/
globalName?: string
/**
* 1. `undefined` or empty string means `default`, for example:
* ```js
* import globalName from 'module-name'
* ```
*
* 2. `null` means namespaced, for example:
* ```js
* import * as globalName from 'module-name'
* ```
*
*/
named?: string | null
/**
* If not `false`, the shim will only be applied when the original `globalName` unavailable,
* for example you may only want polyfill `globalThis.fetch` when it's unavailable natively:
* ```js
* import fetch from 'node-fetch'
*
* if (!globalThis.fetch) {
* globalThis.fetch = fetch
* }
* ```
*/
conditional?: boolean
}execArgvsame as envSYNCKIT_EXEC_ARGVglobalShims: Similar like envSYNCKIT_GLOBAL_SHIMSbut much more flexible which can be aGlobalShimArray, seeGlobalShim's definition for more detailstimeoutsame as envSYNCKIT_TIMEOUTtransferList: Please refer Node.jsworker_threadsdocumentationtsRunnersame as envSYNCKIT_TS_RUNNER
SYNCKIT_EXEC_ARGV: List of node CLI options passed to the worker, split with comma,. (default as[]), see alsonodedocsSYNCKIT_GLOBAL_SHIMS: Whether to enable the defaultDEFAULT_GLOBAL_SHIMS_PRESETasglobalShimsSYNCKIT_TIMEOUT:timeoutfor performing the async job (no default)SYNCKIT_TS_RUNNER: Which TypeScript runner to be used, it could be very useful for development, could be'ts-node' | 'esbuild-register' | 'esbuild-runner' | 'swc' | 'tsx','ts-node'is used by default, make sure you have installed them already
On recent Node versions, you may select this runner to execute your worker file (a .ts file) in the native runtime.
As of Node v23, this feature is supported out of the box. To enable it in the current LTS, you can pass the --experimental-strip-types flag to the process. Visit the documentation to learn more.
When synckit detects the process to be running with this flag, it will execute the worker file with the node runner by default.
Prior to Node v23, you may want to use ts-node to execute your worker file (a .ts file).
If you want to use a custom tsconfig as project instead of default tsconfig.json, use TS_NODE_PROJECT env. Please view ts-node for more details.
If you want to integrate with tsconfig-paths, please view ts-node for more details.
Please view esbuild-register for its document
Please view esbuild-runner for its document
Please view @swc-node/register for its document
Please view tsx for its document
It is about 50x faster than sync-threads but 10x slower than native for reading the file content itself 1000 times during runtime, and 40x faster than sync-threads but 10x slower than native for total time on my personal MacBook Pro with 64G M1 Max.
And it's almost 5x faster than deasync but requires no native bindings or node-gyp.
See benchmark.cjs and benchmark.esm for more details.
You can try it with running yarn benchmark by yourself. Here is the benchmark source code.
| 1stG | RxTS | UnTS |
|---|---|---|
 |
 |
 |
| 1stG | RxTS | UnTS |
|---|---|---|
 |
 |
 |
Detailed changes for each release are documented in CHANGELOG.md.
