@lossless.org/client 1.10.0 → 1.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lossless.org/client",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "private": false,
   "description": "One typed client for NoSQLDB, MongoDB, SQLDB, MariaDB, ClickHouse and S3 object storage.",
   "exports": {
@@ -85,7 +85,7 @@
     "@git.zone/tsrun": "3.0.0",
     "@git.zone/tstest": "6.3.0",
     "@lossless.org/nosqldb": "8.0.2",
-    "@lossless.org/nosqldb-qualified": "npm:@lossless.org/nosqldb@10.7.0",
+    "@lossless.org/nosqldb-qualified": "npm:@lossless.org/nosqldb@10.7.1",
     "@lossless.org/objectstorage": "10.3.1",
     "@lossless.org/sqldb": "0.2.3",
     "@push.rocks/qenv": "^6.1.3",

package/readme.md

@@ -102,7 +102,10 @@ Family imports preserve the established SmartData and SmartBucket names and cons
 | Migration-owned indexes | `toleratedIndexNames` on the model — named undeclared indexes are observed, never created, dropped or verified, and no longer make the topology divergent |
 | Partial index filters in inspection | `inspectNamespace()`, `inspectCollectionTopology()` and `getIndexInfo()` report a partial index's `partialFilterExpression` exactly as the backend lists it, as a frozen snapshot present only on a partial index |
 | Key-value store readiness | `EasyStore.ensureInitialized()` — installs the store's declared index at startup, outside any transaction window, so a first `readKey()`/`writeKey()` needs no index DDL |
+| Key-value store copies | `EasyStore` `readKey()`/`readAll()` return copies and `writeKey()`/`writeAll()`/`replace()` store copies, in the persisted BSON form, so a read result is a stable snapshot and a caller-side mutation never reaches the store |
 | Client deadlines | `timeoutMS` (1..120000) on every ordinary model read and write, instance `save()`/`saveIf()`/`delete()` included, on every exact call, and `session.withTransaction(callback, { timeoutMS })` for a whole transaction, retries and commit included; expiry rejects with `SmartdataPersistenceError` code `timeout`, and an exact write interrupted in flight with `ambiguous_write` |
+| Bounded database close | `db.close({ timeoutMs })` bounds the whole close — session cleanup, the optional database removal and the driver client's close — and rejects at its deadline with `SmartdataPersistenceError` code `timeout`, leaving the database `close_failed`; the driver's close keeps running until it settles on its own, and the next `close()` joins it |
+| Transactions ended by close | a `session.withTransaction()` whose session `db.close()` ends while it runs rejects with `SmartdataPersistenceError` code `unsupported_operation` — "nothing was committed" before the commit, "the commit outcome is unknown" during it — instead of resolving with the callback's result |
 | Cancellation | `signal` on every exact call, `atomicDeleteMany()` and `session.withTransaction(callback, { signal })`, which interrupts the session's operation in flight, rolls the attempt back and never commits after an abort |
 | Disposable test databases on a unix socket | `SmartdataTestDatabase.create({ connection: { socketPath } })` from `@lossless.org/client/testsupport` reaches an engine that listens only on a unix-domain socket, fault helpers included; the loopback `host`/`port` form is unchanged |
 
@@ -119,7 +122,7 @@ A bucket lookup sends one HeadBucket for the named bucket, never ListBuckets, so
 
 ### Document APIs that need a MongoDB backend
 
-The document model runs on both NoSQLDB and MongoDB, but several APIs do not mean the same thing on both. The NoSQLDB engine is qualified at 8.0.2 and 10.7.0 (see [Verification](#verification)); the two releases part on the grouped-totals and guarded-`$expr` rows below — 10.7.0 groups composite keys exactly and evaluates the guard, 8.0.2 does neither — on whether a migration can create a partial index or a collection validator at all, and on when a transaction learns of a write conflict.
+The document model runs on both NoSQLDB and MongoDB, but several APIs do not mean the same thing on both. The NoSQLDB engine is qualified at 8.0.2 and 10.7.1 (see [Verification](#verification)); the two releases part on the grouped-totals and guarded-`$expr` rows below — 10.7.1 groups composite keys exactly and evaluates the guard, 8.0.2 does neither — on whether a migration can create a partial index or a collection validator at all, on when a transaction learns of a write conflict, and on whether `$elemMatch` applies query operators to scalar array elements.
 
 `init()` asks the connected engine what it is with one `buildInfo` command and records the answer on the database as `engineIdentity` (`{ product, version }`). NoSQLDB answers with its own `nosqldb` identity document from 10.3.0 onward; a MongoDB server answers `buildInfo` without one; an engine that refuses the command — NoSQLDB 8.0.2 answers `CommandNotFound` — stays `{ product: 'unknown', version: null }`. The identity is what states `capabilities` on a plain `SmartdataDb`, and an unidentified engine states none at all, so every capability-gated call refuses. `NoSqlConnection` keeps stating the capabilities of its declared backend from construction on.
 
@@ -129,12 +132,13 @@ The document model runs on both NoSQLDB and MongoDB, but several APIs do not mea
 | the same with **two** `groupBy` fields | exact, `sums` included, on an engine that identifies itself as NoSQLDB 10.5.0 or newer: that release evaluates the composite group key per document. Below it the call is refused with `unsupported_operation` naming both fields and the single-field form, because the engine leaves the composite group key unresolved and answers with a single row whose group values are the literal field paths (`'$owner'`) and whose count is the whole filtered collection; the refusal is the guard against that wrong number, not a fix for it | exact |
 | guarded `$expr` atomic filters (`$add`, `$lte`, `$ifNull`) | exact on 10.6.0 and newer: the engine evaluates the client's fail-closed compilation (`$cond`, `$let`, `$isNumber`, `$type`), so the guard admits within the limit, refuses beyond it and never matches a stored value that is not a finite number. 8.0.2 rejects the compilation with `invalid argument: $cond` and leaves the document untouched | exact |
 | `watch()` change streams | unsupported. `NoSqlConnection` refuses with `unsupported_capability`, and so does a plain `SmartdataDb` whose engine identified itself; against an engine that answers no identity the refusal instead arrives from the engine as `CommandNotFound` once the change stream is read | supported on replica sets |
-| model-declared partial indexes (`partialFilterExpression`) | not expressible: the index-option type rejects it and the runtime refuses it with `invalid_configuration`. A client decision, not an engine limit on every release — 10.6.0 and newer create partial indexes, 8.0.2 refuses the option with `InvalidOptions` (72) — because one model declaration has to hold on every qualified backend. A migration may create one on 10.7.0; `toleratedIndexNames` accepts it and inspection reports its filter | not expressible, but a migration may own one; inspection reports its filter |
-| collection validators (`validator`, `validationLevel`, `validationAction`) | no client API; a migration owns a validator through the driver. 10.7.0 creates the collection, lists the options exactly as given and enforces them on every model write: a violating `insert()` or `atomicUpdate()` rejects with the engine's `DocumentValidationFailure` (121) and its `errInfo`, which the client passes through unchanged rather than mapping to a `SmartdataPersistenceError` code, and stores nothing. Models initialize on a validated collection like on any other. 8.0.2 refuses the option with `InvalidOptions` (72) and creates no collection, so a validator is never silently dropped | enforced; not exercised by the client's MongoDB suite |
-| write conflicts between transactions, and writes outside a transaction to a document a transaction holds | 10.7.0 (since 10.6.1) detects a conflict at the statement, as MongoDB does: the first writer wins, and the later transaction's statement rejects with the engine's `WriteConflict` (112) labelled `TransientTransactionError`, which the client passes through so `session.withTransaction()` re-runs that callback. A write outside a transaction waits until the transaction holding its document ends, then applies on top; the wait is bounded by the write's own `timeoutMS` and by the engine's fixed 60-second transaction lifetime, after which a waiting writer aborts the holder. Awaiting such a write inside the holding transaction's callback therefore stalls that transaction until one of the two expires. 8.0.2 detects the conflict at commit: the first transaction to commit wins, a write outside a transaction applies at once, and the transaction that wrote first re-runs. Both writes land on either engine; a callback must be safe to re-run and must not swallow the statement error | first writer wins at the statement and outside writes wait, MongoDB's documented rule; not exercised by the client's MongoDB suite |
+| model-declared partial indexes (`partialFilterExpression`) | not expressible: the index-option type rejects it and the runtime refuses it with `invalid_configuration`. A client decision, not an engine limit on every release — 10.6.0 and newer create partial indexes, 8.0.2 refuses the option with `InvalidOptions` (72) — because one model declaration has to hold on every qualified backend. A migration may create one on 10.7.1; `toleratedIndexNames` accepts it and inspection reports its filter | not expressible, but a migration may own one; inspection reports its filter |
+| collection validators (`validator`, `validationLevel`, `validationAction`) | no client API; a migration owns a validator through the driver. 10.7.0 and newer create the collection, list the options exactly as given and enforce them on every model write: a violating `insert()` or `atomicUpdate()` rejects with the engine's `DocumentValidationFailure` (121) and its `errInfo`, which the client passes through unchanged rather than mapping to a `SmartdataPersistenceError` code, and stores nothing. Models initialize on a validated collection like on any other. 8.0.2 refuses the option with `InvalidOptions` (72) and creates no collection, so a validator is never silently dropped | enforced; not exercised by the client's MongoDB suite |
+| write conflicts between transactions, and writes outside a transaction to a document a transaction holds | 10.7.1 (since 10.6.1) detects a conflict at the statement, as MongoDB does: the first writer wins, and the later transaction's statement rejects with the engine's `WriteConflict` (112) labelled `TransientTransactionError`, which the client passes through so `session.withTransaction()` re-runs that callback. A write outside a transaction waits until the transaction holding its document ends, then applies on top; the wait is bounded by the write's own `timeoutMS` and by the engine's fixed 60-second transaction lifetime, after which a waiting writer aborts the holder. Awaiting such a write inside the holding transaction's callback therefore stalls that transaction until one of the two expires. 8.0.2 detects the conflict at commit: the first transaction to commit wins, a write outside a transaction applies at once, and the transaction that wrote first re-runs. Both writes land on either engine; a callback must be safe to re-run and must not swallow the statement error | first writer wins at the statement and outside writes wait, MongoDB's documented rule; not exercised by the client's MongoDB suite |
+| value-form `$elemMatch` in read filters (`{ scores: { $elemMatch: { $gte: 80, $lt: 90 } } }`, `{ labels: { $not: { $elemMatch: { $nin: runnerLabels } } } }`) | exact on 10.7.1: the operators apply to each array element as a whole, so the range matches only a document with one score inside it and the claim selects a job only when every one of its labels is a runner label. 8.0.2 parses every operand as a query over embedded documents and refuses the value form with `TypeMismatch` (14). A non-document operand is refused on both, with MongoDB's `BadValue` (2) on 10.7.1 and 14 on 8.0.2. The client passes the operand through unchanged; the filter type admits the value form over scalar elements and the document form over embedded documents. Atomic filters (`atomicUpdate()` and the other atomic writes) accept no `$elemMatch` on any backend: the client refuses it with `invalid_argument` before any backend is contacted | exact |
 | aggregation-pipeline (array) updates | refused by the client with `invalid_argument` before any backend is contacted. A client-owned refusal, not an engine limit: both qualified engines apply a pipeline update themselves | same client refusal |
 
-`test/nosqldb/smartdb/test.engine-capability-boundary.node.ts` asserts the identity, grouped-totals, guarded-`$expr`, partial-index, collection-validator, write-conflict and pipeline-update rows against both qualified engines, so a boundary that moves shows up as a failing suite rather than as a changed number in a consumer. The two halves of the grouped-totals, guarded-`$expr` and write-conflict rows are separate tests, each bound to the engine that answers it, and the engine's own composite-key answer stays under assertion through the raw `aggregateGroupedTotals()` boundary — one literal row on 8.0.2, the two exact pairs on 10.7.0. The same boundary pins the rest of the engine's `$group` stage: a non-document accumulator is refused with `TypeMismatch` (14) on 10.7.0 while 8.0.2 answers it, and a `$cond` inside a composite key is evaluated per document on 10.7.0 while 8.0.2 answers its single literal row. It also pins whether a migration can create a partial index — 10.7.0 creates it and lists the filter, 8.0.2 refuses with 72 — and a collection validator — 10.7.0 creates and enforces it against model inserts and updates, 8.0.2 refuses with 72 — and which writer a conflict sends back: on 10.7.0 the later transaction fails at its statement and re-runs while a write outside a transaction waits for the holder's commit, on 8.0.2 the later transaction commits first and the holder re-runs. The `watch()` row is the contract refusal `ts/nosqldb/classes.collection.ts` states; the engine suite opens no change stream.
+`test/nosqldb/smartdb/test.engine-capability-boundary.node.ts` asserts the identity, grouped-totals, guarded-`$expr`, partial-index, collection-validator, write-conflict, `$elemMatch` and pipeline-update rows against both qualified engines, so a boundary that moves shows up as a failing suite rather than as a changed number in a consumer. The two halves of the grouped-totals, guarded-`$expr`, write-conflict and `$elemMatch` rows are separate tests, each bound to the engine that answers it, and the engine's own composite-key answer stays under assertion through the raw `aggregateGroupedTotals()` boundary — one literal row on 8.0.2, the two exact pairs on 10.7.1. The same boundary pins the rest of the engine's `$group` stage: a non-document accumulator is refused with `TypeMismatch` (14) on 10.7.1 while 8.0.2 answers it, and a `$cond` inside a composite key is evaluated per document on 10.7.1 while 8.0.2 answers its single literal row. It also pins whether a migration can create a partial index — 10.7.1 creates it and lists the filter, 8.0.2 refuses with 72 — and a collection validator — 10.7.1 creates and enforces it against model inserts and updates, 8.0.2 refuses with 72 — which writer a conflict sends back: on 10.7.1 the later transaction fails at its statement and re-runs while a write outside a transaction waits for the holder's commit, on 8.0.2 the later transaction commits first and the holder re-runs — and what `$elemMatch` answers through `getInstances()`: 10.7.1 matches the documented range and the `$not`/`$elemMatch`/`$nin` claim exactly as the MongoDB filter suite asserts them, 8.0.2 refuses both with 14, and a non-document operand is refused with 2 on 10.7.1 and 14 on 8.0.2. The `watch()` row is the contract refusal `ts/nosqldb/classes.collection.ts` states; the engine suite opens no change stream.
 
 ## Relational SQL
 
@@ -214,14 +218,14 @@ Qualified engines:
 
 | Component | Qualified versions |
 | --- | --- |
-| NoSQLDB engine | **8.0.2 and 10.7.0** — the same `test/nosqldb/smartdb/` suite runs against both, through the single engine seam in `test/nosqldb/helpers/smartdb.ts`; `NOSQLDB_ENGINE=qualified` selects 10.7.0 |
+| NoSQLDB engine | **8.0.2 and 10.7.1** — the same `test/nosqldb/smartdb/` suite runs against both, through the single engine seam in `test/nosqldb/helpers/smartdb.ts`; `NOSQLDB_ENGINE=qualified` selects 10.7.1 |
 | MongoDB | 8.0.26 replica sets |
 | ObjectStorage | 10.3.1 |
 | SQLDB | 0.2.3 |
 | MariaDB | 11.8 |
 | ClickHouse | 25.8 |
 
-Both engine versions run the whole document suite. They part on asserted boundaries — 10.7.0 groups composite keys exactly and answers two-field grouped totals, evaluates guarded `$expr` filters, creates migration-owned partial indexes and collection validators and reports a transaction write conflict at the statement, 8.0.2 does none of these, reports the conflict at commit, and the client refuses the two-field form there — which [Document APIs that need a MongoDB backend](#document-apis-that-need-a-mongodb-backend) states row by row. Text search, the Lucene adapter and the broad read-filter surface are exercised against MongoDB only. `pnpm run test:minio` uses a digest-pinned MinIO image: `sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e`. That MinIO version enforces the tested conditional uploads but does not enforce conditional deletion; its exact-purge capability is correctly unavailable. ObjectStorage passes both live probes. AWS S3 has not been qualified against a live account in this migration; no universal S3 exact-operation guarantee is inferred from the SDK.
+Both engine versions run the whole document suite. They part on asserted boundaries — 10.7.1 groups composite keys exactly and answers two-field grouped totals, evaluates guarded `$expr` filters, creates migration-owned partial indexes and collection validators, reports a transaction write conflict at the statement and matches value-form `$elemMatch`, 8.0.2 does none of these, reports the conflict at commit, and the client refuses the two-field form there — which [Document APIs that need a MongoDB backend](#document-apis-that-need-a-mongodb-backend) states row by row. Text search, the Lucene adapter and the broad read-filter surface are exercised against MongoDB only. `pnpm run test:minio` uses a digest-pinned MinIO image: `sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e`. That MinIO version enforces the tested conditional uploads but does not enforce conditional deletion; its exact-purge capability is correctly unavailable. ObjectStorage passes both live probes. AWS S3 has not been qualified against a live account in this migration; no universal S3 exact-operation guarantee is inferred from the SDK.
 
 ## License and Legal Information
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@lossless.org/client',
-  version: '1.10.0',
+  version: '1.12.0',
   description: 'One typed client for NoSQLDB, MongoDB, SQLDB, MariaDB, ClickHouse and S3 object storage.'
 }

package/ts/nosqldb/classes.db.ts

@@ -2,7 +2,11 @@ import * as plugins from './plugins.js';
 
 import { SmartdataCollection } from './classes.collection.js';
 import { EasyStore } from './classes.easystore.js';
-import { SmartdataPersistenceError } from './classes.persistence.js';
+import {
+  createSmartdataTimeoutError,
+  isMongoDeadlineError,
+  SmartdataPersistenceError,
+} from './classes.persistence.js';
 import { SmartdataMongoAdministration } from './classes.mongoadministration.js';
 import {
   createSmartdataSession,
@@ -78,7 +82,14 @@ export interface ISmartdataInitOptions {
 }
 
 export interface ISmartdataCloseOptions {
-  /** Total deadline for removal, including preceding session cleanup (1..120000 ms). */
+  /**
+   * Deadline for the whole close (1..120000 ms): session cleanup, the optional
+   * database removal and the driver client's close. When it expires the call
+   * rejects with `SmartdataPersistenceError` code `timeout` and the database is
+   * `close_failed`. Cleanup still running at that point is not abandoned: it
+   * stays owned by this `SmartdataDb`, and the next `close()` joins it.
+   * Without `timeoutMs`, close waits for every cleanup to settle.
+   */
   timeoutMs?: number;
   dropDatabase?: {
     expectedDatabaseName: string;
@@ -120,6 +131,9 @@ type TSmartdataDbLifecycleState =
 
 type TSmartdataDbLifecycleOperation = 'init' | 'close';
 
+/** How the driver's close of an owned client ended, kept until a close() has observed it. */
+type TSmartdataClientCloseOutcome = { failed: false } | { failed: true; error: unknown };
+
 const readinessDefaultTimeoutMs = 2_000;
 const readinessMaximumTimeoutMs = 30_000;
 
@@ -177,6 +191,8 @@ export class SmartdataDb {
   private lifecycleEpoch = 0;
   private activeLifecycleOperation: TSmartdataDbLifecycleOperation | null = null;
   private pendingClient?: plugins.mongodb.MongoClient;
+  /** The driver's close of the owned client until a close() has observed its outcome. */
+  private clientClosing?: Promise<TSmartdataClientCloseOutcome>;
   private engineIdentityState: ISmartdataEngineIdentity = unidentifiedSmartdataEngine;
   private capabilitiesState: ICapabilities | undefined;
 
@@ -327,7 +343,8 @@ export class SmartdataDb {
   }
 
   /**
-   * closes the connection to the databse
+   * Closes the connection to the database. `timeoutMs` bounds the whole call;
+   * see `ISmartdataCloseOptions`.
    */
   public async close(optionsArg: ISmartdataCloseOptions = {}): Promise<void> {
     this.assertLifecycleOperationCanBegin('close');
@@ -341,7 +358,14 @@ export class SmartdataDb {
     try {
       const closeErrors: unknown[] = [];
       try {
-        await invalidateSmartdataSessions(this);
+        const invalidation = invalidateSmartdataSessions(this, budget?.cleanupOptions());
+        // A session whose cleanup outlives the deadline stays owned and invalidated
+        // until the next close() ends it. Its abort already carries the same
+        // deadline, so a late failure can only be that deadline, which this close
+        // reports as `timeout`.
+        invalidation.catch(() => {});
+        if (budget) await budget.waitFor(invalidation);
+        await invalidation;
       } catch (errorArg) {
         closeErrors.push(
           ...(unwrapSmartdataSessionInvalidationErrors(errorArg) ?? [errorArg]),
@@ -360,16 +384,28 @@ export class SmartdataDb {
           closeErrors.push(errorArg);
         }
       }
-      try {
-        await mongoDbClient?.close();
-        this.pendingClient = undefined;
-      } catch (errorArg) {
-        closeErrors.push(errorArg);
+      if (mongoDbClient) {
+        const clientClosing = this.closeOwnedClient(mongoDbClient);
+        try {
+          if (budget) await budget.waitFor(clientClosing);
+          // Settled in time: this close observes the outcome, and a later one starts afresh.
+          const outcome = await clientClosing;
+          this.clientClosing = undefined;
+          if (outcome.failed) throw outcome.error;
+          this.pendingClient = undefined;
+        } catch (errorArg) {
+          closeErrors.push(errorArg);
+        }
       }
       if (closeErrors.length > 0) {
         this.transitionLifecycle('close_failed');
-        if (budget) throw new SmartdataPersistenceError('unsupported_operation',
-          'SmartData database cleanup failed; close must be retried.');
+        if (budget) {
+          throw budget.expired() || closeErrors.some(isMongoDeadlineError)
+            ? createSmartdataTimeoutError(
+              'SmartData database close exceeded its deadline; close must be retried.')
+            : new SmartdataPersistenceError('unsupported_operation',
+              'SmartData database cleanup failed; close must be retried.');
+        }
         if (closeErrors.length === 1) {
           throw closeErrors[0];
         }
@@ -653,6 +689,22 @@ export class SmartdataDb {
     return this.mongoDb;
   }
 
+  /**
+   * Starts the driver's close of an owned client, or joins the one a previous
+   * close() started. The driver offers no deadline for it, so a close that
+   * outlived its caller keeps running, and its outcome — a rejection included —
+   * waits here for the next close() instead of being lost.
+   */
+  private closeOwnedClient(
+    clientArg: plugins.mongodb.MongoClient,
+  ): Promise<TSmartdataClientCloseOutcome> {
+    this.clientClosing ??= clientArg.close().then(
+      (): TSmartdataClientCloseOutcome => ({ failed: false }),
+      (errorArg: unknown): TSmartdataClientCloseOutcome => ({ failed: true, error: errorArg }),
+    );
+    return this.clientClosing;
+  }
+
   private endLifecycleOperation(operationArg: TSmartdataDbLifecycleOperation): void {
     if (this.activeLifecycleOperation === operationArg) {
       this.activeLifecycleOperation = null;

package/ts/nosqldb/classes.doc.ts

@@ -561,7 +561,24 @@ export type TSmartdataOptionalNullPredicate<TValue> =
 type InValues<T> = ReadonlyArray<ElementOf<T> | TSmartdataOptionalNullPredicate<T>>;
 
 // Type that allows MongoDB operators on leaf values while maintaining nested type safety
-export type MongoFilterCondition<T> = T | TSmartdataOptionalNullPredicate<T> | {
+export type MongoFilterCondition<T> =
+  | T
+  | TSmartdataOptionalNullPredicate<T>
+  | TSmartdataFilterOperators<T>;
+
+/**
+ * The operand of `$elemMatch`: a query on each element, the document form, or
+ * an operator document applied to each element as a whole, the value form
+ * (`{ $gte: 80, $lt: 90 }`). Elements that are all documents take only the
+ * document form; any other element type takes either, so element unions that
+ * include documents, nullable documents and `unknown` keep the document form.
+ */
+type TSmartdataElemMatchOperand<TElement> = [TElement] extends [object]
+  ? MongoFilter<TElement>
+  : MongoFilter<TElement> | TSmartdataFilterOperators<TElement>;
+
+/** The operator document of a field condition. */
+type TSmartdataFilterOperators<T> = {
   $eq?: T | TSmartdataOptionalNullPredicate<T>;
   $ne?: T | TSmartdataOptionalNullPredicate<T>;
   $gt?: T;
@@ -575,7 +592,7 @@ export type MongoFilterCondition<T> = T | TSmartdataOptionalNullPredicate<T> | {
   $regex?: string | RegExp;
   $options?: string;
   $all?: T extends ReadonlyArray<infer U> ? ReadonlyArray<U> : never;
-  $elemMatch?: T extends ReadonlyArray<infer U> ? MongoFilter<U> : never;
+  $elemMatch?: T extends ReadonlyArray<infer U> ? TSmartdataElemMatchOperand<U> : never;
   $size?: T extends ReadonlyArray<any> ? number : never;
   $not?: MongoFilterCondition<T>;
 };

package/ts/nosqldb/classes.easystore.ts

@@ -34,6 +34,24 @@ const getEasyStoreClassForDb = <T>(smartdataDbArg: SmartdataDb) => {
   return SmartdataEasyStore;
 };
 
+/**
+ * Copies a store value into the form the store persists: undefined object
+ * properties are dropped, an undefined array element becomes null and every
+ * value takes its BSON form, exactly as a save and a later read from the
+ * database do. The copy shares no object with the argument, so neither side can
+ * change the other afterwards. A value BSON cannot encode (a cycle, for
+ * example) throws here, before the store's cache is touched.
+ */
+const copyInPersistedForm = <TValue>(valueArg: TValue): TValue => {
+  if (valueArg === undefined) {
+    return valueArg;
+  }
+  const document = plugins.mongodb.BSON.deserialize(
+    plugins.mongodb.BSON.serialize({ value: valueArg }, { ignoreUndefined: true }),
+  );
+  return document.value as TValue;
+};
+
 /**
  * EasyStore allows the storage of easy objects. It also allows easy sharing of the object between different instances
  */
@@ -98,65 +116,131 @@ export class EasyStore<T> {
   }
 
   /**
-   * reads all keyValue pairs at once and returns them
+   * Runs store operations one at a time, in the order they were called. Every
+   * read and write of this instance goes through here, so a write builds its
+   * next state from the state every earlier write left, and a read never sees
+   * the state of a write whose save has not resolved yet. A rejected operation
+   * does not stop the ones queued behind it.
+   */
+  private operationQueue: Promise<void> = Promise.resolve();
+  private runExclusive<TResult>(operationArg: () => Promise<TResult>): Promise<TResult> {
+    const result = this.operationQueue.then(operationArg);
+    this.operationQueue = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    return result;
+  }
+
+  /**
+   * Persists `nextDataArg` as the store's data. The document's `save()` writes
+   * the instance's own fields, so the next state is installed for the save and
+   * the previous one is put back when the save rejects: a failed write leaves
+   * the cache as it was. Callers hold the operation queue.
    */
-  public async readAll() {
-    const easyStore = await this.getEasyStore();
-    return easyStore.data;
+  private async commit(
+    easyStoreArg: InstanceType<typeof this.easyStoreClass>,
+    nextDataArg: Partial<T>,
+  ): Promise<void> {
+    const previousData = easyStoreArg.data;
+    easyStoreArg.data = nextDataArg;
+    try {
+      await easyStoreArg.save();
+    } catch (error) {
+      easyStoreArg.data = previousData;
+      throw error;
+    }
   }
 
   /**
-   * reads a keyValueFile from disk
+   * reads all keyValue pairs at once and returns them as a copy in the
+   * persisted form: mutating the result does not change the store, and later
+   * writes do not change the result.
+   */
+  public async readAll(): Promise<Partial<T>> {
+    return this.runExclusive(async () => {
+      const easyStore = await this.getEasyStore();
+      return copyInPersistedForm(easyStore.data);
+    });
+  }
+
+  /**
+   * reads one key and returns a copy of its value in the persisted form, or
+   * `undefined` when the key is absent
    */
   public async readKey<TKey extends keyof T>(keyArg: TKey): Promise<Partial<T>[TKey]> {
-    const easyStore = await this.getEasyStore();
-    return easyStore.data[keyArg];
+    return this.runExclusive(async () => {
+      const easyStore = await this.getEasyStore();
+      return copyInPersistedForm(easyStore.data[keyArg]);
+    });
   }
 
   /**
-   * writes a specific key to the keyValueStore
+   * writes a specific key to the keyValueStore. The store keeps a copy, so
+   * mutating `valueArg` afterwards does not change the store. When the save
+   * rejects, the store keeps its previous state.
    */
   public async writeKey<TKey extends keyof T>(keyArg: TKey, valueArg: T[TKey]) {
-    const easyStore = await this.getEasyStore();
-    easyStore.data[keyArg] = valueArg;
-    await easyStore.save();
+    const value = copyInPersistedForm(valueArg);
+    await this.runExclusive(async () => {
+      const easyStore = await this.getEasyStore();
+      const nextData: Partial<T> = { ...easyStore.data };
+      nextData[keyArg] = value;
+      await this.commit(easyStore, nextData);
+    });
   }
 
+  /**
+   * deletes a key. When the save rejects, the store keeps its previous state.
+   */
   public async deleteKey(keyArg: keyof T) {
-    const easyStore = await this.getEasyStore();
-    delete easyStore.data[keyArg];
-    await easyStore.save();
+    await this.runExclusive(async () => {
+      const easyStore = await this.getEasyStore();
+      const nextData: Partial<T> = { ...easyStore.data };
+      delete nextData[keyArg];
+      await this.commit(easyStore, nextData);
+    });
   }
 
   /**
    * merges all keyValue pairs from the object argument into the store.
    * Existing keys that are not present in `keyValueObject` are preserved.
    * To overwrite the entire store and drop missing keys, use `replace()`.
+   * The store keeps a copy, so mutating `keyValueObject` afterwards does not
+   * change the store. When the save rejects, the store keeps its previous state.
    */
   public async writeAll(keyValueObject: Partial<T>) {
-    const easyStore = await this.getEasyStore();
-    easyStore.data = { ...easyStore.data, ...keyValueObject };
-    await easyStore.save();
+    const values = copyInPersistedForm(keyValueObject);
+    await this.runExclusive(async () => {
+      const easyStore = await this.getEasyStore();
+      await this.commit(easyStore, { ...easyStore.data, ...values });
+    });
   }
 
   /**
    * atomically replaces the entire store with the given object.
    * Unlike `writeAll` (which merges), `replace` clears any keys not
    * present in `keyValueObject`. Useful when you need to drop a key.
+   * The store keeps a copy, so mutating `keyValueObject` afterwards does not
+   * change the store. When the save rejects, the store keeps its previous state.
    */
   public async replace(keyValueObject: Partial<T>) {
-    const easyStore = await this.getEasyStore();
-    easyStore.data = { ...keyValueObject };
-    await easyStore.save();
+    const values = copyInPersistedForm(keyValueObject);
+    await this.runExclusive(async () => {
+      const easyStore = await this.getEasyStore();
+      await this.commit(easyStore, values);
+    });
   }
 
   /**
-   * wipes a key value store from disk
+   * wipes a key value store from disk. When the save rejects, the store keeps
+   * its previous state.
    */
   public async wipe() {
-    const easyStore = await this.getEasyStore();
-    easyStore.data = {};
-    await easyStore.save();
+    await this.runExclusive(async () => {
+      const easyStore = await this.getEasyStore();
+      await this.commit(easyStore, {});
+    });
   }
 
   public async cleanUpEphemeral() {

package/ts/nosqldb/classes.operationbudget.ts

@@ -46,6 +46,12 @@ export class SmartdataOperationBudget {
     }
   }
 
+  /** Whether the deadline itself has passed; a caller's signal does not count. */
+  public expired(): boolean {
+    if (performance.now() >= this.expiresAt) this.controller.abort();
+    return this.controller.signal.aborted;
+  }
+
   public remainingMs(): number {
     this.check();
     return this.cleanupOptions().timeoutMS;