uql-orm 0.80.0 → 0.82.0

package/dist/util/index.d.ts

@@ -7,6 +7,7 @@ export * from './ddlExpression.util.js';
 export * from './logger.js';
 export * from './object.util.js';
 export * from './raw.js';
+export * from './triggerWrite.js';
 export * from './rowKey.util.js';
 export * from './relationQuery.util.js';
 export * from './sql.util.js';

package/dist/util/index.js

@@ -7,6 +7,7 @@ export * from './ddlExpression.util.js';
 export * from './logger.js';
 export * from './object.util.js';
 export * from './raw.js';
+export * from './triggerWrite.js';
 export * from './rowKey.util.js';
 export * from './relationQuery.util.js';
 export * from './sql.util.js';

package/dist/util/logger.d.ts

@@ -3,8 +3,8 @@ import type { Logger, LoggingOptions } from '../type/logger.js';
  * Default implementation of the Logger interface using console methods.
  */
 export declare class DefaultLogger implements Logger {
-    logQuery(query: string, values?: unknown[], duration?: number): void;
-    logSlowQuery(query: string, values?: unknown[], duration?: number): void;
+    logQuery(query: string, values?: readonly unknown[], duration?: number): void;
+    logSlowQuery(query: string, values?: readonly unknown[], duration?: number): void;
     logWarn(message: string): void;
     logError(message: string, error?: unknown): void;
     logInfo(message: string): void;
@@ -37,7 +37,7 @@ export declare class LoggerWrapper implements Logger {
     constructor(options?: LoggingOptions, config?: LoggerWrapperConfig);
     /** Whether `logQuery` would ever actually surface bound values, given the configured levels/slowQuery/logValues. */
     willLogValues(): boolean;
-    logQuery(query: string, values?: unknown[], duration?: number): void;
+    logQuery(query: string, values?: readonly unknown[], duration?: number): void;
     logWarn(message: string): void;
     logError(message: string, error?: unknown): void;
     logInfo(message: string): void;

package/dist/util/object.util.js

@@ -1,8 +1,9 @@
+import { UqlUsageError } from './uqlError.js';
 export function throwPendingTransaction() {
-    throw TypeError('pending transaction');
+    throw new UqlUsageError('pending transaction');
 }
 export function throwNoPendingTransaction() {
-    throw TypeError('not a pending transaction');
+    throw new UqlUsageError('not a pending transaction');
 }
 export function clone(value) {
     if (typeof value !== 'object' || value === null) {

package/dist/util/raw.d.ts

@@ -1,4 +1,4 @@
-import { ColumnRef, type EntitySql, type EntityWhere, type EntityWhereMeta, QueryRaw, type QueryRawFn, type ComputedRefs, type RefMap, type TriggerRowName, type Type } from '../type/index.js';
+import { type EntitySql, type EntityWhere, type EntityWhereMeta, QueryRaw, type QueryRawFn, type ComputedRefs, type RefMap, type TriggerRowName, type Type } from '../type/index.js';
 /**
  * Raw SQL, where an interpolated value binds, a `refs` field renders its column, and a `raw` renders
  * in place: `raw`GREATEST(0, ${user.credits} - ${amount})``. A callback writes whatever it writes, so
@@ -27,10 +27,9 @@ 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>;
 /**
- * The fields of `E` as the row a trigger body reads them off, qualified by the side it names: `NEW."col"`
- * against the incoming row, `OLD."col"` against the outgoing one. Columns only, never a relation's
- * aggregate: that is a subquery, and a trigger fires on one row rather than over a table to correlate to.
+ * The fields of `entity` as the row a trigger body reads them off, qualified by the side it names:
+ * `NEW."col"` against the incoming row, `OLD."col"` against the outgoing one. Bound to the entity, as
+ * {@link refs} are, so each names its own column wherever it renders, a write to another table included.
+ * Columns only: a relation's aggregate is a subquery, and a trigger fires on one row, not over a table.
  */
-export declare function rowRefs<E>(qualifier: TriggerRowName): RefMap<E>;
-/** One field of a trigger's row, for code that names it by its key rather than off {@link rowRefs}. */
-export declare function rowColumn(qualifier: TriggerRowName, key: string): ColumnRef;
+export declare function rowRefs<E>(entity: Type<E>, qualifier: TriggerRowName): RefMap<E>;

package/dist/util/raw.js

@@ -2,6 +2,7 @@ import { getMeta } from '../entity/metadata/definition.js';
 import { ColumnRef, QueryRaw, RAW_TEXT, RelationAggregate, } from '../type/index.js';
 import { aggregateOf, isInlinedExpression } from './field.util.js';
 import { entityName, hasKeys } from './object.util.js';
+import { UqlUsageError } from './uqlError.js';
 export function raw(value, ...rest) {
     if (!isTemplateStrings(value)) {
         return new QueryRaw(value);
@@ -78,22 +79,19 @@ function rowsOf(q) {
 function relationAggregate(spec) {
     return new RelationAggregate(spec, (opts) => {
         if (!opts.entity) {
-            throw new TypeError(`'${spec.relation}' was read off a definition's refs, so it renders only inside its entity's SQL`);
+            throw new UqlUsageError(`'${spec.relation}' was read off a definition's refs, so it renders only inside its entity's SQL`);
         }
         opts.dialect.appendRelationAggregate(opts.ctx, opts.entity, spec, opts.prefix);
     });
 }
 /**
- * The fields of `E` as the row a trigger body reads them off, qualified by the side it names: `NEW."col"`
- * against the incoming row, `OLD."col"` against the outgoing one. Columns only, never a relation's
- * aggregate: that is a subquery, and a trigger fires on one row rather than over a table to correlate to.
+ * The fields of `entity` as the row a trigger body reads them off, qualified by the side it names:
+ * `NEW."col"` against the incoming row, `OLD."col"` against the outgoing one. Bound to the entity, as
+ * {@link refs} are, so each names its own column wherever it renders, a write to another table included.
+ * Columns only: a relation's aggregate is a subquery, and a trigger fires on one row, not over a table.
  */
-export function rowRefs(qualifier) {
-    return new Proxy({}, { get: (_, key) => rowColumn(qualifier, String(key)) });
-}
-/** One field of a trigger's row, for code that names it by its key rather than off {@link rowRefs}. */
-export function rowColumn(qualifier, key) {
-    return columnRef(undefined, key, qualifier);
+export function rowRefs(entity, qualifier) {
+    return new Proxy({}, { get: (_, key) => columnRef(entity, String(key), qualifier) });
 }
 /**
  * One field as SQL, against its own entity or, read off a definition, the entity rendering it. A
@@ -103,7 +101,7 @@ function columnRef(entity, key, qualifier) {
     return new ColumnRef(key, (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`);
+            throw new UqlUsageError(`'${key}' was read off a definition's refs, so it renders only inside its entity's SQL`);
         }
         renderColumn(getMeta(owner), key, { ...opts, entity: owner }, qualifier);
     });
@@ -119,7 +117,7 @@ function renderColumn(meta, key, opts, qualifier) {
     if (field && isInlinedExpression(field)) {
         // A relation aggregate is a subquery correlated to a table in scope, and a trigger's row is not one.
         if (qualifier !== undefined && aggregateOf(field)) {
-            throw new TypeError(`'${entityName(meta)}.${key}' reads a relation, which a trigger's row cannot: it fires on one row, ` +
+            throw new UqlUsageError(`'${entityName(meta)}.${key}' reads a relation, which a trigger's row cannot: it fires on one row, ` +
                 'with no table in scope to correlate a subquery to. Name the columns it is derived from instead.');
         }
         scope.ctx.append('(');

package/dist/util/sqlLiteral.js

@@ -1,6 +1,7 @@
 // SQL literal escaping for `Dialect.escape`: ANSI quote doubling, or MySQL's backslashes. UQL binds
 // values instead, so this is the hand-written-SQL hatch, and inline MySQL literals break under
 // `NO_BACKSLASH_ESCAPES` or a GBK-like charset: prefer bound parameters. Postgres arrays are separate.
+import { UqlUsageError } from './uqlError.js';
 const SINGLE_QUOTE = /'/g;
 /** Doubles every single quote in `val`, the ANSI escaping shared by string literals and JSON path keys. */
 export function escapeSingleQuotes(val) {
@@ -73,7 +74,7 @@ function createEscaper(escapeString) {
         if ('toSqlString' in value && typeof value.toSqlString === 'function') {
             return String(value.toSqlString());
         }
-        throw new TypeError('escapeSqlLiteral: plain objects are not supported; use bound parameters or JSON.stringify + a string column.');
+        throw new UqlUsageError('escapeSqlLiteral: plain objects are not supported; use bound parameters or JSON.stringify + a string column.');
     };
     const escapeValue = (value) => {
         if (value === undefined || value === null) {
@@ -92,7 +93,7 @@ function createEscaper(escapeString) {
                 return escapeObject(value);
             default:
                 // A symbol or a function, or a future JS type: none of them may silently become SQL.
-                throw new TypeError(`escapeSqlLiteral: unsupported value type '${typeof value}'; use bound parameters.`);
+                throw new UqlUsageError(`escapeSqlLiteral: unsupported value type '${typeof value}'; use bound parameters.`);
         }
     };
     return escapeValue;

package/dist/util/triggerWrite.d.ts

@@ -0,0 +1,15 @@
+import type { EntityPredicate, QueryRaw, Type, UpdatePayload, WritableKey, WriteRow } from '../type/index.js';
+/**
+ * A row inserted by a trigger's body, into any table: `insertInto(PostAudit, { postId: newRow.id })`.
+ * Each value is a literal or SQL, a row's ref most often, and every engine renders it, SQL Server's
+ * set-based trigger included, where it inserts one row for each the statement touched.
+ */
+export declare function insertInto<E extends object>(entity: Type<E>, row: WriteRow<E>): QueryRaw;
+/** The rows `q.$where` names updated by a trigger's body: `updateTable(Post, { $where: { id: newRow.postId } }, set)`. */
+export declare function updateTable<E extends object>(entity: Type<E>, q: {
+    readonly $where: EntityPredicate<E>;
+}, set: UpdatePayload<E, QueryRaw, WritableKey<E>, never>): QueryRaw;
+/** The rows `q.$where` names deleted by a trigger's body, outright: a soft delete is an `updateTable`. */
+export declare function deleteFrom<E extends object>(entity: Type<E>, q: {
+    readonly $where: EntityPredicate<E>;
+}): QueryRaw;

package/dist/util/triggerWrite.js

@@ -0,0 +1,20 @@
+import { raw } from './raw.js';
+/**
+ * A row inserted by a trigger's body, into any table: `insertInto(PostAudit, { postId: newRow.id })`.
+ * Each value is a literal or SQL, a row's ref most often, and every engine renders it, SQL Server's
+ * set-based trigger included, where it inserts one row for each the statement touched.
+ */
+export function insertInto(entity, row) {
+    return written({ kind: 'insert', entity, row });
+}
+/** The rows `q.$where` names updated by a trigger's body: `updateTable(Post, { $where: { id: newRow.postId } }, set)`. */
+export function updateTable(entity, q, set) {
+    return written({ kind: 'update', entity, set, where: q.$where });
+}
+/** The rows `q.$where` names deleted by a trigger's body, outright: a soft delete is an `updateTable`. */
+export function deleteFrom(entity, q) {
+    return written({ kind: 'delete', entity, where: q.$where });
+}
+function written(write) {
+    return raw(({ ctx, dialect, rows }) => dialect.triggerWrite(ctx, write, rows));
+}

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

package/skills/uql-orm/SKILL.md

@@ -84,7 +84,7 @@ export class Post {
   an update must carry the version it read (a compile error otherwise), and one against a row someone else moved on throws `UqlOptimisticLockError` (kind `optimisticLock`, HTTP 409). Its updates name one row by its id; save and upsert are refused.
 - `@Field({ computed })` is a value the database produces, on a `readonly` property: SQL over the row, ``(u) => raw`${u.first} || ' ' || ${u.last}` ``, or a relation aggregate, `(order) => order.items.count()`.
   `stored: true` makes the SQL a generated column; `stored: ['insert', 'update']` makes it a stamp, a trigger writing it on those events whoever writes the row (``computed: raw`CURRENT_TIMESTAMP` ``), where `onUpdate` covers only uql's own writes.
-- `@Trigger({ on: 'afterUpdate', of: (post) => [post.status], where: { $old: { status: 'draft' } }, run })` is a trigger the database fires; `where` holds a `$where` predicate per row it names, or SQL off the rows. `run` reads `{ newRow }` on insert, `{ newRow, oldRow }` on update, `{ oldRow }` on delete, and returns the engine's own SQL, one body for every engine or `{ postgres, mssql, ... }` where they differ (SQL Server fires per statement, reading `inserted`/`deleted` as tables, with no `before*` and no `where`). MongoDB has none, and refuses a write to an entity declaring one.
+- `@Trigger({ on: 'afterUpdate', of: (post) => [post.status], where: { $old: { status: 'draft' } }, run })` is a trigger the database fires (`defineEntity`'s `triggers` or `defineTrigger` without decorators); `where` holds a `$where` predicate per row it names, or SQL off the rows. `run` takes `(newRow, oldRow)`, each only where the event has it (no `oldRow` on insert, no `newRow` on delete), and returns the body: `insertInto(Audit, { postId: newRow.id })`, `updateTable(Audit, { $where: { postId: newRow.id } }, { status: newRow.status })` or `deleteFrom(Audit, { $where: { postId: oldRow.id } })`, typed by the entity written and rendered on every engine (no `onInsert`/`onUpdate` fills, so an insert names each field uql fills on insert unless its column has a `defaultValue`; `$where` reads the entity's own fields; no entity filters, security ones included, so a soft-delete entity is hard-deleted; an update or delete naming no rows is refused; no `$inc`/`$mul`/`$push` on SQL Server), several joined in one `raw`. Anything else is `raw` SQL over the refs, one body for every engine or `{ postgres, mssql, ... }` where they differ (SQL Server fires per statement, reading `inserted`/`deleted` as tables, with no `before*` and no `where`). MongoDB has none, and refuses a write to an entity declaring one.
 - `defineEntity` defines the same entity without decorators: https://uql-orm.dev/entities/imperative.md
 
 ## Queries
@@ -123,7 +123,7 @@ 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` naming no rows - no `$where`, no `$limit` - throw; `{ unfiltered: true }` means the whole table.
+- `updateMany` and `deleteMany` naming no rows - no `$where` holding a value (an `undefined` or an empty group holds none), 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`.
@@ -133,7 +133,7 @@ const users = await pool.findMany(User, {
 - `queryErrorKind(err)` names any failure the same on every engine - `uniqueViolation`, `foreignKeyViolation`,
   `notNullViolation`, `checkViolation`, `optimisticLock`, `retryable`, `usage` - so catch by kind rather than by
   a driver's code or an `instanceof`.
-- `raw()` embeds SQL anywhere a value or field goes; `pool.all(sql, values)` runs a raw `SELECT`.
+- `raw()` embeds SQL anywhere a value or field goes; `pool.all(sql, values)` runs a raw `SELECT`. A field read off `refs(Entity)` carries its type: on its own as a value it fits only a field of that type.
 
 ## Connections and transactions