uql-orm 0.60.0 → 0.62.0

package/dist/type/queryRaw.d.ts

@@ -1,43 +1,36 @@
 import type { QueryContext, QueryDialect } from './dialect.js';
-import type { Scalar } from './utility.js';
-/**
- * What may be passed towards a `raw` callback. Every key is optional here because the callers along the
- * way fill them in progressively; what reaches the callback is the complete set - see {@link QueryRawFn}.
- */
-export type QueryRawFnOptions = {
-    /**
-     * the current dialect.
-     */
-    dialect?: QueryDialect;
-    /**
-     * the prefix.
-     */
-    prefix?: string;
-    /**
-     * the escaped prefix.
-     */
-    escapedPrefix?: string;
+import type { Type } from './utility.js';
+/** What a `raw` callback receives. See {@link QueryRawFn}. */
+export type QueryRawRenderOptions = {
+    /** The dialect rendering the SQL. */
+    dialect: QueryDialect;
+    /** The alias of the table in scope, unescaped; empty where there is none. */
+    prefix: string;
+    /** {@link prefix} escaped, with its trailing dot. */
+    escapedPrefix: string;
+    /** The query context the SQL is written into. */
+    ctx: QueryContext;
     /**
-     * the query context.
+     * The entity being rendered, which a ref read off a definition's map resolves its column against: a
+     * computed field's own, or the one whose schema is built. Absent where a statement renders SQL.
      */
-    ctx?: QueryContext;
+    entity?: Type<unknown>;
 };
+/** {@link QueryRawRenderOptions} as the callers along the way fill them in, every one still optional. */
+export type QueryRawFnOptions = Partial<QueryRawRenderOptions>;
 /**
  * A `raw` callback: write into `ctx`, or return a string or number to have it appended. Anything else
  * it returns is ignored, which is why the return type is `unknown` rather than `void | Scalar` - the
  * latter rejected `({ ctx }) => ctx.append(...)`, the form every computed field is written in, because
  * TypeScript's "returning a value where void is expected" allowance does not apply to a union.
- *
- * `Required`, and the parameter not optional, because the one place that calls it (`getRawValue`)
- * passes all four every time.
  */
-export type QueryRawFn = (opts: Required<QueryRawFnOptions>) => unknown;
+export type QueryRawFn = (opts: QueryRawRenderOptions) => unknown;
 export declare const RAW_VALUE: unique symbol;
 export declare const RAW_ALIAS: unique symbol;
 export declare class QueryRaw {
-    readonly [RAW_VALUE]: Scalar | QueryRawFn;
+    readonly [RAW_VALUE]: QueryRawFn;
     readonly [RAW_ALIAS]?: string;
-    constructor(value: Scalar | QueryRawFn, alias?: string);
+    constructor(value: QueryRawFn, alias?: string);
     /** The same expression under an alias, for a `$select` projection. */
     as(alias: string): QueryRaw;
     /**
@@ -45,9 +38,8 @@ export declare class QueryRaw {
      * business, which is what lets a `raw` tagged template resolve an interpolated fragment without
      * the dialect having to expose a method for it.
      *
-     * The alias is not emitted here: it belongs to a `$select` projection, not to an expression, and
-     * a fragment nested inside another would otherwise emit one mid-expression. `getRawValue` appends
-     * it around this call.
+     * The alias is not emitted here: it names a `$select` projection, which writes it after the term,
+     * and anywhere else it would land mid-expression.
      */
-    render(opts: Required<QueryRawFnOptions>): void;
+    render(opts: QueryRawRenderOptions): void;
 }

package/dist/type/queryRaw.js

@@ -16,17 +16,11 @@ export class QueryRaw {
      * business, which is what lets a `raw` tagged template resolve an interpolated fragment without
      * the dialect having to expose a method for it.
      *
-     * The alias is not emitted here: it belongs to a `$select` projection, not to an expression, and
-     * a fragment nested inside another would otherwise emit one mid-expression. `getRawValue` appends
-     * it around this call.
+     * The alias is not emitted here: it names a `$select` projection, which writes it after the term,
+     * and anywhere else it would land mid-expression.
      */
     render(opts) {
-        const value = this[RAW_VALUE];
-        if (typeof value !== 'function') {
-            opts.ctx.append(opts.prefix + String(value));
-            return;
-        }
-        const emitted = value(opts);
+        const emitted = this[RAW_VALUE](opts);
         if (typeof emitted === 'string' || (typeof emitted === 'number' && !Number.isNaN(emitted))) {
             opts.ctx.append(String(emitted));
         }

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

@@ -1,15 +1,10 @@
-import { type IndexColumnInput, type IndexColumnSchema, QueryRaw } from '../type/index.js';
+import { type EntityIndexColumn, type IndexColumnInput, type IndexColumnSchema, QueryRaw } from '../type/index.js';
 /**
- * SQL bound for DDL, as the text a generator renders. `raw` with no interpolation, or a bare string
- * where one is still accepted: DDL is evaluated once at creation time, so there is no query context
- * for the callback form and no placeholder a `CREATE` statement could bind a value into.
- *
- * `what` names the thing being declared, so the error says which one the caller got wrong.
+ * Reduces an authored index entry to the form metadata keeps, so the shapes users write - a column
+ * name, an expression's callback, an options object - reach the schema as one, each callback resolved.
  */
-export declare function ddlText(value: string | QueryRaw, what: string): string;
-export declare function ddlText(value: string | QueryRaw | undefined, what: string): string | undefined;
-/**
- * Reduces an authored index entry to its normalized form, so the three shapes users write - a column
- * name, an expression, or an options object - reach the dialects as one.
- */
-export declare function normalizeIndexColumn(entry: IndexColumnInput): IndexColumnSchema;
+export declare function normalizeIndexColumn(entry: IndexColumnInput): EntityIndexColumn;
+/** An index entry as the schema holds it, its expression rendered to text by `render`. */
+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[];

package/dist/util/ddlExpression.util.js

@@ -1,27 +1,25 @@
-import { QueryRaw, RAW_VALUE } from '../type/index.js';
-export function ddlText(value, what) {
-    if (!(value instanceof QueryRaw)) {
-        return value;
-    }
-    const sql = value[RAW_VALUE];
-    if (typeof sql !== 'string') {
-        throw new TypeError(`${what} needs raw() with no interpolation, not a function or a bound value`);
-    }
-    return sql;
-}
+import { QueryRaw } from '../type/index.js';
+import { entitySql } from './raw.js';
 /**
- * Reduces an authored index entry to its normalized form, so the three shapes users write - a column
- * name, an expression, or an options object - reach the dialects as one.
+ * Reduces an authored index entry to the form metadata keeps, so the shapes users write - a column
+ * name, an expression's callback, an options object - reach the schema as one, each callback resolved.
  */
 export function normalizeIndexColumn(entry) {
     if (typeof entry === 'string') {
         return { column: entry };
     }
-    if (entry instanceof QueryRaw) {
-        return { column: ddlText(entry, 'an index expression'), expression: true };
+    if (typeof entry === 'function') {
+        return { column: entitySql(entry) };
     }
-    const { column, ...rest } = entry;
-    return column instanceof QueryRaw
-        ? { ...rest, column: ddlText(column, 'an index expression'), expression: true }
-        : { ...rest, column };
+    const { column } = entry;
+    return { ...entry, column: typeof column === 'function' ? entitySql(column) : column };
+}
+/** An index entry as the schema holds it, its expression rendered to text by `render`. */
+export function renderIndexColumn(entry, render) {
+    const { column } = entry;
+    return column instanceof QueryRaw ? { ...entry, column: render(column), expression: true } : { ...entry, column };
+}
+/** What an unnamed index's name is built from: each entry's column, or `expr<n>` for an expression, which has none. */
+export function indexNameParts(entries) {
+    return entries.map((entry, at) => (typeof entry.column === 'string' ? entry.column : `expr${at}`));
 }

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

@@ -83,7 +83,7 @@ export declare function findVectorSort<E>(sort: QuerySortMap<E> | 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.
  */
-export declare function findVectorIndex<E>(meta: EntityMeta<E>, key: string): EntityIndexMeta | undefined;
+export declare function findVectorIndex<E>(meta: EntityMeta<E>, key: string): EntityIndexMeta<E> | undefined;
 /**
  * Whether a `$where` filters by vector distance anywhere in its tree, `$and`/`$or`/`$not` included.
  * What tells Postgres that an HNSW scan needs to iterate rather than return one candidate list.

package/dist/util/dialect.util.js

@@ -222,7 +222,7 @@ export function hasVectorNear(where) {
     return Object.entries(where).some(([key, value]) => key === '$near' || hasVectorNear(value));
 }
 function indexCoversColumn(index, key) {
-    return index.columns.some((entry) => !(entry instanceof QueryRaw) && entry.column === key);
+    return index.columns.some((entry) => entry.column === key);
 }
 /** `satisfies` ties this to {@link JsonUpdateOp}, so renaming an operator breaks it at compile time. */
 const JSON_UPDATE_OPS = [
@@ -293,8 +293,7 @@ export function applyFilters(meta, whereMap, opts) {
         if (!active) {
             continue;
         }
-        const raw = filter.condition;
-        const condition = typeof raw === 'function' ? raw(context) : raw;
+        const condition = typeof filter.where === 'function' ? filter.where(context) : filter.where;
         if (condition === undefined) {
             const onMissing = filter.onMissing ?? (filter.security ? 'throw' : 'skip');
             if (onMissing === 'throw') {
@@ -444,7 +443,7 @@ export function textSearchFields(meta, search) {
     }
     const fulltext = (meta.indexes ?? []).filter((index) => index.type === 'fulltext');
     if (fulltext.length === 1) {
-        return fulltext[0].columns.map((entry) => entry.column);
+        return fulltext[0].columns.flatMap((entry) => (typeof entry.column === 'string' ? [entry.column] : []));
     }
     const name = entityName(meta);
     const declared = fulltext.length

package/dist/util/field.util.d.ts

@@ -32,7 +32,7 @@ export declare function isIntegerColumn(field: Pick<FieldOptions, 'type' | 'colu
  * Every read site asks this - the DDL skip, the projection, the `$where` and `ORDER BY` operands -
  * because an inlined field has no column to name, while a stored one is read like any other.
  */
-export declare function isInlinedExpression(field: FieldOptions): boolean;
+export declare function isInlinedExpression<F extends FieldOptions>(field: F): field is F & Required<Pick<F, 'computed'>>;
 /**
  * Whether the database supplies this field's value, so no insert or update may write it: a stored
  * computed column *is* a real column, read like one, but writing to it is an error on every engine.

package/dist/util/raw.d.ts

@@ -1,36 +1,38 @@
-import { QueryRaw, type QueryRawFn } from '../type/index.js';
+import { type EntitySql, type EntityWhere, type EntityWhereMeta, QueryRaw, type QueryRawFn, type RefMap, type Type } from '../type/index.js';
 /**
  * Create a raw SQL expression.
  *
  * As a tagged template the literal text is emitted as written and every interpolation is resolved by
  * what it is, so a value cannot become SQL whatever it holds:
  *
- * | Interpolated       | Becomes                 |
- * | :----------------- | :---------------------- |
- * | any value          | a bound parameter       |
- * | a {@link QueryRaw} | that fragment, in place |
+ * | Interpolated        | Becomes                                |
+ * | :------------------ | :------------------------------------- |
+ * | any value           | a bound parameter; in DDL, its literal |
+ * | a {@link ColumnRef} | its column, escaped and qualified      |
+ * | a {@link QueryRaw}  | that fragment, in place                |
  *
  * ```ts
- * raw`GREATEST(0, "creditsAllowance" - ${amount})`
- * raw`CONCAT(${col('firstName')}, ' ', ${col('lastName')})`
+ * const user = refs(User);
+ * raw`GREATEST(0, ${user.creditsAllowance} - ${amount})`
+ * raw`CONCAT(${user.firstName}, ' ', ${user.lastName})`
  * raw`LOG10(${points})`.as('score')
  * ```
  *
  * The callback form remains for SQL a template cannot express, such as a sub-query generated through
- * `dialect.find(...)`. See {@link col} for a context-aware column reference.
+ * `dialect.find(...)`.
  *
  * **⚠️ Security:** the tag is safe because it binds; a callback is not, since it emits whatever it
  * writes, so never build one from user input. Inside a callback, bind with `ctx.addValue()`.
  */
 export declare function raw(strings: TemplateStringsArray, ...values: readonly unknown[]): QueryRaw;
-export declare function raw(value: QueryRawFn, alias?: string): QueryRaw;
+export declare function raw(value: QueryRawFn): QueryRaw;
 /**
- * A column of the entity being queried, alias-qualified and escaped for the dialect. This is what a
- * template cannot know on its own: the alias is decided while the statement is built, not where the
- * expression is written.
- *
- * Takes the column name as it exists in the database, not the entity's field name: no entity metadata
- * is in scope here, so a naming strategy is not applied for you. `escapedPrefix` already carries its
- * trailing dot, which is the detail this exists to stop you getting wrong.
+ * The fields of `entity` as {@link ColumnRef}s, each rendering inside `raw` as its column: named the way
+ * the dialect names it, so the naming strategy and `@Field({ name })` apply, and qualified by the alias
+ * in scope. Metadata is read when a ref renders, so the map serves before the fields are registered.
  */
-export declare function col(column: string): QueryRaw;
+export declare function refs<E>(entity: Type<E>): RefMap<E>;
+/** SQL a definition writes, a callback's refs read off {@link MEMBER_REFS}. */
+export declare function entitySql<E>(sql: EntitySql<E>): QueryRaw;
+/** A definition's predicate, its callback resolved the way {@link entitySql} resolves one. */
+export declare function entityWhere<E>(where: EntityWhere<E>): EntityWhereMeta<E>;

package/dist/util/raw.js

@@ -1,13 +1,9 @@
-import { QueryRaw } from '../type/index.js';
+import { getMeta } from '../entity/metadata/definition.js';
+import { QueryRaw, } from '../type/index.js';
+import { isInlinedExpression } from './field.util.js';
 export function raw(value, ...rest) {
-    const [alias] = rest;
     if (!isTemplateStrings(value)) {
-        return new QueryRaw(value, typeof alias === 'string' ? alias : undefined);
-    }
-    if (!rest.length) {
-        // Nothing to bind, so this is the string form: keep it one, for the DDL paths that need to read
-        // the expression back as text (an index expression cannot carry a parameter).
-        return new QueryRaw(value[0]);
+        return new QueryRaw(value);
     }
     return new QueryRaw((opts) => {
         const { ctx } = opts;
@@ -24,16 +20,46 @@ export function raw(value, ...rest) {
     });
 }
 /**
- * A column of the entity being queried, alias-qualified and escaped for the dialect. This is what a
- * template cannot know on its own: the alias is decided while the statement is built, not where the
- * expression is written.
- *
- * Takes the column name as it exists in the database, not the entity's field name: no entity metadata
- * is in scope here, so a naming strategy is not applied for you. `escapedPrefix` already carries its
- * trailing dot, which is the detail this exists to stop you getting wrong.
+ * The fields of `entity` as {@link ColumnRef}s, each rendering inside `raw` as its column: named the way
+ * the dialect names it, so the naming strategy and `@Field({ name })` apply, and qualified by the alias
+ * in scope. Metadata is read when a ref renders, so the map serves before the fields are registered.
  */
-export function col(column) {
-    return new QueryRaw(({ escapedPrefix, dialect }) => escapedPrefix + dialect.escapeId(column, true));
+export function refs(entity) {
+    return new Proxy({}, { get: (_, key) => columnRef(entity, String(key)) });
+}
+/**
+ * The refs a definition's callback reads. A member decorator sees no class, so these name no entity and
+ * resolve against the one rendering them: a computed field's own, or the one whose schema is built.
+ */
+const MEMBER_REFS = new Proxy({}, { get: (_, key) => columnRef(undefined, String(key)) });
+/** SQL a definition writes, a callback's refs read off {@link MEMBER_REFS}. */
+export function entitySql(sql) {
+    return sql instanceof QueryRaw ? sql : sql(MEMBER_REFS);
+}
+/** A definition's predicate, its callback resolved the way {@link entitySql} resolves one. */
+export function entityWhere(where) {
+    return typeof where === 'function' ? where(MEMBER_REFS) : where;
+}
+/** One field as SQL, against its own entity or, read off a definition, the entity rendering it. */
+function columnRef(entity, key) {
+    return new QueryRaw((opts) => {
+        const owner = entity ?? opts.entity;
+        if (!owner) {
+            throw new TypeError(`'${key}' was read off a definition's refs, so it renders only inside its entity's SQL`);
+        }
+        renderColumn(getMeta(owner), key, { ...opts, entity: owner });
+    });
+}
+/** A field's column, or the expression an inlined computed one stands for, as a `$where` on it reads it. */
+function renderColumn(meta, key, opts) {
+    const field = meta.fields[key];
+    if (field && isInlinedExpression(field)) {
+        opts.ctx.append('(');
+        field.computed.render(opts);
+        opts.ctx.append(')');
+        return;
+    }
+    opts.ctx.append(opts.escapedPrefix + opts.dialect.escapeId(opts.dialect.columnOf(meta, key), true));
 }
 /** A tag call passes the frozen strings array, which carries its own `raw` counterpart. */
 function isTemplateStrings(value) {

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