@lossless.org/client 1.20.2 → 1.21.1

package/ts/nosqldb/classes.session.ts

@@ -1,6 +1,7 @@
 import * as plugins from './plugins.js';
 
 import type { SmartdataCollection } from './classes.collection.js';
+import { getOrderingIdentityFields } from './classes.collectiontopology.js';
 import type { SmartdataDb } from './classes.db.js';
 import {
   SmartdataOperationDeadline,
@@ -22,6 +23,16 @@ import {
   type ISmartdataWrite,
   type TSmartdataWriteKind,
 } from './classes.writeobserver.js';
+import {
+  captureSmartdataCollectionChange,
+  captureSmartdataReadChange,
+  hasSmartdataReadScope,
+  hasSmartdataReadSets,
+  observeSmartdataRead,
+  runSmartdataWrite,
+  type ISmartdataReadRecorder,
+  type ISmartdataReadSpec,
+} from './classes.readtracker.js';
 
 interface ISmartdataSessionBinding {
   session: SmartdataSession;
@@ -43,14 +54,28 @@ interface ISmartdataSessionBinding {
   transactionCommitReached: boolean;
   /** Set when the session ended while a transaction ran, stating how far the transaction had got. */
   transactionEnded?: TSmartdataTransactionEnd;
-  /** The write reports of the current attempt, delivered once the transaction committed. */
-  transactionWrites: Array<() => void>;
+  /**
+   * The writes of the current attempt: their reports, delivered once the
+   * transaction committed, and their changes to open read sets, also applied
+   * when the commit outcome is unknown.
+   */
+  transactionWrites: ISmartdataTransactionWrite[];
   operationSettled?: Promise<void>;
   resolveOperationSettled?: () => void;
   invalidated: boolean;
   closing?: Promise<void>;
 }
 
+interface ISmartdataTransactionWrite {
+  deliver?: () => void;
+  changeReads?: () => void;
+}
+
+/** A transaction whose commit outcome is unknown may have applied its writes. */
+const changeReadsOfTransaction = (writesArg: readonly ISmartdataTransactionWrite[]): void => {
+  for (const write of writesArg) write.changeReads?.();
+};
+
 /** How far a transaction had got when its session ended outside the callback's control. */
 type TSmartdataTransactionEnd = 'before_commit' | 'during_commit';
 
@@ -445,7 +470,7 @@ export class SmartdataSession {
     };
     let result: TResult | undefined;
     let transactionEnded: TSmartdataTransactionEnd | undefined;
-    let committedWrites: Array<() => void> = [];
+    let committedWrites: ISmartdataTransactionWrite[] = [];
     try {
       result = timeoutMS === undefined
         ? await binding.rawSession.withTransaction(runAttempt)
@@ -454,6 +479,7 @@ export class SmartdataSession {
       committedWrites = binding.transactionWrites;
     } catch (errorArg) {
       const { error, outcome } = settleTransactionRejection(errorArg);
+      if (outcome === 'unknown') changeReadsOfTransaction(binding.transactionWrites);
       throw rejectTransaction(error, outcome);
     } finally {
       binding.transactionActive = false;
@@ -466,13 +492,13 @@ export class SmartdataSession {
       binding.transactionWrites = [];
     }
     if (transactionEnded) {
-      throw rejectTransaction(
-        createTransactionSessionEndedError(transactionEnded),
-        commitOutcomeOfTransactionEnd(transactionEnded),
-      );
+      const outcome = commitOutcomeOfTransactionEnd(transactionEnded);
+      if (outcome === 'unknown') changeReadsOfTransaction(committedWrites);
+      throw rejectTransaction(createTransactionSessionEndedError(transactionEnded), outcome);
     }
-    for (const deliverWrite of committedWrites) {
-      deliverWrite();
+    changeReadsOfTransaction(committedWrites);
+    for (const write of committedWrites) {
+      write.deliver?.();
     }
     return result;
   }
@@ -676,12 +702,14 @@ export const leaseOrdinarySmartdataSession = (
     if (
       optionsArg.ordinaryWrite
       && sessionArg?.inTransaction()
-      && hasSmartdataWriteObservers(ownerArg)
+      && (hasSmartdataWriteObservers(ownerArg) || hasSmartdataReadSets(ownerArg))
     ) {
       // Only an owned transaction tells SmartData whether it committed.
       throw new SmartdataPersistenceError(
         'unsupported_operation',
-        'Writes of an observed database run in transactions of db.createSession(), not raw driver sessions.',
+        hasSmartdataWriteObservers(ownerArg)
+          ? 'Writes of an observed database run in transactions of db.createSession(), not raw driver sessions.'
+          : 'Writes of a database with open read sets run in transactions of db.createSession(), not raw driver sessions.',
       );
     }
     return { rawSession: sessionArg, release: () => {} };
@@ -755,7 +783,9 @@ export const settleSmartdataOperationError = (
 /**
  * Runs one model operation on the ordinary session boundary: the owned
  * session lease, the operation's client deadline and signal, and the mapping
- * of an expired driver deadline to the `timeout` persistence error.
+ * of an expired driver deadline to the `timeout` persistence error. A write
+ * that fails once started may still have applied, so it changes every open
+ * read set that read its collection.
  */
 export const runWithOrdinarySmartdataSession = async <TResult>(
   sessionArg: TSmartdataOrdinarySession | undefined,
@@ -769,10 +799,19 @@ export const runWithOrdinarySmartdataSession = async <TResult>(
   optionsArg.signal?.throwIfAborted();
   const lease = leaseOrdinarySmartdataSession(sessionArg, ownerArg, optionsArg);
   let deadline: SmartdataOperationDeadline | undefined;
+  let writeStarted = false;
   try {
     deadline = resolveSmartdataOperationDeadline(sessionArg, optionsArg);
-    return await operationArg(lease.rawSession, deadline);
+    if (!optionsArg.ordinaryWrite) {
+      return await operationArg(lease.rawSession, deadline);
+    }
+    const writeDeadline = deadline;
+    writeStarted = true;
+    return await runSmartdataWrite(ownerArg, () => operationArg(lease.rawSession, writeDeadline));
   } catch (errorArg) {
+    if (writeStarted && optionsArg.collectionName) {
+      reportSmartdataWriteFailure(ownerArg, sessionArg, optionsArg.collectionName);
+    }
     throw deadline
       ? settleSmartdataOperationError(sessionArg, deadline, errorArg)
       : normalizeDeadlineError(errorArg);
@@ -782,50 +821,147 @@ export const runWithOrdinarySmartdataSession = async <TResult>(
 };
 
 /**
- * Reports one acknowledged write to the owner's write observers: at once, or,
- * inside an owned transaction, after it committed. A transaction that rolls
- * back, or whose commit outcome is unknown, reports nothing, and a retried
- * attempt reports only its own writes.
+ * Buffers one write of an owned transaction's current attempt. A write that
+ * settles after its attempt ended rolls back with that attempt.
+ */
+const bufferTransactionWrite = (
+  bindingArg: ISmartdataSessionBinding,
+  writeArg: ISmartdataTransactionWrite,
+): void => {
+  const attempt = transactionContext.getStore()?.attempt;
+  if (attempt !== undefined && attempt === bindingArg.transactionAttempt) {
+    bindingArg.transactionWrites.push(writeArg);
+  }
+};
+
+/**
+ * Reports one acknowledged write to the owner's write observers and open read
+ * sets: at once, or, inside an owned transaction, after it committed. A
+ * transaction that rolls back reports nothing, one whose commit outcome is
+ * unknown changes the read sets only, and a retried attempt reports only its
+ * own writes. Read sets change before observers hear of the write.
  */
 export const reportSmartdataWrite = (
   ownerArg: SmartdataDb,
   sessionArg: TSmartdataOrdinarySession | undefined,
   writeArg: ISmartdataWrite,
 ): void => {
-  // A raw driver transaction passed its lease while nobody observed, and
-  // whether it commits is never known here.
-  if (!isSmartdataSession(sessionArg) && sessionArg?.inTransaction()) return;
+  if (!isSmartdataSession(sessionArg) && sessionArg?.inTransaction()) {
+    // A raw driver transaction passed its lease while nobody observed or
+    // tracked, and whether it commits is never known here.
+    captureSmartdataCollectionChange(ownerArg, writeArg.collection, false)?.();
+    return;
+  }
+  const binding = isSmartdataSession(sessionArg) ? bindings.get(sessionArg) : undefined;
+  const buffered = binding?.transactionActive === true;
+  const changeReads = captureSmartdataReadChange(ownerArg, writeArg, buffered);
   const deliver = captureSmartdataWrite(ownerArg, writeArg);
-  if (!deliver) return;
+  if (!changeReads && !deliver) return;
+  if (binding && buffered) {
+    bufferTransactionWrite(binding, { deliver, changeReads });
+    return;
+  }
+  changeReads?.();
+  deliver?.();
+};
+
+/**
+ * Reports a write to the collection that failed after it was sent: it may
+ * still have applied, so every open read set that read the collection
+ * changes, inside an owned transaction once it commits.
+ */
+export const reportSmartdataWriteFailure = (
+  ownerArg: SmartdataDb,
+  sessionArg: TSmartdataOrdinarySession | undefined,
+  collectionNameArg: string,
+): void => {
   const binding = isSmartdataSession(sessionArg) ? bindings.get(sessionArg) : undefined;
-  if (binding?.transactionActive) {
-    // A write that settles after its attempt ended rolls back with that attempt.
-    const attempt = transactionContext.getStore()?.attempt;
-    if (attempt !== undefined && attempt === binding.transactionAttempt) {
-      binding.transactionWrites.push(deliver);
-    }
+  const buffered = binding?.transactionActive === true;
+  const changeReads = captureSmartdataCollectionChange(ownerArg, collectionNameArg, buffered);
+  if (!changeReads) return;
+  if (binding && buffered) {
+    bufferTransactionWrite(binding, { changeReads });
     return;
   }
-  deliver();
+  changeReads();
 };
 
-/** Reports one acknowledged write of a model collection; see `reportSmartdataWrite`. */
+/**
+ * Reports one acknowledged write of a model collection; see
+ * `reportSmartdataWrite`. `readImagesArg` states which document states the
+ * documents are and the update applied; without it, read sets count the
+ * write as changing every read of the collection.
+ */
 export const reportSmartdataCollectionWrite = (
   collectionArg: SmartdataCollection<any>,
   sessionArg: TSmartdataOrdinarySession | undefined,
   kindArg: TSmartdataWriteKind,
   documentsArg: readonly object[] | null,
   selectorArg?: unknown,
+  readImagesArg?: Pick<ISmartdataWrite, 'images' | 'update'>,
 ): void => {
+  const schema = collectionArg.getBoundModelSchema();
   reportSmartdataWrite(collectionArg.smartdataDb, sessionArg, {
     collection: collectionArg.collectionName,
     kind: kindArg,
     documents: documentsArg,
     selector: selectorArg,
-    identityDocumentIdField: collectionArg.getBoundModelSchema()?.identityAsDocumentId,
+    identityDocumentIdField: schema?.identityAsDocumentId,
+    identityFields: identityFieldsOfSchema(schema),
+    ...readImagesArg,
   });
 };
 
+/** The identity fields a read or write names a document by besides `_id`. */
+const identityFieldsOfSchema = (
+  schemaArg: ReturnType<SmartdataCollection<any>['getBoundModelSchema']>,
+): readonly string[] | undefined =>
+  schemaArg && !schemaArg.identityAsDocumentId && schemaArg.identityFields.length > 0
+    ? schemaArg.identityFields
+    : undefined;
+
+/**
+ * Registers one read of a model collection with the open read sets of the
+ * current async context, right before it is issued; `undefined` when none is
+ * open. See `observeSmartdataRead`.
+ */
+export const trackSmartdataRead = (
+  collectionArg: SmartdataCollection<any>,
+  sessionArg: TSmartdataOrdinarySession | undefined,
+  specArg: Omit<ISmartdataReadSpec, 'collection' | 'identityFields' | 'orderingIdentityFields'>,
+): ISmartdataReadRecorder | undefined => trackSmartdataModelRead(
+  collectionArg.smartdataDb,
+  collectionArg.collectionName,
+  collectionArg.getBoundModelSchema(),
+  sessionArg,
+  specArg,
+);
+
+/** `trackSmartdataRead` for a read that names its model by schema rather than collection. */
+export const trackSmartdataModelRead = (
+  dbArg: SmartdataDb,
+  collectionNameArg: string,
+  schemaArg: ReturnType<SmartdataCollection<any>['getBoundModelSchema']>,
+  sessionArg: TSmartdataOrdinarySession | undefined,
+  specArg: Omit<ISmartdataReadSpec, 'collection' | 'identityFields' | 'orderingIdentityFields'>,
+): ISmartdataReadRecorder | undefined => {
+  if (!hasSmartdataReadScope()) return undefined;
+  let inTransaction: boolean;
+  try {
+    inTransaction = isOrdinarySessionInTransaction(sessionArg);
+  } catch {
+    // An ended session's read fails; a set must not count it as followed.
+    inTransaction = true;
+  }
+  const identityFields = identityFieldsOfSchema(schemaArg);
+  return observeSmartdataRead(dbArg, {
+    ...specArg,
+    collection: collectionNameArg,
+    identityFields,
+    orderingIdentityFields: schemaArg && identityFields ? getOrderingIdentityFields(schemaArg) : undefined,
+  }, inTransaction);
+};
+
 /**
  * Ends every session of the owner. `endOptionsArg.timeoutMS` is the driver's
  * deadline for aborting a transaction a session still holds.

package/ts/nosqldb/classes.storedinspection.ts

@@ -3,7 +3,9 @@ import type { SmartdataDb } from './classes.db.js';
 import { convertFilterForMongoDb } from './classes.doc.js';
 import { SmartdataPersistenceError } from './classes.persistence.js';
 import { runCursorOperation } from './classes.cursoroperation.js';
-import { acquireSmartdataSession, isSmartdataSession, type SmartdataSession } from './classes.session.js';
+import {
+  acquireSmartdataSession, isSmartdataSession, trackSmartdataModelRead, type SmartdataSession,
+} from './classes.session.js';
 import {
   collectionTopologyDbInspectionSymbol, collectionModelSchemaResolverSymbol,
 } from './classes.collectiontopology.js';
@@ -79,6 +81,9 @@ const readStoredDocuments = async (
   let page: { documents: plugins.mongodb.Document[]; hasMore: boolean };
   try {
     page = await dbArg[collectionTopologyDbInspectionSymbol](async (mongoDbArg) => {
+      const tracked = trackSmartdataModelRead(dbArg, schema.collectionName, schema, opts.session, {
+        kind: 'documents', filter, sort: { _id: 1 }, matches: skip > 0, limited: true,
+      });
       const cursor = mongoDbArg.collection(schema.collectionName).find(filter, {
         sort: { _id: 1 }, skip, limit: limit + 1, batchSize: 1,
         timeoutMS, timeoutMode: 'cursorLifetime', signal: opts.signal, session: lease?.rawSession,
@@ -88,8 +93,15 @@ const readStoredDocuments = async (
         let bytes = 0;
         while (true) {
           const next = await cursorArg.next();
-          if (next === null) return { documents, hasMore: false };
-          if (documents.length === limit) return { documents, hasMore: true };
+          if (next === null) {
+            tracked?.settle();
+            return { documents, hasMore: false };
+          }
+          tracked?.record(next);
+          if (documents.length === limit) {
+            tracked?.settle();
+            return { documents, hasMore: true };
+          }
           bytes += plugins.mongodb.BSON.calculateObjectSize(next);
           if (bytes > maxBytes) throw new SmartdataPersistenceError('unsupported_operation',
             'Stored inspection exceeds its byte budget.');

package/ts/nosqldb/classes.testdatabase.ts

@@ -3,6 +3,7 @@ import { snapshotBoundedBsonDocument } from './classes.bsonsnapshot.js';
 import { SmartdataDb } from './classes.db.js';
 import { SmartDataDbDoc } from './classes.doc.js';
 import { SmartdataPersistenceError } from './classes.persistence.js';
+import { captureSmartdataCollectionChange } from './classes.readtracker.js';
 import { assertDataOptions, SmartdataOperationBudget } from './classes.operationbudget.js';
 
 /** A loopback TCP engine endpoint. */
@@ -255,14 +256,19 @@ export class SmartdataTestDatabase {
         await modelArg.prepareCollection({ mode: 'ensureCompatible', timeoutMs: budget.remainingMs(), signal: budget.signal });
         this.assertOwnedBinding();
         const raw = this.db.mongoDb.collection(expected.collectionName);
-        if (replacementArg) {
-          const result = await raw.replaceOne({ _id: document._id }, document,
-            { upsert: false, ...budget.operationOptions() });
-          if (!result.acknowledged || result.matchedCount !== 1) throw new SmartdataPersistenceError(
-            'unsupported_operation', 'Exact fault replacement requires one existing document.');
-        } else {
-          const result = await raw.insertOne(document, budget.operationOptions());
-          if (!result.acknowledged) throw new SmartdataPersistenceError('unsupported_operation', 'Fault insertion was not acknowledged.');
+        try {
+          if (replacementArg) {
+            const result = await raw.replaceOne({ _id: document._id }, document,
+              { upsert: false, ...budget.operationOptions() });
+            if (!result.acknowledged || result.matchedCount !== 1) throw new SmartdataPersistenceError(
+              'unsupported_operation', 'Exact fault replacement requires one existing document.');
+          } else {
+            const result = await raw.insertOne(document, budget.operationOptions());
+            if (!result.acknowledged) throw new SmartdataPersistenceError('unsupported_operation', 'Fault insertion was not acknowledged.');
+          }
+        } finally {
+          // A fault writes behind the models, so every open read set that read the collection changes.
+          captureSmartdataCollectionChange(this.db, expected.collectionName, false)?.();
         }
         budget.check();
       })();

package/ts/nosqldb/classes.writeobserver.ts

@@ -51,6 +51,17 @@ export interface ISmartdataWrite {
   selector?: unknown;
   /** The model's `identityAsDocumentId` field, whose value a selector carries as `_id`. */
   identityDocumentIdField?: string;
+  /**
+   * Which stored states `documents` are, for read sets: the whole document
+   * after the write (for a replacement, the last one), before it, both
+   * (before, then after), or neither. A write without it changes every read
+   * of its collection.
+   */
+  images?: 'after' | 'before' | 'beforeAndAfter' | 'none';
+  /** The update document a write by selector applied. */
+  update?: unknown;
+  /** The model's identity fields, by which a selector names a document without its `_id`. */
+  identityFields?: readonly string[];
 }
 
 interface IWriteObserver {