@rebasepro/server-postgres 0.12.1-canary.gcfa333c → 0.12.1-canary.gddbd489

package/dist/policy-CeA1JcxP.js

@@ -0,0 +1,105 @@
+import { createRequire as __createRequire } from "module";
+import "process";
+__createRequire(import.meta.url);
+//#region ../types/src/types/policy.ts
+/**
+* The id a request without a logged-in user reports as `auth.uid()`.
+*
+* A user-context request always sets `app.uid`: blank would read back as
+* `NULL`, and `NULL` is how the trusted server context is recognised, so an
+* anonymous visitor would be promoted to server privileges. The driver
+* therefore substitutes this sentinel at the single chokepoint where the GUC
+* is set.
+*
+* The consequence for policy authors is that **`auth.uid() IS NOT NULL` is a
+* tautology on the user path** — it is true for anonymous visitors too. Use
+* {@link policy.authenticated} to mean "signed in", and
+* {@link policy.serverContext} to mean "the trusted server context". Do not
+* hand-write the comparison: see {@link ANONYMOUS_USER_IDS} for why one
+* literal is not enough.
+*
+* @group Models
+*/
+var ANONYMOUS_USER_ID = "anonymous";
+/**
+* Every uid that has ever meant "nobody is signed in" — newest first.
+*
+* There are two because there were two. The types, the policy compiler, the
+* JavaScript evaluator and the linter were all built on
+* {@link ANONYMOUS_USER_ID}, while the request path scoped unauthenticated
+* callers as `'anon'` — so `policy.authenticated()`, which compiled to
+* `auth.uid() <> 'anonymous'`, was *true* for an anonymous visitor. The
+* sanctioned way to write "signed in" granted to everyone, and the linter
+* flagged the spelling that actually worked as a foreign convention.
+*
+* The request path now reports {@link ANONYMOUS_USER_ID}. `'anon'` stays here
+* because policies outlive the server that generated them: a database still
+* holding policies from before the fix, or a project whose server has not been
+* upgraded yet, must not become a grant in either direction. Compile against
+* this list, not against a single literal.
+*
+* No real user id is ever one of these, so a match is always "not signed in".
+*
+* @group Models
+*/
+var ANONYMOUS_USER_IDS = [ANONYMOUS_USER_ID, "anon"];
+/** @group Models */
+var policy = {
+	true: () => ({ kind: "true" }),
+	false: () => ({ kind: "false" }),
+	and: (...operands) => ({
+		kind: "and",
+		operands
+	}),
+	or: (...operands) => ({
+		kind: "or",
+		operands
+	}),
+	not: (operand) => ({
+		kind: "not",
+		operand
+	}),
+	compare: (left, op, right) => ({
+		kind: "compare",
+		op,
+		left,
+		right
+	}),
+	rolesOverlap: (roles) => ({
+		kind: "rolesOverlap",
+		roles
+	}),
+	rolesContain: (roles) => ({
+		kind: "rolesContain",
+		roles
+	}),
+	authenticated: () => ({ kind: "authenticated" }),
+	serverContext: () => ({ kind: "serverContext" }),
+	existsIn: (args) => ({
+		kind: "existsIn",
+		collection: args.collection,
+		where: args.where
+	}),
+	raw: (sql) => ({
+		kind: "raw",
+		sql
+	}),
+	field: (name) => ({
+		kind: "field",
+		name
+	}),
+	outerField: (name) => ({
+		kind: "outerField",
+		name
+	}),
+	literal: (value) => ({
+		kind: "literal",
+		value
+	}),
+	authUid: () => ({ kind: "authUid" }),
+	authRoles: () => ({ kind: "authRoles" })
+};
+//#endregion
+export { ANONYMOUS_USER_IDS as n, policy as r, ANONYMOUS_USER_ID as t };
+
+//# sourceMappingURL=policy-CeA1JcxP.js.map

package/dist/policy-CeA1JcxP.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-CeA1JcxP.js","names":[],"sources":["../../types/src/types/policy.ts"],"sourcesContent":["/**\n * Structured, engine-agnostic policy expressions.\n *\n * A {@link PolicyExpression} is the single source of truth for a row-level\n * security condition. It is compiled to Postgres `USING`/`WITH CHECK` SQL\n * (authoritative enforcement) and independently evaluated in JavaScript (to\n * drive the admin UI, and — in future — to enforce on engines without native\n * RLS such as MongoDB). Because both the SQL and the JS decision derive from\n * the *same* expression, the UI matches database enforcement by construction —\n * no drift between two hand-written implementations.\n *\n * The only escape hatch that cannot be evaluated client-side is the\n * {@link RawPolicyExpression} node (`{ kind: \"raw\" }`): it preserves full\n * PostgreSQL power but, being arbitrary SQL, is treated as *unknown* by the\n * JavaScript evaluator (never silently allowed) and reflected exactly in the UI\n * via server-computed capability flags.\n *\n * @group Models\n */\nexport type PolicyExpression =\n    | TruePolicyExpression\n    | FalsePolicyExpression\n    | AndPolicyExpression\n    | OrPolicyExpression\n    | NotPolicyExpression\n    | ComparePolicyExpression\n    | RolesOverlapPolicyExpression\n    | RolesContainPolicyExpression\n    | AuthenticatedPolicyExpression\n    | ServerContextPolicyExpression\n    | ExistsInPolicyExpression\n    | RawPolicyExpression;\n\n/**\n * The id a request without a logged-in user reports as `auth.uid()`.\n *\n * A user-context request always sets `app.uid`: blank would read back as\n * `NULL`, and `NULL` is how the trusted server context is recognised, so an\n * anonymous visitor would be promoted to server privileges. The driver\n * therefore substitutes this sentinel at the single chokepoint where the GUC\n * is set.\n *\n * The consequence for policy authors is that **`auth.uid() IS NOT NULL` is a\n * tautology on the user path** — it is true for anonymous visitors too. Use\n * {@link policy.authenticated} to mean \"signed in\", and\n * {@link policy.serverContext} to mean \"the trusted server context\". Do not\n * hand-write the comparison: see {@link ANONYMOUS_USER_IDS} for why one\n * literal is not enough.\n *\n * @group Models\n */\nexport const ANONYMOUS_USER_ID = \"anonymous\";\n\n/**\n * Every uid that has ever meant \"nobody is signed in\" — newest first.\n *\n * There are two because there were two. The types, the policy compiler, the\n * JavaScript evaluator and the linter were all built on\n * {@link ANONYMOUS_USER_ID}, while the request path scoped unauthenticated\n * callers as `'anon'` — so `policy.authenticated()`, which compiled to\n * `auth.uid() <> 'anonymous'`, was *true* for an anonymous visitor. The\n * sanctioned way to write \"signed in\" granted to everyone, and the linter\n * flagged the spelling that actually worked as a foreign convention.\n *\n * The request path now reports {@link ANONYMOUS_USER_ID}. `'anon'` stays here\n * because policies outlive the server that generated them: a database still\n * holding policies from before the fix, or a project whose server has not been\n * upgraded yet, must not become a grant in either direction. Compile against\n * this list, not against a single literal.\n *\n * No real user id is ever one of these, so a match is always \"not signed in\".\n *\n * @group Models\n */\nexport const ANONYMOUS_USER_IDS: readonly string[] = [ANONYMOUS_USER_ID, \"anon\"];\n\n/**\n * Whether a uid stands for \"no one is signed in\", in any spelling rebase has\n * used. `null`/`undefined` is the trusted server context, not an anonymous\n * caller, and is therefore **not** anonymous — see {@link ANONYMOUS_USER_ID}.\n *\n * @group Models\n */\nexport function isAnonymousUid(uid: string | null | undefined): boolean {\n    return typeof uid === \"string\" && ANONYMOUS_USER_IDS.includes(uid);\n}\n\n/** Always allows. Compiles to `true`. @group Models */\nexport interface TruePolicyExpression {\n    kind: \"true\";\n}\n\n/** Always denies. Compiles to `false`. @group Models */\nexport interface FalsePolicyExpression {\n    kind: \"false\";\n}\n\n/** Logical AND — every operand must pass. @group Models */\nexport interface AndPolicyExpression {\n    kind: \"and\";\n    operands: readonly PolicyExpression[];\n}\n\n/** Logical OR — at least one operand must pass. @group Models */\nexport interface OrPolicyExpression {\n    kind: \"or\";\n    operands: readonly PolicyExpression[];\n}\n\n/** Logical negation. @group Models */\nexport interface NotPolicyExpression {\n    kind: \"not\";\n    operand: PolicyExpression;\n}\n\n/** Comparison operators available to {@link ComparePolicyExpression}. @group Models */\nexport type PolicyCompareOperator = \"eq\" | \"neq\" | \"lt\" | \"lte\" | \"gt\" | \"gte\";\n\n/**\n * Compares two operands, e.g. `owner_id = auth.uid()`.\n * @group Models\n */\nexport interface ComparePolicyExpression {\n    kind: \"compare\";\n    op: PolicyCompareOperator;\n    left: PolicyOperand;\n    right: PolicyOperand;\n}\n\n/**\n * True when the user holds *at least one* of the given application roles.\n * Compiles to `string_to_array(auth.roles(), ',') && ARRAY[...]`.\n * @group Models\n */\nexport interface RolesOverlapPolicyExpression {\n    kind: \"rolesOverlap\";\n    roles: readonly string[];\n}\n\n/**\n * True when the user holds *all* of the given application roles.\n * Compiles to `string_to_array(auth.roles(), ',') @> ARRAY[...]`.\n * @group Models\n */\nexport interface RolesContainPolicyExpression {\n    kind: \"rolesContain\";\n    roles: readonly string[];\n}\n\n/**\n * True when a signed-in user is making the request. Compiles to\n * `auth.uid() IS NOT NULL AND auth.uid() <> 'anonymous'`.\n *\n * Both halves are load-bearing. `IS NOT NULL` excludes the server context;\n * the {@link ANONYMOUS_USER_ID} comparison excludes anonymous visitors, who\n * *do* carry a non-null `auth.uid()`. Checking only `IS NOT NULL` grants to\n * everyone — see {@link ANONYMOUS_USER_ID}.\n *\n * `policy.not(policy.authenticated())` therefore means \"anonymous visitor or\n * the server context\". To single out the server context, use\n * {@link ServerContextPolicyExpression}.\n * @group Models\n */\nexport interface AuthenticatedPolicyExpression {\n    kind: \"authenticated\";\n}\n\n/**\n * True only in the trusted **server context** — the built-in flows that run\n * without a user (signup, migrations, `dataAsAdmin`) set no user GUC, so\n * `auth.uid()` is `NULL` for them and only for them. Compiles to\n * `auth.uid() IS NULL`.\n *\n * This is what lets the owner connection satisfy a policy even under FORCE RLS.\n * It is deliberately a primitive rather than `not(authenticated())`: the two\n * meant the same thing while `authenticated` ignored {@link ANONYMOUS_USER_ID},\n * and conflating them is what turns a server-only grant into an anonymous one.\n *\n * The JavaScript evaluator always returns `false` for this node — a client is\n * never the server context.\n * @group Models\n */\nexport interface ServerContextPolicyExpression {\n    kind: \"serverContext\";\n}\n\n/**\n * Membership / relational access: true when at least one row exists in another\n * collection (a join/membership table) matching `where`. This is what lets you\n * scope reads to \"rows whose team the caller belongs to\" without an N+1\n * per-row lookup — it compiles to a single correlated `EXISTS` subquery.\n *\n * Inside `where`, {@link FieldPolicyOperand} (`policy.field`) references a column\n * of the joined collection, while {@link OuterFieldPolicyOperand}\n * (`policy.outerField`) references a column of the row being checked (the outer\n * table under RLS). Combine with {@link AuthUidPolicyOperand} to correlate to\n * the caller.\n *\n * @example\n * ```ts\n * // documents visible only to members of the document's team:\n * policy.existsIn({\n *   collection: \"team_members\",\n *   where: policy.and(\n *     policy.compare(policy.field(\"team_id\"), \"eq\", policy.outerField(\"team_id\")),\n *     policy.compare(policy.field(\"user_id\"), \"eq\", policy.authUid()),\n *   ),\n * })\n * // → EXISTS (SELECT 1 FROM team_members _ex0\n * //           WHERE _ex0.team_id = documents.team_id AND _ex0.user_id = auth.uid())\n * ```\n *\n * Postgres-authoritative: like {@link RawPolicyExpression}, the JavaScript\n * evaluator treats it as *unknown* (it cannot run a subquery client-side), so\n * enforcement is always the database's.\n * @group Models\n */\nexport interface ExistsInPolicyExpression {\n    kind: \"existsIn\";\n    /** Slug of the collection to search (the join / membership table). */\n    collection: string;\n    /** Condition evaluated against the joined collection's rows. */\n    where: PolicyExpression;\n}\n\n/**\n * A raw PostgreSQL boolean expression — the full-power escape hatch.\n *\n * Columns can be referenced as `{column_name}`. This is Postgres-only and\n * **server-authoritative**: the JavaScript evaluator cannot evaluate arbitrary\n * SQL, so it treats this node as *unknown* rather than guessing.\n * @group Models\n */\nexport interface RawPolicyExpression {\n    kind: \"raw\";\n    sql: string;\n}\n\n/**\n * An operand referenced by a {@link ComparePolicyExpression}.\n * @group Models\n */\nexport type PolicyOperand =\n    | FieldPolicyOperand\n    | OuterFieldPolicyOperand\n    | LiteralPolicyOperand\n    | AuthUidPolicyOperand\n    | AuthRolesPolicyOperand;\n\n/** A column value on the row being evaluated. @group Models */\nexport interface FieldPolicyOperand {\n    kind: \"field\";\n    /** The property/column name (resolved to its DB column when compiled). */\n    name: string;\n}\n\n/**\n * A column value on the *outer* row when used inside {@link ExistsInPolicyExpression}\n * — i.e. the row the RLS policy is being evaluated for, referenced from within the\n * subquery. Outside an `existsIn` it is equivalent to {@link FieldPolicyOperand}.\n * @group Models\n */\nexport interface OuterFieldPolicyOperand {\n    kind: \"outerField\";\n    /** The property/column name on the outer collection. */\n    name: string;\n}\n\n/** A constant value. @group Models */\nexport interface LiteralPolicyOperand {\n    kind: \"literal\";\n    value: string | number | boolean | null;\n}\n\n/** The current user's id — compiles to `auth.uid()`. @group Models */\nexport interface AuthUidPolicyOperand {\n    kind: \"authUid\";\n}\n\n/**\n * The current user's roles as an array — compiles to\n * `string_to_array(auth.roles(), ',')`.\n * @group Models\n */\nexport interface AuthRolesPolicyOperand {\n    kind: \"authRoles\";\n}\n\n// ── Constructor helpers ──────────────────────────────────────────────\n// Small, dependency-free builders so callers (and the desugaring in\n// `@rebasepro/common`) can assemble expressions without object-literal noise.\n\n/** @group Models */\nexport const policy = {\n    true: (): TruePolicyExpression => ({ kind: \"true\" }),\n    false: (): FalsePolicyExpression => ({ kind: \"false\" }),\n    and: (...operands: readonly PolicyExpression[]): AndPolicyExpression => ({ kind: \"and\",\noperands: operands as PolicyExpression[] }),\n    or: (...operands: readonly PolicyExpression[]): OrPolicyExpression => ({ kind: \"or\",\noperands: operands as PolicyExpression[] }),\n    not: (operand: PolicyExpression): NotPolicyExpression => ({ kind: \"not\",\noperand }),\n    compare: (left: PolicyOperand, op: PolicyCompareOperator, right: PolicyOperand): ComparePolicyExpression =>\n        ({ kind: \"compare\",\nop,\nleft,\nright }),\n    rolesOverlap: (roles: readonly string[]): RolesOverlapPolicyExpression => ({ kind: \"rolesOverlap\",\nroles: roles as string[] }),\n    rolesContain: (roles: readonly string[]): RolesContainPolicyExpression => ({ kind: \"rolesContain\",\nroles: roles as string[] }),\n    authenticated: (): AuthenticatedPolicyExpression => ({ kind: \"authenticated\" }),\n    serverContext: (): ServerContextPolicyExpression => ({ kind: \"serverContext\" }),\n    existsIn: (args: { collection: string; where: PolicyExpression }): ExistsInPolicyExpression =>\n        ({ kind: \"existsIn\",\ncollection: args.collection,\nwhere: args.where }),\n    raw: (sql: string): RawPolicyExpression => ({ kind: \"raw\",\nsql }),\n    field: (name: string): FieldPolicyOperand => ({ kind: \"field\",\nname }),\n    outerField: (name: string): OuterFieldPolicyOperand => ({ kind: \"outerField\",\nname }),\n    literal: (value: string | number | boolean | null): LiteralPolicyOperand => ({ kind: \"literal\",\nvalue }),\n    authUid: (): AuthUidPolicyOperand => ({ kind: \"authUid\" }),\n    authRoles: (): AuthRolesPolicyOperand => ({ kind: \"authRoles\" })\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAmDA,IAAa,oBAAoB;;;;;;;;;;;;;;;;;;;;;;AAuBjC,IAAa,qBAAwC,CAAC,mBAAmB,MAAM;;AA2N/E,IAAa,SAAS;CAClB,aAAmC,EAAE,MAAM,OAAO;CAClD,cAAqC,EAAE,MAAM,QAAQ;CACrD,MAAM,GAAG,cAAgE;EAAE,MAAM;EAC3E;CAA+B;CACrC,KAAK,GAAG,cAA+D;EAAE,MAAM;EACzE;CAA+B;CACrC,MAAM,aAAoD;EAAE,MAAM;EACtE;CAAQ;CACJ,UAAU,MAAqB,IAA2B,WACrD;EAAE,MAAM;EACjB;EACA;EACA;CAAM;CACF,eAAe,WAA4D;EAAE,MAAM;EAChF;CAAkB;CACrB,eAAe,WAA4D;EAAE,MAAM;EAChF;CAAkB;CACrB,sBAAqD,EAAE,MAAM,gBAAgB;CAC7E,sBAAqD,EAAE,MAAM,gBAAgB;CAC7E,WAAW,UACN;EAAE,MAAM;EACjB,YAAY,KAAK;EACjB,OAAO,KAAK;CAAM;CACd,MAAM,SAAsC;EAAE,MAAM;EACxD;CAAI;CACA,QAAQ,UAAsC;EAAE,MAAM;EAC1D;CAAK;CACD,aAAa,UAA2C;EAAE,MAAM;EACpE;CAAK;CACD,UAAU,WAAmE;EAAE,MAAM;EACzF;CAAM;CACF,gBAAsC,EAAE,MAAM,UAAU;CACxD,kBAA0C,EAAE,MAAM,YAAY;AAClE"}

package/dist/schema/ensure-collection-tables.d.ts

@@ -56,7 +56,7 @@ export interface ExistingSchema {
     constraints?: Set<string>;
 }
 export interface EnsureAction {
-    kind: "create-enum" | "create-table" | "add-column" | "add-constraint";
+    kind: "create-enum" | "create-table" | "add-column" | "add-constraint" | "rename-column";
     /** Qualified target, for logging: `public.posts` or `public.posts.title`. */
     target: string;
     sql: string;
@@ -65,6 +65,26 @@ export interface EnsurePlan {
     actions: EnsureAction[];
     /** Every statement, in dependency order. Empty when the schema is current. */
     statements: string[];
+    /**
+     * Relation columns this plan is about to create where the table already
+     * carries the same column under its pre-singularization name.
+     *
+     * The reason this is reported rather than silently handled: the ensure is
+     * additive, so it would add `category_id` beside a populated
+     * `categorie_id` and the relation would then read the new, empty one. No
+     * statement fails, no table is missing, and the only symptom is relations
+     * resolving to nothing — which is indistinguishable from having no data.
+     */
+    legacyForeignKeys: LegacyForeignKey[];
+}
+/** A relation column whose old and new spellings both plausibly apply. */
+export interface LegacyForeignKey {
+    /** `schema.table`. */
+    table: string;
+    /** The name the current rule derives, and what this plan would create. */
+    expected: string;
+    /** The name the old rule derived, which the table already has. */
+    legacy: string;
 }
 export interface EnsureOutcome extends EnsurePlan {
     /**

package/dist/schema/generate-postgres-ddl-logic.d.ts

@@ -19,6 +19,15 @@ type ResolveCollection = (slug: string) => CollectionConfig | undefined;
  * multiple commands in one execute), while `db push` writes the joined string.
  */
 export declare const generatePolicyStatements: (collection: CollectionConfig, rule: SecurityRule, resolveCollection: ResolveCollection) => string[];
+/**
+ * Single-quote escaping for a SQL string literal (PostgreSQL doubles the
+ * quote). Enum labels come straight from user-authored collection config, so a
+ * label like `it's` closes the literal early and the whole generated file stops
+ * parsing at the `CREATE TYPE`. Lives here rather than next to its other caller
+ * because ensure-collection-tables already imports from this module — the
+ * reverse would be a cycle.
+ */
+export declare const quoteSqlLiteral: (value: string) => string;
 export declare const getSqlColumnType: (propName: string, prop: Property, collection: CollectionConfig, collections: CollectionConfig[]) => string;
 export declare const generatePostgresDdl: (collections: CollectionConfig[], options?: {
     includePolicies?: boolean;
@@ -52,6 +61,15 @@ export interface RelationalColumnPlan {
     type: string;
     /** Absent when the target collection is not part of this bundle. */
     foreignKey?: ForeignKeyPlan;
+    /**
+     * What this column would have been called before `generateForeignKeyName`
+     * learned to singularize — set only when the two differ and the column name
+     * is the derived default rather than one the author wrote.
+     *
+     * Carried so the boot-time ensure can notice a database provisioned under
+     * the old rule. It is never used to name anything.
+     */
+    legacyColumn?: string;
 }
 /** The table behind a many-to-many `through` relation. */
 export interface JunctionTablePlan {
@@ -61,6 +79,7 @@ export interface JunctionTablePlan {
     columns: {
         name: string;
         type: string;
+        legacyName?: string;
     }[];
     /** Both endpoint columns plus the composite primary key. */
     createTable: string;

package/dist/schema/introspect-db-constraints.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Reading validation rules out of CHECK constraints.
+ *
+ * A CHECK constraint is the schema author stating a rule the database already
+ * enforces. Introspection has never read them, so a generated form let the user
+ * type a value the database was always going to reject — the rule was written
+ * down, in the schema, and the UI asked anyway.
+ *
+ * Everything here parses the *normalized* text `pg_get_constraintdef` produces,
+ * not what the author typed: Postgres re-renders the expression from its parse
+ * tree, so `CHECK (price > 0)` on a `numeric` column always comes back as
+ * `CHECK ((price > (0)::numeric))`. That normalization is what makes a
+ * string-level parser tractable — the input is generated, and the shapes are
+ * few.
+ *
+ * Constraints this cannot read are skipped in full. A partially-understood
+ * constraint is worse than an unread one: it would produce validation that
+ * *narrows* differently from the database, so a value the UI accepts still
+ * fails on write, or — worse — a value the database allows is refused in the
+ * form with no way to see why.
+ *
+ * Pure module: no I/O, no logging.
+ */
+import type { CheckConstraintRow } from "./introspect-db-logic";
+/** What a table's CHECK constraints say about one column. */
+export interface ColumnCheckFacts {
+    /** Allowed values, from `IN (…)` / `= ANY (ARRAY[…])` / `= 'literal'`. */
+    enumValues?: string[];
+    /** `x >= n` */
+    min?: number;
+    /** `x <= n` */
+    max?: number;
+    /** `x > n` */
+    moreThan?: number;
+    /** `x < n` */
+    lessThan?: number;
+    /** `length(x) >= n` */
+    lengthMin?: number;
+    /** `length(x) <= n` */
+    lengthMax?: number;
+}
+/** Per-table, per-column facts. */
+export type CheckFactsByTable = Map<string, Map<string, ColumnCheckFacts>>;
+/** Removes one layer of wrapping parentheses, repeatedly, when balanced. */
+export declare function unwrapParens(input: string): string;
+/** Drops trailing `::type` casts, including array and quoted forms. */
+export declare function stripCasts(input: string): string;
+/**
+ * Reads one constraint definition into per-column facts.
+ *
+ * Returns an empty map for anything not understood — including a constraint
+ * that is understood but spans two columns (`start_date < end_date`), which no
+ * per-property validation rule can express.
+ */
+export declare function parseCheckDefinition(definition: string): Map<string, ColumnCheckFacts>;
+/** Merges every readable CHECK in the schema into per-table, per-column facts. */
+export declare function parseCheckConstraints(rows: CheckConstraintRow[]): CheckFactsByTable;

package/dist/schema/introspect-db-logic.d.ts

@@ -1,5 +1,10 @@
+import { mapPgType } from "./introspect-db-types";
+import type { CheckFactsByTable } from "./introspect-db-constraints";
+import type { TableClassification } from "./introspect-db-structure";
 export interface TableRow {
     table_name: string;
+    /** True for the parent of a partitioned table (`relkind = 'p'`). */
+    is_partitioned?: boolean;
 }
 export interface TableColumn {
     table_name: string;
@@ -9,6 +14,18 @@ export interface TableColumn {
     is_nullable: string;
     column_default: string | null;
     atttypmod: number | null;
+    /** 1-based position in the table, as declared. */
+    ordinal_position?: number;
+    /** `"ALWAYS"` for a generated column, `"NEVER"` otherwise. */
+    is_generated?: string;
+    /** `"YES"` for an identity column. */
+    is_identity?: string;
+    /** `"ALWAYS"` or `"BY DEFAULT"` on an identity column. */
+    identity_generation?: string | null;
+    /** The declared `varchar(n)` / `char(n)` bound, if any. */
+    character_maximum_length?: number | null;
+    numeric_precision?: number | null;
+    numeric_scale?: number | null;
 }
 export interface EnumValue {
     enum_name: string;
@@ -24,6 +41,53 @@ export interface ForeignKeyRow {
     column_name: string;
     foreign_table_name: string;
     foreign_column_name: string;
+    /** Name of the FK constraint — the only way to tell composite keys apart. */
+    constraint_name?: string;
+    /** 1-based position of this column within its constraint. */
+    ordinal?: number;
+    /** `"CASCADE"`, `"RESTRICT"`, `"SET NULL"`, `"SET DEFAULT"`, `"NO ACTION"`. */
+    delete_rule?: string;
+}
+/** A unique constraint or unique index, as an ordered column list. */
+export interface UniqueConstraintRow {
+    table_name: string;
+    constraint_name: string;
+    column_names: string[];
+}
+/** A CHECK constraint, as `pg_get_constraintdef` renders it. */
+export interface CheckConstraintRow {
+    table_name: string;
+    constraint_name: string;
+    definition: string;
+}
+/** A `COMMENT ON TABLE` (null `column_name`) or `COMMENT ON COLUMN`. */
+export interface CommentRow {
+    table_name: string;
+    column_name: string | null;
+    comment: string;
+}
+/**
+ * Everything one introspection run reads from the database.
+ *
+ * Passed around as one value so a new signal means a new field here rather than
+ * a new parameter on every function between the query and the generator — the
+ * shape `generateCollectionFile` had grown to seven positional arguments by.
+ */
+export interface SchemaMetadata {
+    schema: string;
+    tables: TableRow[];
+    columns: TableColumn[];
+    enumValues: EnumValue[];
+    pks: PrimaryKeyRow[];
+    fks: ForeignKeyRow[];
+    uniques: UniqueConstraintRow[];
+    checks: CheckConstraintRow[];
+    comments: CommentRow[];
+    /**
+     * Row counts for the tables that needed one, capped — see `countRowsUpTo`.
+     * Absent for every table introspection never had a reason to count.
+     */
+    rowCounts: Record<string, number>;
 }
 export interface TableMeta {
     name: string;
@@ -38,12 +102,23 @@ export declare function singularize(word: string): string;
  */
 export declare function toCollectionVarName(tableName: string): string;
 export declare function getIconForTable(tableName: string): string;
-/**
- * Map a PostgreSQL data type to a Rebase property type.
- */
-export declare function mapPgType(dataType: string): string;
+export { mapPgType };
 export declare function buildEnumMap(enumValues: EnumValue[]): Map<string, string[]>;
 export declare function buildTablesMap(tables: TableRow[], columns: TableColumn[], pks: PrimaryKeyRow[], fks: ForeignKeyRow[]): Map<string, TableMeta>;
+/**
+ * Join tables, identified by column name.
+ *
+ * Superseded for the CLI by `classifyTables` in `./introspect-db-structure`,
+ * which asks the database instead: two single-column keys, unique together, no
+ * payload column, nothing referencing the table. This rule folds away
+ * `northwind.order_details` — which has the key shape and carries unit price,
+ * quantity and discount — because it recognises `id`, `created_at` and
+ * `updated_at` by name and calls everything else a foreign key.
+ *
+ * Still used by `./introspect-runtime`, which builds collections in memory from
+ * a narrower set of catalog queries and has no unique-constraint or row-count
+ * data to reason with.
+ */
 export declare function identifyJoinTables(tablesMap: Map<string, TableMeta>): Set<string>;
 /**
  * Property metadata used to compute display priority.
@@ -93,11 +168,25 @@ export interface GeneratedFile {
     fileName: string;
     content: string;
 }
+/**
+ * The structural analysis a run can hand the generator.
+ *
+ * Optional in full, and the generator degrades to exactly its previous output
+ * without it. That is not politeness towards old callers: three existing test
+ * suites and the `rebase init` scaffold path build a `TableMeta` by hand and
+ * have no database to read constraints or row counts from, and they must keep
+ * producing a valid collection.
+ */
+export interface GenerationContext {
+    metadata?: SchemaMetadata;
+    classifications?: Map<string, TableClassification>;
+    checkFacts?: CheckFactsByTable;
+}
 /**
  * Generate the full TypeScript file content for a single collection.
  * Pure function — no I/O.
  */
-export declare function generateCollectionFile(tableName: string, meta: TableMeta, allFks: ForeignKeyRow[], joinTables: Set<string>, tablesMap: Map<string, TableMeta>, enumMap: Map<string, string[]>, sampleData?: Record<string, unknown>[]): string;
+export declare function generateCollectionFile(tableName: string, meta: TableMeta, allFks: ForeignKeyRow[], joinTables: Set<string>, tablesMap: Map<string, TableMeta>, enumMap: Map<string, string[]>, sampleData?: Record<string, unknown>[], context?: GenerationContext): string;
 /**
  * Generate the content for an index.ts file that re-exports all collections.
  */

package/dist/schema/introspect-db-queries.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The catalog queries introspection runs, and the shape they produce.
+ *
+ * These live apart from {@link ./introspect-db.ts} (the CLI entry point) on
+ * purpose: the fixture-capture script and the live e2e read a database through
+ * this module too, so what the tests see is what the CLI sees. A query that
+ * only exists inside the CLI's `main()` can only be tested by running the CLI.
+ *
+ * No side effects beyond `SELECT`. Introspection reads a database it does not
+ * own — it must never `ANALYZE`, create a temp table, or otherwise write.
+ */
+import type { SchemaMetadata } from "./introspect-db-logic";
+/** The subset of `pg.Client` this module needs, so tests can pass a fake. */
+export interface QueryableClient {
+    query<R = Record<string, unknown>>(text: string, values?: unknown[]): Promise<{
+        rows: R[];
+    }>;
+}
+/**
+ * Base tables, excluding partitions.
+ *
+ * `relispartition` is the reason this reads `pg_class` rather than
+ * `information_schema.tables`, which reports every partition as a base table of
+ * its own. Pagila partitions `payment` by month; introspected through
+ * information_schema it yields `payment` plus 26 near-identical
+ * `payment_p2022_*` collections, each with its own nav entry.
+ *
+ * `relkind = 'p'` (the partitioned parent) is included and `'r'` partitions are
+ * dropped, which is the right way round: the parent is the queryable table.
+ */
+export declare const TABLES_QUERY = "\n    SELECT c.relname AS table_name,\n           c.relkind = 'p' AS is_partitioned\n    FROM pg_class c\n    JOIN pg_namespace n ON n.oid = c.relnamespace\n    WHERE n.nspname = $1\n      AND c.relkind IN ('r', 'p')\n      AND NOT c.relispartition\n      AND c.relname NOT LIKE 'drizzle_%'\n      AND c.relname NOT LIKE 'rebase_%'\n    ORDER BY c.relname\n";
+/**
+ * Columns, with the catalog facts that say a column is not the user's to edit.
+ *
+ * `is_generated`/`is_identity` are read for that reason: a generated column
+ * rejects any write, so a form that offers it is offering a field that always
+ * errors. `character_maximum_length` is the declared `varchar(n)` bound —
+ * already enforced by the database, and free to surface as validation.
+ */
+export declare const COLUMNS_QUERY = "\n    SELECT\n        c.table_name,\n        c.column_name,\n        c.data_type,\n        c.udt_name,\n        c.is_nullable,\n        c.column_default,\n        c.ordinal_position,\n        c.is_generated,\n        c.is_identity,\n        c.identity_generation,\n        c.character_maximum_length,\n        c.numeric_precision,\n        c.numeric_scale,\n        (SELECT a.atttypmod FROM pg_attribute a\n         JOIN pg_class pc ON a.attrelid = pc.oid\n         WHERE pc.relname = c.table_name\n           AND a.attname = c.column_name\n           AND pc.relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = c.table_schema)) as atttypmod\n    FROM information_schema.columns c\n    WHERE c.table_schema = $1\n    ORDER BY c.table_name, c.ordinal_position\n";
+export declare const ENUMS_QUERY = "\n    SELECT t.typname AS enum_name,\n           e.enumlabel AS enum_value,\n           e.enumsortorder AS sort_order\n    FROM pg_type t\n    JOIN pg_enum e ON t.oid = e.enumtypid\n    JOIN pg_namespace n ON t.typnamespace = n.oid\n    WHERE n.nspname = $1\n    ORDER BY t.typname, e.enumsortorder\n";
+/**
+ * Primary key columns, in key order.
+ *
+ * `ORDER BY k.ord` matters for composite keys: the position of a column inside
+ * the key is what tells a two-column PK made of two foreign keys apart from an
+ * ordinary composite key, and `= ANY(i.indkey)` (the shape this replaced)
+ * returns catalog order instead.
+ */
+export declare const PRIMARY_KEYS_QUERY = "\n    SELECT t.relname AS table_name,\n           a.attname AS column_name\n    FROM pg_index i\n    JOIN pg_class t ON t.oid = i.indrelid\n    JOIN pg_namespace n ON n.oid = t.relnamespace\n    CROSS JOIN LATERAL unnest(i.indkey) WITH ORDINALITY AS k(attnum, ord)\n    JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum\n    WHERE i.indisprimary AND n.nspname = $1\n    ORDER BY t.relname, k.ord\n";
+/**
+ * Foreign keys, one row per referencing column, with the delete rule.
+ *
+ * Read from `pg_constraint` rather than through
+ * `information_schema.constraint_column_usage`, which does not preserve the
+ * pairing on a composite foreign key: it reports the cross product of the
+ * constraint's columns, so a two-column FK comes back as four rows, two of them
+ * pairing the wrong columns. `unnest(...) WITH ORDINALITY` on both sides joined
+ * on the ordinal keeps each referencing column with the column it references.
+ *
+ * `confdeltype` is carried because `ON DELETE CASCADE` is the schema author
+ * saying, in the database, that the child cannot outlive the parent — the one
+ * unambiguous declaration of ownership a schema contains.
+ *
+ * Constraints declared on a *partition* are attributed to the partition root,
+ * because that is the table this run generates a collection for. Pagila declares
+ * `payment`'s three foreign keys on each monthly partition and none on the
+ * parent, so reading `pg_constraint` at face value gives the `payment`
+ * collection no relations at all. `pick = 1` then keeps one row per logical key,
+ * preferring the root's own constraint when it has one, so a schema that
+ * declares the key on the parent *and* inherits it onto 26 partitions does not
+ * yield 27 copies of the same relation.
+ */
+export declare const FOREIGN_KEYS_QUERY = "\n    WITH fk AS (\n        SELECT con.oid,\n               con.conname,\n               con.conrelid,\n               con.confrelid,\n               con.conkey,\n               con.confkey,\n               con.confdeltype,\n               COALESCE(pg_partition_root(con.conrelid), con.conrelid) AS root_oid,\n               row_number() OVER (\n                   PARTITION BY COALESCE(pg_partition_root(con.conrelid), con.conrelid),\n                                con.confrelid, con.conkey, con.confkey\n                   ORDER BY (con.conrelid = COALESCE(pg_partition_root(con.conrelid), con.conrelid)) DESC,\n                            con.oid\n               ) AS pick\n        FROM pg_constraint con\n        JOIN pg_namespace n ON n.oid = con.connamespace\n        WHERE con.contype = 'f' AND n.nspname = $1\n    )\n    SELECT root.relname AS table_name,\n           sa.attname AS column_name,\n           tgt.relname AS foreign_table_name,\n           ta.attname AS foreign_column_name,\n           fk.conname AS constraint_name,\n           s.ord::int AS ordinal,\n           CASE fk.confdeltype\n               WHEN 'a' THEN 'NO ACTION'\n               WHEN 'r' THEN 'RESTRICT'\n               WHEN 'c' THEN 'CASCADE'\n               WHEN 'n' THEN 'SET NULL'\n               WHEN 'd' THEN 'SET DEFAULT'\n           END AS delete_rule\n    FROM fk\n    JOIN pg_class root ON root.oid = fk.root_oid\n    JOIN pg_class tgt ON tgt.oid = fk.confrelid\n    CROSS JOIN LATERAL unnest(fk.conkey) WITH ORDINALITY AS s(attnum, ord)\n    JOIN pg_attribute sa ON sa.attrelid = fk.conrelid AND sa.attnum = s.attnum\n    CROSS JOIN LATERAL unnest(fk.confkey) WITH ORDINALITY AS f(attnum, ord)\n    JOIN pg_attribute ta ON ta.attrelid = fk.confrelid AND ta.attnum = f.attnum\n    WHERE fk.pick = 1 AND s.ord = f.ord\n    ORDER BY root.relname, fk.conname, s.ord\n";
+/**
+ * Unique constraints and unique indexes, as ordered column lists.
+ *
+ * Indexes rather than constraints alone, because `CREATE UNIQUE INDEX` and
+ * `ADD CONSTRAINT ... UNIQUE` produce the same guarantee and schemas use both.
+ * Partial indexes (`indpred IS NOT NULL`) are excluded: they promise uniqueness
+ * only over the rows matching their predicate, which is not the promise a
+ * `validation: { unique: true }` field makes.
+ */
+export declare const UNIQUE_CONSTRAINTS_QUERY = "\n    SELECT t.relname AS table_name,\n           ic.relname AS constraint_name,\n           -- ::text, because the driver has no parser for an array of `name`\n           -- and hands back the raw `{a,b}` literal as a string. Every consumer\n           -- here indexes and compares it as an array, and a string of that\n           -- shape fails those silently rather than loudly.\n           array_agg(a.attname::text ORDER BY k.ord) AS column_names\n    FROM pg_index i\n    JOIN pg_class t ON t.oid = i.indrelid\n    JOIN pg_class ic ON ic.oid = i.indexrelid\n    JOIN pg_namespace n ON n.oid = t.relnamespace\n    CROSS JOIN LATERAL unnest(i.indkey) WITH ORDINALITY AS k(attnum, ord)\n    JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum\n    WHERE i.indisunique\n      AND NOT i.indisprimary\n      AND i.indpred IS NULL\n      AND n.nspname = $1\n      AND NOT t.relispartition\n    GROUP BY t.relname, ic.relname\n    ORDER BY t.relname, ic.relname\n";
+/**
+ * CHECK constraints, as the source text Postgres reproduces them from.
+ *
+ * `pg_get_constraintdef` output is normalized by the server — the parser in
+ * {@link ./introspect-db-constraints.ts} reads that normalized form, not
+ * whatever the author typed.
+ */
+export declare const CHECK_CONSTRAINTS_QUERY = "\n    SELECT DISTINCT\n           root.relname AS table_name,\n           con.conname AS constraint_name,\n           pg_get_constraintdef(con.oid) AS definition\n    FROM pg_constraint con\n    JOIN pg_namespace n ON n.oid = con.connamespace\n    JOIN pg_class root ON root.oid = COALESCE(pg_partition_root(con.conrelid), con.conrelid)\n    WHERE con.contype = 'c'\n      AND n.nspname = $1\n    ORDER BY root.relname, con.conname\n";
+/**
+ * `COMMENT ON TABLE` / `COMMENT ON COLUMN`, which is documentation the author
+ * already wrote and which nothing downstream has ever read.
+ */
+export declare const COMMENTS_QUERY = "\n    SELECT t.relname AS table_name,\n           a.attname AS column_name,\n           d.description AS comment\n    FROM pg_description d\n    JOIN pg_class t ON t.oid = d.objoid\n    JOIN pg_namespace n ON n.oid = t.relnamespace\n    LEFT JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = d.objsubid\n    WHERE n.nspname = $1\n      AND t.relkind IN ('r', 'p')\n      AND (d.objsubid = 0 OR a.attname IS NOT NULL)\n    ORDER BY t.relname, d.objsubid\n";
+/**
+ * Counts a table's rows, stopping once the answer can only be "more than
+ * `limit`".
+ *
+ * Introspection asks this to tell a small reference table from a table that
+ * merely looks like one (see `classifyTables`). `reltuples` would answer for
+ * free but lies on a table that has never been analyzed — which is every table
+ * in a database restored from a dump, i.e. exactly the case introspection meets
+ * — and reports -1 there rather than an error, so the lie is silent.
+ *
+ * The subquery's LIMIT caps the work at `limit + 1` rows however large the
+ * table is, so this stays cheap on a table with a billion rows.
+ */
+export declare function countRowsUpTo(client: QueryableClient, schema: string, table: string, limit: number): Promise<number>;
+/**
+ * Reads everything the generator needs, in one pass.
+ *
+ * `rowCounts` is deliberately absent here: it costs a query per table and only
+ * a handful of tables can possibly need it. The caller fills it in for the
+ * candidates `lookupCandidates()` names.
+ */
+export declare function readSchemaMetadata(client: QueryableClient, schema: string): Promise<SchemaMetadata>;