@liorandb/core 1.0.16 → 1.0.17

package/dist/index.d.ts

@@ -92,10 +92,15 @@ declare class LioranDB {
     private walPath;
     private metaPath;
     private meta;
+    private migrator;
     private static TX_SEQ;
     constructor(basePath: string, dbName: string, manager: LioranManager);
     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;

package/dist/index.js

@@ -1,11 +1,11 @@
 // src/LioranManager.ts
-import path6 from "path";
-import fs6 from "fs";
+import path7 from "path";
+import fs7 from "fs";
 import process2 from "process";
 
 // src/core/database.ts
-import path3 from "path";
-import fs3 from "fs";
+import path4 from "path";
+import fs4 from "fs";
 import { execFile } from "child_process";
 import { promisify } from "util";
 
@@ -13,8 +13,8 @@ import { promisify } from "util";
 import { ClassicLevel as ClassicLevel3 } from "classic-level";
 
 // src/core/query.ts
-function getByPath(obj, path7) {
-  return path7.split(".").reduce((o, p) => o ? o[p] : void 0, obj);
+function getByPath(obj, path8) {
+  return path8.split(".").reduce((o, p) => o ? o[p] : void 0, obj);
 }
 function matchDocument(doc, query) {
   for (const key of Object.keys(query)) {
@@ -670,10 +670,134 @@ var Collection = class {
   }
 };
 
+// src/core/migration.ts
+import fs3 from "fs";
+import path3 from "path";
+import crypto3 from "crypto";
+var LOCK_FILE = "__migration.lock";
+var HISTORY_FILE = "__migration_history.json";
+var MigrationEngine = class {
+  constructor(db) {
+    this.db = db;
+  }
+  migrations = /* @__PURE__ */ new Map();
+  /* ------------------------------------------------------------ */
+  /* Public API */
+  /* ------------------------------------------------------------ */
+  register(from, to, fn) {
+    const key = `${from}\u2192${to}`;
+    if (this.migrations.has(key)) {
+      throw new Error(`Duplicate migration: ${key}`);
+    }
+    this.migrations.set(key, fn);
+  }
+  async migrate(from, to, fn) {
+    this.register(from, to, fn);
+    await this.execute();
+  }
+  async upgradeToLatest() {
+    await this.execute();
+  }
+  /* ------------------------------------------------------------ */
+  /* Core Execution Logic */
+  /* ------------------------------------------------------------ */
+  async execute() {
+    let current = this.db.getSchemaVersion();
+    while (true) {
+      const next = this.findNext(current);
+      if (!next) break;
+      const fn = this.migrations.get(`${current}\u2192${next}`);
+      await this.runMigration(current, next, fn);
+      current = next;
+    }
+  }
+  findNext(current) {
+    for (const key of this.migrations.keys()) {
+      const [from, to] = key.split("\u2192");
+      if (from === current) return to;
+    }
+    return null;
+  }
+  /* ------------------------------------------------------------ */
+  /* Atomic Migration Execution */
+  /* ------------------------------------------------------------ */
+  async runMigration(from, to, fn) {
+    const current = this.db.getSchemaVersion();
+    if (current !== from) {
+      throw new Error(
+        `Schema mismatch: DB=${current}, expected=${from}`
+      );
+    }
+    const lockPath = path3.join(this.db.basePath, LOCK_FILE);
+    if (fs3.existsSync(lockPath)) {
+      throw new Error(
+        "Previous migration interrupted. Resolve manually before continuing."
+      );
+    }
+    this.acquireLock(lockPath);
+    try {
+      await this.db.transaction(async () => {
+        await fn(this.db);
+        this.writeHistory(from, to, fn);
+        this.db.setSchemaVersion(to);
+      });
+    } finally {
+      this.releaseLock(lockPath);
+    }
+  }
+  /* ------------------------------------------------------------ */
+  /* Locking */
+  /* ------------------------------------------------------------ */
+  acquireLock(file) {
+    const token = crypto3.randomBytes(16).toString("hex");
+    fs3.writeFileSync(
+      file,
+      JSON.stringify({
+        pid: process.pid,
+        token,
+        time: Date.now()
+      })
+    );
+  }
+  releaseLock(file) {
+    if (fs3.existsSync(file)) fs3.unlinkSync(file);
+  }
+  /* ------------------------------------------------------------ */
+  /* Migration History */
+  /* ------------------------------------------------------------ */
+  historyPath() {
+    return path3.join(this.db.basePath, HISTORY_FILE);
+  }
+  readHistory() {
+    if (!fs3.existsSync(this.historyPath())) return [];
+    return JSON.parse(fs3.readFileSync(this.historyPath(), "utf8"));
+  }
+  writeHistory(from, to, fn) {
+    const history = this.readHistory();
+    history.push({
+      from,
+      to,
+      checksum: this.hash(fn.toString()),
+      appliedAt: Date.now()
+    });
+    fs3.writeFileSync(this.historyPath(), JSON.stringify(history, null, 2));
+  }
+  hash(data) {
+    return crypto3.createHash("sha256").update(data).digest("hex");
+  }
+  /* ------------------------------------------------------------ */
+  /* Diagnostics */
+  /* ------------------------------------------------------------ */
+  getHistory() {
+    return this.readHistory();
+  }
+};
+
 // src/core/database.ts
 var exec = promisify(execFile);
 var META_FILE = "__db_meta.json";
 var META_VERSION = 1;
+var DEFAULT_SCHEMA_VERSION = "v1";
 var DBTransactionContext = class {
   constructor(db, txId) {
     this.db = db;
@@ -710,33 +834,60 @@ var LioranDB = class _LioranDB {
   walPath;
   metaPath;
   meta;
+  migrator;
   static TX_SEQ = 0;
   constructor(basePath, dbName, manager) {
     this.basePath = basePath;
     this.dbName = dbName;
     this.manager = manager;
     this.collections = /* @__PURE__ */ new Map();
-    this.walPath = path3.join(basePath, "__tx_wal.log");
-    this.metaPath = path3.join(basePath, META_FILE);
-    fs3.mkdirSync(basePath, { recursive: true });
+    this.walPath = path4.join(basePath, "__tx_wal.log");
+    this.metaPath = path4.join(basePath, META_FILE);
+    fs4.mkdirSync(basePath, { recursive: true });
     this.loadMeta();
+    this.migrator = new MigrationEngine(this);
     this.recoverFromWAL().catch(console.error);
   }
   /* ------------------------- META ------------------------- */
   loadMeta() {
-    if (!fs3.existsSync(this.metaPath)) {
-      this.meta = { version: META_VERSION, indexes: {} };
+    if (!fs4.existsSync(this.metaPath)) {
+      this.meta = {
+        version: META_VERSION,
+        indexes: {},
+        schemaVersion: DEFAULT_SCHEMA_VERSION
+      };
       this.saveMeta();
       return;
     }
-    this.meta = JSON.parse(fs3.readFileSync(this.metaPath, "utf8"));
+    this.meta = JSON.parse(fs4.readFileSync(this.metaPath, "utf8"));
+    if (!this.meta.schemaVersion) {
+      this.meta.schemaVersion = DEFAULT_SCHEMA_VERSION;
+      this.saveMeta();
+    }
   }
   saveMeta() {
-    fs3.writeFileSync(this.metaPath, JSON.stringify(this.meta, null, 2));
+    fs4.writeFileSync(this.metaPath, JSON.stringify(this.meta, null, 2));
+  }
+  getSchemaVersion() {
+    return this.meta.schemaVersion;
+  }
+  setSchemaVersion(v) {
+    this.meta.schemaVersion = v;
+    this.saveMeta();
+  }
+  /* ------------------------- MIGRATION API ------------------------- */
+  migrate(from, to, fn) {
+    this.migrator.register(from, to, async (db) => {
+      await fn(db);
+      db.setSchemaVersion(to);
+    });
+  }
+  async applyMigrations(targetVersion) {
+    await this.migrator.upgradeToLatest();
   }
   /* ------------------------- WAL ------------------------- */
   async writeWAL(entries) {
-    const fd = await fs3.promises.open(this.walPath, "a");
+    const fd = await fs4.promises.open(this.walPath, "a");
     for (const e of entries) {
       await fd.write(JSON.stringify(e) + "\n");
     }
@@ -745,13 +896,13 @@ var LioranDB = class _LioranDB {
   }
   async clearWAL() {
     try {
-      await fs3.promises.unlink(this.walPath);
+      await fs4.promises.unlink(this.walPath);
     } catch {
     }
   }
   async recoverFromWAL() {
-    if (!fs3.existsSync(this.walPath)) return;
-    const raw = await fs3.promises.readFile(this.walPath, "utf8");
+    if (!fs4.existsSync(this.walPath)) return;
+    const raw = await fs4.promises.readFile(this.walPath, "utf8");
     const committed = /* @__PURE__ */ new Set();
     const applied = /* @__PURE__ */ new Set();
     const ops = /* @__PURE__ */ new Map();
@@ -785,8 +936,8 @@ var LioranDB = class _LioranDB {
       if (schema) col2.setSchema(schema);
       return col2;
     }
-    const colPath = path3.join(this.basePath, name);
-    fs3.mkdirSync(colPath, { recursive: true });
+    const colPath = path4.join(this.basePath, name);
+    fs4.mkdirSync(colPath, { recursive: true });
     const col = new Collection(colPath, schema);
     const metas = this.meta.indexes[name] ?? [];
     for (const m of metas) {
@@ -801,9 +952,15 @@ var LioranDB = class _LioranDB {
     const existing = this.meta.indexes[collection]?.find((i) => i.field === field);
     if (existing) return;
     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"));
-      await index.insert(doc);
+    for await (const [key, enc] of col.db.iterator()) {
+      if (!enc) continue;
+      try {
+        const doc = decryptData2(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}`);
+      }
     }
     col.registerIndex(index);
     if (!this.meta.indexes[collection]) {
@@ -812,41 +969,6 @@ var LioranDB = class _LioranDB {
     this.meta.indexes[collection].push({ field, options });
     this.saveMeta();
   }
-  /* ------------------------- SNAPSHOT ENGINE ------------------------- */
-  // async snapshot(snapshotPath: string) {
-  //   await this.clearWAL();
-  //   for (const col of this.collections.values()) {
-  //     await col.close();
-  //   }
-  //   fs.mkdirSync(path.dirname(snapshotPath), { recursive: true });
-  //   await exec("tar", [
-  //     "-czf",
-  //     snapshotPath,
-  //     "-C",
-  //     this.basePath,
-  //     "."
-  //   ]);
-  // }
-  // async restore(snapshotPath: string) {
-  //   if (!fs.existsSync(snapshotPath)) {
-  //     throw new Error("Snapshot file does not exist");
-  //   }
-  //   await this.close();
-  //   const tmp = this.basePath + ".restore";
-  //   await fs.promises.rm(tmp, { recursive: true, force: true });
-  //   await fs.promises.mkdir(tmp, { recursive: true });
-  //   await exec("tar", [
-  //     "-xzf",
-  //     snapshotPath,
-  //     "-C",
-  //     tmp
-  //   ]);
-  //   await fs.promises.rm(this.basePath, { recursive: true, force: true });
-  //   await fs.promises.rename(tmp, this.basePath);
-  //   this.collections.clear();
-  //   this.loadMeta();
-  //   await this.recoverFromWAL();
-  // }
   /* ------------------------- COMPACTION ------------------------- */
   async compactCollection(name) {
     await this.clearWAL();
@@ -878,18 +1000,21 @@ var LioranDB = class _LioranDB {
     this.collections.clear();
   }
 };
+function decryptData2(enc) {
+  throw new Error("Function not implemented.");
+}
 
 // src/utils/rootpath.ts
 import os2 from "os";
-import path4 from "path";
-import fs4 from "fs";
+import path5 from "path";
+import fs5 from "fs";
 function getDefaultRootPath() {
   let dbPath = process.env.LIORANDB_PATH;
   if (!dbPath) {
     const homeDir = os2.homedir();
-    dbPath = path4.join(homeDir, "LioranDB", "db");
-    if (!fs4.existsSync(dbPath)) {
-      fs4.mkdirSync(dbPath, { recursive: true });
+    dbPath = path5.join(homeDir, "LioranDB", "db");
+    if (!fs5.existsSync(dbPath)) {
+      fs5.mkdirSync(dbPath, { recursive: true });
     }
     process.env.LIORANDB_PATH = dbPath;
   }
@@ -904,24 +1029,24 @@ import net from "net";
 
 // src/ipc/socketPath.ts
 import os3 from "os";
-import path5 from "path";
+import path6 from "path";
 function getIPCSocketPath(rootPath) {
   if (os3.platform() === "win32") {
     return `\\\\.\\pipe\\liorandb_${rootPath.replace(/[:\\\/]/g, "_")}`;
   }
-  return path5.join(rootPath, ".lioran.sock");
+  return path6.join(rootPath, ".lioran.sock");
 }
 
 // src/ipc/client.ts
 function delay(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
-async function connectWithRetry(path7) {
+async function connectWithRetry(path8) {
   let attempt = 0;
   while (true) {
     try {
       return await new Promise((resolve, reject) => {
-        const socket = net.connect(path7, () => resolve(socket));
+        const socket = net.connect(path8, () => resolve(socket));
         socket.once("error", reject);
       });
     } catch (err) {
@@ -1004,11 +1129,11 @@ var DBQueue = class {
     return this.exec("compact:all", {});
   }
   /* ----------------------------- SNAPSHOT API ----------------------------- */
-  snapshot(path7) {
-    return this.exec("snapshot", { path: path7 });
+  snapshot(path8) {
+    return this.exec("snapshot", { path: path8 });
   }
-  restore(path7) {
-    return this.exec("restore", { path: path7 });
+  restore(path8) {
+    return this.exec("restore", { path: path8 });
   }
   /* ------------------------------ SHUTDOWN ------------------------------ */
   async shutdown() {
@@ -1023,7 +1148,7 @@ var dbQueue = new DBQueue();
 
 // src/ipc/server.ts
 import net2 from "net";
-import fs5 from "fs";
+import fs6 from "fs";
 var IPCServer = class {
   server;
   manager;
@@ -1034,7 +1159,7 @@ var IPCServer = class {
   }
   start() {
     if (!this.socketPath.startsWith("\\\\.\\")) {
-      if (fs5.existsSync(this.socketPath)) fs5.unlinkSync(this.socketPath);
+      if (fs6.existsSync(this.socketPath)) fs6.unlinkSync(this.socketPath);
     }
     this.server = net2.createServer((socket) => {
       let buffer = "";
@@ -1136,7 +1261,7 @@ var IPCServer = class {
     if (this.server) this.server.close();
     if (!this.socketPath.startsWith("\\\\.\\")) {
       try {
-        fs5.unlinkSync(this.socketPath);
+        fs6.unlinkSync(this.socketPath);
       } catch {
       }
     }
@@ -1154,8 +1279,8 @@ var LioranManager = class {
   constructor(options = {}) {
     const { rootPath, encryptionKey } = options;
     this.rootPath = rootPath || getDefaultRootPath();
-    if (!fs6.existsSync(this.rootPath)) {
-      fs6.mkdirSync(this.rootPath, { recursive: true });
+    if (!fs7.existsSync(this.rootPath)) {
+      fs7.mkdirSync(this.rootPath, { recursive: true });
     }
     if (encryptionKey) {
       setEncryptionKey(encryptionKey);
@@ -1178,18 +1303,18 @@ var LioranManager = class {
     }
   }
   tryAcquireLock() {
-    const lockPath = path6.join(this.rootPath, ".lioran.lock");
+    const lockPath = path7.join(this.rootPath, ".lioran.lock");
     try {
-      this.lockFd = fs6.openSync(lockPath, "wx");
-      fs6.writeSync(this.lockFd, String(process2.pid));
+      this.lockFd = fs7.openSync(lockPath, "wx");
+      fs7.writeSync(this.lockFd, String(process2.pid));
       return true;
     } catch {
       try {
-        const pid = Number(fs6.readFileSync(lockPath, "utf8"));
+        const pid = Number(fs7.readFileSync(lockPath, "utf8"));
         if (!this.isProcessAlive(pid)) {
-          fs6.unlinkSync(lockPath);
-          this.lockFd = fs6.openSync(lockPath, "wx");
-          fs6.writeSync(this.lockFd, String(process2.pid));
+          fs7.unlinkSync(lockPath);
+          this.lockFd = fs7.openSync(lockPath, "wx");
+          fs7.writeSync(this.lockFd, String(process2.pid));
           return true;
         }
       } catch {
@@ -1210,8 +1335,8 @@ var LioranManager = class {
     if (this.openDBs.has(name)) {
       return this.openDBs.get(name);
     }
-    const dbPath = path6.join(this.rootPath, name);
-    await fs6.promises.mkdir(dbPath, { recursive: true });
+    const dbPath = path7.join(this.rootPath, name);
+    await fs7.promises.mkdir(dbPath, { recursive: true });
     const db = new LioranDB(dbPath, name, this);
     this.openDBs.set(name, db);
     return db;
@@ -1232,7 +1357,7 @@ var LioranManager = class {
         }
       }
     }
-    fs6.mkdirSync(path6.dirname(snapshotPath), { recursive: true });
+    fs7.mkdirSync(path7.dirname(snapshotPath), { recursive: true });
     const tar = await import("tar");
     await tar.c({
       gzip: true,
@@ -1250,8 +1375,8 @@ var LioranManager = class {
       return dbQueue.exec("restore", { path: snapshotPath });
     }
     await this.closeAll();
-    fs6.rmSync(this.rootPath, { recursive: true, force: true });
-    fs6.mkdirSync(this.rootPath, { recursive: true });
+    fs7.rmSync(this.rootPath, { recursive: true, force: true });
+    fs7.mkdirSync(this.rootPath, { recursive: true });
     const tar = await import("tar");
     await tar.x({
       file: snapshotPath,
@@ -1276,8 +1401,8 @@ var LioranManager = class {
     }
     this.openDBs.clear();
     try {
-      if (this.lockFd) fs6.closeSync(this.lockFd);
-      fs6.unlinkSync(path6.join(this.rootPath, ".lioran.lock"));
+      if (this.lockFd) fs7.closeSync(this.lockFd);
+      fs7.unlinkSync(path7.join(this.rootPath, ".lioran.lock"));
     } catch {
     }
     await this.ipcServer?.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liorandb/core",
-  "version": "1.0.16",
+  "version": "1.0.17",
   "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/database.ts

@@ -4,6 +4,7 @@ import { execFile } from "child_process";
 import { promisify } from "util";
 import { Collection } from "./collection.js";
 import { Index, IndexOptions } from "./index.js";
+import { MigrationEngine } from "./migration.js";
 import type { LioranManager } from "../LioranManager.js";
 import type { ZodSchema } from "zod";
 
@@ -24,10 +25,12 @@ type IndexMeta = {
 type DBMeta = {
   version: number;
   indexes: Record<string, IndexMeta[]>;
+  schemaVersion: string;
 };
 
 const META_FILE = "__db_meta.json";
 const META_VERSION = 1;
+const DEFAULT_SCHEMA_VERSION = "v1";
 
 /* ---------------------- TRANSACTION CONTEXT ---------------------- */
 
@@ -37,7 +40,7 @@ class DBTransactionContext {
   constructor(
     private db: LioranDB,
     public readonly txId: number
-  ) {}
+  ) { }
 
   collection(name: string) {
     return new Proxy({}, {
@@ -70,10 +73,13 @@ export class LioranDB {
   dbName: string;
   manager: LioranManager;
   collections: Map<string, Collection>;
+
   private walPath: string;
   private metaPath: string;
   private meta!: DBMeta;
 
+  private migrator: MigrationEngine;
+
   private static TX_SEQ = 0;
 
   constructor(basePath: string, dbName: string, manager: LioranManager) {
@@ -81,12 +87,15 @@ export class LioranDB {
     this.dbName = dbName;
     this.manager = manager;
     this.collections = new Map();
+
     this.walPath = path.join(basePath, "__tx_wal.log");
     this.metaPath = path.join(basePath, META_FILE);
 
     fs.mkdirSync(basePath, { recursive: true });
 
     this.loadMeta();
+    this.migrator = new MigrationEngine(this);
+
     this.recoverFromWAL().catch(console.error);
   }
 
@@ -94,18 +103,49 @@ export class LioranDB {
 
   private loadMeta() {
     if (!fs.existsSync(this.metaPath)) {
-      this.meta = { version: META_VERSION, indexes: {} };
+      this.meta = {
+        version: META_VERSION,
+        indexes: {},
+        schemaVersion: DEFAULT_SCHEMA_VERSION
+      };
       this.saveMeta();
       return;
     }
 
     this.meta = JSON.parse(fs.readFileSync(this.metaPath, "utf8"));
+
+    if (!this.meta.schemaVersion) {
+      this.meta.schemaVersion = DEFAULT_SCHEMA_VERSION;
+      this.saveMeta();
+    }
   }
 
   private saveMeta() {
     fs.writeFileSync(this.metaPath, JSON.stringify(this.meta, null, 2));
   }
 
+  getSchemaVersion(): string {
+    return this.meta.schemaVersion;
+  }
+
+  setSchemaVersion(v: string) {
+    this.meta.schemaVersion = v;
+    this.saveMeta();
+  }
+
+  /* ------------------------- MIGRATION API ------------------------- */
+
+  migrate(from: string, to: string, fn: (db: LioranDB) => Promise<void>) {
+    this.migrator.register(from, to, async db => {
+      await fn(db);
+      db.setSchemaVersion(to);
+    });
+  }
+
+  async applyMigrations(targetVersion: string) {
+    await this.migrator.upgradeToLatest();
+  }
+
   /* ------------------------- WAL ------------------------- */
 
   async writeWAL(entries: WALEntry[]) {
@@ -118,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() {
@@ -196,9 +236,26 @@ 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"));
-      await index.insert(doc);
+    // 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
+        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
+      }
     }
 
     col.registerIndex(index);
@@ -211,53 +268,6 @@ export class LioranDB {
     this.saveMeta();
   }
 
-  /* ------------------------- SNAPSHOT ENGINE ------------------------- */
-
-  // async snapshot(snapshotPath: string) {
-  //   await this.clearWAL();
-
-  //   for (const col of this.collections.values()) {
-  //     await col.close();
-  //   }
-
-  //   fs.mkdirSync(path.dirname(snapshotPath), { recursive: true });
-
-  //   await exec("tar", [
-  //     "-czf",
-  //     snapshotPath,
-  //     "-C",
-  //     this.basePath,
-  //     "."
-  //   ]);
-  // }
-
-  // async restore(snapshotPath: string) {
-  //   if (!fs.existsSync(snapshotPath)) {
-  //     throw new Error("Snapshot file does not exist");
-  //   }
-
-  //   await this.close();
-
-  //   const tmp = this.basePath + ".restore";
-
-  //   await fs.promises.rm(tmp, { recursive: true, force: true });
-  //   await fs.promises.mkdir(tmp, { recursive: true });
-
-  //   await exec("tar", [
-  //     "-xzf",
-  //     snapshotPath,
-  //     "-C",
-  //     tmp
-  //   ]);
-
-  //   await fs.promises.rm(this.basePath, { recursive: true, force: true });
-  //   await fs.promises.rename(tmp, this.basePath);
-
-  //   this.collections.clear();
-  //   this.loadMeta();
-  //   await this.recoverFromWAL();
-  // }
-
   /* ------------------------- COMPACTION ------------------------- */
 
   async compactCollection(name: string) {
@@ -287,8 +297,12 @@ 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/core/migration.store.ts

@@ -0,0 +1,40 @@
+import { MigrationMeta } from "./migration.types";
+import type { LioranDB } from "./database.js";
+
+const MIGRATION_COLLECTION = "__migrations__";
+const MIGRATION_KEY = "__migration_meta__";
+
+export class MigrationStore {
+  constructor(private db: LioranDB) {}
+
+  async get(): Promise<MigrationMeta> {
+    const col = this.db.collection<MigrationMeta>(MIGRATION_COLLECTION);
+    const meta = await col.findOne((d: MigrationMeta) => d.id === MIGRATION_KEY);
+    return (
+      meta ?? {
+        currentVersion: "v1",
+        history: []
+      }
+    );
+  }
+
+  async set(meta: MigrationMeta): Promise<void> {
+    const col = this.db.collection<MigrationMeta>(MIGRATION_COLLECTION);
+    const existing = await col.findOne((d: MigrationMeta) => d.id === MIGRATION_KEY);
+    if (existing) {
+      await col.updateOne(existing._id, { ...meta, id: MIGRATION_KEY });
+    } else {
+      await col.insertOne({ ...meta, id: MIGRATION_KEY });
+    }
+  }
+
+  async updateVersion(version: string): Promise<void> {
+    const meta = await this.get();
+    meta.currentVersion = version;
+    meta.history.push({
+      version,
+      appliedAt: Date.now()
+    });
+    await this.set(meta);
+  }
+}

package/src/core/migration.ts

@@ -0,0 +1,162 @@
+import fs from "fs";
+import path from "path";
+import crypto from "crypto";
+import type { LioranDB } from "./database.js";
+
+export type MigrationFn = (db: LioranDB) => Promise<void>;
+
+type MigrationRecord = {
+  from: string;
+  to: string;
+  checksum: string;
+  appliedAt: number;
+};
+
+const LOCK_FILE = "__migration.lock";
+const HISTORY_FILE = "__migration_history.json";
+
+export class MigrationEngine {
+  private migrations = new Map<string, MigrationFn>();
+
+  constructor(private db: LioranDB) {}
+
+  /* ------------------------------------------------------------ */
+  /* Public API */
+  /* ------------------------------------------------------------ */
+
+  register(from: string, to: string, fn: MigrationFn) {
+    const key = `${from}→${to}`;
+
+    if (this.migrations.has(key)) {
+      throw new Error(`Duplicate migration: ${key}`);
+    }
+
+    this.migrations.set(key, fn);
+  }
+
+  async migrate(from: string, to: string, fn: MigrationFn) {
+    this.register(from, to, fn);
+    await this.execute();
+  }
+
+  async upgradeToLatest() {
+    await this.execute();
+  }
+
+  /* ------------------------------------------------------------ */
+  /* Core Execution Logic */
+  /* ------------------------------------------------------------ */
+
+  private async execute() {
+    let current = this.db.getSchemaVersion();
+
+    while (true) {
+      const next = this.findNext(current);
+      if (!next) break;
+
+      const fn = this.migrations.get(`${current}→${next}`)!;
+      await this.runMigration(current, next, fn);
+      current = next;
+    }
+  }
+
+  private findNext(current: string): string | null {
+    for (const key of this.migrations.keys()) {
+      const [from, to] = key.split("→");
+      if (from === current) return to;
+    }
+    return null;
+  }
+
+  /* ------------------------------------------------------------ */
+  /* Atomic Migration Execution */
+  /* ------------------------------------------------------------ */
+
+  private async runMigration(from: string, to: string, fn: MigrationFn) {
+    const current = this.db.getSchemaVersion();
+    if (current !== from) {
+      throw new Error(
+        `Schema mismatch: DB=${current}, expected=${from}`
+      );
+    }
+
+    const lockPath = path.join(this.db.basePath, LOCK_FILE);
+
+    if (fs.existsSync(lockPath)) {
+      throw new Error(
+        "Previous migration interrupted. Resolve manually before continuing."
+      );
+    }
+
+    this.acquireLock(lockPath);
+
+    try {
+      await this.db.transaction(async () => {
+        await fn(this.db);
+        this.writeHistory(from, to, fn);
+        this.db.setSchemaVersion(to);
+      });
+    } finally {
+      this.releaseLock(lockPath);
+    }
+  }
+
+  /* ------------------------------------------------------------ */
+  /* Locking */
+  /* ------------------------------------------------------------ */
+
+  private acquireLock(file: string) {
+    const token = crypto.randomBytes(16).toString("hex");
+
+    fs.writeFileSync(
+      file,
+      JSON.stringify({
+        pid: process.pid,
+        token,
+        time: Date.now(),
+      })
+    );
+  }
+
+  private releaseLock(file: string) {
+    if (fs.existsSync(file)) fs.unlinkSync(file);
+  }
+
+  /* ------------------------------------------------------------ */
+  /* Migration History */
+  /* ------------------------------------------------------------ */
+
+  private historyPath() {
+    return path.join(this.db.basePath, HISTORY_FILE);
+  }
+
+  private readHistory(): MigrationRecord[] {
+    if (!fs.existsSync(this.historyPath())) return [];
+    return JSON.parse(fs.readFileSync(this.historyPath(), "utf8"));
+  }
+
+  private writeHistory(from: string, to: string, fn: MigrationFn) {
+    const history = this.readHistory();
+
+    history.push({
+      from,
+      to,
+      checksum: this.hash(fn.toString()),
+      appliedAt: Date.now(),
+    });
+
+    fs.writeFileSync(this.historyPath(), JSON.stringify(history, null, 2));
+  }
+
+  private hash(data: string) {
+    return crypto.createHash("sha256").update(data).digest("hex");
+  }
+
+  /* ------------------------------------------------------------ */
+  /* Diagnostics */
+  /* ------------------------------------------------------------ */
+
+  getHistory(): MigrationRecord[] {
+    return this.readHistory();
+  }
+}

package/src/core/migration.types.ts

@@ -0,0 +1,22 @@
+import type { LioranDB } from "./database.js";
+
+export type MigrationVersion = string;
+
+export type MigrationFn = (db: LioranDB) => Promise<void>;
+
+export interface Migration {
+  from: MigrationVersion;
+  to: MigrationVersion;
+  run: MigrationFn;
+}
+
+export interface MigrationRecord {
+  version: MigrationVersion;
+  appliedAt: number;
+}
+
+export interface MigrationMeta {
+  id?: string;
+  currentVersion: MigrationVersion;
+  history: MigrationRecord[];
+}