@happyvertical/smrt-web 0.43.1 → 0.43.3

package/dist/index.d.ts

@@ -131,6 +131,14 @@ export declare function createSmrtWebClient(): SmrtWebClient;
  */
 export declare function createSmrtWebEventSubscriber(config: SmrtWebEventSubscriberConfig): SmrtWebEventSubscriber;
 
+/**
+ * Create a query controller over one SMRT collection. Query rows stay in a
+ * separate keyed cache; the collection's full list is never loaded.
+ */
+export declare function createSmrtWebQuery<TData extends object>(_collection: SmrtWebCollection<TData>, transport: SmrtWebQueryTransport, options?: {
+    staleTimeMs?: number;
+}): SmrtWebQuery<TData>;
+
 /**
  * Create the framework-free `updateAvailable` primitive. Kicks off async
  * contract detection immediately (compare running vs. persisted manifest hash);
@@ -1040,6 +1048,64 @@ export declare interface SmrtWebMutationEnvelope {
     readonly baseUpdatedAt?: string;
 }
 
+export declare interface SmrtWebQuery<TData extends object = object> {
+    readonly state: SmrtWebQueryState<TData>;
+    readonly request: SmrtWebDataQueryRequest | undefined;
+    execute(request: SmrtWebDataQueryRequest, options?: SmrtWebQueryRunOptions): Promise<SmrtWebDataQueryResult>;
+    refresh(options?: Omit<SmrtWebQueryRunOptions, 'mode' | 'force'>): Promise<SmrtWebDataQueryResult | undefined>;
+    retry(): Promise<SmrtWebDataQueryResult | undefined>;
+    subscribe(listener: (state: SmrtWebQueryState<TData>) => void): () => void;
+    subscribeLive(): SmrtWebQueryLiveSubscription | undefined;
+    invalidate(): void;
+    dispose(): void;
+}
+
+export declare interface SmrtWebQueryLiveSubscription {
+    unsubscribe(): void;
+    reconnect(): void;
+}
+
+/** How a query run is allowed to affect the visible query state. */
+export declare type SmrtWebQueryMode = 'visible' | 'background' | 'prefetch' | 'silent';
+
+export declare interface SmrtWebQueryPage {
+    kind: 'offset' | 'cursor';
+    limit: number;
+    offset?: number;
+    nextCursor?: string;
+    hasMore: boolean;
+}
+
+export declare interface SmrtWebQueryRunOptions {
+    mode?: SmrtWebQueryMode;
+    signal?: AbortSignal;
+    /** Cancel this run after the given number of milliseconds. */
+    deadlineMs?: number;
+    /** Bypass the keyed cache and execute a fresh request (used by refresh). */
+    force?: boolean;
+}
+
+export declare interface SmrtWebQueryState<TData extends object = object> {
+    readonly rows: ReadonlyArray<TData>;
+    readonly page: SmrtWebQueryPage | undefined;
+    readonly total: SmrtWebDataQueryResult['total'] | undefined;
+    readonly loading: boolean;
+    readonly refreshing: boolean;
+    readonly stale: boolean;
+    readonly error: unknown;
+    readonly lastUpdated: number | undefined;
+    readonly result: SmrtWebDataQueryResult | undefined;
+}
+
+export declare interface SmrtWebQueryTransport extends SmrtWebDataQueryTransport {
+    /** Subscribe to changes for this exact query, not the entire collection. */
+    subscribe?(request: SmrtWebDataQueryRequest, onResult: (result: unknown) => void, options?: {
+        signal?: AbortSignal;
+    }): SmrtWebQueryLiveSubscription | {
+        unsubscribe(): void;
+    };
+}
+
 /**
  * A manifest-derived edge from this collection to a sibling REST collection,
  * emitted by the `@happyvertical/smrt-virt-web` virtual module. When a mutation

package/dist/index.js

@@ -1,2 +1,2 @@
-import { A as executeSmrtWebDataQuery, C as MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES, D as MAX_SMRT_WEB_DATA_QUERY_ROWS, E as MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES, M as runWrapMutation, O as MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH, S as MAX_SMRT_WEB_DATA_QUERY_FACETS, T as MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT, _ as offlineOutbox, a as createSmrtWebClient, b as wipeDurableStore, c as unwrapItemResult, d as createUpdateState, f as createSmrtWebEventSubscriber, g as getOutboxHandle, h as persistCollection, i as createSmrtCollection, j as normalizeSmrtWebDataQueryResult, k as MAX_SMRT_WEB_DATA_QUERY_WARNINGS, l as unwrapListResult, m as DEFAULT_PERSIST_DEBOUNCE_MS, n as buildListQuery, o as getEngineCollection, p as liveInvalidation, r as createDefinitionFetchers, s as newLocalId, t as SmrtWebRequestError, u as registerWebMcpTools, v as durableStoreNamespace, w as MAX_SMRT_WEB_DATA_QUERY_OFFSET, x as MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS, y as registerDurableResource } from "./chunks/src-CDdW9uYx.js";
-export { DEFAULT_PERSIST_DEBOUNCE_MS, MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS, MAX_SMRT_WEB_DATA_QUERY_FACETS, MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES, MAX_SMRT_WEB_DATA_QUERY_OFFSET, MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT, MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES, MAX_SMRT_WEB_DATA_QUERY_ROWS, MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH, MAX_SMRT_WEB_DATA_QUERY_WARNINGS, SmrtWebRequestError, buildListQuery, createDefinitionFetchers, createSmrtCollection, createSmrtWebClient, createSmrtWebEventSubscriber, createUpdateState, durableStoreNamespace, executeSmrtWebDataQuery, getEngineCollection, getOutboxHandle, liveInvalidation, newLocalId, normalizeSmrtWebDataQueryResult, offlineOutbox, persistCollection, registerDurableResource, registerWebMcpTools, runWrapMutation, unwrapItemResult, unwrapListResult, wipeDurableStore };
+import { A as MAX_SMRT_WEB_DATA_QUERY_WARNINGS, C as MAX_SMRT_WEB_DATA_QUERY_FACETS, D as MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES, E as MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT, M as normalizeSmrtWebDataQueryResult, N as runWrapMutation, O as MAX_SMRT_WEB_DATA_QUERY_ROWS, S as MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS, T as MAX_SMRT_WEB_DATA_QUERY_OFFSET, _ as getOutboxHandle, a as createSmrtWebClient, b as registerDurableResource, c as unwrapItemResult, d as createUpdateState, f as createSmrtWebEventSubscriber, g as persistCollection, h as DEFAULT_PERSIST_DEBOUNCE_MS, i as createSmrtCollection, j as executeSmrtWebDataQuery, k as MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH, l as unwrapListResult, m as createSmrtWebQuery, n as buildListQuery, o as getEngineCollection, p as liveInvalidation, r as createDefinitionFetchers, s as newLocalId, t as SmrtWebRequestError, u as registerWebMcpTools, v as offlineOutbox, w as MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES, x as wipeDurableStore, y as durableStoreNamespace } from "./chunks/src-D9RvoJSQ.js";
+export { DEFAULT_PERSIST_DEBOUNCE_MS, MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS, MAX_SMRT_WEB_DATA_QUERY_FACETS, MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES, MAX_SMRT_WEB_DATA_QUERY_OFFSET, MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT, MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES, MAX_SMRT_WEB_DATA_QUERY_ROWS, MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH, MAX_SMRT_WEB_DATA_QUERY_WARNINGS, SmrtWebRequestError, buildListQuery, createDefinitionFetchers, createSmrtCollection, createSmrtWebClient, createSmrtWebEventSubscriber, createSmrtWebQuery, createUpdateState, durableStoreNamespace, executeSmrtWebDataQuery, getEngineCollection, getOutboxHandle, liveInvalidation, newLocalId, normalizeSmrtWebDataQueryResult, offlineOutbox, persistCollection, registerDurableResource, registerWebMcpTools, runWrapMutation, unwrapItemResult, unwrapListResult, wipeDurableStore };

package/dist/webmcp.js

@@ -1,2 +1,2 @@
-import { u as registerWebMcpTools } from "./chunks/src-CDdW9uYx.js";
+import { u as registerWebMcpTools } from "./chunks/src-D9RvoJSQ.js";
 export { registerWebMcpTools };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-web",
-  "version": "0.43.1",
+  "version": "0.43.3",
   "description": "SMRT browser client data runtime: typed collection factory wrapping the client-data engine over generated REST clients",
   "author": "HappyVertical",
   "type": "module",