better-supabase 0.4.0 → 0.5.1

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-Bv7gvfzC.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,10 @@ interface KitLayout {
   readonly claims?: ClaimsMeta;
   /** PermDock's helpers and membership sources, from its manifest: `entitlements` reads them instead of `tenant`. */
   readonly permdock?: KitPermdock;
+  /** PermDock's permission helpers for the `access` module's `permdock` model, from its manifest. */
+  readonly accessPermdock?: KitAccessPermdock;
+  /** `config.kits`: modes, names and permission keys per module. */
+  readonly kits?: KitsConfig;
 }
 /** One PermDock membership source, from the manifest's `memberships`. */
 interface KitMembershipSource {
@@ -80,8 +255,19 @@ 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[];
 }
+/** Where the `permdock` access model finds `permitted_<scope>_ids` and `permdock_has`. */
+interface KitAccessPermdock {
+  /** PermDock's `rls.schema`. */
+  readonly schema: string;
+  /** The PermDock scope tenants are: the manifest's root scope unless set. */
+  readonly scope: string;
+  /** The scope's id type, from the manifest's `rls.scopes[].type`. */
+  readonly idType: KitIdType;
+}
 /** An embedding column `db.$search` can query. */
 interface VectorSearchTable {
   /** `table` or `schema.table`. */
@@ -91,10 +277,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,12 +300,98 @@ 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 schema or test file `renderKit` writes for each of `names` and the
+ * modules they pull in, without rendering: modules in custom mode have none.
+ */
+export declare function kitFilePaths(names: readonly string[], layout?: KitLayout): ReadonlyMap<string, string>;
+/** A permission key a kit module checks, from `kitPermissionKeys`. */
+interface KitPermissionKey {
+  readonly module: string;
+  /** The action in `kits.<module>.permissions` that overrides the key. */
+  readonly action: string;
+  readonly key: string;
+  /**
+   * `tenant` for keys checked in a tenant (`member_can`, `can`,
+   * `tenant_ids_with`), `platform` for `is_platform` and `platform_can`.
+   */
+  readonly scope: "tenant" | "platform";
+}
+/**
+ * Every permission key the modules `names` install (with what they pull
+ * in) check, after `kits.<module>.permissions` overrides. Modules in custom
+ * mode are skipped, and so is `invitations.invitePlatform` without platform
+ * roles. PermDock's doctor runs the same catalog check from its side.
+ */
+export declare function kitPermissionKeys(kits: KitsConfig, names: readonly string[]): KitPermissionKey[];
+/**
+ * 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;
+export declare function kitLayout(config: ResolvedConfig, testsDir?: string, readSets?: KitLayout["readSets"], permdock?: KitPermdock, accessPermdock?: KitAccessPermdock): 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. */
@@ -136,4 +408,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 KitAccessPermdock, type KitContext, type KitContractFunction, type KitDeprecation, type KitFile, type KitIdType, type KitLayout, type KitNames, type KitPermdock, type KitPermissionKey, type KitTableSpec, type KitUpgrade, type KitUpgradePlan, type MigrationOptionUse, PERMDOCK_SCHEMA, type PermdockCatalog, type PermdockKeyStatus, type SqlModule, permdockKeyStatus, permdockKeys };