@liorandb/core 1.0.13 → 1.0.14

package/dist/index.d.ts

@@ -1,6 +1,26 @@
 import { ClassicLevel } from 'classic-level';
 import { ZodSchema } from 'zod';
 
+interface IndexOptions {
+    unique?: boolean;
+}
+declare class Index {
+    readonly field: string;
+    readonly unique: boolean;
+    readonly dir: string;
+    readonly db: ClassicLevel<string, string>;
+    constructor(baseDir: string, field: string, options?: IndexOptions);
+    private normalizeKey;
+    private getRaw;
+    private setRaw;
+    private delRaw;
+    insert(doc: any): Promise<void>;
+    delete(doc: any): Promise<void>;
+    update(oldDoc: any, newDoc: any): Promise<void>;
+    find(value: any): Promise<string[]>;
+    close(): Promise<void>;
+}
+
 interface UpdateOptions$1 {
     upsert?: boolean;
 }
@@ -9,7 +29,10 @@ declare class Collection<T = any> {
     db: ClassicLevel<string, string>;
     private queue;
     private schema?;
+    private indexes;
     constructor(dir: string, schema?: ZodSchema<T>);
+    registerIndex(index: Index): void;
+    getIndex(field: string): Index | undefined;
     setSchema(schema: ZodSchema<T>): void;
     private validate;
     private _enqueue;
@@ -28,6 +51,7 @@ declare class Collection<T = any> {
     deleteOne(filter: any): Promise<any>;
     deleteMany(filter: any): Promise<any>;
     countDocuments(filter?: any): Promise<any>;
+    private _updateIndexes;
     private _insertOne;
     private _insertMany;
     private _findOne;
@@ -68,13 +92,18 @@ declare class LioranDB {
     manager: LioranManager;
     collections: Map<string, Collection>;
     private walPath;
+    private metaPath;
+    private meta;
     private static TX_SEQ;
     constructor(basePath: string, dbName: string, manager: LioranManager);
+    private loadMeta;
+    private saveMeta;
     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>;
     transaction<T>(fn: (tx: DBTransactionContext) => Promise<T>): Promise<T>;
     close(): Promise<void>;
 }
@@ -114,5 +143,35 @@ interface UpdateOptions {
 type Query<T = any> = Partial<T> & {
     [key: string]: any;
 };
+type IndexType = "hash" | "btree";
+interface IndexDefinition<T = any> {
+    field: keyof T | string;
+    unique?: boolean;
+    sparse?: boolean;
+    type?: IndexType;
+}
+interface IndexMetadata {
+    field: string;
+    unique: boolean;
+    sparse: boolean;
+    type: IndexType;
+    createdAt: number;
+}
+interface QueryExplainPlan {
+    indexUsed?: string;
+    indexType?: IndexType;
+    scannedDocuments: number;
+    returnedDocuments: number;
+    executionTimeMs: number;
+}
+interface CollectionIndexAPI<T = any> {
+    createIndex(def: IndexDefinition<T>): Promise<void>;
+    dropIndex(field: keyof T | string): Promise<void>;
+    listIndexes(): Promise<IndexMetadata[]>;
+    rebuildIndexes(): Promise<void>;
+}
+interface DatabaseIndexAPI {
+    rebuildAllIndexes(): Promise<void>;
+}
 
-export { LioranDB, LioranManager, type LioranManagerOptions, type Query, type UpdateOptions, getBaseDBFolder };
+export { type CollectionIndexAPI, type DatabaseIndexAPI, type IndexDefinition, type IndexMetadata, type IndexType, LioranDB, LioranManager, type LioranManagerOptions, type Query, type QueryExplainPlan, type UpdateOptions, getBaseDBFolder };

package/dist/index.js

@@ -1,18 +1,18 @@
 // src/LioranManager.ts
-import path4 from "path";
-import fs4 from "fs";
+import path5 from "path";
+import fs5 from "fs";
 import process2 from "process";
 
 // src/core/database.ts
-import path from "path";
-import fs from "fs";
+import path2 from "path";
+import fs2 from "fs";
 
 // src/core/collection.ts
 import { ClassicLevel } from "classic-level";
 
 // src/core/query.ts
-function getByPath(obj, path5) {
-  return path5.split(".").reduce((o, p) => o ? o[p] : void 0, obj);
+function getByPath(obj, path6) {
+  return path6.split(".").reduce((o, p) => o ? o[p] : void 0, obj);
 }
 function matchDocument(doc, query) {
   for (const key of Object.keys(query)) {
@@ -27,8 +27,7 @@ function matchDocument(doc, query) {
         if (op === "$lte" && !(val <= v)) return false;
         if (op === "$ne" && val === v) return false;
         if (op === "$eq" && val !== v) return false;
-        if (op === "$in" && (!Array.isArray(v) || !v.includes(val)))
-          return false;
+        if (op === "$in" && (!Array.isArray(v) || !v.includes(val))) return false;
       }
     } else {
       if (val !== cond) return false;
@@ -67,6 +66,19 @@ function applyUpdate(oldDoc, update) {
   }
   return doc;
 }
+function extractIndexQuery(query) {
+  for (const key of Object.keys(query)) {
+    const cond = query[key];
+    if (key === "_id") continue;
+    if (!cond || typeof cond !== "object" || Array.isArray(cond)) {
+      return { field: key, value: cond };
+    }
+    if ("$eq" in cond) {
+      return { field: key, value: cond.$eq };
+    }
+  }
+  return null;
+}
 
 // src/core/collection.ts
 import { v4 as uuid } from "uuid";
@@ -150,11 +162,20 @@ var Collection = class {
   db;
   queue = Promise.resolve();
   schema;
+  indexes = /* @__PURE__ */ new Map();
   constructor(dir, schema) {
     this.dir = dir;
     this.db = new ClassicLevel(dir, { valueEncoding: "utf8" });
     this.schema = schema;
   }
+  /* ---------------------- INDEX MANAGEMENT ---------------------- */
+  registerIndex(index) {
+    this.indexes.set(index.field, index);
+  }
+  getIndex(field) {
+    return this.indexes.get(field);
+  }
+  /* -------------------------- CORE -------------------------- */
   setSchema(schema) {
     this.schema = schema;
   }
@@ -166,6 +187,12 @@ var Collection = class {
     return this.queue;
   }
   async close() {
+    for (const idx of this.indexes.values()) {
+      try {
+        await idx.close();
+      } catch {
+      }
+    }
     try {
       await this.db.close();
     } catch {
@@ -195,6 +222,7 @@ var Collection = class {
         throw new Error(`Unknown operation: ${op}`);
     }
   }
+  /* --------------------- PUBLIC API --------------------- */
   insertOne(doc) {
     return this._enqueue(() => this._exec("insertOne", [doc]));
   }
@@ -232,11 +260,18 @@ var Collection = class {
       () => this._exec("countDocuments", [filter])
     );
   }
+  /* ------------------ INDEX HOOK ------------------ */
+  async _updateIndexes(oldDoc, newDoc) {
+    for (const index of this.indexes.values()) {
+      await index.update(oldDoc, newDoc);
+    }
+  }
   /* ---------------- Storage ---------------- */
   async _insertOne(doc) {
     const _id = doc._id ?? uuid();
     const final = this.validate({ _id, ...doc });
     await this.db.put(String(_id), encryptData(final));
+    await this._updateIndexes(null, final);
     return final;
   }
   async _insertMany(docs) {
@@ -245,10 +280,17 @@ var Collection = class {
     for (const d of docs) {
       const _id = d._id ?? uuid();
       const final = this.validate({ _id, ...d });
-      batch.push({ type: "put", key: String(_id), value: encryptData(final) });
+      batch.push({
+        type: "put",
+        key: String(_id),
+        value: encryptData(final)
+      });
       out.push(final);
     }
     await this.db.batch(batch);
+    for (const doc of out) {
+      await this._updateIndexes(null, doc);
+    }
     return out;
   }
   async _findOne(query) {
@@ -260,6 +302,17 @@ var Collection = class {
         return null;
       }
     }
+    const iq = extractIndexQuery(query);
+    if (iq && this.indexes.has(iq.field)) {
+      const ids = await this.indexes.get(iq.field).find(iq.value);
+      if (!ids.length) return null;
+      try {
+        const enc = await this.db.get(ids[0]);
+        return enc ? decryptData(enc) : null;
+      } catch {
+        return null;
+      }
+    }
     for await (const [, enc] of this.db.iterator()) {
       const v = decryptData(enc);
       if (matchDocument(v, query)) return v;
@@ -273,12 +326,17 @@ var Collection = class {
         const updated = this.validate(applyUpdate(value, update));
         updated._id = value._id;
         await this.db.put(key, encryptData(updated));
+        await this._updateIndexes(value, updated);
         return updated;
       }
     }
     if (options?.upsert) {
-      const doc = this.validate({ _id: uuid(), ...applyUpdate({}, update) });
+      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 null;
@@ -291,12 +349,26 @@ var Collection = class {
         const updated = this.validate(applyUpdate(value, update));
         updated._id = value._id;
         await this.db.put(key, encryptData(updated));
+        await this._updateIndexes(value, updated);
         out.push(updated);
       }
     }
     return out;
   }
   async _find(query) {
+    const iq = extractIndexQuery(query);
+    if (iq && this.indexes.has(iq.field)) {
+      const ids = await this.indexes.get(iq.field).find(iq.value);
+      const out2 = [];
+      for (const id of ids) {
+        try {
+          const enc = await this.db.get(id);
+          if (enc) out2.push(decryptData(enc));
+        } catch {
+        }
+      }
+      return out2;
+    }
     const out = [];
     for await (const [, enc] of this.db.iterator()) {
       const v = decryptData(enc);
@@ -306,8 +378,10 @@ var Collection = class {
   }
   async _deleteOne(filter) {
     for await (const [key, enc] of this.db.iterator()) {
-      if (matchDocument(decryptData(enc), filter)) {
+      const value = decryptData(enc);
+      if (matchDocument(value, filter)) {
         await this.db.del(key);
+        await this._updateIndexes(value, null);
         return true;
       }
     }
@@ -316,8 +390,10 @@ var Collection = class {
   async _deleteMany(filter) {
     let count = 0;
     for await (const [key, enc] of this.db.iterator()) {
-      if (matchDocument(decryptData(enc), filter)) {
+      const value = decryptData(enc);
+      if (matchDocument(value, filter)) {
         await this.db.del(key);
+        await this._updateIndexes(value, null);
         count++;
       }
     }
@@ -325,6 +401,10 @@ var Collection = class {
   }
   async _countDocuments(filter) {
     let c = 0;
+    const iq = extractIndexQuery(filter);
+    if (iq && this.indexes.has(iq.field)) {
+      return (await this.indexes.get(iq.field).find(iq.value)).length;
+    }
     for await (const [, enc] of this.db.iterator()) {
       if (matchDocument(decryptData(enc), filter)) c++;
     }
@@ -332,7 +412,115 @@ var Collection = class {
   }
 };
 
+// src/core/index.ts
+import path from "path";
+import fs from "fs";
+import { ClassicLevel as ClassicLevel2 } from "classic-level";
+var Index = class {
+  field;
+  unique;
+  dir;
+  db;
+  constructor(baseDir, field, options = {}) {
+    this.field = field;
+    this.unique = !!options.unique;
+    this.dir = path.join(baseDir, "__indexes", field + ".idx");
+    fs.mkdirSync(this.dir, { recursive: true });
+    this.db = new ClassicLevel2(this.dir, { valueEncoding: "utf8" });
+  }
+  /* ------------------------- INTERNAL ------------------------- */
+  normalizeKey(value) {
+    if (value === null || value === void 0) return "__null__";
+    if (typeof value === "object") {
+      return JSON.stringify(value);
+    }
+    return String(value);
+  }
+  async getRaw(key) {
+    try {
+      const v = await this.db.get(key);
+      if (v === void 0) return null;
+      return JSON.parse(v);
+    } catch {
+      return null;
+    }
+  }
+  async setRaw(key, value) {
+    await this.db.put(key, JSON.stringify(value));
+  }
+  async delRaw(key) {
+    try {
+      await this.db.del(key);
+    } catch {
+    }
+  }
+  /* --------------------------- API --------------------------- */
+  async insert(doc) {
+    const val = doc[this.field];
+    if (val === void 0) return;
+    const key = this.normalizeKey(val);
+    if (this.unique) {
+      const existing = await this.getRaw(key);
+      if (existing) {
+        throw new Error(
+          `Unique index violation on "${this.field}" = ${val}`
+        );
+      }
+      await this.setRaw(key, doc._id);
+      return;
+    }
+    const arr = await this.getRaw(key);
+    if (!arr) {
+      await this.setRaw(key, [doc._id]);
+    } else {
+      if (!arr.includes(doc._id)) {
+        arr.push(doc._id);
+        await this.setRaw(key, arr);
+      }
+    }
+  }
+  async delete(doc) {
+    const val = doc[this.field];
+    if (val === void 0) return;
+    const key = this.normalizeKey(val);
+    if (this.unique) {
+      await this.delRaw(key);
+      return;
+    }
+    const arr = await this.getRaw(key);
+    if (!arr) return;
+    const next = arr.filter((id) => id !== doc._id);
+    if (next.length === 0) {
+      await this.delRaw(key);
+    } else {
+      await this.setRaw(key, next);
+    }
+  }
+  async update(oldDoc, newDoc) {
+    const oldVal = oldDoc?.[this.field];
+    const newVal = newDoc?.[this.field];
+    if (oldVal === newVal) return;
+    if (oldDoc) await this.delete(oldDoc);
+    if (newDoc) await this.insert(newDoc);
+  }
+  async find(value) {
+    const key = this.normalizeKey(value);
+    const raw = await this.getRaw(key);
+    if (!raw) return [];
+    if (this.unique) return [raw];
+    return raw;
+  }
+  async close() {
+    try {
+      await this.db.close();
+    } catch {
+    }
+  }
+};
+
 // src/core/database.ts
+var META_FILE = "__db_meta.json";
+var META_VERSION = 1;
 var DBTransactionContext = class {
   constructor(db, txId) {
     this.db = db;
@@ -367,18 +555,39 @@ var LioranDB = class _LioranDB {
   manager;
   collections;
   walPath;
+  metaPath;
+  meta;
   static TX_SEQ = 0;
   constructor(basePath, dbName, manager) {
     this.basePath = basePath;
     this.dbName = dbName;
     this.manager = manager;
     this.collections = /* @__PURE__ */ new Map();
-    this.walPath = path.join(basePath, "__tx_wal.log");
-    fs.mkdirSync(basePath, { recursive: true });
+    this.walPath = path2.join(basePath, "__tx_wal.log");
+    this.metaPath = path2.join(basePath, META_FILE);
+    fs2.mkdirSync(basePath, { recursive: true });
+    this.loadMeta();
     this.recoverFromWAL().catch(console.error);
   }
+  /* ------------------------- META ------------------------- */
+  loadMeta() {
+    if (!fs2.existsSync(this.metaPath)) {
+      this.meta = { version: META_VERSION, indexes: {} };
+      this.saveMeta();
+      return;
+    }
+    try {
+      this.meta = JSON.parse(fs2.readFileSync(this.metaPath, "utf8"));
+    } catch {
+      throw new Error("Database metadata corrupted");
+    }
+  }
+  saveMeta() {
+    fs2.writeFileSync(this.metaPath, JSON.stringify(this.meta, null, 2));
+  }
+  /* ------------------------- WAL ------------------------- */
   async writeWAL(entries) {
-    const fd = await fs.promises.open(this.walPath, "a");
+    const fd = await fs2.promises.open(this.walPath, "a");
     for (const e of entries) {
       await fd.write(JSON.stringify(e) + "\n");
     }
@@ -387,13 +596,13 @@ var LioranDB = class _LioranDB {
   }
   async clearWAL() {
     try {
-      await fs.promises.unlink(this.walPath);
+      await fs2.promises.unlink(this.walPath);
     } catch {
     }
   }
   async recoverFromWAL() {
-    if (!fs.existsSync(this.walPath)) return;
-    const raw = await fs.promises.readFile(this.walPath, "utf8");
+    if (!fs2.existsSync(this.walPath)) return;
+    const raw = await fs2.promises.readFile(this.walPath, "utf8");
     const committed = /* @__PURE__ */ new Set();
     const applied = /* @__PURE__ */ new Set();
     const ops = /* @__PURE__ */ new Map();
@@ -424,18 +633,41 @@ var LioranDB = class _LioranDB {
       await collection._exec(op, args);
     }
   }
+  /* ------------------------- COLLECTION ------------------------- */
   collection(name, schema) {
     if (this.collections.has(name)) {
       const col2 = this.collections.get(name);
       if (schema) col2.setSchema(schema);
       return col2;
     }
-    const colPath = path.join(this.basePath, name);
-    fs.mkdirSync(colPath, { recursive: true });
+    const colPath = path2.join(this.basePath, name);
+    fs2.mkdirSync(colPath, { recursive: true });
     const col = new Collection(colPath, schema);
+    const metas = this.meta.indexes[name] ?? [];
+    for (const m of metas) {
+      col.registerIndex(new Index(colPath, m.field, m.options));
+    }
     this.collections.set(name, col);
     return col;
   }
+  /* ------------------------- INDEX API ------------------------- */
+  async createIndex(collection, field, options = {}) {
+    const col = this.collection(collection);
+    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);
+    }
+    col.registerIndex(index);
+    if (!this.meta.indexes[collection]) {
+      this.meta.indexes[collection] = [];
+    }
+    this.meta.indexes[collection].push({ field, options });
+    this.saveMeta();
+  }
+  /* ------------------------- TX API ------------------------- */
   async transaction(fn) {
     const txId = ++_LioranDB.TX_SEQ;
     const tx = new DBTransactionContext(this, txId);
@@ -443,6 +675,7 @@ var LioranDB = class _LioranDB {
     await tx.commit();
     return result;
   }
+  /* ------------------------- SHUTDOWN ------------------------- */
   async close() {
     for (const col of this.collections.values()) {
       try {
@@ -456,15 +689,15 @@ var LioranDB = class _LioranDB {
 
 // src/utils/rootpath.ts
 import os2 from "os";
-import path2 from "path";
-import fs2 from "fs";
+import path3 from "path";
+import fs3 from "fs";
 function getDefaultRootPath() {
   let dbPath = process.env.LIORANDB_PATH;
   if (!dbPath) {
     const homeDir = os2.homedir();
-    dbPath = path2.join(homeDir, "LioranDB", "db");
-    if (!fs2.existsSync(dbPath)) {
-      fs2.mkdirSync(dbPath, { recursive: true });
+    dbPath = path3.join(homeDir, "LioranDB", "db");
+    if (!fs3.existsSync(dbPath)) {
+      fs3.mkdirSync(dbPath, { recursive: true });
     }
     process.env.LIORANDB_PATH = dbPath;
   }
@@ -479,24 +712,24 @@ import net from "net";
 
 // src/ipc/socketPath.ts
 import os3 from "os";
-import path3 from "path";
+import path4 from "path";
 function getIPCSocketPath(rootPath) {
   if (os3.platform() === "win32") {
     return `\\\\.\\pipe\\liorandb_${rootPath.replace(/[:\\\/]/g, "_")}`;
   }
-  return path3.join(rootPath, ".lioran.sock");
+  return path4.join(rootPath, ".lioran.sock");
 }
 
 // src/ipc/client.ts
 function delay(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
-async function connectWithRetry(path5) {
+async function connectWithRetry(path6) {
   let attempt = 0;
   while (true) {
     try {
       return await new Promise((resolve, reject) => {
-        const socket = net.connect(path5, () => resolve(socket));
+        const socket = net.connect(path6, () => resolve(socket));
         socket.once("error", reject);
       });
     } catch (err) {
@@ -580,7 +813,7 @@ var dbQueue = new DBQueue();
 
 // src/ipc/server.ts
 import net2 from "net";
-import fs3 from "fs";
+import fs4 from "fs";
 var IPCServer = class {
   server;
   manager;
@@ -591,7 +824,7 @@ var IPCServer = class {
   }
   start() {
     if (!this.socketPath.startsWith("\\\\.\\")) {
-      if (fs3.existsSync(this.socketPath)) fs3.unlinkSync(this.socketPath);
+      if (fs4.existsSync(this.socketPath)) fs4.unlinkSync(this.socketPath);
     }
     this.server = net2.createServer((socket) => {
       let buffer = "";
@@ -641,7 +874,7 @@ var IPCServer = class {
     if (this.server) this.server.close();
     if (!this.socketPath.startsWith("\\\\.\\")) {
       try {
-        fs3.unlinkSync(this.socketPath);
+        fs4.unlinkSync(this.socketPath);
       } catch {
       }
     }
@@ -659,8 +892,8 @@ var LioranManager = class {
   constructor(options = {}) {
     const { rootPath, encryptionKey } = options;
     this.rootPath = rootPath || getDefaultRootPath();
-    if (!fs4.existsSync(this.rootPath)) {
-      fs4.mkdirSync(this.rootPath, { recursive: true });
+    if (!fs5.existsSync(this.rootPath)) {
+      fs5.mkdirSync(this.rootPath, { recursive: true });
     }
     if (encryptionKey) {
       setEncryptionKey(encryptionKey);
@@ -682,18 +915,18 @@ var LioranManager = class {
     }
   }
   tryAcquireLock() {
-    const lockPath = path4.join(this.rootPath, ".lioran.lock");
+    const lockPath = path5.join(this.rootPath, ".lioran.lock");
     try {
-      this.lockFd = fs4.openSync(lockPath, "wx");
-      fs4.writeSync(this.lockFd, String(process2.pid));
+      this.lockFd = fs5.openSync(lockPath, "wx");
+      fs5.writeSync(this.lockFd, String(process2.pid));
       return true;
     } catch {
       try {
-        const pid = Number(fs4.readFileSync(lockPath, "utf8"));
+        const pid = Number(fs5.readFileSync(lockPath, "utf8"));
         if (!this.isProcessAlive(pid)) {
-          fs4.unlinkSync(lockPath);
-          this.lockFd = fs4.openSync(lockPath, "wx");
-          fs4.writeSync(this.lockFd, String(process2.pid));
+          fs5.unlinkSync(lockPath);
+          this.lockFd = fs5.openSync(lockPath, "wx");
+          fs5.writeSync(this.lockFd, String(process2.pid));
           return true;
         }
       } catch {
@@ -713,8 +946,8 @@ var LioranManager = class {
     if (this.openDBs.has(name)) {
       return this.openDBs.get(name);
     }
-    const dbPath = path4.join(this.rootPath, name);
-    await fs4.promises.mkdir(dbPath, { recursive: true });
+    const dbPath = path5.join(this.rootPath, name);
+    await fs5.promises.mkdir(dbPath, { recursive: true });
     const db = new LioranDB(dbPath, name, this);
     this.openDBs.set(name, db);
     return db;
@@ -734,8 +967,8 @@ var LioranManager = class {
     }
     this.openDBs.clear();
     try {
-      if (this.lockFd) fs4.closeSync(this.lockFd);
-      fs4.unlinkSync(path4.join(this.rootPath, ".lioran.lock"));
+      if (this.lockFd) fs5.closeSync(this.lockFd);
+      fs5.unlinkSync(path5.join(this.rootPath, ".lioran.lock"));
     } catch {
     }
     await this.ipcServer?.close();

package/package.json

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