npm - flarp - Versions diffs - 2.0.1 → 2.5.1 - Mend

flarp 2.0.1 → 2.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/README.md +259 -251
package/package.json +2 -2
package/src/components/index.js +3 -1
package/src/dom/find.js +5 -5
package/src/index.js +24 -12
package/src/sync/Store.js +633 -0
package/src/sync/Sync.js +369 -0
package/src/sync/index.js +3 -1
package/src/xml/Node.js +8 -1
package/src/components/FStore.js +0 -332

package/README.md CHANGED Viewed

@@ -1,145 +1,203 @@
 # Flarp
-**DOM-native XML State Management for Web Components**
+**DOM-native XML State Management with Multi-Master Sync**
+Flarp treats XML as state, the DOM as the runtime, and all browser tabs as equal peers. State survives refresh, syncs across tabs, and conflicts are resolved automatically.
+```html
+<f-store key="myapp" autosave="500">
+  <user>
+    <n>Alice</n>
+    <role>admin</role>
+  </user>
+</f-store>
+<f-text path="user.name"></f-text>
+<f-field path="user.role"></f-field>
 ```
-XML is state. Signals are reactive. The DOM is the runtime.
+## Core Principles
+1. **XML is State** — Human-readable, self-describing, works with AI
+2. **DOM is Runtime** — No virtual DOM, no compile step, just the browser
+3. **Multi-Master Sync** — All tabs are equal peers, no single source of truth
+4. **Eventually Consistent** — Conflicts resolved deterministically, all tabs agree
+---
+## Quick Start
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <script type="module" src="./src/index.js"></script>
+</head>
+<body>
+  <f-store key="demo" autosave="500">
+    <counter>
+      <value>0</value>
+    </counter>
+  </f-store>
+  <p>Count: <f-text path="counter.value"></f-text></p>
+  <button id="inc">+1</button>
+  <script type="module">
+    const store = document.querySelector('f-store');
+    store.state.when('ready', () => {
+      document.getElementById('inc').onclick = () => {
+        const val = store.at('counter.value');
+        val.value = String(Number(val.value) + 1);
+      };
+    });
+  </script>
+</body>
+</html>
 ```
 ---
-## Why Flarp?
+## Revision System (CouchDB-style)
-State management shouldn't require learning proprietary patterns. Flarp uses what the web already has:
+Every node has two special attributes:
-- **XML for state** — Nested structure you can see and understand
-- **Signals for reactivity** — No virtual DOM, no diffing, just updates
-- **Web Components for UI** — Standard, portable, composable
-- **DOM as runtime** — MutationObserver does the scheduling
+- **uuid** — Stable identity (never changes)
+- **rev** — Version string: `{number}-{hash}`
-## Quick Start
+```xml
+<user uuid="abc123" rev="3-f7a8b9c0">
+  <n>Alice</n>
+</user>
+```
-```html
-<script type="module">
-  import 'https://unpkg.com/flarp/src/index.js';
-</script>
+### Why This Format?
-<f-state key="myapp" autosave="500">
-  <user>
-    <name>Alice</name>
-    <role>Developer</role>
-  </user>
-</f-state>
+The revision number enables quick comparison (higher wins). The hash enables conflict detection (same number, different hash = conflict) and deterministic tie-breaking (alphabetically first hash wins).
+### Conflict Resolution
-<main>
-  <h1><f-text path="user.name"></f-text></h1>
-  <f-field path="user.role"></f-field>
-</main>
+When two tabs write simultaneously:
+```
+Tab A writes: rev="3-aaa111"
+Tab B writes: rev="3-bbb222"
 ```
-Components find `<f-state>` automatically — no nesting required!
+1. Both writes succeed (no data loss!)
+2. Conflict detected (same number: 3)
+3. Tab A wins (aaa < bbb alphabetically)
+4. All tabs independently agree on Tab A
-> **Note:** The DOM lowercases all tag names. Use lowercase paths like `user.name`, not `User.Name`. Path matching is case-insensitive, so `User.Name` will still work, but your XML will appear lowercase in the DOM.
+```javascript
+// Listen for conflicts
+store.onConflict(({ uuid, localRev, remoteRev, winner }) => {
+  console.log(`Conflict on ${uuid}: ${winner} won`);
+});
+```
-## Key Innovation: Signal-Based Readiness
+---
-Events fire once. If you miss them, you miss them. Signals don't have this problem:
+## Cross-Tab Synchronization
-```js
-// This works even if 'ready' already happened!
-store.state.when('ready', () => {
-  const name = store.at('User.Name');
-  name.subscribe(v => console.log('Name:', v));
+When you set `key="..."`, Flarp automatically:
+1. Persists to localStorage
+2. Syncs across browser tabs via BroadcastChannel
+3. Requests catch-up sync on connect
+```html
+<f-store key="myapp" autosave="500">
+  <!-- Shared across all tabs with key="myapp" -->
+</f-store>
+```
+### How It Works
+1. Each tab broadcasts changes to a shared channel
+2. Other tabs receive and apply changes (if revision wins)
+3. Changes include: `{ uuid, rev, data: "<xml>..." }`
+4. On startup, tabs request missed changes from peers
+```javascript
+// Access the sync instance
+store.sync.onChange(change => {
+  console.log('Remote change:', change);
 });
-// Or use async/await
-await store.state.until('ready');
+store.sync.onConflict(info => {
+  console.log('Conflict:', info);
+});
 ```
-## Installation
+---
-```bash
-npm install flarp
+## External Updates (Server Push)
+Apply updates from WebSocket, HTTP push, or postMessage:
+```javascript
+// From WebSocket
+ws.onmessage = e => {
+  const { applied, conflict, winner } = store.applyRemote(e.data);
+  console.log(`Applied: ${applied}, Winner: ${winner}`);
+};
+// From postMessage
+window.onmessage = e => {
+  if (e.data.type === 'node-update') {
+    store.applyRemote(e.data.xml);
+  }
+};
 ```
-Or use directly:
+The XML must include uuid and rev:
-```html
-<script type="module">
-  import 'https://unpkg.com/flarp/src/index.js';
-</script>
+```xml
+<n uuid="abc123" rev="5-xyz789">New Value</n>
 ```
 ---
 ## Components
-### `<f-state>` — The Store
+### `<f-store>` — State Container
 ```html
-<f-state
-  key="myapp"      <!-- Persistence key -->
-  autosave="500"   <!-- Debounce ms -->
-  src="/api/data"  <!-- Load from URL -->
+<f-store
+  key="myapp"           <!-- Storage/sync key -->
+  autosave="500"        <!-- Debounced save (ms) -->
+  sync="true"           <!-- Enable cross-tab sync -->
 >
-  <User>
-    <n>Alice</n>
-  </User>
-</f-state>
+  <!-- Your XML state here -->
+</f-store>
 ```
-**API:**
-- `at(path)` — Get reactive node
-- `query(path)` — Get all matching nodes
-- `set(path, value)` — Set value
-- `add(path, xml)` — Add child
-- `remove(path)` — Remove node
-- `serialize()` — Get XML string
-- `on(action, fn)` — Register action
-- `emit(action, payload)` — Dispatch action
-- `state.when(name, fn)` — React to state
-- `state.until(name)` — Promise for state
-### `<f-text>` — Display
+### `<f-text>` — Display Value
 ```html
-<f-text path="User.Name"></f-text>
-<f-text path="Price" format="currency"></f-text>
+<f-text path="user.name"></f-text>
 ```
-**Formats:** `uppercase`, `lowercase`, `number`, `currency`, `percent`
 ### `<f-field>` — Two-Way Binding
 ```html
-<f-field path="User.Name"></f-field>
-<f-field path="User.Age" type="number"></f-field>
-<f-field path="User.Active" type="checkbox"></f-field>
-```
-### `<f-each>` — Lists
-```html
-<f-each path="Users.User">
-  <template>
-    <div class="card">
-      <f-text path="Name"></f-text>
-      <f-field path="Email"></f-field>
-    </div>
-  </template>
-</f-each>
+<f-field path="user.name"></f-field>
+<f-field path="user.role" type="select">
+  <option value="admin">Admin</option>
+  <option value="user">User</option>
+</f-field>
 ```
-Paths inside templates are relative to each item.
-### `<f-when>` — Conditionals
+### `<f-when>` — Conditional
 ```html
-<f-when test="User.LoggedIn == 'true'">
-  <span>Welcome!</span>
+<f-when test="user.active == 'true'">
+  <span>Active!</span>
 </f-when>
-<f-when test="Cart.Total > 100">
+<f-when test="cart.total > 100">
   <span>Free shipping!</span>
 </f-when>
 ```
@@ -147,225 +205,179 @@ Paths inside templates are relative to each item.
 ### `<f-match>` — Switch
 ```html
-<f-match test="User.Role">
+<f-match test="user.role">
   <f-case value="admin">Admin Panel</f-case>
   <f-case value="user">Dashboard</f-case>
   <f-else>Please log in</f-else>
 </f-match>
 ```
----
-## Store Discovery
-Components don't need to be nested inside `<f-state>`. Flarp searches siblings and ancestors:
+### `<f-each>` — Iteration
 ```html
-<div class="app">
-  <f-state id="app">
-    <User><n>Alice</n></User>
-  </f-state>
-  <main>
-    <!-- Finds sibling f-state automatically -->
-    <f-text path="User.Name"></f-text>
-  </main>
-</div>
+<f-each path="users.user">
+  <template>
+    <div class="user">
+      <f-text path="name"></f-text>
+    </div>
+  </template>
+</f-each>
 ```
-Or reference explicitly:
+---
-```html
-<f-text store="app" path="User.Name"></f-text>
-```
+## JavaScript API
----
+```javascript
+const store = document.querySelector('f-store');
-## Event Sourcing
+// Wait for ready
+store.state.when('ready', () => {
-```js
-// Register actions
-store.on('addUser', ({ name, role }) => {
-  store.add('Users', `<User><n>${name}</n><Role>${role}</Role></User>`);
-});
+  // Get reactive node
+  const name = store.at('user.name');
-// Dispatch
-store.emit('addUser', { name: 'Bob', role: 'Developer' });
-```
+  // Read/write
+  console.log(name.value);
+  name.value = 'Bob';
----
+  // Subscribe to changes
+  name.subscribe(v => console.log('Name changed:', v));
-## Per-Node Reactivity
+  // Query multiple
+  const users = store.query('users.user');
-Every XML node is independently:
-- **Reactive** — Has its own Signal
-- **Identifiable** — `uuid` attribute (stable identity)
-- **Versioned** — `rev` for conflict detection & resolution
-- **Serializable** — `node.serialize()`
+  // Add node
+  store.add('users', '<user><n>New User</n></user>');
-```js
-const node = store.at('user.name');
+  // Remove node
+  store.remove('users.user[0]');
-node.uuid;        // "a1b2c3..." (stable identity)
-node.rev;         // "5-f94bc318..." (revision)
-node.revNumber;   // 5
-node.revId;       // "f94bc318..." (write identifier)
+  // Serialize
+  const xml = store.serialize();
-node.serialize(); // '<name uuid="..." rev="5-...">Alice</name>'
+  // Manual save
+  store.save();
+  // Apply external update
+  store.applyRemote('<n uuid="..." rev="5-abc">Value</n>');
+});
-// Subscribe to just this node
-node.subscribe(value => console.log(value));
+// Event handlers
+store.onChange(xml => console.log('Changed'));
+store.onConflict(info => console.log('Conflict:', info));
 ```
 ---
-## Revision Format (CouchDB-style)
-Flarp uses CouchDB-style revision tracking: `{number}-{uuid}`
+## Architecture
 ```
-rev="3-ee30f92d-a785-4603-b0b8-b681b8707e39"
-     │  └─ Revision UUID (fresh on each write)
-     └─ Revision number (increments)
+flarp/
+├── src/
+│   ├── core/           # Reactive primitives
+│   │   ├── Signal.js   # Synchronous reactive value
+│   │   └── State.js    # Named states (ready, synced, etc.)
+│   │
+│   ├── xml/            # XML utilities
+│   │   ├── Node.js     # Reactive node wrapper
+│   │   ├── Path.js     # Path resolution
+│   │   └── Tree.js     # Tree management
+│   │
+│   ├── sync/           # Persistence & sync
+│   │   ├── Sync.js     # Cross-tab sync with changes feed
+│   │   ├── Store.js    # FStore component
+│   │   ├── Persist.js  # Storage adapters
+│   │   └── Channel.js  # BroadcastChannel wrapper
+│   │
+│   ├── dom/            # DOM utilities
+│   │   └── find.js     # Store discovery
+│   │
+│   ├── components/     # Web Components
+│   │   ├── FText.js
+│   │   ├── FField.js
+│   │   ├── FWhen.js
+│   │   ├── FEach.js
+│   │   └── FBind.js
+│   │
+│   └── index.js        # Main exports
+│
+├── index.html          # Demo
+├── multiuser.html      # Multi-tab sync demo
+└── README.md
 ```
-**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
+## Multi-User Demo
-Tie-breaker: Sort UUIDs alphabetically, first wins
-             "56b1d51a" < "ee30f92d" → User B wins
-```
+Open `multiuser.html` in multiple browser tabs to see sync in action:
-This ensures:
-- No data loss (both writes saved with unique UUIDs)
-- Consistent winner selection (all nodes agree independently)
-- Eventual consistency across distributed systems
+1. Each tab gets a unique user ID
+2. Changes sync instantly across all tabs
+3. Conflicts are detected and resolved automatically
+4. Enable "auto-write" to stress test
-```js
-// Check for conflict
-if (node.conflictsWith(remoteRev)) {
-  console.log('Conflict detected!');
-}
+```bash
+# Start a local server
+npm run dev
-// Merge with automatic conflict resolution
-const result = node.merge(remoteXml);
-// { applied: true, conflict: true, winner: 'remote' }
+# Open multiple tabs to:
+http://localhost:8080/multiuser.html
 ```
 ---
-## Persistence
+## Saving & Persistence
-State persists to localStorage automatically:
+### Automatic
 ```html
-<f-state key="myapp" autosave="500">
+<f-store key="myapp" autosave="500">
+  <!-- Saves 500ms after last change -->
+</f-store>
 ```
-Features:
-- **Crash recovery** — Reload resumes state
-- **Cross-tab sync** — BroadcastChannel
-- **Conflict resolution** — Higher `rev` wins, `uuid` tiebreaker
----
-## Modular Architecture
-Flarp is built from composable pieces:
+### Manual
-```js
-// Just the signal primitive
-import { Signal } from 'flarp/core';
-// Just XML utilities
-import { Node, Path } from 'flarp/xml';
-// Just persistence
-import { Persist } from 'flarp/sync';
+```javascript
+store.save();  // Save now
+store.clear(); // Clear stored state
 ```
----
-## Custom Components
-```js
-import { findStore } from 'flarp';
-class UserCard extends HTMLElement {
-  connectedCallback() {
-    const store = findStore(this);
-    store.state.when('ready', () => {
-      const name = store.at('User.Name');
-      name.subscribe(v => {
-        this.innerHTML = `<h2>${v}</h2>`;
-      });
-    });
-  }
-}
+### Emergency Save
-customElements.define('user-card', UserCard);
-```
----
+Flarp automatically saves on `beforeunload` (browser close/refresh).
-## Philosophy
+### Storage Location
-1. **XML is data** — Human-readable, self-describing, AI-friendly
-2. **Signals are sync** — No scheduler, no batching, just updates
-3. **DOM is truth** — MutationObserver, not virtual DOM
-4. **State ≠ UI** — Keep them separate, connect with paths
-5. **Persist by default** — State survives refresh
+Data is stored in localStorage under `flarp-data:{key}`.
 ---
 ## Tag Naming
-**Important:** The browser's HTML parser lowercases all tag names. When you write:
+⚠️ **Use lowercase tags!** The DOM lowercases all tag names, so `<User>` becomes `<user>`. For clarity, always write lowercase:
 ```html
-<f-state>
-  <User><Name>Alice</Name></User>
-</f-state>
-```
-The DOM actually contains:
-```html
-<f-state>
-  <user><name>Alice</name></user>
-</f-state>
-```
-**Flarp handles this automatically** — path matching is case-insensitive. Both `user.name` and `User.Name` will work. However, we recommend using lowercase tags for clarity:
-```html
-<f-state>
-  <user>
-    <name>Alice</name>
-    <email>alice@example.com</email>
-  </user>
-</f-state>
+<!-- Good -->
+<f-store>
+  <user><n>Alice</n></user>
+</f-store>
+<!-- Works but confusing -->
+<f-store>
+  <User><n>Alice</n></User>
+</f-store>
 ```
 ---
 ## Browser Support
-Modern browsers with ES modules:
-- Chrome 61+
-- Firefox 60+
-- Safari 11+
-- Edge 79+
+- Modern browsers with BroadcastChannel (Chrome, Firefox, Safari, Edge)
+- Falls back to localStorage events for older browsers
+- Requires ES modules support
 ---
@@ -373,14 +385,10 @@ Modern browsers with ES modules:
 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.
+/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.
 ---
 ## License
 MIT
----
-*Built for developers who believe state management can be simple.*

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "flarp",
-  "version": "2.0.1",
-  "description": "DOM-native XML state management for Web Components",
+  "version": "2.5.1",
+  "description": "DOM-native XML state management with multi-master sync",
   "type": "module",
   "main": "src/index.js",
   "module": "src/index.js",

package/src/components/index.js CHANGED Viewed

@@ -2,7 +2,9 @@
  * Flarp Web Components
  */
-export { default as FStore } from './FStore.js';
+// FStore is in sync module for better organization
+export { FStore } from '../sync/index.js';
 export { default as FText } from './FText.js';
 export { default as FField } from './FField.js';
 export { default as FBind } from './FBind.js';