@treenity/core 1.0.48 → 3.0.0

package/src/comp/index.test.ts

@@ -0,0 +1,129 @@
+// Tests for getComp, setComp, newComp
+// Key behavior: when node.$type matches component $type, node itself IS the component.
+
+import { getComp, newComp, registerType, setComp } from '#comp';
+import { type NodeData } from '#core';
+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);
+
+// ── getComp ──
+
+describe('getComp', () => {
+  it('returns node itself when node.$type matches component type', () => {
+    const node: NodeData = { $path: '/a', $type: 'test.item', name: 'sword', quantity: 3 };
+    const comp = getComp(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 = getComp(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 = getComp(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(getComp(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');
+  });
+});

package/src/comp/index.ts

@@ -0,0 +1,175 @@
+// Treenity Component Registration — between core and server
+// registerType(type, cls) → stamps $type, registers class, auto-registers actions from methods
+
+import { registerActionNeeds } from '#comp/needs';
+import { type Class, ComponentData, getComponent, NodeData, normalizeType, register, resolve, type TypeId } from '#core';
+import { trackType } from '#mod/tracking';
+import { type Tree } from '#tree';
+
+export type { Class };
+export type TypeClass<T> = Class<T> & { $type: string };
+
+// Strip methods from a type — only keep data fields (recursive)
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+export type Raw<T> = { [K in keyof T as T[K] extends Function ? never : K]: T[K] extends (infer U)[] ? U extends object ? Raw<U>[] : T[K] : T[K] extends object ? Raw<T[K]> : T[K] };
+
+// Actions<T>: map class methods to typed async client signatures
+// Uses Parameters<>/ReturnType<> to avoid TypeScript's "() => T extends (x: D) => T" false-match.
+// Arity: Parameters<fn> extends [infer D, ...] → (data: D); else → ()
+// Internal `deps` second-arg is absorbed by `...any[]` and dropped from client type.
+// Generator methods (async *) → AsyncIterable<Y>; regular → Promise<R>
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+type _AnyFn = (...args: any[]) => any;
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+type _ToFn<T> = T extends _AnyFn ? T : never;
+
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+export type Actions<T> = {
+  [K in keyof T as T[K] extends Function ? K : never]:
+    ReturnType<_ToFn<T[K]>> extends AsyncGenerator<infer Y, any, any>
+      ? Parameters<_ToFn<T[K]>> extends [infer D, ...any[]]
+        ? (data: D) => AsyncIterable<Y>
+        : () => AsyncIterable<Y>
+    : Parameters<_ToFn<T[K]>> extends [infer D, ...any[]]
+      ? (data: D) => Promise<Awaited<ReturnType<_ToFn<T[K]>>>>
+      : () => Promise<Awaited<ReturnType<_ToFn<T[K]>>>>
+};
+
+// TypeProxy<T>: readonly data fields + async action methods
+export type TypeProxy<T> = Raw<T> & Actions<T>;
+
+declare module '#core/context' {
+  interface ContextHandlers {
+    class: Class<unknown>;
+  }
+}
+
+// ── Action context for class methods ──
+// Node.js: AsyncLocalStorage (survives await, concurrent-safe)
+// Browser: global _ctx fallback (safe — single-threaded, no concurrent actions)
+
+let _als: any = null;
+let _ctx: ExecCtx | null = null;
+
+// Async init — resolves before any action can fire (server boot is async).
+// Browser: import fails → _als stays null → falls back to _ctx global.
+import('node:async_hooks')
+  .then(m => { _als = new m.AsyncLocalStorage(); })
+  .catch(() => {});
+
+export type ExecCtx = { node: NodeData; store: Tree; signal: AbortSignal; [k: string]: unknown };
+
+export function getCtx(): ExecCtx {
+  const ctx = _als?.getStore() ?? _ctx;
+  if (!ctx) throw new Error('getCtx(): called outside action context');
+  return ctx;
+}
+
+// ── Registration ──
+
+// Port declaration: which component fields an action reads (pre) and writes (post).
+// Stored as registry meta on action:* contexts. Queried via comp/ports.ts and comp/planner.ts.
+export type PortDecl = { pre?: string[]; post?: string[] };
+type CompOptions = { needs?: string[]; ports?: Record<string, PortDecl> };
+
+export function registerType<T>(type: string, cls: Class<T>, opts?: CompOptions): TypeClass<T> {
+  const compClass = cls as TypeClass<T>;
+  compClass.$type = normalizeType(type);
+  // Bracket access in treeChain: proxy[Counter] → Proxy.get(_, "§app.counter")
+  (cls as any)[Symbol.toPrimitive] = () => `§${compClass.$type}`;
+  register(type, 'class', cls, opts);
+  trackType(compClass.$type);
+
+  // Per-action needs from static property on class
+  const staticNeeds = (cls as any).needs as Record<string, string[]> | undefined;
+  if (staticNeeds) {
+    for (const [action, patterns] of Object.entries(staticNeeds)) {
+      registerActionNeeds(type, action, patterns);
+    }
+  }
+
+  // opts.needs = global fallback ('*') for all actions
+  if (opts?.needs) registerActionNeeds(type, '*', opts.needs);
+
+  const proto = cls.prototype;
+  for (const name of Object.getOwnPropertyNames(proto)) {
+    if (name === 'constructor') continue;
+    if (typeof proto[name] === 'function') {
+      register(type, `action:${name}`, (ctx: any, data: unknown) => {
+        const target = ctx.comp ?? ctx.node;
+        if (_als) return _als.run(ctx, () => proto[name].call(target, data, ctx.deps));
+        _ctx = ctx;
+        try { return proto[name].call(target, data, ctx.deps); }
+        finally { _ctx = null; }
+      }, opts?.ports?.[name]);
+    }
+  }
+  return compClass;
+}
+
+// Register server-only actions from a class. _ prefixed = internal (hidden from clients).
+export function registerActions<T>(type: TypeId, cls: Class<T>, opts?: CompOptions): void {
+  const t = normalizeType(type);
+  const proto = cls.prototype;
+  for (const name of Object.getOwnPropertyNames(proto)) {
+    if (name === 'constructor') continue;
+    if (typeof proto[name] === 'function') {
+      register(t, `action:${name}`, (ctx: any, data: unknown) => {
+        const target = ctx.comp ?? ctx.node;
+        if (_als) return _als.run(ctx, () => proto[name].call(target, data, ctx.deps));
+        _ctx = ctx;
+        try { return proto[name].call(target, data, ctx.deps); }
+        finally { _ctx = null; }
+      }, opts?.ports?.[name]);
+    }
+  }
+}
+
+// ── Type-safe component access ──
+
+// Alias for getComponent (unified in L0)
+export { getComponent as getComp };
+
+export function setComp<T>(node: NodeData, cls: Class<T>, data: Partial<Raw<T>>, field?: string): void {
+  const comp = getComponent(node, cls, field);
+  if (comp) {
+    Object.assign(comp as object, data);
+  } else {
+    const $type = normalizeType(cls);
+    const name = field ?? $type.split('.').at(-1)!;
+    if (node[name]) throw new Error(`Component ${name} already exists on ${node.$path}`);
+    node[name] = newComp<T>(cls, data);
+  }
+}
+
+export function newComp<T>(cls: Class<T>, data: Partial<Raw<T>>): ComponentData<T> {
+  const $type = normalizeType(cls);
+  return Object.assign({ $type }, data, { $type }) as ComponentData<T>;
+}
+
+// Get default field values for a type: class instance fields → schema defaults → {}
+export function getDefaults<T = any>(type: TypeId<T>): Partial<Raw<T>> {
+  type R = Partial<Raw<T>>;
+
+  // 1. Try registered class — new Class() gives field initializers
+  const cls = resolve(type, 'class');
+  if (cls) {
+    const inst = new cls();
+    return Object.assign({}, inst) as R;
+  }
+
+  // 2. Fall back to JSON schema defaults
+  const schemaHandler = resolve(type, 'schema');
+  if (schemaHandler) {
+    const schema = schemaHandler() as { properties?: Record<string, { default?: unknown }> };
+    if (schema?.properties) {
+      const out: Record<string, unknown> = {};
+      for (const [k, prop] of Object.entries(schema.properties)) {
+        if ('default' in prop) out[k] = prop.default;
+      }
+      return out as R;
+    }
+  }
+
+  return {} as R;
+}