DOCSEARCHbyAlgolia
Submit Docs

seald/nedb

repository·master·Indexed 19 days ago

https://github.com/seald/nedb

A maintained fork of NeDB providing a file-based, embedded, persistent, or in-memory data store for Node.js, Electron, and browsers. It offers a MongoDB-subset API with a 100% JavaScript implementation and no binary dependencies. Features include support for indexing, dot-notation querying, and compatibility with React Native via async-storage.

Tokens
9.4K
Snippets
31
Records
41
Agent score
62%

What's inside @seald-io/nedb

  1. Use serialization hooks for data encryption

    master
    You can use beforeDeserialization and afterSerialization hooks within the Persistence constructor to transform data. These are useful for implementing encryption: afterSerialization runs after stringifying a document (before writing to disk), and beforeDeserialization runs after reading from disk but before parsing the document.

  2. Manage database persistence and compaction

    master

    NeDB uses an append-only format for performance. The database is automatically compacted (reformatted to one-line-per-document) every time it is loaded.

    Note: Calling methods directly on yourDatabase.persistence is deprecated since v3.0.0; use the methods directly on the Datastore instance instead.

    • Manual Compaction: Use compactDatafileAsync().
    • Automatic Compaction: Use setAutocompactionInterval(interval) to set a regular interval, or stopAutocompaction() to stop it.

  3. How NeDB persistence and compaction work

    master

    NeDB uses an append-only format for performance: updates and deletes are appended to the end of the datafile rather than modifying existing lines.

    To maintain efficiency, the database is automatically compacted (reformatted to one-line-per-document) every time it is loaded. Compaction also removes documents with corrupted data, provided the total corruption remains below the corruptAlertThreshold.

    Durability Note: Compaction forces the OS to physically flush data to disk. Standard appends rely on the OS to flush data. In the event of a crash, you may lose data accumulated since the last sync (typically every 30 seconds).

  4. Understand the NeDB document structure

    master
    A NeDB document is a standard JavaScript object. The only guaranteed property is _id, which is the internal identifier. The _id may be null or undefined in certain lifecycle stages (e.g., before a document is inserted).

  5. Understand NeDB performance and memory usage

    master

    Speed

    NeDB is designed for smaller datasets and is not a replacement for large-scale databases like MongoDB. Performance is significantly improved when using indexing.

    Typical performance on a standard development machine (for 10,000 documents with indexing):

    • Insert: ~10,680 ops/s
    • Find: ~43,290 ops/s
    • Update: ~8,000 ops/s
    • Remove: ~11,750 ops/s

    You can run benchmarks using the scripts in the benchmarks folder with the --help flag.

    Memory Footprint

    NeDB keeps a copy of the entire database in memory. For context, 10,000 documents of 2KB each will consume approximately 20MB of memory.

  6. Understand NeDB persistence and compaction

    master

    NeDB uses an append-only format for persistence. Updates and deletes result in new lines added to the end of the datafile for performance.

    Key Concepts:

    • Compaction: The database is automatically compacted (reverting to one-line-per-document format) whenever a database is loaded. Compaction is a blocking operation; no other operations can occur during this time.
    • Durability: Compaction forces the OS to flush data to disk. Appends do not guarantee immediate disk flushing (the OS handles this). A crash between syncs may result in losing data since the last sync (typically every 30 seconds).
    • Corruption: Compaction removes corrupted documents as long as the total percentage of corrupted documents remains below the corruptAlertThreshold.

    Note: Since version 3.0.0, manually using Datastore.persistence methods is deprecated.

  7. Use serialization hooks for encryption or transformation

    master

    The beforeDeserialization and afterSerialization hooks are callbacks executed during the data lifecycle:

    • afterSerialization: Executed after stringifying documents (useful for encryption).
    • beforeDeserialization: Executed before parsing documents (useful for decryption).

    These hooks return either a string or a Promise<string>.

  9. Initialize a NeDB Datastore

    master

    You can use NeDB as an in-memory datastore or a persistent datastore. A Datastore instance is equivalent to a MongoDB collection.

    • In-memory: No filename option is provided. No loading is required.
    • Persistent: Provide a filename. You must either call loadDatabaseAsync() manually or set autoload: true in the options. If using autoload: true, you can monitor db.autoloadPromise to catch loading errors.
    const Datastore = require('@seald-io/nedb')

// Type 1: In-memory only
const db = new Datastore()

// Type 2: Persistent with manual loading
const db = new Datastore({ filename: 'path/to/datafile' })
try {
  await db.loadDatabaseAsync()
} catch (error) {
  // loading failed
}

// Type 3: Persistent with automatic loading
const db = new Datastore({ filename: 'path/to/datafile', autoload: true })
// You can await db.autoloadPromise to catch errors

  10. Use NeDB in the Browser

    master

    To use NeDB in a web browser, include the nedb.js or nedb.min.js bundle in your HTML file. Once loaded, the global Nedb object is available and provides the same API as the Node.js version.

    If you instantiate new Nedb() without a filename, the database operates entirely in-memory. If you provide a filename, NeDB becomes persistent by automatically selecting the best available storage method via localforage (IndexedDB, WebSQL, or localStorage).

    WARNING: The storage system changed between v1.3 and v1.4 and is not back-compatible. Applications must resync client-side when upgrading NeDB versions.

    <script src="nedb.min.js"></script>
<script>
  var db = new Nedb();   // Create an in-memory only datastore
  
  db.insert({ planet: 'Earth' }, function (err) {
   db.find({}, function (err, docs) {
     // docs contains the two planets Earth and Mars
   });
  });
</script>

  12. Install @seald-io/nedb via npm

    master

    Install the @seald-io/nedb package using npm to use this embedded persistent or in-memory database in Node.js, Electron, or browsers. It is a 100% JavaScript implementation with no binary dependencies.

    npm install @seald-io/nedb