monsqlize 3.3.0 → 3.3.2

package/dist/cjs/transaction/Transaction.cjs

@@ -1,5 +1,51 @@
 "use strict";
 
+// src/core/cache-coordination.ts
+var coordinators = /* @__PURE__ */ new WeakMap();
+var origins = /* @__PURE__ */ new WeakMap();
+function coordinator(cache) {
+  const origin = origins.get(cache) ?? cache;
+  let state = coordinators.get(origin);
+  if (!state) {
+    state = { tickets: /* @__PURE__ */ new Set(), tails: /* @__PURE__ */ new Map() };
+    coordinators.set(origin, state);
+  }
+  return state;
+}
+function matches(intent, key) {
+  if (intent.type === "key") return intent.value === key;
+  const pattern = intent.value.split("*").map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*");
+  return new RegExp(`^${pattern}$`).test(key);
+}
+function serialize(state, key, task) {
+  const result = (state.tails.get(key) ?? Promise.resolve()).catch(() => void 0).then(task);
+  state.tails.set(key, result);
+  void result.finally(() => {
+    if (state.tails.get(key) === result) state.tails.delete(key);
+  }).catch(() => void 0);
+  return result;
+}
+async function coordinateInvalidation(cache, intents, task) {
+  const state = coordinator(cache);
+  for (const ticket of state.tickets) {
+    if (intents.some((intent) => matches(intent, ticket.key))) ticket.valid = false;
+  }
+  const keys = [...state.tails.keys()].filter((key) => intents.some((intent) => matches(intent, key)));
+  const previous = keys.map((key) => state.tails.get(key));
+  let finish;
+  const done = new Promise((resolve) => {
+    finish = resolve;
+  });
+  const pending = keys.map((key) => serialize(state, key, () => done));
+  try {
+    await Promise.allSettled(previous);
+    return await task();
+  } finally {
+    finish();
+    await Promise.allSettled(pending);
+  }
+}
+
 // src/capabilities/transaction/index.ts
 var import_node_crypto = require("node:crypto");
 
@@ -148,8 +194,13 @@ var Transaction = class {
   constructor(session, options = {}) {
     this.session = session;
     this.options = options;
+    this.commitPromise = null;
+    this.abortPromise = null;
+    this.endPromise = null;
+    this.commitOutcomeUnknown = false;
     this.id = `tx_${(0, import_node_crypto.randomBytes)(8).toString("hex")}`;
     this.state = "pending";
+    this.acceptingWrites = false;
     this.startedAt = null;
     this.timeoutTimer = null;
     this.pendingInvalidations = /* @__PURE__ */ new Set();
@@ -163,11 +214,13 @@ var Transaction = class {
    * @since v1.4.0
    */
   async start() {
+    if (this.endPromise || this.abortPromise) throw createError(ErrorCodes.INVALID_OPERATION, "Transaction is already ending.");
     if (this.state !== "pending") {
       throw createError(ErrorCodes.INVALID_OPERATION, `Cannot start transaction in state: ${this.state}`);
     }
     this.session.startTransaction(this.options.transactionOptions);
     this.state = "active";
+    this.acceptingWrites = true;
     this.startedAt = Date.now();
     const timeout = this.options.timeout ?? 3e4;
     if (timeout > 0) {
@@ -187,11 +240,42 @@ var Transaction = class {
    * @since v1.4.0
    */
   async commit() {
+    if (this.commitPromise) return this.commitPromise;
+    if (this.endPromise || this.abortPromise) {
+      throw createError(ErrorCodes.INVALID_OPERATION, "Transaction is already ending.");
+    }
     if (this.state !== "active") {
       throw createError(ErrorCodes.INVALID_OPERATION, `Cannot commit transaction in state: ${this.state}`);
     }
+    this.acceptingWrites = false;
+    const timeout = this.options.timeout ?? 3e4;
+    if (!this.commitOutcomeUnknown && timeout > 0 && this.getDuration() >= timeout) {
+      await this.abort();
+      throw createError(ErrorCodes.OPERATION_TIMEOUT, "Transaction work exceeded its timeout before commit.");
+    }
+    this.clearTimeout();
+    const committing = this.commitOnce();
+    this.commitPromise = committing;
+    try {
+      await committing;
+    } finally {
+      if (this.commitPromise === committing) this.commitPromise = null;
+    }
+  }
+  async commitOnce() {
     if (typeof this.session.commitTransaction === "function") {
-      await commitTransactionWithRetry(this.session, this.options.logger);
+      try {
+        await commitTransactionWithRetry(this.session, this.options.logger);
+        this.commitOutcomeUnknown = false;
+      } catch (error) {
+        this.commitOutcomeUnknown = isUnknownTransactionCommitResult(error);
+        if (this.commitOutcomeUnknown) {
+          await this.flushPendingInvalidations().catch((cacheError) => {
+            this.options.logger?.warn?.("[Transaction] uncertain commit cache invalidation failed.", cacheError);
+          });
+        }
+        throw error;
+      }
     }
     this.state = "committed";
     try {
@@ -215,6 +299,14 @@ var Transaction = class {
    * @since v1.4.0
    */
   async abort() {
+    this.acceptingWrites = false;
+    if (this.commitPromise) await this.commitPromise.catch(() => void 0);
+    if (this.commitOutcomeUnknown) return;
+    if (this.abortPromise) return this.abortPromise;
+    this.abortPromise = this.abortOnce();
+    return this.abortPromise;
+  }
+  async abortOnce() {
     if (this.state !== "pending" && this.state !== "active") {
       return;
     }
@@ -239,10 +331,24 @@ var Transaction = class {
    * @since v1.4.0
    */
   async end() {
+    if (this.endPromise) return this.endPromise;
+    this.endPromise = this.endOnce();
+    return this.endPromise;
+  }
+  async endOnce() {
+    this.acceptingWrites = false;
+    if (this.commitPromise) await this.commitPromise.catch(() => void 0);
+    if (this.abortPromise) await this.abortPromise;
+    else if (this.state === "active" && !this.commitOutcomeUnknown) await this.abort();
     this.clearTimeout();
     this.options.lockManager?.releaseLocks(this.id);
     await this.session.endSession();
   }
+  assertAcceptingWrites() {
+    if (this.state !== "active" || !this.acceptingWrites) {
+      throw createError(ErrorCodes.INVALID_OPERATION, `Managed transaction ${this.id} is no longer accepting writes.`);
+    }
+  }
   /**
    * Record a cache invalidation intent.
    * @since v1.4.0
@@ -270,15 +376,17 @@ var Transaction = class {
       return;
     }
     const cacheWithDelete = this.options.cache;
-    for (const intent of this.pendingInvalidationIntents.values()) {
-      if (intent.type === "pattern") {
-        await this.options.cache.delPattern?.(intent.value);
-      } else if (typeof cacheWithDelete.del === "function") {
-        await cacheWithDelete.del(intent.value);
-      } else if (typeof cacheWithDelete.delete === "function") {
-        await cacheWithDelete.delete(intent.value);
+    await coordinateInvalidation(this.options.cache, [...this.pendingInvalidationIntents.values()], async () => {
+      for (const intent of this.pendingInvalidationIntents.values()) {
+        if (intent.type === "pattern") {
+          await cacheWithDelete.delPattern?.(intent.value);
+        } else if (typeof cacheWithDelete.del === "function") {
+          await cacheWithDelete.del(intent.value);
+        } else if (typeof cacheWithDelete.delete === "function") {
+          await cacheWithDelete.delete(intent.value);
+        }
       }
-    }
+    });
   }
   async clearPendingInvalidationBarriers() {
     if (!this.options.cache || this.pendingInvalidationIntents.size === 0) {
@@ -353,12 +461,30 @@ function stringifySessionId(id) {
   }
   return String(id);
 }
-function isUnknownTransactionCommitResult(error) {
-  if (!error || typeof error !== "object") {
-    return false;
+function transactionErrorChain(error) {
+  const chain = [];
+  const seen = /* @__PURE__ */ new Set();
+  let current = error;
+  while (current && typeof current === "object" && chain.length < 8 && !seen.has(current)) {
+    seen.add(current);
+    const candidate = current;
+    chain.push(candidate);
+    current = candidate.cause;
+  }
+  return chain;
+}
+function hasTransactionErrorLabel(candidate, label) {
+  if (Array.isArray(candidate.errorLabels) && candidate.errorLabels.includes(label)) return true;
+  if (typeof candidate.hasErrorLabel === "function") {
+    try {
+      return Boolean(candidate.hasErrorLabel.call(candidate, label));
+    } catch {
+    }
   }
-  const candidate = error;
-  return typeof candidate.hasErrorLabel === "function" && candidate.hasErrorLabel("UnknownTransactionCommitResult");
+  return false;
+}
+function isUnknownTransactionCommitResult(error) {
+  return transactionErrorChain(error).some((candidate) => hasTransactionErrorLabel(candidate, "UnknownTransactionCommitResult"));
 }
 async function commitTransactionWithRetry(session, logger) {
   const maxAttempts = 3;

package/dist/cjs/transaction/TransactionManager.cjs

@@ -1,5 +1,51 @@
 "use strict";
 
+// src/core/cache-coordination.ts
+var coordinators = /* @__PURE__ */ new WeakMap();
+var origins = /* @__PURE__ */ new WeakMap();
+function coordinator(cache) {
+  const origin = origins.get(cache) ?? cache;
+  let state = coordinators.get(origin);
+  if (!state) {
+    state = { tickets: /* @__PURE__ */ new Set(), tails: /* @__PURE__ */ new Map() };
+    coordinators.set(origin, state);
+  }
+  return state;
+}
+function matches(intent, key) {
+  if (intent.type === "key") return intent.value === key;
+  const pattern = intent.value.split("*").map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*");
+  return new RegExp(`^${pattern}$`).test(key);
+}
+function serialize(state, key, task) {
+  const result = (state.tails.get(key) ?? Promise.resolve()).catch(() => void 0).then(task);
+  state.tails.set(key, result);
+  void result.finally(() => {
+    if (state.tails.get(key) === result) state.tails.delete(key);
+  }).catch(() => void 0);
+  return result;
+}
+async function coordinateInvalidation(cache, intents, task) {
+  const state = coordinator(cache);
+  for (const ticket of state.tickets) {
+    if (intents.some((intent) => matches(intent, ticket.key))) ticket.valid = false;
+  }
+  const keys = [...state.tails.keys()].filter((key) => intents.some((intent) => matches(intent, key)));
+  const previous = keys.map((key) => state.tails.get(key));
+  let finish;
+  const done = new Promise((resolve) => {
+    finish = resolve;
+  });
+  const pending = keys.map((key) => serialize(state, key, () => done));
+  try {
+    await Promise.allSettled(previous);
+    return await task();
+  } finally {
+    finish();
+    await Promise.allSettled(pending);
+  }
+}
+
 // src/capabilities/transaction/index.ts
 var import_node_crypto = require("node:crypto");
 
@@ -148,8 +194,13 @@ var Transaction = class {
   constructor(session, options = {}) {
     this.session = session;
     this.options = options;
+    this.commitPromise = null;
+    this.abortPromise = null;
+    this.endPromise = null;
+    this.commitOutcomeUnknown = false;
     this.id = `tx_${(0, import_node_crypto.randomBytes)(8).toString("hex")}`;
     this.state = "pending";
+    this.acceptingWrites = false;
     this.startedAt = null;
     this.timeoutTimer = null;
     this.pendingInvalidations = /* @__PURE__ */ new Set();
@@ -163,11 +214,13 @@ var Transaction = class {
    * @since v1.4.0
    */
   async start() {
+    if (this.endPromise || this.abortPromise) throw createError(ErrorCodes.INVALID_OPERATION, "Transaction is already ending.");
     if (this.state !== "pending") {
       throw createError(ErrorCodes.INVALID_OPERATION, `Cannot start transaction in state: ${this.state}`);
     }
     this.session.startTransaction(this.options.transactionOptions);
     this.state = "active";
+    this.acceptingWrites = true;
     this.startedAt = Date.now();
     const timeout = this.options.timeout ?? 3e4;
     if (timeout > 0) {
@@ -187,11 +240,42 @@ var Transaction = class {
    * @since v1.4.0
    */
   async commit() {
+    if (this.commitPromise) return this.commitPromise;
+    if (this.endPromise || this.abortPromise) {
+      throw createError(ErrorCodes.INVALID_OPERATION, "Transaction is already ending.");
+    }
     if (this.state !== "active") {
       throw createError(ErrorCodes.INVALID_OPERATION, `Cannot commit transaction in state: ${this.state}`);
     }
+    this.acceptingWrites = false;
+    const timeout = this.options.timeout ?? 3e4;
+    if (!this.commitOutcomeUnknown && timeout > 0 && this.getDuration() >= timeout) {
+      await this.abort();
+      throw createError(ErrorCodes.OPERATION_TIMEOUT, "Transaction work exceeded its timeout before commit.");
+    }
+    this.clearTimeout();
+    const committing = this.commitOnce();
+    this.commitPromise = committing;
+    try {
+      await committing;
+    } finally {
+      if (this.commitPromise === committing) this.commitPromise = null;
+    }
+  }
+  async commitOnce() {
     if (typeof this.session.commitTransaction === "function") {
-      await commitTransactionWithRetry(this.session, this.options.logger);
+      try {
+        await commitTransactionWithRetry(this.session, this.options.logger);
+        this.commitOutcomeUnknown = false;
+      } catch (error) {
+        this.commitOutcomeUnknown = isUnknownTransactionCommitResult(error);
+        if (this.commitOutcomeUnknown) {
+          await this.flushPendingInvalidations().catch((cacheError) => {
+            this.options.logger?.warn?.("[Transaction] uncertain commit cache invalidation failed.", cacheError);
+          });
+        }
+        throw error;
+      }
     }
     this.state = "committed";
     try {
@@ -215,6 +299,14 @@ var Transaction = class {
    * @since v1.4.0
    */
   async abort() {
+    this.acceptingWrites = false;
+    if (this.commitPromise) await this.commitPromise.catch(() => void 0);
+    if (this.commitOutcomeUnknown) return;
+    if (this.abortPromise) return this.abortPromise;
+    this.abortPromise = this.abortOnce();
+    return this.abortPromise;
+  }
+  async abortOnce() {
     if (this.state !== "pending" && this.state !== "active") {
       return;
     }
@@ -239,10 +331,24 @@ var Transaction = class {
    * @since v1.4.0
    */
   async end() {
+    if (this.endPromise) return this.endPromise;
+    this.endPromise = this.endOnce();
+    return this.endPromise;
+  }
+  async endOnce() {
+    this.acceptingWrites = false;
+    if (this.commitPromise) await this.commitPromise.catch(() => void 0);
+    if (this.abortPromise) await this.abortPromise;
+    else if (this.state === "active" && !this.commitOutcomeUnknown) await this.abort();
     this.clearTimeout();
     this.options.lockManager?.releaseLocks(this.id);
     await this.session.endSession();
   }
+  assertAcceptingWrites() {
+    if (this.state !== "active" || !this.acceptingWrites) {
+      throw createError(ErrorCodes.INVALID_OPERATION, `Managed transaction ${this.id} is no longer accepting writes.`);
+    }
+  }
   /**
    * Record a cache invalidation intent.
    * @since v1.4.0
@@ -270,15 +376,17 @@ var Transaction = class {
       return;
     }
     const cacheWithDelete = this.options.cache;
-    for (const intent of this.pendingInvalidationIntents.values()) {
-      if (intent.type === "pattern") {
-        await this.options.cache.delPattern?.(intent.value);
-      } else if (typeof cacheWithDelete.del === "function") {
-        await cacheWithDelete.del(intent.value);
-      } else if (typeof cacheWithDelete.delete === "function") {
-        await cacheWithDelete.delete(intent.value);
+    await coordinateInvalidation(this.options.cache, [...this.pendingInvalidationIntents.values()], async () => {
+      for (const intent of this.pendingInvalidationIntents.values()) {
+        if (intent.type === "pattern") {
+          await cacheWithDelete.delPattern?.(intent.value);
+        } else if (typeof cacheWithDelete.del === "function") {
+          await cacheWithDelete.del(intent.value);
+        } else if (typeof cacheWithDelete.delete === "function") {
+          await cacheWithDelete.delete(intent.value);
+        }
       }
-    }
+    });
   }
   async clearPendingInvalidationBarriers() {
     if (!this.options.cache || this.pendingInvalidationIntents.size === 0) {
@@ -416,12 +524,12 @@ var TransactionManager = class {
         return result;
       } catch (error) {
         lastError = error;
-        await transaction.abort();
-        this.recordStats(transaction, Date.now() - startedAt, false);
         if (transaction.state === "committed") {
           throw error;
         }
-        if (!enableRetry || attempt === maxRetries || !isTransientTransactionError(error)) {
+        await transaction.abort();
+        this.recordStats(transaction, Date.now() - startedAt, false);
+        if (!enableRetry || attempt === maxRetries || isUnknownTransactionCommitResult(error) || !isTransientTransactionError(error)) {
           throw error;
         }
         await sleep(retryDelay * Math.pow(retryBackoff, attempt));
@@ -522,22 +630,34 @@ function stringifySessionId(id) {
   }
   return String(id);
 }
-function isTransientTransactionError(error) {
-  if (!error || typeof error !== "object") {
-    return false;
-  }
-  const candidate = error;
-  if (typeof candidate.hasErrorLabel === "function" && candidate.hasErrorLabel("TransientTransactionError")) {
-    return true;
+function transactionErrorChain(error) {
+  const chain = [];
+  const seen = /* @__PURE__ */ new Set();
+  let current = error;
+  while (current && typeof current === "object" && chain.length < 8 && !seen.has(current)) {
+    seen.add(current);
+    const candidate = current;
+    chain.push(candidate);
+    current = candidate.cause;
+  }
+  return chain;
+}
+function hasTransactionErrorLabel(candidate, label) {
+  if (Array.isArray(candidate.errorLabels) && candidate.errorLabels.includes(label)) return true;
+  if (typeof candidate.hasErrorLabel === "function") {
+    try {
+      return Boolean(candidate.hasErrorLabel.call(candidate, label));
+    } catch {
+    }
   }
-  return candidate.code === 112 || candidate.code === 117;
+  return false;
 }
 function isUnknownTransactionCommitResult(error) {
-  if (!error || typeof error !== "object") {
-    return false;
-  }
-  const candidate = error;
-  return typeof candidate.hasErrorLabel === "function" && candidate.hasErrorLabel("UnknownTransactionCommitResult");
+  return transactionErrorChain(error).some((candidate) => hasTransactionErrorLabel(candidate, "UnknownTransactionCommitResult"));
+}
+function isTransientTransactionError(error) {
+  if (isUnknownTransactionCommitResult(error)) return false;
+  return transactionErrorChain(error).some((candidate) => hasTransactionErrorLabel(candidate, "TransientTransactionError") || candidate.code === 112 || candidate.code === 117 || candidate.codeName === "WriteConflict" || candidate.codeName === "LockTimeout");
 }
 async function commitTransactionWithRetry(session, logger) {
   const maxAttempts = 3;