Local NoSQL Database for Exploration and Education

Common errors

• La base de données n'est pas initialisée. Veuillez appeler 'init()' avant d'effectuer des opérations.

  cause Attempting to perform database operations (like accessing a collection) before calling the `init()` method on the `Database` instance.
  fix Ensure you call `await db.init()` after creating a new `Database` instance and await its completion before any other database interactions.

• Chemin de base de données non valide ou inaccessible.

  cause The provided path to the `Database` constructor is invalid, does not exist, or the application lacks the necessary file system permissions.
  fix Verify the `dbPath` string is a valid file system path and that your application has read/write permissions for that directory. Ensure the directory exists before initializing the database or handle its creation programmatically.

• Erreur de lecture du fichier JSON de la collection: [chemin/vers/fichier.json]. Le fichier est corrompu ou mal formé.

  cause A collection's JSON data file has become corrupted or contains invalid JSON syntax, preventing the library from parsing it.
  fix Inspect the specified JSON file for syntax errors. If the data is not critical, delete the file (losing data for that collection) or manually repair the JSON structure. Implement robust error handling around file I/O if possible, although the library might abstract this.

Warnings

• breaking This package is explicitly stated as 'Not suitable for production' use. It is intended solely for exploration and educational purposes and lacks features critical for production environments such as robust error handling, concurrency control, data integrity, and performance optimization for large datasets.
  Fix: Do not deploy applications using local-nosql-db to production. Use mature, production-ready NoSQL databases like MongoDB, CouchDB, or a cloud-managed service.
• gotcha All internal messages and logs generated by the library are in French. This can be a significant barrier for non-French speakers attempting to debug or understand library output.
  Fix: Translate any French error messages or log outputs using a translation tool to understand the underlying issue.
• gotcha As a file-based database, concurrent writes or sudden application termination can lead to data corruption or inconsistencies. There are no built-in mechanisms for atomic transactions or robust recovery.
  Fix: Ensure proper shutdown procedures for your application. Avoid highly concurrent write operations. Regularly back up your data directory if critical, even for development purposes. Consider using a more robust embedded database if data integrity is paramount.
• gotcha Query capabilities are extremely limited, primarily supporting direct field matching. Complex queries, aggregations, indexing, or advanced search patterns common in full NoSQL databases are not supported.
  Fix: Filter results in application memory after fetching them from the database, or simplify your data model to fit the basic query capabilities. For complex data needs, migrate to a feature-rich NoSQL solution.
• deprecated The library's development activity is infrequent, reflecting its purpose as an educational tool rather than a continuously evolving product. Users should not expect regular updates, new features, or rapid bug fixes.
  Fix: Accept that the library's feature set and maintenance schedule are minimal. For projects requiring active development and support, choose a different database solution.

Install

• npm install local-nosql-db npm
• yarn add local-nosql-db yarn
• pnpm add local-nosql-db pnpm

Imports

• Database
  wrong:

  const { Database } = require('local-nosql-db');

  correct:

  import { Database } from 'local-nosql-db';

  The primary class for database interaction. While ESM is preferred for modern Node.js, CJS `require` might still be seen in older projects given the library's local-first nature.
• Database (CommonJS)
  wrong:

  import { Database } from 'local-nosql-db';

  correct:

  const { Database } = require('local-nosql-db');

  For older Node.js projects or environments where CommonJS modules are still in use.
• IDocument

  import type { IDocument } from 'local-nosql-db';

  Type import for documents, useful when working with TypeScript to define the structure of data stored in the database.

Quickstart

This quickstart demonstrates how to initialize the local NoSQL database, create a collection, and perform basic CRUD operations (insert, find, update, delete) on documents. It also shows how to manage the persistence directory.

import { Database } from 'local-nosql-db';
import * as path from 'path';
import * as fs from 'fs';

const dbPath = path.join(__dirname, 'local-db-data');

// Ensure the database directory exists, or create it
if (!fs.existsSync(dbPath)) {
  fs.mkdirSync(dbPath, { recursive: true });
}

async function runDbOperations() {
  const db = new Database(dbPath);
  await db.init(); // Initialize the database

  const usersCollection = db.collection('users');

  // 1. Insert a document
  console.log('Inserting a new user...');
  const newUser = await usersCollection.insert({
    name: 'Alice Smith',
    email: 'alice@example.com',
    age: 30
  });
  console.log('Inserted user:', newUser);

  // 2. Find documents
  console.log('\nFinding all users...');
  const allUsers = await usersCollection.find({});
  console.log('All users:', allUsers);

  console.log('\nFinding user by email...');
  const foundUser = await usersCollection.findOne({ email: 'alice@example.com' });
  console.log('Found user:', foundUser);

  // 3. Update a document
  if (foundUser && foundUser._id) {
    console.log('\nUpdating user age...');
    const updatedUser = await usersCollection.update(
      { _id: foundUser._id },
      { $set: { age: 31, status: 'active' } }
    );
    console.log('Updated user:', updatedUser);
  }

  // 4. Delete a document
  if (newUser && newUser._id) {
    console.log('\nDeleting the new user...');
    const deleteResult = await usersCollection.delete({ _id: newUser._id });
    console.log('Delete result:', deleteResult);
  }

  console.log('\nFinal check of users after deletion:');
  const remainingUsers = await usersCollection.find({});
  console.log('Remaining users:', remainingUsers);

  // Clean up the created data directory (optional)
  // fs.rmSync(dbPath, { recursive: true, force: true });
  // console.log('\nDatabase directory cleaned up.');
}

runDbOperations().catch(console.error);