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

package/src/client/index.js

@@ -3,23 +3,61 @@ import { EventEmitter } from 'events';
 import { encode as encode_messagepack, decode as decode_messagepack } from 'msgpackr';
 import Database from './database.js';
 
+/**
+ * Creates MessagePack encoding options for consistent serialization.
+ * @returns {Object} MessagePack encoding options
+ */
+const create_messagepack_options = () => ({
+  useFloat32: false,
+  int64AsType: 'number',
+  mapsAsObjects: true
+});
+
 /**
  * Encodes a message with MessagePack and prepends a 4-byte length header.
  * @param {any} data - The data to encode
  * @returns {Buffer} The encoded message with length header
  */
 const encode_message = (data) => {
-  // NOTE: Use compatible MessagePack options to avoid parsing issues.
-  const messagepack_data = encode_messagepack(data, {
-    useFloat32: false,
-    int64AsType: 'number',
-    mapsAsObjects: true
-  });
+  const messagepack_data = encode_messagepack(data, create_messagepack_options());
   const length_buffer = Buffer.allocUnsafe(4);
   length_buffer.writeUInt32BE(messagepack_data.length, 0);
   return Buffer.concat([length_buffer, messagepack_data]);
 };
 
+/**
+ * Extracts complete message from buffer when enough data is available.
+ * @param {Buffer} buffer - Current buffer
+ * @param {number} expected_length - Expected message length
+ * @returns {Object} Result with message data and remaining buffer
+ */
+const extract_complete_message = (buffer, expected_length) => {
+  const message_data = buffer.slice(0, expected_length);
+  const remaining_buffer = buffer.slice(expected_length);
+  
+  try {
+    const decoded_message = decode_messagepack(message_data, create_messagepack_options());
+    return { message: decoded_message, buffer: remaining_buffer };
+  } catch (error) {
+    throw new Error(`Invalid message format: ${error.message}`);
+  }
+};
+
+/**
+ * Reads length header from buffer if available.
+ * @param {Buffer} buffer - Current buffer
+ * @returns {Object} Result with expected length and remaining buffer
+ */
+const read_length_header = (buffer) => {
+  if (buffer.length < 4) {
+    return { expected_length: null, buffer };
+  }
+  
+  const expected_length = buffer.readUInt32BE(0);
+  const remaining_buffer = buffer.slice(4);
+  return { expected_length, buffer: remaining_buffer };
+};
+
 /**
  * Creates a message parser for handling TCP stream data with length-prefixed MessagePack messages.
  * @returns {Object} Parser object with parse_messages and reset methods
@@ -28,64 +66,143 @@ const create_message_parser = () => {
   let buffer = Buffer.alloc(0);
   let expected_length = null;
   
-  /**
-   * Parses incoming data and extracts complete messages.
-   * @param {Buffer} data - Raw TCP data
-   * @returns {Array} Array of decoded messages
-   * @throws {Error} When message format is invalid
-   */
   const parse_messages = (data) => {
     buffer = Buffer.concat([buffer, data]);
     const messages = [];
     
     while (buffer.length > 0) {
       if (expected_length === null) {
-        if (buffer.length < 4) {
+        const header_result = read_length_header(buffer);
+        expected_length = header_result.expected_length;
+        buffer = header_result.buffer;
+        
+        if (expected_length === null) {
           break;
         }
-        
-        expected_length = buffer.readUInt32BE(0);
-        buffer = buffer.slice(4);
       }
       
       if (buffer.length < expected_length) {
         break;
       }
       
-      const message_data = buffer.slice(0, expected_length);
-      buffer = buffer.slice(expected_length);
+      const message_result = extract_complete_message(buffer, expected_length);
+      messages.push(message_result.message);
+      buffer = message_result.buffer;
       expected_length = null;
-      
-      try {
-        // NOTE: Use compatible MessagePack options to avoid parsing issues.
-        const decoded_message = decode_messagepack(message_data, {
-          useFloat32: false,
-          int64AsType: 'number',
-          mapsAsObjects: true
-        });
-        messages.push(decoded_message);
-      } catch (error) {
-        throw new Error(`Invalid message format: ${error.message}`);
-      }
     }
     
     return messages;
   };
   
-  /**
-   * Resets the parser state, clearing buffers and expected length.
-   */
   const reset = () => {
     buffer = Buffer.alloc(0);
     expected_length = null;
   };
   
-  return {
-    parse_messages,
-    reset
-  };
+  return { parse_messages, reset };
 };
 
+/**
+ * Calculates exponential backoff delay with maximum limit.
+ * @param {number} attempt_number - Current attempt number
+ * @param {number} base_delay - Base delay in milliseconds
+ * @returns {number} Calculated delay in milliseconds
+ */
+const calculate_reconnect_delay = (attempt_number, base_delay) => {
+  return Math.min(base_delay * Math.pow(2, attempt_number - 1), 30000);
+};
+
+/**
+ * Creates default client options with fallback values.
+ * @param {Object} options - User provided options
+ * @returns {Object} Complete options object with defaults
+ */
+const create_client_options = (options = {}) => ({
+  host: options.host || 'localhost',
+  port: options.port || 1983,
+  password: options.password || null,
+  timeout: options.timeout || 5000,
+  reconnect: options.reconnect !== false,
+  max_reconnect_attempts: options.max_reconnect_attempts || 10,
+  reconnect_delay: options.reconnect_delay || 1000,
+  auto_connect: options.auto_connect !== false
+});
+
+/**
+ * Creates a connection timeout handler.
+ * @param {net.Socket} socket - Socket connection
+ * @param {Function} error_handler - Error handling function
+ * @param {number} timeout_ms - Timeout duration in milliseconds
+ * @returns {NodeJS.Timeout} Timeout reference
+ */
+const create_connection_timeout = (socket, error_handler, timeout_ms) => {
+  return setTimeout(() => {
+    if (socket && !socket.destroyed) {
+      socket.destroy();
+      error_handler(new Error('Connection timeout'));
+    }
+  }, timeout_ms);
+};
+
+/**
+ * Creates a request timeout handler.
+ * @param {Map} pending_requests - Map of pending requests
+ * @param {number} request_id - Request identifier
+ * @param {number} timeout_ms - Timeout duration in milliseconds
+ * @returns {NodeJS.Timeout} Timeout reference
+ */
+const create_request_timeout = (pending_requests, request_id, timeout_ms) => {
+  return setTimeout(() => {
+    const request = pending_requests.get(request_id);
+    if (request) {
+      pending_requests.delete(request_id);
+      request.reject(new Error('Request timeout'));
+    }
+  }, timeout_ms);
+};
+
+/**
+ * Clears all pending requests with error.
+ * @param {Map} pending_requests - Map of pending requests
+ * @param {string} error_message - Error message to send
+ */
+const clear_pending_requests = (pending_requests, error_message) => {
+  for (const [request_id, { reject, timeout }] of pending_requests) {
+    clearTimeout(timeout);
+    reject(new Error(error_message));
+  }
+  pending_requests.clear();
+};
+
+/**
+ * Determines if response indicates success.
+ * @param {Object} message - Server response message
+ * @returns {boolean} True if response indicates success
+ */
+const is_successful_response = (message) => {
+  return message.ok === 1 || message.ok === true;
+};
+
+/**
+ * Determines if response indicates failure.
+ * @param {Object} message - Server response message
+ * @returns {boolean} True if response indicates failure
+ */
+const is_error_response = (message) => {
+  return message.ok === 0 || message.ok === false;
+};
+
+/**
+ * Extracts error message from server response.
+ * @param {Object} message - Server response message
+ * @returns {string} Error message
+ */
+const extract_error_message = (message) => {
+  if (typeof message.error === 'string') {
+    return message.error;
+  }
+  return JSON.stringify(message.error) || 'Operation failed';
+};
 
 /**
  * @typedef {Object} ClientOptions
@@ -110,20 +227,17 @@ const create_message_parser = () => {
  * @fires JoystickDBClient#response
  */
 class JoystickDBClient extends EventEmitter {
-  /**
-   * Creates a new JoystickDB client instance.
-   * @param {ClientOptions} [options={}] - Client configuration options
-   */
   constructor(options = {}) {
     super();
     
-    this.host = options.host || 'localhost';
-    this.port = options.port || 1983;
-    this.password = options.password || null;
-    this.timeout = options.timeout || 5000;
-    this.reconnect = options.reconnect !== false;
-    this.max_reconnect_attempts = options.max_reconnect_attempts || 10;
-    this.reconnect_delay = options.reconnect_delay || 1000;
+    const client_options = create_client_options(options);
+    this.host = client_options.host;
+    this.port = client_options.port;
+    this.password = client_options.password;
+    this.timeout = client_options.timeout;
+    this.reconnect = client_options.reconnect;
+    this.max_reconnect_attempts = client_options.max_reconnect_attempts;
+    this.reconnect_delay = client_options.reconnect_delay;
     
     this.socket = null;
     this.message_parser = null;
@@ -137,14 +251,11 @@ class JoystickDBClient extends EventEmitter {
     this.request_id_counter = 0;
     this.request_queue = [];
     
-    if (options.auto_connect !== false) {
+    if (client_options.auto_connect) {
       this.connect();
     }
   }
   
-  /**
-   * Establishes connection to the JoystickDB server.
-   */
   connect() {
     if (this.is_connecting || this.is_connected) {
       return;
@@ -154,41 +265,25 @@ class JoystickDBClient extends EventEmitter {
     this.socket = new net.Socket();
     this.message_parser = create_message_parser();
     
-    const connection_timeout = setTimeout(() => {
-      if (this.socket && !this.is_connected) {
-        this.socket.destroy();
-        this.handle_connection_error(new Error('Connection timeout'));
-      }
-    }, this.timeout);
+    const connection_timeout = create_connection_timeout(
+      this.socket, 
+      this.handle_connection_error.bind(this), 
+      this.timeout
+    );
     
+    this.setup_socket_handlers(connection_timeout);
     this.socket.connect(this.port, this.host, () => {
-      clearTimeout(connection_timeout);
-      this.is_connected = true;
-      this.is_connecting = false;
-      this.reconnect_attempts = 0;
-      
-      this.emit('connect');
-      
-      if (this.password) {
-        this.authenticate();
-      } else {
-        // NOTE: If no password provided, assume development mode and skip authentication.
-        this.is_authenticated = true;
-        this.emit('authenticated');
-        this.process_request_queue();
-      }
+      this.handle_successful_connection(connection_timeout);
     });
-    
+  }
+  
+  /**
+   * Sets up socket event handlers.
+   * @param {NodeJS.Timeout} connection_timeout - Connection timeout reference
+   */
+  setup_socket_handlers(connection_timeout) {
     this.socket.on('data', (data) => {
-      try {
-        const messages = this.message_parser.parse_messages(data);
-        
-        for (const message of messages) {
-          this.handle_message(message);
-        }
-      } catch (error) {
-        this.emit('error', new Error(`Message parsing failed: ${error.message}`));
-      }
+      this.handle_incoming_data(data);
     });
     
     this.socket.on('error', (error) => {
@@ -203,8 +298,49 @@ class JoystickDBClient extends EventEmitter {
   }
   
   /**
-   * Authenticates with the server using provided credentials.
+   * Handles successful socket connection.
+   * @param {NodeJS.Timeout} connection_timeout - Connection timeout reference
+   */
+  handle_successful_connection(connection_timeout) {
+    clearTimeout(connection_timeout);
+    this.is_connected = true;
+    this.is_connecting = false;
+    this.reconnect_attempts = 0;
+    
+    this.emit('connect');
+    
+    if (this.password) {
+      this.authenticate();
+    } else {
+      this.handle_authentication_complete();
+    }
+  }
+  
+  /**
+   * Handles completion of authentication process.
+   */
+  handle_authentication_complete() {
+    this.is_authenticated = true;
+    this.emit('authenticated');
+    this.process_request_queue();
+  }
+  
+  /**
+   * Handles incoming data from socket.
+   * @param {Buffer} data - Raw TCP data
    */
+  handle_incoming_data(data) {
+    try {
+      const messages = this.message_parser.parse_messages(data);
+      
+      for (const message of messages) {
+        this.handle_message(message);
+      }
+    } catch (error) {
+      this.emit('error', new Error(`Message parsing failed: ${error.message}`));
+    }
+  }
+  
   async authenticate() {
     if (!this.password) {
       this.emit('error', new Error('Password required for authentication. Provide password in client options: joystickdb.client({ password: "your_password" })'));
@@ -218,9 +354,7 @@ class JoystickDBClient extends EventEmitter {
       });
       
       if (result.ok === 1) {
-        this.is_authenticated = true;
-        this.emit('authenticated');
-        this.process_request_queue();
+        this.handle_authentication_complete();
       } else {
         throw new Error('Authentication failed');
       }
@@ -230,58 +364,51 @@ class JoystickDBClient extends EventEmitter {
     }
   }
   
-  /**
-   * Handles incoming messages from the server.
-   * @param {Object} message - Decoded message from server
-   */
   handle_message(message) {
     if (this.pending_requests.size > 0) {
-      const [request_id, { resolve, reject, timeout }] = this.pending_requests.entries().next().value;
-      clearTimeout(timeout);
-      this.pending_requests.delete(request_id);
-      
-      if (message.ok === 1 || message.ok === true) {
-        resolve(message);
-      } else if (message.ok === 0 || message.ok === false) {
-        const error_message = typeof message.error === 'string' ? message.error : JSON.stringify(message.error) || 'Operation failed';
-        reject(new Error(error_message));
-      } else {
-        resolve(message);
-      }
+      this.handle_pending_request_response(message);
     } else {
       this.emit('response', message);
     }
   }
   
   /**
-   * Handles connection errors and manages reconnection logic.
-   * @param {Error} error - The connection error
+   * Handles response for pending request.
+   * @param {Object} message - Server response message
    */
-  handle_connection_error(error) {
-    this.is_connecting = false;
-    this.is_connected = false;
-    this.is_authenticated = false;
+  handle_pending_request_response(message) {
+    const [request_id, { resolve, reject, timeout }] = this.pending_requests.entries().next().value;
+    clearTimeout(timeout);
+    this.pending_requests.delete(request_id);
     
-    if (this.socket) {
-      this.socket.removeAllListeners();
-      this.socket.destroy();
-      this.socket = null;
+    if (is_successful_response(message)) {
+      resolve(message);
+    } else if (is_error_response(message)) {
+      const error_message = extract_error_message(message);
+      reject(new Error(error_message));
+    } else {
+      resolve(message);
     }
+  }
+  
+  handle_connection_error(error) {
+    this.reset_connection_state();
+    clear_pending_requests(this.pending_requests, 'Connection lost');
     
-    if (this.message_parser) {
-      this.message_parser.reset();
-    }
+    this.emit('error', error);
     
-    // NOTE: Reject all pending requests.
-    for (const [request_id, { reject, timeout }] of this.pending_requests) {
-      clearTimeout(timeout);
-      reject(new Error('Connection lost'));
+    if (this.should_attempt_reconnect()) {
+      this.schedule_reconnect();
+    } else {
+      this.emit('disconnect');
     }
-    this.pending_requests.clear();
-    
-    this.emit('error', error);
+  }
+  
+  handle_disconnect() {
+    this.reset_connection_state();
+    clear_pending_requests(this.pending_requests, 'Connection closed');
     
-    if (this.reconnect && this.reconnect_attempts < this.max_reconnect_attempts) {
+    if (this.should_attempt_reconnect()) {
       this.schedule_reconnect();
     } else {
       this.emit('disconnect');
@@ -289,45 +416,35 @@ class JoystickDBClient extends EventEmitter {
   }
   
   /**
-   * Handles disconnection events and manages reconnection logic.
+   * Resets connection state variables.
    */
-  handle_disconnect() {
+  reset_connection_state() {
+    this.is_connecting = false;
     this.is_connected = false;
     this.is_authenticated = false;
-    this.is_connecting = false;
     
     if (this.socket) {
       this.socket.removeAllListeners();
+      this.socket.destroy();
       this.socket = null;
     }
     
     if (this.message_parser) {
       this.message_parser.reset();
     }
-    
-    // NOTE: Reject all pending requests.
-    for (const [request_id, { reject, timeout }] of this.pending_requests) {
-      clearTimeout(timeout);
-      reject(new Error('Connection closed'));
-    }
-    this.pending_requests.clear();
-    
-    if (this.reconnect && this.reconnect_attempts < this.max_reconnect_attempts) {
-      this.schedule_reconnect();
-    } else {
-      this.emit('disconnect');
-    }
   }
   
   /**
-   * Schedules a reconnection attempt with exponential backoff.
+   * Determines if reconnection should be attempted.
+   * @returns {boolean} True if reconnection should be attempted
    */
+  should_attempt_reconnect() {
+    return this.reconnect && this.reconnect_attempts < this.max_reconnect_attempts;
+  }
+  
   schedule_reconnect() {
     this.reconnect_attempts++;
-    const delay = Math.min(
-      this.reconnect_delay * Math.pow(2, this.reconnect_attempts - 1),
-      30000
-    );
+    const delay = calculate_reconnect_delay(this.reconnect_attempts, this.reconnect_delay);
     
     this.emit('reconnecting', { attempt: this.reconnect_attempts, delay });
     
@@ -336,36 +453,16 @@ class JoystickDBClient extends EventEmitter {
     }, delay);
   }
   
-  /**
-   * Sends a request to the server.
-   * @param {string} op - Operation name
-   * @param {Object} [data={}] - Request data
-   * @param {boolean} [use_queue=true] - Whether to queue request if not connected
-   * @returns {Promise<Object>} Server response
-   */
   send_request(op, data = {}, use_queue = true) {
     return new Promise((resolve, reject) => {
       const request_id = ++this.request_id_counter;
-      const message = {
-        op,
-        data
-      };
+      const message = { op, data };
       
-      const request = {
-        message,
-        resolve,
-        reject,
-        request_id
-      };
+      const request = { message, resolve, reject, request_id };
       
-      if (!this.is_connected || (op !== 'authentication' && op !== 'setup' && op !== 'ping' && !this.is_authenticated)) {
-        if (use_queue) {
-          this.request_queue.push(request);
-          return;
-        } else {
-          reject(new Error('Not connected or authenticated'));
-          return;
-        }
+      if (this.should_queue_request(op, use_queue)) {
+        this.request_queue.push(request);
+        return;
       }
       
       this.send_request_now(request);
@@ -373,17 +470,22 @@ class JoystickDBClient extends EventEmitter {
   }
   
   /**
-   * Immediately sends a request to the server.
-   * @param {Object} request - Request object with message, resolve, reject, and request_id
+   * Determines if request should be queued.
+   * @param {string} op - Operation type
+   * @param {boolean} use_queue - Whether to use queue
+   * @returns {boolean} True if request should be queued
    */
+  should_queue_request(op, use_queue) {
+    const bypass_auth_ops = ['authentication', 'setup', 'ping'];
+    const needs_auth = !bypass_auth_ops.includes(op);
+    
+    return (!this.is_connected || (needs_auth && !this.is_authenticated)) && use_queue;
+  }
+  
   send_request_now(request) {
     const { message, resolve, reject, request_id } = request;
     
-    const timeout = setTimeout(() => {
-      this.pending_requests.delete(request_id);
-      reject(new Error('Request timeout'));
-    }, this.timeout);
-    
+    const timeout = create_request_timeout(this.pending_requests, request_id, this.timeout);
     this.pending_requests.set(request_id, { resolve, reject, timeout });
     
     try {
@@ -396,9 +498,6 @@ class JoystickDBClient extends EventEmitter {
     }
   }
   
-  /**
-   * Processes queued requests after connection and authentication.
-   */
   process_request_queue() {
     while (this.request_queue.length > 0 && this.is_connected && this.is_authenticated) {
       const request = this.request_queue.shift();
@@ -406,9 +505,6 @@ class JoystickDBClient extends EventEmitter {
     }
   }
   
-  /**
-   * Disconnects from the server and disables reconnection.
-   */
   disconnect() {
     this.reconnect = false;
     
@@ -422,30 +518,15 @@ class JoystickDBClient extends EventEmitter {
     }
   }
   
-  
-  
   // NOTE: Backup Operations.
-  /**
-   * Triggers an immediate backup.
-   * @returns {Promise<Object>} Backup result
-   */
   async backup_now() {
     return this.send_request('admin', { admin_action: 'backup_now' });
   }
   
-  /**
-   * Lists all available backups.
-   * @returns {Promise<Object>} Backups list
-   */
   async list_backups() {
     return this.send_request('admin', { admin_action: 'list_backups' });
   }
   
-  /**
-   * Restores from a specific backup.
-   * @param {string} backup_name - Name of backup to restore
-   * @returns {Promise<Object>} Restore result
-   */
   async restore_backup(backup_name) {
     return this.send_request('admin', { 
       admin_action: 'restore_backup', 
@@ -454,96 +535,48 @@ class JoystickDBClient extends EventEmitter {
   }
   
   // NOTE: Replication Operations.
-  /**
-   * Gets replication status and statistics.
-   * @returns {Promise<Object>} Replication status
-   */
   async get_replication_status() {
     return this.send_request('admin', { admin_action: 'get_replication_status' });
   }
 
-  /**
-   * Adds a secondary node to replication.
-   * @param {Object} secondary - Secondary node configuration
-   * @param {string} secondary.id - Secondary node ID
-   * @param {string} secondary.ip - Secondary node IP address
-   * @param {number} secondary.port - Secondary node port
-   * @param {string} secondary.private_key - Base64 encoded private key
-   * @returns {Promise<Object>} Add secondary result
-   */
   async add_secondary(secondary) {
     return this.send_request('admin', { admin_action: 'add_secondary', ...secondary });
   }
 
-  /**
-   * Removes a secondary node from replication.
-   * @param {string} secondary_id - Secondary node ID to remove
-   * @returns {Promise<Object>} Remove secondary result
-   */
   async remove_secondary(secondary_id) {
     return this.send_request('admin', { admin_action: 'remove_secondary', secondary_id });
   }
 
-  /**
-   * Forces synchronization with all secondary nodes.
-   * @returns {Promise<Object>} Sync result
-   */
   async sync_secondaries() {
     return this.send_request('admin', { admin_action: 'sync_secondaries' });
   }
 
-  /**
-   * Gets health status of secondary nodes.
-   * @returns {Promise<Object>} Secondary health status
-   */
   async get_secondary_health() {
     return this.send_request('admin', { admin_action: 'get_secondary_health' });
   }
 
-  /**
-   * Gets write forwarder status (for secondary nodes).
-   * @returns {Promise<Object>} Write forwarder status
-   */
   async get_forwarder_status() {
     return this.send_request('admin', { admin_action: 'get_forwarder_status' });
   }
   
   // NOTE: Health and Utility Operations.
-  /**
-   * Pings the server to check connectivity.
-   * @returns {Promise<Object>} Ping result
-   */
   async ping() {
     return this.send_request('ping', {}, false);
   }
   
-  /**
-   * Reloads server configuration.
-   * @returns {Promise<Object>} Reload result
-   */
   async reload() {
     return this.send_request('reload');
   }
   
   // NOTE: Auto-Indexing Operations.
-  /**
-   * Gets automatic indexing statistics.
-   * @returns {Promise<Object>} Auto-indexing statistics
-   */
   async get_auto_index_stats() {
     return this.send_request('admin', { admin_action: 'get_auto_index_stats' });
   }
   
-  
   // NOTE: Setup Operation.
-  /**
-   * Performs initial server setup.
-   * @returns {Promise<Object>} Setup result
-   */
   async setup() {
     const result = await this.send_request('setup', {}, false);
     
-    // NOTE: Display setup instructions to user.
     if (result.data && result.data.instructions) {
       console.log(result.data.instructions);
     }
@@ -552,14 +585,6 @@ class JoystickDBClient extends EventEmitter {
   }
   
   // NOTE: Database Operations.
-  /**
-   * Deletes multiple documents from a collection.
-   * @param {string} collection - Collection name
-   * @param {Object} [filter={}] - Query filter to match documents
-   * @param {Object} [options={}] - Delete options
-   * @param {number} [options.limit] - Maximum number of documents to delete
-   * @returns {Promise<Object>} Delete result with acknowledged, deleted_count, and operation_time
-   */
   async delete_many(collection, filter = {}, options = {}) {
     return this.send_request('delete_many', { 
       collection, 
@@ -569,24 +594,19 @@ class JoystickDBClient extends EventEmitter {
   }
   
   // NOTE: Database Interface.
-  /**
-   * Returns a database interface for method chaining operations.
-   * @param {string} database_name - Database name
-   * @returns {Database} Database interface instance
-   */
   db(database_name) {
     return new Database(this, database_name);
   }
   
-  
   // NOTE: Multi-Database Admin Operations.
-  /**
-   * Lists all databases on the server.
-   * @returns {Promise<Object>} Databases list
-   */
   async list_databases() {
     return this.send_request('admin', { admin_action: 'list_databases' });
   }
+  
+  // NOTE: Statistics Operations.
+  async get_stats() {
+    return this.send_request('admin', { admin_action: 'stats' });
+  }
 }
 
 /**
@@ -594,24 +614,12 @@ class JoystickDBClient extends EventEmitter {
  * Provides a fluent API for database operations on a specific collection.
  */
 class Collection {
-  /**
-   * Creates a new Collection instance.
-   * @param {JoystickDBClient} client - The client instance
-   * @param {string} database_name - Name of the database
-   * @param {string} collection_name - Name of the collection
-   */
   constructor(client, database_name, collection_name) {
     this.client = client;
     this.database_name = database_name;
     this.collection_name = collection_name;
   }
   
-  /**
-   * Inserts a single document into the collection.
-   * @param {Object} document - Document to insert
-   * @param {Object} [options={}] - Insert options
-   * @returns {Promise<Object>} Insert result
-   */
   async insert_one(document, options = {}) {
     return this.client.send_request('insert_one', { 
       database: this.database_name,
@@ -621,12 +629,6 @@ class Collection {
     });
   }
   
-  /**
-   * Finds a single document in the collection.
-   * @param {Object} [filter={}] - Query filter
-   * @param {Object} [options={}] - Find options
-   * @returns {Promise<Object|null>} Found document or null
-   */
   async find_one(filter = {}, options = {}) {
     const result = await this.client.send_request('find_one', { 
       database: this.database_name,
@@ -637,12 +639,6 @@ class Collection {
     return result.document;
   }
   
-  /**
-   * Finds multiple documents in the collection.
-   * @param {Object} [filter={}] - Query filter
-   * @param {Object} [options={}] - Find options
-   * @returns {Promise<Array>} Array of found documents
-   */
   async find(filter = {}, options = {}) {
     const result = await this.client.send_request('find', { 
       database: this.database_name,
@@ -650,16 +646,9 @@ class Collection {
       filter, 
       options 
     });
-    return result.documents || [];
+    return { documents: result.documents || [] };
   }
   
-  /**
-   * Updates a single document in the collection.
-   * @param {Object} filter - Query filter to match document
-   * @param {Object} update - Update operations
-   * @param {Object} [options={}] - Update options
-   * @returns {Promise<Object>} Update result
-   */
   async update_one(filter, update, options = {}) {
     return this.client.send_request('update_one', { 
       database: this.database_name,
@@ -670,12 +659,6 @@ class Collection {
     });
   }
   
-  /**
-   * Deletes a single document from the collection.
-   * @param {Object} filter - Query filter to match document
-   * @param {Object} [options={}] - Delete options
-   * @returns {Promise<Object>} Delete result
-   */
   async delete_one(filter, options = {}) {
     return this.client.send_request('delete_one', { 
       database: this.database_name,
@@ -685,13 +668,6 @@ class Collection {
     });
   }
   
-  /**
-   * Deletes multiple documents from the collection.
-   * @param {Object} [filter={}] - Query filter to match documents
-   * @param {Object} [options={}] - Delete options
-   * @param {number} [options.limit] - Maximum number of documents to delete
-   * @returns {Promise<Object>} Delete result with acknowledged, deleted_count, and operation_time
-   */
   async delete_many(filter = {}, options = {}) {
     return this.client.send_request('delete_many', { 
       database: this.database_name,
@@ -701,12 +677,6 @@ class Collection {
     });
   }
   
-  /**
-   * Performs multiple write operations in a single request.
-   * @param {Array<Object>} operations - Array of write operations
-   * @param {Object} [options={}] - Bulk write options
-   * @returns {Promise<Object>} Bulk write result
-   */
   async bulk_write(operations, options = {}) {
     return this.client.send_request('bulk_write', { 
       database: this.database_name,
@@ -716,12 +686,6 @@ class Collection {
     });
   }
   
-  /**
-   * Creates an index on a collection field.
-   * @param {string} field - Field name to index
-   * @param {Object} [options={}] - Index options
-   * @returns {Promise<Object>} Index creation result
-   */
   async create_index(field, options = {}) {
     return this.client.send_request('create_index', { 
       database: this.database_name,
@@ -731,12 +695,6 @@ class Collection {
     });
   }
   
-  /**
-   * Creates or updates an index on a collection field (upsert operation).
-   * @param {string} field - Field name to index
-   * @param {Object} [options={}] - Index options
-   * @returns {Promise<Object>} Index upsert result
-   */
   async upsert_index(field, options = {}) {
     return this.client.send_request('create_index', { 
       database: this.database_name,
@@ -746,11 +704,6 @@ class Collection {
     });
   }
   
-  /**
-   * Drops an index from a collection field.
-   * @param {string} field - Field name of index to drop
-   * @returns {Promise<Object>} Index drop result
-   */
   async drop_index(field) {
     return this.client.send_request('drop_index', { 
       database: this.database_name,
@@ -759,10 +712,6 @@ class Collection {
     });
   }
   
-  /**
-   * Gets all indexes for the collection.
-   * @returns {Promise<Object>} Indexes information
-   */
   async get_indexes() {
     return this.client.send_request('get_indexes', { 
       database: this.database_name,
@@ -771,19 +720,9 @@ class Collection {
   }
 }
 
-// NOTE: Add Collection class as static property for Database class access.
 JoystickDBClient.Collection = Collection;
 
-/**
- * JoystickDB client factory and utilities.
- * @namespace
- */
 const joystickdb = {
-  /**
-   * Creates a new JoystickDB client instance.
-   * @param {ClientOptions} options - Client configuration options
-   * @returns {JoystickDBClient} New client instance
-   */
   client: (options) => new JoystickDBClient(options)
 };