{"id":16322,"library":"csv-database","title":"csv-database","description":"csv-database is a lightweight Node.js library offering a complete CRUD (Create, Read, Update, Delete) API, utilizing CSV files for data storage. Built with TypeScript and leveraging async/await, it provides native JavaScript object interaction, allowing developers to query and manipulate data using familiar object predicates. As of version 0.9.2, it is in active development, with a focus on stability for its upcoming 1.0 release. Key differentiators include its strong TypeScript typings, built-in model validation, and a focus on being \"concurrency-ready\" for file operations. It's designed for applications requiring simple, local data persistence without the overhead of a full relational or NoSQL database, making it suitable for smaller projects or configuration storage.","status":"active","version":"0.9.2","language":"javascript","source_language":"en","source_url":"https://github.com/ysnglt/node-csvdb","tags":["javascript","csv","database","db","crud","storage","flat file","file"],"install":[{"cmd":"npm install csv-database","lang":"bash","label":"npm"},{"cmd":"yarn add csv-database","lang":"bash","label":"yarn"},{"cmd":"pnpm add csv-database","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary `csvdb` function is a default export, not a named export. Ensure you import without curly braces.","wrong":"import { csvdb } from 'csv-database';","symbol":"csvdb","correct":"import csvdb from 'csv-database';"},{"note":"When using CommonJS `require` with an ES module's default export, you must explicitly access the `.default` property.","wrong":"const csvdb = require('csv-database');","symbol":"csvdb","correct":"const csvdb = require('csv-database').default;"},{"note":"The `CsvDatabase` interface/type for the returned database instance is a named export, typically used alongside the default `csvdb` function for type hinting in TypeScript.","wrong":"import { CsvDatabase } from 'csv-database';","symbol":"CsvDatabase","correct":"import csvdb, { CsvDatabase } from 'csv-database';"}],"quickstart":{"code":"import csvdb, { CsvDatabase } from 'csv-database';\nimport path from 'path';\nimport fs from 'fs/promises';\n\ninterface User {\n  id: number;\n  name: string;\n  mail: string;\n}\n\nasync function main() {\n  const filename = path.join(__dirname, 'users.csv');\n  // Ensure the file exists (or is created) and cleanup for demo\n  try { await fs.unlink(filename); } catch (e) { /* ignore */ }\n\n  const db: CsvDatabase<User> = await csvdb<User>(filename, ['id', 'name', 'mail']);\n\n  console.log('Database initialized.');\n\n  // Add data\n  await db.add([{ id: 1, name: 'johndoe', mail: 'john@example.com' }]);\n  await db.add({ id: 2, name: 'janedoe', mail: 'jane@example.com' });\n  console.log('Added two users.');\n\n  // Get all data\n  const allUsers = await db.get();\n  console.log('All users:', allUsers);\n\n  // Get data with predicate\n  const john = await db.get({ name: 'johndoe' });\n  console.log('John Doe:', john);\n\n  // Edit data\n  await db.edit({ name: 'johndoe' }, { mail: 'john.doe@newmail.com' });\n  const updatedJohn = await db.get({ id: 1 });\n  console.log('Updated John:', updatedJohn);\n\n  // Delete data\n  await db.delete({ id: 2 });\n  const remainingUsers = await db.get();\n  console.log('Remaining users after delete:', remainingUsers);\n\n  // Clean up the created file\n  await fs.unlink(filename);\n  console.log('Cleaned up users.csv');\n}\n\nmain().catch(console.error);","lang":"typescript","description":"This quickstart demonstrates how to initialize a CSV database, add, retrieve, edit, and delete records, and clean up the created file."},"warnings":[{"fix":"Initialize the database with the desired delimiter: `const db = await csvdb(\"users.csv\", [\"id\",\"name\",\"mail\"], \",\");`","message":"The default delimiter used by `csv-database` is a semicolon (`;`), not the more common comma (`,`). If your CSV files use commas, you must explicitly specify the delimiter during database initialization.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure all keys in your predicate objects exactly match one of the fields defined in your database model. For example, if your model is `['id', 'name']`, a predicate `{ userID: 1 }` will fail.","message":"Predicates used in `get`, `edit`, and `delete` operations are strictly validated against the database's model. Providing a field in the predicate that is not defined in the model will result in an error.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Monitor the project's GitHub repository or release notes for upcoming changes, especially when upgrading between minor versions. Consider pinning to a specific minor version for production deployments (`~0.9.2` instead of `^0.9.2`).","message":"As `csv-database` is currently below version 1.0 (e.g., 0.9.2), its API may not be fully stable. Minor versions could introduce breaking changes as the library matures towards its stable release.","severity":"gotcha","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":"Review your database model definition and ensure all predicate keys exactly match a field in the model. E.g., if model is `['id', 'name']`, use `{ id: 1 }` not `{ userID: 1 }`.","cause":"Attempting to use a key in a predicate object (for `get`, `edit`, `delete`) that is not defined in the CSV database's model array.","error":"Error: Field 'unknownField' is not part of the model."},{"fix":"Ensure you `await` the `csvdb` call (e.g., `const db = await csvdb(...)`). If using CommonJS, use `const csvdb = require('csv-database').default;`.","cause":"This usually occurs if `await` is missing when calling `csvdb` (it returns a Promise), or if using `require` without `.default` for a default ES module export.","error":"TypeError: csvdb is not a function"},{"fix":"Check the permissions of the directory where the CSV file is located. Ensure the user running the Node.js application has read/write/delete access to that directory.","cause":"The Node.js process does not have the necessary file system permissions to create, read, write, or delete the specified CSV file.","error":"Error: EACCES: permission denied, unlink 'path/to/your/file.csv'"}],"ecosystem":"npm"}