@sdxc/backoff 0.0.0-stage → 2026.10.13

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

@@ -1,3 +1,216 @@
-# Temporary Holding Version
+# @sdxc/backoff
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Retry delay schedules with exponential, linear, constant or stepped growth, a ceiling, free attempts and seedable jitter.
+
+## Installation
+
+```sh
+npm add @sdxc/backoff
+```
+
+Durations are [`@sdxc/duration`](https://www.npmjs.com/package/@sdxc/duration) inputs, and jitter draws from a [`@sdxc/random`](https://www.npmjs.com/package/@sdxc/random) stream; install `@sdxc/random` too when you pass a seeded one.
+
+## Usage
+
+### Build a schedule
+
+`delay(attempt)` answers the milliseconds to wait after `attempt` failures, counting from 1.
+
+```typescript
+import { createBackoff } from "@sdxc/backoff";
+
+let backoff = createBackoff({ base: "15 seconds", max: "12 hours" });
+
+backoff.delay(1); // 15_000
+backoff.delay(3); // 60_000
+backoff.delay(20); // 43_200_000, the ceiling
+```
+
+That schedule is `Math.min(15_000 * 2 ** (attempt - 1), 43_200_000)`.
+
+### Pick the growth
+
+`growth` changes the curve, and `steps` replaces it with a table whose last entry repeats.
+
+```typescript
+createBackoff({ base: "1 second", factor: 3 }); // 1s, 3s, 9s, 27s…
+createBackoff({ base: "30 seconds", growth: "linear" }); // 30s, 60s, 90s…
+createBackoff({ base: "5 seconds", growth: "constant" }); // 5s, 5s, 5s…
+createBackoff({ steps: ["15 seconds", "1 minute", "5 minutes", "2 hours"] }); // …2h, 2h
+```
+
+### Spread retries with jitter
+
+A fraction `f` draws each delay from `delay × (1 ± f)`; `"full"` draws from `[0, delay]`. Jitter applies after `max`, so retries waiting at the ceiling still spread out.
+
+```typescript
+let backoff = createBackoff({ base: "15 seconds", max: "12 hours", jitter: 0.2 });
+
+backoff.delay(1); // between 12_000 and 18_000
+```
+
+### Allow free attempts
+
+The first `free` failures 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
+```
+
+## API
+
+### `createBackoff(options: BackoffOptions): Backoff`
+
+Validates the options once and returns the schedule, so `delay` and `at` never fail. 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.
+
+A curve schedule takes:
+
+- `base`: the delay after the first counted failure
+- `growth`: `"exponential"` (default) multiplies by `factor` per failure, `"linear"` adds `base`, `"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 `Jitter`; none when omitted. Jittered delays round to whole milliseconds
+- `random`: the stream jitter draws from, `systemRandom()` by default
+
+### `Backoff`
+
+- `delay(attempt: number): number`: milliseconds after `attempt` failures; `0` for a non-positive or free attempt
+- `at(attempt: number, now: number): number`: `now + delay(attempt)`, for storing when to try again
+
+### Types
+
+#### `BackoffOptions`
+
+`BackoffCurveOptions | BackoffStepsOptions`, both extending `BackoffSharedOptions` (`free`, `jitter`, `random`).
+
+#### `Jitter`
+
+`number | "full"`: a fraction in `[0, 1]`, or a draw from zero to the full delay.
+
+## 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";
+
+let 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: Retrying A Request And Honoring Retry-After
+
+When a server says how long to wait, wait at least that long. `Retry-After` is either a number of seconds or an HTTP date; anything else counts as no answer.
+
+```typescript
+import { createBackoff } from "@sdxc/backoff";
+
+let backoff = createBackoff({ base: "1 second", max: "5 minutes", jitter: "full" });
+
+function retryAfterMs(response: Response, now: number): number {
+	let header = response.headers.get("retry-after");
+	if (header === null) return 0;
+
+	let seconds = Number(header);
+	if (Number.isFinite(seconds)) return Math.max(seconds * 1000, 0);
+
+	let date = Date.parse(header);
+	return Number.isNaN(date) ? 0 : Math.max(date - now, 0);
+}
+
+async function fetchWithRetry(url: string, attempts = 5): Promise<Response> {
+	for (let attempt = 1; ; attempt++) {
+		let response = await fetch(url);
+		if (response.ok || attempt === attempts) return response;
+		let wait = Math.max(retryAfterMs(response, Date.now()), backoff.delay(attempt));
+		await new Promise((resolve) => setTimeout(resolve, wait));
+	}
+}
+```
+
+## Pattern: Locking Out Repeated Sign-In Failures
+
+A stored failure count and `at()` give a row the time its next attempt opens. The first three failures cost nothing.
+
+```typescript
+import { createBackoff } from "@sdxc/backoff";
+
+let lockout = createBackoff({ free: 3, steps: ["30 seconds", "5 minutes", "1 hour"] });
+
+interface SignInState {
+	failures: number;
+	lockedUntil: number;
+}
+
+function isLocked(state: SignInState, now: number): boolean {
+	return state.lockedUntil > now;
+}
+
+function recordFailure(state: SignInState, now: number): SignInState {
+	let failures = state.failures + 1;
+	return { failures, lockedUntil: lockout.at(failures, now) };
+}
+```
+
+## Pattern: Exact Delays In Tests
+
+Pass a seeded `Random` and every jittered delay is reproducible, so a test asserts exact values.
+
+```typescript
+import { createBackoff } from "@sdxc/backoff";
+import { createRandom } from "@sdxc/random";
+import { expect, test } from "vitest";
+
+test("jitter is reproducible", () => {
+	let first = createBackoff({ base: 1000, jitter: 0.2, random: createRandom("test") });
+	let second = createBackoff({ base: 1000, jitter: 0.2, random: createRandom("test") });
+
+	expect(first.delay(3)).toBe(second.delay(3));
+	expect(first.delay(3)).toBeGreaterThanOrEqual(3200);
+	expect(first.delay(3)).toBeLessThanOrEqual(4800);
+});
+```
+
+## 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

@@ -1,6 +1,32 @@
 {
-  "name": "@sdxc/backoff",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@sdxc/backoff",
+	"version": "2026.10.13",
+	"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.13",
+		"@sdxc/random": "2026.10.13"
+	},
+	"gitHead": "5ff758a57e35480a8db7abd24f1d9527b81bfb51",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/sergiodxa/monorepo.git",
+		"directory": "packages/backoff"
+	},
+	"homepage": "https://sdxc.sergiodxa.com/api/backoff",
+	"author": {
+		"name": "Sergio Xalambrí",
+		"url": "https://sergiodxa.com"
+	},
+	"funding": {
+		"type": "github",
+		"url": "https://github.com/sponsors/sergiodxa"
+	}
+}