synckit

Perform async work synchronously in Node.js/Bun using worker_threads with first-class TypeScript and Yarn P'n'P support.

Usage

Install

# yarn
yarn add synckit

# npm
npm i synckit

API

// 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

Types

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
}

Options

execArgv same as env SYNCKIT_EXEC_ARGV
globalShims: Similar like env SYNCKIT_GLOBAL_SHIMS but much more flexible which can be a GlobalShim Array, see GlobalShim's definition for more details
timeout same as env SYNCKIT_TIMEOUT
transferList: Please refer Node.js worker_threads documentation
tsRunner same as env SYNCKIT_TS_RUNNER

Envs

SYNCKIT_EXEC_ARGV: List of node CLI options passed to the worker, split with comma ,. (default as []), see also node docs
SYNCKIT_GLOBAL_SHIMS: Whether to enable the default DEFAULT_GLOBAL_SHIMS_PRESET as globalShims
SYNCKIT_TIMEOUT: timeout for performing the async job (no default)
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

TypeScript

`node` (Default, Node 22.6+)

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.6, this feature is supported out of the box. For Node >=22.6 <23.6, this feature is supported via --experimental-strip-types flag. Visit the documentation to learn more.

When synckit detects the process to be running with supported Node versions (>=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.

`bun` (Default, Bun)

Bun supports TypeScript natively.

When synckit detects the process to be running with Bun, it will execute the worker file with the bun runner by default.

In this case, synckit doesn't do anything to the worker itself, it just passes through the worker directly.

`ts-node` (Default)

Prior to Node v22.6, 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.

`esbuild-register`

Please view esbuild-register for its document

`esbuild-runner`

Please view esbuild-runner for its document

`oxc`

Please view @oxc-node/core for its document

`swc`

Please view @swc-node/register for its document

`tsx`

Please view tsx for its document

Benchmark

The 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:

# cjs
┌───────────┬────────────┬──────────────┬───────────────────┬─────────────┬────────────────┬───────────────────┬────────────────────────┬───────────┬─────────────────┐
│ (index)   │ synckit    │ sync-threads │ perf sync-threads │ deasync     │ perf deasync   │ make-synchronized │ perf make-synchronized │ native    │ perf native     │
├───────────┼────────────┼──────────────┼───────────────────┼─────────────┼────────────────┼───────────────────┼────────────────────────┼───────────┼─────────────────┤
│ loadTime  │ '17.26ms'  │ '1.49ms'     │ '11.57x slower'   │ '146.55ms'  │ '8.49x faster' │ '1025.77ms'       │ '59.42x faster'        │ '0.29ms'  │ '59.71x slower' │
│ runTime   │ '143.12ms' │ '3689.15ms'  │ '25.78x faster'   │ '1221.11ms' │ '8.53x faster' │ '2842.50ms'       │ '19.86x faster'        │ '12.64ms' │ '11.33x slower' │
│ totalTime │ '160.38ms' │ '3690.64ms'  │ '23.01x faster'   │ '1367.66ms' │ '8.53x faster' │ '3868.27ms'       │ '24.12x faster'        │ '12.93ms' │ '12.41x slower' │
└───────────┴────────────┴──────────────┴───────────────────┴─────────────┴────────────────┴───────────────────┴────────────────────────┴───────────┴─────────────────┘

# esm
┌───────────┬────────────┬──────────────┬───────────────────┬─────────────┬────────────────┬───────────────────┬────────────────────────┬───────────┬─────────────────┐
│ (index)   │ synckit    │ sync-threads │ perf sync-threads │ deasync     │ perf deasync   │ make-synchronized │ perf make-synchronized │ native    │ perf native     │
├───────────┼────────────┼──────────────┼───────────────────┼─────────────┼────────────────┼───────────────────┼────────────────────────┼───────────┼─────────────────┤
│ loadTime  │ '23.88ms'  │ '2.03ms'     │ '11.75x slower'   │ '70.95ms'   │ '2.97x faster' │ '400.24ms'        │ '16.76x faster'        │ '0.44ms'  │ '54.70x slower' │
│ runTime   │ '139.56ms' │ '3570.12ms'  │ '25.58x faster'   │ '1150.99ms' │ '8.25x faster' │ '3484.04ms'       │ '24.96x faster'        │ '12.98ms' │ '10.75x slower' │
│ totalTime │ '163.44ms' │ '3572.15ms'  │ '21.86x faster'   │ '1221.93ms' │ '7.48x faster' │ '3884.28ms'       │ '23.77x faster'        │ '13.42ms' │ '12.18x slower' │
└───────────┴────────────┴──────────────┴───────────────────┴─────────────┴────────────────┴───────────────────┴────────────────────────┴───────────┴─────────────────┘

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.

Sponsors and Backers

Backers

1stG	RxTS	UnTS

Who are using `synckit`

Acknowledgements

This package is original inspired by esbuild and sync-threads.

Changelog

Detailed changes for each release are documented in CHANGELOG.md.

License

Current Tags

0.11.12 ... latest (3 months ago)
0.10.4 ... release-0.10 (10 months ago)

synckit

TOC

Usage

Install

API

Types

Options

Envs

TypeScript

`node` (Default, Node 22.6+)

`bun` (Default, Bun)

`ts-node` (Default)

`esbuild-register`

`esbuild-runner`

`oxc`

`swc`

`tsx`

Benchmark

Sponsors and Backers

Sponsors

Backers

Who are using `synckit`

Acknowledgements

Changelog

License

Current Tags

53 Versions

synckit

TOC

Usage

Install

API

Types

Options

Envs

TypeScript

node (Default, Node 22.6+)

bun (Default, Bun)

ts-node (Default)

esbuild-register

esbuild-runner

oxc

swc

tsx

Benchmark

Sponsors and Backers

Sponsors

Backers

Who are using synckit

Acknowledgements

Changelog

License

Current Tags

53 Versions

`node` (Default, Node 22.6+)

`bun` (Default, Bun)

`ts-node` (Default)

`esbuild-register`

`esbuild-runner`

`oxc`

`swc`

`tsx`

Who are using `synckit`