@vereda/http 1.0.0

package/dist/ticket/ticket.js

@@ -0,0 +1,186 @@
+import { EventEmitter } from "node:events";
+import { CancelledError } from "../core/errors.js";
+import { emitIsolated } from "../core/listeners.js";
+// Allowed transitions between ticket states. `done` and `cancelled` are both
+// terminal: `cancel()` resolves the ticket directly with a CancelledError
+// result, so a cancelled ticket is never transitioned to `done` by the retry
+// loop (its `_markDone` becomes a no-op). The `retrying -> retrying` self-loop
+// permits re-entering `retrying` with a new attempt number (a fresh status
+// object is assigned, not mutated in place). `pending -> done` is the
+// first-attempt success path: client.ts calls `_markDone` directly from
+// `pending` when the initial request succeeds, so it is an intentional
+// shortcut, not a gap in the lifecycle.
+const ALLOWED_TRANSITIONS = {
+    pending: ["queued", "done", "cancelled"],
+    queued: ["retrying", "done", "cancelled"],
+    retrying: ["retrying", "done", "cancelled"],
+    cancelled: [],
+    done: [],
+};
+// ---------------------------------------------------------------------------
+// Ticket
+// ---------------------------------------------------------------------------
+export class Ticket {
+    id;
+    emitter = new EventEmitter();
+    _status = { state: "pending" };
+    _cancelled = false;
+    _abortController = new AbortController();
+    _resolve;
+    _promise;
+    /** @internal — use `createTicket()` to obtain a ticket and its controller. */
+    constructor(id) {
+        this.id = id;
+        this._promise = new Promise((resolve) => {
+            this._resolve = resolve;
+        });
+        // Prevent Node from throwing on unhandled "error" events
+        this.emitter.on("error", () => { });
+    }
+    get status() {
+        return this._status;
+    }
+    /** Validate and apply a state transition. Returns false (and leaves the
+     *  current state untouched) when `next` is not reachable from the current
+     *  state, so illegal transitions are ignored rather than corrupting state. */
+    applyTransition(next) {
+        if (!ALLOWED_TRANSITIONS[this._status.state].includes(next.state)) {
+            return false;
+        }
+        this._status = next;
+        return true;
+    }
+    get signal() {
+        return this._abortController.signal;
+    }
+    // biome-ignore lint/suspicious/noExplicitAny: overload implementation signature must accept every declared overload; callers only see the typed overloads.
+    on(event, listener) {
+        // biome-ignore lint/suspicious/noExplicitAny: EventEmitter's own listener signature.
+        this.emitter.on(event, listener);
+        return this;
+    }
+    // biome-ignore lint/suspicious/noExplicitAny: overload implementation signature must accept every declared overload; callers only see the typed overloads.
+    off(event, listener) {
+        // biome-ignore lint/suspicious/noExplicitAny: EventEmitter's own listener signature.
+        this.emitter.off(event, listener);
+        return this;
+    }
+    // -- Public API ------------------------------------------------------------
+    cancel() {
+        if (this._cancelled)
+            return;
+        // `cancelled` is terminal — if the ticket already resolved, this is a no-op.
+        if (!this.applyTransition({ state: "cancelled" }))
+            return;
+        this._cancelled = true;
+        this._abortController.abort();
+        const result = { success: false, error: new CancelledError() };
+        emitIsolated(this.emitter, "update", { type: "cancelled" });
+        emitIsolated(this.emitter, "done", result);
+        emitIsolated(this.emitter, "error", result.error);
+        this._resolve(result);
+    }
+    toPromise() {
+        return this._promise;
+    }
+    async *subscribe() {
+        // Already terminal — yield synthetic update and return
+        const current = this._status;
+        if (current.state === "done") {
+            yield { type: "done", result: current.result };
+            return;
+        }
+        if (current.state === "cancelled") {
+            yield { type: "cancelled" };
+            return;
+        }
+        const updates = [];
+        let notify = null;
+        let isDone = false;
+        const onUpdate = (update) => {
+            updates.push(update);
+            notify?.();
+            notify = null;
+            if (update.type === "done" || update.type === "cancelled") {
+                isDone = true;
+            }
+        };
+        this.emitter.on("update", onUpdate);
+        try {
+            while (!isDone || updates.length > 0) {
+                if (updates.length > 0) {
+                    yield updates.shift();
+                }
+                else {
+                    await new Promise((r) => {
+                        notify = r;
+                    });
+                }
+            }
+        }
+        finally {
+            this.emitter.off("update", onUpdate);
+        }
+    }
+    get isCancelled() {
+        return this._cancelled;
+    }
+    /** True once this ticket has reached a terminal state by any path — a
+     *  normal `done` transition or `cancel()` (which resolves the ticket
+     *  directly, bypassing `done`). A terminal-event emitter must check this
+     *  before firing, or a result racing a concurrent cancel() can emit a
+     *  second, contradictory terminal event for the same ticket. */
+    get isSettled() {
+        return this._status.state === "done" || this._cancelled;
+    }
+    // -- Internal mutators (private, accessed via TicketController) ------------
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: reached via bracket notation from createTicket(); Biome cannot see that access.
+    markQueued() {
+        if (!this.applyTransition({ state: "queued" }))
+            return;
+        emitIsolated(this.emitter, "update", { type: "queued" });
+    }
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: reached via bracket notation from createTicket(); Biome cannot see that access.
+    markRetrying(attempt, delayMs) {
+        if (!this.applyTransition({ state: "retrying", attempt }))
+            return;
+        emitIsolated(this.emitter, "update", {
+            type: "retrying",
+            attempt,
+            delayMs,
+        });
+    }
+    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: reached via bracket notation from createTicket(); Biome cannot see that access.
+    markDone(result) {
+        if (!this.applyTransition({ state: "done", result }))
+            return;
+        emitIsolated(this.emitter, "update", { type: "done", result });
+        emitIsolated(this.emitter, "done", result);
+        if (result.success === false) {
+            emitIsolated(this.emitter, "error", result.error);
+        }
+        this._resolve(result);
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory — the only public way to get a ticket and its controller
+// ---------------------------------------------------------------------------
+export function createTicket(id) {
+    const ticket = new Ticket(id);
+    // Bind the private methods to the ticket instance and expose them
+    // through the controller interface.
+    const controller = {
+        // Bracket notation accesses private methods — the type boundary prevents
+        // external callers from reaching these, while the controller provides
+        // a clean compile-time API for internal use.
+        // biome-ignore-start lint/complexity/useLiteralKeys: these members are private; dot
+        // access is a compile error, bracket notation is the deliberate escape hatch.
+        markQueued: () => ticket["markQueued"](),
+        markRetrying: (attempt, delayMs) => ticket["markRetrying"](attempt, delayMs),
+        markDone: (result) => ticket["markDone"](result),
+        abortSignal: () => ticket["_abortController"].abort(),
+        // biome-ignore-end lint/complexity/useLiteralKeys: restore the rule.
+    };
+    return { ticket, controller };
+}
+//# sourceMappingURL=ticket.js.map

package/dist/ticket/ticket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ticket.js","sourceRoot":"","sources":["../../src/ticket/ticket.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,85 @@
+{
+	"name": "@vereda/http",
+	"version": "1.0.0",
+	"description": "A resilient HTTP client with automatic queuing, retries, and bulkhead isolation",
+	"type": "module",
+	"sideEffects": false,
+	"exports": {
+		".": {
+			"types": "./dist/core/index.d.ts",
+			"import": "./dist/core/index.js"
+		},
+		"./middleware": {
+			"types": "./dist/middleware/index.d.ts",
+			"import": "./dist/middleware/index.js"
+		},
+		"./zod": {
+			"types": "./dist/adapters/zod.d.ts",
+			"import": "./dist/adapters/zod.js"
+		}
+	},
+	"scripts": {
+		"build": "tsc",
+		"prepublishOnly": "npm run build && npm test",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"test:coverage": "vitest run --coverage",
+		"typecheck": "tsc --noEmit && tsc -p tsconfig.test.json && tsc -p examples/tsconfig.json && tsc -p performance/tsconfig.json",
+		"example:checkout": "tsx --tsconfig examples/tsconfig.json examples/checkout/index.ts",
+		"lint": "biome lint",
+		"lint:fix": "biome lint --write",
+		"format": "biome format --write",
+		"format:check": "biome format",
+		"check": "biome check --error-on-warnings",
+		"check:fix": "biome check --write",
+		"ci": "biome ci --error-on-warnings",
+		"docs": "typedoc"
+	},
+	"keywords": [
+		"http",
+		"client",
+		"queue",
+		"retry",
+		"bulkhead",
+		"resilience"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/riosgabriel/vereda.git"
+	},
+	"bugs": {
+		"url": "https://github.com/riosgabriel/vereda/issues"
+	},
+	"homepage": "https://github.com/riosgabriel/vereda#readme",
+	"engines": {
+		"node": ">=22"
+	},
+	"files": [
+		"dist",
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"peerDependencies": {
+		"zod": "^4.6.5"
+	},
+	"peerDependenciesMeta": {
+		"zod": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@arethetypeswrong/cli": "^0.18.5",
+		"@biomejs/biome": "^2.5.14",
+		"@types/node": "^26.6.2",
+		"@vitest/coverage-v8": "5.0.1",
+		"husky": "^9.1.7",
+		"publint": "^0.3.24",
+		"tsx": "^4.23.15",
+		"typedoc": "^0.28.20",
+		"typescript": "^6.0.0",
+		"vitest": "^5.0.1",
+		"zod": "^4.6.5"
+	}
+}

package/src/adapters/zod.ts

@@ -0,0 +1,16 @@
+import type { ZodType } from "zod";
+import type { ParseFn } from "../core/types.ts";
+
+/**
+ * Wraps a Zod schema into a ParseFn for use with vereda's `parse` option.
+ *
+ * @example
+ * const UserSchema = z.object({ id: z.number(), name: z.string() });
+ *
+ * const ticket = client.get('/users/1', {
+ *   parse: withZod(UserSchema),
+ * });
+ */
+export function withZod<T>(schema: ZodType<T>): ParseFn<T> {
+	return (data: unknown): T => schema.parse(data);
+}

package/src/core/backoff.ts

@@ -0,0 +1,26 @@
+import type { BackoffFn, BackoffOptions } from "./types.ts";
+
+/** Default base delay in ms for exponential backoff. */
+export const DEFAULT_BASE_DELAY_MS = 200;
+/** Default max delay cap in ms for exponential backoff. */
+export const DEFAULT_MAX_DELAY_MS = 30_000;
+/** Default jitter setting for exponential backoff. */
+export const DEFAULT_JITTER = true;
+
+export function buildBackoffFn(config?: BackoffFn | BackoffOptions): BackoffFn {
+	if (typeof config === "function") {
+		return config;
+	}
+
+	const baseDelayMs = config?.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+	const maxDelayMs = config?.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+	const jitter = config?.jitter ?? DEFAULT_JITTER;
+
+	return (attempt: number): number => {
+		const exponential = baseDelayMs * 2 ** attempt;
+		const capped = Math.min(exponential, maxDelayMs);
+		if (!jitter) return capped;
+		// Full jitter: random value in [0, capped]
+		return Math.random() * capped;
+	};
+}