@liorandb/core 1.0.0

package/LICENSE.md

@@ -0,0 +1,41 @@
+LIORANDB LICENSE
+
+Copyright (c) 2025 Swaraj Puppalwar
+All rights reserved.
+
+Permission is hereby granted to any person obtaining a copy of this software and associated documentation files (the "Software") to use, copy, modify, and distribute the Software for PERSONAL, NON-COMMERCIAL PURPOSES ONLY, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHOR OR COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+---
+
+SPECIAL CONDITIONS FOR LIORANDB
+
+Notwithstanding the general permission above, the following additional conditions apply specifically to LioranDB:
+
+1. Personal Use
+   Permission is granted to use the Software for personal projects, educational purposes, experimentation, and non-commercial development only.
+
+2. Commercial and Production Use
+   Any use of the Software for commercial purposes, including but not limited to:
+
+* deployment in production environments,
+* integration into paid products or services,
+* hosting for third parties,
+* resale or monetization of any form,
+
+is strictly prohibited without obtaining a separate commercial license from the official LioranDB SaaS platform or direct written authorization from Swaraj Puppalwar or Lioran Group.
+
+3. No Resale or Redistribution
+   You may not sell, sublicense, redistribute, or repackage the Software as a standalone product or as part of any commercial offering without explicit written permission and a valid commercial agreement.
+
+4. Ownership
+   All intellectual property rights in the Software, including but not limited to source code, architecture, brand identity, and system design, remain the exclusive property of Swaraj Puppalwar and Lioran Group.
+
+By using this Software, you agree to comply fully with this license and all associated conditions.
+
+This license supersedes and replaces any previous licensing terms related to LioranDB.
+
+© 2025 Swaraj Puppalwar & Lioran Group. All rights reserved.

package/README.md

@@ -0,0 +1,224 @@
+# @liorandb/core
+
+**LioranDB Core Module** – Lightweight, local-first, peer-to-peer database management for Node.js.
+
+This is the **core system-level module** of LioranDB. It provides foundational database management functionality, including collections, queries, updates, encryption, and environment setup. **Note:** This is not the final database product, but a core module designed to be used in larger systems.
+
+---
+
+## Table of Contents
+
+* [Installation](#installation)
+* [Overview](#overview)
+* [Getting Started](#getting-started)
+* [API Reference](#api-reference)
+
+  * [LioranManager](#lioranmanager)
+  * [LioranDB](#liorandb)
+  * [Collection](#collection)
+  * [Query Operators](#query-operators)
+  * [Update Operators](#update-operators)
+  * [Utilities](#utilities)
+* [Encryption](#encryption)
+* [Environment Setup](#environment-setup)
+* [License](#license)
+
+---
+
+## Installation
+
+```bash
+npm install @liorandb/core
+```
+
+> Node.js v18+ recommended.
+
+---
+
+## Overview
+
+`@liorandb/core` provides:
+
+* Local-first, file-based database directories.
+* MongoDB-style API (`db`, `collection`, `insertOne`, `find`, `updateOne`, etc.).
+* Peer-to-peer-friendly design.
+* Data encryption at rest.
+* Automatic environment configuration.
+* TypeScript typings for full developer support.
+
+This module is intended for **Node.js projects** and can serve as the core database engine for larger LioranDB systems.
+
+---
+
+## Getting Started
+
+```javascript
+import { LioranManager } from "@liorandb/core";
+
+async function main() {
+  const manager = new LioranManager();
+  const db = await manager.db("myDatabase");
+
+  const users = db.collection("users");
+
+  // Insert a document
+  const user = await users.insertOne({ name: "Alice", age: 25 });
+
+  // Query documents
+  const results = await users.find({ age: { $gte: 18 } });
+
+  console.log(results);
+}
+
+main();
+```
+
+---
+
+## API Reference
+
+### LioranManager
+
+Manages databases and provides MongoDB-style client access.
+
+```ts
+class LioranManager {
+  rootPath: string;
+  db(name: string): Promise<LioranDB>;
+  createDatabase(name: string): Promise<LioranDB>;
+  openDatabase(name: string): Promise<LioranDB>;
+  closeDatabase(name: string): Promise<void>;
+  renameDatabase(oldName: string, newName: string): Promise<boolean>;
+  deleteDatabase(name: string): Promise<boolean>;
+  dropDatabase(name: string): Promise<boolean>;
+  listDatabases(): Promise<string[]>;
+}
+```
+
+**Example:**
+
+```javascript
+const manager = new LioranManager();
+await manager.createDatabase("testDB");
+const db = await manager.db("testDB");
+```
+
+### LioranDB
+
+Represents a single database instance with multiple collections.
+
+```ts
+class LioranDB {
+  basePath: string;
+  dbName: string;
+  collection<T>(name: string): Collection<T>;
+  createCollection(name: string): Promise<boolean>;
+  deleteCollection(name: string): Promise<boolean>;
+  dropCollection(name: string): Promise<boolean>;
+  renameCollection(oldName: string, newName: string): Promise<boolean>;
+  listCollections(): Promise<string[]>;
+}
+```
+
+**Example:**
+
+```javascript
+const users = db.collection("users");
+await db.createCollection("products");
+const collections = await db.listCollections();
+```
+
+### Collection
+
+Handles documents within a database.
+
+```ts
+class Collection<T extends { _id?: string }> {
+  insertOne(doc: T): Promise<T>;
+  insertMany(docs: T[]): Promise<T[]>;
+  find(query?: FilterQuery<T>): Promise<T[]>;
+  findOne(query?: FilterQuery<T>): Promise<T | null>;
+  updateOne(filter: FilterQuery<T>, update: UpdateQuery<T>, options?: { upsert?: boolean }): Promise<T | null>;
+  updateMany(filter: FilterQuery<T>, update: UpdateQuery<T>): Promise<T[]>;
+  deleteOne(filter: FilterQuery<T>): Promise<boolean>;
+  deleteMany(filter: FilterQuery<T>): Promise<number>;
+  countDocuments(filter?: FilterQuery<T>): Promise<number>;
+  close(): Promise<void>;
+}
+```
+
+**Example:**
+
+```javascript
+await users.insertOne({ name: "Bob", age: 30 });
+const adults = await users.find({ age: { $gte: 18 } });
+await users.updateOne({ name: "Bob" }, { $inc: { age: 1 } });
+await users.deleteOne({ name: "Alice" });
+```
+
+### Query Operators
+
+* `$gt`, `$gte`, `$lt`, `$lte`, `$ne`, `$eq`, `$in`
+
+**Example:**
+
+```javascript
+users.find({ age: { $gte: 18, $lt: 65 } });
+```
+
+### Update Operators
+
+* `$set` – set field values
+* `$inc` – increment numeric fields
+
+**Example:**
+
+```javascript
+users.updateOne({ name: "Alice" }, { $set: { city: "Mumbai" }, $inc: { age: 1 } });
+```
+
+### Utilities
+
+```ts
+function getBaseDBFolder(): string;
+```
+
+Returns the root folder for LioranDB databases. Automatically sets environment variables if missing.
+
+---
+
+## Encryption
+
+All documents are encrypted using **AES-256-GCM**.
+
+* Uses a master key stored in `.secureKey` within the base folder.
+* Data is encrypted automatically before storage and decrypted on retrieval.
+
+**Utility Functions:**
+
+* `encryptData(obj)`
+* `decryptData(encStr)`
+
+**Master Key Management:**
+
+* Managed via `getMasterKey()`
+* Auto-generates 256-bit key if not found.
+
+---
+
+## Environment Setup
+
+* `getBaseDBFolder()` ensures `LIORANDB_PATH` is set.
+* Auto-generates scripts for **Windows PowerShell** or **Linux/macOS bash**.
+* Guides users to set system-wide environment variables if missing.
+
+---
+
+## License
+
+**Author:** Swaraj Puppalwar
+**License:** LIORANDB LICENSE
+
+---
+
+**Keywords:** p2p-database, lioran, liorandb, p2p-db, peer-to-peer-db, peer-to-peer-database, localfirst-db, localfirst-database

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@liorandb/core",
+  "version": "1.0.0",
+  "description": "LioranDB is a lightweight, local-first, peer-to-peer, file-based database with a MongoDB-style Node.js API and a simple CLI for seamless distributed development.",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "type": "module",
+  "scripts": {},
+  "bin": {},
+  "keywords": [
+    "p2p-database",
+    "lioran",
+    "liorandb",
+    "p2p-db",
+    "peer-to-peer-db",
+    "peer-to-peer-database",
+    "localfirst-db",
+    "localfirst-database"
+  ],
+  "author": "Swaraj Puppalwar",
+  "license": "LIORANDB LICENSE",
+  "dependencies": {
+    "classic-level": "^1.3.0",
+    "crypto": "^1.0.1",
+    "uuid": "^9.0.0"
+  }
+}

package/src/LioranManager.js

@@ -0,0 +1,120 @@
+import path from "path";
+import fs from "fs";
+import { LioranDB } from "./core/database.js";
+
+export class LioranManager {
+  constructor() {
+    this.rootPath = path.join(
+      process.env.LIORANDB_PATH ||
+        path.join(process.env.HOME || process.env.USERPROFILE),
+      "LioranDB",
+      "db"
+    );
+
+    if (!fs.existsSync(this.rootPath)) {
+      fs.mkdirSync(this.rootPath, { recursive: true });
+    }
+
+    this.openDBs = new Map();
+  }
+
+  // -----------------------------------------
+  // MongoDB-style: client.db("name")
+  // Auto-create database if not exists
+  // -----------------------------------------
+  async db(name) {
+    return this.openDatabase(name);
+  }
+
+  // -----------------------------------------
+  // Create a new database (returns db instance)
+  // -----------------------------------------
+  async createDatabase(name) {
+    const dbPath = path.join(this.rootPath, name);
+
+    if (fs.existsSync(dbPath)) {
+      throw new Error(`Database "${name}" already exists`);
+    }
+
+    await fs.promises.mkdir(dbPath, { recursive: true });
+    return this.openDatabase(name);
+  }
+
+  // -----------------------------------------
+  // Open DB - AUTO CREATE if missing
+  // -----------------------------------------
+  async openDatabase(name) {
+    const dbPath = path.join(this.rootPath, name);
+
+    // Auto-create if not exists
+    if (!fs.existsSync(dbPath)) {
+      await fs.promises.mkdir(dbPath, { recursive: true });
+    }
+
+    if (this.openDBs.has(name)) {
+      return this.openDBs.get(name);
+    }
+
+    const db = new LioranDB(dbPath, name, this);
+    this.openDBs.set(name, db);
+
+    return db;
+  }
+
+  // -----------------------------------------
+  // Close database
+  // -----------------------------------------
+  async closeDatabase(name) {
+    if (!this.openDBs.has(name)) return;
+
+    const db = this.openDBs.get(name);
+
+    for (const [, col] of db.collections.entries()) {
+      await col.close();
+    }
+
+    this.openDBs.delete(name);
+  }
+
+  // -----------------------------------------
+  // Rename database
+  // -----------------------------------------
+  async renameDatabase(oldName, newName) {
+    const oldPath = path.join(this.rootPath, oldName);
+    const newPath = path.join(this.rootPath, newName);
+
+    if (!fs.existsSync(oldPath)) throw new Error(`Database "${oldName}" not found`);
+    if (fs.existsSync(newPath)) throw new Error(`Database "${newName}" already exists`);
+
+    await this.closeDatabase(oldName);
+    await fs.promises.rename(oldPath, newPath);
+
+    return true;
+  }
+
+  // -----------------------------------------
+  // Delete / Drop database
+  // -----------------------------------------
+  async deleteDatabase(name) {
+    return this.dropDatabase(name);
+  }
+
+  async dropDatabase(name) {
+    const dbPath = path.join(this.rootPath, name);
+
+    if (!fs.existsSync(dbPath)) return false;
+
+    await this.closeDatabase(name);
+    await fs.promises.rm(dbPath, { recursive: true, force: true });
+
+    return true;
+  }
+
+  // -----------------------------------------
+  // List all databases
+  // -----------------------------------------
+  async listDatabases() {
+    const items = await fs.promises.readdir(this.rootPath, { withFileTypes: true });
+    return items.filter(i => i.isDirectory()).map(i => i.name);
+  }
+}

package/src/core/collection.js

@@ -0,0 +1,160 @@
+import { ClassicLevel } from "classic-level";
+import { matchDocument, applyUpdate } from "./query.js";
+import { v4 as uuid } from "uuid";
+import { encryptData, decryptData } from "../utils/encryption.js";
+
+export class Collection {
+  constructor(dir) {
+    this.dir = dir;
+    this.db = new ClassicLevel(dir, { valueEncoding: "json" });
+
+    // Queue system
+    this.queue = Promise.resolve(); // start with a resolved promise
+  }
+
+  // Queue wrapper
+  _enqueue(task) {
+    // Add task to the queue
+    this.queue = this.queue.then(() => task()).catch(console.error);
+    return this.queue;
+  }
+
+  async close() {
+    if (this.db) {
+      try {
+        await this.db.close();
+      } catch (err) {
+        console.warn("Warning: close() failed", err);
+      }
+    }
+  }
+
+  async insertOne(doc) {
+    return this._enqueue(async () => {
+      const _id = doc._id ?? uuid();
+      const final = { _id, ...doc };
+      const encrypted = encryptData(final);
+      await this.db.put(String(_id), encrypted);
+      return final;
+    });
+  }
+
+  async insertMany(docs = []) {
+    return this._enqueue(async () => {
+      const ops = [];
+      const out = [];
+
+      for (const d of docs) {
+        const _id = d._id ?? uuid();
+        const final = { _id, ...d };
+        const encrypted = encryptData(final);
+        ops.push({ type: "put", key: String(_id), value: encrypted });
+        out.push(final);
+      }
+
+      await this.db.batch(ops);
+      return out;
+    });
+  }
+
+  async find(query = {}) {
+    return this._enqueue(async () => {
+      const out = [];
+      for await (const [, encValue] of this.db.iterator()) {
+        const value = decryptData(encValue);
+        if (matchDocument(value, query)) out.push(value);
+      }
+      return out;
+    });
+  }
+
+  async findOne(query = {}) {
+    return this._enqueue(async () => {
+      for await (const [, encValue] of this.db.iterator()) {
+        const value = decryptData(encValue);
+        if (matchDocument(value, query)) return value;
+      }
+      return null;
+    });
+  }
+
+  async updateOne(filter = {}, update = {}, options = { upsert: false }) {
+    return this._enqueue(async () => {
+      for await (const [key, encValue] of this.db.iterator()) {
+        const value = decryptData(encValue);
+        if (matchDocument(value, filter)) {
+          const updated = applyUpdate(value, update);
+          updated._id = value._id;
+          const encrypted = encryptData(updated);
+          await this.db.put(key, encrypted);
+          return updated;
+        }
+      }
+
+      if (options.upsert) {
+        const newDoc = applyUpdate(filter, update);
+        newDoc._id = newDoc._id ?? uuid();
+        const encrypted = encryptData(newDoc);
+        await this.db.put(String(newDoc._id), encrypted);
+        return newDoc;
+      }
+
+      return null;
+    });
+  }
+
+  async updateMany(filter = {}, update = {}) {
+    return this._enqueue(async () => {
+      const updated = [];
+      for await (const [key, encValue] of this.db.iterator()) {
+        const value = decryptData(encValue);
+        if (matchDocument(value, filter)) {
+          const newDoc = applyUpdate(value, update);
+          newDoc._id = value._id;
+          const encrypted = encryptData(newDoc);
+          await this.db.put(key, encrypted);
+          updated.push(newDoc);
+        }
+      }
+      return updated;
+    });
+  }
+
+  async deleteOne(filter = {}) {
+    return this._enqueue(async () => {
+      for await (const [key, encValue] of this.db.iterator()) {
+        const value = decryptData(encValue);
+        if (matchDocument(value, filter)) {
+          await this.db.del(key);
+          return true;
+        }
+      }
+      return false;
+    });
+  }
+
+  async deleteMany(filter = {}) {
+    return this._enqueue(async () => {
+      let count = 0;
+      for await (const [key, encValue] of this.db.iterator()) {
+        const value = decryptData(encValue);
+        if (matchDocument(value, filter)) {
+          await this.db.del(key);
+          count++;
+        }
+      }
+      return count;
+    });
+  }
+
+  async countDocuments(filter = {}) {
+    return this._enqueue(async () => {
+      let c = 0;
+      for await (const [, encValue] of this.db.iterator()) {
+        const value = decryptData(encValue);
+        if (matchDocument(value, filter)) c++;
+      }
+      return c;
+    });
+  }
+}

package/src/core/database.js

@@ -0,0 +1,109 @@
+import path from "path";
+import fs from "fs";
+import { Collection } from "./collection.js";
+
+export class LioranDB {
+  constructor(basePath, dbName, manager) {
+    this.basePath = basePath;
+    this.dbName = dbName;
+    this.manager = manager;
+    this.collections = new Map();
+
+    if (!fs.existsSync(basePath)) {
+      fs.mkdirSync(basePath, { recursive: true });
+    }
+  }
+
+  /** Get or auto-create collection object */
+  collection(name) {
+    if (this.collections.has(name)) {
+      return this.collections.get(name);
+    }
+
+    const colPath = path.join(this.basePath, name);
+
+    // auto-create directory
+    if (!fs.existsSync(colPath)) {
+      fs.mkdirSync(colPath, { recursive: true });
+    }
+
+    const col = new Collection(colPath);
+    this.collections.set(name, col);
+    return col;
+  }
+
+  /** Create collection manually */
+  async createCollection(name) {
+    const colPath = path.join(this.basePath, name);
+
+    if (fs.existsSync(colPath)) {
+      throw new Error("Collection already exists");
+    }
+
+    // create folder
+    await fs.promises.mkdir(colPath, { recursive: true });
+
+    // load into memory map
+    const col = new Collection(colPath);
+    this.collections.set(name, col);
+
+    return true;
+  }
+
+  /** Delete collection fully */
+  async deleteCollection(name) {
+    const colPath = path.join(this.basePath, name);
+
+    if (!fs.existsSync(colPath)) {
+      throw new Error("Collection does not exist");
+    }
+
+    // close LevelDB instance if opened
+    if (this.collections.has(name)) {
+      const col = this.collections.get(name);
+      await col.close().catch(() => {});
+      await col.db.clear().catch(() => {});
+      this.collections.delete(name);
+    }
+
+    // force delete directory
+    await fs.promises.rm(colPath, { recursive: true, force: true });
+
+    return true;
+  }
+
+  /** Rename collection */
+  async renameCollection(oldName, newName) {
+    const oldPath = path.join(this.basePath, oldName);
+    const newPath = path.join(this.basePath, newName);
+
+    if (!fs.existsSync(oldPath)) throw new Error("Collection does not exist");
+    if (fs.existsSync(newPath)) throw new Error("New collection name exists");
+
+    if (this.collections.has(oldName)) {
+      await this.collections.get(oldName).close().catch(() => {});
+      this.collections.delete(oldName);
+    }
+
+    await fs.promises.rename(oldPath, newPath);
+
+    const newCol = new Collection(newPath);
+    this.collections.set(newName, newCol);
+
+    return true;
+  }
+
+  /** Drop a collection (alias deleteCollection) */
+  async dropCollection(name) {
+    return this.deleteCollection(name);
+  }
+
+  /** List all collections */
+  async listCollections() {
+    const dirs = await fs.promises.readdir(this.basePath, { withFileTypes: true });
+
+    return dirs
+      .filter(dirent => dirent.isDirectory())
+      .map(dirent => dirent.name);
+  }
+}

package/src/core/query.js

@@ -0,0 +1,65 @@
+function getByPath(obj, path) {
+  return path.split(".").reduce((o, p) => (o ? o[p] : undefined), obj);
+}
+
+export function matchDocument(doc, query) {
+  for (const key of Object.keys(query)) {
+    const cond = query[key];
+    const val = getByPath(doc, key);
+
+    if (cond && typeof cond === "object" && !Array.isArray(cond)) {
+      for (const op of Object.keys(cond)) {
+        const v = cond[op];
+        if (op === "$gt" && !(val > v)) return false;
+        if (op === "$gte" && !(val >= v)) return false;
+        if (op === "$lt" && !(val < v)) return false;
+        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;
+      }
+    } else {
+      if (val !== cond) return false;
+    }
+  }
+  return true;
+}
+
+export function applyUpdate(oldDoc, update) {
+  const doc = structuredClone(oldDoc);
+
+  // $set
+  if (update.$set) {
+    for (const k in update.$set) {
+      const parts = k.split(".");
+      let cur = doc;
+      for (let i = 0; i < parts.length - 1; i++) {
+        cur[parts[i]] = cur[parts[i]] ?? {};
+        cur = cur[parts[i]];
+      }
+      cur[parts.at(-1)] = update.$set[k];
+    }
+  }
+
+  // $inc
+  if (update.$inc) {
+    for (const k in update.$inc) {
+      const val = getByPath(doc, k) ?? 0;
+      const parts = k.split(".");
+      let cur = doc;
+      for (let i = 0; i < parts.length - 1; i++) {
+        cur[parts[i]] = cur[parts[i]] ?? {};
+        cur = cur[parts[i]];
+      }
+      cur[parts.at(-1)] = val + update.$inc[k];
+    }
+  }
+
+  // Direct merge (no operators)
+  const hasOp = Object.keys(update).some((k) => k.startsWith("$"));
+  if (!hasOp) {
+    return { ...doc, ...update };
+  }
+
+  return doc;
+}

package/src/index.d.ts

@@ -0,0 +1,123 @@
+// ================================================
+// @liorandb/core - Type Definitions
+// ================================================
+
+declare module "@liorandb/core" {
+  // --------------------------
+  // Generic Query Operators
+  // --------------------------
+
+  export interface QueryOperators<T> {
+    $gt?: T;
+    $gte?: T;
+    $lt?: T;
+    $lte?: T;
+    $ne?: T;
+    $in?: T[];
+  }
+
+  export type FilterQuery<T> = {
+    [K in keyof T]?: T[K] | QueryOperators<T[K]>;
+  };
+
+  // --------------------------
+  // Update Operators
+  // --------------------------
+
+  export interface UpdateSet<T> {
+    $set?: Partial<T>;
+  }
+
+  export interface UpdateInc<T> {
+    $inc?: {
+      [K in keyof T]?: number;
+    };
+  }
+
+  export type UpdateQuery<T> = Partial<T> | (UpdateSet<T> & UpdateInc<T>);
+
+  // --------------------------
+  // Collection Class
+  // --------------------------
+
+  export class Collection<T extends { _id?: string }> {
+    constructor(dir: string);
+
+    close(): Promise<void>;
+
+    insertOne(doc: T): Promise<T>;
+    insertMany(docs: T[]): Promise<T[]>;
+
+    find(query?: FilterQuery<T>): Promise<T[]>;
+    findOne(query?: FilterQuery<T>): Promise<T | null>;
+
+    updateOne(
+      filter: FilterQuery<T>,
+      update: UpdateQuery<T>,
+      options?: { upsert?: boolean }
+    ): Promise<T | null>;
+
+    updateMany(
+      filter: FilterQuery<T>,
+      update: UpdateQuery<T>
+    ): Promise<T[]>;
+
+    deleteOne(filter: FilterQuery<T>): Promise<boolean>;
+    deleteMany(filter: FilterQuery<T>): Promise<number>;
+
+    countDocuments(filter?: FilterQuery<T>): Promise<number>;
+  }
+
+  // --------------------------
+  // LioranDB: Database Instance
+  // --------------------------
+
+  export class LioranDB {
+    basePath: string;
+    dbName: string;
+
+    constructor(basePath: string, dbName: string, manager: LioranManager);
+
+    collection<T extends { _id?: string }>(name: string): Collection<T>;
+
+    createCollection(name: string): Promise<boolean>;
+    deleteCollection(name: string): Promise<boolean>;
+    dropCollection(name: string): Promise<boolean>;
+    renameCollection(oldName: string, newName: string): Promise<boolean>;
+
+    listCollections(): Promise<string[]>;
+  }
+
+  // --------------------------
+  // LioranManager
+  // --------------------------
+
+  export class LioranManager {
+    rootPath: string;
+
+    constructor();
+
+    // MongoDB-style
+    db(name: string): Promise<LioranDB>;
+
+    createDatabase(name: string): Promise<LioranDB>;
+    openDatabase(name: string): Promise<LioranDB>;
+    closeDatabase(name: string): Promise<void>;
+
+    renameDatabase(oldName: string, newName: string): Promise<boolean>;
+
+    deleteDatabase(name: string): Promise<boolean>;
+    dropDatabase(name: string): Promise<boolean>;
+
+    listDatabases(): Promise<string[]>;
+  }
+
+  // --------------------------
+  // Utils
+  // --------------------------
+
+  export function getBaseDBFolder(): string;
+
+  // Package exports
+  export { LioranManager, LioranDB, getBaseDBFolder };
+}

package/src/index.js

@@ -0,0 +1,4 @@
+// src/index.js
+export { LioranManager } from "./LioranManager.js";
+export { LioranDB } from "./core/database.js";
+export { getBaseDBFolder } from "./utils/rootpath.js";

package/src/utils/encryption.js

@@ -0,0 +1,30 @@
+import crypto from "crypto";
+import { getMasterKey } from "./secureKey.js";
+
+const algorithm = "aes-256-gcm";
+const key = Buffer.from(getMasterKey(), "hex");
+
+export function encryptData(plainObj) {
+  const iv = crypto.randomBytes(16); // random 16-byte IV
+  const data = Buffer.from(JSON.stringify(plainObj), "utf8");
+
+  const cipher = crypto.createCipheriv(algorithm, key, iv);
+  const encrypted = Buffer.concat([cipher.update(data), cipher.final()]);
+  const tag = cipher.getAuthTag();
+
+  // store as iv + tag + data, base64 encoded
+  return Buffer.concat([iv, tag, encrypted]).toString("base64");
+}
+
+export function decryptData(encStr) {
+  const buf = Buffer.from(encStr, "base64");
+  const iv = buf.slice(0, 16);
+  const tag = buf.slice(16, 32);
+  const encrypted = buf.slice(32);
+
+  const decipher = crypto.createDecipheriv(algorithm, key, iv);
+  decipher.setAuthTag(tag);
+
+  const decrypted = Buffer.concat([decipher.update(encrypted), decipher.final()]);
+  return JSON.parse(decrypted.toString("utf8"));
+}

package/src/utils/rootpath.js

@@ -0,0 +1,77 @@
+import os from "os";
+import path from "path";
+import fs from "fs";
+
+export function getBaseDBFolder() {
+  let dbPath = process.env.LIORANDB_PATH;
+
+  // If LIORANDB_PATH is NOT set system-wide
+  if (!dbPath) {
+    const homeDir = os.homedir();
+    dbPath = path.join(homeDir, "LioranDB");
+
+    // Ensure directory exists
+    if (!fs.existsSync(dbPath)) {
+      fs.mkdirSync(dbPath, { recursive: true });
+    }
+
+    // Set env var for current process
+    process.env.LIORANDB_PATH = dbPath;
+
+    // Create OS-specific installer scripts
+    createSystemEnvInstaller(dbPath);
+  }
+
+  return dbPath;
+}
+
+function createSystemEnvInstaller(dbPath) {
+  const platform = os.platform();
+  const scriptsDir = path.join(os.tmpdir(), "lioran_env_setup");
+
+  if (!fs.existsSync(scriptsDir)) {
+    fs.mkdirSync(scriptsDir, { recursive: true });
+  }
+
+  if (platform === "win32") {
+    const winScript = path.join(scriptsDir, "set-lioran-env.ps1");
+    fs.writeFileSync(
+      winScript,
+      `Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
+[System.Environment]::SetEnvironmentVariable("LIORANDB_PATH", "${dbPath}", "Machine")
+Write-Host "LIORANDB_PATH set system-wide to: ${dbPath}"`,
+      "utf8"
+    );
+
+    console.log(`
+⚠️ LIORANDB_PATH is not set system-wide.
+Run this PowerShell script as ADMIN:
+
+  ${winScript}
+`);
+  }
+
+  if (platform === "linux" || platform === "darwin") {
+    const bashScript = path.join(scriptsDir, "set-lioran-env.sh");
+    fs.writeFileSync(
+      bashScript,
+      `#!/bin/bash
+echo 'export LIORANDB_PATH="${dbPath}"' >> ~/.bashrc
+echo 'export LIORANDB_PATH="${dbPath}"' >> ~/.zshrc
+echo "LIORANDB_PATH set system-wide to: ${dbPath}"
+source ~/.bashrc 2>/dev/null
+source ~/.zshrc 2>/dev/null
+`,
+      "utf8"
+    );
+
+    fs.chmodSync(bashScript, 0o755);
+
+    console.log(`
+⚠️ LIORANDB_PATH is not set system-wide.
+Run this script:
+
+  bash ${bashScript}
+`);
+  }
+}

package/src/utils/secureKey.js

@@ -0,0 +1,18 @@
+import fs from "fs";
+import path from "path";
+import crypto from "crypto";
+import { getBaseDBFolder } from "./rootpath.js";
+
+const KEY_FILE = path.join(getBaseDBFolder(), ".secureKey");
+
+export function getMasterKey() {
+  if (!fs.existsSync(KEY_FILE)) {
+    // generate 32-byte random key (256-bit)
+    const key = crypto.randomBytes(32).toString("hex");
+    fs.writeFileSync(KEY_FILE, key, { encoding: "utf8", mode: 0o600 });
+    return key;
+  }
+
+  const key = fs.readFileSync(KEY_FILE, "utf8").trim();
+  return key;
+}