{"id":15372,"library":"ready-callback","title":"Ready Callback for Asynchronous Task Coordination","description":"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.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/node-modules/ready-callback","tags":["javascript","koa","ready","async","typescript"],"install":[{"cmd":"npm install ready-callback","lang":"bash","label":"npm"},{"cmd":"yarn add ready-callback","lang":"bash","label":"yarn"},{"cmd":"pnpm add ready-callback","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { ready } from 'ready-callback';\n// 'ready' is the default export (a factory function), not a named export.","symbol":"ready","correct":"import ready from 'ready-callback';\nconst appReady = ready();"},{"note":"For explicit class instantiation, import the named `Ready` class. The default export is a convenient factory function that essentially calls `new Ready()`.","wrong":"import Ready from 'ready-callback';\n// The default export is the factory function, not the class constructor itself.","symbol":"ReadyClass","correct":"import { Ready } from 'ready-callback';\nconst appReady = new Ready();"},{"note":"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.","wrong":"app.readyCallback = () => {};\n// Do not reassign, use the method provided after mixing in.","symbol":"readyCallback","correct":"app.readyCallback('serviceName');"}],"quickstart":{"code":"import Koa from 'koa';\nimport ready from 'ready-callback';\n\nconst app = new Koa();\nconst appReady = ready();\n\n// Mix the ready-callback functionality into your Koa application instance\nappReady.mixin(app);\n\n// Register an asynchronous service task\nconst dbConnectDone = app.readyCallback('databaseConnection');\nsetTimeout(() => {\n  console.log('Database connected!');\n  dbConnectDone(); // Mark the task as complete\n}, 1000);\n\n// Register another async task, e.g., loading config\nconst configLoadDone = app.readyCallback('configurationLoading', { timeout: 500 });\nsetTimeout(() => {\n  console.log('Configuration loaded!');\n  configLoadDone();\n}, 300);\n\n// The main application logic waits for all registered tasks\napp.ready(() => {\n  console.log('All async tasks are ready. Launching server...');\n  app.listen(3000, () => {\n    console.log('Server listening on http://localhost:3000');\n  });\n});\n\n// Example of error handling for a task\napp.on('error', (err, ctx) => {\n  console.error('Server error or ready-callback error:', err.message);\n  // Handle errors emitted by ready-callback if a task fails and is not weak\n});\n\n// Example of timeout handling\napp.on('ready_timeout', (id) => {\n  console.warn(`Task '${id}' timed out!`);\n});","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js runtime environment to version 16.0.0 or higher to use ready-callback v4.0.0+.","message":"Version 4.0.0 dropped support for Node.js versions older than 16. Applications running on Node.js 14 or earlier will not be compatible.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade your Node.js runtime environment to version 14.0.0 or higher. For v4.0.0+, Node.js 16+ is required.","message":"Version 3.0.0 dropped support for Node.js versions older than 14. Applications on Node.js 12 or earlier will not be compatible.","severity":"breaking","affected_versions":">=3.0.0 <4.0.0"},{"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});`.","message":"By 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Tasks 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Upgrade your Node.js environment to version 16.0.0 or newer. You can use tools like `nvm` to manage Node.js versions.","cause":"Attempting to use ready-callback v4.0.0 or higher on an unsupported Node.js runtime.","error":"Error: Node.js version is too low. Required Node.js >= 16.0.0"},{"fix":"Ensure you call `appReady.mixin(app);` after initializing `const appReady = ready();` and before calling `app.readyCallback()`.","cause":"The `ready-callback` functionality has not been mixed into the application instance (e.g., `Koa` app).","error":"TypeError: app.readyCallback is not a function"},{"fix":"For ESM, use `import ready from 'ready-callback';`. For CJS, use `const ready = require('ready-callback');` and then `const appReady = ready();`.","cause":"The `ready` factory function was not correctly imported or required.","error":"ReferenceError: ready is not defined"},{"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.","cause":"One or more asynchronous tasks registered with `app.readyCallback()` never called their `done()` function, preventing the overall 'ready' state from being reached.","error":"The `ready` callback never fires and the application hangs during startup."}],"ecosystem":"npm"}