uql-orm 0.56.0 → 0.58.0

package/dist/dialect/queryJoins.d.ts

@@ -1,5 +1,4 @@
-import type { EntityMeta, Query, QuerySortMap, RelationMeta, Type } from '../type/index.js';
-import { type RelationQuery } from '../util/index.js';
+import type { EntityMeta, Query, QuerySortMap, RelationMeta, RelationQuery, Type } from '../type/index.js';
 /**
  * One relation a statement joins, keyed by the alias its columns are addressed by (`tax`,
  * `tax.category`). `projected` tells a `$populate` join, whose columns are selected, from one only
@@ -8,8 +7,10 @@ import { type RelationQuery } from '../util/index.js';
 export type QueryJoin = {
     /** The relation key on its parent, which is how MongoDB names the field a `$lookup` adds. */
     readonly key: string;
-    /** Dotted path from the queried entity, which is how the SQL dialects alias the join. */
+    /** Dotted path from the queried entity, which is what a joined row's columns answer under. */
     readonly path: string;
+    /** The alias the statement reads it through: its path, unless another table of the statement took it. */
+    readonly alias: string;
     readonly entity: Type<object>;
     readonly meta: EntityMeta<object>;
     readonly relation: RelationMeta;
@@ -38,14 +39,17 @@ export type QuerySortOptions = {
  * related column needs that relation joined just as much as selecting it does. The two sources meet
  * here, so the columns, the `ORDER BY` and the row lock cannot disagree about what is in the
  * statement. `$sort` contributes to-one relations only; the rest is rejected where it is rendered.
+ * `claimAlias` names each join's table, parents first.
  */
-export declare function resolveQueryJoins<E>(meta: EntityMeta<E>, q: Query<E>): QueryJoins;
+export declare function resolveQueryJoins<E>(meta: EntityMeta<E>, q: Query<E>, claimAlias?: (path: string) => string): QueryJoins;
 /**
  * Whether a join drops parents that have no match, which is the one thing a join does to *how many*
  * rows a read returns rather than how wide they are. A count that skips the joins has to be told, or
  * it counts the parents the read will never hand back.
  */
 export declare function hasRequiredJoin<E>(meta: EntityMeta<E>, q: Query<E>): boolean;
+/** Whether a statement aggregates a relation's rows: a to-many off its own row, or off a row it joins. */
+export declare function aggregatesRelations<E>(meta: EntityMeta<E>, q: Query<E>): boolean;
 /**
  * The join an ordering may address at `path`, with the relation's own sort map, or why it may not.
  * Every backend answers this the same way - a to-many has no single value to order by, a relation

package/dist/dialect/queryJoins.js

@@ -1,19 +1,20 @@
 import { getMeta, relationOf } from '../entity/index.js';
-import { getKeys, getRelationRequestSummary, isToManyRelation, parseRelationAtKey, } from '../util/index.js';
+import { getKeys, getRelationRequestSummary, isToManyRelation, parseRelationAtKey } from '../util/index.js';
 export const NO_JOINS = new Map();
 /**
  * What the statement joins, from the whole query rather than from `$populate` alone: ordering by a
  * related column needs that relation joined just as much as selecting it does. The two sources meet
  * here, so the columns, the `ORDER BY` and the row lock cannot disagree about what is in the
  * statement. `$sort` contributes to-one relations only; the rest is rejected where it is rendered.
+ * `claimAlias` names each join's table, parents first.
  */
-export function resolveQueryJoins(meta, q) {
+export function resolveQueryJoins(meta, q, claimAlias = (path) => path) {
     if (!q.$populate && !q.$sort) {
         return NO_JOINS;
     }
     const joins = new Map();
-    addPopulateJoins(joins, meta, q.$populate);
-    addSortJoins(joins, meta, q.$sort);
+    addPopulateJoins(joins, claimAlias, meta, q.$populate);
+    addSortJoins(joins, claimAlias, meta, q.$sort);
     return joins;
 }
 /**
@@ -29,7 +30,19 @@ export function hasRequiredJoin(meta, q) {
     }
     return false;
 }
-function addJoin(joins, parent, key, relation, query, required, projected) {
+/** Whether a statement aggregates a relation's rows: a to-many off its own row, or off a row it joins. */
+export function aggregatesRelations(meta, q) {
+    if (getRelationRequestSummary(meta, q.$populate).toManyKeys.length) {
+        return true;
+    }
+    for (const join of resolveQueryJoins(meta, q).values()) {
+        if (getRelationRequestSummary(join.meta, join.query.$populate).toManyKeys.length) {
+            return true;
+        }
+    }
+    return false;
+}
+function addJoin(joins, claimAlias, parent, key, relation, query, required, projected) {
     const path = parent ? `${parent.path}.${key}` : key;
     const existing = joins.get(path);
     // `$populate` runs first, so an already-joined relation keeps its columns and its `$required`
@@ -41,6 +54,7 @@ function addJoin(joins, parent, key, relation, query, required, projected) {
     const join = {
         key,
         path,
+        alias: claimAlias(path),
         entity,
         meta: getMeta(entity),
         relation,
@@ -52,15 +66,15 @@ function addJoin(joins, parent, key, relation, query, required, projected) {
     joins.set(path, join);
     return join;
 }
-function addPopulateJoins(joins, meta, populate, parent) {
+function addPopulateJoins(joins, claimAlias, meta, populate, parent) {
     for (const key of getRelationRequestSummary(meta, populate).joinableKeys) {
         const relation = relationOf(meta, key);
         const { query, required } = parseRelationAtKey(key, populate);
-        const join = addJoin(joins, parent, key, relation, query, required, true);
-        addPopulateJoins(joins, join.meta, query.$populate, join);
+        const join = addJoin(joins, claimAlias, parent, key, relation, query, required, true);
+        addPopulateJoins(joins, claimAlias, join.meta, query.$populate, join);
     }
 }
-function addSortJoins(joins, meta, sort, parent) {
+function addSortJoins(joins, claimAlias, meta, sort, parent) {
     if (!sort) {
         return;
     }
@@ -72,8 +86,9 @@ function addSortJoins(joins, meta, sort, parent) {
         if (!relation || isToManyRelation(relation) || !isSortMap(value)) {
             continue;
         }
-        const join = addJoin(joins, parent, key, relation, {}, false, false);
-        addSortJoins(joins, join.meta, value, join);
+        const join = addJoin(joins, claimAlias, parent, key, relation, {}, false, false);
+        // `E` stated: inferred from a `QuerySortMap<object>`, it lands on the nested relation's target.
+        addSortJoins(joins, claimAlias, join.meta, value, join);
     }
 }
 /**

package/dist/dialect/vectorSqlDialect.d.ts

@@ -78,8 +78,8 @@ export declare abstract class VectorSqlDialect extends AbstractDialect {
      */
     supportedVectorType(cast: VectorCast): VectorCast;
     /**
-     * Append a vector distance projection.
-     * Delegates to `appendVectorSort` so each dialect's distance syntax is written once.
+     * The distance a vector `$sort` projects, which the projection names after `$project`. Delegates to
+     * `appendVectorSort` so each dialect's distance syntax is written once.
      */
     protected appendVectorProjection<E>(ctx: QueryContext, meta: EntityMeta<E>, key: string, search: QueryVectorSearch): void;
     /**

package/dist/dialect/vectorSqlDialect.js

@@ -96,8 +96,8 @@ export class VectorSqlDialect extends AbstractDialect {
         return this.hasNarrowVectorTypes ? cast : 'vector';
     }
     /**
-     * Append a vector distance projection.
-     * Delegates to `appendVectorSort` so each dialect's distance syntax is written once.
+     * The distance a vector `$sort` projects, which the projection names after `$project`. Delegates to
+     * `appendVectorSort` so each dialect's distance syntax is written once.
      */
     appendVectorProjection(ctx, meta, key, search) {
         const alias = search.$project;
@@ -108,7 +108,6 @@ export class VectorSqlDialect extends AbstractDialect {
             throw new TypeError(`$project '${alias}' collides with a field of '${entityName(meta)}'`);
         }
         this.appendVectorSort(ctx, meta, key, search);
-        ctx.append(` AS ${this.escapeId(alias)}`);
     }
     /**
      * The distance expression, in whichever of the two shapes this dialect spells it. One method for

package/dist/entity/decorator/bag.d.ts

@@ -1,4 +1,4 @@
-import type { FieldOptions, HookEvent, RelationOptions, Type } from '../../type/index.js';
+import type { FieldOptions, HookEvent, RelationRegistration, Type } from '../../type/index.js';
 /**
  * What the member decorators record for one class, waiting for `@Entity()` or `defineEntity` to drain
  * it into the metadata registry. Member decorators receive no class reference under the standard
@@ -9,7 +9,7 @@ import type { FieldOptions, HookEvent, RelationOptions, Type } from '../../type/
  */
 export type MemberRegistrations = {
     readonly fields: Record<string, FieldOptions>;
-    readonly relations: Record<string, RelationOptions>;
+    readonly relations: Record<string, RelationRegistration>;
     readonly hooks: Partial<Record<HookEvent, string[]>>;
 };
 /**

package/dist/entity/decorator/entity.d.ts

@@ -1,4 +1,4 @@
-import type { EntityOptions, FieldKey, FilterOptions, IndexColumnInput, IndexOptions, Type } from '../../type/index.js';
+import type { EntityIndexOptions, EntityOptions, FieldKey, FilterOptions, IndexColumnInput, KeyMap, Type } from '../../type/index.js';
 /**
  * Marks a class as an entity and finalizes its metadata.
  *
@@ -16,13 +16,12 @@ export declare function Entity<E>(opts?: EntityOptions<E>): (entity: Type<E>, co
  */
 export declare function Filter<E>(name: string, opts: FilterOptions<E>): (entity: Type<E>) => void;
 /**
- * Declares a composite index. Stacks, so several may sit above one class.
+ * Declares a composite index, its columns read off the key map. Stacks, so several may sit above one
+ * class. `E` is inferred from the class the returned decorator is applied to, which is what types the
+ * key map: `@Index((user) => [user.nope])` does not compile, and a rename reaches every column.
  *
- * `E` is inferred from the class the returned decorator is applied to, which is what lets the column
- * names be checked against it: `@Index(['nope'])` does not compile.
- *
- * @example `@Index(['lastName', 'firstName'], { name: 'users_fullname_idx' })`
- * @example `@Index(['email'], { unique: true })`
- * @example `@Index(['status'], { where: "status = 'active'" })`
+ * @example `@Index((user) => [user.lastName, user.firstName], { name: 'users_fullname_idx' })`
+ * @example `@Index((user) => [user.email], { unique: true })`
+ * @example `@Index((user) => [user.status], { where: "status = 'active'" })`
  */
-export declare function Index<E>(columns: readonly IndexColumnInput<FieldKey<E>, E>[], options?: IndexOptions<E>): (entity: Type<E>) => void;
+export declare function Index<E>(columns: (keys: KeyMap<E>) => readonly IndexColumnInput<FieldKey<NoInfer<E>>, NoInfer<E>>[], options?: EntityIndexOptions<NoInfer<E>>): (entity: Type<E>) => void;

package/dist/entity/decorator/entity.js

@@ -28,14 +28,13 @@ export function Filter(name, opts) {
     };
 }
 /**
- * Declares a composite index. Stacks, so several may sit above one class.
+ * Declares a composite index, its columns read off the key map. Stacks, so several may sit above one
+ * class. `E` is inferred from the class the returned decorator is applied to, which is what types the
+ * key map: `@Index((user) => [user.nope])` does not compile, and a rename reaches every column.
  *
- * `E` is inferred from the class the returned decorator is applied to, which is what lets the column
- * names be checked against it: `@Index(['nope'])` does not compile.
- *
- * @example `@Index(['lastName', 'firstName'], { name: 'users_fullname_idx' })`
- * @example `@Index(['email'], { unique: true })`
- * @example `@Index(['status'], { where: "status = 'active'" })`
+ * @example `@Index((user) => [user.lastName, user.firstName], { name: 'users_fullname_idx' })`
+ * @example `@Index((user) => [user.email], { unique: true })`
+ * @example `@Index((user) => [user.status], { where: "status = 'active'" })`
  */
 export function Index(columns, options = {}) {
     return (entity) => {

package/dist/entity/decorator/members.d.ts

@@ -1,7 +1,7 @@
 import type { EntityGetter, FieldOptions, FieldType, IdValue, NamedIdKey, RelationManyToManyOptions, RelationManyToOneOptions, RelationOneToManyOptions, RelationOneToOneOptions, TsTypeOf } from '../../type/index.js';
 import type { RejectIncompatible } from '../../util/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;
+/** A member decorator that also constrains the property it may be applied to, on a class `O`. */
+type MemberDecorator<V, O = unknown> = (value: undefined, context: ClassFieldDecoratorContext<O, V>) => void;
 /**
  * Maps any option the type does not declare to `never`, turning a typo into a compile error.
  *
@@ -73,14 +73,15 @@ export declare function Id<O extends FieldOptions<DeclaredValue<O>> & {
  * `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
  * cardinality on a non-array property does too. `entity` is required because nothing reflects it now.
+ * `O` is inferred from the class the decorator sits on, which types `references`' own side.
  */
 type WithEntity<E, O> = O & {
     readonly entity: EntityGetter<E>;
 };
-export declare function OneToOne<E>(opts: WithEntity<E, RelationOneToOneOptions<E>>): MemberDecorator<E | undefined>;
-export declare function ManyToOne<E>(opts: WithEntity<E, RelationManyToOneOptions<E>>): MemberDecorator<E | undefined>;
-export declare function OneToMany<E>(opts: WithEntity<E, RelationOneToManyOptions<E>>): MemberDecorator<readonly E[] | undefined>;
-export declare function ManyToMany<E>(opts: WithEntity<E, RelationManyToManyOptions<E>>): MemberDecorator<readonly E[] | undefined>;
+export declare function OneToOne<E extends object, O>(opts: WithEntity<E, RelationOneToOneOptions<E, O>>): MemberDecorator<E | undefined, O>;
+export declare function ManyToOne<E extends object, O>(opts: WithEntity<E, RelationManyToOneOptions<E, O>>): MemberDecorator<E | undefined, O>;
+export declare function OneToMany<E extends object, O>(opts: WithEntity<E, RelationOneToManyOptions<E, O>>): MemberDecorator<readonly E[] | undefined, O>;
+export declare function ManyToMany<E extends object, O>(opts: WithEntity<E, RelationManyToManyOptions<E, O>>): MemberDecorator<readonly E[] | undefined, O>;
 export declare const BeforeInsert: () => <This>(_value: unknown, context: ClassMethodDecoratorContext<This>) => void;
 export declare const AfterInsert: () => <This>(_value: unknown, context: ClassMethodDecoratorContext<This>) => void;
 export declare const BeforeUpdate: () => <This>(_value: unknown, context: ClassMethodDecoratorContext<This>) => void;

package/dist/entity/decorator/members.js

@@ -1,3 +1,4 @@
+import { relationRegistration } from '../metadata/definition.js';
 import { memberRegistrations } from './bag.js';
 /**
  * Declares a persisted field.
@@ -28,7 +29,7 @@ export function Id(opts) {
 }
 function relation(opts) {
     return (_value, context) => {
-        memberRegistrations(context.metadata).relations[String(context.name)] = opts;
+        memberRegistrations(context.metadata).relations[String(context.name)] = relationRegistration(opts);
     };
 }
 export function OneToOne(opts) {

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

@@ -1,13 +1,20 @@
-import type { EntityData, EntityIndexInput, EntityMembers, EntityMeta, EntityOptions, FieldKey, FieldMeta, FieldOptions, FilterOptions, HookEvent, IdKey, RelationKey, RelationMeta, RelationOptions, Type, WrittenId } from '../../type/index.js';
+import type { EntityData, EntityIndexInput, EntityMembers, EntityMeta, EntityOptions, FieldMeta, FieldOptions, FilterOptions, HookEvent, IdKey, RelationKey, RelationMeta, RelationOptions, RelationRegistration, Type, WrittenId } from '../../type/index.js';
 export declare function defineField<E>(entity: Type<E>, key: string, opts?: FieldOptions): EntityMeta<E>;
 export declare function defineId<E>(entity: Type<E>, key: string, opts: FieldOptions): EntityMeta<E>;
-export declare function defineRelation<E>(entity: Type<E>, key: string, opts: RelationOptions): EntityMeta<E>;
+/** `T` is the relation's target, independent of the owner `E`. */
+export declare function defineRelation<E, T extends object>(entity: Type<E>, key: string, opts: RelationOptions<T, E>): EntityMeta<E>;
+/**
+ * `opts` as the registry takes them: `mappedBy` and `references` read off their key maps down to the
+ * names they give. The callbacks only read properties, so they run here, before any entity has to
+ * exist, and the registry holds data alone.
+ */
+export declare function relationRegistration<T extends object, O>({ mappedBy, references, ...opts }: RelationOptions<T, O>): RelationRegistration;
 export declare function defineHook<E>(entity: Type<E>, methodName: string, event: HookEvent): EntityMeta<E>;
 /**
- * Declares a composite index. `unique` and the authored column sugar are normalized here, which is what
- * lets the dialects render one shape instead of re-parsing it.
+ * Declares a composite index, its columns read off the key map. `unique` and the authored column sugar
+ * are normalized here, which is what lets the dialects render one shape instead of re-parsing it.
  */
-export declare function defineIndex<E>(entity: Type<E>, index: EntityIndexInput<FieldKey<E>, E>): EntityMeta<E>;
+export declare function defineIndex<E>(entity: Type<E>, index: EntityIndexInput<E>): EntityMeta<E>;
 export declare function defineFilter<E>(entity: Type<E>, name: string, opts: FilterOptions<E>): EntityMeta<E>;
 /**
  * Feeds fields, relations and hooks into the `define*` primitives, so the decorators and the imperative
@@ -15,10 +22,8 @@ export declare function defineFilter<E>(entity: Type<E>, name: string, opts: Fil
  */
 export declare function applyMembers<E>(entity: Type<E>, specs: EntityMembers | undefined): void;
 /**
- * Registers an entity described by data alone, minting the class the registry keys it by. The row
- * type follows from the spec - see {@link SpecRow} - so a definition written out is checked column by
- * column, and one assembled at runtime is the column bag it is. Pass `Row` to name a shape the spec
- * cannot describe, such as the interface `uql-migrate types` generated for it.
+ * Registers a class as an entity from `opts` alone, the decorator-free counterpart of `@Entity()` with
+ * `@Field`/`@ManyToOne`/...
  */
 export declare function defineEntity<E>(entity: Type<E>, opts?: EntityOptions<E>): EntityMeta<E>;
 /**
@@ -31,7 +36,7 @@ export declare function assertSoleId<E>(meta: EntityMeta<E>, what: string): void
 /** The entity's one primary key, for a path that cannot express a composite. See {@link assertSoleId}. */
 export declare function soleIdOf<E>(meta: EntityMeta<E>, what: string): IdKey<E>;
 /** The field `key` names, for a caller that took `key` from the metadata itself. */
-export declare function fieldOf<E>(meta: EntityMeta<E>, key: FieldKey<E>): FieldMeta;
+export declare function fieldOf<E>(meta: EntityMeta<E>, key: string): FieldMeta;
 /** The relation `key` names, for a caller that took `key` from the metadata itself. */
 export declare function relationOf<E>(meta: EntityMeta<E>, key: RelationKey<E>): RelationMeta;
 /**
@@ -61,5 +66,5 @@ export declare function idOf<E>(meta: EntityMeta<E>, row: EntityData<E>): Writte
  * registration). See the Runtime Schemas guide.
  */
 export declare function removeEntity<E>(entity: Type<E>): boolean;
-export declare function getEntities(): Type<unknown>[];
+export declare function getEntities(): Type<object>[];
 export declare function getMeta<E>(entity: Type<E>): EntityMeta<E>;

package/dist/entity/metadata/definition.js

@@ -38,18 +38,41 @@ export function defineField(entity, key, opts = {}) {
 export function defineId(entity, key, opts) {
     return defineField(entity, key, { ...opts, isId: true });
 }
-// `RelationOptions` is parameterized by the *target* entity, which is independent of the owner `E`, so it
-// is left at its default here rather than tied to the class being registered.
+/** `T` is the relation's target, independent of the owner `E`. */
 export function defineRelation(entity, key, opts) {
-    if (!opts.entity) {
+    return addRelation(entity, key, relationRegistration(opts));
+}
+/**
+ * `opts` as the registry takes them: `mappedBy` and `references` read off their key maps down to the
+ * names they give. The callbacks only read properties, so they run here, before any entity has to
+ * exist, and the registry holds data alone.
+ */
+export function relationRegistration({ mappedBy, references, ...opts }) {
+    return {
+        ...opts,
+        ...(mappedBy ? { mappedBy: mappedBy(keyMap()) } : {}),
+        ...(references ? { references: [...references(keyMap(), keyMap())] } : {}),
+    };
+}
+/** Every entity's key map: a callback only reads one property off it, and that property is its own key. */
+function keyMap() {
+    return KEY_MAP;
+}
+const KEY_MAP = new Proxy({}, { get: (_, key) => key });
+function addRelation(entity, key, registration) {
+    if (!registration.entity) {
         throw new TypeError(`'${entity.name}.${key}' needs an 'entity' getter, e.g. '@ManyToOne({ entity: () => Company })'.`);
     }
+    if (registration.through && registration.references) {
+        throw new TypeError(`'${entity.name}.${key}' joins through a junction, whose columns follow the convention; 'references' ` +
+            "pairs the declaring entity's columns with the target's instead.");
+    }
     const meta = ensureWritableMeta(entity);
-    // 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.
+    // Registration writes into a map declared as resolved: `getMeta` runs `fillRelations`, which settles
+    // `references` 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 };
+    relations[key] = { ...relations[key], ...registration };
     return meta;
 }
 export function defineHook(entity, methodName, event) {
@@ -62,18 +85,18 @@ export function defineHook(entity, methodName, event) {
     return meta;
 }
 /**
- * Declares a composite index. `unique` and the authored column sugar are normalized here, which is what
- * lets the dialects render one shape instead of re-parsing it.
+ * Declares a composite index, its columns read off the key map. `unique` and the authored column sugar
+ * are normalized here, which is what lets the dialects render one shape instead of re-parsing it.
  */
 export function defineIndex(entity, index) {
     const meta = ensureWritableMeta(entity);
-    if (!meta.indexes)
-        meta.indexes = [];
-    meta.indexes.push({
+    const keys = keyMap();
+    (meta.indexes ??= []).push({
         ...index,
         unique: index.unique ?? false,
         where: ddlText(index.where, 'a partial-index predicate'),
-        columns: index.columns.map(normalizeIndexColumn),
+        columns: index.columns(keys).map(normalizeIndexColumn),
+        include: index.include?.(keys),
     });
     return meta;
 }
@@ -104,7 +127,7 @@ export function applyMembers(entity, specs) {
         }
     }
     for (const [key, spec] of definedEntries(specs?.relations ?? {})) {
-        defineRelation(entity, key, spec);
+        addRelation(entity, key, spec);
     }
     for (const [event, methodNames] of definedEntries(specs?.hooks ?? {})) {
         for (const methodName of methodNames) {
@@ -113,10 +136,8 @@ export function applyMembers(entity, specs) {
     }
 }
 /**
- * Registers an entity described by data alone, minting the class the registry keys it by. The row
- * type follows from the spec - see {@link SpecRow} - so a definition written out is checked column by
- * column, and one assembled at runtime is the column bag it is. Pass `Row` to name a shape the spec
- * cannot describe, such as the interface `uql-migrate types` generated for it.
+ * Registers a class as an entity from `opts` alone, the decorator-free counterpart of `@Entity()` with
+ * `@Field`/`@ManyToOne`/...
  */
 export function defineEntity(entity, opts = {}) {
     // Ahead of any registration, so a rejected definition leaves nothing half-written in the registry.
@@ -132,7 +153,12 @@ export function defineEntity(entity, opts = {}) {
     // drains `context.metadata` itself, because TypeScript only attaches `Symbol.metadata` to the class
     // after class decorators return; draining empties the bag, so whichever runs second is a no-op.
     applyMembers(entity, ownRegistrations(entity));
-    applyMembers(entity, opts);
+    const keys = keyMap();
+    applyMembers(entity, {
+        fields: opts.fields,
+        relations: Object.fromEntries(definedEntries(opts.relations ?? {}).map(([key, spec]) => [key, relationRegistration(spec)])),
+        hooks: Object.fromEntries(definedEntries(opts.hooks ?? {}).map(([event, methods]) => [event, methods(keys)])),
+    });
     // Unnamed checks are named by the generator, as unnamed indexes are.
     for (const check of opts.checks ?? []) {
         (meta.checks ??= []).push({ name: check.name, expression: ddlText(check.expression, 'a check constraint') });
@@ -267,12 +293,7 @@ export function removeEntity(entity) {
     return metas.delete(entity);
 }
 export function getEntities() {
-    return metas.entries().reduce((acc, [key, val]) => {
-        if (val.ids.length) {
-            acc.push(key);
-        }
-        return acc;
-    }, []);
+    return [...metas.values()].filter((meta) => meta.ids.length).map((meta) => meta.entity);
 }
 /**
  * The metadata of `entity`, marked as changed. Every `define*` goes through this, and nothing outside
@@ -308,11 +329,11 @@ export function getMeta(entity) {
 }
 function fillRelations(meta) {
     for (const [relKey, relation] of definedEntries(meta.relations)) {
-        // The authored view: `mappedBy` may still be the callback and `references` unset until this settles them.
+        // The registered view: `references` may be unset until this settles it.
         const relOpts = relation;
         const at = `'${meta.entity.name}.${relKey}'`;
         if (relOpts.mappedBy) {
-            fillInverseSide(at, meta, relOpts);
+            fillInverseSide(at, meta, relOpts, relOpts.mappedBy);
         }
         else if (!relOpts.references) {
             fillOwningSide(at, meta, relKey, relOpts);
@@ -326,8 +347,8 @@ function fillRelations(meta) {
             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'.");
+                throw new TypeError(`${at} joins through '${junction.entity.name}', which has no '${local}' field: a junction's ` +
+                    'columns are named after the entities it joins. Declare it.');
             }
         }
     }
@@ -337,9 +358,9 @@ function fillRelations(meta) {
 function fillOwningSide(at, meta, relKey, relOpts) {
     const relMeta = ensureMeta(relOpts.entity());
     if (relOpts.through) {
-        // Both columns live on the junction, whatever the cardinality: `fillToManyThroughRelation`,
-        // `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.
+        // 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.
         relOpts.references = [
             ...meta.ids.map((key) => ({ local: junctionColumn(meta, key), foreign: key })),
             ...relMeta.ids.map((key) => ({ local: junctionColumn(relMeta, key), foreign: key })),
@@ -372,11 +393,9 @@ function fillOwningSide(at, meta, relKey, relOpts) {
         };
     }
 }
-function fillInverseSide(at, meta, relOpts) {
+function fillInverseSide(at, meta, relOpts, mappedBy) {
     const relEntity = relOpts.entity();
     const relMeta = getMeta(relEntity);
-    const mappedBy = getMappedByKey(relOpts);
-    relOpts.mappedBy = mappedBy;
     if (relOpts.references)
         return;
     if (relMeta.fields[mappedBy]) {
@@ -448,13 +467,6 @@ function fillForeignKeyRelations(meta) {
 function junctionColumn(meta, idKey) {
     return lowerFirst(entityName(meta)) + upperFirst(fieldOf(meta, 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;
-}
 /** Every key the entity marks, in declaration order. More than one is a composite primary key. */
 function getIdKeys(meta) {
     return getKeys(meta.fields).filter((key) => meta.fields[key]?.isId);

package/dist/http/handler.d.ts

@@ -49,8 +49,8 @@ export type HookContext<E extends object, Ctx = unknown> = {
 export type Hook<Ctx = unknown> = <E extends object>(ctx: HookContext<E, Ctx>) => void | Promise<void>;
 export type ResponseHook<Ctx = unknown> = <E extends object>(ctx: HookContext<E, Ctx>, envelope: RequestSuccessResponse<unknown>) => void | Promise<void>;
 export type RequestHandlerOptions<Ctx = unknown> = {
-    include?: Type<any>[];
-    exclude?: Type<any>[];
+    include?: Type<object>[];
+    exclude?: Type<object>[];
     /**
      * The URL segment an entity is addressed by, defaulting to its kebab-cased class name.
      *

package/dist/http/handler.js

@@ -27,7 +27,6 @@ export function createRequestHandler(opts) {
             "A route is the kebab-cased class name unless 'entityPath' says otherwise. Name them apart, " +
             "pass an 'entityPath', or pass only one of them in 'include'.");
     }
-    // oxlint-disable-next-line typescript/no-explicit-any -- heterogeneous entity map
     const entityByPath = new Map([...byPath].map(([path, [entity]]) => [path, entity]));
     return (req) => {
         const entity = entityByPath.get(req.entityPath);

package/dist/maria/mariaDialect.d.ts

@@ -1,5 +1,6 @@
+import { type RelationRows } from '../dialect/abstractSqlDialect.js';
 import { MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
-import type { DialectFeatures, EntityMeta, FieldOptions, Query, QueryContext, QueryOptions, Type, VectorDistance, VectorMetric } from '../type/index.js';
+import type { DialectFeatures, EntityMeta, FieldOptions, Query, QueryContext, Type, VectorDistance, VectorMetric } from '../type/index.js';
 export declare class MariaDialect extends MysqlLikeSqlDialect {
     readonly dialectName = "mariadb";
     readonly insertIdSource = "returning";
@@ -10,6 +11,11 @@ export declare class MariaDialect extends MysqlLikeSqlDialect {
      * and `CREATE INDEX` takes `IF NOT EXISTS` - which MySQL's grammar has no place for.
      */
     protected readonly featureOverrides: Partial<DialectFeatures>;
+    /**
+     * A derived table here reads no column of the statement around it, so the aggregate reads the
+     * related table itself, and orders and pages inside `JSON_ARRAYAGG`, which takes both.
+     */
+    protected appendRelationArray(ctx: QueryContext, { entity, query, alias, joins }: RelationRows): void;
     protected upsertReturning<E>(meta: EntityMeta<E>): string;
     /**
      * MariaDB supports neither MySQL's `->`/`->>` shorthand nor the base's chained form. `JSON_VALUE`
@@ -36,12 +42,13 @@ export declare class MariaDialect extends MysqlLikeSqlDialect {
      */
     protected appendVectorValue(ctx: QueryContext, value: readonly unknown[]): void;
     /**
-     * `SET STATEMENT mhnsw_ef_search=N FOR SELECT ...` - MariaDB scopes a variable to one statement, so
-     * the tuning needs neither a transaction nor a restore afterwards, and cannot leak to the next
-     * query on this pooled connection. That is why it prefixes the SQL here instead of coming back
-     * from `vectorTuningStatements`, which is Postgres's `SET LOCAL` shape.
+     * `mhnsw_ef_search` too, where a vector search is tuned. A setting scoped to one statement needs
+     * neither a transaction nor a restore, and cannot leak to the next query on this pooled connection,
+     * which is why the tuning is not `vectorTuningStatements`, Postgres's `SET LOCAL` shape.
      */
-    find<E>(ctx: QueryContext, entity: Type<E>, q?: Query<E>, opts?: QueryOptions, totalAlias?: string): void;
+    protected statementSettings<E>(entity: Type<E>, q: Query<E>): string[];
+    /** `SET STATEMENT ... FOR`, which scopes a variable to the statement it prefixes. */
+    protected applySettings(sql: string, settings: readonly string[]): string;
     /** The reverse: selecting a `VECTOR` column raw yields that blob, so it is read back as text. */
     protected selectFieldExpr(escapedColumn: string, field: FieldOptions): string;
 }

package/dist/maria/mariaDialect.js

@@ -1,3 +1,4 @@
+import { relationTermKey } from '../dialect/abstractSqlDialect.js';
 import { jsonPath } from '../dialect/jsonSql.js';
 import { MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
 import { getMeta } from '../entity/index.js';
@@ -18,6 +19,24 @@ export class MariaDialect extends MysqlLikeSqlDialect {
         vectorIndexRequiresNotNull: true,
         indexIfNotExists: true,
     };
+    /**
+     * A derived table here reads no column of the statement around it, so the aggregate reads the
+     * related table itself, and orders and pages inside `JSON_ARRAYAGG`, which takes both.
+     */
+    appendRelationArray(ctx, { entity, query, alias, joins }) {
+        const meta = getMeta(entity);
+        const terms = this.projection(ctx, entity, query, { prefix: alias, json: true }, joins);
+        const sortOpts = { prefix: alias, joins, distinct: query.$distinct };
+        const order = this.buildFragment(ctx, (fragmentCtx) => this.sort(fragmentCtx, entity, query.$sort, sortOpts));
+        const page = this.buildFragment(ctx, (fragmentCtx) => this.pager(fragmentCtx, query));
+        const from = this.buildFragment(ctx, (fragmentCtx) => {
+            this.selectRelationJoins(fragmentCtx, meta, alias, joins);
+            this.where(fragmentCtx, entity, query.$where, { prefix: alias });
+        });
+        const object = this.jsonObject(terms.map((term) => [relationTermKey(term), term.sql]));
+        const rows = `${query.$distinct ? 'DISTINCT ' : ''}${object}${order}${page}`;
+        ctx.append(`COALESCE((SELECT JSON_ARRAYAGG(${rows}) FROM ${this.tableRef(meta, alias).ref}${from}), JSON_ARRAY())`);
+    }
     upsertReturning(meta) {
         const returning = this.returningId(meta);
         return returning ? ` ${returning}` : '';
@@ -61,18 +80,19 @@ export class MariaDialect extends MysqlLikeSqlDialect {
         ctx.append(')');
     }
     /**
-     * `SET STATEMENT mhnsw_ef_search=N FOR SELECT ...` - MariaDB scopes a variable to one statement, so
-     * the tuning needs neither a transaction nor a restore afterwards, and cannot leak to the next
-     * query on this pooled connection. That is why it prefixes the SQL here instead of coming back
-     * from `vectorTuningStatements`, which is Postgres's `SET LOCAL` shape.
+     * `mhnsw_ef_search` too, where a vector search is tuned. A setting scoped to one statement needs
+     * neither a transaction nor a restore, and cannot leak to the next query on this pooled connection,
+     * which is why the tuning is not `vectorTuningStatements`, Postgres's `SET LOCAL` shape.
      */
-    find(ctx, entity, q = {}, opts, totalAlias) {
+    statementSettings(entity, q) {
         // `$candidates` first: `getMeta` would otherwise be resolved on every read, to discover that
         // almost none of them tune anything.
-        if (q.$candidates !== undefined && this.tunedVectorIndex(getMeta(entity), q)) {
-            ctx.append(`SET STATEMENT mhnsw_ef_search=${q.$candidates} FOR `);
-        }
-        super.find(ctx, entity, q, opts, totalAlias);
+        const tuned = q.$candidates !== undefined && this.tunedVectorIndex(getMeta(entity), q);
+        return [...(tuned ? [`mhnsw_ef_search=${q.$candidates}`] : []), ...super.statementSettings(entity, q)];
+    }
+    /** `SET STATEMENT ... FOR`, which scopes a variable to the statement it prefixes. */
+    applySettings(sql, settings) {
+        return `SET STATEMENT ${settings.join(', ')} FOR ${sql}`;
     }
     /** The reverse: selecting a `VECTOR` column raw yields that blob, so it is read back as text. */
     selectFieldExpr(escapedColumn, field) {