monsqlize 2.0.2 → 2.0.3

package/dist/cjs/transaction/Transaction.cjs

@@ -2,6 +2,91 @@
 
 // src/capabilities/transaction/index.ts
 var import_node_crypto = require("node:crypto");
+
+// src/core/errors/index.ts
+var ErrorCodes = {
+  INVALID_ARGUMENT: "INVALID_ARGUMENT",
+  INVALID_COLLECTION_NAME: "INVALID_COLLECTION_NAME",
+  INVALID_DATABASE_NAME: "INVALID_DATABASE_NAME",
+  INVALID_EXPRESSION: "INVALID_EXPRESSION",
+  INVALID_PAGINATION: "INVALID_PAGINATION",
+  INVALID_OPERATION: "INVALID_OPERATION",
+  CACHE_UNAVAILABLE: "CACHE_UNAVAILABLE",
+  MANAGEMENT_OPERATION_FAILED: "MANAGEMENT_OPERATION_FAILED",
+  NOT_CONNECTED: "NOT_CONNECTED",
+  CONNECTION_FAILED: "CONNECTION_FAILED",
+  CONNECTION_CLOSED: "CONNECTION_CLOSED",
+  INVALID_CONFIG: "INVALID_CONFIG",
+  OPERATION_TIMEOUT: "OPERATION_TIMEOUT",
+  UNSUPPORTED_DATABASE: "UNSUPPORTED_DATABASE",
+  /** v1 compat: insertOne requires a non-null, non-array object document */
+  DOCUMENT_REQUIRED: "DOCUMENT_REQUIRED",
+  /** v1 compat: MongoDB duplicate key (error code 11000) */
+  DUPLICATE_KEY: "DUPLICATE_KEY",
+  /** v1 compat: general write failure (maps from MongoError in insert/update/delete) */
+  WRITE_ERROR: "WRITE_ERROR",
+  /** v1 compat: model-layer schema validation failure */
+  VALIDATION_ERROR: "VALIDATION_ERROR",
+  /** v1 compat: stream mode cannot use page jump (page > 1 with stream: true) */
+  STREAM_NO_JUMP: "STREAM_NO_JUMP",
+  /** v1 compat: stream mode cannot compute totals */
+  STREAM_NO_TOTALS: "STREAM_NO_TOTALS",
+  /** v1 compat: stream mode cannot use explain */
+  STREAM_NO_EXPLAIN: "STREAM_NO_EXPLAIN",
+  /** v1 compat: page jump exceeds the maxHops limit */
+  JUMP_TOO_FAR: "JUMP_TOO_FAR",
+  /** v1 compat: generic MongoDB driver error (maps numeric MongoDB error codes) */
+  MONGODB_ERROR: "MONGODB_ERROR",
+  /** v1 compat: cursor sort options mismatch between pages */
+  CURSOR_SORT_MISMATCH: "CURSOR_SORT_MISMATCH",
+  /** v1 compat: invalid or expired cursor token */
+  INVALID_CURSOR: "INVALID_CURSOR",
+  /** v1 compat: connection timeout */
+  CONNECTION_TIMEOUT: "CONNECTION_TIMEOUT",
+  /** v1 compat: generic database error */
+  DATABASE_ERROR: "DATABASE_ERROR",
+  /** v1 compat: query execution timeout */
+  QUERY_TIMEOUT: "QUERY_TIMEOUT",
+  /** v1 compat: cache backend error */
+  CACHE_ERROR: "CACHE_ERROR",
+  /** v1 compat: cache operation timeout */
+  CACHE_TIMEOUT: "CACHE_TIMEOUT",
+  /** v1 compat: model.define() called without schema */
+  MISSING_SCHEMA: "MISSING_SCHEMA",
+  /** v1 compat: model already registered under same name */
+  MODEL_ALREADY_EXISTS: "MODEL_ALREADY_EXISTS",
+  /** v1 compat: write requires at least one document */
+  DOCUMENTS_REQUIRED: "DOCUMENTS_REQUIRED",
+  /** v1 compat: concurrent write conflict in transaction */
+  WRITE_CONFLICT: "WRITE_CONFLICT",
+  /** v1 compat: business lock acquire failed */
+  LOCK_ACQUIRE_FAILED: "LOCK_ACQUIRE_FAILED",
+  /** v1 compat: business lock wait timeout */
+  LOCK_TIMEOUT: "LOCK_TIMEOUT",
+  /** v1 compat: model.model() called when not connected */
+  MODEL_NOT_DEFINED: "MODEL_NOT_DEFINED",
+  /** v1 compat: pool() called without pools configured */
+  NO_POOL_MANAGER: "NO_POOL_MANAGER",
+  /** v1 compat: pool() called with a pool name that does not exist */
+  POOL_NOT_FOUND: "POOL_NOT_FOUND",
+  /** v1 compat: model definition is not a valid object */
+  INVALID_MODEL_DEFINITION: "INVALID_MODEL_DEFINITION",
+  /** v1 compat: schema property is not a function or object */
+  INVALID_SCHEMA_TYPE: "INVALID_SCHEMA_TYPE"
+};
+function createError(code, message, details, cause) {
+  const error = new Error(message);
+  error.code = code;
+  if (details !== void 0) {
+    error.details = details;
+  }
+  if (cause !== void 0) {
+    error.cause = cause;
+  }
+  return error;
+}
+
+// src/capabilities/transaction/index.ts
 function toPublicTransactionStatus(state) {
   return state === "active" ? "started" : state;
 }
@@ -22,9 +107,9 @@ var Transaction = class {
    */
   async start() {
     if (this.state !== "pending") {
-      throw new Error(`Cannot start transaction in state: ${this.state}`);
+      throw createError(ErrorCodes.INVALID_OPERATION, `Cannot start transaction in state: ${this.state}`);
     }
-    this.session.startTransaction();
+    this.session.startTransaction(this.options.transactionOptions);
     this.state = "active";
     this.startedAt = Date.now();
     const timeout = this.options.timeout ?? 3e4;
@@ -44,7 +129,7 @@ var Transaction = class {
    */
   async commit() {
     if (this.state !== "active") {
-      throw new Error(`Cannot commit transaction in state: ${this.state}`);
+      throw createError(ErrorCodes.INVALID_OPERATION, `Cannot commit transaction in state: ${this.state}`);
     }
     if (typeof this.session.commitTransaction === "function") {
       await this.session.commitTransaction();

package/dist/cjs/transaction/TransactionManager.cjs

@@ -2,6 +2,91 @@
 
 // src/capabilities/transaction/index.ts
 var import_node_crypto = require("node:crypto");
+
+// src/core/errors/index.ts
+var ErrorCodes = {
+  INVALID_ARGUMENT: "INVALID_ARGUMENT",
+  INVALID_COLLECTION_NAME: "INVALID_COLLECTION_NAME",
+  INVALID_DATABASE_NAME: "INVALID_DATABASE_NAME",
+  INVALID_EXPRESSION: "INVALID_EXPRESSION",
+  INVALID_PAGINATION: "INVALID_PAGINATION",
+  INVALID_OPERATION: "INVALID_OPERATION",
+  CACHE_UNAVAILABLE: "CACHE_UNAVAILABLE",
+  MANAGEMENT_OPERATION_FAILED: "MANAGEMENT_OPERATION_FAILED",
+  NOT_CONNECTED: "NOT_CONNECTED",
+  CONNECTION_FAILED: "CONNECTION_FAILED",
+  CONNECTION_CLOSED: "CONNECTION_CLOSED",
+  INVALID_CONFIG: "INVALID_CONFIG",
+  OPERATION_TIMEOUT: "OPERATION_TIMEOUT",
+  UNSUPPORTED_DATABASE: "UNSUPPORTED_DATABASE",
+  /** v1 compat: insertOne requires a non-null, non-array object document */
+  DOCUMENT_REQUIRED: "DOCUMENT_REQUIRED",
+  /** v1 compat: MongoDB duplicate key (error code 11000) */
+  DUPLICATE_KEY: "DUPLICATE_KEY",
+  /** v1 compat: general write failure (maps from MongoError in insert/update/delete) */
+  WRITE_ERROR: "WRITE_ERROR",
+  /** v1 compat: model-layer schema validation failure */
+  VALIDATION_ERROR: "VALIDATION_ERROR",
+  /** v1 compat: stream mode cannot use page jump (page > 1 with stream: true) */
+  STREAM_NO_JUMP: "STREAM_NO_JUMP",
+  /** v1 compat: stream mode cannot compute totals */
+  STREAM_NO_TOTALS: "STREAM_NO_TOTALS",
+  /** v1 compat: stream mode cannot use explain */
+  STREAM_NO_EXPLAIN: "STREAM_NO_EXPLAIN",
+  /** v1 compat: page jump exceeds the maxHops limit */
+  JUMP_TOO_FAR: "JUMP_TOO_FAR",
+  /** v1 compat: generic MongoDB driver error (maps numeric MongoDB error codes) */
+  MONGODB_ERROR: "MONGODB_ERROR",
+  /** v1 compat: cursor sort options mismatch between pages */
+  CURSOR_SORT_MISMATCH: "CURSOR_SORT_MISMATCH",
+  /** v1 compat: invalid or expired cursor token */
+  INVALID_CURSOR: "INVALID_CURSOR",
+  /** v1 compat: connection timeout */
+  CONNECTION_TIMEOUT: "CONNECTION_TIMEOUT",
+  /** v1 compat: generic database error */
+  DATABASE_ERROR: "DATABASE_ERROR",
+  /** v1 compat: query execution timeout */
+  QUERY_TIMEOUT: "QUERY_TIMEOUT",
+  /** v1 compat: cache backend error */
+  CACHE_ERROR: "CACHE_ERROR",
+  /** v1 compat: cache operation timeout */
+  CACHE_TIMEOUT: "CACHE_TIMEOUT",
+  /** v1 compat: model.define() called without schema */
+  MISSING_SCHEMA: "MISSING_SCHEMA",
+  /** v1 compat: model already registered under same name */
+  MODEL_ALREADY_EXISTS: "MODEL_ALREADY_EXISTS",
+  /** v1 compat: write requires at least one document */
+  DOCUMENTS_REQUIRED: "DOCUMENTS_REQUIRED",
+  /** v1 compat: concurrent write conflict in transaction */
+  WRITE_CONFLICT: "WRITE_CONFLICT",
+  /** v1 compat: business lock acquire failed */
+  LOCK_ACQUIRE_FAILED: "LOCK_ACQUIRE_FAILED",
+  /** v1 compat: business lock wait timeout */
+  LOCK_TIMEOUT: "LOCK_TIMEOUT",
+  /** v1 compat: model.model() called when not connected */
+  MODEL_NOT_DEFINED: "MODEL_NOT_DEFINED",
+  /** v1 compat: pool() called without pools configured */
+  NO_POOL_MANAGER: "NO_POOL_MANAGER",
+  /** v1 compat: pool() called with a pool name that does not exist */
+  POOL_NOT_FOUND: "POOL_NOT_FOUND",
+  /** v1 compat: model definition is not a valid object */
+  INVALID_MODEL_DEFINITION: "INVALID_MODEL_DEFINITION",
+  /** v1 compat: schema property is not a function or object */
+  INVALID_SCHEMA_TYPE: "INVALID_SCHEMA_TYPE"
+};
+function createError(code, message, details, cause) {
+  const error = new Error(message);
+  error.code = code;
+  if (details !== void 0) {
+    error.details = details;
+  }
+  if (cause !== void 0) {
+    error.cause = cause;
+  }
+  return error;
+}
+
+// src/capabilities/transaction/index.ts
 function toPublicTransactionStatus(state) {
   return state === "active" ? "started" : state;
 }
@@ -22,9 +107,9 @@ var Transaction = class {
    */
   async start() {
     if (this.state !== "pending") {
-      throw new Error(`Cannot start transaction in state: ${this.state}`);
+      throw createError(ErrorCodes.INVALID_OPERATION, `Cannot start transaction in state: ${this.state}`);
     }
-    this.session.startTransaction();
+    this.session.startTransaction(this.options.transactionOptions);
     this.state = "active";
     this.startedAt = Date.now();
     const timeout = this.options.timeout ?? 3e4;
@@ -44,7 +129,7 @@ var Transaction = class {
    */
   async commit() {
     if (this.state !== "active") {
-      throw new Error(`Cannot commit transaction in state: ${this.state}`);
+      throw createError(ErrorCodes.INVALID_OPERATION, `Cannot commit transaction in state: ${this.state}`);
     }
     if (typeof this.session.commitTransaction === "function") {
       await this.session.commitTransaction();
@@ -142,7 +227,9 @@ var TransactionManager = class {
     this.stats = {
       totalTransactions: 0,
       successfulTransactions: 0,
-      failedTransactions: 0
+      failedTransactions: 0,
+      readOnlyTransactions: 0,
+      writeTransactions: 0
     };
     const options = "client" in input ? input : {
       client: input,
@@ -153,6 +240,10 @@ var TransactionManager = class {
     this.cache = options.cache ?? null;
     this.logger = options.logger ?? null;
     this.lockManager = options.lockManager ?? null;
+    this.defaultReadConcern = options.defaultReadConcern;
+    this.defaultWriteConcern = options.defaultWriteConcern;
+    this.defaultReadPreference = options.defaultReadPreference;
+    this.maxStatsSamples = options.maxStatsSamples ?? 1e3;
     this.defaultOptions = {
       maxDuration: options.maxDuration ?? 3e4,
       enableRetry: options.enableRetry ?? true,
@@ -169,11 +260,17 @@ var TransactionManager = class {
     const session = this.client.startSession({
       causalConsistency: options.causalConsistency !== false
     });
+    const transactionOptions = {
+      readConcern: options.readConcern ?? this.defaultReadConcern,
+      writeConcern: options.writeConcern ?? this.defaultWriteConcern,
+      readPreference: options.readPreference ?? this.defaultReadPreference
+    };
     const transaction = new Transaction(session, {
       cache: this.cache,
       logger: this.logger,
       lockManager: options.enableCacheLock === false ? null : this.lockManager,
-      timeout: options.timeout ?? options.maxDuration ?? this.defaultOptions.maxDuration
+      timeout: options.timeout ?? options.maxDuration ?? this.defaultOptions.maxDuration,
+      transactionOptions: compactUndefined(transactionOptions)
     });
     const originalEnd = transaction.end.bind(transaction);
     transaction.end = async () => {
@@ -200,12 +297,12 @@ var TransactionManager = class {
         await transaction.start();
         const result = await callback(transaction);
         await transaction.commit();
-        this.recordStats(Date.now() - startedAt, true);
+        this.recordStats(transaction, Date.now() - startedAt, true);
         return result;
       } catch (error) {
         lastError = error;
         await transaction.abort();
-        this.recordStats(Date.now() - startedAt, false);
+        this.recordStats(transaction, Date.now() - startedAt, false);
         if (!enableRetry || attempt === maxRetries || !isTransientTransactionError(error)) {
           throw error;
         }
@@ -241,27 +338,54 @@ var TransactionManager = class {
    */
   getStats() {
     const averageDuration = this.durations.length === 0 ? 0 : this.durations.reduce((sum, item) => sum + item, 0) / this.durations.length;
+    const sortedDurations = [...this.durations].sort((a, b) => a - b);
+    const p95Duration = percentile(sortedDurations, 0.95);
+    const p99Duration = percentile(sortedDurations, 0.99);
+    const totalTransactions = this.stats.totalTransactions;
     return {
-      totalTransactions: this.stats.totalTransactions,
+      totalTransactions,
       successfulTransactions: this.stats.successfulTransactions,
       failedTransactions: this.stats.failedTransactions,
+      readOnlyTransactions: this.stats.readOnlyTransactions,
+      writeTransactions: this.stats.writeTransactions,
       activeTransactions: this.activeTransactions.size,
-      averageDuration
+      averageDuration,
+      p95Duration,
+      p99Duration,
+      successRate: totalTransactions > 0 ? `${(this.stats.successfulTransactions / totalTransactions * 100).toFixed(2)}%` : "0%",
+      readOnlyRatio: totalTransactions > 0 ? `${(this.stats.readOnlyTransactions / totalTransactions * 100).toFixed(2)}%` : "0%",
+      sampleCount: this.durations.length
     };
   }
-  recordStats(duration, success) {
+  recordStats(transaction, duration, success) {
     this.stats.totalTransactions += 1;
     if (success) {
       this.stats.successfulTransactions += 1;
     } else {
       this.stats.failedTransactions += 1;
     }
+    if (transaction.pendingInvalidations.size > 0) {
+      this.stats.writeTransactions += 1;
+    } else {
+      this.stats.readOnlyTransactions += 1;
+    }
     this.durations.push(duration);
-    if (this.durations.length > 100) {
+    if (this.durations.length > this.maxStatsSamples) {
       this.durations.shift();
     }
   }
 };
+function percentile(sortedValues, ratio) {
+  if (sortedValues.length === 0) {
+    return 0;
+  }
+  const index = Math.floor(sortedValues.length * ratio);
+  return sortedValues[Math.min(index, sortedValues.length - 1)] ?? 0;
+}
+function compactUndefined(value) {
+  const entries = Object.entries(value).filter(([, item]) => item !== void 0);
+  return entries.length === 0 ? void 0 : Object.fromEntries(entries);
+}
 function stringifySessionId(id) {
   if (typeof id === "string") {
     return id;