@liorandb/core 1.0.15 → 1.0.16

package/dist/index.d.ts

@@ -102,13 +102,7 @@ declare class LioranDB {
     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 +124,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

@@ -6,6 +6,8 @@ import process2 from "process";
 // src/core/database.ts
 import path3 from "path";
 import fs3 from "fs";
+import { execFile } from "child_process";
+import { promisify } from "util";
 
 // src/core/collection.ts
 import { ClassicLevel as ClassicLevel3 } from "classic-level";
@@ -669,6 +671,7 @@ var Collection = class {
 };
 
 // src/core/database.ts
+var exec = promisify(execFile);
 var META_FILE = "__db_meta.json";
 var META_VERSION = 1;
 var DBTransactionContext = class {
@@ -726,11 +729,7 @@ var LioranDB = class _LioranDB {
       this.saveMeta();
       return;
     }
-    try {
-      this.meta = JSON.parse(fs3.readFileSync(this.metaPath, "utf8"));
-    } catch {
-      throw new Error("Database metadata corrupted");
-    }
+    this.meta = JSON.parse(fs3.readFileSync(this.metaPath, "utf8"));
   }
   saveMeta() {
     fs3.writeFileSync(this.metaPath, JSON.stringify(this.meta, null, 2));
@@ -758,16 +757,12 @@ var LioranDB = class _LioranDB {
     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) {
@@ -817,18 +812,47 @@ var LioranDB = class _LioranDB {
     this.meta.indexes[collection].push({ field, options });
     this.saveMeta();
   }
-  /* ---------------------- COMPACTION ORCHESTRATOR ---------------------- */
-  /**
-   * Compact single collection safely (WAL + TX safe)
-   */
+  /* ------------------------- 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) {
-    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()) {
@@ -979,6 +1003,13 @@ var DBQueue = class {
   compactAll() {
     return this.exec("compact:all", {});
   }
+  /* ----------------------------- SNAPSHOT API ----------------------------- */
+  snapshot(path7) {
+    return this.exec("snapshot", { path: path7 });
+  }
+  restore(path7) {
+    return this.exec("restore", { path: path7 });
+  }
   /* ------------------------------ SHUTDOWN ------------------------------ */
   async shutdown() {
     try {
@@ -1016,7 +1047,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 +1090,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;
         }
@@ -1122,6 +1168,7 @@ var LioranManager = class {
       this._registerShutdownHooks();
     }
   }
+  /* ---------------- LOCK MANAGEMENT ---------------- */
   isProcessAlive(pid) {
     try {
       process2.kill(pid, 0);
@@ -1150,6 +1197,7 @@ var LioranManager = class {
       return false;
     }
   }
+  /* ---------------- DB OPEN ---------------- */
   async db(name) {
     if (this.mode === "client" /* CLIENT */) {
       await dbQueue.exec("db", { db: name });
@@ -1168,6 +1216,51 @@ var LioranManager = class {
     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 {
+        }
+      }
+    }
+    fs6.mkdirSync(path6.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();
+    fs6.rmSync(this.rootPath, { recursive: true, force: true });
+    fs6.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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liorandb/core",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "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"
   },

package/src/LioranManager.ts

@@ -51,6 +51,8 @@ export class LioranManager {
     }
   }
 
+  /* ---------------- LOCK MANAGEMENT ---------------- */
+
   private isProcessAlive(pid: number): boolean {
     try {
       process.kill(pid, 0);
@@ -68,7 +70,6 @@ export class LioranManager {
       fs.writeSync(this.lockFd, String(process.pid));
       return true;
     } catch {
-      // Possible stale lock → validate PID
       try {
         const pid = Number(fs.readFileSync(lockPath, "utf8"));
         if (!this.isProcessAlive(pid)) {
@@ -77,18 +78,18 @@ export class LioranManager {
           fs.writeSync(this.lockFd, String(process.pid));
           return true;
         }
-      } catch {}
-
+      } catch { }
       return false;
     }
   }
 
+  /* ---------------- DB OPEN ---------------- */
+
   async db(name: string): Promise<LioranDB> {
     if (this.mode === ProcessMode.CLIENT) {
       await dbQueue.exec("db", { db: name });
       return new IPCDatabase(name) as any;
     }
-
     return this.openDatabase(name);
   }
 
@@ -107,6 +108,64 @@ export class LioranManager {
     return db;
   }
 
+  /* ---------------- SNAPSHOT ORCHESTRATION ---------------- */
+
+  /**
+   * Create TAR snapshot of full DB directory
+   */
+  async snapshot(snapshotPath: string) {
+    if (this.mode === ProcessMode.CLIENT) {
+      return dbQueue.exec("snapshot", { path: snapshotPath });
+    }
+
+    // Flush all DBs safely
+    for (const db of this.openDBs.values()) {
+      for (const col of db.collections.values()) {
+        try { await col.db.close(); } catch { }
+      }
+    }
+
+    // Ensure backup directory exists
+    fs.mkdirSync(path.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: string) {
+    if (this.mode === ProcessMode.CLIENT) {
+      return dbQueue.exec("restore", { path: snapshotPath });
+    }
+
+    await this.closeAll();
+
+    fs.rmSync(this.rootPath, { recursive: true, force: true });
+    fs.mkdirSync(this.rootPath, { recursive: true });
+
+    const tar = await import("tar");
+
+    await tar.x({
+      file: snapshotPath,
+      cwd: this.rootPath
+    });
+
+    console.log("Restore completed. Restart required.");
+    process.exit(0);
+  }
+
+  /* ---------------- SHUTDOWN ---------------- */
+
   async closeAll(): Promise<void> {
     if (this.closed) return;
     this.closed = true;
@@ -117,7 +176,7 @@ export class LioranManager {
     }
 
     for (const db of this.openDBs.values()) {
-      try { await db.close(); } catch {}
+      try { await db.close(); } catch { }
     }
 
     this.openDBs.clear();
@@ -125,7 +184,7 @@ export class LioranManager {
     try {
       if (this.lockFd) fs.closeSync(this.lockFd);
       fs.unlinkSync(path.join(this.rootPath, ".lioran.lock"));
-    } catch {}
+    } catch { }
 
     await this.ipcServer?.close();
   }
@@ -154,7 +213,7 @@ export class LioranManager {
 /* ---------------- IPC PROXY DB ---------------- */
 
 class IPCDatabase {
-  constructor(private name: string) {}
+  constructor(private name: string) { }
 
   collection(name: string) {
     return new IPCCollection(this.name, name);
@@ -165,7 +224,7 @@ class IPCCollection {
   constructor(
     private db: string,
     private col: string
-  ) {}
+  ) { }
 
   private call(method: string, params: any[]) {
     return dbQueue.exec("op", {

package/src/core/database.ts

@@ -1,10 +1,14 @@
 import path from "path";
 import fs from "fs";
+import { execFile } from "child_process";
+import { promisify } from "util";
 import { Collection } from "./collection.js";
 import { Index, IndexOptions } from "./index.js";
 import type { LioranManager } from "../LioranManager.js";
 import type { ZodSchema } from "zod";
 
+const exec = promisify(execFile);
+
 /* ----------------------------- TYPES ----------------------------- */
 
 type TXOp = { tx: number; col: string; op: string; args: any[] };
@@ -95,11 +99,7 @@ export class LioranDB {
       return;
     }
 
-    try {
-      this.meta = JSON.parse(fs.readFileSync(this.metaPath, "utf8"));
-    } catch {
-      throw new Error("Database metadata corrupted");
-    }
+    this.meta = JSON.parse(fs.readFileSync(this.metaPath, "utf8"));
   }
 
   private saveMeta() {
@@ -133,17 +133,13 @@ export class LioranDB {
     for (const line of raw.split("\n")) {
       if (!line.trim()) continue;
 
-      try {
-        const entry: WALEntry = 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: WALEntry = 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);
       }
     }
 
@@ -177,7 +173,6 @@ export class LioranDB {
 
     const col = new Collection<T>(colPath, schema);
 
-    // Auto-load indexes
     const metas = this.meta.indexes[name] ?? [];
     for (const m of metas) {
       col.registerIndex(new Index(colPath, m.field, m.options));
@@ -216,27 +211,63 @@ export class LioranDB {
     this.saveMeta();
   }
 
-  /* ---------------------- COMPACTION ORCHESTRATOR ---------------------- */
+  /* ------------------------- SNAPSHOT ENGINE ------------------------- */
 
-  /**
-   * Compact single collection safely (WAL + TX safe)
-   */
-  async compactCollection(name: string) {
-    const col = this.collection(name);
+  // async snapshot(snapshotPath: string) {
+  //   await this.clearWAL();
 
-    // Ensure WAL is fully flushed
-    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 });
 
-    // Perform compaction inside write barrier
+  //   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) {
+    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()) {
       await this.compactCollection(name);
     }
@@ -247,10 +278,8 @@ export class LioranDB {
   async transaction<T>(fn: (tx: DBTransactionContext) => Promise<T>): Promise<T> {
     const txId = ++LioranDB.TX_SEQ;
     const tx = new DBTransactionContext(this, txId);
-
     const result = await fn(tx);
     await tx.commit();
-
     return result;
   }
 
@@ -262,4 +291,4 @@ export class LioranDB {
     }
     this.collections.clear();
   }
-}
+}

package/src/ipc/index.ts

@@ -72,6 +72,14 @@ class DBProxy {
   compact() {
     return dbQueue.exec("compact:db", { db: this.dbName });
   }
+
+  snapshot(path: string) {
+    return dbQueue.exec("snapshot", { path });
+  }
+
+  restore(path: string) {
+    return dbQueue.exec("restore", { path });
+  }
 }
 
 /* -------------------------------- MANAGER PROXY -------------------------------- */
@@ -85,6 +93,18 @@ class LioranManagerIPC {
   compactAll() {
     return dbQueue.exec("compact:all", {});
   }
+
+  snapshot(path: string) {
+    return dbQueue.exec("snapshot", { path });
+  }
+
+  restore(path: string) {
+    return dbQueue.exec("restore", { path });
+  }
+
+  shutdown() {
+    return dbQueue.shutdown();
+  }
 }
 
 export const manager = new LioranManagerIPC();

package/src/ipc/queue.ts

@@ -10,7 +10,13 @@ export type IPCAction =
   | "compact:collection"
   | "compact:db"
   | "compact:all"
-  | "shutdown";
+  | "shutdown"
+  | "open"
+  | "close"
+  | "minimize"
+  | "maximize"
+  | "restore"
+  | "snapshot";
 
 /* -------------------------------- DB QUEUE -------------------------------- */
 
@@ -39,6 +45,16 @@ export class DBQueue {
     return this.exec("compact:all", {});
   }
 
+  /* ----------------------------- SNAPSHOT API ----------------------------- */
+
+  snapshot(path: string) {
+    return this.exec("snapshot", { path });
+  }
+
+  restore(path: string) {
+    return this.exec("restore", { path });
+  }
+
   /* ------------------------------ SHUTDOWN ------------------------------ */
 
   async shutdown() {

package/src/ipc/server.ts

@@ -32,7 +32,7 @@ export class IPCServer {
           try {
             const msg = JSON.parse(raw);
             await this.handleMessage(socket, msg);
-          } catch (err) {
+          } catch {
             socket.write(JSON.stringify({
               id: null,
               ok: false,
@@ -85,13 +85,31 @@ export class IPCServer {
         case "compact:db": {
           const { db } = args;
           const database = await this.manager.db(db);
-          await (database as any).compact();
+          await (database as any).compactAll();
           result = true;
           break;
         }
 
         case "compact:all": {
-          await (this.manager as any).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;
         }

package/src/utils/tar.ts

@@ -0,0 +1,89 @@
+import fs from "fs";
+import path from "path";
+import { pipeline } from "stream/promises";
+import zlib from "zlib";
+import tar from "tar-stream";
+
+/**
+ * Create a TAR.GZ archive from a directory
+ */
+export async function createTarGz(
+  sourceDir: string,
+  outFile: string
+): Promise<void> {
+  await fs.promises.mkdir(path.dirname(outFile), { recursive: true });
+
+  const pack = tar.pack();
+  const gzip = zlib.createGzip();
+  const out = fs.createWriteStream(outFile + ".tmp");
+
+  const writeStream = pipeline(pack, gzip, out);
+
+  async function walk(dir: string) {
+    const entries = await fs.promises.readdir(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      const relPath = path.relative(sourceDir, fullPath);
+
+      if (entry.isDirectory()) {
+        await walk(fullPath);
+      } else if (entry.isFile()) {
+        const stat = await fs.promises.stat(fullPath);
+        const stream = fs.createReadStream(fullPath);
+
+        await new Promise<void>((resolve, reject) => {
+          const header = {
+            name: relPath,
+            size: stat.size,
+            mode: stat.mode,
+            mtime: stat.mtime
+          };
+
+          const entryStream = pack.entry(header, err => {
+            if (err) reject(err);
+            else resolve();
+          });
+
+          stream.pipe(entryStream);
+        });
+      }
+    }
+  }
+
+  await walk(sourceDir);
+
+  pack.finalize();
+  await writeStream;
+
+  await fs.promises.rename(outFile + ".tmp", outFile);
+}
+
+/**
+ * Extract TAR.GZ archive into directory
+ */
+export async function extractTarGz(
+  archiveFile: string,
+  targetDir: string
+): Promise<void> {
+  await fs.promises.mkdir(targetDir, { recursive: true });
+
+  const extract = tar.extract();
+  const gunzip = zlib.createGunzip();
+  const input = fs.createReadStream(archiveFile);
+
+  extract.on("entry", async (header, stream, next) => {
+    const outPath = path.join(targetDir, header.name);
+
+    await fs.promises.mkdir(path.dirname(outPath), { recursive: true });
+
+    const out = fs.createWriteStream(outPath, {
+      mode: header.mode
+    });
+
+    await pipeline(stream, out);
+    next();
+  });
+
+  await pipeline(input, gunzip, extract);
+}