jprx 1.3.0 → 1.4.0

package/README.md

@@ -2,6 +2,8 @@
 
 **JPRX** is a declarative, reactive expression syntax designed for JSON-based data structures. It extends [JSON Pointer (RFC 6901)](https://www.rfc-editor.org/rfc/rfc6901) with reactivity, relative paths, operator syntax, and a rich library of helper functions.
 
+> **v1.4.0 Syntax Update**: JPRX now uses a wrapper syntax `=(expr)` for unambiguous expression parsing. Legacy prefix-only syntax (e.g., `=/path`) is still supported but will be deprecated after March 31, 2026.
+
 ## Overview
 
 JPRX is a **syntax** and an **expression engine**. While this repository provides the parser and core helper functions, JPRX is intended to be integrated into UI libraries or state management systems that can "hydrate" these expressions into active reactive bindings.
@@ -26,17 +28,17 @@ JPRX extends the base JSON Pointer syntax with:
 
 | Feature | Syntax | Description |
 |---------|--------|-------------|
-| **Global Path** | `=/user/name` | Access global state via an absolute path. |
-| **Relative Path** | `./count` | Access properties relative to the current context. |
-| **Parent Path** | `../id` | Traverse up the state hierarchy (UP-tree search). |
-| **Functions** | `=sum(/items...price)` | Call registered core helpers. |
-| **Explosion** | `/items...name` | Extract a property from every object in an array (spread). |
-| **Operators** | `=++/count`, `=/a + =/b` | Familiar JS-style prefix, postfix, and infix operators. |
+| **Global Path** | `=(/user/name)` | Access global state via an absolute path. |
+| **Relative Path** | `=(./count)` | Access properties relative to the current context. |
+| **Parent Path** | `=(../id)` | Traverse up the state hierarchy (UP-tree search). |
+| **Functions** | `=(sum(/items...price))` | Call registered core helpers. |
+| **Explosion** | `=(/items...name)` | Extract a property from every object in an array (spread). |
+| **Operators** | `=(++/count)`, `=(/a + /b)` | Familiar JS-style prefix, postfix, and infix operators. |
 | **Placeholders** | `_` (item), `$this`, `$event` | Context-aware placeholders for iteration and interaction. |
-| **Two-Way Binding**| `=bind(/user/name)`| Create a managed, two-way reactive link for inputs. |
-| **DOM Patches**    | `=move(target, loc)`| Decentralized layout: Move/replace host element into a target. |
+| **Two-Way Binding**| `=(bind(/user/name))`| Create a managed, two-way reactive link for inputs. |
+| **DOM Patches**    | `=(move(target, loc))`| Decentralized layout: Move/replace host element into a target. |
 
-Once inside a JPRX expression, the `=` prefix is only needed at the start of the expression for paths or function names.
+**Note**: For initialization functions like `state()` and `signal()`, use `=function(...)` without the outer wrapper, as they execute once on mount rather than being reactive expressions.
 
 
 ## State Management
@@ -104,7 +106,7 @@ To ensure unambiguous data flow, `=bind` only accepts direct paths. It cannot be
 
 ### Handling Transformations
 If you need to transform data during a two-way binding, there are two primary approaches:
-1. **Event-Based**: Use a manual `oninput` handler to apply the transformation, e.g., `=set(/name, upper($event/target/value))`.
+1. **Event-Based**: Use a manual `oninput` handler to apply the transformation, e.g., `=(set(/name, upper($event/target/value)))`.
 2. **Schema-Based**: Define a `transform` or `pattern` in the schema for the path. The `=bind` helper will respect the schema rules during the write-back phase.
 
 ---
@@ -159,9 +161,9 @@ A modern, lifecycle-based reactive counter:
     "onmount": "=state({ count: 0 }, { name: 'counter', schema: 'auto', scope: $this })",
     "children": [
       { "h2": "Modern JPRX Counter" },
-      { "p": ["Current Count: ", "=/counter/count"] },
-      { "button": { "onclick": "=++/counter/count", "children": ["+"] } },
-      { "button": { "onclick": "=--/counter/count", "children": ["-"] } }
+      { "p": ["Current Count: ", "=(/counter/count)"] },
+      { "button": { "onclick": "=(++/counter/count)", "children": ["+"] } },
+      { "button": { "onclick": "=(--/counter/count)", "children": ["-"] } }
     ]
   }
 }

package/index.js

@@ -19,7 +19,8 @@ export {
     resolvePathAsContext,
     resolveExpression,
     parseCDOMC,
-    parseJPRX,
+    parseCDOMC as parseJPRX,
+    parseJPRX as oldParseJPRX,
     unwrapSignal,
     getRegistry,
     BindingTarget

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "jprx",
-    "version": "1.3.0",
+    "version": "1.4.0",
     "description": "JSON Path Reactive eXpressions - A reactive expression language for JSON data",
     "main": "index.js",
     "type": "module",

package/parser.js

@@ -1409,6 +1409,7 @@ export const parseExpression = (expr, context) => {
  * Supports unquoted keys/values and strictly avoids 'eval'.
  */
 export const parseCDOMC = (input) => {
+    if (typeof input !== 'string') return input;
     let i = 0;
     const len = input.length;
 
@@ -1666,6 +1667,7 @@ export const parseCDOMC = (input) => {
  * @returns {object} - Parsed JSON object
  */
 export const parseJPRX = (input) => {
+    if (typeof input !== 'string') return input;
     let result = '';
     let i = 0;
     const len = input.length;
@@ -1728,7 +1730,44 @@ export const parseJPRX = (input) => {
             continue;
         }
 
-        // Handle JPRX expressions starting with = (MUST come before word handler!)
+        // Handle JPRX expressions starting with = or #
+        // New wrapper syntax: =(expr) or #(xpath)
+        if ((char === '=' || char === '#') && input[i + 1] === '(') {
+            const prefix = char;
+            let expr = prefix;
+            i++; // skip = or #
+            let parenDepth = 0;
+            let inExprQuote = null;
+
+            while (i < len) {
+                const c = input[i];
+
+                if (inExprQuote) {
+                    if (c === inExprQuote && input[i - 1] !== '\\') inExprQuote = null;
+                } else if (c === '"' || c === "'") {
+                    inExprQuote = c;
+                } else {
+                    if (c === '(') parenDepth++;
+                    else if (c === ')') {
+                        parenDepth--;
+                        if (parenDepth === 0) {
+                            expr += c;
+                            i++;
+                            break;
+                        }
+                    }
+                }
+
+                expr += c;
+                i++;
+            }
+
+            // Use JSON.stringify to safely quote and escape the expression
+            result += JSON.stringify(expr);
+            continue;
+        }
+
+        // Handle legacy JPRX expressions starting with = (without parentheses)
         if (char === '=') {
             let expr = '';
             let parenDepth = 0;
@@ -1790,10 +1829,57 @@ export const parseJPRX = (input) => {
             continue;
         }
 
+        // Handle XPath expressions starting with # (legacy syntax)
+        if (char === '#') {
+            let expr = '';
+            let parenDepth = 0;
+            let bracketDepth = 0;
+            let inExprQuote = null;
+
+            while (i < len) {
+                const c = input[i];
+
+                if (inExprQuote) {
+                    if (c === inExprQuote && input[i - 1] !== '\\') inExprQuote = null;
+                } else if (c === '"' || c === "'") {
+                    inExprQuote = c;
+                } else {
+                    // Check for break BEFORE updating depth
+                    if (parenDepth === 0 && bracketDepth === 0) {
+                        // Break on structural characters at depth 0
+                        if (/[}[\],:]/.test(c) && expr.length > 1) break;
+                        // For whitespace, peek ahead
+                        if (/\s/.test(c)) {
+                            let j = i + 1;
+                            while (j < len && /\s/.test(input[j])) j++;
+                            if (j < len) {
+                                const nextChar = input[j];
+                                if (nextChar === '}' || nextChar === ',' || nextChar === ']') {
+                                    break;
+                                }
+                            }
+                        }
+                    }
+
+                    if (c === '(') parenDepth++;
+                    else if (c === ')') parenDepth--;
+                    else if (c === '[') bracketDepth++;
+                    else if (c === ']') bracketDepth--;
+                }
+
+                expr += c;
+                i++;
+            }
+
+            // Use JSON.stringify to safely quote and escape the expression
+            result += JSON.stringify(expr);
+            continue;
+        }
+
         // Handle unquoted property names, identifiers, paths, and FUNCTION CALLS
-        if (/[a-zA-Z_$/./]/.test(char)) {
+        if (/[a-zA-Z_$\/.\/]/.test(char)) {
             let word = '';
-            while (i < len && /[a-zA-Z0-9_$/.-]/.test(input[i])) {
+            while (i < len && /[a-zA-Z0-9_$\/.-]/.test(input[i])) {
                 word += input[i];
                 i++;
             }