quansync

The quansync function allows you to create a single function that can be executed either synchronously or asynchronously. You can define this behavior in two ways:

1. Implementation Object: Provide an object with sync and async properties containing the respective implementations.
2. Generator Function: Provide a generator function. Inside the generator, use yield* to call other quansync functions. This allows the logic to be shared between both modes.

Once created, you can access the synchronous version via .sync() and the asynchronous version via .async() (or by awaiting the function directly).

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

// Method 1: Implementation Object
const readFile = quansync({
  sync: (path: string) => fs.readFileSync(path),
  async: (path: string) => fs.promises.readFile(path),
})

// Method 2: Generator Function
const myFunction = quansync(function* (filename) {
  // Use `yield*` to call another quansync function
  const code = yield* readFile(filename, 'utf8')
  return `// some custom prefix\n${code}`
})

// Usage
const result = myFunction.sync('./some-file.js') // Sync
const asyncResult = await myFunction.async('./some-file.js') // Async

If you prefer using standard async/await syntax instead of generator functions (function* and yield*), you can use the quansync/macro entry point. This requires the unplugin-quansync build-time macro to transform the code so that it still provides a .sync() method.

Note: This approach requires a build step using unplugin-quansync.

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

const readFile = quansync({
  sync: (path: string) => fs.readFileSync(path),
  async: (path: string) => fs.promises.readFile(path),
})

// Use an async function instead of a generator
const myFunction = quansync(async (filename) => {
  // Use `await` instead of `yield*`
  const code = await readFile(filename, 'utf8')
  return `// some custom prefix\n${code}`
})

const result = myFunction.sync('./some-file.js')
const asyncResult = await myFunction.async('./some-file.js')

The QuansyncFn is the core abstraction of the library, representing a "superposition" function that can be consumed in both synchronous and asynchronous contexts.

It provides two primary execution paths:

1. .sync(...args): Returns a generator that yields values synchronously.
2. .async(...args): Returns a promise that resolves to a generator, allowing for asynchronous yielding.

Warning: The .sync and .async methods are consumed upon invocation and will be lost after the function is called.

It also includes a .bind() method to allow binding a specific this context to the function.

export type QuansyncFn<Return = any, Args extends any[] = []>
  = ((...args: Args) => QuansyncAwaitableGenerator<QuansyncUnwrapGenerator<Return>>)
    & {
      bind: <T, A extends any[], B extends any[]>(
        this: (this: T, ...args: [...A, ...B]) => QuansyncAwaitableGenerator<QuansyncUnwrapGenerator<Return>>,
        thisArg: T,
        ...args: A
      ) => ((...args: B) => QuansyncAwaitableGenerator<QuansyncUnwrapGenerator<Return>>),
      sync: (...args: Args) => QuansyncUnwrapGenerator<Return>,
      async: (...args: Args) => Promise<QuansyncUnwrapGenerator<Return>>
    }

The quansync function creates a "superposition" function that can behave either synchronously or asynchronously depending on the context. You can initialize it using three different input types:

1. An object with sync and async methods: Define explicit implementations for both modes.
2. A generator function: Provide a generator that uses yield to switch between modes.
3. A Promise or value: Wrap a promise so it can be treated as a sync value (throwing if a promise is encountered in a sync context) or an async value.

When the resulting function is called, it detects the execution context. If called in an async context, it executes the async path; otherwise, it executes the sync path.

import { quansync } from 'quansync';

// 1. From an object with sync/async implementations
const dual = quansync({
  sync: (x: number) => x + 1,
  async: async (x: number) => x + 1
});

// 2. From a generator function
const gen = quansync(function* (x: number) {
  const isAsync = yield getIsAsync;
  if (isAsync) {
    return await Promise.resolve(x + 1);
  }
  return x + 1;
});

// 3. From a Promise
const fromPromise = quansync(Promise.resolve(42));