hyperstack-typescript 0.2.0

package/README.md

@@ -0,0 +1,111 @@
+# Hyperstack TypeScript SDK
+
+Pure TypeScript SDK for the Hyperstack Solana streaming platform. Framework-agnostic core with AsyncIterable-based streaming.
+
+## Installation
+
+```bash
+npm install hyperstack-typescript
+```
+
+## Usage
+
+### Setup
+
+```typescript
+import { HyperStack } from 'hyperstack-typescript';
+import { SETTLEMENT_GAME_STACK } from './generated/settlement-game-stack';
+
+const hs = await HyperStack.connect('wss://mainnet.hyperstack.xyz', {
+  stack: SETTLEMENT_GAME_STACK,
+});
+```
+
+### Streaming with AsyncIterable
+
+```typescript
+for await (const update of hs.views.settlementGame.list.watch()) {
+  if (update.type === 'upsert') {
+    console.log('Game updated:', update.key, update.data);
+  } else if (update.type === 'delete') {
+    console.log('Game deleted:', update.key);
+  }
+}
+
+for await (const update of hs.views.settlementGame.state.watch('game-123')) {
+  console.log('Game 123 updated:', update.data);
+}
+
+for await (const update of hs.views.settlementGame.list.watchRich()) {
+  if (update.type === 'updated') {
+    console.log('Changed from:', update.before);
+    console.log('Changed to:', update.after);
+  }
+}
+```
+
+### One-Shot Queries
+
+```typescript
+const games = await hs.views.settlementGame.list.get();
+
+const game = await hs.views.settlementGame.state.get('game-123');
+```
+
+### Connection Management
+
+```typescript
+console.log(hs.connectionState);
+
+const unsubscribe = hs.onConnectionStateChange((state) => {
+  console.log('Connection state:', state);
+});
+
+await hs.disconnect();
+```
+
+## API
+
+### HyperStack
+
+Main client class with typed view accessors.
+
+- `HyperStack.connect(url, options)` - Connect to a HyperStack server
+- `views` - Typed view accessors based on your stack definition
+- `connectionState` - Current connection state
+- `onConnectionStateChange(callback)` - Listen for connection changes
+- `disconnect()` - Disconnect from the server
+
+### Views
+
+Each view provides:
+
+**StateView (keyed entities)**
+- `watch(key)` - AsyncIterable of updates for a specific key
+- `watchRich(key)` - AsyncIterable with before/after diffs
+- `get(key)` - Get entity by key
+- `getSync(key)` - Get entity synchronously (if available)
+
+**ListView (collections)**
+- `watch()` - AsyncIterable of all updates
+- `watchRich()` - AsyncIterable with before/after diffs
+- `get()` - Get all entities
+- `getSync()` - Get all entities synchronously (if available)
+
+### Update Types
+
+```typescript
+type Update<T> =
+  | { type: 'upsert'; key: string; data: T }
+  | { type: 'patch'; key: string; data: Partial<T> }
+  | { type: 'delete'; key: string };
+
+type RichUpdate<T> =
+  | { type: 'created'; key: string; data: T }
+  | { type: 'updated'; key: string; before: T; after: T; patch?: unknown }
+  | { type: 'deleted'; key: string; lastKnown?: T };
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,206 @@
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error';
+type Update<T> = {
+    type: 'upsert';
+    key: string;
+    data: T;
+} | {
+    type: 'patch';
+    key: string;
+    data: Partial<T>;
+} | {
+    type: 'delete';
+    key: string;
+};
+type RichUpdate<T> = {
+    type: 'created';
+    key: string;
+    data: T;
+} | {
+    type: 'updated';
+    key: string;
+    before: T;
+    after: T;
+    patch?: unknown;
+} | {
+    type: 'deleted';
+    key: string;
+    lastKnown?: T;
+};
+interface ViewDef<T, TMode extends 'state' | 'list'> {
+    readonly mode: TMode;
+    readonly view: string;
+    readonly _entity?: T;
+}
+interface StackDefinition {
+    readonly name: string;
+    readonly views: Record<string, ViewGroup>;
+}
+interface ViewGroup {
+    state?: ViewDef<unknown, 'state'>;
+    list?: ViewDef<unknown, 'list'>;
+}
+interface Subscription {
+    view: string;
+    key?: string;
+    partition?: string;
+    filters?: Record<string, string>;
+}
+interface HyperStackOptions<TStack extends StackDefinition> {
+    stack: TStack;
+    autoReconnect?: boolean;
+    reconnectIntervals?: number[];
+    maxReconnectAttempts?: number;
+}
+interface HyperStackConfig {
+    websocketUrl?: string;
+    reconnectIntervals?: number[];
+    maxReconnectAttempts?: number;
+    initialSubscriptions?: Subscription[];
+}
+declare const DEFAULT_CONFIG: Required<Pick<HyperStackConfig, 'reconnectIntervals' | 'maxReconnectAttempts'>>;
+declare class HyperStackError extends Error {
+    code: string;
+    details?: unknown | undefined;
+    constructor(message: string, code: string, details?: unknown | undefined);
+}
+type TypedViews<TViews extends StackDefinition['views']> = {
+    [K in keyof TViews]: TypedViewGroup<TViews[K]>;
+};
+type TypedViewGroup<TGroup> = {
+    state: TGroup extends {
+        state: ViewDef<infer T, 'state'>;
+    } ? TypedStateView<T> : never;
+    list: TGroup extends {
+        list: ViewDef<infer T, 'list'>;
+    } ? TypedListView<T> : never;
+};
+interface TypedStateView<T> {
+    watch(key: string): AsyncIterable<Update<T>>;
+    watchRich(key: string): AsyncIterable<RichUpdate<T>>;
+    get(key: string): Promise<T | null>;
+    getSync(key: string): T | null | undefined;
+}
+interface TypedListView<T> {
+    watch(): AsyncIterable<Update<T>>;
+    watchRich(): AsyncIterable<RichUpdate<T>>;
+    get(): Promise<T[]>;
+    getSync(): T[] | undefined;
+}
+type SubscribeCallback<T> = (update: Update<T>) => void;
+type UnsubscribeFn = () => void;
+type ConnectionStateCallback = (state: ConnectionState, error?: string) => void;
+
+type FrameMode = 'state' | 'append' | 'list';
+type FrameOp = 'create' | 'upsert' | 'patch' | 'delete';
+interface EntityFrame<T = unknown> {
+    mode: FrameMode;
+    entity: string;
+    op: FrameOp;
+    key: string;
+    data: T;
+}
+declare function parseFrame(data: ArrayBuffer | string): EntityFrame;
+declare function parseFrameFromBlob(blob: Blob): Promise<EntityFrame>;
+declare function isValidFrame(frame: unknown): frame is EntityFrame;
+
+type FrameHandler = <T>(frame: EntityFrame<T>) => void;
+declare class ConnectionManager {
+    private ws;
+    private websocketUrl;
+    private reconnectIntervals;
+    private maxReconnectAttempts;
+    private reconnectAttempts;
+    private reconnectTimeout;
+    private pingInterval;
+    private currentState;
+    private subscriptionQueue;
+    private activeSubscriptions;
+    private frameHandlers;
+    private stateHandlers;
+    constructor(config: HyperStackConfig);
+    getState(): ConnectionState;
+    onFrame(handler: FrameHandler): () => void;
+    onStateChange(handler: ConnectionStateCallback): () => void;
+    connect(): Promise<void>;
+    disconnect(): void;
+    subscribe(subscription: Subscription): void;
+    unsubscribe(view: string, key?: string): void;
+    isConnected(): boolean;
+    private makeSubKey;
+    private flushSubscriptionQueue;
+    private resubscribeActive;
+    private updateState;
+    private notifyFrameHandlers;
+    private handleReconnect;
+    private clearReconnectTimeout;
+    private startPingInterval;
+    private stopPingInterval;
+}
+
+type EntityUpdateCallback = (viewPath: string, key: string, update: Update<unknown>) => void;
+type RichUpdateCallback = (viewPath: string, key: string, update: RichUpdate<unknown>) => void;
+declare class EntityStore {
+    private entities;
+    private updateCallbacks;
+    private richUpdateCallbacks;
+    handleFrame<T>(frame: EntityFrame<T>): void;
+    getAll<T>(viewPath: string): T[];
+    get<T>(viewPath: string, key: string): T | null;
+    getAllSync<T>(viewPath: string): T[] | undefined;
+    getSync<T>(viewPath: string, key: string): T | null | undefined;
+    keys(viewPath: string): string[];
+    size(viewPath: string): number;
+    clear(): void;
+    clearView(viewPath: string): void;
+    onUpdate(callback: EntityUpdateCallback): UnsubscribeFn;
+    onRichUpdate(callback: RichUpdateCallback): UnsubscribeFn;
+    subscribe<T>(viewPath: string, callback: SubscribeCallback<T>): UnsubscribeFn;
+    subscribeToKey<T>(viewPath: string, key: string, callback: SubscribeCallback<T>): UnsubscribeFn;
+    private notifyUpdate;
+    private notifyRichUpdate;
+    private notifyRichDelete;
+}
+
+declare class SubscriptionRegistry {
+    private subscriptions;
+    private connection;
+    constructor(connection: ConnectionManager);
+    subscribe(subscription: Subscription): UnsubscribeFn;
+    unsubscribe(subscription: Subscription): void;
+    getRefCount(subscription: Subscription): number;
+    getActiveSubscriptions(): Subscription[];
+    clear(): void;
+    private makeSubKey;
+}
+
+declare class HyperStack<TStack extends StackDefinition> {
+    private readonly connection;
+    private readonly store;
+    private readonly subscriptionRegistry;
+    private readonly _views;
+    private readonly stack;
+    private constructor();
+    static connect<T extends StackDefinition>(url: string, options: HyperStackOptions<T>): Promise<HyperStack<T>>;
+    get views(): TypedViews<TStack['views']>;
+    get connectionState(): ConnectionState;
+    get stackName(): string;
+    onConnectionStateChange(callback: ConnectionStateCallback): UnsubscribeFn;
+    onFrame(callback: (frame: EntityFrame) => void): UnsubscribeFn;
+    connect(): Promise<void>;
+    disconnect(): void;
+    isConnected(): boolean;
+    clearStore(): void;
+    getStore(): EntityStore;
+    getConnection(): ConnectionManager;
+    getSubscriptionRegistry(): SubscriptionRegistry;
+}
+
+declare function createUpdateStream<T>(store: EntityStore, subscriptionRegistry: SubscriptionRegistry, subscription: Subscription, keyFilter?: string): AsyncIterable<Update<T>>;
+declare function createRichUpdateStream<T>(store: EntityStore, subscriptionRegistry: SubscriptionRegistry, subscription: Subscription, keyFilter?: string): AsyncIterable<RichUpdate<T>>;
+
+declare function createTypedStateView<T>(viewDef: ViewDef<T, 'state'>, store: EntityStore, subscriptionRegistry: SubscriptionRegistry): TypedStateView<T>;
+declare function createTypedListView<T>(viewDef: ViewDef<T, 'list'>, store: EntityStore, subscriptionRegistry: SubscriptionRegistry): TypedListView<T>;
+declare function createTypedViews<TStack extends StackDefinition>(stack: TStack, store: EntityStore, subscriptionRegistry: SubscriptionRegistry): TypedViews<TStack['views']>;
+
+export { ConnectionManager, DEFAULT_CONFIG, EntityStore, HyperStack, HyperStackError, SubscriptionRegistry, createRichUpdateStream, createTypedListView, createTypedStateView, createTypedViews, createUpdateStream, isValidFrame, parseFrame, parseFrameFromBlob };
+export type { ConnectionState, ConnectionStateCallback, EntityFrame, FrameMode, FrameOp, HyperStackConfig, HyperStackOptions, RichUpdate, StackDefinition, SubscribeCallback, Subscription, TypedListView, TypedStateView, TypedViewGroup, TypedViews, UnsubscribeFn, Update, ViewDef, ViewGroup };