Callback/Promise Catering Utility

Common errors

• TypeError: Cannot read properties of undefined (reading 'then')

  cause The module wrapped with `fromCallback` was called without returning `callback[kPromise]`, causing the promise-based consumption to receive `undefined`.
  fix Ensure `return callback[kPromise]` is present at the end of the module's function when using `fromCallback` to expose the promise interface.

• Error: callback is not a function

  cause When defining a module using `fromPromise` or `fromCallback`, the first argument `callback` is expected to be a function if the user is consuming it with a callback. If it's `undefined` or not a function and the internal logic attempts to call it directly (before `fromCallback` or `fromPromise` has processed it), this error can occur.
  fix Ensure that if your module's function accepts a `callback` argument, you either pass a function or `undefined` (if the consumer intends to use promises). `catering` handles the `undefined` case for promise consumption.

Warnings

• gotcha When using `fromCallback`, the `kPromise` symbol must be passed and returned to correctly expose the Promise API. Forgetting to return `callback[kPromise]` will result in a module that only supports callbacks.
  Fix: Ensure `return callback[kPromise]` is the last statement in your module's function when using `fromCallback`.
• gotcha The `fromPromise` function internally calls the provided callback in a `queueMicrotask` (or equivalent next tick behavior). This is intentional to "escape the promise chain" and prevent promise rejections from implicitly catching errors that should go directly to the callback. This means callback errors are not catchable by a `.catch()` attached to the promise returned by `fromPromise`.
  Fix: Handle errors delivered to the callback via the `(err, result)` signature. Do not rely on `.catch()` on the promise returned by `fromPromise` to handle errors for the callback path.
• gotcha While `catering` supports older Node.js versions (>=6), it is generally recommended to use modern Node.js environments (LTS or current) to benefit from performance improvements, security patches, and full ES module support.
  Fix: Upgrade to a current Node.js LTS version (e.g., Node.js 18 or 20) for optimal compatibility and security.

Install

• npm install catering npm
• yarn add catering yarn
• pnpm add catering pnpm

Imports

• fromCallback
  wrong:

  const { fromCallback } = require('catering')

  correct:

  import { fromCallback } from 'catering'

  ESM is preferred. CommonJS `require` is also supported.
• fromPromise
  wrong:

  const { fromPromise } = require('catering')

  correct:

  import { fromPromise } from 'catering'

  ESM is preferred. CommonJS `require` is also supported.
• kPromise
  wrong:

  const { kPromise } = require('catering')

  correct:

  import { kPromise } from 'catering'

  The `kPromise` symbol is used internally by `fromCallback` to attach the promise instance. While exported, direct use is uncommon.
• Module (CommonJS)

  const { fromCallback, fromPromise } = require('catering')

  For Node.js CommonJS modules, destructuring `require('catering')` is the standard way to get exported utilities.

Quickstart

Demonstrates how to create modules that internally use either callbacks or promises, and how `catering` enables them to be consumed with both `async/await` and traditional Node.js callbacks.

import { fromCallback, fromPromise } from 'catering';

const kPromise = Symbol('promise');

// Example: Internally uses callbacks
function createCallbackModule(callback) {
  callback = fromCallback(callback, kPromise);
  setTimeout(() => {
    // Simulate async operation
    if (Math.random() > 0.5) {
      callback(null, 'Data from callback source');
    } else {
      callback(new Error('Failed to get callback data'));
    }
  }, 100);
  return callback[kPromise];
}

// Example: Internally uses promises
function createPromiseModule(callback) {
  const promise = new Promise((resolve, reject) => {
    setTimeout(() => {
      // Simulate async operation
      if (Math.random() > 0.5) {
        resolve('Data from promise source');
      } else {
        reject(new Error('Failed to get promise data'));
      }
    }, 100);
  });
  return fromPromise(promise, callback);
}

async function runExamples() {
  console.log('--- Callback Module Example ---');
  try {
    const result = await createCallbackModule();
    console.log('Async/await result:', result);
  } catch (error) {
    console.error('Async/await error:', error.message);
  }

  createCallbackModule((err, result) => {
    if (err) console.error('Callback error:', err.message);
    else console.log('Callback result:', result);
  });

  console.log('\n--- Promise Module Example ---');
  try {
    const result = await createPromiseModule();
    console.log('Async/await result:', result);
  } catch (error) {
    console.error('Async/await error:', error.message);
  }

  createPromiseModule((err, result) => {
    if (err) console.error('Callback error:', err.message);
    else console.log('Callback result:', result);
  });
}

runExamples();