tablinum 0.0.1 → 0.1.1

package/README.md

@@ -1 +1,77 @@
-# localstr
+# 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).
+
+## 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
+
+## How it works
+
+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.
+
+## Getting started
+
+### Pick a relay
+
+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:
+
+- **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
+
+### Install
+
+```bash
+npm install tablinum
+```
+
+### Quick start
+
+```typescript
+import { Effect } from "effect";
+import { createTablinum, collection, field } from "tablinum";
+
+const schema = {
+  todos: collection("todos", {
+    title: field.string(),
+    done: field.boolean(),
+  }),
+};
+
+const program = Effect.gen(function* () {
+  const db = yield* createTablinum({
+    schema,
+    relays: ["wss://relay.example.com"],
+  });
+
+  const todos = db.collection("todos");
+
+  // Create
+  const id = yield* todos.add({ title: "Buy milk", done: false });
+
+  // Read
+  const todo = yield* todos.get(id);
+
+  // Query
+  const pending = yield* todos.where("done").equals(false).toArray();
+
+  // Update
+  yield* todos.update(id, { done: true });
+
+  // Sync across devices
+  yield* db.sync();
+});
+
+Effect.runPromise(Effect.scoped(program));
+```
+
+## License
+
+MIT

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

@@ -0,0 +1,21 @@
+import { Effect, 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";
+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 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>>;
+}
+export type OnWriteCallback = (event: StoredEvent) => Effect.Effect<void>;
+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

@@ -0,0 +1,42 @@
+import { Effect, 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";
+import type { WatchContext } from "./watch.ts";
+export interface WhereClause<T> {
+    readonly equals: (value: string | number | boolean) => QueryBuilder<T>;
+    readonly above: (value: number) => QueryBuilder<T>;
+    readonly aboveOrEqual: (value: number) => QueryBuilder<T>;
+    readonly below: (value: number) => QueryBuilder<T>;
+    readonly belowOrEqual: (value: number) => QueryBuilder<T>;
+    readonly between: (lower: number, upper: number, options?: {
+        includeLower?: boolean;
+        includeUpper?: boolean;
+    }) => QueryBuilder<T>;
+    readonly startsWith: (prefix: string) => QueryBuilder<T>;
+    readonly anyOf: (values: ReadonlyArray<string | number | boolean>) => QueryBuilder<T>;
+    readonly noneOf: (values: ReadonlyArray<string | number | boolean>) => QueryBuilder<T>;
+}
+export interface QueryBuilder<T> {
+    readonly and: (fn: (item: T) => boolean) => QueryBuilder<T>;
+    readonly sortBy: (field: string) => QueryBuilder<T>;
+    readonly reverse: () => 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 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 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>;

package/dist/crud/watch.d.ts

@@ -0,0 +1,25 @@
+import { Effect, PubSub, Ref, Stream } from "effect";
+import type { IDBStorageHandle } from "../storage/idb.ts";
+import type { StorageError } from "../errors.ts";
+export interface ChangeEvent {
+    readonly collection: string;
+    readonly recordId: string;
+    readonly kind: "create" | "update" | "delete";
+}
+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

@@ -0,0 +1,12 @@
+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 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 createTablinum<S extends SchemaConfig>(config: TablinumConfig<S>): Effect.Effect<DatabaseHandle<S>, ValidationError | StorageError | CryptoError, Scope.Scope>;

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

@@ -0,0 +1,13 @@
+import type { Effect } from "effect";
+import type { CollectionHandle } from "../crud/collection-handle.ts";
+import type { SchemaConfig } from "../schema/types.ts";
+import type { StorageError, SyncError, RelayError, CryptoError } from "../errors.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 exportKey: () => string;
+    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>;
+}

package/dist/db/identity.d.ts

@@ -0,0 +1,8 @@
+import { Effect } from "effect";
+import { CryptoError } from "../errors.ts";
+export interface Identity {
+    readonly privateKey: Uint8Array;
+    readonly publicKey: string;
+    readonly exportKey: () => string;
+}
+export declare function createIdentity(suppliedKey?: Uint8Array): Effect.Effect<Identity, CryptoError>;

package/dist/errors.d.ts

@@ -0,0 +1,58 @@
+declare const ValidationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ValidationError";
+} & Readonly<A>;
+export declare class ValidationError extends ValidationError_base<{
+    readonly message: string;
+    readonly field?: string | undefined;
+}> {
+}
+declare const StorageError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "StorageError";
+} & Readonly<A>;
+export declare class StorageError extends StorageError_base<{
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+}
+declare const CryptoError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "CryptoError";
+} & Readonly<A>;
+export declare class CryptoError extends CryptoError_base<{
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+}
+declare const RelayError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "RelayError";
+} & Readonly<A>;
+export declare class RelayError extends RelayError_base<{
+    readonly message: string;
+    readonly url?: string | undefined;
+    readonly cause?: unknown;
+}> {
+}
+declare const SyncError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "SyncError";
+} & Readonly<A>;
+export declare class SyncError extends SyncError_base<{
+    readonly message: string;
+    readonly phase?: string | undefined;
+    readonly cause?: unknown;
+}> {
+}
+declare const NotFoundError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "NotFoundError";
+} & Readonly<A>;
+export declare class NotFoundError extends NotFoundError_base<{
+    readonly collection: string;
+    readonly id: string;
+}> {
+}
+declare const ClosedError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ClosedError";
+} & Readonly<A>;
+export declare class ClosedError extends ClosedError_base<{
+    readonly message: string;
+}> {
+}
+export {};

package/{src/index.ts → dist/index.d.ts}

@@ -1,32 +1,12 @@
-// Schema
 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";
-
-// Database
-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";
-
-// CRUD
 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";
-
-// Errors
-export {
-  ValidationError,
-  StorageError,
-  CryptoError,
-  RelayError,
-  SyncError,
-  NotFoundError,
-  ClosedError,
-} from "./errors.ts";
+export type { WhereClause, QueryBuilder, OrderByBuilder, QueryExecutor, } from "./crud/query-builder.ts";
+export { ValidationError, StorageError, CryptoError, RelayError, SyncError, NotFoundError, ClosedError, } from "./errors.ts";