ChronoDB: Local-first TypeScript database with snapshots and optional cloud sync (cloud sync not fully implemented yet)
npm install chronodb
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`)