LokiJS In-Memory Database

Common errors

• Trying to update unsynced document. Please save the document first by using insert() or addMany()

  cause Attempting to update a document by passing a new object literal or a document missing the internal '$loki' ID.
  fix Always retrieve the document from the collection, modify the returned object reference, and then pass that specific object to `collection.update()`. Example: `const doc = collection.findOne({ id: 1 }); doc.field = 'newValue'; collection.update(doc);`

• Error: Cannot find module 'lokijs'

  cause Incorrect import path or CommonJS `require()` syntax in an environment where ESM is expected, or vice-versa, or bundling issues in environments like Electron.
  fix For Node.js, ensure `const Loki = require('lokijs');` is used. For modern browsers or bundlers supporting ESM, use `import Loki from 'lokijs';`. If using a specific adapter, ensure the path `lokijs/src/loki-adapter-name` is correct. Verify `lokijs` is correctly installed in `node_modules` and your build process includes it.

Warnings

• breaking Some external sources (e.g., database.guide) claim LokiJS was abandoned in 2022 and its official website redirects to RxDB, suggesting a lack of active development or future deprecation in favor of alternatives. While the GitHub repository shows some recent minor commits, the discrepancy and the outdated README (referencing v1.3 while npm is v1.5.12) indicate potential long-term maintenance uncertainty and recommend evaluating alternatives like RxDB for new projects.
  Fix: For new projects, consider modern alternatives like RxDB or other actively maintained in-memory databases. For existing projects, be aware of the potential for limited support or future breaking changes without clear migration paths.
• gotcha LokiJS is an in-memory database, meaning data is lost upon application restart or browser refresh unless a persistence adapter is explicitly configured. Default behavior is purely in-memory.
  Fix: Always initialize LokiJS with a suitable persistence adapter (e.g., `LokiLocalStorageAdapter`, `LokiIndexedAdapter`, `LokiFsAdapter` for Node.js) and enable `autoload: true` and `autosave: true` options to prevent data loss. Remember to manually call `db.saveDatabase()` before application exit if `autosave` is not active or for immediate writes.
• gotcha Using plain LokiJS across multiple browser tabs can lead to data loss due to instances overwriting each other's persistence. LokiJS loads data in bulk and periodically persists it, which is not designed for concurrent multi-tab writes without external coordination.
  Fix: If multi-tab support is required, consider wrapping LokiJS with a solution that handles leader election or provides a more robust multi-instance synchronization mechanism, such as the RxDB LokiJS plugin which addresses this issue. Alternatively, ensure only one tab is actively writing to the database.
• gotcha When updating documents, you must pass an existing document object (which contains the `$loki` ID) to the `collection.update()` method. Passing a plain object or a modified copy without the `$loki` property will result in a 'Trying to update unsynced document' error.
  Fix: Retrieve the document from the collection first using `find()` or `findOne()`, modify the retrieved object, and then pass that *same object* back to `collection.update()`. Alternatively, use `collection.findAndUpdate()` with a query and an update function.

Install

• npm install lokijs npm
• yarn add lokijs yarn
• pnpm add lokijs pnpm

Imports

• Loki
  wrong:

  import { Loki } from 'lokijs';

  correct:

  import Loki from 'lokijs';

  LokiJS primarily uses a default export for the main Loki class in ESM environments, though it's fundamentally a CommonJS library. Accessing named exports like `Loki` directly often fails without proper bundler configuration for CJS interoperability.
• Loki
  wrong:

  const { Loki } = require('lokijs');

  correct:

  const Loki = require('lokijs');

  For CommonJS, the `require('lokijs')` call returns the Loki class constructor directly, not an object with named exports.
• LokiLocalStorageAdapter
  wrong:

  import { LokiLocalStorageAdapter } from 'lokijs';

  correct:

  import LokiLocalStorageAdapter from 'lokijs/src/loki-local-storage-adapter';

  Persistence adapters are typically located in the `src` subdirectory and often require direct import from their specific file paths, rather than being named exports from the main `lokijs` package.

Quickstart

This quickstart demonstrates how to initialize a LokiJS in-memory database, configure it with the LocalStorage adapter for persistence, add a collection with a unique constraint, insert documents, and perform basic queries and updates. It includes an `autoload` and `autosave` setup to manage data lifecycle across sessions.

import Loki from 'lokijs';
import LokiLocalStorageAdapter from 'lokijs/src/loki-local-storage-adapter';

const dbName = 'myCoolDatabase.db';
const adapter = new LokiLocalStorageAdapter(dbName);

const db = new Loki(dbName, {
  adapter: adapter,
  autoload: true,
  autoloadCallback: databaseInitialize,
  autosave: true,
  autosaveInterval: 4000
});

function databaseInitialize() {
  let users = db.getCollection('users');
  if (users === null) {
    users = db.addCollection('users', { unique: ['email'] });
  }

  // Check if there's any data, if not, insert some
  if (users.count() === 0) {
    users.insert({ name: 'Alice', email: 'alice@example.com', age: 30 });
    users.insert({ name: 'Bob', email: 'bob@example.com', age: 24 });
    console.log('Initial data inserted.');
  } else {
    console.log('Database already contains data.');
  }

  const allUsers = users.find();
  console.log('All users:', allUsers);

  const youngUsers = users.find({ age: { '$lt': 25 } });
  console.log('Users younger than 25:', youngUsers);

  // Update an existing user
  const alice = users.findOne({ name: 'Alice' });
  if (alice) {
    alice.age = 31;
    users.update(alice);
    console.log('Alice updated:', users.findOne({ name: 'Alice' }));
  }

  // Ensure data is saved after modifications if autosave is off or before manual exit
  // db.saveDatabase(); // Autosave handles this in this example
}

console.log('LokiJS database initialized or loaded.');