uql-orm 0.65.0 → 0.65.1

package/dist/entity/metadata/definition.d.ts

@@ -71,6 +71,6 @@ export declare function getMeta<E>(entity: Type<E>): EntityMeta<E>;
 /**
  * The foreign keys an entity holds: each owning to-one's columns, and each `@Field({ references })` no
  * relation joins on, as the many-to-one it describes, once its target has registered a key. What the
- * schema build constrains and a junction joins by.
+ * schema build constrains and a junction joins by, read once the relations holding them are settled.
  */
 export declare function foreignKeysOf<E>(meta: EntityMeta<E>): RelationMeta[];

package/dist/entity/metadata/definition.js

@@ -306,74 +306,88 @@ function ensureMeta(entity) {
     return meta;
 }
 export function getMeta(entity) {
+    const meta = registeredMeta(entity);
+    // Stamped once finalizing succeeds, so a read after a failure reports the same mistake again. Finalizing
+    // reads other entities without resolving them, so no entity is ever read half resolved.
+    if (meta.processedAt !== meta.revision) {
+        fillRelations(meta);
+        meta.processedAt = meta.revision;
+    }
+    return meta;
+}
+/** The metadata `entity` registered, however much of it is resolved. */
+function registeredMeta(entity) {
     const meta = metas.get(entity);
     if (!meta) {
         throw TypeError(`'${entity.name}' is not an entity`);
     }
-    if (meta.processedAt === meta.revision) {
-        return meta;
-    }
-    // Stamped before finalizing: `fillInverseSide` reads the other side through `getMeta`, and with each
-    // side mapped by the other that recursion has to find this half-filled meta rather than run again.
-    // Unstamped when finalizing throws, so the next read reports the same mistake; running it again is
-    // harmless, since every step skips what it settled.
-    meta.processedAt = meta.revision;
-    try {
-        return fillRelations(meta);
-    }
-    catch (error) {
-        meta.processedAt = undefined;
-        throw error;
-    }
+    return meta;
 }
 function fillRelations(meta) {
     for (const [relKey, relation] of definedEntries(meta.relations)) {
-        // The registered view: `references` may be unset, or the one column a to-one names, until this settles it.
-        const relOpts = relation;
         const at = `'${meta.entity.name}.${relKey}'`;
-        const references = relOpts.mappedBy
-            ? fillInverseSide(at, meta, relOpts, relOpts.mappedBy)
-            : (pairedReferences(at, relOpts) ?? fillOwningSide(at, meta, relKey, relOpts));
-        if (!references.length) {
+        if (!settledReferences(at, meta, relKey, relation).length) {
             throw new TypeError(`${at} has no columns to join on.`);
         }
     }
     // A column `references` names is a foreign key with or without a relation over it, and one cannot point
     // at a composite key: refused on first read, as a relation that cannot join is, not at the schema build.
     foreignKeysOf(meta);
-    return meta;
 }
 /**
- * The pairs a relation joins on, with the one column a to-one names paired with the target's primary key:
- * on first read rather than at registration, which can run before the target has a key to pair with.
+ * The pairs a relation joins on, settled on first read, whether its own entity is being resolved or another
+ * needs it. Never resolving an entity is what keeps it from recursing, and the one column a to-one names is
+ * paired with its target's key only here, since registration can run before the target has one.
  */
-function pairedReferences(at, relOpts) {
-    const { references } = relOpts;
-    if (typeof references !== 'string') {
-        return references;
+function settledReferences(at, meta, relKey, relOpts) {
+    const { references, mappedBy, through } = relOpts;
+    if (typeof references === 'string') {
+        const target = ensureMeta(relOpts.entity());
+        if (mappedBy || isToManyRelation(relOpts) || target.ids.length > 1) {
+            throw new TypeError(`${at} names one column, '${references}', which only a to-one holding a foreign key to a one-column key ` +
+                'can: pair the columns, [{ local, foreign }].');
+        }
+        relOpts.references = [{ local: references, foreign: soleIdOf(target, 'a foreign key') }];
+        return relOpts.references;
     }
-    const target = ensureMeta(relOpts.entity());
-    if (relOpts.mappedBy || isToManyRelation(relOpts) || target.ids.length > 1) {
-        throw new TypeError(`${at} names one column, '${references}', which only a to-one holding a foreign key to a one-column key ` +
-            'can: pair the columns, [{ local, foreign }].');
+    if (references)
+        return references;
+    if (mappedBy)
+        return fillInverseSide(at, meta, relOpts, mappedBy);
+    if (through)
+        return fillThrough(at, meta, relOpts, through);
+    return fillOwningSide(at, meta, relKey, relOpts);
+}
+/**
+ * Settles each relation joining on its own entity's columns, every one but an inverse side and a `through`:
+ * the columns they create and the foreign keys they hold are what another entity reads off this one.
+ */
+function settleOwnColumns(meta) {
+    for (const [relKey, relation] of definedEntries(meta.relations)) {
+        if (!relation.mappedBy && !relation.through) {
+            settledReferences(`'${meta.entity.name}.${relKey}'`, meta, relKey, relation);
+        }
     }
-    relOpts.references = [{ local: references, foreign: soleIdOf(target, 'a foreign key') }];
+}
+/**
+ * Each key of this entity, then each of the target, paired with the junction's one column referencing it.
+ * Both groups live on the junction whatever the cardinality, as `deleteRelations` and every dialect read
+ * them, and a composite key gives a pair per column, which is what makes a join address a whole key.
+ */
+function fillThrough(at, meta, relOpts, through) {
+    const junction = registeredMeta(through());
+    relOpts.references = [
+        ...junctionReferences(at, junction, meta),
+        ...junctionReferences(at, junction, ensureMeta(relOpts.entity())),
+    ];
     return relOpts.references;
 }
 function fillOwningSide(at, meta, relKey, relOpts) {
-    const relMeta = ensureMeta(relOpts.entity());
-    if (relOpts.through) {
-        // Both columns live on the junction, whatever the cardinality: `deleteRelations` and every dialect
-        // read them as junction columns. A composite key contributes one pair per column of it, which is
-        // what makes the join address a whole key rather than part.
-        const junction = getMeta(relOpts.through());
-        relOpts.references = [...junctionReferences(at, junction, meta), ...junctionReferences(at, junction, relMeta)];
-        return relOpts.references;
-    }
     if (isToManyRelation(relOpts)) {
         throw new TypeError(`${at} is a to-many relation with no way to join: it needs 'mappedBy' (the field on the other side), ` +
             "'through' (a junction entity), or 'references' (the columns).");
     }
+    const relMeta = ensureMeta(relOpts.entity());
     // `<rel>Id` for the one-key case it has always been; `<rel><Key>` per column otherwise. Both name a
     // property, so both are spelled from the referenced *property* - a column name is what the naming
     // strategy makes of this afterwards.
@@ -406,14 +420,13 @@ function fillOwningSide(at, meta, relKey, relOpts) {
     return references;
 }
 function fillInverseSide(at, meta, relOpts, mappedBy) {
-    const relEntity = relOpts.entity();
-    const relMeta = getMeta(relEntity);
-    const own = pairedReferences(at, relOpts);
-    if (own)
-        return own;
+    const relMeta = registeredMeta(relOpts.entity());
+    const other = `'${relMeta.entity.name}.${mappedBy}'`;
+    // The other side's own columns first: they declare, or create, what this side is mapped by.
+    settleOwnColumns(relMeta);
     if (relMeta.fields[mappedBy]) {
         if (meta.ids.length > 1) {
-            throw new TypeError(`${at} is mapped by '${relEntity.name}.${mappedBy}', one column, but the primary key of ` +
+            throw new TypeError(`${at} is mapped by ${other}, one column, but the primary key of ` +
                 `'${meta.entity.name}' is composite (${meta.ids.join(', ')}). Map it by the relation on the other side ` +
                 'instead, which joins every column of the key.');
         }
@@ -421,16 +434,14 @@ function fillInverseSide(at, meta, relOpts, mappedBy) {
         relOpts.references = [{ local: meta.ids[0], foreign: mappedBy }];
         return relOpts.references;
     }
-    // Authored view again: with each side mapped by the other, the target is still mid-resolution here and
-    // its own `references` are unset, which is what the second throw reports.
     const owner = relMeta.relations[mappedBy];
     if (!owner) {
-        throw new TypeError(`${at} is mapped by '${mappedBy}', which is neither a field nor a relation of '${relEntity.name}'.`);
+        throw new TypeError(`${at} is mapped by '${mappedBy}', which is neither a field nor a relation of '${relMeta.entity.name}'.`);
     }
-    const ownerReferences = pairedReferences(`'${relEntity.name}.${mappedBy}'`, owner);
-    if (!ownerReferences?.length) {
-        throw new TypeError(`${at} is mapped by '${relEntity.name}.${mappedBy}', an inverse side too, so neither owns the foreign key.`);
+    if (owner.mappedBy) {
+        throw new TypeError(`${at} is mapped by ${other}, an inverse side too, so neither owns the foreign key.`);
     }
+    const ownerReferences = settledReferences(other, relMeta, mappedBy, owner);
     // Two different flips: a junction's pairs are the owner's group followed by ours, so the two groups
     // swap - `toReversed` would also reverse each group, pairing a composite's columns crosswise. A
     // plain foreign key is one pair per key whose ends swap.
@@ -444,12 +455,13 @@ function fillInverseSide(at, meta, relOpts, mappedBy) {
 /**
  * The foreign keys an entity holds: each owning to-one's columns, and each `@Field({ references })` no
  * relation joins on, as the many-to-one it describes, once its target has registered a key. What the
- * schema build constrains and a junction joins by.
+ * schema build constrains and a junction joins by, read once the relations holding them are settled.
  */
 export function foreignKeysOf(meta) {
+    settleOwnColumns(meta);
     const owning = definedEntries(meta.relations)
         .map(([, relation]) => relation)
-        .filter(({ cardinality, mappedBy }) => cardinality === 'm1' || (cardinality === '11' && !mappedBy));
+        .filter((relation) => !relation.mappedBy && !relation.through && !isToManyRelation(relation));
     const joined = new Set(owning.flatMap(({ references }) => references.map(({ local }) => local)));
     const columns = definedEntries(meta.fields).flatMap(([key, field]) => {
         if (!field.references || joined.has(key))

package/dist/type/entity.d.ts

@@ -558,10 +558,9 @@ type RelationReferencePairs<E, O> = (local: KeyMap<O>, foreign: KeyMap<E>) => re
  * assertions - `fillRelations` establishes the invariant once, and throws where it cannot.
  *
  * `entity` and `through` stay {@link EntityGetter}s. Resolution could call them once and store the class,
- * but only by keeping the authored relations in a second map: it reads them *across* entities, and a
- * circular import can leave the entity being read mid-resolution, where telling "no such relation" apart
- * from "declared, but an inverse side too, so neither owns the foreign key" needs the unresolved shape
- * still there to find. A phase-split metadata map costs more than the call parentheses it saves.
+ * but only by keeping the authored relations in a second map: it settles them in place, reading them across
+ * entities not resolved yet, so the authored and the settled shape have to be one object. A phase-split
+ * metadata map costs more than the call parentheses it saves.
  */
 export type RelationMeta = Omit<RelationRegistration, 'references'> & {
     references: RelationReferences;

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "The JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.65.0",
+  "version": "0.65.1",
   "type": "module",
   "engines": {
     "node": ">=24"