{"id":16612,"library":"croxydb","title":"CroxyDB","description":"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.","status":"active","version":"0.0.26","language":"javascript","source_language":"en","source_url":"https://github.com/croxydeveloper/croxydb","tags":["javascript","croxy","croxy-api","croxyapi","croxydb","croxy-db","json","jsondb","yaml","typescript"],"install":[{"cmd":"npm install croxydb","lang":"bash","label":"npm"},{"cmd":"yarn add croxydb","lang":"bash","label":"yarn"},{"cmd":"pnpm add croxydb","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency when using the 'mongo' adapter for database storage. Ensure it's installed alongside croxydb.","package":"mongodb","optional":true}],"imports":[{"note":"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`.","wrong":"const { db } = require('croxydb')","symbol":"db","correct":"import db from 'croxydb'"},{"note":"This type interface defines the configuration options for CroxyDB, useful for advanced TypeScript usage, though the library does not export a class named 'CroxyDB'.","symbol":"CroxyDBOptions","correct":"import type { CroxyDBOptions } from 'croxydb'"},{"note":"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.","symbol":"AdapterType","correct":"import type { AdapterType } from 'croxydb'"}],"quickstart":{"code":"import db from 'croxydb';\n\n// Configure database options before first operation\ndb.setReadable(true); // Makes the JSON DB file human-readable for easier inspection\ndb.noBlankData(true); // Automatically removes parent objects if child properties are deleted and it becomes empty\ndb.setAdapter(\"jsondb\"); // Explicitly set default JSON adapter (optional, as it's default)\ndb.setFolder(\"my_app_data\"); // Set custom folder name for database files\ndb.setFile(\"my_db\"); // Set custom database file name (e.g., my_db.json)\ndb.setCheckUpdates(true); // Enable warnings for new package updates\n\nasync function runExample() {\n  console.log('--- Initializing CroxyDB Example ---');\n  // Basic key-value operations with dot notation\n  await db.set(\"user.profile.name\", \"Alice\");\n  console.log('Set user name to Alice.');\n  console.log('Retrieved user name:', await db.get(\"user.profile.name\")); // Output: Alice\n\n  // Array manipulation\n  await db.push(\"shoppingCart\", \"Milk\");\n  await db.push(\"shoppingCart\", \"Bread\");\n  console.log('Shopping cart:', await db.get(\"shoppingCart\")); // Output: [ 'Milk', 'Bread' ]\n  await db.unpush(\"shoppingCart\", \"Milk\");\n  console.log('Shopping cart after removing Milk:', await db.get(\"shoppingCart\")); // Output: [ 'Bread' ]\n\n  // Check existence and delete operations\n  console.log('Does user profile exist?', await db.has(\"user.profile\")); // Output: true\n  await db.delete(\"user.profile\");\n  console.log('Does user profile exist after delete?', await db.has(\"user.profile\")); // Output: false\n\n  // View all data\n  console.log('All data currently in DB:', await db.all()); // Output: { shoppingCart: [ 'Bread' ] } (if noBlankData is true)\n\n  // Clean up all data\n  await db.deleteAll();\n  console.log('All data after deleteAll:', await db.all()); // Output: {}\n  console.log('--- CroxyDB Example Finished ---');\n}\n\nrunExample().catch(console.error);\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"CroxyDB 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.","severity":"gotcha","affected_versions":"<1.0.0"},{"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.","message":"In 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.","severity":"breaking","affected_versions":">=0.0.26"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"*"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"This error typically occurs when the `croxydb` module is not correctly imported, or when attempting to use named imports that are not exported.","error":"TypeError: db.set is not a function"},{"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.","cause":"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.","error":"MongoServerError: Authentication failed."},{"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.","cause":"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.","error":"ENOENT: no such file or directory, open 'my_app_data/my_db.json'"}],"ecosystem":"npm"}