tablinum 0.1.0 → 0.1.3

package/README.md

@@ -36,7 +36,7 @@ npm install tablinum
 
 ```typescript
 import { Effect } from "effect";
-import { createLocalstr, collection, field } from "tablinum";
+import { createTablinum, collection, field } from "tablinum";
 
 const schema = {
   todos: collection("todos", {
@@ -46,7 +46,7 @@ const schema = {
 };
 
 const program = Effect.gen(function* () {
-  const db = yield* createLocalstr({
+  const db = yield* createTablinum({
     schema,
     relays: ["wss://relay.example.com"],
   });
@@ -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/dist/db/{create-localstr.d.ts → create-tablinum.d.ts}

@@ -2,11 +2,11 @@ import { Effect, Scope } from "effect";
 import type { SchemaConfig } from "../schema/types.ts";
 import type { DatabaseHandle } from "./database-handle.ts";
 import { CryptoError, StorageError, ValidationError } from "../errors.ts";
-export interface LocalstrConfig<S extends SchemaConfig> {
+export interface TablinumConfig<S extends SchemaConfig> {
     readonly schema: S;
     readonly relays: readonly string[];
     readonly privateKey?: Uint8Array | undefined;
     readonly dbName?: string | undefined;
     readonly onSyncError?: ((error: Error) => void) | undefined;
 }
-export declare function createLocalstr<S extends SchemaConfig>(config: LocalstrConfig<S>): Effect.Effect<DatabaseHandle<S>, ValidationError | StorageError | CryptoError, Scope.Scope>;
+export declare function createTablinum<S extends SchemaConfig>(config: TablinumConfig<S>): Effect.Effect<DatabaseHandle<S>, ValidationError | StorageError | CryptoError, Scope.Scope>;

package/dist/index.d.ts

@@ -3,8 +3,8 @@ export { collection } from "./schema/collection.ts";
 export type { CollectionDef, CollectionFields } from "./schema/collection.ts";
 export type { FieldDef, FieldKind } from "./schema/field.ts";
 export type { InferRecord, SchemaConfig } from "./schema/types.ts";
-export { createLocalstr } from "./db/create-localstr.ts";
-export type { LocalstrConfig } from "./db/create-localstr.ts";
+export { createTablinum } from "./db/create-tablinum.ts";
+export type { TablinumConfig } from "./db/create-tablinum.ts";
 export type { DatabaseHandle, SyncStatus } from "./db/database-handle.ts";
 export type { CollectionHandle } from "./crud/collection-handle.ts";
 export type { CollectionOptions } from "./schema/collection.ts";

package/dist/index.js

@@ -48,7 +48,7 @@ function collection(name, fields, options) {
   }
   return { _tag: "CollectionDef", name, fields, indices };
 }
-// src/db/create-localstr.ts
+// src/db/create-tablinum.ts
 import { Effect as Effect14, PubSub as PubSub2, Ref as Ref5 } from "effect";
 
 // src/schema/validate.ts
@@ -160,7 +160,7 @@ function buildPartialValidator(collectionName, def) {
 // src/storage/idb.ts
 import { Effect as Effect2 } from "effect";
 import { openDB } from "idb";
-var DB_NAME = "localstr";
+var DB_NAME = "tablinum";
 function storeName(collection2) {
   return `col_${collection2}`;
 }
@@ -1665,7 +1665,7 @@ function createSyncHandle(storage, giftWrapHandle, relay, publishQueue, syncStat
       const result = yield* Effect13.result(relay.publish(giftWrap.event, relayUrls));
       if (result._tag === "Failure") {
         yield* publishQueue.enqueue(giftWrap.id);
-        console.error("[localstr:publishLocal] relay error:", result.failure);
+        console.error("[tablinum:publishLocal] relay error:", result.failure);
         if (onSyncError)
           onSyncError(result.failure);
       }
@@ -1685,19 +1685,19 @@ function createSyncHandle(storage, giftWrapHandle, relay, publishQueue, syncStat
           }));
         }));
         if (subResult._tag === "Failure") {
-          console.error("[localstr:subscribe] failed for", url, subResult.failure);
+          console.error("[tablinum:subscribe] failed for", url, subResult.failure);
           if (onSyncError)
             onSyncError(subResult.failure);
         } else {
-          console.log("[localstr:subscribe] listening on", url);
+          console.log("[tablinum:subscribe] listening on", url);
         }
       }
     })
   };
 }
 
-// src/db/create-localstr.ts
-function createLocalstr(config) {
+// src/db/create-tablinum.ts
+function createTablinum(config) {
   return Effect14.gen(function* () {
     if (!config.relays || config.relays.length === 0) {
       return yield* new ValidationError({
@@ -1711,7 +1711,7 @@ function createLocalstr(config) {
       });
     }
     let resolvedKey = config.privateKey;
-    const storageKeyName = `localstr-key-${config.dbName ?? "localstr"}`;
+    const storageKeyName = `tablinum-key-${config.dbName ?? "tablinum"}`;
     if (!resolvedKey && typeof globalThis.localStorage !== "undefined") {
       const saved = globalThis.localStorage.getItem(storageKeyName);
       if (saved && saved.length === 64) {
@@ -1737,7 +1737,7 @@ function createLocalstr(config) {
     const syncStatus = yield* createSyncStatusHandle();
     const syncHandle = createSyncHandle(storage, giftWrapHandle, relayHandle, publishQueue, syncStatus, watchCtx, config.relays, identity.publicKey, config.onSyncError);
     const onWrite = (event) => Effect14.gen(function* () {
-      console.log("[localstr:onWrite]", event.kind, event.collection, event.recordId);
+      console.log("[tablinum:onWrite]", event.kind, event.collection, event.recordId);
       const content = event.kind === "delete" ? JSON.stringify({ _deleted: true }) : JSON.stringify(event.data);
       const dTag = `${event.collection}:${event.recordId}`;
       const wrapResult = yield* Effect14.result(giftWrapHandle.wrap({
@@ -1748,13 +1748,13 @@ function createLocalstr(config) {
       }));
       if (wrapResult._tag === "Success") {
         const gw = wrapResult.success;
-        console.log("[localstr:onWrite] gift wrap created:", gw.id, "kind:", gw.kind, "tags:", JSON.stringify(gw.tags));
+        console.log("[tablinum:onWrite] gift wrap created:", gw.id, "kind:", gw.kind, "tags:", JSON.stringify(gw.tags));
         yield* storage.putGiftWrap({
           id: gw.id,
           event: gw,
           createdAt: gw.created_at
         });
-        console.log("[localstr:onWrite] gift wrap stored, publishing...");
+        console.log("[tablinum:onWrite] gift wrap stored, publishing...");
         const publishEffect = Effect14.gen(function* () {
           const pubResult = yield* Effect14.result(syncHandle.publishLocal({
             id: gw.id,
@@ -1763,17 +1763,17 @@ function createLocalstr(config) {
           }));
           if (pubResult._tag === "Failure") {
             const err = pubResult.failure;
-            console.error("[localstr:publish] failed:", err);
+            console.error("[tablinum:publish] failed:", err);
             if (config.onSyncError)
               config.onSyncError(err);
           } else {
-            console.log("[localstr:publish] success");
+            console.log("[tablinum:publish] success");
           }
         });
         yield* Effect14.forkDetach(publishEffect);
       } else {
         const err = wrapResult.failure;
-        console.error("[localstr:onWrite] wrap failed:", err);
+        console.error("[tablinum:onWrite] wrap failed:", err);
         if (config.onSyncError)
           config.onSyncError(err);
       }
@@ -1821,7 +1821,7 @@ function createLocalstr(config) {
 }
 export {
   field,
-  createLocalstr,
+  createTablinum,
   collection,
   ValidationError,
   SyncError,

package/dist/svelte/collection.svelte.d.ts

@@ -0,0 +1,20 @@
+import type { CollectionDef, CollectionFields } from "../schema/collection.ts";
+import type { InferRecord } from "../schema/types.ts";
+import type { CollectionHandle } from "../crud/collection-handle.ts";
+import { type SvelteWhereClause, type SvelteOrderByBuilder } from "./query.svelte.ts";
+export declare class Collection<C extends CollectionDef<CollectionFields>> {
+    #private;
+    items: any;
+    error: any;
+    constructor(handle: CollectionHandle<C>);
+    add: (data: Omit<InferRecord<C>, "id">) => Promise<string>;
+    update: (id: string, data: Partial<Omit<InferRecord<C>, "id">>) => Promise<void>;
+    delete: (id: string) => Promise<void>;
+    get: (id: string) => Promise<InferRecord<C>>;
+    first: () => Promise<InferRecord<C> | null>;
+    count: () => Promise<number>;
+    where: (field: string & keyof Omit<InferRecord<C>, "id">) => SvelteWhereClause<InferRecord<C>>;
+    orderBy: (field: string & keyof Omit<InferRecord<C>, "id">) => SvelteOrderByBuilder<InferRecord<C>>;
+    /** @internal Called by Database.close() */
+    _destroy(): void;
+}

package/dist/svelte/database.svelte.d.ts

@@ -0,0 +1,15 @@
+import { Scope } from "effect";
+import type { SchemaConfig } from "../schema/types.ts";
+import type { DatabaseHandle } from "../db/database-handle.ts";
+import { Collection } from "./collection.svelte.ts";
+export declare class Database<S extends SchemaConfig> {
+    #private;
+    status: any;
+    error: any;
+    constructor(handle: DatabaseHandle<S>, scope: Scope.Closeable);
+    collection<K extends string & keyof S>(name: K): Collection<S[K]>;
+    exportKey(): string;
+    close: () => Promise<void>;
+    sync: () => Promise<void>;
+    rebuild: () => Promise<void>;
+}

package/dist/svelte/index.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { SchemaConfig } from "../schema/types.ts";
+import { type TablinumConfig } from "../db/create-tablinum.ts";
+import { Database } from "./database.svelte.ts";
+export { field } from "../schema/field.ts";
+export { collection } from "../schema/collection.ts";
+export type { CollectionDef, CollectionFields } from "../schema/collection.ts";
+export type { FieldDef, FieldKind } from "../schema/field.ts";
+export type { InferRecord, SchemaConfig } from "../schema/types.ts";
+export type { TablinumConfig } from "../db/create-tablinum.ts";
+export type { SyncStatus } from "../db/database-handle.ts";
+export { ValidationError, StorageError, CryptoError, RelayError, SyncError, NotFoundError, ClosedError, } from "../errors.ts";
+export { Database } from "./database.svelte.ts";
+export { Collection } from "./collection.svelte.ts";
+export { LiveQuery } from "./live-query.svelte.ts";
+export type { SvelteQueryBuilder, SvelteWhereClause, SvelteOrderByBuilder, } from "./query.svelte.ts";
+export declare function createTablinum<S extends SchemaConfig>(config: TablinumConfig<S>): Promise<Database<S>>;