@devjuanes/matuclient

Official JavaScript/TypeScript client for MatuDB — a self-hosted, Supabase-compatible database platform.

Installation

npm install @devjuanes/matuclient

Or use locally (within the monorepo):

npm install ../matu-db-api/packages/matuclient

Configuration

The client can be configured manually or via environment variables.

Automatic Configuration (Environment Variables)

If you call createClient() without arguments, it will automatically look for these variables:

# MatuDB Backend URL
MATUDB_URL=http://localhost:3001

# MatuDB Project ID (Defaults to 'default')
MATUDB_PROJECT_ID=my-project

# MatuDB API Key (Anon or Service Role)
MATUDB_API_KEY=anon_xxxx...

# Supabase Fallback (Optional)
# Set to 'true' to route all calls through the official Supabase client
MATUDB_USE_SUPABASE=false

Manual Configuration

import { createClient } from '@devjuanes/matuclient';

const db = createClient({
  url: 'http://localhost:3001',
  projectId: 'my-project',
  apiKey: 'anon_xxxx',
  useSupabase: false // Set to true to use Supabase instead
});

Quick Start

import { createClient } from '@devjuanes/matuclient';

const db = createClient({
  url: 'http://localhost:3001',
  projectId: 'your-project-id',
  apiKey: 'your-anon-key',
});

API Reference

db.from(table) — Query Builder

Mirrors supabase.from() with a Supabase-compatible API.

// SELECT with filters
const { data, error } = await db
  .from('users')
  .select('id, name, email')
  .eq('active', true)
  .order('created_at', { ascending: false })
  .limit(10);

// Filter operators
.eq('col', value)       // =
.neq('col', value)      // !=
.gt('col', value)       // >
.gte('col', value)      // >=
.lt('col', value)       // <
.lte('col', value)      // <=
.like('col', '%patt%')  // LIKE
.ilike('col', '%patt%') // ILIKE (case-insensitive)
.in('col', [1, 2, 3])   // IN (...)
.is('col', null)        // IS NULL / IS TRUE / IS FALSE

// Single row
const { data: user } = await db.from('users').select('*').eq('id', userId).single();

// INSERT
const { data, error } = await db.from('products').insert({ name: 'Widget', price: 9.99 });

// INSERT multiple
const { data } = await db.from('products').insert([{ name: 'A' }, { name: 'B' }]);

// UPDATE
const { data } = await db.from('users').update({ name: 'Alice' }).eq('id', userId);

// DELETE
const { data } = await db.from('orders').delete().eq('id', orderId);

db.auth — Authentication

Mirrors supabase.auth.*.

// Sign up
const { data, error } = await db.auth.signUp({ email, password });

// Sign in
const { data, error } = await db.auth.signInWithPassword({ email, password });
// data = { user, session: { access_token, expires_at, user } }

// Sign out
await db.auth.signOut();

// Get current session
const { data: { session } } = await db.auth.getSession();

// Get current user
const { data: { user } } = await db.auth.getUser();

// Listen for auth changes
const { data: { subscription } } = db.auth.onAuthStateChange((event, session) => {
  console.log(event); // 'SIGNED_IN' | 'SIGNED_OUT'
});
// Cleanup:
subscription.unsubscribe();

db.storage — File Storage

Mirrors supabase.storage.*.

// Upload
const { data, error } = await db.storage.upload('avatar.png', file);

// Get public URL
const { data: { publicUrl } } = db.storage.getPublicUrl('avatar.png');

// List files
const { data: files } = await db.storage.list();

// Download
const { data: blob } = await db.storage.download('report.pdf');

// Delete
await db.storage.remove(['old-file.png', 'another.pdf']);

// Supabase bucket compat (bucket name is ignored):
await db.storage.from('avatars').upload('user.png', file);

db.channel() — Realtime

Mirrors supabase.channel().

// Supabase-compatible style
const channel = db
  .channel('public:users')
  .on('postgres_changes', { event: '*', schema: 'public', table: 'users' }, payload => {
    console.log('Change:', payload);
  })
  .subscribe();

// Short style
db.channel('orders')
  .on('INSERT', payload => console.log('New order:', payload.data))
  .on('DELETE', payload => console.log('Deleted:', payload.data))
  .subscribe();

// Cleanup
db.removeChannel(channel);
db.removeAllChannels();

db.rpc() — Raw SQL

const { data, error } = await db.rpc('SELECT * FROM users WHERE created_at > NOW() - INTERVAL \'7 days\'');

Migrating from Supabase

| Supabase | MatuDB | |---|---| | createClient(url, anonKey) | createClient({ url, projectId, apiKey }) | | supabase.from('t').select() | db.from('t').select() ✅ same | | supabase.auth.signInWithPassword() | db.auth.signInWithPassword() ✅ same | | supabase.storage.from('b').upload() | db.storage.upload() or .from('b').upload() ✅ | | supabase.channel('x').on(...) | db.channel('x').on(...) ✅ same | | supabase.rpc('fn', args) | db.rpc('SELECT ...') (raw SQL) |

All query responses return { data, error } — same as Supabase.