@stacksjs/realtime 0.70.87 → 0.70.88

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/realtime",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.87",
+  "version": "0.70.88",
   "description": "The Stacks realtime integration. Built on top of ts-broadcasting.",
   "author": "Chris Breuer",
   "contributors": [
@@ -53,7 +53,7 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "ts-broadcasting": "^0.0.5"
+    "ts-broadcasting": "^0.0.8"
   },
   "devDependencies": {
     "better-dx": "^0.2.16"

package/dist/broadcast.d.ts

@@ -1,62 +0,0 @@
-import type { ChannelType } from 'ts-broadcasting';
-/**
- * Install (or clear) the backpressure guard. Pass `null` to disable.
- */
-export declare function setBackpressureGuard(cfg: BackpressureGuardConfig | null): void;
-/**
- * Read the currently-installed guard config (useful for tests).
- */
-export declare function getBackpressureGuard(): Required<BackpressureGuardConfig> | null;
-/**
- * Run a broadcast from a broadcast file
- *
- * @example
- * await runBroadcast('OrderCreated', { orderId: 123 })
- */
-export declare function runBroadcast(name: string, payload?: any): Promise<void>;
-/**
- * Alias for runBroadcast.
- *
- * @example
- * await broadcast('OrderCreated', { orderId: 123 })
- */
-export declare function broadcast(name: string, payload?: any): Promise<void>;
-/**
- * Backpressure guard config (stacksjs/stacks#1877 R-2). The default
- * threshold is 1 MiB of buffered-bytes per socket — above this, the
- * configured `onSlow` callback fires once per offending socket per
- * broadcast. Apps install via `setBackpressureGuard({...})`; the
- * default is "no guard" for backwards-compat, so existing callers
- * see no behavior change until they opt in.
- *
- * Why opt-in: the underlying ts-broadcasting `server.broadcast()` is
- * synchronous and we can't inject between message-serialize and
- * socket-write. The best we can do at the Stacks layer is detect
- * slow consumers AROUND the broadcast call and let the app decide
- * what to do (close socket, drop client from channel, scale up).
- */
-export declare interface BackpressureGuardConfig {
-  maxPerSocketBytes?: number
-  onSlow?: (info: { channelName: string, backpressure: number, socket: unknown }) => void
-}
-export declare interface BroadcastInstance {
-  channel?: () => string | string[]
-  broadcastOn?: () => string | string[]
-  event?: () => string
-  broadcastAs?: () => string
-  data?: () => any
-  broadcastWith?: () => any
-  handle?: (payload?: any) => Promise<void> | void
-}
-/**
- * Stacks Broadcast class for backward compatibility
- * Wraps ts-broadcasting's BroadcastServer
- */
-export declare class Broadcast {
-  connect(): Promise<void>;
-  disconnect(): Promise<void>;
-  subscribe(channel: string, callback: (data: any) => void): void;
-  unsubscribe(channel: string): void;
-  broadcast(channel: string, event: string, data?: any, type?: ChannelType): void;
-  isConnected(): boolean;
-}

package/dist/channel.d.ts

@@ -1,24 +0,0 @@
-import type { ChannelType } from 'ts-broadcasting';
-/**
- * Create a new channel instance
- *
- * @example
- * // Broadcast to a public channel
- * await channel('orders').public('created', { id: 1 })
- *
- * // Broadcast to a private channel
- * await channel('orders.123').private('updated', { status: 'shipped' })
- *
- * // Broadcast to a presence channel
- * await channel('chat.room.1').presence('message', { text: 'Hello' })
- */
-export declare function channel(name: string): Channel;
-/**
- * Stacks Channel class for backward compatibility
- * Provides a fluent API for broadcasting to channels
- */
-export declare class Channel {
-  constructor(channel: string);
-  presence(event: string, data?: any): Promise<void>;
-  broadcast(event: string, data?: any, type?: ChannelType): Promise<void>;
-}

package/dist/emit.d.ts

@@ -1,37 +0,0 @@
-/**
- * Emit an event to a channel
- *
- * @example
- * // Simple emit to public channel
- * emit('orders', 'created', { id: 1, total: 99.99 })
- *
- * // Emit to private channel
- * emit('orders.123', 'updated', { status: 'shipped' }, { private: true })
- *
- * // Emit to presence channel
- * emit('chat.room.1', 'message', { text: 'Hello' }, { presence: true })
- *
- * // Exclude specific users
- * emit('chat.room.1', 'message', { text: 'Hello' }, { exclude: 'user-123' })
- */
-export declare function emit<T = unknown>(channel: string, event: string, data?: T, options?: EmitOptions): void;
-/**
- * Emit an event to a specific user
- *
- * @example
- * emitToUser('user-123', 'notification', { message: 'You have a new order!' })
- */
-export declare function emitToUser<T = unknown>(userId: string | number, event: string, data?: T, options?: Omit<EmitOptions, 'private'>): void;
-/**
- * Emit an event to multiple users
- *
- * @example
- * emitToUsers(['user-1', 'user-2'], 'announcement', { message: 'Server maintenance!' })
- */
-export declare function emitToUsers<T = unknown>(userIds: (string | number)[], event: string, data?: T, options?: Omit<EmitOptions, 'private'>): void;
-export declare interface EmitOptions {
-  private?: boolean
-  presence?: boolean
-  exclude?: string | string[]
-  driver?: string
-}

package/dist/heartbeat.d.ts

@@ -1,32 +0,0 @@
-/**
- * Install (or replace) the heartbeat config. Pass `null` to stop
- * the heartbeat loop. Safe to call multiple times — the previous
- * timer is cleared before the new one starts.
- */
-export declare function setHeartbeatConfig(cfg: HeartbeatConfig | null): void;
-/** Read the current config — useful for tests. */
-export declare function getHeartbeatConfig(): Readonly<HeartbeatState> | null;
-/**
- * Manually fire a single heartbeat tick. Exposed for tests; in
- * production it's invoked by the internal interval.
- */
-export declare function runOneTick(): void;
-/**
- * Called from the server's pong handler (or message handler when
- * fallback `__stacks_ping__` text frames are in use). Resets the
- * missed-pong counter for the given socket so it doesn't get
- * declared dead.
- */
-export declare function markPong(socket: object): void;
-export declare interface HeartbeatConfig {
-  intervalMs?: number
-  maxMissedPongs?: number
-  onDead?: (socket: unknown) => void
-}
-declare interface HeartbeatState {
-  intervalMs: number
-  maxMissedPongs: number
-  onDead: (socket: unknown) => void
-  missed: WeakMap<object, number>
-  timer: ReturnType<typeof setInterval> | null
-}

package/dist/index.d.ts

@@ -1,37 +0,0 @@
-export type { EmitOptions } from './emit';
-export type { BroadcastInstance } from './broadcast';
-export type { BackpressureGuardConfig } from './broadcast';
-export type { HeartbeatConfig } from './heartbeat';
-export type { BufferedMessage, ReplayBufferConfig } from './replay-buffer';
-export type { WsAuthenticator, WsAuthResult } from './ws';
-/**
- * Stacks Realtime Module
- *
- * This module provides real-time broadcasting capabilities for Stacks applications.
- * It's built on top of ts-broadcasting and provides a familiar Laravel-like API.
- */
-// Re-export everything from ts-broadcasting
-export * from 'ts-broadcasting';
-// Note: all exports are already provided by `export * from 'ts-broadcasting'` above.
-// Aliases are provided below for convenience.
-// Server instance management
-export { getServer, setServer, createServer, stopServer } from './server-instance';
-// Stacks-specific exports
-export { emit, emitToUser, emitToUsers } from './emit';
-export { channel, channel as createChannel, Channel as StacksChannel } from './channel';
-export { broadcast as dispatchBroadcast, runBroadcast, Broadcast as LegacyBroadcast } from './broadcast';
-// Backpressure guard for slow consumers (stacksjs/stacks#1877 R-2).
-// Opt-in via setBackpressureGuard; default is no-op.
-export { setBackpressureGuard, getBackpressureGuard } from './broadcast';
-// Heartbeat ping/pong for detecting half-closed sockets
-// (stacksjs/stacks#1877 R-5). Opt-in via setHeartbeatConfig.
-export { getHeartbeatConfig, markPong, runOneTick, setHeartbeatConfig } from './heartbeat';
-// At-least-once replay buffer for reconnect (stacksjs/stacks#1877 R-3).
-// Opt-in via setReplayBuffer. Apps wire `replaySince(channel, seq)`
-// into their reconnect handler to re-send missed messages.
-export { debugSnapshot, getReplayBuffer, pruneExpired, recordBroadcast, replaySince, setReplayBuffer } from './replay-buffer';
-export { setBunSocket, handleWebSocketRequest, storeWebSocketEvent } from './ws';
-// WebSocket authenticator wiring (stacksjs/stacks#1877 R-1). Install
-// once at server boot to require a valid token / cookie at the
-// handshake boundary — without it, the upgrade proceeds unauthed.
-export { setWsAuthenticator, getWsAuthenticator } from './ws';

package/dist/index.js

@@ -1,2 +0,0 @@
-// @bun
-export*from"ts-broadcasting";export{l as storeWebSocketEvent,C as stopServer,p as setWsAuthenticator,A as setServer,m as setReplayBuffer,W as setHeartbeatConfig,f as setBunSocket,Q as setBackpressureGuard,V as runOneTick,N as runBroadcast,k as replaySince,$ as recordBroadcast,_ as pruneExpired,U as markPong,g as handleWebSocketRequest,w as getWsAuthenticator,z as getServer,Z as getReplayBuffer,T as getHeartbeatConfig,R as getBackpressureGuard,G as emitToUsers,F as emitToUser,E as emit,M as dispatchBroadcast,Y as debugSnapshot,B as createServer,J as createChannel,I as channel,K as StacksChannel,O as LegacyBroadcast};

package/dist/replay-buffer.d.ts

@@ -1,83 +0,0 @@
-/**
- * Install (or replace) the replay-buffer config. Pass `null` to disable
- * and drop all buffered state. Safe to call multiple times.
- */
-export declare function setReplayBuffer(cfg: ReplayBufferConfig | null): void;
-/** Read the current config — useful for tests. */
-export declare function getReplayBuffer(): Readonly<BufferRegistry> | null;
-/**
- * Called by the broadcast wrapper for every outbound message on a
- * matched channel. Records the message and assigns a monotonic seq.
- * Returns the seq for the caller to optionally include in the
- * outbound payload — clients store the latest seq locally and send
- * it back on reconnect via `replaySince`.
- */
-export declare function recordBroadcast(channel: string, event: string, data: unknown): number | null;
-/**
- * Replay every buffered message on `channel` with `seq > sinceSeq`.
- * Stale entries (older than `ttlMs`) are evicted on the way through
- * so callers don't see them. Returns the array of messages the
- * caller should re-send to the reconnecting client.
- *
- * @example
- * ```ts
- * // Inside the reconnect handler:
- * const missed = replaySince('orders', lastSeenSeq)
- * for (const msg of missed) {
- *   socket.send(JSON.stringify({ event: msg.event, data: msg.data, seq: msg.seq }))
- * }
- * ```
- */
-export declare function replaySince(channel: string, sinceSeq: number): BufferedMessage[];
-/**
- * Drop expired entries across every tracked channel. Called by apps
- * that want eager memory reclaim — the default lazy-on-read path is
- * adequate for most workloads.
- */
-export declare function pruneExpired(): void;
-/**
- * Snapshot the buffer state — debugging only. Don't depend on this
- * shape in production code; the internals may change.
- */
-export declare function debugSnapshot(): Record<string, { count: number, firstSeq: number | null, lastSeq: number | null }>;
-/**
- * Per-channel message replay buffer (stacksjs/stacks#1877 R-3).
- *
- * Background: ts-broadcasting delivers messages at-most-once — a client
- * that drops between two broadcasts loses everything in flight. For
- * channels where the app needs every message (chat, presence, order
- * updates), reconnect-after-network-blip becomes a silent data loss.
- *
- * Fix: opt-in per-channel ring buffer that retains the most-recent N
- * messages with monotonic sequence IDs. On reconnect, the client sends
- * its last-seen seq; the server replays everything stored after that
- * point. Apps install via `setReplayBuffer({ channels, maxPerChannel,
- * ttlMs })`. Buffer is in-process — for cross-instance replay, route
- * through a shared store (Redis Streams, Postgres LISTEN/NOTIFY, etc.).
- *
- * Memory shape: `Map<channel, RingBuffer<BufferedMessage>>`. Bounded by
- * `maxPerChannel` (default 100) so a chatty channel can't OOM the
- * server. Entries past `ttlMs` are evicted lazily on read — apps that
- * want eager eviction can call `pruneExpired()` from their own timer.
- */
-export declare interface ReplayBufferConfig {
-  channels?: string[]
-  maxPerChannel?: number
-  ttlMs?: number
-}
-export declare interface BufferedMessage {
-  seq: number
-  ts: number
-  event: string
-  data: unknown
-}
-declare interface ChannelState {
-  messages: BufferedMessage[]
-  nextSeq: number
-}
-declare interface BufferRegistry {
-  channels: string[]
-  maxPerChannel: number
-  ttlMs: number
-  state: Map<string, ChannelState>
-}

package/dist/server-instance.d.ts

@@ -1,17 +0,0 @@
-import type { BroadcastServer, ServerConfig } from 'ts-broadcasting';
-/**
- * Set the global broadcast server instance
- */
-export declare function setServer(server: BroadcastServer): void;
-/**
- * Get the global broadcast server instance
- */
-export declare function getServer(): BroadcastServer | null;
-/**
- * Create and start a new broadcast server
- */
-export declare function createServer(config: ServerConfig): Promise<BroadcastServer>;
-/**
- * Stop the current broadcast server
- */
-export declare function stopServer(): Promise<void>;

package/dist/ws.d.ts

@@ -1,44 +0,0 @@
-import type { Server } from 'bun';
-import type { BroadcastServer } from 'ts-broadcasting';
-/**
- * Set the broadcast server instance
- * @deprecated Use setServer from './server-instance' instead
- */
-export declare function setBunSocket(server: BroadcastServer | null): void;
-/**
- * Store WebSocket event in the database
- * Note: This function is now a no-op. WebSocket events are tracked internally by ts-broadcasting.
- */
-export declare function storeWebSocketEvent(_type: 'disconnection' | 'error' | 'success', _socket: string, _details: string): Promise<void>;
-/**
- * Install (or clear) the global WebSocket authenticator. Called once
- * at server boot; pass `null` to disable auth (the unauthed default).
- */
-export declare function setWsAuthenticator(fn: WsAuthenticator | null): void;
-/** Read the currently-installed authenticator. Useful for tests. */
-export declare function getWsAuthenticator(): WsAuthenticator | null;
-/**
- * Handle WebSocket request upgrade. If an authenticator is installed
- * (see `setWsAuthenticator`), it runs FIRST and a 401 is returned on
- * failure (stacksjs/stacks#1877 R-1). Without an authenticator the
- * upgrade proceeds for backwards-compat — the function still works
- * the same way it did before.
- */
-export declare function handleWebSocketRequest(req: Request, server: Server<any>): Promise<Response | undefined>;
-/**
- * Optional authenticator invoked at WebSocket handshake time.
- *
- * Apps install one via `setWsAuthenticator(fn)` to require a valid
- * token / cookie / signed query param BEFORE the upgrade goes through
- * (stacksjs/stacks#1877 R-1). Without an authenticator, the upgrade
- * proceeds as before — useful for local-dev / public-broadcast apps,
- * but production apps should always install one.
- *
- * The returned `data` is attached to the upgraded socket as `ws.data`
- * so per-message authorization can read it back without re-parsing
- * the auth token on every frame.
- */
-export type WsAuthenticator = (req: Request) => Promise<WsAuthResult> | WsAuthResult;
-/** Result returned from a `WsAuthenticator`. */
-export type WsAuthResult = | { ok: true, data?: Record<string, unknown> }
-  | { ok: false, status?: number, message?: string }