safe-timeouts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aryan Tiwari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,278 @@
+# safe-timeout
+
+**Deadline-based timeouts for async Node.js code with AbortSignal support.**
+
+[![npm version](https://img.shields.io/npm/v/safe-timeout)](https://www.npmjs.com/package/safe-timeout)
+[![npm downloads](https://img.shields.io/npm/dm/safe-timeout)](https://www.npmjs.com/package/safe-timeout)
+[![license](https://img.shields.io/npm/l/safe-timeout)](./LICENSE)
+[![types](https://img.shields.io/npm/types/safe-timeout)](https://www.npmjs.com/package/safe-timeout)
+[![node](https://img.shields.io/node/v/safe-timeout)](https://nodejs.org)
+
+Promise-based deadline enforcement for async code in Node.js. `safe-timeout` helps you apply a **single execution deadline** across async functions, services, and external calls using standard `AbortSignal` semantics.
+
+---
+
+## Why this exists
+
+In real backend systems, timeouts are **end-to-end**, not per-function:
+
+* An HTTP request has a deadline
+* That deadline must apply across DB calls, service logic, and external APIs
+* Nested functions should **not accidentally extend** the available time
+
+Most timeout utilities fail here because they:
+
+* don’t propagate context
+* don’t compose across nested calls
+* don’t integrate with `AbortSignal`
+
+`safe-timeout` solves this correctly.
+
+---
+
+## Installation
+
+```bash
+npm install safe-timeout
+```
+
+Node.js >= 16 is required.
+
+---
+
+## Basic usage
+
+```ts
+import { withTimeout, TimeoutError } from "safe-timeout";
+import axios from "axios";
+
+try {
+  const result = await withTimeout(2000, async (signal) => {
+    const res = await axios.get("https://api.example.com/users", { signal });
+    return res.data;
+  });
+
+  console.log(result);
+} catch (err) {
+  if (err instanceof TimeoutError) {
+    console.error("Request timed out");
+  }
+}
+```
+
+What happens:
+
+* A 2s deadline is created
+* An `AbortController` is started internally
+* If the deadline is exceeded:
+
+  * the promise rejects with `TimeoutError`
+  * the `AbortSignal` is aborted
+  * Axios cancels the HTTP request
+
+---
+
+## Nested timeouts (key feature)
+
+Deadlines **propagate and compose automatically**.
+
+```ts
+await withTimeout(3000, async () => {
+  await serviceA();          // uses part of the budget
+
+  await withTimeout(5000, async () => {
+    await serviceB();        // still limited by the original 3s
+  });
+});
+```
+
+The inner timeout **cannot extend** the outer deadline.
+
+This makes time budgets safe and deterministic.
+
+---
+
+## Using with services (multiple layers)
+
+```ts
+import axios from "axios";
+
+await withTimeout(2000, async (signal) => {
+  await controller(signal);
+});
+
+async function controller(signal) {
+  await serviceA(signal);
+}
+
+async function serviceA(signal) {
+  await serviceB(signal);
+}
+
+async function serviceB(signal) {
+  const res = await axios.get("/users", { signal });
+  return res.data;
+}
+```
+
+All functions share the same deadline by passing the same `AbortSignal` down the call chain.
+
+---
+
+## Abort-aware vs non-abort-aware operations
+
+### Abort-aware APIs (cancel immediately)
+
+These stop execution as soon as the deadline is exceeded:
+
+* `fetch` (Node 18+)
+* `axios` (with `{ signal }`)
+* `fs/promises` (partial)
+* `stream.pipeline`
+* `timers/promises`
+
+Example:
+
+```ts
+    // GET
+    await axios.get(url, { signal }); // 👈 AbortSignal goes here
+    // POST
+    await axios.post(
+      url,
+      { name: "Aryan", role: "admin" },
+      {
+        signal, // 👈 AbortSignal goes here
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: "Bearer YOUR_TOKEN",
+        },
+      })
+
+```
+
+### Non-abort-aware operations (cooperative)
+
+These **cannot be forcibly stopped**:
+
+* `setTimeout` / sleep
+* Sequelize queries
+* CPU-bound loops
+* legacy libraries
+
+For these, `safe-timeout`:
+
+* stops waiting
+* rejects the outer promise
+* allows you to guard further logic
+
+---
+
+## Non-abort-aware operations and control flow
+
+JavaScript cannot forcibly stop non-abort-aware operations (like `setTimeout`, Sequelize queries, or CPU-bound work).
+
+When such operations exceed the deadline:
+
+* `safe-timeout` rejects the outer promise
+* abort-aware APIs are cancelled automatically
+* JavaScript execution resumes only when the pending operation completes
+
+To keep control flow predictable:
+
+* prefer calling abort-aware APIs (Axios, fetch, streams) after non-abort-aware work
+* abort-aware APIs will throw immediately if the deadline has already been exceeded
+
+This design avoids hidden global checks while remaining honest about JavaScript limitations.
+
+---
+
+## Axios integration
+
+`safe-timeout` works with Axios by passing the provided `AbortSignal` to the request.
+
+```ts
+import axios from "axios";
+import { withTimeout } from "safe-timeout";
+
+await withTimeout(2000, async (signal) => {
+  const res = await axios.get("/users", { signal });
+  return res.data;
+});
+```
+
+Axios is abort-aware:
+
+* if the deadline is exceeded before the request starts, Axios throws immediately
+* if the deadline is exceeded while the request is in flight, Axios cancels the request
+
+This explicit integration keeps cancellation predictable and avoids hidden behavior.
+
+---
+
+## What `safe-timeout` does NOT do
+
+It is important to be explicit about limitations:
+
+* ❌ It cannot forcibly stop JavaScript execution
+* ❌ It cannot cancel non-abort-aware libraries
+* ❌ It cannot stop CPU-bound loops
+* ❌ It does not replace DB-level timeouts
+
+This matches the realities of Node.js and modern async runtimes.
+
+---
+
+## How this differs from `setTimeout`
+
+| Feature             | setTimeout | safe-timeout |
+| ------------------- | ---------- | ------------ |
+| End-to-end deadline | ❌          | ✅            |
+| Nested composition  | ❌          | ✅            |
+| AbortSignal support | ❌          | ✅            |
+| Context propagation | ❌          | ✅            |
+| Concurrency-safe    | ❌          | ✅            |
+
+`setTimeout` works locally. `safe-timeout` works across your entire async call graph.
+
+---
+
+## API
+
+### `withTimeout(ms, fn)`
+
+Runs an async function with a deadline.
+
+```ts
+withTimeout<T>(ms: number, fn: (signal: AbortSignal) => Promise<T>): Promise<T>
+```
+
+Rejects with `TimeoutError` when the deadline is exceeded.
+
+---
+
+### `TimeoutError`
+
+Error thrown when the deadline is exceeded.
+
+```ts
+instanceof TimeoutError === true
+```
+
+---
+
+## When to use this
+
+Use `safe-timeout` when:
+
+* you want request-level deadlines
+* you call multiple async services
+* you rely on Axios, fetch, or streams
+* you want correct nested timeout behavior
+
+Do **not** use it as a replacement for DB-level query timeouts.
+
+---
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,16 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+declare function withTimeout<T>(ms: number, fn: (signal: AbortSignal) => Promise<T>): Promise<T>;
+
+type TimeoutContext = {
+    deadline: number;
+    controller: AbortController;
+};
+
+declare const timeoutContext: AsyncLocalStorage<TimeoutContext>;
+
+declare class TimeoutError extends Error {
+    constructor(message?: string);
+}
+
+export { TimeoutError, timeoutContext, withTimeout };

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+declare function withTimeout<T>(ms: number, fn: (signal: AbortSignal) => Promise<T>): Promise<T>;
+
+type TimeoutContext = {
+    deadline: number;
+    controller: AbortController;
+};
+
+declare const timeoutContext: AsyncLocalStorage<TimeoutContext>;
+
+declare class TimeoutError extends Error {
+    constructor(message?: string);
+}
+
+export { TimeoutError, timeoutContext, withTimeout };

package/dist/index.js

@@ -0,0 +1,77 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  TimeoutError: () => TimeoutError,
+  timeoutContext: () => timeoutContext,
+  withTimeout: () => withTimeout
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/context.ts
+var import_node_async_hooks = require("async_hooks");
+var timeoutContext = new import_node_async_hooks.AsyncLocalStorage();
+
+// src/errors.ts
+var TimeoutError = class extends Error {
+  constructor(message = "Operation timed out") {
+    super(message);
+    this.name = "TimeoutError";
+  }
+};
+
+// src/withTimeout.ts
+async function withTimeout(ms, fn) {
+  const parent = timeoutContext.getStore();
+  const now = Date.now();
+  const deadline = parent ? Math.min(parent.deadline, now + ms) : now + ms;
+  if (deadline <= now) {
+    throw new TimeoutError();
+  }
+  const controller = new AbortController();
+  const remaining = deadline - now;
+  const timer = setTimeout(() => {
+    controller.abort();
+  }, remaining);
+  try {
+    return await timeoutContext.run(
+      { deadline, controller },
+      () => Promise.race([
+        fn(controller.signal),
+        new Promise((_, reject) => {
+          controller.signal.addEventListener(
+            "abort",
+            () => reject(new TimeoutError()),
+            { once: true }
+          );
+        })
+      ])
+    );
+  } finally {
+    clearTimeout(timer);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TimeoutError,
+  timeoutContext,
+  withTimeout
+});

package/dist/index.mjs

@@ -0,0 +1,48 @@
+// src/context.ts
+import { AsyncLocalStorage } from "async_hooks";
+var timeoutContext = new AsyncLocalStorage();
+
+// src/errors.ts
+var TimeoutError = class extends Error {
+  constructor(message = "Operation timed out") {
+    super(message);
+    this.name = "TimeoutError";
+  }
+};
+
+// src/withTimeout.ts
+async function withTimeout(ms, fn) {
+  const parent = timeoutContext.getStore();
+  const now = Date.now();
+  const deadline = parent ? Math.min(parent.deadline, now + ms) : now + ms;
+  if (deadline <= now) {
+    throw new TimeoutError();
+  }
+  const controller = new AbortController();
+  const remaining = deadline - now;
+  const timer = setTimeout(() => {
+    controller.abort();
+  }, remaining);
+  try {
+    return await timeoutContext.run(
+      { deadline, controller },
+      () => Promise.race([
+        fn(controller.signal),
+        new Promise((_, reject) => {
+          controller.signal.addEventListener(
+            "abort",
+            () => reject(new TimeoutError()),
+            { once: true }
+          );
+        })
+      ])
+    );
+  } finally {
+    clearTimeout(timer);
+  }
+}
+export {
+  TimeoutError,
+  timeoutContext,
+  withTimeout
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "safe-timeouts",
+  "version": "0.1.0",
+  "description": "Deadline-based timeouts for async code in Node.js. Enforce end-to-end execution deadlines with automatic propagation and AbortSignal support.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yetanotheraryan/safe-timeout.git"
+  },
+  "keywords": [
+    "timeout",
+    "deadline",
+    "abortcontroller",
+    "abortsignal",
+    "async",
+    "nodejs",
+    "axios",
+    "fetch",
+    "structured-concurrency",
+    "async-hooks"
+  ],
+  "author": "Aryan Tiwari",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/yetanotheraryan/safe-timeout/issues"
+  },
+  "homepage": "https://github.com/yetanotheraryan/safe-timeout#readme",
+  "devDependencies": {
+    "@types/node": "^25.0.9",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}