RustyBase SDK
A comprehensive, industry-standard TypeScript/JavaScript SDK for RustyBase. Seamless interface for CRUD, Aggregation, and Database Management.
Features
Strictly Typed
Full TypeScript support with comprehensive interfaces.
Isomorphic
Works in Node.js, Browsers, and Deno (uses standard fetch).
Auto-Auth
Intelligent header selection and automatic JWT token refresh logic.
Dual Build
Supports both ESM and CommonJS.
Aggregation
Full support for MongoDB-style aggregation pipelines.
ObjectId
Built-in helper for generating 24-char hex IDs.
Installation
1npm install rustybase-sdk1yarn add rustybase-sdk1pnpm add rustybase-sdkQuick Start
Initialize the Client
You can connect using a connection string or a base URL.
1import { RustyBaseClient } from "rustybase-sdk";
2
3// Option 1: Connection String
4const client = new RustyBaseClient({
5 connectionString:
6 "rustybase://user:pass@127.0.0.1:3000/my_db?authSource=admin",
7});
8
9// Option 2: Base URL + Environment Variables
10// (Reads RUSTYBASE_URL or RUSTYBASE_CONN if config is empty)
11const client = new RustyBaseClient({ baseUrl: "http://localhost:3000" });Authentication
The SDK manages authentication automatically. If you provide a connection string, it uses theX-Connection-String header. You can also log in manually to use JWT-based authentication.
1await client.login({
2 username: "admin",
3 password: "password123",
4 database: "admin",
5});
6// After login, the SDK uses "Authorization: Bearer <token>"
7// and handles token refresh automatically.CRUD Operations
Access databases and collections via a hierarchical API.
1const db = client.db("my_database");
2const users = db.collection("users");
3
4// Insert
5const userId = await users.insertOne({
6 name: "John Doe",
7 role: "developer",
8});
9
10// Find
11const user = await users.findOne({ name: "John Doe" });
12const { documents, total } = await users.find(
13 { role: "developer" },
14 { limit: 10 },
15);
16
17// Update
18await users.updateOne(
19 { name: "John Doe" },
20 { $set: { role: "senior developer" } },
21);
22
23// Delete
24await users.deleteOne({ name: "John Doe" });Aggregation
Run complex pipelines using the aggregate method.
1const pipeline = [
2 { $match: { status: "active" } },
3 { $group: { _id: "$category", total: { $sum: "$amount" } } },
4];
5
6const results = await db.collection("orders").aggregate(pipeline);Detailed API Reference
RustyBaseClient
The main entry point for the SDK. Handles authentication, connection state, and database access.
| Method | Returns | Description |
|---|---|---|
| login(credentials) | Promise<LoginResponse> | Authenticates the user and retrieves JWT tokens. |
| db(name) | Database | Returns a Database instance for operations on a specific DB. |
| listDatabases() | Promise<string[]> | Retrieves a list of all available databases on the server. |
| createDatabase(name) | Promise<boolean> | Creates a new database. |
| Method | Request Type | Description |
|---|---|---|
| createUser(user) | CreateUserRequest | Creates a new system user with specific roles. |
| wipeAllData() | - | DANGER: Wipes all data from the server. Use with extreme caution. |
Collection
Created via db.collection(name). This is where most data operations occur.
Technical Details
Authentication Interceptor
The SDK implements an automated retry pattern. If a request fails with a 401 Unauthorized and a refresh_token is available, the SDK call /refresh, updates internal state, and automatically retries the original request.
Error Handling
1try {
2 await client.listDatabases();
3} catch (error) {
4 if (error instanceof RustyBaseError) {
5 console.log(error.status);
6 console.log(error.code);
7 }
8}