Spedo Node.js, TypeScript & React SDK (@spedo/react)

Since version v0.64.0

Spedo offers first-class support for the entire JavaScript and TypeScript ecosystem:

1. Node.js & Backend Services: Connect directly over standard high-performance RESP protocol using standard clients (e.g. ioredis) or native WebSocket RPC.

2. React & Frontend Applications: Ultra-lightweight (< 3KB), zero-boilerplate React SDK (@spedo/react) for live variables, delta queries, optimistic UI updates, and instant UI synchronization without polling.

1. Quick Installation

For Frontend / Full-Stack React Apps:

npm install @spedo/react
# or
pnpm add @spedo/react
# or
yarn add @spedo/react

For Node.js Backend Services:

npm install ioredis
# or
pnpm add ioredis

2. Node.js Backend Integration (Standard RESP)

Because Spedo implements the standard RESP wire protocol, your Node.js / Express / Fastify / NestJS backends can connect with zero custom drivers:

import Redis from 'ioredis';

// Connect to local or remote Spedo instance on port 6380
const spedo = new Redis({
  host: process.env.SPEDO_HOST || '127.0.0.1',
  port: Number(process.env.SPEDO_PORT) || 6380,
  enableAutoPipelining: true,
  maxRetriesPerRequest: 3,
});

// 1. Ultra-fast Key-Value & JSON
await spedo.set('user:101', JSON.stringify({ name: 'Alice', tier: 'enterprise' }));
const raw = await spedo.get('user:101');
const user = JSON.parse(raw!);

// 2. High-Throughput Priority Push & Pop (FairShare 7:2:1)
await spedo.send_command('QPUSH', ['jobs:render', 'task_99', 'PRIORITY', '0', 'FAMILY', 'tenant_a']);
const batch = await spedo.send_command('QPOP', ['jobs:render', 'COUNT', '10']);

// 3. In-Engine SIMD Vector Search (AVX2/NEON)
const vectorQuery = [0.042, -0.189, 0.812];
const nearest = await spedo.send_command('SPEDO.VECSEARCH', [
  'docs:embeddings',
  JSON.stringify(vectorQuery),
  'TOP_K', '5',
  'METRIC', 'COSINE'
]);
console.log('Top matches:', nearest);

3. React Frontend Architecture & Overview

Traditional web applications suffer from constant polling, stale React state, complex WebSocket glue code, and sluggish mutations.

@spedo/react connects frontend interfaces directly to Spedo's live reactive streams:

+-----------------------------------------------------------------------------------------+
|                    SPEDO REACT & TYPESCRIPT SDK ARCHITECTURE                            |
+-----------------------------------------------------------------------------------------+

  React Application (Next.js / Vite / Remix / CRA)
  +-------------------------------------------------------------------------------------+
  | <SpedoProvider url="ws://localhost:8080/spedo">                                     |
  |                                                                                     |
  |   +-------------------------------------------------------------------------------+ |
  |   | Component A                                                                   | |
  |   |   const [darkMode, setDarkMode] = useSpedoVar("flags:dark_mode", false);      | |
  |   |   // 0µs local reads + Optimistic UI updates with instant rollback            | |
  |   +-------------------------------------------------------------------------------+ |
  |                                                                                     |
  |   +-------------------------------------------------------------------------------+ |
  |   | Component B                                                                   | |
  |   |   const { data: orders } = useSpedoQuery("order:*", { freshness: "50ms" });  | |
  |   |   // Differential micro-deltas patched into local state without re-fetching   | |
  |   +-------------------------------------------------------------------------------+ |
  +-------------------------------------------------------------------------------------+
            ^                                                   |
            | Real-Time Delta Push (CDC Stream)                 | Optimistic Mutation (0µs)
            | (DeltaOp: UPDATE_FIELD, SET, DEL)                 | & WebSocket / HTTP RPC
            v                                                   v
  +-------------------------------------------------------------------------------------+
  | Spedo Engine Cluster / Embedded Worker (Port 6380 / 8080)                           |
  +-------------------------------------------------------------------------------------+

2. Quickstart & Installation

npm install @spedo/react
# or
pnpm add @spedo/react

Wrap with <SpedoProvider>

import React from 'react';
import { SpedoProvider } from '@spedo/react';

export function App() {
  return (
    <SpedoProvider url="ws://localhost:8080/spedo">
      <Dashboard />
    </SpedoProvider>
  );
}

3. Core React Hooks

A. useSpedoVar<T>(key, defaultValue, options)

Provides real-time synchronized state with Optimistic UI Updates. When mutated via setValue(), the component state updates instantly in local memory (0 µs), while sending the change across the wire. If a network fault occurs, state automatically rolls back and captures the error.

import React from 'react';
import { useSpedoVar } from '@spedo/react';

export function MaintenanceToggle() {
  const [enabled, setEnabled, { isPending, error }] = useSpedoVar<boolean>(
    'config:maintenance_mode',
    false,
    { optimistic: true, rollbackOnError: true }
  );

  return (
    <button disabled={isPending} onClick={() => setEnabled(!enabled)}>
      Maintenance: {enabled ? 'Active 🚨' : 'Disabled ✅'}
    </button>
  );
}

B. useSpedoQuery<T>(pattern, options)

Binds a live query collection (e.g. "order:*") with configurable Freshness Contracts. Only modified fields or items trigger micro-deltas, avoiding full-collection refetches.

import React from 'react';
import { useSpedoQuery } from '@spedo/react';

interface Order {
  id: number;
  customer: string;
  status: 'PENDING' | 'PAID' | 'DELIVERED';
}

export function OrdersFeed() {
  const { data: orders, loading, isStale } = useSpedoQuery<Order>('order:*', {
    freshness: 'bounded:50ms',
    filterFn: (k, v) => v && v.status !== 'DELIVERED',
  });

  if (loading) return <div>Loading live orders...</div>;

  return (
    <div>
      {isStale && <span className="warning">Syncing latest deltas...</span>}
      <ul>
        {orders.map((order) => (
          <li key={order.id}>{order.customer}: {order.status}</li>
        ))}
      </ul>
    </div>
  );
}

C. useSpedoVectorSearch<T>(options)

Executes in-cache semantic similarity searches powered by Spedo's native SIMD vector engine.

import React from 'react';
import { useSpedoVectorSearch } from '@spedo/react';

export function SearchComponent() {
  const { results, loading, search } = useSpedoVectorSearch<{ title: string }>();

  const onSearch = async (embedding: number[]) => {
    await search(embedding, { k: 5, threshold: 0.85 });
  };

  return (
    <div>
      {results.map((r) => (
        <div key={r.key}>{r.data?.title} ({(r.score * 100).toFixed(1)}%)</div>
      ))}
    </div>
  );
}

4. Standalone TypeScript Client (Node / Edge / Browser)

The SDK can be used in pure TypeScript environments without React:

import { SpedoClient, DeltaOp } from '@spedo/react';

const spedo = new SpedoClient({
  url: 'http://localhost:8090',
  defaultFreshness: 'bounded:50ms',
});

// 1. KV Operations
await spedo.set('user:101', { name: 'Alice' });
const user = await spedo.get('user:101');

// 2. Bound Queries
const query = spedo.bindQuery('order:*', { freshness: 'bounded:50ms' });
query.subscribe((key, op, val) => {
  console.log(`Delta received: ${op} on ${key}`);
});

5. Summary & Ecosystem Benefits