Wio.db

Common errors

• ReferenceError: require is not defined

  cause Attempting to use CommonJS `require()` syntax in an ECMAScript Module (ESM) file (e.g., a `.mjs` file or a project with `"type": "module"` in `package.json`).
  fix Change your import statement to use ESM syntax: `import { JsonDatabase, YamlDatabase } from 'wio.db';`

• TypeError: JsonDatabase is not a constructor

  cause You are calling `JsonDatabase()` or `YamlDatabase()` without the `new` keyword.
  fix Always instantiate database classes with `new`: `const db = new JsonDatabase({ databasePath: './data.json' });`

• Error: Database path is required

  cause The `databasePath` option was omitted or left undefined when initializing `JsonDatabase` or `YamlDatabase`.
  fix Provide a valid string path for your database file: `const db = new JsonDatabase({ databasePath: './my-database.json' });`

Warnings

• gotcha Wio.db requires Node.js version 12 or greater to function correctly. Running on older Node.js versions may lead to unexpected errors or stability issues.
  Fix: Upgrade your Node.js installation to version 12 or higher. For example, using nvm: `nvm install 16 && nvm use 16`.
• breaking The `<db>.arrayHasValue` method has been removed in Wio.db v4. This functionality is no longer available.
  Fix: Migrate your code to use alternative array manipulation methods or implement custom logic to check for array values. Consider using `<db>.pull` with a custom filter function or `<db>.get` and manual array iteration.
• breaking The static property `JsonDatabase.DBCollection` has been removed in Wio.db v4. This property is no longer accessible.
  Fix: Review your code for any reliance on `JsonDatabase.DBCollection`. This property was internal and its removal indicates a refactoring of how database collections are managed. You may need to adapt your application logic if you were directly accessing it.
• breaking The `<db>.totalDBSize` property has been removed in Wio.db v4. You can no longer directly access the total database size via this property.
  Fix: Utilize the new `<db>.info` property to get database statistics, which may include size-related information. If specific size metrics are required, you might need to calculate them manually based on the database file's size or content.

Install

• npm install wio.db npm
• yarn add wio.db yarn
• pnpm add wio.db pnpm

Imports

• JsonDatabase
  wrong:

  import wiodb from 'wio.db'; // No default export

  correct:

  import { JsonDatabase } from 'wio.db';

  For ESM environments and TypeScript. Wio.db primarily exports named classes.
• YamlDatabase
  wrong:

  const YamlDatabase = require('wio.db').YamlDatabase; // Direct access is less idiomatic for multiple exports

  correct:

  const { YamlDatabase } = require('wio.db');

  For CommonJS environments. Destructuring is the standard approach.
• All exports
  wrong:

  import { Database } from 'wio.db'; // 'Database' is not an exported symbol

  correct:

  import { JsonDatabase, YamlDatabase } from 'wio.db';

  Ensure you are importing the specific named classes provided by the library.

Quickstart

This quickstart demonstrates how to initialize JSON and YAML database instances, perform common data operations like setting, getting, checking existence, pushing to arrays, performing math operations, retrieving all data, and deleting entries, using both JSON and YAML databases.

import { JsonDatabase, YamlDatabase } from 'wio.db';

// Initialize a JSON database instance
const db = new JsonDatabase({
  databasePath: './databases/myJsonDatabase.json'
});

// Initialize a YAML database instance
const yamldb = new YamlDatabase({
  databasePath: './databases/myYamlDatabase.yml'
});

// --- JSON Database Operations ---

// Set a value
db.set('user_settings.theme', 'dark');
console.log("Set 'user_settings.theme' to 'dark'");

// Get a value
const theme = db.get('user_settings.theme');
console.log(`Retrieved theme: ${theme}`); // Expected: dark

// Check if a key exists
const hasSetting = db.has('user_settings.theme');
console.log(`Does 'user_settings.theme' exist? ${hasSetting}`); // Expected: true

// Push to an array
db.push('recent_logins', 'user123');
db.push('recent_logins', 'admin456');
console.log(`Recent logins: ${db.get('recent_logins')}`); // Expected: [ 'user123', 'admin456' ]

// Add a number
db.add('user_points', 100);
db.add('user_points', 50);
console.log(`User points: ${db.get('user_points')}`); // Expected: 150

// Get all data (top 5 entries)
const allData = db.all(5);
console.log('All JSON DB data (top 5):', allData);

// Delete a key
db.delete('user_settings.theme');
console.log("Deleted 'user_settings.theme'");
console.log(`Does 'user_settings.theme' exist after delete? ${db.has('user_settings.theme')}`); // Expected: false

// Get DB info
console.log('JSON DB Info:', db.info);

// --- YAML Database Operations (similar) ---
yamldb.set('config.port', 3000);
console.log(`YAML config port: ${yamldb.get('config.port')}`);

// To destroy databases and clean up files (uncomment to run)
// db.destroy();
// yamldb.destroy();