@jesscss/core 2.0.0-alpha.4 → 2.0.0-alpha.6

package/src/tree/__tests__/node-flags-perf.test.ts

@@ -0,0 +1,195 @@
+import { describe, it, expect } from 'vitest';
+import { performance } from 'node:perf_hooks';
+import {
+  Node,
+  F_STATIC,
+  F_NON_STATIC,
+  F_MAY_ASYNC,
+  any,
+  dimension,
+  num,
+  list,
+  paren,
+  expr,
+  seq,
+  decl,
+  ref
+} from '../index.js';
+import { Context } from '../../context.js';
+import { pipe } from '@jesscss/awaitable-pipe';
+import { isEvaluated, isPreEvaluated, setEvaluated, setPreEvaluated } from '../util/field-helpers.js';
+
+function fmt(ms: number) {
+  return `${ms.toFixed(3)}ms`;
+}
+
+function buildStaticTree(depth: number, breadth: number): Node {
+  if (depth === 0) {
+    return any(`leaf`);
+  }
+  const children: Node[] = [];
+  for (let i = 0; i < breadth; i++) {
+    children.push(buildStaticTree(depth - 1, breadth));
+  }
+  return list(children);
+}
+
+function buildDeclTree(count: number, staticRatio: number = 1.0): Node[] {
+  const decls: Node[] = [];
+  for (let i = 0; i < count; i++) {
+    if (i / count < staticRatio) {
+      decls.push(
+        decl({
+          name: any(`prop-${i}`, { role: 'property' }),
+          value: expr(any(`value-${i}`))
+        })
+      );
+    } else {
+      decls.push(
+        decl({
+          name: any(`prop-${i}`, { role: 'property' }),
+          value: expr(ref({ key: any(`var-${i}`) }))
+        })
+      );
+    }
+  }
+  return decls;
+}
+
+function evalStaticLegacy(node: Node, context: Context): any {
+  let preEvaluatedNode: Node;
+
+  return pipe(
+    () => {
+      if (!isPreEvaluated(node, context)) {
+        return node.preEval(context);
+      }
+      return node;
+    },
+    (preEvald: Node) => {
+      preEvaluatedNode = preEvald;
+      setPreEvaluated(preEvaluatedNode, true, context);
+      if (preEvald !== node) {
+        preEvaluatedNode.inherit(node);
+      }
+      if (!isEvaluated(preEvaluatedNode, context)) {
+        return preEvaluatedNode['evalNode'](context);
+      }
+      return preEvaluatedNode;
+    },
+    (evald: Node) => {
+      setEvaluated(evald, true, context);
+      if (preEvaluatedNode !== evald) {
+        evald.inherit(preEvaluatedNode);
+      }
+      return evald;
+    }
+  );
+}
+
+describe('Node Flags Performance', () => {
+  it('should verify static trees have correct flags', () => {
+    const tree = buildStaticTree(3, 4);
+    expect(tree.hasFlag(F_STATIC)).toBe(true);
+    expect(tree.hasFlag(F_MAY_ASYNC)).toBe(false);
+    expect(tree.hasFlag(F_NON_STATIC)).toBe(false);
+  });
+
+  it('sync fast-path: static tree eval should be sync', () => {
+    const context = new Context();
+    const tree = buildStaticTree(4, 5);
+    const result = Node.evalStatic(tree, context);
+    expect(result).not.toBeInstanceOf(Promise);
+  });
+
+  it('benchmark: optimized vs legacy evalStatic for static declarations', () => {
+    const iterations = 1000;
+
+    // Optimized path
+    {
+      const context = new Context();
+      const declSets = Array.from({ length: iterations }, () => buildDeclTree(10, 1.0));
+      const start = performance.now();
+      for (let i = 0; i < iterations; i++) {
+        for (const d of declSets[i]!) {
+          void Node.evalStatic(d, context);
+        }
+      }
+      const optimized = performance.now() - start;
+      console.log(`  Optimized: ${fmt(optimized)} for ${iterations * 10} static decls`);
+    }
+
+    // Legacy path (always uses pipe)
+    {
+      const context = new Context();
+      const declSets = Array.from({ length: iterations }, () => buildDeclTree(10, 1.0));
+      const start = performance.now();
+      for (let i = 0; i < iterations; i++) {
+        for (const d of declSets[i]!) {
+          void evalStaticLegacy(d, context);
+        }
+      }
+      const legacy = performance.now() - start;
+      console.log(`  Legacy:    ${fmt(legacy)} for ${iterations * 10} static decls`);
+    }
+  });
+
+  it('benchmark: optimized vs legacy evalStatic for static trees', () => {
+    const iterations = 200;
+
+    // Optimized path
+    {
+      const context = new Context();
+      const trees = Array.from({ length: iterations }, () => buildStaticTree(3, 5));
+      const start = performance.now();
+      for (let i = 0; i < iterations; i++) {
+        void Node.evalStatic(trees[i]!, context);
+      }
+      const optimized = performance.now() - start;
+      console.log(`  Optimized: ${fmt(optimized)} for ${iterations} static trees (depth=3, breadth=5)`);
+    }
+
+    // Legacy path
+    {
+      const context = new Context();
+      const trees = Array.from({ length: iterations }, () => buildStaticTree(3, 5));
+      const start = performance.now();
+      for (let i = 0; i < iterations; i++) {
+        void evalStaticLegacy(trees[i]!, context);
+      }
+      const legacy = performance.now() - start;
+      console.log(`  Legacy:    ${fmt(legacy)} for ${iterations} static trees (depth=3, breadth=5)`);
+    }
+  });
+
+  it('benchmark: re-eval already-evaluated static nodes should be near-zero', () => {
+    const context = new Context();
+    const tree = buildStaticTree(4, 5);
+
+    void Node.evalStatic(tree, context);
+
+    const iterations = 10000;
+    const start = performance.now();
+    for (let i = 0; i < iterations; i++) {
+      void Node.evalStatic(tree, context);
+    }
+    const elapsed = performance.now() - start;
+
+    console.log(`  Re-eval static tree: ${fmt(elapsed)} for ${iterations} calls (${fmt(elapsed / iterations)}/call)`);
+    expect(elapsed).toBeLessThan(100);
+  });
+
+  it('flag propagation: count nodes with correct flags in a large tree', () => {
+    const tree = buildStaticTree(4, 5);
+    let staticCount = 0;
+    let totalCount = 0;
+    for (const node of tree.nodes()) {
+      totalCount++;
+      if (node.hasFlag(F_STATIC)) {
+        staticCount++;
+      }
+    }
+    console.log(`  Flag coverage: ${staticCount}/${totalCount} nodes are F_STATIC (${(staticCount / totalCount * 100).toFixed(1)}%)`);
+    expect(staticCount).toBe(totalCount);
+  });
+});

package/src/tree/__tests__/node-flags.test.ts

@@ -0,0 +1,410 @@
+import {
+  F_STATIC,
+  F_NON_STATIC,
+  F_MAY_ASYNC,
+  any,
+  dimension,
+  num,
+  color,
+  bool,
+  comment,
+  co,
+  nil,
+  list,
+  paren,
+  expr,
+  seq,
+  ref,
+  interpolated,
+  call,
+  op,
+  decl,
+  quoted,
+  url,
+  block
+} from '../index.js';
+
+describe('Node Flags', () => {
+  describe('leaf node flag assignment', () => {
+    it('Any should be F_STATIC', () => {
+      const node = any('hello');
+      expect(node.hasFlag(F_STATIC)).toBe(true);
+      expect(node.hasFlag(F_NON_STATIC)).toBe(false);
+      expect(node.hasFlag(F_MAY_ASYNC)).toBe(false);
+    });
+
+    it('Dimension should be F_STATIC', () => {
+      const node = dimension([10, 'px']);
+      expect(node.hasFlag(F_STATIC)).toBe(true);
+      expect(node.hasFlag(F_NON_STATIC)).toBe(false);
+      expect(node.hasFlag(F_MAY_ASYNC)).toBe(false);
+    });
+
+    it('Num should be F_STATIC', () => {
+      const node = num(42);
+      expect(node.hasFlag(F_STATIC)).toBe(true);
+      expect(node.hasFlag(F_NON_STATIC)).toBe(false);
+    });
+
+    it('Color should be F_STATIC', () => {
+      const node = color([255, 0, 0, 1]);
+      expect(node.hasFlag(F_STATIC)).toBe(true);
+      expect(node.hasFlag(F_NON_STATIC)).toBe(false);
+      expect(node.hasFlag(F_MAY_ASYNC)).toBe(false);
+    });
+
+    it('Bool should be F_STATIC', () => {
+      const node = bool(true);
+      expect(node.hasFlag(F_STATIC)).toBe(true);
+      expect(node.hasFlag(F_NON_STATIC)).toBe(false);
+    });
+
+    it('Comment should be F_STATIC', () => {
+      const node = comment('/* test */');
+      expect(node.hasFlag(F_STATIC)).toBe(true);
+      expect(node.hasFlag(F_NON_STATIC)).toBe(false);
+    });
+
+    it('Combinator should be F_STATIC', () => {
+      const node = co('>');
+      expect(node.hasFlag(F_STATIC)).toBe(true);
+      expect(node.hasFlag(F_NON_STATIC)).toBe(false);
+    });
+
+    it('Nil should be F_STATIC (invisible but static)', () => {
+      const node = nil();
+      expect(node.hasFlag(F_STATIC)).toBe(true);
+      expect(node.hasFlag(F_NON_STATIC)).toBe(false);
+    });
+  });
+
+  describe('non-static node flag assignment', () => {
+    it('Reference should be F_NON_STATIC and F_MAY_ASYNC', () => {
+      const node = ref({ key: any('color') });
+      expect(node.hasFlag(F_NON_STATIC)).toBe(true);
+      expect(node.hasFlag(F_MAY_ASYNC)).toBe(true);
+      expect(node.hasFlag(F_STATIC)).toBe(false);
+    });
+
+    it('Interpolated should be F_NON_STATIC and F_MAY_ASYNC', () => {
+      const node = interpolated({
+        source: 'hello%%',
+        replacements: [ref({ key: any('name') })]
+      });
+      expect(node.hasFlag(F_NON_STATIC)).toBe(true);
+      expect(node.hasFlag(F_MAY_ASYNC)).toBe(true);
+      expect(node.hasFlag(F_STATIC)).toBe(false);
+    });
+
+    it('Operation should be F_NON_STATIC', () => {
+      const node = op([dimension([10, 'px']), '+', dimension([5, 'px'])]);
+      expect(node.hasFlag(F_NON_STATIC)).toBe(true);
+      expect(node.hasFlag(F_STATIC)).toBe(false);
+    });
+
+    it('Call should be F_NON_STATIC and F_MAY_ASYNC', () => {
+      const node = call({ name: 'rgb', args: list([num(255), num(0), num(0)]) });
+      expect(node.hasFlag(F_NON_STATIC)).toBe(true);
+      expect(node.hasFlag(F_MAY_ASYNC)).toBe(true);
+      expect(node.hasFlag(F_STATIC)).toBe(false);
+    });
+  });
+
+  describe('flag bubbling via adopt()', () => {
+    it('container with all-static children should get F_STATIC', () => {
+      const items = [any('hello'), any('world')];
+      const node = list(items);
+      expect(node.hasFlag(F_STATIC)).toBe(true);
+      expect(node.hasFlag(F_NON_STATIC)).toBe(false);
+      expect(node.hasFlag(F_MAY_ASYNC)).toBe(false);
+    });
+
+    it('container with one non-static child should get F_NON_STATIC', () => {
+      const items = [any('hello'), ref({ key: any('name') })];
+      const node = list(items as any);
+      expect(node.hasFlag(F_NON_STATIC)).toBe(true);
+      expect(node.hasFlag(F_STATIC)).toBe(false);
+    });
+
+    it('container with one async child should get F_MAY_ASYNC', () => {
+      const items = [any('hello'), ref({ key: any('name') })];
+      const node = list(items as any);
+      expect(node.hasFlag(F_MAY_ASYNC)).toBe(true);
+    });
+
+    it('F_NON_STATIC takes precedence over F_STATIC', () => {
+      const items = [any('static-child'), ref({ key: any('dynamic') })];
+      const node = list(items as any);
+      expect(node.hasFlag(F_NON_STATIC)).toBe(true);
+      expect(node.hasFlag(F_STATIC)).toBe(false);
+    });
+
+    it('nested static containers should bubble F_STATIC up', () => {
+      const inner = list([any('a'), any('b')]);
+      const outer = paren(inner);
+      expect(inner.hasFlag(F_STATIC)).toBe(true);
+      expect((outer as any).hasFlag(F_STATIC)).toBe(true);
+      expect((outer as any).hasFlag(F_NON_STATIC)).toBe(false);
+    });
+
+    it('nested non-static containers should bubble F_NON_STATIC up', () => {
+      const inner = list([any('a'), ref({ key: any('x') })] as any);
+      const outer = paren(inner);
+      expect((outer as any).hasFlag(F_NON_STATIC)).toBe(true);
+      expect((outer as any).hasFlag(F_STATIC)).toBe(false);
+    });
+
+    it('F_MAY_ASYNC should bubble through multiple levels', () => {
+      const r = ref({ key: any('x') });
+      const inner = list([r] as any);
+      const outer = paren(inner);
+      expect((outer as any).hasFlag(F_MAY_ASYNC)).toBe(true);
+    });
+
+    it('expression is always F_NON_STATIC (needs unwrapping)', () => {
+      const node = expr(any('hello'));
+      expect(node.hasFlag(F_NON_STATIC)).toBe(true);
+      expect(node.hasFlag(F_STATIC)).toBe(false);
+    });
+
+    it('sequence with all static children should be F_STATIC', () => {
+      const node = seq([any('a'), any('b')]);
+      expect(node.hasFlag(F_STATIC)).toBe(true);
+    });
+
+    it('Declaration with expr value gets F_NON_STATIC from Expression', () => {
+      const d = decl({
+        name: any('color', { role: 'property' }),
+        value: expr(any('red'))
+      });
+      expect(d.hasFlag(F_NON_STATIC)).toBe(true);
+      expect(d.hasFlag(F_STATIC)).toBe(false);
+      expect(d.hasFlag(F_MAY_ASYNC)).toBe(false);
+    });
+
+    it('Declaration with direct static value (no expr) should be F_STATIC', () => {
+      const d = decl({
+        name: any('color', { role: 'property' }),
+        value: any('red')
+      });
+      expect(d.hasFlag(F_STATIC)).toBe(true);
+      expect(d.hasFlag(F_NON_STATIC)).toBe(false);
+    });
+
+    it('Declaration with interpolated name should be F_NON_STATIC', () => {
+      const d = decl({
+        name: interpolated({
+          source: 'col%%',
+          replacements: [ref({ key: any('suffix') })]
+        }),
+        value: expr(any('red'))
+      });
+      expect(d.hasFlag(F_NON_STATIC)).toBe(true);
+      expect(d.hasFlag(F_MAY_ASYNC)).toBe(true);
+    });
+
+    it('Declaration with non-static value should be F_NON_STATIC', () => {
+      const d = decl({
+        name: any('color', { role: 'property' }),
+        value: expr(ref({ key: any('main-color') }))
+      });
+      expect(d.hasFlag(F_NON_STATIC)).toBe(true);
+      expect(d.hasFlag(F_MAY_ASYNC)).toBe(true);
+    });
+  });
+
+  describe('flag exclusivity', () => {
+    it('addFlag(F_STATIC) is a no-op when F_NON_STATIC is set', () => {
+      const node = any('test');
+      node.addFlag(F_NON_STATIC);
+      node.addFlag(F_STATIC);
+      expect(node.hasFlag(F_NON_STATIC)).toBe(true);
+      expect(node.hasFlag(F_STATIC)).toBe(false);
+    });
+
+    it('addFlag(F_NON_STATIC) removes F_STATIC', () => {
+      const node = any('test');
+      expect(node.hasFlag(F_STATIC)).toBe(true);
+      node.addFlag(F_NON_STATIC);
+      expect(node.hasFlag(F_NON_STATIC)).toBe(true);
+      expect(node.hasFlag(F_STATIC)).toBe(false);
+    });
+  });
+
+  describe('Quoted flag behavior', () => {
+    it('Quoted with string value should be F_STATIC', () => {
+      const node = quoted('"hello world"');
+      expect(node.hasFlag(F_STATIC)).toBe(true);
+      expect(node.hasFlag(F_NON_STATIC)).toBe(false);
+    });
+
+    it('Quoted with interpolation should be F_NON_STATIC', () => {
+      const interp = interpolated({
+        source: 'hello%%',
+        replacements: [ref({ key: any('name') })]
+      });
+      const node = quoted(interp);
+      expect(node.hasFlag(F_NON_STATIC)).toBe(true);
+      expect(node.hasFlag(F_MAY_ASYNC)).toBe(true);
+    });
+  });
+
+  describe('Url flag behavior', () => {
+    it('Url with static quoted path should be F_STATIC', () => {
+      const node = url(quoted('"image.png"'));
+      expect(node.hasFlag(F_STATIC)).toBe(true);
+    });
+
+    it('Url with static Any path should be F_STATIC', () => {
+      const node = url(any('image.png'));
+      expect(node.hasFlag(F_STATIC)).toBe(true);
+    });
+  });
+
+  describe('Block flag behavior', () => {
+    it('Block with static child should be F_STATIC', () => {
+      const node = block(any('test'));
+      expect(node.hasFlag(F_STATIC)).toBe(true);
+    });
+
+    it('Block with non-static child should be F_NON_STATIC', () => {
+      const node = block(ref({ key: any('x') }));
+      expect(node.hasFlag(F_NON_STATIC)).toBe(true);
+    });
+  });
+
+  describe('Paren flag behavior', () => {
+    it('non-escaped Paren with static child inherits F_STATIC', () => {
+      const node = paren(any('hello'));
+      expect((node as any).hasFlag(F_STATIC)).toBe(true);
+      expect((node as any).hasFlag(F_NON_STATIC)).toBe(false);
+    });
+
+    it('escaped Paren is always F_NON_STATIC', () => {
+      const node = paren(any('hello'), { escaped: true });
+      expect((node as any).hasFlag(F_NON_STATIC)).toBe(true);
+      expect((node as any).hasFlag(F_STATIC)).toBe(false);
+    });
+
+    it('Paren with non-static child gets F_NON_STATIC', () => {
+      const node = paren(ref({ key: any('x') }));
+      expect((node as any).hasFlag(F_NON_STATIC)).toBe(true);
+      expect((node as any).hasFlag(F_MAY_ASYNC)).toBe(true);
+    });
+  });
+
+  describe('Quoted escaped flag behavior', () => {
+    it('escaped Quoted with string value is F_NON_STATIC', () => {
+      const node = quoted('2/1', { escaped: true });
+      expect(node.hasFlag(F_NON_STATIC)).toBe(true);
+      expect(node.hasFlag(F_STATIC)).toBe(false);
+    });
+
+    it('non-escaped Quoted with string value is F_STATIC', () => {
+      const node = quoted('hello');
+      expect(node.hasFlag(F_STATIC)).toBe(true);
+      expect(node.hasFlag(F_NON_STATIC)).toBe(false);
+    });
+  });
+
+  describe('Expression always non-static', () => {
+    it('Expression wrapping static Any is still F_NON_STATIC', () => {
+      const node = expr(any('hello'));
+      expect(node.hasFlag(F_NON_STATIC)).toBe(true);
+      expect(node.hasFlag(F_STATIC)).toBe(false);
+    });
+
+    it('Expression wrapping Dimension is F_NON_STATIC', () => {
+      const node = expr(dimension({ number: 42, unit: 'px' }));
+      expect(node.hasFlag(F_NON_STATIC)).toBe(true);
+    });
+
+    it('Expression wrapping Reference is F_NON_STATIC and F_MAY_ASYNC', () => {
+      const node = expr(ref({ key: any('x') }));
+      expect(node.hasFlag(F_NON_STATIC)).toBe(true);
+      expect(node.hasFlag(F_MAY_ASYNC)).toBe(true);
+    });
+  });
+
+  describe('composed containers', () => {
+    it('list of static values is F_STATIC', () => {
+      const node = list([any('a'), any('b'), dimension({ number: 1 })]);
+      expect(node.hasFlag(F_STATIC)).toBe(true);
+      expect(node.hasFlag(F_NON_STATIC)).toBe(false);
+    });
+
+    it('list with one non-static child gets F_NON_STATIC', () => {
+      const node = list([any('a'), ref({ key: any('b') })]);
+      expect(node.hasFlag(F_NON_STATIC)).toBe(true);
+      expect(node.hasFlag(F_STATIC)).toBe(false);
+    });
+
+    it('sequence of static values is F_STATIC', () => {
+      const node = seq([any('a'), any('b')]);
+      expect(node.hasFlag(F_STATIC)).toBe(true);
+    });
+
+    it('sequence with expression child gets F_NON_STATIC', () => {
+      const node = seq([any('a'), expr(any('b'))]);
+      expect(node.hasFlag(F_NON_STATIC)).toBe(true);
+      expect(node.hasFlag(F_STATIC)).toBe(false);
+    });
+
+    it('Declaration wrapping expr(ref()) gets F_NON_STATIC and F_MAY_ASYNC', () => {
+      const d = decl({
+        name: any('color', { role: 'property' }),
+        value: expr(ref({ key: any('main-color') }))
+      });
+      expect(d.hasFlag(F_NON_STATIC)).toBe(true);
+      expect(d.hasFlag(F_MAY_ASYNC)).toBe(true);
+    });
+
+    it('Declaration with static name and value (no expr wrapper) is F_STATIC', () => {
+      const d = decl({
+        name: any('color', { role: 'property' }),
+        value: any('red')
+      });
+      expect(d.hasFlag(F_STATIC)).toBe(true);
+    });
+
+    it('nested lists: list(list(static)) is F_STATIC', () => {
+      const inner = list([any('a'), any('b')]);
+      const outer = list([inner, any('c')]);
+      expect(outer.hasFlag(F_STATIC)).toBe(true);
+    });
+
+    it('nested lists: list(list(ref())) is F_NON_STATIC', () => {
+      const inner = list([any('a'), ref({ key: any('x') })]);
+      const outer = list([inner, any('c')]);
+      expect(outer.hasFlag(F_NON_STATIC)).toBe(true);
+      expect(outer.hasFlag(F_MAY_ASYNC)).toBe(true);
+    });
+
+    it('paren(expr(static)) is F_NON_STATIC because of Expression', () => {
+      const node = paren(expr(any('foo')));
+      expect((node as any).hasFlag(F_NON_STATIC)).toBe(true);
+    });
+
+    it('Combinator is always F_STATIC', () => {
+      const node = co(' ');
+      expect(node.hasFlag(F_STATIC)).toBe(true);
+    });
+
+    it('escaped paren wrapping escaped quoted is F_NON_STATIC', () => {
+      const node = paren(quoted('2/1', { escaped: true }), { escaped: true });
+      expect((node as any).hasFlag(F_NON_STATIC)).toBe(true);
+    });
+
+    it('F_VISIBLE is preserved when adding F_STATIC', () => {
+      const node = any('hello');
+      expect(node.hasFlag(F_STATIC)).toBe(true);
+      expect(node.visible).toBe(true);
+    });
+
+    it('F_VISIBLE is preserved when adding F_NON_STATIC', () => {
+      const node = expr(any('hello'));
+      expect(node.hasFlag(F_NON_STATIC)).toBe(true);
+      expect(node.visible).toBe(true);
+    });
+  });
+});