or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

adapters.mdadvanced-features.mddatabase-operations.mdindex.md
tile.json

tessl/npm-node-json-db

Database using JSON file as storage for Node.JS

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/node-json-db@2.3.x

To install, run

npx @tessl/cli install tessl/npm-node-json-db@2.3.0

index.mddocs/

Node JSON DB

Node JSON DB is a lightweight JSON file-based database solution for Node.js applications that need simple persistent data storage without the complexity of traditional databases. It offers a filesystem-based storage approach using JSON files with a JavaScript Object interface, supporting async/await operations, DataPath traversal similar to XMLPath for accessing nested properties, and includes features like file locking for concurrent access protection.

Package Information

  • Package Name: node-json-db
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install node-json-db

Core Imports

import { JsonDB, Config } from "node-json-db";

For advanced usage with custom adapters:

import { JsonDB, ConfigWithAdapter, IAdapter, JsonAdapter, FileAdapter } from "node-json-db";

Error handling imports:

import { DatabaseError, DataError } from "node-json-db";

CommonJS:

const { JsonDB, Config } = require("node-json-db");

Basic Usage

import { JsonDB, Config } from "node-json-db";

// Create database with file-based storage
// Parameters: filename, saveOnPush, humanReadable, separator, syncOnSave
const db = new JsonDB(new Config("myDatabase", true, false, "/"));

// Store data using DataPath (XMLPath-like syntax)
await db.push("/users/1", {
  name: "Alice",
  email: "alice@example.com",
  age: 25
});

// Retrieve data
const user = await db.getData("/users/1");
console.log(user.name); // "Alice"

// Check if data exists
const exists = await db.exists("/users/1");

// Update with merge (non-destructive)
await db.push("/users/1", { active: true }, false);

// Delete data
await db.delete("/users/1");

Architecture

Node JSON DB is built around several key components:

  • JsonDB Class: Main database interface providing all CRUD operations and data access methods
  • DataPath System: XMLPath-like string navigation for accessing nested data (e.g., "/users/1/profile/name")
  • Adapter Pattern: Pluggable storage backends with built-in JSON file adapter and support for custom adapters
  • Configuration System: Flexible configuration through Config class or ConfigWithAdapter for custom setups
  • Locking Mechanism: Read/write locks for safe concurrent access using the rwlock library
  • Array Support: Advanced array indexing including negative indices, append operations, and multi-dimensional arrays
  • Type Safety: Full TypeScript support with generic methods and comprehensive type definitions

Capabilities

Database Operations

Core CRUD operations for managing data in the JSON database, including data retrieval, storage, updates, and deletion with DataPath navigation.

class JsonDB {
  constructor(config: JsonDBConfig);
  
  // Data retrieval
  getData(dataPath: string): Promise<any>;
  getObject<T>(dataPath: string): Promise<T>;
  getObjectDefault<T>(dataPath: string, defaultValue?: T): Promise<T>;
  exists(dataPath: string): Promise<boolean>;
  
  // Data modification
  push(dataPath: string, data: any, override?: boolean): Promise<void>;
  delete(dataPath: string): Promise<void>;
}

Database Operations

Configuration and Adapters

Flexible configuration system with built-in file storage adapter and support for custom storage backends through the adapter pattern.

class Config implements JsonDBConfig {
  constructor(
    filename: string,
    saveOnPush?: boolean,
    humanReadable?: boolean,
    separator?: string,
    syncOnSave?: boolean
  );
}

interface IAdapter<T> {
  readAsync(): Promise<T | null>;
  writeAsync(data: T): Promise<void>;
}

Adapters and Configuration

Advanced Features

Advanced functionality including array operations, search capabilities, database management, locking, and path utilities for complex data scenarios.

class JsonDB {
  // Array operations
  count(dataPath: string): Promise<number>;
  getIndex(dataPath: string, searchValue: string | number, propertyName?: string): Promise<number>;
  getIndexValue(dataPath: string, searchValue: string | number): Promise<number>;
  
  // Search operations
  filter<T>(rootPath: string, callback: FindCallback): Promise<T[] | undefined>;
  find<T>(rootPath: string, callback: FindCallback): Promise<T | undefined>;
  
  // Database management
  load(): Promise<void>;
  save(force?: boolean): Promise<void>;
  reload(): Promise<void>;
  
  // Path utilities
  fromPath(path: string, propertyName?: string): Promise<string>;
}

type FindCallback = (entry: any, index: number | string) => boolean;

Advanced Features

Error Handling

The library provides comprehensive error handling with specific error types:

class DatabaseError extends NestedError {
  constructor(message: string, id: Number, inner?: Error);
}

class DataError extends NestedError {
  constructor(message: string, id: Number, inner?: Error);
}

abstract class NestedError extends Error {
  readonly inner?: Error;
  readonly id: Number;
  toString(): string;
}

Common error scenarios:

  • DataError: Invalid DataPath, array index out of bounds, type mismatches
  • DatabaseError: File I/O errors, JSON parsing errors, database loading/saving failures

Core Types

interface JsonDBConfig {
  readonly adapter: IAdapter<any>;
  readonly saveOnPush: boolean;
  readonly separator: string;
}

type FindCallback = (entry: any, index: number | string) => boolean;