nodejs-json-db 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,1052 @@
+/**
+ * Base document type - all documents must have an _id field
+ */
+interface Document {
+    _id: string;
+    [key: string]: unknown;
+}
+/**
+ * Query comparison operators
+ */
+interface ComparisonOperators<T> {
+    $eq?: T;
+    $ne?: T;
+    $gt?: T;
+    $gte?: T;
+    $lt?: T;
+    $lte?: T;
+    $in?: T[];
+    $nin?: T[];
+    $regex?: RegExp | string;
+    $exists?: boolean;
+    $startsWith?: string;
+    $endsWith?: string;
+    $contains?: T extends unknown[] ? T[number] : never;
+}
+/**
+ * Field-level query type
+ */
+type QueryField<T> = T | ComparisonOperators<T>;
+/**
+ * Query type for finding documents
+ */
+type Query<T> = {
+    [K in keyof T]?: QueryField<T[K]>;
+} & {
+    $and?: Query<T>[];
+    $or?: Query<T>[];
+    $not?: Query<T>;
+};
+/**
+ * Update operators for modifying documents
+ */
+interface UpdateOperators<T> {
+    $set?: Partial<T>;
+    $unset?: {
+        [K in keyof T]?: true;
+    };
+    $inc?: {
+        [K in keyof T]?: T[K] extends number ? number : never;
+    };
+    $push?: {
+        [K in keyof T]?: T[K] extends unknown[] ? T[K][number] : never;
+    };
+    $pull?: {
+        [K in keyof T]?: T[K] extends unknown[] ? T[K][number] : never;
+    };
+    $addToSet?: {
+        [K in keyof T]?: T[K] extends unknown[] ? T[K][number] : never;
+    };
+}
+/**
+ * Sort order for query results
+ */
+type SortOrder = 1 | -1 | 'asc' | 'desc';
+/**
+ * Sort specification
+ */
+type Sort<T> = {
+    [K in keyof T]?: SortOrder;
+};
+/**
+ * Options for find operations
+ */
+interface FindOptions<T> {
+    sort?: Sort<T>;
+    limit?: number;
+    skip?: number;
+}
+/**
+ * Collection configuration options
+ */
+interface CollectionOptions {
+    /** Name of the collection */
+    name: string;
+    /** Custom ID generator function */
+    idGenerator?: () => string;
+}
+/**
+ * High-concurrency mode options
+ */
+interface HighConcurrencyOptions {
+    /** Enable high-concurrency mode (default: false) */
+    enabled: boolean;
+    /** Number of partitions for data sharding (default: 16) */
+    partitions?: number;
+    /** Maximum writes before automatic flush (default: 1000) */
+    batchSize?: number;
+    /** Maximum time in ms before automatic flush (default: 100) */
+    flushInterval?: number;
+    /** Maximum concurrent I/O operations (default: 4) */
+    maxConcurrentIO?: number;
+    /** Whether to coalesce duplicate writes (default: true) */
+    coalesceWrites?: boolean;
+}
+/**
+ * JsonDB configuration options
+ */
+interface JsonDBOptions {
+    /** Path to the database directory */
+    dataDir: string;
+    /** Whether to auto-save after each write operation (default: true) */
+    autoSave?: boolean;
+    /** Debounce time in ms for auto-save (default: 0) */
+    saveDebounce?: number;
+    /** Whether to pretty print JSON files (default: true) */
+    prettyPrint?: boolean;
+    /** Custom file extension (default: .json) */
+    fileExtension?: string;
+    /** High-concurrency mode options (opt-in) */
+    highConcurrency?: HighConcurrencyOptions;
+}
+/**
+ * Internal collection data structure
+ */
+interface CollectionData<T extends Document = Document> {
+    name: string;
+    documents: T[];
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Storage adapter interface
+ */
+interface StorageAdapter {
+    read<T extends Document>(collectionName: string): Promise<CollectionData<T> | null>;
+    write<T extends Document>(collectionName: string, data: CollectionData<T>): Promise<void>;
+    exists(collectionName: string): Promise<boolean>;
+    delete(collectionName: string): Promise<void>;
+    list(): Promise<string[]>;
+}
+
+/**
+ * File-based storage adapter for JSON data
+ */
+declare class Storage implements StorageAdapter {
+    private readonly dataDir;
+    private readonly fileExtension;
+    private readonly prettyPrint;
+    private readonly cache;
+    private readonly locks;
+    constructor(options: JsonDBOptions);
+    /**
+     * Ensure the data directory exists
+     */
+    private ensureDirectory;
+    /**
+     * Get the file path for a collection
+     */
+    private getFilePath;
+    /**
+     * Acquire a lock for a collection
+     */
+    private acquireLock;
+    /**
+     * Read collection data from file
+     */
+    read<T extends Document>(collectionName: string): Promise<CollectionData<T> | null>;
+    /**
+     * Write collection data to file atomically
+     */
+    write<T extends Document>(collectionName: string, data: CollectionData<T>): Promise<void>;
+    /**
+     * Check if a collection file exists
+     */
+    exists(collectionName: string): Promise<boolean>;
+    /**
+     * Delete a collection file
+     */
+    delete(collectionName: string): Promise<void>;
+    /**
+     * List all collection names
+     */
+    list(): Promise<string[]>;
+    /**
+     * Clear the cache for a specific collection or all collections
+     */
+    clearCache(collectionName?: string): void;
+    /**
+     * Get the data directory path
+     */
+    getDataDir(): string;
+}
+
+/**
+ * Schema validator interface (compatible with Zod)
+ */
+interface SchemaValidator$1<T> {
+    safeParse(data: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            issues: Array<{
+                path: PropertyKey[];
+                message: string;
+                code?: string;
+            }>;
+        };
+    };
+}
+/**
+ * Collection class for managing documents
+ */
+declare class Collection<T extends Document> {
+    private readonly name;
+    private readonly storage;
+    private readonly queryEngine;
+    private readonly autoSave;
+    private readonly saveDebounce;
+    private readonly idGenerator;
+    private readonly schema?;
+    private saveTimeout;
+    private pendingSave;
+    constructor(name: string, storage: Storage, options?: {
+        autoSave?: boolean;
+        saveDebounce?: number;
+        idGenerator?: () => string;
+        schema?: SchemaValidator$1<T>;
+    });
+    /**
+     * Validate a document against the schema (if defined)
+     */
+    private validate;
+    /**
+     * Get or create collection data
+     */
+    private getData;
+    /**
+     * Save collection data with debouncing
+     */
+    private save;
+    /**
+     * Force save any pending writes
+     */
+    flush(): Promise<void>;
+    /**
+     * Insert a single document
+     */
+    insert(doc: Omit<T, '_id'> & {
+        _id?: string;
+    }): Promise<T>;
+    /**
+     * Insert a single document without duplicate check (faster)
+     * In standard mode, this is equivalent to insert() but skips the duplicate check.
+     * Use this when you're certain the ID is unique.
+     */
+    insertFast(doc: Omit<T, '_id'> & {
+        _id?: string;
+    }): Promise<T>;
+    /**
+     * Insert multiple documents
+     */
+    insertMany(docs: (Omit<T, '_id'> & {
+        _id?: string;
+    })[]): Promise<T[]>;
+    /**
+     * Find documents matching a query
+     */
+    find(query?: Query<T>, options?: FindOptions<T>): Promise<T[]>;
+    /**
+     * Find a single document matching a query
+     */
+    findOne(query: Query<T>): Promise<T | null>;
+    /**
+     * Find a document by ID
+     */
+    findById(id: string): Promise<T | null>;
+    /**
+     * Count documents matching a query
+     */
+    count(query?: Query<T>): Promise<number>;
+    /**
+     * Update documents matching a query
+     */
+    update(query: Query<T>, update: UpdateOperators<T> | Partial<T>): Promise<number>;
+    /**
+     * Update a single document matching a query
+     */
+    updateOne(query: Query<T>, update: UpdateOperators<T> | Partial<T>): Promise<T | null>;
+    /**
+     * Update a document by ID
+     */
+    updateById(id: string, update: UpdateOperators<T> | Partial<T>): Promise<T | null>;
+    /**
+     * Delete documents matching a query
+     */
+    delete(query: Query<T>): Promise<number>;
+    /**
+     * Delete a single document matching a query
+     */
+    deleteOne(query: Query<T>): Promise<T | null>;
+    /**
+     * Delete a document by ID
+     */
+    deleteById(id: string): Promise<T | null>;
+    /**
+     * Get all documents in the collection
+     */
+    getAll(): Promise<T[]>;
+    /**
+     * Clear all documents in the collection
+     */
+    clear(): Promise<void>;
+    /**
+     * Drop the collection (delete the file)
+     */
+    drop(): Promise<void>;
+    /**
+     * Get the collection name
+     */
+    getName(): string;
+    /**
+     * Apply update operators to a document
+     */
+    private applyUpdate;
+    /**
+     * Sort documents by the specified sort options
+     */
+    private sortDocuments;
+}
+
+/**
+ * Task function type for worker pool
+ */
+type TaskFunction<T = void> = () => Promise<T>;
+/**
+ * Worker pool options
+ */
+interface WorkerPoolOptions {
+    /** Maximum concurrent operations (default: 4) */
+    maxConcurrent?: number;
+    /** Maximum queue size before rejecting new tasks (default: 10000) */
+    maxQueueSize?: number;
+}
+/**
+ * Worker pool statistics
+ */
+interface WorkerPoolStats {
+    activeWorkers: number;
+    queuedTasks: number;
+    completedTasks: number;
+    failedTasks: number;
+}
+/**
+ * WorkerPool - Manages parallel I/O operations with concurrency limits
+ *
+ * Features:
+ * - Configurable concurrency limit
+ * - Priority queue for task ordering
+ * - Backpressure handling (rejects when queue full)
+ * - Statistics tracking
+ */
+declare class WorkerPool {
+    private readonly maxConcurrent;
+    private readonly maxQueueSize;
+    private readonly queue;
+    private activeCount;
+    private completedCount;
+    private failedCount;
+    private isShuttingDown;
+    constructor(options?: WorkerPoolOptions);
+    /**
+     * Submit a task to the worker pool
+     * @param task The async function to execute
+     * @param priority Higher priority tasks are executed first (default: 0)
+     */
+    submit<T>(task: TaskFunction<T>, priority?: number): Promise<T>;
+    /**
+     * Submit multiple tasks and wait for all to complete
+     */
+    submitAll<T>(tasks: TaskFunction<T>[], priority?: number): Promise<T[]>;
+    /**
+     * Submit multiple tasks and process results as they complete
+     */
+    submitStream<T>(tasks: TaskFunction<T>[], priority?: number): AsyncGenerator<T, void, unknown>;
+    /**
+     * Process the next task in the queue
+     */
+    private processNext;
+    /**
+     * Wait for all currently queued tasks to complete
+     */
+    drain(): Promise<void>;
+    /**
+     * Gracefully shutdown the worker pool
+     * Stops accepting new tasks and waits for existing ones to complete
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get current pool statistics
+     */
+    getStats(): WorkerPoolStats;
+    /**
+     * Check if pool is idle (no active or queued tasks)
+     */
+    isIdle(): boolean;
+    /**
+     * Check if pool is shutting down
+     */
+    isClosing(): boolean;
+    /**
+     * Get the current queue size
+     */
+    queueSize(): number;
+    /**
+     * Get the number of active workers
+     */
+    activeWorkers(): number;
+}
+/**
+ * Helper to run tasks with limited concurrency
+ * Simpler alternative to WorkerPool for one-off batch operations
+ */
+declare function parallelLimit<T, R>(items: T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+
+/**
+ * HighConcurrencyStorage - Storage adapter optimized for high-throughput scenarios
+ *
+ * Features:
+ * - Write buffering with automatic batch flushing
+ * - Data sharding across multiple partitions
+ * - Parallel I/O with concurrency limits
+ * - Operation coalescing for duplicate writes
+ */
+declare class HighConcurrencyStorage {
+    private readonly partitionManager;
+    private readonly writeQueue;
+    private readonly workerPool;
+    private readonly options;
+    constructor(dbOptions: JsonDBOptions);
+    /**
+     * Process a batch of write operations
+     */
+    private processBatch;
+    /**
+     * Process operations for a single collection
+     */
+    private processCollectionOperations;
+    /**
+     * Process operations for a single partition
+     */
+    private processPartitionOperations;
+    /**
+     * Enqueue an insert operation
+     */
+    insert<T extends Document>(collectionName: string, document: T): Promise<void>;
+    /**
+     * Enqueue a bulk insert operation
+     */
+    insertMany<T extends Document>(collectionName: string, documents: T[]): Promise<void>;
+    /**
+     * Enqueue an update operation
+     */
+    update<T extends Document>(collectionName: string, documentId: string, changes: Partial<T>): Promise<void>;
+    /**
+     * Enqueue a delete operation
+     */
+    delete(collectionName: string, documentId: string): Promise<void>;
+    /**
+     * Enqueue a clear operation
+     */
+    clear(collectionName: string): Promise<void>;
+    /**
+     * Read a document by ID (bypasses queue, reads directly)
+     */
+    findById<T extends Document>(collectionName: string, documentId: string): Promise<T | null>;
+    /**
+     * Read all documents from a collection
+     */
+    readAll<T extends Document>(collectionName: string): Promise<T[]>;
+    /**
+     * Check if a collection exists
+     */
+    exists(collectionName: string): Promise<boolean>;
+    /**
+     * Initialize a collection with empty partitions
+     */
+    initializeCollection(collectionName: string): Promise<void>;
+    /**
+     * Delete a collection and all its partitions
+     */
+    deleteCollection(collectionName: string): Promise<void>;
+    /**
+     * List all collections
+     */
+    listCollections(): Promise<string[]>;
+    /**
+     * Flush all pending writes
+     */
+    flush(): Promise<void>;
+    /**
+     * Gracefully shutdown the storage
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get pending write count
+     */
+    pendingWrites(): number;
+    /**
+     * Get worker pool statistics
+     */
+    getStats(): {
+        pendingWrites: number;
+        workerPool: WorkerPoolStats;
+        partitions: number;
+    };
+    /**
+     * Clear cache for a collection
+     */
+    clearCache(collectionName?: string): void;
+}
+
+/**
+ * Schema validator interface (compatible with Zod)
+ */
+interface SchemaValidator<T> {
+    safeParse(data: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            issues: Array<{
+                path: PropertyKey[];
+                message: string;
+                code?: string;
+            }>;
+        };
+    };
+}
+/**
+ * HighConcurrencyCollection - Collection class optimized for high-throughput scenarios
+ *
+ * Features:
+ * - Uses HighConcurrencyStorage for batched, partitioned writes
+ * - Same API as regular Collection for compatibility
+ * - Optimized for write-heavy workloads
+ */
+declare class HighConcurrencyCollection<T extends Document> {
+    private readonly name;
+    private readonly storage;
+    private readonly queryEngine;
+    private readonly idGenerator;
+    private readonly schema?;
+    constructor(name: string, storage: HighConcurrencyStorage, options?: {
+        idGenerator?: () => string;
+        schema?: SchemaValidator<T>;
+    });
+    /**
+     * Validate a document against the schema (if defined)
+     */
+    private validate;
+    /**
+     * Insert a single document
+     */
+    insert(doc: Omit<T, '_id'> & {
+        _id?: string;
+    }): Promise<T>;
+    /**
+     * Insert a single document without duplicate check (faster)
+     * Use this when you're certain the ID is unique
+     */
+    insertFast(doc: Omit<T, '_id'> & {
+        _id?: string;
+    }): Promise<T>;
+    /**
+     * Insert multiple documents
+     */
+    insertMany(docs: (Omit<T, '_id'> & {
+        _id?: string;
+    })[]): Promise<T[]>;
+    /**
+     * Find documents matching a query
+     */
+    find(query?: Query<T>, options?: FindOptions<T>): Promise<T[]>;
+    /**
+     * Find a single document matching a query
+     */
+    findOne(query: Query<T>): Promise<T | null>;
+    /**
+     * Find a document by ID
+     */
+    findById(id: string): Promise<T | null>;
+    /**
+     * Count documents matching a query
+     */
+    count(query?: Query<T>): Promise<number>;
+    /**
+     * Update documents matching a query
+     */
+    update(query: Query<T>, update: UpdateOperators<T> | Partial<T>): Promise<number>;
+    /**
+     * Update a single document matching a query
+     */
+    updateOne(query: Query<T>, update: UpdateOperators<T> | Partial<T>): Promise<T | null>;
+    /**
+     * Update a document by ID
+     */
+    updateById(id: string, update: UpdateOperators<T> | Partial<T>): Promise<T | null>;
+    /**
+     * Delete documents matching a query
+     */
+    delete(query: Query<T>): Promise<number>;
+    /**
+     * Delete a single document matching a query
+     */
+    deleteOne(query: Query<T>): Promise<T | null>;
+    /**
+     * Delete a document by ID
+     */
+    deleteById(id: string): Promise<T | null>;
+    /**
+     * Get all documents in the collection
+     */
+    getAll(): Promise<T[]>;
+    /**
+     * Clear all documents in the collection
+     */
+    clear(): Promise<void>;
+    /**
+     * Drop the collection
+     */
+    drop(): Promise<void>;
+    /**
+     * Flush pending writes
+     */
+    flush(): Promise<void>;
+    /**
+     * Get the collection name
+     */
+    getName(): string;
+    /**
+     * Get update changes from update operators
+     */
+    private getUpdateChanges;
+    /**
+     * Sort documents by the specified sort options
+     */
+    private sortDocuments;
+}
+
+/**
+ * Collection type union for standard and high-concurrency modes
+ */
+type AnyCollection<T extends Document> = Collection<T> | HighConcurrencyCollection<T>;
+/**
+ * Stats returned by getStats() in high-concurrency mode
+ */
+interface HighConcurrencyStats {
+    pendingWrites: number;
+    workerPool: WorkerPoolStats;
+    partitions: number;
+}
+/**
+ * JsonDB - A lightweight JSON-based database for Node.js and Electron
+ *
+ * Supports two modes:
+ * - Standard mode: Single-file storage per collection (default)
+ * - High-concurrency mode: Partitioned storage with write batching (opt-in)
+ */
+declare class JsonDB {
+    private readonly options;
+    private readonly storage;
+    private readonly hcStorage;
+    private readonly collections;
+    private readonly isHighConcurrency;
+    private connected;
+    /**
+     * Create a new JsonDB instance
+     * @param options Database configuration options
+     */
+    constructor(options: JsonDBOptions);
+    /**
+     * Get the standard storage (throws if in HC mode)
+     */
+    private getStorage;
+    /**
+     * Get the high-concurrency storage (throws if in standard mode)
+     */
+    private getHCStorage;
+    /**
+     * Connect to the database (initialize storage)
+     */
+    connect(): Promise<void>;
+    /**
+     * Close the database connection
+     */
+    close(): Promise<void>;
+    /**
+       * Get or create a collection
+       * @param name Collection name
+       * @param options Collection options (including optional Zod schema)
+       */
+    collection<T extends Document>(name: string, options?: {
+        schema?: {
+            safeParse(data: unknown): {
+                success: true;
+                data: T;
+            } | {
+                success: false;
+                error: {
+                    issues: Array<{
+                        path: PropertyKey[];
+                        message: string;
+                        code?: string;
+                    }>;
+                };
+            };
+        };
+    }): AnyCollection<T>;
+    /**
+     * Get or create a collection internally
+     */
+    private getOrCreateCollection;
+    /**
+     * Check if a collection exists
+     * @param name Collection name
+     */
+    hasCollection(name: string): Promise<boolean>;
+    /**
+     * Get list of all collection names
+     */
+    listCollections(): Promise<string[]>;
+    /**
+     * Drop a collection
+     * @param name Collection name
+     */
+    dropCollection(name: string): Promise<void>;
+    /**
+     * Drop the entire database (delete all collections)
+     */
+    drop(): Promise<void>;
+    /**
+     * Get the data directory path
+     */
+    getDataDir(): string;
+    /**
+     * Check if database is connected
+     */
+    isConnected(): boolean;
+    /**
+     * Check if high-concurrency mode is enabled
+     */
+    isHighConcurrencyMode(): boolean;
+    /**
+     * Get high-concurrency storage statistics
+     * Only available in high-concurrency mode
+     */
+    getStats(): HighConcurrencyStats | null;
+    /**
+     * Flush all pending writes
+     * Useful in high-concurrency mode to ensure all writes are persisted
+     */
+    flush(): Promise<void>;
+}
+
+/**
+ * Write operation types
+ */
+type WriteOperation<T extends Document = Document> = {
+    type: 'insert';
+    collectionName: string;
+    document: T;
+} | {
+    type: 'update';
+    collectionName: string;
+    documentId: string;
+    changes: Partial<T>;
+} | {
+    type: 'delete';
+    collectionName: string;
+    documentId: string;
+} | {
+    type: 'bulkInsert';
+    collectionName: string;
+    documents: T[];
+} | {
+    type: 'bulkUpdate';
+    collectionName: string;
+    documentIds: string[];
+    changes: Partial<T>;
+} | {
+    type: 'bulkDelete';
+    collectionName: string;
+    documentIds: string[];
+} | {
+    type: 'clear';
+    collectionName: string;
+} | {
+    type: 'fullWrite';
+    collectionName: string;
+    data: CollectionData<T>;
+};
+/**
+ * Write queue options
+ */
+interface WriteQueueOptions {
+    /** Maximum writes before automatic flush (default: 1000) */
+    batchSize?: number;
+    /** Maximum time in ms before automatic flush (default: 100) */
+    flushInterval?: number;
+    /** Whether to coalesce duplicate operations (default: true) */
+    coalesceWrites?: boolean;
+}
+/**
+ * Batch processor callback type
+ */
+type BatchProcessor = (operations: Map<string, WriteOperation[]>) => Promise<void>;
+/**
+ * WriteQueue - Buffers and batches write operations for high throughput
+ *
+ * Features:
+ * - Batches writes to reduce I/O operations
+ * - Coalesces duplicate operations (e.g., multiple updates to same doc)
+ * - Automatic flush by count or time interval
+ * - Promise-based API for tracking write completion
+ */
+declare class WriteQueue {
+    private readonly batchSize;
+    private readonly flushInterval;
+    private readonly coalesceWrites;
+    private readonly batchProcessor;
+    private queue;
+    private flushTimer;
+    private pendingFlush;
+    private totalQueued;
+    private isShuttingDown;
+    constructor(batchProcessor: BatchProcessor, options?: WriteQueueOptions);
+    /**
+     * Enqueue a write operation
+     * Returns a promise that resolves when the write is persisted
+     */
+    enqueue<T extends Document>(operation: WriteOperation<T>): Promise<void>;
+    /**
+     * Try to coalesce a write with existing queued operations
+     */
+    private tryCoalesce;
+    /**
+     * Schedule a flush if not already scheduled
+     */
+    private scheduleFlush;
+    /**
+     * Flush all pending writes
+     */
+    flush(): Promise<void>;
+    /**
+     * Process a batch of operations
+     */
+    private processBatch;
+    /**
+     * Gracefully shutdown the queue
+     * Flushes all pending writes and stops accepting new ones
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get the number of pending operations
+     */
+    pending(): number;
+    /**
+     * Check if the queue is empty
+     */
+    isEmpty(): boolean;
+    /**
+     * Check if the queue is shutting down
+     */
+    isClosing(): boolean;
+}
+
+/**
+ * Partition options
+ */
+interface PartitionOptions {
+    /** Number of partitions (default: 16) */
+    partitionCount?: number;
+    /** Whether to pretty print JSON (default: true) */
+    prettyPrint?: boolean;
+    /** File extension (default: .json) */
+    fileExtension?: string;
+}
+/**
+ * Partition info for a collection
+ */
+interface PartitionInfo {
+    name: string;
+    partitionIndex: number;
+    documentCount: number;
+}
+/**
+ * PartitionManager - Distributes documents across multiple files (shards)
+ *
+ * Features:
+ * - Consistent hashing for document distribution
+ * - Parallel I/O across partitions
+ * - Automatic partition discovery and initialization
+ * - Maintains per-partition caching
+ */
+declare class PartitionManager {
+    private readonly dataDir;
+    private readonly partitionCount;
+    private readonly prettyPrint;
+    private readonly fileExtension;
+    private readonly cache;
+    private readonly locks;
+    constructor(dataDir: string, options?: PartitionOptions);
+    /**
+     * Ensure the data directory exists
+     */
+    private ensureDirectory;
+    /**
+     * Get partition index for a document ID using consistent hashing
+     */
+    getPartitionIndex(documentId: string): number;
+    /**
+     * Get partition file name
+     */
+    getPartitionFileName(collectionName: string, partitionIndex: number): string;
+    /**
+     * Get partition file path
+     */
+    getPartitionFilePath(collectionName: string, partitionIndex: number): string;
+    /**
+     * Get cache key for a partition
+     */
+    private getCacheKey;
+    /**
+     * Acquire lock for a partition
+     */
+    private acquireLock;
+    /**
+     * Read a single partition
+     */
+    readPartition<T extends Document>(collectionName: string, partitionIndex: number): Promise<CollectionData<T> | null>;
+    /**
+     * Write a single partition atomically
+     */
+    writePartition<T extends Document>(collectionName: string, partitionIndex: number, data: CollectionData<T>): Promise<void>;
+    /**
+     * Read all partitions for a collection in parallel
+     */
+    readAllPartitions<T extends Document>(collectionName: string): Promise<Map<number, CollectionData<T>>>;
+    /**
+     * Write multiple partitions in parallel
+     */
+    writePartitions<T extends Document>(collectionName: string, partitions: Map<number, CollectionData<T>>): Promise<void>;
+    /**
+     * Initialize empty partitions for a collection
+     */
+    initializePartitions(collectionName: string): Promise<void>;
+    /**
+     * Get partition info for a collection
+     */
+    getPartitionInfo(collectionName: string): Promise<PartitionInfo[]>;
+    /**
+     * Get all documents from all partitions
+     */
+    getAllDocuments<T extends Document>(collectionName: string): Promise<T[]>;
+    /**
+     * Find document by ID (searches correct partition)
+     */
+    findById<T extends Document>(collectionName: string, documentId: string): Promise<T | null>;
+    /**
+     * Delete all partitions for a collection
+     */
+    deleteCollection(collectionName: string): Promise<void>;
+    /**
+     * Clear cache for a collection or all collections
+     */
+    clearCache(collectionName?: string): void;
+    /**
+     * Get the number of partitions
+     */
+    getPartitionCount(): number;
+    /**
+     * List all partitioned collections
+     */
+    listCollections(): Promise<string[]>;
+}
+
+/**
+ * Base error class for JsonDB errors
+ */
+declare class JsonDBError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when a document is not found
+ */
+declare class DocumentNotFoundError extends JsonDBError {
+    constructor(collectionName: string, id?: string);
+}
+/**
+ * Error thrown when a duplicate key is detected
+ */
+declare class DuplicateKeyError extends JsonDBError {
+    constructor(collectionName: string, id: string);
+}
+/**
+ * Zod error issue type (subset of ZodIssue for type safety without importing zod)
+ */
+interface SchemaIssue {
+    path: PropertyKey[];
+    message: string;
+    code?: string;
+}
+/**
+ * Error thrown when validation fails
+ */
+declare class ValidationError extends JsonDBError {
+    readonly collectionName: string;
+    readonly issues: SchemaIssue[];
+    readonly field?: string;
+    readonly value?: unknown;
+    constructor(collectionName: string, issues: SchemaIssue[], field?: string, value?: unknown);
+}
+/**
+ * Error thrown when storage operations fail
+ */
+declare class StorageError extends JsonDBError {
+    readonly cause?: Error;
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Error thrown when collection operations fail
+ */
+declare class CollectionError extends JsonDBError {
+    constructor(message: string);
+}
+
+/**
+ * Generate a unique ID using bson ObjectId
+ * @param _length - Ignored, kept for backward compatibility
+ * @returns A 24-character hexadecimal string
+ */
+declare function generateId(_length?: number): string;
+/**
+ * Check if a value is a valid ID
+ * Supports both ObjectId (24 hex chars) and custom IDs (1-64 chars)
+ */
+declare function isValidId(id: unknown): id is string;
+
+export { Collection, type CollectionData, CollectionError, type CollectionOptions, type ComparisonOperators, type Document, DocumentNotFoundError, DuplicateKeyError, type FindOptions, HighConcurrencyCollection, type HighConcurrencyOptions, HighConcurrencyStorage, JsonDB, JsonDBError, type JsonDBOptions, PartitionManager, type Query, type QueryField, type SchemaIssue, type SchemaValidator$1 as SchemaValidator, type Sort, type SortOrder, type StorageAdapter, StorageError, type UpdateOperators, ValidationError, WorkerPool, WriteQueue, generateId, isValidId, parallelLimit };