CroxyDB

Common errors

• TypeError: db.set is not a function

  cause 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.

  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.
  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'

  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.
  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.

Warnings

• gotcha 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install croxydb npm
• yarn add croxydb yarn
• pnpm add croxydb pnpm

Imports

• db
  wrong:

  const { db } = require('croxydb')

  correct:

  import db from '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.

Quickstart

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);