uql-orm 0.31.0 → 0.31.2

package/README.md

@@ -34,17 +34,16 @@ npm install uql-orm pg   # or mysql2, mariadb, better-sqlite3, mongodb, @tursoda
 
 That is the whole install ([setup](https://uql-orm.dev/getting-started)), and the [imperative API](https://uql-orm.dev/entities/imperative) skips decorators altogether.
 
-```ts
-await pool.findMany(User, {
-  $select: { id: true, email: true },
-  $populate: { posts: { $select: { title: true } } },
-  $where: { email: { $endsWith: '@uql-orm.dev' } },
-  $limit: 10,
-});
-```
+<a href="https://uql-orm.dev">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://uql-orm.dev/demo-dark.webp">
+    <img src="https://uql-orm.dev/demo-light.webp" alt="A UQL query being typed: the compiler underlines the misspelled 'emial', then 'titel' three levels deep inside $populate">
+  </picture>
+</a>
+
+Our type-safety automatically prevents the bugs above, without codegen: the entity classes are the schema, pure TypeScript power. That demo editor is [on the home page](https://uql-orm.dev).
 
-That query is a serializable value. Build it dynamically, store it, diff it, or send it
-from the browser to the server. The same object runs on every supported database.
+The query is just JSON: build it dynamically, store it, diff it, or send it from the browser to the server. The same object runs on every supported database.
 
 ## Why UQL?
 
@@ -71,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/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/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.0",
+  "version": "0.31.2",
   "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",