uql-orm 0.24.1 → 0.24.3

package/README.md

@@ -51,7 +51,7 @@ 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.4× faster than the runner-up on average, over 4.6M ops/s on simple SELECTs.
-- **Light.** Zero dependencies, under 1 MB installed, every dialect included.
+- **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/decorator/members.d.ts

@@ -1,6 +1,17 @@
-import type { EntityGetter, FieldOptions, FieldType, RelationManyToManyOptions, RelationManyToOneOptions, RelationOneToManyOptions, RelationOneToOneOptions, TsTypeOf } from '../../type/index.js';
+import type { EntityGetter, FieldOptions, FieldType, IdValue, RelationManyToManyOptions, RelationManyToOneOptions, RelationOneToManyOptions, RelationOneToOneOptions, TsTypeOf } from '../../type/index.js';
 /** A member decorator that also constrains the property it may be applied to. */
 type MemberDecorator<V> = (value: undefined, context: ClassFieldDecoratorContext<unknown, V>) => void;
+/**
+ * The property type a set of field options describes, in the same order schema generation resolves the
+ * column: a declared `type` wins, and otherwise the column - and so the property - is the referenced
+ * primary key's own type. Which is what makes `@Field({ references: () => User })` on a `number`, where
+ * `User.id` is a `uuid`, a compile error rather than a column that disagrees with its property.
+ */
+type DeclaredValue<O> = O extends {
+    readonly type: infer T extends FieldType;
+} ? TsTypeOf<T> : O extends {
+    readonly references: EntityGetter<infer E>;
+} ? IdValue<E> : never;
 /**
  * Declares a persisted field.
  *
@@ -8,27 +19,22 @@ type MemberDecorator<V> = (value: undefined, context: ClassFieldDecoratorContext
  * which is what makes the now-mandatory `type` worth stating.
  *
  * @example `@Field({ type: String }) name?: string;`
- * @example `@Field({ references: () => Company }) companyId?: string;`
- */
-export declare function Field<T extends FieldType>(opts: FieldOptions & {
-    readonly type: T;
-}): MemberDecorator<TsTypeOf<T> | undefined>;
-/**
- * A foreign key may omit `type`: schema generation resolves it from the referenced primary key, so the
- * column picks up that key's `columnType`, length and chained references rather than a guess.
+ * @example `@Field({ references: () => User }) userId?: string;` (where `User.id` is a `uuid`)
  */
-export declare function Field(opts: FieldOptions & {
-    readonly references: EntityGetter;
-}): MemberDecorator<unknown>;
+export declare function Field<O extends FieldOptions<DeclaredValue<O>> & ({
+    type: FieldType;
+} | {
+    references: EntityGetter;
+})>(opts: O): MemberDecorator<DeclaredValue<O> | undefined>;
 /**
  * Declares the primary key, checked the same way as `@Field`.
  *
  * @example `@Id({ type: Number }) id?: number;`
  * @example `@Id({ type: 'uuid', onInsert: uuidv7 }) id?: string;`
  */
-export declare function Id<T extends FieldType>(opts: FieldOptions & {
-    readonly type: T;
-}): MemberDecorator<TsTypeOf<T> | undefined>;
+export declare function Id<O extends FieldOptions<DeclaredValue<O>> & {
+    type: FieldType;
+}>(opts: O): MemberDecorator<DeclaredValue<O> | undefined>;
 /**
  * `E` comes from the mandatory `entity` getter, so the context can insist the property really holds that
  * entity: `@ManyToOne({ entity: () => Other })` on a `Company` field stops compiling, and a to-many

package/dist/entity/decorator/members.js

@@ -1,4 +1,13 @@
 import { memberRegistrations } from './bag.js';
+/**
+ * Declares a persisted field.
+ *
+ * `@Field({ type: String })` on a `number` property is a compile error rather than a silent TEXT column,
+ * which is what makes the now-mandatory `type` worth stating.
+ *
+ * @example `@Field({ type: String }) name?: string;`
+ * @example `@Field({ references: () => User }) userId?: string;` (where `User.id` is a `uuid`)
+ */
 export function Field(opts) {
     return (_value, context) => {
         memberRegistrations(context.metadata).fields[String(context.name)] = opts;

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,122 +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) {
-            const throughEntity = relOpts.through();
-            const throughMeta = fillThroughRelations(throughEntity);
+            const junction = getMeta(relOpts.through());
             for (const { local } of relOpts.references) {
-                if (throughMeta.fields[local])
+                if (junction.fields[local])
                     continue;
-                throw new TypeError(`'${meta.entity.name}.${relKey}' joins through '${throughEntity.name}', which has no '${local}' ` +
-                    "field. Declare it, or name the join columns yourself with 'references'.");
+                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,
-    }));
-}
-// `getMeta` rather than `ensureMeta`: a pivot that declares its sides as relations rather than as
-// `@Field({ references })` columns gets those foreign-key columns auto-created there, and the caller
-// checks its own derived join columns against them.
-function fillThroughRelations(entity) {
-    const meta = getMeta(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;
-    }, {});
-    return meta;
+    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 Object.fromEntries(keys.map((key) => [key, key]));
+/** `<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);
@@ -305,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

@@ -206,9 +206,11 @@ export type FieldType = StringConstructor | NumberConstructor | BooleanConstruct
  */
 export type TypeFor<V, T = NonNullable<V>> = IsJson<T> extends true ? JsonColumnType : IsJson<NonNullable<Unpacked<T>>> extends true ? JsonColumnType : T extends readonly number[] ? VectorColumnType : T extends string ? StringConstructor | StringColumnType : T extends number ? NumberConstructor | NumericColumnType : T extends bigint ? BigIntConstructor | NumericColumnType : T extends boolean ? BooleanConstructor | BooleanColumnType : T extends Date ? DateConstructor | DateColumnType : T extends Uint8Array ? BlobColumnType : FieldType;
 /**
- * Configurable options for a field
+ * Configurable options for a field, carrying `V`, the value the column holds: what a generator returns
+ * and what a default is has to be that value, checked the same way the declared `type` is. `Scalar` by
+ *  by default, for the places that handle a field without knowing which one it is.
  */
-export type FieldOptions = {
+export type FieldOptions<V = TsTypeOf<FieldType>> = {
     readonly name?: string;
     readonly isId?: true;
     readonly type?: FieldType;
@@ -238,8 +240,8 @@ export type FieldOptions = {
     readonly virtual?: QueryRaw;
     readonly updatable?: boolean;
     readonly eager?: boolean;
-    readonly onInsert?: OnFieldCallback;
-    readonly onUpdate?: OnFieldCallback;
+    readonly onInsert?: OnFieldCallback<V>;
+    readonly onUpdate?: OnFieldCallback<V>;
     /**
      * Marks this field as the soft-delete field. Its presence makes the entity "soft deletable":
      * a `delete` becomes an `UPDATE` that stamps this field instead of removing the row, and reads
@@ -251,7 +253,7 @@ export type FieldOptions = {
      * @example `@Field({ softDelete: true }) deletedAt?: Date;`
      * @example `@Field({ softDelete: () => Date.now() }) deletedAt?: number;`
      */
-    readonly softDelete?: OnFieldCallback;
+    readonly softDelete?: true | OnFieldCallback<V>;
     /**
      * SQL column type for migrations. If not specified, inferred from TypeScript type.
      */
@@ -279,7 +281,7 @@ export type FieldOptions = {
     /**
      * Default value for the column
      */
-    readonly defaultValue?: Scalar | Record<string, unknown>;
+    readonly defaultValue?: V | Record<string, unknown>;
     /**
      * Whether the column is auto-incrementing (for integer IDs).
      */
@@ -293,7 +295,7 @@ export type FieldOptions = {
      */
     readonly comment?: string;
 };
-export type OnFieldCallback = Scalar | QueryRaw | (() => Scalar | QueryRaw);
+export type OnFieldCallback<V = TsTypeOf<FieldType>> = V | QueryRaw | (() => V | QueryRaw);
 /**
  * The TypeScript types a field may be declared as, given the `type` it registers: the inverse of
  * {@link TypeFor}.
@@ -316,9 +318,9 @@ export type TsTypeOf<T> = T extends StringConstructor ? string : T extends Numbe
  * `@Field({ references: () => Company })` would silently downgrade a `uuid` key to TEXT on every
  * column pointing at it.
  */
-export type FieldOptionsFor<V> = (FieldOptions & {
+export type FieldOptionsFor<V> = (FieldOptions<NonNullable<V>> & {
     readonly type: TypeFor<V>;
-}) | (FieldOptions & {
+}) | (FieldOptions<NonNullable<V>> & {
     readonly references: EntityGetter;
     readonly type?: TypeFor<V>;
 });
@@ -331,12 +333,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.
  */
@@ -357,18 +359,37 @@ export type RelationOptions<E = any> = {
     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 `!`. The
- * map is built from the target's metadata (see `getRelationKeyMap`), where every key is present and
- * every key is a string.
+ * `'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 Key<E>]: K;
@@ -493,9 +514,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/dialect.util.d.ts

@@ -14,12 +14,20 @@ export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: E, call
  * chunk-size estimate inspects the raw payload).
  */
 export declare function getInsertFieldKeys<E>(meta: EntityMeta<E>, payloads: E[]): FieldKey<E>[];
-export declare function getFieldCallbackValue(val: OnFieldCallback): QueryRaw | import("../type/utility.js").Scalar;
+export declare function getFieldCallbackValue(val: OnFieldCallback): string | number | bigint | boolean | Date | QueryRaw | readonly {
+    readonly __json?: never;
+}[] | readonly number[] | Uint8Array<ArrayBufferLike> | {
+    readonly __json?: never;
+};
 /**
  * Resolves the value stamped on the soft-delete field when deleting a row.
  * `true` stamps the current timestamp (`new Date()`); any other marker is an {@link OnFieldCallback}.
  */
-export declare function getSoftDeleteValue(field: FieldOptions): QueryRaw | import("../type/utility.js").Scalar;
+export declare function getSoftDeleteValue(field: FieldOptions): string | number | bigint | boolean | Date | QueryRaw | readonly {
+    readonly __json?: never;
+}[] | readonly number[] | Uint8Array<ArrayBufferLike> | {
+    readonly __json?: never;
+};
 export declare function fillOnFields<E>(meta: EntityMeta<E>, payload: E | E[], callbackKey: CallbackKey): E[];
 /**
  * The relation keys present in `payload` whose cascade configuration allows `action`. Only

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.1",
+  "version": "0.24.3",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -198,5 +198,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "7f11b72301d647853c7a2778daaa09af8f4d5695"
+  "gitHead": "4301613bcab77a626513197f1e815f972aa21bba"
 }