@liorandb/core 1.0.17 → 1.0.18

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,15 @@ 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 TXOp = {
@@ -105,7 +115,7 @@ declare class LioranDB {
     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>;
@@ -149,13 +159,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 +197,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 +240,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 };

package/dist/index.js

@@ -370,26 +370,43 @@ var Collection = class {
   db;
   queue = Promise.resolve();
   schema;
+  schemaVersion = 1;
+  migrations = [];
   indexes = /* @__PURE__ */ new Map();
-  constructor(dir, schema) {
+  constructor(dir, schema, schemaVersion = 1) {
     this.dir = dir;
     this.db = new ClassicLevel3(dir, { valueEncoding: "utf8" });
     this.schema = schema;
+    this.schemaVersion = schemaVersion;
   }
-  /* ---------------------- INDEX MANAGEMENT ---------------------- */
-  registerIndex(index) {
-    this.indexes.set(index.field, index);
-  }
-  getIndex(field) {
-    return this.indexes.get(field);
-  }
-  /* -------------------------- CORE -------------------------- */
-  setSchema(schema) {
+  /* ===================== SCHEMA ===================== */
+  setSchema(schema, version) {
     this.schema = schema;
+    this.schemaVersion = version;
+  }
+  addMigration(migration) {
+    this.migrations.push(migration);
+    this.migrations.sort((a, b) => a.from - b.from);
   }
   validate(doc) {
     return this.schema ? validateSchema(this.schema, doc) : doc;
   }
+  migrateIfNeeded(doc) {
+    let currentVersion = doc.__v ?? 1;
+    if (currentVersion === this.schemaVersion) {
+      return doc;
+    }
+    let working = doc;
+    for (const migration of this.migrations) {
+      if (migration.from === currentVersion) {
+        working = migration.migrate(working);
+        currentVersion = migration.to;
+      }
+    }
+    working.__v = this.schemaVersion;
+    return this.validate(working);
+  }
+  /* ===================== QUEUE ===================== */
   _enqueue(task) {
     this.queue = this.queue.then(task).catch(console.error);
     return this.queue;
@@ -406,7 +423,19 @@ var Collection = class {
     } catch {
     }
   }
-  /* -------------------- COMPACTION ENGINE -------------------- */
+  /* ===================== INDEX MANAGEMENT ===================== */
+  registerIndex(index) {
+    this.indexes.set(index.field, index);
+  }
+  getIndex(field) {
+    return this.indexes.get(field);
+  }
+  async _updateIndexes(oldDoc, newDoc) {
+    for (const index of this.indexes.values()) {
+      await index.update(oldDoc, newDoc);
+    }
+  }
+  /* ===================== COMPACTION ===================== */
   async compact() {
     return this._enqueue(async () => {
       try {
@@ -418,6 +447,7 @@ var Collection = class {
       await rebuildIndexes(this);
     });
   }
+  /* ===================== INTERNAL EXEC ===================== */
   async _exec(op, args) {
     switch (op) {
       case "insertOne":
@@ -442,16 +472,14 @@ var Collection = class {
         throw new Error(`Unknown operation: ${op}`);
     }
   }
-  /* ------------------ INDEX HOOK ------------------ */
-  async _updateIndexes(oldDoc, newDoc) {
-    for (const index of this.indexes.values()) {
-      await index.update(oldDoc, newDoc);
-    }
-  }
-  /* ---------------- Storage ---------------- */
+  /* ===================== STORAGE ===================== */
   async _insertOne(doc) {
     const _id = doc._id ?? uuid();
-    const final = this.validate({ _id, ...doc });
+    const final = this.validate({
+      _id,
+      ...doc,
+      __v: this.schemaVersion
+    });
     await this.db.put(String(_id), encryptData(final));
     await this._updateIndexes(null, final);
     return final;
@@ -461,7 +489,11 @@ var Collection = class {
     const out = [];
     for (const d of docs) {
       const _id = d._id ?? uuid();
-      const final = this.validate({ _id, ...d });
+      const final = this.validate({
+        _id,
+        ...d,
+        __v: this.schemaVersion
+      });
       batch.push({
         type: "put",
         key: String(_id),
@@ -475,7 +507,7 @@ var Collection = class {
     }
     return out;
   }
-  /* ---------------- QUERY ENGINE (INDEXED) ---------------- */
+  /* ===================== QUERY ===================== */
   async _getCandidateIds(query) {
     const indexedFields = new Set(this.indexes.keys());
     return runIndexedQuery(
@@ -497,15 +529,26 @@ var Collection = class {
       }
     );
   }
+  async _readAndMigrate(id) {
+    const enc = await this.db.get(id);
+    if (!enc) return null;
+    const raw = decryptData(enc);
+    const migrated = this.migrateIfNeeded(raw);
+    if (raw.__v !== this.schemaVersion) {
+      await this.db.put(id, encryptData(migrated));
+      await this._updateIndexes(raw, migrated);
+    }
+    return migrated;
+  }
   async _find(query) {
     const ids = await this._getCandidateIds(query);
     const out = [];
     for (const id of ids) {
       try {
-        const enc = await this.db.get(id);
-        if (!enc) continue;
-        const doc = decryptData(enc);
-        if (matchDocument(doc, query)) out.push(doc);
+        const doc = await this._readAndMigrate(id);
+        if (doc && matchDocument(doc, query)) {
+          out.push(doc);
+        }
       } catch {
       }
     }
@@ -514,8 +557,7 @@ var Collection = class {
   async _findOne(query) {
     if (query?._id) {
       try {
-        const enc = await this.db.get(String(query._id));
-        return enc ? decryptData(enc) : null;
+        return await this._readAndMigrate(String(query._id));
       } catch {
         return null;
       }
@@ -523,10 +565,10 @@ var Collection = class {
     const ids = await this._getCandidateIds(query);
     for (const id of ids) {
       try {
-        const enc = await this.db.get(id);
-        if (!enc) continue;
-        const doc = decryptData(enc);
-        if (matchDocument(doc, query)) return doc;
+        const doc = await this._readAndMigrate(id);
+        if (doc && matchDocument(doc, query)) {
+          return doc;
+        }
       } catch {
       }
     }
@@ -537,40 +579,34 @@ var Collection = class {
     let count = 0;
     for (const id of ids) {
       try {
-        const enc = await this.db.get(id);
-        if (!enc) continue;
-        if (matchDocument(decryptData(enc), filter)) count++;
+        const doc = await this._readAndMigrate(id);
+        if (doc && matchDocument(doc, filter)) {
+          count++;
+        }
       } catch {
       }
     }
     return count;
   }
-  /* ---------------- UPDATE ---------------- */
+  /* ===================== UPDATE ===================== */
   async _updateOne(filter, update, options) {
     const ids = await this._getCandidateIds(filter);
     for (const id of ids) {
-      try {
-        const enc = await this.db.get(id);
-        if (!enc) continue;
-        const value = decryptData(enc);
-        if (matchDocument(value, filter)) {
-          const updated = this.validate(applyUpdate(value, update));
-          updated._id = value._id;
-          await this.db.put(id, encryptData(updated));
-          await this._updateIndexes(value, updated);
-          return updated;
-        }
-      } catch {
+      const existing = await this._readAndMigrate(id);
+      if (!existing) continue;
+      if (matchDocument(existing, filter)) {
+        const updated = this.validate({
+          ...applyUpdate(existing, update),
+          _id: existing._id,
+          __v: this.schemaVersion
+        });
+        await this.db.put(id, encryptData(updated));
+        await this._updateIndexes(existing, updated);
+        return updated;
       }
     }
     if (options?.upsert) {
-      const doc = this.validate({
-        _id: uuid(),
-        ...applyUpdate({}, update)
-      });
-      await this.db.put(String(doc._id), encryptData(doc));
-      await this._updateIndexes(null, doc);
-      return doc;
+      return this._insertOne(applyUpdate({}, update));
     }
     return null;
   }
@@ -578,36 +614,31 @@ var Collection = class {
     const ids = await this._getCandidateIds(filter);
     const out = [];
     for (const id of ids) {
-      try {
-        const enc = await this.db.get(id);
-        if (!enc) continue;
-        const value = decryptData(enc);
-        if (matchDocument(value, filter)) {
-          const updated = this.validate(applyUpdate(value, update));
-          updated._id = value._id;
-          await this.db.put(id, encryptData(updated));
-          await this._updateIndexes(value, updated);
-          out.push(updated);
-        }
-      } catch {
+      const existing = await this._readAndMigrate(id);
+      if (!existing) continue;
+      if (matchDocument(existing, filter)) {
+        const updated = this.validate({
+          ...applyUpdate(existing, update),
+          _id: existing._id,
+          __v: this.schemaVersion
+        });
+        await this.db.put(id, encryptData(updated));
+        await this._updateIndexes(existing, updated);
+        out.push(updated);
       }
     }
     return out;
   }
-  /* ---------------- DELETE ---------------- */
+  /* ===================== DELETE ===================== */
   async _deleteOne(filter) {
     const ids = await this._getCandidateIds(filter);
     for (const id of ids) {
-      try {
-        const enc = await this.db.get(id);
-        if (!enc) continue;
-        const value = decryptData(enc);
-        if (matchDocument(value, filter)) {
-          await this.db.del(id);
-          await this._updateIndexes(value, null);
-          return true;
-        }
-      } catch {
+      const existing = await this._readAndMigrate(id);
+      if (!existing) continue;
+      if (matchDocument(existing, filter)) {
+        await this.db.del(id);
+        await this._updateIndexes(existing, null);
+        return true;
       }
     }
     return false;
@@ -616,21 +647,17 @@ var Collection = class {
     const ids = await this._getCandidateIds(filter);
     let count = 0;
     for (const id of ids) {
-      try {
-        const enc = await this.db.get(id);
-        if (!enc) continue;
-        const value = decryptData(enc);
-        if (matchDocument(value, filter)) {
-          await this.db.del(id);
-          await this._updateIndexes(value, null);
-          count++;
-        }
-      } catch {
+      const existing = await this._readAndMigrate(id);
+      if (!existing) continue;
+      if (matchDocument(existing, filter)) {
+        await this.db.del(id);
+        await this._updateIndexes(existing, null);
+        count++;
       }
     }
     return count;
   }
-  /* ---------------- PUBLIC API (Mongo-style) ---------------- */
+  /* ===================== PUBLIC API ===================== */
   insertOne(doc) {
     return this._enqueue(() => this._exec("insertOne", [doc]));
   }
@@ -875,7 +902,7 @@ var LioranDB = class _LioranDB {
     this.meta.schemaVersion = v;
     this.saveMeta();
   }
-  /* ------------------------- MIGRATION API ------------------------- */
+  /* ------------------------- DB MIGRATIONS ------------------------- */
   migrate(from, to, fn) {
     this.migrator.register(from, to, async (db) => {
       await fn(db);
@@ -930,15 +957,21 @@ var LioranDB = class _LioranDB {
     }
   }
   /* ------------------------- COLLECTION ------------------------- */
-  collection(name, schema) {
+  collection(name, schema, schemaVersion) {
     if (this.collections.has(name)) {
       const col2 = this.collections.get(name);
-      if (schema) col2.setSchema(schema);
+      if (schema && schemaVersion !== void 0) {
+        col2.setSchema(schema, schemaVersion);
+      }
       return col2;
     }
     const colPath = path4.join(this.basePath, name);
     fs4.mkdirSync(colPath, { recursive: true });
-    const col = new Collection(colPath, schema);
+    const col = new Collection(
+      colPath,
+      schema,
+      schemaVersion ?? 1
+    );
     const metas = this.meta.indexes[name] ?? [];
     for (const m of metas) {
       col.registerIndex(new Index(colPath, m.field, m.options));
@@ -955,11 +988,11 @@ var LioranDB = class _LioranDB {
     for await (const [key, enc] of col.db.iterator()) {
       if (!enc) continue;
       try {
-        const doc = decryptData2(enc);
+        const doc = decryptData(enc);
         await index.insert(doc);
       } catch (err) {
-        const errorMessage = err instanceof Error ? err.message : String(err);
-        console.warn(`Could not decrypt document ${key} during index build: ${errorMessage}`);
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`Index build skipped doc ${key}: ${msg}`);
       }
     }
     col.registerIndex(index);
@@ -1000,9 +1033,6 @@ var LioranDB = class _LioranDB {
     this.collections.clear();
   }
 };
-function decryptData2(enc) {
-  throw new Error("Function not implemented.");
-}
 
 // src/utils/rootpath.ts
 import os2 from "os";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liorandb/core",
-  "version": "1.0.17",
+  "version": "1.0.18",
   "description": "LioranDB Core Module – Lightweight, local-first, peer-to-peer database management for Node.js.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/core/collection.ts

@@ -11,6 +11,14 @@ import { validateSchema } from "../utils/schema.js";
 import { Index } from "./index.js";
 import { compactCollectionEngine, rebuildIndexes } from "./compaction.js";
 
+/* ===================== SCHEMA VERSIONING ===================== */
+
+export interface Migration<T = any> {
+  from: number;
+  to: number;
+  migrate: (doc: any) => T;
+}
+
 export interface UpdateOptions {
   upsert?: boolean;
 }
@@ -19,35 +27,62 @@ export class Collection<T = any> {
   dir: string;
   db: ClassicLevel<string, string>;
   private queue: Promise<any> = Promise.resolve();
+
   private schema?: ZodSchema<T>;
+  private schemaVersion: number = 1;
+  private migrations: Migration<T>[] = [];
+
   private indexes = new Map<string, Index>();
 
-  constructor(dir: string, schema?: ZodSchema<T>) {
+  constructor(
+    dir: string,
+    schema?: ZodSchema<T>,
+    schemaVersion: number = 1
+  ) {
     this.dir = dir;
     this.db = new ClassicLevel(dir, { valueEncoding: "utf8" });
     this.schema = schema;
+    this.schemaVersion = schemaVersion;
   }
 
-  /* ---------------------- INDEX MANAGEMENT ---------------------- */
+  /* ===================== SCHEMA ===================== */
 
-  registerIndex(index: Index) {
-    this.indexes.set(index.field, index);
+  setSchema(schema: ZodSchema<T>, version: number) {
+    this.schema = schema;
+    this.schemaVersion = version;
   }
 
-  getIndex(field: string) {
-    return this.indexes.get(field);
-  }
-
-  /* -------------------------- CORE -------------------------- */
-
-  setSchema(schema: ZodSchema<T>) {
-    this.schema = schema;
+  addMigration(migration: Migration<T>) {
+    this.migrations.push(migration);
+    this.migrations.sort((a, b) => a.from - b.from);
   }
 
   private validate(doc: any): T {
     return this.schema ? validateSchema(this.schema, doc) : doc;
   }
 
+  private migrateIfNeeded(doc: any): T {
+    let currentVersion = doc.__v ?? 1;
+
+    if (currentVersion === this.schemaVersion) {
+      return doc;
+    }
+
+    let working = doc;
+
+    for (const migration of this.migrations) {
+      if (migration.from === currentVersion) {
+        working = migration.migrate(working);
+        currentVersion = migration.to;
+      }
+    }
+
+    working.__v = this.schemaVersion;
+    return this.validate(working);
+  }
+
+  /* ===================== QUEUE ===================== */
+
   private _enqueue<R>(task: () => Promise<R>): Promise<R> {
     this.queue = this.queue.then(task).catch(console.error);
     return this.queue;
@@ -60,24 +95,38 @@ export class Collection<T = any> {
     try { await this.db.close(); } catch {}
   }
 
-  /* -------------------- COMPACTION ENGINE -------------------- */
+  /* ===================== INDEX MANAGEMENT ===================== */
+
+  registerIndex(index: Index) {
+    this.indexes.set(index.field, index);
+  }
+
+  getIndex(field: string) {
+    return this.indexes.get(field);
+  }
+
+  private async _updateIndexes(oldDoc: any, newDoc: any) {
+    for (const index of this.indexes.values()) {
+      await index.update(oldDoc, newDoc);
+    }
+  }
+
+  /* ===================== COMPACTION ===================== */
 
   async compact(): Promise<void> {
     return this._enqueue(async () => {
-      // Close active DB handles
       try { await this.db.close(); } catch {}
 
-      // Run compaction engine
       await compactCollectionEngine(this);
 
-      // Reopen fresh DB
       this.db = new ClassicLevel(this.dir, { valueEncoding: "utf8" });
 
-      // Rebuild indexes
       await rebuildIndexes(this);
     });
   }
 
+  /* ===================== INTERNAL EXEC ===================== */
+
   async _exec(op: string, args: any[]) {
     switch (op) {
       case "insertOne": return this._insertOne(args[0]);
@@ -93,19 +142,15 @@ export class Collection<T = any> {
     }
   }
 
-  /* ------------------ INDEX HOOK ------------------ */
-
-  private async _updateIndexes(oldDoc: any, newDoc: any) {
-    for (const index of this.indexes.values()) {
-      await index.update(oldDoc, newDoc);
-    }
-  }
-
-  /* ---------------- Storage ---------------- */
+  /* ===================== STORAGE ===================== */
 
   private async _insertOne(doc: any) {
     const _id = doc._id ?? uuid();
-    const final = this.validate({ _id, ...doc });
+    const final = this.validate({
+      _id,
+      ...doc,
+      __v: this.schemaVersion
+    });
 
     await this.db.put(String(_id), encryptData(final));
     await this._updateIndexes(null, final);
@@ -114,12 +159,16 @@ export class Collection<T = any> {
   }
 
   private async _insertMany(docs: any[]) {
-    const batch: Array<{ type: "put"; key: string; value: string }> = [];
+    const batch: any[] = [];
     const out = [];
 
     for (const d of docs) {
       const _id = d._id ?? uuid();
-      const final = this.validate({ _id, ...d });
+      const final = this.validate({
+        _id,
+        ...d,
+        __v: this.schemaVersion
+      });
 
       batch.push({
         type: "put",
@@ -139,7 +188,7 @@ export class Collection<T = any> {
     return out;
   }
 
-  /* ---------------- QUERY ENGINE (INDEXED) ---------------- */
+  /* ===================== QUERY ===================== */
 
   private async _getCandidateIds(query: any): Promise<Set<string>> {
     const indexedFields = new Set(this.indexes.keys());
@@ -148,7 +197,6 @@ export class Collection<T = any> {
       query,
       {
         indexes: indexedFields,
-
         findByIndex: async (field, value) => {
           const idx = this.indexes.get(field);
           if (!idx) return null;
@@ -165,17 +213,32 @@ export class Collection<T = any> {
     );
   }
 
+  private async _readAndMigrate(id: string) {
+    const enc = await this.db.get(id);
+    if (!enc) return null;
+
+    const raw = decryptData(enc);
+    const migrated = this.migrateIfNeeded(raw);
+
+    // Lazy write-back if migrated
+    if (raw.__v !== this.schemaVersion) {
+      await this.db.put(id, encryptData(migrated));
+      await this._updateIndexes(raw, migrated);
+    }
+
+    return migrated;
+  }
+
   private async _find(query: any) {
     const ids = await this._getCandidateIds(query);
     const out = [];
 
     for (const id of ids) {
       try {
-        const enc = await this.db.get(id);
-        if (!enc) continue;
-
-        const doc = decryptData(enc);
-        if (matchDocument(doc, query)) out.push(doc);
+        const doc = await this._readAndMigrate(id);
+        if (doc && matchDocument(doc, query)) {
+          out.push(doc);
+        }
       } catch {}
     }
 
@@ -185,8 +248,7 @@ export class Collection<T = any> {
   private async _findOne(query: any) {
     if (query?._id) {
       try {
-        const enc = await this.db.get(String(query._id));
-        return enc ? decryptData(enc) : null;
+        return await this._readAndMigrate(String(query._id));
       } catch { return null; }
     }
 
@@ -194,11 +256,10 @@ export class Collection<T = any> {
 
     for (const id of ids) {
       try {
-        const enc = await this.db.get(id);
-        if (!enc) continue;
-
-        const doc = decryptData(enc);
-        if (matchDocument(doc, query)) return doc;
+        const doc = await this._readAndMigrate(id);
+        if (doc && matchDocument(doc, query)) {
+          return doc;
+        }
       } catch {}
     }
 
@@ -211,50 +272,41 @@ export class Collection<T = any> {
 
     for (const id of ids) {
       try {
-        const enc = await this.db.get(id);
-        if (!enc) continue;
-
-        if (matchDocument(decryptData(enc), filter)) count++;
+        const doc = await this._readAndMigrate(id);
+        if (doc && matchDocument(doc, filter)) {
+          count++;
+        }
       } catch {}
     }
 
     return count;
   }
 
-  /* ---------------- UPDATE ---------------- */
+  /* ===================== UPDATE ===================== */
 
   private async _updateOne(filter: any, update: any, options: UpdateOptions) {
     const ids = await this._getCandidateIds(filter);
 
     for (const id of ids) {
-      try {
-        const enc = await this.db.get(id);
-        if (!enc) continue;
+      const existing = await this._readAndMigrate(id);
+      if (!existing) continue;
 
-        const value = decryptData(enc);
+      if (matchDocument(existing, filter)) {
+        const updated = this.validate({
+          ...applyUpdate(existing, update),
+          _id: (existing as any)._id,
+          __v: this.schemaVersion
+        });
 
-        if (matchDocument(value, filter)) {
-          const updated = this.validate(applyUpdate(value, update)) as any;
-          updated._id = value._id;
+        await this.db.put(id, encryptData(updated));
+        await this._updateIndexes(existing, updated);
 
-          await this.db.put(id, encryptData(updated));
-          await this._updateIndexes(value, updated);
-
-          return updated;
-        }
-      } catch {}
+        return updated;
+      }
     }
 
     if (options?.upsert) {
-      const doc = this.validate({
-        _id: uuid(),
-        ...applyUpdate({}, update)
-      }) as any;
-
-      await this.db.put(String(doc._id), encryptData(doc));
-      await this._updateIndexes(null, doc);
-
-      return doc;
+      return this._insertOne(applyUpdate({}, update));
     }
 
     return null;
@@ -265,45 +317,40 @@ export class Collection<T = any> {
     const out = [];
 
     for (const id of ids) {
-      try {
-        const enc = await this.db.get(id);
-        if (!enc) continue;
-
-        const value = decryptData(enc);
+      const existing = await this._readAndMigrate(id);
+      if (!existing) continue;
 
-        if (matchDocument(value, filter)) {
-          const updated = this.validate(applyUpdate(value, update)) as any;
-          updated._id = value._id;
+      if (matchDocument(existing, filter)) {
+        const updated = this.validate({
+          ...applyUpdate(existing, update),
+          _id: (existing as any)._id,
+          __v: this.schemaVersion
+        });
 
-          await this.db.put(id, encryptData(updated));
-          await this._updateIndexes(value, updated);
+        await this.db.put(id, encryptData(updated));
+        await this._updateIndexes(existing, updated);
 
-          out.push(updated);
-        }
-      } catch {}
+        out.push(updated);
+      }
     }
 
     return out;
   }
 
-  /* ---------------- DELETE ---------------- */
+  /* ===================== DELETE ===================== */
 
   private async _deleteOne(filter: any) {
     const ids = await this._getCandidateIds(filter);
 
     for (const id of ids) {
-      try {
-        const enc = await this.db.get(id);
-        if (!enc) continue;
-
-        const value = decryptData(enc);
+      const existing = await this._readAndMigrate(id);
+      if (!existing) continue;
 
-        if (matchDocument(value, filter)) {
-          await this.db.del(id);
-          await this._updateIndexes(value, null);
-          return true;
-        }
-      } catch {}
+      if (matchDocument(existing, filter)) {
+        await this.db.del(id);
+        await this._updateIndexes(existing, null);
+        return true;
+      }
     }
 
     return false;
@@ -314,24 +361,20 @@ export class Collection<T = any> {
     let count = 0;
 
     for (const id of ids) {
-      try {
-        const enc = await this.db.get(id);
-        if (!enc) continue;
+      const existing = await this._readAndMigrate(id);
+      if (!existing) continue;
 
-        const value = decryptData(enc);
-
-        if (matchDocument(value, filter)) {
-          await this.db.del(id);
-          await this._updateIndexes(value, null);
-          count++;
-        }
-      } catch {}
+      if (matchDocument(existing, filter)) {
+        await this.db.del(id);
+        await this._updateIndexes(existing, null);
+        count++;
+      }
     }
 
     return count;
   }
 
-  /* ---------------- PUBLIC API (Mongo-style) ---------------- */
+  /* ===================== PUBLIC API ===================== */
 
   insertOne(doc: any) {
     return this._enqueue(() => this._exec("insertOne", [doc]));

package/src/core/database.ts

@@ -7,6 +7,7 @@ import { Index, IndexOptions } from "./index.js";
 import { MigrationEngine } from "./migration.js";
 import type { LioranManager } from "../LioranManager.js";
 import type { ZodSchema } from "zod";
+import { decryptData } from "../utils/encryption.js";
 
 const exec = promisify(execFile);
 
@@ -25,7 +26,7 @@ type IndexMeta = {
 type DBMeta = {
   version: number;
   indexes: Record<string, IndexMeta[]>;
-  schemaVersion: string;
+  schemaVersion: string; // DB-level schema (not collection schema)
 };
 
 const META_FILE = "__db_meta.json";
@@ -40,7 +41,7 @@ class DBTransactionContext {
   constructor(
     private db: LioranDB,
     public readonly txId: number
-  ) { }
+  ) {}
 
   collection(name: string) {
     return new Proxy({}, {
@@ -79,7 +80,6 @@ export class LioranDB {
   private meta!: DBMeta;
 
   private migrator: MigrationEngine;
-
   private static TX_SEQ = 0;
 
   constructor(basePath: string, dbName: string, manager: LioranManager) {
@@ -133,7 +133,7 @@ export class LioranDB {
     this.saveMeta();
   }
 
-  /* ------------------------- MIGRATION API ------------------------- */
+  /* ------------------------- DB MIGRATIONS ------------------------- */
 
   migrate(from: string, to: string, fn: (db: LioranDB) => Promise<void>) {
     this.migrator.register(from, to, async db => {
@@ -158,7 +158,7 @@ export class LioranDB {
   }
 
   async clearWAL() {
-    try { await fs.promises.unlink(this.walPath); } catch { }
+    try { await fs.promises.unlink(this.walPath); } catch {}
   }
 
   private async recoverFromWAL() {
@@ -172,7 +172,6 @@ export class LioranDB {
 
     for (const line of raw.split("\n")) {
       if (!line.trim()) continue;
-
       const entry: WALEntry = JSON.parse(line);
 
       if ("commit" in entry) committed.add(entry.tx);
@@ -201,17 +200,27 @@ export class LioranDB {
 
   /* ------------------------- COLLECTION ------------------------- */
 
-  collection<T = any>(name: string, schema?: ZodSchema<T>): Collection<T> {
+  collection<T = any>(
+    name: string,
+    schema?: ZodSchema<T>,
+    schemaVersion?: number
+  ): Collection<T> {
     if (this.collections.has(name)) {
       const col = this.collections.get(name)!;
-      if (schema) col.setSchema(schema);
+      if (schema && schemaVersion !== undefined) {
+        col.setSchema(schema, schemaVersion);
+      }
       return col as Collection<T>;
     }
 
     const colPath = path.join(this.basePath, name);
     fs.mkdirSync(colPath, { recursive: true });
 
-    const col = new Collection<T>(colPath, schema);
+    const col = new Collection<T>(
+      colPath,
+      schema,
+      schemaVersion ?? 1
+    );
 
     const metas = this.meta.indexes[name] ?? [];
     for (const m of metas) {
@@ -236,25 +245,14 @@ export class LioranDB {
 
     const index = new Index(col.dir, field, options);
 
-    // for await (const [, enc] of col.db.iterator()) {
-    //   // const doc = JSON.parse(
-    //   //   Buffer.from(enc, "base64").subarray(32).toString("utf8")
-    //   // );
-    //   const payload = Buffer.from(enc, "utf8").subarray(32);
-    //   const doc = JSON.parse(payload.toString("utf8"));
-    //   await index.insert(doc);
-    // }
-
     for await (const [key, enc] of col.db.iterator()) {
       if (!enc) continue;
-
       try {
-        const doc = decryptData(enc);           // ← this does base64 → AES-GCM → JSON
+        const doc = decryptData(enc);
         await index.insert(doc);
       } catch (err) {
-        const errorMessage = err instanceof Error ? err.message : String(err);
-        console.warn(`Could not decrypt document ${key} during index build: ${errorMessage}`);
-        // You can continue, or collect bad keys for later inspection
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`Index build skipped doc ${key}: ${msg}`);
       }
     }
 
@@ -297,12 +295,8 @@ export class LioranDB {
 
   async close(): Promise<void> {
     for (const col of this.collections.values()) {
-      try { await col.close(); } catch { }
+      try { await col.close(); } catch {}
     }
     this.collections.clear();
   }
-}
-
-function decryptData(enc: string) {
-  throw new Error("Function not implemented.");
-}
+}

package/src/types/index.ts

@@ -1,63 +1,136 @@
-/* ----------------------------- MANAGER OPTIONS ----------------------------- */
+/* ============================= MANAGER OPTIONS ============================= */
 
 export interface LioranManagerOptions {
-  rootPath?: string
-  encryptionKey?: string | Buffer
-  ipc?: boolean
+  rootPath?: string;
+  encryptionKey?: string | Buffer;
+  ipc?: boolean;
+
+  /**
+   * If true, database auto-applies pending migrations on startup.
+   */
+  autoMigrate?: boolean;
 }
 
-/* ----------------------------- UPDATE OPTIONS ----------------------------- */
+/* ============================= UPDATE OPTIONS ============================= */
 
 export interface UpdateOptions {
-  upsert?: boolean
+  upsert?: boolean;
+
+  /**
+   * If true, returns the modified document instead of the original.
+   */
+  returnNew?: boolean;
 }
 
-/* --------------------------------- QUERY --------------------------------- */
+/* ================================ QUERY =================================== */
 
-export type Query<T = any> = Partial<T> & {
-  [key: string]: any
-}
+export type Query<T = any> =
+  | Partial<T>
+  | {
+      [K in keyof T]?: any;
+    } & {
+      [key: string]: any;
+    };
 
-/* --------------------------------- INDEX --------------------------------- */
+/* ================================ INDEX =================================== */
 
-export type IndexType = "hash" | "btree"
+export type IndexType = "hash" | "btree";
 
 export interface IndexDefinition<T = any> {
-  field: keyof T | string
-  unique?: boolean
-  sparse?: boolean
-  type?: IndexType
+  field: keyof T | string;
+  unique?: boolean;
+  sparse?: boolean;
+  type?: IndexType;
 }
 
 export interface IndexMetadata {
-  field: string
-  unique: boolean
-  sparse: boolean
-  type: IndexType
-  createdAt: number
+  field: string;
+  unique: boolean;
+  sparse: boolean;
+  type: IndexType;
+  createdAt: number;
 }
 
-/* ----------------------------- QUERY PLANNER ------------------------------ */
+/* =========================== QUERY PLANNER ================================ */
 
 export interface QueryExplainPlan {
-  indexUsed?: string
-  indexType?: IndexType
-  scannedDocuments: number
-  returnedDocuments: number
-  executionTimeMs: number
+  indexUsed?: string;
+  indexType?: IndexType;
+  scannedDocuments: number;
+  returnedDocuments: number;
+  executionTimeMs: number;
+}
+
+/* ========================== SCHEMA VERSIONING ============================= */
+
+/**
+ * Per-collection document schema version
+ */
+export type SchemaVersion = number;
+
+/**
+ * Collection-level migration definition
+ */
+export interface CollectionMigration<T = any> {
+  from: SchemaVersion;
+  to: SchemaVersion;
+  migrate: (doc: any) => T;
+}
+
+/**
+ * Database-level migration definition
+ */
+export interface DatabaseMigration {
+  from: string;
+  to: string;
+  migrate: () => Promise<void>;
 }
 
-/* ------------------------------ COLLECTION -------------------------------- */
+/* ============================== COLLECTION ================================ */
+
+export 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>[];
+}
 
 export interface CollectionIndexAPI<T = any> {
-  createIndex(def: IndexDefinition<T>): Promise<void>
-  dropIndex(field: keyof T | string): Promise<void>
-  listIndexes(): Promise<IndexMetadata[]>
-  rebuildIndexes(): Promise<void>
+  createIndex(def: IndexDefinition<T>): Promise<void>;
+  dropIndex(field: keyof T | string): Promise<void>;
+  listIndexes(): Promise<IndexMetadata[]>;
+  rebuildIndexes(): Promise<void>;
 }
 
-/* ------------------------------- DATABASE --------------------------------- */
+/* =============================== DATABASE ================================= */
 
 export interface DatabaseIndexAPI {
-  rebuildAllIndexes(): Promise<void>
+  rebuildAllIndexes(): Promise<void>;
+}
+
+/**
+ * Database migration coordination API
+ */
+export interface DatabaseMigrationAPI {
+  migrate(
+    from: string,
+    to: string,
+    fn: () => Promise<void>
+  ): void;
+
+  applyMigrations(targetVersion: string): Promise<void>;
+
+  getSchemaVersion(): string;
+
+  setSchemaVersion(version: string): void;
 }