0
# Node JSON DB
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: node-json-db
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install node-json-db`
10
11
## Core Imports
12
13
```typescript
14
import { JsonDB, Config } from "node-json-db";
15
```
16
17
For advanced usage with custom adapters:
18
19
```typescript
20
import { JsonDB, ConfigWithAdapter, IAdapter, JsonAdapter, FileAdapter } from "node-json-db";
21
```
22
23
Error handling imports:
24
25
```typescript
26
import { DatabaseError, DataError } from "node-json-db";
27
```
28
29
CommonJS:
30
31
```javascript
32
const { JsonDB, Config } = require("node-json-db");
33
```
34
35
## Basic Usage
36
37
```typescript
38
import { JsonDB, Config } from "node-json-db";
39
40
// Create database with file-based storage
41
// Parameters: filename, saveOnPush, humanReadable, separator, syncOnSave
42
const db = new JsonDB(new Config("myDatabase", true, false, "/"));
43
44
// Store data using DataPath (XMLPath-like syntax)
45
await db.push("/users/1", {
46
name: "Alice",
47
email: "alice@example.com",
48
age: 25
49
});
50
51
// Retrieve data
52
const user = await db.getData("/users/1");
53
console.log(user.name); // "Alice"
54
55
// Check if data exists
56
const exists = await db.exists("/users/1");
57
58
// Update with merge (non-destructive)
59
await db.push("/users/1", { active: true }, false);
60
61
// Delete data
62
await db.delete("/users/1");
63
```
64
65
## Architecture
66
67
Node JSON DB is built around several key components:
68
69
- **JsonDB Class**: Main database interface providing all CRUD operations and data access methods
70
- **DataPath System**: XMLPath-like string navigation for accessing nested data (e.g., "/users/1/profile/name")
71
- **Adapter Pattern**: Pluggable storage backends with built-in JSON file adapter and support for custom adapters
72
- **Configuration System**: Flexible configuration through `Config` class or `ConfigWithAdapter` for custom setups
73
- **Locking Mechanism**: Read/write locks for safe concurrent access using the `rwlock` library
74
- **Array Support**: Advanced array indexing including negative indices, append operations, and multi-dimensional arrays
75
- **Type Safety**: Full TypeScript support with generic methods and comprehensive type definitions
76
77
## Capabilities
78
79
### Database Operations
80
81
Core CRUD operations for managing data in the JSON database, including data retrieval, storage, updates, and deletion with DataPath navigation.
82
83
```typescript { .api }
84
class JsonDB {
85
constructor(config: JsonDBConfig);
86
87
// Data retrieval
88
getData(dataPath: string): Promise<any>;
89
getObject<T>(dataPath: string): Promise<T>;
90
getObjectDefault<T>(dataPath: string, defaultValue?: T): Promise<T>;
91
exists(dataPath: string): Promise<boolean>;
92
93
// Data modification
94
push(dataPath: string, data: any, override?: boolean): Promise<void>;
95
delete(dataPath: string): Promise<void>;
96
}
97
```
98
99
[Database Operations](./database-operations.md)
100
101
### Configuration and Adapters
102
103
Flexible configuration system with built-in file storage adapter and support for custom storage backends through the adapter pattern.
104
105
```typescript { .api }
106
class Config implements JsonDBConfig {
107
constructor(
108
filename: string,
109
saveOnPush?: boolean,
110
humanReadable?: boolean,
111
separator?: string,
112
syncOnSave?: boolean
113
);
114
}
115
116
interface IAdapter<T> {
117
readAsync(): Promise<T | null>;
118
writeAsync(data: T): Promise<void>;
119
}
120
```
121
122
[Adapters and Configuration](./adapters.md)
123
124
### Advanced Features
125
126
Advanced functionality including array operations, search capabilities, database management, locking, and path utilities for complex data scenarios.
127
128
```typescript { .api }
129
class JsonDB {
130
// Array operations
131
count(dataPath: string): Promise<number>;
132
getIndex(dataPath: string, searchValue: string | number, propertyName?: string): Promise<number>;
133
getIndexValue(dataPath: string, searchValue: string | number): Promise<number>;
134
135
// Search operations
136
filter<T>(rootPath: string, callback: FindCallback): Promise<T[] | undefined>;
137
find<T>(rootPath: string, callback: FindCallback): Promise<T | undefined>;
138
139
// Database management
140
load(): Promise<void>;
141
save(force?: boolean): Promise<void>;
142
reload(): Promise<void>;
143
144
// Path utilities
145
fromPath(path: string, propertyName?: string): Promise<string>;
146
}
147
148
type FindCallback = (entry: any, index: number | string) => boolean;
149
```
150
151
[Advanced Features](./advanced-features.md)
152
153
## Error Handling
154
155
The library provides comprehensive error handling with specific error types:
156
157
```typescript { .api }
158
class DatabaseError extends NestedError {
159
constructor(message: string, id: Number, inner?: Error);
160
}
161
162
class DataError extends NestedError {
163
constructor(message: string, id: Number, inner?: Error);
164
}
165
166
abstract class NestedError extends Error {
167
readonly inner?: Error;
168
readonly id: Number;
169
toString(): string;
170
}
171
```
172
173
Common error scenarios:
174
- **DataError**: Invalid DataPath, array index out of bounds, type mismatches
175
- **DatabaseError**: File I/O errors, JSON parsing errors, database loading/saving failures
176
177
## Core Types
178
179
```typescript { .api }
180
interface JsonDBConfig {
181
readonly adapter: IAdapter<any>;
182
readonly saveOnPush: boolean;
183
readonly separator: string;
184
}
185
186
type FindCallback = (entry: any, index: number | string) => boolean;
187
```