quansync

Create sync/async APIs with usable logic.

Quantum + Sync - "Superposition" between sync and async.

• Typesafe
• ESM, modern JavaScript
• Zero dependencies

Heavily inspired by genasync by @loganfsmyth.

Why & How

Please refer to Anthony's blog post: Async, Sync, in Between.

Usage

1pnpm i quansync

1import fs from 'node:fs'
2import { quansync } from 'quansync'
3
4// Create a quansync function by providing `sync` and `async` implementations
5const readFile = quansync({
6  sync: (path: string) => fs.readFileSync(path),
7  async: (path: string) => fs.promises.readFile(path),
8})
9
10// Create a quansync function by providing a generator function
11const myFunction = quansync(function* (filename) {
12  // Use `yield*` to call another quansync function
13  const code = yield* readFile(filename, 'utf8')
14
15  return `// some custom prefix\n${code}`
16})
17
18// Use it as a sync function
19const result = myFunction.sync('./some-file.js')
20
21// Use it as an async function
22const asyncResult = await myFunction.async('./some-file.js')

getIsAsync

Returns a boolean indicating whether the current execution is in async mode.

1import { getIsAsync, quansync } from 'quansync'
2
3const fn = quansync(function* () {
4  const isAsync: boolean = yield* getIsAsync()
5  console.log(isAsync)
6})
7
8fn.sync() // false
9await fn() // true
10await fn.async() // true

Build-time Macro

If you don't like the function* and yield* syntax, we also provide a build-time macro via unplugin-quansync allowing you use quansync with async/await syntax, while still able to get the sync version out of that.

Here is an example:

1import fs from 'node:fs'
2import { quansync } from 'quansync/macro'
3
4// Create a quansync function by providing `sync` and `async` implementations
5const readFile = quansync({
6  sync: (path: string) => fs.readFileSync(path),
7  async: (path: string) => fs.promises.readFile(path),
8})
9
10// Create a quansync function by providing an **async** function
11const myFunction = quansync(async (filename) => {
12  // Use `await` to call another quansync function
13  const code = await readFile(filename, 'utf8')
14
15  return `// some custom prefix\n${code}`
16})
17
18// Use it as a sync function
19const result = myFunction.sync('./some-file.js')
20
21// Use it as an async function
22const asyncResult = await myFunction.async('./some-file.js')

For more details on usage, refer to unplugin-quansync's docs.

Benchmark

Run the following command to benchmark the performance of quansync:

1pnpm run build && pnpm run benchmark

Benchmark results indicate that each yield incurs an overhead of approximately 150 ns, comparable to that of await sync(). (On Apple M1 Max)

Sponsors

License

MIT License © Anthony Fu and Kevin Deng