@joystick.js/db-canary 0.0.0-canary.2251 → 0.0.0-canary.2253

package/src/server/lib/operations/bulk_write.js

@@ -11,51 +11,152 @@ import create_logger from '../logger.js';
 
 const { create_context_logger } = create_logger('bulk_write');
 
+/**
+ * Validates database name parameter.
+ * @param {string} database_name - Database name to validate
+ * @throws {Error} When database name is missing
+ */
+const validate_database_name = (database_name) => {
+  if (!database_name) {
+    throw new Error('Database name is required');
+  }
+};
+
+/**
+ * Validates collection name parameter.
+ * @param {string} collection_name - Collection name to validate
+ * @throws {Error} When collection name is missing
+ */
+const validate_collection_name = (collection_name) => {
+  if (!collection_name) {
+    throw new Error('Collection name is required');
+  }
+};
+
+/**
+ * Validates operations array parameter.
+ * @param {Array} operations - Operations array to validate
+ * @throws {Error} When operations array is invalid
+ */
+const validate_operations_array = (operations) => {
+  if (!Array.isArray(operations) || operations.length === 0) {
+    throw new Error('Operations must be a non-empty array');
+  }
+};
+
+/**
+ * Validates all bulk write parameters.
+ * @param {string} database_name - Database name
+ * @param {string} collection_name - Collection name
+ * @param {Array} operations - Operations array
+ */
+const validate_bulk_write_parameters = (database_name, collection_name, operations) => {
+  validate_database_name(database_name);
+  validate_collection_name(collection_name);
+  validate_operations_array(operations);
+};
+
+/**
+ * Applies $set operator to document.
+ * @param {Object} document - Document to update
+ * @param {Object} operations - Set operations
+ * @returns {Object} Updated document
+ */
+const apply_set_operator = (document, operations) => {
+  return { ...document, ...operations };
+};
+
+/**
+ * Applies $unset operator to document.
+ * @param {Object} document - Document to update
+ * @param {Object} operations - Unset operations
+ * @returns {Object} Updated document
+ */
+const apply_unset_operator = (document, operations) => {
+  const updated_document = { ...document };
+  for (const field of Object.keys(operations)) {
+    delete updated_document[field];
+  }
+  return updated_document;
+};
+
+/**
+ * Applies $inc operator to document.
+ * @param {Object} document - Document to update
+ * @param {Object} operations - Increment operations
+ * @returns {Object} Updated document
+ */
+const apply_inc_operator = (document, operations) => {
+  const updated_document = { ...document };
+  for (const [field, value] of Object.entries(operations)) {
+    updated_document[field] = (updated_document[field] || 0) + value;
+  }
+  return updated_document;
+};
+
+/**
+ * Applies $push operator to document.
+ * @param {Object} document - Document to update
+ * @param {Object} operations - Push operations
+ * @returns {Object} Updated document
+ */
+const apply_push_operator = (document, operations) => {
+  const updated_document = { ...document };
+  for (const [field, value] of Object.entries(operations)) {
+    if (!Array.isArray(updated_document[field])) {
+      updated_document[field] = [];
+    }
+    updated_document[field] = [...updated_document[field], value];
+  }
+  return updated_document;
+};
+
+/**
+ * Applies $pull operator to document.
+ * @param {Object} document - Document to update
+ * @param {Object} operations - Pull operations
+ * @returns {Object} Updated document
+ */
+const apply_pull_operator = (document, operations) => {
+  const updated_document = { ...document };
+  for (const [field, value] of Object.entries(operations)) {
+    if (Array.isArray(updated_document[field])) {
+      updated_document[field] = updated_document[field].filter(item => item !== value);
+    }
+  }
+  return updated_document;
+};
+
 /**
  * Applies MongoDB-style update operators to a document.
- * Supports $set, $unset, $inc, $push, and $pull operators for document modification.
- * Creates a new document object without mutating the original.
  * @param {Object} document - Original document to update
  * @param {Object} update_operations - Update operations to apply
  * @returns {Object} Updated document with applied operations
  * @throws {Error} When unsupported update operator is used
  */
 const apply_update_operators = (document, update_operations) => {
-  const updated_document = { ...document };
+  let updated_document = { ...document };
   
   for (const [operator, operations] of Object.entries(update_operations)) {
     switch (operator) {
       case '$set':
-        Object.assign(updated_document, operations);
+        updated_document = apply_set_operator(updated_document, operations);
         break;
         
       case '$unset':
-        for (const field of Object.keys(operations)) {
-          delete updated_document[field];
-        }
+        updated_document = apply_unset_operator(updated_document, operations);
         break;
         
       case '$inc':
-        for (const [field, value] of Object.entries(operations)) {
-          updated_document[field] = (updated_document[field] || 0) + value;
-        }
+        updated_document = apply_inc_operator(updated_document, operations);
         break;
         
       case '$push':
-        for (const [field, value] of Object.entries(operations)) {
-          if (!Array.isArray(updated_document[field])) {
-            updated_document[field] = [];
-          }
-          updated_document[field].push(value);
-        }
+        updated_document = apply_push_operator(updated_document, operations);
         break;
         
       case '$pull':
-        for (const [field, value] of Object.entries(operations)) {
-          if (Array.isArray(updated_document[field])) {
-            updated_document[field] = updated_document[field].filter(item => item !== value);
-          }
-        }
+        updated_document = apply_pull_operator(updated_document, operations);
         break;
         
       default:
@@ -66,10 +167,19 @@ const apply_update_operators = (document, update_operations) => {
   return updated_document;
 };
 
+/**
+ * Checks if document field matches filter value.
+ * @param {Object} document - Document to check
+ * @param {string} field - Field name
+ * @param {any} value - Expected value
+ * @returns {boolean} True if field matches value
+ */
+const field_matches_value = (document, field, value) => {
+  return document[field] === value;
+};
+
 /**
  * Checks if a document matches the provided filter criteria.
- * Performs exact field matching for all filter properties.
- * Empty or null filters match all documents.
  * @param {Object} document - Document to check against filter
  * @param {Object} filter - Filter criteria for matching
  * @returns {boolean} True if document matches all filter criteria
@@ -80,7 +190,7 @@ const matches_filter = (document, filter) => {
   }
   
   for (const [field, value] of Object.entries(filter)) {
-    if (document[field] !== value) {
+    if (!field_matches_value(document, field, value)) {
       return false;
     }
   }
@@ -88,64 +198,88 @@ const matches_filter = (document, filter) => {
   return true;
 };
 
+/**
+ * Validates insert operation document.
+ * @param {Object} document_data - Document to validate
+ * @throws {Error} When document is invalid
+ */
+const validate_insert_document = (document_data) => {
+  if (!document_data || typeof document_data !== 'object') {
+    throw new Error('insertOne operation requires a valid document');
+  }
+};
+
+/**
+ * Creates current timestamp string.
+ * @returns {string} ISO timestamp string
+ */
+const create_current_timestamp = () => {
+  return new Date().toISOString();
+};
+
+/**
+ * Prepares document for insertion with ID and timestamps.
+ * @param {Object} document_data - Original document
+ * @returns {Object} Document prepared for insertion
+ */
+const prepare_document_for_insertion = (document_data) => {
+  const document_id = document_data._id || generate_document_id();
+  const current_timestamp = create_current_timestamp();
+  
+  return {
+    ...document_data,
+    _id: document_id,
+    _created_at: current_timestamp,
+    _updated_at: current_timestamp
+  };
+};
+
+/**
+ * Checks if document already exists in database.
+ * @param {Object} db - Database instance
+ * @param {string} collection_key - Collection key for document
+ * @param {string} document_id - Document ID
+ * @throws {Error} When document already exists
+ */
+const check_document_does_not_exist = (db, collection_key, document_id) => {
+  const existing_document_data = db.get(collection_key);
+  if (existing_document_data) {
+    throw new Error(`Document with _id ${document_id} already exists`);
+  }
+};
+
 /**
  * Processes a single insert operation within a bulk write transaction.
- * Validates document, generates ID if needed, checks for duplicates, and inserts document.
- * Adds creation and update timestamps automatically.
  * @param {Object} db - LMDB database instance
  * @param {string} database_name - Name of the database
  * @param {string} collection_name - Name of the collection
  * @param {Object} operation - Insert operation data
- * @param {Object} operation.document - Document to insert
  * @returns {Object} Insert result with inserted_id
- * @throws {Error} When document is invalid or already exists
  */
 const process_insert_one = (db, database_name, collection_name, operation) => {
   const document_data = operation.document;
   
-  if (!document_data || typeof document_data !== 'object') {
-    throw new Error('insertOne operation requires a valid document');
-  }
+  validate_insert_document(document_data);
   
-  const document_id = document_data._id || generate_document_id();
-  const collection_key = build_collection_key(database_name, collection_name, document_id);
+  const document_to_insert = prepare_document_for_insertion(document_data);
+  const collection_key = build_collection_key(database_name, collection_name, document_to_insert._id);
   
-  const existing_document_data = db.get(collection_key);
-  if (existing_document_data) {
-    throw new Error(`Document with _id ${document_id} already exists`);
-  }
-  
-  const document_to_insert = {
-    ...document_data,
-    _id: document_id,
-    _created_at: new Date().toISOString(),
-    _updated_at: new Date().toISOString()
-  };
+  check_document_does_not_exist(db, collection_key, document_to_insert._id);
   
   db.put(collection_key, JSON.stringify(document_to_insert));
   
   return {
-    inserted_id: document_id
+    inserted_id: document_to_insert._id
   };
 };
 
 /**
- * Processes a single update operation within a bulk write transaction.
- * Finds matching document, applies update operators, and handles upsert if specified.
- * Updates modification timestamp and tracks match/modification counts.
- * @param {Object} db - LMDB database instance
- * @param {string} database_name - Name of the database
- * @param {string} collection_name - Name of the collection
- * @param {Object} operation - Update operation data
- * @param {Object} operation.filter - Filter to find document to update
- * @param {Object} operation.update - Update operations to apply
- * @param {boolean} [operation.upsert=false] - Whether to insert if no match found
- * @returns {Object} Update result with counts and upserted_id if applicable
- * @throws {Error} When filter or update is invalid
+ * Validates update operation parameters.
+ * @param {Object} filter - Filter criteria
+ * @param {Object} update - Update operations
+ * @throws {Error} When parameters are invalid
  */
-const process_update_one = (db, database_name, collection_name, operation) => {
-  const { filter, update, upsert = false } = operation;
-  
+const validate_update_parameters = (filter, update) => {
   if (!filter || typeof filter !== 'object') {
     throw new Error('updateOne operation requires a valid filter');
   }
@@ -153,214 +287,344 @@ const process_update_one = (db, database_name, collection_name, operation) => {
   if (!update || typeof update !== 'object') {
     throw new Error('updateOne operation requires a valid update');
   }
+};
+
+/**
+ * Adds updated timestamp to document.
+ * @param {Object} document - Document to update
+ * @returns {Object} Document with updated timestamp
+ */
+const add_updated_timestamp = (document) => {
+  return {
+    ...document,
+    _updated_at: create_current_timestamp()
+  };
+};
+
+/**
+ * Checks if document has been modified.
+ * @param {Object} original_document - Original document
+ * @param {Object} updated_document - Updated document
+ * @returns {boolean} True if document was modified
+ */
+const document_was_modified = (original_document, updated_document) => {
+  return JSON.stringify(original_document) !== JSON.stringify(updated_document);
+};
+
+/**
+ * Creates new document for upsert operation.
+ * @param {Object} filter - Filter criteria
+ * @param {Object} update - Update operations
+ * @returns {Object} New document for upsert
+ */
+const create_upsert_document = (filter, update) => {
+  const document_id = generate_document_id();
+  const current_timestamp = create_current_timestamp();
   
-  const collection_prefix = `${database_name}:${collection_name}:`;
-  let matched_count = 0;
-  let modified_count = 0;
-  let upserted_id = null;
+  const base_document = {
+    ...filter,
+    _id: document_id,
+    _created_at: current_timestamp,
+    _updated_at: current_timestamp
+  };
   
+  return apply_update_operators(base_document, update);
+};
+
+/**
+ * Searches for and updates matching document.
+ * @param {Object} db - Database instance
+ * @param {string} database_name - Database name
+ * @param {string} collection_name - Collection name
+ * @param {Object} filter - Filter criteria
+ * @param {Object} update - Update operations
+ * @returns {Object|null} Update result or null if no match
+ */
+const find_and_update_document = (db, database_name, collection_name, filter, update) => {
+  const collection_prefix = `${database_name}:${collection_name}:`;
   const range = db.getRange({ start: collection_prefix, end: collection_prefix + '\xFF' });
+  
   for (const { key, value: document_data } of range) {
     const document = JSON.parse(document_data);
     if (matches_filter(document, filter)) {
-      matched_count = 1;
-      
       const updated_document = apply_update_operators(document, update);
-      updated_document._updated_at = new Date().toISOString();
+      const timestamped_document = add_updated_timestamp(updated_document);
       
-      if (JSON.stringify(document) !== JSON.stringify(updated_document)) {
-        db.put(key, JSON.stringify(updated_document));
+      let modified_count = 0;
+      if (document_was_modified(document, timestamped_document)) {
+        db.put(key, JSON.stringify(timestamped_document));
         modified_count = 1;
       }
       
-      return { matched_count, modified_count };
+      return { matched_count: 1, modified_count };
     }
   }
   
+  return null;
+};
+
+/**
+ * Processes a single update operation within a bulk write transaction.
+ * @param {Object} db - LMDB database instance
+ * @param {string} database_name - Name of the database
+ * @param {string} collection_name - Name of the collection
+ * @param {Object} operation - Update operation data
+ * @returns {Object} Update result with counts and upserted_id if applicable
+ */
+const process_update_one = (db, database_name, collection_name, operation) => {
+  const { filter, update, upsert = false } = operation;
+  
+  validate_update_parameters(filter, update);
+  
+  const update_result = find_and_update_document(db, database_name, collection_name, filter, update);
+  
+  if (update_result) {
+    return update_result;
+  }
+  
   if (upsert) {
-    const document_id = generate_document_id();
-    const collection_key = build_collection_key(database_name, collection_name, document_id);
-    
-    const new_document = {
-      ...filter,
-      _id: document_id,
-      _created_at: new Date().toISOString(),
-      _updated_at: new Date().toISOString()
-    };
+    const upserted_document = create_upsert_document(filter, update);
+    const collection_key = build_collection_key(database_name, collection_name, upserted_document._id);
     
-    const upserted_document = apply_update_operators(new_document, update);
     db.put(collection_key, JSON.stringify(upserted_document));
     
-    upserted_id = document_id;
+    return { matched_count: 0, modified_count: 0, upserted_id: upserted_document._id };
   }
   
-  return { matched_count, modified_count, upserted_id };
+  return { matched_count: 0, modified_count: 0 };
 };
 
 /**
- * Processes a single delete operation within a bulk write transaction.
- * Finds first matching document and removes it from the database.
- * Returns count of deleted documents (0 or 1).
- * @param {Object} db - LMDB database instance
- * @param {string} database_name - Name of the database
- * @param {string} collection_name - Name of the collection
- * @param {Object} operation - Delete operation data
- * @param {Object} operation.filter - Filter to find document to delete
- * @returns {Object} Delete result with deleted_count
+ * Validates delete operation filter.
+ * @param {Object} filter - Filter criteria
  * @throws {Error} When filter is invalid
  */
-const process_delete_one = (db, database_name, collection_name, operation) => {
-  const { filter } = operation;
-  
+const validate_delete_filter = (filter) => {
   if (!filter || typeof filter !== 'object') {
     throw new Error('deleteOne operation requires a valid filter');
   }
-  
+};
+
+/**
+ * Searches for and deletes matching document.
+ * @param {Object} db - Database instance
+ * @param {string} database_name - Database name
+ * @param {string} collection_name - Collection name
+ * @param {Object} filter - Filter criteria
+ * @returns {number} Number of deleted documents (0 or 1)
+ */
+const find_and_delete_document = (db, database_name, collection_name, filter) => {
   const collection_prefix = `${database_name}:${collection_name}:`;
-  
   const range = db.getRange({ start: collection_prefix, end: collection_prefix + '\xFF' });
+  
   for (const { key, value: document_data } of range) {
     const document = JSON.parse(document_data);
     if (matches_filter(document, filter)) {
       db.remove(key);
-      return { deleted_count: 1 };
+      return 1;
     }
   }
   
-  return { deleted_count: 0 };
+  return 0;
+};
+
+/**
+ * Processes a single delete operation within a bulk write transaction.
+ * @param {Object} db - LMDB database instance
+ * @param {string} database_name - Name of the database
+ * @param {string} collection_name - Name of the collection
+ * @param {Object} operation - Delete operation data
+ * @returns {Object} Delete result with deleted_count
+ */
+const process_delete_one = (db, database_name, collection_name, operation) => {
+  const { filter } = operation;
+  
+  validate_delete_filter(filter);
+  
+  const deleted_count = find_and_delete_document(db, database_name, collection_name, filter);
+  
+  return { deleted_count };
+};
+
+/**
+ * Creates initial bulk write results object.
+ * @returns {Object} Initial results object
+ */
+const create_initial_bulk_results = () => ({
+  acknowledged: true,
+  inserted_count: 0,
+  matched_count: 0,
+  modified_count: 0,
+  deleted_count: 0,
+  upserted_count: 0,
+  inserted_ids: {},
+  upserted_ids: {}
+});
+
+/**
+ * Normalizes operation type to handle both naming conventions.
+ * @param {string} operation_type - Original operation type
+ * @returns {string} Normalized operation type
+ */
+const normalize_operation_type = (operation_type) => {
+  const type_mappings = {
+    'insertOne': 'insert_one',
+    'updateOne': 'update_one',
+    'deleteOne': 'delete_one'
+  };
+  
+  return type_mappings[operation_type] || operation_type;
+};
+
+/**
+ * Processes insert operation result.
+ * @param {Object} results - Bulk results object
+ * @param {Object} result - Insert operation result
+ * @param {number} index - Operation index
+ */
+const process_insert_result = (results, result, index) => {
+  results.inserted_count++;
+  results.inserted_ids[index] = result.inserted_id;
+};
+
+/**
+ * Processes update operation result.
+ * @param {Object} results - Bulk results object
+ * @param {Object} result - Update operation result
+ * @param {number} index - Operation index
+ */
+const process_update_result = (results, result, index) => {
+  results.matched_count += result.matched_count;
+  results.modified_count += result.modified_count;
+  
+  if (result.upserted_id) {
+    results.upserted_count++;
+    results.upserted_ids[index] = result.upserted_id;
+  }
+};
+
+/**
+ * Processes delete operation result.
+ * @param {Object} results - Bulk results object
+ * @param {Object} result - Delete operation result
+ */
+const process_delete_result = (results, result) => {
+  results.deleted_count += result.deleted_count;
+};
+
+/**
+ * Processes a single bulk operation.
+ * @param {Object} db - Database instance
+ * @param {string} database_name - Database name
+ * @param {string} collection_name - Collection name
+ * @param {Object} operation - Operation to process
+ * @param {number} index - Operation index
+ * @param {Object} results - Bulk results object
+ */
+const process_single_operation = (db, database_name, collection_name, operation, index, results) => {
+  const operation_type = Object.keys(operation)[0];
+  const operation_data = operation[operation_type];
+  const normalized_type = normalize_operation_type(operation_type);
+  
+  switch (normalized_type) {
+    case 'insert_one': {
+      const result = process_insert_one(db, database_name, collection_name, operation_data);
+      process_insert_result(results, result, index);
+      break;
+    }
+    
+    case 'update_one': {
+      const result = process_update_one(db, database_name, collection_name, operation_data);
+      process_update_result(results, result, index);
+      break;
+    }
+    
+    case 'delete_one': {
+      const result = process_delete_one(db, database_name, collection_name, operation_data);
+      process_delete_result(results, result);
+      break;
+    }
+    
+    default:
+      throw new Error(`Unsupported bulk operation: ${operation_type}`);
+  }
 };
 
+/**
+ * Logs bulk write operation completion.
+ * @param {Function} log - Logger function
+ * @param {string} database_name - Database name
+ * @param {string} collection_name - Collection name
+ * @param {number} operations_count - Number of operations
+ * @param {Object} results - Operation results
+ */
+const log_bulk_write_completion = (log, database_name, collection_name, operations_count, results) => {
+  log.info('Bulk write operation completed', {
+    database: database_name,
+    collection: collection_name,
+    operations_count,
+    results
+  });
+};
+
+/**
+ * Creates write queue operation metadata.
+ * @param {string} database_name - Database name
+ * @param {string} collection_name - Collection name
+ * @param {number} operations_count - Number of operations
+ * @returns {Object} Operation metadata
+ */
+const create_write_queue_metadata = (database_name, collection_name, operations_count) => ({
+  operation: 'bulk_write',
+  database: database_name,
+  collection: collection_name,
+  operations_count
+});
+
 /**
  * Internal bulk write implementation with transaction support.
- * Processes all operations atomically within a single database transaction.
- * Supports insert_one, update_one, and delete_one operations with both naming conventions.
  * @param {string} database_name - Name of the database to operate on
  * @param {string} collection_name - Name of the collection to operate on
  * @param {Array<Object>} operations - Array of bulk operations to execute
- * @param {Object} [options={}] - Additional options for bulk write
+ * @param {Object} options - Additional options for bulk write
  * @returns {Promise<Object>} Bulk write results with operation counts and IDs
- * @throws {Error} When database name, collection name is missing, operations are invalid, or operation fails
  */
 const bulk_write_internal = async (database_name, collection_name, operations, options = {}) => {
   const log = create_context_logger();
   
-  if (!database_name) {
-    throw new Error('Database name is required');
-  }
-  
-  if (!collection_name) {
-    throw new Error('Collection name is required');
-  }
-  
-  if (!Array.isArray(operations) || operations.length === 0) {
-    throw new Error('Operations must be a non-empty array');
-  }
+  validate_bulk_write_parameters(database_name, collection_name, operations);
   
   const db = get_database();
-  const results = {
-    acknowledged: true,
-    inserted_count: 0,
-    matched_count: 0,
-    modified_count: 0,
-    deleted_count: 0,
-    upserted_count: 0,
-    inserted_ids: {},
-    upserted_ids: {}
-  };
+  const results = create_initial_bulk_results();
   
   await db.transaction(() => {
     operations.forEach((operation, index) => {
-      const operation_type = Object.keys(operation)[0];
-      const operation_data = operation[operation_type];
-      
-      // NOTE: Support both snake_case (preferred) and camelCase (backward compatibility).
-      switch (operation_type) {
-        case 'insert_one':
-        case 'insertOne': {
-          const result = process_insert_one(db, database_name, collection_name, operation_data);
-          results.inserted_count++;
-          results.inserted_ids[index] = result.inserted_id;
-          break;
-        }
-        
-        case 'update_one':
-        case 'updateOne': {
-          const result = process_update_one(db, database_name, collection_name, operation_data);
-          results.matched_count += result.matched_count;
-          results.modified_count += result.modified_count;
-          
-          if (result.upserted_id) {
-            results.upserted_count++;
-            results.upserted_ids[index] = result.upserted_id;
-          }
-          break;
-        }
-        
-        case 'delete_one':
-        case 'deleteOne': {
-          const result = process_delete_one(db, database_name, collection_name, operation_data);
-          results.deleted_count += result.deleted_count;
-          break;
-        }
-        
-        default:
-          throw new Error(`Unsupported bulk operation: ${operation_type}`);
-      }
+      process_single_operation(db, database_name, collection_name, operation, index, results);
     });
   });
   
-  log.info('Bulk write operation completed', {
-    database: database_name,
-    collection: collection_name,
-    operations_count: operations.length,
-    results
-  });
+  log_bulk_write_completion(log, database_name, collection_name, operations.length, results);
   
   return results;
 };
 
 /**
  * Executes bulk write operations with write queue serialization.
- * Provides atomic execution of multiple write operations within a single transaction.
- * Enqueues operation through write queue to ensure proper serialization and consistency.
  * @param {string} database_name - Name of the database to operate on
  * @param {string} collection_name - Name of the collection to operate on
  * @param {Array<Object>} operations - Array of bulk operations to execute
- * @param {Object} [options={}] - Additional options for bulk write
+ * @param {Object} options - Additional options for bulk write
  * @returns {Promise<Object>} Bulk write results
- * @returns {boolean} returns.acknowledged - Whether operation was acknowledged
- * @returns {number} returns.inserted_count - Number of documents inserted
- * @returns {number} returns.matched_count - Number of documents matched for updates
- * @returns {number} returns.modified_count - Number of documents actually modified
- * @returns {number} returns.deleted_count - Number of documents deleted
- * @returns {number} returns.upserted_count - Number of documents upserted
- * @returns {Object} returns.inserted_ids - Map of operation index to inserted document ID
- * @returns {Object} returns.upserted_ids - Map of operation index to upserted document ID
- * @throws {Error} When database name, collection name is missing or operations array is invalid
  */
 const bulk_write = async (database_name, collection_name, operations, options = {}) => {
-  if (!database_name) {
-    throw new Error('Database name is required');
-  }
-  
-  if (!collection_name) {
-    throw new Error('Collection name is required');
-  }
-  
-  if (!Array.isArray(operations) || operations.length === 0) {
-    throw new Error('Operations must be a non-empty array');
-  }
+  validate_bulk_write_parameters(database_name, collection_name, operations);
   
   const write_queue = get_write_queue();
+  const operation_metadata = create_write_queue_metadata(database_name, collection_name, operations.length);
   
   return await write_queue.enqueue_write_operation(
     () => bulk_write_internal(database_name, collection_name, operations, options),
-    {
-      operation: 'bulk_write',
-      database: database_name,
-      collection: collection_name,
-      operations_count: operations.length
-    }
+    operation_metadata
   );
 };