uql-orm 0.83.0 → 0.84.0

package/dist/http/handler.d.ts

@@ -1,5 +1,6 @@
 import type { EntityMeta, QuerierPool, Query, RequestSuccessResponse, Type, UqlContext } from '../type/index.js';
 import { type CrudOperation, type HttpMethod } from './contract.js';
+import { type WireFlags } from './query.js';
 /**
  * Framework-normalized request: adapters (express, fetch, ...) reduce their native
  * request to this shape and get back a status + JSON body.
@@ -30,7 +31,7 @@ export type HookContext<E extends object, Ctx = unknown> = {
     readonly op: CrudOperation;
     readonly method: HttpMethod;
     /** The parsed query, to reshape in place. Scope rows with a `security` filter instead, which a client cannot override. */
-    query: Query<E>;
+    query: Query<E> & WireFlags;
     /**
      * request payload - reassignable for sanitization or field injection.
      */

package/dist/http/handler.js

@@ -2,7 +2,7 @@ import { withContext } from '../context/context.js';
 import { getEntities, getMeta, soleIdOf } from '../entity/index.js';
 import { whereIds, whereWith } from '../util/dialect.util.js';
 import { UqlUsageError } from '../util/uqlError.js';
-import { entityPath, matchRoute } from './contract.js';
+import { CRUD_ROUTES, entityPath, matchRoute, } from './contract.js';
 import { parseQueryParams } from './query.js';
 /** `Company (crm.Company)`: the class, and the table it maps, which is what tells two apart. */
 function tableOf(entity) {
@@ -29,6 +29,7 @@ export function createRequestHandler(opts) {
             "pass an 'entityPath', or pass only one of them in 'include'.");
     }
     const entityByPath = new Map([...byPath].map(([path, [entity]]) => [path, entity]));
+    const served = new Set(entities);
     return (req) => {
         const entity = entityByPath.get(req.entityPath);
         if (!entity) {
@@ -43,121 +44,113 @@ export function createRequestHandler(opts) {
     async function run(entity, { op, method, id }, req) {
         const meta = getMeta(entity);
         // QUERY (RFC 10008) carries the JSON query in the body instead of the query string
-        const rawQuery = method === 'QUERY' ? req.body : req.query;
-        const hookCtx = {
-            meta,
-            op,
-            method,
-            query: parseQueryParams(rawQuery),
-            body: req.body,
-            context: req.context,
-        };
+        const query = parseQueryParams(method === 'QUERY' ? req.body : req.query);
+        const { method: verb } = CRUD_ROUTES[op];
+        // What the client sent, before the hooks: a relation a hook adds is the server's own to add.
+        assertServed(meta, query, served);
+        assertServed(meta, req.body, served);
+        const hookCtx = { meta, op, method, query, body: req.body, context: req.context };
         const appContext = (await getContext?.(req.context)) ?? {};
-        // Resolved where the statement runs, not up front: a hook that aborts the request must not reach
-        // the pool at all, and picking one per request may cost a lookup this request will never use.
-        const resolvePool = async () => (typeof pool === 'function' ? pool(req.context, appContext) : pool);
-        /** Read paths: the pool acquires and releases; nothing here owns a connection. */
-        const withQuerier = async (fn) => (await resolvePool()).withQuerier(fn);
-        /** Write paths: one transaction per request, so a cascade that fails takes its parent with it. */
-        const withTransaction = async (fn) => (await resolvePool()).transaction(fn);
         // Scope the whole request (hooks + querier + relation/cascade queries) to the resolved context.
         return withContext(appContext, async () => {
             await pre?.(hookCtx);
-            if (method === 'POST' || method === 'PUT' || method === 'PATCH') {
-                await preSave?.(hookCtx);
-            }
-            else {
-                await preFilter?.(hookCtx);
-            }
-            const resp = await dispatch();
-            if (post) {
-                await post(hookCtx, resp.body);
-            }
-            return resp;
+            await (verb === 'GET' || verb === 'DELETE' ? preFilter : preSave)?.(hookCtx);
+            // Resolved after the hooks: one that aborts the request must not reach the pool at all.
+            const resolved = typeof pool === 'function' ? await pool(req.context, appContext) : pool;
+            // A read acquires and releases; a write is one transaction, so a failing cascade takes its parent with it.
+            const envelope = await (verb === 'GET' ? resolved.withQuerier(execute) : resolved.transaction(execute));
+            await post?.(hookCtx, envelope);
+            return { status: 200, body: envelope };
         });
-        function dispatch() {
-            // read post-hooks so both in-place mutation and reassignment of hookCtx.query apply
-            const query = hookCtx.query;
-            const flags = query;
-            const hardDelete = flags.hardDelete === 'true' || flags.hardDelete === true;
+        /** Runs `op`, reading the query and body after the hooks, which may have reshaped or reassigned them. */
+        async function execute(querier) {
+            const { query, body } = hookCtx;
+            const { hardDelete = false, count: counts } = query;
+            const scoped = id === undefined
+                ? query
+                : { ...query, $where: whereWith(soleIdOf(meta, 'the HTTP handler'), id, query.$where) };
             switch (op) {
                 case 'findOne':
-                    return withQuerier(async (querier) => {
-                        const data = await querier.findOne(entity, query);
-                        return ok({ data, count: data ? 1 : 0 });
-                    });
-                case 'count':
-                    return withQuerier(async (querier) => {
-                        const count = await querier.count(entity, query);
-                        return ok({ data: count, count });
-                    });
-                case 'findOneById':
-                    return withQuerier(async (querier) => {
-                        const data = await querier.findOne(entity, buildIdQuery(meta, id, query));
-                        return ok({ data, count: data ? 1 : 0 });
-                    });
-                case 'findMany':
-                    return withQuerier(async (querier) => {
-                        const findManyPromise = querier.findMany(entity, query);
-                        const countPromise = flags.count ? querier.count(entity, query) : undefined;
-                        const [data, count] = await Promise.all([findManyPromise, countPromise]);
-                        return ok({ data, count });
-                    });
+                case 'findOneById': {
+                    const data = await querier.findOne(entity, scoped);
+                    return { data, count: data ? 1 : 0 };
+                }
+                case 'count': {
+                    const count = await querier.count(entity, query);
+                    return { data: count, count };
+                }
+                case 'findMany': {
+                    const [data, count] = await Promise.all([
+                        querier.findMany(entity, query),
+                        counts ? querier.count(entity, query) : undefined,
+                    ]);
+                    return { data, count };
+                }
                 case 'insertOne':
-                    return withTransaction(async (querier) => {
-                        const data = await querier.insertOne(entity, hookCtx.body);
-                        return ok({ data, count: 1 });
-                    });
-                case 'insertMany':
-                    return withTransaction(async (querier) => {
-                        const data = await querier.insertMany(entity, hookCtx.body);
-                        return ok({ data, count: data.length });
-                    });
+                    return { data: await querier.insertOne(entity, body), count: 1 };
                 case 'saveOne':
-                    return withTransaction(async (querier) => {
-                        const data = await querier.saveOne(entity, hookCtx.body);
-                        return ok({ data, count: 1 });
-                    });
-                case 'saveMany':
-                    return withTransaction(async (querier) => {
-                        const data = await querier.saveMany(entity, hookCtx.body);
-                        return ok({ data, count: data.length });
-                    });
-                case 'updateOneById':
-                    return withTransaction(async (querier) => {
-                        const count = await querier.updateMany(entity, buildIdQuery(meta, id, query), hookCtx.body);
-                        return ok({ data: id, count });
-                    });
+                    return { data: await querier.saveOne(entity, body), count: 1 };
+                case 'insertMany': {
+                    const data = await querier.insertMany(entity, body);
+                    return { data, count: data.length };
+                }
+                case 'saveMany': {
+                    const data = await querier.saveMany(entity, body);
+                    return { data, count: data.length };
+                }
                 case 'updateMany':
-                    return withTransaction(async (querier) => {
-                        const count = await querier.updateMany(entity, query, hookCtx.body);
-                        return ok({ data: count, count });
-                    });
-                case 'deleteOneById':
-                    return withTransaction(async (querier) => {
-                        const count = await querier.deleteMany(entity, buildIdQuery(meta, id, query), { hardDelete });
-                        return ok({ data: id, count });
-                    });
-                case 'deleteMany':
-                    return withTransaction(async (querier) => {
-                        const founds = await querier.findMany(entity, query);
-                        let ids = [];
-                        let count = 0;
-                        if (founds.length) {
-                            const idKey = soleIdOf(meta, 'the HTTP handler');
-                            ids = founds.map((found) => found[idKey]);
-                            count = await querier.deleteMany(entity, { $where: whereIds(meta, ids) }, { hardDelete });
-                        }
-                        return ok({ data: ids, count });
-                    });
+                case 'updateOneById': {
+                    const count = await querier.updateMany(entity, scoped, body);
+                    return { data: id ?? count, count };
+                }
+                case 'deleteOneById': {
+                    const count = await querier.deleteMany(entity, scoped, { hardDelete });
+                    return { data: id, count };
+                }
+                case 'deleteMany': {
+                    const founds = await querier.findMany(entity, query);
+                    if (!founds.length) {
+                        return { data: [], count: 0 };
+                    }
+                    const idKey = soleIdOf(meta, 'the HTTP handler');
+                    const ids = founds.map((found) => found[idKey]);
+                    return {
+                        data: ids,
+                        count: await querier.deleteMany(entity, { $where: whereIds(meta, ids) }, { hardDelete }),
+                    };
+                }
             }
         }
     }
 }
-function ok(body) {
-    return { status: 200, body };
-}
-function buildIdQuery(meta, id, query) {
-    query.$where = whereWith(soleIdOf(meta, 'the HTTP handler'), id, query.$where);
-    return query;
+/**
+ * Refuses a relation, at any depth of what a client sent, leading to an entity this handler does not
+ * serve: `include` fences the routes, and this the rows a `$populate`, a filter, a sort, a tally or a
+ * written row would otherwise reach through them. Every `$` clause holds keys of the entity it sits on.
+ */
+function assertServed(meta, sent, served, path = '') {
+    if (Array.isArray(sent)) {
+        for (const item of sent) {
+            assertServed(meta, item, served, path);
+        }
+        return;
+    }
+    if (typeof sent !== 'object' || sent === null) {
+        return;
+    }
+    const relations = meta.relations;
+    for (const [key, value] of Object.entries(sent)) {
+        const relation = Object.hasOwn(relations, key) ? relations[key] : undefined;
+        if (relation) {
+            const target = relation.entity();
+            const at = path ? `${path}.${key}` : key;
+            if (!served.has(target)) {
+                throw new UqlUsageError(`'${at}' reaches '${target.name}', which this handler does not serve`);
+            }
+            assertServed(getMeta(target), value, served, at);
+        }
+        else if (key.startsWith('$')) {
+            assertServed(meta, value, served, path);
+        }
+    }
 }

package/dist/http/query.d.ts

@@ -1,9 +1,15 @@
 import type { WireQuery } from '../type/index.js';
+/** The flags a request carries beside its query: `hardDelete` on a delete, `count` on a `findMany`. */
+declare const WIRE_FLAGS: ["hardDelete", "count"];
+/** {@link WIRE_FLAGS} as the booleans {@link parseQueryParams} decodes them to, where a hook may also set them. */
+export type WireFlags = {
+    readonly [K in (typeof WIRE_FLAGS)[number]]?: boolean;
+};
 /**
- * Parse raw query-string entries (with JSON-stringified values) into a UQL query object.
- * Symmetric counterpart of {@link stringifyQuery}. Only {@link ALLOWED_QUERY_KEYS} are honored.
+ * Parse raw query-string entries (with JSON-stringified values), or a `QUERY` body, into a UQL query
+ * object. Symmetric counterpart of {@link stringifyQuery}. Only {@link ALLOWED_QUERY_KEYS} are honored.
  */
-export declare function parseQueryParams<E = unknown>(params?: Record<string, unknown>): WireQuery<E>;
+export declare function parseQueryParams<E = unknown>(params?: unknown): WireQuery<E> & WireFlags;
 /**
  * Serialize a UQL query object into a percent-encoded query string where object values
  * are JSON-stringified. Symmetric counterpart of {@link parseQueryParams}.
@@ -17,3 +23,4 @@ export declare function stringifyQuery(query?: Record<string, unknown>): string;
  * hits where the client's types already refuse a fragment.
  */
 export declare function wireJson(value: unknown): string;
+export {};

package/dist/http/query.js

@@ -4,13 +4,15 @@ import { QUERY_BOOLEAN_CLAUSES, QUERY_NUMBER_CLAUSES, QUERY_OBJECT_CLAUSES, QUER
 // with it, in the browser bundle, which is on a size budget
 import { RAW_VALUE } from '../type/queryRaw.js';
 // the specific util module, not the barrel, so the browser bundle does not pull in entity metadata
-import { getKeys, isWhereMap } from '../util/object.util.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
@@ -30,10 +31,13 @@ const ALLOWED_QUERY_KEYS = new Set([
  */
 const REJECTED_QUERY_KEYS = new Set(['$lock']);
 /**
- * Parse raw query-string entries (with JSON-stringified values) into a UQL query object.
- * Symmetric counterpart of {@link stringifyQuery}. Only {@link ALLOWED_QUERY_KEYS} are honored.
+ * Parse raw query-string entries (with JSON-stringified values), or a `QUERY` body, into a UQL query
+ * object. Symmetric counterpart of {@link stringifyQuery}. Only {@link ALLOWED_QUERY_KEYS} are honored.
  */
 export function parseQueryParams(params = {}) {
+    if (!isRecord(params)) {
+        throw new UqlUsageError('the query must be a JSON object');
+    }
     const query = {};
     for (const key of getKeys(params)) {
         if (REJECTED_QUERY_KEYS.has(key)) {
@@ -50,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}'`);
             }
         }
     }
@@ -66,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

@@ -1,12 +1,12 @@
 import { ObjectId } from 'mongodb';
 import { AbstractDialect } from '../dialect/abstractDialect.js';
 import { AGGREGATE_VALUE_ALIAS, REL_NESTED_KEY, REL_TEMP_PREFIX, SUM_COUNT_ALIAS, nullsSortField, sortAggregateField, TEXT_SCORE_ALIAS, } from '../dialect/aliases.js';
-import { betweenBounds, GROUP_OPS, groupClauses, isGroupOp, whereOperators } from '../dialect/operators.js';
+import { betweenBounds, GROUP_OPS, groupClauses, isGroupOp, LIKE_OPS, likeRegex, whereOperators, } from '../dialect/operators.js';
 import { aggregateColumnField, groupPathField, resolveGroupJoins, relationSortTerms, resolveQueryJoins, resolveSortableJoin, } from '../dialect/queryJoins.js';
 import { assertSoleId, fieldOf, getMeta, relationOf, soleIdOf } from '../entity/index.js';
 import { COUNT_RESULT_KEY } from '../type/query.js';
 import { QueryRaw } from '../type/queryRaw.js';
-import { aggregateOf, asSelectMap, assertAggregateColumns, assertNonNegativeInteger, columnFamily, countedRelations, entityName, fieldUpdateOf, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, getKeys, getRelationRequestSummary, hasKeys, isFieldUpdateOp, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorObject, isRecord, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationAtKey, parseRelationSize, rankedTextSearch, someKey, targetKeyColumns, textSortOf, vectorDistanceOf, } from '../util/index.js';
+import { aggregateOf, isSelectList, assertAggregateColumns, assertNonNegativeInteger, columnFamily, countedRelations, entityName, fieldUpdateOf, fillOnFields, filterFieldKeys, findVectorIndex, findVectorSort, getKeys, getRelationRequestSummary, hasKeys, isFieldUpdateOp, isJsonObject, isJsonUpdateOp, isOperatorMap, isOperatorObject, isRecord, isVectorSearch, normalizeScalarFieldSelection, parentJoins, parseGroupMap, parseRelationAtKey, parseRelationSize, rankedTextSearch, someKey, targetKeyColumns, textSortOf, vectorDistanceOf, } from '../util/index.js';
 import { UqlUsageError } from '../util/uqlError.js';
 import { decodeBigIntsExcept } from '../util/wideNumber.js';
 import { textLanguage } from './textLanguage.js';
@@ -71,17 +71,6 @@ function compareCount(count, size) {
     }
     return comparisons.length === 1 ? comparisons[0] : { $and: comparisons };
 }
-/** String operators -> { pattern: (v) => regex, caseInsensitive } */
-const REGEX_OP_MAP = new Map([
-    ['$startsWith', { wrap: (v) => `^${v}`, ci: false }],
-    ['$istartsWith', { wrap: (v) => `^${v}`, ci: true }],
-    ['$endsWith', { wrap: (v) => `${v}$`, ci: false }],
-    ['$iendsWith', { wrap: (v) => `${v}$`, ci: true }],
-    ['$includes', { wrap: (v) => String(v), ci: false }],
-    ['$iincludes', { wrap: (v) => String(v), ci: true }],
-    ['$like', { wrap: (v) => String(v).replace(/%/g, '.*').replace(/_/g, '.'), ci: false }],
-    ['$ilike', { wrap: (v) => String(v).replace(/%/g, '.*').replace(/_/g, '.'), ci: true }],
-]);
 /** MongoDB native operators - pass through as-is. */
 const NATIVE_OPS = new Set([
     '$all',
@@ -361,11 +350,11 @@ export class MongoDialect extends AbstractDialect {
                 result[op] = val;
                 continue;
             }
-            // String/pattern -> regex operators (8 variants including $like/$ilike)
-            const regexEntry = REGEX_OP_MAP.get(op);
-            if (regexEntry) {
-                result['$regex'] = regexEntry.wrap(val);
-                if (regexEntry.ci)
+            // The `$like` family, as the regex matching what its `LIKE` pattern matches on SQL.
+            const like = LIKE_OPS.get(op);
+            if (like) {
+                result['$regex'] = likeRegex(like.pattern(String(val)));
+                if (like.insensitive)
                     result['$options'] = 'i';
                 continue;
             }
@@ -429,17 +418,16 @@ export class MongoDialect extends AbstractDialect {
         if (!select && !exclude) {
             return {};
         }
-        if (Array.isArray(select)) {
+        if (isSelectList(select)) {
             throw new UqlUsageError('raw $select is not supported on MongoDB');
         }
-        const selectMap = asSelectMap(select);
         // Projected by column, not by field key; `normalizeId` maps them back on the way out.
-        const projection = normalizeScalarFieldSelection(meta, selectMap, exclude).reduce((acc, key) => {
+        const projection = normalizeScalarFieldSelection(meta, select, exclude).reduce((acc, key) => {
             // A computed field writing SQL leaves the document nothing to project: refused asked for by
             // name, skipped swept in with the rest. A relation aggregate is on it by now, like any column.
             const field = meta.fields[key];
             if (field?.computed && !aggregateOf(field)) {
-                if (selectMap && key in selectMap) {
+                if (select && key in select) {
                     assertReadable(meta, key);
                 }
                 return acc;
@@ -450,7 +438,7 @@ export class MongoDialect extends AbstractDialect {
         // MongoDB returns `_id` unless it is explicitly excluded, so subtracting the primary key needs
         // `_id: 0` - the one inclusion/exclusion mix MongoDB allows - or `$exclude: { id: true }` would
         // have no effect at all.
-        if (this.subtractsKey(soleIdOf(meta, 'MongoDB'), selectMap, exclude)) {
+        if (this.subtractsKey(soleIdOf(meta, 'MongoDB'), select, exclude)) {
             projection[ID_KEY] = 0;
         }
         return projection;
@@ -565,7 +553,7 @@ export class MongoDialect extends AbstractDialect {
     /** The relation aggregates a read projects or sorts by; its `$where` puts its own on the document. */
     aggregateKeys(entity, q) {
         const meta = getMeta(entity);
-        const projected = normalizeScalarFieldSelection(meta, asSelectMap(q.$select), q.$exclude);
+        const projected = normalizeScalarFieldSelection(meta, isSelectList(q.$select) ? undefined : q.$select, q.$exclude);
         return [...projected, ...Object.keys(q.$sort ?? {})].filter((key) => aggregateOf(meta.fields[key]));
     }
     /**

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;