flarp 1.0.0

package/src/xml/Node.js

@@ -0,0 +1,396 @@
+/**
+ * Node - Reactive wrapper for XML elements
+ * 
+ * Each Node is:
+ * - Independently reactive (has its own Signal)
+ * - Uniquely identifiable (UUID)
+ * - Version-tracked (rev for conflict resolution)
+ * - Serializable on its own
+ * 
+ * @example
+ * const node = Node.wrap(element);
+ * 
+ * node.text; // read text content
+ * node.text = 'new value'; // write (increments rev)
+ * 
+ * node.subscribe(text => console.log(text));
+ * 
+ * node.uuid; // unique identifier
+ * node.rev;  // revision number
+ * 
+ * node.serialize(); // just this node as XML string
+ */
+
+import Signal from '../core/Signal.js';
+
+// WeakMap cache: same element → same Node instance
+const cache = new WeakMap();
+
+/**
+ * Generate UUID with fallback for non-HTTPS
+ */
+function uuid() {
+  if (crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {
+    const r = Math.random() * 16 | 0;
+    return (c === 'x' ? r : (r & 0x3 | 0x8)).toString(16);
+  });
+}
+
+export default class Node {
+  #element;
+  #signal;
+  #observer;
+  #disposed = false;
+
+  /**
+   * Get or create Node wrapper for an element
+   * @param {Element} element
+   * @returns {Node}
+   */
+  static wrap(element) {
+    if (cache.has(element)) {
+      return cache.get(element);
+    }
+    const node = new Node(element);
+    cache.set(element, node);
+    return node;
+  }
+
+  /**
+   * Check if element has a Node wrapper
+   * @param {Element} element
+   * @returns {boolean}
+   */
+  static has(element) {
+    return cache.has(element);
+  }
+
+  /**
+   * Remove wrapper from cache (for cleanup)
+   * @param {Element} element
+   */
+  static unwrap(element) {
+    const node = cache.get(element);
+    if (node) {
+      node.dispose();
+      cache.delete(element);
+    }
+  }
+
+  constructor(element) {
+    this.#element = element;
+    this.#signal = new Signal(element.textContent);
+    
+    // Ensure UUID
+    if (!element.hasAttribute('uuid')) {
+      element.setAttribute('uuid', uuid());
+    }
+    
+    // Ensure rev
+    if (!element.hasAttribute('rev')) {
+      element.setAttribute('rev', '0');
+    }
+
+    // Observe mutations to sync signal
+    this.#observer = new MutationObserver(() => {
+      if (!this.#disposed) {
+        this.#signal.value = element.textContent;
+      }
+    });
+
+    this.#observer.observe(element, {
+      childList: true,
+      characterData: true,
+      subtree: true
+    });
+  }
+
+  /**
+   * Get text content
+   */
+  get text() {
+    return this.#signal.value;
+  }
+
+  /**
+   * Set text content (increments rev)
+   */
+  set text(value) {
+    this.#element.textContent = value;
+    this.#incrementRev();
+  }
+
+  /**
+   * Alias for text (compatibility)
+   */
+  get value() {
+    return this.text;
+  }
+
+  set value(v) {
+    this.text = v;
+  }
+
+  /**
+   * Get underlying element
+   */
+  get element() {
+    return this.#element;
+  }
+
+  /**
+   * Get tag name
+   */
+  get tag() {
+    return this.#element.tagName;
+  }
+
+  /**
+   * Get UUID
+   */
+  get uuid() {
+    return this.#element.getAttribute('uuid');
+  }
+
+  /**
+   * Get revision number
+   */
+  get rev() {
+    return parseInt(this.#element.getAttribute('rev') || '0', 10);
+  }
+
+  /**
+   * Get attribute value
+   * @param {string} name
+   * @returns {string|null}
+   */
+  attr(name) {
+    return this.#element.getAttribute(name);
+  }
+
+  /**
+   * Set attribute (increments rev)
+   * @param {string} name
+   * @param {string} value
+   */
+  setAttr(name, value) {
+    this.#element.setAttribute(name, value);
+    this.#incrementRev();
+  }
+
+  /**
+   * Subscribe to text changes
+   * @param {Function} fn
+   * @param {boolean} autorun
+   * @returns {Function} Unsubscribe
+   */
+  subscribe(fn, autorun = true) {
+    return this.#signal.subscribe(fn, autorun);
+  }
+
+  /**
+   * Map to derived signal
+   * @param {Function} fn
+   * @returns {Signal}
+   */
+  map(fn) {
+    return this.#signal.map(fn);
+  }
+
+  /**
+   * Peek value without tracking
+   */
+  peek() {
+    return this.#signal.peek();
+  }
+
+  /**
+   * Serialize this node to XML string
+   * @returns {string}
+   */
+  serialize() {
+    return this.#element.outerHTML;
+  }
+
+  /**
+   * Serialize inner content only
+   * @returns {string}
+   */
+  serializeContent() {
+    return this.#element.innerHTML;
+  }
+
+  /**
+   * Get child nodes as Node wrappers
+   * @returns {Node[]}
+   */
+  children() {
+    return Array.from(this.#element.children).map(el => Node.wrap(el));
+  }
+
+  /**
+   * Query child by path segment
+   * @param {string} tag
+   * @param {number|null} index
+   * @returns {Node|null}
+   */
+  child(tag, index = null) {
+    const tagLower = tag.toLowerCase();
+    const matches = Array.from(this.#element.children).filter(
+      el => el.tagName.toLowerCase() === tagLower
+    );
+    const element = index !== null ? matches[index] : matches[0];
+    return element ? Node.wrap(element) : null;
+  }
+
+  /**
+   * Query all children with tag
+   * @param {string} tag
+   * @returns {Node[]}
+   */
+  childrenByTag(tag) {
+    const tagLower = tag.toLowerCase();
+    return Array.from(this.#element.children)
+      .filter(el => el.tagName.toLowerCase() === tagLower)
+      .map(el => Node.wrap(el));
+  }
+
+  /**
+   * Compare with another node for conflict resolution
+   * Higher rev wins, UUID tiebreaker (alphabetically first wins)
+   * @param {Node} other
+   * @returns {Node} Winner
+   */
+  static resolve(a, b) {
+    if (a.rev !== b.rev) {
+      return a.rev > b.rev ? a : b;
+    }
+    return a.uuid <= b.uuid ? a : b;
+  }
+
+  /**
+   * Merge remote changes into this node
+   * @param {string} remoteXml
+   * @returns {boolean} True if remote won
+   */
+  merge(remoteXml) {
+    const parser = new DOMParser();
+    const doc = parser.parseFromString(remoteXml, 'application/xml');
+    const remoteEl = doc.documentElement;
+    
+    const remoteRev = parseInt(remoteEl.getAttribute('rev') || '0', 10);
+    const remoteUuid = remoteEl.getAttribute('uuid');
+    
+    // Compare versions
+    if (remoteRev > this.rev || 
+        (remoteRev === this.rev && remoteUuid < this.uuid)) {
+      // Remote wins - apply changes
+      this.#element.innerHTML = remoteEl.innerHTML;
+      this.#element.setAttribute('rev', String(remoteRev));
+      this.#signal.value = this.#element.textContent;
+      return true;
+    }
+    
+    return false;
+  }
+
+  /**
+   * Dispose this node wrapper
+   */
+  dispose() {
+    if (this.#disposed) return;
+    this.#disposed = true;
+    
+    this.#observer.disconnect();
+    this.#signal.dispose();
+    cache.delete(this.#element);
+  }
+
+  #incrementRev() {
+    const rev = this.rev + 1;
+    this.#element.setAttribute('rev', String(rev));
+  }
+}
+
+/**
+ * AttrNode - Reactive wrapper for attributes
+ */
+export class AttrNode {
+  #element;
+  #name;
+  #signal;
+  #observer;
+  #disposed = false;
+
+  static #cache = new WeakMap();
+
+  static wrap(element, name) {
+    let attrMap = AttrNode.#cache.get(element);
+    if (!attrMap) {
+      attrMap = new Map();
+      AttrNode.#cache.set(element, attrMap);
+    }
+    
+    if (attrMap.has(name)) {
+      return attrMap.get(name);
+    }
+    
+    const node = new AttrNode(element, name);
+    attrMap.set(name, node);
+    return node;
+  }
+
+  constructor(element, name) {
+    this.#element = element;
+    this.#name = name;
+    this.#signal = new Signal(element.getAttribute(name));
+
+    this.#observer = new MutationObserver(mutations => {
+      for (const m of mutations) {
+        if (m.attributeName === name) {
+          this.#signal.value = element.getAttribute(name);
+        }
+      }
+    });
+
+    this.#observer.observe(element, {
+      attributes: true,
+      attributeFilter: [name]
+    });
+  }
+
+  get value() {
+    return this.#signal.value;
+  }
+
+  set value(v) {
+    this.#element.setAttribute(this.#name, v);
+    // Observer will update signal
+  }
+
+  get name() {
+    return this.#name;
+  }
+
+  subscribe(fn, autorun = true) {
+    return this.#signal.subscribe(fn, autorun);
+  }
+
+  map(fn) {
+    return this.#signal.map(fn);
+  }
+
+  peek() {
+    return this.#signal.peek();
+  }
+
+  dispose() {
+    if (this.#disposed) return;
+    this.#disposed = true;
+    this.#observer.disconnect();
+    this.#signal.dispose();
+  }
+}

package/src/xml/Path.js

@@ -0,0 +1,176 @@
+/**
+ * Path - XML path parsing and resolution
+ * 
+ * Supports:
+ * - Element paths: Product.Details.Price
+ * - Array indexing: Product.Items[0]
+ * - Attributes: Product.Price@currency
+ * - Relative: .Name (within iterations)
+ * 
+ * @example
+ * parse('Product.Items[0]@id')
+ * // { segments: [{tag: 'Product'}, {tag: 'Items', index: 0}], attr: 'id' }
+ */
+
+/**
+ * Parse a path string into structured segments
+ * @param {string} path
+ * @returns {Object} { segments, attr, relative }
+ */
+export function parse(path) {
+  if (!path || path === '.') {
+    return { segments: [], attr: null, relative: path === '.' };
+  }
+
+  const relative = path.startsWith('.');
+  let cleanPath = relative ? path.slice(1) : path;
+  
+  // Handle leading dot for relative paths like ".Name"
+  if (cleanPath.startsWith('.')) {
+    cleanPath = cleanPath.slice(1);
+  }
+
+  // Split off attribute: Product.Price@currency
+  let attr = null;
+  const attrIndex = cleanPath.lastIndexOf('@');
+  if (attrIndex > 0) {
+    attr = cleanPath.slice(attrIndex + 1);
+    cleanPath = cleanPath.slice(0, attrIndex);
+  }
+
+  // Handle empty path after attribute extraction
+  if (!cleanPath) {
+    return { segments: [], attr, relative };
+  }
+
+  // Parse segments
+  const segments = cleanPath.split('.').map(part => {
+    const match = part.match(/^([A-Za-z_][\w-]*)(?:\[(\d+)\])?$/);
+    if (!match) {
+      throw new Error(`Invalid path segment: "${part}"`);
+    }
+    return {
+      tag: match[1],
+      index: match[2] !== undefined ? parseInt(match[2], 10) : null
+    };
+  });
+
+  return { segments, attr, relative };
+}
+
+/**
+ * Resolve a path against an XML element
+ * @param {Element} root - Starting element
+ * @param {string} path - Path to resolve
+ * @returns {Object|null} { element, attr } or null
+ * 
+ * NOTE: Tag matching is case-insensitive because the DOM
+ * lowercases all tag names when parsing HTML.
+ */
+export function resolve(root, path) {
+  const { segments, attr } = parse(path);
+  let current = root;
+
+  for (const { tag, index } of segments) {
+    const tagLower = tag.toLowerCase();
+    const children = Array.from(current.children).filter(
+      el => el.tagName.toLowerCase() === tagLower
+    );
+
+    if (children.length === 0) return null;
+
+    current = index !== null ? children[index] : children[0];
+    if (!current) return null;
+  }
+
+  return { element: current, attr };
+}
+
+/**
+ * Resolve all matching elements for a path
+ * @param {Element} root - Starting element
+ * @param {string} path - Path to resolve
+ * @returns {Element[]} Array of matching elements
+ * 
+ * NOTE: Tag matching is case-insensitive because the DOM
+ * lowercases all tag names when parsing HTML.
+ */
+export function resolveAll(root, path) {
+  const { segments } = parse(path);
+  let current = [root];
+
+  for (const { tag, index } of segments) {
+    const tagLower = tag.toLowerCase();
+    current = current.flatMap(el =>
+      Array.from(el.children).filter(child => child.tagName.toLowerCase() === tagLower)
+    );
+
+    if (index !== null) {
+      current = current[index] ? [current[index]] : [];
+    }
+  }
+
+  return current;
+}
+
+/**
+ * Get parent path
+ * @param {string} path
+ * @returns {string}
+ */
+export function parent(path) {
+  const { segments, attr } = parse(path);
+  
+  if (attr) {
+    // Return path without attribute
+    return segments.map(s => 
+      s.index !== null ? `${s.tag}[${s.index}]` : s.tag
+    ).join('.');
+  }
+  
+  if (segments.length <= 1) return '';
+  
+  return segments.slice(0, -1).map(s => 
+    s.index !== null ? `${s.tag}[${s.index}]` : s.tag
+  ).join('.');
+}
+
+/**
+ * Get last segment tag name
+ * @param {string} path
+ * @returns {string}
+ */
+export function leaf(path) {
+  const { segments, attr } = parse(path);
+  if (attr) return attr;
+  if (segments.length === 0) return '';
+  return segments[segments.length - 1].tag;
+}
+
+/**
+ * Build path string from segments
+ * @param {Array} segments
+ * @param {string|null} attr
+ * @returns {string}
+ */
+export function build(segments, attr = null) {
+  const elementPath = segments.map(s =>
+    s.index !== null ? `${s.tag}[${s.index}]` : s.tag
+  ).join('.');
+  
+  return attr ? `${elementPath}@${attr}` : elementPath;
+}
+
+/**
+ * Join two paths
+ * @param {string} base
+ * @param {string} relative
+ * @returns {string}
+ */
+export function join(base, relative) {
+  if (!base) return relative;
+  if (!relative || relative === '.') return base;
+  return `${base}.${relative}`;
+}
+
+export default { parse, resolve, resolveAll, parent, leaf, build, join };