better-supabase 0.8.0 → 0.9.0

package/dist/preset/index.d.ts

@@ -0,0 +1,352 @@
+import { d as AccessBlockConfig, p as AnyBlocksConfig } from "../authorization-DpRfs6Wx.js";
+import { i as BlockCategory } from "../define-block-CLZMEFeK.js";
+import { i as PortName } from "../ports-Ca63W4cW.js";
+import { $ as PresetAccess, B as PRESETS, G as isPresetName, H as PRESET_NAMES, J as PRESET_FIELDS, K as namedPreset, Q as Preset, Sn as AppTablesConfig, U as PresetGroup, V as PRESET_GROUPS, W as PresetName, X as PRESET_TENANT_NAMES, Y as PRESET_FRAMEWORKS, Z as PRESET_VERSION, at as PresetFramework, bn as AppTableConfig, ct as PresetTenantName, dt as presetField, et as PresetCodeField, fn as AppColumnFormat, ft as presetValueLabel, it as PresetFieldValue, lt as PresetValueInfo, nt as PresetField, ot as PresetPlatforms, pn as AppColumnType, q as DEFAULT_CONVENTIONS, rt as PresetFieldKey, sn as APP_COLUMN_FORMATS, st as PresetScope, tt as PresetConventions, ut as integrationsForFramework, y as BetterSupabaseConfig, z as NamedPreset } from "../codegen-DeoSt1mi.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.
+ */
+export 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
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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". */
+export 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.
+ */
+export 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.
+ */
+export 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`. */
+export 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.
+ */
+export 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. */
+export 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.
+ */
+export declare function expandPreset(config: BetterSupabaseConfig): BetterSupabaseConfig;
+//#endregion
+//#region src/config/app-tables.d.ts
+/**
+ * The columns every app table gets, which `columns` may not name:
+ * `id`, `created_at`, `updated_at`, `user_id` and the tenant column
+ * (`organization_id`, or `<sql.naming.tenant>_id`), whatever the table's
+ * scope, so changing the scope never collides with a column.
+ */
+export declare function appReservedColumns(tenant?: string): readonly string[];
+/** Whether `value` is a default `type` accepts; see `AppColumnConfig.default`. */
+export 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).
+ */
+export declare const DESIGN_FORMAT = 3;
+/** The lowest design format that reads `design`. */
+export declare function designFormat(design: CreateDesign): number;
+/** The longest design code, so a `/create` URL stays under common limits. */
+export 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.
+ */
+export 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. */
+export 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`.
+ */
+export declare function encodeDesign(design: CreateDesign): Promise<string>;
+/** Reads a design code. Throws a TypeError when it isn't a valid one. */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export declare function designInstallCommand(resolved: ResolvedPreset, designCode: string): string;
+/** The command that applies the preset and design to an existing project. */
+export 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.changed" | "table.computed" | "column.added" | "column.dropped" | "column.renamed" | "column.type" | "column.required" | "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, or a column made required without a
+   * default.
+   */
+  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.
+ */
+export declare function diffAppTables(before: AppTablesConfig, after: AppTablesConfig, options?: DiffOptions): readonly DesignChange[];
+/** `diffAppTables` over the app tables of two `/create` designs. */
+export 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`. */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export declare function presetGlue(resolved: ResolvedPreset, catalog?: PresetCatalog): readonly PresetGlueItem[];
+/** The shadcn command that copies glue items into the app. */
+export declare function glueCommand(items: readonly PresetGlueItem[]): string;
+/** The command that starts a project from the preset. */
+export declare function presetInstallCommand(resolved: ResolvedPreset): string;
+/** The command that applies the preset to an existing project. */
+export declare function presetApplyCommand(resolved: ResolvedPreset): string;
+//#endregion
+export { APP_COLUMN_FORMATS, type AppColumnFormat, type ConfigConventions, type CreateDesign, DEFAULT_CONVENTIONS, type DecodedPreset, type DesignChange, type DesignChangeKind, type DiffOptions, type NamedPreset, PRESETS, PRESET_FIELDS, PRESET_FRAMEWORKS, PRESET_GROUPS, PRESET_NAMES, PRESET_TENANT_NAMES, PRESET_VERSION, type Preset, type PresetAccess, type PresetCatalog, type PresetCatalogBlock, type PresetCatalogManifest, type PresetConflict, type PresetConventions, type PresetField, type PresetFieldKey, type PresetFieldValue, type PresetFramework, type PresetGlueItem, type PresetGroup, type PresetInput, type PresetIntegration, type PresetName, type PresetPlatforms, type PresetScope, type PresetValueInfo, type ResolvedPreset, type ResolvedPresetBlock, integrationsForFramework, isPresetName, namedPreset, presetField, presetValueLabel };