@maru-hana/realtime

TypeScript client SDK for Maru Realtime — a real-time database with REST CRUD and WebSocket subscriptions.

Install

npm install @maru-hana/realtime

Quick start

import { initializeApp, getDatabase, doc, collection, getDoc, setDoc, updateDoc, deleteDoc, getDocs, onSnapshot } from '@maru-hana/realtime'

const app = initializeApp({
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
})

const db = getDatabase(app)

CRUD

const userDoc = doc(db, 'users', 'alice')

// Read one document (null if not found)
const data = await getDoc(userDoc)

// Write (replace entire document)
await setDoc(userDoc, { name: 'Alice', age: 30 })

// Partial update (merge fields)
await updateDoc(userDoc, { age: 31 })

// Delete
await deleteDoc(userDoc)

// List all documents in a collection
const userCol = collection(db, 'users')
const { items, total } = await getDocs(userCol)

// With pagination
const { items, total } = await getDocs(userCol, { limit: 20, offset: 0 })
console.log(`showing ${items.length} of ${total}`)

Real-time subscriptions

// Subscribe to a single document
const unsub = onSnapshot(doc(db, 'users', 'alice'), (data) => {
  if (data === null) console.log('document deleted')
  else console.log('updated:', data)
}, (err) => {
  console.error('error:', err)
})

// Subscribe to all changes in a collection
const unsub2 = onSnapshot(collection(db, 'users'), (data) => {
  console.log('collection change:', data)
})

// Stop listening
unsub()
unsub2()

A single WebSocket connection is shared per db instance. It reconnects automatically with exponential backoff if disconnected.

Error handling

All CRUD functions throw Error on non-2xx responses:

try {
  await setDoc(userDoc, { name: 'Alice' })
} catch (err) {
  console.error(err.message) // e.g. "API error 401: unauthorized"
}

onSnapshot never throws — pass an optional error callback as the third argument.

Configuration

| Option | Required | Default | Description | |--------|----------|---------|-------------| | apiKey | ✓ | — | API key for your project | | projectId | ✓ | — | Your project ID | | wsUrl | — | wss://api-realtime.maru-it.com | WebSocket base URL | | apiUrl | — | derived from wsUrl | REST API base URL |

License

MIT