Throwback Async Middleware Composer

Common errors

• TypeError: next is not a function

  cause Attempting to call `next()` when it's not correctly provided to the middleware or trying to pass `ctx` to `next()` after v4.0.0 which disabled this pattern.
  fix Ensure your middleware signature correctly receives `next` and that you are not passing an argument to `next()` if using version 4.0.0 or higher. For versions < 4.0.0, `next(ctx)` was allowed.

• Middleware function must be a generator or return a Promise

  cause A middleware function passed to `compose` is not an `async` function and does not explicitly return a Promise.
  fix Ensure all functions in the middleware array are `async` functions or explicitly return a `Promise`. Example: `async function myMiddleware(ctx, next) { /* ... */ await next(); }`

• Error: next() called multiple times

  cause A middleware function called `next()` more than once, which is an anti-pattern for this type of middleware flow and triggers a development-mode error.
  fix Review your middleware logic. Each middleware function should call `await next()` at most once. If you need to short-circuit, simply omit calling `next()`.

• TypeError: ctx.clone is not a function (or similar context-related error)

  cause Attempting to use `ctx.clone()` as suggested in some `throwback` examples, but your specific `ctx` object does not have a `clone` method.
  fix The `ctx` object is user-defined. If you need cloning functionality, you must implement it within your custom context object. The suggestion in the `throwback` documentation is a pattern recommendation, not an implicit feature of `throwback` itself.

Warnings

• breaking The `debugMode` configuration option was removed. Debugging behavior is now solely controlled by `NODE_ENV`. Setting `NODE_ENV !== 'production'` enables debug checks and verbose errors.
  Fix: Remove any explicit `debugMode` configurations. Ensure your `NODE_ENV` is correctly set for development or production environments.
• breaking The ability to call `next(ctx)` directly to pass a modified context down the stack has been disabled. `next()` no longer accepts an argument. If you need to modify the context for subsequent middleware, it's recommended to create a wrapper function.
  Fix: Instead of `await next(modifiedCtx);`, call `await next();` and modify `ctx` directly. For deep changes, consider a wrapper like `(fn) => (ctx, next) => fn(ctx.clone(), next)` if your context supports cloning.
• breaking Middleware functions now accept only a single `ctx` argument. The previous pattern of `(ctx, next)` is no longer supported for the middleware function signature itself, though the `next` function is still passed as a second argument to the wrapper.
  Fix: Update your middleware functions to accept a single `ctx` argument. The `next` function is still accessible within the composed context's scope or by wrapping. Note: The `next()` function *can* accept an optional `ctx` argument to replace the context downstream since v3.0.0, but this was removed in v4.0.0.
• breaking The library no longer uses `any-promise` and relies exclusively on the native global `Promise` constructor. This might break in environments without native Promise support or if `any-promise` was used for specific polyfills.
  Fix: Ensure your runtime environment (Node.js or browser) provides a native `Promise` implementation. If targeting older environments, you must provide your own Promise polyfill globally before `throwback` is loaded.
• gotcha In development (`NODE_ENV !== 'production'`), `compose` will throw specific errors for unexpected behavior (e.g., calling `next` multiple times). These checks are stripped in production builds for performance.
  Fix: Pay attention to development-time errors to ensure correct middleware behavior. Do not rely on these error checks being present in production.

Install

• npm install throwback npm
• yarn add throwback yarn
• pnpm add throwback pnpm

Imports

• compose
  wrong:

  const { compose } = require('throwback');

  correct:

  import { compose } from 'throwback';

  While CommonJS `require` is shown in old examples, ESM `import` is the idiomatic way for modern TypeScript/JavaScript projects. Throwback ships with TypeScript types.
• MiddlewareFunction

  import type { MiddlewareFunction } from 'throwback';

  Import the `MiddlewareFunction` type for strongly typing your middleware functions in TypeScript.
• NextFunction

  import type { NextFunction } from 'throwback';

  Import the `NextFunction` type for strongly typing the `next` argument in your middleware functions in TypeScript.

Quickstart

Demonstrates how to compose asynchronous middleware functions and execute a stack with a context object and a final callback, showing the order of execution.

import { compose } from 'throwback';

const middlewareStack = [
  async function firstMiddleware(ctx, next) {
    console.log('1: Before next()');
    // 'next()' calls the next middleware in the stack or the final callback.
    await next();
    console.log('4: After next()');
  },
  async function secondMiddleware(ctx, next) {
    console.log('2: Calling next()');
    // You can optionally pass a new context to 'next()' which will replace it
    // for subsequent middleware in the stack and the final callback (since v3).
    // This is useful for request retries or modifying the context downstream.
    await next();
    console.log('3: Returning from next()');
  }
];

const composedApp = compose(middlewareStack);

// The composed function takes a context object and an optional final callback.
// The final callback runs at the end of the middleware stack, before the
// execution bubbles back up through the middleware.
composedApp({}, function finalCallback(ctx) {
  console.log('5: Final callback executed. Context:', ctx);
  ctx.status = 200;
});

/* Expected output:
1: Before next()
2: Calling next()
5: Final callback executed. Context: { status: 200 }
3: Returning from next()
4: After next()
*/