@jsonkit/db

@jsonkit/db is a lightweight, zero-dependency database abstraction for rapid prototyping. It provides simple file based and in memory databases with consistent APIs, suitable for small applications, tooling, tests, and early-stage prototypes where setting up a full database would be unnecessary overhead.

The package exposes two core database types:

• Single entry databases – manage exactly one JSON-serializable object.
• Multi entry databases – manage collections of JSON-serializable objects keyed by an id.

Both concepts are available in file backed and in memory variants.

Goals

• Simple backend prototyping
• No dependancies

Non-goals

• Concurrency
• High performance
• Transactions
• Large datasets

For these, a dedicated database is recommended.

Installation

npm install @jsonkit/db

Multi entry Databases

Multi entry databases manage collections of entries keyed by id.

Common API (MultiEntryDb<T>)

All multi-entry implementations expose the same base methods:

• create(entry)
• getById(id)
• getByIdOrThrow(id)
• getWhere(predicate, pagination?)
• getFirstWhere(predicate)
• getFirstWhereOrThrow(predicate)
• getAll(ids?)
• getAllIds()
• updateById(id, updater)
• updateFirstWhere(predicate, updater)
• updateWhere(predicate, updater, pagination?)
• deleteById(id)
• deleteByIds(ids)
• deleteWhere(predicate)
• exists(id)
• countAll()
• countWhere(predicate)
• destroy()

Updates are partial merges, and changing an entry’s id during an update is supported.

Here are the major types that are used in MultiEntryDb methods:

// An entry's id must be a string or easily convertable into one
type Identifiable = { 
  id: string | number | {
    toString: () => string
  } 
}

// Used in search and filter methods in MultiEntryDbs
type PredicateFn<T extends Identifiable> = (entry: T) => boolean

type PaginationInput = {
  take: number
  page: number
}

// A function that updates an entry and returns a partial of the updated entry
export type UpdaterFn<T> = (entry: T) => Promisable<Partial<T>>

// The output of a `deleteMany` operation
type DeleteManyOutput = {
  deletedIds: string[]
  ignoredIds: string[]
}

MultiEntryFileDb<T>

A file-backed database where each entry is stored as its own JSON file.

import { MultiEntryFileDb } from '@jsonkit/db'

// Second argument is optional and is shown here with it's default values
const db = new MultiEntryFileDb<User>('./path/to/data/dir', {
  parser: JSON,
  indent: 2,
  noPathlikeIds: true,
  disableLogs: true,
})

• Each entry is stored as <id>.json in the provided directory.
• The directory is created implicitly as files are written.
• Second constructor argument and allof it's fields are optional
• IDs are validated to prevent path traversal by default. This can be disabled via the noPathlikeIds option.
• parser option allows custom parsing of entry contents.

MultiEntryMemDb<T>

An in-memory implementation backed by a Map.

import { MultiEntryMemDb } from '@jsonkit/db'

const db = new MultiEntryMemDb<User>()

Behavior

• Fast, ephemeral storage.
• persist() saves all entries to disk.
• load() reads entries from persistent storage created by persist().

Single entry Databases

Single entry databases manage exactly one value, often used for configuration or application state.

Common API (SingleEntryDb<T>)

• isInited()
• read()
• write(entry | updater)
• delete()

write supports either replacing the entry or partially updating it via an updater function.

SingleEntryFileDb<T>

Stores a single JSON object in a file.

import { SingleEntryFileDb } from '@jsonkit/db'

const db = new SingleEntryFileDb<AppConfig>('./config.json')

Behavior

• Reads and writes a single JSON file.

• isInited() checks file existence.

• read() throws if the file does not exist.

• parser defaults to JSON.

SingleEntryMemDb<T>

An in-memory single-value database.

import { SingleEntryMemDb } from '@jsonkit/db'

const db = new SingleEntryMemDb<AppConfig>()

Behavior

• Optional initial value.
• read() throws if uninitialized.
• delete() resets the entry to null.

License

MIT