uql-orm 0.20.2 → 0.22.0

package/dist/cockroachdb/crdbQuerier.d.ts

@@ -6,4 +6,3 @@ import type { CockroachDialect } from './cockroachDialect.js';
  */
 export declare class CrdbQuerier extends AbstractPgQuerier<PoolClient, CockroachDialect> {
 }
-//# sourceMappingURL=crdbQuerier.d.ts.map

package/dist/cockroachdb/crdbQuerier.js

@@ -4,4 +4,3 @@ import { AbstractPgQuerier } from '../postgres/abstractPgQuerier.js';
  */
 export class CrdbQuerier extends AbstractPgQuerier {
 }
-//# sourceMappingURL=crdbQuerier.js.map

package/dist/cockroachdb/crdbQuerierPool.d.ts

@@ -11,4 +11,3 @@ export declare class CrdbQuerierPool extends AbstractPgQuerierPool<PoolClient, C
     constructor(opts: PoolConfig, extra?: ExtraOptions);
     getQuerier(): Promise<CrdbQuerier>;
 }
-//# sourceMappingURL=crdbQuerierPool.d.ts.map

package/dist/cockroachdb/crdbQuerierPool.js

@@ -13,4 +13,3 @@ export class CrdbQuerierPool extends AbstractPgQuerierPool {
         return new CrdbQuerier(() => this.pool.connect(), this.dialect, this.extra);
     }
 }
-//# sourceMappingURL=crdbQuerierPool.js.map

package/dist/cockroachdb/index.d.ts

@@ -1,4 +1,3 @@
 export * from './cockroachDialect.js';
 export * from './crdbQuerier.js';
 export * from './crdbQuerierPool.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/cockroachdb/index.js

@@ -1,4 +1,3 @@
 export * from './cockroachDialect.js';
 export * from './crdbQuerier.js';
 export * from './crdbQuerierPool.js';
-//# sourceMappingURL=index.js.map

package/dist/context/context.browser.d.ts

@@ -6,4 +6,3 @@ export declare function withContext<T>(context: UqlContext, callback: () => T):
 export declare function getContext(): UqlContext | undefined;
 /** Captures the current context and returns a runner that re-establishes it later. See `context.ts`. */
 export declare function captureContext(): <T>(callback: () => T) => T;
-//# sourceMappingURL=context.browser.d.ts.map

package/dist/context/context.browser.js

@@ -30,4 +30,3 @@ export function captureContext() {
     const context = getContext();
     return (callback) => (context ? withContext(context, callback) : callback());
 }
-//# sourceMappingURL=context.browser.js.map

package/dist/context/context.d.ts

@@ -26,4 +26,3 @@ export declare function getContext(): UqlContext | undefined;
  * When no context is active at capture time, the runner just invokes the callback.
  */
 export declare function captureContext(): <T>(callback: () => T) => T;
-//# sourceMappingURL=context.d.ts.map

package/dist/context/context.js

@@ -35,4 +35,3 @@ export function captureContext() {
     const context = getContext();
     return (callback) => (context ? withContext(context, callback) : callback());
 }
-//# sourceMappingURL=context.js.map

package/dist/context/securityError.d.ts

@@ -2,4 +2,3 @@
 export declare class UqlSecurityError extends Error {
     name: string;
 }
-//# sourceMappingURL=securityError.d.ts.map

package/dist/context/securityError.js

@@ -2,4 +2,3 @@
 export class UqlSecurityError extends Error {
     name = 'UqlSecurityError';
 }
-//# sourceMappingURL=securityError.js.map

package/dist/d1/d1Querier.d.ts

@@ -35,12 +35,12 @@ export interface D1Database {
     batch<T = unknown>(statements: D1PreparedStatement[]): Promise<D1Result<T>[]>;
     exec(query: string): Promise<D1ExecResult>;
 }
+/** The only part of a D1 binding the querier uses; a full {@link D1Database} satisfies it. */
+export type D1Preparer = Pick<D1Database, 'prepare'>;
 export declare class D1Querier extends AbstractSqliteQuerier {
-    readonly db: D1Database;
+    readonly db: D1Preparer;
     readonly extra?: ExtraOptions | undefined;
-    constructor(db: D1Database, dialect: SqliteDialect, extra?: ExtraOptions | undefined);
+    constructor(db: D1Preparer, dialect: SqliteDialect, extra?: ExtraOptions | undefined);
     internalAll<T>(query: string, values?: unknown[]): Promise<T[]>;
     internalRun(query: string, values?: unknown[]): Promise<import("../type/query.js").QueryUpdateResult>;
-    internalRelease(): Promise<void>;
 }
-//# sourceMappingURL=d1Querier.d.ts.map

package/dist/d1/d1Querier.js

@@ -21,8 +21,4 @@ export class D1Querier extends AbstractSqliteQuerier {
         const changes = rows.length || res.meta?.changes || 0;
         return this.buildUpdateResult({ rows, changes, id: res.meta?.last_row_id });
     }
-    async internalRelease() {
-        // no-op
-    }
 }
-//# sourceMappingURL=d1Querier.js.map

package/dist/d1/d1QuerierPool.d.ts

@@ -8,4 +8,3 @@ export declare class D1QuerierPool extends AbstractSqlQuerierPool<D1Querier, D1S
     getQuerier(): Promise<D1Querier>;
     end(): Promise<void>;
 }
-//# sourceMappingURL=d1QuerierPool.d.ts.map

package/dist/d1/d1QuerierPool.js

@@ -14,4 +14,3 @@ export class D1QuerierPool extends AbstractSqlQuerierPool {
         // no-op for D1 bindings
     }
 }
-//# sourceMappingURL=d1QuerierPool.js.map

package/dist/d1/d1SqliteDialect.d.ts

@@ -6,5 +6,11 @@ import { SqliteDialect } from '../sqlite/sqliteDialect.js';
  */
 export declare class D1SqliteDialect extends SqliteDialect {
     readonly maxBindValues: number;
+    /**
+     * D1 loads no extensions (its allowlist is FTS5, JSON and the math functions) and has no vector
+     * functions of its own, so the sqlite-vec names inherited from {@link SqliteDialect} would compile
+     * to SQL that only fails once it reaches the edge. `raw()` is no escape hatch either, hence a
+     * message that names the product that does the job.
+     */
+    protected appendVectorSort(): never;
 }
-//# sourceMappingURL=d1SqliteDialect.d.ts.map

package/dist/d1/d1SqliteDialect.js

@@ -7,5 +7,13 @@ import { SqliteDialect } from '../sqlite/sqliteDialect.js';
 export class D1SqliteDialect extends SqliteDialect {
     // Cloudflare D1 caps bound parameters at 100 per query.
     maxBindValues = 100;
+    /**
+     * D1 loads no extensions (its allowlist is FTS5, JSON and the math functions) and has no vector
+     * functions of its own, so the sqlite-vec names inherited from {@link SqliteDialect} would compile
+     * to SQL that only fails once it reaches the edge. `raw()` is no escape hatch either, hence a
+     * message that names the product that does the job.
+     */
+    appendVectorSort() {
+        throw new TypeError('Cloudflare D1 has no vector functions and cannot load sqlite-vec. Use Cloudflare Vectorize for vector search.');
+    }
 }
-//# sourceMappingURL=d1SqliteDialect.js.map

package/dist/d1/index.d.ts

@@ -1,4 +1,3 @@
 export * from './d1Querier.js';
 export * from './d1QuerierPool.js';
 export * from './d1SqliteDialect.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/d1/index.js

@@ -1,4 +1,3 @@
 export * from './d1Querier.js';
 export * from './d1QuerierPool.js';
 export * from './d1SqliteDialect.js';
-//# sourceMappingURL=index.js.map

package/dist/dialect/abstractDialect.d.ts

@@ -1,4 +1,4 @@
-import type { DialectFeatures, DialectName, EntityMeta, FieldOptions, InsertIdSource, NamingStrategy, Type } from '../type/index.js';
+import type { DialectFeatures, DialectName, EntityMeta, FieldOptions, InsertIdSource, NamingStrategy, QueryOptions, QueryWhere, QueryWhereMap, Type } from '../type/index.js';
 /**
  * Options for initializing a dialect.
  */
@@ -20,12 +20,17 @@ export declare abstract class AbstractDialect {
      * {@link DialectOptions.driverCapabilities} overrides. Each concrete dialect declares its own.
      */
     protected abstract readonly featureDefaults: DialectFeatures;
+    /**
+     * How this dialect differs from the family it extends, so a subclass states only its deltas rather
+     * than repeating {@link featureDefaults} in full or injecting them through its constructor.
+     */
+    protected readonly featureOverrides: Partial<DialectFeatures>;
     readonly namingStrategy: NamingStrategy | undefined;
     constructor(options?: DialectOptions);
     /**
-     * Effective features: {@link featureDefaults} merged with any {@link DialectOptions.driverCapabilities}.
-     * Computed lazily (and memoized) because `featureDefaults` is a subclass field, initialized only
-     * after `super()` returns.
+     * Effective features: {@link featureDefaults}, then this dialect's {@link featureOverrides}, then
+     * any per-instance {@link DialectOptions.driverCapabilities}. Computed lazily (and memoized)
+     * because both are subclass fields, initialized only after `super()` returns.
      */
     get features(): DialectFeatures;
     /**
@@ -36,5 +41,16 @@ export declare abstract class AbstractDialect {
      * Resolve the column/field name for a property, applying naming strategy if necessary.
      */
     resolveColumnName(key: string, field: FieldOptions | undefined): string;
+    /**
+     * {@link resolveColumnName} for a field key of `meta` - the form query builders need, so reading a
+     * column never depends on looking the field up by hand first. `MongoDialect` overrides it to map the
+     * primary key to `_id`.
+     */
+    columnOf<E>(meta: EntityMeta<E>, key: string): string;
+    /**
+     * A `$where` normalized to a map with the entity's active filters merged in - the only way any
+     * dialect should enter a new query scope, so a scope cannot be rendered with its `security: true`
+     * filters skipped. Recursion within one scope renders the returned map directly instead.
+     */
+    protected scopedWhereMap<E>(meta: EntityMeta<E>, where?: QueryWhere<E>, opts?: QueryOptions): QueryWhereMap<E>;
 }
-//# sourceMappingURL=abstractDialect.d.ts.map

package/dist/dialect/abstractDialect.js

@@ -1,8 +1,14 @@
+import { applyFilters, buildQueryWhereAsMap } from '../util/dialect.util.js';
 /**
  * Base abstract class for all database dialects (SQL and NoSQL).
  */
 export class AbstractDialect {
     options;
+    /**
+     * How this dialect differs from the family it extends, so a subclass states only its deltas rather
+     * than repeating {@link featureDefaults} in full or injecting them through its constructor.
+     */
+    featureOverrides = {};
     namingStrategy;
     #features;
     constructor(options = {}) {
@@ -10,12 +16,12 @@ export class AbstractDialect {
         this.namingStrategy = options.namingStrategy;
     }
     /**
-     * Effective features: {@link featureDefaults} merged with any {@link DialectOptions.driverCapabilities}.
-     * Computed lazily (and memoized) because `featureDefaults` is a subclass field, initialized only
-     * after `super()` returns.
+     * Effective features: {@link featureDefaults}, then this dialect's {@link featureOverrides}, then
+     * any per-instance {@link DialectOptions.driverCapabilities}. Computed lazily (and memoized)
+     * because both are subclass fields, initialized only after `super()` returns.
      */
     get features() {
-        this.#features ??= { ...this.featureDefaults, ...this.options.driverCapabilities };
+        this.#features ??= { ...this.featureDefaults, ...this.featureOverrides, ...this.options.driverCapabilities };
         return this.#features;
     }
     /**
@@ -37,5 +43,20 @@ export class AbstractDialect {
         }
         return this.namingStrategy.columnName(field.name);
     }
+    /**
+     * {@link resolveColumnName} for a field key of `meta` - the form query builders need, so reading a
+     * column never depends on looking the field up by hand first. `MongoDialect` overrides it to map the
+     * primary key to `_id`.
+     */
+    columnOf(meta, key) {
+        return this.resolveColumnName(key, meta.fields[key]);
+    }
+    /**
+     * A `$where` normalized to a map with the entity's active filters merged in - the only way any
+     * dialect should enter a new query scope, so a scope cannot be rendered with its `security: true`
+     * filters skipped. Recursion within one scope renders the returned map directly instead.
+     */
+    scopedWhereMap(meta, where = {}, opts) {
+        return applyFilters(meta, buildQueryWhereAsMap(meta, where), opts);
+    }
 }
-//# sourceMappingURL=abstractDialect.js.map

package/dist/dialect/abstractSqlDialect.d.ts

@@ -1,6 +1,8 @@
-import { type EntityMeta, type FieldKey, type FieldOptions, type IsolationLevel, type JsonUpdateOp, type Query, type QueryAggMap, type QueryAggregate, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryDialect, type QueryExclude, type QueryGroupMap, type QueryHavingMap, type QueryOptions, type QueryPager, type QueryPopulate, QueryRaw, type QueryRawFnOptions, type QuerySearch, type QuerySelect, type QuerySelectOptions, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOperatorMap, type QueryWhereMap, type QueryWhereOptions, type RelationOptions, type SqlDialectName, type SqlQueryDialect, type Type, type UpdatePayload } from '../type/index.js';
-import { VectorSqlDialect } from './vectorSqlDialect.js';
-export declare abstract class AbstractSqlDialect extends VectorSqlDialect implements QueryDialect, SqlQueryDialect {
+import { type EntityMeta, type FieldKey, type FieldOptions, type IsolationLevel, type JsonColumnType, type JsonUpdateOp, type Query, type QueryAggMap, type QueryAggregate, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryDialect, type QueryExclude, type QueryGroupMap, type QueryHavingMap, type QueryOptions, type QueryPager, type QueryPopulate, QueryRaw, type QueryRawFnOptions, type QuerySearch, type QuerySelect, type QuerySelectOptions, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryWhere, type QueryWhereArray, type QueryWhereFieldOperatorMap, type QueryWhereMap, type QueryWhereOptions, type RelationOptions, type SqlDialectName, type SqlQueryDialect, type Type, type UpdatePayload } from '../type/index.js';
+import { IndexSqlDialect } from './indexSqlDialect.js';
+/** How a column's values are bound: see {@link AbstractSqlDialect.persistKind}. */
+type PersistKind = 'plain' | 'json' | 'vector';
+export declare abstract class AbstractSqlDialect extends IndexSqlDialect implements QueryDialect, SqlQueryDialect {
     abstract readonly dialectName: SqlDialectName;
     abstract readonly escapeIdChar: '"' | '`';
     abstract readonly serialPrimaryKey: string;
@@ -47,6 +49,18 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     returningId<E>(entity: Type<E>): string;
     search<E>(ctx: QueryContext, entity: Type<E>, q?: Query<E>, opts?: QueryOptions): void;
     selectFields<E>(ctx: QueryContext, entity: Type<E>, select: QuerySelectValue<E> | undefined, opts?: QuerySelectOptions, exclude?: QueryExclude<E>): void;
+    /**
+     * The expression a scalar field is read through, the plain column by default. MariaDB reads a
+     * vector column back with `VEC_ToText`, since selecting it raw yields its binary form.
+     */
+    protected selectFieldExpr(escapedColumn: string, _field: FieldOptions): string;
+    /**
+     * The `$text` full-text predicate, which every engine spells differently: `MATCH ... AGAINST`
+     * (MySQL family), `to_tsvector @@ websearch_to_tsquery` (Postgres-wire), an FTS5 `MATCH` against
+     * the table itself (SQLite). No portable form exists, so a dialect without one says so here rather
+     * than inheriting another engine's syntax.
+     */
+    protected appendTextSearch<E>(_ctx: QueryContext, _entity: Type<E>, _meta: EntityMeta<E>, _search: QueryTextSearchOptions<E>): void;
     select<E>(ctx: QueryContext, entity: Type<E>, select: QuerySelectValue<E> | undefined, exclude?: QueryExclude<E>, populate?: QueryPopulate<E>, opts?: QueryOptions, distinct?: boolean, sort?: QuerySortMap<E>): void;
     private resolveRelationAwarePrefix;
     protected selectRelationFields<E>(ctx: QueryContext, entity: Type<E>, select: QuerySelect<E> | undefined, populate: QueryPopulate<E> | undefined, opts?: {
@@ -66,6 +80,8 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     compare<E>(ctx: QueryContext, entity: Type<E>, key: string, val: unknown, opts?: QueryComparisonOptions): void;
     protected compareLogicalOperator<E>(ctx: QueryContext, entity: Type<E>, key: '$and' | '$or' | '$not' | '$nor', val: QueryWhereArray<E>, opts: QueryComparisonOptions): void;
     /** Simple comparison operators: `getComparisonKey → op → addValue`. */
+    /** Memoizes {@link escapedColumnName}; see there for why it is per dialect instance. */
+    private readonly escapedColumns;
     private static readonly NEGATE_OP_MAP;
     private static readonly COMPARE_OP_MAP;
     private static readonly LIKE_OP_MAP;
@@ -188,10 +204,16 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     protected having(ctx: QueryContext, having: QueryHavingMap, aggregateExpressions: Record<string, string>): void;
     private static readonly SORT_DIRECTION_MAP;
     private resolveSortDirection;
-    private static readonly havingOpMap;
+    /** Scalar comparison operators shared by `HAVING` conditions and `$size` comparisons. */
+    private static readonly comparisonOpMap;
     protected havingCondition(ctx: QueryContext, expr: string, condition: QueryHavingMap[string]): void;
     find<E>(ctx: QueryContext, entity: Type<E>, q?: Query<E>, opts?: QueryOptions): void;
     insert<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], opts?: QueryOptions): void;
+    /**
+     * `INSERT INTO ... VALUES (...)` and nothing more. The upsert builders extend this rather than
+     * {@link insert}: their own clause has to come before the `RETURNING`, not after it.
+     */
+    protected appendInsertValues<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], opts?: QueryOptions): void;
     /**
      * Emit the value for a column a payload record does not provide (the column list is the union
      * across all records). `DEFAULT` delegates to the database default; SQLite overrides this since
@@ -204,7 +226,22 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     protected getUpsertConflictPathsStr<E>(meta: EntityMeta<E>, conflictPaths: QueryConflictPaths<E>): string;
     delete<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): void;
     escapeId(val: string, forbidQualified?: boolean, addDot?: boolean): string;
-    protected formatPersistableValue<E>(ctx: QueryContext, field: FieldOptions | undefined, value: unknown): void;
+    /**
+     * Bind one persisted value, classifying its column on the spot. Dialects override
+     * {@link appendJsonValue} and {@link appendVectorValue} rather than this, so the chain runs once per
+     * value - overriding this and delegating back to `super` ran every check twice, measurably slowing
+     * every INSERT/UPDATE.
+     */
+    protected formatPersistableValue(ctx: QueryContext, field: FieldOptions | undefined, value: unknown): void;
+    /**
+     * How a column's values are written. A function of the column, not of the value, so a bulk insert
+     * classifies each column once instead of re-deciding per row: a 20-row, 6-column insert asked
+     * `isJsonType` and `isVectorFieldType` 120 times to get the same six answers.
+     */
+    protected persistKind(field: FieldOptions | undefined): PersistKind;
+    /** The one type dispatch for a persisted value, over a column kind decided by the caller. */
+    private writePersistableValue;
+    protected appendJsonValue(ctx: QueryContext, value: unknown, _type: JsonColumnType): void;
     /**
      * Reads `operand` as a JSON value. Passing the `?` placeholder yields the cast for a bound
      * parameter, and passing an expression re-reads text as JSON - the same SQL either way, which is
@@ -274,21 +311,24 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
      */
     private normalizeWhereValue;
     /**
-     * Filter by relation using an EXISTS subquery.
-     * Supports all cardinalities: mm (via junction), 1m, m1, and 11.
+     * A field key's mapped column (`@Field({ name })`), escaped, memoized per dialect instance: field
+     * metadata is shared between dialects while this result is not, since `escapeIdChar` and the naming
+     * strategy differ. Weakly keyed so a transient entity's metadata stays collectable.
      */
+    private escapedColumnName;
+    private escapedColumn;
+    /** As {@link escapedColumn}, but qualified by the query alias when the parent is nested. */
+    private escapedParentColumn;
     /**
-     * The parent side of a relation-filtering subquery: its table name, escaped id reference, and a
-     * guard against a relation with no configured references. Shared by
-     * `compareRelation`/`compareRelationSize`. `rel.references` is asserted non-null at call sites
-     * relying on this guard, since the check lives here instead of in the caller's own scope.
+     * The single path from a relation operator to its target, so none can emit an unscoped subquery:
+     * the target's `$where` is merged with its active filters, making a trashed or out-of-scope row
+     * invisible here just as it is to a joined `$populate`. The caller's filter bypass is deliberately
+     * not propagated (`withDeleted()` does not reach into relations), matching `selectRelationJoins`.
      */
-    private resolveRelationParent;
+    private appendRelationSubquery;
+    /** Filter by relation: a parent matches when {@link appendRelationSubquery} finds one target row. */
     protected compareRelation<E>(ctx: QueryContext, entity: Type<E>, key: string, val: QueryWhereMap<unknown>, rel: RelationOptions, opts: QueryComparisonOptions): void;
-    /**
-     * Filter by relation size using a `COUNT(*)` subquery.
-     * Supports all cardinalities: mm (via junction), 1m.
-     */
+    /** Filter by relation size: the same subquery, counting instead of testing for existence. */
     protected compareRelationSize<E>(ctx: QueryContext, entity: Type<E>, key: string, sizeVal: number | QuerySizeComparisonOps, rel: RelationOptions, opts: QueryComparisonOptions): void;
     /**
      * Build a complete `$size` comparison expression.
@@ -319,4 +359,4 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     protected numericCast(expr: string): string;
     toString(): string;
 }
-//# sourceMappingURL=abstractSqlDialect.d.ts.map
+export {};