@treenity/core 1.0.48 → 3.0.1

package/src/client/client.test.ts

@@ -0,0 +1,192 @@
+// Treenity Client SDK — e2e tests
+// Tests createTrpcTransport + createRepathTree + t.mount.tree.trpc
+
+import { registerType } from '#comp';
+import { createNode, R, S, W } from '#core';
+import { withMounts } from '#server/mount';
+import '#server/mount-adapters';
+import { createTreenityServer } from '#server/server';
+import { createMemoryTree } from '#tree';
+import { createRepathTree } from '#tree/repath';
+import assert from 'node:assert/strict';
+import type { Socket } from 'node:net';
+import { afterEach, before, beforeEach, describe, it } from 'node:test';
+import { createTrpcTransport } from './trpc';
+
+// ── Helpers ──
+
+function listen(server: import('node:http').Server): Promise<number> {
+  return new Promise((resolve) => {
+    server.listen(0, '127.0.0.1', () => {
+      resolve((server.address() as { port: number }).port);
+    });
+  });
+}
+
+// ── Test type ──
+
+class Counter {
+  count = 0;
+  increment() { this.count++; }
+}
+
+describe('Treenity Client SDK', () => {
+  let ts: ReturnType<typeof createTreenityServer>;
+  let url: string;
+  const sockets = new Set<Socket>();
+
+  before(() => {
+    registerType('counter', Counter);
+  });
+
+  beforeEach(async () => {
+    const bootstrap = createMemoryTree();
+    await bootstrap.set({
+      ...createNode('/', 'root'),
+      $acl: [{ g: 'public', p: R | W | S }],
+    });
+
+    ts = createTreenityServer(bootstrap);
+    ts.server.on('connection', (s: Socket) => {
+      sockets.add(s);
+      s.on('close', () => sockets.delete(s));
+    });
+    const port = await listen(ts.server);
+    url = `http://127.0.0.1:${port}`;
+  });
+
+  afterEach(async () => {
+    for (const s of sockets) s.destroy();
+    sockets.clear();
+    await new Promise<void>((r) => ts.server.close(() => r()));
+  });
+
+  // ── createTrpcTransport ──
+
+  describe('createTrpcTransport', () => {
+    it('tree.get + tree.set roundtrip', async () => {
+      const { tree } = createTrpcTransport({ url });
+      await tree.set(createNode('/hello', 'doc', { title: 'World' }));
+      const node = await tree.get('/hello');
+
+      assert.ok(node);
+      assert.equal(node.$type, 't.doc');
+      assert.equal((node as any).title, 'World');
+    });
+
+    it('tree.getChildren returns children', async () => {
+      const { tree } = createTrpcTransport({ url });
+      await tree.set(createNode('/items', 'dir'));
+      await tree.set(createNode('/items/a', 'doc'));
+      await tree.set(createNode('/items/b', 'doc'));
+
+      const { items } = await tree.getChildren('/items');
+      assert.equal(items.length, 2);
+    });
+
+    it('tree.remove deletes node', async () => {
+      const { tree } = createTrpcTransport({ url });
+      await tree.set(createNode('/tmp', 'doc'));
+      await tree.remove('/tmp');
+
+      assert.equal(await tree.get('/tmp'), undefined);
+    });
+
+    it('execute calls action', async () => {
+      const { tree, execute } = createTrpcTransport({ url });
+      await tree.set(createNode('/c', 'counter', { count: 0 }));
+
+      await execute('/c', 'increment');
+
+      const node = await tree.get('/c');
+      assert.equal((node as any).count, 1);
+    });
+  });
+
+  // ── createRepathTree over tRPC ──
+
+  describe('createRepathTree + tRPC', () => {
+    it('translates paths over the wire', async () => {
+      const { tree: remote } = createTrpcTransport({ url });
+
+      // Write via server at absolute path
+      await remote.set(createNode('/data/item', 'doc', { v: 42 }));
+
+      // Mount remote's /data at local /mnt
+      const mounted = createRepathTree(remote, '/mnt', '/data');
+      const node = await mounted.get('/mnt/item');
+
+      assert.ok(node);
+      assert.equal(node.$path, '/mnt/item');
+      assert.equal((node as any).v, 42);
+    });
+
+    it('set through repath writes to correct remote path', async () => {
+      const { tree: remote } = createTrpcTransport({ url });
+      const mounted = createRepathTree(remote, '/mnt', '/store');
+
+      await mounted.set(createNode('/mnt/new', 'doc', { x: 1 }));
+
+      // Verify via direct remote access
+      const node = await remote.get('/store/new');
+      assert.ok(node);
+      assert.equal(node.$path, '/store/new');
+    });
+  });
+
+  // ── t.mount.tree.trpc ──
+
+  describe('t.mount.tree.trpc', () => {
+    it('mounts remote tree with path translation', async () => {
+      // Set up content on the remote server
+      const { tree: remote } = createTrpcTransport({ url });
+      await remote.set(createNode('/strategies/alpha', 'doc', { score: 99 }));
+
+      // Create a local bootstrap with mount pointing to remote
+      const local = createMemoryTree();
+      await local.set({
+        ...createNode('/', 'root'),
+        $acl: [{ g: 'public', p: R | W | S }],
+      });
+      await local.set({
+        $path: '/remote',
+        $type: 'dir',
+        mount: { $type: 't.mount.tree.trpc' },
+        connection: { $type: 'connection', url, path: '/strategies' },
+      });
+
+      const store = withMounts(local);
+      const node = await store.get('/remote/alpha');
+
+      assert.ok(node);
+      assert.equal(node.$path, '/remote/alpha');
+      assert.equal((node as any).score, 99);
+    });
+
+    it('getChildren through mount', async () => {
+      const { tree: remote } = createTrpcTransport({ url });
+      await remote.set(createNode('/items', 'dir'));
+      await remote.set(createNode('/items/x', 'doc'));
+      await remote.set(createNode('/items/y', 'doc'));
+
+      const local = createMemoryTree();
+      await local.set({
+        ...createNode('/', 'root'),
+        $acl: [{ g: 'public', p: R | W | S }],
+      });
+      await local.set({
+        $path: '/fed',
+        $type: 'dir',
+        mount: { $type: 't.mount.tree.trpc' },
+        connection: { $type: 'connection', url, path: '/items' },
+      });
+
+      const store = withMounts(local);
+      const { items } = await store.getChildren('/fed');
+
+      assert.equal(items.length, 2);
+      const paths = items.map(n => n.$path).sort();
+      assert.deepEqual(paths, ['/fed/x', '/fed/y']);
+    });
+  });
+});

package/src/client/handle.ts

@@ -0,0 +1,53 @@
+// Client node handle — typed access to remote nodes.
+// nc(path).get(Type).method() — actions, no fetch needed.
+// nc(path).fetch(Type) — async fetch + typed proxy.
+// nc(path).sub(Type, cb) — reactive subscription with typed data.
+
+import { type Class, type TypeProxy } from '#comp';
+import { makeTypedProxy, type ExecuteFn } from '#comp/handle';
+import type { NodeData } from '#core';
+import type { TreenityClient } from './index';
+
+export function createNodeClient(client: TreenityClient) {
+  const execute: ExecuteFn = (input) =>
+    client.execute(input.path, input.action, input.data, { type: input.type, key: input.key });
+
+  return (path: string) => ({
+    /** Typed actions proxy — calls execute over network, no fetch needed */
+    get<T extends object>(cls: Class<T>, key?: string): TypeProxy<T> {
+      return makeTypedProxy<T>(undefined, cls, path, execute, undefined, key);
+    },
+
+    /** Fetch node + typed proxy (data fields + action methods) */
+    async fetch<T extends object>(cls: Class<T>, key?: string): Promise<TypeProxy<T>> {
+      const node = await client.tree.get(path);
+      return makeTypedProxy<T>(node, cls, path, execute, undefined, key);
+    },
+
+    /** Subscribe — callback with typed proxy on each change */
+    async sub<T extends object>(cls: Class<T>, cb: (data: TypeProxy<T>) => void, key?: string) {
+      let cached: NodeData | undefined;
+
+      function notify() {
+        cb(makeTypedProxy<T>(cached, cls, path, execute, undefined, key));
+      }
+
+      const { node, unsubscribe } = await client.watchPath(path, (event) => {
+        if (event.type === 'set') {
+          cached = { $path: event.path, ...event.node } as NodeData;
+          notify();
+        }
+        if (event.type === 'patch' && cached) {
+          // Re-fetch on patch (optimize with applyPatch later)
+          client.tree.get(path).then(fresh => {
+            if (fresh) { cached = fresh; notify(); }
+          });
+        }
+      });
+
+      cached = node as NodeData | undefined;
+      if (cached) notify();
+      return { unsubscribe };
+    },
+  });
+}

package/src/client/index.ts

@@ -0,0 +1,18 @@
+// Treenity Client SDK — transport-agnostic tree client interface.
+// Transports: trpc (now), ws (future), http (future).
+
+import type { Tree } from '#tree';
+
+export type WatchSub = { unsubscribe(): void };
+
+export type TreenityClient = {
+  tree: Tree;
+  execute(path: string, action: string, data?: unknown, opts?: { type?: string; key?: string }): Promise<unknown>;
+  /** Global SSE stream — all events for this user */
+  watch(onEvent: (e: any) => void): WatchSub;
+  /** Watch specific path — registers watch + filters events. Returns initial node + subscription. */
+  watchPath(path: string, onEvent: (e: any) => void): Promise<{ node: any; unsubscribe(): void }>;
+};
+
+export { createTrpcTransport } from './trpc';
+export { createNodeClient } from './handle';

package/src/client/trpc.ts

@@ -0,0 +1,92 @@
+// tRPC transport for Treenity Client.
+// HTTP batch for queries/mutations, SSE for subscriptions.
+
+import type { NodeData } from '#core';
+import type { TreeRouter } from '#server/trpc';
+import { defaultPatch } from '#tree/patch';
+import { createTRPCClient, httpBatchLink, httpSubscriptionLink, splitLink } from '@trpc/client';
+import type { TreenityClient, WatchSub } from './index';
+
+export type TrpcTransportOpts = {
+  url: string;
+  getToken?: () => string | null;
+  token?: string;
+  fetch?: (input: any, init?: any) => Promise<Response>;
+};
+
+export function createTrpcTransport(opts: TrpcTransportOpts): TreenityClient & { trpc: ReturnType<typeof createTRPCClient<TreeRouter>> } {
+  const getToken = opts.getToken ?? (() => opts.token ?? null);
+
+  const trpc = createTRPCClient<TreeRouter>({
+    links: [
+      splitLink({
+        condition: (op) => op.type === 'subscription',
+        true: httpSubscriptionLink({
+          url: `${opts.url}/trpc/`,
+          connectionParams: () => {
+            const t = getToken();
+            return t ? { token: t } : {};
+          },
+        }),
+        false: httpBatchLink({
+          url: `${opts.url}/trpc/`,
+          maxURLLength: 2048,
+          headers: () => {
+            const t = getToken();
+            return t ? { Authorization: `Bearer ${t}` } : {};
+          },
+          ...(opts.fetch && { fetch: opts.fetch }),
+        }),
+      }),
+    ],
+  });
+
+  // Shared SSE connection for watchPath — lazy, one per transport
+  let eventSub: WatchSub | null = null;
+  const pathCbs = new Map<string, Set<(e: any) => void>>();
+
+  function ensureSSE() {
+    if (eventSub) return;
+    eventSub = trpc.events.subscribe(undefined as void, {
+      onData: (event: any) => {
+        if ('path' in event) pathCbs.get(event.path)?.forEach(cb => cb(event));
+      },
+    });
+  }
+
+  return {
+    tree: {
+      get: (path) => trpc.get.query({ path }) as Promise<NodeData | undefined>,
+      getChildren: (path, opts) => trpc.getChildren.query({ path, ...opts }),
+      set: (node) => trpc.set.mutate({ node: node as Record<string, unknown> }),
+      remove: (path) => trpc.remove.mutate({ path }).then(() => true),
+      // TODO: add tRPC patch endpoint for single-RPC atomic patch
+      patch: (path, ops) => defaultPatch(
+        (p) => trpc.get.query({ path: p }) as Promise<NodeData | undefined>,
+        (n) => trpc.set.mutate({ node: n as Record<string, unknown> }).then(() => {}),
+        path, ops,
+      ),
+    },
+    execute: (path, action, data, o) =>
+      trpc.execute.mutate({ path, action, data, type: o?.type, key: o?.key }),
+    watch: (onEvent) =>
+      trpc.events.subscribe(undefined as void, { onData: onEvent }),
+
+    watchPath: async (path, onEvent) => {
+      const node = await trpc.get.query({ path, watch: true });
+      ensureSSE();
+      if (!pathCbs.has(path)) pathCbs.set(path, new Set());
+      pathCbs.get(path)!.add(onEvent);
+      return {
+        node,
+        unsubscribe() {
+          const set = pathCbs.get(path);
+          if (set) { set.delete(onEvent); if (!set.size) pathCbs.delete(path); }
+          if (!pathCbs.size && eventSub) { eventSub.unsubscribe(); eventSub = null; }
+        },
+      };
+    },
+
+    trpc,
+  };
+}

package/src/client.ts

@@ -0,0 +1 @@
+export * from './client/index.ts';

package/src/comp/CLAUDE.md

@@ -0,0 +1,14 @@
+## comp
+Component registration layer (L2). Bridges core primitives and server.
+
+### Файлы
+- index.ts — registerType, findCompByType, Actions<T>, TypeProxy<T> = Raw<T> & Actions<T>
+- needs.ts — sibling dependency injection: registerNeeds/resolveNeeds
+- ports.ts — action port graph: pre/post conditions as queryable edges
+- planner.ts — backward+forward chaining planner on the port graph
+
+### Конвенции
+- registerType auto-registers all public methods as action:{name}
+- Components never access siblings directly — use `needs` for injection
+- Ports declared via static metadata, planner resolves execution order
+- ExecCtx = {node, tree, signal, nc, deps} — context during action execution

package/src/comp/handle.ts

@@ -0,0 +1,36 @@
+// Shared typed proxy factory — L0, no server deps.
+// Used by: server (serverNodeHandle), client (createNodeClient), React (hooks).
+
+import { type Class, type TypeProxy } from './index';
+import { getComponent, type NodeData, normalizeType } from '#core';
+
+export type ExecuteInput = { path: string; type?: string; key?: string; action: string; data?: unknown };
+export type ExecuteFn = (input: ExecuteInput) => Promise<unknown>;
+export type StreamFn = (input: ExecuteInput) => AsyncIterable<unknown>;
+
+const AsyncGenFn = Object.getPrototypeOf(async function* () {}).constructor;
+
+/** Create TypeProxy from node data + class. Actions call execute/stream, fields read from comp. */
+export function makeTypedProxy<T extends object>(
+  node: NodeData | undefined,
+  cls: Class<T>,
+  path: string,
+  execute: ExecuteFn,
+  stream?: StreamFn,
+  key?: string,
+): TypeProxy<T> {
+  const type = normalizeType(cls);
+  const comp = node ? getComponent(node, cls, key) : undefined;
+
+  return new Proxy(comp ?? {} as T, {
+    get: (_t, prop: string) => {
+      const fn = (cls.prototype as any)[prop];
+      if (typeof fn === 'function') {
+        if (stream && fn instanceof AsyncGenFn)
+          return (data?: unknown) => stream({ path, type, key, action: prop, data });
+        return (data?: unknown) => execute({ path, type, key, action: prop, data });
+      }
+      return (comp as any)?.[prop];
+    },
+  }) as TypeProxy<T>;
+}

package/src/comp/index.test.ts

@@ -0,0 +1,165 @@
+// Tests for setComp, newComp, getCtx
+// Key behavior: when node.$type matches component $type, node itself IS the component.
+
+import { getCtx, newComp, registerType, setComp } from '#comp';
+import { createNode, getComponent, type NodeData } from '#core';
+import { clearRegistry } from '#core/index.test';
+import { executeAction } from '#server/actions';
+import { createMemoryTree } from '#tree';
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+class TestItem {
+  name = '';
+  quantity = 0;
+}
+registerType('test.item', TestItem);
+
+class TestMeta {
+  title = '';
+  description = '';
+}
+registerType('test.meta', TestMeta);
+
+// ── getComponent ──
+
+describe('getComponent', () => {
+  it('returns node itself when node.$type matches component type', () => {
+    const node: NodeData = { $path: '/a', $type: 'test.item', name: 'sword', quantity: 3 };
+    const comp = getComponent(node, TestItem);
+    assert.ok(comp);
+    assert.equal(comp.name, 'sword');
+    assert.equal(comp.quantity, 3);
+  });
+
+  it('returns named-key component when types differ', () => {
+    const node: NodeData = {
+      $path: '/a', $type: 'dir',
+      meta: { $type: 'test.meta', title: 'Hello', description: 'world' },
+    };
+    const comp = getComponent(node, TestMeta);
+    assert.ok(comp);
+    assert.equal(comp.title, 'Hello');
+    assert.equal(comp.description, 'world');
+  });
+
+  it('prefers node-level over named key when both have same $type', () => {
+    // This is the "wrong data shape" scenario — node-level wins, named key is ignored
+    const node: NodeData = {
+      $path: '/a', $type: 'test.item',
+      item: { $type: 'test.item', name: 'from-key', quantity: 99 },
+    };
+    const comp = getComponent(node, TestItem);
+    assert.ok(comp);
+    // Node-level has no name/quantity fields → undefined, not the named key values
+    assert.equal(comp.name, undefined);
+    assert.equal(comp.quantity, undefined);
+  });
+
+  it('returns undefined when no match', () => {
+    const node: NodeData = { $path: '/a', $type: 'dir' };
+    assert.equal(getComponent(node, TestItem), undefined);
+  });
+});
+
+// ── setComp ──
+
+describe('setComp', () => {
+  it('updates node directly for node-level component', () => {
+    const node: NodeData = { $path: '/a', $type: 'test.item', name: 'old', quantity: 1 };
+    setComp(node, TestItem, { name: 'new', quantity: 5 });
+    assert.equal(node.name, 'new');
+    assert.equal(node.quantity, 5);
+  });
+
+  it('updates named-key component', () => {
+    const node: NodeData = {
+      $path: '/a', $type: 'dir',
+      meta: { $type: 'test.meta', title: 'old', description: 'old' },
+    };
+    setComp(node, TestMeta, { title: 'new' });
+    assert.equal((node.meta as any).title, 'new');
+    assert.equal((node.meta as any).description, 'old'); // not overwritten
+  });
+
+  it('creates new named-key component when not found', () => {
+    const node: NodeData = { $path: '/a', $type: 'dir' };
+    setComp(node, TestItem, { name: 'created', quantity: 10 });
+    // default key = last segment of $type = 'item'
+    assert.ok(node.item);
+    assert.equal((node.item as any).$type, 'test.item');
+    assert.equal((node.item as any).name, 'created');
+    assert.equal((node.item as any).quantity, 10);
+  });
+
+  it('partial update preserves existing fields on node-level', () => {
+    const node: NodeData = { $path: '/a', $type: 'test.item', name: 'keep', quantity: 1 };
+    setComp(node, TestItem, { quantity: 99 });
+    assert.equal(node.name, 'keep');
+    assert.equal(node.quantity, 99);
+  });
+
+  it('preserves $path and $type on node-level update', () => {
+    const node: NodeData = { $path: '/a', $type: 'test.item', name: 'x', quantity: 0 };
+    setComp(node, TestItem, { name: 'y' });
+    assert.equal(node.$path, '/a');
+    assert.equal(node.$type, 'test.item');
+  });
+
+  it('throws when key already exists with different content', () => {
+    const node: NodeData = { $path: '/a', $type: 'dir', meta: { $type: 'other', x: 1 } };
+    assert.throws(
+      () => setComp(node, TestMeta, { title: 'fail' }),
+      (e: Error) => e.message.includes('already exists'),
+    );
+  });
+});
+
+// ── newComp ──
+
+describe('newComp', () => {
+  it('creates component with $type and data', () => {
+    const comp = newComp(TestItem, { name: 'sword', quantity: 3 });
+    assert.equal(comp.$type, 'test.item');
+    assert.equal(comp.name, 'sword');
+    assert.equal(comp.quantity, 3);
+  });
+
+  it('$type cannot be overridden by data', () => {
+    const comp = newComp(TestItem, { name: 'x', $type: 'hacked' } as any);
+    assert.equal(comp.$type, 'test.item');
+  });
+});
+
+// ── getCtx ──
+
+describe('getCtx', () => {
+  it('throws when called outside action context', () => {
+    assert.throws(() => getCtx(), (e: Error) => e.message.includes('outside action context'));
+  });
+
+  it('ALS isolation: concurrent async actions each see their own ctx', async () => {
+    clearRegistry();
+
+    // Method yields to event loop then reads ctx — ALS must keep each action's ctx isolated
+    class AlsNode {
+      async whoami() {
+        await Promise.resolve(); // yield — lets the other action's handler run
+        return getCtx().node.$path;
+      }
+    }
+    registerType('als.test', AlsNode);
+
+    const store = createMemoryTree();
+    await store.set(createNode('/a', 'als.test'));
+    await store.set(createNode('/b', 'als.test'));
+
+    const [pathA, pathB] = await Promise.all([
+      executeAction(store, '/a', undefined, undefined, 'whoami'),
+      executeAction(store, '/b', undefined, undefined, 'whoami'),
+    ]);
+
+    assert.equal(pathA, '/a');
+    assert.equal(pathB, '/b');
+  });
+});