@beforesemicolon/node-json-db

Node JSON Database

A Simple file-based JSON database for Node

Table of Contents

• Install
• Start a Database
• CRUD
  • Insert Item
  • Get Item(s)
  • Update Item(s)
  • Delete Item(s)
• Drop Database
• Query API

Install

npm i @beforesemicolon/node-json-db

Start a Database

To start simply initialize database with the name of the JSON file you want. All the files will be placed at the root of your project inside the .json-db-data directory.

import {JSONDB} from '@beforesemicolon/node-json-db';

type ToDoStatus = "pending" | "completed" | "archived"

interface ToDo {
  name: string;
  status: ToDoStatus;
  user: {
    name: string;
  };
}

const db = new JSONDB<ToDo>("todo");

CRUD

The database supports all the basic CRUD operations.

Insert Item

await db.insert({
  id: crypto.randomUUID(),
  name: "Go To Gym",
  status: "pending",
  user: {
    name: "John Doe",
  },
});

Get Item(s)

const item = await db.getOne()
  .where("status").equals("pending")
  .run();

const item = await db.getAll()
  .where("status").equals("pending")
  .where("user.name").equals("John Doe")
  .run();

Update Item(s)

const item = await db.updateOne({
    status: "completed"
  })
  .where("status").equals("pending")
  .run();

const item = await db.updateAll({
    status: "archived"
  })
  .where("status").equals("pending")
  .where("user.name").equals("John Doe")
  .run();

Delete Item(s)

const item = await db.deleteOne()
    .where("status").equals("pending")
    .run();

const item = await db.deleteAll()
    .where("status").equals("pending")
    .where("user.name").equals("John Doe")
    .run();

Drop Database

Simply drop the database to delete the JSON file.

db.drop()

Query API

The query helps you narrow down your search to identify the item or items you want to perform an action on.

// examples of values
import { VALUE } from "@typescript-eslint/scope-manager/dist/lib/base-config";

KEY_OR_KEY_CHAIN = "user" | "user.name" | "list.0.value" // use dot notation to navigate down
// db actions
ACTION = "getOne" | "getAll" | "updateOne" | "updateAll" | "deleteOne" | "deleteAll";
// value types
VALUE = "Any valid JSON value"

ACTION
  .where(KEY_OR_KEY_CHAIN).equals(VALUE)
  .where(KEY_OR_KEY_CHAIN).notEqual(VALUE)
  .where(KEY_OR_KEY_CHAIN).in(Array<VALUE>)
  .where(KEY_OR_KEY_CHAIN).between([MIN_VALUE, MAX_VALUE])
  .where(KEY_OR_KEY_CHAIN).greaterThen(VALUE)
  .where(KEY_OR_KEY_CHAIN).greaterOrEqual(VALUE)
  .where(KEY_OR_KEY_CHAIN).lessThen(VALUE)
  .where(KEY_OR_KEY_CHAIN).lessOrEqual(VALUE)
  .where(KEY_OR_KEY_CHAIN).matches(STRING_OR_REGEX)
  .where(KEY_OR_KEY_CHAIN).contains(VALUE)
  .where(KEY_OR_KEY_CHAIN).isNull()
  .where(KEY_OR_KEY_CHAIN).isNotNull()
  .where(KEY_OR_KEY_CHAIN).isTruthy()
  .where(KEY_OR_KEY_CHAIN).isFalsy()
  .where(KEY_OR_KEY_CHAIN).startsWith(STRING)
  .where(KEY_OR_KEY_CHAIN).endsWith(STRING)
  .where(KEY_OR_KEY_CHAIN).is((VALUE) => boolean)
  .run() // run the command