flarp 1.0.1 → 2.0.1

package/README.md

@@ -199,16 +199,19 @@ store.emit('addUser', { name: 'Bob', role: 'Developer' });
 
 Every XML node is independently:
 - **Reactive** — Has its own Signal
-- **Identifiable** — UUID attribute
-- **Versioned** — `rev` for conflict resolution
+- **Identifiable** — `uuid` attribute (stable identity)
+- **Versioned** — `rev` for conflict detection & resolution
 - **Serializable** — `node.serialize()`
 
 ```js
-const node = store.at('User.Name');
+const node = store.at('user.name');
 
-node.uuid;        // "a1b2c3..."
-node.rev;         // 5
-node.serialize(); // "<n uuid="..." rev="5">Alice</n>"
+node.uuid;        // "a1b2c3..." (stable identity)
+node.rev;         // "5-f94bc318..." (revision)
+node.revNumber;   // 5
+node.revId;       // "f94bc318..." (write identifier)
+
+node.serialize(); // '<name uuid="..." rev="5-...">Alice</name>'
 
 // Subscribe to just this node
 node.subscribe(value => console.log(value));
@@ -216,6 +219,49 @@ node.subscribe(value => console.log(value));
 
 ---
 
+## Revision Format (CouchDB-style)
+
+Flarp uses CouchDB-style revision tracking: `{number}-{uuid}`
+
+```
+rev="3-ee30f92d-a785-4603-b0b8-b681b8707e39"
+     │  └─ Revision UUID (fresh on each write)
+     └─ Revision number (increments)
+```
+
+**Why two parts?**
+
+1. **Revision number** — Quick comparison (higher wins)
+2. **Revision UUID** — Conflict detection & tie-breaking
+
+**Conflict scenario:**
+```
+User A saves: rev="3-ee30f92d..."
+User B saves: rev="3-56b1d51a..."
+              ↑ Same number = CONFLICT detected
+
+Tie-breaker: Sort UUIDs alphabetically, first wins
+             "56b1d51a" < "ee30f92d" → User B wins
+```
+
+This ensures:
+- No data loss (both writes saved with unique UUIDs)
+- Consistent winner selection (all nodes agree independently)
+- Eventual consistency across distributed systems
+
+```js
+// Check for conflict
+if (node.conflictsWith(remoteRev)) {
+  console.log('Conflict detected!');
+}
+
+// Merge with automatic conflict resolution
+const result = node.merge(remoteXml);
+// { applied: true, conflict: true, winner: 'remote' }
+```
+
+---
+
 ## Persistence
 
 State persists to localStorage automatically:
@@ -323,16 +369,18 @@ Modern browsers with ES modules:
 
 ---
 
-## License
+## Name
 
-MIT
+flarp (from Jargon File)
+
+/flarp/ [Rutgers University] Yet another metasyntactic variable (see foo). Among those who use it, it is associated with a legend that any program not containing the word "flarp" somewhere will not work. The legend is discreetly silent on the reliability of programs which *do* contain the magic word.
 
 ---
 
-*Built for developers who believe state management can be simple.*
+## License
 
-## Name
+MIT
 
-flarp (from Jargon File)
+---
 
-/flarp/ [Rutgers University] Yet another metasyntactic variable (see foo). Among those who use it, it is associated with a legend that any program not containing the word "flarp" somewhere will not work. The legend is discreetly silent on the reliability of programs which *do* contain the magic word.
+*Built for developers who believe state management can be simple.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flarp",
-  "version": "1.0.1",
+  "version": "2.0.1",
   "description": "DOM-native XML state management for Web Components",
   "type": "module",
   "main": "src/index.js",

package/src/xml/Node.js

@@ -3,22 +3,30 @@
  * 
  * Each Node is:
  * - Independently reactive (has its own Signal)
- * - Uniquely identifiable (UUID)
- * - Version-tracked (rev for conflict resolution)
+ * - Uniquely identifiable (UUID - stable identity)
+ * - Version-tracked with conflict detection (rev = number-uuid)
  * - Serializable on its own
  * 
- * @example
- * const node = Node.wrap(element);
+ * ## Revision Format (CouchDB-style)
+ * 
+ * The `rev` attribute follows the format: `{revisionNumber}-{revisionUUID}`
  * 
- * node.text; // read text content
- * node.text = 'new value'; // write (increments rev)
+ * - revisionNumber: Incrementing integer (1, 2, 3...)
+ * - revisionUUID: Fresh UUID generated on each write
  * 
- * node.subscribe(text => console.log(text));
+ * This enables:
+ * 1. Conflict detection: Same revisionNumber + different revisionUUID = conflict
+ * 2. Consistent tie-breaking: Sort revisionUUIDs alphabetically, first wins
+ * 3. Eventual consistency: All nodes independently agree on the same winner
+ * 
+ * @example
+ * const node = Node.wrap(element);
  * 
- * node.uuid; // unique identifier
- * node.rev;  // revision number
+ * node.text = 'new value'; // Generates new rev like "3-a1b2c3..."
  * 
- * node.serialize(); // just this node as XML string
+ * node.revNumber; // 3
+ * node.revId;     // "a1b2c3..."
+ * node.rev;       // "3-a1b2c3..."
  */
 
 import Signal from '../core/Signal.js';
@@ -39,6 +47,35 @@ function uuid() {
   });
 }
 
+/**
+ * Parse rev string into components
+ * @param {string} rev - Format: "number-uuid" or just "number"
+ * @returns {{ number: number, id: string }}
+ */
+function parseRev(rev) {
+  if (!rev) return { number: 0, id: '' };
+  
+  const dashIndex = rev.indexOf('-');
+  if (dashIndex === -1) {
+    // Legacy format: just a number
+    return { number: parseInt(rev, 10) || 0, id: '' };
+  }
+  
+  return {
+    number: parseInt(rev.slice(0, dashIndex), 10) || 0,
+    id: rev.slice(dashIndex + 1)
+  };
+}
+
+/**
+ * Create new rev string
+ * @param {number} number - Revision number
+ * @returns {string} Format: "number-uuid"
+ */
+function createRev(number) {
+  return `${number}-${uuid()}`;
+}
+
 export default class Node {
   #element;
   #signal;
@@ -84,14 +121,14 @@ export default class Node {
     this.#element = element;
     this.#signal = new Signal(element.textContent);
     
-    // Ensure UUID
+    // Ensure UUID (stable node identity)
     if (!element.hasAttribute('uuid')) {
       element.setAttribute('uuid', uuid());
     }
     
-    // Ensure rev
+    // Ensure rev with proper format
     if (!element.hasAttribute('rev')) {
-      element.setAttribute('rev', '0');
+      element.setAttribute('rev', createRev(1));
     }
 
     // Observe mutations to sync signal
@@ -116,7 +153,7 @@ export default class Node {
   }
 
   /**
-   * Set text content (increments rev)
+   * Set text content (increments rev with new UUID)
    */
   set text(value) {
     this.#element.textContent = value;
@@ -149,17 +186,31 @@ export default class Node {
   }
 
   /**
-   * Get UUID
+   * Get node identity UUID (stable)
    */
   get uuid() {
     return this.#element.getAttribute('uuid');
   }
 
   /**
-   * Get revision number
+   * Get full revision string (e.g., "3-a1b2c3...")
    */
   get rev() {
-    return parseInt(this.#element.getAttribute('rev') || '0', 10);
+    return this.#element.getAttribute('rev') || '0-';
+  }
+
+  /**
+   * Get revision number only
+   */
+  get revNumber() {
+    return parseRev(this.rev).number;
+  }
+
+  /**
+   * Get revision UUID only (the tie-breaker)
+   */
+  get revId() {
+    return parseRev(this.rev).id;
   }
 
   /**
@@ -259,42 +310,91 @@ export default class Node {
   }
 
   /**
-   * Compare with another node for conflict resolution
-   * Higher rev wins, UUID tiebreaker (alphabetically first wins)
-   * @param {Node} other
-   * @returns {Node} Winner
+   * Compare revisions for conflict resolution
+   * 
+   * Rules:
+   * 1. Higher revision number wins
+   * 2. Same revision number = CONFLICT
+   *    - Tie-breaker: alphabetically first revId wins
+   *    - This ensures all nodes independently agree on the same winner
+   * 
+   * @param {Node} a
+   * @param {Node} b
+   * @returns {{ winner: Node, conflict: boolean }}
    */
-  static resolve(a, b) {
-    if (a.rev !== b.rev) {
-      return a.rev > b.rev ? a : b;
+  static compare(a, b) {
+    const revA = parseRev(a.rev);
+    const revB = parseRev(b.rev);
+    
+    // Different revision numbers - higher wins, no conflict
+    if (revA.number !== revB.number) {
+      return {
+        winner: revA.number > revB.number ? a : b,
+        conflict: false
+      };
     }
-    return a.uuid <= b.uuid ? a : b;
+    
+    // Same revision number - this is a conflict!
+    // Tie-breaker: sort revIds, first wins (consistent across all nodes)
+    return {
+      winner: revA.id <= revB.id ? a : b,
+      conflict: revA.id !== revB.id // Same revId means same write, not a conflict
+    };
+  }
+
+  /**
+   * Check if this node conflicts with remote data
+   * @param {string} remoteRev - Remote rev string
+   * @returns {boolean}
+   */
+  conflictsWith(remoteRev) {
+    const local = parseRev(this.rev);
+    const remote = parseRev(remoteRev);
+    
+    return local.number === remote.number && local.id !== remote.id;
   }
 
   /**
    * Merge remote changes into this node
-   * @param {string} remoteXml
-   * @returns {boolean} True if remote won
+   * 
+   * @param {string} remoteXml - Remote node as XML string
+   * @returns {{ applied: boolean, conflict: boolean, winner: 'local'|'remote' }}
    */
   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');
+    const localRev = parseRev(this.rev);
+    const remoteRev = parseRev(remoteEl.getAttribute('rev'));
     
-    // 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;
+    // Remote has higher revision - apply it
+    if (remoteRev.number > localRev.number) {
+      this.#applyRemote(remoteEl, remoteRev);
+      return { applied: true, conflict: false, winner: 'remote' };
     }
     
-    return false;
+    // Local has higher revision - keep local
+    if (localRev.number > remoteRev.number) {
+      return { applied: false, conflict: false, winner: 'local' };
+    }
+    
+    // Same revision number - conflict!
+    const conflict = localRev.id !== remoteRev.id;
+    
+    // Tie-breaker: alphabetically first revId wins
+    if (remoteRev.id < localRev.id) {
+      this.#applyRemote(remoteEl, remoteRev);
+      return { applied: true, conflict, winner: 'remote' };
+    }
+    
+    return { applied: false, conflict, winner: 'local' };
+  }
+
+  #applyRemote(remoteEl, remoteRev) {
+    this.#element.innerHTML = remoteEl.innerHTML;
+    this.#element.setAttribute('rev', `${remoteRev.number}-${remoteRev.id}`);
+    this.#signal.value = this.#element.textContent;
   }
 
   /**
@@ -310,8 +410,8 @@ export default class Node {
   }
 
   #incrementRev() {
-    const rev = this.rev + 1;
-    this.#element.setAttribute('rev', String(rev));
+    const currentNumber = this.revNumber;
+    this.#element.setAttribute('rev', createRev(currentNumber + 1));
   }
 }
 

package/src/xml/Tree.js

@@ -19,6 +19,26 @@ import State from '../core/State.js';
 import Node, { AttrNode } from './Node.js';
 import * as Path from './Path.js';
 
+/**
+ * Generate UUID with fallback
+ */
+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);
+  });
+}
+
+/**
+ * Create CouchDB-style rev string
+ */
+function createRev(number = 1) {
+  return `${number}-${uuid()}`;
+}
+
 export default class Tree {
   #root;
   #parser = new DOMParser();
@@ -113,12 +133,12 @@ export default class Tree {
     for (const child of Array.from(doc.documentElement.children)) {
       const imported = document.importNode(child, true);
       
-      // Ensure UUID/rev
+      // Ensure UUID/rev with proper format
       if (!imported.hasAttribute('uuid')) {
-        imported.setAttribute('uuid', crypto.randomUUID?.() || Math.random().toString(36).slice(2));
+        imported.setAttribute('uuid', uuid());
       }
       if (!imported.hasAttribute('rev')) {
-        imported.setAttribute('rev', '1');
+        imported.setAttribute('rev', createRev(1));
       }
       
       resolved.element.appendChild(imported);
@@ -239,8 +259,8 @@ export default class Tree {
 
       if (matches.length === 0) {
         const newEl = document.createElement(tag);
-        newEl.setAttribute('uuid', crypto.randomUUID?.() || Math.random().toString(36).slice(2));
-        newEl.setAttribute('rev', '1');
+        newEl.setAttribute('uuid', uuid());
+        newEl.setAttribute('rev', createRev(1));
         current.appendChild(newEl);
         current = newEl;
       } else if (index !== null && !matches[index]) {