uql-orm 0.21.0 → 0.23.0

package/dist/dialect/pgLikeSqlDialect.js

@@ -3,6 +3,7 @@ import { QueryRaw, } from '../type/index.js';
 import { escapeSingleQuotes } from '../util/sqlLiteral.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
 import { JSON_PULL_ALIAS, jsonSetTarget } from './jsonSql.js';
+import { resolveVectorCast, toSparsevecLiteral } from './vectorCast.js';
 /**
  * Shared AST/quoting/JSONB/full-text-search/vector-search implementation between Postgres and
  * CockroachDB (wire- and SQL-compatible for everything below, including `to_tsvector`/`to_tsquery`
@@ -24,7 +25,7 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         renameColumn: true,
         foreignKeyAlter: true,
         columnComment: false,
-        vectorIndexStyle: 'create',
+        inlineVectorIndex: false,
         vectorSupportsLength: true,
         supportsTimestamptz: true,
         defaultStringAsText: true,
@@ -42,12 +43,16 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
     alterColumnStrategy = 'separate-clauses';
     insertIdSource = 'returning';
     maxBindValues = 65535;
-    vectorOpsClass = new Map([
-        ['cosine', 'vector_cosine_ops'],
-        ['l2', 'vector_l2_ops'],
-        ['inner', 'vector_ip_ops'],
-        ['l1', 'vector_l1_ops'],
-        ['hamming', 'bit_hamming_ops'],
+    /**
+     * Each metric's pgvector distance operator and the operator-class suffix its index takes, in one
+     * place so a dialect cannot end up with the operator but not the opclass. The key set is the single
+     * source of truth for which metrics the dialect supports at all: CockroachDB narrows it to three.
+     */
+    vectorMetrics = new Map([
+        ['cosine', { op: '<=>', opsSuffix: 'cosine' }],
+        ['l2', { op: '<->', opsSuffix: 'l2' }],
+        ['inner', { op: '<#>', opsSuffix: 'ip' }],
+        ['l1', { op: '<+>', opsSuffix: 'l1' }],
     ]);
     normalizeValue(value) {
         if (value != null && typeof value === 'object' && Array.isArray(value)) {
@@ -55,55 +60,88 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         }
         return super.normalizeValue(value);
     }
-    placeholder(index) {
-        return `$${index}`;
+    /** pgvector's own index types; CockroachDB's native one widens this. */
+    isVectorIndex(index) {
+        return index.type === 'hnsw' || index.type === 'ivfflat';
+    }
+    indexAccessMethod(index) {
+        return index.type ? ` USING ${index.type}` : '';
+    }
+    indexFeatures = new Set([
+        'expression',
+        'nullsOrder',
+        'opsClass',
+        'include',
+    ]);
+    /**
+     * A vector index's operator class is named `{type}_{metric}_ops`: an index on a `halfvec` column
+     * needs `halfvec_cosine_ops`, and `vector_cosine_ops` there is rejected outright. An unsupported
+     * distance throws rather than being omitted, since a bare `USING hnsw ("embedding")` would build
+     * with the dialect's default metric instead of the one requested, with nothing signalling it.
+     * Everything else takes the operator class the entry declares, e.g. `jsonb_path_ops` for GIN.
+     */
+    indexColumnOpsClass(entry, index) {
+        if (!this.isVectorIndex(index) || !index.distance) {
+            return entry.opsClass ? ` ${entry.opsClass}` : '';
+        }
+        const metric = this.vectorMetrics.get(index.distance);
+        if (!metric) {
+            throw new TypeError(`${this.dialectName} does not support vector distance metric: ${index.distance} (index "${index.name}")`);
+        }
+        const vectorType = this.supportedVectorType(index.vectorType ?? 'vector');
+        const opsClass = `${vectorType}_${metric.opsSuffix}_ops`;
+        // IVFFlat has neither a sparsevec nor an L1 operator class; HNSW has all of them (pgvector 0.8.2).
+        if (index.type === 'ivfflat' && (vectorType === 'sparsevec' || index.distance === 'l1')) {
+            throw new TypeError(`ivfflat has no ${opsClass} operator class (index "${index.name}"); use hnsw`);
+        }
+        return ` ${opsClass}`;
+    }
+    indexInclude(index) {
+        return index.include?.length ? ` INCLUDE (${index.include.map((column) => this.escapeId(column)).join(', ')})` : '';
     }
-    insert(ctx, entity, payload, opts) {
-        super.insert(ctx, entity, payload, opts);
-        ctx.append(' ' + this.returningId(entity));
+    indexTuning(index) {
+        if (!this.isVectorIndex(index)) {
+            return '';
+        }
+        const params = [];
+        if (index.m !== undefined)
+            params.push(`m = ${index.m}`);
+        if (index.efConstruction !== undefined)
+            params.push(`ef_construction = ${index.efConstruction}`);
+        if (index.lists !== undefined)
+            params.push(`lists = ${index.lists}`);
+        return params.length > 0 ? ` WITH (${params.join(', ')})` : '';
     }
-    upsert(ctx, entity, conflictPaths, payload) {
-        this.buildUpsertOnConflict(ctx, entity, conflictPaths, payload);
+    placeholder(index) {
+        return `$${index}`;
     }
     /**
-     * Shared `INSERT ... ON CONFLICT (...) DO UPDATE/NOTHING RETURNING ...` builder, assembling
-     * everything upfront rather than handing back fragments, for the `$N`-placeholder Postgres-wire
-     * dialects. `extraReturning` lets {@link PostgresDialect} append `(xmax = 0) AS "_created"` to
-     * detect insert-vs-update; CockroachDB has no `xmax`/`ctid` system columns, so it uses the default
-     * (empty) and `created` stays `undefined` in the result.
+     * The same statement as the base, binding the assignments into the main context instead of a second
+     * one: `$N` placeholders carry their own index, so the values need not be in statement order, and
+     * computing them first is what keeps `appendInsertValues`' `onInsert` fields out of the update set.
      */
-    buildUpsertOnConflict(ctx, entity, conflictPaths, payload, extraReturning = '') {
+    upsert(ctx, entity, conflictPaths, payload, extraReturning = '') {
         const meta = getMeta(entity);
-        const update = this.getUpsertUpdateAssignments(ctx, meta, conflictPaths, payload, (name) => `EXCLUDED.${name}`);
-        const keysStr = this.getUpsertConflictPathsStr(meta, conflictPaths);
+        const update = this.getUpsertUpdateAssignments(ctx, meta, conflictPaths, payload, this.upsertExcluded);
+        const keys = this.getUpsertConflictPathsStr(meta, conflictPaths);
         const onConflict = update ? `DO UPDATE SET ${update}` : 'DO NOTHING';
-        super.insert(ctx, entity, payload);
-        ctx.append(` ON CONFLICT (${keysStr}) ${onConflict} ${this.returningId(entity)}${extraReturning}`);
+        this.appendInsertValues(ctx, entity, payload);
+        ctx.append(` ON CONFLICT (${keys}) ${onConflict} ${this.returningId(entity)}${extraReturning}`);
     }
     /**
-     * Full-text search: `to_tsvector(...) @@ websearch_to_tsquery(...)`. `websearch_to_tsquery` takes
-     * free-form user input (quoted phrases, `or`, `-negation`) and never raises a syntax error, unlike
-     * `to_tsquery`, which rejects anything unparseable - including a plain two-word search.
+     * `to_tsvector(...) @@ websearch_to_tsquery(...)`. `websearch_to_tsquery` takes free-form user input
+     * (quoted phrases, `or`, `-negation`) and never raises a syntax error, unlike `to_tsquery`, which
+     * rejects anything unparseable - including a plain two-word search.
      */
-    compare(ctx, entity, key, val, opts = {}) {
-        if (key === '$text') {
-            const meta = getMeta(entity);
-            const search = val;
-            const fields = (search.$fields ?? [])
-                .map((fKey) => {
-                const field = meta.fields[fKey];
-                const columnName = this.resolveColumnName(fKey, field);
-                return this.escapeId(columnName);
-            })
-                .join(` || ' ' || `);
-            // The config is bound once and its numbered placeholder reused by both calls.
-            const config = search.$config ? `${this.addValue(ctx.values, search.$config)}::regconfig, ` : '';
-            ctx.append(`to_tsvector(${config}${fields}) @@ websearch_to_tsquery(${config}`);
-            ctx.addValue(search.$value);
-            ctx.append(')');
-            return;
-        }
-        super.compare(ctx, entity, key, val, opts);
+    appendTextSearch(ctx, _entity, meta, search) {
+        const fields = (search.$fields ?? [])
+            .map((key) => this.escapeId(this.resolveColumnName(key, meta.fields[key])))
+            .join(` || ' ' || `);
+        // The config is bound once and its numbered placeholder reused by both calls.
+        const config = search.$config ? `${this.addValue(ctx.values, search.$config)}::regconfig, ` : '';
+        ctx.append(`to_tsvector(${config}${fields}) @@ websearch_to_tsquery(${config}`);
+        ctx.addValue(search.$value);
+        ctx.append(')');
     }
     jsonAll(ctx, jsonField, value) {
         return `${jsonField} @> ${this.jsonVal(ctx, value)}`;
@@ -146,9 +184,14 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
     appendJsonValue(ctx, value, type) {
         ctx.append(this.jsonVal(ctx, value, type));
     }
-    appendVectorValue(ctx, value) {
-        ctx.addValue(`[${value.join(',')}]`);
-        ctx.append('::vector');
+    /**
+     * pgvector needs the cast to pick the right type, and `sparsevec` needs its own literal: the dense
+     * `[1,0,2]` every other type takes is rejected as "invalid input syntax for type sparsevec".
+     */
+    appendVectorValue(ctx, value, field) {
+        const vectorType = this.supportedVectorType(resolveVectorCast(field));
+        ctx.addValue(vectorType === 'sparsevec' ? toSparsevecLiteral(value) : `[${value.join(',')}]`);
+        ctx.append(`::${vectorType}`);
     }
     /**
      * `create_if_missing => false` keeps an absent key (and a NULL column) untouched; `WITH
@@ -189,29 +232,15 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         const ph = this.addValue(ctx.values, json);
         return this.features.explicitJsonCast ? `(${ph}::text)::${type}` : `${ph}::${type}`;
     }
-    /**
-     * pgvector distance operators. Not every dialect supports every metric - see
-     * {@link CockroachDialect.vectorOpsClass} for which ones each dialect actually has; the
-     * `vectorOpsClass` key set (checked in `appendVectorSort` below via `vectorOpsClass.get`)
-     * is the single source of truth for that, not this map.
-     */
-    static VECTOR_OPS = {
-        cosine: '<=>',
-        l2: '<->',
-        inner: '<#>',
-        l1: '<+>',
-        hamming: '<~>',
-    };
     /** Emit a pgvector-style distance expression: `"col" <op> $N::<vectorType>`. */
     appendVectorSort(ctx, meta, key, search) {
-        const { colName, distance, vectorCast } = this.resolveVectorSortParams(meta, key, search);
-        if (!this.vectorOpsClass.get(distance)) {
+        const { colName, distance, field } = this.resolveVectorSortParams(meta, key, search);
+        const metric = this.vectorMetrics.get(distance);
+        if (!metric) {
             throw new TypeError(`${this.dialectName} does not support vector distance metric: ${distance}`);
         }
-        const op = PgLikeSqlDialect.VECTOR_OPS[distance];
-        ctx.append(`${this.escapeId(colName)} ${op} `);
-        ctx.addValue(`[${search.$vector.join(',')}]`);
-        ctx.append(`::${vectorCast}`);
+        ctx.append(`${this.escapeId(colName)} ${metric.op} `);
+        this.appendVectorValue(ctx, search.$vector, field);
     }
 }
 /**

package/dist/dialect/vectorCast.d.ts

@@ -2,10 +2,31 @@
  * Kept out of `schema/canonicalType.ts`: importing one function from that migration/codegen module
  * pulled all ~18 KB of its type-mapping tables into every consumer's bundle.
  */
+import type { DialectName } from '../type/querier.js';
 /** Vector cast types supported by pgvector. */
 export type VectorCast = 'vector' | 'halfvec' | 'sparsevec';
+/**
+ * The dialects that have more than one vector column type. pgvector is the only one: `halfvec` and
+ * `sparsevec` exist nowhere else (`HALFVEC(3)` is a syntax error on CockroachDB 26.2 and MariaDB 12.3,
+ * not merely unsupported at runtime), so a field declaring one is stored - and therefore cast - as
+ * plain `vector`. Both halves of that used to be stated separately, in this dialect layer and in the
+ * migration type maps.
+ */
+export declare const MULTI_VECTOR_TYPE_DIALECTS: ReadonlySet<DialectName>;
+/**
+ * Whether a declared field type is a vector of any width. Every dialect that treats vectors specially
+ * has to answer this for all three, not just `vector`: matching that one alone left `halfvec` and
+ * `sparsevec` fields binding as plain arrays on insert and reading back raw.
+ */
+export declare function isVectorFieldType(type: unknown): boolean;
 /** Resolves the effective cast from field options, `columnType` taking priority over `type`. */
 export declare function resolveVectorCast(field: {
     type?: unknown;
     columnType?: unknown;
 } | undefined): VectorCast;
+/**
+ * pgvector's `sparsevec` literal: 1-based `index:value` pairs of the non-zero elements, then the
+ * dimension count (`{1:1,3:2}/3`). A dense `[1,0,2]` is rejected outright by that type, so an entity
+ * declaring `type: 'sparsevec'` still hands UQL the dense array its field type promises.
+ */
+export declare function toSparsevecLiteral(values: readonly unknown[]): string;

package/dist/dialect/vectorCast.js

@@ -2,6 +2,22 @@
  * Kept out of `schema/canonicalType.ts`: importing one function from that migration/codegen module
  * pulled all ~18 KB of its type-mapping tables into every consumer's bundle.
  */
+/**
+ * The dialects that have more than one vector column type. pgvector is the only one: `halfvec` and
+ * `sparsevec` exist nowhere else (`HALFVEC(3)` is a syntax error on CockroachDB 26.2 and MariaDB 12.3,
+ * not merely unsupported at runtime), so a field declaring one is stored - and therefore cast - as
+ * plain `vector`. Both halves of that used to be stated separately, in this dialect layer and in the
+ * migration type maps.
+ */
+export const MULTI_VECTOR_TYPE_DIALECTS = new Set(['postgres']);
+/**
+ * Whether a declared field type is a vector of any width. Every dialect that treats vectors specially
+ * has to answer this for all three, not just `vector`: matching that one alone left `halfvec` and
+ * `sparsevec` fields binding as plain arrays on insert and reading back raw.
+ */
+export function isVectorFieldType(type) {
+    return type === 'vector' || type === 'halfvec' || type === 'sparsevec';
+}
 /** Resolves the effective cast from field options, `columnType` taking priority over `type`. */
 export function resolveVectorCast(field) {
     const raw = field?.columnType ?? field?.type;
@@ -11,3 +27,15 @@ export function resolveVectorCast(field) {
         return 'sparsevec';
     return 'vector';
 }
+/**
+ * pgvector's `sparsevec` literal: 1-based `index:value` pairs of the non-zero elements, then the
+ * dimension count (`{1:1,3:2}/3`). A dense `[1,0,2]` is rejected outright by that type, so an entity
+ * declaring `type: 'sparsevec'` still hands UQL the dense array its field type promises.
+ */
+export function toSparsevecLiteral(values) {
+    const pairs = values
+        .map((value, index) => `${index + 1}:${value}`)
+        .filter((_, index) => Number(values[index]) !== 0)
+        .join(',');
+    return `{${pairs}}/${values.length}`;
+}

package/dist/dialect/vectorSqlDialect.d.ts

@@ -14,8 +14,6 @@ import { type VectorCast } from './vectorCast.js';
  * {@link appendVectorSort} or filling {@link vectorDistanceFns}.
  */
 export declare abstract class VectorSqlDialect extends AbstractDialect {
-    /** Vector index operator classes, keyed by distance metric. Partial: not every dialect supports every metric. */
-    readonly vectorOpsClass: ReadonlyMap<VectorDistance, string> | undefined;
     readonly vectorExtension: string | undefined;
     /**
      * Mapping of UQL vector distance metrics to native SQL functions.
@@ -33,8 +31,17 @@ export declare abstract class VectorSqlDialect extends AbstractDialect {
         colName: string;
         distance: VectorDistance;
         field: FieldOptions | undefined;
-        vectorCast: VectorCast;
     };
+    /**
+     * Binds a vector, both as a persisted value and as the query vector of a distance expression, so a
+     * dialect needing a conversion around it (`$1::vector`, `VEC_FromText(?)`) declares it once.
+     */
+    protected appendVectorValue(ctx: QueryContext, value: readonly unknown[], _field?: FieldOptions): void;
+    /**
+     * 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. See {@link MULTI_VECTOR_TYPE_DIALECTS}.
+     */
+    protected supportedVectorType(cast: VectorCast): VectorCast;
     /**
      * Append a vector similarity function call: `fn(col, ?)`.
      * Used by dialects that express vector distance via SQL functions (SQLite, MariaDB).

package/dist/dialect/vectorSqlDialect.js

@@ -1,5 +1,5 @@
 import { AbstractDialect } from './abstractDialect.js';
-import { resolveVectorCast } from './vectorCast.js';
+import { MULTI_VECTOR_TYPE_DIALECTS } 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.
@@ -13,8 +13,6 @@ import { resolveVectorCast } from './vectorCast.js';
  * {@link appendVectorSort} or filling {@link vectorDistanceFns}.
  */
 export class VectorSqlDialect extends AbstractDialect {
-    /** Vector index operator classes, keyed by distance metric. Partial: not every dialect supports every metric. */
-    vectorOpsClass = undefined;
     vectorExtension = undefined;
     /**
      * Mapping of UQL vector distance metrics to native SQL functions.
@@ -30,21 +28,34 @@ export class VectorSqlDialect extends AbstractDialect {
         const field = meta.fields[key];
         const colName = this.resolveColumnName(key, field);
         const distance = search.$distance ?? field?.distance ?? 'cosine';
-        const vectorCast = resolveVectorCast(field);
-        return { colName, distance, field, vectorCast };
+        return { colName, distance, field };
+    }
+    /**
+     * Binds a vector, both as a persisted value and as the query vector of a distance expression, so a
+     * dialect needing a conversion around it (`$1::vector`, `VEC_FromText(?)`) declares it once.
+     */
+    appendVectorValue(ctx, value, _field) {
+        ctx.addValue(`[${value.join(',')}]`);
+    }
+    /**
+     * 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. See {@link MULTI_VECTOR_TYPE_DIALECTS}.
+     */
+    supportedVectorType(cast) {
+        return MULTI_VECTOR_TYPE_DIALECTS.has(this.dialectName) ? cast : 'vector';
     }
     /**
      * Append a vector similarity function call: `fn(col, ?)`.
      * Used by dialects that express vector distance via SQL functions (SQLite, MariaDB).
      */
     appendFunctionVectorSort(ctx, meta, key, search) {
-        const { colName, distance } = this.resolveVectorSortParams(meta, key, search);
+        const { colName, distance, field } = this.resolveVectorSortParams(meta, key, search);
         const fn = this.vectorDistanceFns.get(distance);
         if (!fn) {
             throw Error(`${this.dialectName} does not support vector distance metric: ${distance}`);
         }
         ctx.append(`${fn}(${this.escapeId(colName)}, `);
-        ctx.addValue(`[${search.$vector.join(',')}]`);
+        this.appendVectorValue(ctx, search.$vector, field);
         ctx.append(')');
     }
     /**
@@ -64,6 +75,6 @@ export class VectorSqlDialect extends AbstractDialect {
             this.appendFunctionVectorSort(ctx, meta, key, search);
             return;
         }
-        throw new TypeError('Vector similarity sort is not supported by this dialect. Use raw() for vector queries.');
+        throw new TypeError(`${this.dialectName} does not support vector similarity sort. Use raw() for vector queries.`);
     }
 }

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

@@ -0,0 +1,35 @@
+import type { FieldOptions, HookEvent, RelationOptions, 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.
+ */
+export type MemberRegistrations = {
+    readonly fields: Record<string, FieldOptions>;
+    readonly relations: Record<string, RelationOptions>;
+    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.
+ */
+export declare function memberRegistrations(metadata: DecoratorMetadata): MemberRegistrations;
+/**
+ * Takes the registrations belonging to `metadata`, leaving none behind, so finalizing an entity twice
+ * cannot register its hooks twice.
+ */
+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.
+ */
+export declare function ownRegistrations(entity: Type<unknown>): MemberRegistrations | undefined;

package/dist/entity/decorator/bag.js

@@ -0,0 +1,54 @@
+/**
+ * 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.
+ */
+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.
+ */
+export function memberRegistrations(metadata) {
+    if (!Object.hasOwn(metadata, registrations)) {
+        metadata[registrations] = { fields: {}, relations: {}, hooks: {} };
+    }
+    return metadata[registrations];
+}
+/**
+ * Takes the registrations belonging to `metadata`, leaving none behind, so finalizing an entity twice
+ * cannot register its hooks twice.
+ */
+export function drainRegistrations(metadata) {
+    if (!metadata || !Object.hasOwn(metadata, registrations)) {
+        return undefined;
+    }
+    const own = metadata[registrations];
+    delete metadata[registrations];
+    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.
+ */
+export function ownRegistrations(entity) {
+    const metadata = Object.getOwnPropertyDescriptor(entity, Symbol.metadata)?.value;
+    return drainRegistrations(metadata);
+}

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

@@ -1,2 +1,28 @@
-import type { EntityOptions, Type } from '../../type/index.js';
-export declare function Entity<E>(opts?: EntityOptions<E>): (entity: Type<E>) => void;
+import type { EntityOptions, FieldKey, FilterOptions, IndexColumnInput, IndexOptions, 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.
+ */
+export declare function Entity<E>(opts?: 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', { condition: { status: 'active' }, default: false })`
+ */
+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.
+ *
+ * `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: 'idx_users_fullname' })`
+ * @example `@Index(['email'], { unique: true })`
+ * @example `@Index(['status'], { where: "status = 'active'" })`
+ */
+export declare function Index<E>(columns: readonly IndexColumnInput<FieldKey<E>>[], options?: IndexOptions): (entity: Type<E>) => void;

package/dist/entity/decorator/entity.js

@@ -1,6 +1,44 @@
-import { defineEntity } from '../metadata/definition.js';
+import { applyMembers, defineEntity, defineFilter, defineIndex } from '../metadata/definition.js';
+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.
+ */
 export function Entity(opts) {
-    return (entity) => {
+    return (entity, context) => {
+        applyMembers(entity, drainRegistrations(context?.metadata));
         defineEntity(entity, opts);
     };
 }
+/**
+ * Registers a named `$where` filter, applied to every query unless bypassed via `QueryOptions.filters`.
+ *
+ * @example `@Filter('active', { condition: { status: 'active' }, default: false })`
+ */
+export function Filter(name, opts) {
+    return (entity) => {
+        defineFilter(entity, name, opts);
+    };
+}
+/**
+ * Declares a composite index. Stacks, so several may sit above one class.
+ *
+ * `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: 'idx_users_fullname' })`
+ * @example `@Index(['email'], { unique: true })`
+ * @example `@Index(['status'], { where: "status = 'active'" })`
+ */
+export function Index(columns, options = {}) {
+    return (entity) => {
+        defineIndex(entity, { ...options, columns });
+    };
+}

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

@@ -0,0 +1,51 @@
+import type { EntityGetter, FieldOptions, FieldType, 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;
+/**
+ * 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: () => 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.
+ */
+export declare function Field(opts: FieldOptions & {
+    readonly references: EntityGetter;
+}): MemberDecorator<unknown>;
+/**
+ * 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>;
+/**
+ * `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.
+ */
+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 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;
+export declare const AfterUpdate: () => <This>(_value: unknown, context: ClassMethodDecoratorContext<This>) => void;
+export declare const BeforeDelete: () => <This>(_value: unknown, context: ClassMethodDecoratorContext<This>) => void;
+export declare const AfterDelete: () => <This>(_value: unknown, context: ClassMethodDecoratorContext<This>) => void;
+export declare const AfterLoad: () => <This>(_value: unknown, context: ClassMethodDecoratorContext<This>) => void;
+export {};