{"id":16605,"library":"blade-client","title":"RONIN Client for TypeScript","description":"The `blade-client` package provides a robust and type-safe client for accessing and querying data from your RONIN database. Currently at version 3.29.10, this library is designed for ease of use and integrates seamlessly into modern JavaScript and TypeScript projects, including those targeting edge and serverless environments. While an explicit release cadence isn't stated, the frequent version updates suggest active development and maintenance. Its key differentiator is its direct, strongly-typed access to RONIN databases, abstracting complex database interactions into a developer-friendly API that includes ORM-like query, insert, and update operations. It's built to be a reliable solution for applications requiring efficient and secure data retrieval and manipulation from RONIN backends.","status":"active","version":"3.29.10","language":"javascript","source_language":"en","source_url":"https://github.com/ronin-co/client","tags":["javascript","ronin","client","database","orm","edge","serverless","typescript"],"install":[{"cmd":"npm install blade-client","lang":"bash","label":"npm"},{"cmd":"yarn add blade-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add blade-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Requires a compatible Node.js runtime environment.","package":"node","optional":false}],"imports":[{"note":"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.","wrong":"const RONINClient = require('blade-client');","symbol":"RONINClient","correct":"import { RONINClient } from 'blade-client';"},{"note":"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.","symbol":"QueryResult","correct":"import type { QueryResult, RowData } from 'blade-client';"},{"note":"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.","wrong":"import RONINClient from 'blade-client';","symbol":"RONINClient (CommonJS)","correct":"const { RONINClient } = require('blade-client');"}],"quickstart":{"code":"import { RONINClient } from 'blade-client';\n\nasync function main() {\n  // Initialize the RONINClient with your API key and optionally an endpoint.\n  // It's recommended to use environment variables for sensitive information.\n  const roninClient = new RONINClient({\n    apiKey: process.env.RONIN_API_KEY ?? 'your-development-api-key',\n    // endpoint: process.env.RONIN_ENDPOINT ?? 'https://api.ronin.example.com/v1' // Optional: if your RONIN instance has a custom endpoint\n  });\n\n  try {\n    console.log('Attempting to fetch data from RONIN database...');\n\n    // Example 1: Fetch all entries from a 'users' collection/table\n    const allUsers = await roninClient.query<{ id: string; name: string; email: string }[]>(\n      `SELECT id, name, email FROM users`\n    );\n    console.log('Fetched users:', allUsers.slice(0, 3)); // Log first 3 users for brevity\n\n    // Example 2: Insert a new record into a 'logs' collection\n    const newLogEntry = { timestamp: new Date().toISOString(), message: 'Application startup', level: 'INFO' };\n    const insertResult = await roninClient.insert('logs', newLogEntry);\n    console.log('Inserted new log entry with ID:', insertResult.id);\n\n    // Example 3: Update an existing record in 'products' with a specific ID\n    const productIdToUpdate = 'some-product-uuid'; // Replace with an actual product ID\n    const updateResult = await roninClient.update('products', { price: 29.99 }, { id: productIdToUpdate });\n    console.log(`Updated product ${productIdToUpdate}:`, updateResult);\n\n  } catch (error) {\n    console.error('An error occurred during RONIN operation:');\n    if (error instanceof Error) {\n      console.error('Error message:', error.message);\n      console.error('Error stack:', error.stack);\n    } else {\n      console.error(error);\n    }\n  }\n}\n\nmain().catch(error => {\n  console.error('Unhandled error in main function:', error);\n  process.exit(1);\n});","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js environment to version 18.17.0 or newer. Use `nvm` or `volta` for easy version management.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Always use `await` when calling asynchronous `blade-client` methods within an `async` function, and ensure proper `try...catch` blocks for robust error handling.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Switch to ES module `import` syntax: `import { RONINClient } from 'blade-client';`.","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`).","error":"ReferenceError: require is not defined in ES module scope"},{"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.","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).","error":"Error: Failed to establish connection to RONIN database. Please check your API key and network connectivity."},{"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.","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.","error":"TypeError: roninClient.query is not a function"}],"ecosystem":"npm"}