Registry / database / csv-database

csv-database

JSON →
library0.9.2jsnpmunverified

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.

npm install csv-database
INSTALL
IMPORT
SIG · CSV-DATABASE
C
csv-database
databasejavascriptv0.9.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

csvdb
import csvdb from 'csv-database';
import { csvdb } from 'csv-database';
The primary `csvdb` function is a default export, not a named export. Ensure you import without curly braces.
csvdb
const csvdb = require('csv-database').default;
const csvdb = require('csv-database');
When using CommonJS `require` with an ES module's default export, you must explicitly access the `.default` property.
CsvDatabase
import csvdb, { CsvDatabase } from 'csv-database';
import { CsvDatabase } from 'csv-database';
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.

This quickstart demonstrates how to initialize a CSV database, add, retrieve, edit, and delete records, and clean up the created file.

import csvdb, { CsvDatabase } from 'csv-database'; import path from 'path'; import fs from 'fs/promises'; interface User { id: number; name: string; mail: string; } async function main() { const filename = path.join(__dirname, 'users.csv'); // Ensure the file exists (or is created) and cleanup for demo try { await fs.unlink(filename); } catch (e) { /* ignore */ } const db: CsvDatabase<User> = await csvdb<User>(filename, ['id', 'name', 'mail']); console.log('Database initialized.'); // Add data await db.add([{ id: 1, name: 'johndoe', mail: 'john@example.com' }]); await db.add({ id: 2, name: 'janedoe', mail: 'jane@example.com' }); console.log('Added two users.'); // Get all data const allUsers = await db.get(); console.log('All users:', allUsers); // Get data with predicate const john = await db.get({ name: 'johndoe' }); console.log('John Doe:', john); // Edit data await db.edit({ name: 'johndoe' }, { mail: 'john.doe@newmail.com' }); const updatedJohn = await db.get({ id: 1 }); console.log('Updated John:', updatedJohn); // Delete data await db.delete({ id: 2 }); const remainingUsers = await db.get(); console.log('Remaining users after delete:', remainingUsers); // Clean up the created file await fs.unlink(filename); console.log('Cleaned up users.csv'); } main().catch(console.error);
Debug
Known issues
gotchaThe 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.
fix
Initialize the database with the desired delimiter: `const db = await csvdb("users.csv", ["id","name","mail"], ",");`
affects: >=0.1.0
gotchaPredicates 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.
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.
affects: >=0.1.0
gotchaAs `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.
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`).
affects: <1.0.0
Errors
Common errors & fixes
Error: Field 'unknownField' is not part of the model.
Attempting to use a key in a predicate object (for `get`, `edit`, `delete`) that is not defined in the CSV database's model array.
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 }`.
TypeError: csvdb is not a function
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.
fix
Ensure you `await` the `csvdb` call (e.g., `const db = await csvdb(...)`). If using CommonJS, use `const csvdb = require('csv-database').default;`.
Error: EACCES: permission denied, unlink 'path/to/your/file.csv'
The Node.js process does not have the necessary file system permissions to create, read, write, or delete the specified CSV file.
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.
Upgrade
Version history
0.9.2latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
15 hits · last 30 days
node
14
OpenAI (training)
1
Resources
csv-database — npm install csv-database · libregistry