@lossless.org/client 1.11.0 → 1.12.0

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.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;

package/ts/nosqldb/classes.session.ts

@@ -31,12 +31,36 @@ interface ISmartdataSessionBinding {
   transactionSignal?: AbortSignal;
   transactionAttempt?: symbol;
   transactionFailure?: { error: unknown };
+  /** Set once the current attempt's callback returned and the driver moves on to commit. */
+  transactionCommitReached: boolean;
+  /** Set when the session ended while a transaction ran, stating how far the transaction had got. */
+  transactionEnded?: TSmartdataTransactionEnd;
   operationSettled?: Promise<void>;
   resolveOperationSettled?: () => void;
   invalidated: boolean;
   closing?: Promise<void>;
 }
 
+/** How far a transaction had got when its session ended outside the callback's control. */
+type TSmartdataTransactionEnd = 'before_commit' | 'during_commit';
+
+/**
+ * The session of a transaction ended while it ran, for example through the
+ * database's `close()`. The driver then returns the callback's result without
+ * committing, so the call must reject instead.
+ */
+const createTransactionSessionEndedError = (
+  endArg: TSmartdataTransactionEnd,
+  causeArg?: unknown,
+): SmartdataPersistenceError =>
+  new SmartdataPersistenceError(
+    'unsupported_operation',
+    endArg === 'during_commit'
+      ? 'SmartData transaction session ended during commit; the commit outcome is unknown.'
+      : 'SmartData transaction session ended before commit; nothing was committed.',
+    causeArg === undefined ? undefined : { cause: causeArg },
+  );
+
 const bindings = new WeakMap<SmartdataSession, ISmartdataSessionBinding>();
 const bindingsByOwner = new WeakMap<SmartdataDb, Set<ISmartdataSessionBinding>>();
 const smartdataSessionInvalidationAggregateBrand = Symbol(
@@ -162,6 +186,12 @@ export class SmartdataSession {
    * Any operation on the session that its deadline or a signal interrupts
    * fails the attempt: the call rolls it back and rejects with that
    * operation's error even when the callback caught it.
+   *
+   * When the session ends while the call runs — the database's `close()`
+   * ends every session — the call never reports a commit. It rejects with
+   * `unsupported_operation`: before the callback returned nothing was
+   * committed, afterwards the commit outcome is unknown. The callback's
+   * error, if it threw, is the `cause`.
    */
   public async withTransaction<TResult>(
     callbackArg: (sessionArg: SmartdataSession) => Promise<TResult>,
@@ -185,19 +215,24 @@ export class SmartdataSession {
     binding.transactionActive = true;
     binding.transactionTimeoutMS = timeoutMS;
     binding.transactionSignal = signal;
+    binding.transactionEnded = undefined;
     let callbackError: unknown;
-    let commitReached = false;
+    /** The signal or deadline interruption that failed the last attempt. */
+    let attemptInterruption: { error: unknown } | undefined;
+    let sessionEndedError: SmartdataPersistenceError | undefined;
     const runAttempt = async () => {
       const attempt = Symbol('smartdataTransactionAttempt');
       binding.transactionAttempt = attempt;
       binding.transactionCallbackOpen = true;
       binding.transactionUsesOrdinaryWrite = false;
       binding.transactionFailure = undefined;
+      binding.transactionCommitReached = false;
       callbackError = undefined;
-      commitReached = false;
+      attemptInterruption = undefined;
       try {
         let result: TResult;
         let callbackReturned = false;
+        let callbackThrown: { error: unknown } | undefined;
         try {
           // A retry the driver starts after an abort ends before the callback.
           signal?.throwIfAborted();
@@ -206,6 +241,9 @@ export class SmartdataSession {
             async () => callbackArg(this),
           );
           callbackReturned = true;
+        } catch (errorArg) {
+          callbackThrown = { error: errorArg };
+          throw errorArg;
         } finally {
           const activeOperation = binding.operationActive
             ? binding.operationSettled
@@ -217,7 +255,17 @@ export class SmartdataSession {
           if (activeOperation) {
             await activeOperation;
           }
+          attemptInterruption = binding.transactionFailure;
           assertTransactionSucceeded(binding);
+          if (binding.transactionEnded) {
+            // The driver would commit or return the result on a session that is
+            // being ended; the attempt fails instead, keeping the callback's error.
+            sessionEndedError = createTransactionSessionEndedError(
+              binding.transactionEnded,
+              callbackThrown?.error,
+            );
+            throw sessionEndedError;
+          }
           if (callbackReturned && activeOperation) {
             throw new SmartdataPersistenceError(
               'unsupported_operation',
@@ -227,26 +275,49 @@ export class SmartdataSession {
         }
         // An abort that arrived while the callback ran rolls the attempt back.
         signal?.throwIfAborted();
-        // The driver commits next; a deadline that expires from here on
-        // leaves the commit outcome unknown.
-        commitReached = true;
+        // The driver commits next; a deadline that expires or a session that
+        // ends from here on leaves the commit outcome unknown.
+        binding.transactionCommitReached = true;
         return result;
       } catch (errorArg) {
         callbackError = errorArg;
+        if (signal?.aborted && errorArg === signal.reason) {
+          attemptInterruption ??= { error: errorArg };
+        }
         throw errorArg;
       }
     };
+    let result: TResult | undefined;
+    let transactionEnded: TSmartdataTransactionEnd | undefined;
     try {
-      return timeoutMS === undefined
+      result = timeoutMS === undefined
         ? await binding.rawSession.withTransaction(runAttempt)
         : await binding.rawSession.withTransaction(runAttempt, { timeoutMS });
+      transactionEnded = binding.transactionEnded;
     } catch (errorArg) {
+      // The driver's closing abort replaces the attempt's error when it finds
+      // the transaction already aborted, as a session that close() ended leaves
+      // it; the interruption that failed the attempt keeps its rejection.
+      if (attemptInterruption) {
+        throw normalizeDeadlineError(attemptInterruption.error);
+      }
+      if (sessionEndedError) {
+        throw sessionEndedError;
+      }
+      if (
+        binding.transactionEnded
+        && errorArg !== signal?.reason
+        && !isMongoDeadlineError(errorArg)
+        && !(errorArg instanceof SmartdataPersistenceError && errorArg.code === 'timeout')
+      ) {
+        throw createTransactionSessionEndedError(binding.transactionEnded, errorArg);
+      }
       if (errorArg === callbackError) {
         throw normalizeDeadlineError(errorArg);
       }
       if (isMongoDeadlineError(errorArg)) {
         throw createSmartdataTimeoutError(
-          commitReached
+          binding.transactionCommitReached
             ? 'SmartData transaction exceeded its client deadline during commit; the commit outcome is unknown.'
             : 'SmartData transaction exceeded its client deadline before commit; nothing was committed.',
           errorArg,
@@ -265,7 +336,13 @@ export class SmartdataSession {
       binding.transactionSignal = undefined;
       binding.transactionUsesOrdinaryWrite = false;
       binding.transactionFailure = undefined;
+      binding.transactionCommitReached = false;
+      binding.transactionEnded = undefined;
+    }
+    if (transactionEnded) {
+      throw createTransactionSessionEndedError(transactionEnded);
     }
+    return result;
   }
 
   public async close(): Promise<void> {
@@ -301,6 +378,7 @@ export const createSmartdataSession = (ownerArg: SmartdataDb): SmartdataSession
     transactionActive: false,
     transactionCallbackOpen: false,
     transactionUsesOrdinaryWrite: false,
+    transactionCommitReached: false,
     invalidated: false,
   };
   bindings.set(session, binding);
@@ -559,8 +637,13 @@ export const runWithOrdinarySmartdataSession = async <TResult>(
   }
 };
 
+/**
+ * Ends every session of the owner. `endOptionsArg.timeoutMS` is the driver's
+ * deadline for aborting a transaction a session still holds.
+ */
 export const invalidateSmartdataSessions = async (
   ownerArg: SmartdataDb,
+  endOptionsArg?: Pick<plugins.mongodb.EndSessionOptions, 'timeoutMS'>,
 ): Promise<void> => {
   const ownerBindings = bindingsByOwner.get(ownerArg);
   if (!ownerBindings) {
@@ -568,11 +651,11 @@ export const invalidateSmartdataSessions = async (
   }
   const sessions = [...ownerBindings];
   for (const bindingArg of sessions) {
-    bindingArg.invalidated = true;
+    invalidateSessionBinding(bindingArg);
   }
   const results = await Promise.allSettled(
     sessions.map((bindingArg) =>
-      closeSessionBinding(bindingArg),
+      closeSessionBinding(bindingArg, endOptionsArg),
     ),
   );
   const errors = results.flatMap((resultArg) =>
@@ -589,12 +672,28 @@ export const invalidateSmartdataSessions = async (
   }
 };
 
+/**
+ * Refuses every later operation on the session. A transaction still running on
+ * it records how far it had got, so it rejects instead of reporting a commit.
+ */
+const invalidateSessionBinding = (bindingArg: ISmartdataSessionBinding): void => {
+  bindingArg.invalidated = true;
+  if (bindingArg.transactionActive) {
+    bindingArg.transactionEnded ??= bindingArg.transactionCommitReached
+      ? 'during_commit'
+      : 'before_commit';
+  }
+};
+
 /** Failed cleanup remains owned and invalidated until an explicit retry succeeds. */
-const closeSessionBinding = async (bindingArg: ISmartdataSessionBinding): Promise<void> => {
+const closeSessionBinding = async (
+  bindingArg: ISmartdataSessionBinding,
+  endOptionsArg?: Pick<plugins.mongodb.EndSessionOptions, 'timeoutMS'>,
+): Promise<void> => {
   if (bindingArg.closing) return bindingArg.closing;
-  bindingArg.invalidated = true;
+  invalidateSessionBinding(bindingArg);
   const closing = Promise.resolve().then(async () => {
-    await bindingArg.rawSession.endSession();
+    await bindingArg.rawSession.endSession(endOptionsArg);
     bindingsByOwner.get(bindingArg.owner)?.delete(bindingArg);
     bindings.delete(bindingArg.session);
   });