@treenity/core 1.0.47 → 3.0.0

package/src/server/watch.ts

@@ -0,0 +1,202 @@
+// Treenity WatchManager — Layer 5
+// Exact-path + prefix (children) watch/unwatch per user.
+// Supports multiple connections per user (multi-tab).
+// Grace period: on last disconnect, watches survive briefly for SSE auto-reconnect.
+
+import { type NodeEvent } from './sub';
+
+export type WatchPush = (event: NodeEvent) => void;
+
+export type WatchManagerOpts = {
+  gracePeriodMs?: number;
+  onUserRemoved?: (userId: string) => void;
+};
+
+export type WatchOpts = { children?: boolean; autoWatch?: boolean };
+
+export type WatchManager = {
+  /** Attach push channel. Returns true if watches were preserved (reconnect within grace). */
+  connect(connId: string, userId: string, push: WatchPush): boolean;
+  disconnect(connId: string): void;
+  watch(userId: string, paths: string[], opts?: WatchOpts): void;
+  unwatch(userId: string, paths: string[], opts?: { children?: boolean }): void;
+  notify(event: NodeEvent): void;
+  clientCount(): number;
+};
+
+const DEFAULT_GRACE_MS = 5_000;
+
+function addTo(map: Map<string, Set<string>>, key: string, uid: string) {
+  let set = map.get(key);
+  if (!set) {
+    set = new Set();
+    map.set(key, set);
+  }
+  set.add(uid);
+}
+
+function removeFrom(map: Map<string, Set<string>>, key: string, uid: string) {
+  const set = map.get(key);
+  if (!set) return;
+  set.delete(uid);
+  if (set.size === 0) map.delete(key);
+}
+
+export function createWatchManager(opts?: WatchManagerOpts): WatchManager {
+  const gracePeriodMs = opts?.gracePeriodMs ?? DEFAULT_GRACE_MS;
+  const pathToUsers = new Map<string, Set<string>>();
+  const prefixToUsers = new Map<string, Set<string>>();
+  const users = new Map<
+    string,
+    { pushes: Map<string, WatchPush>; paths: Set<string>; prefixes: Map<string, boolean> }
+  >();
+  const graceTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
+  function removeUser(userId: string) {
+    const user = users.get(userId);
+    if (!user) return;
+    for (const p of user.paths) removeFrom(pathToUsers, p, userId);
+    for (const p of user.prefixes.keys()) removeFrom(prefixToUsers, p, userId);
+    users.delete(userId);
+    opts?.onUserRemoved?.(userId);
+  }
+
+  function pushToUser(uid: string, event: NodeEvent) {
+    const user = users.get(uid);
+    if (!user) return;
+    for (const push of user.pushes.values()) push(event);
+  }
+
+  function ensureUser(userId: string) {
+    let user = users.get(userId);
+    if (!user) {
+      user = { pushes: new Map(), paths: new Set(), prefixes: new Map() };
+      users.set(userId, user);
+    }
+    return user;
+  }
+
+  return {
+    connect(connId, userId, push) {
+      // Cancel grace timer — user reconnected in time
+      const timer = graceTimers.get(userId);
+      if (timer) {
+        clearTimeout(timer);
+        graceTimers.delete(userId);
+      }
+
+      const preserved = users.has(userId);
+      const user = ensureUser(userId);
+      user.pushes.set(connId, push);
+      return preserved;
+    },
+
+    disconnect(connId) {
+      for (const [userId, user] of users) {
+        if (!user.pushes.has(connId)) continue;
+        user.pushes.delete(connId);
+
+        if (user.pushes.size === 0) {
+          // Start grace period — don't nuke watches yet
+          const timer = setTimeout(() => {
+            graceTimers.delete(userId);
+            const u = users.get(userId);
+            if (u && u.pushes.size === 0) removeUser(userId);
+          }, gracePeriodMs);
+          graceTimers.set(userId, timer);
+        }
+        return;
+      }
+    },
+
+    watch(userId, paths, watchOpts) {
+      const user = ensureUser(userId);
+
+      if (watchOpts?.children) {
+        for (const p of paths) {
+          user.prefixes.set(p, watchOpts.autoWatch ?? false);
+          addTo(prefixToUsers, p, userId);
+        }
+      } else {
+        for (const p of paths) {
+          user.paths.add(p);
+          addTo(pathToUsers, p, userId);
+        }
+      }
+    },
+
+    unwatch(userId, paths, unwatchOpts) {
+      const user = users.get(userId);
+      if (!user) return;
+
+      if (unwatchOpts?.children) {
+        for (const p of paths) {
+          user.prefixes.delete(p);
+          removeFrom(prefixToUsers, p, userId);
+        }
+      } else {
+        for (const p of paths) {
+          user.paths.delete(p);
+          removeFrom(pathToUsers, p, userId);
+        }
+      }
+    },
+
+    notify(event) {
+      if (event.type === 'reconnect') return;
+      const notified = new Set<string>();
+
+      // Exact match
+      const exact = pathToUsers.get(event.path);
+      if (exact)
+        for (const uid of exact) {
+          notified.add(uid);
+          pushToUser(uid, event);
+        }
+
+      // Prefix match: direct parent only (mirrors getChildren depth=1)
+      const idx = event.path.lastIndexOf('/');
+      if (idx < 0) return;
+      const parent = idx === 0 ? '/' : event.path.slice(0, idx);
+      const watchers = prefixToUsers.get(parent);
+      if (watchers)
+        for (const uid of watchers) {
+          if (notified.has(uid)) continue;
+          notified.add(uid);
+          const user = users.get(uid);
+          if (!user) continue;
+          pushToUser(uid, event);
+          // autoWatch: subscribe to exact path for future updates
+          if (user.prefixes.get(parent)) {
+            user.paths.add(event.path);
+            addTo(pathToUsers, event.path, uid);
+          }
+        }
+
+      // Virtual Parent Match (CDC Matrix events)
+      const vps = [...('addVps' in event && event.addVps ? event.addVps : []), ...(event.rmVps || [])];
+      for (const vp of vps) {
+        const vpWatchers = prefixToUsers.get(vp);
+        if (vpWatchers) {
+          for (const uid of vpWatchers) {
+            if (notified.has(uid)) continue;
+            notified.add(uid);
+            const user = users.get(uid);
+            if (!user) continue;
+            pushToUser(uid, event);
+            if (user.prefixes.get(vp)) {
+              user.paths.add(event.path);
+              addTo(pathToUsers, event.path, uid);
+            }
+          }
+        }
+      }
+    },
+
+    clientCount() {
+      let count = 0;
+      for (const user of users.values()) count += user.pushes.size;
+      return count;
+    },
+  };
+}

package/src/server/workflow.test.ts

@@ -0,0 +1,82 @@
+import { registerType } from '#comp';
+import { createNode } from '#core';
+import { clearRegistry } from '#core/index.test';
+import { createMemoryTree, type Tree } from '#tree';
+import assert from 'node:assert/strict';
+import { beforeEach, describe, it } from 'node:test';
+import { withMounts } from './mount';
+import { createTreeRouter } from './trpc';
+import { createWatchManager } from './watch';
+
+class Order {
+  status = 'new';
+  
+  cook() {
+    this.status = 'kitchen';
+  }
+}
+
+describe('Workflow & Spatial Gravity', () => {
+  let rootStore: Tree;
+  let trpcStore: Tree;
+
+  beforeEach(async () => {
+    clearRegistry();
+    // We register the query mount manually or import it
+    await import('./mount-adapters');
+    registerType('order', Order);
+    rootStore = createMemoryTree();
+    trpcStore = withMounts(rootStore);
+  });
+
+  it('moves order from new to kitchen seamlessly with Immer patch', async () => {
+    // 0. Setup root ACL
+    await trpcStore.set({
+      ...createNode('/', 'root'),
+      $acl: [{ g: 'public', p: 15 }]
+    });
+
+    // 1. Setup flat data folder
+    await trpcStore.set(createNode('/entities/orders/1', 'order', { status: 'new' }));
+
+    // 2. Setup query mounts
+    await trpcStore.set(
+      createNode('/workflows/new', 'folder', {}, {
+        mount: { $type: 't.mount.query' },
+        query: { $type: 'query', source: '/entities/orders', match: { status: 'new' } }
+      })
+    );
+    await trpcStore.set(
+      createNode('/workflows/kitchen', 'folder', {}, {
+        mount: { $type: 't.mount.query' },
+        query: { $type: 'query', source: '/entities/orders', match: { status: 'kitchen' } }
+      })
+    );
+
+    // Initial check
+    let newFolder = await trpcStore.getChildren('/workflows/new');
+    let kitchenFolder = await trpcStore.getChildren('/workflows/kitchen');
+    assert.equal(newFolder.items.length, 1);
+    assert.equal(kitchenFolder.items.length, 0);
+
+    // Create tRPC router
+    const watcher = createWatchManager();
+    const router = createTreeRouter(trpcStore as any, watcher);
+    const caller = router.createCaller({ session: null, token: null });
+
+    // Execute the action (should emit patches in console and update DB)
+    await caller.execute({
+      path: '/entities/orders/1',
+      action: 'cook',
+    });
+
+    // Check spatial gravity (moved via query mounts)
+    newFolder = await trpcStore.getChildren('/workflows/new');
+    kitchenFolder = await trpcStore.getChildren('/workflows/kitchen');
+    
+    assert.equal(newFolder.items.length, 0, 'Order should leave /workflows/new');
+    assert.equal(kitchenFolder.items.length, 1, 'Order should appear in /workflows/kitchen');
+    assert.equal(kitchenFolder.items[0].$path, '/entities/orders/1', 'Order path remains canonical');
+    assert.equal(kitchenFolder.items[0].status, 'kitchen', 'Status is updated');
+  });
+});

package/src/tree/CLAUDE.md

@@ -0,0 +1,13 @@
+## store (Tree)
+Tree interface + adapters. Layer 1 — no deps except core types.
+
+### Файлы
+- index.ts — Tree interface, paginate, createMemoryTree, createOverlayTree, createFilterTree, resolveRef
+- mongo.ts — MongoDB adapter with $↔_ field mapping, $rev OCC (conditional replaceOne)
+- fs.ts — FS adapter (JSON files on disk), $rev OCC
+- query.ts — Query tree: virtual filtered view via sift (Mongo syntax). Used by t.mount.query
+
+### Конвенции
+- $rev: if present on incoming node → OCC check (match stored rev). If absent → blind upsert
+- Mongo: $ prefix → _ prefix transparently (toStorage/fromStorage)
+- Tree composability: overlay(upper, lower), filter(upper, lower, predicate)

package/src/tree/cache.test.ts

@@ -0,0 +1,213 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { withCache } from './cache';
+import { createMemoryTree } from './index';
+
+function makeNode(path: string, extra?: Record<string, unknown>) {
+  return { $path: path, $type: 'test', ...extra };
+}
+
+describe('withCache — reads', () => {
+  it('miss: delegates to underlying store', async () => {
+    const mem = createMemoryTree();
+    await mem.set(makeNode('/a'));
+    const cached = withCache(mem);
+    const node = await cached.get('/a');
+    assert.ok(node);
+    assert.equal(node.$path, '/a');
+  });
+
+  it('hit: second get does not call underlying store', async () => {
+    let calls = 0;
+    const mem = createMemoryTree();
+    await mem.set(makeNode('/a'));
+
+    const spied: typeof mem = {
+      ...mem,
+      async get(path, ctx) { calls++; return mem.get(path, ctx); },
+      async getChildren(p, o, c) { return mem.getChildren(p, o, c); },
+      async set(n, c) { return mem.set(n, c); },
+      async remove(p, c) { return mem.remove(p, c); },
+    };
+
+    const cached = withCache(spied);
+    await cached.get('/a');  // miss — calls underlying
+    await cached.get('/a');  // hit — should NOT call underlying
+    assert.equal(calls, 1);
+  });
+
+  it('get on missing path returns undefined without caching null', async () => {
+    const mem = createMemoryTree();
+    const cached = withCache(mem);
+    const result = await cached.get('/nonexistent');
+    assert.equal(result, undefined);
+    // After the node is added, it should be fetchable
+    await mem.set(makeNode('/nonexistent'));
+    const fresh = await cached.get('/nonexistent');
+    assert.ok(fresh);
+  });
+});
+
+describe('withCache — writes populate', () => {
+  it('set populates cache — next get returns fresh without underlying call', async () => {
+    let gets = 0;
+    const mem = createMemoryTree();
+
+    const spied: typeof mem = {
+      ...mem,
+      async get(path, ctx) { gets++; return mem.get(path, ctx); },
+      async getChildren(p, o, c) { return mem.getChildren(p, o, c); },
+      async set(n, c) { return mem.set(n, c); },
+      async remove(p, c) { return mem.remove(p, c); },
+    };
+
+    const cached = withCache(spied);
+    await cached.set(makeNode('/a', { v: 1 })); // write-populate: 1 get for re-read
+    gets = 0;
+
+    const node = await cached.get('/a'); // should hit cache
+    assert.equal(gets, 0);
+    assert.equal((node as any).v, 1);
+  });
+
+  it('set captures fresh $rev in cache', async () => {
+    const mem = createMemoryTree();
+    const cached = withCache(mem);
+
+    await cached.set(makeNode('/a', { v: 1 }));
+    const node = await cached.get('/a');
+    assert.equal(node?.$rev, 1, 'cache should have $rev bumped by store');
+  });
+
+  it('set then bypass update then set — cache reflects last write', async () => {
+    const mem = createMemoryTree();
+    const cached = withCache(mem);
+
+    await cached.set(makeNode('/a', { v: 1 }));
+    await mem.set(makeNode('/a', { v: 2 }));       // bypass cache
+    await cached.set(makeNode('/a', { v: 3 }));     // write-populate
+
+    const node = await cached.get('/a');
+    assert.equal((node as any).v, 3);
+  });
+
+  it('remove invalidates cache entry', async () => {
+    const mem = createMemoryTree();
+    await mem.set(makeNode('/a'));
+    const cached = withCache(mem);
+
+    await cached.get('/a');      // populate cache
+    await cached.remove('/a');   // invalidate
+    const node = await cached.get('/a');
+    assert.equal(node, undefined);
+  });
+});
+
+describe('withCache — inflight dedup', () => {
+  it('concurrent gets produce single underlying call', async () => {
+    let calls = 0;
+    const mem = createMemoryTree();
+    await mem.set(makeNode('/a', { v: 42 }));
+
+    const spied: typeof mem = {
+      ...mem,
+      async get(path, ctx) {
+        calls++;
+        // Simulate async delay
+        await new Promise(r => setImmediate(r));
+        return mem.get(path, ctx);
+      },
+      async getChildren(p, o, c) { return mem.getChildren(p, o, c); },
+      async set(n, c) { return mem.set(n, c); },
+      async remove(p, c) { return mem.remove(p, c); },
+    };
+
+    const cached = withCache(spied);
+
+    // Fire 10 concurrent gets
+    const results = await Promise.all(
+      Array.from({ length: 10 }, () => cached.get('/a')),
+    );
+
+    assert.equal(calls, 1, 'only one underlying get call');
+    for (const r of results) {
+      assert.equal((r as any).v, 42);
+    }
+  });
+
+  it('after inflight settles, next call retries', async () => {
+    let calls = 0;
+    const mem = createMemoryTree();
+    await mem.set(makeNode('/a'));
+
+    const spied: typeof mem = {
+      ...mem,
+      async get(path, ctx) { calls++; return mem.get(path, ctx); },
+      async getChildren(p, o, c) { return mem.getChildren(p, o, c); },
+      async set(n, c) { return mem.set(n, c); },
+      async remove(p, c) { return mem.remove(p, c); },
+    };
+
+    const cached = withCache(spied);
+    await cached.get('/a');          // miss → call 1, populates cache
+    await cached.remove('/a');       // invalidates
+    await mem.set(makeNode('/a'));    // restore in underlying
+    await cached.get('/a');          // miss again → call 2
+    assert.equal(calls, 2);
+  });
+});
+
+describe('withCache — getChildren populates cache', () => {
+  it('nodes fetched via getChildren are cached for subsequent get', async () => {
+    let gets = 0;
+    const mem = createMemoryTree();
+    await mem.set(makeNode('/parent'));
+    await mem.set(makeNode('/parent/child'));
+
+    const spied: typeof mem = {
+      ...mem,
+      async get(path, ctx) { gets++; return mem.get(path, ctx); },
+      async getChildren(p, o, c) { return mem.getChildren(p, o, c); },
+      async set(n, c) { return mem.set(n, c); },
+      async remove(p, c) { return mem.remove(p, c); },
+    };
+
+    const cached = withCache(spied);
+    await cached.getChildren('/parent');   // fetches children, populates cache
+    gets = 0;                              // reset counter
+
+    await cached.get('/parent/child');     // should hit cache, not call underlying
+    assert.equal(gets, 0);
+  });
+});
+
+describe('withCache — tree structure', () => {
+  it('caches deep paths independently', async () => {
+    const mem = createMemoryTree();
+    await mem.set(makeNode('/a/b/c'));
+    await mem.set(makeNode('/a/b/d'));
+    const cached = withCache(mem);
+
+    await cached.get('/a/b/c');
+    await cached.get('/a/b/d');
+
+    // Verify both are in cache by checking remove invalidates correctly
+    await cached.remove('/a/b/c');
+    const c = await cached.get('/a/b/c');
+    const d = await cached.get('/a/b/d'); // /d is still cached
+    assert.equal(c, undefined);
+    assert.ok(d);
+  });
+
+  it('sibling paths do not interfere', async () => {
+    const mem = createMemoryTree();
+    await mem.set(makeNode('/x/a', { tag: 'a' }));
+    await mem.set(makeNode('/x/b', { tag: 'b' }));
+    const cached = withCache(mem);
+
+    const a = await cached.get('/x/a');
+    const b = await cached.get('/x/b');
+    assert.equal((a as any).tag, 'a');
+    assert.equal((b as any).tag, 'b');
+  });
+});

package/src/tree/cache.ts

@@ -0,0 +1,51 @@
+// Treenity Cache Tree — Layer 1
+// Write-populate tree cache wrapping any Tree.
+// Tree structure mirrors path hierarchy — O(depth) navigation, O(1) subtree drop.
+// Populate on read AND write. Inflight dedup prevents thundering herd.
+
+import type { NodeData } from '#core';
+import { type Tree, treeEnsure, treeNavigate, type TreeNode } from './index';
+import { createInflight } from './inflight';
+
+export function withCache(store: Tree): Tree {
+  const root: TreeNode<NodeData> = { children: new Map() };
+  const dedup = createInflight<NodeData | undefined>();
+
+  return {
+    async get(path, ctx) {
+      const cached = treeNavigate(root, path);
+      if (cached?.data !== undefined) return cached.data;
+      return dedup(path, async () => {
+        const node = await store.get(path, ctx);
+        if (node) treeEnsure(root, node.$path).data = node;
+        return node;
+      });
+    },
+
+    async getChildren(path, opts, ctx) {
+      const result = await store.getChildren(path, opts, ctx);
+      for (const node of result.items) treeEnsure(root, node.$path).data = node;
+      return result;
+    },
+
+    async set(node, ctx) {
+      await store.set(node, ctx);
+      // Write-populate: re-read to capture $rev bump, warm cache for subscribers
+      const fresh = await store.get(node.$path, ctx);
+      treeEnsure(root, node.$path).data = fresh;
+    },
+
+    async remove(path, ctx) {
+      const result = await store.remove(path, ctx);
+      const cached = treeNavigate(root, path);
+      if (cached) cached.data = undefined;
+      return result;
+    },
+
+    async patch(path, ops, ctx) {
+      await store.patch(path, ops, ctx);
+      const fresh = await store.get(path, ctx);
+      treeEnsure(root, path).data = fresh;
+    },
+  };
+}