uql-orm 0.31.1 → 0.31.3

package/README.md

@@ -70,7 +70,7 @@ Release notes live in [CHANGELOG.md](https://github.com/rogerpadilla/uql/blob/ma
 
 ## Made with UQL
 
-**[Variability.ai](https://variability.ai)** - AI meeting recorder and video summarizer for Zoom, Meet, and Teams. Instant summaries with action items in 35+ languages.
+**[Variability.ai](https://variability.ai)** - AI meeting ntetaker and video summarizer for Zoom, Meet, Slack, and Teams. Instant summaries with action items in 35+ languages. Built by UQL's author.
 
 Built something? [Open a PR](https://github.com/rogerpadilla/uql/blob/main/CONTRIBUTING.md) and add it here.
 

package/dist/nestjs/uqlModule.d.ts

@@ -30,6 +30,11 @@ export type UqlModuleAsyncOptions<Req = unknown> = UqlModuleCommon<Req> & {
     /** Providers to inject into `useFactory`. */
     readonly inject?: FactoryProvider['inject'];
 };
+/**
+ * NestJS integration: provides the pool via DI, sets it as UQL's default pool (so `getQuerier()`,
+ * `querierMiddleware` (express platform) and `createFetchHandler` work unchanged), optionally scopes
+ * every request to a {@link UqlContext} (multi-tenancy), and ends the pool on application shutdown.
+ */
 export declare class UqlModule {
     /** Configure with an already-built pool. */
     static forRoot<Req = unknown>({ pool, global, getContext }: UqlModuleOptions<Req>): DynamicModule;

package/dist/nestjs/uqlModule.js

@@ -43,11 +43,6 @@ import { UqlContextInterceptor } from './uqlContextInterceptor.js';
  * does not redirect UQL internals.
  */
 export const UQL_QUERIER_POOL = Symbol('UQL_QUERIER_POOL');
-/**
- * NestJS integration: provides the pool via DI, sets it as UQL's default pool (so `getQuerier()`,
- * `querierMiddleware` (express platform) and `createFetchHandler` work unchanged), optionally scopes
- * every request to a {@link UqlContext} (multi-tenancy), and ends the pool on application shutdown.
- */
 /**
  * Ends the pool when Nest shuts down.
  *
@@ -66,6 +61,11 @@ class UqlPoolLifecycle {
         return this.pool.end();
     }
 }
+/**
+ * NestJS integration: provides the pool via DI, sets it as UQL's default pool (so `getQuerier()`,
+ * `querierMiddleware` (express platform) and `createFetchHandler` work unchanged), optionally scopes
+ * every request to a {@link UqlContext} (multi-tenancy), and ends the pool on application shutdown.
+ */
 let UqlModule = (() => {
     let _classDecorators = [Module({})];
     let _classDescriptor;

package/dist/querier/abstractQuerier.d.ts

@@ -23,11 +23,13 @@ export declare abstract class AbstractQuerier implements Querier {
     private validateProjectionQueryRecursive;
     /**
      * Resolves `[entity, query, opts]` for the dual call pattern: `(entity, q, opts)` (entity argument)
-     * vs `(query, opts)` (entity via the query's `$entity` field).
+     * vs `(query, opts)` (entity via the query's `$entity` field). Generic in the query `Q` because it
+     * only ever reads `$entity`: pinning it to one statement's shape made every caller launder its own
+     * through a cast, which is how a read query's `$sort` used to reach a write's.
      */
-    protected resolveEntityQuery<E extends object>(entityOrQuery: Type<E> | (QuerySearch<E> & {
+    protected resolveEntityQuery<E extends object, Q extends object>(entityOrQuery: Type<E> | (Q & {
         $entity: Type<E>;
-    }), maybeQueryOrOpts?: QuerySearch<E> | QueryOptions, maybeOpts?: QueryOptions): [Type<E>, QuerySearch<E>, QueryOptions | undefined];
+    }), maybeQueryOrOpts?: Q | QueryOptions, maybeOpts?: QueryOptions): [Type<E>, Q, QueryOptions | undefined];
     findOneById<E extends object>(entity: Type<E>, id: IdValue<E>, q?: QueryOne<E>, opts?: QueryOptions): Promise<E | undefined>;
     /**
      * Find a single record matching the query.

package/dist/querier/abstractQuerier.js

@@ -65,7 +65,9 @@ export class AbstractQuerier {
     }
     /**
      * Resolves `[entity, query, opts]` for the dual call pattern: `(entity, q, opts)` (entity argument)
-     * vs `(query, opts)` (entity via the query's `$entity` field).
+     * vs `(query, opts)` (entity via the query's `$entity` field). Generic in the query `Q` because it
+     * only ever reads `$entity`: pinning it to one statement's shape made every caller launder its own
+     * through a cast, which is how a read query's `$sort` used to reach a write's.
      */
     resolveEntityQuery(entityOrQuery, maybeQueryOrOpts, maybeOpts) {
         if (typeof entityOrQuery === 'function' && entityOrQuery.prototype) {

package/dist/type/entity.d.ts

@@ -13,17 +13,21 @@ export declare const idKey: unique symbol;
 export type Key<E> = keyof E & string;
 /**
  * Infers the field names of an entity.
- * Includes scalar fields, JSON fields, and scalar arrays (e.g. vector `number[]`).
+ * Includes scalar fields, JSON fields, scalar arrays (e.g. vector `number[]`) and arrays of JSON.
  * The `-?` modifier strips optionality so the indexed access yields clean key unions
  * (without it, optional properties leak `undefined` into the union).
  *
+ * `readonly Json[]` is its own arm because the brand sits on the element, so the `Json` arm cannot
+ * see it. What keeps a to-many relation out of that arm is the weak-type check: `Json<unknown>` is
+ * all-optional, which a class with named properties is not assignable to.
+ *
  * The check is bracketed so `any` resolves once rather than matching both this and
  * {@link RelationKey}: an unbracketed `any extends X` satisfies either branch. It reads
  * `readonly Scalar[]`, which every mutable one satisfies too, so declaring a vector or a scalar
  * array `readonly` does not push the field over into {@link RelationKey}.
  */
 export type FieldKey<E> = {
-    readonly [K in keyof E]-?: [NonNullable<E[K]>] extends [Scalar | readonly Scalar[] | Json] ? K : never;
+    readonly [K in keyof E]-?: [NonNullable<E[K]>] extends [Scalar | readonly Scalar[] | Json | readonly Json[]] ? K : never;
 }[Key<E>];
 /**
  * Infers the relation names of an entity: whatever is left once its fields and its methods are
@@ -41,10 +45,21 @@ type IsJson<T> = '__json' extends keyof T ? true : false;
 /** The payload `P` of a branded `Json<P>`, or `never` for any non-JSON type. */
 type UnwrapJson<T> = IsJson<T> extends true ? (T extends Json<infer P> ? P : never) : never;
 /**
- * The `Json` payload of a field value `V`: both `Json<T>` and `Json<T>[]` yield `T` (via
- * `Unpacked`, a no-op for the non-array case); `never` when `V` is not a JSON field.
+ * The one branded value a field value `V` holds: `Json<T>` for both `Json<T>` and `Json<T>[]`, via
+ * `Unpacked`, a no-op for the non-array case.
+ */
+type JsonElement<V> = NonNullable<Unpacked<NonNullable<V>>>;
+/** The `Json` payload of a field value `V`; `never` when `V` is not a JSON field. */
+type JsonPayload<V> = UnwrapJson<JsonElement<V>>;
+/**
+ * The fields carrying the `Json` brand, `never` on an entity with none - which is most of them, and
+ * what makes {@link JsonFieldPaths} collapse to `never` without deriving a path for anything. Tests
+ * the brand rather than the payload, whose extra `Json<infer P>` inference is only worth doing once
+ * a field is known to be JSON.
  */
-type JsonPayload<V> = UnwrapJson<NonNullable<Unpacked<NonNullable<V>>>>;
+type JsonFieldKey<E> = {
+    readonly [K in keyof E]-?: IsJson<JsonElement<E[K]>> extends true ? K : never;
+}[Key<E>];
 /**
  * Recursively derives dot-notation key paths from a JSON payload type. Handles every shape at
  * entry: an untyped (`unknown`) payload accepts any suffix via a `string` pattern, scalars are
@@ -57,15 +72,15 @@ type DeepJsonKeys<T, D extends unknown[] = []> = unknown extends T ? string : No
 }[keyof NonNullable<T> & string];
 /**
  * Extracts dot-notation paths from `Json<T>` values, handling both scalar JSON
- * and arrays of JSON (e.g., `Json<{foo: string}>[]` in MongoDB).
+ * and arrays of JSON (`Json<{foo: string}>[]`, a column holding a list of documents).
  * For `kind?: Json<{ public: number; theme: { color: string } }>`,
  * produces `'kind.public' | 'kind.theme' | 'kind.theme.color'`.
  * For `items?: Json<{id: string}>[]`, produces `'items.id'`.
  * An untyped `Json<unknown>` field yields the scoped pattern `` `${K}.${string}` ``.
  */
 export type JsonFieldPaths<E> = {
-    readonly [K in FieldKey<E>]: [JsonPayload<E[K]>] extends [never] ? never : `${K & string}.${Exclude<DeepJsonKeys<JsonPayload<E[K]>>, '__json'>}`;
-}[FieldKey<E>];
+    readonly [K in JsonFieldKey<E>]: `${K & string}.${DeepJsonKeys<JsonPayload<E[K]>>}`;
+}[JsonFieldKey<E>];
 /**
  * The value type inside `T` at dot-path `P`; `unknown` when unresolvable (e.g. through a
  * `Record<string, unknown>` leaf). Arrays are stepped into via their element type.
@@ -73,9 +88,10 @@ export type JsonFieldPaths<E> = {
 type PathValue<T, P extends string> = unknown extends T ? unknown : NonNullable<T> extends readonly (infer U)[] ? PathValue<NonNullable<U>, P> : P extends `${infer K}.${infer Rest}` ? K extends keyof NonNullable<T> ? PathValue<NonNullable<T>[K], Rest> : unknown : P extends keyof NonNullable<T> ? NonNullable<T>[P] : unknown;
 /**
  * The value type at a JSON dot-path `P` of entity `E`; `unknown` when unresolvable, which keeps
- * untyped paths fully permissive in `$where`.
+ * untyped paths fully permissive in `$where`. Gated on {@link JsonFieldKey}, the same predicate
+ * {@link JsonFieldPaths} derives its keys from, so a path that is offered always resolves a value.
  */
-export type JsonFieldPathValue<E, P extends string> = P extends `${infer F}.${infer Rest}` ? F extends FieldKey<E> ? [JsonPayload<E[F]>] extends [never] ? unknown : PathValue<JsonPayload<E[F]>, Rest> : unknown : unknown;
+export type JsonFieldPathValue<E, P extends string> = P extends `${infer F}.${infer Rest}` ? F extends JsonFieldKey<E> ? PathValue<JsonPayload<E[F]>, Rest> : unknown : unknown;
 /**
  * Extracts only the array-typed keys from `T`, mapping each to its element type via `Unpacked`.
  * Used by `$push` and `$pull` to provide type-safe element targets.

package/dist/type/query.d.ts

@@ -36,7 +36,9 @@ export type QuerySelectOptions = {
     autoPrefixAlias?: boolean;
 };
 /**
- * Query field selection - `{ name: true }` whitelists specific fields.
+ * Query field selection - `{ name: true }` whitelists specific fields. Fields only: a relation is a
+ * sub-query rather than a projection flag, and a whitelist naming one could not say whether the
+ * scalars come with it. Relations go in `$populate`.
  */
 export type QuerySelect<E> = {
     [K in FieldKey<E>]?: BooleanLike;
@@ -116,17 +118,27 @@ export type QuerySortDirection = -1 | 1 | 'asc' | 'desc';
  * Accepted value for a field in `$sort` - either a direction or a vector similarity search.
  */
 export type QuerySortValue = QuerySortDirection | QueryVectorSearch;
+/**
+ * To-one relations only: a parent holds many rows of a to-many, so there is no single value to order
+ * it by, and joining one in would duplicate the parent instead. Order those inside `$populate`.
+ */
+type ToOneRelationKey<E> = {
+    [K in RelationKey<E>]: IsMany<E[K]> extends true ? never : K;
+}[RelationKey<E>];
 /**
  * sort by map - supports field keys, JSON dot-notation paths (restricted to real JSON fields,
  * like `QueryWhereMap`), relation sort via nested objects, and vector similarity search on
- * `number[]` fields.
+ * `number[]` fields. `Vector` is what confines a vector search to the level the statement ranks:
+ * the queried entity. A relation of it is joined in one row at a time, so there is nothing to rank
+ * there - the SQL dialects throw, and MongoDB would quietly drop it, so this is its only guard.
+ *
+ * One mapped type over the three key sets rather than three intersected. The sets are disjoint - a
+ * JSON path is dotted, and a field key cannot also be a relation key - and an assignability check
+ * against an intersection is repeated per constituent, which made this the single most expensive
+ * type in the package to check.
  */
 export type QuerySortMap<E, Vector extends boolean = true> = {
-    [K in FieldKey<E>]?: Vector extends true ? NonNullable<E[K]> extends readonly number[] ? QuerySortValue : QuerySortDirection : QuerySortDirection;
-} & {
-    [P in JsonFieldPaths<E>]?: QuerySortDirection;
-} & {
-    [K in RelationKey<E> as IsMany<E[K]> extends true ? never : K]?: QuerySortMap<RelationTarget<E[K]>, false>;
+    [K in FieldKey<E> | JsonFieldPaths<E> | ToOneRelationKey<E>]?: K extends RelationKey<E> ? QuerySortMap<RelationTarget<E[K]>, false> : K extends FieldKey<E> ? Vector extends true ? NonNullable<E[K]> extends readonly number[] ? QuerySortValue : QuerySortDirection : QuerySortDirection : QuerySortDirection;
 };
 /**
  * pager options.
@@ -153,17 +165,16 @@ export type QueryFilter<E> = {
 };
 /**
  * A filter plus the ordering and page `updateMany`/`deleteMany` take. Both settle the rows they
- * picked before writing, so the page is portable rather than MySQL-only.
- *
- * `$sort` excludes vector search here for the reason `$lock` is declared on {@link Query} instead:
- * a vector search ranks rows into a projected distance column, and only a SELECT has a projection
- * list to hold one. Passing `QuerySortMap` its `Vector = false` is what keeps it off these.
+ * picked with a SELECT before writing, so the page is portable rather than MySQL-only - and so a
+ * vector `$sort` is as valid here as on a read: it ranks the settle query's rows, which has the
+ * projection list to hold the distance. `$lock` is the clause that stays off these, declared on
+ * {@link Query} instead.
  */
 export type QuerySearch<E> = QueryFilter<E> & {
     /**
      * sorting options.
      */
-    $sort?: QuerySortMap<E, false>;
+    $sort?: QuerySortMap<E>;
 } & QueryPager;
 /**
  * query options.
@@ -243,3 +254,4 @@ export type QueryUpdateResult = {
      */
     created?: boolean;
 };
+export {};

package/dist/type/utility.d.ts

@@ -25,7 +25,8 @@ export type PrimaryKey = string | number | bigint;
 /**
  * Marker type for JSON/JSONB fields.
  * Wrapping a field's TypeScript type with `Json<T>` ensures it is classified as a `FieldKey`
- * (not a `RelationKey`), enabling type-safe usage in `$where`, `$select`, and `$sort`.
+ * (not a `RelationKey`), enabling type-safe usage in `$where`, `$select`, and `$sort`. A column
+ * holding a list of documents is `Json<T>[]`, also a field, whose dot-paths address the element.
  *
  * @example
  * ```ts

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "JSON-native TypeScript ORM for Node.js, Bun and Deno. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.31.1",
+  "version": "0.31.3",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -129,13 +129,13 @@
     }
   },
   "devDependencies": {
-    "@electric-sql/pglite": "0.5.7",
-    "@electric-sql/pglite-pgvector": "0.0.8",
+    "@electric-sql/pglite": "0.5.8",
+    "@electric-sql/pglite-pgvector": "0.0.9",
     "@libsql/client": "^0.17.4",
     "@neondatabase/serverless": "^1.1.0",
-    "@nestjs/common": "^11.2.1",
-    "@nestjs/core": "^11.2.1",
-    "@nestjs/testing": "^11.2.1",
+    "@nestjs/common": "^12.0.1",
+    "@nestjs/core": "^12.0.1",
+    "@nestjs/testing": "^12.0.1",
     "@tursodatabase/database": "^0.7.2",
     "@tursodatabase/serverless": "^1.4.0",
     "@types/better-sqlite3": "^9.6.0",
@@ -145,8 +145,8 @@
     "better-sqlite3": "^13.0.3",
     "express": "^5.2.1",
     "mariadb": "^3.5.3",
-    "mongodb": "^7.5.0",
-    "mysql2": "^3.23.4",
+    "mongodb": "^7.6.0",
+    "mysql2": "^3.24.2",
     "pg": "^8.23.0",
     "pg-query-stream": "^4.17.0",
     "rxjs": "^7.8.2",