jprx 1.0.0 → 1.1.0

package/README.md

@@ -10,8 +10,15 @@ JPRX is a **syntax** and an **expression engine**. While this repository provide
 
 - **Declarative Power**: Define relationships between data points as easily as writing an Excel formula.
 - **Security**: JPRX strictly avoids `eval()`. Expressions are handled by a custom high-performance Pratt parser and a registry of pre-defined helpers, making it safe for dynamic content.
-- **Portability**: Because JPRX expressions are strings within JSON structures, they are easily serialized, stored, and sent over the wire.
-- **Platform Agnostic**: While Lightview is the first implementation, JPRX can be used in any environment that manages reactive state.
+- **Portability**: JPRX expressions are strings within JSON, making them easily serialized and platform-agnostic.
+- **Schema-First**: Integrated support for JSON Schema and shorthand descriptors provides industrial-strength validation and "future-proof" reactivity.
+
+## UI Library Requirements
+
+To fully support JPRX, an underlying UI library **MUST** provide:
+- **Mount Lifecycle**: A hook (e.g., `onmount`) where state initialization can occur. JPRX relies on the library to trigger these initializers.
+- **Event Handling**: Support for standard event handlers (like `oninput`, `onclick`) **SHOULD** be provided, though exact implementations may vary by platform.
+- **Reactivity**: A way to resolve paths to reactive primitives (e.g., Signals or Proxies).
 
 ## Syntax & Features
 
@@ -21,110 +28,102 @@ JPRX extends the base JSON Pointer syntax with:
 |---------|--------|-------------|
 | **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. |
+| **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), `$event` | Context-aware placeholders for iteration and interaction. |
-
-## Human & AI Utility
-
-JPRX is uniquely positioned to bridge the gap between human developers and AI coding assistants:
-
-### For Humans: "The Excel Paradigm"
-Humans are often familiar with the "recalculation" model of spreadsheets. JPRX brings this to UI development. Instead of writing complex "glue code" (event listeners, state updates, DOM manipulation), developers specify the *formula* for a UI element once, and it stays updated forever.
+| **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. |
 
-### For AI: Structured & Concise
-Large Language Models (LLMs) are exceptionally good at generating structured data (JSON) and formulaic expressions. They are often prone to errors when generating large blocks of imperative JavaScript logic. JPRX provides a high-level, declarative "target" for AI to aim at, resulting in:
-- **Higher Accuracy**: Less boilerplate means fewer places for the AI to hallucinate.
-- **Safety**: AI can generate UI logic that remains sandboxed and secure.
-- **Compactness**: Entire interactive components can be described in a few lines of JSON.
+Once inside a JPRX expression, the `$` prefix is only needed at the start of the expression for paths or function names.
 
-## Operators
+## State Management
 
-JPRX supports a wide range of operators that provide a more concise and familiar syntax than function calls.
+JPRX utilizes explicit state initializers within lifecycle hooks:
 
-### Arithmetic & Logic (Infix)
-Infix operators require surrounding whitespace in JPRX to avoid ambiguity with path separators.
+### Scoped State
+States can be attached to specific scopes (such as a DOM node or Component instance) using the `scope` property in the options argument.
+- **Up-tree Resolution**: When resolving a path, JPRX walks up the provided scope chain looking for the nearest owner of that name.
+- **Future Signals**: JPRX allows subscription to a named signal *before* it is initialized. The system will automatically "hook up" once the state is created via `$state` or `$signal`.
 
-- **Arithmetic**: `+`, `-`, `*`, `/`, `mod`, `pow`
-- **Comparison**: `>`, `<`, `>=`, `<=`, `==`, `!=`
-- **Logic**: `&&`, `||`
+### The `$state` and `$signal` Helpers
+- `$state(value, { name: 'user', schema: 'UserProfile', scope: event.target })`
+- `$signal(0, { name: 'count', schema: 'auto' })`
 
-*Example:* `$/a + $/b * 10 > $/threshold`
+## Schema Registry & Validation
 
-### Mutation & Unary (Prefix/Postfix)
-These operators are typically used in event handlers or for immediate state transformation.
+JPRX integrates with a global Schema Registry via `jprx.registerSchema(name, definition)`.
 
-- **Increment**: `$++/count` (prefix) or `$/count++` (postfix)
-- **Decrement**: `$--/count` (prefix) or `$/count--` (postfix)
-- **Toggle**: `$!!/enabled` (logical NOT/toggle)
+### Registering and Using Schemas
+```javascript
+// 1. Register a schema centrally
+jprx.registerSchema('UserProfile', {
+  name: "string",
+  age: "number",
+  email: { type: "string", format: "email" }
+});
 
-## Helper Functions
+// 2. Reference the registered schema by name (Scoped)
+const user = $state({}, { name: 'user', schema: 'UserProfile', scope: $this });
 
-JPRX includes a comprehensive library of built-in helpers. For security, only registered helpers are available—there is no access to the global JavaScript environment.
-
-### Math
-`add`, `sub`, `mul`, `div`, `mod`, `pow`, `sqrt`, `abs`, `round`, `ceil`, `floor`, `min`, `max`
-
-### Stats
-`sum`, `avg`, `min`, `max`, `median`, `stdev`, `var`
+// 3. Use the 'polymorphic' shorthand for auto-coercion
+const settings = $state({ volume: 50 }, { name: 'settings', schema: 'polymorphic' });
+// Result: settings.volume = "60" will automatically coerce to the number 60.
+```
 
-### String
-`upper`, `lower`, `trim`, `capitalize`, `titleCase`, `contains`, `startsWith`, `endsWith`, `replace`, `split`, `join`, `concat`, `len`, `default`
+- **Polymorphic Schemas**:
+  - **`"auto"`**: Infers the fixed schema from the initial value. Strict type checking (e.g., setting a number to a string throws). New properties are not allowed.
+  - **`"dynamic"`**: Like `auto`, but allows new properties to be added to the state object.
+  - **`"polymorphic"`**: Includes **`dynamic`** behavior and automatically coerces values to match the inferred type (e.g., "50" -> 50) rather than throwing.
+  - **Shorthand**: A simple object like `{ name: "string" }` is internally normalized to a JSON Schema.
 
-### Array
-`count`, `map`, `filter`, `find`, `unique`, `sort`, `reverse`, `first`, `last`, `slice`, `flatten`, `join`, `len`
+### Transformation Schemas
+Schemas can define transformations that occur during state updates, ensuring data remains in a consistent format regardless of how it was input.
 
-### Logic & Comparison
-`if`, `and`, `or`, `not`, `eq`, `neq`, `gt`, `lt`, `gte`, `lte`, `between`, `in`
+```json
+{
+  "type": "object",
+  "properties": {
+    "username": {
+      "type": "string",
+      "transform": "lower"
+    }
+  }
+}
+```
+*Note: The `$bind` helper uses these transformations to automatically clean data as the user types.*
 
-### Formatting
-`number`, `currency`, `percent`, `thousands`
+## Two-Way Binding with `$bind`
 
-### DateTime
-`now`, `today`, `date`, `formatDate`, `year`, `month`, `day`, `weekday`, `addDays`, `dateDiff`
+The `$bind(path)` helper creates a managed, two-way link between the UI and a state path.
 
-### Lookup
-`lookup`, `vlookup`, `index`, `match`
+### Strictness
+To ensure unambiguous data flow, `$bind` only accepts direct paths. It cannot be used directly with computed expressions like `$bind(upper(/name))`.
 
-### State Mutation
-`set`, `increment`, `decrement`, `toggle`, `push`, `pop`, `assign`, `clear`
+### 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))`.
+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.
 
-### Network
-`fetch(url, options?)` - *Auto-serializes JSON bodies and handles content-types.*
+---
 
 ## Example
 
-A simple reactive counter described in JPRX syntax:
+A modern, lifecycle-based reactive counter:
 
 ```json
 {
   "div": {
-    "cdom-state": { "count": 0 },
+    "onmount": $state({ count: 0 }, { name: 'counter', schema: 'auto', scope: $this }),
     "children": [
-      { "h2": "Counter" },
-      { "p": ["Current Count: ", "$/count"] },
-      { "button": { "onclick": "$increment(/count)", "children": ["+"] } },
-      { "button": { "onclick": "$decrement(/count)", "children": ["-"] } }
+      { "h2": "Modern JPRX Counter" },
+      { "p": ["Current Count: ", $/counter/count] },
+      { "button": { "onclick": $++/counter/count, "children": ["+"] } },
+      { "button": { "onclick": $--/counter/count, "children": ["-"] } }
     ]
   }
 }
 ```
 
-## Reference Implementation: Lightview
-
-JPRX was originally developed for [Lightview](https://github.com/anywhichway/lightview) to power its **Computational DOM (cDOM)**. Lightview serves as the primary example of how a UI library can hydrate JPRX expressions into a live, reactive interface.
-
-If you are building a UI library and want to support reactive JSON structures, this parser provides the foundation.
-
-## Getting Started
-
-The JPRX package contains:
-1. `parser.js`: The core Pratt parser and path resolution logic.
-2. `helpers/`: A comprehensive library of math, logic, string, array, formatting, and state helpers.
-
-To use JPRX, you typically register your state-management primitives (like Signals or Proxies) with the parser's registry, and then call `hydrate()` or `resolveExpression()` to activate the logic.
-
 ---
 © 2026 Simon Y. Blackwell, AnyWhichWay LLC. Licensed under MIT.

package/helpers/state.js

@@ -64,6 +64,24 @@ export const clear = (target) => {
     return set(target, null);
 };
 
+export function $state(val, options) {
+    if (globalThis.Lightview) {
+        const finalOptions = typeof options === 'string' ? { name: options } : options;
+        return globalThis.Lightview.state(val, finalOptions);
+    }
+    throw new Error('JPRX: $state requires a UI library implementation.');
+}
+
+export function $signal(val, options) {
+    if (globalThis.Lightview) {
+        const finalOptions = typeof options === 'string' ? { name: options } : options;
+        return globalThis.Lightview.signal(val, finalOptions);
+    }
+    throw new Error('JPRX: $signal requires a UI library implementation.');
+}
+
+export const $bind = (path, options) => ({ __JPRX_BIND__: true, path, options });
+
 export const registerStateHelpers = (register) => {
     const opts = { pathAware: true };
     register('set', set, opts);
@@ -77,4 +95,7 @@ export const registerStateHelpers = (register) => {
     register('pop', pop, opts);
     register('assign', assign, opts);
     register('clear', clear, opts);
+    register('state', $state);
+    register('signal', $signal);
+    register('bind', $bind);
 };

package/package.json

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

package/parser.js

@@ -28,6 +28,9 @@ const DEFAULT_PRECEDENCE = {
  */
 export const registerHelper = (name, fn, options = {}) => {
     helpers.set(name, fn);
+    if (globalThis.__LIGHTVIEW_INTERNALS__) {
+        globalThis.__LIGHTVIEW_INTERNALS__.helpers.set(name, fn);
+    }
     if (options) helperOptions.set(name, options);
 };
 
@@ -134,27 +137,12 @@ export const resolvePath = (path, context) => {
     if (path === '.') return unwrapSignal(context);
 
     // Global absolute path: $/something
-    // First check if the root is in the local context's state (cdom-state)
-    // This allows $/cart to resolve from cdom-state: { cart: {...} }
     if (path.startsWith('$/')) {
         const [rootName, ...rest] = path.slice(2).split('/');
-
-        // Check local state chain first (via __state__ property set by handleCDOMState)
-        let cur = context;
-        while (cur) {
-            const localState = cur.__state__;
-            if (localState && rootName in localState) {
-                return traverse(localState[rootName], rest);
-            }
-            cur = cur.__parent__;
-        }
-
-        // Then check global registry
-        const rootSignal = registry?.get(rootName);
-        if (!rootSignal) return undefined;
-
-        // Root can be a signal or a state proxy
-        return traverse(rootSignal, rest);
+        const LV = getLV();
+        const root = LV ? LV.get(rootName, { scope: context?.__node__ || context }) : registry?.get(rootName);
+        if (!root) return undefined;
+        return traverse(root, rest);
     }
 
     // Relative path from current context
@@ -197,26 +185,13 @@ export const resolvePathAsContext = (path, context) => {
     if (path === '.') return context;
 
     // Global absolute path: $/something
-    // First check if the root is in the local context's state (cdom-state)
     if (path.startsWith('$/')) {
         const segments = path.slice(2).split(/[/.]/);
         const rootName = segments.shift();
-
-        // Check local state chain first
-        let cur = context;
-        while (cur) {
-            const localState = cur.__state__;
-            if (localState && rootName in localState) {
-                return traverseAsContext(localState[rootName], segments);
-            }
-            cur = cur.__parent__;
-        }
-
-        // Then check global registry
-        const rootSignal = registry?.get(rootName);
-        if (!rootSignal) return undefined;
-
-        return traverseAsContext(rootSignal, segments);
+        const LV = getLV();
+        const root = LV ? LV.get(rootName, { scope: context?.__node__ || context }) : registry?.get(rootName);
+        if (!root) return undefined;
+        return traverseAsContext(root, segments);
     }
 
     // Relative path from current context
@@ -260,6 +235,11 @@ class LazyValue {
     }
 }
 
+/**
+ * Node helper - identifies if a value is a DOM node.
+ */
+const isNode = (val) => val && typeof val === 'object' && globalThis.Node && val instanceof globalThis.Node;
+
 /**
  * Helper to resolve an argument which could be a literal, a path, or an explosion.
  * @param {string} arg - The argument string
@@ -294,10 +274,23 @@ const resolveArgument = (arg, context, globalMode = false) => {
         };
     }
 
-    // 5. Event Placeholder ($event)
+    // 5. Context Identifiers ($this, $event)
+    if (arg === '$this' || arg.startsWith('$this/') || arg.startsWith('$this.')) {
+        return {
+            value: new LazyValue((context) => {
+                const node = context?.__node__ || context;
+                if (arg === '$this') return node;
+                const path = arg.startsWith('$this.') ? arg.slice(6) : arg.slice(6);
+                return resolvePath(path, node);
+            }),
+            isLazy: true
+        };
+    }
+
     if (arg === '$event' || arg.startsWith('$event/') || arg.startsWith('$event.')) {
         return {
-            value: new LazyValue((event) => {
+            value: new LazyValue((context) => {
+                const event = context?.$event || context?.event || context;
                 if (arg === '$event') return event;
                 const path = arg.startsWith('$event.') ? arg.slice(7) : arg.slice(7);
                 return resolvePath(path, event);
@@ -319,6 +312,18 @@ const resolveArgument = (arg, context, globalMode = false) => {
                         const final = (res instanceof LazyValue) ? res.resolve(context) : res;
                         return unwrapSignal(final);
                     }
+                    if (node === '$this' || node.startsWith('$this/') || node.startsWith('$this.')) {
+                        const path = (node.startsWith('$this.') || node.startsWith('$this/')) ? node.slice(6) : node.slice(6);
+                        const ctxNode = context?.__node__ || context;
+                        const res = node === '$this' ? ctxNode : resolvePath(path, ctxNode);
+                        return unwrapSignal(res);
+                    }
+                    if (node === '$event' || node.startsWith('$event/') || node.startsWith('$event.')) {
+                        const path = (node.startsWith('$event.') || node.startsWith('$event/')) ? node.slice(7) : node.slice(7);
+                        const event = context?.$event || context?.event || (context && !isNode(context) ? context : null);
+                        const res = node === '$event' ? event : resolvePath(path, event);
+                        return unwrapSignal(res);
+                    }
                     if (node === '_' || node.startsWith('_/') || node.startsWith('_.')) {
                         const path = (node.startsWith('_.') || node.startsWith('_/')) ? node.slice(2) : node.slice(2);
                         const res = node === '_' ? context : resolvePath(path, context);
@@ -433,6 +438,7 @@ const TokenType = {
     COMMA: 'COMMA',         // ,
     EXPLOSION: 'EXPLOSION', // ... suffix
     PLACEHOLDER: 'PLACEHOLDER', // _, _/path
+    THIS: 'THIS',           // $this
     EVENT: 'EVENT',         // $event, $event.target
     EOF: 'EOF'
 };
@@ -620,6 +626,18 @@ const tokenize = (expr) => {
             continue;
         }
 
+        // $this placeholder
+        if (expr.slice(i, i + 5) === '$this') {
+            let thisPath = '$this';
+            i += 5;
+            while (i < len && /[a-zA-Z0-9_./]/.test(expr[i])) {
+                thisPath += expr[i];
+                i++;
+            }
+            tokens.push({ type: TokenType.THIS, value: thisPath });
+            continue;
+        }
+
         // $event placeholder
         if (expr.slice(i, i + 6) === '$event') {
             let eventPath = '$event';
@@ -871,6 +889,12 @@ class PrattParser {
             return { type: 'Placeholder', value: tok.value };
         }
 
+        // This
+        if (tok.type === TokenType.THIS) {
+            this.consume();
+            return { type: 'This', value: tok.value };
+        }
+
         // Event
         if (tok.type === TokenType.EVENT) {
             this.consume();
@@ -927,8 +951,18 @@ const evaluateAST = (ast, context, forMutation = false) => {
             });
         }
 
+        case 'This': {
+            return new LazyValue((context) => {
+                const node = context?.__node__ || context;
+                if (ast.value === '$this') return node;
+                const path = ast.value.startsWith('$this.') ? ast.value.slice(6) : ast.value.slice(6);
+                return resolvePath(path, node);
+            });
+        }
+
         case 'Event': {
-            return new LazyValue((event) => {
+            return new LazyValue((context) => {
+                const event = context?.$event || context?.event || context;
                 if (ast.value === '$event') return event;
                 const path = ast.value.startsWith('$event.') ? ast.value.slice(7) : ast.value.slice(7);
                 return resolvePath(path, event);
@@ -1117,7 +1151,7 @@ export const resolveExpression = (expr, context) => {
             });
         }
 
-        const result = helper(...resolvedArgs);
+        const result = helper.apply(context?.__node__ || null, resolvedArgs);
         return unwrapSignal(result);
     }