ChronoDB

> ChronoDB is a local-first, file-based TypeScript database engine with schema validation, indexing, transactions, and snapshot-based versioning designed for simplicity, predictability, and offline-first applications.

ChronoDB stores data as plain JSON files, adds strong schema guarantees, and tracks changes through snapshots that can later be synced to the cloud (cloud sync is not fully integrated yet).

---

✨ Key Features

* 📁 File-based storage (JSON)
* 🧩 Schema validation (primitive, enum, defaults, custom validators)
* 🔐 Strict mode (reject unknown fields)
* 🆔 Auto-generated IDs
* ⏱ createdAt / updatedAt timestamps
* 🔍 Indexed fields for faster lookups
* 📦 Collections API (CRUD)
* 🔁 Transactions with rollback
* 🕒 Automatic & manual snapshots
* ☁️ Optional cloud sync (not fully integrated yet)
* 🧠 Type-safe (TypeScript-first)

---

📦 Installation

``
npm install chronodb
`

or

`
yarn add chronodb
`

---

🚀 Quick Start

`
import ChronoDB from "chronodb";

const db = await ChronoDB.open({ cloudSync: false });

const users = db.col("users", {
schema: {
name: {
type: "string",
important: true,
},
email: {
type: "string",
distinct: true,
},
role: {
type: "enum",
values: ["admin", "user"],
default: "user",
},
age: "number"
}
});
`

---

📂 Storage Structure

ChronoDB stores everything as files:

`
data/
├─ users.json
├─ users.json.index.json
├─ .__state.json
└─ .snapshots/
└─ meta.json
`

* collection.json → actual documents
* .index.json → auto-generated indexes
* .snapshots/meta.json → snapshot history
* .__state.json → transaction state backup

---

🧱 Collections

A collection represents a single JSON-backed dataset.

`
const users = db.col("users");
`

$3

`
const posts = db.col("posts", {
schema: {
title: "string",
published: "boolean",
views: { type: "number", default: 0 },
},
indexes: ["published"],
});
`

---

📐 Schema System

ChronoDB enforces schemas at write-time.

$3

`
{
name: "string",
age: "number"
}
`

$3

`
{
email: {
type: "string",
distinct: true,
validate: v => v.includes("@")
}
}
`

$3

`
{
status: {
type: "enum",
values: ["draft", "published"]
}
}
`

$3

| Rule | Description |
| ----------- | ---------------- |
| type | Field type |
| important | Required field |
| distinct | Must be unique |
| nullable | Allow null |
| default | Default value |
| validate | Custom validator |

> In strict mode, unknown fields are rejected.

---

🆕 Creating Documents

$3

`
const user = await users.add({
name: "Alice",
email: "alice@mail.com",
});
`

Automatically adds:

`
{
id,
createdAt,
updatedAt
}
`

$3

`
await users.addMany([
{ name: "Bob", email: "bob@mail.com" },
{ name: "Jane", email: "jane@mail.com" },
]);
`

Validation is done atomically across the batch.

---

📖 Reading Data

$3

`
await users.getAll();
`

$3

`
await users.getOne({ email: "alice@mail.com" });
`

$3

`
await users.getMany({ role: "admin" });
`

---

✏️ Updating

$3

`
await users.updateById(id, {
name: "Alice Updated"
});
`

$3

`
await users.updateMany({ role: "guest" }, {
role: "user"
});
`

* Schema is revalidated
* updatedAt is refreshed for all matching documents
* Distinct fields are respected
* Supports updating multiple documents at once

---

🗑 Deleting

$3

`
await users.deleteById(id);
`

$3

`
await users.deleteMany({ role: "guest" });
`

$3

`
await users.deleteAll();
`

---

🔍 Indexing

Indexes are automatically rebuilt on write.

`
db.col("users", {
indexes: ["email", "role"]
});
`

Indexes are stored in:

`
users.json.index.json
`

> Indexing is transparent and requires no manual queries.

---

🔁 Transactions

ChronoDB supports safe transactions with rollback.

`
await db.transaction(async () => {
await users.add({ name: "A", email: "a@mail.com" });
await users.add({ name: "B", email: "a@mail.com" }); // ❌ duplicate
});
`

If any error occurs:

* State is restored
* No partial writes remain

---

🕒 Snapshots (Versioning)

ChronoDB tracks changes using snapshots.

$3

* On every data change
* On manual trigger
* On time intervals

$3

`
{
snapshotId: string;
timestamp: number;
version: number;
reason: "change" | "interval" | "manual";
}
`

$3

`
await db.snapshots.list();
`

$3

`
await db.snapshots.delete(snapshotId);
`

$3

`
await db.snapshots.deleteAll();
`

$3

`
await db.snapshots.setInterval(60000); // every 1 min
`

> Snapshots are metadata-first and designed to power restore & future cloud sync.

---

☁️ Cloud Sync (Optional, Not Fully Integrated)

ChronoDB supports pluggable cloud sync, but the feature is still in progress.

`
new ChronoDB("./data", {
cloudSync: true
});
`

* Snapshots are planned to be synced, not raw files
* Cloud logic is abstracted via CloudSync
* Authentication & providers are user-defined

> Currently, cloud sync is not fully functional.

---

🧠 Philosophy

ChronoDB is built around:

* Predictability over magic
* Local-first by default
* Explicit schemas
* Durable writes
* Offline-safe design
* Composable cloud sync

It is ideal for:

* Desktop apps
* CLI tools
* Embedded databases
* Offline-first apps
* Developer tooling

---

🛠 Roadmap (Planned)

* Snapshot restore / rewind
* Differential snapshot storage
* Conflict resolution strategies
* Cloud providers (S3, Firebase, custom APIs)
* Query operators ($gt, $in, $or`)
* Read-only replicas

---

📜 License

MIT © You