better-supabase 0.12.0 → 0.14.0

package/dist/index-BSUX4dlB.d.ts

@@ -0,0 +1,305 @@
+import { Et as AppTableConfig, _t as AppColumnConfig, an as PresetFieldKey, en as Preset, h as PresetCatalog, jt as AppTablesConfig, nn as PresetCodeField, o as presetConfig, u as ResolvedPreset, v as PresetGlueItem, yt as AppColumnType } from "./config-BuOz_O-y.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/preset/blocks.d.ts
+/**
+ * Every block a preset code can select, by bit position. Append-only: a new
+ * block goes at the end, and a removed block becomes `null` (a tombstone) so
+ * the blocks after it keep their bits. A test checks that it lists every SQL
+ * module.
+ */
+declare const PRESET_BLOCKS: readonly (string | null)[];
+//#endregion
+//#region src/preset/catalog.generated.d.ts
+declare const PRESET_CATALOG: PresetCatalog;
+//#endregion
+//#region src/preset/code.d.ts
+/** What `decodePreset` returns. */
+interface DecodedPreset {
+  readonly preset: Preset;
+  /** The code version the code was written with. */
+  readonly version: number;
+  /** Fields the code's version predates, set to their defaults. */
+  readonly derived: readonly PresetFieldKey[];
+}
+/** The fields and blocks a code is read against; tests pass their own. */
+interface PresetLayout {
+  readonly fields: readonly PresetCodeField[];
+  readonly blocks: readonly (string | null)[];
+  readonly version: number;
+}
+/**
+ * The preset as a code: a version character, then base62 of one BigInt that
+ * holds each field's value index and a bit per selected block.
+ */
+declare function encodePreset(preset: Partial<Preset>, layout?: PresetLayout): string;
+/**
+ * The preset with one convention set to `value`, checked against the field: a
+ * value the field doesn't list throws. For a field that takes several values
+ * (`integrations`), `value` switches that one on or off.
+ */
+declare function withPresetField(preset: Preset, key: PresetFieldKey, value: string): Preset;
+/**
+ * Reads a code from `encodePreset`. A code from an older version decodes with
+ * the fields it predates at their defaults, listed in `derived`. A code from a
+ * newer release throws, naming the upgrade.
+ */
+declare function decodePreset(code: string, layout?: PresetLayout): DecodedPreset;
+/**
+ * Whether `value` reads as a preset code rather than a preset name: a version
+ * character (`1` to `9`, then `A` to `Z`) and base62 digits.
+ */
+declare function isPresetCode(value: string): boolean;
+//#endregion
+//#region src/config/app-defaults.d.ts
+/**
+ * Why `value` can't be the default of `column`, or `undefined` when it can: it
+ * must be on the `isAppDefault` allowlist, one of the column's `options`, and
+ * inside its bounds (`min`, `max`, or those of its format).
+ */
+declare function appDefaultError(column: Pick<AppColumnConfig, "type" | "options" | "min" | "max" | "format">, value: string): string | undefined;
+/** Whether `value` is a default `type` accepts; see `AppColumnConfig.default`. */
+declare function isAppDefault(type: AppColumnType, value: string): boolean;
+//#endregion
+//#region src/preset/design.d.ts
+/**
+ * What the `/create` canvas adds to a preset (ADR 0040): tables the app owns,
+ * extra columns on block tables, and where each table sits on the canvas. It
+ * travels in the `&design=` parameter of a `/create` URL.
+ */
+interface CreateDesign {
+  /** `config.appTables`. */
+  readonly appTables?: Readonly<Record<string, AppTableConfig>>;
+  /**
+   * `blocks.<module>.options.extraColumns`: column name to SQL type, per
+   * module.
+   */
+  readonly extraColumns?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+  /** Canvas positions by `schema.table`, as `[x, y]`; the config ignores them. */
+  readonly positions?: Readonly<Record<string, readonly [number, number]>>;
+}
+/**
+ * The newest format of the design JSON, in its `version` key (ADR 0042). A code
+ * carries the lowest format that reads it, and none for format 0, so a design
+ * without format 1 keys still opens in an older release. Format 1 adds column
+ * `format`, `options`, `min`, `max`, `comment` and `identity`, and table `id`,
+ * `unique`, `indexes` and `comment`. Format 2 adds table `subject` (ADR 0043).
+ * Format 3 adds table `rollups` and `lookups` (ADR 0044). Format 4 adds table
+ * `events` (ADR 0048) and subject `versions`. Format 5 adds column `access`
+ * (ADR 0051). Format 6 adds column `encrypted` and table `auditReads` (ADR
+ * 0087).
+ */
+declare const DESIGN_FORMAT = 6;
+/** The lowest design format that reads `design`. */
+declare function designFormat(design: CreateDesign): number;
+/** The longest design code, so a `/create` URL stays under common limits. */
+declare const MAX_DESIGN_CODE_LENGTH = 6e3;
+/** The name Create gives the design file it downloads. */
+declare const DESIGN_FILE = "better-supabase.design.json";
+/**
+ * Why a design, a design code or a design file was rejected. The codes are
+ * stable; the messages may change.
+ */
+type DesignErrorCode = "invalid_design" | "unknown_key" | "unsupported_format" | "too_large" | "unknown_block" | "no_extra_columns" | "block_not_installed" | "invalid_name" | "invalid_type" | "invalid_position" | "invalid_app_table" | "invalid_code" | "too_long" | "invalid_file" | "invalid_preset";
+/** One problem with a design, as `safeParseDesign` reports it. */
+interface DesignParseIssue {
+  readonly code: DesignErrorCode;
+  /**
+   * A JSON Pointer (RFC 6901) to the key at fault in the value that was read,
+   * such as `/appTables/tasks/columns/title`. `""` is the value itself. When
+   * the key is missing, it points to the nearest parent.
+   */
+  readonly path: string;
+  readonly message: string;
+}
+/**
+ * What `parseDesign`, `decodeDesign`, `designFileSource` and `readDesignFile`
+ * throw.
+ */
+declare class DesignParseError extends TypeError implements DesignParseIssue {
+  readonly code: DesignErrorCode;
+  readonly path: string;
+  constructor(code: DesignErrorCode, path: string, message: string, options?: ErrorOptions);
+  /** The issue as a plain, serializable object. */
+  toJSON(): DesignParseIssue;
+}
+/**
+ * What `encodeDesign` throws when a valid design is too long for a URL, so a
+ * caller can offer the config download instead of a fix.
+ */
+declare class DesignTooLongError extends DesignParseError {
+  /** The length the code would have. */
+  readonly length: number;
+  constructor(length: number);
+}
+/** Whether `value` has the shape of a design code. It may still fail to decode. */
+declare function isDesignCode(value: string): boolean;
+/**
+ * Checks a design object, such as one from storage or a request body, and drops
+ * its empty parts. It runs the same checks as `decodeDesign`, without the code.
+ * Throws a `DesignParseError` naming the first problem; `safeParseDesign`
+ * returns it instead.
+ */
+declare function parseDesign(value: unknown): CreateDesign;
+/** What `safeParseDesign` and `safeDesignFileSource` return. */
+type DesignParseResult<T> = ({
+  readonly ok: true;
+} & T) | {
+  readonly ok: false;
+  readonly issues: readonly DesignParseIssue[];
+};
+/**
+ * `parseDesign` without the throw: the design, or the issue that stopped it,
+ * with a stable `code` and a JSON Pointer `path`.
+ */
+declare function safeParseDesign(value: unknown): DesignParseResult<{
+  readonly design: CreateDesign;
+}>;
+/**
+ * A Standard Schema (v1) for a design, so a form library, a router or an AI SDK
+ * tool can validate one with the same rules as `parseDesign`. The output drops
+ * the empty parts; each issue's `path` lists the keys of its JSON Pointer.
+ * `schemas/design-v1.json` is the JSON Schema of its shape.
+ */
+declare const designSchema: StandardSchemaV1<unknown, CreateDesign>;
+/**
+ * The design as a code for the `&design=` parameter: `0`, then its JSON (with
+ * `version` set to `designFormat` when it is above 0) compressed with
+ * deflate-raw, in base64url. An empty design is `""`. Throws a
+ * `DesignParseError` when the design is invalid, and a `DesignTooLongError`
+ * when the code would be longer than `MAX_DESIGN_CODE_LENGTH`.
+ */
+declare function encodeDesign(design: CreateDesign): Promise<string>;
+/** Reads a design code. Throws a `DesignParseError` when it isn't a valid one. */
+declare function decodeDesign(code: string): Promise<CreateDesign>;
+/**
+ * The design in a `/create` URL's `&design=` parameter, or in a bare design
+ * code; `undefined` when `input` has neither.
+ */
+declare function designOf(input: string): Promise<CreateDesign | undefined>;
+/**
+ * The config keys a preset with a design sets: `presetConfig`, with each
+ * block's `options.extraColumns` and `appTables`. Throws a `DesignParseError`
+ * when the design adds columns to a block the preset doesn't install.
+ */
+declare function designConfig(resolved: ResolvedPreset, design: CreateDesign): ReturnType<typeof presetConfig> & {
+  readonly appTables?: AppTablesConfig;
+};
+/**
+ * `better-supabase.config.ts` for a preset with a design. `designCode`, the
+ * design's `encodeDesign`, goes into the `/create` URL in the comment, so the
+ * canvas reopens with its positions.
+ */
+declare function designConfigSource(resolved: ResolvedPreset, design: CreateDesign, designCode?: string): string;
+/**
+ * The command that starts a project from the preset and design: `init` with the
+ * quoted `/create` URL, or `presetInstallCommand` when `designCode` is empty.
+ */
+declare function designInstallCommand(resolved: ResolvedPreset, designCode: string): string;
+/**
+ * A preset and its design as one JSON file, for a design too long for a URL
+ * (ADR 0058). `init --preset` and `apply --preset` read it from a path.
+ */
+interface DesignFile {
+  /** The preset code. */
+  readonly preset: string;
+  /** The design, with `version` set to `designFormat` when it is above 0. */
+  readonly design: CreateDesign & {
+    readonly version?: number;
+  };
+}
+/**
+ * The design file for a preset and design, as JSON text. Throws a
+ * `DesignParseError` when the design is invalid; `safeDesignFileSource` returns
+ * it instead. It has no length limit.
+ */
+declare function designFileSource(resolved: ResolvedPreset, design: CreateDesign): string;
+/**
+ * `designFileSource` without the throw: the file text, or the issue that
+ * stopped it. Each `path` points into the design.
+ */
+declare function safeDesignFileSource(resolved: ResolvedPreset, design: CreateDesign): DesignParseResult<{
+  readonly source: string;
+}>;
+/**
+ * Reads a design file's text. Each `DesignParseError` path points into the
+ * file, so a design problem starts with `/design`. Throws one naming the first
+ * problem: text that isn't JSON, a missing or invalid preset, or an invalid
+ * design.
+ */
+declare function readDesignFile(text: string): {
+  readonly preset: Preset;
+  readonly design: CreateDesign;
+};
+/** The command that applies the preset and design to an existing project. */
+declare function designApplyCommand(resolved: ResolvedPreset, designCode: string): string;
+//#endregion
+//#region src/preset/design-diff.d.ts
+/** What changed between two sets of app tables. */
+type DesignChangeKind = "table.added" | "table.dropped" | "table.renamed" | "table.id" | "table.scope" | "table.unique" | "table.columns" | "table.changed" | "table.computed" | "table.events" | "table.versions" | "column.added" | "column.dropped" | "column.renamed" | "column.type" | "column.required" | "column.unique" | "column.options" | "column.bounds" | "column.format" | "column.reference" | "column.access" | "column.encrypted" | "column.changed";
+interface DesignChange {
+  readonly kind: DesignChangeKind;
+  readonly table: string;
+  readonly column?: string;
+  /** The old name of a renamed table or column, or the old type. */
+  readonly from?: string;
+  /** The new type of a type change. */
+  readonly to?: string;
+  /**
+   * True when existing rows or app code can break: a dropped or renamed table
+   * or column, a type change, a column made required without a default, a new
+   * or tighter constraint (unique, options, bounds, format, a reference
+   * target), tighter column access, encryption turned on or off, a new scope,
+   * or removed generated columns.
+   */
+  readonly breaking: boolean;
+  readonly summary: string;
+  /** The expand-and-contract steps that make a breaking change safe. */
+  readonly steps: readonly string[];
+}
+interface DiffOptions {
+  /**
+   * Leave out tables that `after` doesn't have, as `apply` does: it writes the
+   * tables of a design and keeps the others.
+   */
+  readonly keepMissing?: boolean;
+}
+/**
+ * What changes from `before` to `after`: each added, dropped, renamed or
+ * changed table and column, with the breaking ones marked and their
+ * expand-and-contract steps. A rename is a dropped name and an added one with
+ * the same definition.
+ */
+declare function diffAppTables(before: AppTablesConfig, after: AppTablesConfig, options?: DiffOptions): readonly DesignChange[];
+/** `diffAppTables` over the app tables of two `/create` designs. */
+declare function diffDesigns(before: CreateDesign, after: CreateDesign): readonly DesignChange[];
+//#endregion
+//#region src/preset/render.d.ts
+/** The comment a config with the provider access model gets above `blocks`. */
+declare const PROVIDER_COMMENT: readonly string[];
+/**
+ * `better-supabase.config.ts` for a resolved preset: every block with its
+ * reason, and the conventions that differ from the defaults.
+ */
+declare function presetConfigSource(resolved: ResolvedPreset): string;
+/**
+ * `lib/blocks.ts`: the blocks with a TypeScript client, wired with
+ * `defineBlocks` over the Data API as the caller. Each block's schema (the API
+ * schema when `sql.api` is set) and shared options come from `blockConfig`,
+ * which `better-supabase gen` writes to `blocks.generated.ts`;
+ * `blockConfigImport` is its import path.
+ */
+declare function presetBlocksSource(resolved: ResolvedPreset, blockConfigImport?: string): string;
+/**
+ * The registry glue for the preset's framework and platforms: each item whose
+ * blocks are all installed, except bundles and items that write
+ * `lib/blocks.ts`, which the preset writes itself.
+ */
+declare function presetGlue(resolved: ResolvedPreset, catalog?: PresetCatalog): readonly PresetGlueItem[];
+/** The shadcn command that copies glue items into the app. */
+declare function glueCommand(items: readonly PresetGlueItem[]): string;
+/** The command that starts a project from the preset. */
+declare function presetInstallCommand(resolved: ResolvedPreset): string;
+/** The command that applies the preset to an existing project. */
+declare function presetApplyCommand(resolved: ResolvedPreset): string;
+//#endregion
+export { designOf as A, DecodedPreset as B, decodeDesign as C, designFileSource as D, designConfigSource as E, readDesignFile as F, PRESET_CATALOG as G, encodePreset as H, safeDesignFileSource as I, PRESET_BLOCKS as K, safeParseDesign as L, encodeDesign as M, isDesignCode as N, designFormat as O, parseDesign as P, appDefaultError as R, MAX_DESIGN_CODE_LENGTH as S, designConfig as T, isPresetCode as U, decodePreset as V, withPresetField as W, DesignFile as _, presetConfigSource as a, DesignParseResult as b, DesignChange as c, diffAppTables as d, diffDesigns as f, DesignErrorCode as g, DESIGN_FORMAT as h, presetBlocksSource as i, designSchema as j, designInstallCommand as k, DesignChangeKind as l, DESIGN_FILE as m, glueCommand as n, presetGlue as o, CreateDesign as p, presetApplyCommand as r, presetInstallCommand as s, PROVIDER_COMMENT as t, DiffOptions as u, DesignParseError as v, designApplyCommand as w, DesignTooLongError as x, DesignParseIssue as y, isAppDefault as z };

package/dist/index-BgSuw4CC.d.ts

@@ -0,0 +1,151 @@
+import { n as RouteGuardOptions } from "./refusal-efy5bZMd.js";
+import { t as Validated } from "./shared-CRRfQAKG.js";
+import { AnyEntry, Contributions } from "@supabase/middleware";
+import { IncomingMessage, ServerResponse } from "node:http";
+//#region src/node/http.d.ts
+interface WebRequestOptions {
+  /**
+   * Read the protocol and host from `x-forwarded-proto` and `x-forwarded-host`.
+   * Turn it on behind a proxy you control. Defaults to false.
+   */
+  readonly trustProxy?: boolean;
+  /** Stream the request body into the `Request`. Defaults to true. */
+  readonly body?: boolean;
+}
+/**
+ * A Node `IncomingMessage` as a Web `Request`. Express, Fastify and Koa pass
+ * theirs (`req`, `request.raw`, `ctx.req`). With `body: false` the stream stays
+ * unread, for middleware that runs before a body parser.
+ */
+declare function toWebRequest(req: IncomingMessage, options?: WebRequestOptions): Request;
+/** Writes a Web `Response` to a Node `ServerResponse`, streaming the body. */
+declare function sendWebResponse(res: ServerResponse, response: Response): Promise<void>;
+//#endregion
+//#region src/node/index.d.ts
+interface ToNodeOptions<Req = IncomingMessage> extends Omit<WebRequestOptions, "body"> {
+  /**
+   * The host's env object for `getEnv`; defaults to `process.env` through
+   * `getEnv`.
+   */
+  readonly env?: (req: Req) => unknown;
+}
+/**
+ * A `node:http` request listener running the entries around `handler`.
+ * Response-phase entries see the handler's response, so refreshed cookies and
+ * `withDbStats` totals reach the client.
+ *
+ * ```ts
+ * createServer(
+ *   toNodeHandler([withBetterSupabase(server)], (request, { db }) =>
+ *     db.notes.findMany(),
+ *   ),
+ * );
+ * ```
+ */
+declare function toNodeHandler<const Entries extends readonly AnyEntry[]>(entries: Entries & Validated<Entries>, handler: (request: Request, contributions: Contributions<Entries>) => unknown, options?: ToNodeOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+/** The part of an Express response the middleware writes. */
+interface ExpressResponse extends ServerResponse {
+  /** Express's per-request locals; the contributions land here. */
+  locals: Record<string, unknown>;
+}
+/** Express (or Connect) middleware, typed structurally. */
+type ExpressMiddleware = (req: IncomingMessage, res: ExpressResponse, next: (error?: unknown) => void) => void;
+/** An Express error handler, typed structurally. */
+type ExpressErrorHandler = (error: unknown, req: IncomingMessage, res: ExpressResponse, next: (error?: unknown) => void) => void;
+/**
+ * Express middleware that puts every contribution on `res.locals`
+ * (`res.locals.db`, `res.locals.bs`). Mount it before the routes.
+ *
+ * ```ts
+ * app.use(toExpress([withBetterSupabase(server)]));
+ * app.get("/notes", async (req, res) =>
+ *   res.json(await res.locals.db.notes.findMany().orThrow()),
+ * );
+ * ```
+ */
+declare function toExpress<const Entries extends readonly AnyEntry[]>(entries: Entries & Validated<Entries>, options?: ToNodeOptions): ExpressMiddleware;
+/**
+ * Express route middleware that refuses callers outside `options`: Problem
+ * Details, or a redirect to `signIn` or `mfa`. Runs after `toExpress`.
+ *
+ * ```ts
+ * app.get("/admin", guard({ roles: ["admin"] }), handler);
+ * ```
+ */
+declare function guard(options?: RouteGuardOptions): ExpressMiddleware;
+/**
+ * An Express error handler that answers thrown `DbException`s (from
+ * `.orThrow()`) with Problem Details and passes every other error on. Register
+ * it after the routes.
+ */
+declare function problemErrorHandler(options?: {
+  readonly expose?: boolean;
+}): ExpressErrorHandler;
+/** The part of a Fastify request the hook reads and writes. */
+interface FastifyRequestLike {
+  readonly raw: IncomingMessage;
+  /** The contributions land here: `request.locals.db`. */
+  locals?: Record<string, unknown>;
+}
+/** The part of a Fastify reply the hook writes. */
+interface FastifyReplyLike {
+  readonly raw: ServerResponse;
+  readonly sent: boolean;
+  code(status: number): FastifyReplyLike;
+  header(name: string, value: string | readonly string[]): FastifyReplyLike;
+  getHeader(name: string): number | string | string[] | undefined;
+  send(payload?: unknown): FastifyReplyLike;
+}
+/** A Fastify `onRequest` or `preHandler` hook, typed structurally. */
+type FastifyHook = (request: FastifyRequestLike, reply: FastifyReplyLike) => Promise<void>;
+/**
+ * A Fastify `onRequest` hook that puts every contribution on `request.locals`.
+ * Declare `locals` with `app.decorateRequest('locals', null)`.
+ *
+ * ```ts
+ * app.decorateRequest("locals", null);
+ * app.addHook("onRequest", toFastify([withBetterSupabase(server)]));
+ * app.get("/notes", (request) =>
+ *   request.locals.db.notes.findMany().orThrow(),
+ * );
+ * ```
+ */
+declare function toFastify<const Entries extends readonly AnyEntry[]>(entries: Entries & Validated<Entries>, options?: ToNodeOptions<FastifyRequestLike>): FastifyHook;
+/**
+ * A Fastify `preHandler` hook that refuses callers outside `options`. Runs
+ * after `toFastify`.
+ */
+declare function fastifyGuard(options?: RouteGuardOptions): FastifyHook;
+/** The part of a Koa context the middleware reads and writes. */
+interface KoaContextLike {
+  readonly req: IncomingMessage;
+  readonly res: ServerResponse;
+  /** Koa's per-request state; the contributions land here. */
+  state: Record<string, unknown>;
+  status: number;
+  body: unknown;
+  set(name: string, value: string | readonly string[]): void;
+  get response(): {
+    get(name: string): string | string[] | undefined;
+  };
+}
+/** Koa middleware, typed structurally. */
+type KoaMiddleware = (ctx: KoaContextLike, next: () => Promise<unknown>) => Promise<void>;
+/**
+ * Koa middleware that puts every contribution on `ctx.state`, then awaits the
+ * rest of the chain. Thrown `DbException`s become Problem Details.
+ *
+ * ```ts
+ * app.use(toKoa([withBetterSupabase(server)]));
+ * app.use(async (ctx) => {
+ *   ctx.body = await ctx.state.db.notes.findMany().orThrow();
+ * });
+ * ```
+ */
+declare function toKoa<const Entries extends readonly AnyEntry[]>(entries: Entries & Validated<Entries>, options?: ToNodeOptions<KoaContextLike> & {
+  readonly expose?: boolean;
+}): KoaMiddleware;
+/** Koa middleware that refuses callers outside `options`. Runs after `toKoa`. */
+declare function koaGuard(options?: RouteGuardOptions): KoaMiddleware;
+//#endregion
+export { toNodeHandler as _, FastifyReplyLike as a, toWebRequest as b, KoaMiddleware as c, guard as d, koaGuard as f, toKoa as g, toFastify as h, FastifyHook as i, ToNodeOptions as l, toExpress as m, ExpressMiddleware as n, FastifyRequestLike as o, problemErrorHandler as p, ExpressResponse as r, KoaContextLike as s, ExpressErrorHandler as t, fastifyGuard as u, WebRequestOptions as v, sendWebResponse as y };