uql-orm 0.83.1 → 0.85.0

package/dist/http/query.js

@@ -7,10 +7,12 @@ import { RAW_VALUE } from '../type/queryRaw.js';
 import { getKeys, isRecord, isWhereMap } from '../util/object.util.js';
 // the error class alone, from its own leaf module: `queryError.ts` carries every driver's code map
 import { UqlUsageError } from '../util/uqlError.js';
+/** The flags a request carries beside its query: `hardDelete` on a delete, `count` on a `findMany`. */
+const WIRE_FLAGS = ['hardDelete', 'count'];
 /**
- * Keys accepted from the wire - query structure ({@link Query}) plus the `hardDelete`/`count` scalar
- * flags. Anything else (e.g. `filters`, `context`, `$entity`) is dropped so a remote client can't
- * bypass a security filter or inject ambient context - those are server-only. The `satisfies` ties
+ * Keys accepted from the wire - query structure ({@link Query}) plus the {@link WIRE_FLAGS}. Anything else
+ * (e.g. `filters`, `context`, `$entity`) is dropped so a remote client can't bypass a security filter or
+ * inject ambient context - those are server-only. The `satisfies` ties
  * every entry to a real query/option key, so a typo or a renamed option fails to compile.
  */
 const ALLOWED_QUERY_KEYS = new Set([
@@ -19,8 +21,7 @@ const ALLOWED_QUERY_KEYS = new Set([
     ...QUERY_NUMBER_CLAUSES,
     ...QUERY_ROOT_NUMBER_CLAUSES,
     ...QUERY_BOOLEAN_CLAUSES,
-    'hardDelete',
-    'count',
+    ...WIRE_FLAGS,
 ]);
 /**
  * Keys that mean something locally but that this transport can never honor, so they are rejected
@@ -53,7 +54,7 @@ export function parseQueryParams(params = {}) {
                 query[key] = JSON.parse(value);
             }
             catch {
-                throw Object.assign(new SyntaxError(`invalid JSON in '${key}'`), { status: 400 });
+                throw new UqlUsageError(`invalid JSON in '${key}'`);
             }
         }
     }
@@ -69,7 +70,7 @@ export function parseQueryParams(params = {}) {
             query[key] = Number(query[key]);
         }
     }
-    for (const key of QUERY_BOOLEAN_CLAUSES) {
+    for (const key of [...QUERY_BOOLEAN_CLAUSES, ...WIRE_FLAGS]) {
         if (query[key] !== undefined) {
             query[key] = query[key] === true || query[key] === 'true';
         }

package/dist/mongo/mongoDialect.js

@@ -32,6 +32,7 @@ export const mongoDialectFeatures = {
     serverSideCursors: false,
     correlatedWrites: false,
     rowLocks: false, // its concurrency control is the transaction plus atomic document updates
+    transactions: true,
 };
 /** What `toWireId` converts: the hex spelling of an `ObjectId`, and nothing looser. */
 const HEX_24 = /^[0-9a-f]{24}$/i;

package/dist/mssql/mssqlDialect.js

@@ -31,6 +31,7 @@ const MSSQL_FEATURES = {
     serverSideCursors: false,
     correlatedWrites: true,
     rowLocks: { of: true, withWindow: true, placement: 'tableHint' },
+    transactions: true,
     nullsOrdering: 'case',
     textScoreIndexes: false,
     orderedUpsertReturning: false,

package/dist/querier/abstractQuerier.d.ts

@@ -88,6 +88,8 @@ export declare abstract class AbstractQuerier implements Querier {
      * same rows the statement wrote.
      */
     insertMany<E extends object>(entity: Type<E>, payload: readonly EntityWrite<E>[]): Promise<(WrittenId<E> | undefined)[]>;
+    /** Fills and guards `rows`, then writes them: an insert, and the insert half of a guarded upsert. */
+    private insertRows;
     /** Writes `rows`, and onto each one the key the database generated for it, where it can tell. */
     protected abstract internalInsertMany<E extends object>(entity: Type<E>, rows: EntityData<E>[]): Promise<void>;
     updateOneById<E extends object>(entity: Type<E>, id: EntityId<E>, payload: UpdateWrite<E>, opts?: QueryOptions): Promise<number>;
@@ -126,6 +128,12 @@ export declare abstract class AbstractQuerier implements Querier {
     /** Fires `beforeUpsert`/`afterUpsert`: which branch a row takes is the database's to decide, so neither the insert's nor the update's pair fits. */
     upsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityWrite<E>): Promise<QueryUpsertOneResult<E>>;
     upsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: readonly EntityWrite<E>[]): Promise<QueryUpsertManyResult<E>>;
+    /**
+     * An upsert on an entity a `security` filter guards. `ON CONFLICT` updates the conflicting row whoever
+     * it belongs to, so the rows the conflict names are read through the filter: those found update, the
+     * rest insert, where another tenant's row fails on its key. See architecture/security-filter-writes.md.
+     */
+    private guardedUpsert;
     protected abstract internalUpsertOne<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>): Promise<QueryUpdateResult>;
     protected abstract internalUpsertMany<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: EntityData<E>[]): Promise<QueryUpdateResult>;
     deleteOneById<E extends object>(entity: Type<E>, id: EntityId<E>, opts?: QueryOptions): Promise<number>;
@@ -171,9 +179,9 @@ export declare abstract class AbstractQuerier implements Querier {
      */
     private emitLoaded;
     /**
-     * The ids of `rows`, read back by the columns an upsert matched them on, for a statement that could
-     * not report them in payload order. A row that no read row matches, or that two do, keeps
-     * `undefined`: a missing id is honest where a guessed one is not.
+     * The ids of `rows`, read through the filters by the columns an upsert matches them on: after a
+     * statement that could not report them in payload order, or before a guarded upsert. A row that no
+     * read row matches, or that two do, keeps `undefined`: a missing id is honest where a guessed one is not.
      */
     protected idsByConflict<E extends object>(entity: Type<E>, conflictPaths: QueryConflictPaths<E>, rows: EntityData<E>[]): Promise<(PrimaryKey | undefined)[]>;
     /**

package/dist/querier/abstractQuerier.js

@@ -1,7 +1,7 @@
 import { assertSoleId, getMeta, idOf, namesKey, relationOf } from '../entity/index.js';
 import { namesRows } from '../dialect/operators.js';
 import { parseQueryLock } from '../type/index.js';
-import { cascadesOnDelete, childrenOf, clone, entityName, fillOnFields, filterFieldKeys, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, idOnlyQuery, keySet, isPagedQuery, isScalarId, LoggerWrapper, parentJoins, queryLoggerFor, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, someKey, targetKeyColumns, whereAnyOf, whereEach, whereIds, whereWith, withoutSoftDeleteFilter, } from '../util/index.js';
+import { cascadesOnDelete, childrenOf, clone, entityName, fillOnFields, filterFieldKeys, filterPersistableRelationKeys, forEachRequestedRelation, getKeys, getRelationRequestSummary, guardWrite, idOnlyQuery, keySet, isPagedQuery, isScalarId, LoggerWrapper, parentJoins, queryLoggerFor, parseRelationAtKey, parseRelationQueryValue, rowKey, runHooks, securityConditions, someKey, targetKeyColumns, whereAnyOf, whereEach, whereIds, whereWith, withoutSoftDeleteFilter, } from '../util/index.js';
 import { UqlOptimisticLockError, UqlUsageError } from '../util/uqlError.js';
 import { enrichError } from './queryError.js';
 /**
@@ -240,11 +240,17 @@ export class AbstractQuerier {
         }
         const meta = getMeta(entity);
         return this.hooked(entity, 'Insert', payload, async (rows) => {
-            fillOnFields(meta, rows, 'onInsert');
-            await this.internalInsertMany(entity, rows);
+            await this.insertRows(entity, rows);
             return writtenIds(meta, rows);
         });
     }
+    /** Fills and guards `rows`, then writes them: an insert, and the insert half of a guarded upsert. */
+    async insertRows(entity, rows) {
+        const meta = getMeta(entity);
+        fillOnFields(meta, rows, 'onInsert');
+        guardWrite(meta, rows, 'insert');
+        await this.internalInsertMany(entity, rows);
+    }
     async updateOneById(entity, id, payload, opts) {
         assertIdValue(entity, id);
         return this.updateMany(entity, { $where: whereIds(getMeta(entity), id) }, payload, opts);
@@ -261,6 +267,7 @@ export class AbstractQuerier {
     async updateRows(entity, q, row, opts, lockKey) {
         const meta = getMeta(entity);
         fillOnFields(meta, [row], 'onUpdate');
+        guardWrite(meta, [row], 'update');
         const relKeys = filterPersistableRelationKeys(meta, row, 'persist');
         const settles = !!relKeys.length || this.settlesWrite(entity, q);
         if (lockKey) {
@@ -345,7 +352,9 @@ export class AbstractQuerier {
         const meta = getMeta(entity);
         assertUnversioned(meta, "'upsertOne'");
         return this.hooked(entity, 'Upsert', [payload], async (rows) => {
-            const { ids, changes, created } = await this.internalUpsertOne(entity, conflictPaths, rows[0]);
+            const { ids, changes, created } = securityConditions(meta).length
+                ? await this.guardedUpsert(entity, conflictPaths, rows)
+                : await this.internalUpsertOne(entity, conflictPaths, rows[0]);
             adoptReportedIds(meta, rows, ids);
             const [id] = writtenIds(meta, rows);
             return { id, changes, created };
@@ -355,11 +364,49 @@ export class AbstractQuerier {
         const meta = getMeta(entity);
         assertUnversioned(meta, "'upsertMany'");
         return this.hooked(entity, 'Upsert', payload, async (rows) => {
-            const { ids, changes } = await this.internalUpsertMany(entity, conflictPaths, rows);
+            const { ids, changes } = securityConditions(meta).length
+                ? await this.guardedUpsert(entity, conflictPaths, rows)
+                : await this.internalUpsertMany(entity, conflictPaths, rows);
             adoptReportedIds(meta, rows, ids);
             return { ids: writtenIds(meta, rows), changes };
         });
     }
+    /**
+     * An upsert on an entity a `security` filter guards. `ON CONFLICT` updates the conflicting row whoever
+     * it belongs to, so the rows the conflict names are read through the filter: those found update, the
+     * rest insert, where another tenant's row fails on its key. See architecture/security-filter-writes.md.
+     */
+    async guardedUpsert(entity, conflictPaths, rows) {
+        guardWrite(getMeta(entity), rows, 'insert');
+        if (!rows.length) {
+            return { changes: 0 };
+        }
+        const keys = getKeys(conflictPaths);
+        const write = async () => {
+            const ids = await this.idsByConflict(entity, conflictPaths, rows);
+            let changes = 0;
+            for (const [index, row] of rows.entries()) {
+                if (ids[index] !== undefined) {
+                    // What `ON CONFLICT` would assign: the row, less the columns it matched on.
+                    const payload = { ...row };
+                    for (const key of keys) {
+                        delete payload[key];
+                    }
+                    changes += await this.updateColumns(entity, { $where: whereEach(keys, (key) => row[key]) }, payload, undefined, 0);
+                }
+            }
+            const inserts = rows.filter((_, index) => ids[index] === undefined);
+            if (inserts.length) {
+                await this.insertRows(entity, inserts);
+                changes += inserts.length;
+            }
+            const created = rows.length === 1 ? ids[0] === undefined : undefined;
+            // A found row's key is adopted by the caller; an inserted one carries the key its insert wrote.
+            return { changes, created, ids };
+        };
+        // One row is one statement after the read, so it needs no transaction of its own.
+        return rows.length === 1 ? write() : this.transaction(write);
+    }
     async deleteOneById(entity, id, opts) {
         assertIdValue(entity, id);
         return this.deleteMany(entity, { $where: whereIds(getMeta(entity), id) }, opts);
@@ -571,9 +618,9 @@ export class AbstractQuerier {
         await this.emitHook(entity, 'afterLoad', rows);
     }
     /**
-     * The ids of `rows`, read back by the columns an upsert matched them on, for a statement that could
-     * not report them in payload order. A row that no read row matches, or that two do, keeps
-     * `undefined`: a missing id is honest where a guessed one is not.
+     * The ids of `rows`, read through the filters by the columns an upsert matches them on: after a
+     * statement that could not report them in payload order, or before a guarded upsert. A row that no
+     * read row matches, or that two do, keeps `undefined`: a missing id is honest where a guessed one is not.
      */
     async idsByConflict(entity, conflictPaths, rows) {
         const meta = getMeta(entity);

package/dist/querier/queryError.js

@@ -1,4 +1,4 @@
-import { UqlOptimisticLockError, UqlUsageError } from '../util/uqlError.js';
+import { UqlError } from '../util/uqlError.js';
 /** Postgres, CockroachDB, PGlite and Neon in `code`; Bun SQL in `errno`. */
 const SQLSTATE_KINDS = new Map([
     ['23505', 'uniqueViolation'],
@@ -53,7 +53,7 @@ export function queryErrorKind(err) {
     if (typeof err !== 'object' || err === null) {
         return undefined;
     }
-    if (err instanceof UqlOptimisticLockError || err instanceof UqlUsageError) {
+    if (err instanceof UqlError) {
         return err.kind;
     }
     const { code, errno, number, errorLabels, message } = err;

package/dist/sqlite/sqliteDialect.js

@@ -34,6 +34,7 @@ export const SQLITE_FEATURES = {
     serverSideCursors: false,
     correlatedWrites: true,
     rowLocks: false,
+    transactions: true,
     nullsOrdering: 'clause',
     textScoreIndexes: false,
     orderedUpsertReturning: true,

package/dist/type/dialect.d.ts

@@ -141,6 +141,11 @@ export interface DialectFeatures {
      * value rather than a flag each, since the details mean nothing without a lock.
      */
     readonly rowLocks: RowLockFeatures | false;
+    /**
+     * Whether the engine runs a transaction across statements: false on D1, which refuses one, so what
+     * would open one can run its steps in order instead. MongoDB has them as a replica set alone.
+     */
+    readonly transactions: boolean;
 }
 /** How a dialect spells a row lock, once {@link DialectFeatures.rowLocks} says it has one. */
 export interface RowLockFeatures {

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

@@ -119,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) => {
@@ -295,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.1",
+  "version": "0.85.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -35,6 +35,7 @@
     "./http": "./dist/http/index.js",
     "./express": "./dist/express/index.js",
     "./nestjs": "./dist/nestjs/index.js",
+    "./betterAuth": "./dist/betterAuth/index.js",
     "./browser": {
       "types": "./dist/browser/index.d.ts",
       "import": "./dist/browser/index.js",
@@ -56,7 +57,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",
@@ -71,6 +72,7 @@
     "@nestjs/core": ">=10.0.0",
     "@tursodatabase/database": ">=0.7.0",
     "@tursodatabase/serverless": ">=1.3.0",
+    "better-auth": ">=1.7.0",
     "better-sqlite3": ">=9.0.0",
     "express": ">=5.0.0",
     "mariadb": ">=3.0.0",
@@ -103,6 +105,9 @@
     "@tursodatabase/serverless": {
       "optional": true
     },
+    "better-auth": {
+      "optional": true
+    },
     "better-sqlite3": {
       "optional": true
     },
@@ -132,6 +137,7 @@
     }
   },
   "devDependencies": {
+    "@better-auth/test-utils": "^1.7.6",
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@libsql/client": "^0.18.0",
@@ -146,6 +152,7 @@
     "@types/mssql": "^12.3.0",
     "@types/pg": "^8.23.1",
     "@types/ws": "^8.18.1",
+    "better-auth": "^1.7.6",
     "better-sqlite3": "^13.0.3",
     "express": "^5.2.1",
     "mariadb": "^3.5.4",

package/skills/uql-orm/SKILL.md

@@ -119,7 +119,8 @@ const users = await pool.findMany(User, {
 - A result is narrowed to what the query selected and populated: reading an unselected field is a compile error.
   Name that shape with `QueryFindResult<User, 'id' | 'email'>` rather than widening the query.
 - `$populate` loads relations in the same statement. Nothing is lazy: a relation not populated is not there.
-- A query is plain data, so it can be built dynamically, stored, or sent from a browser to `uql-orm/http`.
+- A query is plain data, so it can be built dynamically, stored, or sent from a browser to `uql-orm/http`,
+  whose handler serves only the entities its required `include` names.
 - 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.
@@ -131,8 +132,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
@@ -157,6 +158,13 @@ transaction. A querier from `pool.getQuerier()` is yours to release: bind it wit
 writes entity classes from an existing database; `drift:check` fails when the database no longer matches.
 Triggers are part of the diff: uql installs its own under `_uql_`-prefixed names and never touches another.
 
+## Better Auth
+
+`betterAuth({ ...authOptions, database: uqlAdapter(pool) })`, from `uql-orm/betterAuth`, runs Better Auth on any
+pool; `...authEntities(authOptions)` in the config's `entities` has `uql-migrate` create its tables. Keep
+`authOptions` (plugins, table and field names, `rateLimit.storage`) in a module of its own, since the config imports
+it, and never put those entities in an HTTP handler's `include`: a session row holds its token.
+
 ## Where to read more
 
 - Operators, per-dialect SQL: https://uql-orm.dev/querying/comparison-operators.md
@@ -165,4 +173,5 @@ Triggers are part of the diff: uql installs its own under `_uql_`-prefixed names
 - Triggers: https://uql-orm.dev/entities/triggers.md
 - Every method's signature: https://uql-orm.dev/querying/methods.md
 - Coming from Prisma, Drizzle, TypeORM or MikroORM: https://uql-orm.dev/switching-to-uql.md
+- Better Auth: https://uql-orm.dev/better-auth.md
 - Breaking changes by version: https://uql-orm.dev/upgrade-guide.md

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';
-}