socket-store

library0.0.3jsnpmunverified

Socket-store is a lightweight WebSocket-first topic state store for JavaScript/TypeScript that routes incoming messages by topic to typed handlers. Version 0.0.3 ships TypeScript types and supports schema-based usage for type safety. It provides store.send, store.subscribe, store.getState, and connection status tracking. Compared to generic WebSocket wrappers, it offers a structured state management pattern similar to Redux but for real-time topics. Released as an early-stage package (0.x.x) with limited adoption; no breaking changes documented yet.

messaging

npm install socket-store

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SOCKET-STORE

socket-store

messagingjavascriptv0.0.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SocketStore

✓ import { SocketStore, createMessageHandler } from 'socket-store'

✗ import SocketStore from 'socket-store'

SocketStore and createMessageHandler are named exports. Default import does not exist.

createMessageHandler

✓ import { createMessageHandler } from 'socket-store'

✗ const createMessageHandler = require('socket-store').createMessageHandler

Works in both ESM and CJS environments, but named import is preferred.

SocketStoreConfig, SocketStoreEvents

✓ import type { SocketStoreConfig, SocketStoreEvents } from 'socket-store'

✗ import { SocketStoreConfig } from 'socket-store'

Type-only exports; use 'import type' for TypeScript to avoid runtime import.

Shows how to create typed handlers, instantiate SocketStore, subscribe, send, get state, and manage subscriptions.

import { SocketStore, createMessageHandler } from 'socket-store'; // Define schema interface ChatMessage { author: string; text: string; } interface PriceTick { symbol: string; value: number; } // Create handlers const chatHandler = createMessageHandler<ChatMessage[], ChatMessage, 'chat'>( 'chat', (state, payload) => [...state, payload], [] ); const priceHandler = createMessageHandler<PriceTick | null, PriceTick, 'price'>( 'price', (_state, payload) => payload, null ); // Create store const socket = new WebSocket('wss://example.com/realtime'); const store = new SocketStore(socket, [chatHandler, priceHandler]); // Subscribe store.subscribe('chat', (msgs) => console.log(msgs.at(-1))); store.subscribe('price', (p) => console.log(p)); // Send message store.send({ key: 'chat', data: { author: 'Ada', text: 'Hello' } }); // Get state const messages = store.getState('chat'); const price = store.getState('price'); // Get status const status = store.getStatus(); console.log(status); // e.g., 'open' // Unsubscribe const unsub = store.subscribe('price', () => {}); unsub();

Debug

Known issues

gotchaWebSocket must already be open or connecting. SocketStore does not manage connection lifecycle (reconnect, etc.)

fix

Pass an open/connecting WebSocket instance. Use a library like 'reconnecting-websocket' if auto-reconnect is needed.

affects: >=0.0.0

gotchacreateMessageHandler generic parameters are (stateType, payloadType, topicName). Wrong order or missing type arguments cause compilation errors.

fix

Explicitly specify state, payload, and topic (as string literal) for full type safety: createMessageHandler<State, Payload, 'topicName'>(...)

affects: >=0.0.0

deprecatedVersions <0.0.3 might have different API for handlers. Check changelog for migration.

fix

Update to 0.0.3 and follow the schema-based usage documented.

affects: <0.0.3

gotchastore.send expects argument with key and data properties. Mismatch causes runtime error or unexpected behavior.

fix

Always use { key: 'topicName', data: yourPayload }. The key must match a registered handler topic.

affects: >=0.0.0

gotchaIncoming WebSocket messages must be JSON with key and data fields. Non-JSON or missing fields are ignored or throw.

fix

Ensure server sends messages as JSON: e.g., { "key": "chat", "data": { ... } }

affects: >=0.0.0

Errors

Common errors & fixes

Type 'SocketStore<unknown, unknown>' is not assignable to type 'SocketStore<AppSchema, never>'.

Supplying incorrect schema type parameter or omitting schema type.

fix

Provide a schema type that matches the handler topics: new SocketStore<AppSchema>(socket, handlers)

Cannot find name 'createMessageHandler'. Did you mean 'SocketStore'?

Wrong import: only imported SocketStore, missing named export.

fix

import { SocketStore, createMessageHandler } from 'socket-store'

ReferenceError: WebSocket is not defined

Trying to run in Node.js without the 'ws' library or global WebSocket.

fix

Install 'ws' and assign global.WebSocket = require('ws'); or use a polyfill.

Upgrade

Version history

0.0.3latest on npm

Audit

Dependencies

wsoptionalUsed for WebSocket in Node.js environments; not needed in browsers.

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/nerdchanii/socket-store ↗

packagesocket-store ↗

homepagehttps://nerdchanii.github.io/socket-store/ ↗