tablinum 0.2.0 → 0.5.0

package/README.md

@@ -1,30 +1,39 @@
 # tablinum
 
-A local-first storage library for the browser. Define typed collections, read and write data locally via IndexedDB, and sync across devices through Nostr relays.
-
-Built on [Effect](https://effect.website) and [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API).
+A local-first database for the browser with encrypted sync and built-in collaboration.
 
 ## Features
 
-- **Typed schema** — define collections with `collection()` and `field.*()` builders, get full TypeScript inference
-- **Local-first** — all reads hit IndexedDB, no network required
-- **Cross-device sync** — replicate data via Nostr relays using NIP-59 gift wrapping for privacy
-- **Efficient reconciliation** — NIP-77 negentropy for minimal sync overhead
-- **Dexie-style queries** — chainable `.where()`, `.above()`, `.below()`, `.orderBy()` API
-- **Svelte 5 bindings** — optional reactive runes integration
+### Local first
 
-## How it works
+Your app works offline. All data lives on your device in the browser.
 
-Tablinum stores all data locally in IndexedDB so your app works offline and reads are instant. When you call `sync()`, it replicates data to [Nostr](https://nostr.com) relays so your other devices can pick it up. All data sent to relays is encrypted using [NIP-59 gift wrapping](https://github.com/nostr-protocol/nips/blob/master/59.md) — relays never see your application data. Sync uses [NIP-77 negentropy](https://github.com/nostr-protocol/nips/blob/master/77.md) to efficiently reconcile what each side has, minimizing bandwidth.
+### Backed up and encrypted
 
-## Getting started
+Data syncs to relays so it's safe across devices. Everything stored on relays is end-to-end encrypted - relay operators cannot read your data.
 
-### Pick a relay
+### Identity and collaboration built in
 
-Tablinum syncs through Nostr relays, which must support [NIP-77 (Negentropy)](https://github.com/nostr-protocol/nips/blob/master/77.md). You have two options:
+Tablinum has a built-in system for sharing a database with other people, and for removing access when needed.
 
-- **Use a public relay** — find NIP-77 compatible relays at [nostrwat.ch](https://nostrwat.ch)
-- **Self-host a relay** — [strfry](https://github.com/hoytech/strfry) is a good choice if you want full control over where your users' data is stored
+Every database has a shared secret key. When you invite someone, they get a copy of the key so they can read and write data. If someone leaves or is removed, a new key is created and shared with everyone _except_ the removed person — like changing the locks when a roommate moves out. Old data is still available to the removed person but they will not get anything new.
+
+Invites are just links. Share one, and the other person has everything they need to join.
+
+### Typed collections and queries
+
+Define your data shape once with `collection()` and `field.*()` builders, and get full TypeScript inference everywhere. Query with a chainable API:
+
+```typescript
+const pending = await todos.where("done").equals(false).get();
+const recent = await todos.orderBy("createdAt").get();
+```
+
+### Svelte 5 bindings
+
+Optional reactive integration using Svelte 5 async runes. No Effect knowledge needed — the API is plain async/await.
+
+## Getting started
 
 ### Install
 
@@ -32,7 +41,7 @@ Tablinum syncs through Nostr relays, which must support [NIP-77 (Negentropy)](ht
 npm install tablinum
 ```
 
-### Quick start
+### Quick start (Effect)
 
 ```typescript
 import { Effect } from "effect";
@@ -72,11 +81,9 @@ 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.
+### Quick start (Svelte 5)
 
-This API uses Svelte's async runes support, so enable it in your app config:
+Import from `tablinum/svelte` for reactive bindings. This API uses Svelte's async runes support, so enable it in your app config:
 
 ```js
 // svelte.config.js
@@ -89,9 +96,7 @@ const config = {
 };
 ```
 
-### Setup
-
-Create a database helper that defines your schema and initializes the database:
+Create a database helper:
 
 ```typescript
 // src/lib/db.ts
@@ -118,9 +123,7 @@ export const db = new Tablinum({
 export const todos = db.collection("todos");
 ```
 
-### Component
-
-Async collection reads are reactive when used inside `$derived(await ...)` expressions.
+Use it in a component:
 
 ```svelte
 <script lang="ts">
@@ -188,13 +191,108 @@ Async collection reads are reactive when used inside `$derived(await ...)` expre
 </svelte:boundary>
 ```
 
-### Key concepts
+#### Key concepts
 
 - **`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
 
+## Logging
+
+Tablinum uses [Effect's built-in logging](https://effect.website/docs/observability/logging/) under the hood. By default, logging is completely silent. Set `logLevel` in your config to enable it:
+
+```typescript
+const db = yield* createTablinum({
+  schema,
+  relays: ["wss://relay.example.com"],
+  logLevel: "debug", // "debug" | "info" | "warning" | "error" | "none"
+});
+```
+
+Wire it to an environment variable for easy toggling:
+
+```typescript
+// Effect API
+createTablinum({
+  schema,
+  relays: ["wss://relay.example.com"],
+  logLevel: import.meta.env.VITE_LOG_LEVEL ?? "none",
+});
+
+// Svelte API
+new Tablinum({
+  schema,
+  relays: ["wss://relay.example.com"],
+  logLevel: import.meta.env.VITE_LOG_LEVEL ?? "none",
+});
+```
+
+### Log levels
+
+| Level | What you see |
+|-------|-------------|
+| `"none"` | Nothing (default) |
+| `"error"` | Unrecoverable failures |
+| `"warning"` | Recoverable issues (e.g. rejected writes from removed members) |
+| `"info"` | Lifecycle milestones — storage opened, identity loaded, sync started/complete |
+| `"debug"` | Everything above plus CRUD operations (with record data), relay reconciliation details, gift wrap processing |
+
+### Log spans
+
+Key operations include timing spans that appear automatically in log output:
+
+```
+[11:50:31] INFO (#1) tablinum.init=13ms: Tablinum ready { ... }
+[11:50:41] INFO (#1) tablinum.sync=520ms: Sync complete { changed: ["todos"] }
+```
+
+Spans: `tablinum.init`, `tablinum.sync`, `tablinum.syncRelay`, `tablinum.negentropy`.
+
+### Using Effect's LogLevel type
+
+Power users can also pass Effect's `LogLevel` type directly:
+
+```typescript
+import { LogLevel } from "tablinum";
+createTablinum({ ..., logLevel: LogLevel.Debug });
+```
+
+## How it works
+
+Tablinum is built on [Effect](https://effect.website) and stores all data locally in [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API).
+
+Sync happens through [Nostr](https://nostr.com) relays. All data sent to relays is encrypted using [NIP-59 gift wrapping](https://github.com/nostr-protocol/nips/blob/master/59.md). Relays never see your application data. Sync uses [NIP-77 negentropy](https://github.com/nostr-protocol/nips/blob/master/77.md) to efficiently reconcile what each side has, minimizing bandwidth usage.
+
+### Picking a relay
+
+Tablinum syncs through Nostr relays that support [NIP-77 (Negentropy)](https://github.com/nostr-protocol/nips/blob/master/77.md). You have two options:
+
+- **Use a public relay** — find NIP-77 compatible relays at [nostrwat.ch](https://nostrwat.ch)
+- **Self-host a relay** — [strfry](https://github.com/hoytech/strfry) is a good choice if you want full control over where your users' data is stored
+
+## Development
+
+### Local relays
+
+To run the example app or integration tests against local relays, spin up three [strfry](https://github.com/hoytech/strfry) instances with Docker:
+
+```bash
+bun run relays        # starts 3 relays on ports 7984, 7985, 7986
+bun run relays:down   # stop relays (data is preserved)
+bun run relays:clean  # stop relays and delete all data
+```
+
+The first run builds strfry from source, which takes a few minutes. Subsequent starts are instant.
+
+Then point your app at the local relays:
+
+```typescript
+relays: ["ws://localhost:7984", "ws://localhost:7985", "ws://localhost:7986"]
+```
+
+The Svelte example app (`bun run demo:svelte`) is pre-configured to use these local relays.
+
 ## License
 
 MIT

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

@@ -1,4 +1,5 @@
 import { Effect, Option, Stream } from "effect";
+import type { LogLevel } 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";
@@ -6,10 +7,12 @@ import type { IDBStorageHandle, StoredEvent } from "../storage/idb.ts";
 import { NotFoundError, StorageError, ValidationError } from "../errors.ts";
 import type { WatchContext } from "./watch.ts";
 import type { WhereClause, QueryBuilder } from "./query-builder.ts";
+export declare function pruneEvents(storage: IDBStorageHandle, collection: string, recordId: string, retention: number): Effect.Effect<void, StorageError>;
 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 undo: (id: string) => Effect.Effect<void, StorageError | NotFoundError>;
     readonly get: (id: string) => Effect.Effect<InferRecord<C>, StorageError | NotFoundError>;
     readonly first: () => Effect.Effect<Option.Option<InferRecord<C>>, StorageError>;
     readonly count: () => Effect.Effect<number, StorageError>;
@@ -18,4 +21,4 @@ export interface CollectionHandle<C extends CollectionDef<CollectionFields>> {
     readonly orderBy: (field: string & keyof Omit<InferRecord<C>, "id">) => QueryBuilder<InferRecord<C>>;
 }
 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>;
+export declare function createCollectionHandle<C extends CollectionDef<CollectionFields>>(def: C, storage: IDBStorageHandle, watchCtx: WatchContext, validator: RecordValidator<C["fields"]>, partialValidator: PartialValidator<C["fields"]>, makeEventId: () => string, localAuthor?: string, onWrite?: OnWriteCallback, logLevel?: LogLevel.LogLevel): CollectionHandle<C>;

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

@@ -1,14 +1,18 @@
 import { Effect, Scope } from "effect";
+import type { LogLevel } 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 type TablinumLogLevel = "debug" | "info" | "warning" | "error" | "none" | LogLevel.LogLevel;
+export declare function resolveLogLevel(input: TablinumLogLevel | undefined): LogLevel.LogLevel;
 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 logLevel?: TablinumLogLevel | undefined;
     readonly onSyncError?: ((error: Error) => void) | undefined;
     readonly onRemoved?: ((info: {
         epochId: string;

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

@@ -4,7 +4,7 @@ import type { CollectionHandle } from "../crud/collection-handle.ts";
 import type { SchemaConfig } from "../schema/types.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 { MemberRecord, AuthorProfile } from "./members.ts";
 import type { RelayStatus } from "../sync/relay.ts";
 export type SyncStatus = "idle" | "syncing";
 export interface DatabaseHandle<S extends SchemaConfig> {
@@ -25,6 +25,7 @@ export interface DatabaseHandle<S extends SchemaConfig> {
     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 getProfile: () => Effect.Effect<AuthorProfile, StorageError>;
     readonly setProfile: (profile: {
         name?: string;
         picture?: string;

package/dist/index.d.ts

@@ -4,13 +4,14 @@ 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 { createTablinum } from "./db/create-tablinum.ts";
-export type { TablinumConfig } from "./db/create-tablinum.ts";
+export type { TablinumConfig, TablinumLogLevel } from "./db/create-tablinum.ts";
+export { LogLevel } from "effect";
 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 { MemberRecord, AuthorProfile } from "./db/members.ts";
 export type { CollectionHandle } from "./crud/collection-handle.ts";
 export type { CollectionOptions } from "./schema/collection.ts";
 export type { WhereClause, QueryBuilder, OrderByBuilder } from "./crud/query-builder.ts";