uql-orm 0.71.0 → 0.72.1

package/dist/type/queryAggregate.d.ts

@@ -2,7 +2,7 @@ import type { FieldKey, RelationKey, RelationTarget } from './entity.js';
 import type { QueryPager, QuerySelect, QuerySortDirection } from './query.js';
 import type { QueryRaw } from './queryRaw.js';
 import type { QueryWhere, QueryWhereFieldValue } from './queryWhere.js';
-import type { IsMany, RejectKeys } from './utility.js';
+import type { ExactlyOne, IsMany, RejectKeys } from './utility.js';
 /** The columns `$group` names by a literal `true`, so an uninferred `$group`, its own constraint, names none. */
 type GroupedKeys<G> = {
     [K in keyof G]: G[K] extends true ? K : never;
@@ -37,13 +37,6 @@ export declare function resolveAggregateOp(key: string): {
     op: QueryAggregateOp;
     distinct: boolean;
 };
-/**
- * Exactly one key of `T` with its value; every other key is forbidden (`never`). `Pick`, not `Record`,
- * so the chosen key stays linked to `T`'s own property and renames follow it through.
- */
-type ExactlyOne<T> = {
-    [K in keyof T]: Readonly<Pick<T, K>> & Partial<Readonly<Record<Exclude<keyof T, K>, never>>>;
-}[keyof T];
 /**
  * One field named as a key - `{ amount: true }` - the way a statement names every field, so an editor
  * rename reaches it where a string never would. `F` narrows which fields qualify.

package/dist/type/utility.d.ts

@@ -30,6 +30,12 @@ export type ExpandScalar<T> = T extends Date ? Date | string : T;
 export interface RawRow {
     [key: string]: unknown;
 }
+/**
+ * Whether `A` and `B` are the same type, `readonly` included - which no conditional sees, since
+ * assignability ignores the modifier. Two identical generic signatures compare equal only when their
+ * deferred bodies do.
+ */
+export type IsEqual<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => (T extends B ? 1 : 2) ? true : false;
 export type Writable<T> = {
     -readonly [K in keyof T]: T[K];
 };
@@ -46,6 +52,13 @@ export type Except<T, K extends keyof T> = {
  * excess-property check on one.
  */
 export type RejectKeys<K> = [K] extends [never] ? unknown : Record<K & string, never>;
+/**
+ * Exactly one key of `T` with its value; every other key is forbidden (`never`). `Pick`, not `Record`,
+ * so the chosen key stays linked to `T`'s own property and renames follow it through.
+ */
+export type ExactlyOne<T> = {
+    [K in keyof T]: Readonly<Pick<T, K>> & Partial<Readonly<Record<Exclude<keyof T, K>, never>>>;
+}[keyof T];
 export type Unpacked<T> = T extends readonly (infer U)[] ? U : T extends (...args: unknown[]) => infer U ? U : T extends Promise<infer U> ? U : T;
 /**
  * Whether the value a property holds is many rather than one: a to-many relation, a scalar array, a

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

@@ -1,4 +1,5 @@
-import { type CascadeType, type EntityData, type EntityId, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type JsonUpdateOp, type OnFieldCallback, type Query, type QueryAggMap, type QueryAggregateOp, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorSearch, type QueryWhere, type RelationKey, type UpdatePayload } from '../type/index.js';
+import type { IndexType } from '../schema/types.js';
+import { type CascadeType, type EntityData, type EntityId, type EntityIndexMeta, type EntityMeta, type FieldKey, type FieldOptions, type FieldUpdateOp, type JsonUpdateOp, type OnFieldCallback, type Query, type QueryAggMap, type QueryAggregateOp, type QueryExclude, type QueryGroupMap, type QueryOptions, QueryRaw, type QuerySearch, type QuerySelect, type QuerySelectValue, type QuerySizeComparisonOps, type QuerySortMap, type QueryTextSearchOptions, type QueryVectorSearch, type QueryWhere, type RelationKey, type UpdatePayload } from '../type/index.js';
 export type CallbackKey = keyof Pick<FieldOptions, 'onInsert' | 'onUpdate'>;
 /** The keys of `payload` a write persists as columns. */
 export declare function filterFieldKeys<E>(meta: EntityMeta<E>, payload: EntityData<E> | UpdatePayload<E>, callbackKey: CallbackKey): FieldKey<E>[];
@@ -87,6 +88,10 @@ export declare function findVectorIndex<E>(meta: EntityMeta<E>, key: string): En
 export declare function hasVectorNear(where: unknown): boolean;
 /** Type guard: checks whether an update payload value is a JSON operator object. */
 export declare function isJsonUpdateOp(value: unknown): value is JsonUpdateOp;
+/** Type guard: checks whether an update payload value is a scalar field's operator. */
+export declare function isFieldUpdateOp(value: unknown): value is FieldUpdateOp;
+/** The one operator a scalar field's update carries, and its operand. */
+export declare function fieldUpdateOf(value: FieldUpdateOp): [keyof FieldUpdateOp, number | bigint];
 /**
  * The `$where` naming rows by key: a bare value names the one key column (refused on a composite), a
  * composite's key map is a `$where` already, and a list is an `IN` of bare values or an OR of maps.
@@ -167,8 +172,31 @@ export declare function assertAggregateColumns(clauseMap: object, emitted: Reado
 export declare function fulltextConfig(index: {
     readonly config?: string;
 }): string;
+/**
+ * Each column's weight in a fulltext index, 1 where it states none, or none at all where they are alike.
+ * Checked wherever it is read, so the migration, the search and its rank refuse the same declaration.
+ */
+export declare function fulltextWeights(index: {
+    readonly type?: IndexType;
+    readonly entries: readonly {
+        readonly weight?: number;
+    }[];
+}): readonly number[] | undefined;
+/**
+ * A weighted fulltext index's lightest weight, and what each column weighs beyond it: the score over every
+ * column counts the lightest, and a column weighing more adds its own score times the rest.
+ */
+export declare function textWeightSteps(weights: readonly number[]): {
+    lightest: number;
+    extra: number[];
+};
 /** 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 search a `$sort` by `$text` ranks by: the one at the root of the same query's `$where`. A nested or
+ * negated one has no score to order by, and MongoDB scores only the one `$text` it allows.
+ */
+export declare function rankedTextSearch<E>(where: QueryWhere<E> | undefined): QueryTextSearchOptions<E>;
 /**
  * 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

@@ -236,6 +236,16 @@ const JSON_UPDATE_OPS = [
 export function isJsonUpdateOp(value) {
     return isRecord(value) && someKey(value, (key) => JSON_UPDATE_OPS.includes(key));
 }
+/** `satisfies` ties this to {@link FieldUpdateOp}, so renaming an operator breaks it at compile time. */
+const FIELD_UPDATE_OPS = ['$inc', '$mul'];
+/** Type guard: checks whether an update payload value is a scalar field's operator. */
+export function isFieldUpdateOp(value) {
+    return isRecord(value) && someKey(value, (key) => FIELD_UPDATE_OPS.includes(key));
+}
+/** The one operator a scalar field's update carries, and its operand. */
+export function fieldUpdateOf(value) {
+    return value.$inc === undefined ? ['$mul', value.$mul] : ['$inc', value.$inc];
+}
 /**
  * The `$where` naming rows by key: a bare value names the one key column (refused on a composite), a
  * composite's key map is a `$where` already, and a list is an `IN` of bare values or an OR of maps.
@@ -370,7 +380,7 @@ export function parseGroupMap(group, select) {
         // `$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 } : {}) });
+        entries.push({ kind: 'fn', alias, op, fieldRef, distinct, ...(hasKeys(where) ? { where } : {}) });
     }
     return entries;
 }
@@ -446,12 +456,51 @@ const DEFAULT_TEXT_CONFIG = 'simple';
 export function fulltextConfig(index) {
     return index.config ?? DEFAULT_TEXT_CONFIG;
 }
+/** The largest weight MongoDB's text index takes, which truncates a fraction to the whole number below. */
+const MAX_TEXT_WEIGHT = 99_999;
+/**
+ * Each column's weight in a fulltext index, 1 where it states none, or none at all where they are alike.
+ * Checked wherever it is read, so the migration, the search and its rank refuse the same declaration.
+ */
+export function fulltextWeights(index) {
+    if (!index.entries.some((entry) => entry.weight !== undefined)) {
+        return undefined;
+    }
+    if (index.type !== 'fulltext') {
+        throw new TypeError(`a column weight ranks a fulltext index, and this one is ${index.type ?? 'btree'}`);
+    }
+    const weights = index.entries.map(({ weight = 1 }) => {
+        if (!Number.isInteger(weight) || weight < 1 || weight > MAX_TEXT_WEIGHT) {
+            throw new TypeError(`a column weight is a whole number from 1 to ${MAX_TEXT_WEIGHT}, not ${weight}`);
+        }
+        return weight;
+    });
+    return new Set(weights).size > 1 ? weights : undefined;
+}
+/**
+ * A weighted fulltext index's lightest weight, and what each column weighs beyond it: the score over every
+ * column counts the lightest, and a column weighing more adds its own score times the rest.
+ */
+export function textWeightSteps(weights) {
+    const lightest = Math.min(...weights);
+    return { lightest, extra: weights.map((weight) => weight - lightest) };
+}
 /** 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 search a `$sort` by `$text` ranks by: the one at the root of the same query's `$where`. A nested or
+ * negated one has no score to order by, and MongoDB scores only the one `$text` it allows.
+ */
+export function rankedTextSearch(where) {
+    if (!where?.$text) {
+        throw new TypeError('$sort by $text ranks by the $text at the root of $where, which this query has none of');
+    }
+    return where.$text;
+}
 /**
  * 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.71.0",
+  "version": "0.72.1",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -168,7 +168,6 @@
     "url": "https://github.com/rogerpadilla/uql/issues"
   },
   "keywords": [
-    "tanstack-intent",
     "orm",
     "uql",
     "sql",

package/skills/uql-orm/SKILL.md

@@ -98,7 +98,8 @@ const users = await pool.findMany(User, {
 });
 ```
 
-- The keys are `$select`, `$exclude`, `$where`, `$populate`, `$sort`, `$skip`, `$limit`.
+- The keys are `$select`, `$exclude`, `$where`, `$populate`, `$count`, `$distinct`, `$sort`, `$skip`, `$limit`;
+  `$count: { posts: true }` tallies a to-many under `_count` without loading it.
 - `$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.
@@ -109,7 +110,10 @@ const users = await pool.findMany(User, {
 - 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.
+- `updateMany` and `deleteMany` naming no rows - no `$where`, no `$limit` - throw; `{ unfiltered: true }` means the whole table.
+- An update takes `{ stock: { $inc: -1 } }` to add, or `$mul` to multiply, in the statement, a NULL counting as 0,
+  so a guard in `$where` (`stock: { $gte: 1 }`) makes a decrement race-safe. JSON fields take `$set`, `$unset`,
+  `$push`, `$pull`.
 - `raw()` embeds SQL anywhere a value or field goes; `pool.all(sql, values)` runs a raw `SELECT`.
 
 ## Connections and transactions