tablinum 0.1.3 → 0.2.0

package/README.md

@@ -60,7 +60,7 @@ const program = Effect.gen(function* () {
   const todo = yield* todos.get(id);
 
   // Query
-  const pending = yield* todos.where("done").equals(false).toArray();
+  const pending = yield* todos.where("done").equals(false).get();
 
   // Update
   yield* todos.update(id, { done: true });
@@ -76,13 +76,26 @@ Effect.runPromise(Effect.scoped(program));
 
 Import from `tablinum/svelte` for reactive bindings that use Svelte 5 runes. No Effect knowledge needed — the API is plain async/await.
 
+This API uses Svelte's async runes support, so enable it in your app config:
+
+```js
+// svelte.config.js
+const config = {
+  compilerOptions: {
+    experimental: {
+      async: true,
+    },
+  },
+};
+```
+
 ### 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";
+import { Tablinum, collection, field } from "tablinum/svelte";
 
 const schema = {
   todos: collection(
@@ -97,92 +110,90 @@ const schema = {
 
 export type AppSchema = typeof schema;
 
-export async function initDb() {
-  return createTablinum({
-    schema,
-    relays: ["wss://relay.example.com"],
-  });
-}
+export const db = new Tablinum({
+  schema,
+  relays: ["wss://relay.example.com"],
+});
+
+export const todos = db.collection("todos");
 ```
 
 ### Component
 
-Collections and live queries are reactive — their `.items` property updates automatically when data changes.
+Async collection reads are reactive when used inside `$derived(await ...)` expressions.
 
 ```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);
+  import { db, todos } from "$lib/db";
 
   let title = $state("");
-
-  async function init() {
-    db = await initDb();
-    todos = db.collection("todos");
-    pending = todos.where("done").equals(false).live();
-  }
-
-  init();
+  let booted = $derived(await db.ready.then(() => true, () => false));
+  let pending = $derived(
+    booted && db.status === "ready"
+      ? await todos.where("done").equals(false).get()
+      : [],
+  );
 
   async function addTodo(e: SubmitEvent) {
     e.preventDefault();
-    if (!todos || !title.trim()) return;
+    if (!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 });
+    await todos.update(id, { done: !currentDone });
   }
 
   async function remove(id: string) {
-    await todos?.delete(id);
+    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>
+<svelte:boundary>
+  {#snippet pending()}
+    <p>Initializing database...</p>
+  {/snippet}
+
+  {#if db.status === "error"}
+    <p>{db.error?.message}</p>
+  {:else}
+    <p>{pending.length} pending</p>
+
+    <form onsubmit={addTodo}>
+      <input bind:value={title} placeholder="Add a todo..." />
+      <button type="submit">Add</button>
+    </form>
+
+    <ul>
+      {#each pending 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>
+
+    {#if db.syncStatus === "syncing"}
+      <p>Syncing...</p>
+    {/if}
+
+    <button onclick={() => db.sync()}>Sync</button>
+  {/if}
+</svelte:boundary>
 ```
 
 ### 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`
+- **`new Tablinum(config)`** starts initialization immediately and exposes `db.ready`
+- **Async queries are reactive** when used inside `$derived(await ...)`
+- **`db.status`** tracks initialization and terminal state; **`db.syncStatus`** tracks sync activity
+- **`createTablinum(config)`** still exists as a convenience and resolves once `db.ready` completes
 
 ## License
 

package/dist/brands.d.ts

@@ -0,0 +1,5 @@
+import { Brand } from "effect";
+export type EpochId = Brand.Branded<string, "EpochId">;
+export declare const EpochId: Brand.Constructor<EpochId>;
+export type DatabaseName = Brand.Branded<string, "DatabaseName">;
+export declare const DatabaseName: Brand.Constructor<DatabaseName>;

package/dist/crud/collection-handle.d.ts

@@ -1,21 +1,21 @@
-import { Effect, Stream } from "effect";
+import { Effect, Option, Stream } from "effect";
 import type { CollectionDef, CollectionFields } from "../schema/collection.ts";
 import type { InferRecord } from "../schema/types.ts";
 import type { RecordValidator, PartialValidator } from "../schema/validate.ts";
 import type { IDBStorageHandle, StoredEvent } from "../storage/idb.ts";
 import { NotFoundError, StorageError, ValidationError } from "../errors.ts";
 import type { WatchContext } from "./watch.ts";
-import type { WhereClause, OrderByBuilder } from "./query-builder.ts";
+import type { WhereClause, QueryBuilder } from "./query-builder.ts";
 export interface CollectionHandle<C extends CollectionDef<CollectionFields>> {
     readonly add: (data: Omit<InferRecord<C>, "id">) => Effect.Effect<string, ValidationError | StorageError>;
     readonly update: (id: string, data: Partial<Omit<InferRecord<C>, "id">>) => Effect.Effect<void, ValidationError | StorageError | NotFoundError>;
     readonly delete: (id: string) => Effect.Effect<void, StorageError | NotFoundError>;
     readonly get: (id: string) => Effect.Effect<InferRecord<C>, StorageError | NotFoundError>;
-    readonly first: () => Effect.Effect<InferRecord<C> | null, StorageError>;
+    readonly first: () => Effect.Effect<Option.Option<InferRecord<C>>, StorageError>;
     readonly count: () => Effect.Effect<number, StorageError>;
     readonly watch: () => Stream.Stream<ReadonlyArray<InferRecord<C>>, StorageError>;
     readonly where: (field: string & keyof Omit<InferRecord<C>, "id">) => WhereClause<InferRecord<C>>;
-    readonly orderBy: (field: string & keyof Omit<InferRecord<C>, "id">) => OrderByBuilder<InferRecord<C>>;
+    readonly orderBy: (field: string & keyof Omit<InferRecord<C>, "id">) => QueryBuilder<InferRecord<C>>;
 }
-export type OnWriteCallback = (event: StoredEvent) => Effect.Effect<void>;
+export type OnWriteCallback = (event: StoredEvent) => Effect.Effect<void, StorageError>;
 export declare function createCollectionHandle<C extends CollectionDef<CollectionFields>>(def: C, storage: IDBStorageHandle, watchCtx: WatchContext, validator: RecordValidator<C["fields"]>, partialValidator: PartialValidator<C["fields"]>, makeEventId: () => string, onWrite?: OnWriteCallback): CollectionHandle<C>;

package/dist/crud/query-builder.d.ts

@@ -1,4 +1,4 @@
-import { Effect, Stream } from "effect";
+import { Effect, Option, Stream } from "effect";
 import type { IDBStorageHandle } from "../storage/idb.ts";
 import type { StorageError, ValidationError } from "../errors.ts";
 import type { CollectionDef, CollectionFields } from "../schema/collection.ts";
@@ -24,19 +24,10 @@ export interface QueryBuilder<T> {
     readonly offset: (n: number) => QueryBuilder<T>;
     readonly limit: (n: number) => QueryBuilder<T>;
     readonly get: () => Effect.Effect<ReadonlyArray<T>, StorageError | ValidationError>;
-    readonly first: () => Effect.Effect<T | null, StorageError | ValidationError>;
+    readonly first: () => Effect.Effect<Option.Option<T>, StorageError | ValidationError>;
     readonly count: () => Effect.Effect<number, StorageError | ValidationError>;
     readonly watch: () => Stream.Stream<ReadonlyArray<T>, StorageError | ValidationError>;
 }
-export interface OrderByBuilder<T> {
-    readonly reverse: () => OrderByBuilder<T>;
-    readonly offset: (n: number) => OrderByBuilder<T>;
-    readonly limit: (n: number) => OrderByBuilder<T>;
-    readonly get: () => Effect.Effect<ReadonlyArray<T>, StorageError | ValidationError>;
-    readonly first: () => Effect.Effect<T | null, StorageError | ValidationError>;
-    readonly count: () => Effect.Effect<number, StorageError | ValidationError>;
-    readonly watch: () => Stream.Stream<ReadonlyArray<T>, StorageError | ValidationError>;
-}
-export type QueryExecutor<T> = QueryBuilder<T>;
+export type OrderByBuilder<T> = QueryBuilder<T>;
 export declare function createWhereClause<T>(storage: IDBStorageHandle, watchCtx: WatchContext, collectionName: string, def: CollectionDef<CollectionFields>, fieldName: string, mapRecord: (record: Record<string, unknown>) => T): WhereClause<T>;
-export declare function createOrderByBuilder<T>(storage: IDBStorageHandle, watchCtx: WatchContext, collectionName: string, def: CollectionDef<CollectionFields>, fieldName: string, mapRecord: (record: Record<string, unknown>) => T): OrderByBuilder<T>;
+export declare function createOrderByBuilder<T>(storage: IDBStorageHandle, watchCtx: WatchContext, collectionName: string, def: CollectionDef<CollectionFields>, fieldName: string, mapRecord: (record: Record<string, unknown>) => T): QueryBuilder<T>;

package/dist/crud/watch.d.ts

@@ -10,16 +10,6 @@ export interface WatchContext {
     readonly pubsub: PubSub.PubSub<ChangeEvent>;
     readonly replayingRef: Ref.Ref<boolean>;
 }
-/**
- * Create a reactive Stream that emits the current result set whenever it changes.
- */
 export declare function watchCollection<T>(ctx: WatchContext, storage: IDBStorageHandle, collectionName: string, filter?: (record: Record<string, unknown>) => boolean, mapRecord?: (record: Record<string, unknown>) => T): Stream.Stream<ReadonlyArray<T>, StorageError>;
-/**
- * Notify subscribers of a change.
- */
 export declare function notifyChange(ctx: WatchContext, event: ChangeEvent): Effect.Effect<void>;
-/**
- * Emit a replay-complete notification for all collections that changed.
- * Call after sync replay to trigger batched watch updates.
- */
 export declare function notifyReplayComplete(ctx: WatchContext, collections: ReadonlyArray<string>): Effect.Effect<void>;

package/dist/db/create-tablinum.d.ts

@@ -1,12 +1,19 @@
 import { Effect, Scope } from "effect";
 import type { SchemaConfig } from "../schema/types.ts";
 import type { DatabaseHandle } from "./database-handle.ts";
+import type { EpochKeyInput } from "./epoch.ts";
 import { CryptoError, StorageError, ValidationError } from "../errors.ts";
 export interface TablinumConfig<S extends SchemaConfig> {
     readonly schema: S;
     readonly relays: readonly string[];
     readonly privateKey?: Uint8Array | undefined;
+    readonly epochKeys?: ReadonlyArray<EpochKeyInput> | undefined;
     readonly dbName?: string | undefined;
     readonly onSyncError?: ((error: Error) => void) | undefined;
+    readonly onRemoved?: ((info: {
+        epochId: string;
+        removedBy: string;
+    }) => void) | undefined;
+    readonly onMembersChanged?: (() => void) | undefined;
 }
 export declare function createTablinum<S extends SchemaConfig>(config: TablinumConfig<S>): Effect.Effect<DatabaseHandle<S>, ValidationError | StorageError | CryptoError, Scope.Scope>;

package/dist/db/database-handle.d.ts

@@ -1,13 +1,34 @@
 import type { Effect } from "effect";
+import type { CollectionDef, CollectionFields } from "../schema/collection.ts";
 import type { CollectionHandle } from "../crud/collection-handle.ts";
 import type { SchemaConfig } from "../schema/types.ts";
-import type { StorageError, SyncError, RelayError, CryptoError } from "../errors.ts";
+import type { StorageError, SyncError, RelayError, CryptoError, ValidationError } from "../errors.ts";
+import type { Invite } from "./invite.ts";
+import type { MemberRecord } from "./members.ts";
+import type { RelayStatus } from "../sync/relay.ts";
 export type SyncStatus = "idle" | "syncing";
 export interface DatabaseHandle<S extends SchemaConfig> {
     readonly collection: <K extends string & keyof S>(name: K) => CollectionHandle<S[K]>;
+    readonly publicKey: string;
+    readonly members: CollectionHandle<CollectionDef<CollectionFields>>;
     readonly exportKey: () => string;
+    readonly exportInvite: () => Invite;
     readonly close: () => Effect.Effect<void, StorageError>;
     readonly rebuild: () => Effect.Effect<void, StorageError>;
     readonly sync: () => Effect.Effect<void, SyncError | RelayError | CryptoError | StorageError>;
     readonly getSyncStatus: () => Effect.Effect<SyncStatus>;
+    readonly subscribeSyncStatus: (callback: (status: SyncStatus) => void) => () => void;
+    readonly pendingCount: () => Effect.Effect<number>;
+    readonly subscribePendingCount: (callback: (count: number) => void) => () => void;
+    readonly getRelayStatus: () => RelayStatus;
+    readonly subscribeRelayStatus: (callback: (status: RelayStatus) => void) => () => void;
+    readonly addMember: (pubkey: string) => Effect.Effect<void, ValidationError | StorageError | CryptoError>;
+    readonly removeMember: (pubkey: string) => Effect.Effect<void, ValidationError | StorageError | SyncError | RelayError | CryptoError>;
+    readonly getMembers: () => Effect.Effect<ReadonlyArray<MemberRecord>, StorageError>;
+    readonly setProfile: (profile: {
+        name?: string;
+        picture?: string;
+        about?: string;
+        nip05?: string;
+    }) => Effect.Effect<void, ValidationError | StorageError | CryptoError>;
 }

package/dist/db/epoch.d.ts

@@ -0,0 +1,48 @@
+import { Option, Schema } from "effect";
+import { bytesToHex, hexToBytes } from "@noble/hashes/utils.js";
+import { EpochId, DatabaseName } from "../brands.ts";
+export { EpochId, DatabaseName };
+export { bytesToHex, hexToBytes };
+export interface EpochKeyInput {
+    readonly epochId: EpochId;
+    readonly key: string;
+}
+export interface EpochKey {
+    readonly id: EpochId;
+    readonly privateKey: string;
+    readonly publicKey: string;
+    readonly createdBy: string;
+    readonly parentEpoch?: EpochId;
+}
+export interface EpochStore {
+    readonly epochs: Map<EpochId, EpochKey>;
+    readonly keysByPublicKey: Map<string, Uint8Array>;
+    currentEpochId: EpochId;
+}
+export declare const EpochKeyInputSchema: Schema.Struct<{
+    readonly epochId: Schema.String;
+    readonly key: Schema.String;
+}>;
+interface EpochStoreSnapshot {
+    readonly epochs: ReadonlyArray<{
+        readonly id: string;
+        readonly privateKey: string;
+        readonly createdBy: string;
+        readonly parentEpoch?: string;
+    }>;
+    readonly currentEpochId: string;
+}
+export declare function createEpochKey(id: EpochId, privateKeyHex: string, createdBy: string, parentEpoch?: EpochId): EpochKey;
+export declare function createEpochStore(initialEpoch: EpochKey): EpochStore;
+export declare function addEpoch(store: EpochStore, epoch: EpochKey): void;
+export declare function hydrateEpochStore(snapshot: EpochStoreSnapshot): EpochStore;
+export declare function createEpochStoreFromInputs(epochKeys: ReadonlyArray<EpochKeyInput>, options?: {
+    readonly createdBy?: string | undefined;
+}): EpochStore;
+export declare function getCurrentEpoch(store: EpochStore): EpochKey;
+export declare function getCurrentPublicKey(store: EpochStore): string;
+export declare function getAllPublicKeys(store: EpochStore): string[];
+export declare function getDecryptionKey(store: EpochStore, publicKey: string): Uint8Array | undefined;
+export declare function exportEpochKeys(store: EpochStore): ReadonlyArray<EpochKeyInput>;
+export declare function stringifyEpochStore(store: EpochStore): string;
+export declare function deserializeEpochStore(raw: string): Option.Option<EpochStore>;

package/dist/db/invite.d.ts

@@ -0,0 +1,8 @@
+import { DatabaseName, type EpochKeyInput } from "./epoch.ts";
+export interface Invite {
+    readonly epochKeys: Array<EpochKeyInput>;
+    readonly relays: string[];
+    readonly dbName: DatabaseName;
+}
+export declare function encodeInvite(invite: Invite): string;
+export declare function decodeInvite(encoded: string): Invite;

package/dist/db/key-rotation.d.ts

@@ -0,0 +1,24 @@
+import { Option } from "effect";
+import type { NostrEvent } from "nostr-tools/pure";
+import type { EpochKey, EpochStore } from "./epoch.ts";
+import { EpochId } from "./epoch.ts";
+export interface RotationResult {
+    readonly epoch: EpochKey;
+    readonly wrappedEvents: NostrEvent[];
+    readonly removalNotices: NostrEvent[];
+}
+export interface RotationData {
+    readonly _rotation: true;
+    readonly epochId: EpochId;
+    readonly epochKey: string;
+    readonly parentEpoch: EpochId;
+    readonly removedMembers: readonly string[];
+}
+export interface RemovalNotice {
+    readonly _removed: true;
+    readonly epochId: EpochId;
+    readonly removedBy: string;
+}
+export declare function createRotation(epochStore: EpochStore, senderPrivateKey: Uint8Array, senderPublicKey: string, remainingMemberPubkeys: string[], removedMemberPubkeys: string[]): RotationResult;
+export declare function parseRotationEvent(content: string, dTag: string): Option.Option<RotationData>;
+export declare function parseRemovalNotice(content: string, dTag: string): Option.Option<RemovalNotice>;

package/dist/db/members.d.ts

@@ -0,0 +1,24 @@
+import { Effect, Option } from "effect";
+import type { CollectionDef } from "../schema/collection.ts";
+import type { RelayHandle } from "../sync/relay.ts";
+import { RelayError } from "../errors.ts";
+import type { EpochId } from "../brands.ts";
+export interface MemberRecord {
+    readonly id: string;
+    readonly name?: string;
+    readonly picture?: string;
+    readonly about?: string;
+    readonly nip05?: string;
+    readonly addedAt: number;
+    readonly addedInEpoch: EpochId;
+    readonly removedAt?: number;
+    readonly removedInEpoch?: EpochId;
+}
+export interface AuthorProfile {
+    readonly name?: string;
+    readonly picture?: string;
+    readonly about?: string;
+    readonly nip05?: string;
+}
+export declare const membersCollectionDef: CollectionDef;
+export declare function fetchAuthorProfile(relay: RelayHandle, relayUrls: readonly string[], pubkey: string): Effect.Effect<Option.Option<AuthorProfile>, RelayError>;

package/dist/db/runtime-config.d.ts

@@ -0,0 +1,16 @@
+import { Effect } from "effect";
+import { ValidationError } from "../errors.ts";
+import { type EpochKeyInput, DatabaseName } from "./epoch.ts";
+export interface RuntimeConfigSource {
+    readonly relays: readonly string[];
+    readonly privateKey?: Uint8Array | undefined;
+    readonly epochKeys?: ReadonlyArray<EpochKeyInput> | undefined;
+    readonly dbName?: string | undefined;
+}
+export interface ResolvedRuntimeConfig {
+    readonly relays: readonly string[];
+    readonly privateKey?: Uint8Array | undefined;
+    readonly epochKeys?: ReadonlyArray<EpochKeyInput> | undefined;
+    readonly dbName: DatabaseName;
+}
+export declare function resolveRuntimeConfig(source: RuntimeConfigSource): Effect.Effect<ResolvedRuntimeConfig, ValidationError>;

package/dist/index.d.ts

@@ -6,7 +6,14 @@ export type { InferRecord, SchemaConfig } from "./schema/types.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 { encodeInvite, decodeInvite } from "./db/invite.ts";
+export type { Invite } from "./db/invite.ts";
+export { EpochId, DatabaseName } from "./brands.ts";
+export type { EpochKey, EpochKeyInput } from "./db/epoch.ts";
+export type { MemberRecord } from "./db/members.ts";
 export type { CollectionHandle } from "./crud/collection-handle.ts";
 export type { CollectionOptions } from "./schema/collection.ts";
-export type { WhereClause, QueryBuilder, OrderByBuilder, QueryExecutor, } from "./crud/query-builder.ts";
+export type { WhereClause, QueryBuilder, OrderByBuilder } from "./crud/query-builder.ts";
+export { TablinumLive } from "./layers/TablinumLive.ts";
+export type { TablinumConfigShape } from "./services/Config.ts";
 export { ValidationError, StorageError, CryptoError, RelayError, SyncError, NotFoundError, ClosedError, } from "./errors.ts";