hyperstack-react 0.4.2 → 0.5.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import React, { ReactNode } from 'react';
-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 { WalletAdapter, Schema, 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, Schema, 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';
@@ -36,10 +36,12 @@ interface UseHyperstackOptions {
     /** Override the stack's embedded URL (useful for local development) */
     url?: string;
 }
-interface ViewHookOptions {
+interface ViewHookOptions<TSchema = unknown> {
     enabled?: boolean;
     initialData?: unknown;
     refreshOnReconnect?: boolean;
+    /** Schema to validate entities. Returns undefined if validation fails. */
+    schema?: Schema<TSchema>;
 }
 interface ViewHookResult<T> {
     data: T | undefined;
@@ -47,20 +49,22 @@ interface ViewHookResult<T> {
     error?: Error;
     refresh: () => void;
 }
-interface ListParamsBase {
+interface ListParamsBase<TSchema = unknown> {
     key?: string;
     where?: Record<string, unknown>;
     limit?: number;
     filters?: Record<string, string>;
     skip?: number;
+    /** Schema to validate/filter entities. Only entities passing safeParse will be returned. */
+    schema?: Schema<TSchema>;
 }
-interface ListParamsSingle extends ListParamsBase {
+interface ListParamsSingle<TSchema = unknown> extends ListParamsBase<TSchema> {
     take: 1;
 }
-interface ListParamsMultiple extends ListParamsBase {
+interface ListParamsMultiple<TSchema = unknown> extends ListParamsBase<TSchema> {
     take?: number;
 }
-type ListParams = ListParamsSingle | ListParamsMultiple;
+type ListParams<TSchema = unknown> = ListParamsSingle<TSchema> | ListParamsMultiple<TSchema>;
 interface UseMutationReturn {
     submit: (instructionOrTx: unknown | unknown[]) => Promise<string>;
     status: 'idle' | 'pending' | 'success' | 'error';
@@ -74,14 +78,15 @@ interface StateViewHook<T> {
     }, options?: ViewHookOptions) => ViewHookResult<T>;
 }
 interface ListViewHook<T> {
-    use(params: ListParamsSingle, options?: ViewHookOptions): ViewHookResult<T | undefined>;
-    use(params?: ListParamsMultiple, options?: ViewHookOptions): ViewHookResult<T[]>;
-    useOne: (params?: Omit<ListParamsBase, 'take'>, options?: ViewHookOptions) => ViewHookResult<T | undefined>;
+    use<TSchema = T>(params: ListParamsSingle<TSchema>, options?: ViewHookOptions): ViewHookResult<TSchema | undefined>;
+    use<TSchema = T>(params?: ListParamsMultiple<TSchema>, options?: ViewHookOptions): ViewHookResult<TSchema[]>;
+    useOne: <TSchema = T>(params?: Omit<ListParamsBase<TSchema>, 'take'>, options?: ViewHookOptions) => ViewHookResult<TSchema | undefined>;
 }
 
 interface HyperstackContextValue {
     getOrCreateClient: <TStack extends StackDefinition>(stack: TStack, urlOverride?: string) => Promise<HyperStack<TStack>>;
     getClient: <TStack extends StackDefinition>(stack: TStack | undefined) => HyperStack<TStack> | null;
+    subscribeToClientChanges: (callback: () => void) => () => void;
     config: HyperstackConfig;
 }
 declare function HyperstackProvider({ children, fallback, ...config }: HyperstackConfig & {
@@ -149,19 +154,19 @@ declare class ZustandAdapter implements StorageAdapter {
 }
 
 type ViewHookForDef<TDef> = TDef extends ViewDef<infer T, 'state'> ? {
-    use: (key?: Record<string, string>, options?: ViewHookOptions) => ViewHookResult<T>;
+    use: <TSchema = T>(key?: Record<string, string>, options?: ViewHookOptions<TSchema>) => ViewHookResult<TSchema>;
 } : TDef extends ViewDef<infer T, 'list'> ? {
     use: {
-        (params: ListParamsSingle, options?: ViewHookOptions): ViewHookResult<T | undefined>;
-        (params?: ListParamsMultiple, options?: ViewHookOptions): ViewHookResult<T[]>;
+        <TSchema = T>(params: ListParamsSingle<TSchema>, options?: ViewHookOptions<TSchema>): ViewHookResult<TSchema | undefined>;
+        <TSchema = T>(params?: ListParamsMultiple<TSchema>, options?: ViewHookOptions<TSchema>): ViewHookResult<TSchema[]>;
     };
-    useOne: (params?: Omit<ListParamsBase, 'take'>, options?: ViewHookOptions) => ViewHookResult<T | undefined>;
+    useOne: <TSchema = T>(params?: Omit<ListParamsBase<TSchema>, 'take'>, options?: ViewHookOptions<TSchema>) => ViewHookResult<TSchema | undefined>;
 } : TDef extends ViewDef<infer T, 'state' | 'list'> ? {
     use: {
-        (params: ListParamsSingle, options?: ViewHookOptions): ViewHookResult<T | undefined>;
-        (params?: ListParamsMultiple | Record<string, string>, options?: ViewHookOptions): ViewHookResult<T | T[]>;
+        <TSchema = T>(params: ListParamsSingle<TSchema>, options?: ViewHookOptions<TSchema>): ViewHookResult<TSchema | undefined>;
+        <TSchema = T>(params?: ListParamsMultiple<TSchema> | Record<string, string>, options?: ViewHookOptions<TSchema>): ViewHookResult<TSchema | TSchema[]>;
     };
-    useOne: (params?: Omit<ListParamsBase, 'take'>, options?: ViewHookOptions) => ViewHookResult<T | undefined>;
+    useOne: <TSchema = T>(params?: Omit<ListParamsBase<TSchema>, 'take'>, options?: ViewHookOptions<TSchema>) => ViewHookResult<TSchema | undefined>;
 } : never;
 type BuildViewInterface<TViews extends Record<string, ViewGroup>> = {
     [K in keyof TViews]: {
@@ -180,6 +185,8 @@ type StackClient<TStack extends StackDefinition> = {
     instructions: BuildInstructionInterface<TStack['instructions']>;
     zustandStore: UseBoundStore<StoreApi<HyperStackStore>>;
     client: HyperStack<TStack>;
+    connectionState: ConnectionState;
+    isConnected: boolean;
     isLoading: boolean;
     error: Error | null;
 };