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

package/types/client/index.d.ts

@@ -0,0 +1,447 @@
+export default joystickdb;
+export type ClientOptions = {
+    /**
+     * - Server hostname
+     */
+    host?: string;
+    /**
+     * - Server port
+     */
+    port?: number;
+    /**
+     * - Authentication options
+     */
+    authentication?: {
+        password?: string;
+    };
+    /**
+     * - Request timeout in milliseconds
+     */
+    timeout?: number;
+    /**
+     * - Enable automatic reconnection
+     */
+    reconnect?: boolean;
+    /**
+     * - Maximum reconnection attempts
+     */
+    max_reconnect_attempts?: number;
+    /**
+     * - Initial reconnection delay in milliseconds
+     */
+    reconnect_delay?: number;
+    /**
+     * - Automatically connect on instantiation
+     */
+    auto_connect?: boolean;
+};
+
+/**
+ * Bulk write operation types using snake_case naming convention
+ */
+export type BulkInsertOperation = {
+    insert_one: {
+        document: any;
+    };
+};
+
+export type BulkUpdateOperation = {
+    update_one: {
+        filter: any;
+        update: any;
+        upsert?: boolean;
+    };
+};
+
+export type BulkDeleteOperation = {
+    delete_one: {
+        filter: any;
+    };
+};
+
+/**
+ * Union type for all bulk write operations
+ */
+export type BulkWriteOperation = BulkInsertOperation | BulkUpdateOperation | BulkDeleteOperation;
+
+/**
+ * Legacy bulk write operation types using camelCase naming (deprecated but supported for backward compatibility)
+ */
+export type LegacyBulkInsertOperation = {
+    insertOne: {
+        document: any;
+    };
+};
+
+export type LegacyBulkUpdateOperation = {
+    updateOne: {
+        filter: any;
+        update: any;
+        upsert?: boolean;
+    };
+};
+
+export type LegacyBulkDeleteOperation = {
+    deleteOne: {
+        filter: any;
+    };
+};
+
+/**
+ * Union type for legacy bulk write operations (backward compatibility)
+ */
+export type LegacyBulkWriteOperation = LegacyBulkInsertOperation | LegacyBulkUpdateOperation | LegacyBulkDeleteOperation;
+declare namespace joystickdb {
+    function client(options: ClientOptions): JoystickDBClient;
+}
+/**
+ * @typedef {Object} ClientOptions
+ * @property {string} [host='localhost'] - Server hostname
+ * @property {number} [port=1983] - Server port
+ * @property {Object} [authentication={}] - Authentication options
+ * @property {string} [authentication.password] - Authentication password
+ * @property {number} [timeout=5000] - Request timeout in milliseconds
+ * @property {boolean} [reconnect=true] - Enable automatic reconnection
+ * @property {number} [max_reconnect_attempts=10] - Maximum reconnection attempts
+ * @property {number} [reconnect_delay=1000] - Initial reconnection delay in milliseconds
+ * @property {boolean} [auto_connect=true] - Automatically connect on instantiation
+ */
+/**
+ * JoystickDB TCP client for connecting to JoystickDB server.
+ * @extends EventEmitter
+ * @fires JoystickDBClient#connect
+ * @fires JoystickDBClient#authenticated
+ * @fires JoystickDBClient#error
+ * @fires JoystickDBClient#disconnect
+ * @fires JoystickDBClient#reconnecting
+ * @fires JoystickDBClient#response
+ */
+declare class JoystickDBClient extends EventEmitter<[never]> {
+    /**
+     * Creates a new JoystickDB client instance.
+     * @param {ClientOptions} [options={}] - Client configuration options
+     */
+    constructor(options?: ClientOptions);
+    host: string;
+    port: number;
+    authentication: {
+        /**
+         * - Authentication password
+         */
+        password?: string;
+    };
+    timeout: number;
+    reconnect: boolean;
+    max_reconnect_attempts: number;
+    reconnect_delay: number;
+    socket: any;
+    message_parser: any;
+    is_connected: boolean;
+    is_authenticated: boolean;
+    is_connecting: boolean;
+    reconnect_attempts: number;
+    reconnect_timeout: NodeJS.Timeout;
+    pending_requests: Map<any, any>;
+    request_id_counter: number;
+    request_queue: any[];
+    /**
+     * Establishes connection to the JoystickDB server.
+     */
+    connect(): void;
+    /**
+     * Authenticates with the server using provided credentials.
+     * @throws {Error} When password is not provided or authentication fails
+     */
+    authenticate(): Promise<void>;
+    /**
+     * Handles incoming messages from the server.
+     * @param {Object} message - Decoded message from server
+     */
+    handle_message(message: any): void;
+    /**
+     * Handles connection errors and manages reconnection logic.
+     * @param {Error} error - The connection error
+     */
+    handle_connection_error(error: Error): void;
+    /**
+     * Handles disconnection events and manages reconnection logic.
+     */
+    handle_disconnect(): void;
+    /**
+     * Schedules a reconnection attempt with exponential backoff.
+     */
+    schedule_reconnect(): void;
+    /**
+     * 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: string, data?: any, use_queue?: boolean): Promise<any>;
+    /**
+     * Immediately sends a request to the server.
+     * @param {Object} request - Request object with message, resolve, reject, and request_id
+     */
+    send_request_now(request: any): void;
+    /**
+     * Processes queued requests after connection and authentication.
+     */
+    process_request_queue(): void;
+    /**
+     * Disconnects from the server and disables reconnection.
+     */
+    disconnect(): void;
+    /**
+     * Inserts a single document into a collection.
+     * @param {string} collection - Collection name
+     * @param {Object} document - Document to insert
+     * @param {Object} [options={}] - Insert options
+     * @returns {Promise<Object>} Insert result
+     */
+    insert_one(collection: string, document: any, options?: any): Promise<any>;
+    /**
+     * Finds a single document in a collection.
+     * @param {string} collection - Collection name
+     * @param {Object} [filter={}] - Query filter
+     * @param {Object} [options={}] - Find options
+     * @returns {Promise<Object|null>} Found document or null
+     */
+    find_one(collection: string, filter?: any, options?: any): Promise<any | null>;
+    /**
+     * Finds multiple documents in a collection.
+     * @param {string} collection - Collection name
+     * @param {Object} [filter={}] - Query filter
+     * @param {Object} [options={}] - Find options
+     * @returns {Promise<any[]>} Array of found documents
+     */
+    find(collection: string, filter?: any, options?: any): Promise<any[]>;
+    /**
+     * Updates a single document in a collection.
+     * @param {string} collection - Collection name
+     * @param {Object} filter - Query filter to match document
+     * @param {Object} update - Update operations
+     * @param {Object} [options={}] - Update options
+     * @returns {Promise<Object>} Update result
+     */
+    update_one(collection: string, filter: any, update: any, options?: any): Promise<any>;
+    /**
+     * Deletes a single document from a collection.
+     * @param {string} collection - Collection name
+     * @param {Object} filter - Query filter to match document
+     * @param {Object} [options={}] - Delete options
+     * @returns {Promise<Object>} Delete result
+     */
+    delete_one(collection: string, filter: any, options?: any): Promise<any>;
+    /**
+     * Performs multiple write operations in a single request.
+     * @param {string} collection - Collection name
+     * @param {Array<BulkWriteOperation | LegacyBulkWriteOperation>} operations - Array of write operations (supports both snake_case and camelCase)
+     * @param {Object} [options={}] - Bulk write options
+     * @returns {Promise<Object>} Bulk write result
+     */
+    bulk_write(collection: string, operations: Array<BulkWriteOperation | LegacyBulkWriteOperation>, options?: any): Promise<any>;
+    /**
+     * Creates an index on a collection field.
+     * @param {string} collection - Collection name
+     * @param {string} field - Field name to index
+     * @param {Object} [options={}] - Index options
+     * @returns {Promise<Object>} Index creation result
+     */
+    create_index(collection: string, field: string, options?: any): Promise<any>;
+    /**
+     * Creates or updates an index on a collection field (upsert operation).
+     * @param {string} collection - Collection name
+     * @param {string} field - Field name to index
+     * @param {Object} [options={}] - Index options
+     * @returns {Promise<Object>} Index upsert result
+     */
+    upsert_index(collection: string, field: string, options?: any): Promise<any>;
+    /**
+     * Drops an index from a collection field.
+     * @param {string} collection - Collection name
+     * @param {string} field - Field name of index to drop
+     * @returns {Promise<Object>} Index drop result
+     */
+    drop_index(collection: string, field: string): Promise<any>;
+    /**
+     * Gets all indexes for a collection.
+     * @param {string} collection - Collection name
+     * @returns {Promise<Object>} Indexes information
+     */
+    get_indexes(collection: string): Promise<any>;
+    /**
+     * Gets database statistics.
+     * @returns {Promise<Object>} Database statistics
+     */
+    get_stats(): Promise<any>;
+    /**
+     * Lists all collections in the database.
+     * @returns {Promise<Object>} Collections list
+     */
+    list_collections(): Promise<any>;
+    /**
+     * Lists documents in a collection with pagination.
+     * @param {string} collection - Collection name
+     * @param {Object} [options={}] - List options (limit, offset, etc.)
+     * @returns {Promise<Object>} Documents list
+     */
+    list_documents(collection: string, options?: any): Promise<any>;
+    /**
+     * Gets a specific document by ID.
+     * @param {string} collection - Collection name
+     * @param {string} document_id - Document ID
+     * @returns {Promise<Object>} Document data
+     */
+    get_document(collection: string, document_id: string): Promise<any>;
+    /**
+     * Queries documents with advanced filtering.
+     * @param {string} collection - Collection name
+     * @param {Object} [filter={}] - Query filter
+     * @param {Object} [options={}] - Query options
+     * @returns {Promise<Object>} Query results
+     */
+    query_documents(collection: string, filter?: any, options?: any): Promise<any>;
+    /**
+     * Inserts a document via admin interface.
+     * @param {string} collection - Collection name
+     * @param {Object} document - Document to insert
+     * @returns {Promise<Object>} Insert result
+     */
+    insert_document(collection: string, document: any): Promise<any>;
+    /**
+     * Updates a document by ID via admin interface.
+     * @param {string} collection - Collection name
+     * @param {string} document_id - Document ID
+     * @param {Object} update - Update operations
+     * @returns {Promise<Object>} Update result
+     */
+    update_document(collection: string, document_id: string, update: any): Promise<any>;
+    /**
+     * Deletes a document by ID via admin interface.
+     * @param {string} collection - Collection name
+     * @param {string} document_id - Document ID
+     * @returns {Promise<Object>} Delete result
+     */
+    delete_document(collection: string, document_id: string): Promise<any>;
+    /**
+     * Triggers an immediate backup.
+     * @returns {Promise<Object>} Backup result
+     */
+    backup_now(): Promise<any>;
+    /**
+     * Lists all available backups.
+     * @returns {Promise<Object>} Backups list
+     */
+    list_backups(): Promise<any>;
+    /**
+     * Restores from a specific backup.
+     * @param {string} backup_name - Name of backup to restore
+     * @returns {Promise<Object>} Restore result
+     */
+    restore_backup(backup_name: string): Promise<any>;
+    /**
+     * Pings the server to check connectivity.
+     * @returns {Promise<Object>} Ping result
+     */
+    ping(): Promise<any>;
+    /**
+     * Reloads server configuration.
+     * @returns {Promise<Object>} Reload result
+     */
+    reload(): Promise<any>;
+    /**
+     * Performs initial server setup.
+     * @returns {Promise<Object>} Setup result
+     */
+    setup(): Promise<any>;
+    /**
+     * Returns a collection interface for method chaining operations.
+     * @param {string} name - Collection name
+     * @returns {Collection} Collection interface instance
+     */
+    collection(name: string): Collection;
+}
+/**
+ * Collection interface for method chaining operations.
+ * Provides a fluent API for database operations on a specific collection.
+ */
+declare class Collection {
+    /**
+     * Creates a new Collection instance.
+     * @param {JoystickDBClient} client - The client instance
+     * @param {string} collection_name - Name of the collection
+     */
+    constructor(client: JoystickDBClient, collection_name: string);
+    client: JoystickDBClient;
+    collection_name: string;
+    /**
+     * Inserts a single document into the collection.
+     * @param {Object} document - Document to insert
+     * @param {Object} [options={}] - Insert options
+     * @returns {Promise<Object>} Insert result
+     */
+    insert_one(document: any, options?: any): Promise<any>;
+    /**
+     * 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
+     */
+    find_one(filter?: any, options?: any): Promise<any | null>;
+    /**
+     * Finds multiple documents in the collection.
+     * @param {Object} [filter={}] - Query filter
+     * @param {Object} [options={}] - Find options
+     * @returns {Promise<any[]>} Array of found documents
+     */
+    find(filter?: any, options?: any): Promise<any[]>;
+    /**
+     * 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
+     */
+    update_one(filter: any, update: any, options?: any): Promise<any>;
+    /**
+     * 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
+     */
+    delete_one(filter: any, options?: any): Promise<any>;
+    /**
+     * Performs multiple write operations in a single request.
+     * @param {Array<BulkWriteOperation | LegacyBulkWriteOperation>} operations - Array of write operations (supports both snake_case and camelCase)
+     * @param {Object} [options={}] - Bulk write options
+     * @returns {Promise<Object>} Bulk write result
+     */
+    bulk_write(operations: Array<BulkWriteOperation | LegacyBulkWriteOperation>, options?: any): Promise<any>;
+    /**
+     * 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
+     */
+    create_index(field: string, options?: any): Promise<any>;
+    /**
+     * 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
+     */
+    upsert_index(field: string, options?: any): Promise<any>;
+    /**
+     * Drops an index from a collection field.
+     * @param {string} field - Field name of index to drop
+     * @returns {Promise<Object>} Index drop result
+     */
+    drop_index(field: string): Promise<any>;
+    /**
+     * Gets all indexes for the collection.
+     * @returns {Promise<Object>} Indexes information
+     */
+    get_indexes(): Promise<any>;
+}
+import { EventEmitter } from 'events';

package/types/server/cluster/index.d.ts

@@ -0,0 +1,28 @@
+export default start_cluster;
+export type ClusterOptions = {
+    /**
+     * - Number of worker processes to spawn
+     */
+    worker_count?: number;
+    /**
+     * - Server port
+     */
+    port?: number;
+    /**
+     * - Settings file path
+     */
+    settings_file?: string;
+};
+/**
+ * @typedef {Object} ClusterOptions
+ * @property {number} [worker_count] - Number of worker processes to spawn
+ * @property {number} [port=1983] - Server port
+ * @property {string} [settings_file='settings.db.json'] - Settings file path
+ */
+/**
+ * Starts the cluster with master and worker processes.
+ * @param {ClusterOptions} [options={}] - Cluster configuration options
+ * @returns {ClusterMaster|undefined} Master instance if running as master, undefined if worker
+ */
+export function start_cluster(options?: ClusterOptions): ClusterMaster | undefined;
+import ClusterMaster from './master.js';

package/types/server/cluster/master.d.ts

@@ -0,0 +1,115 @@
+export default ClusterMaster;
+export type ClusterMasterOptions = {
+    /**
+     * - Number of worker processes to spawn
+     */
+    worker_count?: number;
+    /**
+     * - Server port
+     */
+    port?: number;
+    /**
+     * - Settings file path
+     */
+    settings_file?: string;
+};
+/**
+ * @typedef {Object} ClusterMasterOptions
+ * @property {number} [worker_count] - Number of worker processes to spawn
+ * @property {number} [port=1983] - Server port
+ * @property {string} [settings_file='settings.db.json'] - Settings file path
+ */
+/**
+ * Cluster master process that manages worker processes and coordinates database writes.
+ * @extends EventEmitter
+ * @fires ClusterMaster#writes_completed
+ */
+declare class ClusterMaster extends EventEmitter<[never]> {
+    /**
+     * Creates a new cluster master instance.
+     * @param {ClusterMasterOptions} [options={}] - Master configuration options
+     */
+    constructor(options?: ClusterMasterOptions);
+    workers: Map<any, any>;
+    write_queue: any[];
+    processing_writes: boolean;
+    authenticated_sessions: Map<any, any>;
+    worker_count: any;
+    port: number;
+    settings_file: string;
+    settings: any;
+    pending_writes: Map<any, any>;
+    write_id_counter: number;
+    shutting_down: boolean;
+    log: any;
+    /**
+     * Sets up the cluster master configuration and event handlers.
+     */
+    setup_master(): void;
+    /**
+     * Starts the cluster master and spawns worker processes.
+     * @throws {Error} When startup fails
+     */
+    start(): Promise<void>;
+    /**
+     * Spawns a new worker process.
+     * @returns {cluster.Worker} The spawned worker instance
+     */
+    spawn_worker(): cluster.Worker;
+    /**
+     * Handles worker process death and respawning.
+     * @param {cluster.Worker} dead_worker - The worker that died
+     */
+    handle_worker_death(dead_worker: cluster.Worker): void;
+    /**
+     * Handles messages from worker processes.
+     * @param {cluster.Worker} worker - Worker that sent the message
+     * @param {Object} message - Message from worker
+     */
+    handle_worker_message(worker: cluster.Worker, message: any): void;
+    handle_worker_ready_for_config(worker: any, message: any): void;
+    handle_worker_server_ready(worker: any, message: any): void;
+    /**
+     * Handles write requests from workers, queuing them for serialized execution.
+     * @param {cluster.Worker} worker - Worker requesting the write
+     * @param {Object} message - Write request message
+     */
+    handle_write_request(worker: cluster.Worker, message: any): Promise<void>;
+    /**
+     * Processes the write queue, executing operations serially.
+     */
+    process_write_queue(): Promise<void>;
+    /**
+     * Executes a single write operation and sends response to worker.
+     * @param {Object} write_op - Write operation to execute
+     */
+    execute_write_operation(write_op: any): Promise<void>;
+    /**
+     * Performs the actual database write operation.
+     * @param {string} op_type - Type of write operation
+     * @param {Object} data - Operation data
+     * @returns {Promise<Object>} Operation result
+     * @throws {Error} When operation fails or is unsupported
+     */
+    perform_database_write(op_type: string, data: any): Promise<any>;
+    /**
+     * Broadcasts write notifications to all workers except the originating one.
+     * @param {string} op_type - Type of write operation
+     * @param {Object} data - Operation data
+     * @param {number} exclude_worker_id - Worker ID to exclude from broadcast
+     */
+    broadcast_write_notification(op_type: string, data: any, exclude_worker_id: number): void;
+    handle_auth_request(worker: any, message: any): void;
+    update_worker_connections(worker: any, message: any): void;
+    handle_worker_heartbeat(worker: any, message: any): void;
+    /**
+     * Gets comprehensive cluster statistics.
+     * @returns {Object} Cluster statistics including worker info and connection counts
+     */
+    get_cluster_stats(): any;
+    /**
+     * Performs graceful shutdown of the cluster master and all workers.
+     */
+    shutdown(): Promise<void>;
+}
+import { EventEmitter } from 'events';

package/types/server/cluster/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/types/server/lib/auth_manager.d.ts

@@ -0,0 +1,13 @@
+export function setup_authentication(): any;
+export function verify_password(password: any, ip: any): Promise<boolean>;
+export function get_client_ip(socket: any): any;
+export function is_rate_limited(ip: any): boolean;
+export function get_auth_stats(): {
+    configured: boolean;
+    failed_attempts_count: number;
+    rate_limited_ips: number;
+    created_at: any;
+    last_updated: any;
+};
+export function initialize_auth_manager(): void;
+export function reset_auth_state(): void;

package/types/server/lib/backup_manager.d.ts

@@ -0,0 +1,43 @@
+export function get_s3_client(): {
+    client: any;
+    bucket: any;
+};
+export function test_s3_connection(): Promise<boolean>;
+export function create_backup(): Promise<{
+    filename: string;
+    size_bytes: number;
+    checksum: any;
+    created_at: string;
+    duration_ms: number;
+    s3_location: string;
+}>;
+export function list_backups(): Promise<{
+    backups: any[];
+    total_count: number;
+    total_size_bytes: number;
+    total_size_mb?: undefined;
+} | {
+    backups: any;
+    total_count: any;
+    total_size_bytes: any;
+    total_size_mb: number;
+}>;
+export function restore_backup(backup_filename: any): Promise<{
+    backup_filename: any;
+    restored_at: string;
+    duration_ms: number;
+    status: string;
+}>;
+export function cleanup_old_backups(): Promise<{
+    deleted_count: number;
+    retained_count: number;
+    hourly_backups?: undefined;
+    daily_backups?: undefined;
+} | {
+    deleted_count: number;
+    retained_count: number;
+    hourly_backups: number;
+    daily_backups: number;
+}>;
+export function start_backup_schedule(): void;
+export function stop_backup_schedule(): void;

package/types/server/lib/connection_manager.d.ts

@@ -0,0 +1,15 @@
+export function create_connection_manager(options?: {}): {
+    add_connection: (socket: any) => boolean;
+    remove_connection: (socket_id: any) => void;
+    update_activity: (socket_id: any) => void;
+    create_request_timeout: (socket_id: any, operation: any) => NodeJS.Timeout;
+    get_stats: () => {
+        total_connections: number;
+        max_connections: any;
+        total_requests: number;
+        oldest_connection_age_ms: number;
+        idle_timeout_ms: any;
+        request_timeout_ms: any;
+    };
+    shutdown: () => void;
+};

package/types/server/lib/disk_utils.d.ts

@@ -0,0 +1,3 @@
+export function get_disk_size(path?: string): Promise<number>;
+export function calculate_map_size(database_path?: string): Promise<number>;
+export function should_grow_map_size(current_size: any, used_size: any, disk_size: any): number;

package/types/server/lib/index_manager.d.ts

@@ -0,0 +1,24 @@
+export function initialize_index_database(): any;
+export function get_index_database(): any;
+export function create_index(collection_name: any, field_name: any, options?: {}): Promise<{
+    acknowledged: boolean;
+}>;
+export function drop_index(collection_name: any, field_name: any): Promise<{
+    acknowledged: boolean;
+}>;
+export function get_indexes(collection_name: any): any[];
+export function update_indexes_on_insert(collection_name: any, document: any): Promise<void>;
+export function update_indexes_on_update(collection_name: any, old_document: any, new_document: any): Promise<void>;
+export function update_indexes_on_delete(collection_name: any, document: any): Promise<void>;
+export function find_documents_by_index(collection_name: any, field_name: any, operator: any, value: any): any[];
+export function can_use_index(collection_name: any, filter: any): {
+    field: string;
+    operators: string[];
+};
+export function build_index_key(collection_name: any, field_name: any, field_value: any): string;
+export function parse_index_key(key: any): {
+    collection: any;
+    field: any;
+    value: any;
+};
+export function cleanup_index_database(): void;