Registry / database / a1-database

a1-database

JSON →
library1.8.0jsnpmunverified

a1-database is an embedded, zero-dependency, zero-installation JSON database designed for simplicity and portability. As of version 1.8.0, it stores all data in a single file, making it ideal for development, local applications, or scenarios where a lightweight, persistent data store is required without external database server overhead. It operates directly on JavaScript objects, eliminating the need for an ORM, and returns query results as arrays of objects. The package provides methods that cater to both SQL-like (e.g., `insert`, `update` with `id` keys) and document-like (flexible `save` with custom filter functions for multi-key or heterogeneous data) paradigms. Each database instance is represented by a single file, facilitating easy backup and data dumping. Its primary release cadence is not explicitly stated, but ongoing development is implied by the version number, focusing on a straightforward API for common CRUD operations like `save`, `find`, and `delete`.

npm install a1-database
INSTALL
IMPORT
SIG · A1-DATABASE
A
a1-database
databasejavascriptv1.8.0
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.

database
const database = require('a1-database')
import database from 'a1-database'
A1-database is primarily designed for CommonJS. Direct ESM `import` might not be supported without specific Node.js configuration (e.g., 'type: module' in package.json) or transpilation.

Demonstrates database connection, saving data (including upsert behavior with IDs), finding records, checking existence, and deleting entries, along with proper cleanup of the database file.

const database = require('a1-database'); const fs = require('fs/promises'); // For cleanup async function runExample() { const dbPath = 'users.db'; try { // Ensure cleanup of previous runs for a fresh start try { await fs.unlink(dbPath); } catch (e) { /* ignore if file doesn't exist */ } const db = await database.get(dbPath); console.log('Database connected to', dbPath); // Save initial data await db.save({ name: 'Juan', email: 'juan@example.com' }); await db.save({ name: 'Maria', email: 'maria@example.com' }); console.log('Initial users saved.'); // Save with an ID, demonstrating upsert behavior await db.save([{ id: 100, value: 'old test data' }]); console.log('Saved item with id 100 (old).'); await db.save([{ id: 100, value: 'new test data', timestamp: Date.now() }]); // item with id, so old items are removed console.log('Saved item with id 100 (new), overwriting old data.'); // Find operations const juan = await db.findOne(el => el.name === 'Juan'); console.log('Found Juan:', juan); const allUsers = await db.find(el => el.name === 'Juan' || el.name === 'Maria'); console.log('Found all initial users:', allUsers); // Demonstrate existence check const existsJuan = await db.exists(el => el.name === 'Juan'); console.log('Does Juan exist?', !!existsJuan); // Delete operation const deletedCount = await db.delete(el => el.email === 'maria@example.com'); console.log(`Deleted ${deletedCount} user(s).`); const remainingUsers = await db.find(el => true); console.log('Remaining items after delete:', remainingUsers); // Disconnect from the database await database.disconnect(db); console.log('Database disconnected.'); } catch (error) { console.error('An error occurred:', error); } finally { // Optional: Clean up the database file after the example try { await fs.unlink(dbPath); } catch (e) { /* ignore */ } console.log('Cleaned up database file.'); } } runExample().catch(console.error);
Debug
Known issues
gotchaDatabase file paths are resolved relative to `process.CWD()` (Current Working Directory) where the Node.js process was started, not relative to the JavaScript file where `a1-database` is instantiated. This can lead to unexpected file locations if not explicitly managed.
fix
Always use absolute paths or carefully manage the current working directory to ensure the database file is created and accessed in the intended location.
affects: >=1.0.0
gotchaThe `save` method automatically updates existing items if an `id` property is present in the item(s) being saved, acting as an upsert. For items without an `id` or when using a custom `filter` function, `save` will append new items or replace items matching the filter, requiring careful filter definition to prevent unintended duplicates or data loss.
fix
When using `save`, be explicit about providing `id` for upserts, or define precise filter functions to control replacement behavior. Use `insert` for strict 'add-only' semantics.
affects: >=1.0.0
gotchaThe `insert` method enforces uniqueness based on the `id` field. Attempting to `insert` an item with an `id` that already exists in the database will throw an error, unlike `save` which overwrites. Developers should choose `insert` for strict 'no-duplicate-ID' policies and `save` for 'upsert' behavior.
fix
If an item might already exist, use `save` if overwriting is acceptable. If strict uniqueness is required for new entries, use `insert` and wrap calls in a `try...catch` block to handle potential duplicate ID errors.
affects: >=1.0.0
gotchaAs a file-based embedded database, `a1-database` performs disk I/O for every write operation. While suitable for many use cases, high-frequency write operations or very large datasets may experience performance bottlenecks compared to in-memory or server-based databases. Automatic compaction is triggered every 10,000 consecutive save/delete operations.
fix
For high-throughput applications, consider batching writes or evaluating if an in-memory or server-based database is more appropriate. Monitor disk I/O metrics if performance becomes a concern.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Item with ID [ID_VALUE] already exists.
This error occurs when attempting to use `db.insert()` with an item whose `id` field matches an existing record in the database.
fix
To fix this, either ensure that the `id` is unique before calling `db.insert()`, or use `db.save()` instead if the intention is to update/overwrite the existing item with the same `id`.
Upgrade
Version history
1.8.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
54 hits · last 30 days
node
48
OpenAI (training)
1
Resources
a1-database — npm install a1-database · libregistry