Unified Async/Sync Function Execution

Common errors

• TypeError: this.async is not a function

  cause The function passed to `runAsync` is not being called with the correct `this` context, which typically provides the `async` method.
  fix Ensure `runAsync` is called such that the wrapped function's `this` context is correctly bound or provided by `run-async` itself. Avoid using arrow functions for the wrapped function if you intend to use `this.async()`, as arrow functions lexically bind `this`.

• Error: Callback was already called.

  cause This error typically occurs when the `done()` callback (from `this.async()`) or a Promise's `resolve`/`reject` function is invoked more than once within the wrapped function.
  fix Review your asynchronous logic to ensure that `done()`, `resolve()`, or `reject()` are called exactly once per `runAsync` invocation, even in error scenarios. Add guards to prevent multiple calls.

Warnings

• breaking Version 2.0.0 changed the `runAsync` signature. If your Node.js version supports native Promises, `runAsync` will now return a Promise, altering how it's consumed compared to earlier versions that exclusively used callbacks.
  Fix: Migrate your usage to consume the returned Promise (e.g., `runAsync(func)(args).then(cb)`) or ensure your callback handling is compatible with both Promise-based and traditional callback flows.
• breaking The `runAsync.cb` function, introduced in v2.1.0, requires the wrapped function to have a fixed number of parameters. Variable argument functions or functions with `arguments` objects may not behave as expected.
  Fix: Ensure that any function passed to `runAsync.cb` explicitly defines all its parameters, including the final callback argument.
• gotcha Prior to v2.2.0, Promise polyfill behavior was conditional. Since v2.2.0, `runAsync` consistently returns a Promise, relying on the 'Pinkie' polyfill if native Promises are not available in the Node.js environment.
  Fix: Be aware that `runAsync` will always return a Promise for consistent behavior across Node.js versions, which might slightly change execution flow compared to pre-2.2.0 versions on older Node.js.
• gotcha The `is-promise` dependency was removed in v2.4.1 due to issues with the upstream package, making `run-async` dependency-free. Older versions might have experienced unexpected behavior or issues related to this dependency.
  Fix: Upgrade `run-async` to version 2.4.1 or higher to remove the `is-promise` dependency and ensure a more stable, dependency-free experience.
• gotcha The Node.js 0.10 Promise polyfill was removed in v2.3.0. Users on very old Node.js 0.10 environments might experience Promise-related issues without the polyfill.
  Fix: Upgrade your Node.js runtime to a supported version (e.g., 0.12 or higher as per package.json engines) to ensure native Promise support or proper polyfill handling by `run-async`.

Install

• npm install run-async npm
• yarn add run-async yarn
• pnpm add run-async pnpm

Imports

• runAsync
  wrong:

  const runAsync = require('run-async');

  correct:

  import { runAsync } from 'run-async';

  While CommonJS `require` is shown in the README, modern Node.js and TypeScript projects should use ESM imports.
• runAsync.cb
  wrong:

  import { cb } from 'run-async';

  correct:

  import { runAsync } from 'run-async'; runAsync.cb(...);

  `cb` is a property of the main `runAsync` export, not a separate named export.
• RunAsync function types

  import type { RunAsync } from 'run-async';

  For type-checking in TypeScript, import the `RunAsync` interface or similar utility types.

Quickstart

Demonstrates how to use `runAsync` to execute functions that use `this.async()`, return a Promise, or return a synchronous value. Also includes an example of `runAsync.cb` for Node.js callback-style functions.

import { runAsync } from 'run-async';

// A helper to demonstrate how runAsync normalizes different function types
const printAfter = async (func: Function) => {
  const cb = (err: Error | null, returnValue: unknown) => {
    if (err) {
      console.error('Error:', err);
      return;
    }
    console.log(returnValue);
  };

  // Execute the function using runAsync, passing a callback
  // runAsync returns a function that takes arguments for func
  try {
    const result = await runAsync(func, cb)();
    // If func returns a Promise, runAsync resolves it. The callback also fires.
    // We'll catch the potential Promise resolution here.
    // The callback provided to runAsync will still be called.
  } catch (error) {
    console.error('Caught an error from runAsync execution:', error);
  }
};

console.log('--- Using this.async ---');
printAfter(function (this: any) {
  const done = this.async();
  setTimeout(() => {
    done(null, 'done running with callback');
  }, 10);
});

console.log('\n--- Returning a Promise ---');
printAfter(function () {
  return new Promise(resolve => {
    setTimeout(() => resolve('done running with promises'), 5);
  });
});

console.log('\n--- Synchronous function ---');
printAfter(function () {
  return 'done running sync function';
});

// Example using runAsync.cb for Node.js callback style
console.log('\n--- Using runAsync.cb (Node.js callback style) ---');
runAsync.cb(
  (a: number, b: number, cb: (err: Error | null, result: number) => void) => {
    setTimeout(() => cb(null, a + b), 20);
  },
  (err: Error | null, result: number) => {
    if (err) console.error('Error with runAsync.cb:', err);
    else console.log(`runAsync.cb result: ${result}`);
  }
)(5, 7);