hyperstack-typescript 0.3.1 → 0.3.3

package/dist/index.d.ts

@@ -44,6 +44,8 @@ interface Subscription {
     key?: string;
     partition?: string;
     filters?: Record<string, string>;
+    take?: number;
+    skip?: number;
 }
 interface HyperStackOptions<TStack extends StackDefinition> {
     stack: TStack;
@@ -93,7 +95,18 @@ type UnsubscribeFn = () => void;
 type ConnectionStateCallback = (state: ConnectionState, error?: string) => void;
 
 type FrameMode = 'state' | 'append' | 'list';
-type FrameOp = 'create' | 'upsert' | 'patch' | 'delete' | 'snapshot';
+type FrameOp = 'create' | 'upsert' | 'patch' | 'delete' | 'snapshot' | 'subscribed';
+type SortOrder = 'asc' | 'desc';
+interface SortConfig {
+    field: string[];
+    order: SortOrder;
+}
+interface SubscribedFrame {
+    op: 'subscribed';
+    view: string;
+    mode: FrameMode;
+    sort?: SortConfig;
+}
 interface EntityFrame<T = unknown> {
     mode: FrameMode;
     entity: string;
@@ -111,9 +124,13 @@ interface SnapshotFrame<T = unknown> {
     entity: string;
     op: 'snapshot';
     data: SnapshotEntity<T>[];
+    /** Indicates if this is the final snapshot batch. When false, more batches will follow. */
+    complete?: boolean;
 }
-type Frame<T = unknown> = EntityFrame<T> | SnapshotFrame<T>;
+type Frame<T = unknown> = EntityFrame<T> | SnapshotFrame<T> | SubscribedFrame;
 declare function isSnapshotFrame<T>(frame: Frame<T>): frame is SnapshotFrame<T>;
+declare function isSubscribedFrame(frame: Frame): frame is SubscribedFrame;
+declare function isEntityFrame<T>(frame: Frame<T>): frame is EntityFrame<T>;
 declare function parseFrame(data: ArrayBuffer | string): Frame;
 declare function parseFrameFromBlob(blob: Blob): Promise<Frame>;
 declare function isValidFrame(frame: unknown): frame is Frame;
@@ -153,10 +170,13 @@ declare class ConnectionManager {
 }
 
 type UpdateCallback<T = unknown> = (viewPath: string, key: string, update: Update<T>) => void;
-type RichUpdateCallback<T = unknown> = (viewPath: string, key: string, update: RichUpdate<T>) => void;
+type RichUpdateCallback$1<T = unknown> = (viewPath: string, key: string, update: RichUpdate<T>) => void;
 interface StorageAdapterConfig {
     maxEntriesPerView?: number | null;
 }
+interface ViewSortConfig {
+    sort?: SortConfig;
+}
 /**
  * Storage adapter interface for HyperStack entity storage.
  * Implement this to integrate with Zustand, Pinia, Svelte stores, Redux, IndexedDB, etc.
@@ -173,8 +193,10 @@ interface StorageAdapter {
     delete(viewPath: string, key: string): void;
     clear(viewPath?: string): void;
     evictOldest?(viewPath: string): string | undefined;
+    setViewConfig?(viewPath: string, config: ViewSortConfig): void;
+    getViewConfig?(viewPath: string): ViewSortConfig | undefined;
     onUpdate(callback: UpdateCallback): () => void;
-    onRichUpdate(callback: RichUpdateCallback): () => void;
+    onRichUpdate(callback: RichUpdateCallback$1): () => void;
     notifyUpdate<T>(viewPath: string, key: string, update: Update<T>): void;
     notifyRichUpdate<T>(viewPath: string, key: string, update: RichUpdate<T>): void;
 }
@@ -221,18 +243,86 @@ declare class HyperStack<TStack extends StackDefinition> {
 
 interface FrameProcessorConfig {
     maxEntriesPerView?: number | null;
+    /**
+     * Interval in milliseconds to buffer frames before flushing to storage.
+     * Set to 0 for immediate processing (no buffering).
+     * Default: 0 (immediate)
+     *
+     * For React applications, 16ms (one frame at 60fps) is recommended to
+     * reduce unnecessary re-renders during high-frequency updates.
+     */
+    flushIntervalMs?: number;
 }
 declare class FrameProcessor {
     private storage;
     private maxEntriesPerView;
+    private flushIntervalMs;
+    private pendingUpdates;
+    private flushTimer;
+    private isProcessing;
     constructor(storage: StorageAdapter, config?: FrameProcessorConfig);
     handleFrame<T>(frame: Frame<T>): void;
+    /**
+     * Immediately flush all pending updates.
+     * Useful for ensuring all updates are processed before reading state.
+     */
+    flush(): void;
+    /**
+     * Clean up any pending timers. Call when disposing the processor.
+     */
+    dispose(): void;
+    private scheduleFlush;
+    private flushPendingUpdates;
+    private processFrame;
+    private processFrameWithoutEnforce;
+    private handleSubscribedFrame;
     private handleSnapshotFrame;
+    private handleSnapshotFrameWithoutEnforce;
     private handleEntityFrame;
+    private handleEntityFrameWithoutEnforce;
     private emitRichUpdate;
     private enforceMaxEntries;
 }
 
+interface EntityStoreConfig {
+    maxEntriesPerView?: number | null;
+}
+interface ViewConfig {
+    sort?: SortConfig;
+}
+type EntityUpdateCallback = (viewPath: string, key: string, update: Update<unknown>) => void;
+type RichUpdateCallback = (viewPath: string, key: string, update: RichUpdate<unknown>) => void;
+declare class EntityStore {
+    private views;
+    private viewConfigs;
+    private updateCallbacks;
+    private richUpdateCallbacks;
+    private maxEntriesPerView;
+    constructor(config?: EntityStoreConfig);
+    private enforceMaxEntries;
+    handleFrame<T>(frame: Frame<T>): void;
+    private handleSubscribedFrame;
+    private handleSnapshotFrame;
+    private handleEntityFrame;
+    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;
+    getViewConfig(viewPath: string): ViewConfig | undefined;
+    setViewConfig(viewPath: string, config: ViewConfig): 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 MemoryAdapter implements StorageAdapter {
     private views;
     private updateCallbacks;
@@ -250,7 +340,7 @@ declare class MemoryAdapter implements StorageAdapter {
     clear(viewPath?: string): void;
     evictOldest(viewPath: string): string | undefined;
     onUpdate(callback: UpdateCallback): () => void;
-    onRichUpdate(callback: RichUpdateCallback): () => void;
+    onRichUpdate(callback: RichUpdateCallback$1): () => void;
     notifyUpdate<T>(viewPath: string, key: string, update: Update<T>): void;
     notifyRichUpdate<T>(viewPath: string, key: string, update: RichUpdate<T>): void;
 }
@@ -262,5 +352,5 @@ declare function createTypedStateView<T>(viewDef: ViewDef<T, 'state'>, storage:
 declare function createTypedListView<T>(viewDef: ViewDef<T, 'list'>, storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry): TypedListView<T>;
 declare function createTypedViews<TStack extends StackDefinition>(stack: TStack, storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry): TypedViews<TStack['views']>;
 
-export { ConnectionManager, DEFAULT_CONFIG, DEFAULT_MAX_ENTRIES_PER_VIEW, FrameProcessor, HyperStack, HyperStackError, MemoryAdapter, SubscriptionRegistry, createRichUpdateStream, createTypedListView, createTypedStateView, createTypedViews, createUpdateStream, isSnapshotFrame, isValidFrame, parseFrame, parseFrameFromBlob };
-export type { ConnectionState, ConnectionStateCallback, EntityFrame, Frame, FrameMode, FrameOp, FrameProcessorConfig, HyperStackConfig, HyperStackOptions, HyperStackOptionsWithStorage, RichUpdate, RichUpdateCallback, SnapshotEntity, SnapshotFrame, StackDefinition, StorageAdapter, StorageAdapterConfig, SubscribeCallback, Subscription, TypedListView, TypedStateView, TypedViewGroup, TypedViews, UnsubscribeFn, Update, UpdateCallback, ViewDef, ViewGroup };
+export { ConnectionManager, DEFAULT_CONFIG, DEFAULT_MAX_ENTRIES_PER_VIEW, EntityStore, FrameProcessor, HyperStack, HyperStackError, MemoryAdapter, SubscriptionRegistry, createRichUpdateStream, createTypedListView, createTypedStateView, createTypedViews, createUpdateStream, isEntityFrame, isSnapshotFrame, isSubscribedFrame, isValidFrame, parseFrame, parseFrameFromBlob };
+export type { ConnectionState, ConnectionStateCallback, EntityFrame, EntityStoreConfig, Frame, FrameMode, FrameOp, FrameProcessorConfig, HyperStackConfig, HyperStackOptions, HyperStackOptionsWithStorage, RichUpdate, RichUpdateCallback$1 as RichUpdateCallback, SnapshotEntity, SnapshotFrame, SortConfig, SortOrder, StackDefinition, StorageAdapter, StorageAdapterConfig, SubscribeCallback, SubscribedFrame, Subscription, TypedListView, TypedStateView, TypedViewGroup, TypedViews, UnsubscribeFn, Update, UpdateCallback, ViewConfig, ViewDef, ViewGroup, ViewSortConfig };