TypeScript-first JSON database

OctaveDB

A simple, TypeScript-first JSON file database for local development and prototyping

npm install octavedb
✨ Zero config•🔒 Type-safe•📦 Lightweight

Important: When to use this

✅ Good for:

  • • Local development & prototyping
  • • CLI tools & desktop apps
  • • Demo projects & tutorials
  • • Single-user applications

❌ Not for:

  • • Production web applications
  • • Multi-user environments
  • • Sensitive data (no encryption)
  • • High-concurrency scenarios

Why OctaveDB?

Zero Configuration

No database server to install or configure. Just create a JSON file and start building. Perfect for getting started quickly without infrastructure overhead.

TypeScript-First

Built with TypeScript generics for full type safety. Get autocomplete, type checking, and catch errors at compile time instead of runtime.

Easy to Debug

It's just JSON! Open the file in any text editor to see exactly what's stored. No need for database clients or query tools to inspect your data.

Lightweight & Reliable

Minimal dependencies keep your bundle small. Atomic file writes prevent data corruption if your app crashes during a write operation.

Quick Start

1

Define your types

// types.ts
import { Resource } from 'octavedb';

export interface User extends Resource {
  username: string;
  email: string;
}

export interface Post extends Resource {
  title: string;
  content: string;
  userId: User['id'];
}

export interface Database {
  users: User[];
  posts: Post[];
}
2

Create a JSON file

// database.json
{
  "users": [],
  "posts": []
}
3

Initialize the client

// lib/db.ts
import { createClient } from 'octavedb';
import type { Database } from './types';

export const db = createClient<Database>('./database.json');

// Also export the helpers for convenience
export { makeResource, makeDateTime, makeId } from 'octavedb';
4

Start building!

import { db, makeResource, makeDateTime } from './lib/db';
import type { User } from './types';

// CREATE
function createUser(username: string, email: string) {
  const user = makeResource<User>({ username, email });
  const data = db.read();

  data.users.push(user);
  db.write(data);

  return user;
}

// READ
function getUser(id: string) {
  const data = db.read();
  return data.users.find(u => u.id === id);
}

// UPDATE
function updateUser(id: string, email: string) {
  const data = db.read();
  const index = data.users.findIndex(u => u.id === id);

  if (index < 0) throw new Error('User not found');

  data.users[index] = { ...data.users[index], email, updatedAt: makeDateTime() };
  db.write(data);

  return data.users[index];
}

// DELETE
function deleteUser(id: string) {
  const data = db.read();
  const index = data.users.findIndex(u => u.id === id);

  if (index < 0) throw new Error('User not found');

  const deleted = data.users.splice(index, 1)[0];

  db.write(data);

  return deleted;
}

API Reference

createClient<Database>(filePath)

Creates a database client for the specified JSON file.

const db = createClient<Database>('./database.json');

db.read()

Reads and returns the entire database.

const data = db.read();

db.write(data)

Writes data to the database file atomically.

db.write(data);

makeResource<T>(data)

Creates a new resource with automatic id, createdAt, and updatedAt fields.

const user = makeResource<User>({ username: 'johndoe' });

makeId() / makeDateTime()

Helper functions for generating UUIDs and ISO timestamps.