uql-orm 0.83.0 → 0.84.0

package/dist/type/queryWhere.d.ts

@@ -138,35 +138,37 @@ export type QueryWhereFieldOperatorMap<T, Raw = QueryRaw> = {
      */
     $between?: readonly [ExpandScalar<T>, ExpandScalar<T>];
     /**
-     * whether a string begins with the given string (case sensitive).
+     * whether a string begins with the given text, taken literally (case sensitive).
      */
     $startsWith?: string;
     /**
-     * whether a string begins with the given string (case insensitive).
+     * whether a string begins with the given text, taken literally (case insensitive).
      */
     $istartsWith?: string;
     /**
-     * whether a string ends with the given string (case sensitive).
+     * whether a string ends with the given text, taken literally (case sensitive).
      */
     $endsWith?: string;
     /**
-     * whether a string ends with the given string (case insensitive).
+     * whether a string ends with the given text, taken literally (case insensitive).
      */
     $iendsWith?: string;
     /**
-     * whether a string is contained within the given string (case sensitive).
+     * whether a string contains the given text, taken literally (case sensitive).
      */
     $includes?: string;
     /**
-     * whether a string is contained within the given string (case insensitive).
+     * whether a string contains the given text, taken literally (case insensitive).
      */
     $iincludes?: string;
     /**
-     * whether a string fulfills the given pattern (case sensitive).
+     * whether a whole string matches the given pattern, the same on every engine: `%` is any run of
+     * characters, `_` any one, and `\` makes the next one literal; a last `\` with nothing after it to
+     * escape, `'John\'`, is refused (case sensitive).
      */
     $like?: string;
     /**
-     * whether a string fulfills the given pattern (case insensitive).
+     * whether a whole string matches the given pattern, as `$like` reads it (case insensitive).
      */
     $ilike?: string;
     /**

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

@@ -63,11 +63,8 @@ export declare function whereEach<E>(keys: readonly FieldKey<E>[], valueOf: (key
 export declare function whereAnyOf<E>(clauses: QueryWhereArray<E>): QueryWhere<E>;
 /** `q` selecting nothing but the id: what a write hands its backend's own read builder to settle the rows it will name. */
 export declare function idOnlyQuery<E>(meta: EntityMeta<E>, q: QuerySearch<E>): Query<E>;
-/**
- * The map form of a `$select` value, or `undefined` for the raw-array form. Centralizes the one
- * narrowing cast: `Array.isArray` does not narrow `readonly` arrays out of a union.
- */
-export declare function asSelectMap<E>(select: QuerySelectValue<E> | undefined): QuerySelect<E> | undefined;
+/** Whether `select` is the list form `raw()` fills, narrowing both ways, which `Array.isArray` does not for a `readonly` array. */
+export declare function isSelectList<E>(select: QuerySelectValue<E> | undefined): select is readonly QueryRaw[];
 export declare function normalizeScalarFieldSelection<E>(meta: EntityMeta<E>, select?: QuerySelect<E>, exclude?: QueryExclude<E>): FieldKey<E>[];
 /** Type guard: checks whether a sort value is a vector similarity search. */
 export declare function isVectorSearch(value: unknown): value is QueryVectorSearch;
@@ -122,10 +119,21 @@ export declare function assertWhere<E>(meta: EntityMeta<E>, where: unknown): voi
 export declare function withoutSoftDeleteFilter(filters: QueryOptions['filters']): QueryOptions['filters'];
 /**
  * `$where` with the entity's active filters merged in, against the ambient {@link UqlContext}. A convenience
- * filter yields to a `$where` on its key; a `security` one is always ANDed, and throws where its condition
- * resolves to nothing, unless `onMissing: 'skip'`.
+ * filter yields to a `$where` on its key; a `security` one is always ANDed, from {@link securityConditions}.
  */
 export declare function applyFilters<E>(meta: EntityMeta<E>, whereMap: QueryWhere<E>, opts?: QueryOptions): QueryWhere<E>;
+/**
+ * Each `security` filter's condition, by name, resolved against the ambient context. One resolving to
+ * `{}`, a trusted context's "no restriction", is left out. Reads AND these in; writes are held to them.
+ */
+export declare function securityConditions<E>(meta: EntityMeta<E>): [name: string, condition: QueryWhere<E>][];
+/**
+ * Holds written rows to the `security` filters, as {@link applyFilters} holds reads: an inserted row gets
+ * each field a condition names and it leaves out, and a row naming one must carry the condition's value.
+ * A condition other than field equalities refuses the write, having nothing a row can be checked against.
+ * See architecture/security-filter-writes.md.
+ */
+export declare function guardWrite<E, R extends EntityData<E> | UpdatePayload<E>>(meta: EntityMeta<E>, rows: readonly R[], write: 'insert' | 'update'): void;
 /**
  * Parsed entry from a `$group` map - either a raw group key or an aggregate function call.
  */

package/dist/util/dialect.util.js

@@ -1,10 +1,10 @@
-import { getContext, UqlSecurityError } from '../context/context.js';
+import { getContext } from '../context/context.js';
 import { soleIdOf } from '../entity/metadata/definition.js';
 import { QueryRaw, resolveAggregateOp, SOFT_DELETE_FILTER, } from '../type/index.js';
 import { DEFAULT_VECTOR_DISTANCE, VECTOR_INDEX_TYPES } from '../type/vector.js';
 import { defaultReadKeys, fieldKeys, isDatabaseWritten } from './field.util.js';
 import { entityName, getKeys, hasKeys, isOperatorObject, isScalarId, isRecord, isWhereMap, someKey, } from './object.util.js';
-import { UqlUsageError } from './uqlError.js';
+import { UqlSecurityError, UqlUsageError } from './uqlError.js';
 /** The keys of `payload` a write persists as columns. */
 export function filterFieldKeys(meta, payload, callbackKey) {
     return getKeys(payload).filter((key) => {
@@ -138,12 +138,9 @@ export function whereAnyOf(clauses) {
 export function idOnlyQuery(meta, q) {
     return { ...q, $select: keySet(meta.ids) };
 }
-/**
- * The map form of a `$select` value, or `undefined` for the raw-array form. Centralizes the one
- * narrowing cast: `Array.isArray` does not narrow `readonly` arrays out of a union.
- */
-export function asSelectMap(select) {
-    return Array.isArray(select) ? undefined : select;
+/** Whether `select` is the list form `raw()` fills, narrowing both ways, which `Array.isArray` does not for a `readonly` array. */
+export function isSelectList(select) {
+    return Array.isArray(select);
 }
 export function normalizeScalarFieldSelection(meta, select, exclude) {
     // A positive `$select` (the common case) wins outright and returns
@@ -298,59 +295,78 @@ export function withoutSoftDeleteFilter(filters) {
 }
 /**
  * `$where` with the entity's active filters merged in, against the ambient {@link UqlContext}. A convenience
- * filter yields to a `$where` on its key; a `security` one is always ANDed, and throws where its condition
- * resolves to nothing, unless `onMissing: 'skip'`.
+ * filter yields to a `$where` on its key; a `security` one is always ANDed, from {@link securityConditions}.
  */
 export function applyFilters(meta, whereMap, opts) {
     if (!meta.filters) {
         return whereMap;
     }
-    const context = getContext();
     const result = { ...whereMap };
-    const securityConditions = [];
-    for (const name of getKeys(meta.filters)) {
-        const filter = meta.filters[name];
-        let active;
-        if (filter.security) {
-            active = true;
-        }
-        else if (opts?.filters === false) {
-            active = false;
-        }
-        else {
-            active = opts?.filters?.[name] ?? filter.default !== false;
-        }
-        if (!active) {
+    for (const [name, filter] of Object.entries(meta.filters)) {
+        const active = opts?.filters !== false && (opts?.filters?.[name] ?? filter.default !== false);
+        if (filter.security || !active) {
             continue;
         }
-        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') {
-                throw new UqlSecurityError(`filter '${name}' on '${entityName(meta)}' could not resolve (missing context)`);
+        const condition = resolveFilter(meta, name, filter) ?? {};
+        for (const key of getKeys(condition)) {
+            if (result[key] === undefined) {
+                result[key] = condition[key];
             }
-            continue;
-        }
-        const conditionMap = condition;
-        if (!hasKeys(conditionMap)) {
-            continue; // resolved to "no restriction" (e.g. a trusted system context) - nothing to merge
         }
-        if (filter.security) {
-            securityConditions.push(conditionMap);
+    }
+    const security = securityConditions(meta).map(([, condition]) => condition);
+    if (security.length) {
+        const existing = result['$and'];
+        result['$and'] = existing ? [...existing, ...security] : security;
+    }
+    return result;
+}
+/**
+ * Each `security` filter's condition, by name, resolved against the ambient context. One resolving to
+ * `{}`, a trusted context's "no restriction", is left out. Reads AND these in; writes are held to them.
+ */
+export function securityConditions(meta) {
+    return Object.entries(meta.filters ?? {}).flatMap(([name, filter]) => {
+        const condition = filter.security ? resolveFilter(meta, name, filter) : undefined;
+        return condition && hasKeys(condition) ? [[name, condition]] : [];
+    });
+}
+/** A filter's condition, `undefined` where it resolves to nothing and may skip; throws where it may not. */
+function resolveFilter(meta, name, filter) {
+    const condition = typeof filter.where === 'function' ? filter.where(getContext()) : filter.where;
+    const onMissing = filter.onMissing ?? (filter.security ? 'throw' : 'skip');
+    if (condition === undefined && onMissing === 'throw') {
+        throw new UqlSecurityError(`filter '${name}' on '${entityName(meta)}' could not resolve (missing context)`);
+    }
+    return condition;
+}
+/**
+ * Holds written rows to the `security` filters, as {@link applyFilters} holds reads: an inserted row gets
+ * each field a condition names and it leaves out, and a row naming one must carry the condition's value.
+ * A condition other than field equalities refuses the write, having nothing a row can be checked against.
+ * See architecture/security-filter-writes.md.
+ */
+export function guardWrite(meta, rows, write) {
+    for (const [name, condition] of securityConditions(meta)) {
+        const values = condition;
+        const keys = fieldKeys(meta, () => true).filter((key) => Object.hasOwn(values, key));
+        const equalities = keys.length === getKeys(values).length;
+        if (!equalities || keys.some((key) => Array.isArray(values[key]) || isOperatorObject(values[key]))) {
+            throw new UqlSecurityError(`'${entityName(meta)}' security filter '${name}' is not field equalities, so no write can be checked against it`);
         }
-        else {
-            for (const key of getKeys(conditionMap)) {
-                if (result[key] === undefined) {
-                    result[key] = conditionMap[key];
+        for (const key of keys) {
+            for (const row of rows) {
+                if (row[key] === undefined) {
+                    if (write === 'insert') {
+                        row[key] = values[key];
+                    }
+                }
+                else if (row[key] !== values[key]) {
+                    throw new UqlSecurityError(`'${entityName(meta)}' row sets '${key}' outside security filter '${name}'`);
                 }
             }
         }
     }
-    if (securityConditions.length) {
-        const existing = result['$and'];
-        result['$and'] = existing ? [...existing, ...securityConditions] : securityConditions;
-    }
-    return result;
 }
 /**
  * The `$size` of a relation condition, `{ comments: { $size: { $gte: 2 } } }`, or `undefined` where it

package/dist/util/uqlError.d.ts

@@ -2,22 +2,33 @@
  * What a failed query ran into, named the same on every engine - what {@link queryErrorKind} answers
  * with, whether a driver raised the error or UQL did. `retryable` is a deadlock, a serialization
  * failure, a lock timeout or a busy database: the transaction can simply run again. `usage` is the
- * caller's own mistake, which running it again will not fix.
+ * caller's own mistake, which running it again will not fix. `security` is a `security` filter refusing.
  */
-export type QueryErrorKind = 'uniqueViolation' | 'foreignKeyViolation' | 'notNullViolation' | 'checkViolation' | 'optimisticLock' | 'retryable' | 'usage';
+export type QueryErrorKind = 'uniqueViolation' | 'foreignKeyViolation' | 'notNullViolation' | 'checkViolation' | 'optimisticLock' | 'retryable' | 'usage' | 'security';
+/** Every error UQL raises of its own: the kind `queryErrorKind` answers, and the status HTTP answers with. */
+export declare abstract class UqlError extends Error {
+    abstract readonly kind: QueryErrorKind;
+    abstract readonly status: number;
+}
 /**
  * Thrown where the caller used the API in a way no statement can carry out: an update payload with no
- * version, a `$lock` outside a transaction, a method with no version to match. A `TypeError` still,
- * since the call itself is wrong, but one carrying the `status` an HTTP transport answers with - the
+ * version, a `$lock` outside a transaction, a method with no version to match. A `400` over HTTP: the
  * request is malformed, not the server's failure, and an untyped client is exactly who reaches this.
  */
-export declare class UqlUsageError extends TypeError {
+export declare class UqlUsageError extends UqlError {
     name: string;
-    /** What `queryErrorKind` answers, so a caller branches on it rather than on the class. */
     readonly kind = "usage";
-    /** What an HTTP transport answers with. */
     readonly status = 400;
 }
+/**
+ * Thrown where a `security` filter refuses: its context is missing, or a write would leave a row outside it.
+ * Fails the statement closed.
+ */
+export declare class UqlSecurityError extends UqlError {
+    name: string;
+    readonly kind = "security";
+    readonly status = 403;
+}
 /** What a value is, for a refusal naming what `/http` handed over instead of what the types require. */
 export declare function kindOf(value: unknown): string;
 /**
@@ -31,7 +42,7 @@ export type UqlLockUsageError = UqlUsageError;
  * or it is gone. `expected` is what the payload carried, `actual` what the row holds now, `undefined`
  * where there is no row left.
  */
-export declare class UqlOptimisticLockError extends Error {
+export declare class UqlOptimisticLockError extends UqlError {
     readonly expected: unknown;
     readonly actual: unknown;
     name: string;

package/dist/util/uqlError.js

@@ -1,16 +1,25 @@
+/** Every error UQL raises of its own: the kind `queryErrorKind` answers, and the status HTTP answers with. */
+export class UqlError extends Error {
+}
 /**
  * Thrown where the caller used the API in a way no statement can carry out: an update payload with no
- * version, a `$lock` outside a transaction, a method with no version to match. A `TypeError` still,
- * since the call itself is wrong, but one carrying the `status` an HTTP transport answers with - the
+ * version, a `$lock` outside a transaction, a method with no version to match. A `400` over HTTP: the
  * request is malformed, not the server's failure, and an untyped client is exactly who reaches this.
  */
-export class UqlUsageError extends TypeError {
+export class UqlUsageError extends UqlError {
     name = 'UqlUsageError';
-    /** What `queryErrorKind` answers, so a caller branches on it rather than on the class. */
     kind = 'usage';
-    /** What an HTTP transport answers with. */
     status = 400;
 }
+/**
+ * Thrown where a `security` filter refuses: its context is missing, or a write would leave a row outside it.
+ * Fails the statement closed.
+ */
+export class UqlSecurityError extends UqlError {
+    name = 'UqlSecurityError';
+    kind = 'security';
+    status = 403;
+}
 /** What a value is, for a refusal naming what `/http` handed over instead of what the types require. */
 export function kindOf(value) {
     return value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value;
@@ -25,7 +34,7 @@ export const UqlLockUsageError = UqlUsageError;
  * or it is gone. `expected` is what the payload carried, `actual` what the row holds now, `undefined`
  * where there is no row left.
  */
-export class UqlOptimisticLockError extends Error {
+export class UqlOptimisticLockError extends UqlError {
     expected;
     actual;
     name = 'UqlOptimisticLockError';

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "uql-orm",
   "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.",
+  "description": "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.83.0",
+  "version": "0.84.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -56,7 +56,7 @@
     "README.md"
   ],
   "scripts": {
-    "prepack": "bun run build && bun run verify-dist.ts && cp ../../README.md . && cp -R ../../skills .",
+    "prepack": "bun run build && 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",

package/skills/uql-orm/SKILL.md

@@ -131,8 +131,8 @@ const users = await pool.findMany(User, {
   someone else holds) and needs an open transaction; SQLite, libSQL, Turso, D1 and MongoDB have no row lock and
   refuse it.
 - `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`.
+  `notNullViolation`, `checkViolation`, `optimisticLock`, `retryable`, `usage`, `security` - so catch by kind
+  rather than by a driver's code or an `instanceof`. Every error UQL raises itself is a `UqlError`.
 - `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

package/dist/context/securityError.d.ts

@@ -1,4 +0,0 @@
-/** Thrown when a `security` filter can't resolve its condition - fails the query closed. */
-export declare class UqlSecurityError extends Error {
-    name: string;
-}

package/dist/context/securityError.js

@@ -1,4 +0,0 @@
-/** Thrown when a `security` filter can't resolve its condition - fails the query closed. */
-export class UqlSecurityError extends Error {
-    name = 'UqlSecurityError';
-}