uql-orm 0.65.1 → 0.67.0

package/dist/dialect/queryContext.js

@@ -1,10 +1,4 @@
-/**
- * SqlQueryContext is an implementation of the QueryContext interface specifically for SQL-based dialects.
- * It follows the "Accumulator" or "Builder" pattern to construct SQL queries and their corresponding parameters.
- *
- * This pattern solves the problem of building complex SQL strings while safely managing parameterized values,
- * preventing SQL injection and handling dialect-specific parameter placeholders (e.g., '?' for MySQL, '$n' for PostgreSQL).
- */
+/** A SQL statement being built: its text, and the values it binds, placeholders numbered by the dialect. */
 export class SqlQueryContext {
     dialect;
     statement;
@@ -13,14 +7,8 @@ export class SqlQueryContext {
     params;
     tableAliases = new Set();
     /**
-     * @param dialect The SQL dialect used to determine how values should be formatted as placeholders.
-     * @param params An existing values array to bind into instead of a fresh one - shared by a
-     * fragment context built via {@link AbstractSqlDialect.buildFragment}, so a bound value's
-     * placeholder is numbered correctly against the real query from the moment it's added, rather
-     * than needing to be reconciled after the fact.
-     * @param statement The context this one renders a fragment of, which owns the claimed aliases: a
-     * fragment is part of one statement, so its aliases have to be unique across the whole of it.
-     * @param inlineValues See {@link QueryContext.inlineValues}; a fragment takes its statement's.
+     * `params` and `statement` are a fragment's parent's, so a value numbers against the whole statement and
+     * an alias is unique across it; a fragment inlines values where its statement does.
      */
     constructor(dialect, params = [], statement, inlineValues = false) {
         this.dialect = dialect;
@@ -51,13 +39,7 @@ export class SqlQueryContext {
         this.sqlChunks.push(this.dialect.addValue(this, value));
         return this;
     }
-    /**
-     * Pushes values to the parameters list without appending placeholders to the SQL.
-     * This is useful when the placeholder is already present in the SQL string or handled elsewhere.
-     *
-     * @param values The values to be added to the parameters.
-     * @returns The current context instance for method chaining.
-     */
+    /** Binds values whose placeholders the SQL already carries. */
     pushValue(...values) {
         this.params.push(...values.map((v) => this.dialect.normalizeValue(v)));
         return this;

package/dist/dialect/queryJoins.d.ts

@@ -35,11 +35,8 @@ export type QuerySortOptions = {
     readonly distinct?: boolean;
 };
 /**
- * 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.
+ * What the statement joins, from `$populate` and from a `$sort` by a to-one relation's field, so the
+ * columns, the `ORDER BY` and the lock agree. `claimAlias` names each join's table, parents first.
  */
 export declare function resolveQueryJoins<E>(meta: EntityMeta<E>, q: Query<E>, claimAlias?: (path: string) => string): QueryJoins;
 /**
@@ -50,13 +47,7 @@ export declare function resolveQueryJoins<E>(meta: EntityMeta<E>, q: Query<E>, c
 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
- * sort is a map of that relation's fields, and the path has to be joined - so it is answered once
- * here rather than per dialect, where the three checks had already drifted apart twice. Only the
- * remedy for an unjoined path is the dialect's business, which is what `unjoinable` says.
- */
+/** The join a sort may address at `path` with the relation's own sort map, or why it may not; `unjoinable` is the dialect's remedy. */
 export declare function resolveSortableJoin(relation: RelationMeta, path: string, value: unknown, joins: QueryJoins, unjoinable: string): {
     readonly join: QueryJoin;
     readonly sort: QuerySortMap<object>;

package/dist/dialect/queryJoins.js

@@ -2,11 +2,8 @@ import { getMeta, relationOf } from '../entity/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.
+ * What the statement joins, from `$populate` and from a `$sort` by a to-one relation's field, so the
+ * columns, the `ORDER BY` and the lock agree. `claimAlias` names each join's table, parents first.
  */
 export function resolveQueryJoins(meta, q, claimAlias = (path) => path) {
     if (!q.$populate && !q.$sort) {
@@ -91,13 +88,7 @@ function addSortJoins(joins, claimAlias, meta, sort, parent) {
         addSortJoins(joins, claimAlias, join.meta, value, join);
     }
 }
-/**
- * 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
- * sort is a map of that relation's fields, and the path has to be joined - so it is answered once
- * here rather than per dialect, where the three checks had already drifted apart twice. Only the
- * remedy for an unjoined path is the dialect's business, which is what `unjoinable` says.
- */
+/** The join a sort may address at `path` with the relation's own sort map, or why it may not; `unjoinable` is the dialect's remedy. */
 export function resolveSortableJoin(relation, path, value, joins, unjoinable) {
     if (isToManyRelation(relation)) {
         throw new TypeError(`cannot $sort by '${path}': a parent has many of them, so there is no single value to order by. Sort the relation's own rows inside $populate instead.`);

package/dist/dialect/vectorCast.d.ts

@@ -16,17 +16,7 @@ export declare function resolveVectorCast(field: {
  */
 export declare function toSparsevecLiteral(values: readonly unknown[]): string;
 /**
- * The inverse of the two literals above. pgvector hands a vector column back as **text**, so a read
- * that did not parse it returned a string from a field whose declared type is `number[]`: invisible
- * to the compiler, and invisible to any mocked test, because a mock returns the array the entity
- * promises. It surfaces only as arithmetic quietly producing nonsense on real rows.
- *
- * Driven by `cast`, never by the shape of the text, so this is the exact mirror of the write side:
- * a `sparsevec` column is read as `{1:1,3:2}/3` because that is what it was written as, and a dense
- * one as `[1,2,3]`. Both return the dense array the field type promises, whichever width the column
- * has. Sniffing the string instead would guess at a type the caller already knows.
- *
- * Returns `undefined` when the text does not match the column's own format, so a caller can keep the
- * raw value rather than replace it with something invented.
+ * A vector column's text as the dense array its field promises (pgvector returns text), read by `cast`
+ * as it was written, `{1:1,3:2}/3` or `[1,2,3]`; `undefined` where the text matches neither.
  */
 export declare function parseVectorLiteral(raw: string, cast: VectorCast): number[] | undefined;

package/dist/dialect/vectorCast.js

@@ -24,18 +24,8 @@ export function toSparsevecLiteral(values) {
     return `{${pairs}}/${values.length}`;
 }
 /**
- * The inverse of the two literals above. pgvector hands a vector column back as **text**, so a read
- * that did not parse it returned a string from a field whose declared type is `number[]`: invisible
- * to the compiler, and invisible to any mocked test, because a mock returns the array the entity
- * promises. It surfaces only as arithmetic quietly producing nonsense on real rows.
- *
- * Driven by `cast`, never by the shape of the text, so this is the exact mirror of the write side:
- * a `sparsevec` column is read as `{1:1,3:2}/3` because that is what it was written as, and a dense
- * one as `[1,2,3]`. Both return the dense array the field type promises, whichever width the column
- * has. Sniffing the string instead would guess at a type the caller already knows.
- *
- * Returns `undefined` when the text does not match the column's own format, so a caller can keep the
- * raw value rather than replace it with something invented.
+ * A vector column's text as the dense array its field promises (pgvector returns text), read by `cast`
+ * as it was written, `{1:1,3:2}/3` or `[1,2,3]`; `undefined` where the text matches neither.
  */
 export function parseVectorLiteral(raw, cast) {
     const text = raw.trim();
@@ -63,13 +53,7 @@ function parseSparse(text) {
     }
     return dense;
 }
-/**
- * `[1,0,2]`, whatever width the column has.
- *
- * A dense literal is valid JSON by construction, so parsing it as JSON is both stricter and cheaper
- * than splitting: `[1,,2]` throws here, where `split(',').map(Number)` would have turned the hole
- * into a 0.
- */
+/** `[1,0,2]`, parsed as the JSON it is, which refuses a hole `split` would read as 0. */
 function parseDense(text) {
     if (!text.startsWith('[') || !text.endsWith(']'))
         return undefined;

package/dist/dialect/vectorSqlDialect.d.ts

@@ -1,48 +1,23 @@
-import type { EntityIndexMeta, EntityMeta, FieldOptions, Query, QueryContext, QueryVectorSearch, VectorDistance, VectorMetric } from '../type/index.js';
+import type { EntityIndexMeta, EntityMeta, FieldOptions, Query, QueryContext, QueryVectorSearch, SqlDialectFeatures, VectorDistance, VectorMetric } from '../type/index.js';
 import { AbstractDialect } from './abstractDialect.js';
 import type { VectorCast } from './vectorCast.js';
 /**
- * Vector similarity search for SQL dialects: the `ORDER BY <distance>` expression, its projection as
- * a named score, and the index metadata the schema generator reads.
- *
- * A layer of its own because it is nearly self-contained - it needs only `escapeId` from the SQL
- * dialect above it - unlike the JSON operators, which are woven into the generic comparison
- * machinery (`neExpr`, `numericCast`, `formatIn`, ...) and belong with it.
- *
- * A dialect declares which metrics it has, and how it spells each, in {@link vectorMetrics}. Both
- * shapes live in that one map - an operator (`"col" <=> $1`, Postgres/CockroachDB) or a function call
- * (`VEC_DISTANCE_COSINE(col, ?)`, MariaDB/SQLite) - so {@link appendVectorSort} is written once and an
- * engine with no vector search at all is simply the empty map.
+ * Vector search for the SQL dialects: the distance a `$sort` ranks by and projects, and the ANN tuning.
+ * Each dialect lists its metrics in {@link vectorMetrics}, an operator or a function; empty means no search.
  */
 export declare abstract class VectorSqlDialect extends AbstractDialect {
     readonly vectorExtension: string | undefined;
+    abstract readonly features: SqlDialectFeatures;
     /**
-     * Whether {@link vectorTuningStatements} only applies inside a transaction. `SET LOCAL` does
-     * nothing outside one, so the querier - the only layer that knows whether a transaction is open -
-     * refuses instead of running a tuning that would silently not apply.
-     */
-    readonly vectorTuningNeedsTransaction: boolean;
-    /**
-     * `SET`s that widen an ANN index's search for one query, run before it on the same connection.
-     *
-     * Keyed off `$sort` rather than a `$where` `$near`, because the ANN index is what ranks: pgvector
-     * reaches for HNSW on an `ORDER BY distance LIMIT`, while a bare distance predicate scans whatever
-     * the planner picks. Tuning a query that never touches the index would set a knob for nothing.
-     *
-     * Empty by default: SQLite, libSQL and Turso compute every distance, so there is no candidate list
-     * to widen, and a field with no ANN index has nothing to tune either.
+     * `SET`s widening an ANN index's search for one query, run before it on its connection. Keyed off `$sort`,
+     * since the index is what ranks. Empty where every distance is computed anyway.
      */
     vectorTuningStatements<E>(_meta: EntityMeta<E>, _q: Query<E>): readonly string[];
     /** The `$sort` key carrying a vector search, if the query ranks by one. */
     protected vectorSortKey<E>(q: Query<E>): string | undefined;
     /**
-     * The ANN index `$candidates` would tune for this query, and nothing when there is none to tune -
-     * no `$candidates`, no vector ranking, or a field with no ANN index on it. One place, so the two
-     * dialects that act on it cannot disagree about when tuning applies.
-     *
-     * Validates here rather than at each emitter because the number is spelled into the statement
-     * rather than bound: `SET LOCAL hnsw.ef_search = $1` is not a thing either engine accepts. `/http`
-     * casts client JSON straight to `Query`, so `'abc'` and `null` both reach this.
+     * The ANN index `$candidates` tunes for the query, or nothing to tune. Checked here, since the number is
+     * spelled into a `SET` rather than bound, and `/http` input is untyped.
      */
     protected tunedVectorIndex<E>(meta: EntityMeta<E>, q: Query<E>): EntityIndexMeta | undefined;
     /**
@@ -67,11 +42,6 @@ export declare abstract class VectorSqlDialect extends AbstractDialect {
      * dialect needing a conversion around it (`$1::vector`, `VEC_FromText(?)`) declares it once.
      */
     protected appendVectorValue(ctx: QueryContext, value: readonly unknown[], _field?: FieldOptions): void;
-    /**
-     * Whether this engine has pgvector's narrower vector types (`halfvec`, `sparsevec`) or only the one.
-     * Declared by the dialect that has them rather than looked up in a table keyed by dialect name.
-     */
-    protected readonly hasNarrowVectorTypes: boolean;
     /**
      * The vector type this dialect actually has for a declared one, so the cast follows the column
      * rather than naming a type the engine does not define.

package/dist/dialect/vectorSqlDialect.js

@@ -3,35 +3,14 @@ import { findVectorIndex, findVectorSort } from '../util/dialect.util.js';
 import { entityName } from '../util/object.util.js';
 import { AbstractDialect } from './abstractDialect.js';
 /**
- * Vector similarity search for SQL dialects: the `ORDER BY <distance>` expression, its projection as
- * a named score, and the index metadata the schema generator reads.
- *
- * A layer of its own because it is nearly self-contained - it needs only `escapeId` from the SQL
- * dialect above it - unlike the JSON operators, which are woven into the generic comparison
- * machinery (`neExpr`, `numericCast`, `formatIn`, ...) and belong with it.
- *
- * A dialect declares which metrics it has, and how it spells each, in {@link vectorMetrics}. Both
- * shapes live in that one map - an operator (`"col" <=> $1`, Postgres/CockroachDB) or a function call
- * (`VEC_DISTANCE_COSINE(col, ?)`, MariaDB/SQLite) - so {@link appendVectorSort} is written once and an
- * engine with no vector search at all is simply the empty map.
+ * Vector search for the SQL dialects: the distance a `$sort` ranks by and projects, and the ANN tuning.
+ * Each dialect lists its metrics in {@link vectorMetrics}, an operator or a function; empty means no search.
  */
 export class VectorSqlDialect extends AbstractDialect {
     vectorExtension = undefined;
     /**
-     * Whether {@link vectorTuningStatements} only applies inside a transaction. `SET LOCAL` does
-     * nothing outside one, so the querier - the only layer that knows whether a transaction is open -
-     * refuses instead of running a tuning that would silently not apply.
-     */
-    vectorTuningNeedsTransaction = false;
-    /**
-     * `SET`s that widen an ANN index's search for one query, run before it on the same connection.
-     *
-     * Keyed off `$sort` rather than a `$where` `$near`, because the ANN index is what ranks: pgvector
-     * reaches for HNSW on an `ORDER BY distance LIMIT`, while a bare distance predicate scans whatever
-     * the planner picks. Tuning a query that never touches the index would set a knob for nothing.
-     *
-     * Empty by default: SQLite, libSQL and Turso compute every distance, so there is no candidate list
-     * to widen, and a field with no ANN index has nothing to tune either.
+     * `SET`s widening an ANN index's search for one query, run before it on its connection. Keyed off `$sort`,
+     * since the index is what ranks. Empty where every distance is computed anyway.
      */
     vectorTuningStatements(_meta, _q) {
         return [];
@@ -41,13 +20,8 @@ export class VectorSqlDialect extends AbstractDialect {
         return findVectorSort(q.$sort)?.key;
     }
     /**
-     * The ANN index `$candidates` would tune for this query, and nothing when there is none to tune -
-     * no `$candidates`, no vector ranking, or a field with no ANN index on it. One place, so the two
-     * dialects that act on it cannot disagree about when tuning applies.
-     *
-     * Validates here rather than at each emitter because the number is spelled into the statement
-     * rather than bound: `SET LOCAL hnsw.ef_search = $1` is not a thing either engine accepts. `/http`
-     * casts client JSON straight to `Query`, so `'abc'` and `null` both reach this.
+     * The ANN index `$candidates` tunes for the query, or nothing to tune. Checked here, since the number is
+     * spelled into a `SET` rather than bound, and `/http` input is untyped.
      */
     tunedVectorIndex(meta, q) {
         const candidates = q.$candidates;
@@ -83,17 +57,12 @@ export class VectorSqlDialect extends AbstractDialect {
     appendVectorValue(ctx, value, _field) {
         ctx.addValue(`[${value.join(',')}]`);
     }
-    /**
-     * Whether this engine has pgvector's narrower vector types (`halfvec`, `sparsevec`) or only the one.
-     * Declared by the dialect that has them rather than looked up in a table keyed by dialect name.
-     */
-    hasNarrowVectorTypes = false;
     /**
      * The vector type this dialect actually has for a declared one, so the cast follows the column
      * rather than naming a type the engine does not define.
      */
     supportedVectorType(cast) {
-        return this.hasNarrowVectorTypes ? cast : 'vector';
+        return this.features.narrowVectorTypes ? cast : 'vector';
     }
     /**
      * The distance a vector `$sort` projects, which the projection names after `$project`. Delegates to

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

@@ -1,11 +1,7 @@
 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
- * decorator spec, so this object is the only channel between them and the class decorator that does.
- *
- * The writable counterpart of `EntityMembers`, which is what registration reads: this one is written
- * into member by member, so every map is present and none of them is readonly.
+ * What the member decorators record for one class, until `@Entity()` or `defineEntity` drains it: the
+ * only channel from a member decorator to its class. The writable counterpart of `EntityMembers`.
  */
 export type MemberRegistrations = {
     readonly fields: Record<string, FieldOptions>;
@@ -13,13 +9,8 @@ export type MemberRegistrations = {
     readonly hooks: Partial<Record<HookEvent, string[]>>;
 };
 /**
- * The calling class's own registrations, created on first use.
- *
- * Deliberately holds **only** this class's members: inheritance is resolved later by walking the class
- * prototype chain, not by reading through the metadata object's. tsc chains a subclass's metadata to its
- * parent's and SWC does not, so anything built on that chain would work under one compiler and quietly
- * lose inherited fields under the other. Keeping each bag to its own members also means a parent's map
- * is never shared with its subclasses, and hooks cannot be registered twice.
+ * The class's own registrations, created on first use, never read through a parent's: inheritance walks
+ * the class chain, since not every compiler chains decorator metadata.
  */
 export declare function memberRegistrations(metadata: DecoratorMetadata): MemberRegistrations;
 /**
@@ -28,11 +19,7 @@ export declare function memberRegistrations(metadata: DecoratorMetadata): Member
  */
 export declare function drainRegistrations(metadata: DecoratorMetadata | undefined): MemberRegistrations | undefined;
 /**
- * The registrations a class made for itself.
- *
- * @remarks Only usable once the class is fully defined, which is why `@Entity()` reads
- * `context.metadata` instead: TypeScript attaches `Symbol.metadata` to the class *after* its class
- * decorators return. Ancestors are always fully defined by then, so this is how inherited members are
- * collected.
+ * The registrations a class made for itself, readable once it is fully defined: `@Entity()` reads
+ * `context.metadata` instead, since the class gets `Symbol.metadata` after its decorators return.
  */
 export declare function ownRegistrations(entity: Type<unknown>): MemberRegistrations | undefined;

package/dist/entity/decorator/bag.js

@@ -1,26 +1,14 @@
 /**
- * Polyfill `Symbol.metadata`, which no runtime we support defines yet (checked on Node 24 and Bun
- * 1.3): TypeScript's decorator emit reads it to decide whether to build the metadata object at all, so
- * without this every `context.metadata` is `undefined` and field registration is silently dropped
- * rather than failing.
- *
- * `Symbol.for`, not `Symbol()`, so a duplicated copy of this module (HMR, federated bundles, ESM+CJS
- * dual-loading) lands on the same symbol, and so it agrees with the key esbuild and SWC fall back to
- * (`Symbol.metadata ?? Symbol.for('Symbol.metadata')`). Assigned through a widened alias because the
- * lib declares the property `readonly`; when a runtime does define it, `??=` leaves it alone.
+ * Polyfills `Symbol.metadata`, without which TypeScript builds no `context.metadata` and every field is
+ * silently dropped. `Symbol.for`, the key esbuild and SWC fall back to, so duplicated modules agree.
  */
 const symbolCtor = Symbol;
 symbolCtor.metadata ??= Symbol.for('Symbol.metadata');
 /** Where member registrations live on the per-class metadata object. */
 const registrations = Symbol.for('uql-orm/entity/decoratorMembers');
 /**
- * The calling class's own registrations, created on first use.
- *
- * Deliberately holds **only** this class's members: inheritance is resolved later by walking the class
- * prototype chain, not by reading through the metadata object's. tsc chains a subclass's metadata to its
- * parent's and SWC does not, so anything built on that chain would work under one compiler and quietly
- * lose inherited fields under the other. Keeping each bag to its own members also means a parent's map
- * is never shared with its subclasses, and hooks cannot be registered twice.
+ * The class's own registrations, created on first use, never read through a parent's: inheritance walks
+ * the class chain, since not every compiler chains decorator metadata.
  */
 export function memberRegistrations(metadata) {
     if (!Object.hasOwn(metadata, registrations)) {
@@ -41,12 +29,8 @@ export function drainRegistrations(metadata) {
     return own;
 }
 /**
- * The registrations a class made for itself.
- *
- * @remarks Only usable once the class is fully defined, which is why `@Entity()` reads
- * `context.metadata` instead: TypeScript attaches `Symbol.metadata` to the class *after* its class
- * decorators return. Ancestors are always fully defined by then, so this is how inherited members are
- * collected.
+ * The registrations a class made for itself, readable once it is fully defined: `@Entity()` reads
+ * `context.metadata` instead, since the class gets `Symbol.metadata` after its decorators return.
  */
 export function ownRegistrations(entity) {
     const metadata = Object.getOwnPropertyDescriptor(entity, Symbol.metadata)?.value;

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

@@ -1,20 +1,15 @@
-import type { EntityIndexColumnInput, EntityIndexOptions, EntityOptions, FilterOptions, RefMap, Type } from '../../type/index.js';
+import type { EntityIndexColumnInput, EntityIndexOptions, EntityOptions, FilterName, FilterOptions, RefMap, Type } from '../../type/index.js';
 /**
- * Marks a class as an entity and finalizes its metadata.
- *
- * @remarks Takes the registrations from `context.metadata` rather than from the class. Member
- * decorators have already run by the time a class decorator does, but TypeScript defines
- * `Symbol.metadata` on the class *after* the class decorators return, so reading `entity[Symbol.metadata]`
- * here would find only what the base class left behind. `defineEntity` reads it off the class instead,
- * which is correct for the imperative path because it runs later still.
+ * Marks a class as an entity and finalizes its metadata, draining `context.metadata`: the class gets
+ * `Symbol.metadata` only after its decorators return.
  */
-export declare function Entity<E>(opts?: EntityOptions<E>): (entity: Type<E>, context?: ClassDecoratorContext) => void;
+export declare function Entity<E>(opts?: NoInfer<EntityOptions<E>>): (entity: Type<E>, context?: ClassDecoratorContext) => void;
 /**
  * Registers a named `$where` filter, applied to every query unless bypassed via `QueryOptions.filters`.
  *
  * @example `@Filter('active', { where: { status: 'active' }, default: false })`
  */
-export declare function Filter<E>(name: string, opts: FilterOptions<E>): (entity: Type<E>) => void;
+export declare function Filter<E, N extends string>(name: FilterName<N>, opts: FilterOptions<E>): (entity: Type<E>) => void;
 /**
  * Declares a composite index, its columns read off the entity's refs, so `@Index((user) => [user.nope])`
  * does not compile and a rename reaches every column. Stacks, so several may sit above one class.

package/dist/entity/decorator/entity.js

@@ -3,13 +3,8 @@ import { drainRegistrations } from './bag.js';
 // The class-level decorators. Unlike the member ones they receive the class, so each is a direct call
 // into the registry with no bag in between.
 /**
- * Marks a class as an entity and finalizes its metadata.
- *
- * @remarks Takes the registrations from `context.metadata` rather than from the class. Member
- * decorators have already run by the time a class decorator does, but TypeScript defines
- * `Symbol.metadata` on the class *after* the class decorators return, so reading `entity[Symbol.metadata]`
- * here would find only what the base class left behind. `defineEntity` reads it off the class instead,
- * which is correct for the imperative path because it runs later still.
+ * Marks a class as an entity and finalizes its metadata, draining `context.metadata`: the class gets
+ * `Symbol.metadata` only after its decorators return.
  */
 export function Entity(opts) {
     return (entity, context) => {

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

@@ -1,15 +1,7 @@
-import type { EntityGetter, FieldOptions, FieldType, IdValue, NamedIdKey, RelationManyToManyOptions, RelationManyToOneOptions, RelationOneToManyOptions, RelationOneToOneOptions, TsTypeOf } from '../../type/index.js';
+import type { EntityGetter, FieldOptions, FieldType, HasCompositeKey, IdValue, NamedIdKey, RejectKeys, 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, 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.
- *
- * Needed because the decorators capture their options as a naked type parameter, and TypeScript
- * skips excess-property checking on one of those: `@Field({ nulable: true })` compiled and was
- * silently ignored. Resolves to `unknown` - an inert intersection member - when there are none.
- */
-type RejectUnknown<O, Known> = [Exclude<keyof O, keyof Known>] extends [never] ? unknown : Record<Exclude<keyof O, keyof Known> & string, never>;
 /**
  * The property type a set of field options describes: the declared `type`, narrowed by `enum` to the
  * values that type admits (so `enum: [2]` stays off a `String`), or else the referenced key's own type,
@@ -21,32 +13,23 @@ type DeclaredValue<O> = O extends {
     readonly enum: infer E extends readonly unknown[];
 } ? EnumValue<Extract<E[number], TsTypeOf<T>>, TsTypeOf<T>> : TsTypeOf<T> : O extends {
     readonly references: EntityGetter<infer E>;
-} ? IdValue<E> : never;
-/**
- * The enum's members, or a named complaint when they widened.
- *
- * `['a', 'b']` without `as const` infers `string[]`, whose member type is the field's own type and
- * so narrows nothing - the check would be silently off. Resolving to a type no property can hold
- * makes that a compile error that says why, rather than a decoration.
- */
+} ? HasCompositeKey<E> extends true ? {
+    readonly __compositeKeyNeedsAColumnPerKey: true;
+} : IdValue<E> : never;
+/** The enum's members, or a named complaint where they widened for lack of `as const`, which would check nothing. */
 type EnumValue<Members, Declared> = Declared extends Members ? {
     readonly __enumNeedsAsConst: true;
 } : Members;
 /**
- * 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.
- *
+ * Declares a persisted field, its `type` checked against the property's.
  * @example `@Field({ type: String }) name?: string;`
- * @example `@Field({ references: () => User }) userId?: string;` (where `User.id` is a `uuid`)
- * @example `@Field({ type: Number, computed: (line) => raw`${line.qty} * ${line.price}` }) total?: number;`
+ * @example `@Field({ references: () => User }) userId?: string;`
  */
 export declare function Field<This, O extends FieldOptions<DeclaredValue<O>, This> & ({
     type: FieldType;
 } | {
     references: EntityGetter;
-}) & RejectUnknown<O, FieldOptions> & RejectIncompatible<O>>(opts: O): MemberDecorator<DeclaredValue<O> | undefined, This>;
+}) & RejectKeys<Exclude<keyof O, keyof FieldOptions>> & RejectIncompatible<O>>(opts: O): MemberDecorator<DeclaredValue<O> | undefined, This>;
 /**
  * A key the type level cannot name, reported on each `@Id` that leaves it unnamed. Where no `idKey`
  * brand and no conventional name applies, `IdKey` falls back to every field, and `IdValue`,
@@ -58,16 +41,12 @@ type KeyIsNamed<This> = [NamedIdKey<This>] extends [never] ? {
 /** {@link MemberDecorator} that also constrains the class, which is where a key is named. */
 type IdDecorator<V> = <This>(value: undefined, context: ClassFieldDecoratorContext<This, V> & KeyIsNamed<This>) => void;
 /**
- * Declares the primary key, checked the same way as `@Field` and additionally against the class:
- * a key not named `id`, `_id` or `uuid` has to be named by the `idKey` brand.
- *
- * @example `@Id({ type: Number }) id?: number;`
+ * Declares the primary key, checked like `@Field`; a key not named `id`, `_id` or `uuid` needs the `idKey` brand.
  * @example `@Id({ type: 'uuid', onInsert: uuidv7 }) id?: string;`
- * @example `[idKey]?: 'pk';` beside `@Id({ type: Number }) pk?: number;`
  */
 export declare function Id<O extends FieldOptions<DeclaredValue<O>> & {
     type: FieldType;
-} & RejectUnknown<O, FieldOptions> & RejectIncompatible<O> & {
+} & RejectKeys<Exclude<keyof O, keyof FieldOptions>> & RejectIncompatible<O> & {
     readonly nullable?: false;
 }>(opts: O): IdDecorator<DeclaredValue<O> | undefined>;
 /**

package/dist/entity/decorator/members.js

@@ -1,14 +1,9 @@
 import { relationRegistration } from '../metadata/definition.js';
 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.
- *
+ * Declares a persisted field, its `type` checked against the property's.
  * @example `@Field({ type: String }) name?: string;`
- * @example `@Field({ references: () => User }) userId?: string;` (where `User.id` is a `uuid`)
- * @example `@Field({ type: Number, computed: (line) => raw`${line.qty} * ${line.price}` }) total?: number;`
+ * @example `@Field({ references: () => User }) userId?: string;`
  */
 export function Field(opts) {
     return (_value, context) => {
@@ -16,12 +11,8 @@ export function Field(opts) {
     };
 }
 /**
- * Declares the primary key, checked the same way as `@Field` and additionally against the class:
- * a key not named `id`, `_id` or `uuid` has to be named by the `idKey` brand.
- *
- * @example `@Id({ type: Number }) id?: number;`
+ * Declares the primary key, checked like `@Field`; a key not named `id`, `_id` or `uuid` needs the `idKey` brand.
  * @example `@Id({ type: 'uuid', onInsert: uuidv7 }) id?: string;`
- * @example `[idKey]?: 'pk';` beside `@Id({ type: Number }) pk?: number;`
  */
 export function Id(opts) {
     return (_value, context) => {

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

@@ -1,4 +1,4 @@
-import type { EntityData, EntityIndexInput, EntityMembers, EntityMeta, EntityOptions, FieldMeta, FieldOptions, FilterOptions, HookEvent, IdKey, RelationKey, RelationMeta, RelationOptions, RelationRegistration, Type, WrittenId } from '../../type/index.js';
+import type { EntityData, EntityIndexInput, EntityMembers, EntityMeta, EntityOptions, FieldMeta, FieldOptions, FilterName, 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>;
 /** `T` is the relation's target, independent of the owner `E`. */
@@ -15,7 +15,7 @@ export declare function defineHook<E>(entity: Type<E>, methodName: string, event
  * 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<E>): EntityMeta<E>;
-export declare function defineFilter<E>(entity: Type<E>, name: string, opts: FilterOptions<E>): EntityMeta<E>;
+export declare function defineFilter<E, N extends string>(entity: Type<E>, name: FilterName<N>, opts: FilterOptions<E>): EntityMeta<E>;
 /**
  * Feeds fields, relations and hooks into the `define*` primitives, so the decorators and the imperative
  * API converge on one registration path before anything is finalized.
@@ -39,25 +39,9 @@ export declare function soleIdOf<E>(meta: EntityMeta<E>, what: string): IdKey<E>
 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;
-/**
- * Whether the caller named every column of the row's primary key, so {@link idOf} can name the row.
- *
- * `!= null` rather than falsiness: `0` and an empty string are ids a row can legitimately carry, and
- * reading them as "no id" is how a write of that row turned into a second insert. Distinct from
- * "does the row carry this column", which an insert asks of `undefined` alone because that is what
- * decides whether the column appears in its `VALUES` list at all.
- */
+/** Whether the row names every column of its primary key, `0` and `''` included. */
 export declare function namesKey<E>(meta: EntityMeta<E>, row: EntityData<E>): boolean;
-/**
- * A row's primary key: the value itself for a single key, an object carrying every key for a
- * composite - which is {@link WrittenId}, and reads as the {@link EntityId} a `$where` takes.
- *
- * What a settled write names its rows by, and what a write hands back. Naming a composite row by one
- * of its columns would address every row agreeing on that one.
- *
- * `WrittenId` does not reduce for an unresolved `E`, so which branch this entity is in cannot be
- * proven here, only checked - which is what `ids.length` does.
- */
+/** A row's primary key: its value, or a map of every column on a composite, checked at run time. */
 export declare function idOf<E>(meta: EntityMeta<E>, row: EntityData<E>): WrittenId<E>;
 /**
  * Forgets an entity, and reports whether there was one - for a registry that grows at runtime, where a
@@ -71,6 +55,6 @@ export declare function getMeta<E>(entity: Type<E>): EntityMeta<E>;
 /**
  * The foreign keys an entity holds: each owning to-one's columns, and each `@Field({ references })` no
  * relation joins on, as the many-to-one it describes, once its target has registered a key. What the
- * schema build constrains and a junction joins by, read once the relations holding them are settled.
+ * schema build constrains and a junction joins by, settling the relations holding them first.
  */
 export declare function foreignKeysOf<E>(meta: EntityMeta<E>): RelationMeta[];