@happyvertical/smrt-web 0.37.10

package/AGENTS.md

@@ -0,0 +1,56 @@
+# @happyvertical/smrt-web
+
+Browser client data runtime — the web twin of `smrt-mobile`. Materializes the
+manifest-generated web collection definitions (`@happyvertical/smrt-virt-web`)
+as cached, reactive collections over the generated SMRT REST surface.
+
+## What it does
+
+Wraps a client-data engine (currently TanStack DB) so consumers get
+stale-while-revalidate reads, concurrent-request dedup, and optimistic
+mutations without hand-wiring cache keys or fetch/state.
+
+- `createSmrtCollection(definition, options)` — typed collection factory over a
+  generated `@happyvertical/smrt-virt-web` definition. Stale-while-revalidate
+  reads (`staleTimeMs`, default 30s); N concurrent identical reads coalesce into
+  one request; optimistic inserts persist through the REST surface and roll back
+  automatically on server error.
+- `createSmrtWebClient()` — an opaque shared-cache handle. Pass one app-wide
+  instance so collections share a cache and deduplicate requests.
+- `createDefinitionFetchers(definition, basePath, fetchFn)` — CRUD fetchers
+  derived from the generated definition (same URL scheme as the generated
+  client, but HTTP error statuses reject instead of resolving).
+- `unwrapListResult` / `unwrapItemResult` — normalize generated-client payloads
+  (`T[]`, `{ data }` envelopes, `{ error }` bodies → thrown
+  `SmrtWebRequestError`).
+
+## The engine-absorption boundary (ratified conditions, #1761)
+
+1. **No engine types in the public API.** `@tanstack/*` types must never appear
+   on this package's public surface. Collections are handed back as the
+   SMRT-owned `SmrtWebCollection`, and the shared cache as the opaque
+   `SmrtWebClient`. Enforced by `scripts/check-smrt-web-engine-boundary.mjs`,
+   run at the end of `build` (fails the build on any `@tanstack/` reference in
+   an emitted `.d.ts`).
+2. **Framework-agnostic core.** This entry imports no UI framework and must not
+   import `@tanstack/svelte-db` (it ships only a `svelte` export condition,
+   unresolvable outside Svelte bundlers). Svelte live-query bindings ship in a
+   separate entry/package.
+3. **Code-split / lazy.** The engine (~76 kB gzip) must never load on public /
+   smrt-sites pages. Consumers load the runtime only on surfaces that use live
+   collections.
+
+## Conventions
+
+- **No inter-smrt dependencies** — depends only on TanStack packages
+  (dependency-DAG guardrails). Definitions and fetchers arrive as arguments.
+- 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.
+- To swap the engine, reimplement the SMRT-owned public types over a different
+  backend; the boundary guard keeps consumers insulated from the change.
+
+## Reference consumer
+
+`packages/products` consumes the runtime as its reference store across npm,
+federation, and standalone modes (see the smrt-web track, PRD #1755).

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,294 @@
+/**
+ * Build CRUD fetchers from a generated collection definition — the same URL
+ * scheme and payload handling as the generated REST client
+ * (`basePath + endpoint`), with one improvement: HTTP error statuses reject
+ * with the server's `{ error }` body instead of resolving with it.
+ */
+export declare function createDefinitionFetchers(definition: SmrtWebCollectionDefinition<object>, basePath?: string, fetchFn?: typeof fetch): SmrtCrudFetchers;
+
+/**
+ * Create a typed client collection over a generated SMRT collection definition
+ * and the matching generated REST client fetchers.
+ *
+ * Reads: stale-while-revalidate. The first subscriber triggers a fetch;
+ * re-subscribing within `staleTimeMs` serves local data with no request. N
+ * concurrent identical reads coalesce into one network request.
+ *
+ * Writes: `collection.insert({ ...data, id: newLocalId() })` applies instantly,
+ * persists through `fetchers.create()` (the temp id is stripped — the server
+ * assigns the real one), then refetches to reconcile. A failed create rejects
+ * the transaction and the optimistic row rolls back automatically.
+ *
+ * Relationship-derived invalidation: once a create/update/delete has persisted,
+ * the query caches of this collection AND the collections named by
+ * `definition.relationships` (manifest-derived edges) are invalidated, so
+ * dependent views refetch. Reaching OTHER collections requires them to share
+ * this collection's `client` (see {@link createSmrtWebClient}); with a private
+ * client only this collection refetches.
+ */
+export declare function createSmrtCollection<TData extends object>(definition: SmrtWebCollectionDefinition<TData>, options: CreateSmrtCollectionOptions): SmrtWebCollection<TData>;
+
+export declare interface CreateSmrtCollectionOptions {
+    /**
+     * Generated REST client surface for this collection, e.g.
+     * `createClient('/api/v1').products` from the virt-client module. When
+     * omitted, fetchers are derived from the definition's endpoint and `basePath`
+     * with the same URL scheme and payload shapes the generated client uses.
+     */
+    fetchers?: SmrtCrudFetchers;
+    /** API base path for definition-derived fetchers (default `/api/v1`). */
+    basePath?: string;
+    /** Fetch implementation override (tests, SSR). Defaults to global fetch. */
+    fetchFn?: typeof fetch;
+    /**
+     * Shared cache handle from {@link createSmrtWebClient}. Pass one app-wide
+     * instance so collections share a cache and deduplicate requests; a private
+     * cache is created when omitted.
+     */
+    client?: SmrtWebClient;
+    /**
+     * Cache namespace for this collection's reads. Fold a backend / tenant /
+     * preview discriminator in here when the SAME generated collection is
+     * materialized against DIFFERENT backends while sharing one {@link client} —
+     * without it those reads share a cache key and could serve one backend's rows
+     * for the other for the whole `staleTimeMs` window. Omit for the common
+     * single-backend case.
+     */
+    scope?: string;
+    /**
+     * Stale-while-revalidate window in milliseconds (default 30s): reads within
+     * the window are served from the local collection without a network request;
+     * the first read after it revalidates in the background.
+     */
+    staleTimeMs?: number;
+    /** Retry failed loads (default false: fail fast, surface errors). */
+    retry?: boolean;
+}
+
+/**
+ * Create a shared client-cache handle. Pass the returned handle as
+ * {@link CreateSmrtCollectionOptions.client} to every collection that should
+ * share a cache and deduplicate requests app-wide.
+ */
+export declare function createSmrtWebClient(): SmrtWebClient;
+
+/**
+ * Retrieve the underlying engine collection backing a handle — an advanced
+ * bridge for trusted framework bindings (e.g. the smrt-svelte live-query
+ * binding), which must feed the engine collection to the query builder. Returns
+ * `unknown` so no engine type crosses the boundary; callers cast. Throws for a
+ * handle not produced by {@link createSmrtCollection}. Not needed for normal
+ * use.
+ */
+export declare function getEngineCollection<TData extends object>(handle: SmrtWebCollection<TData>): unknown;
+
+/**
+ * Generate a client-local id for optimistic inserts. The generated REST layer
+ * strips client-supplied ids on create (mass-assignment guard #1540), so this
+ * id only identifies the optimistic row until the post-persist refetch swaps in
+ * the server-assigned row.
+ */
+export declare function newLocalId(): string;
+
+/**
+ * The per-collection CRUD surface of the generated REST client
+ * (`createClient(basePath).<collection>` from `@happyvertical/smrt-virt-client`).
+ *
+ * Return types are `unknown` on purpose: generated fetchers resolve with
+ * whatever the server sent, so this package normalizes and validates payloads
+ * centrally — see {@link unwrapListResult} / {@link unwrapItemResult}.
+ */
+export declare interface SmrtCrudFetchers {
+    list(params?: Record<string, unknown>): Promise<unknown>;
+    get?(id: string): Promise<unknown>;
+    create(data: Record<string, unknown>): Promise<unknown>;
+    update?(id: string, data: Record<string, unknown>): Promise<unknown>;
+    delete?(id: string): Promise<unknown>;
+}
+
+/**
+ * Opaque handle to the shared client cache / request-dedup layer. Create one
+ * with {@link createSmrtWebClient} and pass the SAME instance to every
+ * collection that should share a cache and deduplicate in-flight requests.
+ *
+ * The engine (currently a TanStack Query client) is intentionally hidden behind
+ * this brand so it stays swappable — do not depend on its concrete shape.
+ */
+export declare interface SmrtWebClient {
+    /** Phantom brand — this handle wraps the hidden client-cache engine. */
+    readonly __smrtWebClient: 'SmrtWebClient';
+}
+
+/**
+ * A live, cached collection of plain-DTO rows — the SMRT-owned public contract
+ * over the client-data engine. Exposes only the committed surface; the engine's
+ * own type is never named here so it stays swappable.
+ */
+export declare interface SmrtWebCollection<TData extends object> {
+    /** All rows currently in the collection (plain DTOs, insertion order). */
+    readonly toArray: ReadonlyArray<SmrtWebRow<TData>>;
+    /** Number of rows currently in the collection. */
+    readonly size: number;
+    /** True when a row with `key` is present. */
+    has(key: string): boolean;
+    /** The row with `key`, or `undefined`. */
+    get(key: string): SmrtWebRow<TData> | undefined;
+    /** Resolve once the first load has completed. */
+    preload(): Promise<void>;
+    /** Tear down subscriptions and cached state. */
+    cleanup(): Promise<void>;
+    /** Subscribe to change notifications; returns a detach handle. */
+    subscribeChanges(callback: (changes: unknown) => void): SmrtWebSubscription;
+    /**
+     * Optimistically insert a row and persist it through the create fetcher. The
+     * row is visible synchronously; the returned transaction settles on the
+     * server outcome (see {@link SmrtWebTransaction}).
+     */
+    insert(row: SmrtWebRow<TData>): SmrtWebTransaction;
+}
+
+/**
+ * One generated collection definition: everything needed to construct a client
+ * collection over the generated REST surface. The `_row` property is a phantom
+ * type carrier threaded through codegen — it never exists at runtime, it only
+ * lets factories infer the row type from a definition.
+ */
+export declare interface SmrtWebCollectionDefinition<TData extends object = object> {
+    /** REST collection name (e.g. `products`). */
+    name: string;
+    /** Source class name (e.g. `Product`). */
+    className: string;
+    /** Path under the API base path (e.g. `/products`). */
+    endpoint: string;
+    /** Primary key field name (`id` for SmrtObject). */
+    idField: string;
+    /** CRUD + custom actions exposed by the api decorator config. */
+    actions: string[];
+    /** Persisted field metadata keyed by field name. */
+    fields: Record<string, SmrtWebFieldDefinition>;
+    /**
+     * Manifest-derived relationship edges to sibling REST collections. Drives
+     * relationship-derived cache invalidation: a settled mutation on this
+     * collection invalidates the caches of the collections these edges name.
+     * Optional so hand-built definitions (older codegen, tests) still satisfy the
+     * type; a missing value means "no derived edges".
+     */
+    relationships?: SmrtWebRelationship[];
+    /** Phantom row-type carrier — never present at runtime. */
+    _row?: TData;
+}
+
+/**
+ * @happyvertical/smrt-web — browser client data runtime (#1761).
+ *
+ * A typed collection factory that materializes the manifest-generated web
+ * collection definitions (`@happyvertical/smrt-virt-web`) as cached, reactive
+ * collections over the generated SMRT REST surface.
+ *
+ * This package is the **engine-absorption boundary**: the client-data engine
+ * (currently TanStack DB) is an implementation detail held entirely inside
+ * this module. Its types never appear on the public API — collections are
+ * handed back as the SMRT-owned {@link SmrtWebCollection}, and the shared cache
+ * as the opaque {@link SmrtWebClient} — so the engine stays swappable without a
+ * consumer-visible break. Consumers never import `@tanstack/*` directly.
+ *
+ * Framework-agnostic by construction: this entry imports no UI framework.
+ * Svelte live-query bindings ship separately (see PRD #1755) so this core never
+ * pulls the Svelte-only `@tanstack/svelte-db` export condition.
+ *
+ * Scope of this slice:
+ * - stale-while-revalidate reads (a `staleTimeMs` window, background revalidation)
+ * - concurrent-read dedup (one network request per in-flight collection load)
+ * - optimistic create that persists through the generated REST surface and
+ *   rolls back automatically when the server errors
+ * - relationship-derived invalidation (#1761): a settled mutation invalidates
+ *   the caches of the collections related to the mutated one, with the edges
+ *   derived from the manifest (`definition.relationships`) — no hand-wired
+ *   cache keys. Cross-collection reach requires a shared client from
+ *   {@link createSmrtWebClient}; with a private client only the mutated
+ *   collection refetches.
+ *
+ * Deliberately NOT here yet (see PRD #1755): SvelteKit hydration seeding,
+ * offline outbox, SSE invalidation, persistence, version awareness.
+ */
+/**
+ * Field metadata emitted per column by the `@happyvertical/smrt-virt-web`
+ * virtual module (generated from the package manifest).
+ */
+export declare interface SmrtWebFieldDefinition {
+    type: string;
+    required?: boolean;
+    default?: unknown;
+}
+
+/**
+ * A manifest-derived edge from this collection to a sibling REST collection,
+ * emitted by the `@happyvertical/smrt-virt-web` virtual module. When a mutation
+ * on this collection settles, the caches of the collections named by these
+ * edges are invalidated (relationship-derived invalidation, #1761), so a
+ * dependent view refetches without any hand-wired cache key.
+ *
+ * SMRT-owned data — no client-engine (`@tanstack/*`) type appears here, so it
+ * stays inside the engine-absorption boundary.
+ */
+export declare interface SmrtWebRelationship {
+    /** The declaring field carrying the relationship (e.g. `groupId`, `items`). */
+    field: string;
+    /** The relationship kind, mirroring the manifest field type. */
+    kind: SmrtWebRelationshipKind;
+    /** REST collection name the edge resolves to (e.g. `ad_groups`). */
+    relatedCollection: string;
+}
+
+/** The relationship kinds a generated web collection edge can describe. */
+export declare type SmrtWebRelationshipKind = 'foreignKey' | 'crossPackageRef' | 'oneToMany' | 'manyToMany';
+
+/**
+ * Raised when a generated-client call resolved with an error payload
+ * (`{ error: string }` from the generated REST routes) or an unexpected shape.
+ * Thrown inside a mutation handler, this triggers the automatic rollback of
+ * optimistic state.
+ */
+export declare class SmrtWebRequestError extends Error {
+    readonly payload: unknown;
+    constructor(message: string, payload?: unknown);
+}
+
+/** A row as stored in the client collection: the DTO plus a required key. */
+export declare type SmrtWebRow<TData extends object> = TData & {
+    id: string;
+};
+
+/** A change-subscription handle. Call {@link unsubscribe} to detach. */
+export declare interface SmrtWebSubscription {
+    unsubscribe(): void;
+}
+
+/**
+ * A pending optimistic mutation. Await {@link isPersisted} to observe the
+ * server outcome: it resolves once the write has been persisted through the
+ * REST surface, and rejects (rolling the optimistic state back) on error.
+ */
+export declare interface SmrtWebTransaction {
+    readonly isPersisted: {
+        readonly promise: Promise<unknown>;
+    };
+}
+
+/**
+ * Normalize a generated-client item result (create/update) to a row.
+ * `{ error }` payloads become failures — inside mutation handlers this is what
+ * makes optimistic state roll back.
+ */
+export declare function unwrapItemResult(result: unknown, context: string): Record<string, unknown>;
+
+/**
+ * Normalize a generated-client list result to an array of rows.
+ *
+ * The generated REST routes return a bare JSON array; `{ error }` payloads are
+ * surfaced as failures. The `{ data: [...] }` envelope is tolerated for
+ * ApiResponse-shaped clients (e.g. a mock client).
+ */
+export declare function unwrapListResult(result: unknown, collectionName: string): Array<Record<string, unknown>>;
+
+export { }

package/dist/index.js

@@ -0,0 +1,187 @@
+import { createCollection } from "@tanstack/db";
+import { QueryClient } from "@tanstack/query-core";
+import { queryCollectionOptions } from "@tanstack/query-db-collection";
+//#region src/index.ts
+var SmrtWebRequestError = class extends Error {
+	payload;
+	constructor(message, payload) {
+		super(message);
+		this.name = "SmrtWebRequestError";
+		this.payload = payload;
+	}
+};
+function unwrapListResult(result, collectionName) {
+	if (Array.isArray(result)) return result;
+	if (result && typeof result === "object") {
+		const record = result;
+		if (typeof record.error === "string") throw new SmrtWebRequestError(`[smrt-web] list(${collectionName}) failed: ${record.error}`, result);
+		if (Array.isArray(record.data)) return record.data;
+	}
+	throw new SmrtWebRequestError(`[smrt-web] list(${collectionName}) returned an unexpected payload shape`, result);
+}
+function unwrapItemResult(result, context) {
+	if (result && typeof result === "object" && !Array.isArray(result)) {
+		const record = result;
+		if (typeof record.error === "string") throw new SmrtWebRequestError(`[smrt-web] ${context} failed: ${record.error}`, result);
+		if (record.data && typeof record.data === "object" && !Array.isArray(record.data)) return record.data;
+		return record;
+	}
+	throw new SmrtWebRequestError(`[smrt-web] ${context} returned an unexpected payload shape`, result);
+}
+function createDefinitionFetchers(definition, basePath = "/api/v1", fetchFn = (...args) => globalThis.fetch(...args)) {
+	const collectionUrl = `${basePath}${definition.endpoint}`;
+	const headers = { "Content-Type": "application/json" };
+	const parse = async (response) => {
+		const payload = await response.json().catch(() => null);
+		if (!response.ok) {
+			const message = payload && typeof payload === "object" && typeof payload.error === "string" ? String(payload.error) : `HTTP ${response.status}`;
+			throw new SmrtWebRequestError(`[smrt-web] ${definition.name} request failed: ${message}`, payload);
+		}
+		return payload;
+	};
+	return {
+		list: async () => parse(await fetchFn(collectionUrl, { headers })),
+		get: async (id) => parse(await fetchFn(`${collectionUrl}/${id}`, { headers })),
+		create: async (data) => parse(await fetchFn(collectionUrl, {
+			method: "POST",
+			headers,
+			body: JSON.stringify(data)
+		})),
+		update: async (id, data) => parse(await fetchFn(`${collectionUrl}/${id}`, {
+			method: "PUT",
+			headers,
+			body: JSON.stringify(data)
+		})),
+		delete: async (id) => {
+			const response = await fetchFn(`${collectionUrl}/${id}`, {
+				method: "DELETE",
+				headers
+			});
+			if (!response.ok) throw new SmrtWebRequestError(`[smrt-web] delete(${definition.name}) failed: HTTP ${response.status}`);
+			return true;
+		}
+	};
+}
+function newLocalId() {
+	const cryptoRef = globalThis.crypto;
+	if (cryptoRef?.randomUUID) return cryptoRef.randomUUID();
+	return `local-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
+function createSmrtWebClient() {
+	return {
+		__smrtWebClient: "SmrtWebClient",
+		queryClient: new QueryClient()
+	};
+}
+function resolveQueryClient(client) {
+	if (!client) return new QueryClient();
+	const engine = client;
+	if (engine.__smrtWebClient !== "SmrtWebClient" || !engine.queryClient) throw new SmrtWebRequestError("[smrt-web] options.client must be a handle from createSmrtWebClient()");
+	return engine.queryClient;
+}
+function toPlainRow(row) {
+	const plain = {};
+	for (const [key, value] of Object.entries(row)) if (key.charCodeAt(0) !== 36) plain[key] = value;
+	return plain;
+}
+function projectChanges(changes) {
+	if (!Array.isArray(changes)) return changes;
+	return changes.map((change) => {
+		if (!change || typeof change !== "object") return change;
+		const record = change;
+		const projected = { ...record };
+		if (record.value && typeof record.value === "object") projected.value = toPlainRow(record.value);
+		if (record.previousValue && typeof record.previousValue === "object") projected.previousValue = toPlainRow(record.previousValue);
+		return projected;
+	});
+}
+var engineCollections = /* @__PURE__ */ new WeakMap();
+function getEngineCollection(handle) {
+	const engine = engineCollections.get(handle);
+	if (engine === void 0) throw new SmrtWebRequestError("[smrt-web] getEngineCollection: not a smrt-web collection handle");
+	return engine;
+}
+function createSmrtCollection(definition, options) {
+	const { staleTimeMs = 3e4, retry = false, scope } = options;
+	const fetchers = options.fetchers ?? createDefinitionFetchers(definition, options.basePath, options.fetchFn);
+	const queryClient = resolveQueryClient(options.client);
+	const idField = definition.idField || "id";
+	const cacheId = scope ? `smrt:${scope}:${definition.name}` : `smrt:${definition.name}`;
+	const queryKey = scope ? [
+		"smrt",
+		scope,
+		definition.name
+	] : ["smrt", definition.name];
+	const invalidationTargets = /* @__PURE__ */ new Set([definition.name]);
+	for (const relationship of definition.relationships ?? []) invalidationTargets.add(relationship.relatedCollection);
+	const invalidateRelated = () => {
+		queryClient.invalidateQueries({ predicate: (query) => {
+			const key = query.queryKey;
+			if (!Array.isArray(key) || key.length === 0) return false;
+			const collectionSegment = key[key.length - 1];
+			return typeof collectionSegment === "string" && invalidationTargets.has(collectionSegment);
+		} });
+	};
+	const collection = createCollection(queryCollectionOptions({
+		id: cacheId,
+		queryKey,
+		queryClient,
+		staleTime: staleTimeMs,
+		retry,
+		queryFn: async () => unwrapListResult(await fetchers.list(), definition.name),
+		getKey: (row) => String(row[idField]),
+		onInsert: async ({ transaction }) => {
+			for (const mutation of transaction.mutations) {
+				const { [idField]: _localId, ...data } = mutation.modified;
+				unwrapItemResult(await fetchers.create(data), `create(${definition.name})`);
+			}
+			invalidateRelated();
+		},
+		onUpdate: fetchers.update ? async ({ transaction }) => {
+			for (const mutation of transaction.mutations) {
+				const key = String(mutation.key);
+				const changes = mutation.changes;
+				unwrapItemResult(await fetchers.update(key, changes), `update(${definition.name})`);
+			}
+			invalidateRelated();
+		} : void 0,
+		onDelete: fetchers.delete ? async ({ transaction }) => {
+			for (const mutation of transaction.mutations) await fetchers.delete(String(mutation.key));
+			invalidateRelated();
+		} : void 0
+	}));
+	const handle = {
+		get toArray() {
+			return collection.toArray.map((row) => toPlainRow(row));
+		},
+		get size() {
+			return collection.size;
+		},
+		has(key) {
+			return collection.has(key);
+		},
+		get(key) {
+			const row = collection.get(key);
+			return row === void 0 ? void 0 : toPlainRow(row);
+		},
+		preload() {
+			return collection.preload();
+		},
+		cleanup() {
+			return collection.cleanup();
+		},
+		subscribeChanges(callback) {
+			const subscription = collection.subscribeChanges((changes) => callback(projectChanges(changes)));
+			return { unsubscribe: () => subscription.unsubscribe() };
+		},
+		insert(row) {
+			return collection.insert(row);
+		}
+	};
+	engineCollections.set(handle, collection);
+	return handle;
+}
+//#endregion
+export { SmrtWebRequestError, createDefinitionFetchers, createSmrtCollection, createSmrtWebClient, getEngineCollection, newLocalId, unwrapItemResult, unwrapListResult };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @happyvertical/smrt-web — browser client data runtime (#1761).\n *\n * A typed collection factory that materializes the manifest-generated web\n * collection definitions (`@happyvertical/smrt-virt-web`) as cached, reactive\n * collections over the generated SMRT REST surface.\n *\n * This package is the **engine-absorption boundary**: the client-data engine\n * (currently TanStack DB) is an implementation detail held entirely inside\n * this module. Its types never appear on the public API — collections are\n * handed back as the SMRT-owned {@link SmrtWebCollection}, and the shared cache\n * as the opaque {@link SmrtWebClient} — so the engine stays swappable without a\n * consumer-visible break. Consumers never import `@tanstack/*` directly.\n *\n * Framework-agnostic by construction: this entry imports no UI framework.\n * Svelte live-query bindings ship separately (see PRD #1755) so this core never\n * pulls the Svelte-only `@tanstack/svelte-db` export condition.\n *\n * Scope of this slice:\n * - stale-while-revalidate reads (a `staleTimeMs` window, background revalidation)\n * - concurrent-read dedup (one network request per in-flight collection load)\n * - optimistic create that persists through the generated REST surface and\n *   rolls back automatically when the server errors\n * - relationship-derived invalidation (#1761): a settled mutation invalidates\n *   the caches of the collections related to the mutated one, with the edges\n *   derived from the manifest (`definition.relationships`) — no hand-wired\n *   cache keys. Cross-collection reach requires a shared client from\n *   {@link createSmrtWebClient}; with a private client only the mutated\n *   collection refetches.\n *\n * Deliberately NOT here yet (see PRD #1755): SvelteKit hydration seeding,\n * offline outbox, SSE invalidation, persistence, version awareness.\n */\n\nimport { createCollection } from '@tanstack/db';\nimport { QueryClient } from '@tanstack/query-core';\nimport { queryCollectionOptions } from '@tanstack/query-db-collection';\n\n// ---------------------------------------------------------------------------\n// Generated definition contract (mirrors @happyvertical/smrt-virt-web)\n// ---------------------------------------------------------------------------\n\n/**\n * Field metadata emitted per column by the `@happyvertical/smrt-virt-web`\n * virtual module (generated from the package manifest).\n */\nexport interface SmrtWebFieldDefinition {\n  type: string;\n  required?: boolean;\n  default?: unknown;\n}\n\n/** The relationship kinds a generated web collection edge can describe. */\nexport type SmrtWebRelationshipKind =\n  | 'foreignKey'\n  | 'crossPackageRef'\n  | 'oneToMany'\n  | 'manyToMany';\n\n/**\n * A manifest-derived edge from this collection to a sibling REST collection,\n * emitted by the `@happyvertical/smrt-virt-web` virtual module. When a mutation\n * on this collection settles, the caches of the collections named by these\n * edges are invalidated (relationship-derived invalidation, #1761), so a\n * dependent view refetches without any hand-wired cache key.\n *\n * SMRT-owned data — no client-engine (`@tanstack/*`) type appears here, so it\n * stays inside the engine-absorption boundary.\n */\nexport interface SmrtWebRelationship {\n  /** The declaring field carrying the relationship (e.g. `groupId`, `items`). */\n  field: string;\n  /** The relationship kind, mirroring the manifest field type. */\n  kind: SmrtWebRelationshipKind;\n  /** REST collection name the edge resolves to (e.g. `ad_groups`). */\n  relatedCollection: string;\n}\n\n/**\n * One generated collection definition: everything needed to construct a client\n * collection over the generated REST surface. The `_row` property is a phantom\n * type carrier threaded through codegen — it never exists at runtime, it only\n * lets factories infer the row type from a definition.\n */\nexport interface SmrtWebCollectionDefinition<TData extends object = object> {\n  /** REST collection name (e.g. `products`). */\n  name: string;\n  /** Source class name (e.g. `Product`). */\n  className: string;\n  /** Path under the API base path (e.g. `/products`). */\n  endpoint: string;\n  /** Primary key field name (`id` for SmrtObject). */\n  idField: string;\n  /** CRUD + custom actions exposed by the api decorator config. */\n  actions: string[];\n  /** Persisted field metadata keyed by field name. */\n  fields: Record<string, SmrtWebFieldDefinition>;\n  /**\n   * Manifest-derived relationship edges to sibling REST collections. Drives\n   * relationship-derived cache invalidation: a settled mutation on this\n   * collection invalidates the caches of the collections these edges name.\n   * Optional so hand-built definitions (older codegen, tests) still satisfy the\n   * type; a missing value means \"no derived edges\".\n   */\n  relationships?: SmrtWebRelationship[];\n  /** Phantom row-type carrier — never present at runtime. */\n  _row?: TData;\n}\n\n// ---------------------------------------------------------------------------\n// Fetcher contract + payload normalization\n// ---------------------------------------------------------------------------\n\n/**\n * The per-collection CRUD surface of the generated REST client\n * (`createClient(basePath).<collection>` from `@happyvertical/smrt-virt-client`).\n *\n * Return types are `unknown` on purpose: generated fetchers resolve with\n * whatever the server sent, so this package normalizes and validates payloads\n * centrally — see {@link unwrapListResult} / {@link unwrapItemResult}.\n */\nexport interface SmrtCrudFetchers {\n  list(params?: Record<string, unknown>): Promise<unknown>;\n  get?(id: string): Promise<unknown>;\n  create(data: Record<string, unknown>): Promise<unknown>;\n  update?(id: string, data: Record<string, unknown>): Promise<unknown>;\n  delete?(id: string): Promise<unknown>;\n}\n\n/**\n * Raised when a generated-client call resolved with an error payload\n * (`{ error: string }` from the generated REST routes) or an unexpected shape.\n * Thrown inside a mutation handler, this triggers the automatic rollback of\n * optimistic state.\n */\nexport class SmrtWebRequestError extends Error {\n  readonly payload: unknown;\n\n  constructor(message: string, payload?: unknown) {\n    super(message);\n    this.name = 'SmrtWebRequestError';\n    this.payload = payload;\n  }\n}\n\n/** A row as stored in the client collection: the DTO plus a required key. */\nexport type SmrtWebRow<TData extends object> = TData & { id: string };\n\n/**\n * Normalize a generated-client list result to an array of rows.\n *\n * The generated REST routes return a bare JSON array; `{ error }` payloads are\n * surfaced as failures. The `{ data: [...] }` envelope is tolerated for\n * ApiResponse-shaped clients (e.g. a mock client).\n */\nexport function unwrapListResult(\n  result: unknown,\n  collectionName: string,\n): Array<Record<string, unknown>> {\n  if (Array.isArray(result)) {\n    return result as Array<Record<string, unknown>>;\n  }\n  if (result && typeof result === 'object') {\n    const record = result as Record<string, unknown>;\n    if (typeof record.error === 'string') {\n      throw new SmrtWebRequestError(\n        `[smrt-web] list(${collectionName}) failed: ${record.error}`,\n        result,\n      );\n    }\n    if (Array.isArray(record.data)) {\n      return record.data as Array<Record<string, unknown>>;\n    }\n  }\n  throw new SmrtWebRequestError(\n    `[smrt-web] list(${collectionName}) returned an unexpected payload shape`,\n    result,\n  );\n}\n\n/**\n * Normalize a generated-client item result (create/update) to a row.\n * `{ error }` payloads become failures — inside mutation handlers this is what\n * makes optimistic state roll back.\n */\nexport function unwrapItemResult(\n  result: unknown,\n  context: string,\n): Record<string, unknown> {\n  if (result && typeof result === 'object' && !Array.isArray(result)) {\n    const record = result as Record<string, unknown>;\n    if (typeof record.error === 'string') {\n      throw new SmrtWebRequestError(\n        `[smrt-web] ${context} failed: ${record.error}`,\n        result,\n      );\n    }\n    if (\n      record.data &&\n      typeof record.data === 'object' &&\n      !Array.isArray(record.data)\n    ) {\n      return record.data as Record<string, unknown>;\n    }\n    return record;\n  }\n  throw new SmrtWebRequestError(\n    `[smrt-web] ${context} returned an unexpected payload shape`,\n    result,\n  );\n}\n\n/**\n * Build CRUD fetchers from a generated collection definition — the same URL\n * scheme and payload handling as the generated REST client\n * (`basePath + endpoint`), with one improvement: HTTP error statuses reject\n * with the server's `{ error }` body instead of resolving with it.\n */\nexport function createDefinitionFetchers(\n  definition: SmrtWebCollectionDefinition<object>,\n  basePath = '/api/v1',\n  fetchFn: typeof fetch = (...args) => globalThis.fetch(...args),\n): SmrtCrudFetchers {\n  const collectionUrl = `${basePath}${definition.endpoint}`;\n  const headers = { 'Content-Type': 'application/json' };\n\n  const parse = async (response: Response): Promise<unknown> => {\n    const payload: unknown = await response.json().catch(() => null);\n    if (!response.ok) {\n      const message =\n        payload &&\n        typeof payload === 'object' &&\n        typeof (payload as Record<string, unknown>).error === 'string'\n          ? String((payload as Record<string, unknown>).error)\n          : `HTTP ${response.status}`;\n      throw new SmrtWebRequestError(\n        `[smrt-web] ${definition.name} request failed: ${message}`,\n        payload,\n      );\n    }\n    return payload;\n  };\n\n  return {\n    list: async () => parse(await fetchFn(collectionUrl, { headers })),\n    get: async (id) =>\n      parse(await fetchFn(`${collectionUrl}/${id}`, { headers })),\n    create: async (data) =>\n      parse(\n        await fetchFn(collectionUrl, {\n          method: 'POST',\n          headers,\n          body: JSON.stringify(data),\n        }),\n      ),\n    update: async (id, data) =>\n      parse(\n        await fetchFn(`${collectionUrl}/${id}`, {\n          method: 'PUT',\n          headers,\n          body: JSON.stringify(data),\n        }),\n      ),\n    delete: async (id) => {\n      const response = await fetchFn(`${collectionUrl}/${id}`, {\n        method: 'DELETE',\n        headers,\n      });\n      if (!response.ok) {\n        throw new SmrtWebRequestError(\n          `[smrt-web] delete(${definition.name}) failed: HTTP ${response.status}`,\n        );\n      }\n      return true;\n    },\n  };\n}\n\n/**\n * Generate a client-local id for optimistic inserts. The generated REST layer\n * strips client-supplied ids on create (mass-assignment guard #1540), so this\n * id only identifies the optimistic row until the post-persist refetch swaps in\n * the server-assigned row.\n */\nexport function newLocalId(): string {\n  const cryptoRef = globalThis.crypto as Crypto | undefined;\n  if (cryptoRef?.randomUUID) {\n    return cryptoRef.randomUUID();\n  }\n  return `local-${Date.now()}-${Math.random().toString(36).slice(2)}`;\n}\n\n// ---------------------------------------------------------------------------\n// Engine-absorbing public surface (no @tanstack/* types leak past here)\n// ---------------------------------------------------------------------------\n\n/**\n * Opaque handle to the shared client cache / request-dedup layer. Create one\n * with {@link createSmrtWebClient} and pass the SAME instance to every\n * collection that should share a cache and deduplicate in-flight requests.\n *\n * The engine (currently a TanStack Query client) is intentionally hidden behind\n * this brand so it stays swappable — do not depend on its concrete shape.\n */\nexport interface SmrtWebClient {\n  /** Phantom brand — this handle wraps the hidden client-cache engine. */\n  readonly __smrtWebClient: 'SmrtWebClient';\n}\n\n/**\n * Engine-side shape of a {@link SmrtWebClient}. Never exported, so the engine\n * type never reaches the public surface. Extends the public brand so the value\n * created here carries the brand at runtime (enabling the validation below).\n */\ninterface SmrtWebClientEngine extends SmrtWebClient {\n  readonly queryClient: QueryClient;\n}\n\n/**\n * Create a shared client-cache handle. Pass the returned handle as\n * {@link CreateSmrtCollectionOptions.client} to every collection that should\n * share a cache and deduplicate requests app-wide.\n */\nexport function createSmrtWebClient(): SmrtWebClient {\n  const engine: SmrtWebClientEngine = {\n    __smrtWebClient: 'SmrtWebClient',\n    queryClient: new QueryClient(),\n  };\n  return engine;\n}\n\nfunction resolveQueryClient(client?: SmrtWebClient): QueryClient {\n  if (!client) return new QueryClient();\n  const engine = client as Partial<SmrtWebClientEngine>;\n  if (engine.__smrtWebClient !== 'SmrtWebClient' || !engine.queryClient) {\n    throw new SmrtWebRequestError(\n      '[smrt-web] options.client must be a handle from createSmrtWebClient()',\n    );\n  }\n  return engine.queryClient;\n}\n\n/**\n * Project an engine row to a plain public DTO. The client-data engine decorates\n * stored rows with enumerable virtual props (`$synced`/`$origin`/`$key`/\n * `$collectionId`) that would otherwise cross the SMRT boundary through spread\n * or JSON serialization. The `$` prefix is reserved for the engine; SMRT\n * columns never begin with it.\n */\nfunction toPlainRow<TData extends object>(row: unknown): SmrtWebRow<TData> {\n  const plain: Record<string, unknown> = {};\n  for (const [key, value] of Object.entries(row as Record<string, unknown>)) {\n    if (key.charCodeAt(0) !== 36 /* '$' */) plain[key] = value;\n  }\n  return plain as SmrtWebRow<TData>;\n}\n\n/** Project the row values carried by a change notification to plain DTOs. */\nfunction projectChanges(changes: unknown): unknown {\n  if (!Array.isArray(changes)) return changes;\n  return changes.map((change) => {\n    if (!change || typeof change !== 'object') return change;\n    const record = change as Record<string, unknown>;\n    const projected: Record<string, unknown> = { ...record };\n    if (record.value && typeof record.value === 'object') {\n      projected.value = toPlainRow(record.value);\n    }\n    if (record.previousValue && typeof record.previousValue === 'object') {\n      projected.previousValue = toPlainRow(record.previousValue);\n    }\n    return projected;\n  });\n}\n\n/**\n * A pending optimistic mutation. Await {@link isPersisted} to observe the\n * server outcome: it resolves once the write has been persisted through the\n * REST surface, and rejects (rolling the optimistic state back) on error.\n */\nexport interface SmrtWebTransaction {\n  readonly isPersisted: { readonly promise: Promise<unknown> };\n}\n\n/** A change-subscription handle. Call {@link unsubscribe} to detach. */\nexport interface SmrtWebSubscription {\n  unsubscribe(): void;\n}\n\n/**\n * A live, cached collection of plain-DTO rows — the SMRT-owned public contract\n * over the client-data engine. Exposes only the committed surface; the engine's\n * own type is never named here so it stays swappable.\n */\nexport interface SmrtWebCollection<TData extends object> {\n  /** All rows currently in the collection (plain DTOs, insertion order). */\n  readonly toArray: ReadonlyArray<SmrtWebRow<TData>>;\n  /** Number of rows currently in the collection. */\n  readonly size: number;\n  /** True when a row with `key` is present. */\n  has(key: string): boolean;\n  /** The row with `key`, or `undefined`. */\n  get(key: string): SmrtWebRow<TData> | undefined;\n  /** Resolve once the first load has completed. */\n  preload(): Promise<void>;\n  /** Tear down subscriptions and cached state. */\n  cleanup(): Promise<void>;\n  /** Subscribe to change notifications; returns a detach handle. */\n  subscribeChanges(callback: (changes: unknown) => void): SmrtWebSubscription;\n  /**\n   * Optimistically insert a row and persist it through the create fetcher. The\n   * row is visible synchronously; the returned transaction settles on the\n   * server outcome (see {@link SmrtWebTransaction}).\n   */\n  insert(row: SmrtWebRow<TData>): SmrtWebTransaction;\n}\n\nexport interface CreateSmrtCollectionOptions {\n  /**\n   * Generated REST client surface for this collection, e.g.\n   * `createClient('/api/v1').products` from the virt-client module. When\n   * omitted, fetchers are derived from the definition's endpoint and `basePath`\n   * with the same URL scheme and payload shapes the generated client uses.\n   */\n  fetchers?: SmrtCrudFetchers;\n  /** API base path for definition-derived fetchers (default `/api/v1`). */\n  basePath?: string;\n  /** Fetch implementation override (tests, SSR). Defaults to global fetch. */\n  fetchFn?: typeof fetch;\n  /**\n   * Shared cache handle from {@link createSmrtWebClient}. Pass one app-wide\n   * instance so collections share a cache and deduplicate requests; a private\n   * cache is created when omitted.\n   */\n  client?: SmrtWebClient;\n  /**\n   * Cache namespace for this collection's reads. Fold a backend / tenant /\n   * preview discriminator in here when the SAME generated collection is\n   * materialized against DIFFERENT backends while sharing one {@link client} —\n   * without it those reads share a cache key and could serve one backend's rows\n   * for the other for the whole `staleTimeMs` window. Omit for the common\n   * single-backend case.\n   */\n  scope?: string;\n  /**\n   * Stale-while-revalidate window in milliseconds (default 30s): reads within\n   * the window are served from the local collection without a network request;\n   * the first read after it revalidates in the background.\n   */\n  staleTimeMs?: number;\n  /** Retry failed loads (default false: fail fast, surface errors). */\n  retry?: boolean;\n}\n\n/**\n * Registry mapping a public collection handle to its underlying engine\n * collection. Keyed weakly so a handle and its engine collection are collected\n * together. Read only through {@link getEngineCollection}.\n */\nconst engineCollections = new WeakMap<object, unknown>();\n\n/**\n * Retrieve the underlying engine collection backing a handle — an advanced\n * bridge for trusted framework bindings (e.g. the smrt-svelte live-query\n * binding), which must feed the engine collection to the query builder. Returns\n * `unknown` so no engine type crosses the boundary; callers cast. Throws for a\n * handle not produced by {@link createSmrtCollection}. Not needed for normal\n * use.\n */\nexport function getEngineCollection<TData extends object>(\n  handle: SmrtWebCollection<TData>,\n): unknown {\n  const engine = engineCollections.get(handle);\n  if (engine === undefined) {\n    throw new SmrtWebRequestError(\n      '[smrt-web] getEngineCollection: not a smrt-web collection handle',\n    );\n  }\n  return engine;\n}\n\n/**\n * Create a typed client collection over a generated SMRT collection definition\n * and the matching generated REST client fetchers.\n *\n * Reads: stale-while-revalidate. The first subscriber triggers a fetch;\n * re-subscribing within `staleTimeMs` serves local data with no request. N\n * concurrent identical reads coalesce into one network request.\n *\n * Writes: `collection.insert({ ...data, id: newLocalId() })` applies instantly,\n * persists through `fetchers.create()` (the temp id is stripped — the server\n * assigns the real one), then refetches to reconcile. A failed create rejects\n * the transaction and the optimistic row rolls back automatically.\n *\n * Relationship-derived invalidation: once a create/update/delete has persisted,\n * the query caches of this collection AND the collections named by\n * `definition.relationships` (manifest-derived edges) are invalidated, so\n * dependent views refetch. Reaching OTHER collections requires them to share\n * this collection's `client` (see {@link createSmrtWebClient}); with a private\n * client only this collection refetches.\n */\nexport function createSmrtCollection<TData extends object>(\n  definition: SmrtWebCollectionDefinition<TData>,\n  options: CreateSmrtCollectionOptions,\n): SmrtWebCollection<TData> {\n  type Row = SmrtWebRow<TData>;\n\n  const { staleTimeMs = 30_000, retry = false, scope } = options;\n  const fetchers =\n    options.fetchers ??\n    createDefinitionFetchers(definition, options.basePath, options.fetchFn);\n  const queryClient = resolveQueryClient(options.client);\n  const idField = definition.idField || 'id';\n\n  // Scope discriminates the cache key so a shared client can materialize the\n  // same collection against different backends without cross-serving reads.\n  const cacheId = scope\n    ? `smrt:${scope}:${definition.name}`\n    : `smrt:${definition.name}`;\n  const queryKey = scope\n    ? ['smrt', scope, definition.name]\n    : ['smrt', definition.name];\n\n  // Relationship-derived invalidation target set (#1761): the collections\n  // whose caches a settled mutation on THIS collection must invalidate. Always\n  // includes this collection itself (so its own read revalidates) plus every\n  // manifest-derived related collection. Built once; a settled write matches\n  // any cached query whose collection-name segment (the LAST queryKey element,\n  // mirroring the `['smrt', (scope,) name]` scheme above) is in this set.\n  //\n  // Over-invalidation is safe — a stale query merely refetches. Under-\n  // invalidation is the bug (a dependent view showing stale rows), so the\n  // predicate matches by collection name across ALL scopes rather than an exact\n  // key: a mutation in one scope refreshes the related collection in every\n  // scope sharing the client.\n  const invalidationTargets = new Set<string>([definition.name]);\n  for (const relationship of definition.relationships ?? []) {\n    invalidationTargets.add(relationship.relatedCollection);\n  }\n\n  /**\n   * Invalidate the query caches of this collection and its manifest-derived\n   * related collections. Cross-collection reach requires those collections to\n   * share this collection's `client` (from {@link createSmrtWebClient}); with a\n   * private client only THIS collection's query lives here, so only it\n   * refetches. Fire-and-forget: invalidation schedules a background refetch and\n   * must not delay the mutation's own settle.\n   */\n  const invalidateRelated = (): void => {\n    void queryClient.invalidateQueries({\n      predicate: (query) => {\n        const key = query.queryKey;\n        if (!Array.isArray(key) || key.length === 0) return false;\n        const collectionSegment = key[key.length - 1];\n        return (\n          typeof collectionSegment === 'string' &&\n          invalidationTargets.has(collectionSegment)\n        );\n      },\n    });\n  };\n\n  const collection = createCollection(\n    queryCollectionOptions<Row>({\n      id: cacheId,\n      queryKey,\n      queryClient,\n      staleTime: staleTimeMs,\n      retry,\n      queryFn: async () =>\n        unwrapListResult(await fetchers.list(), definition.name) as Array<Row>,\n      getKey: (row) => String((row as Record<string, unknown>)[idField]),\n      onInsert: async ({ transaction }) => {\n        for (const mutation of transaction.mutations) {\n          const modified = mutation.modified as Record<string, unknown>;\n          // Strip the client-local id: the generated REST layer rejects or\n          // ignores client-supplied ids on create (#1540); the follow-up\n          // refetch swaps the optimistic row for the server-assigned one.\n          const { [idField]: _localId, ...data } = modified;\n          unwrapItemResult(\n            await fetchers.create(data),\n            `create(${definition.name})`,\n          );\n        }\n        // Persisted: refresh this collection and its related collections. Runs\n        // only after every create resolved — a rejected create rolls the\n        // optimistic row back and never reaches here.\n        invalidateRelated();\n      },\n      onUpdate: fetchers.update\n        ? async ({ transaction }) => {\n            for (const mutation of transaction.mutations) {\n              const key = String(mutation.key);\n              const changes = mutation.changes as Record<string, unknown>;\n              unwrapItemResult(\n                // biome-ignore lint/style/noNonNullAssertion: guarded by the surrounding ternary\n                await fetchers.update!(key, changes),\n                `update(${definition.name})`,\n              );\n            }\n            invalidateRelated();\n          }\n        : undefined,\n      onDelete: fetchers.delete\n        ? async ({ transaction }) => {\n            for (const mutation of transaction.mutations) {\n              // biome-ignore lint/style/noNonNullAssertion: guarded by the surrounding ternary\n              await fetchers.delete!(String(mutation.key));\n            }\n            invalidateRelated();\n          }\n        : undefined,\n    }),\n  );\n\n  // Wrap the engine collection in the SMRT-owned public surface. The wrapper\n  // projects rows to plain DTOs at every read boundary (toArray/get and change\n  // payloads) so the engine's virtual props never escape, and confines the\n  // engine's own types to this module.\n  const handle: SmrtWebCollection<TData> = {\n    get toArray() {\n      return collection.toArray.map((row) => toPlainRow<TData>(row));\n    },\n    get size() {\n      return collection.size;\n    },\n    has(key) {\n      return collection.has(key);\n    },\n    get(key) {\n      const row = collection.get(key);\n      return row === undefined ? undefined : toPlainRow<TData>(row);\n    },\n    preload() {\n      return collection.preload();\n    },\n    cleanup() {\n      return collection.cleanup();\n    },\n    subscribeChanges(callback) {\n      const subscription = collection.subscribeChanges((changes: unknown) =>\n        callback(projectChanges(changes)),\n      );\n      return { unsubscribe: () => subscription.unsubscribe() };\n    },\n    insert(row) {\n      return collection.insert(row) as unknown as SmrtWebTransaction;\n    },\n  };\n\n  engineCollections.set(handle, collection);\n  return handle;\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@happyvertical/smrt-web",
+  "version": "0.37.10",
+  "description": "SMRT browser client data runtime: typed collection factory wrapping the client-data engine over generated REST clients",
+  "author": "HappyVertical",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "CLAUDE.md",
+    "dist",
+    "AGENTS.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@tanstack/db": "^0.6.14",
+    "@tanstack/query-core": "^5.90.5",
+    "@tanstack/query-db-collection": "^1.0.46"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.2",
+    "typescript": "^5.9.3",
+    "vite": "8.1.2",
+    "vitest": "^4.1.9"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/happyvertical/smrt.git",
+    "directory": "packages/smrt-web"
+  },
+  "scripts": {
+    "build": "vite build --mode library && node ../../scripts/check-smrt-web-engine-boundary.mjs",
+    "build:watch": "vite build --mode library --watch",
+    "dev": "vite build --mode library --watch",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "verify:pack": "node ../../scripts/verify-package-types-exports.js ."
+  }
+}