A simple, robust, and thread-safe CRUD library for managing JSON objects in files using Node.js.
- Simple API - Easy to use CRUD operations
- Promise/Async Support - Full async/await API alongside callback methods ✨ New in v1.3
- 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-crudimport 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);
});// Same operations using async/await
try {
const user = await db.createAsync({ name: 'John', age: 30 });
console.log('Created:', user);
const foundUser = await db.findByIdAsync(user.id);
console.log('Found:', foundUser);
const updatedUser = await db.updateAsync(user.id, { age: 31 });
console.log('Updated:', updatedUser);
const deletedUser = await db.deleteAsync(user.id);
console.log('Deleted:', deletedUser);
} catch (error) {
console.error('Error:', error.message);
}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: 'alice@example.com' }, (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');
});All methods have async counterparts that return Promises. Simply add Async to the method name:
All callback methods have async counterparts. Add Async to the method name:
// Using async/await
try {
const user = await db.createAsync({ name: 'John', age: 30 });
const allUsers = await db.readAllAsync();
const foundUser = await db.findByIdAsync(user.id);
const updatedUser = await db.updateAsync(user.id, { age: 31 });
await db.deleteAsync(user.id);
} catch (error) {
console.error('Operation failed:', error.message);
}
// Using Promises
db.createAsync({ name: 'Jane', age: 25 })
.then(user => db.findByIdAsync(user.id))
.then(foundUser => console.log('Found:', foundUser))
.catch(error => console.error('Error:', error.message));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: 'john@example.com'
}, (err, user) => {
// err.message: "Item with email 'john@example.com' 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
- Async/Await Demo - Promise-based API usage with async/await
// 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.jsType 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:
- 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.