About json-file is a Node.js library for working with JSON files in the JSON Lines format. It provides a simple API for adding, updating, deleting, and querying data in JSONL files.
npm install jsonl-dbSimple, lightweight database alternative using JSON files
Stop over-engineering your projects! jsonl-db gives you a database-like experience using simple JSON files. Perfect for prototypes, small projects, or when you just need to get things done quickly without the complexity of traditional databases.
- ๐ Get started in seconds - No setup, no configuration, no complex schemas
- ๐ Uses familiar JSON files - Your data stays in human-readable format
- โก Zero dependencies - Lightweight and fast
- ๐ Full CRUD operations - Add, read, update, delete with simple methods
- ๐ Powerful querying - Search and filter your data easily
- ๐ก Perfect for - Prototypes, small apps, data processing, testing, learning
JSONL (JSON Lines) is a simple format where each line contains a valid JSON object. Think of it as a database table where each row is a JSON object on its own line.
Example:
``jsonl`
{"id": 1, "name": "Alice", "age": 25}
{"id": 2, "name": "Bob", "age": 30}
{"id": 3, "name": "Charlie", "age": 28}
Benefits:
- โ
Easy to read and debug
- โ
Simple to append new records
- โ
No complex parsing needed
- โ
Works with standard text tools
- โ
Human-editable
bash
npm install jsonl-db
`$3
`javascript
import { jsonlDir } from "jsonl-db";// Create a database directory
const db = jsonlDir("./data");
// Create a users collection
const users = db.file("users");
// Add a user
await users.add({ name: "John", age: 27, email: "john@example.com" });
// Find a user
const john = await users.findOne(user => user.name === "John");
// Update a user
const updatedUsers = await users.update(
user => user.name === "John",
user => ({ ...user, age: 28 })
);
// Delete a user
const remainingUsers = await users.delete(user => user.name === "John");
`Core Features โจ
$3
- โ Add - Single records or batches
- ๐ Read - Find first match or all matches
- ๐ Update - By condition with custom logic
- โ Delete - Specific records with conditions$3
- ๐ Find - First match or all matches
- ๐ Count - Total records in collection
- โก Fast Access - Efficient batch processing
- ๐ฏ Flexible - Custom conditions and filters$3
- ๐ Auto-create - Files created automatically
- ๐๏ธ Organized - Directory-based structure
- ๐พ Persistent - Data survives restartsReal-World Examples ๐
$3
`javascript
const db = jsonlDir("./data");
const users = db.file("users");// Add multiple users
await users.add([
{ id: 1, name: "Alice", role: "admin" },
{ id: 2, name: "Bob", role: "user" },
{ id: 3, name: "Charlie", role: "user" }
]);
// Find all admins
const admins = await users.find(user => user.role === "admin");
// Count total users
const userCount = await users.count();
`$3
`javascript
const db = jsonlDir("./logs");
const appLogs = db.file("app");// Add log entry
await appLogs.add({
timestamp: new Date().toISOString(),
level: "info",
message: "User logged in",
userId: 123
});
// Get recent logs
const recentLogs = await appLogs.find(log =>
new Date(log.timestamp) > new Date(Date.now() - 24 60 60 * 1000)
);
`$3
`javascript
const db = jsonlDir("./config");
const settings = db.file("app-settings");// Store settings
await settings.add({ key: "theme", value: "dark" });
await settings.add({ key: "language", value: "en" });
// Get setting
const theme = await settings.findOne(setting => setting.key === "theme");
`$3
`javascript
const db = jsonlDir("./app-data");// Different collections for different entities
const users = db.file("users");
const products = db.file("products");
const orders = db.file("orders");
// Work with users
await users.add({ name: "John", email: "john@example.com" });
// Work with products
await products.add({ name: "Laptop", price: 999.99 });
// Work with orders
await orders.add({ userId: 1, productId: 1, quantity: 2 });
`When to Use jsonl-db ๐ฏ
Perfect for:
- ๐ Prototypes - Get your idea working fast
- ๐ฑ Small apps - Personal projects, simple tools
- ๐งช Testing - Mock data, test scenarios
- ๐ Data processing - ETL jobs, data analysis
- ๐ Learning - Understand database concepts
- ๐ง Configuration - App settings, user preferences
Consider alternatives when:
- ๐ Large datasets - Millions of records
- ๐ฅ Multiple users - Concurrent access needed
- ๐ Complex security - Advanced permissions required
- ๐ High performance - Sub-millisecond queries needed
Requirements โ๏ธ
- Node.js v22 or higher
Multiple formats available for different environments:
- ESM (
.js) - Modern ES modules
- CommonJS (.cjs) - Traditional Node.js
- TypeScript (.d.ts) - Full type supportAPI Reference ๐
$3
#### Creating a Database
`javascript
import { jsonlDir } from "jsonl-db";// Create a database in a directory
const db = jsonlDir("./data");
// Create collections (files) for different entities
const users = db.file("users");
const products = db.file("products");
`#### Adding Data
`javascript
// Single record
await users.add({ name: "John", age: 27 });// Multiple records
await users.add([
{ name: "John", age: 27 },
{ name: "Jane", age: 31 }
]);
`#### Reading Data
`javascript
// Find first match
const user = await users.findOne(user => user.name === "John");// Find all matches
const adults = await users.find(user => user.age >= 18);
// Count total records
const total = await users.count();
`#### Updating Data
`javascript
// Update with custom logic
const updatedUsers = await users.update(
user => user.age > 30,
user => ({ ...user, isSenior: true })
);
`#### Deleting Data
`javascript
// Delete with condition
const remainingUsers = await users.delete(user => user.age > 100);
`Contributing ๐ค
We love contributions! Here's how to help:
1. Fork the repository
2. Create a feature branch:
git checkout -b my-feature
3. Make your changes and add tests
4. Test everything: npm test`MIT License - feel free to use in any project!
---
Ready to simplify your data storage? Start with jsonl-db and focus on building features, not database complexity! ๐