RONIN Data Platform TypeScript Client

6.8.0 verified Thu Apr 23 auth: no javascript

The `ronin` package provides a robust, TypeScript-first client for interacting with the RONIN data platform. Currently at version 6.8.0, it offers an intuitive ORM-like interface designed for efficient data access, particularly optimized for serverless and edge environments. This library abstracts common database operations, enabling developers to seamlessly query, mutate, and manage records through a fluent API. It prioritizes type safety and developer experience, shipping with comprehensive TypeScript definitions. While a precise release cadence isn't published, the versioning suggests regular updates that align with new platform features and bug fixes. Key differentiators include its native TypeScript integration, performance optimization for modern deployment patterns like serverless functions, and direct, secure connectivity to the RONIN backend services.

Common errors

error TypeError: Cannot destructure property 'Ronin' of 'ronin' as it is undefined. ↓

cause Attempting to import `Ronin` as a named export when it might have been default in an older version, or vice-versa, or due to incorrect `package.json` `type` field.

fix

Verify the correct import style (import { Ronin } from 'ronin' or import Ronin from 'ronin') against the version's documentation. Ensure package.json has "type": "module" if you're using ESM imports in a non-transpiled Node.js environment.

error RoninError: Authentication failed. Invalid or missing API token. ↓

cause The `RONIN_TOKEN` environment variable was not provided, or the token is invalid/expired.

fix

Set the RONIN_TOKEN environment variable with a valid API token obtained from your RONIN dashboard before running your application. Double-check for typos or accidental whitespace.

error TS2307: Cannot find module 'ronin' or its corresponding type declarations. ↓

cause TypeScript cannot find the package or its types. This can happen if the package isn't installed, or if `tsconfig.json` isn't configured correctly.

fix

Run npm install ronin (or yarn add ronin). Ensure your tsconfig.json includes "moduleResolution": "Bundler" or "NodeNext" for modern Node.js projects, and that "skipLibCheck": true is not masking other issues.

Warnings

breaking Version 6.0 introduced breaking changes related to the client initialization and API surface, simplifying some methods and consolidating others. Direct access to some internal utilities was removed in favor of the public API. ↓

fix Review the official migration guide for v6.x. Ensure your client initialization now passes configuration directly to the `new Ronin()` constructor. Adapt any custom query logic to the new fluent API.

gotcha The `ronin` package relies heavily on environment variables for API tokens (e.g., `RONIN_TOKEN`). Failing to provide these, or providing an invalid one, will result in authentication errors. ↓

fix Always ensure `process.env.RONIN_TOKEN` (or equivalent for your runtime) is correctly set before initializing the `Ronin` client. For production, use secure environment management; for local development, consider a `.env` file with `dotenv`.

gotcha The library is ESM-first, requiring Node.js >=18.17.0. Older Node.js versions or pure CommonJS environments might encounter issues with import/export syntax without proper transpilation. ↓

fix Ensure your project is configured for ES Modules (e.g., `"type": "module"` in `package.json`) and you are using a compatible Node.js version. If using CommonJS, configure a bundler like Webpack or Rollup, or a transpiler like Babel, to handle ESM imports.

breaking Schema enforcement and type definitions were significantly tightened in version 5.0. If your local TypeScript types do not align with the backend RONIN database schema, you may encounter runtime errors or type mismatches during compilation. ↓

fix Regularly synchronize your local TypeScript interfaces with your RONIN database schema. Leverage the type inference capabilities of the `Ronin` client's methods and define precise interfaces for your data models.

Install

npm install ronin

yarn add ronin

pnpm add ronin

Imports

Ronin
wrong
```
import Ronin from 'ronin'
```
correct
```
import { Ronin } from 'ronin'
```
The primary client class is a named export, not a default export, for better tree-shaking and type inference.
RoninRecord
wrong
```
import { RoninRecord } from 'ronin'
```
correct
```
import type { RoninRecord } from 'ronin'
```
Import types using `import type` for clarity and to ensure they are stripped from the JavaScript bundle.
RoninError
wrong
```
const RoninError = require('ronin').RoninError
```
correct
```
import { RoninError } from 'ronin'
```
The package is primarily designed for ES Modules. While CommonJS might work via transpilation, direct `require` syntax is not officially supported or recommended since Node.js 18.17.0 is the minimum engine.

Quickstart

Initializes the Ronin client, creates a new product, fetches all products, retrieves a specific product by ID, and updates a product's status.

import { Ronin } from 'ronin';

interface Product extends RoninRecord {
  id: string;
  name: string;
  price: number;
  inStock: boolean;
}

async function main() {
  // Ensure RONIN_TOKEN is set as an environment variable
  const roninClient = new Ronin({ token: process.env.RONIN_TOKEN ?? '' });

  try {
    // Create a new product record
    const newProduct = await roninClient.create<Product>('products', {
      name: 'Smart Coffee Maker',
      price: 149.99,
      inStock: true,
    });
    console.log('Created product:', newProduct.name, newProduct.id);

    // Fetch all products
    const allProducts = await roninClient.get<Product[]>('products');
    console.log(`Found ${allProducts.length} products.`);

    // Fetch a specific product by ID
    if (newProduct.id) {
      const fetchedProduct = await roninClient.getById<Product>('products', newProduct.id);
      console.log('Fetched product by ID:', fetchedProduct?.name);
    }

    // Update a product
    const updatedProduct = await roninClient.update<Product>('products', newProduct.id, { inStock: false });
    console.log('Updated product status:', updatedProduct.name, 'inStock:', updatedProduct.inStock);

    // Delete a product (example, uncomment to run)
    // await roninClient.delete('products', newProduct.id);
    // console.log('Deleted product:', newProduct.id);

  } catch (error) {
    console.error('Error interacting with RONIN database:', error);
  }
}

main();