Registry / web-framework / ready-callback

ready-callback

library4.0.0jsnpmunverified

ready-callback is a utility library designed to manage the readiness of a server or application after a series of asynchronous tasks have completed. It's particularly useful in scenarios where a server needs to wait for database connections, external service initializations, or other long-running setup processes before it can start accepting requests. The current stable version is 4.0.0, released in October 2023. This package has a moderate release cadence, with major versions aligning with Node.js LTS updates. Key differentiators include its simple callback-based API for registering tasks, robust error handling with optional 'weak' dependencies, and configurable timeouts for individual tasks or the overall ready process. It also provides status updates during task completion. Originally used heavily within the Egg.js framework ecosystem, it offers a pragmatic solution for orchestrating application startup sequences.

web-framework

npm install ready-callback

github ↗package ↗

INSTALL

IMPORT

SIG · READY-CALLBACK

ready-callback

web-frameworkjavascriptv4.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ready

✓ import ready from 'ready-callback'; const appReady = ready();

✗ import { ready } from 'ready-callback'; // 'ready' is the default export (a factory function), not a named export.

The default export is a factory function that returns a `Ready` instance. While CommonJS might use `require('ready-callback')()` directly, ESM users should import the factory function and then call it.

ReadyClass

✓ import { Ready } from 'ready-callback'; const appReady = new Ready();

✗ import Ready from 'ready-callback'; // The default export is the factory function, not the class constructor itself.

For explicit class instantiation, import the named `Ready` class. The default export is a convenient factory function that essentially calls `new Ready()`.

readyCallback

✓ app.readyCallback('serviceName');

✗ app.readyCallback = () => {}; // Do not reassign, use the method provided after mixing in.

The `readyCallback` method is added to your application instance (e.g., a Koa app) via `ready.mixin(app)`. It's used to register an individual asynchronous task.

Demonstrates initializing `ready-callback` with Koa, registering multiple asynchronous tasks, handling their completion, and launching the server only when all tasks are complete, including error and timeout handling.

import Koa from 'koa'; import ready from 'ready-callback'; const app = new Koa(); const appReady = ready(); // Mix the ready-callback functionality into your Koa application instance appReady.mixin(app); // Register an asynchronous service task const dbConnectDone = app.readyCallback('databaseConnection'); setTimeout(() => { console.log('Database connected!'); dbConnectDone(); // Mark the task as complete }, 1000); // Register another async task, e.g., loading config const configLoadDone = app.readyCallback('configurationLoading', { timeout: 500 }); setTimeout(() => { console.log('Configuration loaded!'); configLoadDone(); }, 300); // The main application logic waits for all registered tasks app.ready(() => { console.log('All async tasks are ready. Launching server...'); app.listen(3000, () => { console.log('Server listening on http://localhost:3000'); }); }); // Example of error handling for a task app.on('error', (err, ctx) => { console.error('Server error or ready-callback error:', err.message); // Handle errors emitted by ready-callback if a task fails and is not weak }); // Example of timeout handling app.on('ready_timeout', (id) => { console.warn(`Task '${id}' timed out!`); });

Debug

Known issues

breakingVersion 4.0.0 dropped support for Node.js versions older than 16. Applications running on Node.js 14 or earlier will not be compatible.

fix

Upgrade your Node.js runtime environment to version 16.0.0 or higher to use ready-callback v4.0.0+.

affects: >=4.0.0

breakingVersion 3.0.0 dropped support for Node.js versions older than 14. Applications on Node.js 12 or earlier will not be compatible.

fix

Upgrade your Node.js runtime environment to version 14.0.0 or higher. For v4.0.0+, Node.js 16+ is required.

affects: >=3.0.0 <4.0.0

gotchaBy default, if a task's callback (e.g., `done(err)`) is called with an error, the `ready` process will halt, and an 'error' event will be emitted on the main instance (e.g., `app.on('error', ...)`) but `app.ready()` will never be called.

fix

Implement robust error handling by listening to the 'error' event on the instance (`app.on('error', callback)`). If you want tasks to complete without blocking the ready process on error, mark them as weak dependencies: `app.readyCallback('service', {isWeakDep: true});` or initialize with `ready({isWeakDep: true});`.

affects: >=1.0.0

gotchaTasks can be configured with a timeout. If a task does not complete (call its `done()` callback) within the specified timeout, a `ready_timeout` event will be emitted, but the ready process may continue depending on whether the task is critical or weak.

fix

Listen for the `ready_timeout` event (`app.on('ready_timeout', (id) => { ... })`) to detect and log tasks that take too long. Adjust timeout values as appropriate for your service's startup characteristics.

affects: >=1.0.0

gotchaWhen using `ready-callback` in TypeScript, ensure you import types correctly. While it ships with types, improper imports (e.g., trying to directly `import Ready from 'ready-callback'` for the class) can lead to type mismatches.

fix

For the factory function, use `import ready from 'ready-callback';`. For the class constructor, use `import { Ready } from 'ready-callback';`. The package is fully TypeScript-refactored since v4.0.0.

affects: >=4.0.0

Errors

Common errors & fixes

Error: Node.js version is too low. Required Node.js >= 16.0.0

Attempting to use ready-callback v4.0.0 or higher on an unsupported Node.js runtime.

fix

Upgrade your Node.js environment to version 16.0.0 or newer. You can use tools like `nvm` to manage Node.js versions.

TypeError: app.readyCallback is not a function

The `ready-callback` functionality has not been mixed into the application instance (e.g., `Koa` app).

fix

Ensure you call `appReady.mixin(app);` after initializing `const appReady = ready();` and before calling `app.readyCallback()`.

ReferenceError: ready is not defined

The `ready` factory function was not correctly imported or required.

fix

For ESM, use `import ready from 'ready-callback';`. For CJS, use `const ready = require('ready-callback');` and then `const appReady = ready();`.

The `ready` callback never fires and the application hangs during startup.

One or more asynchronous tasks registered with `app.readyCallback()` never called their `done()` function, preventing the overall 'ready' state from being reached.

fix

Review your asynchronous task implementations to ensure that `done()` is always called, even in error conditions. Utilize timeouts (`{ timeout: ms }`) to detect hanging tasks, and consider `isWeakDep: true` for non-critical tasks.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/node-modules/ready-callback ↗

packagehttps://www.npmjs.com/package/ready-callback ↗