RONIN Client for TypeScript

Common errors

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use `require()` to import `blade-client` in a Node.js project configured as an ES module (e.g., `"type": "module"` in `package.json`).
  fix Switch to ES module `import` syntax: `import { RONINClient } from 'blade-client';`.

• Error: Failed to establish connection to RONIN database. Please check your API key and network connectivity.

  cause The `RONINClient` could not connect to the RONIN database. This is typically due to an incorrect API key, an inaccessible database endpoint, or network issues (e.g., firewall, DNS resolution).
  fix Verify that `process.env.RONIN_API_KEY` is correctly set with a valid RONIN API key. Ensure that the database endpoint (if explicitly configured) is correct and reachable from your environment. Check network logs for connection refusal or timeout errors.

• TypeError: roninClient.query is not a function

  cause This usually indicates that `roninClient` is not an instance of `RONINClient` or that the `query` method (or other methods like `insert`, `update`) does not exist on the object being called.
  fix Ensure `RONINClient` is correctly imported and instantiated with `new RONINClient(...)`. Double-check the method names and their casing against the library's documentation. If using TypeScript, ensure your environment is correctly set up to catch type errors during compilation.

Warnings

• breaking The `blade-client` package, specifically from version 3.x onwards, requires Node.js version 18.17.0 or higher. Older Node.js runtimes are not supported and will lead to startup failures or unexpected behavior.
  Fix: Upgrade your Node.js environment to version 18.17.0 or newer. Use `nvm` or `volta` for easy version management.
• gotcha All database operations with `blade-client` are asynchronous. Failing to `await` promises returned by methods like `query`, `insert`, or `update` can lead to unhandled promise rejections, incorrect data flow, or silent failures.
  Fix: Always use `await` when calling asynchronous `blade-client` methods within an `async` function, and ensure proper `try...catch` blocks for robust error handling.
• gotcha When contributing to the `blade-client` project, the repository explicitly uses `bun` for dependency management and expects `bun.lockb` over `package-lock.json`. Submitting a pull request with an `package-lock.json` file will likely cause CI failures.
  Fix: For contributors, ensure `bun` is installed and used for `install` and `link` commands. Delete `package-lock.json` before creating a pull request and rely solely on `bun.lockb`.
• gotcha Effective connection pooling and resource management are crucial for database clients, especially in serverless or high-concurrency environments. While `blade-client` likely handles much of this internally, misconfigurations or excessive client instantiations per request can degrade performance or exhaust database connections.
  Fix: Follow best practices for your deployment environment. Typically, a single `RONINClient` instance should be reused across requests (e.g., initialized once per serverless function instance or application lifecycle), rather than creating a new one for every operation.

Install

• npm install blade-client npm
• yarn add blade-client yarn
• pnpm add blade-client pnpm

Imports

• RONINClient
  wrong:

  const RONINClient = require('blade-client');

  correct:

  import { RONINClient } from 'blade-client';

  The primary client class for interacting with the RONIN database. Since version 3.x, the package is primarily designed for ES Module consumption. Using `require` in an ES Module context will result in a runtime error.
• QueryResult

  import type { QueryResult, RowData } from 'blade-client';

  Type imports for defining the structure of query results and individual row data, ensuring type safety in TypeScript applications. These types are directly exported from the main package.
• RONINClient (CommonJS)
  wrong:

  import RONINClient from 'blade-client';

  correct:

  const { RONINClient } = require('blade-client');

  For projects that must use CommonJS, this pattern can be used. However, it's recommended to migrate to ES Modules if possible, as future versions may deprecate full CommonJS compatibility. If `RONINClient` were a default export, `import RONINClient from 'blade-client';` would be correct for ESM.

Quickstart

This quickstart demonstrates how to initialize the RONIN client, perform basic `SELECT` queries, `INSERT` new records, and `UPDATE` existing ones. It includes error handling and assumes an environment variable for the API key.

import { RONINClient } from 'blade-client';

async function main() {
  // Initialize the RONINClient with your API key and optionally an endpoint.
  // It's recommended to use environment variables for sensitive information.
  const roninClient = new RONINClient({
    apiKey: process.env.RONIN_API_KEY ?? 'your-development-api-key',
    // endpoint: process.env.RONIN_ENDPOINT ?? 'https://api.ronin.example.com/v1' // Optional: if your RONIN instance has a custom endpoint
  });

  try {
    console.log('Attempting to fetch data from RONIN database...');

    // Example 1: Fetch all entries from a 'users' collection/table
    const allUsers = await roninClient.query<{ id: string; name: string; email: string }[]>(
      `SELECT id, name, email FROM users`
    );
    console.log('Fetched users:', allUsers.slice(0, 3)); // Log first 3 users for brevity

    // Example 2: Insert a new record into a 'logs' collection
    const newLogEntry = { timestamp: new Date().toISOString(), message: 'Application startup', level: 'INFO' };
    const insertResult = await roninClient.insert('logs', newLogEntry);
    console.log('Inserted new log entry with ID:', insertResult.id);

    // Example 3: Update an existing record in 'products' with a specific ID
    const productIdToUpdate = 'some-product-uuid'; // Replace with an actual product ID
    const updateResult = await roninClient.update('products', { price: 29.99 }, { id: productIdToUpdate });
    console.log(`Updated product ${productIdToUpdate}:`, updateResult);

  } catch (error) {
    console.error('An error occurred during RONIN operation:');
    if (error instanceof Error) {
      console.error('Error message:', error.message);
      console.error('Error stack:', error.stack);
    } else {
      console.error(error);
    }
  }
}

main().catch(error => {
  console.error('Unhandled error in main function:', error);
  process.exit(1);
});