better-supabase 0.4.0 → 0.5.0

package/dist/{simplify-Cqvfr9dj.js → simplify-_0oUKqCd.js}

@@ -1,8 +1,8 @@
-import { n as dbError, t as DbException } from "./errors-L0xK41y_.js";
+import { n as isPlainObject } from "./clone-BfgmLU90.js";
+import { n as dbError, t as DbException } from "./errors-DtwXa6b8.js";
 import { t as lookupOf } from "./lookup-BaP5bI27.js";
-import { i as temporalText } from "./temporal-BwshQk0W.js";
-import { t as temporal } from "./temporal-required-CBNHT6ni.js";
 import { i as or, r as not, t as and } from "./types-6cYK9pbJ.js";
+import { r as encodeValue } from "./wire-D2dT86vi.js";
 //#region src/schema/define.ts
 /**
 * Binds generated model types to runtime metadata. Called from the generated
@@ -29,112 +29,6 @@ function relationMeta(meta, table, relation) {
 	};
 }
 //#endregion
-//#region src/ir/codec.ts
-/** Wire form of an app value: Temporal values to ISO text, `bigint` to decimal text. */
-function encodeValue(value) {
-	if (typeof value !== "object" || value === null) return typeof value === "bigint" ? value.toString() : value;
-	const text = temporalText(value);
-	if (text !== void 0) return text;
-	if (Array.isArray(value)) return value.map(encodeValue);
-	return value;
-}
-function decodeScalar(codec, value) {
-	if (value === null || value === void 0) return value;
-	switch (codec) {
-		case "instant": return temporal().Instant.from(String(value));
-		case "plainDateTime": return temporal().PlainDateTime.from(String(value));
-		case "bigint": return BigInt(value);
-		case "string": return String(value);
-		default: return codec;
-	}
-}
-function decode(codec, value) {
-	return Array.isArray(value) ? value.map((item) => decodeScalar(codec, item)) : decodeScalar(codec, value);
-}
-/** Whether decoding `selection` changes anything, so plain reads skip the walk. */
-function needsDecoding(selection) {
-	let needs = decodes.get(selection);
-	if (needs === void 0) {
-		needs = computeNeedsDecoding(selection);
-		decodes.set(selection, needs);
-	}
-	return needs;
-}
-const decodes = /* @__PURE__ */ new WeakMap();
-function computeNeedsDecoding(selection) {
-	return selection.aggregate !== void 0 || selection.columns.some((column) => column.codec !== void 0) || selection.includes.some((include) => include.count !== void 0 || include.aggregate !== void 0 || needsDecoding(include.selection));
-}
-/** PostgREST returns `[{ count }]` for a `(count)` embed; SQL returns the number. */
-function countOf(value) {
-	if (Array.isArray(value)) {
-		const first = value[0];
-		return Number(first?.count ?? 0);
-	}
-	return Number(value ?? 0);
-}
-function measureOf(measure, value) {
-	if (value === void 0 || value === null) return null;
-	return measure.codec ? decodeScalar(measure.codec, value) : value;
-}
-/** Adds `value` under `row[key][name]`, next to what is already there. */
-function fold(row, folded, key, name, value) {
-	let target = folded.get(key);
-	if (!target) {
-		target = { ...row[key] };
-		folded.set(key, target);
-		row[key] = target;
-	}
-	target[name] = value;
-}
-const droppedKeys = /* @__PURE__ */ new WeakMap();
-/** Wire keys that decoding folds into `_count`, `_sum` and the rest. */
-function droppedOf(selection) {
-	let dropped = droppedKeys.get(selection);
-	if (!dropped) {
-		dropped = /* @__PURE__ */ new Set([...selection.aggregate?.measures.map((measure) => measure.key) ?? [], ...selection.includes.filter((include) => include.count !== void 0 || include.aggregate !== void 0).map((include) => include.alias)]);
-		droppedKeys.set(selection, dropped);
-	}
-	return dropped;
-}
-function decodeRow(selection, row) {
-	const dropped = droppedOf(selection);
-	const out = {};
-	for (const key in row) if (!dropped.has(key) && Object.hasOwn(row, key)) out[key] = row[key];
-	const folded = /* @__PURE__ */ new Map();
-	for (const column of selection.columns) if (column.codec && column.alias in out) out[column.alias] = decode(column.codec, out[column.alias]);
-	if (selection.aggregate) {
-		if (selection.aggregate.count) out["_count"] = countOf(out["_count"]);
-		for (const measure of selection.aggregate.measures) {
-			const value = row[measure.key];
-			fold(out, folded, `_${measure.fn}`, measure.alias, measureOf(measure, value));
-		}
-	}
-	for (const include of selection.includes) {
-		const value = row[include.alias];
-		if (include.count !== void 0) {
-			if (!(include.alias in row)) continue;
-			fold(out, folded, "_count", include.count, countOf(value));
-			continue;
-		}
-		if (include.aggregate !== void 0) {
-			if (!(include.alias in row)) continue;
-			const inner = Array.isArray(value) ? value[0] : value;
-			const measures = {};
-			for (const measure of include.selection.aggregate?.measures ?? []) measures[measure.alias] = measureOf(measure, inner?.[measure.key]);
-			fold(out, folded, `_${include.aggregate.fn}`, include.aggregate.name, measures);
-			continue;
-		}
-		if (Array.isArray(value)) out[include.alias] = value.map((item) => decodeRow(include.selection, item));
-		else if (value && typeof value === "object") out[include.alias] = decodeRow(include.selection, value);
-	}
-	return out;
-}
-/** Applies column codecs to returned rows, including embedded relations. */
-function decodeRows(selection, rows, checked = false) {
-	if (!selection || !checked && !needsDecoding(selection)) return rows;
-	return rows.map((row) => decodeRow(selection, row));
-}
-//#endregion
 //#region src/ir/build.ts
 const AGGREGATE_KEYS = {
 	_sum: "sum",
@@ -181,11 +75,6 @@ const FIELD_OPS = /* @__PURE__ */ new Set([
 	"has",
 	"containedBy"
 ]);
-function isPlainObject(value) {
-	if (typeof value !== "object" || value === null) return false;
-	const proto = Object.getPrototypeOf(value);
-	return proto === Object.prototype || proto === null;
-}
 function isOpsObject(value) {
 	if (!isPlainObject(value)) return false;
 	const keys = Object.keys(value);
@@ -699,4 +588,4 @@ function simplifyOrFalse(condition) {
 	};
 }
 //#endregion
-export { invalidRequest as a, needsDecoding as c, escapeLike as i, defineSchema as l, simplifyOrFalse as n, decodeRows as o, builderFor as r, encodeValue as s, simplify as t, tableMeta as u };
+export { invalidRequest as a, escapeLike as i, simplifyOrFalse as n, defineSchema as o, builderFor as r, tableMeta as s, simplify as t };

package/dist/sql/index.d.ts

@@ -1,8 +1,154 @@
-import { s as ClaimsMeta } from "../types-DONv9SHN.js";
-import { B as ReadSet } from "../define-CRS2MRV3.js";
-import { b as ResolvedConfig } from "../config-C1CYcm6o.js";
-import { n as permdockKeys } from "../permdock-sql-DImJULY-.js";
+import { c as ClaimsMeta } from "../types-Dnf_wRDz.js";
+import { B as ReadSet } from "../define-Bp_BZa5h.js";
+import { b as ResolvedConfig, ct as KitsConfig, lt as ResolvedKitModule, ot as KitMode } from "../config-T_ejwyd3.js";
+import { a as permdockKeys, i as permdockKeyStatus, n as PermdockCatalog, r as PermdockKeyStatus, t as PERMDOCK_SCHEMA } from "../permdock-sql-C2Inc6Xc.js";
+//#region src/sql/context.d.ts
+/** The scope id types kit modules render. */
+export declare const KIT_ID_TYPES: readonly ["uuid", "text", "bigint", "integer"];
+type KitIdType = (typeof KIT_ID_TYPES)[number];
+export declare const isKitIdType: (value: string) => value is KitIdType;
+/**
+ * A Postgres type name as one of `KIT_ID_TYPES`: case and spacing are
+ * normalised and aliases such as `int8` resolved. `undefined` for any other
+ * type, so callers refuse it instead of guessing.
+ */
+export declare function kitIdType(value: string): KitIdType | undefined;
+/** One logical table of a module: its default name and logical columns. */
+interface KitTableSpec {
+  /** Default name, in the module's schema. */
+  readonly name: string;
+  /** Logical column to default column name. */
+  readonly columns: Readonly<Record<string, string>>;
+  /**
+   * Logical columns an adopted table may lack (mapped to `null`): the module
+   * leaves out the feature that needs them.
+   */
+  readonly optional?: readonly string[];
+  /** The app may lack the whole table (`kits.<name>.tables.<table>: null`). */
+  readonly optionalTable?: boolean;
+}
+interface KitNames {
+  readonly tables: Readonly<Record<string, KitTableSpec>>;
+  /** The `before_*` and `after_*` hooks the module calls, so `kits.<name>.hooks.functions` is checked. */
+  readonly hooks?: readonly string[];
+  /** The `kits.<name>.options` keys the module reads; any other key is rejected. */
+  readonly options?: readonly string[];
+}
+/** An event a module writes to the outbox, as SQL expressions. */
+interface KitEmit {
+  /** The event type, e.g. `org.created`. */
+  readonly type: string;
+  /** A `jsonb` expression. */
+  readonly payload: string;
+  /** A `text` expression, e.g. `'organizations/' || new_org`. */
+  readonly subject?: string;
+  /** The tenant id expression; it is cast to text. */
+  readonly tenant?: string;
+  /** A `text` idempotency key expression. */
+  readonly key?: string;
+}
+/** A function of a module's contract: what other modules and the TypeScript side call. */
+interface KitContractFunction {
+  readonly name: string;
+  /** Argument types; `{id}` stands for the module's id type. */
+  readonly args: readonly string[];
+  readonly returns: string;
+}
+/** What a module's `build` reads: resolved names for one layout. */
+interface KitContext {
+  readonly module: string;
+  readonly mode: KitMode;
+  readonly config: ResolvedKitModule;
+  /** The quoted schema of the module's functions and managed tables. */
+  readonly schema: string;
+  readonly schemaName: string;
+  readonly idType: KitIdType;
+  readonly claims: ClaimsMeta;
+  readonly kits: KitsConfig;
+  /** `schema.name` of a module function, quoted. */
+  fn(name: string): string;
+  /** `schema.table` of a logical table, quoted. */
+  table(logical: string): string;
+  /** The unquoted schema and name of a logical table. */
+  tableName(logical: string): {
+    readonly schema: string;
+    readonly name: string;
+  };
+  /** A logical column, quoted. Throws when an adopted table lacks it. */
+  col(table: string, column: string): string;
+  /** Whether a logical column exists (adopted tables can map it to `null`). */
+  has(table: string, column: string): boolean;
+  /** Whether an optional logical table exists (it can be mapped to `null`). */
+  hasTable(table: string): boolean;
+  /** Whether the module owns `table` (managed mode). */
+  readonly manages: boolean;
+  /** The permission key for a kit action, as a SQL literal. */
+  permission(action: string, fallback: string): string;
+  /** The permission key for a kit action. */
+  permissionKey(action: string, fallback: string): string;
+  /** A trigger name with the module's prefix, quoted. */
+  trigger(name: string): string;
+  /** Whether `module` is installed alongside this one. */
+  installed(module: string): boolean;
+  /** The context of another module in the same layout. */
+  of(module: string): KitContext;
+  /** A string module option (`kits.<name>.options`). */
+  text(name: string, fallback: string): string;
+  number(name: string, fallback: number): number;
+  flag(name: string, fallback: boolean): boolean;
+  /** A module option that is a list of strings. */
+  list(name: string, fallback: readonly string[]): readonly string[];
+  /** A declared module option as configured, for object-shaped options. */
+  option(name: string): unknown;
+  /**
+   * PL/pgSQL that calls the app's hook function when it exists, with
+   * `[type, expression]` arguments: `if to_regprocedure(...) is not null
+   * then perform ...; end if;`.
+   */
+  hook(name: string, args: readonly (readonly [string, string])[]): string;
+  /** The app function a hook calls, quoted, for hooks that return a value. */
+  hookTarget(name: string): string;
+  /**
+   * PL/pgSQL that writes the event to the outbox (`emit_event`) when the
+   * `outbox` module is installed and `kits.<name>.events` isn't false;
+   * otherwise an empty string.
+   */
+  emit(event: KitEmit): string;
+}
+/** The contract's argument list with `{id}` resolved, as Postgres prints it. */
+export declare function contractSignature(fn: KitContractFunction, idType: string): string;
+//#endregion
 //#region src/sql/kit.d.ts
+/** The step from one module version to the next, for `sql upgrade`. */
+interface KitUpgrade {
+  /** The installed version this step upgrades from. */
+  readonly from: number;
+  readonly description: string;
+  /** SQL run before the module's current file, e.g. renames and backfills. */
+  readonly sql: (ctx: KitContext) => string;
+}
+/**
+ * A renamed kit symbol. It keeps a compatibility wrapper for at least one
+ * minor release, then is removed; doctor reports uses of both (BS309), and
+ * the name stays reserved.
+ */
+interface KitDeprecation {
+  readonly kind: "function" | "claim" | "table" | "column";
+  /** The old name: `schema.function`, a claim name, `schema.table` or `table.column`. */
+  readonly symbol: string;
+  /** What to use instead. */
+  readonly use: string;
+  /** The package version that deprecated it. */
+  readonly since: string;
+  /** The package version that removed it; until then `wrapper` is written. */
+  readonly removed?: string;
+  /**
+   * The compatibility wrapper the module file keeps, e.g. a function with the
+   * old name that calls the new one and a `comment on function ... is
+   * 'deprecated: use X'`.
+   */
+  readonly wrapper?: (ctx: KitContext) => string;
+}
 /**
  * SQL kit modules for `better-supabase sql add`. Every module is idempotent
  * (`create or replace`, `if not exists`), so re-running it upgrades in place.
@@ -15,19 +161,42 @@ interface SqlModule {
   readonly requires: readonly string[];
   /** What it needs instead when the layout has `permdock`. */
   readonly permdockRequires?: readonly string[];
+  /** What it needs for this layout, e.g. per `kits.access.model`; overrides both. */
+  readonly dependencies?: (layout: KitLayout) => readonly string[];
   /** `schema` files go with your schemas; `test` files go to `supabase/tests`. */
   readonly target: "schema" | "test";
   /** The module with the default claim names. */
   readonly sql: string;
   /** The module for configured claim names (`config.claims`), when it reads claims. */
   readonly render?: (claims: ClaimsMeta, layout: KitLayout) => string;
+  /** Bumped when installed databases need an upgrade step. Defaults to 1. */
+  readonly version?: number;
+  /** The modes `kits.<name>.mode` accepts. Defaults to `managed` only. */
+  readonly modes?: readonly KitMode[];
+  /** The logical tables and columns `kits.<name>.tables` and `columns` map. */
+  readonly names?: KitNames;
+  /** The functions other modules and the TypeScript side call. */
+  readonly contract?: (ctx: KitContext) => readonly KitContractFunction[];
+  /** Renders the module for a layout; takes precedence over `render`. */
+  readonly build?: (ctx: KitContext, layout: KitLayout) => string;
+  readonly upgrades?: readonly KitUpgrade[];
+  readonly deprecated?: readonly KitDeprecation[];
+  /**
+   * Rows, role settings and calls that a schema diff doesn't capture. They
+   * go to `better-supabase-data/` next to the schema folder and a migration
+   * (`sql data`) instead of the schema file.
+   */
+  readonly data?: (ctx: KitContext, layout: KitLayout) => string;
 }
+export declare const moduleVersion: (module: SqlModule) => number;
 /** New modules go at the end: the position is part of the file name. */
 export declare const SQL_MODULES: Readonly<Record<string, SqlModule>>;
 /** The modules to install for `names`, dependencies first. Throws on an unknown name. */
 export declare function resolveModules(names: readonly string[], layout?: KitLayout): SqlModule[];
 interface KitFile {
   readonly module: string;
+  /** `schema` and `test` files are diffed; `data` files go in a migration too. */
+  readonly kind: "schema" | "data" | "test";
   readonly path: string;
   readonly contents: string;
 }
@@ -42,7 +211,9 @@ interface KitLayout {
   readonly version?: string;
   /** `config.realtime.tables`: registered at the end of the `realtime-tables` module. */
   readonly realtimeTables?: readonly string[];
-  /** Tenant column passed to `track_realtime`; tables without it broadcast unscoped. */
+  /** `config.realtime.global`: tables registered with `tenant_column => null`. */
+  readonly realtimeGlobal?: readonly string[];
+  /** Tenant column passed to `track_realtime` for the other tables. */
   readonly tenantColumn?: string;
   /** Check constraints for the `jsonb-schemas` module. */
   readonly jsonSchemas?: readonly JsonSchemaCheck[];
@@ -61,6 +232,8 @@ interface KitLayout {
   readonly claims?: ClaimsMeta;
   /** PermDock's helpers and membership sources, from its manifest: `entitlements` reads them instead of `tenant`. */
   readonly permdock?: KitPermdock;
+  /** `config.kits`: modes, names and permission keys per module. */
+  readonly kits?: KitsConfig;
 }
 /** One PermDock membership source, from the manifest's `memberships`. */
 interface KitMembershipSource {
@@ -80,6 +253,8 @@ interface KitPermdock {
   readonly schema: string;
   /** The PermDock scope tenants map to, e.g. `organization`. */
   readonly scope: string;
+  /** The scope's id type, from the manifest's `rls.scopes[].type`. */
+  readonly idType: KitIdType;
   readonly memberships: readonly KitMembershipSource[];
 }
 /** An embedding column `db.$search` can query. */
@@ -91,10 +266,10 @@ interface VectorSearchTable {
 }
 /** The table holding each tenant's Stripe customer id. */
 interface EntitlementsSource {
-  /** `table` or `schema.table`. */
-  readonly table: string;
+  /** `table` or `schema.table`; unset uses the `organizations` module's. */
+  readonly table?: string;
   /** Column with the Stripe customer id (`cus_...`). */
-  readonly column: string;
+  readonly column?: string;
   /** Column with the tenant id. */
   readonly key: string;
 }
@@ -114,13 +289,75 @@ interface JsonSchemaCheck {
 }
 /** Whether an installed file matches, ignoring the version stamped in its header. */
 export declare function sameKitFile(current: string | undefined, expected: string): boolean;
-/** The files `sql add` writes for these modules. */
+/** The installed version of a kit file, from its `@bs-kit` line. */
+export declare function kitFileVersion(contents: string): {
+  readonly module: string;
+  readonly version: number;
+} | undefined;
+/** A module's SQL for `layout`, without header; `undefined` in custom mode. */
+export declare function moduleBody(name: string, layout?: KitLayout): string | undefined;
+/**
+ * The files `sql add` writes for these modules. Modules in `custom` mode
+ * write nothing: the app implements their contract. A schema module's rows,
+ * role settings and other statements a schema diff can't capture go to a
+ * second file in `better-supabase-data/` (`kind: 'data'`), which
+ * `sql data` writes into a migration.
+ */
 export declare function renderKit(names: readonly string[], layout?: KitLayout): KitFile[];
+/** An installed module, from its file's `@bs-kit` line or `kit_modules`. */
+interface InstalledKitModule {
+  readonly module: string;
+  readonly version: number;
+}
+/** What `sql upgrade` runs for one module behind the current version. */
+interface KitUpgradePlan {
+  readonly module: string;
+  readonly from: number;
+  readonly to: number;
+  readonly steps: readonly {
+    readonly from: number;
+    readonly description: string;
+    readonly sql: string;
+  }[];
+}
+/**
+ * The upgrade steps for modules installed at an older version. A version
+ * without a step needs none: the module file upgrades in place. Modules in
+ * custom mode belong to the app and are skipped.
+ */
+export declare function upgradePlan(installed: readonly InstalledKitModule[], layout?: KitLayout, modules?: Readonly<Record<string, SqlModule>>): KitUpgradePlan[];
+/** Every deprecated or removed kit symbol, with its module. */
+export declare function kitDeprecations(modules?: Readonly<Record<string, SqlModule>>): readonly (KitDeprecation & {
+  readonly module: string;
+})[];
+/** The contract functions of the modules in `custom` mode, for doctor. */
+export declare function customContracts(names: readonly string[], layout?: KitLayout): {
+  readonly module: string;
+  readonly schema: string;
+  readonly idType: KitIdType;
+  readonly functions: readonly KitContractFunction[];
+}[];
 //#endregion
 //#region src/sql/layout.d.ts
 /** Where and how `sql add` writes kit files for this config. */
 export declare function kitLayout(config: ResolvedConfig, testsDir?: string, readSets?: KitLayout["readSets"], permdock?: KitPermdock): KitLayout;
 //#endregion
+//#region src/sql/migration-options.d.ts
+/** A migration-only option a config sets. */
+interface MigrationOptionUse {
+  readonly module: string;
+  readonly option: string;
+  readonly value: unknown;
+  readonly adopted: boolean;
+  /** `kits.<module>.options.<option> ... It <effect>.` */
+  readonly message: string;
+}
+/**
+ * The migration-only options `kits` sets to a value other than the managed
+ * default. They are accepted in `adopt` mode only; doctor warns about each.
+ */
+export declare function migrationOptionUses(kits?: KitsConfig): MigrationOptionUse[];
+//#endregion
 //#region src/sql/read-sets.d.ts
 /** A read set compiled to the SQL of its function. */
 interface CompiledReadSet {
@@ -136,4 +373,4 @@ export declare function compileReadSet(set: ReadSet): Promise<CompiledReadSet>;
 /** Compiles every set, sorted by name. Throws on a duplicate name. */
 export declare function compileReadSets(sets: readonly ReadSet[]): Promise<CompiledReadSet[]>;
 //#endregion
-export { type CompiledReadSet, type KitFile, type KitLayout, type KitPermdock, type SqlModule, permdockKeys };
+export { type CompiledReadSet, type InstalledKitModule, type KitContext, type KitContractFunction, type KitDeprecation, type KitFile, type KitIdType, type KitLayout, type KitNames, type KitPermdock, type KitTableSpec, type KitUpgrade, type KitUpgradePlan, type MigrationOptionUse, PERMDOCK_SCHEMA, type PermdockCatalog, type PermdockKeyStatus, type SqlModule, permdockKeyStatus, permdockKeys };