uql-orm 0.70.0 → 0.71.0

package/dist/type/entity.d.ts

@@ -504,15 +504,26 @@ export type HookRegistration = {
     readonly methodName: string;
 };
 /**
- * An index type with the metric it needs: a vector index has to name one, since engines default to
- * a different one than the queries use, and any other index names none.
+ * An index type with what it needs: a vector index has to name its metric, since engines default to a
+ * different one than the queries use; an Atlas `vectorSearch` index may, else takes its field's, else
+ * cosine; a `fulltext` one may name the text-search `config` it parses with; and any other index neither.
  */
 export type IndexTypeOptions = {
     type: VectorIndexType;
     distance: VectorDistance;
+    config?: never;
 } | {
-    type?: Exclude<IndexType, VectorIndexType>;
+    type: 'vectorSearch';
+    distance?: VectorDistance;
+    config?: never;
+} | {
+    type: 'fulltext';
+    distance?: never;
+    config?: string;
+} | {
+    type?: Exclude<IndexType, VectorIndexType | 'vectorSearch' | 'fulltext'>;
     distance?: never;
+    config?: never;
 };
 /** One index entry as the migration builder takes it: a column name, `raw`, or an object when it needs more. */
 export type IndexColumnInput = string | QueryRaw | EntityIndexColumn;

package/dist/type/migration.d.ts

@@ -1,9 +1,8 @@
-import type { VectorCast } from '../dialect/vectorCast.js';
 import type { AnyMigrationOperation } from '../migrate/builder/types.js';
 import type { IndexFacet } from '../schema/indexDifferences.js';
 import type { SchemaAST } from '../schema/schemaAST.js';
 import type { ColumnNode, ForeignKeyAction, IndexType, TableNode } from '../schema/types.js';
-import type { EntityMeta, EntityWhereMeta, FieldOptions, IndexColumnSchema, LoggingOptions, Querier, SqlQuerier, Type, VectorIndexOptions } from './index.js';
+import type { EntityMeta, EntityWhereMeta, FieldOptions, IndexColumnSchema, IndexedVectorField, LoggingOptions, Querier, SqlQuerier, Type, VectorIndexOptions } from './index.js';
 /**
  * Defines a migration using a simple object literal. `Q` is `MongoQuerier` for a MongoDB migration.
  */
@@ -133,7 +132,12 @@ export interface TableSchema {
 /**
  * Represents an index in a database table
  */
-export interface IndexSchema extends VectorIndexOptions {
+export interface IndexSchema extends VectorIndexOptions, IndexedVectorField {
+    /**
+     * A `fulltext` index's text-search configuration, which `$text` parses with on the Postgres family
+     * (`'english'`); `'simple'` where unstated. Other engines take their language from elsewhere.
+     */
+    readonly config?: string;
     readonly name: string;
     /**
      * What the index is over, in order. Named `entries` and not `columns` because an entry need not be
@@ -149,12 +153,6 @@ export interface IndexSchema extends VectorIndexOptions {
     readonly where?: string;
     /** Non-key columns stored in the index (Postgres-wire `INCLUDE`). */
     readonly include?: readonly string[];
-    /**
-     * The indexed column's vector type, which pgvector's operator-class names are built from
-     * (`halfvec_cosine_ops`). Absent for a non-vector index, and for an index whose column types are
-     * unknown, where `vector` is assumed.
-     */
-    readonly vectorType?: VectorCast;
 }
 /**
  * A foreign key constraint, wherever one is described: read back by introspection, planned into a

package/dist/type/queryAggregate.d.ts

@@ -122,16 +122,12 @@ type QueryGroupSchema<E, G> = Readonly<QuerySelect<E, FieldKey<E>, true>> & {
     readonly [K in Exclude<NamedKeys<G>, FieldKey<E>>]: QueryGroupRef<E>;
 } & RejectKeys<Exclude<GroupedKeys<G>, FieldKey<E>>>;
 /**
- * The value a path reads: the field's own type, or through a relation, `null` where the row points nowhere.
- * `any` answers `unknown`: TypeScript checks a deferred type by instantiating it with `any`, which would
- * walk every relation of the entity on every aggregate call, quadrupling what one costs to check.
+ * The value a path reads: the field at its end as its column holds it, `null` only where that does, since
+ * the path joins the rows it reads. `any` answers `unknown`: TypeScript checks a deferred type by
+ * instantiating it with `any`, which would walk every relation of the entity on every aggregate call.
  */
 type GroupRefValue<E, Ref> = 0 extends 1 & Ref ? unknown : {
-    [K in keyof Ref & keyof E]: Ref[K] extends true ? E[K] : NonNullable<GroupRefLeaf<RelationTarget<E[K]>, Ref[K]>> | null;
-}[keyof Ref & keyof E];
-/** The field at the end of a path, whose type {@link GroupRefValue} widens with `null`; `any` as it does. */
-type GroupRefLeaf<E, Ref> = 0 extends 1 & Ref ? unknown : {
-    [K in keyof Ref & keyof E]: Ref[K] extends true ? E[K] : GroupRefLeaf<RelationTarget<E[K]>, Ref[K]>;
+    [K in keyof Ref & keyof E]: Ref[K] extends true ? Exclude<E[K], undefined> : GroupRefValue<RelationTarget<E[K]>, Ref[K]>;
 }[keyof Ref & keyof E];
 /** Computed columns by the alias each is read back under: `{ count: { $count: '*' }, avgAge: { $avg: { age: true } } }`. */
 export type QueryAggMap<E> = {

package/dist/type/vector.d.ts

@@ -1,3 +1,4 @@
+import type { VectorCast } from '../dialect/vectorCast.js';
 import type { IndexType } from '../schema/types.js';
 /**
  * A vector search's metric: `cosine` (the default), `l2`, `inner` product or `l1`. No hamming: every
@@ -55,6 +56,22 @@ export type VectorIndexOptions = {
     /** IVFFlat: number of inverted lists. */
     lists?: number;
 };
+/** The metric a search or an index measures by where nothing names one: every engine with vectors has it. */
+export declare const DEFAULT_VECTOR_DISTANCE: VectorDistance;
+/** The metric an index is built for: its own, else {@link DEFAULT_VECTOR_DISTANCE}. */
+export declare function indexDistance(index: {
+    readonly distance?: VectorDistance;
+}): VectorDistance;
+/**
+ * What a vector index's DDL reads off the field it indexes, never declared on the index itself, so the
+ * two cannot disagree. Absent for a non-vector index, and for one whose field is unknown.
+ */
+export type IndexedVectorField = {
+    /** The field's vector type, which pgvector's operator classes are named after (`halfvec_cosine_ops`); `vector` where absent. */
+    readonly vectorType?: VectorCast;
+    /** The field's dimensions, which an Atlas vector search index states. */
+    readonly dimensions?: number;
+};
 /**
  * Index types whose emitted DDL depends on the distance metric. The runtime list is the source, so
  * the type and every dialect's "do I have this one?" answer cannot drift from each other.

package/dist/type/vector.js

@@ -5,6 +5,12 @@ export function unsupportedVectorMetric(dialectName, distance, indexName) {
     const where = indexName === undefined ? '' : ` (index "${indexName}")`;
     return new TypeError(`${dialectName} does not support vector distance metric: ${distance}${where}`);
 }
+/** The metric a search or an index measures by where nothing names one: every engine with vectors has it. */
+export const DEFAULT_VECTOR_DISTANCE = 'cosine';
+/** The metric an index is built for: its own, else {@link DEFAULT_VECTOR_DISTANCE}. */
+export function indexDistance(index) {
+    return index.distance ?? DEFAULT_VECTOR_DISTANCE;
+}
 /**
  * Index types whose emitted DDL depends on the distance metric. The runtime list is the source, so
  * the type and every dialect's "do I have this one?" answer cannot drift from each other.

package/dist/util/ddlExpression.util.d.ts

@@ -10,3 +10,5 @@ export declare function declaredIndexes<E>(meta: EntityMeta<E>): EntityIndexMeta
 export declare function renderIndexColumn(entry: EntityIndexColumn, render: (sql: QueryRaw) => string): IndexColumnSchema;
 /** What an unnamed index's name is built from: each entry's column, or `expr<n>` for an expression, which has none. */
 export declare function indexNameParts(entries: readonly EntityIndexColumn[]): string[];
+/** The name an index is created and read by: its own, else one derived from its table and its entries' columns. */
+export declare function declaredIndexName(name: string | undefined, table: string, entries: readonly EntityIndexColumn[]): string;

package/dist/util/ddlExpression.util.js

@@ -1,5 +1,6 @@
 import { ColumnRef, QueryRaw, } from '../type/index.js';
 import { definedEntries } from './object.util.js';
+import { derivedIndexName } from './sql.util.js';
 /**
  * Reduces an authored index entry to the form metadata keeps, so a column, an expression and an options
  * object reach the schema as one: a column read off the refs as its key, any other `raw` as it is.
@@ -30,3 +31,7 @@ export function renderIndexColumn(entry, render) {
 export function indexNameParts(entries) {
     return entries.map((entry, at) => (typeof entry.column === 'string' ? entry.column : `expr${at}`));
 }
+/** The name an index is created and read by: its own, else one derived from its table and its entries' columns. */
+export function declaredIndexName(name, table, entries) {
+    return name ?? derivedIndexName(table, indexNameParts(entries));
+}

package/dist/util/dialect.util.d.ts

@@ -71,6 +71,10 @@ export declare function findVectorSort<E>(sort: QuerySortMap<E> | undefined): {
     key: string;
     search: QueryVectorSearch;
 } | undefined;
+/** `$candidates`, checked: it can be spelled into a statement, and `/http` input is untyped. */
+export declare function vectorCandidates(q: {
+    readonly $candidates?: number;
+}): number | undefined;
 /**
  * The vector index declared on `key`, if any. Answers both "is there an ANN index to tune here" and
  * "which kind", which decide the name Atlas is queried by and the setting Postgres is tuned with.
@@ -114,7 +118,7 @@ export type ParsedGroupEntry<E = object> = {
     readonly alias: string;
     readonly op: QueryAggregateOp;
     readonly fieldRef: string;
-    /** `true` for a flat distinct op (`$countDistinct`, ...) -> `COUNT(DISTINCT field)`. */
+    /** `true` for `$countDistinct`: `COUNT(DISTINCT field)`. */
     readonly distinct: boolean;
     /** The rows it reads, where not all of the statement's. */
     readonly where?: QueryWhere<E>;
@@ -159,6 +163,12 @@ export declare function assertNonNegativeInteger(value: number, clause: string):
 export declare function throwUnknownAggregateColumn(key: string, clause: string): never;
 /** {@link throwUnknownAggregateColumn} over every key of a clause, for backends that check up front. */
 export declare function assertAggregateColumns(clauseMap: object, emitted: ReadonlySet<string>, clause: string): void;
+/** The text-search config a fulltext index builds with, which a search it serves has to parse with too. */
+export declare function fulltextConfig(index: {
+    readonly config?: string;
+}): string;
+/** The fulltext index over exactly `fields`, in order, which a search of them is served by. */
+export declare function fulltextIndexOver<E>(meta: EntityMeta<E>, fields: readonly string[]): EntityIndexMeta<E> | undefined;
 /**
  * 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/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
@@ -359,7 +367,7 @@ export function parseGroupMap(group, select) {
         if (key === undefined) {
             throw new TypeError(`aggregate '${alias}' names no op, only a $where`);
         }
-        // Flat DISTINCT ops (`$countDistinct`, ...) normalize to their base op + a `distinct` flag.
+        // `$countDistinct` normalizes to `$count` plus a `distinct` flag.
         const { op, distinct } = resolveAggregateOp(key);
         const fieldRef = aggregateFieldRef(alias, call[key]);
         entries.push({ kind: 'fn', alias, op, fieldRef, distinct, ...(where && hasKeys(where) ? { where } : {}) });
@@ -432,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.70.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