@evolu/common 8.0.0-next.4 → 8.0.0

package/dist/src/Http.d.ts

@@ -0,0 +1,394 @@
+/**
+ * Task-aware HTTP helpers.
+ *
+ * @module
+ */
+import { type Result } from "./Result.ts";
+import type { Task } from "./Task.ts";
+import type { Typed } from "./Type.ts";
+import type { Awaitable } from "./Types.ts";
+/**
+ * WHATWG-fetch-compatible function used by {@link fetch}.
+ *
+ * A default dependency, replaceable at the composition root — for a
+ * platform-optimized fetch such as React Native's, a configured undici
+ * instance, or a test double. Implementations must be pre-bound; unbound
+ * `globalThis.fetch` throws in browsers.
+ *
+ * @group Fetch
+ */
+export type NativeFetch = typeof globalThis.fetch;
+/**
+ * Dependency wrapper for {@link NativeFetch}.
+ *
+ * @group Fetch
+ */
+export interface NativeFetchDep {
+    readonly nativeFetch: NativeFetch;
+}
+/**
+ * Body mode for {@link fetch}.
+ *
+ * A mode selects a built-in consumer that reads the {@link Response} inside the
+ * fetch Task:
+ *
+ * - `"bytes"` — reads the body as a `Uint8Array<ArrayBuffer>`.
+ * - `"headers"` — cancels the body and returns {@link FetchResponse}. Pair it with
+ *   `{ method: "HEAD" }` when the server should not send a body.
+ * - `"json"` — parses the body as JSON and returns `unknown`. Narrow or decode at
+ *   the call site; there is deliberately no generic to cast through.
+ * - `"text"` — reads the body as a string.
+ *
+ * Body modes (`"bytes"`, `"json"`, `"text"`) return {@link FetchStatusError} for
+ * non-2xx responses. `"headers"` does not judge status, because the status is
+ * usually the value being asked for.
+ *
+ * @group Fetch
+ */
+export type FetchMode = "text" | "json" | "bytes" | "headers";
+/**
+ * Body-free {@link Response} view safe to return from {@link fetch}.
+ *
+ * {@link fetch} returns this view only after the native body has been drained,
+ * errored, or cancelled, so none of its usable members depends on the request
+ * signal. Body-reading members and `Response.clone` are omitted because they
+ * would be invalid after the fetch Task settles.
+ *
+ * This is a TypeScript contract, not a runtime security boundary: the runtime
+ * value can still be a native Response, and casts can access omitted members.
+ *
+ * @group Fetch
+ */
+export type FetchResponse = Omit<Response, "arrayBuffer" | "blob" | "body" | "bodyUsed" | "bytes" | "clone" | "formData" | "json" | "text">;
+/**
+ * Error returned by {@link fetch} body modes.
+ *
+ * The union distinguishes native request failures, non-2xx responses, and body
+ * read failures. Narrow on `type` when handling a specific case. The
+ * distinction matters for retries: {@link FetchBodyError} means a 2xx response
+ * failed during reading, so the server may have committed the request.
+ *
+ * @group Fetch
+ */
+export type FetchError = FetchTransportError | FetchStatusError | FetchBodyError;
+/**
+ * Error returned when the native fetch request fails before a response exists.
+ *
+ * @group Fetch
+ */
+export interface FetchTransportError extends Typed<"FetchTransportError"> {
+    readonly error: unknown;
+}
+/**
+ * Error returned when a body mode receives a non-2xx response.
+ *
+ * The response body is drained as text before this error is returned. Draining
+ * buffers the whole error body; error responses are expected to be small. If
+ * the drain itself fails, `body` contains the read error.
+ *
+ * @group Fetch
+ */
+export interface FetchStatusError extends Typed<"FetchStatusError"> {
+    readonly response: FetchResponse;
+    readonly body: Result<string, unknown>;
+}
+/**
+ * Error returned when a body mode cannot read or decode a 2xx response.
+ *
+ * This includes mid-stream network failures, decoding failures, and — for the
+ * `"json"` mode — empty bodies such as 204 responses, which are not JSON. Do
+ * not use `"json"` for endpoints that return no content.
+ *
+ * @group Fetch
+ */
+export interface FetchBodyError extends Typed<"FetchBodyError"> {
+    readonly response: FetchResponse;
+    readonly error: unknown;
+}
+/**
+ * Consumes a native {@link Response} before {@link fetch} settles.
+ *
+ * The callback runs inside the fetch Task, while the request signal is still
+ * alive. Return a Result error for expected domain failures. Throwing or
+ * rejecting with a non-abort error is a defect, like any other Task body.
+ *
+ * Consumers take values, not dependencies; close over anything they need. A
+ * consumer that needs its own timeout, retries, or child Tasks has outgrown
+ * being a consumer: fetch the body with a mode and compose Tasks on the plain
+ * value, or write a Task that owns the whole request.
+ *
+ * Consumers do not have to normalize abort. {@link fetch} rethrows Evolu
+ * {@link AbortError}, normalizes host abort errors after the Run aborts, and
+ * treats an Err returned after abort as abort control flow — so a consumer's
+ * `try`/`catch` around a body read cannot accidentally turn an abort into a
+ * domain error. An Ok returned after abort is kept; only errors are presumed to
+ * be abort in disguise.
+ *
+ * The Response and anything derived from its live body, such as a reader, must
+ * not escape the consumer. Consume to plain values before returning.
+ *
+ * @group Fetch
+ */
+export type FetchConsume<T, E = never> = (response: Response) => Awaitable<Result<T, E>>;
+/**
+ * Fetches a resource and consumes the {@link Response} inside the Task, so the
+ * body is read while the request signal is still alive.
+ *
+ * The request runs through {@link NativeFetchDep | run.deps.nativeFetch}.
+ * Because native fetch is a default dependency, platforms and tests can replace
+ * it without changing call sites.
+ *
+ * With a {@link FetchMode}, non-2xx responses return {@link FetchStatusError}
+ * (except `"headers"`, which reports status as a value) and unreadable bodies
+ * return {@link FetchBodyError}. With a {@link FetchConsume} callback, native
+ * status semantics apply: HTTP error statuses resolve, and the consumer decides
+ * how to interpret the status and body.
+ *
+ * `signal` is not accepted in init because abort is controlled by the current
+ * Run.
+ *
+ * Aborting the Run aborts the underlying request, any response that arrives
+ * after abort, and any in-progress body read. Abort is represented as
+ * {@link AbortError}, not FetchError: `run(fetch(...))` rejects with AbortError,
+ * and `run.abortable(fetch(...))` returns it as an {@link Err}.
+ *
+ * Some runtimes reject aborted fetches with their own error instead of
+ * `signal.reason`. This wrapper normalizes abort rejections from native fetch,
+ * built-in body reads, and consumer callbacks back to the Run's AbortError.
+ *
+ * `fetch` owns request lifetime and Response containment. It does not transform
+ * requests or interpret app protocols beyond the built-in modes. Use Task
+ * helpers for resilience, app helpers for app conventions, a replacement
+ * {@link NativeFetch} for request-wide behavior (base URLs, auth, logging), and
+ * consumers for response interpretation.
+ *
+ * ### Composing fetch
+ *
+ * Resilience is ordinary Task composition: wrap `fetch(url, "json")` in
+ * {@link timeout}, then in {@link retry}.
+ *
+ * ```ts
+ * import {
+ *   createRun,
+ *   exponential,
+ *   fetch,
+ *   retry,
+ *   take,
+ *   timeout,
+ *   type NativeFetch,
+ * } from "@evolu/common";
+ *
+ * const fetchWithRetry = (url: string) =>
+ *   retry(
+ *     timeout(fetch(url, "json"), "30s"),
+ *     take(2)(exponential("100ms")),
+ *   );
+ *
+ * let requestCount = 0;
+ * const nativeFetch: NativeFetch = () => {
+ *   requestCount++;
+ *   return Promise.resolve(
+ *     requestCount === 1
+ *       ? new Response("Try again", { status: 503 })
+ *       : new Response('{"name":"Ada"}'),
+ *   );
+ * };
+ * await using run = createRun({ nativeFetch });
+ *
+ * expectOk(await run(fetchWithRetry("/api/user")), { name: "Ada" });
+ * ```
+ *
+ * App conventions belong in small app-owned helpers. For example, posting JSON
+ * is native `init` plus two conventions worth centralizing — the content-type
+ * header and the stringify:
+ *
+ * ```ts
+ * import {
+ *   createRun,
+ *   fetch,
+ *   type FetchError,
+ *   type NativeFetch,
+ *   type Task,
+ * } from "@evolu/common";
+ *
+ * const postJson = (
+ *   url: string,
+ *   data: unknown,
+ * ): Task<unknown, FetchError> =>
+ *   fetch(url, "json", {
+ *     method: "POST",
+ *     headers: { "content-type": "application/json" },
+ *     body: JSON.stringify(data),
+ *   });
+ *
+ * const nativeFetch: NativeFetch = () =>
+ *   Promise.resolve(new Response('{"id":"user-1"}'));
+ * await using run = createRun({ nativeFetch });
+ *
+ * expectOk(await run(postJson("/api/users", { name: "Ada" })), {
+ *   id: "user-1",
+ * });
+ * ```
+ *
+ * Your app's version will grow your conventions — auth, envelopes, error
+ * mapping — which is why it belongs to the app, not to `fetch`.
+ *
+ * ### Intercepting requests
+ *
+ * Request-wide behavior belongs to a replacement {@link NativeFetch} installed
+ * at the composition root. This is the equivalent of interceptors or hooks in
+ * libraries that expose client instances.
+ *
+ * ```ts
+ * import { createRun, fetch, type NativeFetch } from "@evolu/common";
+ *
+ * const token = "secret-token";
+ * const baseUrl = "https://api.example.com/v1/";
+ * let interceptedRequest: Request | undefined;
+ * const baseFetch: NativeFetch = (input, init) => {
+ *   interceptedRequest = new Request(input, init);
+ *   return Promise.resolve(new Response("ok"));
+ * };
+ *
+ * const nativeFetch: NativeFetch = (input, init) => {
+ *   const headers = new Headers(init?.headers);
+ *   headers.set("authorization", `Bearer ${token}`);
+ *
+ *   // Only string inputs are resolved against the base URL; URL and Request
+ *   // inputs are passed through unchanged.
+ *   const url =
+ *     typeof input === "string" ? new URL(input, baseUrl) : input;
+ *   return baseFetch(url, { ...init, headers });
+ * };
+ *
+ * await using run = createRun({ nativeFetch });
+ * expectOk(await run(fetch("users", "text")), "ok");
+ * expect({
+ *   url: interceptedRequest?.url,
+ *   authorization: interceptedRequest?.headers.get("authorization"),
+ * }).toEqual({
+ *   url: "https://api.example.com/v1/users",
+ *   authorization: "Bearer secret-token",
+ * });
+ * ```
+ *
+ * ### Consuming responses
+ *
+ * Built-in modes handle common bodies. Specialized response interpretation
+ * belongs in a consumer. Typed decoders, response envelopes, streaming, and
+ * custom status semantics can be built on top without changing `fetch`.
+ *
+ * ```ts
+ * import {
+ *   createRun,
+ *   fetch,
+ *   ok,
+ *   type FetchTransportError,
+ *   type NativeFetch,
+ *   type Task,
+ * } from "@evolu/common";
+ *
+ * const nativeFetch: NativeFetch = (input) =>
+ *   Promise.resolve(
+ *     String(input).endsWith("/metadata")
+ *       ? new Response(null, {
+ *           status: 204,
+ *           headers: { "cache-control": "max-age=60" },
+ *         })
+ *       : new Response('{"name":"Ada"}'),
+ *   );
+ * await using run = createRun({ nativeFetch });
+ *
+ * const user = await run(fetch("/api/user", "json"));
+ * const metadata = fetch("/api/user/metadata", (response) =>
+ *   ok({
+ *     status: response.status,
+ *     cache: response.headers.get("cache-control"),
+ *   }),
+ * );
+ * expectTypeOf(metadata).toEqualTypeOf<
+ *   Task<{ status: number; cache: string | null }, FetchTransportError>
+ * >();
+ * expectOk(user, { name: "Ada" });
+ * expectOk(await run(metadata), { status: 204, cache: "max-age=60" });
+ * ```
+ *
+ * ### Aborting fetch
+ *
+ * Abort follows the standard Task rules: a Fiber from `run(fetch(...))` rejects
+ * with {@link AbortError}, and `run.abortable(fetch(...))` returns it as a
+ * Result error.
+ *
+ * ```ts
+ * import {
+ *   AbortError,
+ *   createRun,
+ *   fetch,
+ *   type NativeFetch,
+ * } from "@evolu/common";
+ *
+ * const nativeFetch: NativeFetch = (_input, init) =>
+ *   new Promise<Response>((_resolve, reject) => {
+ *     const signal = init?.signal;
+ *     if (!signal) throw new Error("Missing signal");
+ *     signal.addEventListener("abort", () => reject(signal.reason), {
+ *       once: true,
+ *     });
+ *   });
+ * await using run = createRun({ nativeFetch });
+ *
+ * const fiber = run.abortable(fetch("/api/user", "json"));
+ * fiber.abort();
+ * const result = await fiber;
+ *
+ * expect(!result.ok && AbortError.is(result.error)).toBe(true);
+ * ```
+ *
+ * @group Fetch
+ */
+export declare function fetch(input: RequestInfo | URL, mode: "text", init?: Omit<RequestInit, "signal">): Task<string, FetchError>;
+export declare function fetch(input: RequestInfo | URL, mode: "json", init?: Omit<RequestInit, "signal">): Task<unknown, FetchError>;
+export declare function fetch(input: RequestInfo | URL, mode: "bytes", init?: Omit<RequestInit, "signal">): Task<Uint8Array<ArrayBuffer>, FetchError>;
+export declare function fetch(input: RequestInfo | URL, mode: "headers", init?: Omit<RequestInit, "signal">): Task<FetchResponse, FetchTransportError>;
+export declare function fetch<T, E = never>(input: RequestInfo | URL, consume: FetchConsume<T, E>, init?: Omit<RequestInit, "signal">): Task<T, FetchTransportError | E>;
+/**
+ * Test {@link NativeFetch} that records calls and serves queued handlers.
+ *
+ * Each call shifts the next handler. Calling with an empty queue throws, so a
+ * test never silently reaches an unplanned request.
+ *
+ * @group Testing
+ */
+export interface TestNativeFetch extends NativeFetch {
+    readonly calls: ReadonlyArray<TestNativeFetchCall>;
+    readonly handle: (handler: TestNativeFetchHandler) => void;
+}
+/**
+ * Recorded {@link TestNativeFetch} call.
+ *
+ * @group Testing
+ */
+export interface TestNativeFetchCall {
+    readonly input: RequestInfo | URL;
+    readonly init: RequestInit | undefined;
+}
+/**
+ * Handler for one {@link TestNativeFetch} call.
+ *
+ * @group Testing
+ */
+export type TestNativeFetchHandler = (input: RequestInfo | URL, init: RequestInit | undefined) => Awaitable<Response>;
+/**
+ * Creates {@link TestNativeFetch}.
+ *
+ * @group Testing
+ */
+export declare const testCreateNativeFetch: (...handlers: ReadonlyArray<TestNativeFetchHandler>) => TestNativeFetch;
+/**
+ * Creates a Response body for {@link NativeFetch} tests that errors on first
+ * read.
+ *
+ * @group Testing
+ */
+export declare const testCreateNativeFetchErroringBody: (error?: unknown) => ReadableStream<Uint8Array>;
+//# sourceMappingURL=Http.d.ts.map

package/dist/src/Http.d.ts.map

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

package/dist/src/Http.js

@@ -0,0 +1,102 @@
+/**
+ * Task-aware HTTP helpers.
+ *
+ * @module
+ */
+import { err, ok, tryAsync } from "./Result.js";
+export function fetch(input, modeOrConsume, init) {
+    return async (run) => {
+        const { signal } = run;
+        // Abort control flow wins over step errors, normalizing host abort errors
+        // from native fetch, body reads, body cancel, and consumers.
+        const orAbort = (error) => {
+            signal.throwIfAborted();
+            return error;
+        };
+        const fetched = await tryAsync(() => run.deps.nativeFetch(input, { ...init, signal }), orAbort);
+        let result;
+        if (!fetched.ok) {
+            result = err({ type: "FetchTransportError", error: fetched.error });
+        }
+        else {
+            const response = fetched.value;
+            // A response that arrives after abort is not processed: cancel its body
+            // best-effort, then let abort win before any mode or consumer runs.
+            if (signal.aborted) {
+                await tryAsync(() => response.body?.cancel());
+                signal.throwIfAborted();
+            }
+            if (typeof modeOrConsume === "function") {
+                const consumed = await tryAsync(() => modeOrConsume(response), orAbort);
+                // A consumer throw is a defect once orAbort has ruled out abort.
+                if (!consumed.ok)
+                    throw consumed.error;
+                result = consumed.value;
+            }
+            else if (modeOrConsume === "headers") {
+                // The head is already a value; body cancel failures are irrelevant.
+                await tryAsync(() => response.body?.cancel(), orAbort);
+                result = ok(response);
+            }
+            else if (!response.ok) {
+                result = err({
+                    type: "FetchStatusError",
+                    response,
+                    // Error bodies are diagnostics; text preserves proxy/HTML/plain responses across modes.
+                    body: await tryAsync(() => response.text(), orAbort),
+                });
+            }
+            else {
+                const body = await tryAsync(() => {
+                    switch (modeOrConsume) {
+                        case "text":
+                            return response.text();
+                        case "json":
+                            return response.json();
+                        case "bytes":
+                            return response.bytes();
+                    }
+                }, orAbort);
+                result = body.ok
+                    ? body
+                    : err({ type: "FetchBodyError", response, error: body.error });
+            }
+        }
+        // An Err produced after abort is treated as abort control flow.
+        if (!result.ok)
+            signal.throwIfAborted();
+        return result;
+    };
+}
+/**
+ * Creates {@link TestNativeFetch}.
+ *
+ * @group Testing
+ */
+export const testCreateNativeFetch = (...handlers) => {
+    const calls = [];
+    const handlerQueue = [...handlers];
+    return Object.assign((input, init) => {
+        calls.push({ input, init });
+        const handler = handlerQueue.shift();
+        if (!handler)
+            throw new Error("Unexpected NativeFetch call");
+        return Promise.resolve(handler(input, init));
+    }, {
+        calls,
+        handle: (handler) => {
+            handlerQueue.push(handler);
+        },
+    });
+};
+/**
+ * Creates a Response body for {@link NativeFetch} tests that errors on first
+ * read.
+ *
+ * @group Testing
+ */
+export const testCreateNativeFetchErroringBody = (error = new Error("stream failed")) => new ReadableStream({
+    pull: (controller) => {
+        controller.error(error);
+    },
+});

package/dist/src/Identicon.d.ts

@@ -3,8 +3,8 @@
  *
  * @module
  */
-import type { Brand } from "./Brand.js";
-import { Id } from "./Type.js";
+import type { Brand } from "./Brand.ts";
+import { Id } from "./Type.ts";
 /**
  * SVG string representing a visual identicon for an {@link Id}, created with
  * {@link createIdenticon}.
@@ -27,13 +27,22 @@ export type IdenticonStyle = "github" | "quadrant" | "gradient" | "sutnar";
  * ### Example
  *
  * ```ts
+ * import { createIdFromString, createIdenticon } from "@evolu/common";
+ *
+ * const id = createIdFromString("identicon-example");
  * const svg = createIdenticon(id);
- * const quadrantStyle = createIdenticon(id, "quadrant");
- * const gradientStyle = createIdenticon(id, "gradient");
- * const sutnarStyle = createIdenticon(id, "sutnar");
+ * const styles = ["quadrant", "gradient", "sutnar"] as const;
+ * const alternativeSvgs = styles.map((style) =>
+ *   createIdenticon(id, style),
+ * );
+ *
+ * // Branded IDs work too.
+ * const todoId = createIdFromString<"Todo">("todo-1");
+ * const todoSvg = createIdenticon(todoId);
  *
- * // Works with branded IDs
- * const ownerSvg = createIdenticon(ownerId);
+ * expect(svg.startsWith("<svg")).toBe(true);
+ * expect(new Set([svg, ...alternativeSvgs]).size).toBe(4);
+ * expect(todoSvg.startsWith("<svg")).toBe(true);
  * ```
  */
 export declare const createIdenticon: (id: Id, style?: IdenticonStyle) => Identicon;

package/dist/src/Identicon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Identicon.d.ts","sourceRoot":"","sources":["../../src/Identicon.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,EAAE,EAAe,MAAM,WAAW,CAAC;AAE5C;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC;AAEpD,+BAA+B;AAC/B,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,eAAe,GAC1B,IAAI,EAAE,EACN,QAAO,cAAyB,KAC/B,SA4JF,CAAC"}
+{"version":3,"file":"Identicon.d.ts","sourceRoot":"","sources":["../../src/Identicon.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,EAAE,EAAe,MAAM,WAAW,CAAC;AAE5C;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC;AAEpD,+BAA+B;AAC/B,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,eAAe,OACtB,EAAE,UACC,cAAc,KACpB,SA4JF,CAAC"}

package/dist/src/Identicon.js

@@ -20,13 +20,22 @@ import { Id, idToIdBytes } from "./Type.js";
  * ### Example
  *
  * ```ts
+ * import { createIdFromString, createIdenticon } from "@evolu/common";
+ *
+ * const id = createIdFromString("identicon-example");
  * const svg = createIdenticon(id);
- * const quadrantStyle = createIdenticon(id, "quadrant");
- * const gradientStyle = createIdenticon(id, "gradient");
- * const sutnarStyle = createIdenticon(id, "sutnar");
+ * const styles = ["quadrant", "gradient", "sutnar"] as const;
+ * const alternativeSvgs = styles.map((style) =>
+ *   createIdenticon(id, style),
+ * );
+ *
+ * // Branded IDs work too.
+ * const todoId = createIdFromString<"Todo">("todo-1");
+ * const todoSvg = createIdenticon(todoId);
  *
- * // Works with branded IDs
- * const ownerSvg = createIdenticon(ownerId);
+ * expect(svg.startsWith("<svg")).toBe(true);
+ * expect(new Set([svg, ...alternativeSvgs]).size).toBe(4);
+ * expect(todoSvg.startsWith("<svg")).toBe(true);
  * ```
  */
 export const createIdenticon = (id, style = "github") => {

package/dist/src/LeakDetector.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Development-time detection of leaked handles via garbage collection.
+ *
+ * @module
+ */
+import { type ConsoleDep } from "./Console.ts";
+/**
+ * Detects handles that are garbage-collected while still considered held.
+ *
+ * A handle such as a Lease must be explicitly cleaned up. Nothing in JavaScript
+ * enforces that, so a handle whose last reference is dropped without cleanup
+ * leaks silently. Garbage collection proves the leak: once the handle is
+ * unreachable, no code can ever clean it up. A LeakDetector observes collection
+ * with `FinalizationRegistry` and warns when the collected handle was still
+ * held — a proven leak with zero false positives, pointing at the tracking
+ * site.
+ *
+ * Detection is best-effort: garbage collection timing is not deterministic, so
+ * a warning may come late or, in short-lived processes, never. It is a
+ * development canary, not a guarantee. Production uses
+ * {@link noopLeakDetector}.
+ */
+export interface LeakDetector {
+    /**
+     * Starts tracking `target` until {@link LeakDetector.untrack | untrack} or
+     * garbage collection.
+     *
+     * When `target` is garbage-collected and {@link Leak.isLeaked} returns `true`,
+     * the leak is reported with the stack captured at this call. The leak must
+     * not reference `target`, or the target would never become unreachable.
+     */
+    readonly track: (target: object, leak: Leak, unregisterToken: object) => void;
+    /** Stops tracking the target registered with `unregisterToken`. */
+    readonly untrack: (unregisterToken: object) => void;
+}
+/** Describes a tracked handle for {@link LeakDetector.track}. */
+export interface Leak {
+    /** Handle name used in the warning, for example `"Lease"`. */
+    readonly name: string;
+    /** Returns whether the collected handle was still considered held. */
+    readonly isLeaked: () => boolean;
+}
+/**
+ * Dependency wrapper for {@link LeakDetector}.
+ *
+ * @see {@link LeakDetector}
+ */
+export interface LeakDetectorDep {
+    readonly leakDetector: LeakDetector;
+}
+/**
+ * Creates {@link LeakDetector} backed by `FinalizationRegistry`.
+ *
+ * Capturing a stack per track call is too expensive for production; use
+ * {@link noopLeakDetector} there.
+ */
+export declare const createLeakDetector: (deps: ConsoleDep) => LeakDetector;
+/** No-op {@link LeakDetector} for production. */
+export declare const noopLeakDetector: LeakDetector;
+/**
+ * Test {@link LeakDetector} with deterministic collection.
+ *
+ * @see {@link testCreateLeakDetector}
+ */
+export interface TestLeakDetector extends LeakDetector {
+    /**
+     * Simulates garbage collection of all tracked targets.
+     *
+     * Reports every tracked handle that is still held and clears tracking.
+     * Returns the number of reported leaks.
+     */
+    readonly collect: () => number;
+    /** Returns the number of currently tracked targets. */
+    readonly getTrackedCount: (options?: {
+        name?: string;
+    }) => number;
+}
+/**
+ * Dependency wrapper for {@link TestLeakDetector}.
+ *
+ * @see {@link TestLeakDetector}
+ */
+export interface TestLeakDetectorDep extends LeakDetectorDep {
+    readonly leakDetector: TestLeakDetector;
+}
+/** Creates {@link TestLeakDetector}. */
+export declare const testCreateLeakDetector: (deps: ConsoleDep) => TestLeakDetector;
+//# sourceMappingURL=LeakDetector.d.ts.map

package/dist/src/LeakDetector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LeakDetector.d.ts","sourceRoot":"","sources":["../../src/LeakDetector.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAG/C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,KAAK,IAAI,CAAC;IAE9E,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,CAAC,eAAe,EAAE,MAAM,KAAK,IAAI,CAAC;CACrD;AAED,iEAAiE;AACjE,MAAM,WAAW,IAAI;IACnB,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;CACrC;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,SAAU,UAAU,KAAG,YAoBrD,CAAC;AAEF,iDAAiD;AACjD,eAAO,MAAM,gBAAgB,EAAE,YAG9B,CAAC;AAyBF;;;;GAIG;AACH,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,MAAM,CAAC;IAE/B,uDAAuD;IACvD,QAAQ,CAAC,eAAe,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,MAAM,CAAC;CACnE;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAoB,SAAQ,eAAe;IAC1D,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAC;CACzC;AAED,wCAAwC;AACxC,eAAO,MAAM,sBAAsB,SAAU,UAAU,KAAG,gBAsCzD,CAAC"}