@bod.ee/db 0.7.0

package/src/shared/pathUtils.ts

@@ -0,0 +1,94 @@
+/** Normalize path: strip leading/trailing slashes, collapse double slashes */
+export function normalizePath(path: string): string {
+  return path.replace(/\/+/g, '/').replace(/^\/+|\/+$/g, '');
+}
+
+/** Validate path segments — no empty segments, no special chars */
+export function validatePath(path: string): string {
+  const normalized = normalizePath(path);
+  if (!normalized) throw new Error('Path cannot be empty');
+  if (/\/\//.test(normalized) || normalized.split('/').some(s => !s)) {
+    throw new Error(`Invalid path: "${path}"`);
+  }
+  return normalized;
+}
+
+/** Get all ancestor paths: 'a/b/c' → ['a/b', 'a'] */
+export function ancestors(path: string): string[] {
+  const parts = path.split('/');
+  const result: string[] = [];
+  for (let i = parts.length - 1; i > 0; i--) {
+    result.push(parts.slice(0, i).join('/'));
+  }
+  return result;
+}
+
+/** Get the parent path, or null for root-level */
+export function parentPath(path: string): string | null {
+  const idx = path.lastIndexOf('/');
+  return idx > 0 ? path.slice(0, idx) : null;
+}
+
+/** Get the key (last segment) of a path */
+export function pathKey(path: string): string {
+  const idx = path.lastIndexOf('/');
+  return idx >= 0 ? path.slice(idx + 1) : path;
+}
+
+/**
+ * Compute the exclusive upper bound for prefix scans.
+ * Appends high Unicode char instead of char increment — safe for all valid path chars.
+ */
+export function prefixEnd(prefix: string): string {
+  return prefix + '\uffff';
+}
+
+/** Flatten a nested object into leaf path→value pairs */
+export function flatten(basePath: string, value: unknown): Array<{ path: string; value: string }> {
+  const results: Array<{ path: string; value: string }> = [];
+
+  function walk(currentPath: string, val: unknown) {
+    if (val === null || val === undefined) return;
+    if (typeof val === 'object' && !Array.isArray(val)) {
+      const obj = val as Record<string, unknown>;
+      const keys = Object.keys(obj);
+      if (keys.length === 0) {
+        results.push({ path: currentPath, value: JSON.stringify(val) });
+        return;
+      }
+      for (const key of keys) {
+        walk(currentPath ? `${currentPath}/${key}` : key, obj[key]);
+      }
+    } else {
+      results.push({ path: currentPath, value: JSON.stringify(val) });
+    }
+  }
+
+  walk(basePath, value);
+  return results;
+}
+
+/** Reconstruct a nested object from leaf path→value rows */
+export function reconstruct(basePath: string, rows: Array<{ path: string; value: string }>): unknown {
+  if (rows.length === 0) return null;
+  if (rows.length === 1 && rows[0].path === basePath) {
+    return JSON.parse(rows[0].value);
+  }
+
+  const root: Record<string, unknown> = {};
+  for (const row of rows) {
+    // For empty basePath, use the full row.path; otherwise strip basePath + '/'
+    const relPath = basePath ? row.path.slice(basePath.length + 1) : row.path;
+    if (!relPath) continue;
+    const parts = relPath.split('/');
+    let current: Record<string, unknown> = root;
+    for (let i = 0; i < parts.length - 1; i++) {
+      if (!(parts[i] in current) || typeof current[parts[i]] !== 'object') {
+        current[parts[i]] = {};
+      }
+      current = current[parts[i]] as Record<string, unknown>;
+    }
+    current[parts[parts.length - 1]] = JSON.parse(row.value);
+  }
+  return root;
+}

package/src/shared/protocol.ts

@@ -0,0 +1,59 @@
+// Client → Server messages
+export type ClientMessage =
+  | { id: string; op: 'auth'; token: string }
+  | { id: string; op: 'get'; path: string; shallow?: boolean }
+  | { id: string; op: 'set'; path: string; value: unknown; ttl?: number }
+  | { id: string; op: 'update'; updates: Record<string, unknown> }
+  | { id: string; op: 'delete'; path: string }
+  | { id: string; op: 'query'; path: string; filters?: QueryFilter[]; order?: OrderClause; limit?: number; offset?: number }
+  | { id: string; op: 'sub'; path: string; event: SubEvent }
+  | { id: string; op: 'unsub'; path: string; event: SubEvent }
+  | { id: string; op: 'batch'; operations: BatchOp[] }
+  | { id: string; op: 'push'; path: string; value: unknown; idempotencyKey?: string }
+  | { id: string; op: 'stream-read';  path: string; groupId: string; limit?: number }
+  | { id: string; op: 'stream-ack';   path: string; groupId: string; key: string }
+  | { id: string; op: 'stream-sub';   path: string; groupId: string }
+  | { id: string; op: 'stream-unsub'; path: string; groupId: string }
+  | { id: string; op: 'mq-push';  path: string; value: unknown; idempotencyKey?: string }
+  | { id: string; op: 'mq-fetch'; path: string; count?: number }
+  | { id: string; op: 'mq-ack';   path: string; key: string }
+  | { id: string; op: 'mq-nack';  path: string; key: string }
+  | { id: string; op: 'mq-peek';  path: string; count?: number }
+  | { id: string; op: 'mq-dlq';   path: string }
+  | { id: string; op: 'mq-purge'; path: string; all?: boolean }
+  | { id: string; op: 'fts-search'; text: string; path?: string; limit?: number }
+  | { id: string; op: 'fts-index'; path: string; content?: string; fields?: string[] }
+  | { id: string; op: 'vector-search'; query: number[]; path?: string; limit?: number; threshold?: number }
+  | { id: string; op: 'vector-store'; path: string; embedding: number[] }
+  | { id: string; op: 'stream-snapshot'; path: string }
+  | { id: string; op: 'stream-materialize'; path: string; keepKey?: string }
+  | { id: string; op: 'stream-compact'; path: string; maxAge?: number; maxCount?: number; keepKey?: string }
+  | { id: string; op: 'stream-reset'; path: string };
+
+// Server → Client messages
+export type ServerMessage =
+  | { id: string; ok: true; data?: unknown }
+  | { id: string; ok: false; error: string; code: string }
+  | { type: 'value'; path: string; data: unknown }
+  | { type: 'child'; path: string; key: string; data: unknown; event: ChildEvent }
+  | { type: 'stream'; path: string; groupId: string; events: Array<{ key: string; data: unknown }> };
+
+export type SubEvent = 'value' | 'child';
+export type ChildEvent = 'added' | 'changed' | 'removed';
+
+export interface QueryFilter {
+  field: string;
+  op: '==' | '!=' | '<' | '<=' | '>' | '>=';
+  value: unknown;
+}
+
+export interface OrderClause {
+  field: string;
+  dir: 'asc' | 'desc';
+}
+
+export type BatchOp =
+  | { op: 'set'; path: string; value: unknown }
+  | { op: 'update'; updates: Record<string, unknown> }
+  | { op: 'delete'; path: string }
+  | { op: 'push'; path: string; value: unknown };

package/src/shared/transforms.ts

@@ -0,0 +1,99 @@
+/** Sentinel marker for transform operations */
+const SENTINEL = Symbol.for('bod-db:sentinel');
+
+export type SentinelType = 'increment' | 'serverTimestamp' | 'arrayUnion' | 'arrayRemove' | 'ref';
+
+interface SentinelBase {
+  [SENTINEL]: SentinelType;
+}
+
+export interface IncrementSentinel extends SentinelBase { delta: number }
+export interface ServerTimestampSentinel extends SentinelBase {}
+export interface ArrayUnionSentinel extends SentinelBase { items: unknown[] }
+export interface ArrayRemoveSentinel extends SentinelBase { items: unknown[] }
+export interface RefSentinel extends SentinelBase { path: string }
+
+export type Sentinel = IncrementSentinel | ServerTimestampSentinel | ArrayUnionSentinel | ArrayRemoveSentinel | RefSentinel;
+
+export function isSentinel(val: unknown): val is Sentinel {
+  return val !== null && typeof val === 'object' && SENTINEL in val;
+}
+
+export function sentinelType(val: Sentinel): SentinelType {
+  return val[SENTINEL];
+}
+
+// Factory functions
+export function increment(delta: number): IncrementSentinel {
+  return { [SENTINEL]: 'increment', delta };
+}
+
+export function serverTimestamp(): ServerTimestampSentinel {
+  return { [SENTINEL]: 'serverTimestamp' };
+}
+
+export function arrayUnion(...items: unknown[]): ArrayUnionSentinel {
+  return { [SENTINEL]: 'arrayUnion', items };
+}
+
+export function arrayRemove(...items: unknown[]): ArrayRemoveSentinel {
+  return { [SENTINEL]: 'arrayRemove', items };
+}
+
+export function ref(path: string): RefSentinel {
+  return { [SENTINEL]: 'ref', path };
+}
+
+/** Resolve sentinels in a value tree against current data */
+export function resolveTransforms(
+  value: unknown,
+  getCurrentValue: () => unknown,
+): unknown {
+  if (isSentinel(value)) {
+    return resolveSentinel(value, getCurrentValue());
+  }
+  if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+    const obj = value as Record<string, unknown>;
+    const current = getCurrentValue();
+    const currentObj = (current !== null && typeof current === 'object' && !Array.isArray(current))
+      ? current as Record<string, unknown>
+      : {};
+    const result: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(obj)) {
+      result[key] = resolveTransforms(val, () => currentObj[key] ?? null);
+    }
+    return result;
+  }
+  return value;
+}
+
+function resolveSentinel(sentinel: Sentinel, currentValue: unknown): unknown {
+  switch (sentinelType(sentinel)) {
+    case 'increment': {
+      const current = typeof currentValue === 'number' ? currentValue : 0;
+      return current + (sentinel as IncrementSentinel).delta;
+    }
+    case 'serverTimestamp':
+      return Date.now();
+    case 'arrayUnion': {
+      const current = Array.isArray(currentValue) ? currentValue : [];
+      const items = (sentinel as ArrayUnionSentinel).items;
+      const set = new Set(current.map(i => JSON.stringify(i)));
+      const result = [...current];
+      for (const item of items) {
+        if (!set.has(JSON.stringify(item))) result.push(item);
+      }
+      return result;
+    }
+    case 'arrayRemove': {
+      const current = Array.isArray(currentValue) ? currentValue : [];
+      const remove = new Set((sentinel as ArrayRemoveSentinel).items.map(i => JSON.stringify(i)));
+      return current.filter(i => !remove.has(JSON.stringify(i)));
+    }
+    case 'ref':
+      // Refs are stored as-is; resolved at read time
+      return { _ref: (sentinel as RefSentinel).path };
+    default:
+      return sentinel;
+  }
+}

package/tests/batch.test.ts

@@ -0,0 +1,60 @@
+import { describe, test, expect } from 'bun:test';
+import { BodDB } from '../src/server/BodDB.ts';
+
+describe('Transaction & Batch', () => {
+  test('transaction wraps multiple ops atomically', () => {
+    const db = new BodDB({ sweepInterval: 0 });
+    db.transaction((tx) => {
+      tx.set('a', 1);
+      tx.set('b', 2);
+      tx.set('c', 3);
+    });
+    expect(db.get('a')).toBe(1);
+    expect(db.get('b')).toBe(2);
+    expect(db.get('c')).toBe(3);
+    db.close();
+  });
+
+  test('transaction rolls back on error', () => {
+    const db = new BodDB({ sweepInterval: 0 });
+    db.set('x', 'original');
+    try {
+      db.transaction((tx) => {
+        tx.set('x', 'modified');
+        throw new Error('rollback');
+      });
+    } catch {}
+    expect(db.get('x')).toBe('original');
+    db.close();
+  });
+
+  test('transaction fires notifications after commit', () => {
+    const db = new BodDB({ sweepInterval: 0 });
+    const events: unknown[] = [];
+    db.on('a', (snap) => events.push(snap.val()));
+
+    db.transaction((tx) => {
+      tx.set('a', 'hello');
+    });
+    expect(events).toEqual(['hello']);
+    db.close();
+  });
+
+  test('transaction supports get/set/update/delete', () => {
+    const db = new BodDB({ sweepInterval: 0 });
+    db.set('item', { name: 'test', count: 1 });
+
+    db.transaction((tx) => {
+      const val = tx.get('item') as Record<string, unknown>;
+      tx.update({ 'item': { count: (val.count as number) + 1 } });
+    });
+    expect(db.get('item/count')).toBe(2);
+    expect(db.get('item/name')).toBe('test');
+
+    db.transaction((tx) => {
+      tx.delete('item/count');
+    });
+    expect(db.get('item/count')).toBeNull();
+    db.close();
+  });
+});

package/tests/bench.ts

@@ -0,0 +1,205 @@
+import { BodDB } from '../src/server/BodDB.ts';
+
+const SEED_COUNT = 1000;
+const OPS = 10000;
+const SUB_WRITES = 1000;
+const SUB_COUNT = 100;
+const ROLES = ['admin', 'user', 'editor', 'viewer'];
+
+interface Result {
+  name: string;
+  ops: number;
+  opsPerSec: number;
+  p50: number;
+  p99: number;
+  totalMs: number;
+}
+
+function percentile(sorted: number[], p: number): number {
+  const idx = Math.ceil((p / 100) * sorted.length) - 1;
+  return sorted[Math.max(0, idx)];
+}
+
+function fmt(n: number): string {
+  return n.toLocaleString('en-US', { maximumFractionDigits: 0 });
+}
+
+function fmtMs(n: number): string {
+  return n.toFixed(2);
+}
+
+async function seed(db: BodDB) {
+  for (let i = 0; i < SEED_COUNT; i++) {
+    db.set(`bench/item${i}`, {
+      i,
+      name: `item_${i}`,
+      score: Math.random() * 1000,
+      role: ROLES[Math.floor(Math.random() * ROLES.length)],
+    });
+  }
+}
+
+function randKey(): string {
+  return `bench/item${Math.floor(Math.random() * SEED_COUNT)}`;
+}
+
+function randRecord(i: number) {
+  return { i, name: `item_${i}`, score: Math.random() * 1000, role: ROLES[Math.floor(Math.random() * ROLES.length)] };
+}
+
+async function runWorkload(name: string, fn: (db: BodDB) => Promise<{ latencies: number[]; ops: number }>): Promise<Result> {
+  const db = new BodDB({ path: ':memory:' });
+  await seed(db);
+  const { latencies, ops } = await fn(db);
+  db.close();
+
+  latencies.sort((a, b) => a - b);
+  const totalMs = latencies.reduce((s, v) => s + v, 0);
+  return {
+    name,
+    ops,
+    opsPerSec: Math.round(ops / (totalMs / 1000)),
+    p50: percentile(latencies, 50),
+    p99: percentile(latencies, 99),
+    totalMs,
+  };
+}
+
+// Workload A: 50% read, 50% write
+async function workloadA(db: BodDB) {
+  const latencies: number[] = [];
+  for (let i = 0; i < OPS; i++) {
+    const t0 = performance.now();
+    if (Math.random() < 0.5) {
+      db.get(randKey());
+    } else {
+      db.set(randKey(), randRecord(SEED_COUNT + i));
+    }
+    latencies.push(performance.now() - t0);
+  }
+  return { latencies, ops: OPS };
+}
+
+// Workload B: 95% read, 5% write
+async function workloadB(db: BodDB) {
+  const latencies: number[] = [];
+  for (let i = 0; i < OPS; i++) {
+    const t0 = performance.now();
+    if (Math.random() < 0.95) {
+      db.get(randKey());
+    } else {
+      db.set(randKey(), randRecord(SEED_COUNT + i));
+    }
+    latencies.push(performance.now() - t0);
+  }
+  return { latencies, ops: OPS };
+}
+
+// Workload C: 100% read
+async function workloadC(db: BodDB) {
+  const latencies: number[] = [];
+  for (let i = 0; i < OPS; i++) {
+    const t0 = performance.now();
+    db.get(randKey());
+    latencies.push(performance.now() - t0);
+  }
+  return { latencies, ops: OPS };
+}
+
+// Workload D: 95% insert, 5% read
+async function workloadD(db: BodDB) {
+  const latencies: number[] = [];
+  let insertIdx = SEED_COUNT;
+  for (let i = 0; i < OPS; i++) {
+    const t0 = performance.now();
+    if (Math.random() < 0.95) {
+      db.set(`bench/item${insertIdx++}`, randRecord(insertIdx));
+    } else {
+      db.get(randKey());
+    }
+    latencies.push(performance.now() - t0);
+  }
+  return { latencies, ops: OPS };
+}
+
+// Workload E: 95% prefix scan, 5% insert
+async function workloadE(db: BodDB) {
+  const latencies: number[] = [];
+  let insertIdx = SEED_COUNT;
+  for (let i = 0; i < OPS; i++) {
+    const t0 = performance.now();
+    if (Math.random() < 0.95) {
+      db.get('bench');
+    } else {
+      db.set(`bench/item${insertIdx++}`, randRecord(insertIdx));
+    }
+    latencies.push(performance.now() - t0);
+  }
+  return { latencies, ops: OPS };
+}
+
+// Workload F: Subscription notify latency
+async function workloadF(): Promise<Result> {
+  const db = new BodDB({ path: ':memory:' });
+  await seed(db);
+
+  const notifyLatencies: number[] = [];
+  const unsubs: (() => void)[] = [];
+
+  for (let s = 0; s < SUB_COUNT; s++) {
+    const key = `bench/item${s}`;
+    const unsub = db.on(key, () => {
+      // callback fired
+    });
+    unsubs.push(unsub);
+  }
+
+  const latencies: number[] = [];
+  for (let i = 0; i < SUB_WRITES; i++) {
+    const key = `bench/item${i % SUB_COUNT}`;
+    const t0 = performance.now();
+    db.set(key, randRecord(i));
+    latencies.push(performance.now() - t0);
+  }
+
+  unsubs.forEach((u) => u());
+  db.close();
+
+  latencies.sort((a, b) => a - b);
+  const totalMs = latencies.reduce((s, v) => s + v, 0);
+  return {
+    name: 'Workload F (subscription)',
+    ops: SUB_WRITES,
+    opsPerSec: Math.round(SUB_WRITES / (totalMs / 1000)),
+    p50: percentile(latencies, 50),
+    p99: percentile(latencies, 99),
+    totalMs,
+  };
+}
+
+async function main() {
+  console.log(`\nBodDB YCSB-inspired Benchmark\n${'='.repeat(60)}\n`);
+
+  const results: Result[] = [];
+
+  results.push(await runWorkload('Workload A (update-heavy)', workloadA));
+  results.push(await runWorkload('Workload B (read-heavy)', workloadB));
+  results.push(await runWorkload('Workload C (read-only)', workloadC));
+  results.push(await runWorkload('Workload D (insert-heavy)', workloadD));
+  results.push(await runWorkload('Workload E (scan)', workloadE));
+  results.push(await workloadF());
+
+  for (const r of results) {
+    console.log(`${r.name.padEnd(32)} ${fmt(r.opsPerSec).padStart(10)} ops/sec  p50: ${fmtMs(r.p50)}ms  p99: ${fmtMs(r.p99)}ms`);
+  }
+
+  console.log(`\n${'='.repeat(60)}`);
+  console.log(`${'Workload'.padEnd(32)} ${'ops/sec'.padStart(10)}  ${'p50'.padStart(8)}  ${'p99'.padStart(8)}`);
+  console.log(`${'-'.repeat(60)}`);
+  for (const r of results) {
+    console.log(`${r.name.padEnd(32)} ${fmt(r.opsPerSec).padStart(10)}  ${(fmtMs(r.p50) + 'ms').padStart(8)}  ${(fmtMs(r.p99) + 'ms').padStart(8)}`);
+  }
+  console.log();
+}
+
+main();