cry-db 2.6.1 → 2.6.2

package/CHANGELOG.md

@@ -0,0 +1,567 @@
+# Changelog
+
+## 2.6.0 — 2026-07-09
+
+### Added
+
+- `emitPublishBracketedEvents()` — third publish-event flavor alongside
+  `emitPublishEvents()` (full doc) and `emitPublishRevEvents()` (revision-only).
+  Emits `publishBracketed` events on `dbbracketed/{db}/{collection}` carrying
+  only the **client diff** (forwarded `rawUpdate`) instead of full parent
+  arrays/objects. Insert operations still carry the full document (there is
+  no diff). Useful for consumers that apply deltas locally rather than
+  replacing whole arrays.
+  - `MongoEmittedEvents` extended with `"publishBracketed"`.
+  - New types: `DbBracketedChannel`, `PublishBracketedPayloadBatch`,
+    `PublishBracketedPayloadBatchItem`, `PublishBracketedSpec`.
+
+### Fixed
+
+- `_buildPublishDelta` dot-path handling: dot-path updates like
+  `cepljenja.xxx = { ... }` now correctly publish the **whole parent object**
+  (`cepljenja`) instead of a flat `cepljenja.xxx` key with `undefined` value.
+  Previously `_buildPublishDelta` treated dot-paths as literal top-level keys,
+  which do not exist in the post-update document → published `undefined`.
+
+### Internal
+
+- Testi: `updateCollections.mjs` — 7 novih testov za publish behavior:
+  - dot-path object-map publish (prej failal)
+  - bracketed array publish (insert/update/remove)
+  - bracketed publish events (3 testi za `publishBracketed` event)
+
+## 2.5.6 — 2026-06-25
+
+### Added
+
+- `findNewerManyStream` server-side scope-exit: po pozitivni delti pošlje še
+  iteme, ki so v tem sync oknu padli izven query-ja. Uporabi `_ts` filter + JS
+  evalvacijo query-ja (`matchesQuery` iz `cry-local-query`). Rezultat pride z
+  `_evictIds: true`, da klient ve, da mora te iteme odstraniti.
+- `_extractQueryFields` — rekurzivno ekstrahira top-level field imena iz
+  MongoDB query-ja (vključno z `$and`/`$or`/`$nor`) za dinamično generiranje
+  projekcije v scope-exit passu.
+
+### Internal
+
+- Dodana dependency `cry-local-query` (za `matchesQuery` v scope-exit).
+- `tsconfig.json` exclude: `dist`, `test`, `node_modules`.
+- Testi: `bracketUnsetPullConflict.mjs` cleanup — odstranjen `describe.skip`
+  bug-repro test, ohranjen samo fixed behaviour.
+- AI test coverage: `deepseek-findNewerManyStream-scopeExit`,
+  `kimi-extractQueryFields`, `kimi-syncedCollections-scopeExit`.
+
+## 2.5.2 — 2026-06-18
+
+### Fixed
+
+- `fix:` detektiran konflikt bare-field array replacement (`postavke: [...]`) +
+  bracket-by-_id sub-field path (`postavke[<id>].field: x`) na istem arrayu.
+  Prej je MongoDB tiho uporabil samo polno zamenjavo, sub-field se je izgubil.
+  Zdaj vrže error v `results.errors` z navodilom naj uporabi terminal-bracket
+  obliko. Zajeti tudi primeri, ko bracket sub-field vsebuje `undefined` (gre v
+  `$unset`) ali ko doda novo polje.
+
+### Internal
+
+- Testi: `bracketFullArrayPlusSubField.mjs` — 8 testov za oba patterna
+  (error in pravilni) z različnimi tipi vrednosti in `undefined`.
+
+## 2.5.1 — 2026-06-18
+
+### Fixed
+
+- `fix:` `$set + $pull` conflikt na istem parent array-u — `setTargetsField` check
+  detektira, ko bracket sub-field update (`arr[A].field: x`) in terminal-bracket
+  remove (`arr[B]: undefined`) targetirata isti array, in pade v pipeline form.
+- `re:` dodani testi za produkcijsko reprodukcijo (odprtiRacuni — remove ene
+  postavke + sub-field update druge + top-level polja).
+- `vp:` dodan TDD test `bracketPullSetConflict.mjs` — 6 testov, vključno z
+  raw MongoDB kontrolo, da `$pull + $set` na istem fieldu res vrže conflikt.
+
+### Internal
+
+- Testi: `computeObjDiff.mjs` dodani testi za `odprtiRacuni` production
+  scenario (remove + modify na različnih arrayih).
+- Testi: `bracketSubFieldViaUpdateCollections.mjs` dodani testi za sub-field
+  update + remove na istem arrayu + top-level fields.
+- Doc: `CHANGES.md` preimenovan v `CHANGELOG.md`.
+
+## 2.5.2 — 2026-06-18
+
+### Added
+
+- `fix:` detekcija konflikta bare-field array replacement (`postavke: [...]`) +
+  bracket-by-_id sub-field (`postavke[<id>].field`) v `_applyBracketProcessing`.
+  MongoDB tiho ignorira bracket sub-field ob polni zamenjavi (napačni podatki).
+  Zdaj vrže error v `results.errors`.
+- `te:` `bracketFullArrayPlusSubField.mjs` — 7 testov za konflikt in pravilni
+  pattern (terminal-bracket insert + sub-field overlay) z različnimi tipi.
+
+## Unreleased
+
+_Nothing yet._
+
+## 2.5.0
+
+### `computeObjDiff` / `applyObjDiff` — document diff utilities (NEW)
+
+Two pure, mongo-independent helpers — the server-side counterpart of the
+`cry-synced-db-client` diff machinery — exported from the package root:
+
+- `computeObjDiff(existing, update)` — the minimal set of MongoDB-style
+  dot/bracket `$set` paths that transform `existing` into `update` (only for
+  keys present in `update`). Arrays of `_id`-keyed objects diff element-wise
+  via `arr[<id>].field`, with composition changes as `arr[<id>] = [el]` /
+  `arr[<id>] = undefined`. `_ts`/`_rev`/`_csq` are never emitted.
+- `applyObjDiff(base, diff, fallbackId, collection)` — replays such a path-set
+  onto a base document the way a server-side `$set` + `$unset` would; returns a
+  fresh object (`base` is cloned, never mutated). Missing bracket-parent arrays
+  are materialized; unrepresentable multi-bracket paths are dropped (logged
+  unless the root field starts with `_`).
+
+Also exported from the same module: `deepEquals`, `setByPath`, `deleteByPath`,
+`tokenizePath`.
+
+```ts
+import { computeObjDiff, applyObjDiff } from 'cry-db';
+
+const diff = computeObjDiff(existing, update);
+// → { "koraki[k1].diag": "new", "koraki[k2]": [{ _id: "k2", ... }] }
+const merged = applyObjDiff(base, diff, fallbackId, collection);
+```
+
+### `updateCollections` — `mustRefresh` + required `_rev` (BREAKING)
+
+Each `updates`/`deletes` entry now carries `_rev` — the revision the client's
+change was computed against — and the result gains
+`results.mustRefresh: (DbEntity & <full record>)[]`: full, sanitized records
+the client MUST replace in its local store. A record lands in `mustRefresh`
+when:
+
+- cry-db **resolved a placeholder field** the client sent — `SEQ_*`
+  (auto-increment) or `__hashed__*` (hashing); or
+- the stored `_rev` **advanced beyond the client's base** by more than this
+  write applied — another actor modified the record first (conflict); or
+- the request **omitted `_rev`** (treated as `0` — the old-client fallback).
+
+Contract:
+
+- Every `mustRefresh._id` **also** appears in `inserted`/`updated`/`deleted`,
+  so dirty-clearing logic keyed off those arrays is unaffected — treat
+  `mustRefresh` as supplementary.
+- Records are **full and sanitized**: `__hashed__*` values never leave the
+  server (the client adopting the record drops any local plaintext);
+  `removeFieldsAlways`/`findNewerRemoveFields` are applied as on reads.
+- The client should **replace** its local record from the `mustRefresh` entry,
+  then run its dirty-merge — apply `mustRefresh` **before** the merge.
+- Conflict detection requires `useRevisions()`. Field-resolution refresh
+  (SEQ/hash) works regardless.
+
+**Why breaking**: the request shape now declares `_rev` required on
+`updates`/`deletes` entries (omission is tolerated at runtime as the fallback,
+but consumers should send it). Do **not** put `_rev` inside `update` — it is
+stripped.
+
+## 2.4.49
+
+### Nested-bracket (multi-level) sub-field and terminal-bracket operations
+
+Bracket-by-`_id` paths now support arbitrary nesting depth in BOTH the
+arrayFilters fast path and the pipeline form. Paths like
+`arr[A].sub[B].field`, `arr[A].sub[B]: [...]` (nested terminal insert),
+and `arr[A].sub[B] = undefined` (nested terminal remove) all work, and
+can be freely combined with top-level bracket operations in the same
+update.
+
+Evolution across releases:
+
+- early bracket releases: combining a nested-bracket path with a
+  terminal-bracket insert threw a descriptive error.
+- 2.4.45: the throw was softened to "drop + log warning" so production sync
+  payloads (e.g. `cry-synced-db-client`'s `_redundanca`) wouldn't fail the
+  whole batch.
+- 2.4.49 (this entry): full support implemented. Drops + warnings of the
+  "nested-bracket dropped" kind no longer occur.
+
+Implementation pieces (`src/mongo.mts`):
+
+- New mutually-recursive types `NestedFieldOps` / `NestedElementOps`.
+  `ElementOps.nestedArrayOps?: Map<arrayField, FieldOps>` carries the
+  per-id sub-array transforms for the inner level.
+- New `_buildArrayTransformExpr(basePath, FieldOps)` factors out the
+  filter+concat+map+switch composition. `_buildElementMergeExpr`
+  recursively calls it inside its overlay for each `nestedArrayOps`
+  entry. The top-level pipeline loop in `_applyBracketProcessing`
+  reuses the same helper.
+- Removes-only nested transforms on a missing source field are wrapped
+  in `$cond: { $isArray: <path> }`, so deleting from a non-existent
+  inner array does NOT create a spurious empty array. Matches mongo's
+  native "$pull on missing field = no-op" semantic.
+
+**Same-id overlap warning**: when a nested "new base" operation AND a
+nested sub-field update target the same element (same `_id` at the
+inner level), both apply (new-base value is set first, sub-field
+overlay applies on top). The unusual overlap is surfaced as a
+`{ kind: 'overlap' }` warning in `result.results.warnings`. Two flavors
+trigger:
+
+- terminal-array insert (`arr[id]: [{...}]`) + sub-field on same id;
+- whole-element replace (`arr[id]: {...}`, object value) + sub-field on
+  same id.
+
+```ts
+await items.updateOne({ _id: 'r1' }, {
+    'terapije[t1].postavke[sp1].kolicina': 99,
+    "terapije[t1].postavke[sp1]": [{ _id: 'sp1', q: 5 }],     // Flavor 1
+    // or, equivalently:
+    // "terapije[t1].postavke[sp1]": { _id: 'sp1', q: 5 },    // Flavor 2
+});
+// final sp1: { _id: 'sp1', q: 5, kolicina: 99 }
+// warning: 'same-id overlap at "terapije[t1].postavke[sp1]" — …'
+```
+
+Top-level same-id case (single-bracket insert/replace + sub-field on
+the same outer `_id`) is the same semantic but stays silent — it's a
+documented merge pattern.
+
+40+ regression tests in `test/bracketNestedSpec.mjs` and
+`test/bracketNestedPermutations.mjs` cover the full matrix of
+add/delete/modify operations at outer and inner levels.
+
+## 2.4.47
+
+### Fix: `$set` + `$pull` conflict for bracket sub-field + same-array remove
+
+Combining a bracket sub-field update (`arr[id].field`, which compiles to
+`$set` with `arrayFilters`) with a terminal-bracket remove on the **same**
+parent array (`arr[otherId] = undefined`, which compiles to `$pull`) tripped
+mongo's "conflict at <field>" guard. Conflict detection now recognizes this
+case and routes the two operations so they no longer collide; `undefined`
+values are logged for visibility. Regression test in
+`test/bracketArrayPaths.mjs` / `updateCollections.mjs`.
+
+## 2.4.46
+
+### `MONGO_DEBUG_UPDATE_COLLECTIONS` — verbose `updateCollections` logging
+
+New env var. When set, `updateCollections` logs each `findOneAndUpdate`
+(query, translated update, options) and the final per-collection results at
+`info` level instead of `debug`, for diagnosing sync-batch processing.
+
+The `updateCollections` partial-failure semantics were also documented: per-record
+failures land in `result.results.errors` and do not stop the rest of the
+batch; only infrastructure failures (connection, sequence pre-processing,
+audit/publish) propagate as a thrown exception.
+
+## 2.4.45
+
+### `CollectionUpdateResult.errors` is now an array (BREAKING)
+
+`result.results.errors` was previously typed as a single `{ _id, error }`
+object, but `updateCollections` internally collected an array and assigned
+only `errors[0]` — silently dropping all but the first failure in a batch.
+The type is now correct: `errors?: { _id: string, error: string }[]`. All
+per-update / per-delete errors in the batch are surfaced.
+
+Consumers that read `result.results.errors._id` / `.error` must switch to
+`result.results.errors[0]._id` / `[0].error` (or iterate).
+
+### `CollectionUpdateResult.warnings` — new field
+
+Companion to `errors`: `warnings?: { _id: string, error: string }[]` carries
+non-fatal issues encountered while processing the batch. The `error` field
+holds a human-readable message; the array entry's `_id` identifies the
+affected document.
+
+Initially emitted when a nested bracket-by-`_id` path had to be **dropped**
+(rather than throwing and failing the whole batch). The **same-id overlap**
+emitter — when a nested terminal-bracket insert and a nested sub-field update
+target the same element — was added in 2.4.49 (see _Nested-bracket
+(multi-level) sub-field and terminal-bracket operations_ above).
+
+### Pipeline `$switch case $eq` normalizes hex bracket-id to ObjectId (FIX)
+
+When an update mixed a bracket-by-`_id` sub-field path
+(`arr[id].field: val`) with a terminal-bracket insert/remove on a sibling
+array — forcing the pipeline form — the per-id `$switch` branches
+compared `$$el._id` against the raw bracket-id token (a hex string).
+Stored `_id`s are usually `ObjectId`s, so the `$eq` branch never matched
+and the sub-field merge silently no-op'd.
+
+Now applies `_normalizeBracketId` to the bracket token (the same
+conversion already used in `arrayFilters`, `$pull`, and `$filter` paths),
+so 24-char hex strings become `ObjectId` for the comparison.
+
+Production trigger (mozirje, 2026-05-10): updateCollections payloads
+combining `postavke[<hex>].kolicina` (sub-field) with `davki[<hex>]:
+[...]` (terminal insert on sibling) silently failed to apply the
+`kolicina` change while the `davki` insert went through. Affected
+documents stayed dirty and the dirty change couldn't drain.
+
+Regression test in `test/bracketSubFieldViaUpdateCollections.mjs`.
+
+## 2.4.40
+
+### `fj` exported — recursive ObjectId formatter
+
+`Mongo`'s internal `ObjectId` log-formatter is now exported from
+`cry-db`. Given any value, it returns:
+
+- `ObjectId("<hex>")` string for an `ObjectId` instance.
+- An array / plain-object structure with all nested `ObjectId`s
+  recursively replaced by their formatted string.
+- Anything else (primitives, `Date`, `Buffer`, BSON-types, …) returned
+  unchanged.
+
+Useful when building log messages or `JSON.stringify` payloads that should
+make `ObjectId` values visible as such rather than as bare hex strings.
+
+```ts
+import { fj } from 'cry-db';
+fj(new ObjectId('507f1f77bcf86cd799439011'));
+// → 'ObjectId("507f1f77bcf86cd799439011")'
+fj({ users: [{ _id: someId, name: 'x' }] });
+// → { users: [{ _id: 'ObjectId("…")', name: 'x' }] }
+```
+
+## 2.4.36
+
+### `$literal` wrap for user values in pipeline form (FIX: dot-in-field-name keys)
+
+User-supplied object/array values that flow into the pipeline form of
+bracket-by-`_id` updates are now wrapped in `$literal` so mongo's
+expression parser treats them as opaque data. Without the wrap, nested
+field names containing `.` or `$` (legitimate as stored mongo doc keys)
+crash the aggregation stage with:
+
+> `FieldPath field names may not contain '.', given '<name>'.`
+
+Production trigger (mozirje): pmz `karence` data carries `not. organi` /
+`not. organi` field names (with a literal dot). Inserting a postavka
+referencing such pmz data via terminal-bracket insert
+(`postavke[<id>]: [<obj>]`), or updating an existing element's
+sub-object value via `postavke[<id>].karence: <obj>` while another
+insert was present in the same operation, threw the FieldPath error and
+left the dirty change stuck forever.
+
+**Two affected paths** in `_applyBracketProcessing`:
+
+1. **Insert path** — `$concatArrays: [filteredExisting, ops.insertElements]`
+   now wraps `ops.insertElements` in `$literal`.
+2. **Sub-field overlay path** — values stored in `node.directs[leaf]`
+   (which feed into `$mergeObjects`) are wrapped in `$literal` when they
+   are plain objects or arrays. New `_needsLiteralWrap` helper
+   distinguishes plain objects/arrays (need wrap) from primitives, `Date`,
+   and BSON types (`ObjectId`, `Timestamp`, `Decimal128`, `Binary`, …;
+   pass through).
+
+Backward compatible — payloads without dot-in-field-name keys produce
+identical mongo updates. `$literal` is a no-op for opaque BSON-encoded
+data; no measurable performance cost.
+
+```ts
+// Now works (previously threw):
+await items.updateOne({ _id: 'racun' }, {
+    'postavke[p2]': [{
+        _id: 'p2',
+        karence: {
+            karence: {
+                'meso': 7,
+                'not. organi': 7,    // ← legit stored key, contains dot
+                'mleko': 3,
+            },
+        },
+    }],
+    'postavke[p1].kolicina': 99,    // forces pipeline form
+});
+```
+
+Three new regression tests in `test/bracketArrayPaths.mjs` cover the
+insert path (alone and combined with sub-field updates) and the
+sub-field-with-object-value path.
+
+## 2.4.35
+
+### Publish payload: de-bracketed `data`, raw `rawUpdate` (BREAKING for bracket-using subscribers)
+
+`update` publish events (and per-item updates inside `batch` events) now
+carry two fields:
+
+- `data` — the de-bracketed result. Sub-field updates (`arr[id].field`) and
+  terminal-bracket inserts/removes (`arr[id]: [els]` / `arr[id]: undefined`)
+  produce **the full post-update parent array** in `data` (no diff, no
+  positional placeholders). Values are sliced straight from the post-update
+  document — nothing is synthesized. `data` never contains mongo operators
+  (`$set`, `$unset`, `$pull`, `$[…]`) or flat dotted/bracket keys.
+- `rawUpdate` — the user's update spec exactly as it came in (top-level
+  shorthand or `$set`/`$unset` form, bracket paths preserved). Mongo
+  operators are allowed here. Always present on `update` events; safe to
+  ignore for consumers that only need to apply the result.
+
+`updateMany` events deliberately **do not** carry `rawUpdate` — mongo's
+`updateMany` doesn't return the list of affected `_id`-s, so the spec on
+its own is not actionable. The `data: { n, ok }` shape is unchanged from
+prior versions; consumers refetch via `findNewer*`.
+
+```ts
+await items.updateOne({ _id: 'r1' }, { 'postavke[p2].kolicina': 99 });
+// publish event:
+{
+    operation: 'update',
+    db: 'mydb',
+    collection: 'items',
+    data: {
+        _id: 'r1',
+        postavke: [
+            { _id: 'p1', kolicina: 1 },
+            { _id: 'p2', kolicina: 99 },
+            { _id: 'p3', kolicina: 3 },
+        ],
+    },
+    rawUpdate: { 'postavke[p2].kolicina': 99 },
+}
+```
+
+**Why breaking**: prior to this change, sub-field bracket updates leaked
+mongo positional placeholders (`postavke.$[f0].kolicina`) into `data` with
+`undefined` values, because `_removeUnchanged` looked up the post-translation
+keys literally on the result document. Subscribers that worked around this
+by reading the broken keys must switch to reading the parent array from
+`data` (e.g. `data.postavke`). Subscribers that only used non-bracket
+updates are unaffected.
+
+## 2.4.34
+
+### Bracketed arrays: no auto-`_id`, mixed full-object + bracketed writes
+
+Bracket-by-`_id` processing no longer injects an `_id` onto objects written
+into an array — the caller's value is stored as-is. A single update may now
+mix a whole-object array replacement with bracketed per-id paths against
+other arrays in the same call.
+
+## 2.4.33
+
+### Bracket-by-`_id` array paths — terminal-bracket insert and remove
+
+All write methods — `updateOne`, `save`, `update`, `upsert`, `upsertBatch`,
+and `updateCollections` — now recognize three shapes of `arr[<id>]` paths
+and route each to the appropriate mongo construct:
+
+| Path shape | Value | Operation |
+|---|---|---|
+| `arr[<id>].field` | any | `$set` / `$unset` with `arrayFilters` (existing behavior) |
+| `arr[<id>]` | array of elements (each with `_id`) | **idempotent insert/replace** — aggregation pipeline `$filter + $concatArrays` |
+| `arr[<id>]` | `undefined` (→ `$unset`) | **remove** — `$pull` on the parent array, or merged into the same pipeline stage when inserts are also present |
+
+Quoted and unquoted ids are equivalent: `arr[p0]`, `arr['p0']`, `arr["p0"]`
+all denote the same element.
+
+Inserts are idempotent: re-sending the same `_id` replaces the element in
+place rather than appending a duplicate. Inserts and removes against the
+same parent array are merged into one atomic `$filter + $concatArrays`
+stage, so remove+insert for the same id has no race window.
+
+Sub-field `arrayFilters` updates may not coexist with terminal-bracket
+inserts in the same update (mongo does not support `arrayFilters` on
+pipeline updates). The library throws a descriptive error in that case;
+split the update into two calls. Terminal-bracket removes alone remain
+compatible with `arrayFilters`. (Softened to drop+warn in 2.4.45, then
+fully supported in 2.4.49 — see above.)
+
+```ts
+// insert / replace by _id
+await items.updateOne({ _id: 'r1' }, {
+    "postavke['p0']": [{ _id: 'p0', value: 0 }],
+});
+
+// remove by _id
+await items.updateOne({ _id: 'r1' }, {
+    "postavke['p1']": undefined,
+});
+
+// combined insert + remove on the same array — single atomic stage
+await items.updateOne({ _id: 'r1' }, {
+    "postavke['p0']": [{ _id: 'p0', value: 0 }],
+    "postavke['p1']": undefined,
+});
+```
+
+See `README.md` → _Bracket-by-`_id` array paths_ for full reference.
+
+## 2.4.32
+
+### `GetNewerSpec.specId` — disambiguate duplicate-collection specs in `findNewerMany` / `findNewerManyStream`
+
+New optional field on `GetNewerSpec`. When set, results for that spec
+are keyed by `specId` in the `findNewerMany` response, and emitted as
+the third arg to `onChunk` in the streaming variant. Lets a single
+batched request carry multiple specs against the same `collection`
+without `Record<key, items[]>` collisions.
+
+```ts
+// Two specs against the same collection — disambiguated via specId
+const result = await mongo.findNewerMany([
+  { collection: 'users', timestamp: 0, query: { active: true },  specId: 'active'   },
+  { collection: 'users', timestamp: 0, query: { active: false }, specId: 'inactive' },
+]);
+result.active   // active users
+result.inactive // inactive users
+
+// Streaming — specId is forwarded to onChunk
+await mongo.findNewerManyStream(specs, async (collection, items, specId) => {
+  // specId === undefined when the originating spec did not set one
+});
+```
+
+- Backwards compatible — specs without `specId` are keyed by
+  `collection` exactly as before.
+- The streaming `onChunk` callback gains an optional third parameter;
+  existing two-arg callbacks continue to work unchanged.
+
+(Docs and the `test/findNewerManySpecId.mjs` suite landed in 2.4.33.)
+
+## 2.4.27
+
+### `findNewerRemoveFields` now also strips publish events
+
+Fields configured via `findNewerRemoveFields()` or `REMOVE_FIELDS_FOR_FINDNEWER` are now stripped from all publish event payloads (single-doc via `_publishAndAudit` and batch via `updateCollections`/`upsertBatch`), not just `findNewer*` query results.
+
+### `removeFieldsAlways()` — fields stripped from all find* and publish events
+
+New instance-level setting for fields that should never reach the client. Seeded from `REMOVE_FIELDS_ALWAYS` env var, configurable at runtime via `removeFieldsAlways()` on both `Mongo` and `Repo<T>`.
+
+```ts
+// getter — returns current field list
+users.removeFieldsAlways();                     // string[]
+
+// setter — accepts comma-separated string or array
+users.removeFieldsAlways('secret,internal');
+users.removeFieldsAlways(['secret', 'internal']);
+```
+
+These fields are removed from:
+
+- All `find*` results (find, findOne, findById, findByIds, findAll, findNewer, etc.)
+- All publish event payloads (single-doc and batch)
+
+## 2.4.25
+
+### `findNewerRemoveFields()` — runtime configuration of stripped fields
+
+`REMOVE_FIELDS_FOR_FINDNEWER` was previously only configurable via environment variable (read once at module load). It is now an instance-level setting configurable at runtime via `findNewerRemoveFields()` on both `Mongo` and `Repo<T>`.
+
+```ts
+// getter — returns current field list
+users.findNewerRemoveFields();                  // string[]
+
+// setter — accepts comma-separated string or array
+users.findNewerRemoveFields('_ts,_rev');
+users.findNewerRemoveFields(['_ts', '_rev']);
+```
+
+The env var `REMOVE_FIELDS_FOR_FINDNEWER` still seeds the initial value. All `findNewer`, `findNewerMany`, and `findNewerManyStream` calls use the instance field.
+
+### `auditCollections()` parameter made optional
+
+`auditCollections(arr?)` now accepts no argument as a getter (was previously required to pass a value).