hyperstack-react 0.3.14 → 0.4.0

package/dist/index.d.ts

@@ -1,18 +1,9 @@
 import React, { ReactNode } from 'react';
-import { StorageAdapter, StorageAdapterConfig, UpdateCallback, RichUpdateCallback, Update, RichUpdate, ConnectionState, ViewSortConfig, ConnectionManager, SubscriptionRegistry } from 'hyperstack-typescript';
-export { ConnectionManager, ConnectionState, DEFAULT_CONFIG, DEFAULT_MAX_ENTRIES_PER_VIEW, EntityFrame, Frame, FrameMode, FrameOp, FrameProcessor, FrameProcessorConfig, HyperStack, HyperStackConfig, HyperStackError, HyperStackOptions, HyperStackOptionsWithStorage, MemoryAdapter, RichUpdate, RichUpdateCallback, SnapshotEntity, SnapshotFrame, StorageAdapter, StorageAdapterConfig, Subscription, SubscriptionRegistry, Update, UpdateCallback, isSnapshotFrame, isValidFrame, parseFrame, parseFrameFromBlob } from 'hyperstack-typescript';
+import { WalletAdapter, StackDefinition, ConnectionState, HyperStack, InstructionExecutorOptions, ExecutionResult, InstructionExecutor, StorageAdapter, StorageAdapterConfig, UpdateCallback, RichUpdateCallback, Update, RichUpdate, ViewSortConfig, ViewGroup, ViewDef, InstructionHandler } from 'hyperstack-typescript';
+export { AccountCategory, AccountMeta, AccountResolutionOptions, AccountResolutionResult, ArgSchema, ArgType, BuiltInstruction, ConfirmationLevel, ConnectionManager, ConnectionState, DEFAULT_CONFIG, DEFAULT_MAX_ENTRIES_PER_VIEW, EntityFrame, ErrorMetadata, ExecuteOptions, ExecutionResult, Frame, FrameMode, FrameOp, FrameProcessor, FrameProcessorConfig, HyperStack, HyperStackConfig, HyperStackError, HyperStackOptions, HyperStackOptionsWithStorage, InstructionDefinition, InstructionExecutor, InstructionExecutorOptions, InstructionHandler, MemoryAdapter, PdaConfig, PdaSeed, ProgramError, ResolvedAccount, ResolvedAccounts, RichUpdate, RichUpdateCallback, SnapshotEntity, SnapshotFrame, StackDefinition, StorageAdapter, StorageAdapterConfig, Subscription, SubscriptionRegistry, Update, UpdateCallback, ViewDef, ViewGroup, WalletAdapter, WalletConnectOptions, WalletState, createInstructionExecutor, createPublicKeySeed, createSeed, derivePda, executeInstruction, formatProgramError, isSnapshotFrame, isValidFrame, parseFrame, parseFrameFromBlob, parseInstructionError, resolveAccounts, serializeInstructionData, validateAccountResolution, waitForConfirmation } from 'hyperstack-typescript';
 import { UseBoundStore, StoreApi } from 'zustand';
 
 type ViewMode = 'state' | 'list';
-interface NetworkConfig {
-    name: string;
-    websocketUrl: string;
-}
-interface ViewDef<T, TMode extends ViewMode> {
-    readonly mode: TMode;
-    readonly view: string;
-    readonly _entity?: T;
-}
 interface TransactionDefinition<TParams = unknown> {
     build: (params: TParams) => {
         instruction: string;
@@ -23,37 +14,27 @@ interface TransactionDefinition<TParams = unknown> {
         key?: string | ((params: TParams) => string);
     }>;
 }
-interface StackDefinition {
-    readonly name: string;
-    readonly views: Record<string, ViewGroup>;
-    transactions?: Record<string, TransactionDefinition>;
-}
-interface ViewGroup {
-    state?: ViewDef<unknown, 'state'>;
-    list?: ViewDef<unknown, 'list'>;
-    /** Allow arbitrary derived views with any name */
-    [key: string]: ViewDef<unknown, ViewMode> | undefined;
-}
+/**
+ * Global configuration for HyperstackProvider.
+ *
+ * Note: WebSocket URL is no longer configured here. The URL is:
+ * 1. Embedded in the stack definition (stack.url)
+ * 2. Optionally overridden per-hook via useHyperstack(stack, { url: '...' })
+ */
 interface HyperstackConfig {
-    websocketUrl?: string;
-    network?: 'devnet' | 'mainnet' | 'localnet' | NetworkConfig;
-    apiKey?: string;
     autoConnect?: boolean;
     wallet?: WalletAdapter;
     reconnectIntervals?: number[];
     maxReconnectAttempts?: number;
     maxEntriesPerView?: number | null;
-    /**
-     * Interval in milliseconds to buffer WebSocket updates before flushing to Zustand.
-     * Reduces React re-renders during high-frequency updates.
-     * Default: 16ms (one frame at 60fps)
-     * Set to 0 for immediate updates (no buffering).
-     */
     flushIntervalMs?: number;
 }
-interface WalletAdapter {
-    publicKey: string;
-    signAndSend: (transaction: unknown) => Promise<string>;
+/**
+ * Options for useHyperstack hook
+ */
+interface UseHyperstackOptions {
+    /** Override the stack's embedded URL (useful for local development) */
+    url?: string;
 }
 interface ViewHookOptions {
     enabled?: boolean;
@@ -98,6 +79,35 @@ interface ListViewHook<T> {
     useOne: (params?: Omit<ListParamsBase, 'take'>, options?: ViewHookOptions) => ViewHookResult<T | undefined>;
 }
 
+interface HyperstackContextValue {
+    getOrCreateClient: <TStack extends StackDefinition>(stack: TStack, urlOverride?: string) => Promise<HyperStack<TStack>>;
+    getClient: <TStack extends StackDefinition>(stack: TStack | undefined) => HyperStack<TStack> | null;
+    config: HyperstackConfig;
+}
+declare function HyperstackProvider({ children, fallback, ...config }: HyperstackConfig & {
+    children: ReactNode;
+    fallback?: ReactNode;
+}): React.JSX.Element;
+declare function useHyperstackContext(): HyperstackContextValue;
+declare function useConnectionState(stack?: StackDefinition): ConnectionState;
+declare function useView<T>(stack: StackDefinition, viewPath: string): T[];
+declare function useEntity<T>(stack: StackDefinition, viewPath: string, key: string): T | null;
+
+type MutationStatus = 'idle' | 'pending' | 'success' | 'error';
+interface UseMutationOptions extends InstructionExecutorOptions {
+    onSuccess?: (result: ExecutionResult) => void;
+    onError?: (error: Error) => void;
+}
+interface UseMutationResult {
+    submit: (args: Record<string, unknown>, options?: Partial<UseMutationOptions>) => Promise<ExecutionResult>;
+    status: MutationStatus;
+    error: string | null;
+    signature: string | null;
+    isLoading: boolean;
+    reset: () => void;
+}
+declare function useInstructionMutation(execute: InstructionExecutor): UseMutationResult;
+
 interface ZustandState {
     entities: Map<string, Map<string, unknown>>;
     sortedKeys: Map<string, string[]>;
@@ -141,37 +151,6 @@ declare class ZustandAdapter implements StorageAdapter {
     private rebuildSortedKeys;
 }
 
-interface SubscriptionHandle {
-    view: string;
-    key?: string;
-    filters?: Record<string, string>;
-    take?: number;
-    skip?: number;
-    unsubscribe: () => void;
-}
-interface HyperstackRuntime {
-    zustandStore: UseBoundStore<StoreApi<HyperStackStore>>;
-    adapter: ZustandAdapter;
-    connection: ConnectionManager;
-    subscriptionRegistry: SubscriptionRegistry;
-    wallet?: WalletAdapter;
-    subscribe(view: string, key?: string, filters?: Record<string, string>, take?: number, skip?: number): 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 useConnectionState(): ConnectionState;
-declare function useView<T>(viewPath: string): T[];
-declare function useEntity<T>(viewPath: string, key: string): T | null;
-
 type ViewHookForDef<TDef> = TDef extends ViewDef<infer T, 'state'> ? {
     use: (key?: Record<string, string>, options?: ViewHookOptions) => ViewHookResult<T>;
 } : TDef extends ViewDef<infer T, 'list'> ? {
@@ -192,19 +171,22 @@ type BuildViewInterface<TViews extends Record<string, ViewGroup>> = {
         [SubK in keyof TViews[K] as TViews[K][SubK] extends ViewDef<unknown, ViewMode> ? SubK : never]: ViewHookForDef<TViews[K][SubK]>;
     };
 };
+type InstructionHook = {
+    useMutation: () => UseMutationResult;
+    execute: InstructionExecutor;
+};
+type BuildInstructionInterface<TInstructions extends Record<string, InstructionHandler> | undefined> = TInstructions extends Record<string, InstructionHandler> ? {
+    [K in keyof TInstructions]: InstructionHook;
+} : {};
 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;
-    };
+    instructions: BuildInstructionInterface<TStack['instructions']>;
     zustandStore: UseBoundStore<StoreApi<HyperStackStore>>;
-    runtime: HyperstackRuntime;
+    client: HyperStack<TStack>;
+    isLoading: boolean;
+    error: Error | null;
 };
-declare function useHyperstack<TStack extends StackDefinition>(stack: TStack): StackClient<TStack>;
+declare function useHyperstack<TStack extends StackDefinition>(stack: TStack, options?: UseHyperstackOptions): StackClient<TStack>;
 
-export { HyperstackProvider, ZustandAdapter, createRuntime, useConnectionState, useEntity, useHyperstack, useHyperstackContext, useView };
-export type { HyperStackStore, HyperstackConfig, HyperstackRuntime, ListParams, ListParamsBase, ListParamsMultiple, ListParamsSingle, ListViewHook, NetworkConfig, StackDefinition, StateViewHook, SubscriptionHandle, TransactionDefinition, UseMutationReturn, ViewDef, ViewGroup, ViewHookOptions, ViewHookResult, ViewMode, WalletAdapter };
+export { HyperstackProvider, ZustandAdapter, useConnectionState, useEntity, useHyperstack, useHyperstackContext, useInstructionMutation, useView };
+export type { HyperStackStore, HyperstackConfig, ListParams, ListParamsBase, ListParamsMultiple, ListParamsSingle, ListViewHook, MutationStatus, StateViewHook, TransactionDefinition, UseHyperstackOptions, UseMutationOptions, UseMutationResult, UseMutationReturn, ViewHookOptions, ViewHookResult, ViewMode };