@avytrix/nestjs-drizzle-crud 3.7.2 → 3.8.1

package/AGENT.md

@@ -189,7 +189,10 @@ Operators inside an object value: `eq`, `gt`, `gte`, `lt`, `lte`, `neq`, `like`,
 `sql.caseSensitive`), `iStartsWith`, `iEndsWith`, `iContains` (always
 case-insensitive), and on PostgreSQL only `arrayContains`, `arrayOverlaps` and
 `jsonContains`. Any other operator is a 400. A bare string is an exact match,
-not a pattern, and `%` in it is a literal character. `isNull` and `isNotNull`
+not a pattern, and `%` in it is a literal character. On a text column it is
+`lower(col) = lower($1)` in `findAll` and `count` (index `lower(col)`), but a
+plain, case-sensitive `=` in `findOne`. https://crud.avytrix.dev/docs/indexes/
+lists the index each query shape needs; the package creates none. `isNull` and `isNotNull`
 take `true` / `false` or the strings `"true"` / `"false"`.
 
 OR and NOT need no raw Drizzle. `and`, `or` and `not` group filter objects, nest,
@@ -392,7 +395,9 @@ restore, force delete, attach included) and written onto every created row, so
 another tenant's id is a 404. A missing context value is a 403, never an
 unscoped query. A belongs-to key a write sets must point at a row of the
 caller's tenant when the related table has the scope columns; another tenant's
-row is the same 400 as a missing one. Do not add `tenant_id` to filters or DTOs
+row is the same 400 as a missing one. Nested create children get the same check
+for the keys their nested relation declares in its own `relations`; declare
+every belongs-to a child can set. Do not add `tenant_id` to filters or DTOs
 by hand, and use `skipScope: true` only in trusted server code.
 
 # Optimistic locking

package/CHANGELOG.md

@@ -11,6 +11,146 @@ restore, `ER_DUP_ENTRY` mapping, dialect locking) are tracked separately and unc
 3.3.1, 3.4.0, 3.5.0 and 3.5.2 were tagged but never published to npm. Their changes reached npm
 in 3.5.1 (3.3.1 to 3.5.0) and 3.6.0 (3.5.2). The unscoped `nestjs-drizzle-crud` stops at 3.3.0.
 
+## [3.8.1] - 2026-11-04
+
+Fixes from the 3.8.0 audit (D-01 to D-11). Three of them close gaps in tenant isolation: a scope
+handed from one service to another, a batch key that differs from another tenant's only in case,
+and nested children that skipped the key check. No public API or override point changed.
+
+### Changed
+
+- Text keys compare exactly in the tenant key check, `attach` and `sync`: `"US"` and `"us"` are
+  two keys, as they are two rows on PostgreSQL and SQLite. Before, every key was lowercased, so a
+  batch holding both could point a row at another tenant's `"us"` and get a 201 where `"us"`
+  alone was a 400. A uuid column still ignores case, and so does MySQL, to follow its default
+  collations, which match `"us"` to a stored `"US"` and cannot hold both as distinct keys.
+- On a scoped entity, a nested create checks the belongs-to keys of the rows it writes (a
+  belongs-to parent, has-many children, new many-to-many targets) against the caller's tenant,
+  using the nested relation's own `relations`. A child key to another tenant's row is the same
+  400 `ForeignKeyViolationException` as a key to a missing row, and nothing is written. It was a
+  201. A child key that no nested relation declares is still left to the database's foreign key.
+- `massSoftDelete` and `massDelete` put `deleted_at IS NULL` in the `WHERE` of their write, as the
+  single-row writes have since 3.8.0. A row soft-deleted between the existence check and the
+  write is a 404 entry and the batch writes nothing, instead of being stamped again or
+  hard-deleted. `massForceDelete` still removes a row in either state.
+- `massCreate` loads `relations` and `counts` inside its transaction again. A load that fails
+  rolls the rows back, so a retry no longer stores them twice. The other mass writes, which give
+  the same rows when retried, still load after the commit.
+- `update` of a missing row with a value the database refuses (`update(999, { views: "abc" })`)
+  is a 404, as it was before 3.8.0, instead of a 400.
+
+### Fixed
+
+- The per-call scope memo is keyed by service and by the context it was resolved for. Options
+  handed from one service to another, the natural way for a subclass override to share a
+  transaction, carried the first service's scope: a service whose scope is `null` let a scoped
+  one read every tenant's rows, and a second service scoped by another column stored `NULL` in
+  it. Each service still runs its scope function once per call.
+- An override of `emitEvent` or `prepareUpdate` keeps the guard read ahead of the write, like an
+  override of a `before*` hook. An `emitEvent` override saw the before event for another
+  tenant's id before the 404.
+- `massUpdate` with a `beforeUpdate` hook that returns `NaN` for one id and `null` for another no
+  longer writes `NaN` to both, and a Drizzle `sql` expression as a value (`views + 1`) works as
+  it does in `update` instead of failing with a circular `TypeError` (a 500).
+- The tenant key check sends its `SELECT`s, one per relation, together instead of one after the
+  other.
+
+### Docs
+
+- The multi-tenancy FAQ answered "No" to "Are eager-loaded relations filtered by tenant?", against
+  the section on the same page. It now says yes, when the related table has the scope columns.
+  The multi-tenancy and relations-on-writes pages say which nested keys are checked, and the bulk
+  operations page says when a mass write loads its relations.
+- `AGENTS.md`, `CONTRIBUTING.md` and `apps/docs/AGENTS.md` point at the changelog page where it
+  lives now, `(support)/changelog.mdx`.
+
+## [3.8.0] - 2026-11-03
+
+Performance fixes from the 3.7.1 performance report. Calls return the same rows, in the same
+order, with the same errors, in fewer statements and shorter transactions. The one visible
+difference is under Changed: a row soft-deleted between the guard read and the write is now a 404
+instead of a write. Inside `SqlBaseCrudService` the six mass writes share one skeleton, and so
+do `softDelete`, `restore` and `delete`; no public API, override point or message changed.
+
+### Added
+
+- Full-text search takes a column that already is a `tsvector`, such as a generated, stored
+  column, and uses it as is instead of wrapping it in `to_tsvector`, so a GIN index on the column
+  serves `fullTextSearch()` and `search.mode: "fullText"`. Before, such a column failed with
+  `function to_tsvector(unknown, tsvector) does not exist`. Next to text columns it is
+  `coalesce(col, ''::tsvector)`; text columns keep the 3.7.2 vector, bare for one column and
+  coalesced for several. On 200,000 rows a search on the stored column with its index took
+  0.6 ms, against 600 to 900 ms computing `to_tsvector` per row without one. The full-text page
+  shows the index for each shape.
+- A docs page, [Database indexes for fast Drizzle queries](https://crud.avytrix.dev/docs/indexes/),
+  lists the index each query shape needs: `lower(col)` (or `citext`, or `caseSensitive: true`) for
+  the default case-insensitive equality, the sort columns plus the primary key for cursor pages,
+  GIN for full-text search, `pg_trgm` for `contains` and `search`, foreign keys and both join
+  table columns for relations, partial indexes on `deleted_at IS NULL`, and the tenant column
+  first. It says when to use `withCount: false` or the cursor on a large table. The filtering
+  page now spells out that `findOne` compares strings with a plain, case-sensitive `=` while
+  `findAll` and `count` use `lower()` by default (unchanged; a default change waits for a major),
+  and the hooks page says where after hooks run: after the commit for a single write, inside
+  the transaction for a mass write.
+
+### Changed
+
+- A row soft-deleted between the guard read and the write is no longer written: `update` and
+  `softDelete` only touch a live row, `restore` only a row in the trash, and `delete` no longer
+  hard-deletes a row that was soft-deleted meanwhile (`forceDelete` still does). Such a call is a
+  404 instead of a write, a `false` return or a "Failed to update entity" error, and one whose
+  row vanished with an expected version is a 404 instead of a 409.
+
+### Fixed
+
+- Keyset pages seek instead of filtering. `findByCursor` adds a bound on the first sort column
+  (`col <= $1` descending, `col >= $1` ascending) ahead of the OR expansion, drops the `IS NULL`
+  branch for NOT NULL and primary key columns (nullable and relation columns keep it), and on
+  PostgreSQL compares `(a, id) > ($1, $2)` as one row value when every column is NOT NULL and
+  sorts the same way. With an index on the sort columns and the primary key, page 9,000 of
+  200,000 rows went from 24.4 ms to 0.6 ms (`created_at` descending) and from 50.3 ms to 0.5 ms
+  (`views` ascending) on PGlite. A sort column the row already carries is no longer selected a
+  second time for the cursor. Pages, their order and cursors are unchanged.
+- Single-row writes skip the read first. On PostgreSQL and SQLite, `update`, `softDelete`,
+  `restore`, `delete` and `forceDelete` send one statement whose `WHERE` holds the whole guard
+  (primary key, tenant scope, expected version, soft delete state) and read the row only when
+  nothing came back, to answer with the same 404 or 409 as before. The read still runs first
+  when something a caller can observe sits between it and the write (an overridden `before*`
+  hook, `validateUpdate` or `mapUpdateDtoToEntity`, or a before event), so hooks and events see
+  exactly what they saw before, and on MySQL. A missing row is still a 404 ahead of a bad body.
+- Mass writes send no savepoint on the happy path when they open their own transaction:
+  `massUpdate`, `massSoftDelete`, `massRestore` and `massDelete` take 4 round trips instead of 8
+  (`BEGIN`, `SELECT`, the set statement, `COMMIT`), `massCreate` and `massUpsert` 3 instead of 5.
+  When the set statement fails, the transaction rolls back and the items are replayed in a fresh
+  transaction that is rolled back too, so `BulkOperationException` names the same items with the
+  same statuses and messages. Inside a caller's transaction, or once a before event handed the
+  transaction to a subscriber, the savepoints stay, so a failed item does not abort the caller's
+  PostgreSQL transaction.
+- `massUpdate` sends one `UPDATE` per distinct SET when `beforeUpdate` returns different data
+  per id, instead of one `UPDATE` and a savepoint pair per id: a hook with two results over 50
+  ids is 5 round trips instead of 155. Rows still come back in the input order, after hooks run
+  in that order, and a failure still names every failing id.
+- On MySQL, `massCreate` of rows with auto-increment keys reads the inserted rows back with one
+  `SELECT ... WHERE id IN (...)` instead of one per row. The inserts stay one per row: MySQL only
+  reports the first id of a multi-row `INSERT`, and InnoDB does not promise the others are
+  consecutive.
+- Relation loaders and relation counts split a parent key list that would not fit in one
+  statement. `loadBelongsTo`, `loadHasMany`, `loadManyToMany` and `loadCounts` send the keys in
+  chunks of 64,535 on PostgreSQL and MySQL, 31,766 on SQLite and 90 on Cloudflare D1, one query per
+  chunk, so a nested page whose level holds 70,000 keys loads in two queries instead of failing
+  with a 400 (3.7.2) or a 500 (before). Below that, it is one query per relation as before. The
+  chunk size is the new protected `relationChunkSize(db)`.
+- Fewer statements in a few calls. `exists(id, options)` is one `SELECT` and no longer loads
+  `options.relations` or `options.counts` it throws away (4 statements to 1 with two relations and
+  a count); they are still checked against the allowlists. A nested create skips the "already
+  linked?" read for its many-to-many ids. `attach`, `sync` and `detach` read the row once and load
+  the relation onto it, instead of reading it before and after (8, 9 and 6 round trips to 7, 8 and
+  5). A mass write that opened its own transaction loads `options.relations` and `options.counts`
+  after it commits, so it holds its row locks for less time; with a count filter, or in a caller's
+  transaction, they still load inside. The returned rows are the same.
+- A `scope` function runs once per call instead of once per statement and relation: 5 times for
+  a `findAll` with three relations and a count, 7 for a `massUpdate`, now 1 each.
+
 ## [3.7.2] - 2026-11-03
 
 Fixes from the 3.7.1 audit. The batch limit now counts the statement the database receives.
@@ -335,7 +475,8 @@ app.
   only operator on MySQL is a 400.
 - **Keyset pagination.** `findByCursor(filters, { cursor, limit, sortBy, count }, options)` returns
   `{ data, limit, nextCursor, total? }`. The cursor is base64url JSON of the last row's sort values
-  plus the primary key, so pages stay stable under inserts and deep pages cost the same as the
+  plus the primary key, so pages stay stable under inserts and, with an index on the sort columns
+  (since 3.8.0), deep pages cost the same as the
   first. It works with every sort, filter, relation and `select`, keeps timestamp microseconds and
   follows the database's NULL ordering. The count only runs with `count: true`. A cursor that is not
   valid, or was made for another sort, is a 400.

package/README.md

@@ -563,6 +563,12 @@ instead of returning an arbitrary row.
 > `like` / `ilike` operators and supply your own wildcards, or `startsWith` /
 > `endsWith` / `contains`, which escape the value for you.
 
+`findOne` is the exception: it compiles a string to a plain `=`, so it is
+case-sensitive whatever `sql.caseSensitive` says. A plain index on the column
+cannot serve `lower(column) = lower($1)`; create one on `lower(column)`. The
+[indexes page](https://crud.avytrix.dev/docs/indexes/) lists the index each
+filter, sort, search and relation needs.
+
 ---
 
 ## Query strings: parseQuery
@@ -654,7 +660,9 @@ in `forRoot` to apply a `created_at` fallback to every entity that doesn't defin
 ## Cursor pagination
 
 `findByCursor` pages with `WHERE (sort columns) > (last row)` instead of
-`OFFSET`, so deep pages stay fast and rows inserted earlier do not shift the
+`OFFSET`, starting with a bound on the first sort column, so with an index on
+the sort columns plus the primary key (`(created_at DESC, id)` below) deep
+pages stay as fast as the first, and rows inserted earlier do not shift the
 next page:
 
 ```typescript
@@ -931,7 +939,9 @@ Each bulk method is one statement for the whole set (plus one `SELECT` that
 checks the ids exist), inside a single transaction: `massUpdate` over 100 ids is
 two queries. If any item fails, a `BulkOperationException` (400) is thrown and
 the transaction rolls back. The failing items are found by replaying the batch
-inside a savepoint that is rolled back, and the response body lists only them:
+in a transaction (or, inside your own transaction, a savepoint) that is rolled
+back, and the response body lists only them. The happy path sends no savepoint
+unless it runs inside your transaction:
 
 ```json
 { "statusCode": 400, "error": "Bad Request",

package/dist/core/abstract/sql-base-crud.service.d.ts

@@ -26,6 +26,8 @@ export declare abstract class SqlBaseCrudService<T extends Record<string, any>,
     protected checkReadOptions(options?: SqlOperationOptions): void;
     protected rowScope(options?: SqlOperationOptions): any[];
     protected resolveScope(options?: SqlOperationOptions): CrudScopeValues | null;
+    private withScopeMemo;
+    private checkScope;
     protected scopeConditions(options?: SqlOperationOptions, table?: any): any[];
     protected relatedRowScope(target: any, options?: SqlOperationOptions): any[];
     protected relatedScopeConditions(target: any, options?: SqlOperationOptions): any[];
@@ -61,6 +63,7 @@ export declare abstract class SqlBaseCrudService<T extends Record<string, any>,
     protected beforeRestore(_id: any): Promise<void>;
     protected afterRestore(_entity: T): Promise<void>;
     protected relationType(relation: RelationConfig): RelationType;
+    private relationNamed;
     protected isCollection(relation: RelationConfig): boolean;
     protected eagerRelations(relations: string[]): string[];
     protected relationTree(paths: string[], configured?: RelationsConfig): RelationNode[];
@@ -78,7 +81,12 @@ export declare abstract class SqlBaseCrudService<T extends Record<string, any>,
     protected loadRelations(db: any, hosts: any[], nodes: RelationNode[], select?: SelectTree, hostTable?: any, options?: SqlOperationOptions): Promise<void>;
     protected loadBelongsTo(db: any, hosts: any[], node: RelationNode, select: SelectTree, options?: SqlOperationOptions): Promise<void>;
     protected loadHasMany(db: any, hosts: any[], node: RelationNode, select: SelectTree, hostTable?: any, options?: SqlOperationOptions): Promise<void>;
+    private loaderKeys;
+    private loadCollection;
+    private selectThrough;
     protected loadManyToMany(db: any, hosts: any[], node: RelationNode, select: SelectTree, hostTable?: any, options?: SqlOperationOptions): Promise<void>;
+    protected relationChunkSize(db: any): number;
+    private inChunks;
     private groupCollection;
     protected applyJoins(query: any, relationNames: string[], options?: SqlOperationOptions): any;
     protected normalizeRelations(rows: any[], eager: string[]): any[];
@@ -111,6 +119,7 @@ export declare abstract class SqlBaseCrudService<T extends Record<string, any>,
         vector: any;
         query: any;
     };
+    private isTsVector;
     protected buildSearchCondition(search?: SqlOperationOptions["search"]): any;
     protected caseInsensitiveLike(column: any, pattern: string): any;
     protected likePattern(column: any, pattern: string): any;
@@ -118,14 +127,20 @@ export declare abstract class SqlBaseCrudService<T extends Record<string, any>,
     idKind(): "int" | "bigint" | "uuid" | "string";
     parseId(raw: unknown): Promise<unknown>;
     private findForGuard;
+    private guardRow;
+    private skipsGuard;
+    private guardOnError;
     protected assertVersion(id: any, actual: unknown, expected: unknown): void;
     protected writeWhere(ids: any[], options?: SqlOperationOptions, table?: any): any;
     protected withVersionBump(set: Record<string, any>): Record<string, any>;
     find(id: any, options?: SqlOperationOptions): Promise<T | null>;
     findOne(where: Partial<T>, options?: SqlOperationOptions): Promise<T | null>;
     private findFirst;
+    private readFirst;
+    private hydrate;
     private planList;
     private listConditions;
+    private parseCount;
     private buildCountQuery;
     findAll(filters: FilterDto | undefined, pagination: PaginationOptions & {
         withCount: false;
@@ -138,6 +153,10 @@ export declare abstract class SqlBaseCrudService<T extends Record<string, any>,
     protected cursorField(column: any): any;
     private compareCursor;
     protected keysetCondition(specs: SortSpec[], values: unknown[]): any;
+    private keysetBound;
+    private keysetRowComparison;
+    private keysetNullable;
+    private nullsFirst;
     private afterCursor;
     protected emitEvent(phase: "before" | "after", operation: CrudWriteOperation, bulk: boolean, payload: {
         ids?: unknown[];
@@ -147,6 +166,8 @@ export declare abstract class SqlBaseCrudService<T extends Record<string, any>,
     }, options?: SqlOperationOptions): Promise<void>;
     private idsOf;
     protected loadWriteRelations(db: any, rows: T[], options?: SqlOperationOptions): Promise<void>;
+    private loadsAfterCommit;
+    private writeThenLoad;
     private expectedVersionOf;
     protected prepareCreate(data: CreateDto, options?: SqlOperationOptions): Promise<Record<string, any>>;
     private insertOne;
@@ -157,6 +178,7 @@ export declare abstract class SqlBaseCrudService<T extends Record<string, any>,
     private keysOutsideScope;
     private assertBatchKeysInScope;
     private assertKeysInScope;
+    private assertNestedKeysInScope;
     private missingParentException;
     private linkTargets;
     attach(id: any, relation: string, relatedIds: unknown[], options?: SqlOperationOptions): Promise<T>;
@@ -171,6 +193,8 @@ export declare abstract class SqlBaseCrudService<T extends Record<string, any>,
     private updateWhereIn;
     private fetchByIds;
     private inIdOrder;
+    private guardedWrite;
+    private staleOrFalse;
     softDelete(id: any, options?: SqlOperationOptions): Promise<boolean>;
     private softDeleteSet;
     restore(id: any, options?: SqlOperationOptions): Promise<T>;
@@ -178,14 +202,18 @@ export declare abstract class SqlBaseCrudService<T extends Record<string, any>,
     forceDelete(id: any, options?: SqlOperationOptions): Promise<boolean>;
     upsert(data: CreateDto, upsert?: UpsertOptions, options?: SqlOperationOptions): Promise<T>;
     massUpsert(data: CreateDto[], upsert?: UpsertOptions, options?: SqlOperationOptions): Promise<T[]>;
+    private upsertSet;
     private conflictKeys;
     private conflictValue;
     private upsertRows;
     private excludedValue;
+    private massWrite;
     massCreate(data: CreateDto[], options?: SqlOperationOptions): Promise<T[]>;
     private insertMany;
+    private readBackCreated;
     private assertAllWritten;
     massUpdate(ids: any[], data: UpdateDto, options?: SqlOperationOptions): Promise<T[]>;
+    private updateSets;
     private runKeyed;
     massSoftDelete(ids: any[], options?: SqlOperationOptions): Promise<boolean>;
     massRestore(ids: any[], options?: SqlOperationOptions): Promise<T[]>;
@@ -201,12 +229,9 @@ export declare abstract class SqlBaseCrudService<T extends Record<string, any>,
         id?: any;
         run: (sp: any) => Promise<unknown>;
     }>, operation: "write" | "delete"): Promise<R>;
+    private settleSet;
     private diagnose;
-    private massCreatePerItem;
-    private massUpdatePerItem;
-    private massSoftDeletePerItem;
-    private massRestorePerItem;
-    private massDeletePerItem;
+    private eachInSavepoint;
     protected savepoint<R>(tx: any, run: (sp: any) => Promise<R>): Promise<R>;
     exists(id: any, options?: SqlOperationOptions): Promise<boolean>;
     count(filters?: FilterDto, options?: SqlOperationOptions): Promise<number>;
@@ -215,6 +240,7 @@ export declare abstract class SqlBaseCrudService<T extends Record<string, any>,
     protected countNames(counts?: RelationCounts): string[];
     protected withCountKeys(base: string[], counts?: RelationCounts): string[];
     protected loadCounts(db: any, rows: any[], counts: RelationCounts | undefined, options?: SqlOperationOptions): Promise<void>;
+    private countPlan;
     private countQuery;
     protected pushColumnCondition(conditions: any[], column: any, value: any, caseInsensitive?: boolean): void;
     protected buildCollectionFilter(relation: RelationConfig, value: Record<string, any>, db?: any, name?: string, options?: SqlOperationOptions): any | undefined;
@@ -241,6 +267,7 @@ export declare abstract class SqlBaseCrudService<T extends Record<string, any>,
     private patternCondition;
     protected applyComplexFilter(conditions: any[], column: any, filterObj: any): void;
     protected executeSqlTransaction<R>(operation: (tx: any) => Promise<R>, existingTransaction?: any): Promise<R>;
+    private readonly ownedTransactions;
     protected assertTransactions(db: any): void;
     protected getEntityName(): string;
     fullTextSearch(searchTerm: string, searchColumns: string[], pagination?: PaginationOptions, options?: FullTextSearchOptions<FilterDto>): Promise<{