@sdxc/backoff 0.0.0-pre.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio Xalambrí
+
+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,162 @@
+# @sdxc/backoff
+
+Retry delay schedules with exponential, linear, constant or stepped growth, a ceiling, free attempts and seedable jitter.
+
+## Installation
+
+```bash
+npm add @sdxc/backoff
+```
+
+## Usage
+
+### A Growing Delay
+
+`delay(attempt)` answers milliseconds to wait after `attempt` failures, counting from 1.
+
+```typescript
+import { createBackoff } from "@sdxc/backoff";
+
+let backoff = createBackoff({ base: "15 seconds", max: "12 hours", jitter: 0.2 });
+
+backoff.delay(1); // 15_000 ±20%
+backoff.delay(3); // 60_000 ±20%
+backoff.delay(20); // 43_200_000 ±20%: the ceiling, then jitter
+```
+
+Without jitter, the same schedule is `Math.min(15_000 * 2 ** (attempt - 1), 43_200_000)`.
+
+### A Stored Next Attempt
+
+`at(attempt, now)` is `now + delay(attempt)`, for a row that records when to try again.
+
+```typescript
+let nextAttemptAt = backoff.at(failureCount, Date.now());
+```
+
+### A Hand-Written Table
+
+`steps` replaces the curve. The last step repeats for every attempt past the end.
+
+```typescript
+let backoff = createBackoff({
+	steps: ["15 seconds", "1 minute", "5 minutes", "30 minutes", "2 hours"],
+	jitter: 0.2,
+});
+```
+
+### Free Attempts
+
+`free` attempts answer `0`, and the curve starts on the failure after them.
+
+```typescript
+let lockout = createBackoff({ free: 3, base: "1 second", max: "15 minutes" });
+
+lockout.delay(3); // 0
+lockout.delay(4); // 1_000
+lockout.delay(5); // 2_000
+```
+
+### Exact Jitter In Tests
+
+Jitter draws from a [`@sdxc/random`](https://www.npmjs.com/package/@sdxc/random) stream. Pass a seeded one and every delay is reproducible.
+
+```typescript
+import { createRandom } from "@sdxc/random";
+
+let backoff = createBackoff({ base: 1000, jitter: 0.2, random: createRandom("test") });
+```
+
+## API
+
+### `createBackoff(options: BackoffOptions): Backoff`
+
+Validate the options once and return the schedule. Throws `RangeError` for a negative or unparseable duration, a `factor` below 1, a `max` below `base`, a `jitter` outside `[0, 1]`, empty `steps`, or a `free` that is not a non-negative integer.
+
+Durations are [`@sdxc/duration`](https://www.npmjs.com/package/@sdxc/duration) inputs: milliseconds or strings such as `"30 minutes"`.
+
+A curve schedule takes:
+
+- `base`: the delay after the first counted failure
+- `growth`: `"exponential"` (default) multiplies by `factor` per failure, `"linear"` adds `base` per failure, `"constant"` repeats `base`
+- `factor`: the exponential multiplier, `2` by default
+- `max`: the ceiling before jitter; unbounded when omitted
+
+A stepped schedule takes `steps`, one delay per counted failure.
+
+Both take:
+
+- `free`: failures that answer `0`, `0` by default
+- `jitter`: a fraction `f` draws from `delay × (1 ± f)`; `"full"` draws from `[0, delay]`; omitted means none. Applied after `max`, so retries waiting at the ceiling still spread out. Jittered delays are rounded to whole milliseconds.
+- `random`: the stream jitter draws from, `systemRandom()` by default
+
+### `Backoff`
+
+- `delay(attempt)`: milliseconds after `attempt` failures; `0` for a non-positive or free attempt
+- `at(attempt, now)`: `now + delay(attempt)`
+
+### `BackoffOptions`, `BackoffCurveOptions`, `BackoffStepsOptions`, `BackoffSharedOptions` and `Jitter`
+
+The option shapes above. `Jitter` is `number | "full"`.
+
+## Pattern: Retrying A Queue Message
+
+A queue consumer passes its delivery count straight in, so early retries come quickly and a receiver that stays down is left alone.
+
+```typescript
+import { createBackoff } from "@sdxc/backoff";
+
+const deliveryBackoff = createBackoff({ base: "1 minute", max: "6 hours", jitter: 0.2 });
+
+export default {
+	async queue(batch: MessageBatch<{ url: string }>) {
+		for (let message of batch.messages) {
+			let response = await fetch(message.body.url, { method: "POST" });
+			if (response.ok) message.ack();
+			else
+				message.retry({ delaySeconds: Math.ceil(deliveryBackoff.delay(message.attempts) / 1000) });
+		}
+	},
+};
+```
+
+## Pattern: Honoring Retry-After
+
+When a server says how long to wait, wait at least that long.
+
+```typescript
+import { createBackoff } from "@sdxc/backoff";
+
+let backoff = createBackoff({ base: "1 second", max: "5 minutes", jitter: "full" });
+
+function waitAfter(response: Response, attempt: number): number {
+	let retryAfterMs = Number(response.headers.get("retry-after") ?? 0) * 1000;
+	return Math.max(retryAfterMs, backoff.delay(attempt));
+}
+```
+
+## Versioning
+
+Releases are dated rather than semantic. A version is the UTC date it was published, written `YYYY.M.D`, so `2026.9.4` is the release from 4 September 2026. At most one release goes out per day.
+
+Those numbers say when, not what: a later date means a later release and carries no compatibility promise. Any release may change or remove an export.
+
+Depend on one exact date, and move it when you are ready to take the change:
+
+```json
+{
+	"dependencies": {
+		"@sdxc/backoff": "2026.9.4"
+	}
+}
+```
+
+A caret or tilde range reads the date as major, minor and patch, so it accepts every later release in the same year. An exact version keeps the upgrade yours to schedule.
+
+## License
+
+MIT
+
+## Author
+
+[Sergio Xalambrí](https://sergiodxa.com)

package/dist/backoff.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Retry delay schedules: how long to wait after the Nth failure, from a growth
+ * curve or a hand-written table, with a ceiling, free attempts and jitter drawn
+ * from an injectable `Random`, so a seeded test asserts exact delays.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { DurationInput } from "@sdxc/duration";
+import type { Random } from "@sdxc/random";
+/** A schedule answering how long to wait after a given number of failures. */
+export interface Backoff {
+    /**
+     * Milliseconds to wait after `attempt` failures, counting from 1. A
+     * non-positive attempt and a free attempt both answer `0`.
+     */
+    delay(attempt: number): number;
+    /** The epoch milliseconds of the next try: `now` plus `delay(attempt)`. */
+    at(attempt: number, now: number): number;
+}
+/**
+ * How jitter spreads a delay: a fraction in `[0, 1]` draws from
+ * `delay × (1 ± fraction)`, and `"full"` draws from `[0, delay]`.
+ */
+export type Jitter = number | "full";
+/** Options every schedule accepts, whatever shapes its delays. */
+export interface BackoffSharedOptions {
+    /**
+     * Failures that answer `0`; the schedule's first delay belongs to the
+     * failure right after them.
+     * @default 0
+     */
+    free?: number;
+    /** Spread applied after the ceiling, so retries waiting at the cap still spread out. */
+    jitter?: Jitter;
+    /**
+     * The stream jitter draws from; pass a seeded one to make delays exact.
+     * @default systemRandom()
+     */
+    random?: Random;
+}
+/** A schedule computed from a base delay and a growth rule. */
+export interface BackoffCurveOptions extends BackoffSharedOptions {
+    /** The delay after the first counted failure. */
+    base: DurationInput;
+    /**
+     * `"exponential"` multiplies by `factor` per failure, `"linear"` adds `base`
+     * per failure, and `"constant"` repeats `base`.
+     * @default "exponential"
+     */
+    growth?: "exponential" | "linear" | "constant";
+    /**
+     * The multiplier per failure of an exponential schedule.
+     * @default 2
+     */
+    factor?: number;
+    /** The ceiling a delay reaches before jitter; unbounded when omitted. */
+    max?: DurationInput;
+}
+/** A schedule chosen by hand, one step per failure, the last one repeating. */
+export interface BackoffStepsOptions extends BackoffSharedOptions {
+    /** The delay after each counted failure, in order. */
+    steps: readonly DurationInput[];
+}
+/** Either shape `createBackoff` accepts. */
+export type BackoffOptions = BackoffCurveOptions | BackoffStepsOptions;
+/**
+ * Build a schedule. Options are validated once here, so `delay` and `at`
+ * never fail afterwards.
+ *
+ * @throws RangeError for a negative or unparseable base, step or ceiling, a
+ * `factor` below 1, a `max` below `base`, a `jitter` outside `[0, 1]`, empty
+ * `steps`, or a `free` that is not a non-negative integer.
+ * @example createBackoff({ base: "15 seconds", max: "12 hours", jitter: 0.2 }).delay(3); // 60_000 ± 20%
+ * @example createBackoff({ steps: ["1 minute", "5 minutes", "1 hour"] }).at(attempts, Date.now());
+ */
+export declare function createBackoff(options: BackoffOptions): Backoff;

package/dist/backoff.js

@@ -0,0 +1,80 @@
+import { toMs } from "@sdxc/duration";
+import { systemRandom } from "@sdxc/random";
+/**
+ * Build a schedule. Options are validated once here, so `delay` and `at`
+ * never fail afterwards.
+ *
+ * @throws RangeError for a negative or unparseable base, step or ceiling, a
+ * `factor` below 1, a `max` below `base`, a `jitter` outside `[0, 1]`, empty
+ * `steps`, or a `free` that is not a non-negative integer.
+ * @example createBackoff({ base: "15 seconds", max: "12 hours", jitter: 0.2 }).delay(3); // 60_000 ± 20%
+ * @example createBackoff({ steps: ["1 minute", "5 minutes", "1 hour"] }).at(attempts, Date.now());
+ */
+export function createBackoff(options) {
+    let free = options.free ?? 0;
+    if (!Number.isSafeInteger(free) || free < 0) {
+        throw new RangeError(`free needs a non-negative integer, received ${free}.`);
+    }
+    let jitter = options.jitter;
+    if (typeof jitter === "number" && !(jitter >= 0 && jitter <= 1)) {
+        throw new RangeError(`jitter needs a fraction in [0, 1] or "full", received ${jitter}.`);
+    }
+    let random = options.random ?? systemRandom();
+    let curve = "steps" in options ? stepsCurve(options) : growthCurve(options);
+    let backoff = {
+        delay(attempt) {
+            let counted = attempt - free;
+            if (!(counted >= 1))
+                return 0;
+            let delay = curve(counted);
+            if (jitter === undefined || jitter === 0)
+                return delay;
+            if (jitter === "full")
+                return Math.round(random.float(0, delay));
+            return Math.round(delay * random.float(1 - jitter, 1 + jitter));
+        },
+        at(attempt, now) {
+            return now + backoff.delay(attempt);
+        },
+    };
+    return backoff;
+}
+/**
+ * Convert a duration option to milliseconds, rejecting the negative values
+ * and unparseable strings that `toMs` reports as `NaN`.
+ */
+function nonNegativeMs(name, input) {
+    let ms = toMs(input);
+    if (!(ms >= 0))
+        throw new RangeError(`${name} needs a non-negative duration, received ${input}.`);
+    return ms;
+}
+/**
+ * The pre-jitter delay of a growth schedule for a counted failure (1 or more).
+ * An unbounded exponential schedule reaches `Infinity` once the product
+ * overflows.
+ */
+function growthCurve(options) {
+    let base = nonNegativeMs("base", options.base);
+    let factor = options.factor ?? 2;
+    if (!(factor >= 1))
+        throw new RangeError(`factor needs to be at least 1, received ${factor}.`);
+    let max = options.max === undefined ? Infinity : nonNegativeMs("max", options.max);
+    if (max < base)
+        throw new RangeError(`max (${max}ms) needs to be at least base (${base}ms).`);
+    let growth = options.growth ?? "exponential";
+    return (counted) => {
+        if (growth === "constant")
+            return Math.min(base, max);
+        if (growth === "linear")
+            return Math.min(base * counted, max);
+        return Math.min(base * factor ** (counted - 1), max);
+    };
+}
+/** The pre-jitter delay of a stepped schedule, repeating the last step past the end. */
+function stepsCurve(options) {
+    if (options.steps.length === 0)
+        throw new RangeError("steps needs at least one delay.");
+    let steps = options.steps.map((step, index) => nonNegativeMs(`steps[${index}]`, step));
+    return (counted) => steps[Math.min(counted, steps.length) - 1];
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The package entrypoint: `createBackoff` and the schedule it returns, which
+ * answers how long to wait after the Nth failure in milliseconds, plus the
+ * option shapes a caller builds one from.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export type { Backoff, BackoffCurveOptions, BackoffOptions, BackoffSharedOptions, BackoffStepsOptions, Jitter, } from "./backoff.js";
+export { createBackoff } from "./backoff.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { createBackoff } from "./backoff.js";

package/package.json

@@ -0,0 +1,23 @@
+{
+	"name": "@sdxc/backoff",
+	"version": "0.0.0-pre.1",
+	"description": "Retry delay schedules with exponential, linear, constant or stepped growth, a ceiling, free attempts and seedable jitter",
+	"license": "MIT",
+	"type": "module",
+	"exports": {
+		".": "./dist/index.js"
+	},
+	"dependencies": {
+		"@sdxc/duration": "2026.10.2",
+		"@sdxc/random": "0.0.0-pre.1"
+	},
+	"gitHead": "780589b65576d3aa4014c6bcd448b33b4931705a",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/sergiodxa/monorepo.git",
+		"directory": "packages/backoff"
+	}
+}