@blujosi/rivetkit-svelte 2.2.1 → 2.3.2

package/README.md

@@ -24,6 +24,7 @@ npm i @blujosi/rivetkit-svelte rivetkit
 - **Svelte 5 Runes** — Built for `$state`, `$effect`, and `$derived`
 - **Real-time Actor Connections** — Connect to RivetKit actors with automatic state sync
 - **Event Handling** — `useEvent` with automatic cleanup
+- **CRUD Transforms** — Pre-built transform factories for managing lists via create/update/delete events
 - **Type Safety** — Full TypeScript support with registry type inference
 - **SSR Compatible** — Browser guard for SvelteKit SSR
 - **SvelteKit Handler** — Run RivetKit serverless inside your SvelteKit app
@@ -470,6 +471,139 @@ count?.refetch();
 | **Best for** | Most use-cases | High-frequency events where refetch would be wasteful |
 | **Refetch** | `.refetch()` available | Not available |
 
+---
+
+### CRUD Transforms (`@blujosi/rivetkit-svelte`)
+
+Pre-built `transform` factories for managing lists of items via create/update/delete events. Use with `useQuery` or `rivetLoad`.
+
+```typescript
+import {
+  crudTransform,
+  createTransform,
+  updateTransform,
+  deleteTransform,
+} from "@blujosi/rivetkit-svelte";
+```
+
+#### `crudTransform<T>(opts?)`
+
+A unified transform that handles all three CRUD operations in a single function. The actor broadcasts events wrapped in a `CrudEvent<T>`:
+
+```typescript
+// In the actor:
+c.broadcast("taskChanged", { type: "created", data: newTask });
+c.broadcast("taskChanged", { type: "updated", data: updatedTask });
+c.broadcast("taskChanged", { type: "deleted", data: deletedTask });
+```
+
+```svelte
+<script lang="ts">
+  import { crudTransform } from "@blujosi/rivetkit-svelte";
+
+  interface Task { id: string; title: string; done: boolean }
+
+  // With useQuery (client-side)
+  const tasks = actor?.useQuery({
+    action: "getTasks",
+    event: "taskChanged",
+    initialValue: [] as Task[],
+    transform: crudTransform<Task>({ key: "id" }),
+  });
+</script>
+```
+
+```typescript
+// With rivetLoad (SSR + live)
+const tasks = await rivetLoad(client, {
+  actor: "taskList",
+  key: ["my-list"],
+  action: "getTasks",
+  event: "taskChanged",
+  transform: crudTransform<Task>({ key: "id" }),
+});
+```
+
+If the incoming payload is **not** wrapped in `{ type, data }`, `crudTransform` falls back to an **upsert** — it updates the item if it exists, or appends it otherwise.
+
+**Options (`CrudTransformOptions<T>`):**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `key` | `keyof T \| (item: T) => unknown` | `"id"` | Property name or accessor used to uniquely identify items |
+
+**`CrudEvent<T>` shape:**
+
+| Field | Type | Description |
+|---|---|---|
+| `type` | `"created" \| "updated" \| "deleted"` | The operation type |
+| `data` | `T` | The item (or key value for deletes) |
+
+#### Individual Transforms
+
+Use these when you have **separate events** for each operation:
+
+##### `createTransform<T>(opts?)`
+
+Appends the incoming item to the list. Duplicates (same key) are ignored.
+
+```typescript
+const tasks = actor?.useQuery({
+  action: "getTasks",
+  event: "taskCreated",
+  initialValue: [],
+  transform: createTransform<Task>({ key: "id" }),
+});
+```
+
+##### `updateTransform<T>(opts?)`
+
+Replaces the matching item in-place. If no match is found, the list is returned unchanged.
+
+```typescript
+const tasks = actor?.useQuery({
+  action: "getTasks",
+  event: "taskUpdated",
+  initialValue: [],
+  transform: updateTransform<Task>({ key: "id" }),
+});
+```
+
+##### `deleteTransform<T>(opts?)`
+
+Removes the matching item. Accepts either a full object or a raw key value.
+
+```typescript
+const tasks = actor?.useQuery({
+  action: "getTasks",
+  event: "taskDeleted",
+  initialValue: [],
+  transform: deleteTransform<Task>({ key: "id" }),
+});
+
+// The actor can broadcast just the key:
+c.broadcast("taskDeleted", taskId);
+// Or the full object:
+c.broadcast("taskDeleted", task);
+```
+
+#### Custom Key Functions
+
+For items keyed by something other than a single property:
+
+```typescript
+const items = actor?.useQuery({
+  action: "getItems",
+  event: "itemChanged",
+  initialValue: [],
+  transform: crudTransform<Item>({
+    key: (item) => `${item.type}:${item.slug}`,
+  }),
+});
+```
+
+---
+
 ### SvelteKit Exports (`@blujosi/rivetkit-svelte/sveltekit`)
 
 #### `createRivetKitHandler(opts)`

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

@@ -0,0 +1,81 @@
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const tasks = await rivetLoad(client, {
+ *   actor: "taskList",
+ *   key: ["my-list"],
+ *   action: "getTasks",
+ *   event: "taskChanged",
+ *   transform: crudTransform<Task>({ key: "id" }),
+ * });
+ * ```
+ */
+/**
+ * An incoming event payload that carries a CRUD operation type.
+ *
+ * Actors should broadcast events in this shape:
+ * ```ts
+ * c.broadcast("todoListUpdate", { data: todo, type: "created" })
+ * ```
+ */
+export interface CrudEvent<T> {
+    data: T;
+    type: "created" | "updated" | "deleted";
+}
+/** Options shared by all CRUD transform factories. */
+export interface CrudTransformOptions<T> {
+    /**
+     * Property name (or accessor) used to uniquely identify items.
+     * Defaults to `"id"`.
+     */
+    key?: keyof T | ((item: T) => unknown);
+}
+/**
+ * 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.
+ */
+export declare function createTransform<T>(opts?: CrudTransformOptions<T>): <C extends T[] | T>(current: C, incoming: unknown) => C;
+/**
+ * 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.
+ */
+export declare function updateTransform<T>(opts?: CrudTransformOptions<T>): <C extends T[] | T>(current: C, incoming: unknown) => C;
+/**
+ * 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).
+ */
+export declare function deleteTransform<T>(opts?: CrudTransformOptions<T>): <C extends T[] | T>(current: C, incoming: unknown) => C;
+/**
+ * A single transform that handles create, update, and delete events.
+ *
+ * Incoming payloads must be a `CrudEvent<T>` with `{ data, type }`:
+ * ```ts
+ * { data: item, type: "created" }
+ * { data: item, type: "updated" }
+ * { data: item, type: "deleted" }
+ * ```
+ *
+ * Actors should broadcast in this shape:
+ * ```ts
+ * c.broadcast("todoListUpdate", { data: todo, type: "created" })
+ * ```
+ *
+ * @example
+ * ```ts
+ * const users = todoActor?.useQuery({
+ *   action: "getUsers",
+ *   event: "userListUpdate",
+ *   initialValue: [],
+ *   transform: crudTransform<User>({ key: "id" }),
+ * });
+ * ```
+ */
+export declare function crudTransform<T>(opts?: CrudTransformOptions<T>): <C extends T[] | T>(current: C, incoming: CrudEvent<T>) => C;

package/dist/svelte/crud-transforms.js

@@ -0,0 +1,127 @@
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const tasks = await rivetLoad(client, {
+ *   actor: "taskList",
+ *   key: ["my-list"],
+ *   action: "getTasks",
+ *   event: "taskChanged",
+ *   transform: crudTransform<Task>({ key: "id" }),
+ * });
+ * ```
+ */
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function getKey(item, key) {
+    return typeof key === "function" ? key(item) : item[key];
+}
+// ---------------------------------------------------------------------------
+// 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.
+ */
+export function createTransform(opts = {}) {
+    const keyProp = opts.key ?? "id";
+    return ((current, incoming) => {
+        const item = incoming;
+        if (Array.isArray(current)) {
+            const id = getKey(item, keyProp);
+            if (current.some((c) => getKey(c, keyProp) === id))
+                return current;
+            return [...current, item];
+        }
+        return 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.
+ */
+export function updateTransform(opts = {}) {
+    const keyProp = opts.key ?? "id";
+    return ((current, incoming) => {
+        const item = incoming;
+        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;
+    });
+}
+/**
+ * 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).
+ */
+export function deleteTransform(opts = {}) {
+    const keyProp = opts.key ?? "id";
+    return ((current, incoming) => {
+        if (Array.isArray(current)) {
+            const id = typeof incoming === "object" && incoming !== null
+                ? getKey(incoming, keyProp)
+                : incoming;
+            return current.filter((c) => getKey(c, keyProp) !== id);
+        }
+        return current;
+    });
+}
+// ---------------------------------------------------------------------------
+// Unified CRUD transform
+// ---------------------------------------------------------------------------
+/**
+ * A single transform that handles create, update, and delete events.
+ *
+ * Incoming payloads must be a `CrudEvent<T>` with `{ data, type }`:
+ * ```ts
+ * { data: item, type: "created" }
+ * { data: item, type: "updated" }
+ * { data: item, type: "deleted" }
+ * ```
+ *
+ * Actors should broadcast in this shape:
+ * ```ts
+ * c.broadcast("todoListUpdate", { data: todo, type: "created" })
+ * ```
+ *
+ * @example
+ * ```ts
+ * const users = todoActor?.useQuery({
+ *   action: "getUsers",
+ *   event: "userListUpdate",
+ *   initialValue: [],
+ *   transform: crudTransform<User>({ key: "id" }),
+ * });
+ * ```
+ */
+export function crudTransform(opts = {}) {
+    const create = createTransform(opts);
+    const update = updateTransform(opts);
+    const del = deleteTransform(opts);
+    return ((current, incoming) => {
+        switch (incoming.type) {
+            case "created":
+                return create(current, incoming.data);
+            case "updated":
+                return update(current, incoming.data);
+            case "deleted":
+                return del(current, incoming.data);
+            default:
+                return current;
+        }
+    });
+}

package/dist/svelte/index.d.ts

@@ -1 +1,2 @@
+export * from "./crud-transforms";
 export * from "./rivet.svelte.js";

package/dist/svelte/index.js

@@ -1 +1,2 @@
+export * from "./crud-transforms";
 export * from "./rivet.svelte.js";

package/package.json

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