uql-orm 0.66.0 → 0.67.0

package/dist/type/dialect.d.ts

@@ -1,5 +1,5 @@
 import type { EntityMeta, UpdatePayload } from './entity.js';
-import type { Query, QueryConflictPaths, QueryFilter, QueryOptions, QuerySearch } from './query.js';
+import type { Query, QueryConflictPaths, QueryOptions, QueryPage, QuerySearch } from './query.js';
 import type { QueryAggMap, QueryAggregate, QueryGroupMap } from './queryAggregate.js';
 import type { Type } from './utility.js';
 /**
@@ -70,13 +70,7 @@ export interface DriverCapabilities {
      */
     readonly nativeArrays: boolean;
 }
-/**
- * How a dialect surfaces the IDs generated by an INSERT statement:
- * - `'returning'`: the statement itself returns one row per inserted record (`RETURNING`,
- *   or MongoDB's `insertedIds`), so IDs are exact for every row.
- * - `'firstId'`: the driver header only exposes the first generated ID (MySQL `insertId`);
- *   the remaining IDs are inferred by incrementing it.
- */
+/** How a dialect reports inserted ids: from the statement per row, or MySQL's first id, the rest inferred. */
 export type InsertIdSource = 'returning' | 'firstId';
 /**
  * Features of the database engine (SQL syntax layer).
@@ -99,25 +93,11 @@ export interface DialectFeatures {
      */
     readonly primaryKeyAlter: boolean;
     /**
-     * Whether a stored generated column can be added to a table that already exists. False on SQLite,
-     * which takes one in a `CREATE TABLE` and rejects the same column in an `ALTER` ("cannot add a
-     * STORED column"), since filling it would rewrite every row - so a sync that would add one is
-     * refused by name rather than by the driver.
-     *
-     * A boolean rather than a mode: SQLite would accept a `VIRTUAL` column here, but emitting one where
-     * the entity said `stored` makes the same entity a stored column on a new database and a virtual one
-     * on an old, which nothing diffs and no one can see. Refusal has one form; only what UQL *emits*
-     * earns a mode, which is what makes {@link DialectFeatures.commentSyntax} three-way.
+     * Whether a stored generated column can be added to an existing table. SQLite takes one only in a
+     * `CREATE TABLE`, so a sync that would add one is refused by name.
      */
     readonly generatedColumnAdd: boolean;
-    /**
-     * How this engine carries a comment on a table or a column, if at all: `inline` writes it into the
-     * declaration (MySQL, MariaDB), `statement` needs a `COMMENT ON` of its own (Postgres, CockroachDB),
-     * `none` has no such thing (SQLite, MongoDB).
-     *
-     * One knob rather than a boolean because the answer is three-way. Read as a boolean, Postgres landed
-     * on the same branch as SQLite and a documented column silently lost its comment.
-     */
+    /** Where a comment goes: in the declaration (MySQL family), a `COMMENT ON` of its own (Postgres family), or nowhere. */
     readonly commentSyntax: 'inline' | 'statement' | 'none';
     /**
      * Whether every column of a vector index has to be `NOT NULL`, which MariaDB 12.3 enforces ("All
@@ -130,13 +110,8 @@ export interface DialectFeatures {
     /** Whether the dialect natively supports the TIMESTAMPTZ alias/type. */
     readonly supportsTimestamptz: boolean;
     /**
-     * How a `string` column is sized: `text` is always the unbounded type whatever length was asked
-     * for (SQLite, whose affinity makes a bound meaningless), `bounded-text` takes the bound when there
-     * is one and the unbounded type otherwise (the Postgres family), `varchar` is always bounded and
-     * falls back to 255 (the MySQL family, SQL Server).
-     *
-     * Three-way for the reason {@link commentSyntax} is: a boolean puts SQLite and Postgres on the
-     * same branch, and they need different answers.
+     * How a string column is sized: always unbounded (`text`, SQLite), bounded where a length is given
+     * (`bounded-text`, the Postgres family), or always bounded, 255 by default (`varchar`).
      */
     readonly stringSizing: 'text' | 'bounded-text' | 'varchar';
     /** Whether the engine has unsigned integers, so `@Field({ unsigned: true })` reaches the column. */
@@ -148,6 +123,29 @@ export interface DialectFeatures {
      */
     readonly serverSideCursors: boolean;
 }
+/** What a SQL engine can do beyond {@link DialectFeatures}, read where a statement is built. */
+export interface SqlDialectFeatures extends DialectFeatures {
+    /** Whether the engine has row locks at all. The SQLite family locks the database instead. */
+    readonly rowLocks: boolean;
+    /** Whether `FOR UPDATE` may share a statement with a window function, which the Postgres family refuses. */
+    readonly rowLockWithWindow: boolean;
+    /** Whether a lock can be narrowed to one table of a join, `FOR UPDATE OF`, which MariaDB lacks. */
+    readonly rowLockOf: boolean;
+    /** Whether a multi-row upsert's `RETURNING` lists its rows in payload order; where not, the ids are read back. */
+    readonly orderedUpsertReturning: boolean;
+    /** Whether a JSON aggregate takes an `ORDER BY` of its own; where not, a relation's rows keep their derived table's order. */
+    readonly orderedJsonAggregates: boolean;
+    /** Whether JSON array containment matches an object element that merely includes the given keys, as `@>` does. */
+    readonly partialJsonContainment: boolean;
+    /** Whether an exploded scalar JSON element keeps its SQL type, as SQLite's `JSON_EACH` does. */
+    readonly typedJsonElements: boolean;
+    /** Whether the engine has pgvector's `halfvec` and `sparsevec`; elsewhere both map onto `vector`. */
+    readonly narrowVectorTypes: boolean;
+    /** Whether an ANN index's tuning `SET` applies only inside a transaction, as `SET LOCAL` does. */
+    readonly vectorTuningNeedsTransaction: boolean;
+    /** Whether the serial column type states `PRIMARY KEY` itself, as SQLite's `AUTOINCREMENT` must. */
+    readonly serialDeclaresPrimaryKey: boolean;
+}
 /**
  * What a SQL statement is rendered through, as a `raw` callback and a query context see it:
  * `AbstractSqlDialect` is the one implementation.
@@ -161,59 +159,19 @@ export interface SqlQueryDialect {
      * the escape character for identifiers.
      */
     readonly escapeIdChar: '"' | '`';
-    /**
-     * The dialect features.
-     */
-    readonly features: DialectFeatures;
-    /**
-     * obtains the records matching the given search parameters.
-     * @param ctx the query context
-     * @param entity the target entity
-     * @param q the criteria options
-     * @param opts the query options
-     * @param totalAlias when given, carry the unpaged match count on every row under this alias
-     */
+    /** What the engine can do. */
+    readonly features: SqlDialectFeatures;
+    /** A read; with `totalAlias`, every row also carries the unpaged match count under that alias. */
     find<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, opts?: QueryOptions, totalAlias?: string): void;
-    /**
-     * counts the number of records matching the given search parameters.
-     * @param ctx the query context
-     * @param entity the target entity
-     * @param q the criteria options
-     * @param opts the query options
-     */
-    count<E>(ctx: QueryContext, entity: Type<E>, q: QueryFilter<E>, opts?: QueryOptions): void;
-    /**
-     * insert records.
-     * @param ctx the query context
-     * @param entity the target entity
-     * @param payload the payload
-     * @param opts the query options
-     */
+    /** A count of the records matching the filter, or of those a page of it takes. */
+    count<E>(ctx: QueryContext, entity: Type<E>, q: QueryPage<E>, opts?: QueryOptions): void;
+    /** An insert of one record or many. */
     insert<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], opts?: QueryOptions): void;
-    /**
-     * update records.
-     * @param ctx the query context
-     * @param entity the target entity
-     * @param q the criteria options
-     * @param payload
-     * @param opts the query options
-     */
+    /** An update of the records the query matches. */
     update<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): void;
-    /**
-     * upsert records.
-     * @param ctx the query context
-     * @param entity the target entity
-     * @param conflictPaths the conflict paths
-     * @param payload
-     */
+    /** An upsert of one record or many by their conflict paths. */
     upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[]): void;
-    /**
-     * delete records.
-     * @param ctx the query context
-     * @param entity the target entity
-     * @param q the criteria options
-     * @param opts the query options
-     */
+    /** A delete of the records the query matches, a soft delete where the entity has one. */
     delete<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): void;
     /**
      * escape an identifier.
@@ -260,19 +218,9 @@ export interface SqlQueryDialect {
  */
 export type SqlDialectName = 'postgres' | 'cockroachdb' | 'mysql' | 'mariadb' | 'sqlite' | 'mssql';
 /**
- * An index capability that some engines have and others reject outright. Verified live: expression
- * indexes exist everywhere but MariaDB 12.3 (which needs a generated column); prefix lengths are
- * MySQL-family only and *required* there to index `TEXT`; `NULLS FIRST/LAST` and operator classes are
- * Postgres-only (CockroachDB 26.2 answers "unimplemented"); `INCLUDE` is Postgres-wire only; the
- * MySQL family is alone in having no partial indexes. The two JSON ones split the other way: the
- * engines that index a path inside a document are the ones whose planner matches the query's own
- * extraction back to it (Postgres, CockroachDB, SQLite - MySQL matches neither
- * `CAST(col->>'$.x' AS CHAR(n))` nor `JSON_VALUE(... RETURNING ...)`, verified on 26.7, and needs a
- * generated column instead), while MySQL alone has the multi-valued index a JSON array needs.
- *
- * Introspectors reuse the vocabulary for what they can read *back*, which is what diffing may
- * compare. The two sets are deliberately not the same object and must not be unified: Postgres can
- * emit an expression index and read one back, but MySQL emits one it cannot describe afterwards.
+ * An index capability some engines lack, named in the words an error reports it in. Introspectors use
+ * the same vocabulary for what they can read back, a separate set: MySQL emits an expression index it
+ * cannot describe again. The engines behind each are in the index guide.
  */
 export declare const INDEX_FEATURE_LABELS: {
     readonly expression: 'expression indexes';

package/dist/type/dialect.js

@@ -1,17 +1,7 @@
 /**
- * An index capability that some engines have and others reject outright. Verified live: expression
- * indexes exist everywhere but MariaDB 12.3 (which needs a generated column); prefix lengths are
- * MySQL-family only and *required* there to index `TEXT`; `NULLS FIRST/LAST` and operator classes are
- * Postgres-only (CockroachDB 26.2 answers "unimplemented"); `INCLUDE` is Postgres-wire only; the
- * MySQL family is alone in having no partial indexes. The two JSON ones split the other way: the
- * engines that index a path inside a document are the ones whose planner matches the query's own
- * extraction back to it (Postgres, CockroachDB, SQLite - MySQL matches neither
- * `CAST(col->>'$.x' AS CHAR(n))` nor `JSON_VALUE(... RETURNING ...)`, verified on 26.7, and needs a
- * generated column instead), while MySQL alone has the multi-valued index a JSON array needs.
- *
- * Introspectors reuse the vocabulary for what they can read *back*, which is what diffing may
- * compare. The two sets are deliberately not the same object and must not be unified: Postgres can
- * emit an expression index and read one back, but MySQL emits one it cannot describe afterwards.
+ * An index capability some engines lack, named in the words an error reports it in. Introspectors use
+ * the same vocabulary for what they can read back, a separate set: MySQL emits an expression index it
+ * cannot describe again. The engines behind each are in the index guide.
  */
 export const INDEX_FEATURE_LABELS = {
     expression: 'expression indexes',