uql-orm 0.57.0 → 0.59.0

package/dist/type/queryWhere.d.ts

@@ -1,4 +1,5 @@
 import type { FieldKey, JsonFieldPaths, JsonFieldPathValue, RelationKey, RelationTarget } from './entity.js';
+import type { QuerySelect } from './query.js';
 import type { QueryRaw } from './queryRaw.js';
 import type { ExpandScalar, IsMany, QueryComparableScalar, Scalar } from './utility.js';
 import type { QueryVectorQuery } from './vector.js';
@@ -11,9 +12,9 @@ export type QueryTextSearchOptions<E> = {
      */
     $value: string;
     /**
-     * list of fields to search on.
+     * the fields to search, `{ title: true, body: true }`, in the order a MySQL `FULLTEXT` index lists them.
      */
-    $fields?: FieldKey<E>[];
+    $fields?: QuerySelect<E>;
     /**
      * Postgres text-search configuration (e.g. `'english'`), applied to both the document and the
      * query. Defaults to the server's `default_text_search_config`. Ignored by other dialects.
@@ -27,17 +28,19 @@ export type QueryTextSearchOptions<E> = {
  * filtered via nested typed objects; dotted relation paths are not supported (the dialects throw
  * for non-JSON dotted keys).
  *
- * One mapped type over the three key sets rather than three intersected, for the reason
- * {@link QuerySortMap} is: the sets are disjoint, and an assignability check against an
- * intersection is repeated per constituent, which every `$where` in a codebase pays. The root
- * operators stay a separate member - they are a fixed shape, not keyed off the entity.
+ * Fields and relations share one mapped type over `K extends keyof E`, which keeps each key linked to
+ * its property (see {@link QuerySelect}). JSON paths are not keys of `E`, so they are a second member,
+ * and only where the entity has one: an empty member would switch off the weak-type check that
+ * rejects `$where: 1`.
  *
  * An object and nothing else: in a union with ids or lists, TypeScript reports a wrong value against
  * the whole `$where` instead of the key holding it. Ids are `{ id: 1 }`, or the by-id methods.
  */
-export type QueryWhere<E> = QueryWhereRootOperator<E> & {
-    [K in FieldKey<E> | RelationKey<E> | JsonFieldPaths<E>]?: K extends FieldKey<E> ? QueryWhereFieldValue<E[K]> : K extends RelationKey<E> ? QueryWhere<RelationTarget<E[K]>> | QueryRelationSizeFilter : QueryWhereFieldValue<JsonFieldPathValue<E, K & string>>;
-};
+export type QueryWhere<E, K extends keyof E = FieldKey<E> | RelationKey<E>> = QueryWhereRootOperator<E> & {
+    [P in K]?: P extends FieldKey<E> ? QueryWhereFieldValue<E[P]> : QueryWhere<RelationTarget<E[P]>> | QueryRelationSizeFilter;
+} & ([JsonFieldPaths<E>] extends [never] ? unknown : {
+    [P in JsonFieldPaths<E>]?: QueryWhereFieldValue<JsonFieldPathValue<E, P>>;
+});
 /**
  * Filter a to-many relation by its row count.
  * @example { users: { $size: 2 } }

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

@@ -145,10 +145,10 @@ export declare function parseRelationSize(val: unknown): number | QuerySizeCompa
  */
 export declare function parseSortByCount(val: unknown): unknown;
 /**
- * Parse the `$group` (grouped columns) and `$agg` (computed aggregates) maps into structured
+ * Parse the `$group` (grouped columns) and `$select` (computed aggregates) maps into structured
  * entries consumable by any dialect. Grouped columns come first, then computed columns.
  */
-export declare function parseGroupMap<E>(group?: QueryGroupMap<E>, agg?: QueryAggMap<E>): ParsedGroupEntry[];
+export declare function parseGroupMap<E>(group?: QueryGroupMap<E>, select?: QueryAggMap<E>): ParsedGroupEntry[];
 /**
  * Whether `value` is a map of comparison operators rather than a value to compare against. Only a
  * plain object qualifies: `Date`, `QueryRaw`, `Uint8Array` and arrays are all `typeof 'object'`, and
@@ -165,7 +165,7 @@ export declare function isOperatorMap(value: unknown): value is Record<string, u
 export declare function assertNonNegativeInteger(value: number, clause: string): number;
 /**
  * Rejects a `$having`/`$sort` key naming something an aggregate does not emit. Its rows are its
- * `$group` columns and its `$agg` aliases; anything else is a value that is not there. Shared so
+ * `$group` columns and its `$select` aliases; anything else is a value that is not there. Shared so
  * SQL and MongoDB refuse the same query with the same words.
  */
 export declare function throwUnknownAggregateColumn(key: string, clause: string): never;

package/dist/util/dialect.util.js

@@ -3,7 +3,7 @@ import { soleIdOf } from '../entity/metadata/definition.js';
 import { QueryRaw, resolveAggregateOp, SOFT_DELETE_FILTER, } from '../type/index.js';
 import { VECTOR_INDEX_TYPES } from '../type/vector.js';
 import { isDatabaseWritten } from './field.util.js';
-import { entityName, getFieldKeys, getKeys, hasKeys, isScalarId, isWhereMap, someKey } from './object.util.js';
+import { entityName, getFieldKeys, getKeys, hasKeys, isScalarId, isRecord, isWhereMap, someKey, } from './object.util.js';
 export function filterFieldKeys(meta, payload, callbackKey) {
     return getKeys(payload).filter((key) => {
         const fieldOpts = meta.fields[key];
@@ -355,10 +355,10 @@ export function parseSortByCount(val) {
     return val.$count;
 }
 /**
- * Parse the `$group` (grouped columns) and `$agg` (computed aggregates) maps into structured
+ * Parse the `$group` (grouped columns) and `$select` (computed aggregates) maps into structured
  * entries consumable by any dialect. Grouped columns come first, then computed columns.
  */
-export function parseGroupMap(group, agg) {
+export function parseGroupMap(group, select) {
     const entries = [];
     const groupMap = group ?? {};
     for (const alias of getKeys(groupMap)) {
@@ -366,22 +366,30 @@ export function parseGroupMap(group, agg) {
             entries.push({ kind: 'key', alias });
         }
     }
-    if (!agg) {
+    if (!select) {
         return entries;
     }
-    for (const alias of getKeys(agg)) {
-        const fnEntry = agg[alias];
+    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 { op, distinct } = resolveAggregateOp(key);
-        const fieldRef = fnEntry[key];
-        if (fieldRef === undefined) {
-            throw TypeError(`empty aggregate function for: ${alias}`);
-        }
-        entries.push({ kind: 'fn', alias, op, fieldRef, distinct });
+        entries.push({ kind: 'fn', alias, op, fieldRef: aggregateFieldRef(alias, fnEntry[key]), distinct });
     }
     return entries;
 }
+/** The column an aggregate reads: `'*'`, or the one field its `{ field: true }` names. */
+function aggregateFieldRef(alias, arg) {
+    const [field, ...rest] = arg === '*' ? [arg] : namedKeys(arg);
+    if (field === undefined || rest.length) {
+        throw new TypeError(`aggregate '${alias}' takes one field as { field: true }, or '*': got ${JSON.stringify(arg)}`);
+    }
+    return field;
+}
+/** The keys a `{ key: true }` map switches on; anything that is not such a map switches on none. */
+function namedKeys(map) {
+    return isRecord(map) ? getKeys(map).filter((key) => map[key]) : [];
+}
 /**
  * Whether `value` is a map of comparison operators rather than a value to compare against. Only a
  * plain object qualifies: `Date`, `QueryRaw`, `Uint8Array` and arrays are all `typeof 'object'`, and
@@ -410,11 +418,11 @@ export function assertNonNegativeInteger(value, clause) {
 }
 /**
  * Rejects a `$having`/`$sort` key naming something an aggregate does not emit. Its rows are its
- * `$group` columns and its `$agg` aliases; anything else is a value that is not there. Shared so
+ * `$group` columns and its `$select` aliases; anything else is a value that is not there. Shared so
  * SQL and MongoDB refuse the same query with the same words.
  */
 export function throwUnknownAggregateColumn(key, clause) {
-    throw new TypeError(`cannot ${clause} by '${key}': it is neither a $group column nor an $agg alias`);
+    throw new TypeError(`cannot ${clause} by '${key}': it is neither a $group column nor a $select alias`);
 }
 /** {@link throwUnknownAggregateColumn} over every key of a clause, for backends that check up front. */
 export function assertAggregateColumns(clauseMap, emitted, clause) {
@@ -430,8 +438,9 @@ export function assertAggregateColumns(clauseMap, emitted, clause) {
  * where neither says, rather than guessed: every engine answers a guess with an error of its own.
  */
 export function textSearchFields(meta, search) {
-    if (search.$fields?.length) {
-        return search.$fields;
+    const named = namedKeys(search.$fields);
+    if (named.length) {
+        return named;
     }
     const fulltext = (meta.indexes ?? []).filter((index) => index.type === 'fulltext');
     if (fulltext.length === 1) {

package/dist/util/relationQuery.util.d.ts

@@ -57,7 +57,7 @@ export declare function populatesRelations<E>(meta: EntityMeta<E>, populate?: Qu
 export declare function countedRelations<E>(meta: EntityMeta<E>, counts: QueryCount<E> | undefined): {
     readonly relKey: RelationKey<E>;
     readonly relation: RelationMeta;
-    readonly where: QueryWhere<unknown>;
+    readonly where: QueryWhere<object>;
 }[];
 export type ParsedRelationQuery<E extends object = object> = {
     query: RelationQuery<E>;

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.57.0",
+  "version": "0.59.0",
   "type": "module",
   "engines": {
     "node": ">=24"