@liorandb/core 1.0.7 → 1.0.8

package/LICENSE.md

@@ -1,4 +1,4 @@
-LIORANDB LICENSE
+LDEP LICENSE
 
 Copyright (c) 2025 Swaraj Puppalwar
 All rights reserved.

package/README.md

@@ -1,27 +1,34 @@
 # @liorandb/core
 
-**LioranDB Core Module** – Lightweight, local-first, peer-to-peer database management for Node.js.
+**LioranDB Core** is a lightweight, encrypted, TypeScript-first embedded database engine 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.
+Think of it as:
 
----
+* ⚡ **LevelDB speed** (powered by `classic-level`)
+* 🔐 **Built-in encryption** (transparent at rest)
+* 🧠 **Mongo-like API** (collections, queries, updates)
+* 📦 **Zero external services** (no server, no daemon)
+* 🧩 **Type-safe by design** (written 100% in TypeScript)
+
+Perfect for:
+
+* Local-first apps
+* Desktop / CLI tools
+* Edge & serverless experiments
+* P2P & offline-sync systems
 
-## Table of Contents
+---
 
-* [Installation](#installation)
-* [Overview](#overview)
-* [Getting Started](#getting-started)
-* [API Reference](#api-reference)
+## Features
 
-  * [LioranManager](#lioranmanager)
-  * [LioranDB](#liorandb)
-  * [Collection](#collection)
-  * [Query Operators](#query-operators)
-  * [Update Operators](#update-operators)
-  * [Utilities](#utilities)
-* [Encryption](#encryption)
-* [Environment Setup](#environment-setup)
-* [License](#license)
+* 📂 Multiple databases under one manager
+* 📁 Multiple collections per database
+* 🔑 Optional encryption (AES-based, transparent)
+* 🧵 Write-queue for consistency (no race conditions)
+* 🧠 Simple query matching
+* 🧩 Strong TypeScript inference
+* 🚫 No native bindings
+* 🚀 Fast startup & low memory
 
 ---
 
@@ -31,194 +38,210 @@ This is the **core system-level module** of LioranDB. It provides foundational d
 npm install @liorandb/core
 ```
 
-> Node.js v18+ recommended.
-
 ---
 
-## Overview
+## Quick Start (30 seconds)
 
-`@liorandb/core` provides:
+```ts
+import { LioranManager } from "@liorandb/core"
 
-* 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.
+const manager = new LioranManager({
+  encryptionKey: "my-secret-key"
+})
 
-This module is intended for **Node.js projects** and can serve as the core database engine for larger LioranDB systems.
+const db = await manager.db("app")
 
----
+const users = db.collection<{ name: string; age: number }>("users")
 
-## Getting Started
+await users.insertOne({ name: "Swaraj", age: 17 })
 
-```javascript
-import { LioranManager } from "@liorandb/core";
+const result = await users.find({ name: "Swaraj" })
+console.log(result)
+```
 
-async function main() {
-  const manager = new LioranManager();
-  const db = await manager.db("myDatabase");
+No config. No server. Just code.
 
-  const users = db.collection("users");
+---
 
-  // Insert a document
-  const user = await users.insertOne({ name: "Alice", age: 25 });
+## Core Concepts
 
-  // Query documents
-  const results = await users.find({ age: { $gte: 18 } });
+### 1️⃣ LioranManager
 
-  console.log(results);
-}
+The **root controller**. Manages databases, encryption and lifecycle.
 
-main();
+```ts
+const manager = new LioranManager({
+  rootPath: "./data",        // optional
+  encryptionKey: "secret"   // optional
+})
 ```
 
----
+Responsibilities:
 
-## API Reference
+* Creates databases
+* Opens databases
+* Tracks open instances
+* Applies encryption globally
 
-### LioranManager
+---
 
-Manages databases and provides MongoDB-style client access.
+### 2️⃣ Database
+
+Each database is a **folder on disk**.
 
 ```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[]>;
-}
+const db = await manager.db("mydb")
 ```
 
-**Example:**
+* Databases are created automatically if missing
+* Re-opening returns the same instance
 
-```javascript
-const manager = new LioranManager();
-await manager.createDatabase("testDB");
-const db = await manager.db("testDB");
-```
+---
 
-### LioranDB
+### 3️⃣ Collections
 
-Represents a single database instance with multiple collections.
+Collections are **LevelDB instances** stored inside the database.
 
 ```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[]>;
-}
+const posts = db.collection<{ title: string; views: number }>("posts")
 ```
 
-**Example:**
+* One folder per collection
+* Fully typed
+* JSON documents only
+
+---
+
+## Collection API
 
-```javascript
-const users = db.collection("users");
-await db.createCollection("products");
-const collections = await db.listCollections();
+### insertOne
+
+```ts
+await users.insertOne({ name: "Alex", age: 22 })
 ```
 
-### Collection
+* Auto-generates `_id`
+* `_id` can be provided manually
 
-Handles documents within a database.
+---
+
+### find
 
 ```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>;
-}
+const all = await users.find()
+const adults = await users.find({ age: 18 })
 ```
 
-**Example:**
+* Partial object matching
+* Returns an array
 
-```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" });
+---
+
+### updateOne
+
+```ts
+await users.updateOne(
+  { name: "Alex" },
+  { $set: { age: 23 } }
+)
 ```
 
-### Query Operators
+Supported operators:
 
-* `$gt`, `$gte`, `$lt`, `$lte`, `$ne`, `$eq`, `$in`
+* `$set`
+* `$unset`
+* `$inc`
 
-**Example:**
+---
+
+## Encryption
 
-```javascript
-users.find({ age: { $gte: 18, $lt: 65 } });
+Encryption is **transparent and automatic**.
+
+```ts
+const manager = new LioranManager({
+  encryptionKey: process.env.DB_KEY
+})
 ```
 
-### Update Operators
+* Data is encrypted before writing to disk
+* Decrypted automatically on read
+* Wrong key = unreadable data
 
-* `$set` – set field values
-* `$inc` – increment numeric fields
+> Encryption is global per manager instance.
 
-**Example:**
+---
 
-```javascript
-users.updateOne({ name: "Alice" }, { $set: { city: "Mumbai" }, $inc: { age: 1 } });
+## File Structure on Disk
+
+```
+rootPath/
+└─ app/
+   ├─ users/
+   ├─ posts/
+   └─ comments/
 ```
 
-### Utilities
+* Human-readable folders
+* Binary LevelDB data inside
+
+---
+
+## Type Safety
+
+LioranDB is **TypeScript-native**.
 
 ```ts
-function getBaseDBFolder(): string;
+const users = db.collection<{ name: string; age: number }>("users")
+
+users.insertOne({ name: "Sam" })      // ❌ age missing
+users.insertOne({ name: "Sam", age: 20 }) // ✅
 ```
 
-Returns the root folder for LioranDB databases. Automatically sets environment variables if missing.
+No `any`. No runtime guessing.
 
 ---
 
-## Encryption
+## Closing Databases
 
-All documents are encrypted using **AES-256-GCM**.
+```ts
+await manager.closeDatabase("app")
+```
 
-* Uses a master key stored in `.secureKey` within the base folder.
-* Data is encrypted automatically before storage and decrypted on retrieval.
+* Closes all collections
+* Flushes LevelDB handles
 
-**Utility Functions:**
+---
 
-* `encryptData(obj)`
-* `decryptData(encStr)`
+## Design Philosophy
 
-**Master Key Management:**
+* **Simple > clever**
+* **Local-first**
+* **No magic network calls**
+* **Readable source > black box**
 
-* Managed via `getMasterKey()`
-* Auto-generates 256-bit key if not found.
+LioranDB is intentionally small and hackable.
 
 ---
 
-## Environment Setup
+## Roadmap
 
-* `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.
+* 🔁 P2P sync layer
+* 🧠 Indexing
+* 🧾 Schema validation
+* ⚡ WAL (write-ahead log)
+* 🌐 Browser storage adapter
 
 ---
 
 ## License
 
-**Author:** Swaraj Puppalwar
-**License:** LIORANDB LICENSE
+LDEP
 
 ---
 
-**Keywords:** p2p-database, lioran, liorandb, p2p-db, peer-to-peer-db, peer-to-peer-database, localfirst-db, localfirst-database
+## Author
+
+Built by **Swaraj Puppalwar** 🚀
+
+> If you are building local-first or offline-first systems — this DB is for you.

package/package.json

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