@vizejs/composable 0.426.3 → 0.427.0

package/dist/ref-debounced.d.mts

@@ -0,0 +1,29 @@
+import { UseDebouncedOptions } from "./use-debounced.mjs";
+import { MaybeRefOrGetter, ShallowRef } from "vue";
+
+//#region src/ref-debounced.d.ts
+/**
+ * Readonly ref that follows `source` after it stayed quiet for `waitMs`.
+ *
+ * Shorthand for `useDebounced(source, waitMs, options).debounced` when the
+ * pending flag and cancel/flush controls are not needed. Inherits every rule
+ * of {@link useDebounced}: synchronous mirroring on the server, reactive
+ * wait, and scope-bound cleanup.
+ *
+ * @example
+ * ```ts
+ * const query = ref("");
+ * const debouncedQuery = refDebounced(query, 300);
+ * ```
+ *
+ * @param source Reactive source.
+ * @param waitMs Reactive quiet period in milliseconds.
+ * @param options Server and scheduler policy.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_DEBOUNCE_INVALID_WAIT` for invalid
+ * waits (see {@link useDebounced}).
+ * @returns The debounced readonly ref.
+ */
+declare function refDebounced<Value>(source: MaybeRefOrGetter<Value>, waitMs: MaybeRefOrGetter<number>, options?: UseDebouncedOptions): Readonly<ShallowRef<Value>>;
+//#endregion
+export { refDebounced };

package/dist/ref-debounced.mjs

@@ -0,0 +1,29 @@
+import { useDebounced } from "./use-debounced.mjs";
+//#region src/ref-debounced.ts
+/**
+* Readonly ref that follows `source` after it stayed quiet for `waitMs`.
+*
+* Shorthand for `useDebounced(source, waitMs, options).debounced` when the
+* pending flag and cancel/flush controls are not needed. Inherits every rule
+* of {@link useDebounced}: synchronous mirroring on the server, reactive
+* wait, and scope-bound cleanup.
+*
+* @example
+* ```ts
+* const query = ref("");
+* const debouncedQuery = refDebounced(query, 300);
+* ```
+*
+* @param source Reactive source.
+* @param waitMs Reactive quiet period in milliseconds.
+* @param options Server and scheduler policy.
+* @default options {}
+* @throws `RangeError` tagged `VIZE_COMPOSE_DEBOUNCE_INVALID_WAIT` for invalid
+* waits (see {@link useDebounced}).
+* @returns The debounced readonly ref.
+*/
+function refDebounced(source, waitMs, options = {}) {
+	return useDebounced(source, waitMs, options).debounced;
+}
+//#endregion
+export { refDebounced };

package/dist/ref-default.d.mts

@@ -0,0 +1,27 @@
+import { MaybeRefOrGetter, Ref, WritableComputedRef } from "vue";
+
+//#region src/ref-default.d.ts
+/**
+ * View a nullable ref through a default value.
+ *
+ * Reads return the source value, or the (possibly reactive) default while the
+ * source holds `null` or `undefined`, so the read type drops those members.
+ * Writes go straight to the source and accept its full type, including
+ * `null`/`undefined` to fall back to the default again. Pure derived state:
+ * SSR-safe and nothing to dispose.
+ *
+ * @example
+ * ```ts
+ * const raw = ref<string | undefined>();
+ * const name = refDefault(raw, "Anonymous");
+ * name.value; // "Anonymous"
+ * name.value = "Ada"; // raw.value === "Ada"
+ * ```
+ *
+ * @param source Writable nullable ref.
+ * @param defaultValue Reactive fallback.
+ * @returns A writable computed ref whose reads never yield `null`/`undefined`.
+ */
+declare function refDefault<Value>(source: Ref<Value>, defaultValue: MaybeRefOrGetter<NonNullable<Value>>): WritableComputedRef<NonNullable<Value>, Value>;
+//#endregion
+export { refDefault };

package/dist/ref-default.mjs

@@ -0,0 +1,33 @@
+import { computed, toValue } from "vue";
+//#region src/ref-default.ts
+/**
+* View a nullable ref through a default value.
+*
+* Reads return the source value, or the (possibly reactive) default while the
+* source holds `null` or `undefined`, so the read type drops those members.
+* Writes go straight to the source and accept its full type, including
+* `null`/`undefined` to fall back to the default again. Pure derived state:
+* SSR-safe and nothing to dispose.
+*
+* @example
+* ```ts
+* const raw = ref<string | undefined>();
+* const name = refDefault(raw, "Anonymous");
+* name.value; // "Anonymous"
+* name.value = "Ada"; // raw.value === "Ada"
+* ```
+*
+* @param source Writable nullable ref.
+* @param defaultValue Reactive fallback.
+* @returns A writable computed ref whose reads never yield `null`/`undefined`.
+*/
+function refDefault(source, defaultValue) {
+	return computed({
+		get: () => source.value ?? toValue(defaultValue),
+		set: (value) => {
+			source.value = value;
+		}
+	});
+}
+//#endregion
+export { refDefault };

package/dist/resize-observer.d.mts

@@ -0,0 +1,96 @@
+import { n as MaybeElementTarget, r as MaybeElementTargets } from "./element-target-Crpxl4D9.mjs";
+import { MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/resize-observer.d.ts
+/** Runtime capability that supplies the `ResizeObserver` constructor. */
+interface ResizeObserverHost {
+  /** `ResizeObserver` constructor, absent in unsupported runtimes. */
+  readonly ResizeObserver?: new (callback: ResizeObserverCallback) => ResizeObserver;
+}
+/** Options for {@link useResizeObserver}. */
+interface UseResizeObserverOptions {
+  /**
+   * Box model reported by the observer.
+   *
+   * @default "content-box"
+   */
+  readonly box?: ResizeObserverBoxOptions;
+  /**
+   * Reactive constructor capability for alternate runtimes and tests.
+   *
+   * @default window when it provides `ResizeObserver`
+   */
+  readonly host?: MaybeRefOrGetter<ResizeObserverHost | null | undefined>;
+  /**
+   * Target resolution timing. `"post"` observes template refs after mount.
+   *
+   * @default "post"
+   */
+  readonly flush?: "pre" | "post" | "sync";
+}
+/** Controls returned by {@link useResizeObserver}. */
+interface ResizeObserverControls {
+  /** Whether the host provides `ResizeObserver`. `false` during server rendering. */
+  readonly isSupported: Readonly<Ref<boolean>>;
+  /** Disconnect the observer and stop following the reactive targets. Idempotent. */
+  readonly stop: () => void;
+}
+/**
+ * Observe size changes of one or more reactive elements.
+ *
+ * A single observer is (re)created whenever the resolved targets, the box
+ * option, or the host change; unresolved targets are skipped. The observer is
+ * disconnected when the owning reactive scope stops or `stop` is called.
+ * During server rendering no host resolves, `isSupported` stays `false`, and
+ * the callback never runs.
+ *
+ * Inside a component the host is read after mounting, so hydration renders
+ * the server fallback first and never mismatches.
+ *
+ * @param targets Reactive element target or list of targets.
+ * @param callback Native `ResizeObserver` callback.
+ * @param options Box model, runtime capability, and watcher timing.
+ * @default options {}
+ * @returns Support flag and stop control.
+ */
+declare function useResizeObserver(targets: MaybeElementTargets, callback: ResizeObserverCallback, options?: UseResizeObserverOptions): ResizeObserverControls;
+/** Element dimensions reported by {@link useElementSize}. */
+interface ElementSize {
+  /** Inline size in CSS pixels. */
+  readonly width: number;
+  /** Block size in CSS pixels. */
+  readonly height: number;
+}
+/** Options for {@link useElementSize}. */
+interface UseElementSizeOptions extends UseResizeObserverOptions {
+  /**
+   * Size exposed before the first observation and during server rendering.
+   * Keep it identical on server and client to avoid hydration mismatches.
+   *
+   * @default { width: 0, height: 0 }
+   */
+  readonly initialSize?: ElementSize;
+}
+/** Reactive size returned by {@link useElementSize}. */
+interface ElementSizeControls extends ResizeObserverControls {
+  /** Observed inline size in CSS pixels. */
+  readonly width: Readonly<Ref<number>>;
+  /** Observed block size in CSS pixels. */
+  readonly height: Readonly<Ref<number>>;
+}
+/**
+ * Track the rendered size of a reactive element.
+ *
+ * Reads the requested box from `contentBoxSize`/`borderBoxSize` (summing
+ * fragments) and falls back to `contentRect` for older engines. When the
+ * target unmounts the size resets to the initial value so stale geometry never
+ * leaks into the next render. Server renders expose `initialSize`.
+ *
+ * @param target Reactive element target.
+ * @param options Initial size, box model, capability, and watcher timing.
+ * @default options {}
+ * @returns Reactive width/height plus observer controls.
+ */
+declare function useElementSize(target: MaybeElementTarget, options?: UseElementSizeOptions): ElementSizeControls;
+//#endregion
+export { ElementSize, ElementSizeControls, ResizeObserverControls, ResizeObserverHost, UseElementSizeOptions, UseResizeObserverOptions, useElementSize, useResizeObserver };

package/dist/resize-observer.mjs

@@ -0,0 +1,111 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { resolveElement, resolveElements } from "./element-target.mjs";
+import { computed, hasInjectionContext, readonly, ref, shallowRef, toValue, watch, watchPostEffect } from "vue";
+//#region src/resize-observer.ts
+/**
+* Observe size changes of one or more reactive elements.
+*
+* A single observer is (re)created whenever the resolved targets, the box
+* option, or the host change; unresolved targets are skipped. The observer is
+* disconnected when the owning reactive scope stops or `stop` is called.
+* During server rendering no host resolves, `isSupported` stays `false`, and
+* the callback never runs.
+*
+* Inside a component the host is read after mounting, so hydration renders
+* the server fallback first and never mismatches.
+*
+* @param targets Reactive element target or list of targets.
+* @param callback Native `ResizeObserver` callback.
+* @param options Box model, runtime capability, and watcher timing.
+* @default options {}
+* @returns Support flag and stop control.
+*/
+function useResizeObserver(targets, callback, options = {}) {
+	const isSupported = ref(false);
+	const hydrated = shallowRef(!hasInjectionContext());
+	if (!hydrated.value) watchPostEffect(() => {
+		hydrated.value = true;
+	});
+	let stopWatch = watch(() => [hydrated.value ? options.host === void 0 ? browserResizeObserverHost() : toValue(options.host) : void 0, resolveElements(targets)], ([host, elements], _previous, onCleanup) => {
+		const Observer = host?.ResizeObserver;
+		isSupported.value = Observer !== void 0;
+		if (!Observer || elements.length === 0) return;
+		const observer = new Observer(callback);
+		const observeOptions = { box: options.box ?? "content-box" };
+		for (const element of elements) observer.observe(element, observeOptions);
+		onCleanup(() => observer.disconnect());
+	}, {
+		immediate: true,
+		flush: options.flush ?? "post"
+	});
+	const stop = () => {
+		stopWatch?.stop();
+		stopWatch = void 0;
+	};
+	tryOnScopeDispose(stop);
+	return {
+		isSupported: readonly(isSupported),
+		stop
+	};
+}
+/**
+* Track the rendered size of a reactive element.
+*
+* Reads the requested box from `contentBoxSize`/`borderBoxSize` (summing
+* fragments) and falls back to `contentRect` for older engines. When the
+* target unmounts the size resets to the initial value so stale geometry never
+* leaks into the next render. Server renders expose `initialSize`.
+*
+* @param target Reactive element target.
+* @param options Initial size, box model, capability, and watcher timing.
+* @default options {}
+* @returns Reactive width/height plus observer controls.
+*/
+function useElementSize(target, options = {}) {
+	const initial = options.initialSize ?? {
+		width: 0,
+		height: 0
+	};
+	const width = ref(initial.width);
+	const height = ref(initial.height);
+	const box = options.box ?? "content-box";
+	const controls = useResizeObserver(target, (entries) => {
+		const entry = entries.at(-1);
+		if (!entry) return;
+		const sizes = box === "border-box" ? entry.borderBoxSize : box === "content-box" ? entry.contentBoxSize : entry.devicePixelContentBoxSize;
+		if (sizes && sizes.length > 0) {
+			let inline = 0;
+			let block = 0;
+			for (const size of sizes) {
+				inline += size.inlineSize;
+				block += size.blockSize;
+			}
+			width.value = inline;
+			height.value = block;
+			return;
+		}
+		width.value = entry.contentRect.width;
+		height.value = entry.contentRect.height;
+	}, options);
+	const stopReset = watch(computed(() => resolveElement(target) !== null), (isMounted) => {
+		if (isMounted) return;
+		width.value = initial.width;
+		height.value = initial.height;
+	});
+	const stop = () => {
+		stopReset.stop();
+		controls.stop();
+	};
+	tryOnScopeDispose(stop);
+	return {
+		width: readonly(width),
+		height: readonly(height),
+		isSupported: controls.isSupported,
+		stop
+	};
+}
+function browserResizeObserverHost() {
+	return typeof window !== "undefined" && typeof window.ResizeObserver === "function" ? window : void 0;
+}
+//#endregion
+export { useElementSize, useResizeObserver };

package/dist/resolver.d.mts

@@ -0,0 +1,124 @@
+//#region src/resolver.d.ts
+/** Package that owns the resolvable exports. */
+declare const VIZE_COMPOSABLE_PACKAGE = "@vizejs/composable";
+/** Entry name (subpath without `./`) that exposes at least one auto-importable export. */
+type VizeComposableEntry = string;
+/** One `vize-lib.lock.json` item (the fields the resolver reads). */
+interface VizeComposableLockedItem {
+  /** Item name, for example `"use-toggle"`. */
+  readonly name: string;
+  /** Item kind, for example `"composable"`. */
+  readonly kind: string;
+  /** Project-relative POSIX directory the registry layout was copied into. */
+  readonly dir: string;
+}
+/** The parts of `vize-lib.lock.json` the resolver reads. */
+interface VizeComposableLockfile {
+  /** Lockfile schema version. */
+  readonly lockfileVersion: number;
+  /** Pulled items. */
+  readonly items: readonly VizeComposableLockedItem[];
+}
+/** Options for the `@vizejs/composable` resolvers. */
+interface VizeComposableResolverOptions {
+  /**
+   * Only resolve exports of these entries (for example `"use-toggle"`).
+   *
+   * @default every entry
+   */
+  readonly include?: readonly VizeComposableEntry[];
+  /**
+   * Never resolve exports of these entries.
+   *
+   * @default []
+   */
+  readonly exclude?: readonly VizeComposableEntry[];
+  /**
+   * Only resolve these export names (for example to avoid clashing with another library).
+   *
+   * @default every runtime export
+   */
+  readonly names?: readonly string[];
+  /**
+   * Resolve to the npm package, or to `vize lib pull` copies recorded in the lockfile.
+   *
+   * @default "package"
+   */
+  readonly source?: "local" | "package";
+  /**
+   * Project root used to locate the lockfile and pulled directories.
+   *
+   * @default process.cwd()
+   */
+  readonly root?: string;
+  /**
+   * Lockfile path (relative to `root`) or an already-parsed lockfile.
+   *
+   * @default "vize-lib.lock.json"
+   */
+  readonly lockfile?: string | VizeComposableLockfile;
+  /**
+   * In `local` mode, resolve entries that were not pulled to the package.
+   *
+   * @default true
+   */
+  readonly fallback?: boolean;
+}
+/** An import produced by the resolver: `import { name } from from`. */
+interface VizeComposableImport {
+  /** Export name. */
+  readonly name: string;
+  /** Module specifier or absolute file path. */
+  readonly from: string;
+}
+/**
+ * Read and validate `vize-lib.lock.json`.
+ *
+ * @param file Absolute lockfile path.
+ * @returns The parsed lockfile.
+ * @throws {Error} `[VIZE_COMPOSE_RESOLVER_LOCKFILE]` when missing or malformed.
+ */
+declare function readComposableLockfile(file: string): VizeComposableLockfile;
+/**
+ * Every auto-importable export the options allow, with its direct subpath import.
+ *
+ * @param options Filters and source mode.
+ * @default options {}
+ * @returns Imports in catalog order.
+ */
+declare function listVizeComposableImports(options?: VizeComposableResolverOptions): readonly VizeComposableImport[];
+/**
+ * `unplugin-auto-import` resolver for every `@vizejs/composable` export.
+ *
+ * Server/SSR: build-time only; reads the lockfile once in `local` mode.
+ *
+ * @example
+ * ```ts
+ * AutoImport({ resolvers: [VizeComposableResolver()] });
+ * // useToggle() -> import { useToggle } from "@vizejs/composable/use-toggle"
+ * ```
+ *
+ * @param options Filters and source mode.
+ * @default options {}
+ * @returns A name -> import resolver function.
+ */
+declare function VizeComposableResolver(options?: VizeComposableResolverOptions): (name: string) => VizeComposableImport | undefined;
+/**
+ * `unplugin-auto-import` `imports` preset: `{ "@vizejs/composable/use-toggle": ["useToggle"] }`.
+ *
+ * @param options Filters and source mode.
+ * @default options {}
+ * @returns Export names grouped by module.
+ */
+declare function vizeComposableImports(options?: VizeComposableResolverOptions): Readonly<Record<string, readonly string[]>>;
+/**
+ * Global declarations for auto-imported composables, for setups without a
+ * generator (Nuxt and `unplugin-auto-import` emit their own).
+ *
+ * @param options Filters and source mode.
+ * @default options {}
+ * @returns A `.d.ts` module declaring each export as a global.
+ */
+declare function createVizeComposableDeclarations(options?: VizeComposableResolverOptions): string;
+//#endregion
+export { VIZE_COMPOSABLE_PACKAGE, VizeComposableEntry, VizeComposableImport, VizeComposableLockedItem, VizeComposableLockfile, VizeComposableResolver, VizeComposableResolverOptions, createVizeComposableDeclarations, listVizeComposableImports, readComposableLockfile, vizeComposableImports };

package/dist/resolver.mjs

@@ -0,0 +1,138 @@
+import { t as COMPOSABLE_CATALOG } from "./catalog-r4Z5nptX.mjs";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+//#region src/resolver.ts
+/**
+* Build-time auto-import resolver for `@vizejs/composable`, driven by the
+* package catalog so every new entry is picked up automatically.
+*
+* Every export resolves to its own subpath (`@vizejs/composable/use-toggle`),
+* so auto-imported code tree-shakes exactly like hand-written imports; this
+* module runs in Node (Vite/Nuxt config) and never ships to the browser.
+* With `source: "local"`, entries pulled by `vize lib pull` (recorded in
+* `vize-lib.lock.json`) resolve to the local copies.
+*/
+/** Package that owns the resolvable exports. */
+const VIZE_COMPOSABLE_PACKAGE = "@vizejs/composable";
+/** Subpaths that are tooling, not auto-importable runtime code. */
+const NON_IMPORTABLE_SUBPATHS = new Set(["./catalog", "./resolver"]);
+/** Export name -> owning entry, first catalog entry wins. */
+function catalogExports() {
+	const exports = /* @__PURE__ */ new Map();
+	for (const entry of COMPOSABLE_CATALOG.entries) {
+		if (NON_IMPORTABLE_SUBPATHS.has(entry.subpath)) continue;
+		for (const name of entry.runtimeExports) if (!exports.has(name)) exports.set(name, {
+			entry: entry.subpath.slice(2),
+			source: entry.source.slice(4)
+		});
+	}
+	return exports;
+}
+function isLockfile(value) {
+	return typeof value === "object" && value !== null && "items" in value && Array.isArray(value.items) && value.items.every((item) => typeof item === "object" && item !== null && "name" in item && "kind" in item && "dir" in item && typeof item.name === "string" && typeof item.kind === "string" && typeof item.dir === "string");
+}
+/**
+* Read and validate `vize-lib.lock.json`.
+*
+* @param file Absolute lockfile path.
+* @returns The parsed lockfile.
+* @throws {Error} `[VIZE_COMPOSE_RESOLVER_LOCKFILE]` when missing or malformed.
+*/
+function readComposableLockfile(file) {
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(file, "utf8"));
+	} catch (error) {
+		throw new Error(`[VIZE_COMPOSE_RESOLVER_LOCKFILE] cannot read ${file}`, { cause: error });
+	}
+	if (!isLockfile(parsed)) throw new Error(`[VIZE_COMPOSE_RESOLVER_LOCKFILE] ${file} is not a vize lib lockfile`);
+	return parsed;
+}
+function createLocator(options) {
+	const include = options.include === void 0 ? void 0 : new Set(options.include);
+	const exclude = new Set(options.exclude ?? []);
+	const allowed = (entry) => (include === void 0 || include.has(entry)) && !exclude.has(entry);
+	if (options.source !== "local") return (item) => allowed(item.entry) ? `${VIZE_COMPOSABLE_PACKAGE}/${item.entry}` : void 0;
+	const root = options.root ?? process.cwd();
+	const lockfile = typeof options.lockfile === "object" ? options.lockfile : readComposableLockfile(path.resolve(root, options.lockfile ?? "vize-lib.lock.json"));
+	const pulled = new Map(lockfile.items.filter((item) => item.kind === "composable").map((item) => [item.name, item.dir]));
+	const fallback = options.fallback ?? true;
+	return (item) => {
+		if (!allowed(item.entry)) return void 0;
+		const dir = pulled.get(item.entry);
+		if (dir === void 0) return fallback ? `${VIZE_COMPOSABLE_PACKAGE}/${item.entry}` : void 0;
+		return path.resolve(root, dir, item.source).split(path.sep).join("/");
+	};
+}
+/**
+* Every auto-importable export the options allow, with its direct subpath import.
+*
+* @param options Filters and source mode.
+* @default options {}
+* @returns Imports in catalog order.
+*/
+function listVizeComposableImports(options = {}) {
+	const locate = createLocator(options);
+	const names = options.names === void 0 ? void 0 : new Set(options.names);
+	const imports = [];
+	for (const [name, item] of catalogExports()) {
+		if (names !== void 0 && !names.has(name)) continue;
+		const from = locate(item);
+		if (from !== void 0) imports.push({
+			name,
+			from
+		});
+	}
+	return imports;
+}
+/**
+* `unplugin-auto-import` resolver for every `@vizejs/composable` export.
+*
+* Server/SSR: build-time only; reads the lockfile once in `local` mode.
+*
+* @example
+* ```ts
+* AutoImport({ resolvers: [VizeComposableResolver()] });
+* // useToggle() -> import { useToggle } from "@vizejs/composable/use-toggle"
+* ```
+*
+* @param options Filters and source mode.
+* @default options {}
+* @returns A name -> import resolver function.
+*/
+function VizeComposableResolver(options = {}) {
+	const allowed = new Map(listVizeComposableImports(options).map((item) => [item.name, item]));
+	return (name) => allowed.get(name);
+}
+/**
+* `unplugin-auto-import` `imports` preset: `{ "@vizejs/composable/use-toggle": ["useToggle"] }`.
+*
+* @param options Filters and source mode.
+* @default options {}
+* @returns Export names grouped by module.
+*/
+function vizeComposableImports(options = {}) {
+	const grouped = {};
+	for (const { name, from } of listVizeComposableImports(options)) (grouped[from] ??= []).push(name);
+	return grouped;
+}
+/**
+* Global declarations for auto-imported composables, for setups without a
+* generator (Nuxt and `unplugin-auto-import` emit their own).
+*
+* @param options Filters and source mode.
+* @default options {}
+* @returns A `.d.ts` module declaring each export as a global.
+*/
+function createVizeComposableDeclarations(options = {}) {
+	return [
+		"// Generated by @vizejs/composable/resolver. Do not edit.",
+		"export {};",
+		"declare global {",
+		...listVizeComposableImports(options).map((item) => `  const ${item.name}: typeof import(${JSON.stringify(item.from)})["${item.name}"];`),
+		"}",
+		""
+	].join("\n");
+}
+//#endregion
+export { VIZE_COMPOSABLE_PACKAGE, VizeComposableResolver, createVizeComposableDeclarations, listVizeComposableImports, readComposableLockfile, vizeComposableImports };

package/dist/retry-async.d.mts

@@ -1,5 +1,5 @@
-import { TimeoutScheduler } from "./timeout-scheduler.mjs";
-import { RetryDelayOptions } from "./retry-delay.mjs";
+import { t as TimeoutScheduler } from "./timeout-scheduler-CI8RVLZs.mjs";
+import { t as RetryDelayOptions } from "./retry-delay-DYsdq4SE.mjs";
 
 //#region src/retry-async.d.ts
 /** Context supplied to every invocation of a retried operation. */

package/dist/retry-delay-DYsdq4SE.d.mts

@@ -0,0 +1,73 @@
+//#region src/retry-delay.d.ts
+/** Options for {@link calculateRetryDelay}. */
+interface RetryDelayOptions {
+  /**
+   * Delay before the first retry, in milliseconds.
+   *
+   * @default 100
+   */
+  readonly initialDelayMs?: number;
+  /**
+   * Exponential multiplier applied for each subsequent retry.
+   *
+   * Values may be fractional but must be finite and at least one. The
+   * calculated delay is rounded up so a retry never starts earlier than the
+   * requested backoff.
+   *
+   * @default 2
+   */
+  readonly multiplier?: number;
+  /**
+   * Inclusive ceiling for the calculated delay, in milliseconds.
+   *
+   * The ceiling may be lower than {@link RetryDelayOptions.initialDelayMs};
+   * in that case it also caps the first retry.
+   *
+   * @default 30000
+   */
+  readonly maximumDelayMs?: number;
+  /**
+   * Fraction of the capped delay eligible for downward jitter.
+   *
+   * `0` is deterministic exponential backoff, `0.5` samples from the upper
+   * half of the range, and `1` applies full jitter from zero through the
+   * capped delay. Jitter never exceeds the unjittered delay.
+   *
+   * @default 0
+   */
+  readonly jitterRatio?: number;
+  /**
+   * Entropy source returning a number in the half-open interval `[0, 1)`.
+   * It is called exactly once when the selected jitter range contains more
+   * than one integer millisecond, and is otherwise not read.
+   *
+   * @default Math.random
+   */
+  readonly random?: () => number;
+}
+/**
+ * Calculate a bounded exponential-backoff delay for a one-based retry.
+ *
+ * The first retry is `retryAttempt = 1`. The result is always an integer from
+ * zero through `2_147_483_647`, making it safe to pass to common host timer
+ * APIs without implementation-specific clamping. The calculation is pure
+ * unless jitter requires the supplied entropy source, and it performs no work
+ * when the module is imported.
+ *
+ * Jitter samples uniformly from the inclusive integer range
+ * `ceil(cappedDelay * (1 - jitterRatio))...cappedDelay`. Capping occurs before
+ * jitter, so neither floating-point overflow nor entropy can exceed the
+ * configured maximum.
+ *
+ * @param retryAttempt One-based retry number after a failed initial attempt.
+ * @param options Backoff, cap, jitter, and entropy configuration.
+ * @default options {}
+ * @throws {RangeError} A tagged error when the retry number, delay options, or
+ * entropy value is outside its documented range.
+ * @throws {TypeError} A tagged error when `options` is not an object or
+ * `random` is not callable.
+ * @returns An integer delay in milliseconds.
+ */
+declare function calculateRetryDelay(retryAttempt: number, options?: RetryDelayOptions): number;
+//#endregion
+export { calculateRetryDelay as n, RetryDelayOptions as t };