JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 1390
  • Score
    100M100P100Q125484F
  • License MIT

Realtime fault-tolerant realtime (pub/sub) SDK

Package Exports

  • @aptly-sdk/brook
  • @aptly-sdk/brook/react

Readme

Brook SDK

A realtime fault-tolerant pub/sub SDK for JavaScript and React applications.

Features

  • ✅ Fault-tolerant real-time messaging
  • ✅ Automatic reconnection with exponential backoff
  • ✅ Message replay for missed messages
  • ✅ React hooks for seamless integration
  • ✅ Full TypeScript support
  • ✅ Lightweight and performant

Getting Started

Get Your API Key

Before using the Brook SDK, you'll need to get your API key from the Console

Demo

👾 Live Demo – play around and see it in action.

Installation

npm install @aptly-sdk/brook
# or
pnpm add @aptly-sdk/brook
# or
yarn add @aptly-sdk/brook

Quick Start

JavaScript

import Brook from '@aptly-sdk/brook';

const client = new Brook({ apiKey: 'your-api-key' });
await client.connect();

const channel = client.realtime.channel('my-topic');

channel.stream((message) => {
    console.log('Incoming message', message);
});

React

import Brook from '@aptly-sdk/brook';
import { BrookProvider, useStream, usePublish } from '@aptly-sdk/brook/react';

// 1. Initialize the client
const client = new Brook({ apiKey: 'your-api-key' });

// 2. Wrap your app with the BrookProvider
function App() {
    return (
        <BrookProvider config={client}>
            <Component1 />
            <Component2 />
        </BrookProvider>
    );
}

function Component1() {
    // 3. Subscribe to the topic
    useStream('my-topic', (message, metadata) => {
        console.log(message, metadata);
    });

    // ... rest of your component
}

function Component2() {
    const publish = usePublish('my-topic');

    useEffect(() => {
        // 4. Publish to the topic (Optional)
        publish({
            message: 'Hello from React SDK',
        });
    }, []);
}

React Setup Guide

1. Initialize the Client

import Brook from '@aptly-sdk/brook';

const client = new Brook({ apiKey: 'your-api-key' });

2. Setup the Provider

import { BrookProvider } from '@aptly-sdk/brook/react';

function App() {
    return (
        <BrookProvider config={client}>
            <Component1 />
            <Component2 />
        </BrookProvider>
    );
}

Provider Props

Prop Type Required Description
config Brook ✓ Brook client instance

3. Subscribe to Topics

import { useStream } from '@aptly-sdk/brook/react';

function Component1() {
    // Automatically subscribes on mount and unsubscribes on unmount
    useStream('my-topic', (message, metadata) => {
        console.log('Received:', message);
        console.log('Metadata:', metadata);
    });
}

Note: useStream automatically subscribes on component mount and unsubscribes on unmount. You typically don't need to use the subscribe and unsubscribe functions from the returned object.

useStream Hook

Parameters
Parameter Type Required Description
topic string ✓ The topic/channel name to subscribe to
callback function ✓ Callback function called when messages are received

Callback signature: (message, metadata) => void

Parameter Type Description
message any The message data received
metadata object Message metadata
metadata.offset number Message sequence number
metadata.timestamp string ISO timestamp when message was sent
metadata.replay boolean True if this is a replayed (missed) message
metadata.channel string Channel name
Returns
Property Type Description
streaming boolean Whether actively streaming
subscribe () => void (Optional) Function to manually subscribe - rarely needed
unsubscribe () => void (Optional) Function to manually unsubscribe - rarely needed

4. Publish to Topics

import { usePublish } from '@aptly-sdk/brook/react';

function Component2() {
    const publish = usePublish('my-topic');

    useEffect(() => {
        publish({
            message: 'Hello from React SDK',
        });
    }, []);
}

usePublish Hook

Parameters
Parameter Type Required Description
topic string ✓ The topic/channel name to publish to
Returns
Property Type Description
publish (data: any) => Promise<PublishResult> Function to publish messages to the channel
publish() Method

Parameters

Parameter Type Required Description
data any ✓ Serializable value that will be sent to the channel

Returns Promise<PublishResult>

Property Type Description
error string | null Error message (if any)
success boolean Success indicator
offset number Message offset in the channel

Additional React Hooks

useConnection

Monitor the connection status.

import { useConnection } from '@aptly-sdk/brook/react';

function Component3() {
    const { status } = useConnection();

    console.log('Connection status', status);
}
Returns
Property Type Description
status string Current connection status: 'disconnected', 'connecting', 'unauthorized', 'authenticating', 'connected', 'reconnecting', or 'failed'

TypeScript Support

This package includes comprehensive TypeScript declarations. All hooks and client methods are fully typed for an optimal development experience.