hyperstack-react 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Hypertek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# @hypertek/typescript
+
+TypeScript SDK for real-time Solana program data streaming from hyperstack
+
+## Installation
+
+```bash
+npm install @hypertek/typescript
+```
+
+## Peer Dependencies
+
+This package requires:
+- `react` ^18.0.0
+- `zustand` ^4.0.0
+
+## Usage
+
+### Basic Setup
+
+```tsx
+import { HyperstackProvider, useHyperstack, defineStack } from '@hypertek/typescript';
+
+const myStack = defineStack({
+  // Your stack configuration
+});
+
+function App() {
+  return (
+    <HyperstackProvider config={{ /* your config */ }}>
+      <MyComponent />
+    </HyperstackProvider>
+  );
+}
+
+function MyComponent() {
+  const stack = useHyperstack(myStack);
+  // Use your stack
+}
+```
+
+### Core Features
+
+- **Real-time Data Streaming**: Subscribe to Solana program state changes
+- **React Integration**: Hooks-based API for easy integration with React applications
+- **State Management**: Built-in state management with Zustand
+- **Type Safety**: Full TypeScript support with comprehensive type definitions
+- **View Definitions**: Create state and list views for your data
+- **Transaction Handling**: Define and execute transactions with hooks
+
+### API
+
+#### Providers
+
+- `HyperstackProvider` - Root provider for Hyperstack configuration
+
+#### Hooks
+
+- `useHyperstack` - Main hook for accessing stack functionality
+- `useHyperstackContext` - Access the runtime context directly
+
+#### Factory Functions
+
+- `defineStack` - Define a new stack configuration
+- `createStateView` - Create a state view
+- `createListView` - Create a list view
+- `createRuntime` - Create a runtime instance
+
+#### Utilities
+
+- `ConnectionManager` - Manage WebSocket connections
+
+## License
+
+MIT
+
+## Author
+
+HyperTek

package/dist/index.d.ts

@@ -0,0 +1,255 @@
+import React, { ReactNode } from 'react';
+import * as zustand from 'zustand';
+
+interface EntityFrame<T = unknown> {
+    mode: 'state' | 'kv' | 'append' | 'list';
+    entity: string;
+    op: 'create' | 'upsert' | 'patch' | 'delete';
+    key: string;
+    data: T;
+}
+interface Subscription {
+    view: string;
+    key?: string;
+    partition?: string;
+    filters?: Record<string, string>;
+}
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'error' | 'reconnecting';
+interface HyperState<T = unknown> {
+    connectionState: ConnectionState;
+    lastError?: string;
+    entities: Map<string, Map<string, T>>;
+    recentFrames: EntityFrame<T>[];
+}
+interface HyperSDKConfig {
+    websocketUrl?: string;
+    reconnectIntervals?: number[];
+    maxReconnectAttempts?: number;
+    initialSubscriptions?: Subscription[];
+    supportsUnsubscribe?: boolean;
+    autoSubscribeDefault?: boolean;
+}
+declare const DEFAULT_CONFIG: HyperSDKConfig;
+declare class HyperStreamError extends Error {
+    code: string;
+    details?: unknown | undefined;
+    constructor(message: string, // human-readable error message
+    code: string, // machine-readable error code (e.g., 'CONNECTION_FAILED')
+    details?: unknown | undefined);
+}
+type ViewMode = 'state' | 'list';
+interface NetworkConfig {
+    name: string;
+    websocketUrl: string;
+}
+interface ViewDefinition<T = any> {
+    mode: ViewMode;
+    view: string;
+    type: T;
+    transform?: (data: any) => T;
+}
+interface TransactionDefinition<TParams = any> {
+    build: (params: TParams) => {
+        instruction: string;
+        params: TParams;
+    };
+    refresh?: Array<{
+        view: string;
+        key?: string | ((params: TParams) => string);
+    }>;
+}
+interface StackDefinition {
+    name: string;
+    views: Record<string, any>;
+    transactions?: Record<string, TransactionDefinition>;
+    helpers?: Record<string, (...args: any[]) => any>;
+}
+interface HyperstackConfig {
+    websocketUrl?: string;
+    network?: 'devnet' | 'mainnet' | 'localnet' | NetworkConfig;
+    apiKey?: string;
+    autoConnect?: boolean;
+    wallet?: WalletAdapter;
+}
+interface WalletAdapter {
+    publicKey: string;
+    signAndSend: (transaction: any) => Promise<string>;
+}
+interface ViewHookOptions {
+    enabled?: boolean;
+    initialData?: any;
+    refreshOnReconnect?: boolean;
+}
+interface ViewHookResult<T> {
+    data: T | undefined;
+    isLoading: boolean;
+    error?: Error;
+    refresh: () => void;
+}
+interface ListParams {
+    key?: string;
+    where?: Record<string, any>;
+    limit?: number;
+    filters?: Record<string, string>;
+}
+interface UseMutationReturn {
+    submit: (instructionOrTx: any | any[]) => Promise<string>;
+    status: 'idle' | 'pending' | 'success' | 'error';
+    error?: string;
+    signature?: string;
+    reset: () => void;
+}
+interface StateViewHook<T> {
+    use: (key: {
+        [keyField: string]: string;
+    }, options?: ViewHookOptions) => ViewHookResult<T>;
+}
+interface ListViewHook<T> {
+    use: (params?: ListParams, options?: ViewHookOptions) => ViewHookResult<T[]>;
+}
+
+type FrameHandler = <T>(frame: EntityFrame<T>) => void;
+type StateHandler = (state: ConnectionState, error?: string) => void;
+declare class ConnectionManager {
+    private ws;
+    private config;
+    private reconnectAttempts;
+    private reconnectTimeout;
+    private pingInterval;
+    private currentState;
+    private subscriptionQueue;
+    private onFrame?;
+    private onStateChange?;
+    constructor(config?: Partial<HyperSDKConfig>);
+    setHandlers(handlers: {
+        onFrame?: FrameHandler;
+        onStateChange?: StateHandler;
+    }): void;
+    getState(): ConnectionState;
+    getConfig(): HyperSDKConfig;
+    connect(): void;
+    disconnect(): void;
+    updateConfig(newConfig: Partial<HyperSDKConfig>): void;
+    subscribe(subscription: Subscription): void;
+    unsubscribe(_view: string, _key?: string): void;
+    private parseBinaryFrame;
+    private updateState;
+    private handleReconnect;
+    private clearReconnectTimeout;
+    private startPingInterval;
+    private stopPingInterval;
+}
+
+type SubKey = string;
+interface SubscriptionTracker {
+    subscription: Subscription;
+    refCount: number;
+}
+interface ViewMetadata {
+    mode: ViewMode;
+    keys: string[];
+    lastArgs?: any;
+    lastUpdatedAt?: number;
+}
+interface ViewCache {
+    [viewPath: string]: ViewMetadata;
+}
+interface HyperStore extends HyperState {
+    handleFrame: <T>(frame: EntityFrame<T>) => void;
+    _incRef: (subscription: Subscription) => void;
+    _decRef: (subscription: Subscription) => void;
+    _getRefCount: (subscription: Subscription) => number;
+    subscribe: (subscription: Subscription) => void;
+    unsubscribe: (entity: string, key?: string) => void;
+    connect: () => void;
+    disconnect: () => void;
+    updateConfig: (config: Partial<HyperSDKConfig>) => void;
+    subscriptionRefs: Map<SubKey, SubscriptionTracker>;
+    connectionManager: ConnectionManager;
+    viewCache: ViewCache;
+}
+declare function createHyperStore(config?: Partial<HyperSDKConfig>): zustand.UseBoundStore<zustand.StoreApi<HyperStore>>;
+
+interface SubscriptionHandle {
+    view: string;
+    key?: string;
+    filters?: Record<string, string>;
+    unsubscribe: () => void;
+}
+interface HyperstackRuntime {
+    store: ReturnType<typeof createHyperStore>;
+    connection: ConnectionManager;
+    wallet?: WalletAdapter;
+    subscribe(view: string, key?: string, filters?: Record<string, string>): SubscriptionHandle;
+    unsubscribe(handle: SubscriptionHandle): void;
+}
+declare function createRuntime(config: HyperstackConfig): HyperstackRuntime;
+
+interface HyperstackContextValue {
+    runtime: HyperstackRuntime;
+    config: HyperstackConfig;
+}
+declare function HyperstackProvider({ children, ...config }: HyperstackConfig & {
+    children: ReactNode;
+}): React.JSX.Element;
+declare function useHyperstackContext(): HyperstackContextValue;
+
+declare function defineStack<TViews extends Record<string, any>, TTxs extends Record<string, TransactionDefinition>, THelpers extends Record<string, (...args: any[]) => any>>(definition: {
+    name: string;
+    views: TViews;
+    transactions?: TTxs;
+    helpers?: THelpers;
+}): StackDefinition & {
+    views: TViews;
+    transactions?: TTxs;
+    helpers?: THelpers;
+};
+type InferViewType<T> = T extends ViewDefinition<infer U> ? U : never;
+type BuildViewInterface<TViews extends Record<string, any>> = {
+    [K in keyof TViews]: TViews[K] extends {
+        state: ViewDefinition<any>;
+        list: ViewDefinition<any>;
+    } ? {
+        state: {
+            use: (key: Record<string, string>, options?: ViewHookOptions) => ViewHookResult<InferViewType<TViews[K]['state']>>;
+        };
+        list: {
+            use: (params?: ListParams, options?: ViewHookOptions) => ViewHookResult<InferViewType<TViews[K]['list']>[]>;
+        };
+    } : TViews[K] extends {
+        state: ViewDefinition<any>;
+    } ? {
+        state: {
+            use: (key: Record<string, string>, options?: ViewHookOptions) => ViewHookResult<InferViewType<TViews[K]['state']>>;
+        };
+    } : TViews[K] extends {
+        list: ViewDefinition<any>;
+    } ? {
+        list: {
+            use: (params?: ListParams, options?: ViewHookOptions) => ViewHookResult<InferViewType<TViews[K]['list']>[]>;
+        };
+    } : never;
+};
+type StackClient<TStack extends StackDefinition> = {
+    views: BuildViewInterface<TStack['views']>;
+    tx: TStack['transactions'] extends Record<string, TransactionDefinition> ? {
+        [K in keyof TStack['transactions']]: TStack['transactions'][K]['build'];
+    } & {
+        useMutation: () => UseMutationReturn;
+    } : {
+        useMutation: () => UseMutationReturn;
+    };
+    helpers: TStack['helpers'] extends Record<string, (...args: any[]) => any> ? TStack['helpers'] : {};
+    store: HyperstackRuntime['store'];
+    runtime: HyperstackRuntime;
+};
+declare function useHyperstack<TStack extends StackDefinition>(stack: TStack): StackClient<TStack>;
+
+interface ViewFactoryOptions<T> {
+    transform?: (data: any) => T;
+}
+declare function createStateView<T>(viewPath: string, options?: ViewFactoryOptions<T>): ViewDefinition<T>;
+declare function createListView<T>(viewPath: string, options?: ViewFactoryOptions<T>): ViewDefinition<T>;
+
+export { ConnectionManager, DEFAULT_CONFIG, HyperStreamError, HyperstackProvider, createListView, createRuntime, createStateView, defineStack, useHyperstack, useHyperstackContext };
+export type { ConnectionState, EntityFrame, HyperSDKConfig, HyperstackConfig, HyperstackRuntime, ListParams, ListViewHook, NetworkConfig, StackDefinition, StateViewHook, Subscription, SubscriptionHandle, TransactionDefinition, UseMutationReturn, ViewDefinition, ViewHookOptions, ViewHookResult, ViewMode, WalletAdapter };