@liorandb/core 1.0.17 → 1.0.19

package/dist/index.d.ts

@@ -21,6 +21,11 @@ declare class Index {
     close(): Promise<void>;
 }
 
+interface Migration<T = any> {
+    from: number;
+    to: number;
+    migrate: (doc: any) => T;
+}
 interface UpdateOptions$1 {
     upsert?: boolean;
 }
@@ -29,20 +34,25 @@ declare class Collection<T = any> {
     db: ClassicLevel<string, string>;
     private queue;
     private schema?;
+    private schemaVersion;
+    private migrations;
     private indexes;
-    constructor(dir: string, schema?: ZodSchema<T>);
-    registerIndex(index: Index): void;
-    getIndex(field: string): Index | undefined;
-    setSchema(schema: ZodSchema<T>): void;
+    constructor(dir: string, schema?: ZodSchema<T>, schemaVersion?: number);
+    setSchema(schema: ZodSchema<T>, version: number): void;
+    addMigration(migration: Migration<T>): void;
     private validate;
+    private migrateIfNeeded;
     private _enqueue;
     close(): Promise<void>;
-    compact(): Promise<void>;
-    _exec(op: string, args: any[]): Promise<any>;
+    registerIndex(index: Index): void;
+    getIndex(field: string): Index | undefined;
     private _updateIndexes;
+    compact(): Promise<void>;
+    _exec(op: string, args: any[]): Promise<number | boolean | T | T[] | null>;
     private _insertOne;
     private _insertMany;
     private _getCandidateIds;
+    private _readAndMigrate;
     private _find;
     private _findOne;
     private _countDocuments;
@@ -50,15 +60,46 @@ declare class Collection<T = any> {
     private _updateMany;
     private _deleteOne;
     private _deleteMany;
-    insertOne(doc: any): Promise<any>;
-    insertMany(docs: any[]): Promise<any>;
-    find(query?: any): Promise<any>;
-    findOne(query?: any): Promise<any>;
-    updateOne(filter: any, update: any, options?: UpdateOptions$1): Promise<any>;
-    updateMany(filter: any, update: any): Promise<any>;
-    deleteOne(filter: any): Promise<any>;
-    deleteMany(filter: any): Promise<any>;
-    countDocuments(filter?: any): Promise<any>;
+    insertOne(doc: any): Promise<number | boolean | T | T[] | null>;
+    insertMany(docs: any[]): Promise<number | boolean | T | T[] | null>;
+    find(query?: any): Promise<number | boolean | T | T[] | null>;
+    findOne(query?: any): Promise<number | boolean | T | T[] | null>;
+    updateOne(filter: any, update: any, options?: UpdateOptions$1): Promise<number | boolean | T | T[] | null>;
+    updateMany(filter: any, update: any): Promise<number | boolean | T | T[] | null>;
+    deleteOne(filter: any): Promise<number | boolean | T | T[] | null>;
+    deleteMany(filter: any): Promise<number | boolean | T | T[] | null>;
+    countDocuments(filter?: any): Promise<number | boolean | T | T[] | null>;
+}
+
+type WALRecord = {
+    lsn: number;
+    tx: number;
+    type: "op";
+    payload: any;
+} | {
+    lsn: number;
+    tx: number;
+    type: "commit";
+} | {
+    lsn: number;
+    tx: number;
+    type: "applied";
+};
+declare class WALManager {
+    private walDir;
+    private currentGen;
+    private lsn;
+    private fd;
+    constructor(baseDir: string);
+    private walPath;
+    private detectLastGeneration;
+    private open;
+    private rotate;
+    append(record: Omit<WALRecord, "lsn">): Promise<number>;
+    replay(fromLSN: number, apply: (r: WALRecord) => Promise<void>): Promise<void>;
+    cleanup(beforeGen: number): Promise<void>;
+    getCurrentLSN(): number;
+    getCurrentGen(): number;
 }
 
 type TXOp = {
@@ -67,15 +108,6 @@ type TXOp = {
     op: string;
     args: any[];
 };
-type TXCommit = {
-    tx: number;
-    commit: true;
-};
-type TXApplied = {
-    tx: number;
-    applied: true;
-};
-type WALEntry = TXOp | TXCommit | TXApplied;
 declare class DBTransactionContext {
     private db;
     readonly txId: number;
@@ -89,27 +121,28 @@ declare class LioranDB {
     dbName: string;
     manager: LioranManager;
     collections: Map<string, Collection>;
-    private walPath;
     private metaPath;
     private meta;
     private migrator;
     private static TX_SEQ;
+    wal: WALManager;
+    private checkpoint;
     constructor(basePath: string, dbName: string, manager: LioranManager);
+    private initialize;
+    private recoverFromWAL;
     private loadMeta;
     private saveMeta;
     getSchemaVersion(): string;
     setSchemaVersion(v: string): void;
     migrate(from: string, to: string, fn: (db: LioranDB) => Promise<void>): void;
     applyMigrations(targetVersion: string): Promise<void>;
-    writeWAL(entries: WALEntry[]): Promise<void>;
-    clearWAL(): Promise<void>;
-    private recoverFromWAL;
     applyTransaction(ops: TXOp[]): Promise<void>;
-    collection<T = any>(name: string, schema?: ZodSchema<T>): Collection<T>;
+    collection<T = any>(name: string, schema?: ZodSchema<T>, schemaVersion?: number): Collection<T>;
     createIndex(collection: string, field: string, options?: IndexOptions): Promise<void>;
     compactCollection(name: string): Promise<void>;
     compactAll(): Promise<void>;
     transaction<T>(fn: (tx: DBTransactionContext) => Promise<T>): Promise<T>;
+    postCommitMaintenance(): Promise<void>;
     close(): Promise<void>;
 }
 
@@ -149,13 +182,23 @@ interface LioranManagerOptions {
     rootPath?: string;
     encryptionKey?: string | Buffer;
     ipc?: boolean;
+    /**
+     * If true, database auto-applies pending migrations on startup.
+     */
+    autoMigrate?: boolean;
 }
 interface UpdateOptions {
     upsert?: boolean;
+    /**
+     * If true, returns the modified document instead of the original.
+     */
+    returnNew?: boolean;
 }
-type Query<T = any> = Partial<T> & {
+type Query<T = any> = Partial<T> | ({
+    [K in keyof T]?: any;
+} & {
     [key: string]: any;
-};
+});
 type IndexType = "hash" | "btree";
 interface IndexDefinition<T = any> {
     field: keyof T | string;
@@ -177,6 +220,40 @@ interface QueryExplainPlan {
     returnedDocuments: number;
     executionTimeMs: number;
 }
+/**
+ * Per-collection document schema version
+ */
+type SchemaVersion = number;
+/**
+ * Collection-level migration definition
+ */
+interface CollectionMigration<T = any> {
+    from: SchemaVersion;
+    to: SchemaVersion;
+    migrate: (doc: any) => T;
+}
+/**
+ * Database-level migration definition
+ */
+interface DatabaseMigration {
+    from: string;
+    to: string;
+    migrate: () => Promise<void>;
+}
+interface CollectionOptions<T = any> {
+    /**
+     * Zod schema used for validation
+     */
+    schema?: any;
+    /**
+     * Current document schema version
+     */
+    schemaVersion?: SchemaVersion;
+    /**
+     * Optional migrations for automatic document upgrading
+     */
+    migrations?: CollectionMigration<T>[];
+}
 interface CollectionIndexAPI<T = any> {
     createIndex(def: IndexDefinition<T>): Promise<void>;
     dropIndex(field: keyof T | string): Promise<void>;
@@ -186,5 +263,14 @@ interface CollectionIndexAPI<T = any> {
 interface DatabaseIndexAPI {
     rebuildAllIndexes(): Promise<void>;
 }
+/**
+ * Database migration coordination API
+ */
+interface DatabaseMigrationAPI {
+    migrate(from: string, to: string, fn: () => Promise<void>): void;
+    applyMigrations(targetVersion: string): Promise<void>;
+    getSchemaVersion(): string;
+    setSchemaVersion(version: string): void;
+}
 
-export { type CollectionIndexAPI, type DatabaseIndexAPI, type IndexDefinition, type IndexMetadata, type IndexType, LioranDB, LioranManager, type LioranManagerOptions, type Query, type QueryExplainPlan, type UpdateOptions, getBaseDBFolder };
+export { type CollectionIndexAPI, type CollectionMigration, type CollectionOptions, type DatabaseIndexAPI, type DatabaseMigration, type DatabaseMigrationAPI, type IndexDefinition, type IndexMetadata, type IndexType, LioranDB, LioranManager, type LioranManagerOptions, type Query, type QueryExplainPlan, type SchemaVersion, type UpdateOptions, getBaseDBFolder };