{"id":16643,"library":"local-nosql-db","title":"Local NoSQL Database for Exploration and Education","description":"local-nosql-db is a lightweight, file-based NoSQL database designed exclusively for local development, educational purposes, and exploration. Version 1.1.7 is the current stable release, with an infrequent release cadence given its niche purpose. It stores data in JSON files, mimicking a simplified MongoDB-like API for basic CRUD operations (Create, Read, Update, Delete). Key differentiators include its extreme simplicity, zero external dependencies, and focus on providing a hands-on experience with NoSQL concepts without the overhead of a full database server. It is explicitly not recommended or suitable for production environments due to inherent limitations in scalability, concurrency handling, and data integrity guarantees. Its primary use case is isolated local data persistence for small projects or learning exercises.","status":"maintenance","version":"1.1.7","language":"javascript","source_language":"en","source_url":"https://github.com/dualB/local-nosql-db","tags":["javascript","local","database","nosql","json","storage","mongodb-like","typescript"],"install":[{"cmd":"npm install local-nosql-db","lang":"bash","label":"npm"},{"cmd":"yarn add local-nosql-db","lang":"bash","label":"yarn"},{"cmd":"pnpm add local-nosql-db","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { Database } = require('local-nosql-db');","symbol":"Database","correct":"import { Database } from 'local-nosql-db';"},{"note":"For older Node.js projects or environments where CommonJS modules are still in use.","wrong":"import { Database } from 'local-nosql-db';","symbol":"Database (CommonJS)","correct":"const { Database } = require('local-nosql-db');"},{"note":"Type import for documents, useful when working with TypeScript to define the structure of data stored in the database.","symbol":"IDocument","correct":"import type { IDocument } from 'local-nosql-db';"}],"quickstart":{"code":"import { Database } from 'local-nosql-db';\nimport * as path from 'path';\nimport * as fs from 'fs';\n\nconst dbPath = path.join(__dirname, 'local-db-data');\n\n// Ensure the database directory exists, or create it\nif (!fs.existsSync(dbPath)) {\n  fs.mkdirSync(dbPath, { recursive: true });\n}\n\nasync function runDbOperations() {\n  const db = new Database(dbPath);\n  await db.init(); // Initialize the database\n\n  const usersCollection = db.collection('users');\n\n  // 1. Insert a document\n  console.log('Inserting a new user...');\n  const newUser = await usersCollection.insert({\n    name: 'Alice Smith',\n    email: 'alice@example.com',\n    age: 30\n  });\n  console.log('Inserted user:', newUser);\n\n  // 2. Find documents\n  console.log('\\nFinding all users...');\n  const allUsers = await usersCollection.find({});\n  console.log('All users:', allUsers);\n\n  console.log('\\nFinding user by email...');\n  const foundUser = await usersCollection.findOne({ email: 'alice@example.com' });\n  console.log('Found user:', foundUser);\n\n  // 3. Update a document\n  if (foundUser && foundUser._id) {\n    console.log('\\nUpdating user age...');\n    const updatedUser = await usersCollection.update(\n      { _id: foundUser._id },\n      { $set: { age: 31, status: 'active' } }\n    );\n    console.log('Updated user:', updatedUser);\n  }\n\n  // 4. Delete a document\n  if (newUser && newUser._id) {\n    console.log('\\nDeleting the new user...');\n    const deleteResult = await usersCollection.delete({ _id: newUser._id });\n    console.log('Delete result:', deleteResult);\n  }\n\n  console.log('\\nFinal check of users after deletion:');\n  const remainingUsers = await usersCollection.find({});\n  console.log('Remaining users:', remainingUsers);\n\n  // Clean up the created data directory (optional)\n  // fs.rmSync(dbPath, { recursive: true, force: true });\n  // console.log('\\nDatabase directory cleaned up.');\n}\n\nrunDbOperations().catch(console.error);\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Translate any French error messages or log outputs using a translation tool to understand the underlying issue.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure you call `await db.init()` after creating a new `Database` instance and await its completion before any other database interactions.","cause":"Attempting to perform database operations (like accessing a collection) before calling the `init()` method on the `Database` instance.","error":"La base de données n'est pas initialisée. Veuillez appeler 'init()' avant d'effectuer des opérations."},{"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.","cause":"The provided path to the `Database` constructor is invalid, does not exist, or the application lacks the necessary file system permissions.","error":"Chemin de base de données non valide ou inaccessible."},{"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.","cause":"A collection's JSON data file has become corrupted or contains invalid JSON syntax, preventing the library from parsing it.","error":"Erreur de lecture du fichier JSON de la collection: [chemin/vers/fichier.json]. Le fichier est corrompu ou mal formé."}],"ecosystem":"npm"}