0
# NeDB (Node Embedded Database)
1

2
NeDB is a lightweight embedded JavaScript database that provides persistent or in-memory data storage for Node.js, Electron, and browser applications. It implements a subset of MongoDB's API with 100% JavaScript implementation and no binary dependencies, making it ideal for applications requiring a simple database solution without server overhead.
3

4
## Package Information
5

6
- **Package Name**: nedb
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install nedb`
10

11
## Core Imports
12

13
```javascript
14
const Datastore = require('nedb');
15
```
16

17
For ES modules:
18

19
```javascript
20
import Datastore from 'nedb';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const Datastore = require('nedb');
27

28
// Create in-memory database
29
const db = new Datastore();
30

31
// Create persistent database
32
const persistentDb = new Datastore({ filename: './data.db', autoload: true });
33

34
// Insert documents
35
db.insert({ name: 'Alice', age: 25 }, (err, newDoc) => {
36
  console.log('Inserted:', newDoc);
37
});
38

39
// Find documents
40
db.find({ age: { $gte: 18 } }, (err, docs) => {
41
  console.log('Adults:', docs);
42
});
43

44
// Update documents
45
db.update({ name: 'Alice' }, { $set: { age: 26 } }, {}, (err, numReplaced) => {
46
  console.log('Updated:', numReplaced);
47
});
48

49
// Remove documents
50
db.remove({ age: { $lt: 18 } }, { multi: true }, (err, numRemoved) => {
51
  console.log('Removed:', numRemoved);
52
});
53
```
54

55
## Architecture
56

57
NeDB is built around several key components:
58

59
- **Datastore Class**: Main database interface providing CRUD operations with MongoDB-like API
60
- **Cursor System**: Chainable query interface for sorting, limiting, and pagination
61
- **Index Management**: Automatic and custom indexing for query performance optimization
62
- **Persistence Layer**: Crash-safe file operations with optional compression and encryption hooks
63
- **Query Engine**: MongoDB-compatible query operators and update modifiers
64
- **Event System**: EventEmitter-based notifications for database operations
65

66
## Capabilities
67

68
### Database Creation & Management
69

70
Core database initialization, loading, and lifecycle management including persistence options and configuration.
71

72
```javascript { .api }
73
/**
74
 * Creates a new NeDB database instance
75
 * @param {string|object} options - Database configuration
76
 */
77
constructor Datastore(options);
78
```
79

80
[Database Management](./database-management.md)
81

82
### Document Operations
83

84
Complete CRUD operations for managing documents including insertion, querying, updating, and deletion with MongoDB-style syntax.
85

86
```javascript { .api }
87
/**
88
 * Insert document(s) into database
89
 * @param {object|array} doc - Document or array of documents to insert
90
 * @param {function} callback - Callback function (err, insertedDoc) => {}
91
 */
92
insert(doc, callback);
93

94
/**
95
 * Find documents matching query
96
 * @param {object} query - MongoDB-style query object
97
 * @param {object} projection - Optional field projection
98
 * @param {function} callback - Callback function (err, docs) => {}
99
 * @returns {Cursor} Cursor for chaining if no callback provided
100
 */
101
find(query, projection, callback);
102
```
103

104
[Document Operations](./document-operations.md)
105

106
### Query System
107

108
Advanced querying capabilities with MongoDB-compatible operators for complex data retrieval and filtering.
109

110
```javascript { .api }
111
/**
112
 * MongoDB-style query operators
113
 */
114
interface QueryOperators {
115
  $lt: any;    // Less than
116
  $lte: any;   // Less than or equal
117
  $gt: any;    // Greater than
118
  $gte: any;   // Greater than or equal
119
  $ne: any;    // Not equal
120
  $in: any[];  // Value in array
121
  $nin: any[]; // Value not in array
122
  $regex: RegExp; // Regular expression match
123
  $exists: boolean; // Field exists check
124
  $size: number;    // Array size
125
  $elemMatch: object; // Element match in array
126
  $or: object[];   // Logical OR
127
  $and: object[];  // Logical AND
128
  $not: object;    // Logical NOT
129
  $where: function; // Function evaluation
130
}
131
```
132

133
[Query System](./query-system.md)
134

135
### Index Management
136

137
Performance optimization through automatic and custom indexing including unique constraints and TTL (time-to-live) indexes.
138

139
```javascript { .api }
140
/**
141
 * Create or ensure index exists
142
 * @param {object} options - Index configuration
143
 * @param {function} callback - Callback function (err) => {}
144
 */
145
ensureIndex(options, callback);
146
```
147

148
[Index Management](./index-management.md)
149

150
### Cursor Operations
151

152
Chainable query interface for sorting, pagination, projection, and result processing with lazy evaluation.
153

154
```javascript { .api }
155
/**
156
 * Cursor interface for chaining query operations
157
 */
158
interface Cursor {
159
  limit(limit: number): Cursor;
160
  skip(skip: number): Cursor;
161
  sort(sortQuery: object): Cursor;
162
  projection(projection: object): Cursor;
163
  exec(callback: function): void;
164
}
165
```
166

167
[Cursor Operations](./cursor-operations.md)
168

169
## Types
170

171
```javascript { .api }
172
/**
173
 * Database configuration options
174
 */
175
interface DatastoreOptions {
176
  filename?: string;                    // Path to database file
177
  inMemoryOnly?: boolean;              // Use memory-only storage (default: false)
178
  autoload?: boolean;                  // Auto-load database on creation (default: false)
179
  timestampData?: boolean;             // Auto-add createdAt/updatedAt (default: false)
180
  onload?: (err: Error) => void;       // Callback after autoload
181
  afterSerialization?: (data: string) => string;     // Transform before disk write
182
  beforeDeserialization?: (data: string) => string;  // Transform after disk read
183
  corruptAlertThreshold?: number;      // Corruption tolerance 0-1 (default: 0.1)
184
  compareStrings?: (a: string, b: string) => number; // Custom string comparison
185
}
186

187
/**
188
 * Index configuration options
189
 */
190
interface IndexOptions {
191
  fieldName: string;           // Field to index (required)
192
  unique?: boolean;           // Unique constraint (default: false)
193
  sparse?: boolean;           // Sparse index (default: false)
194
  expireAfterSeconds?: number; // TTL in seconds for automatic expiration
195
}
196

197
/**
198
 * Update operation options
199
 */
200
interface UpdateOptions {
201
  multi?: boolean;            // Update multiple documents (default: false)
202
  upsert?: boolean;          // Insert if no match found (default: false)
203
  returnUpdatedDocs?: boolean; // Return updated documents (default: false)
204
}
205

206
/**
207
 * Remove operation options
208
 */
209
interface RemoveOptions {
210
  multi?: boolean; // Remove multiple documents (default: false)
211
}
212
```