@treenity/core 1.0.48 → 3.0.0

package/src/comp/needs.test.ts

@@ -0,0 +1,499 @@
+import { registerType } from '#comp';
+import { collectDeps, collectSiblings, getActionNeeds, parseNeedPattern } from '#comp/needs';
+import { createNode } from '#core';
+import { clearRegistry } from '#core/index.test';
+import { executeAction } from '#server/actions';
+import { createMemoryTree } from '#tree';
+import assert from 'node:assert/strict';
+import { beforeEach, describe, it } from 'node:test';
+
+// ── Test classes ──
+
+class Status {
+  value = 'draft';
+  publish() { this.value = 'published'; }
+}
+
+class Payment {
+  amount = 0;
+  settled = false;
+}
+
+class Delivery {
+  status = 'pending';
+}
+
+// ── Tests ──
+
+describe('parseNeedPattern', () => {
+  it('sibling', () => {
+    const spec = parseNeedPattern('payment');
+    assert.deepEqual(spec, { kind: 'sibling', name: 'payment', key: 'payment' });
+  });
+
+  it('field-ref', () => {
+    const spec = parseNeedPattern('@warehouseRef');
+    assert.deepEqual(spec, { kind: 'field-ref', field: 'warehouseRef', key: 'warehouseRef' });
+  });
+
+  it('relative path', () => {
+    const spec = parseNeedPattern('./config');
+    assert.deepEqual(spec, { kind: 'path', path: './config', key: 'config' });
+  });
+
+  it('parent-relative path', () => {
+    const spec = parseNeedPattern('../settings');
+    assert.deepEqual(spec, { kind: 'path', path: '../settings', key: 'settings' });
+  });
+
+  it('absolute path', () => {
+    const spec = parseNeedPattern('/sys/config');
+    assert.deepEqual(spec, { kind: 'path', path: '/sys/config', key: 'config' });
+  });
+
+  it('children pattern', () => {
+    const spec = parseNeedPattern('./items/*');
+    assert.deepEqual(spec, { kind: 'children', path: './items', key: 'items' });
+  });
+});
+
+describe('per-action needs', () => {
+  beforeEach(() => {
+    clearRegistry();
+
+  });
+
+  it('static needs registers per-action', () => {
+    class Article {
+      title = '';
+      static needs = {
+        publish: ['status'],
+        ship: ['status', 'delivery'],
+      };
+      publish() { this.title = 'published'; }
+      ship() { this.title = 'shipped'; }
+    }
+
+    registerType('t.article', Article);
+    registerType('t.status', Status);
+    registerType('t.delivery', Delivery);
+
+    const publishNeeds = getActionNeeds('t.article', 'publish');
+    assert.equal(publishNeeds.length, 1);
+    assert.equal(publishNeeds[0].key, 'status');
+
+    const shipNeeds = getActionNeeds('t.article', 'ship');
+    assert.equal(shipNeeds.length, 2);
+  });
+
+  it('opts.needs registers as * fallback', () => {
+    class Meta { title = ''; rename() {} }
+    registerType('t.meta', Meta, { needs: ['status'] });
+    registerType('t.status', Status);
+
+    // '*' fallback applies to any action
+    const needs = getActionNeeds('t.meta', 'rename');
+    assert.equal(needs.length, 1);
+    assert.equal(needs[0].key, 'status');
+  });
+
+  it('per-action overrides fallback', () => {
+    class Article {
+      title = '';
+      static needs = { publish: ['payment'] };
+      publish() {}
+      archive() {}
+    }
+
+    registerType('t.article', Article, { needs: ['status'] });
+    registerType('t.status', Status);
+    registerType('t.payment', Payment);
+
+    // publish: explicit per-action
+    assert.equal(getActionNeeds('t.article', 'publish')[0].key, 'payment');
+    // archive: falls back to '*'
+    assert.equal(getActionNeeds('t.article', 'archive')[0].key, 'status');
+  });
+});
+
+describe('collectDeps', () => {
+  beforeEach(() => {
+    clearRegistry();
+
+  });
+
+  it('sibling deps from same node', async () => {
+    class Article {
+      title = '';
+      static needs = { publish: ['status'] };
+      publish(_d: unknown, deps: any) {
+        this.title = 'new';
+        deps.status.value = 'published';
+      }
+    }
+
+    registerType('t.article', Article);
+    registerType('t.status', Status);
+
+    const store = createMemoryTree();
+    const node = createNode('/a', 'page', {}, {
+      article: { $type: 't.article', title: 'old' },
+      status: { $type: 't.status', value: 'draft' },
+    });
+
+    const deps = await collectDeps(node, 'article', 'publish', store);
+    assert.equal(Object.keys(deps).length, 1);
+    assert.equal((deps.status as any).value, 'draft');
+  });
+
+  it('@fieldRef resolves to remote node', async () => {
+    class Connector {
+      targetRef = '/config/warehouse';
+      static needs = { check: ['@targetRef'] };
+      check() {}
+    }
+
+    registerType('t.connector', Connector);
+
+    const store = createMemoryTree();
+    await store.set(createNode('/config/warehouse', 'warehouse', { capacity: 100 }));
+    const node = createNode('/order/1', 'page', {}, {
+      connector: { $type: 't.connector', targetRef: '/config/warehouse' },
+    });
+
+    const deps = await collectDeps(node, 'connector', 'check', store);
+    assert.equal((deps.targetRef as any).$path, '/config/warehouse');
+    assert.equal((deps.targetRef as any).capacity, 100);
+  });
+
+  it('relative path ./child resolves', async () => {
+    class Parent {
+      static needs = { run: ['./config'] };
+      run() {}
+    }
+
+    registerType('t.parent', Parent);
+
+    const store = createMemoryTree();
+    await store.set(createNode('/app/config', 'cfg', { debug: true }));
+    const node = createNode('/app', 'dir', {}, {
+      parent: { $type: 't.parent' },
+    });
+
+    const deps = await collectDeps(node, 'parent', 'run', store);
+    assert.equal((deps.config as any).$path, '/app/config');
+    assert.equal((deps.config as any).debug, true);
+  });
+
+  it('parent-relative path ../sibling resolves', async () => {
+    class Child {
+      static needs = { run: ['../settings'] };
+      run() {}
+    }
+
+    registerType('t.child', Child);
+
+    const store = createMemoryTree();
+    await store.set(createNode('/app/settings', 'cfg', { lang: 'en' }));
+    const node = createNode('/app/module', 'dir', {}, {
+      child: { $type: 't.child' },
+    });
+
+    const deps = await collectDeps(node, 'child', 'run', store);
+    assert.equal((deps.settings as any).$path, '/app/settings');
+    assert.equal((deps.settings as any).lang, 'en');
+  });
+
+  it('absolute path resolves', async () => {
+    class Widget {
+      static needs = { init: ['/sys/config'] };
+      init() {}
+    }
+
+    registerType('t.widget', Widget);
+
+    const store = createMemoryTree();
+    await store.set(createNode('/sys/config', 'cfg', { version: 2 }));
+    const node = createNode('/ui/widget', 'dir', {}, {
+      widget: { $type: 't.widget' },
+    });
+
+    const deps = await collectDeps(node, 'widget', 'init', store);
+    assert.equal((deps.config as any).$path, '/sys/config');
+    assert.equal((deps.config as any).version, 2);
+  });
+
+  it('./children/* returns array of child nodes', async () => {
+    class List {
+      static needs = { report: ['./items/*'] };
+      report() {}
+    }
+
+    registerType('t.list', List);
+
+    const store = createMemoryTree();
+    await store.set(createNode('/orders/1/items/a', 'item', { name: 'apple' }));
+    await store.set(createNode('/orders/1/items/b', 'item', { name: 'banana' }));
+    const node = createNode('/orders/1', 'order', {}, {
+      list: { $type: 't.list' },
+    });
+
+    const deps = await collectDeps(node, 'list', 'report', store);
+    assert.ok(Array.isArray(deps.items));
+    assert.equal((deps.items as any[]).length, 2);
+  });
+
+  it('mixed deps: siblings + cross-node', async () => {
+    class OrderStatus {
+      value = 'draft';
+      warehouseRef = '/config/wh';
+
+      static needs = {
+        advance: ['payment', '@warehouseRef', './items/*'],
+      };
+      advance() {}
+    }
+
+    registerType('t.order-status', OrderStatus);
+    registerType('t.payment', Payment);
+
+    const store = createMemoryTree();
+    await store.set(createNode('/config/wh', 'warehouse', { capacity: 50 }));
+    await store.set(createNode('/order/1/items/x', 'item', { qty: 3 }));
+
+    const node = createNode('/order/1', 'order', {}, {
+      status: { $type: 't.order-status', value: 'draft', warehouseRef: '/config/wh' },
+      payment: { $type: 't.payment', amount: 100, settled: false },
+    });
+
+    const deps = await collectDeps(node, 'status', 'advance', store);
+
+    // sibling
+    assert.equal((deps.payment as any).amount, 100);
+    // field-ref
+    assert.equal((deps.warehouseRef as any).$path, '/config/wh');
+    // children
+    assert.ok(Array.isArray(deps.items));
+    assert.equal((deps.items as any[]).length, 1);
+  });
+
+  it('empty needs = no deps', async () => {
+    class Simple {
+      static needs = { run: [] };
+      run() {}
+    }
+
+    registerType('t.simple', Simple);
+    const store = createMemoryTree();
+    const node = createNode('/x', 'dir', {}, { simple: { $type: 't.simple' } });
+
+    const deps = await collectDeps(node, 'simple', 'run', store);
+    assert.deepEqual(deps, {});
+  });
+
+  it('no static needs + no opts.needs = no deps', async () => {
+    class Plain { run() {} }
+    registerType('t.plain', Plain);
+    const store = createMemoryTree();
+    const node = createNode('/x', 'dir', {}, { plain: { $type: 't.plain' } });
+
+    const deps = await collectDeps(node, 'plain', 'run', store);
+    assert.deepEqual(deps, {});
+  });
+
+  // ── Fail-loud ──
+
+  it('throws on missing sibling', async () => {
+    class NeedsMissing {
+      static needs = { run: ['nonexistent'] };
+      run() {}
+    }
+    registerType('t.needs-missing', NeedsMissing);
+    const store = createMemoryTree();
+    const node = createNode('/x', 'dir', {}, { comp: { $type: 't.needs-missing' } });
+
+    await assert.rejects(() => collectDeps(node, 'comp', 'run', store));
+  });
+
+  it('throws on missing @fieldRef target', async () => {
+    class BadRef {
+      targetRef = '/nowhere';
+      static needs = { run: ['@targetRef'] };
+      run() {}
+    }
+    registerType('t.bad-ref', BadRef);
+    const store = createMemoryTree();
+    const node = createNode('/x', 'dir', {}, {
+      comp: { $type: 't.bad-ref', targetRef: '/nowhere' },
+    });
+
+    await assert.rejects(() => collectDeps(node, 'comp', 'run', store));
+  });
+
+  it('throws on missing path dep', async () => {
+    class BadPath {
+      static needs = { run: ['/missing/node'] };
+      run() {}
+    }
+    registerType('t.bad-path', BadPath);
+    const store = createMemoryTree();
+    const node = createNode('/x', 'dir', {}, { comp: { $type: 't.bad-path' } });
+
+    await assert.rejects(() => collectDeps(node, 'comp', 'run', store));
+  });
+
+  it('throws on @field that is not a string', async () => {
+    class BadField {
+      targetRef = 42;
+      static needs = { run: ['@targetRef'] };
+      run() {}
+    }
+    registerType('t.bad-field', BadField as any);
+    const store = createMemoryTree();
+    const node = createNode('/x', 'dir', {}, {
+      comp: { $type: 't.bad-field', targetRef: 42 },
+    });
+
+    await assert.rejects(() => collectDeps(node, 'comp', 'run', store));
+  });
+
+  it('throws on duplicate dep keys', async () => {
+    class DupKeys {
+      static needs = { run: ['payment', '/other/payment'] };
+      run() {}
+    }
+    registerType('t.dup', DupKeys);
+    registerType('t.payment', Payment);
+    const store = createMemoryTree();
+    await store.set(createNode('/other/payment', 'x'));
+    const node = createNode('/x', 'dir', {}, {
+      comp: { $type: 't.dup' },
+      payment: { $type: 't.payment', amount: 0, settled: false },
+    });
+
+    await assert.rejects(() => collectDeps(node, 'comp', 'run', store));
+  });
+});
+
+describe('collectSiblings backward compat', () => {
+  beforeEach(() => {
+    clearRegistry();
+
+  });
+
+  it('opts.needs still works via collectSiblings', () => {
+    class Meta { title = ''; rename() {} }
+    registerType('t.meta', Meta, { needs: ['status'] });
+    registerType('t.status', Status);
+
+    const node = createNode('/p', 'page', {}, {
+      meta: { $type: 't.meta', title: 'old' },
+      status: { $type: 't.status', value: 'draft' },
+    });
+
+    const siblings = collectSiblings(node, 'meta');
+    assert.equal(Object.keys(siblings).length, 1);
+    assert.equal((siblings.status as any).value, 'draft');
+  });
+});
+
+describe('executeAction with deps', () => {
+  beforeEach(() => {
+    clearRegistry();
+
+  });
+
+  it('per-action deps injected into method via executeAction', async () => {
+    class Article {
+      title = '';
+
+      static needs = {
+        publishAndRename: ['status'],
+      };
+
+      publishAndRename({ title }: { title: string }, deps: { status: any }) {
+        this.title = title;
+        deps.status.value = 'published';
+      }
+    }
+
+    registerType('t.article', Article);
+    registerType('t.status', Status);
+
+    const store = createMemoryTree();
+    await store.set(createNode('/a', 'page', {}, {
+      article: { $type: 't.article', title: 'old' },
+      status: { $type: 't.status', value: 'draft' },
+    }));
+
+    await executeAction(store, '/a', 't.article', undefined, 'publishAndRename', { title: 'new' });
+
+    const result = (await store.get('/a'))!;
+    assert.equal((result['article'] as any).title, 'new');
+    assert.equal((result['status'] as any).value, 'published');
+  });
+
+  it('different actions get different deps', async () => {
+    class Processor {
+      value = '';
+
+      static needs = {
+        quick: ['status'],
+        full: ['status', 'payment'],
+      };
+
+      quick(_d: unknown, deps: any) {
+        this.value = `status=${deps.status.value}`;
+      }
+
+      full(_d: unknown, deps: any) {
+        this.value = `status=${deps.status.value},amount=${deps.payment.amount}`;
+      }
+    }
+
+    registerType('t.processor', Processor);
+    registerType('t.status', Status);
+    registerType('t.payment', Payment);
+
+    const store = createMemoryTree();
+    await store.set(createNode('/p', 'page', {}, {
+      processor: { $type: 't.processor', value: '' },
+      status: { $type: 't.status', value: 'active' },
+      payment: { $type: 't.payment', amount: 500, settled: false },
+    }));
+
+    await executeAction(store, '/p', 't.processor', undefined, 'quick', {});
+    let result = (await store.get('/p'))!;
+    assert.equal((result['processor'] as any).value, 'status=active');
+
+    await executeAction(store, '/p', 't.processor', undefined, 'full', {});
+    result = (await store.get('/p'))!;
+    assert.equal((result['processor'] as any).value, 'status=active,amount=500');
+  });
+
+  it('cross-node @fieldRef in executeAction', async () => {
+    class Connector {
+      targetRef = '';
+      result = '';
+
+      static needs = { fetch: ['@targetRef'] };
+
+      fetch(_d: unknown, deps: any) {
+        this.result = deps.targetRef.$path;
+      }
+    }
+
+    registerType('t.connector', Connector);
+
+    const store = createMemoryTree();
+    await store.set(createNode('/config/wh', 'warehouse', { capacity: 50 }));
+    await store.set(createNode('/order/1', 'page', {}, {
+      connector: { $type: 't.connector', targetRef: '/config/wh', result: '' },
+    }));
+
+    await executeAction(store, '/order/1', 't.connector', undefined, 'fetch', {});
+
+    const result = (await store.get('/order/1'))!;
+    assert.equal((result['connector'] as any).result, '/config/wh');
+  });
+});

package/src/comp/needs.ts

@@ -0,0 +1,113 @@
+import { type ComponentData, getCompByKey, isComponent, type NodeData } from '#core';
+import { basename, dirname, join } from '#core/path';
+import { type Tree } from '#tree';
+
+// ── Types ──
+
+export type NeedSpec =
+  | { kind: 'sibling'; name: string; key: string }
+  | { kind: 'field-ref'; field: string; key: string }
+  | { kind: 'path'; path: string; key: string }
+  | { kind: 'children'; path: string; key: string };
+
+export type ResolvedDeps = Record<string, ComponentData | NodeData | NodeData[]>;
+
+// ── Needs store ──
+// Local map keyed by type@action. Populated by registerActionNeeds (called from registerType).
+// Separate from registry meta because needs are registered before actions exist in the registry.
+
+const needsMap = new Map<string, NeedSpec[]>();
+
+export function registerActionNeeds(type: string, action: string, patterns: string[]): void {
+  needsMap.set(`${type}@${action}`, patterns.map(parseNeedPattern));
+}
+
+export function getActionNeeds(type: string, action: string): NeedSpec[] {
+  return needsMap.get(`${type}@${action}`)
+    ?? needsMap.get(`${type}@*`)
+    ?? [];
+}
+
+// ── Pattern parsing ──
+
+export function parseNeedPattern(p: string): NeedSpec {
+  if (p.startsWith('@')) return { kind: 'field-ref', field: p.slice(1), key: p.slice(1) };
+  if (p.endsWith('/*')) return { kind: 'children', path: p.slice(0, -2), key: basename(p.slice(0, -2)) };
+  if (p[0] === '/' || p.startsWith('./') || p.startsWith('../')) return { kind: 'path', path: p, key: basename(p) };
+  return { kind: 'sibling', name: p, key: p };
+}
+
+function resolvePath(base: string, rel: string): string {
+  if (rel[0] === '/') return rel;
+  if (rel.startsWith('./')) return join(base, rel.slice(2));
+  if (!rel.startsWith('../')) throw new Error(`Invalid relative path: ${rel}`);
+  const parent = dirname(base);
+  if (!parent) throw new Error(`Cannot resolve "../" from root`);
+  return join(parent, rel.slice(3));
+}
+
+// ── Dependency collection ──
+
+export async function collectDeps(
+  node: NodeData, componentName: string, actionName: string, store: Tree,
+): Promise<ResolvedDeps> {
+  const cv = getCompByKey(node, componentName);
+  if (!cv) throw new Error(`Component "${componentName}" not found on ${node.$path}`);
+
+  const specs = getActionNeeds(cv.$type, actionName);
+  if (!specs.length) return {};
+
+  const deps: ResolvedDeps = {};
+  const async_: Promise<void>[] = [];
+
+  for (const s of specs) {
+    if (deps[s.key] !== undefined) throw new Error(`Duplicate dep key "${s.key}"`);
+
+    if (s.kind === 'sibling') {
+      const v = node[s.name];
+      if (!isComponent(v)) throw new Error(`Needed sibling "${s.name}" not found on ${node.$path}`);
+      deps[s.key] = v;
+      continue;
+    }
+
+    // cross-node: resolve target path, then fetch
+    let target: string;
+    if (s.kind === 'field-ref') {
+      target = (cv as Record<string, unknown>)[s.field] as string;
+      if (typeof target !== 'string') throw new Error(`Field "${s.field}" on ${componentName} is not a path string`);
+    } else {
+      target = resolvePath(node.$path, s.path);
+    }
+
+    if (s.kind === 'children') {
+      async_.push(store.getChildren(target).then(({ items }) => { deps[s.key] = items; }));
+    } else {
+      async_.push(store.get(target).then(n => {
+        if (!n) throw new Error(`Dep "${s.key}" → "${target}" not found`);
+        deps[s.key] = n;
+      }));
+    }
+  }
+
+  if (async_.length) await Promise.all(async_);
+  return deps;
+}
+
+// ── Backward compat ──
+
+export function collectSiblings(node: NodeData, componentName: string): Record<string, ComponentData> {
+  const cv = getCompByKey(node, componentName);
+  if (!cv) throw new Error(`Component "${componentName}" not found on ${node.$path}`);
+
+  const specs = getActionNeeds(cv.$type, '*');
+  if (!specs.length) return {};
+
+  const out: Record<string, ComponentData> = {};
+  for (const s of specs) {
+    if (s.kind !== 'sibling') continue;
+    const v = node[s.name];
+    if (!isComponent(v)) throw new Error(`Needed component "${s.name}" not found on ${node.$path}`);
+    out[s.key] = v;
+  }
+  return out;
+}