A simple, robust, and thread-safe CRUD library for managing JSON objects in files using Node.js.
- Simple API - Easy to use CRUD operations
- Thread-safe - Sequential operations with automatic queuing
- Auto-ID assignment - Automatic ID generation for new items (configurable)
- Unique Fields - Prevent duplicate values in specified fields ✨ New in v1.1
- Concurrent Operations - Thread-safe operations with automatic queuing
- Custom ID Fields - Use any field name as the primary key (default: 'id')
- Directory Creation - Automatically creates directories if they don't exist ✨ New in v1.1
- Convenience Functions - Helper functions for quick setup ✨ New in v1.1
- TypeScript Support - Full TypeScript definitions for IDE support ✨ New in v1.2
- Error Handling - Comprehensive error handling and detailed error messages
- Zero dependencies - Built with only Node.js built-in modules
- ESM support - Full ES modules support
npm install json-file-crud
import JsonFileCRUD, { createCrud } from 'json-file-crud';
// Standard usage
const db = new JsonFileCRUD('./data.json');
// Quick setup with convenience function
const db2 = createCrud('./users.json');
// Advanced configuration with unique fields
const userDb = new JsonFileCRUD('./users.json', {
uniqueFields: ['email', 'username'],
autoId: true
});
// Create a new item
db.create({ name: 'John', age: 30 }, (err, result) => {
if (err) {
console.error('Error:', err.message);
return;
}
console.log('Created:', result); // { name: 'John', age: 30, id: 1 }
});
// Read all items
db.readAll((err, items) => {
if (err) throw err;
console.log('All items:', items);
});
// Find by ID
db.findById(1, (err, item) => {
if (err) throw err;
console.log('Found:', item);
});
// Update an item
db.update(1, { age: 31 }, (err, updatedItem) => {
if (err) throw err;
console.log('Updated:', updatedItem);
});
// Delete an item
db.delete(1, (err, deletedItem) => {
if (err) throw err;
console.log('Deleted:', deletedItem);
});
Creates a new JsonFileCRUD instance.
filePath
(string): Path to the JSON file (directories will be created if they don't exist)options
(object, optional):idField
(string): Name of the ID field (default: 'id')uniqueFields
(array): Array of field names that must be unique (default: [])autoId
(boolean): Enable automatic ID assignment (default: true)
// Default settings
const db = new JsonFileCRUD('./data.json');
// Custom ID field
const products = new JsonFileCRUD('./products.json', { idField: 'productId' });
// Unique fields validation
const users = new JsonFileCRUD('./users.json', {
uniqueFields: ['email', 'username']
});
// Disable auto-ID
const manualDb = new JsonFileCRUD('./manual.json', { autoId: false });
// Deep directory path (automatically created)
const deepDb = new JsonFileCRUD('./data/nested/deep/file.json');
Quick way to create a JsonFileCRUD instance.
import { createCrud } from 'json-file-crud';
const db = createCrud('./data.json', { uniqueFields: ['email'] });
Creates a new item. Auto-assigns an ID if not provided.
item
(object): The item to createcallback
(function):(error, createdItem) => {}
db.create({ name: 'Alice', email: '[email protected]' }, (err, result) => {
// result: { name: 'Alice', email: 'alice@example.com', id: 1 }
});
Reads all items from the file.
callback
(function):(error, items) => {}
db.readAll((err, items) => {
// items: array of all items
});
Finds an item by its ID.
id
(any): The ID to search forcallback
(function):(error, item) => {}
db.findById(1, (err, item) => {
// item: the found item or null if not found
});
Finds items that match a filter function.
filterFunction
(function): Function that returns true for matching itemscallback
(function):(error, items) => {}
// Find all adults
db.findBy(item => item.age >= 18, (err, adults) => {
// adults: array of matching items
});
// Find by name
db.findBy(item => item.name === 'John', (err, johns) => {
// johns: array of items named John
});
Updates an existing item.
id
(any): The ID of the item to updatedata
(object): The data to update (merged with existing item)callback
(function):(error, updatedItem) => {}
db.update(1, { age: 25, city: 'New York' }, (err, updated) => {
// updated: the item with merged data
});
Deletes an item by ID.
id
(any): The ID of the item to deletecallback
(function):(error, deletedItem) => {}
db.delete(1, (err, deleted) => {
// deleted: the item that was removed
});
Deletes all items from the database.
callback
(function):(error) => {}
db.deleteAll((err) => {
if (err) throw err;
console.log('All items deleted');
});
Returns the total number of items.
callback
(function):(error, count) => {}
db.count((err, total) => {
console.log('Total items:', total);
});
Replaces all data in the file with a new array of items.
items
(array): Array of items to writecallback
(function):(error) => {}
const newData = [
{ name: 'Item 1', id: 1 },
{ name: 'Item 2', id: 2 }
];
db.writeAll(newData, (err) => {
if (!err) console.log('Data replaced successfully');
});
Prevent duplicate values in specified fields:
const userDb = new JsonFileCRUD('./users.json', {
uniqueFields: ['email', 'username']
});
// This will fail if email already exists
userDb.create({
name: 'John',
email: '[email protected]'
}, (err, user) => {
// err.message: "Item with email '[email protected]' already exists"
});
Disable automatic ID assignment:
const db = new JsonFileCRUD('./data.json', { autoId: false });
// No ID will be auto-generated
db.create({ name: 'Test' }, (err, item) => {
// item: { name: 'Test' } (no id field)
});
Automatically creates directories for deep paths:
// This will create ./data/users/ directories if they don't exist
const db = new JsonFileCRUD('./data/users/profiles.json');
For comprehensive examples, see the examples directory:
- Basic Usage - Simple CRUD operations
- Advanced Features - Concurrent operations, filtering, custom ID fields
- User Management - Real-world application with unique fields validation
// Basic usage with unique fields
import JsonFileCRUD, { createCrud } from 'json-file-crud';
const userDb = createCrud('./users.json', {
uniqueFields: ['email', 'username']
});
// Delete all users
userDb.deleteAll((err) => {
console.log('All users deleted');
});
// Example with auto-ID disabled
const manualDb = new JsonFileCRUD('./manual.json', { autoId: false });
manualDb.create({ name: 'Test' }, (err, item) => {
// item: { name: 'Test' } (no auto-generated ID)
});
To run examples:
npm run examples
# or individually:
node examples/basic-usage.js
Type definitions are provided via lib/json-file-crud.d.ts
so the library can be used comfortably in TypeScript projects with autocompletion and compile-time checks.
JsonFileCRUD stores data as a JSON array in the specified file:
[
{ "id": 1, "name": "John", "age": 30 },
{ "id": 2, "name": "Jane", "age": 25 }
]
If the file doesn't exist, it will be created automatically on the first write operation.
- Small to medium datasets: JsonFileCRUD is ideal for applications with up to ~10,000 items
- File I/O: Every operation reads/writes the entire file, so performance scales with file size
- Memory usage: The entire dataset is loaded into memory during operations
- Concurrent access: Operations are queued, so high-concurrency scenarios may experience delays
For larger datasets or high-performance requirements, consider using a dedicated database.
Contributions are welcome! Here are some ways you can help improve JsonFileCRUD:
- Async/Await Support: Add Promise-based API alongside callbacks
- Batch Operations: Add bulk insert/update/delete operations
- File Locking: Add file locking for multi-process safety
- Enhanced Documentation: Improve documentation and add more examples
- Fork the Repository: Create your own fork of the project
- Create a Feature Branch:
git checkout -b feature/your-feature-name
- Write Tests: Ensure your changes are well-tested
- Follow Code Style: Keep the code clean and consistent
- Update Documentation: Add or update relevant documentation
- Submit a Pull Request: Describe your changes clearly
MIT License - see LICENSE file for details.