better-supabase 0.8.0 → 0.10.0

package/dist/index-8xwnaWHY.d.ts

@@ -0,0 +1,344 @@
+import { d as AccessBlockConfig, p as AnyBlocksConfig } from "./authorization-CdJRoZgV.js";
+import { i as BlockCategory } from "./define-block-BlHQxDIQ.js";
+import { i as PortName } from "./ports-B53rB7zg.js";
+import { Nn as AppTablesConfig, On as AppTableConfig, dt as PresetScope, ft as PresetTenantName, it as PresetCodeField, nt as Preset, rt as PresetAccess, st as PresetFieldKey, y as BetterSupabaseConfig } from "./codegen-2m4SKVdi.js";
+//#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-types.d.ts
+/** One SQL module in the preset catalog: a key of `blocks` in the config. */
+interface PresetCatalogBlock {
+  readonly name: string;
+  readonly title: string;
+  readonly category: BlockCategory;
+  /** The modules it needs with the default options. */
+  readonly requires: readonly string[];
+  /** What it needs instead under an access model, where that differs. */
+  readonly requiresByAccess?: Partial<Readonly<Record<PresetAccess, readonly string[]>>>;
+  /** The scopes it runs in; unset, every scope. */
+  readonly scopes?: readonly PresetScope[];
+  /** Tenant names that would rename a table or column to a name it already uses. */
+  readonly tenantNameClashes?: readonly PresetTenantName[];
+  /** The logical table `options.extraColumns` adds columns to, when it takes them. */
+  readonly extraColumns?: string;
+  /** Modules it works with when installed; `*` is every module. */
+  readonly integrates: readonly string[];
+  /** The manifest that installs it, a key of `manifests`. */
+  readonly manifest: string;
+}
+/** One block manifest (ADR 0029): what `lib/blocks.ts` wires. */
+interface PresetCatalogManifest {
+  readonly name: string;
+  /** The SQL modules it installs. */
+  readonly sql: readonly string[];
+  readonly category: BlockCategory;
+  /** Its export and subpath, when it has a TypeScript client. */
+  readonly client: {
+    readonly export: string;
+    readonly subpath: string;
+  } | null;
+  readonly consumes: Partial<Readonly<Record<PortName, "optional" | "required">>>;
+  readonly provides: readonly PortName[];
+}
+/**
+ * One item of the `@better-supabase` shadcn registry: glue the app copies
+ * (`npx shadcn add @better-supabase/<name>`), for some blocks, frameworks
+ * and platforms.
+ */
+interface PresetGlueItem {
+  readonly name: string;
+  readonly title: string;
+  /** The SQL modules the item needs. */
+  readonly blocks: readonly string[];
+  readonly frameworks: readonly string[];
+  readonly platforms: readonly ("web" | "native")[];
+  /** Where its files go, as shadcn targets (`@lib/blocks.ts`, `~/app/...`). */
+  readonly targets: readonly string[];
+  /** The named preset a bundle item (`registry:item`) installs the glue of. */
+  readonly preset?: string;
+}
+/** What `scripts/build-catalog.ts` writes to `catalog.generated.ts`. */
+interface PresetCatalog {
+  readonly blocks: readonly PresetCatalogBlock[];
+  readonly manifests: readonly PresetCatalogManifest[];
+  readonly glue: readonly PresetGlueItem[];
+}
+//#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/preset/resolve.d.ts
+/** One block in a resolved preset, with why it is there. */
+interface ResolvedPresetBlock {
+  readonly name: string;
+  readonly title: string;
+  readonly category: BlockCategory;
+  /** Whether the preset names it, rather than another block requiring it. */
+  readonly selected: boolean;
+  /** The blocks in the set that require it. */
+  readonly requiredBy: readonly string[];
+  /** "selected", or "required by comments and tags". */
+  readonly reason: string;
+}
+/** A soft integration between two blocks that are both in the set. */
+interface PresetIntegration {
+  /** The block that works with `to`. */
+  readonly from: string;
+  readonly to: string;
+}
+/** Something in the preset that can't install, and why. */
+interface PresetConflict {
+  readonly block?: string;
+  readonly field?: PresetFieldKey;
+  readonly reason: string;
+}
+/** What `resolvePreset` returns. */
+interface ResolvedPreset {
+  readonly preset: Preset;
+  /** Every block to install, in install order; conflicting blocks are left out. */
+  readonly blocks: readonly ResolvedPresetBlock[];
+  /** The soft integrations active between blocks in the set. */
+  readonly integrations: readonly PresetIntegration[];
+  readonly conflicts: readonly PresetConflict[];
+  /** The manifests that cover `blocks`, for `lib/blocks.ts`. */
+  readonly manifests: readonly PresetCatalogManifest[];
+}
+/** "a", "a and b", "a, b and c". */
+declare function listNames(names: readonly string[]): string;
+/**
+ * Why `name` can't install with the preset's conventions, or undefined.
+ * `/create` disables a block with this reason before it is selected.
+ */
+declare function presetBlockConflict(preset: Pick<Preset, "access" | "scope">, name: string, catalog?: PresetCatalog): string | undefined;
+/**
+ * The full block set for a preset: the selected blocks and what they
+ * require, a reason per block, the soft integrations active between them,
+ * and what can't install. It reads the generated catalog, never the SQL
+ * renderers, so it runs in the browser.
+ */
+declare function resolvePreset(preset: Preset, catalog?: PresetCatalog): ResolvedPreset;
+//#endregion
+//#region src/preset/config.d.ts
+/** A named preset, a code, a `/create?preset=` URL, or a preset object. */
+type PresetInput = string | (Partial<Preset> & {
+  readonly blocks?: readonly string[];
+});
+/** Reads a named preset, a code or a `/create?preset=` URL into a `Preset`. */
+declare function presetOf(input: PresetInput): Preset;
+/** The conventions that map onto config keys; `tenantName` takes any name `sql.naming.tenant` allows. */
+type ConfigConventions = Pick<Preset, "casing" | "idType" | "scope" | "access" | "api"> & {
+  readonly tenantName: string;
+};
+/**
+ * The config keys conventions set without a preset: `casing`, `sql`, and
+ * `blocks.access` when the access model or id type differ from the defaults.
+ */
+declare function conventionConfig(conventions: ConfigConventions): Pick<BetterSupabaseConfig, "casing" | "sql"> & {
+  readonly blocks?: {
+    readonly access: AccessBlockConfig;
+  };
+};
+/** The config keys a resolved preset sets: its blocks and the conventions that differ from the defaults. */
+declare function presetConfig(resolved: ResolvedPreset): Pick<BetterSupabaseConfig, "casing" | "sql" | "integrations"> & {
+  readonly blocks: AnyBlocksConfig;
+};
+/**
+ * `config` with its `preset` expanded: the preset's blocks (and what they
+ * require) and conventions first, then the config's own keys over them, so
+ * explicit config wins. A block in both keeps the preset's settings that the
+ * config's entry leaves unset. Expanding twice gives the same config.
+ */
+declare function expandPreset(config: BetterSupabaseConfig): BetterSupabaseConfig;
+//#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).
+ */
+declare const DESIGN_FORMAT = 5;
+/** 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;
+/**
+ * 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 TypeError {
+  /** 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;
+/**
+ * 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 TypeError 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 TypeError 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 TypeError 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;
+/** 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.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, 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 { presetConfig as A, decodePreset as B, designOf as C, PresetInput as D, ConfigConventions as E, ResolvedPresetBlock as F, PresetCatalog as G, isPresetCode as H, listNames as I, PresetGlueItem as J, PresetCatalogBlock as K, presetBlockConflict as L, PresetConflict as M, PresetIntegration as N, conventionConfig as O, ResolvedPreset as P, resolvePreset as R, designInstallCommand as S, isDesignCode as T, withPresetField as U, encodePreset as V, PRESET_CATALOG as W, PRESET_BLOCKS as Y, decodeDesign as _, presetConfigSource as a, designConfigSource as b, DesignChange as c, diffAppTables as d, diffDesigns as f, MAX_DESIGN_CODE_LENGTH as g, DesignTooLongError as h, presetBlocksSource as i, presetOf as j, expandPreset as k, DesignChangeKind as l, DESIGN_FORMAT as m, glueCommand as n, presetGlue as o, CreateDesign as p, PresetCatalogManifest as q, presetApplyCommand as r, presetInstallCommand as s, PROVIDER_COMMENT as t, DiffOptions as u, designApplyCommand as v, encodeDesign as w, designFormat as x, designConfig as y, DecodedPreset as z };

package/dist/index-BurdFUXr.d.ts

@@ -0,0 +1,131 @@
+import { t as AsyncResult } from "./result-Cj3yWhjH.js";
+import { a as AnyModels, i as AnyFunctions } from "./types-BO8lVTun.js";
+import { l as PublicEnv } from "./index-CxmVzT-3.js";
+import { h as SessionEncoding } from "./resolve-7atr-wWr.js";
+import { t as BetterSupabase } from "./define-DXTC706J.js";
+import { i as KeyboardPort, l as StoragePort, n as DeepLinkPort, r as FilePickerPort, s as PushTokenPort, t as ClientPorts } from "./ports-Dcnuo3HT.js";
+import { r as BetterClient } from "./bind-DkaP_0iS.js";
+import { n as FunctionContract } from "./function-contract-B4c0XuTU.js";
+import { FunctionInvokeOptions, SupabaseClient, SupabaseClientOptions } from "@supabase/supabase-js";
+//#region src/client/functions.d.ts
+/** `supabase.functions.invoke` options, without the body: `invoke` sends the input. */
+type InvokeOptions = Omit<FunctionInvokeOptions, "body">;
+/** Edge Function contracts by function name. */
+type FunctionContracts = Readonly<Record<string, FunctionContract>>;
+/** Anything with supabase-js's `functions` client, e.g. a `SupabaseClient`. */
+interface FunctionsHost {
+  readonly functions: {
+    invoke(name: string, options?: FunctionInvokeOptions): Promise<{
+      data: unknown;
+      error: unknown;
+      response?: Response;
+    }>;
+  };
+}
+interface TypedFunctions<Contracts extends FunctionContracts> {
+  /**
+   * Calls the function with `input` as the JSON body. Problem Details from
+   * the function come back as their `DbError`; a network or relay failure is
+   * a `network` error.
+   */
+  invoke<N extends keyof Contracts & string>(name: N, ...[input, options]: undefined extends Contracts[N]["input"] ? [input?: Contracts[N]["input"], options?: InvokeOptions] : [input: Contracts[N]["input"], options?: InvokeOptions]): AsyncResult<Contracts[N]["output"]>;
+}
+/**
+ * Typed Edge Function calls over supabase-js's `functions` client. The
+ * contracts come from the functions' own code, imported as types:
+ *
+ * ```ts
+ * import type { SendInvite } from "../supabase/functions/send-invite/index.ts";
+ *
+ * const fns = functions<{ "send-invite": SendInvite }>(supabase);
+ * const invite = await fns.invoke("send-invite", { email }).orThrow();
+ * ```
+ */
+declare function functions<Contracts extends FunctionContracts>(host: FunctionsHost): TypedFunctions<Contracts>;
+//#endregion
+//#region src/client/web-ports.d.ts
+/** The part of a `ServiceWorkerRegistration` the push token port uses. */
+interface PushRegistrationLike {
+  readonly pushManager: {
+    getSubscription(): Promise<unknown>;
+    subscribe(options: {
+      readonly userVisibleOnly: boolean;
+      readonly applicationServerKey: Uint8Array<ArrayBuffer>;
+    }): Promise<unknown>;
+  };
+}
+/**
+ * The storage port over `localStorage` (or `sessionStorage`). Reads resolve
+ * with `null` and writes do nothing where storage is missing or blocked.
+ */
+declare function webStorage(kind?: "local" | "session"): StoragePort;
+/** The keyboard port over `keydown` on `window`; `mod` matches Cmd and Ctrl. */
+declare function webKeyboard(): KeyboardPort;
+/** The file picker port over a hidden `<input type="file">`. */
+declare function webFilePicker(): FilePickerPort;
+/** The deep link port over `location`, `popstate` and `hashchange`. */
+declare function webDeepLinks(): DeepLinkPort;
+interface WebPushTokenOptions {
+  /** The VAPID public key, base64url-encoded. */
+  readonly vapidPublicKey: string;
+  /** The service worker that receives the pushes. Default `navigator.serviceWorker.ready`. */
+  readonly registration?: () => Promise<PushRegistrationLike>;
+}
+/**
+ * The push token port over the Push API: the token is the JSON of the
+ * browser's push subscription, which a Web Push sender needs.
+ */
+declare function webPushToken(options: WebPushTokenOptions): PushTokenPort;
+/** The web ports `createClient` uses: storage, the keyboard, the file picker and deep links. */
+declare function webPorts(): ClientPorts;
+//#endregion
+//#region src/client/index.d.ts
+interface ClientOptions {
+  /** URL and publishable key. Not needed when `client` is given. */
+  readonly env?: PublicEnv;
+  /**
+   * Bring your own supabase-js client (custom storage). React Native apps
+   * use `better-supabase/client/native`, which doesn't load `@supabase/ssr`.
+   */
+  readonly client?: SupabaseClient;
+  /**
+   * `cookies` (default) shares the session with the server through
+   * `@supabase/ssr`; `local` keeps it in localStorage for SPAs without a server.
+   */
+  readonly storage?: "cookies" | "local";
+  readonly cookies?: {
+    /**
+     * `tokens-only` keeps the user object out of the cookie (it lives in
+     * `auth.userStorage`, localStorage by default), so cookies stay small.
+     * Use the same value as the server's `encode`. Defaults to
+     * `user-and-tokens`.
+     */
+    readonly encode?: SessionEncoding;
+  };
+  readonly auth?: {
+    /** Where auth-js keeps the user object with `cookies.encode: 'tokens-only'`. */
+    readonly userStorage?: UserStorage;
+  };
+  /**
+   * `staleTime` for every query option in `bs.queries`. Above zero, a
+   * remount or a window focus reuses cached rows instead of refetching.
+   */
+  readonly staleTime?: number;
+  /**
+   * Platform services for the block hooks, over the web defaults
+   * (`webPorts()` and an upload port over Supabase Storage).
+   */
+  readonly ports?: ClientPorts;
+}
+type UserStorage = NonNullable<NonNullable<SupabaseClientOptions<"public">["auth"]>["userStorage"]>;
+/**
+ * The browser side: a supabase-js client, repositories that follow the
+ * session, TanStack Query options and an auth store for UI state.
+ *
+ * ```ts
+ * export const bs = createClient(betterSupabase, { env: { url, publishableKey } });
+ * ```
+ */
+declare function createClient$1<M extends AnyModels, D, F extends AnyFunctions, E, C = unknown, P = unknown>(betterSupabase: BetterSupabase<M, D, F, E, C, P>, options?: ClientOptions): BetterClient<M, F, E, C, P>;
+//#endregion
+export { webDeepLinks as a, webPorts as c, FunctionContracts as d, FunctionsHost as f, functions as h, WebPushTokenOptions as i, webPushToken as l, TypedFunctions as m, createClient$1 as n, webFilePicker as o, InvokeOptions as p, PushRegistrationLike as r, webKeyboard as s, ClientOptions as t, webStorage as u };