JaguarDb In-Process Database

0.1.3 verified Thu Apr 23 auth: no javascript abandoned

JaguarDb is a minimalist, in-process database designed exclusively for Node.js environments, currently at version 0.1.3. It functions as a rudimentary document-oriented store by serializing JavaScript objects to individual JSON files on the file system and managing an `index.json` master file. The library explicitly states it is not suitable for production use, lacking crucial database features like transactions, ACID properties, and scalability. Its API mimics MongoDB's callback-based interface, making it conceptually familiar for developers and allowing for potentially easier migration to more robust database solutions. However, the project appears to be abandoned, with no active development or maintenance. It is intended solely for small prototypes, unit testing, or scenarios where a quick and dirty, file-based persistence layer is needed without the overhead of an external database process, but users should be aware of its severe limitations and lack of ongoing support.

Common errors

error Error: EACCES: permission denied, open './data_jaguardb_quickstart/index.json' ↓

cause The Node.js process lacks the necessary write permissions for the directory specified in `db.connect()`.

fix

Ensure the user running the Node.js application has read and write permissions to the data directory (e.g., ./data_jaguardb_quickstart) and its contents. You might need to change directory permissions (e.g., chmod 777 data_jaguardb_quickstart for temporary testing, or chown for production).

error TypeError: JaguarDb is not a constructor ↓

cause The `require('jaguardb')` statement was used incorrectly, attempting to instantiate the module object directly instead of its named export `JaguarDb`.

fix

Correct the import statement to destructure the named export: const { JaguarDb } = require('jaguardb');.

error Error: ENOENT: no such file or directory, open './data_jaguardb_quickstart/1.json' ↓

cause An attempt was made to read a specific document file that either never existed, was deleted, or the database's index file (`index.json`) is out of sync or corrupted.

fix

Verify the document's _id and ensure the database was connected to the correct data directory. If index.json is corrupted, manual inspection or re-initialization of the database might be required (losing data).

Warnings

gotcha JaguarDb is explicitly not suitable for production use; it lacks transactions, ACID properties, and is not designed for scalability or high-traffic applications. Data integrity cannot be guaranteed in failure scenarios. ↓

fix For any production or critical application, use a robust, actively maintained database solution such as MongoDB, PostgreSQL, SQLite, or a cloud-based alternative.

gotcha Data is stored as individual JSON files on disk, making it potentially slow for large datasets with many documents and susceptible to corruption if processes crash mid-write, leading to inconsistent states. ↓

fix Ensure proper backup strategies and understand the inherent limitations for I/O-intensive operations. Monitor disk space and performance if used for substantial data volumes.

gotcha The API relies entirely on Node.js-style error-first callbacks, which can lead to 'callback hell' in complex asynchronous flows. There are no native Promise-based or async/await alternatives provided. ↓

fix Wrap API calls in Promises manually using `util.promisify` or a custom wrapper to integrate with modern async/await patterns for improved readability and error handling.

deprecated The `jaguardb` project appears to be abandoned, with its last release (0.1.3) being very old, suggesting no active development, bug fixes, or security updates. This poses risks for long-term use. ↓

fix Consider using actively maintained in-process databases like `NeDB` or `lowdb` for similar lightweight use cases, or a full-fledged database for more robust and supported needs.

Install

npm install jaguardb

yarn add jaguardb

pnpm add jaguardb

Imports

JaguarDb
wrong
```
import { JaguarDb } from 'jaguardb';
```
correct
```
const { JaguarDb } = require('jaguardb');
```
This library is CommonJS-only and exports 'JaguarDb' as a named property. Using ES module 'import' will result in a runtime error.
JaguarDb (module object)
wrong
```
const JaguarDb = require('jaguardb');
const db = new JaguarDb();
```
correct
```
const jaguarDbModule = require('jaguardb');
const db = new jaguarDbModule.JaguarDb();
```
The `require('jaguardb')` call returns an object with `JaguarDb` as a property, not the constructor function itself. Destructuring is the idiomatic way.

Quickstart

This example demonstrates how to connect to a JaguarDb instance, insert two documents, and then query for one of them using its title.

const { JaguarDb } = require('jaguardb');
const path = require('path');

const db = new JaguarDb();
const dataDir = path.join(__dirname, 'data_jaguardb_quickstart');

db.connect(dataDir, function(err) {
  if (err) {
    console.error('Error connecting to database:', err);
    return;
  }
  console.log('Database connected successfully.');

  const doc1 = { title: 'First Document', content: 'This is the content of the first document.' };
  const doc2 = { title: 'Second Document', tags: ['node', 'database'] };

  db.insert(doc1, function(err, insertedDoc1) {
    if (err) {
      console.error('Error inserting doc1:', err);
      return;
    }
    console.log('Inserted document 1 with _id:', insertedDoc1._id);

    db.insert(doc2, function(err, insertedDoc2) {
      if (err) {
        console.error('Error inserting doc2:', err);
        return;
      }
      console.log('Inserted document 2 with _id:', insertedDoc2._id);

      db.find({ title: 'Second Document' }, {}, function(err, documents) {
        if (err) {
          console.error('Error finding documents:', err);
          return;
        }
        console.log('Found documents:', documents);
      });
    });
  });
});