@rebasepro/server-postgres 0.10.1-canary.b1e3dbf → 0.10.1-canary.ed78a2c

package/src/collections/validate-relations.ts

@@ -0,0 +1,280 @@
+import { getTableColumns } from "drizzle-orm";
+import { PgTable } from "drizzle-orm/pg-core";
+import { CollectionConfig, ResolvedRelation } from "@rebasepro/types";
+import { getTableName, resolveCollectionRelations } from "@rebasepro/common";
+
+import { PostgresCollectionRegistry } from "./PostgresCollectionRegistry";
+
+/**
+ * Check every relation against the schema it actually runs on, at boot.
+ *
+ * The tagged union made the *shape* of a relation impossible to get wrong: a
+ * `manyToMany` cannot carry a `foreignKeyOnTarget`, a to-many cannot carry a
+ * `localKey`. What it cannot know is whether any of the names are real —
+ * whether `posts_tags` is a table, whether `author_id` is a column, whether a
+ * `joinPath` connects the tables it claims to. Those are facts about the
+ * database, and the type system never sees them.
+ *
+ * Until now nothing checked them until a query ran, and the failures were the
+ * quiet kind. A missing junction table logged a warning and returned no rows,
+ * so `posts/1/tags` answered `[]` — indistinguishable from a post with no tags.
+ * The relation looked configured, the admin drew the tab, the tab was empty,
+ * and nothing anywhere said why.
+ *
+ * The junction default is the sharp edge this exists for. `through.table`
+ * defaults to the two table names sorted and joined, so renaming a table
+ * silently re-points the relation at a name that was never created. It is the
+ * one default whose output changes when you edit something that looks
+ * unrelated.
+ */
+export interface RelationDefect {
+    /** Slug of the collection declaring the relation. */
+    collection: string;
+    relationName: string;
+    kind: ResolvedRelation["kind"];
+    /** What is wrong, in terms of the schema. */
+    problem: string;
+    /** The edit that fixes it. */
+    fix: string;
+}
+
+/**
+ * Every name a column answers to: the key in the drizzle schema and the real
+ * column name in Postgres. A relation may legitimately be written with either,
+ * and reporting a working relation as broken is worse than not checking.
+ */
+function columnNames(table: PgTable): Set<string> {
+    const names = new Set<string>();
+    for (const [key, col] of Object.entries(getTableColumns(table))) {
+        names.add(key);
+        const dbName = (col as { name?: string })?.name;
+        if (dbName) names.add(dbName);
+    }
+    return names;
+}
+
+const quote = (xs: Iterable<string>) => Array.from(xs).map(s => `\`${s}\``).join(", ");
+
+/** `on.from` / `on.to` accept a single column or a composite tuple. */
+const asColumns = (value: string | string[]): string[] => Array.isArray(value) ? value : [value];
+
+/**
+ * Relations whose names do not resolve against the registered schema.
+ *
+ * Fails open wherever it cannot see enough to be sure — an unregistered source
+ * table, a target belonging to another backend — because a false alarm here
+ * costs more than a missed one: it would block boot on a working app.
+ */
+export function findRelationDefects(
+    collections: CollectionConfig[],
+    registry: PostgresCollectionRegistry
+): RelationDefect[] {
+    const defects: RelationDefect[] = [];
+    const registeredSlugs = new Set(registry.getCollections().map(c => c.slug));
+
+    for (const collection of collections) {
+        const sourceTableName = getTableName(collection);
+        const sourceTable = registry.getTable(sourceTableName);
+        // Nothing to check against. Another boot warning already covers this.
+        if (!sourceTable) continue;
+
+        const sourceColumns = columnNames(sourceTable);
+        const relations = resolveCollectionRelations(collection);
+
+        for (const relation of Object.values(relations)) {
+            const at = { collection: collection.slug,
+relationName: relation.relationName,
+kind: relation.kind };
+
+            let targetCollection: CollectionConfig;
+            try {
+                targetCollection = relation.target();
+            } catch (e) {
+                defects.push({
+                    ...at,
+                    problem: `its \`target()\` threw: ${e instanceof Error ? e.message : String(e)}`,
+                    fix: "a target thunk usually throws because of a circular import — make sure it is `() => otherCollection` and not evaluated at module load"
+                });
+                continue;
+            }
+
+            // A target this registry has never heard of belongs to another
+            // backend; its tables are not ours to check.
+            if (!registeredSlugs.has(targetCollection.slug)) continue;
+
+            const targetTableName = getTableName(targetCollection);
+            const targetTable = registry.getTable(targetTableName);
+            if (!targetTable) {
+                defects.push({
+                    ...at,
+                    problem: `it points at collection \`${targetCollection.slug}\`, which has no table \`${targetTableName}\` in the schema`,
+                    fix: `create the \`${targetTableName}\` table, or correct \`table\` on the \`${targetCollection.slug}\` collection`
+                });
+                continue;
+            }
+            const targetColumns = columnNames(targetTable);
+
+            switch (relation.kind) {
+                case "belongsTo": {
+                    if (!sourceColumns.has(relation.localKey)) {
+                        defects.push({
+                            ...at,
+                            problem: `\`localKey: "${relation.localKey}"\` is not a column on \`${sourceTableName}\``,
+                            fix: `add the column, or set \`localKey\` to one of: ${quote(sourceColumns)}`
+                        });
+                    }
+                    break;
+                }
+
+                case "hasOne":
+                case "hasMany": {
+                    if (!targetColumns.has(relation.foreignKeyOnTarget)) {
+                        defects.push({
+                            ...at,
+                            problem: `\`foreignKeyOnTarget: "${relation.foreignKeyOnTarget}"\` is not a column on the target table \`${targetTableName}\``,
+                            fix: `add the column, or set \`foreignKeyOnTarget\` to one of: ${quote(targetColumns)}`
+                        });
+                    }
+                    break;
+                }
+
+                case "manyToMany": {
+                    const { table, sourceColumn, targetColumn } = relation.through;
+                    const junction = registry.getTable(table);
+                    if (!junction) {
+                        defects.push({
+                            ...at,
+                            problem: `its junction table \`${table}\` does not exist`,
+                            fix: `create \`${table}\`, or name the real one with \`through: { table: "..." }\`. ` +
+                                "Note that an omitted `through.table` is derived from the two table names sorted " +
+                                "and joined, so renaming a table changes it"
+                        });
+                        break;
+                    }
+                    const junctionColumns = columnNames(junction);
+                    for (const [label, column] of [["sourceColumn", sourceColumn], ["targetColumn", targetColumn]] as const) {
+                        if (!junctionColumns.has(column)) {
+                            defects.push({
+                                ...at,
+                                problem: `\`through.${label}: "${column}"\` is not a column on the junction table \`${table}\``,
+                                fix: `set \`through.${label}\` to one of: ${quote(junctionColumns)}` +
+                                    (label === "sourceColumn" ? " — it is the column naming *this* collection" : "")
+                            });
+                        }
+                    }
+                    break;
+                }
+
+                case "via": {
+                    if (relation.joinPath.length === 0) {
+                        defects.push({
+                            ...at,
+                            problem: "its `joinPath` is empty, so it joins nothing",
+                            fix: "add at least one step, ending at the target's table"
+                        });
+                        break;
+                    }
+
+                    // Walk the chain: each step's `from` names columns on the
+                    // previous table, its `to` names columns on its own.
+                    let prevName = sourceTableName;
+                    let prevColumns = sourceColumns;
+                    let broken = false;
+
+                    for (const [i, step] of relation.joinPath.entries()) {
+                        const stepTable = registry.getTable(step.table);
+                        if (!stepTable) {
+                            defects.push({
+                                ...at,
+                                problem: `step ${i + 1} of its \`joinPath\` joins \`${step.table}\`, which is not a table in the schema`,
+                                fix: `correct \`joinPath[${i}].table\``
+                            });
+                            broken = true;
+                            break;
+                        }
+                        const stepColumns = columnNames(stepTable);
+
+                        for (const column of asColumns(step.on.from)) {
+                            if (!prevColumns.has(column)) {
+                                defects.push({
+                                    ...at,
+                                    problem: `step ${i + 1} joins \`${prevName}.${column}\` → \`${step.table}\`, but \`${column}\` is not a column on \`${prevName}\``,
+                                    fix: `\`joinPath[${i}].on.from\` names columns on ${i === 0 ? "this collection's table" : `the previous step's table (\`${prevName}\`)`}: ${quote(prevColumns)}`
+                                });
+                            }
+                        }
+                        for (const column of asColumns(step.on.to)) {
+                            if (!stepColumns.has(column)) {
+                                defects.push({
+                                    ...at,
+                                    problem: `step ${i + 1} joins into \`${step.table}.${column}\`, but \`${column}\` is not a column on \`${step.table}\``,
+                                    fix: `\`joinPath[${i}].on.to\` names columns on \`${step.table}\`: ${quote(stepColumns)}`
+                                });
+                            }
+                        }
+
+                        if (asColumns(step.on.from).length !== asColumns(step.on.to).length) {
+                            defects.push({
+                                ...at,
+                                problem: `step ${i + 1} compares ${asColumns(step.on.from).length} column(s) against ${asColumns(step.on.to).length}`,
+                                fix: `\`from\` and \`to\` must name the same number of columns in \`joinPath[${i}]\``
+                            });
+                        }
+
+                        prevName = step.table;
+                        prevColumns = stepColumns;
+                    }
+
+                    // The chain has to end where the relation says it points,
+                    // or the rows it returns are not the target's rows.
+                    if (!broken && prevName !== targetTableName) {
+                        defects.push({
+                            ...at,
+                            problem: `its \`joinPath\` ends at \`${prevName}\`, but it targets \`${targetCollection.slug}\` (table \`${targetTableName}\`)`,
+                            fix: `make the last step join \`${targetTableName}\`, or point \`target\` at the collection backed by \`${prevName}\``
+                        });
+                    }
+                    break;
+                }
+
+                default: {
+                    const exhaustive: never = relation;
+                    throw new Error(`Unhandled relation kind: ${JSON.stringify(exhaustive)}`);
+                }
+            }
+        }
+    }
+
+    return defects;
+}
+
+/**
+ * Fail boot on any relation that cannot resolve, listing all of them at once.
+ *
+ * Deliberately fatal rather than a warning. Every one of these produces an
+ * empty result at query time and nothing else — an empty tab, an empty
+ * `include`, a subcollection that looks like it has no rows. A server that
+ * refuses to start is recoverable in a minute; a relation that quietly answers
+ * "nothing" is the kind of bug found in production, weeks later, by a user
+ * asking where their data went.
+ */
+export function assertRelationsResolve(
+    collections: CollectionConfig[],
+    registry: PostgresCollectionRegistry
+): void {
+    const defects = findRelationDefects(collections, registry);
+    if (defects.length === 0) return;
+
+    const lines = defects.map(d =>
+        `  • ${d.collection}.${d.relationName} (${d.kind})\n` +
+        `      ${d.problem}\n` +
+        `      fix: ${d.fix}`
+    );
+
+    throw new Error(
+        `${defects.length} relation${defects.length === 1 ? "" : "s"} cannot resolve against the database schema.\n\n` +
+        "Each of these would return no rows at query time rather than reporting an error, " +
+        "so they are fatal at boot instead.\n\n" +
+        lines.join("\n\n") + "\n"
+    );
+}

package/src/data-transformer.ts

@@ -1,7 +1,7 @@
 import { eq, SQL } from "drizzle-orm";
 import { AnyPgColumn } from "drizzle-orm/pg-core";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
-import { CollectionConfig, Properties, Property, Relation, RelationProperty, Vector, BinaryProperty } from "@rebasepro/types";
+import { CollectionConfig, Properties, Property, ResolvedRelation, RelationProperty, Vector, BinaryProperty, hasForeignKeyOnTarget, type ResolvedBelongsTo, type ResolvedForeignKeyOnTarget, type ResolvedVia } from "@rebasepro/types";
 import { getTableName, resolveCollectionRelations, findRelation, createRelationRef, DEFAULT_ONE_OF_TYPE, DEFAULT_ONE_OF_VALUE } from "@rebasepro/common";
 import { PostgresCollectionRegistry } from "./collections/PostgresCollectionRegistry";
 import { DrizzleConditionBuilder } from "./utils/drizzle-conditions";
@@ -31,13 +31,13 @@ export interface SerializedEntityData {
      */
     inverseRelationUpdates: Array<{
         relationKey: string;
-        relation: Relation;
+        relation: ResolvedRelation;
         newValue: unknown;
     }>;
     /** JoinPath relation updates that require multi-hop writes. */
     joinPathRelationUpdates: Array<{
         relationKey: string;
-        relation: Relation;
+        relation: ResolvedVia;
         newTargetId: string | number | null;
     }>;
 }
@@ -110,19 +110,19 @@ joinPathRelationUpdates: [] };
     // Track inverse relations that need to be handled separately
     const inverseRelationUpdates: Array<{
         relationKey: string;
-        relation: Relation;
+        relation: ResolvedRelation;
         newValue: unknown;
     }> = [];
     const joinPathRelationUpdates: Array<{
         relationKey: string;
-        relation: Relation;
+        relation: ResolvedVia;
         newTargetId: string | number | null;
     }> = [];
 
     // Pre-calculate all local keys used as foreign keys
     const foreignKeys = new Set<string>();
     Object.values(resolvedRelations).forEach(relation => {
-        if (relation.localKey) foreignKeys.add(relation.localKey);
+        if (relation.kind === "belongsTo") foreignKeys.add(relation.localKey);
     });
 
     for (const [key, value] of Object.entries(row)) {
@@ -141,7 +141,7 @@ joinPathRelationUpdates: [] };
         if (property.type === "relation" && collection) {
             const relation = findRelation(resolvedRelations, key);
             if (relation) {
-                if (relation.direction === "owning" && relation.localKey) {
+                if (relation.kind === "belongsTo") {
                     // Owning relation: Map relation object to FK column on current table
                     const serializedValue = serializePropertyToServer(effectiveValue, property);
                     if (serializedValue !== undefined) {
@@ -149,7 +149,7 @@ joinPathRelationUpdates: [] };
                     }
                     // Don't add the original relation property to the result
                     continue;
-                } else if (relation.direction === "inverse" && relation.foreignKeyOnTarget) {
+                } else if (hasForeignKeyOnTarget(relation)) {
                     // Inverse relation: Need to update the target table's FK
                     const serializedValue = serializePropertyToServer(effectiveValue, property);
                     inverseRelationUpdates.push({
@@ -159,38 +159,29 @@ joinPathRelationUpdates: [] };
                     });
                     // Don't add the original relation property to the result
                     continue;
-                } else if (relation.direction === "inverse" && relation.joinPath && relation.joinPath.length > 0) {
+                } else if (relation.kind === "via") {
+                    // A join chain is written through its own machinery, one
+                    // row at a time for a to-one and as a set for a to-many.
+                    // There used to be two arms here — "owning" and "inverse"
+                    // joinPath — but a join chain has no owning side, so they
+                    // only ever differed by which list they pushed to.
                     const serializedValue = serializePropertyToServer(effectiveValue, property);
                     if (relation.cardinality === "one") {
-                        // One-to-one inverse joinPath: route through joinPathRelationUpdates.
-                        // The write ordering in PersistService ensures these are processed
-                        // BEFORE the main UPDATE, so parentSourceCol reads the pre-update FK value.
-                        // This prevents stale values from corrupting related rows when an
-                        // intermediate FK (e.g. author_id) changes in the same save.
+                        // Ordering matters: PersistService applies these BEFORE
+                        // the main UPDATE, so the mapping reads the pre-update
+                        // foreign key rather than a value the same save changed.
                         joinPathRelationUpdates.push({
                             relationKey: key,
                             relation,
                             newTargetId: serializedValue as string | number | null
                         });
                     } else {
-                        // Many inverse joinPath: capture as inverse relation update
                         inverseRelationUpdates.push({
                             relationKey: key,
                             relation,
                             newValue: serializedValue
                         });
                     }
-                    // Don't add the original relation property to the result
-                    continue;
-                } else if (relation.cardinality === "one" && relation.direction === "owning" && relation.joinPath && relation.joinPath.length > 0) {
-                    // Owning one-to-one via joinPath: capture as a write intent
-                    const serializedValue = serializePropertyToServer(effectiveValue, property);
-                    joinPathRelationUpdates.push({
-                        relationKey: key,
-                        relation,
-                        newTargetId: serializedValue as string | number | null
-                    });
-                    // Don't include this property directly in payload
                     continue;
                 }
             }
@@ -320,7 +311,7 @@ export async function parseDataFromServer<M extends Record<string, unknown>>(
             // Find the normalized relation for this property
             const relation = findRelation(resolvedRelations, propKey);
             if (relation) {
-                if (relation.direction === "owning" && relation.localKey && relation.localKey in data) {
+                if (relation.kind === "belongsTo" && relation.localKey in data) {
                     // Owning relation: FK is in current table
                     const fkValue = data[relation.localKey as keyof M];
                     if (fkValue !== null && fkValue !== undefined) {
@@ -331,7 +322,7 @@ export async function parseDataFromServer<M extends Record<string, unknown>>(
                             logger.warn(`Could not resolve target collection for relation property: ${propKey}`, { error: e });
                         }
                     }
-                } else if (relation.direction === "inverse" && relation.foreignKeyOnTarget && db && registry) {
+                } else if (hasForeignKeyOnTarget(relation) && db && registry) {
                     // Inverse relation: FK is in target table, need to query for it
                     try {
                         const targetCollection = relation.target();
@@ -368,7 +359,7 @@ export async function parseDataFromServer<M extends Record<string, unknown>>(
                     } catch (e) {
                         logger.warn(`Could not resolve inverse relation property: ${propKey}`, { error: e });
                     }
-                } else if (relation.direction === "inverse" && relation.joinPath && db && registry) {
+                } else if (relation.kind === "via" && db && registry) {
                     // Join path relation: Multi-hop relation using joins
                     try {
                         const targetCollection = relation.target();
@@ -547,17 +538,16 @@ export function parsePropertyFromServer(value: unknown, property: Property, coll
         case "relation":
             // Transform ID back to relation object with type information
             if (typeof value === "string" || typeof value === "number") {
-                let relationDef: Relation | undefined = (property as RelationProperty).relation;
+                // Normalization stamps the resolved relation onto the property;
+                // fall back to the collection's map for a property that never
+                // went through the registry.
+                let relationDef: ResolvedRelation | undefined = (property as RelationProperty).resolvedRelation;
                 if (!relationDef && propertyKey) {
-                    const resolvedRelations = resolveCollectionRelations(collection);
-                    relationDef = findRelation(resolvedRelations, propertyKey);
-                }
-                if (!relationDef) {
-                    relationDef = collection.relations?.find((rel: Relation) => rel.relationName === (property as RelationProperty).relationName);
+                    relationDef = findRelation(resolveCollectionRelations(collection), propertyKey);
                 }
 
                 if (!relationDef) {
-                    logger.warn(`Relation not defined in property for key: ${propertyKey || "unknown"}`);
+                    logger.warn(`ResolvedRelation not defined in property for key: ${propertyKey || "unknown"}`);
                     return value;
                 }
 
@@ -683,7 +673,7 @@ function normalizeScalarValues<M extends Record<string, unknown>>(
     data: M,
     properties: Properties,
     collection: CollectionConfig,
-    resolvedRelations: Record<string, Relation>,
+    resolvedRelations: Record<string, ResolvedRelation>,
     options: { skipRelations: boolean }
 ): Record<string, unknown> {
     const result: Record<string, unknown> = {};
@@ -691,7 +681,7 @@ function normalizeScalarValues<M extends Record<string, unknown>>(
     // Identify FK columns used only for relations and not exposed as properties
     const internalFKColumns = new Set<string>();
     Object.values(resolvedRelations).forEach(relation => {
-        if (relation.localKey && !properties[relation.localKey]) {
+        if (relation.kind === "belongsTo" && !properties[relation.localKey]) {
             internalFKColumns.add(relation.localKey);
         }
     });

package/src/schema/doctor.ts

@@ -12,7 +12,7 @@ import * as fs from "fs";
 import path from "path";
 import { pathToFileURL } from "url";
 import chalk from "chalk";
-import { CollectionConfig, isPostgresCollectionConfig, Property, NumberProperty, StringProperty, DateProperty, ArrayProperty, MapProperty, RelationProperty } from "@rebasepro/types";
+import { CollectionConfig, isPostgresCollectionConfig, Property, NumberProperty, StringProperty, DateProperty, ArrayProperty, MapProperty, RelationProperty, type ResolvedManyToMany, type ResolvedBelongsTo, isManyToMany } from "@rebasepro/types";
 import { generateSchema } from "./generate-drizzle-schema-logic";
 import { generateTypedefs } from "@rebasepro/codegen";
 import { getTableName, resolveCollectionRelations, findRelation } from "@rebasepro/common";
@@ -62,12 +62,10 @@ export function getExpectedColumnType(prop: Property): string | null {
             if (sp.enum) return "USER-DEFINED"; // pgEnum → USER-DEFINED in information_schema
             if ("isId" in sp && sp.isId === "uuid") return "uuid";
             if (sp.columnType === "uuid") return "uuid";
-            // A markdown/multiline string compiles to `text`, not varchar — the
-            // generator treats those UI hints as column-type signals, so the
-            // expectation here must too or every such column reads as drift.
-            if (sp.columnType === "text" || sp.ui?.markdown || sp.ui?.multiline) return "text";
             if (sp.columnType === "char") return "character";
-            return "character varying";
+            if (sp.columnType === "varchar") return "character varying";
+            // `text` is the default — see generate-postgres-ddl-logic.
+            return "text";
         }
         case "number": {
             const np = prop as NumberProperty;
@@ -122,7 +120,9 @@ export function getExpectedColumnType(prop: Property): string | null {
         case "relation":
             return null; // FK columns are derived from the relation, not from the property
         case "reference":
-            return "character varying"; // References default to varchar FK
+            // A reference FK follows the key it points at, and a string key is
+            // `text` — see generate-postgres-ddl-logic.
+            return "text";
         case "vector":
             return "USER-DEFINED";
         case "binary":
@@ -387,7 +387,7 @@ export async function checkCollectionsVsDatabase(
 
         for (const collection of postgresCollections) {
             const tableName = getTableName(collection);
-            const schemaName = collection.schema || "public";
+            const schemaName = (collection as { schema?: string }).schema || "public";
             const fullTableName = schemaName === "public" ? tableName : `${schemaName}.${tableName}`;
 
             // Check table existence
@@ -411,10 +411,10 @@ export async function checkCollectionsVsDatabase(
             // Check properties → columns
             for (const [propName, prop] of Object.entries(collection.properties ?? {})) {
                 if (prop.type === "relation") {
-                    // Relation columns are derived from localKey
+                    // ResolvedRelation columns are derived from localKey
                     const resolvedRelations = resolveCollectionRelations(collection);
-                    const relation = findRelation(resolvedRelations, (prop as RelationProperty).relationName ?? propName);
-                    if (relation?.direction === "owning" && relation.cardinality === "one" && relation.localKey) {
+                    const relation = findRelation(resolvedRelations, (prop as RelationProperty).relation?.relationName ?? propName);
+                    if (relation?.kind === "belongsTo") {
                         const fkColName = relation.localKey;
                         if (!dbColumnMap.has(fkColName)) {
                             issues.push({
@@ -434,7 +434,7 @@ export async function checkCollectionsVsDatabase(
                         try {
                             const targetColl = relation.target();
                             targetTableName = getTableName(targetColl);
-                            targetSchemaName = targetColl.schema || "public";
+                            targetSchemaName = (targetColl as { schema?: string }).schema || "public";
                         } catch { /* ignore */ }
 
                         const hasFk = tableFks.some((fk) =>
@@ -568,9 +568,9 @@ export async function checkCollectionsVsDatabase(
             // Also check junction tables for many-to-many relations
             const resolvedRelations = resolveCollectionRelations(collection);
             for (const relation of Object.values(resolvedRelations)) {
-                if (relation.cardinality === "many" && relation.direction === "owning" && relation.through) {
+                if (isManyToMany(relation)) {
                     const junctionTable = relation.through.table;
-                    const junctionSchema = collection.schema || "public";
+                    const junctionSchema = (collection as { schema?: string }).schema || "public";
                     const fullJunctionTable = junctionSchema === "public" ? junctionTable : `${junctionSchema}.${junctionTable}`;
                     if (!existingTables.has(fullJunctionTable)) {
                         issues.push({