0
# LokiJS
1
2
LokiJS is a fast, document-oriented NoSQL in-memory database written entirely in JavaScript. It provides high-performance data storage and retrieval with unique and binary indexing capabilities, achieving up to 1.1M operations per second. The library supports dynamic views for efficient data subset access, built-in persistence adapters, a changes API for tracking modifications, and join operations for complex queries.
3
4
## Package Information
5
6
- **Package Name**: lokijs
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install lokijs`
10
11
## Core Imports
12
13
```javascript
14
const loki = require('lokijs');
15
```
16
17
For ES6 modules:
18
19
```javascript
20
import loki from 'lokijs';
21
```
22
23
Browser usage:
24
25
```html
26
<script src="lokijs.js"></script>
27
<!-- loki is available as a global variable -->
28
```
29
30
## Basic Usage
31
32
```javascript
33
const loki = require('lokijs');
34
35
// Create database
36
const db = new loki('example.db');
37
38
// Add collection
39
const users = db.addCollection('users');
40
41
// Insert documents
42
users.insert({ name: 'Alice', age: 25, active: true });
43
users.insert({ name: 'Bob', age: 30, active: false });
44
users.insert({ name: 'Charlie', age: 35, active: true });
45
46
// Query documents
47
const activeUsers = users.find({ active: true });
48
const user = users.findOne({ name: 'Alice' });
49
50
// Chain operations
51
const result = users.chain()
52
.find({ active: true })
53
.where(obj => obj.age > 25)
54
.simplesort('name')
55
.data();
56
57
// Save database (with adapter)
58
db.saveDatabase();
59
```
60
61
## Architecture
62
63
LokiJS is built around several key components:
64
65
- **Database (Loki)**: Main container managing collections and persistence
66
- **Collections**: Document containers with indexing, querying, and CRUD operations
67
- **Resultsets**: Chainable query interface for complex data operations
68
- **Dynamic Views**: Live, filtered views of collection data with persistent state
69
- **Persistence Adapters**: Pluggable storage backends for different environments
70
- **Event System**: Event emitters for reactive programming patterns
71
- **Indexing System**: Binary and unique indexes for high-performance queries
72
73
## Capabilities
74
75
### Database Management
76
77
Core database operations including creation, persistence, serialization, and collection management.
78
79
```javascript { .api }
80
class Loki {
81
constructor(filename?: string, options?: DatabaseOptions);
82
83
addCollection(name: string, options?: CollectionOptions): Collection;
84
getCollection(collectionName: string): Collection | null;
85
removeCollection(collectionName: string): void;
86
87
loadDatabase(options?: any, callback?: Function): void;
88
saveDatabase(callback?: Function): void;
89
serialize(options?: SerializeOptions): string;
90
}
91
```
92
93
[Database Management](./database-management.md)
94
95
### Collection Operations
96
97
Document storage and retrieval with powerful querying, indexing, and aggregation capabilities.
98
99
```javascript { .api }
100
class Collection {
101
constructor(name: string, options?: CollectionOptions);
102
103
insert(doc: object | object[]): object | object[];
104
update(doc: object): object;
105
remove(doc: object): object;
106
find(query?: object): object[];
107
findOne(query?: object): object | null;
108
109
chain(transform?: string, parameters?: object): Resultset;
110
where(fun: Function): object[];
111
count(query?: object): number;
112
}
113
```
114
115
[Collection Operations](./collection-operations.md)
116
117
### Advanced Querying
118
119
Chainable query interface with filtering, sorting, transformations, and aggregation operations.
120
121
```javascript { .api }
122
class Resultset {
123
constructor(collection: Collection, options?: object);
124
125
find(query: object, firstOnly?: boolean): Resultset;
126
where(fun: Function): Resultset;
127
sort(comparefun: Function): Resultset;
128
simplesort(propname: string, options?: object): Resultset;
129
limit(qty: number): Resultset;
130
offset(pos: number): Resultset;
131
data(options?: object): object[];
132
}
133
```
134
135
[Advanced Querying](./advanced-querying.md)
136
137
### Dynamic Views
138
139
Live, automatically updated views of collection data with persistent filtering and sorting.
140
141
```javascript { .api }
142
class DynamicView {
143
constructor(collection: Collection, name: string, options?: object);
144
145
applyFind(query: object): DynamicView;
146
applyWhere(fun: Function): DynamicView;
147
applySort(comparefun: Function): DynamicView;
148
applySimpleSort(propname: string, options?: object): DynamicView;
149
150
data(options?: object): object[];
151
count(): number;
152
rematerialize(): DynamicView;
153
}
154
```
155
156
[Dynamic Views](./dynamic-views.md)
157
158
### Persistence Adapters
159
160
Storage backends for different environments including file system, localStorage, IndexedDB, and custom adapters.
161
162
```javascript { .api }
163
interface PersistenceAdapter {
164
loadDatabase(dbname: string, callback: Function): void;
165
saveDatabase(dbname: string, dbref: object, callback: Function): void;
166
}
167
168
// Built-in adapters
169
class LokiFsAdapter implements PersistenceAdapter;
170
class LokiLocalStorageAdapter implements PersistenceAdapter;
171
class LokiMemoryAdapter implements PersistenceAdapter;
172
class LokiPartitioningAdapter implements PersistenceAdapter;
173
```
174
175
[Persistence Adapters](./persistence-adapters.md)
176
177
### Key-Value Storage
178
179
Simple key-value storage with binary search capabilities for efficient lookups.
180
181
```javascript { .api }
182
class KeyValueStore {
183
constructor();
184
185
/** Set a key-value pair */
186
set(key: any, value: any): void;
187
188
/** Get values for a key */
189
get(key: any): any[];
190
191
/** Set custom sort function */
192
setSort(fun: Function): void;
193
194
/** Remove a key-value pair */
195
remove(key: any, value: any): void;
196
197
/** Clear all key-value pairs */
198
clear(): void;
199
}
200
```
201
202
### Utility Functions
203
204
Helper functions for object manipulation, comparison operations, and query processing.
205
206
```javascript { .api }
207
// Object utilities
208
loki.deepFreeze(obj: object): void;
209
loki.freeze(obj: object): void;
210
loki.unFreeze(obj: object): object;
211
212
// Comparison helpers
213
loki.aeq(prop1: any, prop2: any): boolean;
214
loki.lt(prop1: any, prop2: any, equal?: boolean): boolean;
215
loki.gt(prop1: any, prop2: any, equal?: boolean): boolean;
216
217
// Query operations (complete set)
218
loki.LokiOps: {
219
// Comparison operators
220
$eq: Function, $aeq: Function, $ne: Function, $dteq: Function,
221
$gt: Function, $gte: Function, $lt: Function, $lte: Function,
222
$jgt: Function, $jgte: Function, $jlt: Function, $jlte: Function,
223
224
// Range operators
225
$between: Function, $jbetween: Function,
226
227
// Array/Set operators
228
$in: Function, $nin: Function, $inSet: Function,
229
$contains: Function, $containsAny: Function, $containsNone: Function,
230
$containsString: Function,
231
232
// Object operators
233
$keyin: Function, $nkeyin: Function, $definedin: Function, $undefinedin: Function,
234
$elemMatch: Function,
235
236
// Pattern matching
237
$regex: Function, $type: Function, $where: Function
238
};
239
240
// Comparator functions
241
loki.Comparators: {
242
aeq: Function,
243
lt: Function,
244
gt: Function
245
};
246
247
// Constructors available on loki
248
loki.Collection: typeof Collection;
249
loki.DynamicView: typeof DynamicView;
250
loki.Resultset: typeof Resultset;
251
loki.KeyValueStore: typeof KeyValueStore;
252
253
// Persistence adapters
254
loki.LokiMemoryAdapter: typeof LokiMemoryAdapter;
255
loki.LokiPartitioningAdapter: typeof LokiPartitioningAdapter;
256
loki.LokiLocalStorageAdapter: typeof LokiLocalStorageAdapter;
257
loki.LokiFsAdapter: typeof LokiFsAdapter;
258
loki.persistenceAdapters: {
259
fs: typeof LokiFsAdapter;
260
localStorage: typeof LokiLocalStorageAdapter;
261
};
262
263
// Event system (inherited by Loki, Collection, DynamicView)
264
interface EventEmitter {
265
on(eventName: string, listener: Function): void;
266
emit(eventName: string, ...args: any[]): void;
267
removeListener(eventName: string, listener: Function): void;
268
}
269
```
270
271
## Global Types
272
273
```javascript { .api }
274
interface DatabaseOptions {
275
autosave?: boolean;
276
autosaveInterval?: number;
277
adapter?: PersistenceAdapter;
278
serializationMethod?: string;
279
destructureDelimiter?: string;
280
verbose?: boolean;
281
throttledSaves?: boolean;
282
env?: string;
283
persistenceMethod?: string;
284
}
285
286
interface CollectionOptions {
287
unique?: string[];
288
exact?: string[];
289
indices?: string[];
290
adaptiveBinaryIndices?: boolean;
291
asyncListeners?: boolean;
292
disableMeta?: boolean;
293
disableChangesApi?: boolean;
294
disableDeltaChangesApi?: boolean;
295
autoupdate?: boolean;
296
clone?: boolean;
297
cloneMethod?: string;
298
transactional?: boolean;
299
ttl?: number;
300
ttlInterval?: number;
301
serializableIndices?: boolean;
302
}
303
304
interface SerializeOptions {
305
serializationMethod?: string;
306
destructureDelimiter?: string;
307
}
308
```