KiritoDB Remote Database

Common errors

• Error: Sua chave secreta está faltando ou é inválida.

  cause The `KiritoDB` constructor was called without providing a valid secret API key, or the provided key was empty/invalid.
  fix Ensure you provide your secret key as a non-empty string when initializing: `new KiritoDB('your_secret_key')`. Validate the key's correctness.

• TypeError: Cannot read properties of undefined (reading 'someProperty')

  cause Attempting to access a property on an `undefined` value, commonly occurring when `await` is omitted for an asynchronous operation like `db.get()` or `db.all()`, causing the code to operate on a pending Promise instead of the resolved data.
  fix Always use `await` before calls to `db.get()` and `db.all()` to ensure the Promise resolves and returns the actual data before further processing.

• Error: O valor atual da chave 'users.1234.score' não é um número.

  cause The `add` or `sub` method was invoked on a key (`users.1234.score` in this example) whose currently stored value is not a number, such as a string, object, or array.
  fix Confirm that the target key exclusively stores numeric values before using `db.add()` or `db.sub()`. Consider initializing keys with a numeric default if they might be empty, or validating the type before performing arithmetic operations.

Warnings

• breaking The `add` and `sub` methods are strictly designed for numeric values. Attempting to use them on keys where the stored value is a non-numeric data type (such as strings, objects, or arrays) will result in a runtime error and the operation will fail.
  Fix: Before using `add` or `sub`, ensure that the target key's value is, and remains, a number. Initialize numeric keys with a default number (e.g., 0) if they might not exist to prevent type errors.
• gotcha The `get` and `all` methods return Promises, indicating asynchronous operations. It is crucial to use the `await` keyword with these calls to correctly retrieve the resolved data. Failing to `await` will result in working with a pending Promise object instead of the actual value from the database.
  Fix: Always prepend `await` when invoking `db.get('key')` or `db.all()` within an `async` function to ensure the operation completes and returns the expected data.
• breaking A secret API key is a mandatory requirement for initializing `KiritoDB`. The library will not function correctly, and database operations will fail, if a valid key is not provided to the `KiritoDB` constructor.
  Fix: Obtain a valid secret API key from the KiritoDB service and pass it as the first argument to `new KiritoDB('your_secret_key')`. Ensure this key is kept secure and not exposed publicly.
• gotcha The documentation for the `set` method contains contradictory information regarding its support for complex data types. While one statement claims it 'accepts any type of value' (string, number), a direct warning immediately follows, stating 'If the value is an array or object, it will cause an error.' Developers should proceed with caution and assume that directly setting arrays or objects might lead to issues.
  Fix: For maximum compatibility and reliability, prefer setting primitive types (strings, numbers, booleans) directly. If complex data structures like arrays or objects must be stored, consider serializing them into JSON strings (e.g., `JSON.stringify(value)`) before storing and deserializing upon retrieval (e.g., `JSON.parse(retrievedValue)`).

Install

• npm install kirito.db.remote npm
• yarn add kirito.db.remote yarn
• pnpm add kirito.db.remote pnpm

Imports

• KiritoDB

  const { KiritoDB } = require("kirito.db.remote")

  KiritoDB is the main class exported by the library, used for all database interactions. The official documentation exclusively uses CommonJS `require` syntax for importing.

Quickstart

Demonstrates initializing KiritoDB, setting and getting data for various keys, performing numeric addition and subtraction, retrieving all stored data, and deleting specific keys. Requires setting `KIRITO_DB_SECRET_KEY` environment variable.

const { KiritoDB } = require("kirito.db.remote");

async function run() {
  const secretKey = process.env.KIRITO_DB_SECRET_KEY ?? '';
  if (!secretKey) {
    console.error("Environment variable KIRITO_DB_SECRET_KEY is required for authentication.");
    process.exit(1);
  }

  const db = new KiritoDB(secretKey);
  console.log("KiritoDB initialized successfully.");

  // Set a user's name
  await db.set("users.1234.name", "João");
  console.log("Set users.1234.name to João.");

  // Retrieve the user's name
  const userName = await db.get("users.1234.name");
  console.log(`Retrieved users.1234.name: ${userName}`);

  // Add points to a user's score
  await db.add("users.1234.score", 50);
  console.log("Added 50 points to users.1234.score.");
  let userScore = await db.get("users.1234.score");
  console.log(`Current users.1234.score: ${userScore}`);

  // Subtract points
  await db.sub("users.1234.score", 15);
  console.log("Subtracted 15 points from users.1234.score.");
  userScore = await db.get("users.1234.score");
  console.log(`Current users.1234.score: ${userScore}`);

  // Retrieve all data from the database
  const allData = await db.all();
  console.log("All data currently in database:\n", JSON.stringify(allData, null, 2));

  // Delete a specific key
  await db.delete("users.1234.name");
  console.log("Deleted users.1234.name.");
  const deletedUserName = await db.get("users.1234.name");
  console.log(`users.1234.name after deletion: ${deletedUserName}`); // Should be null/undefined
}

run().catch(console.error);