@happyvertical/smrt-web 0.42.4 → 0.42.6

package/AGENTS.md

@@ -39,6 +39,7 @@ module you are editing. This file keeps what holds in every module.
 | `offline/` | durable offline writes — config, sync-apply-only replay, idempotency, the shared namespace-keyed engine, and Web Locks leader election | [agents/offline-outbox.md](agents/offline-outbox.md) |
 | `sse-client.ts` | the client half of live cache invalidation — the app-wide subscriber, the wire contract it consumes, and SSE-vs-polling behaviour | [agents/live-invalidation.md](agents/live-invalidation.md) |
 | `persistence/` + `update-state.ts` | the read-cache rehydrate capability and the framework-free `updateAvailable` primitive (bundle + contract signals) | [agents/version-persistence.md](agents/version-persistence.md) |
+| `data-query.ts` | dependency-free browser mirror and defensive response normalizer for the canonical bounded data-query envelope (#2444) | — |
 
 ## The engine-absorption boundary (ratified conditions, #1761)
 
@@ -60,6 +61,12 @@ module you are editing. This file keeps what holds in every module.
 
 - **No inter-smrt dependencies** — depends only on TanStack packages
   (dependency-DAG guardrails). Definitions and fetchers arrive as arguments.
+- **Data-query mirror** — `data-query.ts` mirrors the portable
+  `smrt-types` request/result shape structurally because this package cannot
+  depend on another SMRT package. Server adapters own authorization and full
+query/result policy; browser code calls `executeSmrtWebDataQuery()` to reject
+malformed or over-limit returned envelopes — including a response for a
+different request id — before they reach a UI surface.
 - Rows are plain DTOs with a required `id`; optimistic inserts use
   `newLocalId()` — the generated REST layer strips client ids on create
   (#1540), so the post-persist refetch reconciles server-assigned ids.

package/dist/index.d.ts

@@ -215,6 +215,11 @@ export declare interface DurableStoreKey {
  */
 export declare function durableStoreNamespace(key: DurableStoreKey): string;
 
+/** Run a browser transport and return the defensive normalized envelope. */
+export declare function executeSmrtWebDataQuery(transport: SmrtWebDataQueryTransport, request: SmrtWebDataQueryRequest, options?: {
+    signal?: AbortSignal;
+}): Promise<SmrtWebDataQueryResult>;
+
 /**
  * Retrieve the underlying engine collection backing a handle — an advanced
  * bridge for trusted framework bindings (e.g. the smrt-svelte live-query
@@ -260,6 +265,25 @@ export declare interface LiveInvalidationConfig {
     tableName: string;
 }
 
+export declare const MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS = 1000;
+
+export declare const MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES = 1000;
+
+export declare const MAX_SMRT_WEB_DATA_QUERY_FACETS = 20;
+
+export declare const MAX_SMRT_WEB_DATA_QUERY_OFFSET = 1000000;
+
+export declare const MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT = 1000;
+
+/** Mirrors core's hard output limits without adding an inter-SMRT dependency. */
+export declare const MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES = 10000000;
+
+export declare const MAX_SMRT_WEB_DATA_QUERY_ROWS = 1000;
+
+export declare const MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH = 65536;
+
+export declare const MAX_SMRT_WEB_DATA_QUERY_WARNINGS = 100;
+
 /** The settle outcome handed to {@link SmrtWebCapability.onSettled}. */
 export declare type MutationSettleOutcome = {
     ok: true;
@@ -277,6 +301,13 @@ export declare type MutationSettleOutcome = {
  */
 export declare function newLocalId(): string;
 
+/**
+ * Check the server-produced, normalized result envelope before a browser
+ * surface consumes it. This validates portable shape only; the server's core
+ * normalizer remains the authorization, projection, and query-policy boundary.
+ */
+export declare function normalizeSmrtWebDataQueryResult(value: unknown): SmrtWebDataQueryResult;
+
 /**
  * Build a durable offline-outbox capability for a collection. Add the returned
  * capability to the collection's `capabilities` array; a collection without it
@@ -735,6 +766,114 @@ export declare interface SmrtWebCollectionDefinition<TData extends object = obje
     _row?: TData;
 }
 
+export declare interface SmrtWebDataQueryFacetResult {
+    field: string;
+    values: Array<{
+        value: SmrtWebDataQueryScalar;
+        count: number;
+    }>;
+    truncated: boolean;
+}
+
+export declare type SmrtWebDataQueryFilter = {
+    kind: 'condition';
+    field: string;
+    operator: SmrtWebDataQueryFilterOperator;
+    value: SmrtWebDataQueryScalar | SmrtWebDataQueryScalar[];
+} | {
+    kind: 'all' | 'any';
+    filters: SmrtWebDataQueryFilter[];
+} | {
+    kind: 'not';
+    filter: SmrtWebDataQueryFilter;
+};
+
+export declare type SmrtWebDataQueryFilterOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'notIn' | 'like';
+
+export declare interface SmrtWebDataQueryRequest {
+    version: 1;
+    requestId: string;
+    mode: 'rows' | 'count' | 'facets';
+    projection?: string[];
+    filter?: SmrtWebDataQueryFilter;
+    sort?: Array<{
+        field: string;
+        direction: 'asc' | 'desc';
+    }>;
+    page?: {
+        kind: 'offset';
+        offset: number;
+        limit: number;
+    } | {
+        kind: 'cursor';
+        after?: string;
+        limit: number;
+    };
+    consistency?: {
+        mode: 'eventual' | 'snapshot';
+        asOf?: string;
+    };
+    facets?: Array<{
+        field: string;
+        limit: number;
+    }>;
+}
+
+export declare interface SmrtWebDataQueryResult {
+    version: 1;
+    requestId: string;
+    queryFingerprint: string;
+    identityField: string;
+    rows: Array<Record<string, unknown>>;
+    page?: {
+        kind: 'offset';
+        limit: number;
+        offset: number;
+        hasMore: boolean;
+    } | {
+        kind: 'cursor';
+        limit: number;
+        nextCursor?: string;
+        hasMore: boolean;
+    };
+    total: SmrtWebDataQueryTotal;
+    facets?: SmrtWebDataQueryFacetResult[];
+    freshness: {
+        state: 'fresh' | 'stale' | 'unknown';
+        asOf?: string;
+    };
+    warnings: string[];
+    truncated: boolean;
+}
+
+/**
+ * Browser transport for the canonical bounded data-query envelope (#2444).
+ *
+ * This is a textual structural mirror of `@happyvertical/smrt-types` rather
+ * than an import: smrt-web deliberately has no inter-SMRT dependencies. The
+ * authenticated server adapter owns allowlist, authorization, fingerprint,
+ * and byte-limit enforcement. This module gives browser callers a stable
+ * request/result shape and rejects malformed response envelopes before they
+ * reach a mounted surface.
+ */
+export declare type SmrtWebDataQueryScalar = string | number | boolean | null;
+
+export declare type SmrtWebDataQueryTotal = {
+    kind: 'exact' | 'estimated';
+    value: number;
+    asOf?: string;
+} | {
+    kind: 'unavailable';
+    reason?: string;
+};
+
+/** Browser transport seam; REST, WebMCP, and test transports share it. */
+export declare interface SmrtWebDataQueryTransport {
+    query(request: SmrtWebDataQueryRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+}
+
 /**
  * The minimal `EventSource` surface the subscriber uses — declared here so a
  * test injects a fake without a real DOM, and so this module compiles without

package/dist/index.js

@@ -14,6 +14,245 @@ async function runWrapMutation(capabilities, envelope, ctx) {
 	return { handled: false };
 }
 //#endregion
+//#region src/data-query.ts
+var FORBIDDEN_KEYS = /* @__PURE__ */ new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+var MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES = 1e7;
+var MAX_SMRT_WEB_DATA_QUERY_ROWS = 1e3;
+var MAX_SMRT_WEB_DATA_QUERY_FACETS = 20;
+var MAX_SMRT_WEB_DATA_QUERY_FACET_VALUES = 1e3;
+var MAX_SMRT_WEB_DATA_QUERY_WARNINGS = 100;
+var MAX_SMRT_WEB_DATA_QUERY_PAGE_LIMIT = 1e3;
+var MAX_SMRT_WEB_DATA_QUERY_OFFSET = 1e6;
+var MAX_SMRT_WEB_DATA_QUERY_CONTAINER_ITEMS = 1e3;
+var MAX_SMRT_WEB_DATA_QUERY_STRING_LENGTH = 65536;
+function consumeBytes(budget, text, label) {
+	const bytes = new TextEncoder().encode(text).byteLength;
+	if (bytes > budget.remaining) throw new TypeError(`${label} exceeds the maximum byte limit`);
+	budget.remaining -= bytes;
+}
+function plainObject(value, label) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${label} must be a plain object`);
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) throw new TypeError(`${label} must be a plain object`);
+	for (const key of Object.keys(value)) if (FORBIDDEN_KEYS.has(key)) throw new TypeError(`${label} contains a forbidden key`);
+	return value;
+}
+function exactKeys(value, allowed, label) {
+	const keys = new Set(allowed);
+	for (const key of Object.keys(value)) if (!keys.has(key)) throw new TypeError(`${label} contains ${key}`);
+}
+function stringValue(value, label, maxLength = 2048) {
+	if (typeof value !== "string" || value.length === 0 || value.length > maxLength) throw new TypeError(`${label} must be a bounded non-empty string`);
+	return value;
+}
+function nonNegativeInteger(value, label) {
+	if (!Number.isSafeInteger(value) || value < 0) throw new TypeError(`${label} must be a non-negative safe integer`);
+	return value;
+}
+function scalar(value, label, budget) {
+	if (typeof value === "string") {
+		if (value.length > 65536) throw new TypeError(`${label} exceeds the string limit`);
+		consumeBytes(budget, JSON.stringify(value), label);
+		return value;
+	}
+	if (value === null || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) {
+		consumeBytes(budget, JSON.stringify(value), label);
+		return value;
+	}
+	throw new TypeError(`${label} must be a JSON scalar`);
+}
+function jsonValue(value, label, budget, depth = 0) {
+	if (depth > 16) throw new TypeError(`${label} exceeds JSON depth`);
+	if (typeof value === "string") {
+		if (value.length > 65536) throw new TypeError(`${label} exceeds the string limit`);
+		consumeBytes(budget, JSON.stringify(value), label);
+		return value;
+	}
+	if (value === null || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) {
+		consumeBytes(budget, JSON.stringify(value), label);
+		return value;
+	}
+	if (Array.isArray(value)) {
+		if (value.length > 1e3) throw new TypeError(`${label} exceeds the container-item limit`);
+		consumeBytes(budget, "[", label);
+		const result2 = [];
+		for (const [index, item] of value.entries()) {
+			if (index > 0) consumeBytes(budget, ",", label);
+			result2.push(jsonValue(item, `${label}[${index}]`, budget, depth + 1));
+		}
+		consumeBytes(budget, "]", label);
+		return result2;
+	}
+	const object = plainObject(value, label);
+	if (Object.keys(object).length > 1e3) throw new TypeError(`${label} exceeds the container-item limit`);
+	const result = /* @__PURE__ */ Object.create(null);
+	consumeBytes(budget, "{", label);
+	for (const [index, key] of Object.keys(object).sort().entries()) {
+		if (key.length > 65536) throw new TypeError(`${label}.${key} exceeds the string limit`);
+		if (index > 0) consumeBytes(budget, ",", label);
+		consumeBytes(budget, JSON.stringify(key), `${label}.${key}`);
+		consumeBytes(budget, ":", label);
+		result[key] = jsonValue(object[key], `${label}.${key}`, budget, depth + 1);
+	}
+	consumeBytes(budget, "}", label);
+	return result;
+}
+function normalizeTotal(value) {
+	const total = plainObject(value, "Data query total");
+	const kind = stringValue(total.kind, "Data query total kind");
+	if (kind === "unavailable") {
+		exactKeys(total, ["kind", "reason"], "Data query unavailable total");
+		return {
+			kind,
+			...total.reason === void 0 ? {} : { reason: stringValue(total.reason, "Data query total reason") }
+		};
+	}
+	if (kind !== "exact" && kind !== "estimated") throw new TypeError("Data query total kind is invalid");
+	exactKeys(total, [
+		"kind",
+		"value",
+		"asOf"
+	], "Data query total");
+	return {
+		kind,
+		value: nonNegativeInteger(total.value, "Data query total value"),
+		...total.asOf === void 0 ? {} : { asOf: stringValue(total.asOf, "Data query total asOf", 128) }
+	};
+}
+function normalizeFacets(value, budget) {
+	if (value === void 0) return void 0;
+	if (!Array.isArray(value)) throw new TypeError("Data query facets must be an array");
+	if (value.length > 20) throw new TypeError("Data query facets exceed the maximum");
+	const fields = /* @__PURE__ */ new Set();
+	return value.map((candidate, index) => {
+		const facet = plainObject(candidate, `Data query facet ${index}`);
+		exactKeys(facet, [
+			"field",
+			"values",
+			"truncated"
+		], "Data query facet");
+		const field = stringValue(facet.field, "Data query facet field");
+		if (fields.has(field)) throw new TypeError("Data query facet fields must be unique");
+		fields.add(field);
+		if (!Array.isArray(facet.values)) throw new TypeError("Data query facet values must be an array");
+		if (facet.values.length > 1e3) throw new TypeError("Data query facet values exceed the maximum");
+		if (typeof facet.truncated !== "boolean") throw new TypeError("Data query facet truncated must be boolean");
+		return {
+			field,
+			values: facet.values.map((value2, valueIndex) => {
+				const entry = plainObject(value2, `Data query facet ${index} value ${valueIndex}`);
+				exactKeys(entry, ["value", "count"], "Data query facet value");
+				return {
+					value: scalar(entry.value, "Data query facet value", budget),
+					count: nonNegativeInteger(entry.count, "Data query facet count")
+				};
+			}),
+			truncated: facet.truncated
+		};
+	});
+}
+function normalizeSmrtWebDataQueryResult(value) {
+	const result = plainObject(value, "Data query result");
+	exactKeys(result, [
+		"version",
+		"requestId",
+		"queryFingerprint",
+		"identityField",
+		"rows",
+		"page",
+		"total",
+		"facets",
+		"freshness",
+		"warnings",
+		"truncated"
+	], "Data query result");
+	if (result.version !== 1) throw new TypeError("Unsupported data query version");
+	const identityField = stringValue(result.identityField, "Data query identity field");
+	if (!Array.isArray(result.rows)) throw new TypeError("Data query rows must be an array");
+	if (result.rows.length > 1e3) throw new TypeError("Data query rows exceed the maximum");
+	const budget = { remaining: MAX_SMRT_WEB_DATA_QUERY_RESULT_BYTES };
+	const rows = result.rows.map((row, index) => {
+		const object = plainObject(jsonValue(row, `Data query row ${index}`, budget), `Data query row ${index}`);
+		const identity = object[identityField];
+		if (typeof identity !== "string" && typeof identity !== "number" || identity === "") throw new TypeError("Data query row is missing its stable identity");
+		return object;
+	});
+	let page;
+	if (result.page !== void 0) {
+		const candidate = plainObject(result.page, "Data query page");
+		exactKeys(candidate, [
+			"kind",
+			"limit",
+			"offset",
+			"nextCursor",
+			"hasMore"
+		], "Data query page");
+		const kind = stringValue(candidate.kind, "Data query page kind");
+		if (kind !== "offset" && kind !== "cursor") throw new TypeError("Data query page kind is invalid");
+		if (typeof candidate.hasMore !== "boolean") throw new TypeError("Data query page hasMore must be boolean");
+		const limit = nonNegativeInteger(candidate.limit, "Data query page limit");
+		if (limit === 0) throw new TypeError("Data query page limit must be positive");
+		if (limit > 1e3) throw new TypeError("Data query page limit exceeds the maximum");
+		if (kind === "offset") {
+			if (candidate.nextCursor !== void 0 || candidate.offset === void 0) throw new TypeError("Offset data query page must carry only an offset");
+			const offset = nonNegativeInteger(candidate.offset, "Data query offset");
+			if (offset > 1e6) throw new TypeError("Data query offset exceeds the maximum");
+			page = {
+				kind,
+				limit,
+				offset,
+				hasMore: candidate.hasMore
+			};
+		} else {
+			if (candidate.offset !== void 0) throw new TypeError("Cursor data query page cannot carry an offset");
+			const nextCursor = candidate.nextCursor === void 0 ? void 0 : stringValue(candidate.nextCursor, "Data query next cursor");
+			if (candidate.hasMore !== Boolean(nextCursor)) throw new TypeError("Cursor data query page hasMore must match nextCursor");
+			page = {
+				kind,
+				limit,
+				hasMore: candidate.hasMore,
+				...nextCursor === void 0 ? {} : { nextCursor }
+			};
+		}
+	}
+	if (page && rows.length > page.limit) throw new TypeError("Data query rows exceed the declared page limit");
+	const freshness = plainObject(result.freshness, "Data query freshness");
+	exactKeys(freshness, ["state", "asOf"], "Data query freshness");
+	const state = stringValue(freshness.state, "Data query freshness state");
+	if (state !== "fresh" && state !== "stale" && state !== "unknown") throw new TypeError("Data query freshness state is invalid");
+	if (!Array.isArray(result.warnings) || result.warnings.length > 100 || result.warnings.some((item) => typeof item !== "string")) throw new TypeError("Data query warnings must be strings");
+	if (typeof result.truncated !== "boolean") throw new TypeError("Data query truncated must be boolean");
+	const facets = normalizeFacets(result.facets, budget);
+	const warnings = result.warnings.map((warning) => stringValue(warning, "Data query warning", 512));
+	const normalized = {
+		version: 1,
+		requestId: stringValue(result.requestId, "Data query request id"),
+		queryFingerprint: stringValue(result.queryFingerprint, "Data query fingerprint"),
+		identityField,
+		rows,
+		...page === void 0 ? {} : { page },
+		total: normalizeTotal(result.total),
+		...facets === void 0 ? {} : { facets },
+		freshness: {
+			state,
+			...freshness.asOf === void 0 ? {} : { asOf: stringValue(freshness.asOf, "Data query freshness asOf", 128) }
+		},
+		warnings: [...new Set(warnings)].sort(),
+		truncated: result.truncated
+	};
+	if (new TextEncoder().encode(JSON.stringify(normalized)).byteLength > 1e7) throw new TypeError("Data query result exceeds the maximum byte limit");
+	return normalized;
+}
+async function executeSmrtWebDataQuery(transport, request, options) {
+	const result = normalizeSmrtWebDataQueryResult(await transport.query(request, options));
+	if (result.requestId !== request.requestId) throw new TypeError("Data query result request id does not match its request");
+	return result;
+}
+//#endregion
 //#region src/durable-store.ts
 function durableStoreNamespace(key) {
 	const optional = (value) => value === void 0 ? "" : `_${encodeURIComponent(value)}`;
@@ -1923,6 +2162,6 @@ function createSmrtCollection(definition, options) {
 	return handle;
 }
 //#endregion
-export { DEFAULT_PERSIST_DEBOUNCE_MS, SmrtWebRequestError, buildListQuery, createDefinitionFetchers, createSmrtCollection, createSmrtWebClient, createSmrtWebEventSubscriber, createUpdateState, durableStoreNamespace, getEngineCollection, getOutboxHandle, liveInvalidation, newLocalId, offlineOutbox, persistCollection, registerDurableResource, registerWebMcpTools, runWrapMutation, unwrapItemResult, unwrapListResult, wipeDurableStore };
+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 };
 
 //# sourceMappingURL=index.js.map