@rebasepro/server-postgres 0.12.1-canary.g4e7bcbf → 0.12.1-canary.g52d71ee

package/dist/services/collection-helpers.d.ts

@@ -1,7 +1,7 @@
 import { PgTable, AnyPgColumn } from "drizzle-orm/pg-core";
-import { CollectionConfig } from "@rebasepro/types";
+import { CollectionConfig, ResolvedHasMany, ResolvedHasOne } from "@rebasepro/types";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
-export { buildCompositeId, parseIdValues, COMPOSITE_ID_SEPARATOR } from "@rebasepro/common";
+export { buildCompositeId, parseIdValues, isAddressableId, COMPOSITE_ID_SEPARATOR } from "@rebasepro/common";
 export type { PrimaryKeyInfo } from "@rebasepro/common";
 import type { PrimaryKeyInfo } from "@rebasepro/common";
 /**
@@ -22,6 +22,17 @@ export interface DrizzleColumnMeta {
 }
 /** Safely extract Drizzle column metadata from a column object. */
 export declare function getColumnMeta(col: AnyPgColumn): DrizzleColumnMeta;
+/**
+ * Whether an address could name a row in this table, judged by the columns.
+ *
+ * {@link getPrimaryKeys} lets a config's `isId: "uuid"` win over the schema, so
+ * its `isUUID` is a claim rather than a fact — right for deriving addresses,
+ * wrong for refusing a query. Here the Drizzle column type decides, because it
+ * is what Postgres will enforce: a `uuid` column meets `/c/products/new` with
+ * `22P02`, which aborts the surrounding transaction and turns every later
+ * statement into an unrelated-looking `25P02`.
+ */
+export declare function idCanAddressTable(id: string | number, table: PgTable, idInfoArray: PrimaryKeyInfo[]): boolean;
 export declare function getCollectionByPath(collectionPath: string, registry: PostgresCollectionRegistry): CollectionConfig;
 export declare function getTableForCollection(collection: CollectionConfig, registry: PostgresCollectionRegistry): PgTable<any>;
 /**
@@ -55,6 +66,29 @@ export declare function getPrimaryKeys(collection: CollectionConfig, registry: P
  * wrong and which collection it is wrong about.
  */
 export declare function requirePrimaryKeys(collection: CollectionConfig, registry: PostgresCollectionRegistry): PrimaryKeyInfo[];
+/**
+ * The column on the *source* table that a `hasOne`/`hasMany` link points at.
+ *
+ * `sourceKey` is authored when the two sides join on a natural key — an
+ * external identity id, a SKU — and left off when they join on the row id,
+ * which is the overwhelming majority. That makes `undefined` the only optional
+ * field on a resolved relation, so it gets exactly one reader: this function.
+ * Every consumer that needs the column asks here, and none of them re-derives
+ * "or else the primary key" for itself. That is the whole point — the fallback
+ * chains this codebase removed from relation resolution were dangerous because
+ * they were *duplicated* and could disagree, not because they existed.
+ */
+export declare function sourceKeyField(relation: ResolvedHasOne | ResolvedHasMany, sourceCollection: CollectionConfig, registry: PostgresCollectionRegistry): string;
+/**
+ * Whether this link joins on something other than the source's primary key.
+ *
+ * Callers that hold a parent *id* — which is most of them, since an id is what
+ * a URL carries — must translate it to the source key's value before it can be
+ * compared with the target's foreign key. Those that hold the parent *row*, or
+ * that build a correlated subquery over the source table, can read the column
+ * directly and skip the lookup.
+ */
+export declare function joinsOnNaturalKey(relation: ResolvedHasOne | ResolvedHasMany, sourceCollection: CollectionConfig, registry: PostgresCollectionRegistry): boolean;
 /**
  * Collections whose key the *browser* cannot resolve, and what it will do
  * instead.

package/dist/{src-BkdpiQdw.js → src-DlPBctw_.js}

@@ -1458,6 +1458,34 @@ function createRelationRefWithData(id, path, data) {
 		data
 	};
 }
+/** The eight-four-four-four-twelve shape of a UUID, any version. */
+var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Whether one address part can be a value of the column it addresses. */
+function partIsAddressable(part, pk) {
+	if (pk.isUUID) return UUID_PATTERN.test(String(part));
+	if (pk.type === "number") return typeof part === "number" ? Number.isFinite(part) : !isNaN(parseInt(String(part), 10));
+	return true;
+}
+/**
+* Whether an address could name a row at all, before asking the database.
+*
+* A `uuid` column cannot hold `"new"`, and an `integer` column cannot hold
+* `"abc"` — so the answer to "which row is this" is "none", and that is a 404,
+* not a failure. Postgres cannot say so politely: the comparison never runs, it
+* raises `22P02` and aborts the enclosing transaction, after which every
+* further statement returns the far less helpful `25P02`.
+*
+* `isUUID` must come from the column, not from `isId: "uuid"` in a config: the
+* config is a claim about a key, and a `text` column that holds ids of some
+* other shape is a working app this must not start rejecting.
+*/
+function isAddressableId(idValue, primaryKeys) {
+	if (primaryKeys.length === 0) return false;
+	if (primaryKeys.length === 1) return partIsAddressable(idValue, primaryKeys[0]);
+	const parts = String(idValue).split(":::");
+	if (parts.length !== primaryKeys.length) return false;
+	return parts.every((part, i) => partIsAddressable(part, primaryKeys[i]));
+}
 /**
 * Derive a row's address from its key columns.
 *
@@ -1598,8 +1626,7 @@ function enumToObjectEntries(enumValues) {
 function resolveRelation(relation, sourceCollection, propertyKey) {
 	const target = relation.target;
 	if (typeof target !== "function") throw new Error(`Relation${relation.relationName ? ` '${relation.relationName}'` : ""} on '${sourceCollection.slug}' has no \`target\`. Give it a thunk: \`target: () => otherCollection\`.`);
-	const targetCollection = target();
-	if (!targetCollection?.slug) throw new Error(`Relation${relation.relationName ? ` '${relation.relationName}'` : ""} on '${sourceCollection.slug}' has a \`target\` that did not resolve to a collection.`);
+	const targetCollection = callTarget(relation, sourceCollection, propertyKey, target);
 	const relationName = relation.relationName ?? propertyKey ?? toSnakeCase(targetCollection.slug);
 	const shared = {
 		relationName,
@@ -1626,7 +1653,8 @@ function resolveRelation(relation, sourceCollection, propertyKey) {
 			cardinality: "one",
 			writable: true,
 			shared: false,
-			foreignKeyOnTarget: relation.foreignKeyOnTarget ?? generateForeignKeyName(sourceName)
+			foreignKeyOnTarget: relation.foreignKeyOnTarget ?? generateForeignKeyName(sourceName),
+			sourceKey: relation.sourceKey
 		};
 		case "hasMany": return {
 			...shared,
@@ -1634,7 +1662,8 @@ function resolveRelation(relation, sourceCollection, propertyKey) {
 			cardinality: "many",
 			writable: true,
 			shared: false,
-			foreignKeyOnTarget: relation.foreignKeyOnTarget ?? generateForeignKeyName(sourceName)
+			foreignKeyOnTarget: relation.foreignKeyOnTarget ?? generateForeignKeyName(sourceName),
+			sourceKey: relation.sourceKey
 		};
 		case "manyToMany": {
 			const sourceTable = getTableName(sourceCollection);
@@ -1663,6 +1692,43 @@ function resolveRelation(relation, sourceCollection, propertyKey) {
 		default: throw new Error(`Unknown relation kind: ${JSON.stringify(relation)}`);
 	}
 }
+/** How this relation is addressed in an error message, before it has a resolved name. */
+function describe(relation, sourceCollection, propertyKey) {
+	const name = relation.relationName ?? propertyKey;
+	return `Relation${name ? ` '${name}'` : ""} on '${sourceCollection.slug}'`;
+}
+/**
+* Call the `target` thunk, and translate the two ways an import cycle breaks it
+* into an error that names the cause.
+*
+* The thunk exists to defer the reference until every module has finished
+* evaluating, and for a cycle that closes at import time it does. What it cannot
+* defer is a cycle that leaves the binding permanently unusable, and there are
+* two shapes of that:
+*
+*  - **ESM/TDZ.** `const` and `class` bindings in a not-yet-evaluated module are
+*    in the temporal dead zone, so reading one throws `ReferenceError: x is not
+*    defined`. The stack points at the thunk — a one-line arrow function that is
+*    obviously fine — and says nothing about the cycle that made it throw.
+*  - **CJS interop.** The half-initialised module object has no `default` yet,
+*    the import resolves to `undefined`, and the thunk returns it without
+*    complaint. That one used to surface here as "did not resolve to a
+*    collection", which is true and unhelpful.
+*
+* Both mean the same thing, and the fix for both is the same: break the cycle,
+* or move the relation into the collection that does not close it.
+*/
+function callTarget(relation, sourceCollection, propertyKey, target) {
+	let targetCollection;
+	try {
+		targetCollection = target();
+	} catch (error) {
+		if (error instanceof ReferenceError) throw new Error(`${describe(relation, sourceCollection, propertyKey)} targets a collection that is not initialized yet — almost always an import cycle between the two collection files. Break the cycle (move the shared piece into a third module, or import the target lazily) so the target's module finishes evaluating before the registry is built.`, { cause: error });
+		throw error;
+	}
+	if (!targetCollection?.slug) throw new Error(`${describe(relation, sourceCollection, propertyKey)} has a \`target\` that resolved to ${targetCollection === void 0 ? "`undefined`" : "something that is not a collection"}. ` + (targetCollection === void 0 ? "Under CommonJS interop an import cycle resolves the default import to `undefined`, so check whether this collection and its target import each other. Otherwise the thunk is returning the wrong value — it must return the collection itself, not a promise or a module." : "The thunk must return a collection config with a `slug`."));
+	return targetCollection;
+}
 //#endregion
 //#region ../common/src/util/relations.ts
 /**
@@ -4228,6 +4294,6 @@ function buildSdkData(driver) {
 	return wrapAsSdkData(buildRebaseData(driver));
 }
 //#endregion
-export { DEFAULT_ONE_OF_TYPE as A, updateDateAutoValues as C, mergeDeep as D, getPolicyNamesForRule as E, hasForeignKeyOnTarget as M, isManyToMany as N, camelCase as O, Vector as P, normalizeToEntityRelation as S, legacyForeignKeyName as T, buildCompositeId as _, getJunctionSecurityRules as a, createRelationRef as b, policyToPostgres as c, findRelation as d, getColumnName as f, resolveCollectionRelations as g, getTableVarName as h, getJunctionCollectionConfig as i, DEFAULT_ONE_OF_VALUE as j, toSnakeCase as k, securityRuleToConditions as l, getTableName as m, CollectionRegistry as n, resolveJunctionSpecs as o, getEnumVarName as p, resolveStringColumnLength as r, getEffectiveSecurityRules as s, buildSdkData as t, findAnonymousGrants as u, getDeclaredPrimaryKeys as v, generateForeignKeyName as w, createRelationRefWithData as x, parseIdValues as y };
+export { toSnakeCase as A, normalizeToEntityRelation as C, getPolicyNamesForRule as D, legacyForeignKeyName as E, Vector as F, DEFAULT_ONE_OF_VALUE as M, hasForeignKeyOnTarget as N, mergeDeep as O, isManyToMany as P, createRelationRefWithData as S, generateForeignKeyName as T, buildCompositeId as _, getJunctionSecurityRules as a, parseIdValues as b, policyToPostgres as c, findRelation as d, getColumnName as f, resolveCollectionRelations as g, getTableVarName as h, getJunctionCollectionConfig as i, DEFAULT_ONE_OF_TYPE as j, camelCase as k, securityRuleToConditions as l, getTableName as m, CollectionRegistry as n, resolveJunctionSpecs as o, getEnumVarName as p, resolveStringColumnLength as r, getEffectiveSecurityRules as s, buildSdkData as t, findAnonymousGrants as u, getDeclaredPrimaryKeys as v, updateDateAutoValues as w, createRelationRef as x, isAddressableId as y };
 
-//# sourceMappingURL=src-BkdpiQdw.js.map
+//# sourceMappingURL=src-DlPBctw_.js.map