better-supabase 0.7.0 → 0.8.0

package/dist/overlay/index.d.ts

@@ -0,0 +1,233 @@
+import { c as SpecDiagnostic } from "../format-DTXdu8ya.js";
+//#region src/overlay/types.d.ts
+/** 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 = {
+  readonly [key: `x-${string}`]: unknown;
+};
+type OverlayInfo = {
+  /** The purpose of the overlay. */
+  readonly title: string;
+  /** The overlay's own version, not the Overlay Specification version. */
+  readonly version: string;
+  /** CommonMark (1.1 and later). */
+  readonly description?: string;
+} & Extensions;
+/** Fields every action kind shares. */
+interface ActionFields {
+  readonly description?: string;
+  /** 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.
+   */
+  readonly "x-better-supabase-allow-empty"?: boolean;
+}
+/** An Overlay 1.0 Action Object. */
+type OverlayAction10 = ActionFields & {
+  /** An RFC 9535 JSONPath query. */
+  readonly target: string;
+} & Extensions;
+/** An Overlay 1.1 and 1.2 Action Object, which adds `copy`. */
+type OverlayAction = OverlayAction10 & {
+  /** A JSONPath query that selects one node whose value is used like `update`. */
+  readonly copy?: string;
+};
+/** The fields of a reusable action (1.2): an Action Object without `target`. */
+type ReusableActionFields = Omit<OverlayAction, "target">;
+/** A Reusable Action Object (Overlay 1.2 § 4.5.5). */
+type ReusableAction = {
+  readonly description?: string;
+  readonly fields?: ReusableActionFields;
+} & Extensions;
+/**
+ * A Reusable Action Reference Object (Overlay 1.2 § 4.5.6). Its own action
+ * fields override the referenced ones for this use.
+ */
+type ReusableActionReference = Partial<Omit<OverlayAction, "target">> & {
+  /** `#/components/actions/<name>`, with the name escaped per RFC 6901. */
+  readonly $ref: `#/components/actions/${string}`;
+  readonly target: string;
+};
+interface OverlayBase {
+  readonly info: OverlayInfo;
+  /** URI of the target document, without a fragment. */
+  readonly extends?: string;
+}
+type Overlay10 = OverlayBase & {
+  readonly overlay: "1.0.0";
+  readonly actions: readonly OverlayAction10[];
+} & Extensions;
+type Overlay11 = OverlayBase & {
+  readonly overlay: "1.1.0";
+  readonly actions: readonly OverlayAction[];
+} & Extensions;
+type Overlay12 = OverlayBase & {
+  readonly overlay: "1.2.0";
+  /** URI of this overlay and its base URI, without a fragment. */
+  readonly $self?: string;
+  readonly actions: readonly (OverlayAction | ReusableActionReference)[];
+  readonly components?: {
+    readonly actions?: Readonly<Record<string, ReusableAction>>;
+  } & Extensions;
+} & Extensions;
+/** 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.
+ */
+interface JsonPathEngine {
+  paths(document: unknown, expression: string): readonly string[];
+}
+interface ApplyOverlayOptions {
+  readonly jsonpath: JsonPathEngine;
+  /** Accept targets that select nothing in every action. Default `false`. */
+  readonly allowEmpty?: boolean;
+}
+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. */
+  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`.
+ *
+ * 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.
+ *
+ * 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`.
+ *
+ * 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 });
+ */
+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`).
+ */
+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. */
+type OverlayInput = {
+  readonly overlay?: OverlayVersion;
+  readonly info: OverlayInfo;
+  readonly extends?: string;
+  readonly $self?: string;
+  readonly actions: readonly (OverlayAction | ReusableActionReference)[];
+  readonly components?: {
+    readonly actions?: Readonly<Record<string, ReusableAction>>;
+  } & Extensions;
+} & Extensions;
+type UsesOverlay12<I extends OverlayInput> = I extends {
+  readonly components: object;
+} ? true : I extends {
+  readonly $self: string;
+} ? true : [Extract<I["actions"][number], {
+  readonly $ref: string;
+}>] extends [never] ? false : true;
+/** The document type `defineOverlay` returns for an input. */
+type DefinedOverlay<I extends OverlayInput> = I extends {
+  readonly overlay: "1.0.0";
+} ? Overlay10 : I extends {
+  readonly overlay: "1.1.0";
+} ? Overlay11 : I extends {
+  readonly overlay: "1.2.0";
+} ? Overlay12 : UsesOverlay12<I> extends true ? Overlay12 : Overlay11;
+/**
+ * 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.
+ *
+ * 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 },
+ *   ],
+ * });
+ */
+export declare function defineOverlay<const I extends OverlayInput>(input: I): DefinedOverlay<I>;
+/**
+ * Turns an overlay into an equivalent Overlay 1.1 document for tools that do
+ * not read 1.2: every reusable action reference becomes a plain action, and
+ * `$self` and `components` are dropped. A reference that does not resolve is
+ * left out and reported as `overlay-ref-unresolved`.
+ */
+export declare function expandReusableActions(overlay: Overlay): {
+  readonly overlay: Overlay11;
+  readonly diagnostics: readonly SpecDiagnostic[];
+};
+//#endregion
+//#region src/overlay/diff.d.ts
+interface OverlayFromDiffOptions<V extends OverlayVersion> {
+  /** The Overlay version to write. Default `1.1.0`. */
+  readonly version?: V;
+  /** Default `{ title: "better-supabase changes", version: "1.0.0" }`. */
+  readonly info?: OverlayInfo;
+  readonly extends?: string;
+}
+type OverlayOf<V extends OverlayVersion> = V extends "1.0.0" ? Overlay10 : V extends "1.2.0" ? Overlay12 : Overlay11;
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * Throws a `TypeError` when the roots are not both objects, or when the two
+ * documents are equal (an overlay needs at least one action).
+ */
+export declare function overlayFromDiff<V extends OverlayVersion = "1.1.0">(base: unknown, enriched: unknown, options?: OverlayFromDiffOptions<V>): OverlayOf<V>;
+//#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.
+ */
+export declare function loadJsonPath(importer?: () => Promise<unknown>): Promise<JsonPathEngine>;
+//#endregion
+export type { ApplyOverlayOptions, DefinedOverlay, Extensions, JsonPathEngine, Overlay, Overlay10, Overlay11, Overlay12, OverlayAction, OverlayAction10, OverlayFromDiffOptions, OverlayInfo, OverlayInput, OverlayResult, OverlayVersion, ReusableAction, ReusableActionFields, ReusableActionReference, SpecDiagnostic };