better-supabase 0.12.0 → 0.13.0

package/dist/otel/index.d.ts

@@ -1,6 +1,6 @@
-import { o as EventHub } from "../events-P3raDX2E.js";
-import { d as Plugin } from "../plugin-D-95Q0w0.js";
-import { t as SPEC_PINS } from "../spec-pins-Dqpml2dZ.js";
+import { o as EventHub } from "../events-DhGgwqQA.js";
+import { d as Plugin } from "../plugin-DouW0Kvg.js";
+import { t as SPEC_PINS } from "../spec-pins-CZ2CL8YZ.js";
 import { Attributes, Meter, Tracer } from "@opentelemetry/api";
 //#region src/otel/index.d.ts
 export declare const INSTRUMENTATION_NAME = "better-supabase";
@@ -14,20 +14,23 @@ export interface OtelOptions {
   /** Set `false` to skip the duration histogram. */
   readonly metrics?: boolean;
   /**
-   * The database name in `db.namespace` (`{database}|{schema}`). Supabase
-   * names it `postgres`, the default for Postgres executors.
+   * The database name in `db.namespace` (`{database}|{schema}`). Supabase names
+   * it `postgres`, the default for Postgres executors.
    */
   readonly database?: string;
-  /** `server.address` and `server.port` on spans and metrics, e.g. the project host. */
+  /**
+   * `server.address` and `server.port` on spans and metrics, e.g. the project
+   * host.
+   */
   readonly server?: {
     readonly address: string;
     readonly port?: number;
   };
 }
 /**
- * Database client spans and metrics for every repository operation, using
- * the OpenTelemetry database conventions. Filter values and row data are
- * never recorded; `db.query.summary` is `SELECT customers`.
+ * Database client spans and metrics for every repository operation, using the
+ * OpenTelemetry database conventions. Filter values and row data are never
+ * recorded; `db.query.summary` is `SELECT customers`.
  *
  * ```ts
  * const betterSupabase = defineSupabase(schema).use(otel());
@@ -35,8 +38,8 @@ export interface OtelOptions {
  */
 export declare function otel(options?: OtelOptions): Plugin<"otel">;
 /**
- * Spans for auth resolution and session refreshes, from `betterSupabase.events`.
- * Returns a function that stops listening.
+ * Spans for auth resolution and session refreshes, from
+ * `betterSupabase.events`. Returns a function that stops listening.
  */
 export declare function traceAuth(betterSupabase: {
   readonly events: EventHub;
@@ -44,16 +47,16 @@ export declare function traceAuth(betterSupabase: {
 /**
  * Records block events (`support.started`, `webhook.failed`, ...) with the
  * `BLOCK_ATTRIBUTES` names: as an event on the active span, or as a short
- * `block <type>` span when there is none. Failures (`*.failed`, `*.denied`)
- * set an error status. Returns a function that stops listening.
+ * `block <type>` span when there is none. Failures (`*.failed`, `*.denied`) set
+ * an error status. Returns a function that stops listening.
  */
 export declare function traceBlockEvents(betterSupabase: {
   readonly events: EventHub;
 }, options?: Pick<OtelOptions, "tracer" | "attributes">): () => void;
 /**
- * A `fetch` that adds W3C `traceparent`/`tracestate` from the active
- * context. Pass it to `createClient(url, key, { global: { fetch } })` so
- * PostgREST, Auth and Storage calls join the trace.
+ * A `fetch` that adds W3C `traceparent`/`tracestate` from the active context.
+ * Pass it to `createClient(url, key, { global: { fetch } })` so PostgREST, Auth
+ * and Storage calls join the trace.
  */
 export declare function tracedFetch(base?: typeof fetch): typeof fetch;
 //#endregion

package/dist/otel/index.js

@@ -1,8 +1,8 @@
-import { r as definePlugin } from "../plugin-tfXW1-qO.js";
-import { t as SPEC_PINS } from "../spec-pins-S4PymRxp.js";
-import "../version-DSWxci83.js";
-import { i as blockEventAttributes } from "../block-events-DD9Q_NUz.js";
+import { r as definePlugin } from "../plugin-D9bYbYli.js";
+import { t as SPEC_PINS } from "../spec-pins-D3Tm6HJi.js";
+import { i as blockEventAttributes } from "../block-events-BURaqwyp.js";
 import { SpanKind, SpanStatusCode, context, metrics, propagation, trace } from "@opentelemetry/api";
+//#endregion
 //#region src/otel/index.ts
 const INSTRUMENTATION_NAME = "better-supabase";
 /** OpenTelemetry semantic conventions version the attributes follow. */
@@ -31,18 +31,18 @@ function systemOf(executor) {
 	return executor.name === "postgrest" || executor.name === "postgres" ? "postgresql" : executor.name;
 }
 /**
-* Database client spans and metrics for every repository operation, using
-* the OpenTelemetry database conventions. Filter values and row data are
-* never recorded; `db.query.summary` is `SELECT customers`.
+* Database client spans and metrics for every repository operation, using the
+* OpenTelemetry database conventions. Filter values and row data are never
+* recorded; `db.query.summary` is `SELECT customers`.
 *
 * ```ts
 * const betterSupabase = defineSupabase(schema).use(otel());
 * ```
 */
 function otel(options = {}) {
-	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.12.0");
+	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.13.0");
 	let histogram;
-	if (options.metrics !== false) histogram = (options.meter ?? metrics.getMeter("better-supabase", "0.12.0")).createHistogram("db.client.operation.duration", {
+	if (options.metrics !== false) histogram = (options.meter ?? metrics.getMeter("better-supabase", "0.13.0")).createHistogram("db.client.operation.duration", {
 		unit: "s",
 		description: "Duration of database client operations.",
 		advice: { explicitBucketBoundaries: [
@@ -149,7 +149,10 @@ function otel(options = {}) {
 			};
 			const rpc = executor.rpc?.bind(executor);
 			const batch = executor.batch?.bind(executor);
-			/** Semantic conventions name a batch `BATCH <operation>` when every operation shares it. */
+			/**
+			* Semantic conventions name a batch `BATCH <operation>` when every
+			* operation shares it.
+			*/
 			const describeBatch = (ops) => {
 				const [only, ...others] = new Set(ops.map(operationName));
 				const operation = only && others.length === 0 ? `BATCH ${only}` : "BATCH";
@@ -212,11 +215,11 @@ function otel(options = {}) {
 	});
 }
 /**
-* Spans for auth resolution and session refreshes, from `betterSupabase.events`.
-* Returns a function that stops listening.
+* Spans for auth resolution and session refreshes, from
+* `betterSupabase.events`. Returns a function that stops listening.
 */
 function traceAuth(betterSupabase, options = {}) {
-	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.12.0");
+	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.13.0");
 	const offAuth = betterSupabase.events.on("auth", (event) => {
 		const span = tracer.startSpan("auth.resolve", {
 			kind: SpanKind.INTERNAL,
@@ -250,11 +253,11 @@ function traceAuth(betterSupabase, options = {}) {
 /**
 * Records block events (`support.started`, `webhook.failed`, ...) with the
 * `BLOCK_ATTRIBUTES` names: as an event on the active span, or as a short
-* `block <type>` span when there is none. Failures (`*.failed`, `*.denied`)
-* set an error status. Returns a function that stops listening.
+* `block <type>` span when there is none. Failures (`*.failed`, `*.denied`) set
+* an error status. Returns a function that stops listening.
 */
 function traceBlockEvents(betterSupabase, options = {}) {
-	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.12.0");
+	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.13.0");
 	return betterSupabase.events.on("block", (event) => {
 		const attributes = {
 			...options.attributes,
@@ -275,9 +278,9 @@ function traceBlockEvents(betterSupabase, options = {}) {
 	});
 }
 /**
-* A `fetch` that adds W3C `traceparent`/`tracestate` from the active
-* context. Pass it to `createClient(url, key, { global: { fetch } })` so
-* PostgREST, Auth and Storage calls join the trace.
+* A `fetch` that adds W3C `traceparent`/`tracestate` from the active context.
+* Pass it to `createClient(url, key, { global: { fetch } })` so PostgREST, Auth
+* and Storage calls join the trace.
 */
 function tracedFetch(base = fetch) {
 	return (input, init) => {

package/dist/outbox-Bsk-HJnq.d.ts

@@ -0,0 +1,199 @@
+/// <reference lib="esnext.temporal" />
+import { b as DbError, t as AsyncResult } from "./result-mijqfoJN.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { i as CursorPageOptions, n as BlockOptions } from "./block-helpers-DyA5BAW4.js";
+import { n as BlockHooks } from "./block-hooks-BadAniNI.js";
+import { t as BlockProblemOptions } from "./problem-D_DEBfMn.js";
+import { i as EventSink, t as CloudEvent } from "./cloud-event-CidL9jiw.js";
+import { g as SubscriberPolicy, i as AuthorizationHooks } from "./authorization-hooks-HXVZXxUk.js";
+//#region src/blocks/outbox/outbox.d.ts
+/** One row of the outbox, as `outbox_claim` and `outbox_history` return it. */
+interface OutboxEvent {
+  /** The cursor value: increases with every event. */
+  readonly position: number;
+  readonly id: string;
+  readonly type: string;
+  readonly payload: unknown;
+  /**
+   * The module or function that wrote it, e.g.
+   * `better-supabase/blocks/organizations`.
+   */
+  readonly source: string | null;
+  readonly subject: string | null;
+  readonly tenant: string | null;
+  readonly key: string | null;
+  readonly actorId: string | null;
+  readonly createdAt: Temporal.Instant;
+}
+interface EmitOptions {
+  readonly subject?: string;
+  readonly tenant?: string;
+  /** With a key, emitting again (per tenant) returns the first event. */
+  readonly key?: string;
+  readonly source?: string;
+}
+/**
+ * `transport` writes (`emit`) and reads (`history`); `service`, which defaults
+ * to `transport`, runs the consumer calls (`register`, `relay`, `consume`,
+ * `deadLetters`, `purge`), which need the service role.
+ */
+interface OutboxOptions extends BlockOptions {
+  /** CloudEvents `source` of the relayed events, e.g. `https://crm.example.com`. */
+  readonly source: string;
+  /**
+   * Prepended to each type with a dot when relaying, e.g. `com.example`.
+   * Defaults to `dev.better-supabase`.
+   */
+  readonly typePrefix?: string;
+  /**
+   * Decides, per event, whether a consumer gets it. The consumer is the
+   * subscriber `{ principal: <consumer name>, kind: "service" }`. An event it
+   * leaves out is skipped and the cursor moves past it; a throw counts as a
+   * failed attempt. Defaults to `authorization.delivery.subscribers`.
+   */
+  readonly subscribers?: SubscriberPolicy;
+  /** `server.authorization`, for its `delivery.subscribers` policy. */
+  readonly authorization?: Pick<AuthorizationHooks, "delivery">;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: BlockHooks<Outbox>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+interface RegisterOptions {
+  /**
+   * Type patterns such as `organization.*` or `invoice.paid`. Defaults to every
+   * event.
+   */
+  readonly types?: readonly string[];
+  /** Start at the first kept event instead of after the latest one. */
+  readonly fromStart?: boolean;
+}
+interface RelayOptions {
+  /** Events per claim and per `sink.send`. Defaults to 100. */
+  readonly batch?: number;
+  /** How long a claim holds the consumer. Defaults to `1 minute`. */
+  readonly lease?: string;
+  /** Stops claiming after this many milliseconds. */
+  readonly budgetMs?: number;
+  /** Identifies this worker in the lease. Defaults to a random id. */
+  readonly owner?: string;
+  /**
+   * Failures in a row before the event that keeps failing goes to the dead
+   * letters and the cursor moves past it. Defaults to 10.
+   */
+  readonly maxAttempts?: number;
+  /** The longest wait between failed attempts. Defaults to `10 minutes`. */
+  readonly maxBackoff?: string;
+}
+interface RelayResult {
+  /** Events handed to the sink or handler. */
+  readonly delivered: number;
+  /**
+   * Events the `subscribers` policy kept from the consumer, when there were
+   * any.
+   */
+  readonly refused?: number;
+  /**
+   * Set when the sink threw: the consumer backs off and retries the batch one
+   * event at a time.
+   */
+  readonly error?: DbError;
+  /** 1 when this run moved the failing event to the dead letters. */
+  readonly deadLettered?: number;
+}
+/** An event a consumer skipped after `maxAttempts` failures. */
+interface OutboxDeadLetter {
+  readonly consumer: string;
+  readonly event: OutboxEvent;
+  readonly attempts: number;
+  readonly error: string | null;
+  readonly deadAt: Temporal.Instant;
+}
+interface OutboxPurgeOptions {
+  /**
+   * A consumer that hasn't claimed for this long (a Postgres interval such as
+   * `30 days`) no longer holds events back. Defaults to waiting for every
+   * consumer.
+   */
+  readonly ignoreIdle?: string;
+}
+/**
+ * Takes a batch of outbox rows, with the actor and tenant that CloudEvents
+ * leave out. Throwing counts a failed attempt: the consumer backs off, then
+ * retries one event at a time until the event that fails goes to the dead
+ * letters.
+ */
+type OutboxHandler = (events: readonly OutboxEvent[]) => unknown;
+interface OutboxRouteOptions extends Omit<RelayOptions, "owner">, BlockProblemOptions {
+  /** The bearer secret, such as `process.env.CRON_SECRET`. */
+  readonly secret: string | undefined;
+  /**
+   * Consumer name to the sink its events go to, or a handler that takes the
+   * rows.
+   */
+  readonly consumers: Readonly<Record<string, EventSink | OutboxHandler>>;
+  readonly onError?: (error: DbError, consumer: string) => void;
+}
+interface OutboxRouteResult {
+  readonly consumers: Readonly<Record<string, RelayResult>>;
+  readonly budgetExhausted: boolean;
+}
+interface HistoryFilter extends CursorPageOptions<number> {
+  readonly subject?: string;
+  readonly type?: string;
+  /** Only events after this position. */
+  readonly cursor?: number;
+  readonly limit?: number;
+}
+interface Outbox {
+  /** Writes an event in the current transaction and returns its id. */
+  emit(type: string, payload?: unknown, options?: EmitOptions): AsyncResult<string>;
+  /** Creates the consumer, or changes its types. Returns its cursor position. */
+  register(consumer: string, options?: RegisterOptions): AsyncResult<number>;
+  /** Removes the consumer, so purges stop waiting for it. */
+  unregister(consumer: string): AsyncResult<boolean>;
+  /**
+   * Claims the consumer's next events, sends them to `sink` as CloudEvents and
+   * moves the cursor, until none are left or the budget runs out. A sink that
+   * throws leaves the batch for a later run with backoff, so delivery is at
+   * least once; an event that fails `maxAttempts` times goes to the dead
+   * letters.
+   */
+  relay(consumer: string, sink: EventSink, options?: RelayOptions): Promise<RelayResult>;
+  /**
+   * Like `relay`, but hands `handler` the outbox rows themselves, with
+   * `actorId`, `tenant` and `key`, for consumers inside the app (search
+   * indexing, notifications) that need the actor.
+   */
+  consume(consumer: string, handler: OutboxHandler, options?: RelayOptions): Promise<RelayResult>;
+  /**
+   * A `GET`/`POST` handler for a cron that relays every consumer at once,
+   * within one budget.
+   */
+  relayRoute(options: OutboxRouteOptions): (request: Request) => Promise<Response>;
+  history(filter?: HistoryFilter): AsyncResult<readonly OutboxEvent[]>;
+  /** The consumer's dead letters, newest first (default 100, at most 1000). */
+  deadLetters(consumer: string, limit?: number): AsyncResult<readonly OutboxDeadLetter[]>;
+  /**
+   * Deletes up to `batch` events (default 10,000) older than `olderThan` that
+   * every consumer has passed, and dead letters older than `olderThan`. Call it
+   * again while it returns `batch`.
+   */
+  purge(olderThan?: string, batch?: number, options?: OutboxPurgeOptions): AsyncResult<number>;
+}
+/**
+ * The CloudEvent for an outbox row: the row id as `id` (stable, so receivers
+ * can deduplicate), the payload as `data`, the tenant as `partitionkey` and the
+ * writing module as `producer`. The actor stays out of the context attributes,
+ * which must not carry personal data.
+ */
+declare function outboxCloudEvent(event: OutboxEvent, options: Pick<OutboxOptions, "source" | "typePrefix">): CloudEvent;
+/**
+ * The outbox over a `BlockTransport`: `sqlTransport(postgres)` on a server
+ * connection, where `emit` joins the caller's transaction, or
+ * `rpcTransport(serviceClient)` for apps that reach the database only through
+ * the Data API, where `emit` writes in its own transaction.
+ */
+declare function createOutbox(options: OutboxOptions): Outbox;
+//#endregion
+export { OutboxEvent as a, OutboxPurgeOptions as c, RegisterOptions as d, RelayOptions as f, outboxCloudEvent as h, OutboxDeadLetter as i, OutboxRouteOptions as l, createOutbox as m, HistoryFilter as n, OutboxHandler as o, RelayResult as p, Outbox as r, OutboxOptions as s, EmitOptions as t, OutboxRouteResult as u };

package/dist/overlay/index.d.ts

@@ -1,6 +1,9 @@
-import { c as SpecDiagnostic } from "../format-CNwSjXUU.js";
+import { c as SpecDiagnostic } from "../format-AYHceC2m.js";
 //#region src/overlay/types.d.ts
-/** The Overlay versions `applyOverlay` reads. Patch versions are ignored (Overlay § 4.1). */
+/**
+ * The Overlay versions `applyOverlay` reads. Patch versions are ignored
+ * (Overlay § 4.1).
+ */
 type OverlayVersion = "1.0.0" | "1.1.0" | "1.2.0";
 /** Specification extensions: fields that start with `x-` (Overlay 1.2 § 4.7). */
 type Extensions = {
@@ -17,13 +20,16 @@ type OverlayInfo = {
 /** Fields every action kind shares. */
 interface ActionFields {
   readonly description?: string;
-  /** Merged into objects, concatenated or appended to arrays, or replaces primitives. */
+  /**
+   * Merged into objects, concatenated or appended to arrays, or replaces
+   * primitives.
+   */
   readonly update?: unknown;
   /** When `true`, every selected node is removed. Wins over `update` and `copy`. */
   readonly remove?: boolean;
   /**
-   * Accept a target that selects nothing. Without it, `applyOverlay`
-   * reports `overlay-no-match` as an error.
+   * Accept a target that selects nothing. Without it, `applyOverlay` reports
+   * `overlay-no-match` as an error.
    */
   readonly "x-better-supabase-allow-empty"?: boolean;
 }
@@ -78,10 +84,10 @@ type Overlay12 = OverlayBase & {
 /** An Overlay document of any supported version. */
 type Overlay = Overlay10 | Overlay11 | Overlay12;
 /**
- * The JSONPath engine `applyOverlay` runs targets with. `paths` returns the
- * RFC 9535 normalized paths (`$['paths']['/a'][0]`) of the selected nodes
- * and throws for an invalid query. `loadJsonPath()` returns the
- * `jsonpath-rfc9535` engine; any RFC 9535 implementation fits.
+ * The JSONPath engine `applyOverlay` runs targets with. `paths` returns the RFC
+ * 9535 normalized paths (`$['paths']['/a'][0]`) of the selected nodes and
+ * throws for an invalid query. `loadJsonPath()` returns the `jsonpath-rfc9535`
+ * engine; any RFC 9535 implementation fits.
  */
 interface JsonPathEngine {
   paths(document: unknown, expression: string): readonly string[];
@@ -94,49 +100,56 @@ interface ApplyOverlayOptions {
 interface OverlayResult<T> {
   /** A new document; the input is never changed. */
   readonly document: T;
-  /** Errors, warnings and notes, in action order. Callers decide what fails a build. */
+  /**
+   * Errors, warnings and notes, in action order. Callers decide what fails a
+   * build.
+   */
   readonly diagnostics: readonly SpecDiagnostic[];
 }
 //#endregion
 //#region src/overlay/apply.d.ts
 /**
- * Applies an Overlay 1.0, 1.1 or 1.2 document to `document` and returns a
- * new document. The input is cloned once with `structuredClone` and never
- * changed; each target runs once through `options.jsonpath`.
+ * Applies an Overlay 1.0, 1.1 or 1.2 document to `document` and returns a new
+ * document. The input is cloned once with `structuredClone` and never changed;
+ * each target runs once through `options.jsonpath`.
  *
- * Actions run in order, each on the result of the previous one (Overlay
- * § 4.5.1.1). `update` merges objects, concatenates or appends to arrays and
+ * Actions run in order, each on the result of the previous one (Overlay §
+ * 4.5.1.1). `update` merges objects, concatenates or appends to arrays and
  * replaces primitives; `remove` deletes the selected nodes; `copy` (1.1 and
  * later) uses the value of the single node its query selects. Reusable action
- * references (1.2) are expanded, with a warning when the overlay declares
- * 1.0 or 1.1.
+ * references (1.2) are expanded, with a warning when the overlay declares 1.0
+ * or 1.1.
  *
  * Problems never throw: they are diagnostics, and the failing action is
- * skipped. A target that selects nothing reports `overlay-no-match` as an
- * error unless the action sets `x-better-supabase-allow-empty: true` or the
- * options set `allowEmpty`. The other codes are `overlay-invalid-target`,
- * `overlay-invalid-action`, `overlay-mixed-targets`,
- * `overlay-merge-conflict`, `overlay-copy-source`, `overlay-ref-unresolved`,
- * `overlay-version-feature`, `overlay-version-unsupported` and
- * `overlay-empty-action`.
+ * skipped. A target that selects nothing reports `overlay-no-match` as an error
+ * unless the action sets `x-better-supabase-allow-empty: true` or the options
+ * set `allowEmpty`. The other codes are `overlay-invalid-target`,
+ * `overlay-invalid-action`, `overlay-mixed-targets`, `overlay-merge-conflict`,
+ * `overlay-copy-source`, `overlay-ref-unresolved`, `overlay-version-feature`,
+ * `overlay-version-unsupported` and `overlay-empty-action`.
  *
- * The result keeps the input's type; an overlay that changes the shape
- * needs the caller to narrow it.
+ * The result keeps the input's type; an overlay that changes the shape needs
+ * the caller to narrow it.
  *
  * @example
- * const jsonpath = await loadJsonPath();
- * const { document, diagnostics } = applyOverlay(openapi, overlay, { jsonpath });
+ *   const jsonpath = await loadJsonPath();
+ *   const { document, diagnostics } = applyOverlay(openapi, overlay, {
+ *     jsonpath,
+ *   });
  */
 export declare function applyOverlay<T>(document: T, overlay: Overlay, options: ApplyOverlayOptions): OverlayResult<T>;
 /**
  * Applies overlays in order, each to the result of the previous one, with a
- * single clone of the input. Diagnostic pointers start with the overlay's
- * index (`/1/actions/0`).
+ * single clone of the input. Diagnostic pointers start with the overlay's index
+ * (`/1/actions/0`).
  */
 export declare function applyOverlays<T>(document: T, overlays: readonly Overlay[], options: ApplyOverlayOptions): OverlayResult<T>;
 //#endregion
 //#region src/overlay/define.d.ts
-/** What `defineOverlay` accepts: an Overlay document whose `overlay` field is optional. */
+/**
+ * What `defineOverlay` accepts: an Overlay document whose `overlay` field is
+ * optional.
+ */
 type OverlayInput = {
   readonly overlay?: OverlayVersion;
   readonly info: OverlayInfo;
@@ -165,22 +178,25 @@ type DefinedOverlay<I extends OverlayInput> = I extends {
 /**
  * Defines an Overlay document with checks a schema cannot make. `overlay`
  * defaults to `1.1.0`, or to `1.2.0` when the input uses a 1.2 feature
- * (`components`, `$self` or a reusable action reference), and the return
- * type follows it.
+ * (`components`, `$self` or a reusable action reference), and the return type
+ * follows it.
  *
- * Throws a `TypeError` when there are no actions, when a feature needs a
- * newer version than the one set (`copy` needs 1.1, reusable actions and
- * `$self` need 1.2), when a reference names a missing reusable action, or
- * when `extends` or `$self` contains a fragment.
+ * Throws a `TypeError` when there are no actions, when a feature needs a newer
+ * version than the one set (`copy` needs 1.1, reusable actions and `$self` need
+ * 1.2), when a reference names a missing reusable action, or when `extends` or
+ * `$self` contains a fragment.
  *
  * @example
- * const overlay = defineOverlay({
- *   info: { title: "Public API", version: "1.0.0" },
- *   actions: [
- *     { target: "$.paths['/customers'].get", update: { summary: "List customers" } },
- *     { target: "$.paths[?@['x-internal'] == true]", remove: true },
- *   ],
- * });
+ *   const overlay = defineOverlay({
+ *     info: { title: "Public API", version: "1.0.0" },
+ *     actions: [
+ *       {
+ *         target: "$.paths['/customers'].get",
+ *         update: { summary: "List customers" },
+ *       },
+ *       { target: "$.paths[?@['x-internal'] == true]", remove: true },
+ *     ],
+ *   });
  */
 export declare function defineOverlay<const I extends OverlayInput>(input: I): DefinedOverlay<I>;
 /**
@@ -206,15 +222,15 @@ type OverlayOf<V extends OverlayVersion> = V extends "1.0.0" ? Overlay10 : V ext
 /**
  * Writes the Overlay that turns `base` into `enriched`, so other tools can
  * reproduce what hooks and transforms changed. Targets use stable keys
- * (`$.paths['/customers'].get`); array indexes appear only inside arrays of
- * the same length.
+ * (`$.paths['/customers'].get`); array indexes appear only inside arrays of the
+ * same length.
  *
  * A deleted key becomes a `remove` action; added keys become one `update` on
- * their parent; a changed primitive becomes an `update` on it (1.1 and
- * later) or a `remove` and re-add (1.0). An array that only grew gets its new
- * items appended; any other array change replaces the array. Applying the
- * result to `base` gives a document equal to `enriched`, though replaced
- * keys move to the end of their object.
+ * their parent; a changed primitive becomes an `update` on it (1.1 and later)
+ * or a `remove` and re-add (1.0). An array that only grew gets its new items
+ * appended; any other array change replaces the array. Applying the result to
+ * `base` gives a document equal to `enriched`, though replaced keys move to the
+ * end of their object.
  *
  * Throws a `TypeError` when the roots are not both objects, or when the two
  * documents are equal (an overlay needs at least one action).
@@ -223,10 +239,10 @@ export declare function overlayFromDiff<V extends OverlayVersion = "1.1.0">(base
 //#endregion
 //#region src/overlay/load.d.ts
 /**
- * Loads the optional `jsonpath-rfc9535` peer, an RFC 9535 implementation
- * that passes the JSONPath Compliance Test Suite, for `applyOverlay`.
- * Rejects with an install message when the package is missing. The engine
- * is loaded once per module; `importer` replaces the import in tests.
+ * Loads the optional `jsonpath-rfc9535` peer, an RFC 9535 implementation that
+ * passes the JSONPath Compliance Test Suite, for `applyOverlay`. Rejects with
+ * an install message when the package is missing. The engine is loaded once per
+ * module; `importer` replaces the import in tests.
  */
 export declare function loadJsonPath(importer?: () => Promise<unknown>): Promise<JsonPathEngine>;
 //#endregion