hyperstack-react 0.3.1 → 0.3.3

package/README.md

@@ -45,6 +45,7 @@ function MyComponent() {
 - **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
+- **Single Item Queries**: Type-safe single item fetching with `take: 1` or `useOne()`
 
 ### API
 
@@ -57,6 +58,12 @@ function MyComponent() {
 - `useHyperstack` - Main hook for accessing stack functionality
 - `useHyperstackContext` - Access the runtime context directly
 
+#### View Methods
+
+- `.use()` - Subscribe to view data (returns `T[]` for lists, `T` for state)
+- `.use({ take: 1 })` - Subscribe to single item with type narrowing (returns `T | undefined`)
+- `.useOne()` - Convenience method for single item queries (returns `T | undefined`)
+
 #### Factory Functions
 
 - `defineStack` - Define a new stack configuration

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import React, { ReactNode } from 'react';
-import { StorageAdapter, StorageAdapterConfig, UpdateCallback, RichUpdateCallback, Update, RichUpdate, ConnectionState, ConnectionManager, SubscriptionRegistry } from 'hyperstack-typescript';
+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 { UseBoundStore, StoreApi } from 'zustand';
 
@@ -31,6 +31,8 @@ interface StackDefinition {
 interface ViewGroup {
     state?: ViewDef<unknown, 'state'>;
     list?: ViewDef<unknown, 'list'>;
+    /** Allow arbitrary derived views with any name */
+    [key: string]: ViewDef<unknown, ViewMode> | undefined;
 }
 interface HyperstackConfig {
     websocketUrl?: string;
@@ -41,6 +43,13 @@ interface HyperstackConfig {
     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;
@@ -57,12 +66,20 @@ interface ViewHookResult<T> {
     error?: Error;
     refresh: () => void;
 }
-interface ListParams {
+interface ListParamsBase {
     key?: string;
     where?: Record<string, unknown>;
     limit?: number;
     filters?: Record<string, string>;
+    skip?: number;
 }
+interface ListParamsSingle extends ListParamsBase {
+    take: 1;
+}
+interface ListParamsMultiple extends ListParamsBase {
+    take?: number;
+}
+type ListParams = ListParamsSingle | ListParamsMultiple;
 interface UseMutationReturn {
     submit: (instructionOrTx: unknown | unknown[]) => Promise<string>;
     status: 'idle' | 'pending' | 'success' | 'error';
@@ -76,11 +93,15 @@ interface StateViewHook<T> {
     }, options?: ViewHookOptions) => ViewHookResult<T>;
 }
 interface ListViewHook<T> {
-    use: (params?: ListParams, options?: ViewHookOptions) => ViewHookResult<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>;
 }
 
 interface ZustandState {
     entities: Map<string, Map<string, unknown>>;
+    sortedKeys: Map<string, string[]>;
+    viewConfigs: Map<string, ViewSortConfig>;
     connectionState: ConnectionState;
     lastError?: string;
 }
@@ -89,6 +110,8 @@ interface ZustandActions {
     _delete: (viewPath: string, key: string) => void;
     _clear: (viewPath?: string) => void;
     _setConnectionState: (state: ConnectionState, error?: string) => void;
+    _setViewConfig: (viewPath: string, config: ViewSortConfig) => void;
+    _updateSortedKeys: (viewPath: string, sortedKeys: string[]) => void;
 }
 type HyperStackStore = ZustandState & ZustandActions;
 declare class ZustandAdapter implements StorageAdapter {
@@ -113,12 +136,17 @@ declare class ZustandAdapter implements StorageAdapter {
     notifyUpdate<T>(viewPath: string, key: string, update: Update<T>): void;
     notifyRichUpdate<T>(viewPath: string, key: string, update: RichUpdate<T>): void;
     setConnectionState(state: ConnectionState, error?: string): void;
+    setViewConfig(viewPath: string, config: ViewSortConfig): void;
+    getViewConfig(viewPath: string): ViewSortConfig | undefined;
+    private rebuildSortedKeys;
 }
 
 interface SubscriptionHandle {
     view: string;
     key?: string;
     filters?: Record<string, string>;
+    take?: number;
+    skip?: number;
     unsubscribe: () => void;
 }
 interface HyperstackRuntime {
@@ -127,7 +155,7 @@ interface HyperstackRuntime {
     connection: ConnectionManager;
     subscriptionRegistry: SubscriptionRegistry;
     wallet?: WalletAdapter;
-    subscribe(view: string, key?: string, filters?: Record<string, string>): SubscriptionHandle;
+    subscribe(view: string, key?: string, filters?: Record<string, string>, take?: number, skip?: number): SubscriptionHandle;
     unsubscribe(handle: SubscriptionHandle): void;
 }
 declare function createRuntime(config: HyperstackConfig): HyperstackRuntime;
@@ -144,30 +172,25 @@ 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'> ? {
+    use: {
+        (params: ListParamsSingle, options?: ViewHookOptions): ViewHookResult<T | undefined>;
+        (params?: ListParamsMultiple, options?: ViewHookOptions): ViewHookResult<T[]>;
+    };
+    useOne: (params?: Omit<ListParamsBase, 'take'>, options?: ViewHookOptions) => ViewHookResult<T | 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[]>;
+    };
+    useOne: (params?: Omit<ListParamsBase, 'take'>, options?: ViewHookOptions) => ViewHookResult<T | undefined>;
+} : never;
 type BuildViewInterface<TViews extends Record<string, ViewGroup>> = {
-    [K in keyof TViews]: TViews[K] extends {
-        state: ViewDef<infer S, 'state'>;
-        list: ViewDef<infer L, 'list'>;
-    } ? {
-        state: {
-            use: (key: Record<string, string>, options?: ViewHookOptions) => ViewHookResult<S>;
-        };
-        list: {
-            use: (params?: ListParams, options?: ViewHookOptions) => ViewHookResult<L[]>;
-        };
-    } : TViews[K] extends {
-        state: ViewDef<infer S, 'state'>;
-    } ? {
-        state: {
-            use: (key: Record<string, string>, options?: ViewHookOptions) => ViewHookResult<S>;
-        };
-    } : TViews[K] extends {
-        list: ViewDef<infer L, 'list'>;
-    } ? {
-        list: {
-            use: (params?: ListParams, options?: ViewHookOptions) => ViewHookResult<L[]>;
-        };
-    } : object;
+    [K in keyof TViews]: {
+        [SubK in keyof TViews[K] as TViews[K][SubK] extends ViewDef<unknown, ViewMode> ? SubK : never]: ViewHookForDef<TViews[K][SubK]>;
+    };
 };
 type StackClient<TStack extends StackDefinition> = {
     views: BuildViewInterface<TStack['views']>;
@@ -184,4 +207,4 @@ type StackClient<TStack extends StackDefinition> = {
 declare function useHyperstack<TStack extends StackDefinition>(stack: TStack): StackClient<TStack>;
 
 export { HyperstackProvider, ZustandAdapter, createRuntime, useConnectionState, useEntity, useHyperstack, useHyperstackContext, useView };
-export type { HyperStackStore, HyperstackConfig, HyperstackRuntime, ListParams, ListViewHook, NetworkConfig, StackDefinition, StateViewHook, SubscriptionHandle, TransactionDefinition, UseMutationReturn, ViewDef, ViewGroup, ViewHookOptions, ViewHookResult, ViewMode, WalletAdapter };
+export type { HyperStackStore, HyperstackConfig, HyperstackRuntime, ListParams, ListParamsBase, ListParamsMultiple, ListParamsSingle, ListViewHook, NetworkConfig, StackDefinition, StateViewHook, SubscriptionHandle, TransactionDefinition, UseMutationReturn, ViewDef, ViewGroup, ViewHookOptions, ViewHookResult, ViewMode, WalletAdapter };