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

package/src/tree/util/collections.ts

@@ -0,0 +1,299 @@
+/**
+ * Originally I had custom Hashmaps and ArrayLists, in order to normalize
+ * generators and iterators for each. But using non-native collections
+ * adds complexity but, more importantly, performance overhead, especially
+ * if you don't use those iterators.
+ *
+ * Even using a Map over an object for a dictionary, in theory, has faster
+ * lookups, but in total evaluation time, when the file is parsed, it would
+ * be passing in either a Map or an object, and converting the object
+ * to a map has object creation overhead, and so does creating the map itself,
+ * if you pass in an array of arrays.
+ *
+ * Maps are good for dynamic property additions and repeated lookups. Nodes
+ * look up / evaluate properties, at most, once per node, so an object-as-map
+ * will either be faster or the differences will be negligible.
+ *
+ * So now, data is exceedingly simple. It's all passed in as is when parsing or
+ * using the API, and we just have some utility functions in this file to iterate over
+ * arrays / objects / simple values and return the values or entries, in any order.
+ */
+import type { ConditionalExcept } from 'type-fest';
+import { isNode } from './is-node.js';
+import { N } from '../node-type.js';
+import type { Mixin } from '../mixin.js';
+import type { Rules } from '../rules.js';
+import type { Ruleset } from '../ruleset.js';
+import type { Node } from '../node.js';
+
+const { isArray } = Array;
+
+/** Fast replacement for lodash isPlainObject — checks constructor === Object */
+export const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && value.constructor === Object;
+
+export function atIndex<T>(array: readonly T[], index: number = -1): T | undefined {
+  if (index >= 0) {
+    return array[index];
+  }
+  /** Use a negative index to access from the last element */
+  return array[array.length + index];
+}
+
+/**
+ * Entry generators, and this type will yield
+ *   - [0] the value
+ *   - [1] the key, if applicable, or the key '__value' for non-objects
+ *   - [2] the containing object.
+ *
+ * The purpose of this structure is to iterate and allow replacement
+ * of the value in its containing object.
+ *
+ * The function logic should mirror this type logic.
+ */
+type GetEntriesOf<T> = T extends readonly any[]
+  ? [T[number], number, T]
+  : T extends Node
+    ? [Node, Node, Rules]
+    : T extends Record<string, infer RecordValue>
+      ? RecordValue extends readonly any[]
+        ? [RecordValue[number], number, RecordValue]
+        : [RecordValue, keyof ConditionalExcept<T, readonly any[]>, T]
+      : [T, 'data', T];
+
+// type Test = GetEntriesOf<Node<string>>
+// type Test2 = GetEntriesOf<Node<string[]>>
+// type Test3 = GetEntriesOf<Node<{ selector: Node[], foo: 'string' }>>
+
+export function* getValues<T>(collection: T, reverse = false): Generator<GetEntriesOf<{ data: T }>[0]> {
+  if (isArray(collection)) {
+    if (reverse) {
+      for (let i = collection.length - 1; i >= 0; i--) {
+        yield collection[i]!;
+      }
+    } else {
+      let length = collection.length;
+      for (let i = 0; i < length; i++) {
+        yield collection[i]!;
+      }
+    }
+  } else if (isPlainObject(collection)) {
+    const values = Object.values(collection as Record<string, unknown>);
+    for (let value of values) {
+      if (isArray(value)) {
+        yield* getValues(value, reverse);
+      } else {
+        yield value;
+      }
+    }
+  } else {
+    yield collection;
+  }
+}
+
+export function* getEntries<T>(collection: T, reverse = false): Generator<GetEntriesOf<T>> {
+  if (isArray(collection)) {
+    if (reverse) {
+      for (let i = collection.length - 1; i >= 0; i--) {
+        yield [collection[i]!, i, collection] as GetEntriesOf<T>;
+      }
+    } else {
+      let length = collection.length;
+      for (let i = 0; i < length; i++) {
+        yield [collection[i]!, i, collection] as GetEntriesOf<T>;
+      }
+    }
+  } else if (isPlainObject(collection)) {
+    const entries = Object.entries(collection as Record<string, unknown>);
+    for (let [key, value] of entries) {
+      if (isArray(value)) {
+        yield* getEntries(value, reverse) as Generator<GetEntriesOf<T>>;
+      } else {
+        yield [value, key, collection] as GetEntriesOf<T>;
+      }
+    }
+  } else if (isNode(collection, N.Mixin | N.Ruleset | N.Rules)) {
+    let rules: Node[];
+    if ((collection as Node).type === 'Mixin') {
+      if ((collection as Mixin).get('params')?.length) {
+        throw new Error('We can\'t iterate over a mixin with parameters');
+      }
+      rules = [...(collection as Mixin).get('rules').value];
+    } else if ((collection as Node).type === 'Ruleset') {
+      rules = [...(collection as Ruleset).get('rules').value];
+    } else if ((collection as Node).type === 'Rules') {
+      rules = [...(collection as Rules).value];
+    }
+    for (let [, value] of rules!.entries()) {
+      if (value.type === 'Comment') {
+        continue;
+      }
+      if (!isNode(value, N.Declaration)) {
+        throw new Error('We can\'t iterate over rules with non-declarations');
+      }
+      yield [value.value, value.name, rules!] as unknown as GetEntriesOf<T>;
+    }
+  } else if (isNode(collection) && isArray((collection as Rules).value)) {
+    yield* getEntries((collection as Rules).value as unknown[], reverse) as Generator<GetEntriesOf<T>>;
+  } else {
+    yield [collection, 'value', collection] as unknown as GetEntriesOf<T>;
+  }
+}
+
+export function arraysEqual(a: string[], b: string[]) {
+  if (a.length !== b.length) {
+    return false;
+  }
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) {
+      return false;
+    }
+  }
+  return true;
+}
+
+type TraversalFrame = {
+  items: Node[];
+  index: number;
+};
+
+type TraversalMark = {
+  stack: TraversalFrame[];
+};
+
+type NodeTraversalOptions = {
+  includeSelf?: boolean;
+  deep?: boolean;
+  reverse?: boolean;
+  includePrePost?: boolean;
+};
+
+function cloneFrames(frames: TraversalFrame[]): TraversalFrame[] {
+  return frames.map(frame => ({
+    items: frame.items,
+    index: frame.index
+  }));
+}
+
+function collectDirectNodes(
+  node: Node,
+  reverse = false,
+  includePrePost = false
+): Node[] {
+  const result: Node[] = [];
+  const keys = (node.constructor as typeof Node).childKeys;
+
+  if (keys) {
+    const keyList = reverse ? [...keys].reverse() : keys;
+
+    for (const key of keyList) {
+      // Read from instance field directly (node[key]) instead of node.data[key],
+      // because array containers' .data getter returns the array itself, not { value: array }.
+      const nodeVal = (node as unknown as Record<string, unknown>)[key!];
+      if (isArray(nodeVal)) {
+        const items = reverse ? [...nodeVal].reverse() : nodeVal;
+        for (const item of items) {
+          if (isNode(item)) {
+            if (includePrePost) {
+              result.push(...item.nodeAndPrePost());
+            } else {
+              result.push(item);
+            }
+          }
+        }
+      } else if (isNode(nodeVal)) {
+        if (includePrePost) {
+          result.push(...nodeVal.nodeAndPrePost());
+        } else {
+          result.push(nodeVal);
+        }
+      }
+    }
+  }
+  // Leaf nodes (keys === null) have no child nodes to collect
+
+  return result;
+}
+
+export class NodeTraversalCursor implements IterableIterator<Node> {
+  private stack: TraversalFrame[] = [];
+  private readonly deep: boolean;
+  private readonly reverse: boolean;
+  private readonly includePrePost: boolean;
+
+  constructor(root: Node, options: NodeTraversalOptions = {}) {
+    const {
+      includeSelf = false,
+      deep = false,
+      reverse = false,
+      includePrePost = false
+    } = options;
+
+    this.deep = deep;
+    this.reverse = reverse;
+    this.includePrePost = includePrePost;
+
+    const initialItems = includeSelf
+      ? includePrePost
+        ? [...root.nodeAndPrePost()]
+        : [root]
+      : collectDirectNodes(root, reverse, includePrePost);
+
+    this.stack.push({
+      items: initialItems,
+      index: 0
+    });
+  }
+
+  [Symbol.iterator](): IterableIterator<Node> {
+    return this;
+  }
+
+  next(): IteratorResult<Node> {
+    while (this.stack.length > 0) {
+      const frame = this.stack[this.stack.length - 1]!;
+
+      if (frame.index >= frame.items.length) {
+        this.stack.pop();
+        continue;
+      }
+
+      const node = frame.items[frame.index++]!;
+
+      if (this.deep) {
+        const children = collectDirectNodes(
+          node,
+          this.reverse,
+          this.includePrePost
+        );
+
+        if (children.length > 0) {
+          this.stack.push({
+            items: children,
+            index: 0
+          });
+        }
+      }
+
+      return {
+        done: false,
+        value: node
+      };
+    }
+
+    return {
+      done: true,
+      value: undefined as never
+    };
+  }
+
+  mark(): TraversalMark {
+    return {
+      stack: cloneFrames(this.stack)
+    };
+  }
+
+  restore(mark: TraversalMark): void {
+    this.stack = cloneFrames(mark.stack);
+  }
+}

package/src/tree/util/compare.ts

@@ -0,0 +1,90 @@
+import { isNode } from './is-node.js';
+import isObject from 'lodash-es/isObject.js';
+import { type Node } from '../node.js';
+import type { EqualityMode } from '../../types/modes.js';
+
+export function compare(a: any, b: any, mode: EqualityMode = 'coerce') {
+  if (a === b) {
+    return 0;
+  }
+  if (!isObject(a) && !isObject(b)) {
+    return a > b ? 1 : -1;
+  }
+  if (isNode(a) && isNode(b)) {
+    return a.compare(b);
+  }
+  /** Do comparison without strict equality */
+  if (mode === 'coerce' && a == b) {
+    return 0;
+  }
+  return undefined;
+}
+
+/**
+ * Find the actual source order of two nodes, by comparing
+ * their position in their lowest common ancestor in the tree.
+ */
+export function comparePosition(a: Node, b: Node) {
+  if (a === b) {
+    return 0;
+  }
+
+  const pathToRoot = (node: Node): Node[] => {
+    const path: Node[] = [];
+    let current: Node | undefined = node;
+    let guard = 0;
+    while (current && guard < 1024) {
+      path.push(current);
+      current = current.parent;
+      guard++;
+    }
+    return path;
+  };
+
+  const aPath = pathToRoot(a);
+  const bPath = pathToRoot(b);
+  let ai = aPath.length - 1;
+  let bi = bPath.length - 1;
+  let commonAncestor: Node | undefined;
+
+  while (ai >= 0 && bi >= 0 && aPath[ai] === bPath[bi]) {
+    commonAncestor = aPath[ai];
+    ai--;
+    bi--;
+  }
+
+  if (!commonAncestor) {
+    return 0;
+  }
+
+  const aChild = ai >= 0 ? aPath[ai] : a;
+  const bChild = bi >= 0 ? bPath[bi] : b;
+  const aIndex = Number.isFinite(aChild.index) ? aChild.index : 0;
+  const bIndex = Number.isFinite(bChild.index) ? bChild.index : 0;
+  return aIndex - bIndex;
+}
+
+export function compareNodeArray(a: any[], b: any[], mode: EqualityMode = 'coerce'): 0 | 1 | -1 | undefined {
+  let output: 0 | 1 | -1 | undefined;
+
+  if (a.length !== b.length) {
+    return undefined;
+  }
+
+  /**
+   * All values must be equal, or less than, or greater than.
+   * Anything else is undefined.
+   */
+  for (let i = 0; i < a.length; i++) {
+    let result = compare(a[i]!, b[i]!, mode);
+    if (result === undefined) {
+      return undefined;
+    }
+    if (output === undefined) {
+      output = result;
+    } else if (result !== output) {
+      return undefined;
+    }
+  }
+  return output;
+}

package/src/tree/util/cursor.ts

@@ -0,0 +1,171 @@
+import { CANONICAL, type Cursor, type Node, type NodeEdge, type RenderKey } from '../node.js';
+
+function nodeFields(node: Node): Record<string, unknown> {
+  return node as unknown as Record<string, unknown>;
+}
+
+function getSingularEdgeStore(
+  node: Node,
+  key: string
+): NodeEdge<Node> | undefined {
+  return nodeFields(node)[`${key}Edge`] as NodeEdge<Node> | undefined;
+}
+
+function getIndexedEdgeStore(
+  node: Node,
+  key: string
+): Array<NodeEdge<Node> | undefined> | undefined {
+  return nodeFields(node)[`${key}Edges`] as Array<NodeEdge<Node> | undefined> | undefined;
+}
+
+function setSingularEdgeStore(
+  node: Node,
+  key: string,
+  edge: NodeEdge<Node>
+): void {
+  nodeFields(node)[`${key}Edge`] = edge;
+}
+
+function setIndexedEdgeStore(
+  node: Node,
+  key: string,
+  edges: Array<NodeEdge<Node> | undefined>
+): void {
+  nodeFields(node)[`${key}Edges`] = edges;
+}
+
+export function lookupEdge<T>(
+  edges: NodeEdge<T> | undefined,
+  key: RenderKey
+): T | undefined {
+  return edges?.get(key);
+}
+
+/**
+ * Resolve the primary parent cursor for a node/render-key pair.
+ *
+ * This mirrors `getParent(...)` at the cursor layer:
+ * - prefer the active render-key parent edge
+ * - fall back to canonical `node.parent`
+ *
+ * It deliberately does not follow secondary lanes such as `CALLER`. Traversals that
+ * want caller fallback must opt into that separately so the main render path stays
+ * stable and predictable.
+ */
+export function getParentEdge(cursor: Cursor): Cursor | undefined {
+  const overridden = lookupEdge(cursor.node.parentEdges, cursor.renderKey);
+  if (overridden !== undefined) {
+    return overridden ? { node: overridden, renderKey: cursor.renderKey } : undefined;
+  }
+
+  return cursor.node.parent
+    ? { node: cursor.node.parent, renderKey: cursor.renderKey }
+    : undefined;
+}
+
+export function getEdge(cursor: Cursor, key: string): Cursor | undefined {
+  const edge = getSingularEdgeStore(cursor.node, key);
+  if (edge) {
+    const overridden = lookupEdge(edge, cursor.renderKey);
+    if (overridden !== undefined) {
+      return overridden ? { node: overridden, renderKey: cursor.renderKey } : undefined;
+    }
+  }
+
+  const canonicalChild = nodeFields(cursor.node)[key] as Node | undefined;
+  return canonicalChild ? { node: canonicalChild, renderKey: cursor.renderKey } : undefined;
+}
+
+export function getEdgeAt(cursor: Cursor, key: string, index: number): Cursor | undefined {
+  const edges = getIndexedEdgeStore(cursor.node, key);
+  if (edges) {
+    const overridden = lookupEdge(edges[index], cursor.renderKey);
+    if (overridden !== undefined) {
+      return overridden ? { node: overridden, renderKey: cursor.renderKey } : undefined;
+    }
+  }
+
+  const canonicalList = nodeFields(cursor.node)[key] as Node[] | undefined;
+  const canonicalChild = canonicalList?.[index];
+  return canonicalChild ? { node: canonicalChild, renderKey: cursor.renderKey } : undefined;
+}
+
+export function addEdge(
+  node: Node,
+  key: string,
+  renderKey: RenderKey,
+  child: Node
+): void {
+  if (renderKey === CANONICAL) {
+    const canonicalChild = nodeFields(node)[key] as Node | undefined;
+    if (canonicalChild === child) {
+      return;
+    }
+    throw new Error(`Cannot add a second CANONICAL edge for ${node.type}.${key}`);
+  }
+  const edge = getSingularEdgeStore(node, key) ?? new Map<RenderKey, Node>();
+  edge.set(renderKey, child);
+  setSingularEdgeStore(node, key, edge);
+}
+
+export function addEdgeAt(
+  node: Node,
+  key: string,
+  index: number,
+  renderKey: RenderKey,
+  child: Node
+): void {
+  if (renderKey === CANONICAL) {
+    const canonicalList = nodeFields(node)[key] as Node[] | undefined;
+    const canonicalChild = canonicalList?.[index];
+    if (canonicalChild === child) {
+      return;
+    }
+    throw new Error(`Cannot add a second CANONICAL edge for ${node.type}.${key}[${index}]`);
+  }
+  const indexedEdges = getIndexedEdgeStore(node, key) ?? [];
+  const edge = indexedEdges[index] ?? new Map<RenderKey, Node>();
+  edge.set(renderKey, child);
+  indexedEdges[index] = edge;
+  setIndexedEdgeStore(node, key, indexedEdges);
+}
+
+export function addParentEdge(
+  node: Node,
+  renderKey: RenderKey,
+  parent: Node
+): void {
+  /**
+   * Parent edges represent render-placement overrides, not a second canonical parent.
+   *
+   * Invariants:
+   * - `CANONICAL` must continue to live on `node.parent`
+   * - non-canonical writes may override the active parent for a render key
+   * - special keys such as `CALLER` are allowed here, but they are secondary lanes;
+   *   they should not be treated as the default upward render path unless a traversal
+   *   explicitly asks for them
+   */
+  if (renderKey === CANONICAL) {
+    if (node.parent === parent) {
+      return;
+    }
+    throw new Error(`Cannot add a second CANONICAL parent edge for ${node.type}`);
+  }
+  const edge = node.parentEdges ?? new Map<RenderKey, Node>();
+  edge.set(renderKey, parent);
+  node.parentEdges = edge;
+}
+
+export function removeParentEdge(
+  node: Node,
+  renderKey: RenderKey
+): void {
+  const edge = node.parentEdges;
+  if (!edge) {
+    return;
+  }
+  edge.delete(renderKey);
+  if (edge.size === 0) {
+    node.parentEdges = undefined;
+  }
+}