@arindam923/flashdb-client

Realtime key-value database client for React with WebSocket connectivity.

Features

• Realtime Subscriptions - Subscribe to key changes with instant updates
• React Hooks - Simple hooks for fetching and mutating data
• Optimistic Updates - Instant UI updates with automatic background sync
• Auto Reconnection - Automatic WebSocket reconnection with exponential backoff
• TypeScript - Full TypeScript support

Installation

npm install @arindam923/flashdb-client

Quick Start

import { FlashDB, FlashDBProvider, useValue, useMutation } from '@arindam923/flashdb-client';

const db = new FlashDB({
  url: 'ws://localhost:8080/ws',
  token: 'your-jwt-token'
});

function App() {
  return (
    <FlashDBProvider client={db}>
      <Counter />
    </FlashDBProvider>
  );
}

function Counter() {
  const { value: count, version, loading } = useValue('counter');
  const { mutate, loading: mutating } = useMutation('counter');
  
  const handleClick = () => {
    mutate((current) => (current ?? 0) + 1);
  };
  
  if (loading) return <div>Loading...</div>;
  
  return (
    <button onClick={handleClick} disabled={mutating}>
      Count: {count ?? 0}
    </button>
  );
}

API

FlashDB Client

const db = new FlashDB({
  url: 'ws://localhost:8080/ws',  // WebSocket URL
  token: 'jwt-token',              // Optional JWT token
  reconnectDelay: 1000,            // Initial reconnect delay (ms)
  maxReconnectDelay: 30000         // Max reconnect delay (ms)
});

Methods

| Method | Description | |--------|-------------| | get(key) | Get value by key | | set(key, value) | Set value | | cas(key, value, version) | Compare-and-swap | | delete(key) | Delete a key | | subscribe(key, listener) | Subscribe to key changes | | getCached(key) | Get from local cache | | isConnected() | Check connection status | | destroy() | Close connection |

React Hooks

useValue(key)

Subscribe to a key's value with realtime updates.

const { value, version, loading, error } = useValue('my-key');

useMutation(key, options)

Set or delete values with automatic retry logic.

const { mutate, delete: del, loading, error } = useMutation('my-key');

// Simple set
await mutate({ name: 'Alice' });

// Optimistic update with function
await mutate(current => ({ ...current, count: (current?.count ?? 0) + 1 }));

// Delete
await del();

Options:

• maxRetries - Max CAS retries (default: 10)

useConnection()

Track WebSocket connection state.

const { connected } = useConnection();

useOptimisticValue(key)

Instant local updates with server reconciliation.

const { value, setOptimistic, isOptimistic } = useOptimisticValue('counter');

// Instant update - UI updates immediately
setOptimistic(v => (v ?? 0) + 1);

Server Requirements

This client connects to a FlashDB server. See flashdb for server setup.

License

MIT