tablinum 0.1.1 → 0.1.3

package/README.md

@@ -72,6 +72,118 @@ const program = Effect.gen(function* () {
 Effect.runPromise(Effect.scoped(program));
 ```
 
+## Svelte 5
+
+Import from `tablinum/svelte` for reactive bindings that use Svelte 5 runes. No Effect knowledge needed — the API is plain async/await.
+
+### Setup
+
+Create a database helper that defines your schema and initializes the database:
+
+```typescript
+// src/lib/db.ts
+import { createTablinum, collection, field } from "tablinum/svelte";
+
+const schema = {
+  todos: collection(
+    "todos",
+    {
+      title: field.string(),
+      done: field.boolean(),
+    },
+    { indices: ["done"] },
+  ),
+};
+
+export type AppSchema = typeof schema;
+
+export async function initDb() {
+  return createTablinum({
+    schema,
+    relays: ["wss://relay.example.com"],
+  });
+}
+```
+
+### Component
+
+Collections and live queries are reactive — their `.items` property updates automatically when data changes.
+
+```svelte
+<script lang="ts">
+  import { onDestroy } from "svelte";
+  import { initDb, type AppSchema } from "$lib/db";
+  import type { Database, Collection, LiveQuery } from "tablinum/svelte";
+
+  let db: Database<AppSchema> | null = $state(null);
+  let todos: Collection<AppSchema["todos"]> | null = $state(null);
+  let pending: LiveQuery<{ id: string; title: string; done: boolean }> | null = $state(null);
+
+  let title = $state("");
+
+  async function init() {
+    db = await initDb();
+    todos = db.collection("todos");
+    pending = todos.where("done").equals(false).live();
+  }
+
+  init();
+
+  async function addTodo(e: SubmitEvent) {
+    e.preventDefault();
+    if (!todos || !title.trim()) return;
+    await todos.add({ title: title.trim(), done: false });
+    title = "";
+  }
+
+  async function toggle(id: string, currentDone: boolean) {
+    await todos?.update(id, { done: !currentDone });
+  }
+
+  async function remove(id: string) {
+    await todos?.delete(id);
+  }
+
+  onDestroy(() => {
+    pending?.destroy();
+    db?.close();
+  });
+</script>
+
+<!-- All todos (reactive via collection.items) -->
+<p>{todos?.items.length ?? 0} total</p>
+
+<!-- Filtered todos (reactive via live query) -->
+<form onsubmit={addTodo}>
+  <input bind:value={title} placeholder="Add a todo..." />
+  <button type="submit">Add</button>
+</form>
+
+<ul>
+  {#each pending?.items ?? [] as todo (todo.id)}
+    <li>
+      <input type="checkbox" checked={todo.done} onchange={() => toggle(todo.id, todo.done)} />
+      <span>{todo.title}</span>
+      <button onclick={() => remove(todo.id)}>Delete</button>
+    </li>
+  {/each}
+</ul>
+
+<!-- Sync status is reactive -->
+{#if db?.status === "syncing"}
+  <p>Syncing...</p>
+{/if}
+
+<button onclick={() => db?.sync()}>Sync</button>
+```
+
+### Key concepts
+
+- **`createTablinum`** returns a `Promise<Database>` (no Effect boilerplate)
+- **`collection.items`** is a reactive `$state` array of all records in the collection
+- **`.where("field").equals(value).live()`** returns a `LiveQuery` whose `.items` update automatically
+- **Cleanup**: call `.destroy()` on live queries and `.close()` on the database in `onDestroy`
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tablinum",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kevmodrome/tablinum.git"