uql-orm 0.24.0 → 0.24.2

package/README.md

@@ -50,8 +50,8 @@ from the browser to the server. The same object runs on every supported database
 
 ## Why UQL?
 
-- **The fastest.** Wins [all 8 categories](https://uql-orm.dev/benchmark) of our [open benchmark](https://github.com/rogerpadilla/ts-orm-benchmark), beating even query builders like Knex and Kysely: ~2.3× faster than the runner-up on average, close to 4M ops/s on simple SELECTs.
-- **Light.** Zero dependencies, under 1 MB installed, every dialect included.
+- **The fastest.** Wins [all 8 categories](https://uql-orm.dev/benchmark) of our [open benchmark](https://github.com/rogerpadilla/ts-orm-benchmark), beating even query builders like Knex and Kysely: ~2.4× faster than the runner-up on average, over 4.6M ops/s on simple SELECTs.
+- **Light.** Zero runtime dependencies, 288 kB on the wire, every dialect included.
 - **Queries are data, not method chains.** Plain JSON in, typed rows out. There's no DSL to learn and nothing to compile.
 - **Type-safe to the leaf.** Operators are gated per field type, and JSON/JSONB dot-paths resolve each path's value type, so `{ age: { $like: 'x' } }` or a typo'd path is a compile error instead of a runtime surprise.
 - **No codegen.** Entities are TypeScript classes, so your code *is* the schema. No `.prisma` file to regenerate, no generated client to keep in sync.

package/dist/dialect/abstractSqlDialect.d.ts

@@ -1,4 +1,4 @@
-import { type EntityMeta, type FieldKey, type FieldOptions, type IsolationLevel, type JsonColumnType, type JsonUpdateOp, type Query, type QueryAggMap, type QueryAggregate, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryDialect, type QueryExclude, type QueryGroupMap, type QueryHavingMap, type QueryOptions, type QueryPager, type QueryPopulate, QueryRaw, type QueryRawFnOptions, type QuerySearch, type QuerySelect, type QuerySelectOptions, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOperatorMap, type QueryWhereMap, type QueryWhereOptions, type RelationOptions, type SqlDialectName, type SqlQueryDialect, type Type, type UpdatePayload } from '../type/index.js';
+import { type EntityMeta, type FieldKey, type FieldOptions, type IsolationLevel, type JsonColumnType, type JsonUpdateOp, type Query, type QueryAggMap, type QueryAggregate, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryDialect, type QueryExclude, type QueryGroupMap, type QueryHavingMap, type QueryOptions, type QueryPager, type QueryPopulate, QueryRaw, type QueryRawFnOptions, type QuerySearch, type QuerySelect, type QuerySelectOptions, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOperatorMap, type QueryWhereMap, type QueryWhereOptions, type RelationMeta, type SqlDialectName, type SqlQueryDialect, type Type, type UpdatePayload } from '../type/index.js';
 import { IndexSqlDialect } from './indexSqlDialect.js';
 /** How a column's values are bound: see {@link AbstractSqlDialect.persistKind}. */
 type PersistKind = 'plain' | 'json' | 'vector';
@@ -340,9 +340,9 @@ export declare abstract class AbstractSqlDialect extends IndexSqlDialect impleme
      */
     private appendRelationSubquery;
     /** Filter by relation: a parent matches when {@link appendRelationSubquery} finds one target row. */
-    protected compareRelation<E>(ctx: QueryContext, entity: Type<E>, key: string, val: QueryWhereMap<unknown>, rel: RelationOptions, opts: QueryComparisonOptions): void;
+    protected compareRelation<E>(ctx: QueryContext, entity: Type<E>, val: QueryWhereMap<unknown>, rel: RelationMeta, opts: QueryComparisonOptions): void;
     /** Filter by relation size: the same subquery, counting instead of testing for existence. */
-    protected compareRelationSize<E>(ctx: QueryContext, entity: Type<E>, key: string, sizeVal: number | QuerySizeComparisonOps, rel: RelationOptions, opts: QueryComparisonOptions): void;
+    protected compareRelationSize<E>(ctx: QueryContext, entity: Type<E>, sizeVal: number | QuerySizeComparisonOps, rel: RelationMeta, opts: QueryComparisonOptions): void;
     /**
      * Build a complete `$size` comparison expression.
      * Handles both single and multiple comparison operators by repeating the size expression.

package/dist/dialect/abstractSqlDialect.js

@@ -215,7 +215,7 @@ export class AbstractSqlDialect extends IndexSqlDialect {
             const joinAlias = this.escapeId(joinRelAlias, true);
             ctx.append(` ${joinType} JOIN ${relEntityName} ${joinAlias} ON `);
             let refAppended = false;
-            for (const it of relOpts.references ?? []) {
+            for (const it of relOpts.references) {
                 if (refAppended)
                     ctx.append(' AND ');
                 const relField = relMeta.fields[it.foreign];
@@ -246,7 +246,7 @@ export class AbstractSqlDialect extends IndexSqlDialect {
         const prefix = opts.prefix;
         for (const relKey of relKeys) {
             const relOpts = meta.relations[relKey];
-            if (!relOpts?.entity)
+            if (!relOpts)
                 continue;
             const isFirstLevel = prefix === tableName;
             const joinRelAlias = isFirstLevel ? relKey : prefix ? `${prefix}.${relKey}` : relKey;
@@ -334,10 +334,10 @@ export class AbstractSqlDialect extends IndexSqlDialect {
         if (rel) {
             const sizeVal = parseRelationSize(val);
             if (sizeVal !== undefined) {
-                this.compareRelationSize(ctx, entity, key, sizeVal, rel, opts);
+                this.compareRelationSize(ctx, entity, sizeVal, rel, opts);
                 return;
             }
-            this.compareRelation(ctx, entity, key, val, rel, opts);
+            this.compareRelation(ctx, entity, val, rel, opts);
             return;
         }
         const value = this.normalizeWhereValue(val);
@@ -1304,12 +1304,9 @@ export class AbstractSqlDialect extends IndexSqlDialect {
      * invisible here just as it is to a joined `$populate`. The caller's filter bypass is deliberately
      * not propagated (`withDeleted()` does not reach into relations), matching `selectRelationJoins`.
      */
-    appendRelationSubquery(ctx, entity, key, rel, opts, projection, val) {
+    appendRelationSubquery(ctx, entity, rel, opts, projection, val) {
         const meta = getMeta(entity);
         const parentTable = this.resolveTableName(entity, meta);
-        if (!rel.references?.length) {
-            throw new TypeError(`Relation '${key}' on '${parentTable}' has no references defined`);
-        }
         const references = rel.references;
         const escapedParentId = this.escapedParentColumn(parentTable, meta, opts, meta.id);
         const relatedEntity = rel.entity();
@@ -1345,13 +1342,13 @@ export class AbstractSqlDialect extends IndexSqlDialect {
         ctx.append(')');
     }
     /** Filter by relation: a parent matches when {@link appendRelationSubquery} finds one target row. */
-    compareRelation(ctx, entity, key, val, rel, opts) {
+    compareRelation(ctx, entity, val, rel, opts) {
         ctx.append('EXISTS ');
-        this.appendRelationSubquery(ctx, entity, key, rel, opts, '1', val);
+        this.appendRelationSubquery(ctx, entity, rel, opts, '1', val);
     }
     /** Filter by relation size: the same subquery, counting instead of testing for existence. */
-    compareRelationSize(ctx, entity, key, sizeVal, rel, opts) {
-        this.buildSizeComparison(ctx, () => this.appendRelationSubquery(ctx, entity, key, rel, opts, 'COUNT(*)', {}), sizeVal);
+    compareRelationSize(ctx, entity, sizeVal, rel, opts) {
+        this.buildSizeComparison(ctx, () => this.appendRelationSubquery(ctx, entity, rel, opts, 'COUNT(*)', {}), sizeVal);
     }
     /**
      * Build a complete `$size` comparison expression.

package/dist/entity/metadata/definition.js

@@ -38,8 +38,11 @@ export function defineRelation(entity, key, opts) {
         throw new TypeError(`'${entity.name}.${key}' needs an 'entity' getter, e.g. '@ManyToOne({ entity: () => Company })'.`);
     }
     const meta = ensureMeta(entity);
-    const relKey = key;
-    meta.relations[relKey] = { ...meta.relations[relKey], ...opts };
+    // Registration writes the authored shape into a map declared as resolved: `getMeta` runs
+    // `fillRelations`, which settles `entity`, `references` and `mappedBy` or throws. Bridging the two
+    // shapes here is what lets every consumer read `RelationMeta` without asserting.
+    const relations = meta.relations;
+    relations[key] = { ...relations[key], ...opts };
     return meta;
 }
 export function defineHook(entity, methodName, event) {
@@ -182,114 +185,131 @@ export function getMeta(entity) {
 }
 function fillRelations(meta) {
     for (const relKey in meta.relations) {
+        // The authored view: `mappedBy` may still be the callback and `references` unset until this settles them.
         const relOpts = meta.relations[relKey];
         if (!relOpts)
             continue;
-        if (relOpts.references) {
-            // references were manually specified
-            continue;
-        }
+        const at = `'${meta.entity.name}.${relKey}'`;
         if (relOpts.mappedBy) {
-            fillInverseSideRelations(relOpts);
-            continue;
+            fillInverseSide(at, relOpts);
         }
-        const relEntity = relOpts.entity();
-        const relMeta = ensureMeta(relEntity);
-        if (relOpts.cardinality === 'mm') {
-            const idKey = meta.id;
-            const relIdKey = relMeta.id;
-            const idName = meta.fields[idKey]?.name ?? idKey;
-            const relIdName = relMeta.fields[relIdKey]?.name ?? relIdKey;
-            const source = lowerFirst(meta.name ?? '') + upperFirst(idName);
-            const target = lowerFirst(relMeta.name ?? '') + upperFirst(relIdName);
-            relOpts.references = [
-                { local: source, foreign: idKey },
-                { local: target, foreign: relIdKey },
-            ];
+        else if (!relOpts.references) {
+            fillOwningSide(at, meta, relKey, relOpts);
         }
-        else {
-            const relIdKey = relMeta.id;
-            const fkKey = `${relKey}Id`;
-            relOpts.references = [{ local: fkKey, foreign: relIdKey }];
-            // Auto-create the FK column when only the relation is declared (no explicit `@Field`).
-            // Mirror an explicit `@Field({ references })` column: carry `references` and mark the type
-            // as inferred so schema generation resolves the exact referenced primary-key type
-            // (columnType, length, chained keys) via `resolveColumnCanonicalType`.
-            if (!meta.fields[fkKey]) {
-                const relatedIdField = relMeta.fields[relIdKey];
-                meta.fields[fkKey] = {
-                    ...meta.fields[fkKey],
-                    name: fkKey,
-                    type: relatedIdField?.type ?? Number,
-                    references: relOpts.entity,
-                    typeFromReference: true,
-                };
-            }
+        if (!relOpts.references?.length) {
+            throw new TypeError(`${at} has no columns to join on.`);
         }
+        // Hand-written `references` land here too: naming the columns says which they are, not that they exist.
         if (relOpts.through) {
-            fillThroughRelations(relOpts.through());
+            const junction = getMeta(relOpts.through());
+            for (const { local } of relOpts.references) {
+                if (junction.fields[local])
+                    continue;
+                throw new TypeError(`${at} joins through '${junction.entity.name}', which has no '${local}' field. Declare it, or name ` +
+                    "the join columns with 'references'.");
+            }
         }
     }
+    fillForeignKeyRelations(meta);
     return meta;
 }
-function fillInverseSideRelations(relOpts) {
+function fillOwningSide(at, meta, relKey, relOpts) {
+    const relMeta = ensureMeta(relOpts.entity());
+    const relIdKey = relMeta.id;
+    if (relOpts.through) {
+        // Both columns live on the junction, whatever the cardinality: `fillToManyThroughRelation`,
+        // `deleteRelations` and every dialect read them as junction columns.
+        relOpts.references = [
+            { local: junctionColumn(meta, meta.id), foreign: meta.id },
+            { local: junctionColumn(relMeta, relIdKey), foreign: relIdKey },
+        ];
+        return;
+    }
+    if (relOpts.cardinality === '1m' || relOpts.cardinality === 'mm') {
+        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 fkKey = `${relKey}Id`;
+    relOpts.references = [{ local: fkKey, foreign: relIdKey }];
+    // `typeFromReference` so schema generation resolves the referenced primary key's exact type
+    // (columnType, length, chained keys) rather than trusting the fallback, as it does for an
+    // explicit `@Field({ references })`.
+    if (!meta.fields[fkKey]) {
+        meta.fields[fkKey] = {
+            name: fkKey,
+            type: relMeta.fields[relIdKey]?.type ?? Number,
+            references: relOpts.entity,
+            typeFromReference: true,
+        };
+    }
+}
+function fillInverseSide(at, relOpts) {
     const relEntity = relOpts.entity();
     const relMeta = getMeta(relEntity);
-    const mappedBy = getMappedByRelationKey(relOpts);
+    const mappedBy = getMappedByKey(relOpts);
     relOpts.mappedBy = mappedBy;
+    if (relOpts.references)
+        return;
     if (relMeta.fields[mappedBy]) {
         relOpts.references = [{ local: relMeta.id, foreign: mappedBy }];
         return;
     }
-    const mappedByRelation = relMeta.relations[mappedBy];
-    if (!mappedByRelation)
-        return;
-    if (relOpts.cardinality === 'm1' || relOpts.cardinality === 'mm') {
-        relOpts.references = (mappedByRelation.references ?? []).slice().reverse();
-        relOpts.through = mappedByRelation.through;
-        return;
+    // 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}'.`);
     }
-    relOpts.references = (mappedByRelation.references ?? []).map(({ local, foreign }) => ({
-        local: foreign,
-        foreign: local,
-    }));
-}
-function fillThroughRelations(entity) {
-    const meta = ensureMeta(entity);
-    meta.relations = getKeys(meta.fields).reduce((relations, key) => {
-        const field = meta.fields[key];
-        if (!field)
-            return relations;
-        if (field.references) {
-            const relEntity = field.references();
-            const relMeta = ensureMeta(relEntity);
-            const relIdKey = relMeta.id;
-            const relKey = key.slice(0, -relIdKey.length);
-            const relOpts = {
-                entity: field.references,
-                cardinality: 'm1',
-                references: [{ local: key, foreign: relIdKey }],
-            };
-            relations[relKey] = relOpts;
-        }
-        return relations;
-    }, {});
+    if (!owner.references?.length) {
+        throw new TypeError(`${at} is mapped by '${relEntity.name}.${mappedBy}', an inverse side too, so neither owns the foreign key.`);
+    }
+    // Two different flips: a junction pair is `[thisSide, otherSide]`, so the array reverses; a plain
+    // foreign key is one pair whose ends swap.
+    relOpts.references =
+        relOpts.cardinality === 'm1' || relOpts.cardinality === 'mm'
+            ? owner.references.toReversed()
+            : owner.references.map(({ local, foreign }) => ({ local: foreign, foreign: local }));
+    relOpts.through = owner.through;
 }
-function getMappedByRelationKey(relOpts) {
-    if (typeof relOpts.mappedBy === 'function') {
-        const relEntity = relOpts.entity();
-        const relMeta = ensureMeta(relEntity);
-        const keyMap = getRelationKeyMap(relMeta);
-        return relOpts.mappedBy(keyMap);
+/**
+ * A field carrying `references` is a foreign key, and a foreign key is a many-to-one whether or not
+ * anyone declared the relation. Deriving it everywhere is what lets a junction be written as two plain
+ * columns: it needs the relations for `$populate` and for its DDL constraints, and it used to get them
+ * only because some *other* entity pointed `through` at it. Gaps only, so a declared relation keeps its
+ * own cardinality and `cascade`.
+ */
+function fillForeignKeyRelations(meta) {
+    const joined = new Set(getKeys(meta.relations).flatMap((key) => meta.relations[key]?.references.map(({ local }) => local) ?? []));
+    for (const fieldKey of getKeys(meta.fields)) {
+        const references = meta.fields[fieldKey]?.references;
+        if (!references || joined.has(fieldKey))
+            continue;
+        const foreign = ensureMeta(references()).id;
+        // The relation takes the column's name minus the key it points at (`itemId` -> `item`); a column
+        // named anything else has no name to take, so it stays a plain foreign key.
+        const suffix = upperFirst(foreign);
+        if (!fieldKey.endsWith(suffix))
+            continue;
+        const relKey = fieldKey.slice(0, -suffix.length);
+        if (!relKey || meta.fields[relKey] || meta.relations[relKey])
+            continue;
+        meta.relations[relKey] = {
+            entity: references,
+            cardinality: 'm1',
+            references: [{ local: fieldKey, foreign }],
+        };
     }
-    return relOpts.mappedBy;
 }
-function getRelationKeyMap(meta) {
-    const keys = [...getKeys(meta.fields), ...getKeys(meta.relations)];
-    return keys.reduce((acc, key) => {
-        acc[key] = key;
-        return acc;
-    }, {});
+/** `<entityName><IdColumn>`, not the `<relationKey>Id` an owning to-one derives: a junction row has no relation key to borrow from. */
+function junctionColumn(meta, idKey) {
+    return lowerFirst(meta.name ?? '') + upperFirst(meta.fields[idKey]?.name ?? idKey);
+}
+/** A callback only reads one property off the key map, and that property is the key, so one serves every entity. */
+const RELATION_KEY_MAP = new Proxy({}, { get: (_, key) => key });
+function getMappedByKey(relOpts) {
+    return typeof relOpts.mappedBy === 'function'
+        ? relOpts.mappedBy(RELATION_KEY_MAP)
+        : relOpts.mappedBy;
 }
 function getIdKey(meta) {
     const id = getKeys(meta.fields).find((key) => meta.fields[key]?.isId);
@@ -297,12 +317,10 @@ function getIdKey(meta) {
 }
 function extendMeta(target, source) {
     const sourceFields = { ...source.fields };
-    const targetId = getIdKey(target);
-    if (targetId) {
-        const sourceId = getIdKey(source);
-        if (sourceId) {
-            delete sourceFields[sourceId];
-        }
+    const sourceId = getIdKey(source);
+    // A subclass that declares its own primary key drops the parent's, so exactly one stays marked.
+    if (sourceId && getIdKey(target)) {
+        delete sourceFields[sourceId];
     }
     target.fields = { ...sourceFields, ...target.fields };
     target.relations = { ...source.relations, ...target.relations };

package/dist/querier/abstractQuerier.js

@@ -40,7 +40,7 @@ export class AbstractQuerier {
         }
         forEachRequestedRelation(meta, q.$populate, (relKey, relValue) => {
             const relOpts = meta.relations[relKey];
-            if (!relOpts?.entity)
+            if (!relOpts)
                 return;
             const relEntity = relOpts.entity();
             const parsed = parseRelationQueryValue(relValue);
@@ -205,7 +205,7 @@ export class AbstractQuerier {
         const localField = relOpts.references[0].local;
         const throughEntity = relOpts.through();
         const throughMeta = getMeta(throughEntity);
-        const targetRelKey = getKeys(throughMeta.relations).find((key) => throughMeta.relations[key].references.some(({ local }) => local === relOpts.references[1].local));
+        const targetRelKey = getKeys(throughMeta.relations).find((key) => throughMeta.relations[key]?.references.some(({ local }) => local === relOpts.references[1].local));
         const ids = payload.map((it) => it[meta.id]);
         const throughFounds = await this.findMany(throughEntity, {
             ...relationQuery,

package/dist/querier/abstractSqlQuerier.js

@@ -119,10 +119,9 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         }
         for (const key in meta.relations) {
             const rel = meta.relations[key];
-            const relEntity = rel?.entity?.();
-            if (!relEntity) {
+            if (!rel)
                 continue;
-            }
+            const relEntity = rel.entity();
             const value = row[key];
             if (Array.isArray(value)) {
                 for (const it of value) {

package/dist/schema/schemaASTBuilder.js

@@ -152,7 +152,7 @@ export class SchemaASTBuilder {
         const relations = meta.relations;
         for (const key of Object.keys(relations)) {
             const relation = relations[key];
-            if (!relation?.entity)
+            if (!relation)
                 continue;
             const relatedEntity = relation.entity();
             const relatedMeta = getMeta(relatedEntity);
@@ -164,11 +164,10 @@ export class SchemaASTBuilder {
             // `references` describe how to join back (its own primary key against the owner's FK column) -
             // reading those as a foreign key emitted a reversed constraint (`User(id) REFERENCES
             // user_profile(creatorId)`), which SQLite rejects outright as a foreign key mismatch.
-            const ownsForeignKey = relation.cardinality === 'm1' || (relation.cardinality === '11' && !!relation.references && !relation.mappedBy);
+            const ownsForeignKey = relation.cardinality === 'm1' || (relation.cardinality === '11' && !relation.mappedBy);
             if (ownsForeignKey) {
-                const references = relation.references ?? [{ local: `${key}Id`, foreign: relatedMeta.id }];
-                const localPropName = references[0].local;
-                const foreignPropName = references[0].foreign;
+                const localPropName = relation.references[0].local;
+                const foreignPropName = relation.references[0].foreign;
                 const localField = meta.fields[localPropName];
                 if (!localField)
                     continue;

package/dist/type/entity.d.ts

@@ -331,12 +331,12 @@ export type RelationTarget<V> = NonNullable<Unpacked<NonNullable<V>>>;
  * {@link RelationOptions} for a relation field declared as `V`, with `entity` required and pinned to
  * `V`'s own type, and the cardinality restricted to the ones that field shape can hold. Together those
  * reject `@ManyToOne({ entity: () => Other })` on a `Company` field, and any to-many cardinality on a
- * field that is not an array.
+ * field that is not an array. An array field additionally needs a {@link RelationJoin}.
  */
 export type RelationOptionsFor<V> = Omit<RelationOptions<RelationTarget<V>>, 'entity' | 'cardinality'> & {
     readonly entity: EntityGetter<RelationTarget<V>>;
     readonly cardinality: NonNullable<V> extends readonly unknown[] ? '1m' | 'mm' : '11' | 'm1';
-};
+} & (NonNullable<V> extends readonly unknown[] ? RelationJoin<RelationTarget<V>> : unknown);
 /**
  * The method names of an entity, so hook registrations name a method that exists.
  */
@@ -350,16 +350,47 @@ export type RelationOptions<E = any> = {
     cardinality: RelationCardinality;
     readonly cascade?: boolean | CascadeType;
     mappedBy?: RelationMappedBy<E>;
-    through?: EntityGetter<RelationValue<E>>;
+    /**
+     * The pivot entity of a many-to-many. Unconstrained by `E`: a pivot holds foreign keys to both
+     * sides and is not a relation value of the target, so nothing about it is derivable from `E`.
+     */
+    through?: EntityGetter;
     references?: RelationReferences;
 };
+/**
+ * A relation once `getMeta` has resolved it: `entity` and `references` are settled and `mappedBy` is
+ * the key its callback named. Consumers read this shape rather than {@link RelationOptions}, so they
+ * need no assertions - `fillRelations` establishes the invariant once, and throws where it cannot.
+ */
+export type RelationMeta<E = any> = Omit<RelationOptions<E>, 'entity' | 'mappedBy' | 'references'> & {
+    entity: EntityGetter<E>;
+    mappedBy?: Key<E>;
+    references: RelationReferences;
+};
+/** How a to-many owner reaches its children: a junction entity, or the join columns by name. */
+type RelationOwnerJoin<E> = Required<Pick<RelationOptions<E>, 'through'>> | Required<Pick<RelationOptions<E>, 'references'>>;
+/**
+ * Every way a to-many can say where its rows are. Required because nothing about the field implies it:
+ * without one of the three, resolution has no columns to join on and throws.
+ */
+type RelationJoin<E> = RelationOwnerJoin<E> | Required<Pick<RelationOptions<E>, 'mappedBy'>>;
 type RelationOptionsOwner<E> = Pick<RelationOptions<E>, 'entity' | 'references' | 'cascade'>;
 type RelationOptionsInverseSide<E> = Required<Pick<RelationOptions<E>, 'entity' | 'mappedBy'>> & Pick<RelationOptions<E>, 'cascade'>;
-type RelationOptionsThroughOwner<E> = Required<Pick<RelationOptions<E>, 'entity'>> & Pick<RelationOptions<E>, 'through' | 'references' | 'cascade'>;
+type RelationOptionsThroughOwner<E> = Required<Pick<RelationOptions<E>, 'entity'>> & Pick<RelationOptions<E>, 'cascade'> & RelationOwnerJoin<E>;
+/**
+ * The key names of `E` as values, so `mappedBy` can be written as `(user) => user.company` instead of
+ * a string literal and survive a rename.
+ *
+ * Mapping over `Key<E>` rather than `keyof E` is what makes the callback usable: a homomorphic
+ * `[K in keyof E]` inherits the entity's optional modifiers, so `user.company` is
+ * `'company' | undefined` and {@link RelationKeyMapper} rejects it - every callback needed a `!`.
+ *
+ * At runtime a callback only ever reads one property off the map, so a single `Proxy` returning its
+ * own key stands in for every entity's: see `RELATION_KEY_MAP`. A key that names neither a field nor
+ * a relation of the target is rejected when the entity resolves.
+ */
 export type RelationKeyMap<E> = {
-    readonly [K in keyof E]: K;
-} & {
-    readonly [key: string]: string;
+    readonly [K in Key<E>]: K;
 };
 export type RelationKeyMapper<E> = (keyMap: RelationKeyMap<E>) => Key<E>;
 export type RelationReferences = {
@@ -481,9 +512,9 @@ export type EntityMeta<E> = {
         [key: string]: FieldOptions | undefined;
     };
     relations: {
-        [K in RelationKey<E>]?: RelationOptions;
+        [K in RelationKey<E>]?: RelationMeta;
     } & {
-        [key: string]: RelationOptions | undefined;
+        [key: string]: RelationMeta | undefined;
     };
     /** Composite indexes defined via @Index decorator */
     indexes?: EntityIndexMeta[];

package/dist/type/queryRaw.d.ts

@@ -1,7 +1,8 @@
 import type { QueryContext, QueryDialect } from './dialect.js';
 import type { Scalar } from './utility.js';
 /**
- * options for the `raw` function.
+ * What may be passed towards a `raw` callback. Every key is optional here because the callers along the
+ * way fill them in progressively; what reaches the callback is the complete set - see {@link QueryRawFn}.
  */
 export type QueryRawFnOptions = {
     /**
@@ -22,9 +23,15 @@ export type QueryRawFnOptions = {
     ctx?: QueryContext;
 };
 /**
- * a `raw` function
+ * A `raw` callback: write into `ctx`, or return a string or number to have it appended. Anything else
+ * it returns is ignored, which is why the return type is `unknown` rather than `void | Scalar` - the
+ * latter rejected `({ ctx }) => ctx.append(...)`, the form every virtual field is written in, because
+ * TypeScript's "returning a value where void is expected" allowance does not apply to a union.
+ *
+ * `Required`, and the parameter not optional, because the one place that calls it (`getRawValue`)
+ * passes all four every time.
  */
-export type QueryRawFn = (opts?: QueryRawFnOptions) => void | Scalar;
+export type QueryRawFn = (opts: Required<QueryRawFnOptions>) => unknown;
 export declare const RAW_VALUE: unique symbol;
 export declare const RAW_ALIAS: unique symbol;
 export declare class QueryRaw {

package/dist/type/utility.d.ts

@@ -6,8 +6,14 @@ export type MongoId = {
 /**
  * Every value type storable in an entity column. Superset of {@link QueryComparableScalar}
  * and {@link PrimaryKey}.
+ *
+ * `Uint8Array` rather than `Buffer`, which every `Buffer` still satisfies: naming an ambient Node
+ * global here made the whole key-checking layer depend on `@types/node` being in scope. Without it
+ * `Buffer` resolves to nothing, this union collapses to `any`, and `FieldKey` - the basis of
+ * `$select`, `$where`, `$sort`, `@Index` and `defineEntity({ fields })` - silently stops checking
+ * anything. A browser or edge project would have got no type safety and no error saying so.
  */
-export type Scalar = string | number | boolean | bigint | Date | RegExp | Buffer | MongoId;
+export type Scalar = string | number | boolean | bigint | Date | RegExp | Uint8Array | MongoId;
 /**
  * Scalar types with a meaningful ordering, accepted by `$lt`/`$lte`/`$gt`/`$gte`/`$between`.
  */

package/dist/util/relationQuery.util.d.ts

@@ -10,8 +10,6 @@ export declare function isPopulatingRelations<E>(meta: EntityMeta<E>, populate?:
 export type RelationQuery<E extends object = object> = Query<E> & {
     $required?: boolean;
 };
-export declare function getRelationQueryValue<E>(relKey: RelationKey<E>, populate?: QueryPopulate<E>): unknown;
-export declare function isRelationQueryObject<E extends object = object>(value: unknown): value is RelationQuery<E>;
 export type ParsedRelationQuery<E extends object = object> = {
     query: RelationQuery<E>;
     required: boolean;

package/dist/util/relationQuery.util.js

@@ -37,13 +37,8 @@ const RELATION_QUERY_ALLOWED_KEYS = new Set([
     ...RELATION_QUERY_NUMBER_KEYS,
     '$where',
 ]);
-export function getRelationQueryValue(relKey, populate) {
-    return populate?.[relKey];
-}
-export function isRelationQueryObject(value) {
-    if (!isRecord(value))
-        return false;
-    return isValidRelationQueryShape(value);
+function isRelationQueryObject(value) {
+    return isRecord(value) && isValidRelationQueryShape(value);
 }
 export function parseRelationQueryValue(value) {
     if (isRelationQueryObject(value)) {
@@ -63,11 +58,11 @@ export function parseRelationQueryValue(value) {
 }
 /** Parses the relation payload for `relKey` */
 export function parseRelationAtKey(relKey, populate) {
-    return parseRelationQueryValue(getRelationQueryValue(relKey, populate));
+    return parseRelationQueryValue(populate?.[relKey]);
 }
 export function forEachRequestedRelation(meta, populate, fn) {
     for (const relKey of getRelationRequestSummary(meta, populate).requestedKeys) {
-        fn(relKey, getRelationQueryValue(relKey, populate));
+        fn(relKey, populate?.[relKey]);
     }
 }
 function isRecord(value) {

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "Extremely fast, type-safe TypeScript ORM - one API for every database",
   "license": "MIT",
-  "version": "0.24.0",
+  "version": "0.24.2",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -198,5 +198,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "d9499a4b8c5ee866950b397fb87f55643d86fc39"
+  "gitHead": "419ba75dc2e856f6b8030fa0a6fed3e5c7940de1"
 }