@joystick.js/db-canary 0.0.0-canary.2209

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

@@ -0,0 +1,367 @@
+/**
+ * @fileoverview Bulk write operations for JoystickDB with transaction support.
+ * Provides atomic bulk operations including insert, update, and delete operations
+ * with comprehensive error handling, index management, and write queue integration.
+ * Supports both snake_case and camelCase operation names for backward compatibility.
+ */
+
+import { get_database, generate_document_id, build_collection_key } from '../query_engine.js';
+import { get_write_queue } from '../write_queue.js';
+import create_logger from '../logger.js';
+
+const { create_context_logger } = create_logger('bulk_write');
+
+/**
+ * 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 };
+  
+  for (const [operator, operations] of Object.entries(update_operations)) {
+    switch (operator) {
+      case '$set':
+        Object.assign(updated_document, operations);
+        break;
+        
+      case '$unset':
+        for (const field of Object.keys(operations)) {
+          delete updated_document[field];
+        }
+        break;
+        
+      case '$inc':
+        for (const [field, value] of Object.entries(operations)) {
+          updated_document[field] = (updated_document[field] || 0) + value;
+        }
+        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);
+        }
+        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);
+          }
+        }
+        break;
+        
+      default:
+        throw new Error(`Unsupported update operator: ${operator}`);
+    }
+  }
+  
+  return updated_document;
+};
+
+/**
+ * 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
+ */
+const matches_filter = (document, filter) => {
+  if (!filter || Object.keys(filter).length === 0) {
+    return true;
+  }
+  
+  for (const [field, value] of Object.entries(filter)) {
+    if (document[field] !== value) {
+      return false;
+    }
+  }
+  
+  return true;
+};
+
+/**
+ * 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');
+  }
+  
+  const document_id = document_data._id || generate_document_id();
+  const collection_key = build_collection_key(database_name, collection_name, document_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()
+  };
+  
+  db.put(collection_key, JSON.stringify(document_to_insert));
+  
+  return {
+    inserted_id: document_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
+ */
+const process_update_one = (db, database_name, collection_name, operation) => {
+  const { filter, update, upsert = false } = operation;
+  
+  if (!filter || typeof filter !== 'object') {
+    throw new Error('updateOne operation requires a valid filter');
+  }
+  
+  if (!update || typeof update !== 'object') {
+    throw new Error('updateOne operation requires a valid update');
+  }
+  
+  const collection_prefix = `${database_name}:${collection_name}:`;
+  let matched_count = 0;
+  let modified_count = 0;
+  let upserted_id = null;
+  
+  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();
+      
+      if (JSON.stringify(document) !== JSON.stringify(updated_document)) {
+        db.put(key, JSON.stringify(updated_document));
+        modified_count = 1;
+      }
+      
+      return { matched_count, modified_count };
+    }
+  }
+  
+  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 = apply_update_operators(new_document, update);
+    db.put(collection_key, JSON.stringify(upserted_document));
+    
+    upserted_id = document_id;
+  }
+  
+  return { matched_count, modified_count, upserted_id };
+};
+
+/**
+ * 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
+ * @throws {Error} When filter is invalid
+ */
+const process_delete_one = (db, database_name, collection_name, operation) => {
+  const { filter } = operation;
+  
+  if (!filter || typeof filter !== 'object') {
+    throw new Error('deleteOne operation requires a valid 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 { deleted_count: 0 };
+};
+
+/**
+ * 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
+ * @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');
+  }
+  
+  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: {}
+  };
+  
+  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}`);
+      }
+    });
+  });
+  
+  log.info('Bulk write operation completed', {
+    database: database_name,
+    collection: collection_name,
+    operations_count: 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
+ * @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');
+  }
+  
+  const write_queue = get_write_queue();
+  
+  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
+    }
+  );
+};
+
+export default bulk_write;

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

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview Create index operation for JoystickDB collections.
+ * Provides functionality to create secondary indexes on collection fields with upsert capabilities.
+ */
+
+import { create_index } from '../index_manager.js';
+import create_logger from '../logger.js';
+
+const { create_context_logger } = create_logger('create_index');
+
+/**
+ * Creates or updates an index on a specified field in a collection.
+ * @param {string} database_name - Name of the database
+ * @param {string} collection_name - Name of the collection to create index for
+ * @param {string} field_name - Name of the field to index
+ * @param {Object} [options={}] - Index creation options
+ * @param {boolean} [options.unique] - Whether the index should enforce uniqueness
+ * @param {boolean} [options.sparse] - Whether the index should be sparse (skip null values)
+ * @returns {Promise<Object>} Index creation result with operation details and message
+ * @throws {Error} When database, collection name or field name is missing, or index creation fails
+ */
+const create_index_operation = async (database_name, collection_name, field_name, 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 (!field_name) {
+    throw new Error('Field name is required');
+  }
+  
+  try {
+    const result = await create_index(database_name, collection_name, field_name, options);
+    
+    const operation_type = result.operation_type || 'created';
+    const action_verb = operation_type === 'created' ? 'created' : 
+                       operation_type === 'updated' ? 'updated' : 
+                       'already exists';
+    
+    log.info(`Index ${action_verb} successfully`, {
+      database: database_name,
+      collection: collection_name,
+      field: field_name,
+      options,
+      operation_type
+    });
+    
+    return {
+      ...result,
+      message: `Index ${action_verb} on ${database_name}.${collection_name}.${field_name}`
+    };
+  } catch (error) {
+    log.error('Failed to create/upsert index', {
+      database: database_name,
+      collection: collection_name,
+      field: field_name,
+      error: error.message
+    });
+    throw error;
+  }
+};
+
+export default create_index_operation;

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

@@ -0,0 +1,114 @@
+import { get_database } from '../query_engine.js';
+import { update_indexes_on_delete } from '../index_manager.js';
+import { get_write_queue } from '../write_queue.js';
+import create_logger from '../logger.js';
+
+const { create_context_logger } = create_logger('delete_one');
+
+/**
+ * Checks if a document matches the given filter criteria (simple equality check).
+ * @param {Object} document - Document to test
+ * @param {Object} filter - Filter criteria
+ * @returns {boolean} True if document matches filter
+ */
+const matches_filter = (document, filter) => {
+  if (!filter || Object.keys(filter).length === 0) {
+    return true;
+  }
+  
+  for (const [field, value] of Object.entries(filter)) {
+    if (document[field] !== value) {
+      return false;
+    }
+  }
+  
+  return true;
+};
+
+/**
+ * Internal implementation of delete_one operation without write queue serialization.
+ * @param {string} database_name - Name of the database
+ * @param {string} collection_name - Name of the collection
+ * @param {Object} filter - Filter criteria to match document for deletion
+ * @param {Object} [options={}] - Delete options (currently unused)
+ * @returns {Promise<Object>} Delete result with acknowledged and deleted_count
+ * @throws {Error} When database name, collection name is missing or filter is invalid
+ */
+const delete_one_internal = async (database_name, collection_name, filter, 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 (!filter || typeof filter !== 'object') {
+    throw new Error('Filter must be a valid object');
+  }
+  
+  const db = get_database();
+  let deleted_count = 0;
+  let deleted_document = null;
+  
+  await db.transaction(() => {
+    const collection_prefix = `${database_name}:${collection_name}:`;
+    
+    const range = db.getRange({ start: collection_prefix, end: collection_prefix + '\xFF' });
+    for (const { key, value } of range) {
+      try {
+        const document = JSON.parse(value);
+        if (matches_filter(document, filter)) {
+          db.remove(key);
+          deleted_document = document;
+          deleted_count = 1;
+          break;
+        }
+      } catch (parse_error) {
+        // Skip documents that can't be parsed
+        continue;
+      }
+    }
+  });
+  
+  if (deleted_document) {
+    await update_indexes_on_delete(database_name, collection_name, deleted_document);
+  }
+  
+  log.info('Delete operation completed', {
+    database: database_name,
+    collection: collection_name,
+    deleted_count
+  });
+  
+  return {
+    acknowledged: true,
+    deleted_count
+  };
+};
+
+/**
+ * Deletes a single document from a collection with write queue serialization.
+ * @param {string} database_name - Name of the database
+ * @param {string} collection_name - Name of the collection
+ * @param {Object} filter - Filter criteria to match document for deletion
+ * @param {Object} [options={}] - Delete options
+ * @returns {Promise<Object>} Delete result with acknowledged and deleted_count
+ */
+const delete_one = async (database_name, collection_name, filter, options = {}) => {
+  const write_queue = get_write_queue();
+  
+  return await write_queue.enqueue_write_operation(
+    () => delete_one_internal(database_name, collection_name, filter, options),
+    {
+      operation: 'delete_one',
+      database: database_name,
+      collection: collection_name,
+      filter_keys: Object.keys(filter || {})
+    }
+  );
+};
+
+export default delete_one;

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

@@ -0,0 +1,58 @@
+/**
+ * @fileoverview Drop index operation for JoystickDB collections.
+ * Provides functionality to remove secondary indexes from collection fields.
+ */
+
+import { drop_index } from '../index_manager.js';
+import create_logger from '../logger.js';
+
+const { create_context_logger } = create_logger('drop_index');
+
+/**
+ * Drops an existing index from a specified field in a collection.
+ * @param {string} database_name - Name of the database containing the collection
+ * @param {string} collection_name - Name of the collection to drop index from
+ * @param {string} field_name - Name of the field to remove index from
+ * @returns {Promise<Object>} Index drop result with operation details and message
+ * @throws {Error} When database name, collection name or field name is missing, or index drop fails
+ */
+const drop_index_operation = async (database_name, collection_name, field_name) => {
+  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 (!field_name) {
+    throw new Error('Field name is required');
+  }
+  
+  try {
+    const result = await drop_index(database_name, collection_name, field_name);
+    
+    log.info('Index dropped successfully', {
+      database: database_name,
+      collection: collection_name,
+      field: field_name
+    });
+    
+    return {
+      ...result,
+      message: `Index dropped on ${database_name}.${collection_name}.${field_name}`
+    };
+  } catch (error) {
+    log.error('Failed to drop index', {
+      database: database_name,
+      collection: collection_name,
+      field: field_name,
+      error: error.message
+    });
+    throw error;
+  }
+};
+
+export default drop_index_operation;