@liorandb/core 1.0.15 → 1.0.17

package/dist/index.d.ts

@@ -92,23 +92,22 @@ 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;
     applyTransaction(ops: TXOp[]): Promise<void>;
     collection<T = any>(name: string, schema?: ZodSchema<T>): Collection<T>;
     createIndex(collection: string, field: string, options?: IndexOptions): Promise<void>;
-    /**
-     * Compact single collection safely (WAL + TX safe)
-     */
     compactCollection(name: string): Promise<void>;
-    /**
-     * Compact entire database safely
-     */
     compactAll(): Promise<void>;
     transaction<T>(fn: (tx: DBTransactionContext) => Promise<T>): Promise<T>;
     close(): Promise<void>;
@@ -130,6 +129,14 @@ declare class LioranManager {
     private tryAcquireLock;
     db(name: string): Promise<LioranDB>;
     openDatabase(name: string): Promise<LioranDB>;
+    /**
+     * Create TAR snapshot of full DB directory
+     */
+    snapshot(snapshotPath: string): Promise<unknown>;
+    /**
+     * Restore TAR snapshot safely
+     */
+    restore(snapshotPath: string): Promise<unknown>;
     closeAll(): Promise<void>;
     close(): Promise<void>;
     private _registerShutdownHooks;

package/dist/index.js

@@ -1,18 +1,20 @@
 // 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";
 
 // src/core/collection.ts
 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)) {
@@ -668,9 +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;
@@ -707,37 +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;
     }
-    try {
-      this.meta = JSON.parse(fs3.readFileSync(this.metaPath, "utf8"));
-    } catch {
-      throw new Error("Database metadata corrupted");
+    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");
     }
@@ -746,28 +896,24 @@ 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();
     for (const line of raw.split("\n")) {
       if (!line.trim()) continue;
-      try {
-        const entry = JSON.parse(line);
-        if ("commit" in entry) committed.add(entry.tx);
-        else if ("applied" in entry) applied.add(entry.tx);
-        else {
-          if (!ops.has(entry.tx)) ops.set(entry.tx, []);
-          ops.get(entry.tx).push(entry);
-        }
-      } catch {
-        break;
+      const entry = JSON.parse(line);
+      if ("commit" in entry) committed.add(entry.tx);
+      else if ("applied" in entry) applied.add(entry.tx);
+      else {
+        if (!ops.has(entry.tx)) ops.set(entry.tx, []);
+        ops.get(entry.tx).push(entry);
       }
     }
     for (const tx of committed) {
@@ -790,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) {
@@ -806,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]) {
@@ -817,18 +969,12 @@ var LioranDB = class _LioranDB {
     this.meta.indexes[collection].push({ field, options });
     this.saveMeta();
   }
-  /* ---------------------- COMPACTION ORCHESTRATOR ---------------------- */
-  /**
-   * Compact single collection safely (WAL + TX safe)
-   */
+  /* ------------------------- COMPACTION ------------------------- */
   async compactCollection(name) {
-    const col = this.collection(name);
     await this.clearWAL();
+    const col = this.collection(name);
     await col.compact();
   }
-  /**
-   * Compact entire database safely
-   */
   async compactAll() {
     await this.clearWAL();
     for (const name of this.collections.keys()) {
@@ -854,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;
   }
@@ -880,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) {
@@ -979,6 +1128,13 @@ var DBQueue = class {
   compactAll() {
     return this.exec("compact:all", {});
   }
+  /* ----------------------------- SNAPSHOT API ----------------------------- */
+  snapshot(path8) {
+    return this.exec("snapshot", { path: path8 });
+  }
+  restore(path8) {
+    return this.exec("restore", { path: path8 });
+  }
   /* ------------------------------ SHUTDOWN ------------------------------ */
   async shutdown() {
     try {
@@ -992,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;
@@ -1003,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 = "";
@@ -1016,7 +1172,7 @@ var IPCServer = class {
           try {
             const msg = JSON.parse(raw);
             await this.handleMessage(socket, msg);
-          } catch (err) {
+          } catch {
             socket.write(JSON.stringify({
               id: null,
               ok: false,
@@ -1059,12 +1215,27 @@ var IPCServer = class {
         case "compact:db": {
           const { db } = args;
           const database = await this.manager.db(db);
-          await database.compact();
+          await database.compactAll();
           result = true;
           break;
         }
         case "compact:all": {
-          await this.manager.compactAll();
+          for (const db of this.manager.openDBs.values()) {
+            await db.compactAll();
+          }
+          result = true;
+          break;
+        }
+        /* ---------------- SNAPSHOT ---------------- */
+        case "snapshot": {
+          const { path: snapshotPath } = args;
+          await this.manager.snapshot(snapshotPath);
+          result = true;
+          break;
+        }
+        case "restore": {
+          const { path: snapshotPath } = args;
+          await this.manager.restore(snapshotPath);
           result = true;
           break;
         }
@@ -1090,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 {
       }
     }
@@ -1108,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);
@@ -1122,6 +1293,7 @@ var LioranManager = class {
       this._registerShutdownHooks();
     }
   }
+  /* ---------------- LOCK MANAGEMENT ---------------- */
   isProcessAlive(pid) {
     try {
       process2.kill(pid, 0);
@@ -1131,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 {
@@ -1150,6 +1322,7 @@ var LioranManager = class {
       return false;
     }
   }
+  /* ---------------- DB OPEN ---------------- */
   async db(name) {
     if (this.mode === "client" /* CLIENT */) {
       await dbQueue.exec("db", { db: name });
@@ -1162,12 +1335,57 @@ 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;
   }
+  /* ---------------- SNAPSHOT ORCHESTRATION ---------------- */
+  /**
+   * Create TAR snapshot of full DB directory
+   */
+  async snapshot(snapshotPath) {
+    if (this.mode === "client" /* CLIENT */) {
+      return dbQueue.exec("snapshot", { path: snapshotPath });
+    }
+    for (const db of this.openDBs.values()) {
+      for (const col of db.collections.values()) {
+        try {
+          await col.db.close();
+        } catch {
+        }
+      }
+    }
+    fs7.mkdirSync(path7.dirname(snapshotPath), { recursive: true });
+    const tar = await import("tar");
+    await tar.c({
+      gzip: true,
+      file: snapshotPath,
+      cwd: this.rootPath,
+      portable: true
+    }, ["./"]);
+    return true;
+  }
+  /**
+   * Restore TAR snapshot safely
+   */
+  async restore(snapshotPath) {
+    if (this.mode === "client" /* CLIENT */) {
+      return dbQueue.exec("restore", { path: snapshotPath });
+    }
+    await this.closeAll();
+    fs7.rmSync(this.rootPath, { recursive: true, force: true });
+    fs7.mkdirSync(this.rootPath, { recursive: true });
+    const tar = await import("tar");
+    await tar.x({
+      file: snapshotPath,
+      cwd: this.rootPath
+    });
+    console.log("Restore completed. Restart required.");
+    process2.exit(0);
+  }
+  /* ---------------- SHUTDOWN ---------------- */
   async closeAll() {
     if (this.closed) return;
     this.closed = true;
@@ -1183,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.15",
+  "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",
@@ -28,7 +28,10 @@
   },
   "homepage": "https://github.com/LioranGroupOfficial/Liorandb#readme",
   "dependencies": {
+    "@types/tar-stream": "^3.1.4",
     "classic-level": "^3.0.0",
+    "tar": "^7.5.9",
+    "tar-stream": "^3.1.7",
     "uuid": "^13.0.0",
     "zod": "^4.3.6"
   },