@blujosi/rivetkit-svelte 2.3.10 → 2.3.12

package/README.md

@@ -315,7 +315,7 @@ const count = counterActor?.useQuery({
 | `args` | `any[]?` | Optional arguments passed to the action |
 | `event` | `string` | The event name to subscribe to for real-time updates |
 | `initialValue` | `T` | The value to use before the action resolves |
-| `transform` | `(current: T, incoming: any) => T?` | Optional function to merge incoming event data with the current value |
+| `transform` | `(current: T, incoming: any) => T?` | Optional function to merge incoming event data with the current value. For CRUD lists, use `crudTransform<T>()` |
 
 **Default transform behavior:**
 - **Plain objects** — shallow merge: `{ ...current, ...incoming }`
@@ -533,8 +533,8 @@ c.broadcast("taskChanged", { type: "deleted", data: deletedTask });
 
   interface Task { id: string; title: string; done: boolean }
 
-  // With useQuery (client-side)
-  const tasks = actor?.useQuery({
+  // With useQuery (client-side) — T is the full state type (Task[])
+  const tasks = actor?.useQuery<Task[]>({
     action: "getTasks",
     event: "taskChanged",
     initialValue: [] as Task[],
@@ -544,8 +544,8 @@ c.broadcast("taskChanged", { type: "deleted", data: deletedTask });
 ```
 
 ```typescript
-// With rivetLoad (SSR + live)
-const tasks = await rivetLoad(client, {
+// With rivetLoad (SSR + live) — T is the item type, data returns Task[]
+const tasks = await rivetLoad<Registry, Task>(client, {
   actor: "taskList",
   key: ["my-list"],
   action: "getTasks",
@@ -622,7 +622,7 @@ c.broadcast("taskDeleted", task);
 For items keyed by something other than a single property:
 
 ```typescript
-const items = actor?.useQuery({
+const items = actor?.useQuery<Item[]>({
   action: "getItems",
   event: "itemChanged",
   initialValue: [],
@@ -743,17 +743,22 @@ export const transport = {
 
 #### 2. Use `rivetLoad()` in your load function
 
+`rivetLoad<T>` is designed for **collections** — `T` is the item type and `data` returns `T[]`. The default transform is `crudTransform<T>()`, so standard CRUD events work out of the box.
+
 ```typescript
-// src/routes/+page.ts
+// src/routes/todos/+page.ts
 import { rivetLoad } from "@blujosi/rivetkit-svelte/sveltekit"
 import { rivetClient } from "$lib/actor.client"
+import type { Registry } from "$backend/registry"
+
+interface Todo { id: string; text: string; done: boolean }
 
 export const load = async () => ({
-  count: await rivetLoad(rivetClient, {
-    actor: 'counter',
-    key: ['test-counter'],
-    action: 'getCount',
-    event: 'newCount',
+  todos: await rivetLoad<Registry, Todo>(rivetClient, {
+    actor: 'todoList',
+    key: ['my-list'],
+    action: 'getTodos',
+    event: 'todoChanged',
   })
 })
 ```
@@ -761,19 +766,23 @@ export const load = async () => ({
 #### 3. Use the data in your component
 
 ```svelte
-<!-- src/routes/+page.svelte -->
+<!-- src/routes/todos/+page.svelte -->
 <script lang="ts">
   let { data } = $props()
 
-  // data.count is already a reactive RivetQueryResult
+  // data.todos is already a reactive RivetQueryResult
   // It has SSR data immediately, then upgrades to live updates
-  const count = $derived(data.count.data)
+  const todos = $derived(data.todos.data)
 </script>
 
-{#if data.count.isLoading}
+{#if data.todos.isLoading}
   <p>Loading...</p>
 {:else}
-  <h1>Counter: {count}</h1>
+  <ul>
+    {#each todos ?? [] as todo}
+      <li>{todo.text}</li>
+    {/each}
+  </ul>
 {/if}
 ```
 
@@ -786,15 +795,20 @@ Fetch actor data for use in SvelteKit load functions. Dual-mode:
 - **Server (SSR):** calls the action via stateless HTTP, wraps result for transport
 - **Client (navigation):** calls action for initial data, then creates a live subscription immediately
 
+`rivetLoad<T>` is designed for **collections** — `T` is the item type and `data` returns `T[]`. The default transform is `crudTransform<T>()`, so standard CRUD events work without specifying a transform.
+
 ```typescript
-const result = await rivetLoad(rivetClient, {
-  actor: 'counter',
-  key: ['test-counter'],
-  action: 'getCount',
-  event: 'newCount',
+interface Todo { id: string; text: string; done: boolean }
+
+const result = await rivetLoad<Registry, Todo>(rivetClient, {
+  actor: 'todoList',
+  key: ['my-list'],
+  action: 'getTodos',
+  event: 'todoChanged',
   args: [],                         // optional action arguments
   params: { authToken: 'jwt-...' }, // optional connection params
-  transform: (current, incoming) => incoming, // optional transform
+  // transform defaults to crudTransform<T>() — override if needed:
+  // transform: (current, incoming) => [...current, incoming.data],
 })
 ```
 
@@ -810,13 +824,13 @@ const result = await rivetLoad(rivetClient, {
 | `params` | `Record<string, string>?` | Optional connection parameters |
 | `createInRegion` | `string?` | Region to create the actor in |
 | `createWithInput` | `unknown?` | Input data for actor creation |
-| `transform` | `(current: T, incoming: unknown) => T?` | Transform incoming event data. Default: full replacement |
+| `transform` | `(current: T[], incoming: CrudEvent<T>) => T[]?` | Transform incoming event data. Default: `crudTransform<T>()` |
 
 **Returns:** `RivetQueryResult<T>` — a reactive object with:
 
 | Property | Type | Description |
 |---|---|---|
-| `data` | `T \| undefined` | The current value |
+| `data` | `T[] \| undefined` | The current value (collection of items) |
 | `isLoading` | `boolean` | `true` while loading |
 | `error` | `Error \| undefined` | Error, if any |
 | `isConnected` | `boolean` | Whether the live connection is active |
@@ -838,24 +852,29 @@ export const transport = {
 }
 ```
 
-> **Note:** `decodeRivetLoad` accepts an optional third argument `transform` if you need to customize how event data is applied. By default, incoming event data fully replaces the current value.
+> **Note:** `decodeRivetLoad` accepts an optional third argument `transform` if you need to customize how event data is applied. By default, the transform is `crudTransform<T>()`, which handles `CrudEvent<T>` payloads (`{ type: "created" | "updated" | "deleted", data: T }`).
 
 ### Multiple queries in one load
 
 ```typescript
 // src/routes/+page.ts
+import type { Registry } from "$backend/registry"
+
+interface Todo { id: string; text: string; done: boolean }
+interface Comment { id: string; todoId: string; body: string }
+
 export const load = async () => ({
-  count: await rivetLoad(rivetClient, {
-    actor: 'counter',
-    key: ['test-counter'],
-    action: 'getCount',
-    event: 'newCount',
+  todos: await rivetLoad<Registry, Todo>(rivetClient, {
+    actor: 'todoList',
+    key: ['my-list'],
+    action: 'getTodos',
+    event: 'todoChanged',
   }),
-  countDouble: await rivetLoad(rivetClient, {
-    actor: 'counter',
-    key: ['test-counter'],
-    action: 'getCountDouble',
-    event: 'newDoubleCount',
+  comments: await rivetLoad<Registry, Comment>(rivetClient, {
+    actor: 'todoList',
+    key: ['my-list'],
+    action: 'getComments',
+    event: 'commentChanged',
   }),
 })
 ```
@@ -870,32 +889,26 @@ SSR data gives you read access. For mutations (calling actions that change state
 
   let { data } = $props();
 
-  // Read: SSR data with live updates
-  const count = $derived(data.count.data);
+  // Read: SSR data with live updates (T[] collection)
+  const todos = $derived(data.todos.data);
 
   // Write: useActor for action calls
-  const counterActor = useActor?.({
-    name: "counter",
-    key: ["test-counter"],
+  const todoActor = useActor?.({
+    name: "todoList",
+    key: ["my-list"],
   });
 
-  const increment = async () => {
-    await counterActor?.current?.connection?.increment(1);
+  const addTodo = async () => {
+    await todoActor?.current?.connection?.addTodo({ text: "New task" });
   };
 </script>
 
-<h1>Counter: {count}</h1>
-<button onclick={increment}>Increment</button>
-```
-
----
-
-## Common Pitfalls
-
-### Don't call `useActor` inside `onMount`
-
-`useActor` uses `$effect` runes internally. Runes must be initialized during synchronous component setup, not in deferred callbacks.
-
+<ul>
+  {#each todos ?? [] as todo}
+    <li>{todo.text}</li>
+  {/each}
+</ul>
+<button onclick={addTodo}>Add Todo</button>
 ```typescript
 // BAD
 onMount(() => {

package/dist/svelte/crud-transforms.d.ts

@@ -2,7 +2,8 @@
  * Generic CRUD transform factories for use with `useQuery` and `rivetLoad`.
  *
  * These produce `transform` functions that handle incoming create/update/delete
- * events against a list of items, keyed by an identifier field.
+ * events against a collection of items (`T[]`), keyed by an identifier field.
+ * `T` is always the **item** type; the state is always `T[]`.
  *
  * @example
  * ```ts
@@ -37,22 +38,19 @@ export interface CrudTransformOptions<T> {
 }
 /**
  * Transform for a **create** event.
- * - **Array:** appends the incoming item; duplicates (same key) are ignored.
- * - **Single item:** replaces the current value with the incoming item.
+ * Appends the incoming item to the collection; duplicates (same key) are ignored.
  */
-export declare function createTransform<T>(opts?: CrudTransformOptions<T>): <C extends T[] | T>(current: C, incoming: CrudEvent<T>) => C;
+export declare function createTransform<T>(opts?: CrudTransformOptions<T>): (current: T[], incoming: CrudEvent<T>) => T[];
 /**
  * Transform for an **update** event.
- * - **Array:** replaces the matching item in-place; returns unchanged if no match.
- * - **Single item:** replaces the current value with the incoming item.
+ * Replaces the matching item in the collection; returns unchanged if no match.
  */
-export declare function updateTransform<T>(opts?: CrudTransformOptions<T>): <C extends T[] | T>(current: C, incoming: CrudEvent<T>) => C;
+export declare function updateTransform<T>(opts?: CrudTransformOptions<T>): (current: T[], incoming: CrudEvent<T>) => T[];
 /**
  * Transform for a **delete** event.
- * - **Array:** removes the matching item. `incoming` can be the full item or just the key value.
- * - **Single item:** returns the current value unchanged (cannot delete a scalar).
+ * Removes the matching item from the collection. `incoming.data` can be the full item or just the key value.
  */
-export declare function deleteTransform<T>(opts?: CrudTransformOptions<T>): <C extends T[] | T>(current: C, incoming: CrudEvent<T>) => C;
+export declare function deleteTransform<T>(opts?: CrudTransformOptions<T>): (current: T[], incoming: CrudEvent<T>) => T[];
 /**
  * A single transform that handles create, update, and delete events.
  *
@@ -70,7 +68,7 @@ export declare function deleteTransform<T>(opts?: CrudTransformOptions<T>): <C e
  *
  * @example
  * ```ts
- * const users = todoActor?.useQuery({
+ * const users = todoActor?.useQuery<User>({
  *   action: "getUsers",
  *   event: "userListUpdate",
  *   initialValue: [],
@@ -78,4 +76,4 @@ export declare function deleteTransform<T>(opts?: CrudTransformOptions<T>): <C e
  * });
  * ```
  */
-export declare function crudTransform<T>(opts?: CrudTransformOptions<T>): <C extends T[] | T>(current: C, incoming: CrudEvent<T>) => C;
+export declare function crudTransform<T>(opts?: CrudTransformOptions<T>): (current: T[], incoming: CrudEvent<T>) => T[];

package/dist/svelte/crud-transforms.js

@@ -2,7 +2,8 @@
  * Generic CRUD transform factories for use with `useQuery` and `rivetLoad`.
  *
  * These produce `transform` functions that handle incoming create/update/delete
- * events against a list of items, keyed by an identifier field.
+ * events against a collection of items (`T[]`), keyed by an identifier field.
+ * `T` is always the **item** type; the state is always `T[]`.
  *
  * @example
  * ```ts
@@ -29,64 +30,55 @@ function getKey(item, key) {
         return item[key];
     }
 }
+function resolveId(item, key) {
+    return key != null ? getKey(item, key) : item.id;
+}
 // ---------------------------------------------------------------------------
 // Individual transforms
 // ---------------------------------------------------------------------------
 /**
  * Transform for a **create** event.
- * - **Array:** appends the incoming item; duplicates (same key) are ignored.
- * - **Single item:** replaces the current value with the incoming item.
+ * Appends the incoming item to the collection; duplicates (same key) are ignored.
  */
 export function createTransform(opts = {}) {
-    const keyProp = opts.key ?? "id";
-    return ((current, incoming) => {
+    const keyProp = opts.key;
+    return (current, incoming) => {
         const item = incoming.data;
-        if (Array.isArray(current)) {
-            const id = getKey(item, keyProp);
-            if (current.some((c) => getKey(c, keyProp) === id))
-                return current;
-            return [...current, item];
-        }
-        return item;
-    });
+        const id = resolveId(item, keyProp);
+        if (current.some((c) => resolveId(c, keyProp) === id))
+            return current;
+        return [...current, item];
+    };
 }
 /**
  * Transform for an **update** event.
- * - **Array:** replaces the matching item in-place; returns unchanged if no match.
- * - **Single item:** replaces the current value with the incoming item.
+ * Replaces the matching item in the collection; returns unchanged if no match.
  */
 export function updateTransform(opts = {}) {
-    const keyProp = opts.key ?? "id";
-    return ((current, incoming) => {
+    const keyProp = opts.key;
+    return (current, incoming) => {
         const item = incoming.data;
-        if (Array.isArray(current)) {
-            const id = getKey(item, keyProp);
-            const idx = current.findIndex((c) => getKey(c, keyProp) === id);
-            if (idx === -1)
-                return current;
-            const next = [...current];
-            next[idx] = item;
-            return next;
-        }
-        return item;
-    });
+        const id = resolveId(item, keyProp);
+        const idx = current.findIndex((c) => resolveId(c, keyProp) === id);
+        if (idx === -1)
+            return current;
+        const next = [...current];
+        next[idx] = item;
+        return next;
+    };
 }
 /**
  * Transform for a **delete** event.
- * - **Array:** removes the matching item. `incoming` can be the full item or just the key value.
- * - **Single item:** returns the current value unchanged (cannot delete a scalar).
+ * Removes the matching item from the collection. `incoming.data` can be the full item or just the key value.
  */
 export function deleteTransform(opts = {}) {
-    const keyProp = opts.key ?? "id";
-    return ((current, incoming) => {
-        if (Array.isArray(current)) {
-            const id = typeof incoming.data === "object" && incoming.data !== null
-                ? getKey(incoming.data, keyProp)
-                : incoming.data;
-            return current.filter((c) => getKey(c, keyProp) !== id);
-        }
-        return current;
-    });
+    const keyProp = opts.key;
+    return (current, incoming) => {
+        const id = typeof incoming.data === "object" && incoming.data !== null
+            ? resolveId(incoming.data, keyProp)
+            : incoming.data;
+        return current.filter((c) => resolveId(c, keyProp) !== id);
+    };
 }
 // ---------------------------------------------------------------------------
 // Unified CRUD transform
@@ -108,7 +100,7 @@ export function deleteTransform(opts = {}) {
  *
  * @example
  * ```ts
- * const users = todoActor?.useQuery({
+ * const users = todoActor?.useQuery<User>({
  *   action: "getUsers",
  *   event: "userListUpdate",
  *   initialValue: [],
@@ -120,7 +112,7 @@ export function crudTransform(opts = {}) {
     const create = createTransform(opts);
     const update = updateTransform(opts);
     const del = deleteTransform(opts);
-    return ((current, incoming) => {
+    return (current, incoming) => {
         switch (incoming.type) {
             case "created":
                 return create(current, incoming);
@@ -131,5 +123,5 @@ export function crudTransform(opts = {}) {
             default:
                 return current;
         }
-    });
+    };
 }

package/dist/svelte/rivet.svelte.d.ts

@@ -64,7 +64,7 @@ export interface ActorStateReference<AD extends AnyActorDefinition> {
 import { createClient } from "rivetkit/client";
 export { createClient } from "rivetkit/client";
 export declare function createRivetKit<Registry extends AnyActorRegistry>(clientInput?: Parameters<typeof createClient>[0], opts?: CreateRivetKitOptions<Registry>): {
-    useActor: <ActorName extends keyof ExtractActorsFromRegistry<Registry>>(opts: ActorOptions<Registry, ActorName>) => {
+    useActor: <ActorName extends keyof ExtractActorsFromRegistry<Registry> & string>(opts: ActorOptions<Registry, ActorName>) => {
         current: {
             connect(): void;
             readonly connection: any;
@@ -102,7 +102,7 @@ export declare function createRivetKit<Registry extends AnyActorRegistry>(client
     };
 };
 export declare function createRivetKitWithClient<Registry extends AnyActorRegistry>(client: Client<Registry>, opts?: CreateRivetKitOptions<Registry>): {
-    useActor: <ActorName extends keyof ExtractActorsFromRegistry<Registry>>(opts: ActorOptions<Registry, ActorName>) => {
+    useActor: <ActorName extends keyof ExtractActorsFromRegistry<Registry> & string>(opts: ActorOptions<Registry, ActorName>) => {
         current: {
             connect(): void;
             readonly connection: any;

package/dist/sveltekit/transport.svelte.d.ts

@@ -7,14 +7,15 @@
  */
 import type { AnyActorRegistry } from "@rivetkit/framework-base";
 import type { Client } from "rivetkit/client";
-/** Reactive query result returned by rivetLoad (after decode) and on client nav. */
-export interface RivetQueryResult<T = unknown> {
-    readonly data: T | undefined;
+import type { CrudEvent } from "../svelte/crud-transforms";
+/** Reactive query result returned by rivetLoad (after decode) and on client nav. `T` is the item type; data is always `T[]`. */
+export interface RivetQueryResult<T> {
+    readonly data: T[] | undefined;
     readonly isLoading: boolean;
     readonly error: Error | undefined;
     readonly isConnected: boolean;
 }
-export interface RivetLoadOptions<T = unknown> {
+export interface RivetLoadOptions<T> {
     /** Actor name from the registry (e.g. 'counter'). */
     actor: string;
     /** Unique key for the actor instance. */
@@ -31,8 +32,8 @@ export interface RivetLoadOptions<T = unknown> {
     createInRegion?: string;
     /** Optional input data for actor creation. */
     createWithInput?: unknown;
-    /** Transform incoming event data into the new value. Default: full replacement. */
-    transform?: (current: T, incoming: any) => T;
+    /** Transform incoming event data into the new collection. Default: `crudTransform<T>()`. */
+    transform?: (current: T[], incoming: CrudEvent<T>) => T[];
 }
 /** Marker class for transport.encode to recognize. */
 export declare class RivetLoadResult<T = unknown> {
@@ -91,5 +92,5 @@ export declare function encodeRivetLoad(value: unknown): false | RivetLoadEncode
  * Decode a serialized RivetLoadResult into a live actor subscription.
  * Uses createDetachedActorQuery — works outside component context.
  */
-export declare function decodeRivetLoad<Registry extends AnyActorRegistry>(encoded: RivetLoadEncoded, client: Client<Registry>, transform?: (current: unknown, incoming: unknown) => unknown): RivetQueryResult<unknown>;
+export declare function decodeRivetLoad<Registry extends AnyActorRegistry>(encoded: RivetLoadEncoded, client: Client<Registry>, transform?: (current: unknown[], incoming: CrudEvent<unknown>) => unknown[]): RivetQueryResult<unknown>;
 export {};

package/dist/sveltekit/transport.svelte.js

@@ -5,6 +5,7 @@
  * On the client, transport.decode upgrades it to a live actor subscription.
  * On client-side navigation, rivetLoad creates a live subscription directly.
  */
+import { crudTransform } from "../svelte/crud-transforms";
 const IS_BROWSER = typeof globalThis.document !== "undefined";
 // ============================================================================
 // RivetLoadResult — the serializable container
@@ -132,7 +133,7 @@ export function decodeRivetLoad(encoded, client, transform) {
  * Connects to the actor, subscribes to event(s), and keeps data reactive.
  */
 function createDetachedActorQuery(client, opts, initialData) {
-    const { actor: actorName, key, event, params, createInRegion, createWithInput, transform = (_current, incoming) => incoming, } = opts;
+    const { actor: actorName, key, event, params, createInRegion, createWithInput, transform = crudTransform(), } = opts;
     let data = $state(initialData);
     let isLoading = $state(false);
     let error = $state(undefined);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@blujosi/rivetkit-svelte",
-	"version": "2.3.10",
+	"version": "2.3.12",
 	"scripts": {
 		"build": "vite build && npm run prepack",
 		"preview": "vite preview",