tablinum 0.0.1

package/src/db/database-handle.ts

@@ -0,0 +1,16 @@
+import type { Effect, Stream } from "effect";
+import type { CollectionDef, CollectionFields } from "../schema/collection.ts";
+import type { CollectionHandle } from "../crud/collection-handle.ts";
+import type { InferRecord, SchemaConfig } from "../schema/types.ts";
+import type { ClosedError, 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/src/db/identity.ts

@@ -0,0 +1,49 @@
+import { Effect } from "effect";
+import { getPublicKey } from "nostr-tools/pure";
+import { CryptoError } from "../errors.ts";
+
+export interface Identity {
+  readonly privateKey: Uint8Array;
+  readonly publicKey: string;
+  readonly exportKey: () => string;
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+export function createIdentity(suppliedKey?: Uint8Array): Effect.Effect<Identity, CryptoError> {
+  return Effect.gen(function* () {
+    let privateKey: Uint8Array;
+
+    if (suppliedKey) {
+      if (suppliedKey.length !== 32) {
+        return yield* new CryptoError({
+          message: `Private key must be 32 bytes, got ${suppliedKey.length}`,
+        });
+      }
+      privateKey = suppliedKey;
+    } else {
+      privateKey = new Uint8Array(32);
+      crypto.getRandomValues(privateKey);
+    }
+
+    const privateKeyHex = bytesToHex(privateKey);
+
+    let publicKey: string;
+    try {
+      publicKey = getPublicKey(privateKey);
+    } catch (e) {
+      return yield* new CryptoError({
+        message: `Failed to derive public key: ${e instanceof Error ? e.message : String(e)}`,
+        cause: e,
+      });
+    }
+
+    return {
+      privateKey,
+      publicKey,
+      exportKey: () => privateKeyHex,
+    };
+  });
+}

package/src/errors.ts

@@ -0,0 +1,37 @@
+import { Data } from "effect";
+
+export class ValidationError extends Data.TaggedError("ValidationError")<{
+  readonly message: string;
+  readonly field?: string | undefined;
+}> {}
+
+export class StorageError extends Data.TaggedError("StorageError")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+export class CryptoError extends Data.TaggedError("CryptoError")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+export class RelayError extends Data.TaggedError("RelayError")<{
+  readonly message: string;
+  readonly url?: string | undefined;
+  readonly cause?: unknown;
+}> {}
+
+export class SyncError extends Data.TaggedError("SyncError")<{
+  readonly message: string;
+  readonly phase?: string | undefined;
+  readonly cause?: unknown;
+}> {}
+
+export class NotFoundError extends Data.TaggedError("NotFoundError")<{
+  readonly collection: string;
+  readonly id: string;
+}> {}
+
+export class ClosedError extends Data.TaggedError("ClosedError")<{
+  readonly message: string;
+}> {}

package/src/index.ts

@@ -0,0 +1,32 @@
+// 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 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";

package/src/main.ts

@@ -0,0 +1,10 @@
+import { Console, Effect } from "effect";
+
+const program = Effect.gen(function* () {
+  yield* Console.log("douala-v4 is running");
+  return 42;
+});
+
+Effect.runPromise(program).then((result) => {
+  console.log(`Result: ${result}`);
+});

package/src/schema/collection.ts

@@ -0,0 +1,53 @@
+import type { FieldDef } from "./field.ts";
+
+export type CollectionFields = Record<string, FieldDef<unknown>>;
+
+export interface CollectionDef<out F extends CollectionFields = CollectionFields> {
+  readonly _tag: "CollectionDef";
+  readonly name: string;
+  readonly fields: F;
+  readonly indices: ReadonlyArray<string>;
+}
+
+export interface CollectionOptions<F extends CollectionFields> {
+  readonly indices?: ReadonlyArray<string & keyof F>;
+}
+
+const RESERVED_NAMES = new Set(["id", "_deleted", "_createdAt", "_updatedAt"]);
+
+export function collection<F extends CollectionFields>(
+  name: string,
+  fields: F,
+  options?: CollectionOptions<F>,
+): CollectionDef<F> {
+  if (!name || name.trim().length === 0) {
+    throw new Error("Collection name must not be empty");
+  }
+  const fieldNames = Object.keys(fields);
+  if (fieldNames.length === 0) {
+    throw new Error(`Collection "${name}" must have at least one field`);
+  }
+  for (const fieldName of fieldNames) {
+    if (RESERVED_NAMES.has(fieldName)) {
+      throw new Error(`Field name "${fieldName}" is reserved`);
+    }
+  }
+
+  const indices: string[] = [];
+  if (options?.indices) {
+    for (const idx of options.indices) {
+      const fieldDef = fields[idx];
+      if (!fieldDef) {
+        throw new Error(`Index field "${idx}" does not exist in collection "${name}"`);
+      }
+      if (fieldDef.kind === "json" || fieldDef.isArray) {
+        throw new Error(
+          `Field "${idx}" cannot be indexed (type: ${fieldDef.kind}${fieldDef.isArray ? "[]" : ""})`,
+        );
+      }
+      indices.push(idx);
+    }
+  }
+
+  return { _tag: "CollectionDef" as const, name, fields, indices };
+}

package/src/schema/field.ts

@@ -0,0 +1,25 @@
+export type FieldKind = "string" | "number" | "boolean" | "json";
+
+export interface FieldDef<out T = unknown> {
+  readonly _tag: "FieldDef";
+  readonly kind: FieldKind;
+  readonly isOptional: boolean;
+  readonly isArray: boolean;
+  /** Phantom type carrier — never read at runtime. */
+  readonly _T?: T;
+}
+
+function make<T>(kind: FieldKind, isOptional: boolean, isArray: boolean): FieldDef<T> {
+  return { _tag: "FieldDef", kind, isOptional, isArray };
+}
+
+export const field = {
+  string: () => make<string>("string", false, false),
+  number: () => make<number>("number", false, false),
+  boolean: () => make<boolean>("boolean", false, false),
+  json: () => make<unknown>("json", false, false),
+  optional: <T>(inner: FieldDef<T>): FieldDef<T | undefined> =>
+    make(inner.kind, true, inner.isArray),
+  array: <T>(inner: FieldDef<T>): FieldDef<ReadonlyArray<T>> =>
+    make(inner.kind, inner.isOptional, true),
+};

package/src/schema/types.ts

@@ -0,0 +1,19 @@
+import type { CollectionDef, CollectionFields } from "./collection.ts";
+import type { FieldDef } from "./field.ts";
+
+/** Extract the TypeScript type from a FieldDef phantom. */
+export type InferFieldType<F> = F extends FieldDef<infer T> ? T : never;
+
+/** Infer the full record type from a CollectionDef, including the auto-injected `id`. */
+export type InferRecord<C> =
+  C extends CollectionDef<infer F>
+    ? { readonly id: string } & {
+        readonly [K in keyof F]: InferFieldType<F[K]>;
+      }
+    : never;
+
+/** A schema configuration mapping collection names to their definitions. */
+export type SchemaConfig = Record<string, CollectionDef<CollectionFields>>;
+
+/** Extract indexed field names from a CollectionDef. */
+export type IndexedFields<C> = C extends CollectionDef<infer _F> ? C["indices"][number] : never;

package/src/schema/validate.ts

@@ -0,0 +1,111 @@
+import { Effect, Schema } from "effect";
+import type { CollectionDef, CollectionFields } from "./collection.ts";
+import type { FieldDef } from "./field.ts";
+import { ValidationError } from "../errors.ts";
+
+function fieldDefToSchema(fd: FieldDef): Schema.Schema<unknown> {
+  let base: Schema.Schema<unknown>;
+  switch (fd.kind) {
+    case "string":
+      base = Schema.String as Schema.Schema<unknown>;
+      break;
+    case "number":
+      base = Schema.Number as Schema.Schema<unknown>;
+      break;
+    case "boolean":
+      base = Schema.Boolean as Schema.Schema<unknown>;
+      break;
+    case "json":
+      base = Schema.Unknown;
+      break;
+  }
+
+  if (fd.isArray) {
+    base = Schema.Array(base) as Schema.Schema<unknown>;
+  }
+  if (fd.isOptional) {
+    base = Schema.UndefinedOr(base) as Schema.Schema<unknown>;
+  }
+
+  return base;
+}
+
+export type RecordValidator<F extends CollectionFields> = (
+  input: unknown,
+) => Effect.Effect<{ readonly id: string } & { readonly [K in keyof F]: unknown }, ValidationError>;
+
+export function buildValidator<F extends CollectionFields>(
+  collectionName: string,
+  def: CollectionDef<F>,
+): RecordValidator<F> {
+  const schemaFields: Record<string, Schema.Schema<unknown>> = {
+    id: Schema.String as Schema.Schema<unknown>,
+  };
+  for (const [name, fieldDef] of Object.entries(def.fields)) {
+    schemaFields[name] = fieldDefToSchema(fieldDef);
+  }
+
+  const recordSchema = Schema.Struct(
+    schemaFields as {
+      [K: string]: Schema.Schema<unknown>;
+    },
+  );
+
+  const decode = Schema.decodeUnknownSync(recordSchema);
+
+  return (input: unknown) =>
+    Effect.gen(function* () {
+      try {
+        const result = decode(input);
+        return result as { readonly id: string } & {
+          readonly [K in keyof F]: unknown;
+        };
+      } catch (e) {
+        return yield* new ValidationError({
+          message: `Validation failed for collection "${collectionName}": ${e instanceof Error ? e.message : String(e)}`,
+        });
+      }
+    });
+}
+
+export type PartialValidator<F extends CollectionFields> = (
+  input: unknown,
+) => Effect.Effect<{ readonly [K in keyof F]?: unknown }, ValidationError>;
+
+export function buildPartialValidator<F extends CollectionFields>(
+  collectionName: string,
+  def: CollectionDef<F>,
+): PartialValidator<F> {
+  return (input: unknown) =>
+    Effect.gen(function* () {
+      if (typeof input !== "object" || input === null) {
+        return yield* new ValidationError({
+          message: `Validation failed for collection "${collectionName}": expected an object`,
+        });
+      }
+      const record = input as Record<string, unknown>;
+      for (const [key, value] of Object.entries(record)) {
+        const fieldDef = def.fields[key];
+        if (!fieldDef) {
+          return yield* new ValidationError({
+            message: `Unknown field "${key}" in collection "${collectionName}"`,
+            field: key,
+          });
+        }
+        if (value === undefined && fieldDef.isOptional) {
+          continue;
+        }
+        const fieldSchema = fieldDefToSchema(fieldDef);
+        const decode = Schema.decodeUnknownSync(fieldSchema);
+        try {
+          decode(value);
+        } catch (e) {
+          return yield* new ValidationError({
+            message: `Validation failed for field "${key}" in collection "${collectionName}": ${e instanceof Error ? e.message : String(e)}`,
+            field: key,
+          });
+        }
+      }
+      return record as { readonly [K in keyof F]?: unknown };
+    });
+}

package/src/storage/events-store.ts

@@ -0,0 +1,24 @@
+import { Effect } from "effect";
+import type { IDBStorageHandle, StoredEvent } from "./idb.ts";
+import type { StorageError } from "../errors.ts";
+
+export function putEvent(
+  storage: IDBStorageHandle,
+  event: StoredEvent,
+): Effect.Effect<void, StorageError> {
+  return storage.putEvent(event);
+}
+
+export function getEventsByRecord(
+  storage: IDBStorageHandle,
+  collection: string,
+  recordId: string,
+): Effect.Effect<ReadonlyArray<StoredEvent>, StorageError> {
+  return storage.getEventsByRecord(collection, recordId);
+}
+
+export function getAllEvents(
+  storage: IDBStorageHandle,
+): Effect.Effect<ReadonlyArray<StoredEvent>, StorageError> {
+  return storage.getAllEvents();
+}

package/src/storage/giftwraps-store.ts

@@ -0,0 +1,23 @@
+import { Effect } from "effect";
+import type { IDBStorageHandle, StoredGiftWrap } from "./idb.ts";
+import type { StorageError } from "../errors.ts";
+
+export function putGiftWrap(
+  storage: IDBStorageHandle,
+  gw: StoredGiftWrap,
+): Effect.Effect<void, StorageError> {
+  return storage.putGiftWrap(gw);
+}
+
+export function getGiftWrap(
+  storage: IDBStorageHandle,
+  id: string,
+): Effect.Effect<StoredGiftWrap | undefined, StorageError> {
+  return storage.getGiftWrap(id);
+}
+
+export function getAllGiftWraps(
+  storage: IDBStorageHandle,
+): Effect.Effect<ReadonlyArray<StoredGiftWrap>, StorageError> {
+  return storage.getAllGiftWraps();
+}

package/src/storage/idb.ts

@@ -0,0 +1,244 @@
+import { Effect, Scope } from "effect";
+import { openDB, type IDBPDatabase } from "idb";
+import { StorageError } from "../errors.ts";
+import type { SchemaConfig } from "../schema/types.ts";
+
+export interface StoredEvent {
+  readonly id: string;
+  readonly collection: string;
+  readonly recordId: string;
+  readonly kind: "create" | "update" | "delete";
+  readonly data: Record<string, unknown> | null;
+  readonly createdAt: number;
+}
+
+export interface StoredGiftWrap {
+  readonly id: string;
+  readonly event: Record<string, unknown>;
+  readonly createdAt: number;
+}
+
+export interface IDBStorageHandle {
+  // Records — per-collection stores with flat shape
+  readonly putRecord: (
+    collection: string,
+    record: Record<string, unknown>,
+  ) => Effect.Effect<void, StorageError>;
+  readonly getRecord: (
+    collection: string,
+    id: string,
+  ) => Effect.Effect<Record<string, unknown> | undefined, StorageError>;
+  readonly getAllRecords: (
+    collection: string,
+  ) => Effect.Effect<ReadonlyArray<Record<string, unknown>>, StorageError>;
+  readonly countRecords: (collection: string) => Effect.Effect<number, StorageError>;
+  readonly clearRecords: (collection: string) => Effect.Effect<void, StorageError>;
+
+  // Index-based queries
+  readonly getByIndex: (
+    collection: string,
+    indexName: string,
+    value: IDBValidKey,
+  ) => Effect.Effect<ReadonlyArray<Record<string, unknown>>, StorageError>;
+  readonly getByIndexRange: (
+    collection: string,
+    indexName: string,
+    range: IDBKeyRange,
+  ) => Effect.Effect<ReadonlyArray<Record<string, unknown>>, StorageError>;
+  readonly getAllSorted: (
+    collection: string,
+    indexName: string,
+    direction?: "next" | "prev",
+  ) => Effect.Effect<ReadonlyArray<Record<string, unknown>>, StorageError>;
+
+  // Events
+  readonly putEvent: (event: StoredEvent) => Effect.Effect<void, StorageError>;
+  readonly getEvent: (id: string) => Effect.Effect<StoredEvent | undefined, StorageError>;
+  readonly getAllEvents: () => Effect.Effect<ReadonlyArray<StoredEvent>, StorageError>;
+  readonly getEventsByRecord: (
+    collection: string,
+    recordId: string,
+  ) => Effect.Effect<ReadonlyArray<StoredEvent>, StorageError>;
+
+  // Gift wraps
+  readonly putGiftWrap: (gw: StoredGiftWrap) => Effect.Effect<void, StorageError>;
+  readonly getGiftWrap: (id: string) => Effect.Effect<StoredGiftWrap | undefined, StorageError>;
+  readonly getAllGiftWraps: () => Effect.Effect<ReadonlyArray<StoredGiftWrap>, StorageError>;
+
+  readonly close: () => Effect.Effect<void>;
+}
+
+const DB_NAME = "localstr";
+
+function storeName(collection: string): string {
+  return `col_${collection}`;
+}
+
+function schemaVersion(schema: SchemaConfig): number {
+  const sig = Object.entries(schema)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([name, def]) => {
+      const indices = [...(def.indices ?? [])].sort().join(",");
+      return `${name}:${indices}`;
+    })
+    .join("|");
+  let hash = 1;
+  for (let i = 0; i < sig.length; i++) {
+    hash = (hash * 31 + sig.charCodeAt(i)) | 0;
+  }
+  return Math.abs(hash) + 1;
+}
+
+function wrap<T>(label: string, fn: () => Promise<T>): Effect.Effect<T, StorageError> {
+  return Effect.tryPromise({
+    try: fn,
+    catch: (e) =>
+      new StorageError({
+        message: `IndexedDB ${label} failed: ${e instanceof Error ? e.message : String(e)}`,
+        cause: e,
+      }),
+  });
+}
+
+export function openIDBStorage(
+  dbName: string | undefined,
+  schema: SchemaConfig,
+): Effect.Effect<IDBStorageHandle, StorageError, Scope.Scope> {
+  return Effect.gen(function* () {
+    const name = dbName ?? DB_NAME;
+    const version = schemaVersion(schema);
+
+    const db: IDBPDatabase = yield* Effect.tryPromise({
+      try: () =>
+        openDB(name, version, {
+          upgrade(database) {
+            // Create events store if missing
+            if (!database.objectStoreNames.contains("events")) {
+              const events = database.createObjectStore("events", {
+                keyPath: "id",
+              });
+              events.createIndex("by-record", ["collection", "recordId"]);
+            }
+
+            // Create giftwraps store if missing
+            if (!database.objectStoreNames.contains("giftwraps")) {
+              database.createObjectStore("giftwraps", {
+                keyPath: "id",
+              });
+            }
+
+            // Remove old shared records store if it exists
+            if (database.objectStoreNames.contains("records")) {
+              database.deleteObjectStore("records");
+            }
+
+            // Determine which collection stores should exist
+            const expectedStores = new Set<string>();
+            for (const [, def] of Object.entries(schema)) {
+              const sn = storeName(def.name);
+              expectedStores.add(sn);
+
+              if (!database.objectStoreNames.contains(sn)) {
+                // Create new collection store
+                const store = database.createObjectStore(sn, { keyPath: "id" });
+                for (const idx of def.indices ?? []) {
+                  store.createIndex(idx, idx);
+                }
+              } else {
+                // Update indices on existing store
+                const tx = (database as any).transaction;
+                // During upgrade, we can access stores via transaction
+                // The idb library handles this through the upgrade callback
+                const store = (tx as IDBTransaction).objectStore(sn);
+                const existingIndices = new Set(Array.from(store.indexNames));
+                const wantedIndices = new Set(def.indices ?? []);
+
+                // Remove stale indices
+                for (const idx of existingIndices) {
+                  if (!wantedIndices.has(idx)) {
+                    store.deleteIndex(idx);
+                  }
+                }
+                // Add new indices
+                for (const idx of wantedIndices) {
+                  if (!existingIndices.has(idx as string)) {
+                    store.createIndex(idx as string, idx as string);
+                  }
+                }
+              }
+            }
+
+            // Remove collection stores no longer in schema
+            const allStores = Array.from(database.objectStoreNames);
+            for (const existing of allStores) {
+              if (existing.startsWith("col_") && !expectedStores.has(existing)) {
+                database.deleteObjectStore(existing);
+              }
+            }
+          },
+        }),
+      catch: (e) =>
+        new StorageError({
+          message: "Failed to open IndexedDB",
+          cause: e,
+        }),
+    });
+
+    yield* Effect.addFinalizer(() => Effect.sync(() => db.close()));
+
+    const handle: IDBStorageHandle = {
+      putRecord: (collection, record) =>
+        wrap("putRecord", () => db.put(storeName(collection), record).then(() => undefined)),
+
+      getRecord: (collection, id) => wrap("getRecord", () => db.get(storeName(collection), id)),
+
+      getAllRecords: (collection) => wrap("getAllRecords", () => db.getAll(storeName(collection))),
+
+      countRecords: (collection) => wrap("countRecords", () => db.count(storeName(collection))),
+
+      clearRecords: (collection) => wrap("clearRecords", () => db.clear(storeName(collection))),
+
+      getByIndex: (collection, indexName, value) =>
+        wrap("getByIndex", () => db.getAllFromIndex(storeName(collection), indexName, value)),
+
+      getByIndexRange: (collection, indexName, range) =>
+        wrap("getByIndexRange", () => db.getAllFromIndex(storeName(collection), indexName, range)),
+
+      getAllSorted: (collection, indexName, direction) =>
+        wrap("getAllSorted", async () => {
+          const sn = storeName(collection);
+          const tx = db.transaction(sn, "readonly");
+          const store = tx.objectStore(sn);
+          const index = store.index(indexName);
+          const results: Record<string, unknown>[] = [];
+          let cursor = await index.openCursor(null, direction ?? "next");
+          while (cursor) {
+            results.push(cursor.value as Record<string, unknown>);
+            cursor = await cursor.continue();
+          }
+          return results;
+        }),
+
+      putEvent: (event) => wrap("putEvent", () => db.put("events", event).then(() => undefined)),
+
+      getEvent: (id) => wrap("getEvent", () => db.get("events", id)),
+
+      getAllEvents: () => wrap("getAllEvents", () => db.getAll("events")),
+
+      getEventsByRecord: (collection, recordId) =>
+        wrap("getEventsByRecord", () =>
+          db.getAllFromIndex("events", "by-record", [collection, recordId]),
+        ),
+
+      putGiftWrap: (gw) => wrap("putGiftWrap", () => db.put("giftwraps", gw).then(() => undefined)),
+
+      getGiftWrap: (id) => wrap("getGiftWrap", () => db.get("giftwraps", id)),
+
+      getAllGiftWraps: () => wrap("getAllGiftWraps", () => db.getAll("giftwraps")),
+
+      close: () => Effect.sync(() => db.close()),
+    };
+
+    return handle;
+  });
+}

package/src/storage/lww.ts

@@ -0,0 +1,17 @@
+export interface EventMeta {
+  readonly id: string;
+  readonly createdAt: number;
+}
+
+/**
+ * Last-write-wins resolution.
+ * Higher `createdAt` wins. Ties broken by lowest event ID (lexicographic).
+ * Returns the winner.
+ */
+export function resolveWinner<T extends EventMeta>(existing: T | null, incoming: T): T {
+  if (existing === null) return incoming;
+  if (incoming.createdAt > existing.createdAt) return incoming;
+  if (incoming.createdAt < existing.createdAt) return existing;
+  // Tie: lowest event ID wins
+  return incoming.id < existing.id ? incoming : existing;
+}