@bod.ee/db 0.7.0

package/src/client/BodClient.ts

@@ -0,0 +1,515 @@
+import type { QueryFilter, OrderClause, BatchOp } from '../shared/protocol.ts';
+import { pathKey } from '../shared/pathUtils.ts';
+
+export class BodClientOptions {
+  url: string = 'ws://localhost:4400';
+  auth?: () => string | Promise<string>;
+  reconnect: boolean = true;
+  reconnectInterval: number = 1000;
+  maxReconnectInterval: number = 30000;
+}
+
+type PendingRequest = {
+  resolve: (data: unknown) => void;
+  reject: (err: Error) => void;
+};
+
+export class BodClient {
+  readonly options: BodClientOptions;
+  private ws: WebSocket | null = null;
+  private msgId = 0;
+  private pending = new Map<string, PendingRequest>();
+  private valueCbs = new Map<string, Set<(snap: ValueSnapshot) => void>>();
+  private childCbs = new Map<string, Set<(event: ChildEvent) => void>>();
+  private activeSubs = new Set<string>(); // tracks 'value:path' and 'child:path' keys
+  private streamCbs = new Map<string, Set<(events: Array<{ key: string; data: unknown }>) => void>>();
+  private activeStreamSubs = new Set<string>(); // tracks 'path:groupId' keys
+  private closed = false;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private reconnectDelay: number;
+  private connectPromise: Promise<void> | null = null;
+
+  constructor(options?: Partial<BodClientOptions>) {
+    this.options = { ...new BodClientOptions(), ...options };
+    this.reconnectDelay = this.options.reconnectInterval;
+  }
+
+  async connect(): Promise<void> {
+    if (this.ws?.readyState === WebSocket.OPEN) return;
+    if (this.connectPromise) return this.connectPromise;
+
+    this.closed = false;
+    this.connectPromise = new Promise<void>((resolve, reject) => {
+      const ws = new WebSocket(this.options.url);
+
+      ws.onopen = async () => {
+        this.ws = ws;
+        this.reconnectDelay = this.options.reconnectInterval;
+
+        try {
+          // Auth if configured
+          if (this.options.auth) {
+            const token = await this.options.auth();
+            await this.send('auth', { token });
+          }
+          // Re-subscribe all active subscriptions
+          for (const key of this.activeSubs) {
+            const [event, ...pathParts] = key.split(':');
+            const path = pathParts.join(':');
+            await this.send('sub', { path, event });
+          }
+          // Re-subscribe stream subs
+          for (const key of this.activeStreamSubs) {
+            const [path, groupId] = this.splitStreamKey(key);
+            await this.send('stream-sub', { path, groupId });
+          }
+          this.connectPromise = null;
+          resolve();
+        } catch (e) {
+          this.connectPromise = null;
+          reject(e);
+        }
+      };
+
+      ws.onmessage = (e: MessageEvent) => {
+        const msg = JSON.parse(typeof e.data === 'string' ? e.data : e.data.toString());
+
+        // Push message (subscription)
+        if (msg.type === 'value') {
+          const cbs = this.valueCbs.get(msg.path);
+          if (cbs) {
+            const snap = new ValueSnapshot(msg.path, msg.data);
+            for (const cb of cbs) cb(snap);
+          }
+          return;
+        }
+        if (msg.type === 'stream') {
+          const streamKey = `${msg.path}:${msg.groupId}`;
+          const cbs = this.streamCbs.get(streamKey);
+          if (cbs) {
+            for (const cb of cbs) cb(msg.events);
+          }
+          return;
+        }
+        if (msg.type === 'child') {
+          const cbs = this.childCbs.get(msg.path);
+          if (cbs) {
+            const event: ChildEvent = {
+              type: msg.event,
+              key: msg.key,
+              path: msg.path + '/' + msg.key,
+              val: () => msg.data,
+            };
+            for (const cb of cbs) cb(event);
+          }
+          return;
+        }
+
+        // Response message
+        const p = this.pending.get(msg.id);
+        if (p) {
+          this.pending.delete(msg.id);
+          if (msg.ok) p.resolve(msg.data ?? null);
+          else p.reject(new Error(msg.error || 'Unknown error'));
+        }
+      };
+
+      ws.onclose = () => {
+        this.ws = null;
+        // Reject all pending requests
+        for (const [, p] of this.pending) {
+          p.reject(new Error('Connection closed'));
+        }
+        this.pending.clear();
+
+        if (!this.closed && this.options.reconnect) {
+          this.scheduleReconnect();
+        }
+
+        if (!this.connectPromise) return;
+        this.connectPromise = null;
+        // Only reject if this was the initial connect
+      };
+
+      ws.onerror = () => {
+        // onclose will fire after this
+      };
+    });
+
+    return this.connectPromise;
+  }
+
+  disconnect() {
+    this.closed = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    this.ws?.close();
+    this.ws = null;
+    this.pending.clear();
+  }
+
+  private scheduleReconnect() {
+    if (this.closed) return;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect().catch(() => {
+        // Exponential backoff
+        this.reconnectDelay = Math.min(this.reconnectDelay * 2, this.options.maxReconnectInterval);
+      });
+    }, this.reconnectDelay);
+  }
+
+  private nextId(): string {
+    return String(++this.msgId);
+  }
+
+  private send(op: string, params: Record<string, unknown> = {}): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        return reject(new Error('Not connected'));
+      }
+      const id = this.nextId();
+      this.pending.set(id, { resolve, reject });
+      this.ws.send(JSON.stringify({ id, op, ...params }));
+    });
+  }
+
+  // CRUD
+
+  async get(path: string): Promise<unknown> {
+    return this.send('get', { path });
+  }
+
+  async getShallow(path?: string): Promise<Array<{ key: string; isLeaf: boolean; value?: unknown }>> {
+    return this.send('get', { path: path ?? '', shallow: true }) as Promise<Array<{ key: string; isLeaf: boolean; value?: unknown }>>;
+  }
+
+  async set(path: string, value: unknown, opts?: { ttl?: number }): Promise<void> {
+    await this.send('set', { path, value, ttl: opts?.ttl });
+  }
+
+  async update(updates: Record<string, unknown>): Promise<void> {
+    await this.send('update', { updates });
+  }
+
+  async delete(path: string): Promise<void> {
+    await this.send('delete', { path });
+  }
+
+  async batch(operations: BatchOp[]): Promise<unknown> {
+    return this.send('batch', { operations });
+  }
+
+  async push(path: string, value: unknown, opts?: { idempotencyKey?: string }): Promise<string> {
+    return this.send('push', { path, value, idempotencyKey: opts?.idempotencyKey }) as Promise<string>;
+  }
+
+  // Query
+
+  query(path: string): ClientQueryBuilder {
+    return new ClientQueryBuilder(this, path);
+  }
+
+  /** @internal — used by ClientQueryBuilder */
+  _query(path: string, filters?: QueryFilter[], order?: OrderClause, limit?: number, offset?: number): Promise<unknown> {
+    return this.send('query', { path, filters, order, limit, offset });
+  }
+
+  // Subscriptions
+
+  on(path: string, cb: (snap: ValueSnapshot) => void): () => void {
+    const subKey = `value:${path}`;
+
+    if (!this.valueCbs.has(path)) this.valueCbs.set(path, new Set());
+    this.valueCbs.get(path)!.add(cb);
+
+    // Subscribe on server if first listener for this path
+    if (!this.activeSubs.has(subKey)) {
+      this.activeSubs.add(subKey);
+      if (this.ws?.readyState === WebSocket.OPEN) {
+        this.send('sub', { path, event: 'value' }).catch(() => {});
+      }
+    }
+
+    return () => {
+      this.valueCbs.get(path)?.delete(cb);
+      if (this.valueCbs.get(path)?.size === 0) {
+        this.valueCbs.delete(path);
+        this.activeSubs.delete(subKey);
+        if (this.ws?.readyState === WebSocket.OPEN) {
+          this.send('unsub', { path, event: 'value' }).catch(() => {});
+        }
+      }
+    };
+  }
+
+  onChild(path: string, cb: (event: ChildEvent) => void): () => void {
+    const subKey = `child:${path}`;
+
+    if (!this.childCbs.has(path)) this.childCbs.set(path, new Set());
+    this.childCbs.get(path)!.add(cb);
+
+    if (!this.activeSubs.has(subKey)) {
+      this.activeSubs.add(subKey);
+      if (this.ws?.readyState === WebSocket.OPEN) {
+        this.send('sub', { path, event: 'child' }).catch(() => {});
+      }
+    }
+
+    return () => {
+      this.childCbs.get(path)?.delete(cb);
+      if (this.childCbs.get(path)?.size === 0) {
+        this.childCbs.delete(path);
+        this.activeSubs.delete(subKey);
+        if (this.ws?.readyState === WebSocket.OPEN) {
+          this.send('unsub', { path, event: 'child' }).catch(() => {});
+        }
+      }
+    };
+  }
+
+  // MQ
+
+  mq(queue: string): MQReader {
+    return new MQReader(this, queue);
+  }
+
+  /** @internal */
+  _mqSend(op: string, params: Record<string, unknown>): Promise<unknown> {
+    return this.send(op, params);
+  }
+
+  // Streams
+
+  stream(path: string, groupId: string): StreamReader {
+    return new StreamReader(this, path, groupId);
+  }
+
+  /** @internal */
+  _streamOn(path: string, groupId: string, cb: (events: Array<{ key: string; data: unknown }>) => void): () => void {
+    const streamKey = `${path}:${groupId}`;
+    if (!this.streamCbs.has(streamKey)) this.streamCbs.set(streamKey, new Set());
+    this.streamCbs.get(streamKey)!.add(cb);
+
+    if (!this.activeStreamSubs.has(streamKey)) {
+      this.activeStreamSubs.add(streamKey);
+      if (this.ws?.readyState === WebSocket.OPEN) {
+        this.send('stream-sub', { path, groupId }).catch(() => {});
+      }
+    }
+
+    return () => {
+      this.streamCbs.get(streamKey)?.delete(cb);
+      if (this.streamCbs.get(streamKey)?.size === 0) {
+        this.streamCbs.delete(streamKey);
+        this.activeStreamSubs.delete(streamKey);
+        if (this.ws?.readyState === WebSocket.OPEN) {
+          this.send('stream-unsub', { path, groupId }).catch(() => {});
+        }
+      }
+    };
+  }
+
+  /** @internal */
+  _streamRead(path: string, groupId: string, limit?: number): Promise<unknown> {
+    return this.send('stream-read', { path, groupId, limit });
+  }
+
+  /** @internal */
+  _streamAck(path: string, groupId: string, key: string): Promise<void> {
+    return this.send('stream-ack', { path, groupId, key }) as Promise<void>;
+  }
+
+  private splitStreamKey(key: string): [string, string] {
+    const lastColon = key.lastIndexOf(':');
+    return [key.slice(0, lastColon), key.slice(lastColon + 1)];
+  }
+
+  // FTS
+
+  async search(opts: { text: string; path?: string; limit?: number }): Promise<Array<{ path: string; data: unknown; rank: number }>> {
+    return this.send('fts-search', opts) as Promise<Array<{ path: string; data: unknown; rank: number }>>;
+  }
+
+  async index(path: string, content: string): Promise<void>;
+  async index(path: string, fields: string[]): Promise<void>;
+  async index(path: string, contentOrFields: string | string[]): Promise<void> {
+    const params: Record<string, unknown> = { path };
+    if (Array.isArray(contentOrFields)) params.fields = contentOrFields;
+    else params.content = contentOrFields;
+    await this.send('fts-index', params);
+  }
+
+  // Vectors
+
+  async vectorSearch(opts: { query: number[]; path?: string; limit?: number; threshold?: number }): Promise<Array<{ path: string; data: unknown; score: number }>> {
+    return this.send('vector-search', opts) as Promise<Array<{ path: string; data: unknown; score: number }>>;
+  }
+
+  async vectorStore(path: string, embedding: number[]): Promise<void> {
+    await this.send('vector-store', { path, embedding });
+  }
+
+  // Stream extended
+
+  async streamSnapshot(path: string): Promise<unknown> {
+    return this.send('stream-snapshot', { path });
+  }
+
+  async streamMaterialize(path: string, opts?: { keepKey?: string }): Promise<Record<string, unknown>> {
+    return this.send('stream-materialize', { path, keepKey: opts?.keepKey }) as Promise<Record<string, unknown>>;
+  }
+
+  async streamCompact(path: string, opts?: { maxAge?: number; maxCount?: number; keepKey?: string }): Promise<unknown> {
+    return this.send('stream-compact', { path, ...opts });
+  }
+
+  async streamReset(path: string): Promise<void> {
+    await this.send('stream-reset', { path });
+  }
+
+  get connected(): boolean {
+    return this.ws?.readyState === WebSocket.OPEN;
+  }
+}
+
+export class ValueSnapshot {
+  constructor(
+    readonly path: string,
+    private data: unknown,
+  ) {}
+
+  val(): unknown { return this.data; }
+  get key(): string { return pathKey(this.path); }
+  exists(): boolean { return this.data !== null && this.data !== undefined; }
+}
+
+export interface ChildEvent {
+  type: 'added' | 'changed' | 'removed';
+  key: string;
+  path: string;
+  val: () => unknown;
+}
+
+export interface StreamEventSnapshot {
+  key: string;
+  val: () => unknown;
+}
+
+export class StreamReader {
+  constructor(
+    private client: BodClient,
+    private path: string,
+    private groupId: string,
+  ) {}
+
+  on(cb: (events: StreamEventSnapshot[]) => void): () => void {
+    return this.client._streamOn(this.path, this.groupId, (events) => {
+      cb(events.map(e => ({ key: e.key, val: () => e.data })));
+    });
+  }
+
+  async read(limit?: number): Promise<StreamEventSnapshot[]> {
+    const events = await this.client._streamRead(this.path, this.groupId, limit) as Array<{ key: string; data: unknown }>;
+    return events.map(e => ({ key: e.key, val: () => e.data }));
+  }
+
+  async ack(key: string): Promise<void> {
+    return this.client._streamAck(this.path, this.groupId, key);
+  }
+}
+
+export class ClientQueryBuilder {
+  private filters: QueryFilter[] = [];
+  private orderClause?: OrderClause;
+  private limitVal?: number;
+  private offsetVal?: number;
+
+  constructor(
+    private client: BodClient,
+    private basePath: string,
+  ) {}
+
+  where(field: string, op: QueryFilter['op'], value: unknown): ClientQueryBuilder {
+    this.filters.push({ field, op, value });
+    return this;
+  }
+
+  order(field: string, dir: 'asc' | 'desc' = 'asc'): ClientQueryBuilder {
+    this.orderClause = { field, dir };
+    return this;
+  }
+
+  limit(n: number): ClientQueryBuilder {
+    this.limitVal = n;
+    return this;
+  }
+
+  offset(n: number): ClientQueryBuilder {
+    this.offsetVal = n;
+    return this;
+  }
+
+  get(): Promise<unknown> {
+    return this.client._query(
+      this.basePath,
+      this.filters.length ? this.filters : undefined,
+      this.orderClause,
+      this.limitVal,
+      this.offsetVal,
+    );
+  }
+}
+
+export class MQMessageSnapshot {
+  constructor(
+    readonly key: string,
+    readonly path: string,
+    readonly deliveryCount: number,
+    readonly status: 'pending' | 'inflight' | 'dead',
+    private data: unknown,
+  ) {}
+
+  val(): unknown { return this.data; }
+  exists(): boolean { return this.data !== null && this.data !== undefined; }
+}
+
+export class MQReader {
+  constructor(
+    private client: BodClient,
+    private queue: string,
+  ) {}
+
+  async push(value: unknown, opts?: { idempotencyKey?: string }): Promise<string> {
+    return this.client._mqSend('mq-push', { path: this.queue, value, idempotencyKey: opts?.idempotencyKey }) as Promise<string>;
+  }
+
+  async fetch(count?: number): Promise<MQMessageSnapshot[]> {
+    const msgs = await this.client._mqSend('mq-fetch', { path: this.queue, count }) as Array<{ key: string; path: string; data: unknown; deliveryCount: number }>;
+    return msgs.map(m => new MQMessageSnapshot(m.key, m.path, m.deliveryCount, m.status, m.data));
+  }
+
+  async ack(key: string): Promise<void> {
+    await this.client._mqSend('mq-ack', { path: this.queue, key });
+  }
+
+  async nack(key: string): Promise<void> {
+    await this.client._mqSend('mq-nack', { path: this.queue, key });
+  }
+
+  async peek(count?: number): Promise<MQMessageSnapshot[]> {
+    const msgs = await this.client._mqSend('mq-peek', { path: this.queue, count }) as Array<{ key: string; path: string; data: unknown; deliveryCount: number }>;
+    return msgs.map(m => new MQMessageSnapshot(m.key, m.path, m.deliveryCount, m.status, m.data));
+  }
+
+  async dlq(): Promise<MQMessageSnapshot[]> {
+    const msgs = await this.client._mqSend('mq-dlq', { path: this.queue }) as Array<{ key: string; path: string; data: unknown; deliveryCount: number }>;
+    return msgs.map(m => new MQMessageSnapshot(m.key, m.path, m.deliveryCount, m.status, m.data));
+  }
+
+  async purge(opts?: { all?: boolean }): Promise<number> {
+    return this.client._mqSend('mq-purge', { path: this.queue, all: opts?.all }) as Promise<number>;
+  }
+}

package/src/react/hooks.ts

@@ -0,0 +1,121 @@
+/**
+ * React hooks for BodDB.
+ * Requires React 18+ as a peer dependency.
+ */
+import { useState, useEffect, useRef, useCallback, useMemo } from 'react';
+import type { BodClient, ValueSnapshot, ChildEvent } from '../client/BodClient.ts';
+import type { QueryFilter, OrderClause } from '../shared/protocol.ts';
+
+/** Subscribe to a value at a path. Returns current value (null while loading). */
+export function useValue(client: BodClient, path: string): { data: unknown; loading: boolean } {
+  const [data, setData] = useState<unknown>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    let mounted = true;
+
+    // Initial fetch
+    client.get(path).then((val) => {
+      if (mounted) { setData(val); setLoading(false); }
+    }).catch(() => {
+      if (mounted) setLoading(false);
+    });
+
+    // Subscribe
+    const off = client.on(path, (snap: ValueSnapshot) => {
+      if (mounted) { setData(snap.val()); setLoading(false); }
+    });
+
+    return () => { mounted = false; off(); };
+  }, [client, path]);
+
+  return { data, loading };
+}
+
+/** Subscribe to child events at a path. Returns map of key → value. */
+export function useChildren(client: BodClient, path: string): {
+  children: Map<string, unknown>;
+  loading: boolean;
+} {
+  const [children, setChildren] = useState<Map<string, unknown>>(new Map());
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    let mounted = true;
+
+    // Initial fetch
+    client.get(path).then((val) => {
+      if (!mounted) return;
+      if (val && typeof val === 'object' && !Array.isArray(val)) {
+        setChildren(new Map(Object.entries(val as Record<string, unknown>)));
+      }
+      setLoading(false);
+    }).catch(() => {
+      if (mounted) setLoading(false);
+    });
+
+    // Subscribe to child events
+    const off = client.onChild(path, (event: ChildEvent) => {
+      if (!mounted) return;
+      setChildren((prev) => {
+        const next = new Map(prev);
+        if (event.type === 'removed') {
+          next.delete(event.key);
+        } else {
+          next.set(event.key, event.val());
+        }
+        return next;
+      });
+    });
+
+    return () => { mounted = false; off(); };
+  }, [client, path]);
+
+  return { children, loading };
+}
+
+/** Execute a query. Re-runs when deps change. */
+export function useQuery(
+  client: BodClient,
+  path: string,
+  build?: (q: { where: (f: string, op: string, v: unknown) => any; order: (f: string, d?: string) => any; limit: (n: number) => any; offset: (n: number) => any }) => any,
+  deps: unknown[] = [],
+): { data: unknown[]; loading: boolean } {
+  const [data, setData] = useState<unknown[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    let mounted = true;
+    setLoading(true);
+
+    let q = client.query(path);
+    if (build) q = build(q) ?? q;
+    q.get().then((result: unknown) => {
+      if (mounted) { setData(result as unknown[]); setLoading(false); }
+    }).catch(() => {
+      if (mounted) setLoading(false);
+    });
+
+    return () => { mounted = false; };
+  }, [client, path, ...deps]);
+
+  return { data, loading };
+}
+
+/** Mutation helpers bound to a client. */
+export function useMutation(client: BodClient) {
+  const set = useCallback(
+    (path: string, value: unknown) => client.set(path, value),
+    [client],
+  );
+  const update = useCallback(
+    (updates: Record<string, unknown>) => client.update(updates),
+    [client],
+  );
+  const del = useCallback(
+    (path: string) => client.delete(path),
+    [client],
+  );
+
+  return { set, update, delete: del };
+}