![\"canc](\"https://raw.githubusercontent.com/cancjs/canc/master/assets/canc-logo.svg\" "\\"canc"){kind=logo}
\n \n \nGlobal handler that silences CancelError rejections from @cancjs/promise.\n
\n\n---\n\n## Introduction\n\nA canceled promise rejects with a `CancelError` by design. When a canceled promise is left without a rejection handler, JavaScript runtimes trigger an `unhandledRejection` event. In Node.js 15 and later, unhandled rejections terminate the process with a non-zero exit code.\n\nThis package registers a global rejection handler that filters out `CancelError` rejections while letting real errors pass through to default environment error handling or custom application callbacks. Adding a single import at your entry point prevents expected cancellation flow from crashing your application.\n\n## Features\n\n- Automatic environment detection supporting Node.js, Deno, Bun, web browsers, Web Workers, Service Workers, Cloudflare Workers, and Electron\n- One-line side-effect import for zero-config global registration\n- Explicit registration API with process-specific and environment-specific methods\n- Optional suppression scope widening for `AbortError` and `TimeoutError`\n- Synchronous custom callback support for custom logging or telemetry forwarding\n- Per-call and global warning controls for diagnostic feedback\n- Environment-safe guards that never throw in non-supported or custom JavaScript environments\n\n## Getting Started\n\n### Installation\n\n```sh\nnpm install @cancjs/unhandled-rejection @cancjs/promise\n```\n\n`@cancjs/promise` is a peer dependency. This package is ecosystem tier: a minor release can carry a breaking change, so pin it with a tilde, `~1.4` (pin the minor, not `~1.x`, which npm expands to the same range as `^1`), rather than the default caret. See [Versioning](https://github.com/cancjs/canc/blob/master/docs/versioning.md) for the full policy.\n\n### Usage\n\nSide-effect registration (automatic environment detection):\n\n```js\nimport '@cancjs/unhandled-rejection/register';\n```\n\nExplicit programmatic registration:\n\n```js\nimport { register } from '@cancjs/unhandled-rejection';\n\nregister();\n```\n\nCustom callback for unhandled non-cancellation errors:\n\n```js\nimport { register } from '@cancjs/unhandled-rejection';\n\nregister({\n onUnhandledRejection(reason, promise) {\n logger.error('Unhandled promise rejection:', reason);\n },\n});\n```\n\n## How It Works\n\n`@cancjs/unhandled-rejection` selects an environment-appropriate strategy during registration. In Node.js, Bun, and Electron main processes, it hooks `process.on('unhandledRejection')`. If the rejection reason is a `CancelError`, the handler returns silently. If the rejection is a real application error, the handler either delegates to your `onUnhandledRejection` callback or re-throws the error to preserve the runtime's default crash behavior.\n\nThe re-throw is not identical to the Node.js default. Without an `onUnhandledRejection` callback the handler throws the rejection reason from inside the listener, so the process still crashes, but it crashes with an uncaught exception rather than an `ERR_UNHANDLED_REJECTION` error. It also overrides `--unhandled-rejections=warn`: a process started with that flag would normally log and continue, and with this handler installed it exits. Pass `onUnhandledRejection` if you need to keep the process alive.\n\nIn web browsers, Deno, Web Workers, Service Workers, and Cloudflare Workers, it attaches an `unhandledrejection` event listener to `globalThis`. When a `CancelError` is encountered, the listener calls `event.preventDefault()` to prevent default browser console reporting or script termination. Non-cancellation rejections are passed to your custom callback (with `preventDefault()`) or left alone to let default runtime behavior proceed.\n\n## Description\n\n### Cancellation and unhandled rejection\n\nIn `@cancjs/promise`, cancellation is represented as a promise rejection using `CancelError`. When an operation is canceled, any pending promise chain rejects. If a consumer drops a promise reference or cancels an operation without attaching a `.catch()` or `catchCancel()` handler, the runtime receives an unhandled rejection event.\n\nTreating cancellation as rejection preserves standard `try`/`catch` control flow and async error propagation semantics. However, uncaught cancellation should not crash Node.js applications or pollute browser telemetry logs. `@cancjs/unhandled-rejection` provides global filtering to distinguish expected cancellation from actual runtime defects.\n\n### Environment detection\n\nThe `register()` function automatically detects your runtime environment in the following order:\n\n| Environment | Detection Rule | Registration Strategy |\n| ------------------ | ----------------------------- | ----------------------------------------------------- |\n| Bun | `globalThis.Bun` | `process.on('unhandledRejection')` |\n| Deno | `globalThis.Deno` | `globalThis.addEventListener('unhandledrejection')` |\n| Electron | `process.versions.electron` | `process.on()` plus the event listener when it exists |\n| Node.js | `process.versions.node` | `process.on('unhandledRejection')` |\n| Browsers / Workers | `globalThis.addEventListener` | `globalThis.addEventListener('unhandledrejection')` |\n\nBun, Deno, and Electron are all checked before `process.versions.node`, because all three define it. Deno 2 runs Node.js compatibility by default, so a `process.versions.node` check alone would take Deno down the Node.js path, and which path it took would depend on the Deno version. Bun uses the Node.js process hook, and the registration is labeled bun so duplicate registration warnings name the real environment. Deno uses the event listener, which it supports in both 1.x and 2.x. An Electron renderer has a Node.js process and a DOM, and renderer rejections land on the DOM event, so both targets are hooked there. An Electron main process has no `addEventListener` and gets the process hook only. Specific registration functions (`registerNode()`, `registerBrowser()`, `registerDeno()`, `registerBun()`, `registerWorker()`, `registerElectron()`) are also exported for explicit control.\n\n### Widening the suppression scope\n\nBy default, only `CancelError` instances are suppressed. You can widen the suppression scope to include `AbortError` or `TimeoutError` by passing optional boolean flags:\n\n```ts\nimport { register } from '@cancjs/unhandled-rejection';\n\nregister({\n abort: true,\n timeout: true,\n});\n```\n\nWhen `abort: true` is set, the handler silences raw `AbortError` instances as well as `CancelError` instances wrapping an abort (where `error.aborted === true`). When `timeout: true` is set, the handler silences raw `TimeoutError` instances as well as `CancelError` instances wrapping a timeout (where `error.timedOut === true`). This matches the predicate matching behavior of `catchCancel` and `suppressCancel` in `@cancjs/promise`. Enable these options if your application frequently aborts `fetch` requests or uses operation timeouts.\n\n### Custom rejection handling\n\nWhen passing `onUnhandledRejection`, your custom function receives `(reason, promise)` for all non-suppressed rejections. In Node.js, specifying a custom callback suppresses default process termination and forwards non-cancellation errors to your function. In browser environments, specifying a custom callback calls `preventDefault()` on the event and routes the error to your callback.\n\nYour `onUnhandledRejection` callback must execute synchronously. Runtimes fire rejection events synchronously and ignore returned promises. If an asynchronous callback rejects, it creates a secondary unhandled rejection. Start async operations inside your callback and handle their errors explicitly:\n\n```js\nregister({\n onUnhandledRejection(reason) {\n sendTelemetry(reason).catch(console.error);\n },\n});\n```\n\n### Integration with error reporting services\n\nWhen using error tracking SDKs like Sentry, Datadog, or Bugsnag, register `@cancjs/unhandled-rejection` before initializing your SDK. For example, with Sentry:\n\n```js\nimport { register } from '@cancjs/unhandled-rejection';\nimport * as Sentry from '@sentry/node';\n\nregister();\n\nSentry.init({\n dsn: 'https://example@sentry.io/123',\n beforeSend(event, hint) {\n if (hint && hint.originalException && hint.originalException.name === 'CancelError') {\n return null;\n }\n return event;\n },\n});\n```\n\nRegistering `@cancjs/unhandled-rejection` first prevents Node.js process termination, while adding a `beforeSend` filter prevents `CancelError` events from generating unnecessary telemetry alerts.\n\n### Integration with existing handlers\n\nEvent listeners for `unhandledrejection` and `process.on('unhandledRejection')` are additive. Attaching `@cancjs/unhandled-rejection` does not remove existing process listeners. If your application or a third-party framework registers a custom rejection listener, that listener will still receive `CancelError` objects unless it includes an explicit `isCancelError` check:\n\n```js\nimport { isCancelError } from '@cancjs/promise';\n\nprocess.on('unhandledRejection', (reason) => {\n if (isCancelError(reason)) {\n return;\n }\n customLogger.error(reason);\n});\n```\n\n### Manual recipes\n\nFor library authors, custom test harnesses, or exotic runtimes where global package registration is not desired, use these manual recipes:\n\nNode.js and Bun:\n\n```js\nimport { isCancelError } from '@cancjs/promise';\n\nprocess.on('unhandledRejection', (reason) => {\n if (!isCancelError(reason)) {\n throw reason;\n }\n});\n```\n\nNode.js and Bun with abort and timeout widening:\n\n```js\nimport { isCancelError } from '@cancjs/promise';\nimport { isAbortError, isTimeoutError } from '@cancjs/toolbox';\n\nprocess.on('unhandledRejection', (reason) => {\n const isSuppressed =\n isCancelError(reason) ||\n isAbortError(reason) ||\n isTimeoutError(reason) ||\n (isCancelError(reason) && (reason.aborted || reason.timedOut));\n\n if (!isSuppressed) {\n throw reason;\n }\n});\n```\n\nBrowsers, Deno, and Web Workers:\n\n```js\nimport { isCancelError } from '@cancjs/promise';\n\nglobalThis.addEventListener('unhandledrejection', (event) => {\n if (isCancelError(event.reason)) {\n event.preventDefault();\n }\n});\n```\n\nBrowsers, Deno, and Web Workers with abort and timeout widening:\n\n```js\nimport { isCancelError } from '@cancjs/promise';\nimport { isAbortError, isTimeoutError } from '@cancjs/toolbox';\n\nglobalThis.addEventListener('unhandledrejection', (event) => {\n const reason = event.reason;\n const isSuppressed =\n isCancelError(reason) ||\n isAbortError(reason) ||\n isTimeoutError(reason) ||\n (isCancelError(reason) && (reason.aborted || reason.timedOut));\n\n if (isSuppressed) {\n event.preventDefault();\n }\n});\n```\n\nCustom logging pattern (Node.js):\n\n```js\nimport { isCancelError } from '@cancjs/promise';\n\nprocess.on('unhandledRejection', (reason) => {\n if (isCancelError(reason)) {\n return;\n }\n logger.error('Unhandled rejection:', reason);\n});\n```\n\nElectron applications:\n\n```js\n// Call register() in main.js and renderer.js entry points\nimport { register } from '@cancjs/unhandled-rejection';\n\nregister();\n```\n\n### Warnings and diagnostics\n\n`@cancjs/unhandled-rejection` logs diagnostic warnings to `console.warn` when duplicate registrations occur or when a process-specific handler is invoked in an incompatible environment.\n\nDisable warnings globally at runtime:\n\n```js\nimport { setWarn } from '@cancjs/unhandled-rejection';\n\nsetWarn(false);\n```\n\nDisable warnings per registration call:\n\n```js\nimport { register } from '@cancjs/unhandled-rejection';\n\nregister({ warn: false });\n```\n\nDisable warnings using environment variables (Node.js/Bun):\n\n```sh\nCANC_UNHANDLED_WARN=0 node app.js\n```\n\n### Library authors\n\nLibraries should not invoke `register()` or `@cancjs/unhandled-rejection/register`. Global rejection handling is an application-level concern. Library code should handle expected cancellation using `catchCancel` or `suppressCancel` from `@cancjs/promise` at internal flow boundaries.\n\n## API\n\n### Registration functions\n\n- `register(options?: RegisterOptions): void`: Autodetects the host environment and installs the corresponding rejection handler.\n- `registerNode(options?: RegisterOptions): void`: Installs a Node.js process listener. Logs a warning if `process.on` is unavailable.\n- `registerBrowser(options?: RegisterOptions): void`: Installs a browser `globalThis` event listener. Logs a warning if `addEventListener` is unavailable.\n- `registerDeno(options?: RegisterOptions): void`: Installs a Deno global event listener.\n- `registerBun(options?: RegisterOptions): void`: Installs a Bun rejection handler through the Node.js process hook.\n- `registerWorker(options?: RegisterOptions): void`: Installs a Web Worker / Service Worker event listener.\n- `registerElectron(options?: RegisterOptions): void`: Installs the process listener and, in a renderer, the `globalThis` event listener as well. Outside Electron it falls back to `register()`.\n\n### Lifecycle & Configuration\n\n- `unregister(): void`: Removes all handlers registered by this package and resets registration tracking.\n- `setWarn(enabled: boolean): void`: Globally enables or disables diagnostic warnings.\n\n### Types\n\n```ts\ninterface RegisterOptions {\n warn?: boolean;\n abort?: boolean;\n timeout?: boolean;\n onUnhandledRejection?: (reason: unknown, promise?: Promise