OpenBase JS SDK

The OpenBase JS SDK provides a lightweight, expressive interface for interacting with your OpenBase projects. It handles database queries (PostgreSQL), file storage (S3/MinIO), and realtime subscriptions via a simple, Supabase-like API.

📦 Installation

npm install openbase-js
# or
yarn add openbase-js

[!NOTE]
If you are using Node.js for file uploads, you will also need form-data:
npm install form-data

🚀 Quick Start

Initialize the client with your project URL, API key, and database name.

const { createClient } = require('openbase-js');

const openbase = createClient(
  'http://localhost:3003', // The URL where your OpenBase backend is running
  'your-anon-key',
  'your-db-name'
);

// Fetch data
async function getLeads() {
  const { data, error } = await openbase
    .from('leads')
    .select('*')
    .eq('status', 'active');
  
  if (error) console.error(error);
  else console.log(data);
}

📊 Database Operations

OpenBase uses a chainable query builder for database operations.

Basic CRUD

Select

const { data } = await openbase.from('users').select('id, username');

Insert

const { data } = await openbase.from('users').insert({
  username: 'jdoe',
  email: '[email protected]'
});

Update

const { data } = await openbase.from('users')
  .update({ email: '[email protected]' })
  .eq('id', 1);

Delete

const { data } = await openbase.from('users')
  .delete()
  .eq('id', 1);

🔍 Detailed Operator Guide

Filtering is done using chainable operator methods.

| Operator | Method | Description | Example | | :--- | :--- | :--- | :--- | | == | .eq(col, val) | Equal to | .eq('name', 'Alice') | | > | .gt(col, val) | Greater than | .gt('age', 21) | | < | .lt(col, val) | Less than | .lt('score', 50) | | >= | .gte(col, val) | Greater than or equal to | .gte('price', 100) | | <= | .lte(col, val) | Less than or equal to | .lte('stock', 5) | | LIKE | .like(col, pattern) | Case-sensitive pattern match | .like('name', '%son%') | | ILIKE | .ilike(col, pattern)| Case-insensitive pattern match | .ilike('name', '%SON%') | | IN | .in(col, array) | Contained in array | .in('role', ['admin', 'mod']) | | IS | .is(col, value) | Check for null or boolean | .is('deleted_at', null) |

🛠️ Modifiers

• .order(column, { ascending: boolean }): Sort the results.
• .limit(count): Limit the number of rows returned.
• .range(from, to): Pagination (0-indexed, inclusive).
• .single(): Returns a single object instead of an array.

const { data } = await openbase
  .from('posts')
  .select('*')
  .gt('likes', 10)
  .order('created_at', { ascending: false })
  .range(0, 9) // First 10 items

📁 Storage

OpenBase provides built-in S3-compatible storage.

Uploading Files

In the browser, you can pass a File or Blob. In Node.js, you can pass a file path, Buffer, or ReadStream.

// Browser
const file = event.target.files[0];
const { data, error } = await openbase.storage.upload(file, 'profile.jpg');

// Node.js (requires form-data)
const { data, error } = await openbase.storage.upload('./local-image.png', 'remote-name.png');

Listing & Managing Files

// List all files in bucket
const { data: files } = await openbase.storage.list();

// Get a public presigned URL (valid for 7 days)
const { data: { url } } = await openbase.storage.getUrl('profile.jpg');

// Remove a file
await openbase.storage.remove('profile.jpg');

🔄 Realtime

Subscribe to database changes using WebSockets.

const subscription = openbase
  .from('messages')
  .on('INSERT', (payload) => {
    console.log('New message:', payload.record);
  })
  .subscribe();

// To stop listening
// subscription.unsubscribe();

⌨️ TypeScript Support

The SDK is written with full TypeScript support. Types are automatically included.

interface Lead {
  id: number;
  company_name: string;
}

const { data } = await openbase.from<Lead>('leads').select('*');
// data is typed as Lead[] | null

🧪 Testing

To run the local tests:

1. Ensure the OpenBase backend is running.
2. Update the credentials in test.js.
3. Run: node test.js