@happyvertical/smrt-svelte 0.37.8 → 0.37.10

package/dist/web/live-collection.svelte.js

@@ -0,0 +1,173 @@
+/**
+ * Svelte 5 live-query bindings for `@happyvertical/smrt-web` (#1761, slice A).
+ *
+ * Turns a SMRT-owned {@link SmrtWebCollection} into runes-reactive live-query
+ * state plus mutation helpers, so a consumer writes reactive components WITHOUT
+ * importing TanStack. The client-data engine (`@tanstack/db` +
+ * `@tanstack/svelte-db`) is used only inside this module — its types never
+ * appear on the public surface, mirroring smrt-web's own engine-absorption
+ * boundary (ratified condition for #1761).
+ *
+ * Two engine facts drive the shape of this file:
+ *
+ * 1. `useLiveQuery` internally uses `$state`/`$derived`/`$effect`, so it (and
+ *    therefore {@link liveCollection}) MUST be called during Svelte component
+ *    initialization — exactly like this package's other `use*` composables.
+ *    Its internal `$effect` binds to the calling component's lifecycle, so the
+ *    live subscription is torn down automatically when the component unmounts.
+ *
+ * 2. `@tanstack/svelte-db` live-query rows carry ENUMERABLE engine virtual
+ *    props (`$key`/`$origin`/`$synced`/`$collectionId`) that would otherwise
+ *    escape through spread or JSON. Every exposed row is projected to a plain
+ *    DTO by stripping `$`-prefixed keys (the `$` prefix is reserved for the
+ *    engine; SMRT columns never begin with it), mirroring smrt-web's internal
+ *    `toPlainRow`.
+ */
+import { getEngineCollection, } from '@happyvertical/smrt-web';
+import { useLiveQuery } from '@tanstack/svelte-db';
+/**
+ * Project an engine live-query row to a plain public DTO by dropping every
+ * `$`-prefixed key. Mirrors smrt-web's internal `toPlainRow`: the `$` prefix is
+ * reserved for the engine's enumerable virtual props (`$key`/`$origin`/
+ * `$synced`/`$collectionId`); SMRT columns never begin with it. Char code 36
+ * is `'$'`.
+ */
+function toPlainRow(row) {
+    const plain = {};
+    for (const [key, value] of Object.entries(row)) {
+        if (key.charCodeAt(0) !== 36)
+            plain[key] = value;
+    }
+    return plain;
+}
+/** Map the engine's fine-grained status to the coarse SMRT-owned status. */
+function toLiveStatus(isReady, isError) {
+    if (isError)
+        return 'error';
+    if (isReady)
+        return 'ready';
+    return 'loading';
+}
+/**
+ * Create a runes-reactive live view over a {@link SmrtWebCollection}.
+ *
+ * MUST be called during Svelte component initialization (it delegates to
+ * `@tanstack/svelte-db`'s `useLiveQuery`, which sets up a `$effect`). The live
+ * subscription is torn down automatically when the calling component unmounts.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { createSmrtCollection } from '@happyvertical/smrt-web';
+ *   import { liveCollection } from '@happyvertical/smrt-svelte/web';
+ *   import { productsDefinition } from '@happyvertical/smrt-virt-web';
+ *
+ *   const products = createSmrtCollection(productsDefinition, {});
+ *   const view = liveCollection(products);
+ *
+ *   async function add() {
+ *     const m = view.insert({ id: crypto.randomUUID(), name: 'New' });
+ *     await m.done.catch(() => {}); // error also reflected on m.error
+ *   }
+ * </script>
+ *
+ * {#if view.isLoading}
+ *   <p>Loading…</p>
+ * {:else if view.isError}
+ *   <p>Failed: {String(view.error)}</p>
+ * {:else}
+ *   <ul>
+ *     {#each view.rows as row (row.id)}
+ *       <li>{row.name}</li>
+ *     {/each}
+ *   </ul>
+ * {/if}
+ * ```
+ */
+export function liveCollection(handle, options = {}) {
+    const { preload = true } = options;
+    // Bridge to the engine collection (typed `unknown` at the boundary — cast to
+    // the engine `Collection` here, and confine that type to this module).
+    const engine = getEngineCollection(handle);
+    // Kick the first load without forcing consumers to await preload() — the
+    // live query subscribes lazily, so nudge it when requested. Swallow the
+    // rejection: a load failure (network error, or an SSR relative-URL
+    // `Failed to parse URL` TypeError) already surfaces reactively via the
+    // live-query status; this fire-and-forget must not become an unhandled
+    // rejection.
+    if (preload) {
+        void handle.preload().catch(() => { });
+    }
+    // The live query over the whole base collection. No `.select()` → `data`
+    // carries the full row objects (with engine virtual props, stripped below).
+    // `useLiveQuery` installs a `$effect`; calling `liveCollection` outside a
+    // component surfaces Svelte's own "effect outside component" error, which is
+    // the correct signal.
+    const query = useLiveQuery((q) => q.from({ row: engine }));
+    // Project rows to plain DTOs reactively. `query.data` is a $state-backed
+    // reactive array; `$derived.by` recomputes the projection when it changes.
+    const rows = $derived.by(() => query.data.map((row) => toPlainRow(row)));
+    const status = $derived(toLiveStatus(query.isReady, query.isError));
+    // useLiveQuery does not surface an error object, only an error status; expose
+    // the status string as the error payload when the read has failed.
+    const error = $derived(query.isError ? query.status : null);
+    return {
+        get rows() {
+            return rows;
+        },
+        get status() {
+            return status;
+        },
+        get error() {
+            return error;
+        },
+        get isLoading() {
+            return status === 'loading';
+        },
+        get isReady() {
+            return status === 'ready';
+        },
+        get isError() {
+            return status === 'error';
+        },
+        insert(row) {
+            return createMutation(() => handle.insert(row).isPersisted.promise);
+        },
+    };
+}
+/**
+ * Wrap a transaction's settle promise in a reactive {@link LiveCollectionMutation}.
+ * Runs the mutation immediately; tracks pending/error via runes. Kept separate
+ * so `insert` (and future `update`/`delete` helpers) share one reactive shape.
+ */
+function createMutation(run) {
+    let pending = $state(true);
+    let settled = $state(false);
+    let error = $state(null);
+    // `done` RESOLVES on settle whether the write persisted or rolled back — the
+    // failure is surfaced only reactively via `error`. Re-throwing here would
+    // reject `done`, which a reactive-only consumer (reads `error`/`pending` in
+    // markup, never awaits `done`) would leave as an unhandled rejection.
+    const done = run().then(() => {
+        pending = false;
+        settled = true;
+    }, (cause) => {
+        pending = false;
+        settled = true;
+        error = cause;
+    });
+    return {
+        get pending() {
+            return pending;
+        },
+        get settled() {
+            return settled;
+        },
+        get error() {
+            return error;
+        },
+        get done() {
+            return done;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-svelte",
-  "version": "0.37.8",
+  "version": "0.37.10",
   "description": "Svelte 5 components for SMRT user management - auth, users, tenants, roles, permissions, groups",
   "type": "module",
   "smrtRawPrimitives": "strict",
@@ -46,6 +46,12 @@
       "svelte": "./dist/browser-ai/svelte/index.js",
       "import": "./dist/browser-ai/svelte/index.js",
       "default": "./dist/browser-ai/svelte/index.js"
+    },
+    "./web": {
+      "types": "./dist/web/index.d.ts",
+      "svelte": "./dist/web/index.js",
+      "import": "./dist/web/index.js",
+      "default": "./dist/web/index.js"
     }
   },
   "files": [
@@ -77,10 +83,13 @@
   },
   "dependencies": {
     "@happyvertical/logger": "^0.74.11",
+    "@tanstack/db": "^0.6.14",
+    "@tanstack/svelte-db": "^0.1.91",
     "esm-env": "^1.2.2",
-    "@happyvertical/smrt-ui": "0.37.8",
-    "@happyvertical/smrt-languages": "0.37.8",
-    "@happyvertical/smrt-types": "0.37.8"
+    "@happyvertical/smrt-languages": "0.37.10",
+    "@happyvertical/smrt-types": "0.37.10",
+    "@happyvertical/smrt-ui": "0.37.10",
+    "@happyvertical/smrt-web": "0.37.10"
   },
   "peerDependencies": {
     "@huggingface/transformers": ">=3.8.1",