const client = new NoexClient(url, {
  auth: { token },
  reconnect: true,
});
await client.connect();

noex ecosystem

noex-client

Name: noex-client
Author: noex

Type-Safe Client SDK

Fully typed WebSocket client for noex-server with automatic reconnect, subscription recovery, reactive store queries, rules engine proxy, and zero runtime dependencies.

View on GitHub

Key Features

Everything you need for type-safe real-time communication with noex-server

Type-Safe Bucket API

Generic BucketAPI<T> with full TypeScript typing. CRUD operations, queries, pagination, and aggregations — all with compile-time type safety.

Automatic Reconnect

Exponential backoff with jitter, configurable parameters (maxRetries, delays, multiplier). Seamless reconnection without manual intervention.

Subscription Recovery

After reconnect, all store and rules subscriptions are automatically restored and fresh data is delivered. No manual resubscription needed.

Reactive Subscriptions

Real-time push notifications for store queries and rules events. Initial data delivered immediately after subscription, then live updates on every change.

Transactions

ACID multi-bucket transactions over WebSocket. Atomic operations with optimistic locking, read-your-own-writes, and automatic rollback on conflict.

Rules Engine Proxy

Emit events, manage facts (set/get/delete/query), and subscribe to pattern-based event streams — all through the same WebSocket connection.

Authentication

Login, logout, and session management via token-based auth. Auto-login on connect and reconnect when auth token is provided.

Zero Dependencies

No runtime dependencies. Works in browser natively and in Node.js with the ws package. Minimal bundle footprint.

Layered Architecture

Clean separation of concerns with four distinct layers

API Layer

StoreAPI, RulesAPI, AuthAPI

Subscription Manager

Registry, push delivery, resubscribe

Protocol Layer

RequestManager + PushRouter

Transport Layer

WebSocket, heartbeat, reconnect

Connection State Machine

disconnected

connecting

reconnecting

connected

Lifecycle events: connected, disconnected, reconnecting, reconnected, error, welcome

Request pipeline: API call → RequestManager (id correlation + timeout) → Transport (WebSocket send) → Response routing

See It in Action

Real code examples showing connection, CRUD, subscriptions, transactions, and rules

client.ts

import { NoexClient } from '@hamicek/noex-client';

const client = new NoexClient('ws://localhost:8080', {
  auth: { token: 'my-secret-token' },
  reconnect: {
    maxRetries: Infinity,
    initialDelayMs: 1_000,
    maxDelayMs: 30_000,
    backoffMultiplier: 2,
    jitterMs: 500,
  },
  requestTimeoutMs: 10_000,
  connectTimeoutMs: 5_000,
  heartbeat: true,
});

const info = await client.connect();
console.log(`Connected to v${info.version}`);

client.on('reconnecting', (attempt) => {
  console.log(`Reconnecting... attempt ${attempt}`);
});

client.on('reconnected', () => {
  console.log('Connection restored!');
});

// Graceful disconnect
await client.disconnect();

Reconnect Behavior

Automatic reconnection with exponential backoff, jitter, and full subscription recovery

Exponential Backoff

#1 ~1s

1000ms + jitter

#2 ~2s

2000ms + jitter

#3 ~4s

4000ms + jitter

#4 ~8s

8000ms + jitter

#5 ~16s

16000ms + jitter

#N max 30s

capped at maxDelayMs

Configuration

maxRetries Infinity

Maximum reconnect attempts

initialDelayMs 1000

Base delay before first retry

maxDelayMs 30000

Maximum delay cap

backoffMultiplier 2

Exponential multiplier

jitterMs 500

Random jitter added to delay

Subscription Recovery Flow

Reconnect

Re-authenticate

Resubscribe all

Deliver fresh data

Disable reconnect with reconnect: false

How It Compares

noex-client vs popular real-time client SDKs

Feature	noex-client	Socket.IO Client	Supabase JS	Firebase JS	Ably Realtime
Type-Safe Generic API	BucketAPI<T>	—	Generated types	Untyped	—
Auto Subscription Recovery	✓	—	—	✓	✓
ACID Transactions	Multi-bucket over WS	—	Postgres transactions	—	—
Rules Engine Proxy	✓	—	—	—	—
Reconnect with Backoff	✓	✓	✓	✓	✓
Auto-login on Reconnect	✓	—	—	✓	—
Reactive Query Subscriptions	Convex-style push	Manual rooms	Postgres changes	Realtime sync	Pub/sub
Facts Management	Set/get/delete/query	—	—	—	—
Runtime Dependencies	Zero	engine.io-client +	Multiple	Multiple	Multiple
Browser + Node.js	✓	✓	✓	✓	✓
Status	Active	Active	Active	Active	Active

What Makes noex-client Unique

Type-Safe Generic API

BucketAPI<T> gives you compile-time type safety on every CRUD operation, query, and aggregation. No more runtime type mismatches.

Automatic Subscription Recovery

On reconnect, all active store and rules subscriptions are automatically restored. Fresh data is delivered without any manual resubscription logic.

Integrated Rules Engine

The only client SDK with built-in rules engine access. Emit events, manage facts, and subscribe to pattern-matched rule events over the same connection.

ACID Transactions over WebSocket

Multi-bucket atomic transactions with optimistic locking, sent as a single message. Read-your-own-writes and automatic rollback on conflict.

Zero Runtime Dependencies

No transitive dependencies to audit or update. Works natively in browsers, and in Node.js with just the ws package as a peer dependency.

Start building type-safe real-time apps

Add noex-client to your project in seconds

npm install @hamicek/noex-client

$ npm install @hamicek/noex-client

Read the Docs Star on GitHub

Requires a running noex-server. In Node.js, install ws as a peer dependency.

Back to noex

Support the Project

Love noex? Help us keep building amazing tools

Bitcoin