timefence 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tung Tran
+
+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,86 @@
+# timefence
+
+> Put a **time limit** on any promise — with real **`AbortSignal` cancellation** and a composable **deadline** signal. **Zero dependencies**.
+
+[![CI](https://github.com/trananhtung/timefence/actions/workflows/ci.yml/badge.svg)](https://github.com/trananhtung/timefence/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/timefence.svg)](https://www.npmjs.com/package/timefence)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/timefence)](https://bundlephobia.com/package/timefence)
+[![types](https://img.shields.io/npm/types/timefence.svg)](https://www.npmjs.com/package/timefence)
+[![license](https://img.shields.io/npm/l/timefence.svg)](./LICENSE)
+
+`Promise.race([op, timer])` "times out" — but the slow operation keeps running in
+the background, holding a socket open and burning quota. `timefence` gives the
+operation an `AbortSignal` that fires on timeout, so the underlying `fetch` (or any
+cooperative work) is actually **cancelled**, not just ignored.
+
+```ts
+import { withTimeout } from "timefence";
+
+// On timeout, the fetch is aborted — not left dangling.
+const res = await withTimeout((signal) => fetch(url, { signal }), 5000);
+```
+
+## Why timefence?
+
+- **Real cancellation.** The function form receives an `AbortSignal` that fires on
+  timeout *or* when your own `signal` aborts — wire it to `fetch`/streams.
+- **Fallback or throw.** Reject with a typed `TimeoutError`, or resolve with a
+  `fallback` value when you'd rather degrade than fail.
+- **Composable deadlines.** `deadline(ms, signal?)` returns an `AbortSignal` that
+  trips after `ms` (or earlier if your signal aborts) — like `AbortSignal.timeout`
+  but composable, with an `unref`'d timer so it won't keep Node alive.
+- **Zero dependencies**, ESM + CJS + types.
+
+## Install
+
+```bash
+npm install timefence
+# or: pnpm add timefence  /  yarn add timefence  /  bun add timefence
+```
+
+## API
+
+### `withTimeout(input, ms, options?) → Promise<T>`
+
+`input` is a promise, or `(signal) => Promise` (preferred — enables cancellation).
+
+```ts
+await withTimeout(slowPromise, 1000);                         // throws TimeoutError
+await withTimeout((s) => fetch(url, { signal: s }), 1000);     // aborts the fetch
+await withTimeout(loadFresh(), 800, { fallback: () => cached });
+```
+
+| Option     | Type                    | Default | Description                                          |
+| ---------- | ----------------------- | ------- | ---------------------------------------------------- |
+| `message`  | `string`                | —       | Message for the thrown `TimeoutError`.               |
+| `signal`   | `AbortSignal`           | —       | Cancel early from outside (rejects with its reason). |
+| `fallback` | `() => T \| Promise<T>` | —       | Resolve with this on timeout instead of throwing.    |
+
+`ms = Infinity` disables the timeout while still honoring `signal`.
+
+### `deadline(ms, signal?) → AbortSignal`
+
+```ts
+const signal = deadline(10_000, userSignal);
+await fetch(url, { signal });          // aborts after 10s, or when userSignal does
+```
+
+### `TimeoutError` / `isTimeoutError(err)`
+
+```ts
+try {
+  await withTimeout(op, 1000);
+} catch (err) {
+  if (isTimeoutError(err)) retryOrDegrade();
+  else throw err;
+}
+```
+
+## Pairs well with
+
+- [`retryfn`](https://www.npmjs.com/package/retryfn) — retry an operation that timed out.
+- [`runpool`](https://www.npmjs.com/package/runpool) / [`ratebucket`](https://www.npmjs.com/package/ratebucket) — bound concurrency and rate; `timefence` bounds *time*.
+
+## License
+
+[MIT](./LICENSE) © Tung Tran

package/dist/index.cjs

@@ -0,0 +1,127 @@
+"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 src_exports = {};
+__export(src_exports, {
+  TimeoutError: () => TimeoutError,
+  deadline: () => deadline,
+  isTimeoutError: () => isTimeoutError,
+  withTimeout: () => withTimeout
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/timeout.ts
+var TimeoutError = class extends Error {
+  constructor(message = "Operation timed out") {
+    super(message);
+    this.name = "TimeoutError";
+  }
+};
+function isTimeoutError(err) {
+  return err instanceof Error && err.name === "TimeoutError";
+}
+function abortError(signal) {
+  return signal?.reason ?? new DOMException("This operation was aborted", "AbortError");
+}
+function withTimeout(input, ms, options = {}) {
+  const { signal: external, message, fallback } = options;
+  return new Promise((resolve, reject) => {
+    const controller = new AbortController();
+    let timer;
+    let settled = false;
+    const cleanup = () => {
+      if (timer !== void 0) clearTimeout(timer);
+      external?.removeEventListener("abort", onExternalAbort);
+    };
+    const settle = (action) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      action();
+    };
+    function onExternalAbort() {
+      controller.abort(external?.reason);
+      settle(() => reject(abortError(external)));
+    }
+    if (external) {
+      if (external.aborted) {
+        controller.abort(external.reason);
+        return settle(() => reject(abortError(external)));
+      }
+      external.addEventListener("abort", onExternalAbort, { once: true });
+    }
+    const onTimeout = () => {
+      const err = new TimeoutError(message ?? `Operation timed out after ${ms} ms`);
+      controller.abort(err);
+      if (fallback) {
+        Promise.resolve().then(fallback).then(
+          (value) => settle(() => resolve(value)),
+          (e) => settle(() => reject(e))
+        );
+      } else {
+        settle(() => reject(err));
+      }
+    };
+    if (Number.isFinite(ms) && ms >= 0) {
+      timer = setTimeout(onTimeout, ms);
+    }
+    let source;
+    if (typeof input === "function") {
+      try {
+        source = Promise.resolve(input(controller.signal));
+      } catch (err) {
+        source = Promise.reject(err);
+      }
+    } else {
+      source = Promise.resolve(input);
+    }
+    source.then(
+      (value) => settle(() => resolve(value)),
+      (err) => settle(() => reject(err))
+    );
+  });
+}
+function deadline(ms, signal) {
+  const controller = new AbortController();
+  if (signal) {
+    if (signal.aborted) {
+      controller.abort(signal.reason);
+      return controller.signal;
+    }
+    signal.addEventListener("abort", () => controller.abort(signal.reason), { once: true });
+  }
+  if (Number.isFinite(ms) && ms >= 0) {
+    const timer = setTimeout(
+      () => controller.abort(new TimeoutError(`Deadline of ${ms} ms exceeded`)),
+      ms
+    );
+    timer.unref?.();
+    controller.signal.addEventListener("abort", () => clearTimeout(timer), { once: true });
+  }
+  return controller.signal;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TimeoutError,
+  deadline,
+  isTimeoutError,
+  withTimeout
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/timeout.ts"],"sourcesContent":["/**\n * timefence — put a time limit on any promise, with real AbortSignal cancellation\n * and a composable deadline signal. Zero dependencies.\n *\n * @packageDocumentation\n */\n\nexport {\n  withTimeout,\n  deadline,\n  TimeoutError,\n  isTimeoutError,\n  type WithTimeoutOptions,\n} from \"./timeout.js\";\n","/** Error thrown when an operation exceeds its time budget. */\nexport class TimeoutError extends Error {\n  constructor(message = \"Operation timed out\") {\n    super(message);\n    this.name = \"TimeoutError\";\n  }\n}\n\n/** `true` if `err` is a {@link TimeoutError}. */\nexport function isTimeoutError(err: unknown): err is TimeoutError {\n  return err instanceof Error && err.name === \"TimeoutError\";\n}\n\nfunction abortError(signal?: AbortSignal): unknown {\n  return signal?.reason ?? new DOMException(\"This operation was aborted\", \"AbortError\");\n}\n\n/** Options for {@link withTimeout}. */\nexport interface WithTimeoutOptions<T> {\n  /** Message for the thrown {@link TimeoutError}. */\n  message?: string;\n  /** External signal that cancels the operation early. */\n  signal?: AbortSignal;\n  /** If provided, resolve with this instead of rejecting when the time runs out. */\n  fallback?: () => T | Promise<T>;\n}\n\n/**\n * Run an operation with a time limit.\n *\n * `input` may be a promise, or a function receiving an `AbortSignal` that fires\n * when the deadline (or an external `signal`) is reached — so cooperative work\n * (`fetch`, etc.) is actually cancelled, not just abandoned.\n *\n * @example\n * ```ts\n * // Function form: the fetch is aborted on timeout.\n * const res = await withTimeout((signal) => fetch(url, { signal }), 5000);\n *\n * // Fallback instead of throwing:\n * const data = await withTimeout(loadFresh(), 800, { fallback: () => cached });\n * ```\n *\n * @param input - A promise, or `(signal) => Promise`.\n * @param ms - Timeout in ms. `Infinity` disables the timeout (abort still works).\n * @throws {TimeoutError} on timeout (unless `fallback` is given); rejects if the\n *   external `signal` aborts.\n */\nexport function withTimeout<T>(\n  input: Promise<T> | ((signal: AbortSignal) => Promise<T> | T),\n  ms: number,\n  options: WithTimeoutOptions<T> = {},\n): Promise<T> {\n  const { signal: external, message, fallback } = options;\n\n  return new Promise<T>((resolve, reject) => {\n    const controller = new AbortController();\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    let settled = false;\n\n    const cleanup = () => {\n      if (timer !== undefined) clearTimeout(timer);\n      external?.removeEventListener(\"abort\", onExternalAbort);\n    };\n    const settle = (action: () => void): void => {\n      if (settled) return;\n      settled = true;\n      cleanup();\n      action();\n    };\n\n    function onExternalAbort(): void {\n      controller.abort(external?.reason);\n      settle(() => reject(abortError(external)));\n    }\n\n    if (external) {\n      if (external.aborted) {\n        controller.abort(external.reason);\n        return settle(() => reject(abortError(external)));\n      }\n      external.addEventListener(\"abort\", onExternalAbort, { once: true });\n    }\n\n    const onTimeout = (): void => {\n      const err = new TimeoutError(message ?? `Operation timed out after ${ms} ms`);\n      controller.abort(err);\n      if (fallback) {\n        Promise.resolve()\n          .then(fallback)\n          .then(\n            (value) => settle(() => resolve(value)),\n            (e) => settle(() => reject(e)),\n          );\n      } else {\n        settle(() => reject(err));\n      }\n    };\n\n    if (Number.isFinite(ms) && ms >= 0) {\n      timer = setTimeout(onTimeout, ms);\n    }\n\n    let source: Promise<T>;\n    if (typeof input === \"function\") {\n      try {\n        source = Promise.resolve((input as (s: AbortSignal) => Promise<T> | T)(controller.signal));\n      } catch (err) {\n        source = Promise.reject(err);\n      }\n    } else {\n      source = Promise.resolve(input);\n    }\n\n    source.then(\n      (value) => settle(() => resolve(value)),\n      (err) => settle(() => reject(err)),\n    );\n  });\n}\n\n/**\n * Create an `AbortSignal` that aborts after `ms` (with a {@link TimeoutError}\n * reason), optionally composed with an external `signal` that aborts it earlier.\n *\n * Like `AbortSignal.timeout`, but composable and with a typed reason. The\n * internal timer is `unref`'d so it never keeps a Node process alive.\n *\n * @example\n * ```ts\n * const res = await fetch(url, { signal: deadline(10_000, userSignal) });\n * ```\n */\nexport function deadline(ms: number, signal?: AbortSignal): AbortSignal {\n  const controller = new AbortController();\n\n  if (signal) {\n    if (signal.aborted) {\n      controller.abort(signal.reason);\n      return controller.signal;\n    }\n    signal.addEventListener(\"abort\", () => controller.abort(signal.reason), { once: true });\n  }\n\n  if (Number.isFinite(ms) && ms >= 0) {\n    const timer = setTimeout(\n      () => controller.abort(new TimeoutError(`Deadline of ${ms} ms exceeded`)),\n      ms,\n    );\n    (timer as { unref?: () => void }).unref?.();\n    controller.signal.addEventListener(\"abort\", () => clearTimeout(timer), { once: true });\n  }\n\n  return controller.signal;\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,52 @@
+/** Error thrown when an operation exceeds its time budget. */
+declare class TimeoutError extends Error {
+    constructor(message?: string);
+}
+/** `true` if `err` is a {@link TimeoutError}. */
+declare function isTimeoutError(err: unknown): err is TimeoutError;
+/** Options for {@link withTimeout}. */
+interface WithTimeoutOptions<T> {
+    /** Message for the thrown {@link TimeoutError}. */
+    message?: string;
+    /** External signal that cancels the operation early. */
+    signal?: AbortSignal;
+    /** If provided, resolve with this instead of rejecting when the time runs out. */
+    fallback?: () => T | Promise<T>;
+}
+/**
+ * Run an operation with a time limit.
+ *
+ * `input` may be a promise, or a function receiving an `AbortSignal` that fires
+ * when the deadline (or an external `signal`) is reached — so cooperative work
+ * (`fetch`, etc.) is actually cancelled, not just abandoned.
+ *
+ * @example
+ * ```ts
+ * // Function form: the fetch is aborted on timeout.
+ * const res = await withTimeout((signal) => fetch(url, { signal }), 5000);
+ *
+ * // Fallback instead of throwing:
+ * const data = await withTimeout(loadFresh(), 800, { fallback: () => cached });
+ * ```
+ *
+ * @param input - A promise, or `(signal) => Promise`.
+ * @param ms - Timeout in ms. `Infinity` disables the timeout (abort still works).
+ * @throws {TimeoutError} on timeout (unless `fallback` is given); rejects if the
+ *   external `signal` aborts.
+ */
+declare function withTimeout<T>(input: Promise<T> | ((signal: AbortSignal) => Promise<T> | T), ms: number, options?: WithTimeoutOptions<T>): Promise<T>;
+/**
+ * Create an `AbortSignal` that aborts after `ms` (with a {@link TimeoutError}
+ * reason), optionally composed with an external `signal` that aborts it earlier.
+ *
+ * Like `AbortSignal.timeout`, but composable and with a typed reason. The
+ * internal timer is `unref`'d so it never keeps a Node process alive.
+ *
+ * @example
+ * ```ts
+ * const res = await fetch(url, { signal: deadline(10_000, userSignal) });
+ * ```
+ */
+declare function deadline(ms: number, signal?: AbortSignal): AbortSignal;
+
+export { TimeoutError, type WithTimeoutOptions, deadline, isTimeoutError, withTimeout };

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+/** Error thrown when an operation exceeds its time budget. */
+declare class TimeoutError extends Error {
+    constructor(message?: string);
+}
+/** `true` if `err` is a {@link TimeoutError}. */
+declare function isTimeoutError(err: unknown): err is TimeoutError;
+/** Options for {@link withTimeout}. */
+interface WithTimeoutOptions<T> {
+    /** Message for the thrown {@link TimeoutError}. */
+    message?: string;
+    /** External signal that cancels the operation early. */
+    signal?: AbortSignal;
+    /** If provided, resolve with this instead of rejecting when the time runs out. */
+    fallback?: () => T | Promise<T>;
+}
+/**
+ * Run an operation with a time limit.
+ *
+ * `input` may be a promise, or a function receiving an `AbortSignal` that fires
+ * when the deadline (or an external `signal`) is reached — so cooperative work
+ * (`fetch`, etc.) is actually cancelled, not just abandoned.
+ *
+ * @example
+ * ```ts
+ * // Function form: the fetch is aborted on timeout.
+ * const res = await withTimeout((signal) => fetch(url, { signal }), 5000);
+ *
+ * // Fallback instead of throwing:
+ * const data = await withTimeout(loadFresh(), 800, { fallback: () => cached });
+ * ```
+ *
+ * @param input - A promise, or `(signal) => Promise`.
+ * @param ms - Timeout in ms. `Infinity` disables the timeout (abort still works).
+ * @throws {TimeoutError} on timeout (unless `fallback` is given); rejects if the
+ *   external `signal` aborts.
+ */
+declare function withTimeout<T>(input: Promise<T> | ((signal: AbortSignal) => Promise<T> | T), ms: number, options?: WithTimeoutOptions<T>): Promise<T>;
+/**
+ * Create an `AbortSignal` that aborts after `ms` (with a {@link TimeoutError}
+ * reason), optionally composed with an external `signal` that aborts it earlier.
+ *
+ * Like `AbortSignal.timeout`, but composable and with a typed reason. The
+ * internal timer is `unref`'d so it never keeps a Node process alive.
+ *
+ * @example
+ * ```ts
+ * const res = await fetch(url, { signal: deadline(10_000, userSignal) });
+ * ```
+ */
+declare function deadline(ms: number, signal?: AbortSignal): AbortSignal;
+
+export { TimeoutError, type WithTimeoutOptions, deadline, isTimeoutError, withTimeout };

package/dist/index.js

@@ -0,0 +1,97 @@
+// src/timeout.ts
+var TimeoutError = class extends Error {
+  constructor(message = "Operation timed out") {
+    super(message);
+    this.name = "TimeoutError";
+  }
+};
+function isTimeoutError(err) {
+  return err instanceof Error && err.name === "TimeoutError";
+}
+function abortError(signal) {
+  return signal?.reason ?? new DOMException("This operation was aborted", "AbortError");
+}
+function withTimeout(input, ms, options = {}) {
+  const { signal: external, message, fallback } = options;
+  return new Promise((resolve, reject) => {
+    const controller = new AbortController();
+    let timer;
+    let settled = false;
+    const cleanup = () => {
+      if (timer !== void 0) clearTimeout(timer);
+      external?.removeEventListener("abort", onExternalAbort);
+    };
+    const settle = (action) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      action();
+    };
+    function onExternalAbort() {
+      controller.abort(external?.reason);
+      settle(() => reject(abortError(external)));
+    }
+    if (external) {
+      if (external.aborted) {
+        controller.abort(external.reason);
+        return settle(() => reject(abortError(external)));
+      }
+      external.addEventListener("abort", onExternalAbort, { once: true });
+    }
+    const onTimeout = () => {
+      const err = new TimeoutError(message ?? `Operation timed out after ${ms} ms`);
+      controller.abort(err);
+      if (fallback) {
+        Promise.resolve().then(fallback).then(
+          (value) => settle(() => resolve(value)),
+          (e) => settle(() => reject(e))
+        );
+      } else {
+        settle(() => reject(err));
+      }
+    };
+    if (Number.isFinite(ms) && ms >= 0) {
+      timer = setTimeout(onTimeout, ms);
+    }
+    let source;
+    if (typeof input === "function") {
+      try {
+        source = Promise.resolve(input(controller.signal));
+      } catch (err) {
+        source = Promise.reject(err);
+      }
+    } else {
+      source = Promise.resolve(input);
+    }
+    source.then(
+      (value) => settle(() => resolve(value)),
+      (err) => settle(() => reject(err))
+    );
+  });
+}
+function deadline(ms, signal) {
+  const controller = new AbortController();
+  if (signal) {
+    if (signal.aborted) {
+      controller.abort(signal.reason);
+      return controller.signal;
+    }
+    signal.addEventListener("abort", () => controller.abort(signal.reason), { once: true });
+  }
+  if (Number.isFinite(ms) && ms >= 0) {
+    const timer = setTimeout(
+      () => controller.abort(new TimeoutError(`Deadline of ${ms} ms exceeded`)),
+      ms
+    );
+    timer.unref?.();
+    controller.signal.addEventListener("abort", () => clearTimeout(timer), { once: true });
+  }
+  return controller.signal;
+}
+export {
+  TimeoutError,
+  deadline,
+  isTimeoutError,
+  withTimeout
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/timeout.ts"],"sourcesContent":["/** Error thrown when an operation exceeds its time budget. */\nexport class TimeoutError extends Error {\n  constructor(message = \"Operation timed out\") {\n    super(message);\n    this.name = \"TimeoutError\";\n  }\n}\n\n/** `true` if `err` is a {@link TimeoutError}. */\nexport function isTimeoutError(err: unknown): err is TimeoutError {\n  return err instanceof Error && err.name === \"TimeoutError\";\n}\n\nfunction abortError(signal?: AbortSignal): unknown {\n  return signal?.reason ?? new DOMException(\"This operation was aborted\", \"AbortError\");\n}\n\n/** Options for {@link withTimeout}. */\nexport interface WithTimeoutOptions<T> {\n  /** Message for the thrown {@link TimeoutError}. */\n  message?: string;\n  /** External signal that cancels the operation early. */\n  signal?: AbortSignal;\n  /** If provided, resolve with this instead of rejecting when the time runs out. */\n  fallback?: () => T | Promise<T>;\n}\n\n/**\n * Run an operation with a time limit.\n *\n * `input` may be a promise, or a function receiving an `AbortSignal` that fires\n * when the deadline (or an external `signal`) is reached — so cooperative work\n * (`fetch`, etc.) is actually cancelled, not just abandoned.\n *\n * @example\n * ```ts\n * // Function form: the fetch is aborted on timeout.\n * const res = await withTimeout((signal) => fetch(url, { signal }), 5000);\n *\n * // Fallback instead of throwing:\n * const data = await withTimeout(loadFresh(), 800, { fallback: () => cached });\n * ```\n *\n * @param input - A promise, or `(signal) => Promise`.\n * @param ms - Timeout in ms. `Infinity` disables the timeout (abort still works).\n * @throws {TimeoutError} on timeout (unless `fallback` is given); rejects if the\n *   external `signal` aborts.\n */\nexport function withTimeout<T>(\n  input: Promise<T> | ((signal: AbortSignal) => Promise<T> | T),\n  ms: number,\n  options: WithTimeoutOptions<T> = {},\n): Promise<T> {\n  const { signal: external, message, fallback } = options;\n\n  return new Promise<T>((resolve, reject) => {\n    const controller = new AbortController();\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    let settled = false;\n\n    const cleanup = () => {\n      if (timer !== undefined) clearTimeout(timer);\n      external?.removeEventListener(\"abort\", onExternalAbort);\n    };\n    const settle = (action: () => void): void => {\n      if (settled) return;\n      settled = true;\n      cleanup();\n      action();\n    };\n\n    function onExternalAbort(): void {\n      controller.abort(external?.reason);\n      settle(() => reject(abortError(external)));\n    }\n\n    if (external) {\n      if (external.aborted) {\n        controller.abort(external.reason);\n        return settle(() => reject(abortError(external)));\n      }\n      external.addEventListener(\"abort\", onExternalAbort, { once: true });\n    }\n\n    const onTimeout = (): void => {\n      const err = new TimeoutError(message ?? `Operation timed out after ${ms} ms`);\n      controller.abort(err);\n      if (fallback) {\n        Promise.resolve()\n          .then(fallback)\n          .then(\n            (value) => settle(() => resolve(value)),\n            (e) => settle(() => reject(e)),\n          );\n      } else {\n        settle(() => reject(err));\n      }\n    };\n\n    if (Number.isFinite(ms) && ms >= 0) {\n      timer = setTimeout(onTimeout, ms);\n    }\n\n    let source: Promise<T>;\n    if (typeof input === \"function\") {\n      try {\n        source = Promise.resolve((input as (s: AbortSignal) => Promise<T> | T)(controller.signal));\n      } catch (err) {\n        source = Promise.reject(err);\n      }\n    } else {\n      source = Promise.resolve(input);\n    }\n\n    source.then(\n      (value) => settle(() => resolve(value)),\n      (err) => settle(() => reject(err)),\n    );\n  });\n}\n\n/**\n * Create an `AbortSignal` that aborts after `ms` (with a {@link TimeoutError}\n * reason), optionally composed with an external `signal` that aborts it earlier.\n *\n * Like `AbortSignal.timeout`, but composable and with a typed reason. The\n * internal timer is `unref`'d so it never keeps a Node process alive.\n *\n * @example\n * ```ts\n * const res = await fetch(url, { signal: deadline(10_000, userSignal) });\n * ```\n */\nexport function deadline(ms: number, signal?: AbortSignal): AbortSignal {\n  const controller = new AbortController();\n\n  if (signal) {\n    if (signal.aborted) {\n      controller.abort(signal.reason);\n      return controller.signal;\n    }\n    signal.addEventListener(\"abort\", () => controller.abort(signal.reason), { once: true });\n  }\n\n  if (Number.isFinite(ms) && ms >= 0) {\n    const timer = setTimeout(\n      () => controller.abort(new TimeoutError(`Deadline of ${ms} ms exceeded`)),\n      ms,\n    );\n    (timer as { unref?: () => void }).unref?.();\n    controller.signal.addEventListener(\"abort\", () => clearTimeout(timer), { once: true });\n  }\n\n  return controller.signal;\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "timefence",
+  "version": "0.1.0",
+  "description": "Put a time limit on any promise, with real AbortSignal cancellation and a composable deadline signal. Zero dependencies.",
+  "keywords": [
+    "timeout",
+    "deadline",
+    "p-timeout",
+    "abortsignal",
+    "abort",
+    "promise",
+    "cancel",
+    "async",
+    "race",
+    "resilience",
+    "zero-dependency"
+  ],
+  "license": "MIT",
+  "author": "Tung Tran (https://github.com/trananhtung)",
+  "homepage": "https://github.com/trananhtung/timefence#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/trananhtung/timefence.git"
+  },
+  "bugs": {
+    "url": "https://github.com/trananhtung/timefence/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.10",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}