@ericsanchezok/synergy-util 3.0.23 → 3.1.0

package/dist/render-ui.js

@@ -0,0 +1,208 @@
+import { z } from "zod";
+export var RenderUI;
+(function (RenderUI) {
+    RenderUI.Key = z
+        .string()
+        .regex(/^[a-zA-Z][\w-]{0,63}$/)
+        .refine((key) => !["constructor", "prototype", "__proto__"].includes(key));
+    RenderUI.Value = z.union([z.string().max(2000), z.number().finite(), z.boolean()]);
+    RenderUI.Binding = z.union([RenderUI.Value, z.object({ ref: RenderUI.Key }).strict()]);
+    const base = { id: RenderUI.Key, parent: RenderUI.Key.optional() };
+    const text = z.string().max(4000);
+    RenderUI.Node = z.discriminatedUnion("type", [
+        z.object({ ...base, type: z.literal("heading"), text, level: z.enum(["2", "3"]).optional() }).strict(),
+        z.object({ ...base, type: z.literal("text"), text }).strict(),
+        z.object({ ...base, type: z.literal("row"), columns: z.number().int().min(1).max(4).optional() }).strict(),
+        z.object({ ...base, type: z.literal("card"), title: text.optional() }).strict(),
+        z
+            .object({
+            ...base,
+            type: z.literal("metric"),
+            label: text,
+            value: RenderUI.Binding,
+            prefix: z.string().max(40).optional(),
+            suffix: z.string().max(40).optional(),
+        })
+            .strict(),
+        z
+            .object({
+            ...base,
+            type: z.literal("slider"),
+            label: text,
+            state: RenderUI.Key,
+            min: z.number().finite(),
+            max: z.number().finite(),
+            step: z.number().positive().optional(),
+        })
+            .strict(),
+        z
+            .object({
+            ...base,
+            type: z.literal("select"),
+            label: text,
+            state: RenderUI.Key,
+            options: z.array(z.string().max(200)).min(1).max(24),
+        })
+            .strict(),
+        z.object({ ...base, type: z.literal("checkbox"), label: text, state: RenderUI.Key }).strict(),
+        z.object({ ...base, type: z.literal("button"), label: text, text: z.string().min(1).max(4000) }).strict(),
+        z
+            .object({
+            ...base,
+            type: z.literal("bar"),
+            label: text,
+            items: z
+                .array(z.object({ label: text, value: RenderUI.Binding }).strict())
+                .min(1)
+                .max(32),
+        })
+            .strict(),
+    ]);
+    RenderUI.Computed = z
+        .object({
+        id: RenderUI.Key,
+        op: z.enum(["add", "subtract", "multiply", "divide", "min", "max"]),
+        inputs: z.tuple([RenderUI.Binding, RenderUI.Binding]),
+    })
+        .strict();
+    RenderUI.Spec = z
+        .object({
+        state: z.record(RenderUI.Key, RenderUI.Value).default({}),
+        computed: z.array(RenderUI.Computed).max(64).default([]),
+        nodes: z.array(RenderUI.Node).min(1).max(128),
+    })
+        .strict()
+        .superRefine((spec, ctx) => {
+        if (new TextEncoder().encode(JSON.stringify(spec)).byteLength > 128 * 1024)
+            ctx.addIssue({ code: "custom", message: "UI exceeds 128 KiB" });
+        if (new TextEncoder().encode(JSON.stringify(spec.state)).byteLength > 12 * 1024)
+            ctx.addIssue({ code: "custom", message: "Initial state exceeds 12 KiB" });
+        const values = new Set(Object.keys(spec.state));
+        if (values.size > 32)
+            ctx.addIssue({ code: "custom", message: "At most 32 state values" });
+        const numericValues = new Set(Object.keys(spec.state).filter((key) => typeof spec.state[key] === "number"));
+        function binding(value, numeric = false) {
+            if (typeof value === "object" && !values.has(value.ref))
+                ctx.addIssue({ code: "custom", message: `Unknown value: ${value.ref}` });
+            else if (numeric && (typeof value === "object" ? !numericValues.has(value.ref) : typeof value !== "number"))
+                ctx.addIssue({ code: "custom", message: "Computations and chart values must be numeric" });
+        }
+        for (const computed of spec.computed) {
+            if (values.has(computed.id))
+                ctx.addIssue({ code: "custom", message: `Duplicate value: ${computed.id}` });
+            computed.inputs.forEach((value) => binding(value, true));
+            values.add(computed.id);
+            numericValues.add(computed.id);
+        }
+        const nodes = new Map();
+        for (const node of spec.nodes) {
+            if (nodes.has(node.id))
+                ctx.addIssue({ code: "custom", message: `Duplicate node: ${node.id}` });
+            if (node.parent) {
+                const parent = nodes.get(node.parent);
+                if (!parent || !["row", "card"].includes(parent.type))
+                    ctx.addIssue({ code: "custom", message: `Parent must be an earlier row or card: ${node.id}` });
+            }
+            if ("state" in node) {
+                const value = spec.state[node.state];
+                if (value === undefined ||
+                    (node.type === "slider" &&
+                        (typeof value !== "number" || node.min >= node.max || value < node.min || value > node.max)) ||
+                    (node.type === "checkbox" && typeof value !== "boolean") ||
+                    (node.type === "select" && (typeof value !== "string" || !node.options.includes(value))))
+                    ctx.addIssue({ code: "custom", message: `Invalid control state: ${node.id}` });
+            }
+            if (node.type === "metric")
+                binding(node.value);
+            if (node.type === "bar")
+                node.items.forEach((item) => binding(item.value, true));
+            nodes.set(node.id, node);
+        }
+    })
+        .meta({ ref: "RenderUI" });
+    /**
+     * Provenance: https://www.openui.com/blog/how-chatgpt-intelligent-ui-works
+     * Local adaptation: bounded declarative data, keyed controls and local arithmetic replace authored programs.
+     */
+    function evaluate(spec, state) {
+        const values = Object.assign(Object.create(null), spec.state, state);
+        function resolve(value) {
+            return typeof value === "object" ? values[value.ref] : value;
+        }
+        for (const item of spec.computed) {
+            const a = resolve(item.inputs[0]), b = resolve(item.inputs[1]);
+            if (typeof a !== "number" || typeof b !== "number")
+                throw new Error(`Invalid numeric inputs: ${item.id}`);
+            const result = item.op === "add"
+                ? a + b
+                : item.op === "subtract"
+                    ? a - b
+                    : item.op === "multiply"
+                        ? a * b
+                        : item.op === "divide"
+                            ? a / b
+                            : item.op === "min"
+                                ? Math.min(a, b)
+                                : Math.max(a, b);
+            if (!Number.isFinite(result))
+                throw new Error(`Invalid arithmetic result: ${item.id}`);
+            values[item.id] = result;
+        }
+        return values;
+    }
+    RenderUI.evaluate = evaluate;
+    function preview(input) {
+        if (!input || typeof input !== "object")
+            return;
+        const raw = input;
+        if (raw.state !== undefined && (!raw.state || typeof raw.state !== "object" || Array.isArray(raw.state)))
+            return;
+        const state = z.record(RenderUI.Key, RenderUI.Value).safeParse(Object.fromEntries(Object.entries(raw.state ?? {})));
+        if (!state.success || Object.keys(state.data).length > 32 || !Array.isArray(raw.nodes) || raw.nodes.length > 128)
+            return;
+        const computed = [];
+        if (Array.isArray(raw.computed)) {
+            if (raw.computed.length > 64)
+                return;
+            for (const value of raw.computed) {
+                const parsed = RenderUI.Computed.safeParse(value);
+                if (!parsed.success)
+                    break;
+                computed.push(parsed.data);
+            }
+        }
+        const nodes = [];
+        for (const value of raw.nodes) {
+            const parsed = RenderUI.Node.safeParse(value);
+            if (!parsed.success)
+                break;
+            nodes.push(parsed.data);
+        }
+        const parsed = RenderUI.Spec.safeParse({ state: state.data, computed, nodes });
+        return parsed.success ? parsed.data : undefined;
+    }
+    RenderUI.preview = preview;
+    function fallback(spec) {
+        const values = evaluate(spec, spec.state);
+        const escape = (text) => String(text).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
+        const resolve = (value) => (typeof value === "object" ? values[value.ref] : value);
+        return spec.nodes
+            .map((node) => {
+            if (node.type === "heading")
+                return `<h${node.level ?? "2"}>${escape(node.text)}</h${node.level ?? "2"}>`;
+            if (node.type === "text")
+                return `<p>${escape(node.text)}</p>`;
+            if (node.type === "metric")
+                return `<p>${escape(node.label)}: ${escape(node.prefix ?? "")}${escape(resolve(node.value))}${escape(node.suffix ?? "")}</p>`;
+            if (node.type === "bar")
+                return `<p>${escape(node.label)}</p><ul>${node.items.map((item) => `<li>${escape(item.label)}: ${escape(resolve(item.value))}</li>`).join("")}</ul>`;
+            if ("state" in node)
+                return `<p>${escape(node.label)}: ${escape(spec.state[node.state])}</p>`;
+            if (node.type === "card" && node.title)
+                return `<h3>${escape(node.title)}</h3>`;
+            return "";
+        })
+            .join("\n");
+    }
+    RenderUI.fallback = fallback;
+})(RenderUI || (RenderUI = {}));

package/dist/resource-reference.d.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+export declare namespace ResourceReference {
+    const Workspace: z.ZodObject<{
+        id: z.ZodString;
+        generation: z.ZodNumber;
+        root: z.ZodString;
+    }, z.core.$strip>;
+    type Workspace = z.infer<typeof Workspace>;
+    const Context: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        state: z.ZodLiteral<"bound">;
+        workspace: z.ZodObject<{
+            id: z.ZodString;
+            generation: z.ZodNumber;
+            root: z.ZodString;
+        }, z.core.$strip>;
+        directory: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        state: z.ZodLiteral<"none">;
+    }, z.core.$strip>, z.ZodObject<{
+        state: z.ZodLiteral<"unresolved">;
+    }, z.core.$strip>], "state">;
+    type Context = z.infer<typeof Context>;
+    const Location: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"text">;
+        line: z.ZodNumber;
+        column: z.ZodOptional<z.ZodNumber>;
+        endLine: z.ZodOptional<z.ZodNumber>;
+        endColumn: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"heading">;
+        id: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"page">;
+        page: z.ZodNumber;
+    }, z.core.$strip>], "kind">;
+    type Location = z.infer<typeof Location>;
+    type Target = {
+        kind: "workspace-file";
+        path: string;
+        location?: Location;
+    } | {
+        kind: "asset";
+        url: string;
+        location?: Location;
+    } | {
+        kind: "note";
+        id: string;
+        location?: Location;
+    } | {
+        kind: "url";
+        url: string;
+    } | {
+        kind: "image";
+        url: string;
+    } | {
+        kind: "anchor";
+        id: string;
+    } | {
+        kind: "unavailable";
+        value: string;
+        reason: "invalid-target" | "invalid-location" | "unsupported-protocol";
+    };
+    function parse(input: string): Target;
+    function normalizePath(value: string): string | undefined;
+    function format(reference: Target, location?: Location): string;
+    function fileUrl(path: string): string;
+    function resolvePath(input: string, context: Context): string | undefined;
+    function capture(workspace: {
+        id?: string;
+        generation?: number;
+        path: string;
+    } | null | undefined): Context;
+}

package/dist/resource-reference.js

@@ -0,0 +1,227 @@
+import { z } from "zod";
+import { AssetReference } from "./asset-reference";
+export var ResourceReference;
+(function (ResourceReference) {
+    const position = z.number().int().positive().max(2_147_483_647);
+    ResourceReference.Workspace = z.object({ id: z.string().min(1), generation: position, root: z.string() });
+    ResourceReference.Context = z.discriminatedUnion("state", [
+        z.object({ state: z.literal("bound"), workspace: ResourceReference.Workspace, directory: z.string() }),
+        z.object({ state: z.literal("none") }),
+        z.object({ state: z.literal("unresolved") }),
+    ]);
+    ResourceReference.Location = z
+        .discriminatedUnion("kind", [
+        z.object({
+            kind: z.literal("text"),
+            line: position,
+            column: position.optional(),
+            endLine: position.optional(),
+            endColumn: position.optional(),
+        }),
+        z.object({ kind: z.literal("heading"), id: z.string() }),
+        z.object({ kind: z.literal("page"), page: position }),
+    ])
+        .refine((value) => value.kind !== "text" ||
+        (value.endLine ?? value.line) > value.line ||
+        ((value.endLine ?? value.line) === value.line && (value.endColumn ?? value.column ?? 1) >= (value.column ?? 1)));
+    const controls = /[\u0000-\u001f\u007f]/;
+    const absolute = (value) => value.startsWith("/") || /^[a-z]:\//i.test(value);
+    const slash = (value) => value.replaceAll("\\", "/");
+    function textLocation(match) {
+        return {
+            kind: "text",
+            line: Number(match[2]),
+            ...(match[3] ? { column: Number(match[3]) } : {}),
+            ...(match[4] ? { endLine: Number(match[4]) } : {}),
+            ...(match[5] ? { endColumn: Number(match[5]) } : {}),
+        };
+    }
+    function parse(input) {
+        const value = input.trim();
+        const unavailable = (reason = "invalid-target") => ({
+            kind: "unavailable",
+            value: input,
+            reason,
+        });
+        if (!value || controls.test(value))
+            return unavailable();
+        if (/^data:image\/(?:png|jpe?g|gif|webp|avif|bmp|x-icon|vnd\.microsoft\.icon|svg\+xml)(?:;[^,]*)?,/i.test(value))
+            return { kind: "image", url: value };
+        if (value.startsWith("blob:")) {
+            if (/^blob:null\/[^/]+$/.test(value))
+                return { kind: "image", url: value };
+            try {
+                const source = new URL(value.slice(5));
+                if (["http:", "https:"].includes(source.protocol) && source.hostname && source.pathname !== "/")
+                    return { kind: "image", url: value };
+            }
+            catch { }
+            return unavailable("unsupported-protocol");
+        }
+        if (/^(https?:|mailto:|tel:)/i.test(value)) {
+            try {
+                const url = new URL(value);
+                if ((url.protocol === "http:" || url.protocol === "https:") && !url.hostname)
+                    return unavailable();
+                return { kind: "url", url: value };
+            }
+            catch {
+                return unavailable();
+            }
+        }
+        if (value.startsWith("//"))
+            return parse(`https:${value}`);
+        try {
+            if (/^note:/i.test(value)) {
+                const match = value.match(/^note:\/\/([a-zA-Z0-9_-]+)(?:#(.*))?$/i);
+                if (!match)
+                    return unavailable();
+                const id = match[1];
+                const block = match[2] ? decodeURIComponent(match[2]) : undefined;
+                if (block && controls.test(block))
+                    return unavailable("invalid-location");
+                return { kind: "note", id, ...(block ? { location: { kind: "heading", id: block } } : {}) };
+            }
+            if (value.startsWith("#"))
+                return { kind: "anchor", id: decodeURIComponent(value.slice(1)) };
+            let path = value;
+            let location;
+            const hash = path.indexOf("#");
+            if (hash >= 0) {
+                const fragment = path.slice(hash + 1);
+                const lines = fragment.match(/^()L(\d+)(?:C(\d+))?(?:[-–]L?(\d+)(?:C(\d+))?)?$/);
+                location = lines
+                    ? textLocation(lines)
+                    : /^page=\d+$/.test(fragment)
+                        ? { kind: "page", page: Number(fragment.slice(5)) }
+                        : { kind: "heading", id: decodeURIComponent(fragment) };
+                if (/^L\d|^page=/.test(fragment) && location.kind === "heading")
+                    return unavailable("invalid-location");
+                path = path.slice(0, hash);
+            }
+            else {
+                const lines = path.match(/^(.*?):(\d+)(?::(\d+))?(?:[-–](\d+)(?::(\d+))?)?$/);
+                if (lines) {
+                    path = lines[1];
+                    location = textLocation(lines);
+                }
+            }
+            if (location && !ResourceReference.Location.safeParse(location).success)
+                return unavailable("invalid-location");
+            if (path.startsWith("asset://") || path.startsWith("/asset/")) {
+                const asset = AssetReference.parse(path.startsWith("/asset/") ? `asset://${path.slice(7)}` : path);
+                return asset ? { kind: "asset", url: asset.url, ...(location ? { location } : {}) } : unavailable();
+            }
+            if (/^file:/i.test(path)) {
+                const url = new URL(path);
+                if (url.search || url.username || url.password || url.port)
+                    return unavailable();
+                path = decodeURIComponent(url.pathname);
+                if (url.hostname && url.hostname !== "localhost")
+                    path = `//${url.hostname}${path}`;
+                else if (/^\/[a-z]:\//i.test(path))
+                    path = path.slice(1);
+            }
+            else {
+                if (/^[a-z][a-z\d+.-]*:/i.test(path) && !/^[a-z]:[\\/]/i.test(path))
+                    return unavailable("unsupported-protocol");
+                if (path.includes("?"))
+                    return unavailable();
+                path = decodeURIComponent(path);
+            }
+            if (!path || controls.test(path))
+                return unavailable();
+            return { kind: "workspace-file", path: slash(path), ...(location ? { location } : {}) };
+        }
+        catch {
+            return unavailable();
+        }
+    }
+    ResourceReference.parse = parse;
+    function normalizePath(value) {
+        if (controls.test(value) || absolute(slash(value)))
+            return;
+        const parts = [];
+        for (const part of slash(value).split("/")) {
+            if (!part || part === ".")
+                continue;
+            if (part === "..") {
+                if (!parts.length)
+                    return;
+                parts.pop();
+            }
+            else
+                parts.push(part);
+        }
+        return parts.join("/");
+    }
+    ResourceReference.normalizePath = normalizePath;
+    function format(reference, location) {
+        if (reference.kind === "unavailable")
+            return reference.value;
+        if (reference.kind === "anchor")
+            return `#${encodeURIComponent(reference.id)}`;
+        if (reference.kind === "url" || reference.kind === "image")
+            return reference.url;
+        const target = reference.kind === "asset"
+            ? reference.url
+            : reference.kind === "note"
+                ? `note://${reference.id}`
+                : absolute(slash(reference.path))
+                    ? fileUrl(reference.path)
+                    : reference.path.split("/").map(encodeURIComponent).join("/");
+        const position = location ?? reference.location;
+        if (!position)
+            return target;
+        if (position.kind === "heading")
+            return `${target}#${encodeURIComponent(position.id)}`;
+        if (position.kind === "page")
+            return `${target}#page=${position.page}`;
+        const start = `L${position.line}${position.column === undefined ? "" : `C${position.column}`}`;
+        const end = position.endLine !== undefined || position.endColumn !== undefined
+            ? `-L${position.endLine ?? position.line}${position.endColumn === undefined ? "" : `C${position.endColumn}`}`
+            : "";
+        return `${target}#${start}${end}`;
+    }
+    ResourceReference.format = format;
+    function fileUrl(path) {
+        const value = slash(path);
+        if (!absolute(value) || controls.test(value))
+            throw new Error("A file URL requires an absolute path");
+        const encoded = value
+            .split("/")
+            .map((part, index) => (index === 0 && /^[a-z]:$/i.test(part) ? part : encodeURIComponent(part)))
+            .join("/");
+        return value.startsWith("//") ? `file:${encoded}` : `file://${value.startsWith("/") ? "" : "/"}${encoded}`;
+    }
+    ResourceReference.fileUrl = fileUrl;
+    function resolvePath(input, context) {
+        if (context.state !== "bound" || input.startsWith("~") || controls.test(input))
+            return;
+        const value = slash(input);
+        const root = slash(context.workspace.root).replace(/\/$/, "");
+        if (absolute(value)) {
+            if (context.workspace.root === "/" && value.startsWith("/"))
+                return normalizePath(value.slice(1));
+            if (!root)
+                return;
+            const windows = /^[a-z]:\//i.test(root) || root.startsWith("//");
+            const compare = windows ? value.toLowerCase() : value;
+            const base = windows ? root.toLowerCase() : root;
+            if (compare === base)
+                return "";
+            if (!compare.startsWith(`${base}/`))
+                return;
+            return normalizePath(value.slice(root.length + 1));
+        }
+        return normalizePath(context.directory ? `${context.directory}/${value}` : value);
+    }
+    ResourceReference.resolvePath = resolvePath;
+    function capture(workspace) {
+        if (!workspace)
+            return { state: "none" };
+        const parsed = ResourceReference.Workspace.safeParse({ id: workspace.id, generation: workspace.generation, root: workspace.path });
+        return parsed.success ? { state: "bound", workspace: parsed.data, directory: "" } : { state: "unresolved" };
+    }
+    ResourceReference.capture = capture;
+})(ResourceReference || (ResourceReference = {}));

package/dist/retry.d.ts

@@ -4,5 +4,9 @@ export interface RetryOptions {
     factor?: number;
     maxDelay?: number;
     retryIf?: (error: unknown) => boolean;
+    retryDelay?: (error: unknown) => number | undefined;
+    signal?: AbortSignal;
 }
+export declare function retrySleep(ms: number, signal?: AbortSignal): Promise<void>;
+export declare function retryAfterMs(headers?: Headers | Record<string, string>, now?: number): number | undefined;
 export declare function retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;

package/dist/retry.js

@@ -1,33 +1,66 @@
-const TRANSIENT_MESSAGES = [
-    "load failed",
-    "network connection was lost",
-    "network request failed",
-    "failed to fetch",
-    "econnreset",
-    "econnrefused",
-    "etimedout",
-    "socket hang up",
-];
-function isTransientError(error) {
-    if (!error)
-        return false;
-    const message = String(error instanceof Error ? error.message : error).toLowerCase();
-    return TRANSIENT_MESSAGES.some((m) => message.includes(m));
+import { classifyNetworkError } from "./network-error";
+export function retrySleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(signal.reason);
+        const abort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", abort);
+            resolve();
+        }, Math.max(0, Math.min(ms, 2_147_483_647)));
+        signal?.addEventListener("abort", abort, { once: true });
+    });
 }
+// Provenance: https://www.rfc-editor.org/rfc/rfc9110.html#section-10.2.3
+// Local adaptation: accept finite retry-after-ms extensions and case-insensitive headers, rejecting partial numeric parses.
+export function retryAfterMs(headers, now = Date.now()) {
+    if (!headers)
+        return undefined;
+    let values;
+    try {
+        values = headers instanceof Headers ? headers : new Headers(headers);
+    }
+    catch {
+        return undefined;
+    }
+    const milliseconds = values.get("retry-after-ms")?.trim();
+    if (milliseconds && /^\d+(?:\.\d+)?$/.test(milliseconds) && Number.isFinite(Number(milliseconds)))
+        return Number(milliseconds);
+    const value = values.get("retry-after")?.trim();
+    if (!value)
+        return undefined;
+    if (/^\d+$/.test(value)) {
+        const result = Number(value) * 1000;
+        return Number.isFinite(result) ? result : undefined;
+    }
+    if (!/^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(value))
+        return undefined;
+    const result = Date.parse(value) - now;
+    return Number.isFinite(result) && result >= 0 ? result : undefined;
+}
+// Provenance: https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
+// Local adaptation: equal jitter keeps a positive half-delay while preserving server retry hints and caller cancellation.
 export async function retry(fn, options = {}) {
-    const { attempts = 3, delay = 500, factor = 2, maxDelay = 10000, retryIf = isTransientError } = options;
-    let lastError;
-    for (let attempt = 0; attempt < attempts; attempt++) {
+    const { attempts = 3, delay = 500, factor = 2, maxDelay = 10000, retryIf = (error) => classifyNetworkError(error)?.kind === "transient", retryDelay, signal, } = options;
+    if (!Number.isInteger(attempts) || attempts < 1)
+        throw new RangeError("Retry attempts must be a positive integer");
+    for (let attempt = 0;; attempt++) {
+        signal?.throwIfAborted();
         try {
             return await fn();
         }
         catch (error) {
-            lastError = error;
-            if (attempt === attempts - 1 || !retryIf(error))
+            signal?.throwIfAborted();
+            if (attempt >= attempts - 1 || !retryIf(error))
                 throw error;
-            const wait = Math.min(delay * Math.pow(factor, attempt), maxDelay);
-            await new Promise((resolve) => setTimeout(resolve, wait));
+            const hint = retryDelay?.(error);
+            const wait = hint !== undefined && Number.isFinite(hint) && hint >= 0
+                ? hint
+                : Math.min(delay * Math.pow(factor, attempt), maxDelay) * (0.5 + Math.random() / 2);
+            await retrySleep(wait, signal);
         }
     }
-    throw lastError;
 }