Registry / database / croxydb

croxydb

JSON →
library0.0.26jsnpmunverified

CroxyDB is a versatile JavaScript database module designed for Node.js environments, currently at version 0.0.26. It provides a straightforward API for managing data with support for various storage backends including JSON files (default), YAML files, and external MongoDB instances. The library offers a familiar key-value store interface with advanced features like dot notation for nested object access (e.g., `db.set("x.y.z", "value")`), array manipulation (`push`, `unpush`, `delByPriority`, `setByPriority`), and robust configuration options for file-based adapters. While in an early pre-1.0 development stage, CroxyDB aims for ease of use and flexibility, allowing developers to switch between local file storage and a remote NoSQL database like MongoDB using a simple adapter system. Its current release cadence appears to be driven by feature additions and bug fixes rather than a strict schedule, as indicated by recent updates like the enhanced `db.subtract` function.

npm install croxydb
INSTALL
IMPORT
SIG · CROXYDB
C
croxydb
databasejavascriptv0.0.26
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
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 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

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

db
✓ import db from 'croxydb'
✗ const { db } = require('croxydb')
CroxyDB exports a single object containing all database methods and configuration. For CommonJS, the correct import is `const db = require('croxydb')`. Attempting to destructure (`{ db }`) from the default export will result in an undefined `db`.
CroxyDBOptions
✓ import type { CroxyDBOptions } from 'croxydb'
This type interface defines the configuration options for CroxyDB, useful for advanced TypeScript usage, though the library does not export a class named 'CroxyDB'.
AdapterType
✓ import type { AdapterType } from 'croxydb'
This type alias represents the string literals for available database adapters (e.g., 'jsondb', 'yamldb', 'mongo'), providing type safety when calling `db.setAdapter` in TypeScript.

Demonstrates setting various global configuration options for the database, performing core data operations like setting and retrieving values (including nested paths), manipulating arrays, checking for key existence, and deleting data. The example highlights asynchronous operations common with database interactions.

import db from 'croxydb'; // Configure database options before first operation db.setReadable(true); // Makes the JSON DB file human-readable for easier inspection db.noBlankData(true); // Automatically removes parent objects if child properties are deleted and it becomes empty db.setAdapter("jsondb"); // Explicitly set default JSON adapter (optional, as it's default) db.setFolder("my_app_data"); // Set custom folder name for database files db.setFile("my_db"); // Set custom database file name (e.g., my_db.json) db.setCheckUpdates(true); // Enable warnings for new package updates async function runExample() { console.log('--- Initializing CroxyDB Example ---'); // Basic key-value operations with dot notation await db.set("user.profile.name", "Alice"); console.log('Set user name to Alice.'); console.log('Retrieved user name:', await db.get("user.profile.name")); // Output: Alice // Array manipulation await db.push("shoppingCart", "Milk"); await db.push("shoppingCart", "Bread"); console.log('Shopping cart:', await db.get("shoppingCart")); // Output: [ 'Milk', 'Bread' ] await db.unpush("shoppingCart", "Milk"); console.log('Shopping cart after removing Milk:', await db.get("shoppingCart")); // Output: [ 'Bread' ] // Check existence and delete operations console.log('Does user profile exist?', await db.has("user.profile")); // Output: true await db.delete("user.profile"); console.log('Does user profile exist after delete?', await db.has("user.profile")); // Output: false // View all data console.log('All data currently in DB:', await db.all()); // Output: { shoppingCart: [ 'Bread' ] } (if noBlankData is true) // Clean up all data await db.deleteAll(); console.log('All data after deleteAll:', await db.all()); // Output: {} console.log('--- CroxyDB Example Finished ---'); } runExample().catch(console.error);
Debug
Known issues
gotchaCroxyDB is in an early development stage (version 0.0.26). APIs may not be stable and could undergo breaking changes in minor or patch releases, especially as it approaches a 1.0 release. Users should pin exact versions to avoid unexpected issues.
fix
Pin the exact package version in your `package.json` (e.g., `"croxydb": "0.0.26"`) and review release notes carefully when updating to newer versions.
affects: <1.0.0
breakingIn version `0.0.26`, the `db.subtract` function's behavior was updated to allow values to reduce below zero. If your application previously relied on `subtract` clamping at zero (preventing negative values), this change will alter existing logic.
fix
Review all usages of `db.subtract`. If negative values are undesired, implement explicit checks (e.g., `if (newValue < 0) newValue = 0;`) after subtraction or before persisting the value.
affects: >=0.0.26
gotchaWhen using the MongoDB adapter (`db.setAdapter("mongo", ...)`), all database operations (e.g., `set`, `get`, `push`) become asynchronous and return Promises. Failing to `await` these operations will lead to unhandled promise rejections or inconsistent data state.
fix
Always use `await` with `db` methods when operating with the MongoDB adapter. It is good practice to `await` all `db` operations to ensure consistency, even with local file adapters that might technically be synchronous.
affects: *
gotchaThe primary support channel for CroxyDB is its Discord server. While this provides direct access to the developer and community, formal documentation or dedicated bug tracking might be less comprehensive, requiring reliance on community assistance for complex issues.
fix
Join the official Discord server for real-time support, to report bugs, and to stay updated. Implement robust error handling in your application to gracefully manage unexpected behaviors.
affects: *
Errors
Common errors & fixes
TypeError: db.set is not a function
This error typically occurs when the `croxydb` module is not correctly imported, or when attempting to use named imports that are not exported.
fix
Ensure you are importing the default export: `import db from 'croxydb'` for ESM or `const db = require('croxydb')` for CommonJS. Avoid destructuring the import.
MongoServerError: Authentication failed.
When using the MongoDB adapter, this indicates issues with the provided MongoDB connection URL, incorrect credentials (username/password), or network/firewall restrictions preventing access to the MongoDB server.
fix
Double-check the MongoDB connection URL for accuracy, including credentials. Verify the database user has the necessary permissions and that your server can establish a connection to the MongoDB host.
ENOENT: no such file or directory, open 'my_app_data/my_db.json'
When using local file adapters (JSON/YAML), this error means the specified folder or file path for the database does not exist, or the application lacks the necessary write permissions to create it.
fix
Ensure the directory specified by `db.setFolder()` exists or can be created by the application process. Verify file system permissions for the target directory to allow read and write access.
Upgrade
Version history
0.0.26latest on npm
Audit
Dependencies
mongodboptionalRequired as a peer dependency when using the 'mongo' adapter for database storage. Ensure it's installed alongside croxydb.
Agent activity
13 hits · last 30 days
node
10
OpenAI (training)
1
Resources
croxydb — npm install croxydb · libregistry