unplugin-quansync

Write async functions, get both async and sync functions with quansync and compile-time magics 🪄.

Features

• 🪄 Compile-time magic: Write async functions, get both async and sync functions.
• 🦾 Type-safe: Fully typed with TypeScript.
• 🌱 Lightweight: No runtime dependencies.
• 🚀 Zero-config: Works out of the box with Vite, Rollup, Webpack, esbuild, and more.

Installation

1npm i -D unplugin-quansync

1// vite.config.ts
2import Quansync from 'unplugin-quansync/vite'
3
4export default defineConfig({
5  plugins: [Quansync()],
6})

1// rollup.config.js
2import Quansync from 'unplugin-quansync/rollup'
3
4export default {
5  plugins: [Quansync()],
6}

1// rolldown.config.js
2import Quansync from 'unplugin-quansync/rolldown'
3
4export default {
5  plugins: [Quansync()],
6}

1import { build } from 'esbuild'
2import Quansync from 'unplugin-quansync/esbuild'
3
4build({
5  plugins: [Quansync()],
6})

1// webpack.config.js
2import Quansync from 'unplugin-quansync/webpack'
3
4export default {
5  /* ... */
6  plugins: [Quansync()],
7}

1// rspack.config.js
2import Quansync from 'unplugin-quansync/rspack'
3
4export default {
5  /* ... */
6  plugins: [Quansync()],
7}

Usage

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 quansync's docs.

How it works

unplugin-quansync transforms your async functions into generator functions wrapped by quansync from quansync/macro, replacing await with yield.

The example above becomes:

1import fs from 'node:fs'
2import { quansync } from 'quansync/macro'
3
4// No transformations needed for objects
5const readFile = quansync({
6  sync: (path: string) => fs.readFileSync(path),
7  async: (path: string) => fs.promises.readFile(path),
8})
9
10// `async function` is transformed into a generator function
11const myFunction = quansync(function* (filename) {
12  // `await` is transformed into `yield ...`
13  const code = yield readFile(filename, 'utf8')
14
15  return `// some custom prefix\n${code}`
16})

Caveats

Arrow functions

Both arrow functions and generators have been available since ES2015, but a "generator arrow function" syntax does not exist yet.

You can still use arrow functions and this with quansync macro, but they will be transformed into generator functions, retaining this binding and omitting the arguments object.

1const fn = quansync(() => this)
2
3// Transforms to:
4
5const fn = quansync((v) => {
6  return function* () {
7    return this
8  }.call(this)
9})

Sponsors

License

MIT License © 2025-PRESENT 三咲智子