db-faker

A lightweight, MongoDB-like local JSON database for Node.js and TypeScript applications.

db-faker lets you work with local collections using a simple API:

const users = await db.collection<User>("users");

await users.insert({
  name: "John",
  age: 25
});

const usersList = (await users.find()).all();

Features

• Local JSON-based storage
• MongoDB-style collections
• TypeScript support
• Generic, type-safe collections
• Automatic document IDs
• Async CRUD API
• Separate data for each collection
• No external database server required

Installation

npm install db-faker

Usage

import { DB } from "db-faker";

interface User {
  name: string;
  age: number;
}

const db = new DB("database");

const users = await db.collection<User>("users");

await users.insert({
  name: "John",
  age: 25
});

const result = (await users.find()).first();

console.log(result);

Collections

Create or access a collection using db.collection():

const users = await db.collection<User>("users");

const products = await db.collection<Product>("products");

Each collection maintains its own documents.

Insert

await users.insert({
  name: "John",
  age: 25
});

A document ID can be generated automatically.

Example stored document:

{
  "name": "John",
  "age": 25,
  "id": "users__07cf55ab-2186-458f-b231-c7f678ea68c5",
  "createdAt": 1790527401103,
  "updatedAt": 1790527401103
}

Find

Get all documents:

const users = (await usersCollection.find()).all();

Example:

const usersCollection = await db.collection<User>("users");

const users = (await usersCollection.find()).all();

console.log(users);

TypeScript

Collections can be strongly typed using generics:

interface User {
  name: string;
  age: number;
}

const users = await db.collection<User>("users");

TypeScript will validate inserted documents:

await users.insert({
  name: "John",
  age: 25
});

For example, this will produce a TypeScript error:

await users.insert({
  name: "John",
  age: "25"
});

because age is defined as a number.

Data Storage

Collections are stored locally as JSON files.

For example:

database/
├── users.json
├── products.json
└── orders.json

The database does not require MongoDB, MySQL, PostgreSQL, or another external database server.

API

DB

Create a database:

const db = new DB("database");

db.collection<T>(name)

Get a collection:

const users = db.collection<User>("users");

collection.insert(document)

Insert a document:

await users.insert({
  name: "John",
  age: 25
});

collection.find()

Retrieve documents:

const result = (await users.find()).all();

Example Project

import { DB } from "db-faker";

interface User {
  name: string;
  age: number;
}

const db = new DB("database");

const users = await db.collection<User>("users");

await users.insert({
  name: "John",
  age: 25
});

await users.insert({
  name: "Ali",
  age: 30
});

const result = (await users.find()).all();

console.log(result);

Why db-faker?

db-faker is useful for:

• Prototyping applications
• Learning database concepts
• Local development
• Testing
• Small applications
• Mocking database functionality
• Projects where a full database server is unnecessary

License

MIT