uql-orm 0.69.0 → 0.71.0

package/dist/util/dialect.util.js

@@ -188,6 +188,14 @@ export function findVectorSort(sort) {
     }
     return undefined;
 }
+/** `$candidates`, checked: it can be spelled into a statement, and `/http` input is untyped. */
+export function vectorCandidates(q) {
+    const candidates = q.$candidates;
+    if (candidates !== undefined && (!Number.isInteger(candidates) || candidates < 1)) {
+        throw new TypeError(`$candidates must be a positive integer, got ${JSON.stringify(candidates)}`);
+    }
+    return candidates;
+}
 /**
  * Every index type that means "vector" to some engine: pgvector's two, the generic one MariaDB and
  * CockroachDB share, and Atlas's. Wider than {@link VECTOR_INDEX_TYPES}, which is the set whose DDL
@@ -344,22 +352,36 @@ export function parseGroupMap(group, select) {
     const entries = [];
     const groupMap = group ?? {};
     for (const alias of getKeys(groupMap)) {
-        if (groupMap[alias]) {
-            entries.push({ kind: 'key', alias });
+        const ref = groupMap[alias];
+        if (ref) {
+            entries.push({ kind: 'key', alias, path: ref === true ? [alias] : groupRefPath(alias, ref) });
         }
     }
     if (!select) {
         return entries;
     }
     for (const alias of getKeys(select)) {
-        const fnEntry = select[alias];
-        const key = getKeys(fnEntry)[0];
-        // Flat DISTINCT ops (`$countDistinct`, ...) normalize to their base op + a `distinct` flag.
+        const { $where: where } = select[alias];
+        const call = select[alias];
+        const key = getKeys(call).find((name) => name !== '$where');
+        if (key === undefined) {
+            throw new TypeError(`aggregate '${alias}' names no op, only a $where`);
+        }
+        // `$countDistinct` normalizes to `$count` plus a `distinct` flag.
         const { op, distinct } = resolveAggregateOp(key);
-        entries.push({ kind: 'fn', alias, op, fieldRef: aggregateFieldRef(alias, fnEntry[key]), distinct });
+        const fieldRef = aggregateFieldRef(alias, call[key]);
+        entries.push({ kind: 'fn', alias, op, fieldRef, distinct, ...(where && hasKeys(where) ? { where } : {}) });
     }
     return entries;
 }
+/** The path a group key's `{ transaction: { orderId: true } }` names, one key at each level. */
+function groupRefPath(alias, ref) {
+    const [key, ...rest] = isRecord(ref) ? getKeys(ref) : [];
+    if (!isRecord(ref) || key === undefined || rest.length) {
+        throw new TypeError(`$group '${alias}' names one field by the path to it: got ${JSON.stringify(ref)}`);
+    }
+    return ref[key] === true ? [key] : [key, ...groupRefPath(alias, ref[key])];
+}
 /** The column an aggregate reads: `'*'`, or the one field its `{ field: true }` names. */
 function aggregateFieldRef(alias, arg) {
     const [field, ...rest] = arg === '*' ? [arg] : namedKeys(arg);
@@ -418,6 +440,18 @@ export function assertAggregateColumns(clauseMap, emitted, clause) {
         }
     }
 }
+/** The text-search config a fulltext index builds with where it states none: language-neutral, no stemming. */
+const DEFAULT_TEXT_CONFIG = 'simple';
+/** The text-search config a fulltext index builds with, which a search it serves has to parse with too. */
+export function fulltextConfig(index) {
+    return index.config ?? DEFAULT_TEXT_CONFIG;
+}
+/** The fulltext index over exactly `fields`, in order, which a search of them is served by. */
+export function fulltextIndexOver(meta, fields) {
+    return meta.indexes?.find((index) => index.type === 'fulltext' &&
+        index.columns.length === fields.length &&
+        index.columns.every((entry, at) => entry.column === fields[at]));
+}
 /**
  * The fields a `$text` searches: those it names, or else the columns of the entity's fulltext index,
  * the declaration MySQL's `MATCH` has to name exactly and a MongoDB text index already is. Refused

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "The JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.69.0",
+  "version": "0.71.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -52,11 +52,12 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md"
   ],
   "scripts": {
-    "prepack": "bun run build && bun run verify-dist.ts && cp ../../README.md .",
-    "postpack": "rm README.md && npm pkg delete gitHead",
+    "prepack": "bun run build && bun run verify-dist.ts && cp ../../README.md . && cp -R ../../skills .",
+    "postpack": "rm -r README.md skills && npm pkg delete gitHead",
     "compile.browser": "bun build src/browser/index.ts --minify --sourcemap=linked --format=esm --target=browser --outdir=dist/browser --entry-naming 'uql-browser.min.[ext]'",
     "build": "bun run clean && tsc -b tsconfig.build.json && bun run compile.browser && bun run verify-dist.ts",
     "start": "tsc --watch",
@@ -167,6 +168,7 @@
     "url": "https://github.com/rogerpadilla/uql/issues"
   },
   "keywords": [
+    "tanstack-intent",
     "orm",
     "uql",
     "sql",

package/skills/uql-orm/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: uql-orm
+description: >
+  Write code with UQL (the uql-orm package), the TypeScript ORM whose queries are plain JSON objects,
+  on PostgreSQL, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, MongoDB, Turso, Neon, D1 and PGlite.
+  Use when a project imports uql-orm, or when defining entities, querying, populating relations,
+  writing transactions, raw SQL or migrations with it. UQL is not Prisma, Drizzle, TypeORM or MikroORM:
+  their APIs do not carry over.
+---
+
+# UQL
+
+Entities are classes; a query is a JSON object checked key by key against the entity; the same query runs
+on every database UQL supports. There is no schema file, no generated client, and no query builder.
+
+The full docs are Markdown at https://uql-orm.dev/llms.txt, one page per URL. Read the page for the task
+before guessing an option: every page listed there is a `.md` URL.
+
+## Setup
+
+```sh
+npm install uql-orm pg   # or mysql2, mariadb, better-sqlite3, mongodb, @libsql/client, ...
+```
+
+ESM only. Node 24+, Bun, Deno or an edge runtime, TypeScript 5.2+. Decorators are the TC39 standard:
+never enable `experimentalDecorators` or `emitDecoratorMetadata`, never import `reflect-metadata`.
+In `tsconfig.json`, `module` is `nodenext` or `preserve`, and `target` is a dated one (`es2022`+), not `esnext`.
+
+```ts
+// uql.config.ts
+import type { Config } from 'uql-orm';
+import { PgQuerierPool } from 'uql-orm/postgres';
+import { Post, User } from './entities.js';
+
+export const pool = new PgQuerierPool({ connectionString: process.env.DATABASE_URL });
+
+export default { pool, entities: [User, Post] } satisfies Config;
+```
+
+Each driver has its own entry point: `uql-orm/postgres`, `uql-orm/mysql`, `uql-orm/maria`, `uql-orm/sqlite`,
+`uql-orm/mongo`, `uql-orm/libsql`, `uql-orm/turso`, `uql-orm/neon`, `uql-orm/d1`, `uql-orm/pglite`,
+`uql-orm/bunSql`, `uql-orm/mssql`, `uql-orm/cockroachdb`. Build the pool once per process and import it.
+
+## Entities
+
+```ts
+import { Entity, Field, Id, ManyToOne, OneToMany } from 'uql-orm';
+
+@Entity()
+export class User {
+  @Id({ type: 'uuid', onInsert: () => crypto.randomUUID() })
+  id?: string;
+
+  @Field({ type: String, unique: true, nullable: false })
+  email?: string;
+
+  @OneToMany({ entity: () => Post, mappedBy: (post) => post.author })
+  posts?: Post[];
+}
+
+@Entity()
+export class Post {
+  @Id({ type: Number })
+  id?: number;
+
+  @Field({ type: String })
+  title?: string | null;
+
+  @Field({ references: () => User })
+  authorId?: string | null;
+
+  @ManyToOne({ entity: () => User, references: (post) => post.authorId })
+  author?: User;
+}
+```
+
+- Every `@Field` states its `type` (`String`, `Number`, `Boolean`, `Date`, `BigInt`, or a column type such as
+  `'uuid'`, `'text'`, `'jsonb'`), except a foreign key, which takes `references` and inherits the target key's type.
+- A column is nullable unless it says `nullable: false`, and its property must admit `null` to match:
+  `title?: string | null`. A property typed without `| null` on a nullable column is a compile error.
+- Members are named by callbacks, never by strings: `mappedBy: (post) => post.author`, `references: (post) => post.authorId`.
+- `@ManyToMany({ entity: () => Tag, through: () => PostTag })` names its junction entity.
+- `defineEntity` defines the same entity without decorators: https://uql-orm.dev/entities/imperative.md
+
+## Queries
+
+```ts
+import { pool } from './uql.config.js';
+import { User } from './entities.js';
+
+const users = await pool.findMany(User, {
+  $select: { id: true, email: true },
+  $where: { email: { $endsWith: '@uql-orm.dev' }, $or: [{ id: 'a' }, { id: 'b' }] },
+  $populate: { posts: { $select: { title: true }, $sort: { id: 'desc' }, $limit: 5 } },
+  $sort: { email: 'asc' },
+  $skip: 0,
+  $limit: 20,
+});
+```
+
+- The keys are `$select`, `$exclude`, `$where`, `$populate`, `$sort`, `$skip`, `$limit`.
+- `$where` takes a value for equality or an operator map: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`,
+  `$nin`, `$between`, `$like`, `$ilike`, `$regex`, `$startsWith`, `$endsWith`, `$includes`, `$isNull`,
+  `$isNotNull`. `$and`, `$or`, `$not` and `$nor` combine clauses.
+- A result is narrowed to what the query selected and populated: reading an unselected field is a compile error.
+  Name that shape with `QueryFindResult<User, 'id' | 'email'>` rather than widening the query.
+- `$populate` loads relations in the same statement. Nothing is lazy: a relation not populated is not there.
+- A query is plain data, so it can be built dynamically, stored, or sent from a browser to `uql-orm/http`.
+- Methods: `findMany`, `findOne`, `findOneById`, `findManyAndCount`, `findManyStream`, `count`, `exists`,
+  `aggregate`, `insertOne`, `insertMany`, `updateOneById`, `updateMany`, `saveOne`, `saveMany`, `upsertOne`,
+  `upsertMany`, `deleteOneById`, `deleteMany`. Each takes the entity class first.
+- `updateMany` and `deleteMany` with no `$where` throw; `{ unfiltered: true }` means the whole table.
+- `raw()` embeds SQL anywhere a value or field goes; `pool.all(sql, values)` runs a raw `SELECT`.
+
+## Connections and transactions
+
+Every method is on both the pool and a querier. A pool call acquires a connection for that call and releases it.
+To run several operations on one connection, or atomically, hold a querier:
+
+```ts
+await pool.transaction(async (querier) => {
+  const userId = await querier.insertOne(User, { email: 'ada@uql-orm.dev' });
+  await querier.insertOne(Post, { title: 'Hello', authorId: userId });
+});
+```
+
+Inside the callback, call `querier`, never `pool`: a `pool` call runs on another connection, outside the
+transaction. A querier from `pool.getQuerier()` is yours to release: bind it with `await using`.
+
+## Migrations
+
+`npx uql-migrate` reads `uql.config.ts`. `sync` creates what the entities imply (development only);
+`generate:entities` writes the diff as a migration file to review; `up` applies migrations; `generate:from-db`
+writes entity classes from an existing database; `drift:check` fails when the database no longer matches.
+
+## Where to read more
+
+- Operators, per-dialect SQL: https://uql-orm.dev/querying/comparison-operators.md
+- Relations and deep `$populate`: https://uql-orm.dev/querying/relations.md
+- Every method's signature: https://uql-orm.dev/querying/methods.md
+- Coming from Prisma, Drizzle, TypeORM or MikroORM: https://uql-orm.dev/switching-to-uql.md
+- Breaking changes by version: https://uql-orm.dev/upgrade-guide.md