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

npm i -D unplugin-quansync

// vite.config.ts
import Quansync from 'unplugin-quansync/vite'

export default defineConfig({
  plugins: [Quansync()],
})

// rollup.config.js
import Quansync from 'unplugin-quansync/rollup'

export default {
  plugins: [Quansync()],
}

// rolldown.config.js
import Quansync from 'unplugin-quansync/rolldown'

export default {
  plugins: [Quansync()],
}

import { build } from 'esbuild'
import Quansync from 'unplugin-quansync/esbuild'

build({
  plugins: [Quansync()],
})

// webpack.config.js
import Quansync from 'unplugin-quansync/webpack'

export default {
  /* ... */
  plugins: [Quansync()],
}

// rspack.config.js
import Quansync from 'unplugin-quansync/rspack'

export default {
  /* ... */
  plugins: [Quansync()],
}

Usage

Here is an example:

import fs from 'node:fs'
import { quansync } from 'quansync/macro'

// Create a quansync function by providing `sync` and `async` implementations
const readFile = quansync({
  sync: (path: string) => fs.readFileSync(path),
  async: (path: string) => fs.promises.readFile(path),
})

// Create a quansync function by providing an **async** function
const myFunction = quansync(async (filename) => {
  // Use `await` to call another quansync function
  const code = await readFile(filename, 'utf8')

  return `// some custom prefix\n${code}`
})

// Use it as a sync function
const result = myFunction.sync('./some-file.js')

// Use it as an async function
const 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:

import fs from 'node:fs'
import { quansync } from 'quansync/macro'

// No transformations needed for objects
const readFile = quansync({
  sync: (path: string) => fs.readFileSync(path),
  async: (path: string) => fs.promises.readFile(path),
})

// `async function` is transformed into a generator function
const myFunction = quansync(function* (filename) {
  // `await` is transformed into `yield ...`
  const code = yield readFile(filename, 'utf8')

  return `// some custom prefix\n${code}`
})

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.

const fn = quansync(() => this)

// Transforms to:

const fn = quansync((v) => {
  return function* () {
    return this
  }.call(this)
})

Sponsors

License

MIT License © 2025-PRESENT Kevin Deng