safe-timeouts 0.1.2 → 0.1.3

package/README.md

@@ -3,6 +3,7 @@
 **Deadline-based timeouts for async Node.js code with AbortSignal support.**
 
 ![NPM Version](https://img.shields.io/npm/v/safe-timeouts)
+![NPM Downloads](https://img.shields.io/npm/dw/safe-timeouts)
 ![GitHub package.json version](https://img.shields.io/github/package-json/v/yetanotheraryan/safe-timeouts?style=flat-square&color=blue)
 ![GitHub last commit](https://img.shields.io/github/last-commit/yetanotheraryan/safe-timeouts)
 ![GitHub contributors](https://img.shields.io/github/contributors/yetanotheraryan/safe-timeouts)
@@ -45,16 +46,20 @@ Node.js >= 16 is required.
 ## Basic usage
 
 ```ts
-import { withTimeout, TimeoutError } from "safe-timeouts";
+import { withTimeout, TimeoutError, safeAxios } from "safe-timeouts";
 import axios from "axios";
 
 try {
-  const result = await withTimeout(2000, async (signal) => {
-    const res = await axios.get("https://api.example.com/users", { signal });
+  const resultWithSafeAxios = await withTimeout(2000, async () => {
+    const res = await safeAxios.get("https://api.example.com/users"); // no signal to be passed.
+    return res.data;
+  });
+
+  const resultWithAxios = await withTimeout(2000, async (signal) => { // signal to be taken.
+    const res = await axios.get("https://api.example.com/users", {signal}); // signal to be passed.
     return res.data;
   });
 
-  console.log(result);
 } catch (err) {
   if (err instanceof TimeoutError) {
     console.error("Request timed out");
@@ -94,7 +99,77 @@ This makes time budgets safe and deterministic.
 
 ---
 
-## Using with services (multiple layers)
+## safeAxios (optional helper but recommended)
+
+`safeAxios` is a **convenience wrapper** around Axios that automatically integrates with safe-timeouts.
+
+When used inside withTimeout, HTTP requests are automatically cancellable.
+When used outside withTimeout, it behaves exactly like a normal Axios instance.
+
+Example
+```ts
+import { withTimeout, safeAxios } from "safe-timeouts";
+
+await withTimeout(2000, async () => {
+  const res = await safeAxios.get("/users");
+  return res.data;
+});
+```
+
+
+### Custom Axios instance can also be created
+```ts
+import { withTimeout, createSafeAxios } from "safe-timeouts";
+
+const api = createSafeAxios({
+  baseURL: "https://api.example.com",
+});
+
+await withTimeout(1000, async () => {
+  await api.post("/sync");
+});
+```
+
+## How it works (context propagation)
+
+safe-timeouts uses AsyncLocalStorage to propagate timeout context across async boundaries.
+
+Example flow
+```ts
+await withTimeout(2000, async () => {
+  await controller();
+});
+
+async function controller() {
+  return serviceA();
+}
+
+async function serviceA() {
+  return serviceB();
+}
+
+async function serviceB() {
+  return safeAxios.get("/users");
+}
+
+
+Context flow diagram
+withTimeout
+  └─ Async context (deadline + AbortController)
+       ├─ controller()
+       │    └─ serviceA()
+       │         └─ serviceB()
+       │              └─ safeAxios.get()
+       │                   └─ axios(request + signal)
+
+```
+The timeout context is created once
+Node automatically propagates it across async calls
+**safeAxios reads the context at request time When the deadline expires, the request is aborted**
+
+---
+
+## Using with services (multiple layers) without safeAxios
 
 ```ts
 import axios from "axios";
@@ -136,6 +211,20 @@ These stop execution as soon as the deadline is exceeded:
 Example:
 
 ```ts
+    // GET
+    await safeAxios.get(url); // 👈 No AbortSignal needed
+    // POST
+    await safeAxios.post(
+      url,
+      { name: "Aryan", role: "admin" },
+      {
+       // 👈 No AbortSignal goes here
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: "Bearer YOUR_TOKEN",
+        },
+      })
+
     // GET
     await axios.get(url, { signal }); // 👈 AbortSignal goes here
     // POST

package/dist/index.d.mts

@@ -1,3 +1,5 @@
+import * as axios from 'axios';
+import { AxiosRequestConfig, AxiosInstance } from 'axios';
 import { AsyncLocalStorage } from 'node:async_hooks';
 
 declare function withTimeout<T>(ms: number, fn: (signal: AbortSignal) => Promise<T>): Promise<T>;
@@ -13,4 +15,12 @@ declare class TimeoutError extends Error {
     constructor(message?: string);
 }
 
-export { TimeoutError, timeoutContext, withTimeout };
+/**
+ * Axios instance that automatically attaches AbortSignal
+ * from the current safe-timeout context (if present).
+ */
+declare function createSafeAxios(config?: AxiosRequestConfig): AxiosInstance;
+
+declare const safeAxios: axios.AxiosInstance;
+
+export { TimeoutError, createSafeAxios, safeAxios, timeoutContext, withTimeout };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import * as axios from 'axios';
+import { AxiosRequestConfig, AxiosInstance } from 'axios';
 import { AsyncLocalStorage } from 'node:async_hooks';
 
 declare function withTimeout<T>(ms: number, fn: (signal: AbortSignal) => Promise<T>): Promise<T>;
@@ -13,4 +15,12 @@ declare class TimeoutError extends Error {
     constructor(message?: string);
 }
 
-export { TimeoutError, timeoutContext, withTimeout };
+/**
+ * Axios instance that automatically attaches AbortSignal
+ * from the current safe-timeout context (if present).
+ */
+declare function createSafeAxios(config?: AxiosRequestConfig): AxiosInstance;
+
+declare const safeAxios: axios.AxiosInstance;
+
+export { TimeoutError, createSafeAxios, safeAxios, timeoutContext, withTimeout };

package/dist/index.js

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,21 +17,47 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
   TimeoutError: () => TimeoutError,
+  createSafeAxios: () => createSafeAxios,
+  safeAxios: () => safeAxios,
   timeoutContext: () => timeoutContext,
   withTimeout: () => withTimeout
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/safeAxios.ts
+var import_axios = __toESM(require("axios"));
+
 // src/context.ts
 var import_node_async_hooks = require("async_hooks");
 var timeoutContext = new import_node_async_hooks.AsyncLocalStorage();
 
+// src/safeAxios.ts
+function createSafeAxios(config) {
+  const instance = import_axios.default.create(config);
+  instance.interceptors.request.use((req) => {
+    const ctx = timeoutContext.getStore();
+    if (ctx?.controller && !req.signal) {
+      req.signal = ctx.controller.signal;
+    }
+    return req;
+  });
+  return instance;
+}
+
 // src/errors.ts
 var TimeoutError = class extends Error {
   constructor(message = "Operation timed out") {
@@ -69,9 +97,14 @@ async function withTimeout(ms, fn) {
     clearTimeout(timer);
   }
 }
+
+// src/index.ts
+var safeAxios = createSafeAxios();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   TimeoutError,
+  createSafeAxios,
+  safeAxios,
   timeoutContext,
   withTimeout
 });

package/dist/index.mjs

@@ -1,7 +1,23 @@
+// src/safeAxios.ts
+import axios from "axios";
+
 // src/context.ts
 import { AsyncLocalStorage } from "async_hooks";
 var timeoutContext = new AsyncLocalStorage();
 
+// src/safeAxios.ts
+function createSafeAxios(config) {
+  const instance = axios.create(config);
+  instance.interceptors.request.use((req) => {
+    const ctx = timeoutContext.getStore();
+    if (ctx?.controller && !req.signal) {
+      req.signal = ctx.controller.signal;
+    }
+    return req;
+  });
+  return instance;
+}
+
 // src/errors.ts
 var TimeoutError = class extends Error {
   constructor(message = "Operation timed out") {
@@ -41,8 +57,13 @@ async function withTimeout(ms, fn) {
     clearTimeout(timer);
   }
 }
+
+// src/index.ts
+var safeAxios = createSafeAxios();
 export {
   TimeoutError,
+  createSafeAxios,
+  safeAxios,
   timeoutContext,
   withTimeout
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "safe-timeouts",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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",
@@ -34,5 +34,8 @@
     "@types/node": "^25.0.9",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "axios": "^1.13.2"
   }
-}
+}