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
```