assign-gingerly 0.0.60 → 0.0.61

package/README.md

@@ -300,7 +300,7 @@ In real-world use cases, you often need to replace one object with another of a
 
 **Exception: classes with `static assignTo`**
 
-If the current value is an instance of a class that defines [`static assignTo`](#custom-assignment-with-static-assignto-protocol), that method is called instead of replacing. This allows classes to opt into custom assignment behavior (e.g., reactive models, validated records, iterable collections with private lists):
+If the current value is an instance of a class that defines `static assignTo`, that method is called instead of replacing. This allows classes to opt into custom assignment behavior (e.g., reactive models, validated records, iterable collections with private lists). See the full [Custom Assignment with `static assignTo` Protocol](#custom-assignment-with-static-assignto-protocol) section below for details, examples, and the method signature.
 
 ```TypeScript
 class TodoList {
@@ -4237,6 +4237,42 @@ get: {
 
 For full details, see [docs/manage-template-list.md](docs/manage-template-list.md).
 
+### Built-in handler: `builtIns.rangeSelector`
+
+Evaluates a value against a series of range conditions and merges the matched case's properties into the target. Converts imperative if/else-if chains into declarative JSON configs.
+
+```JavaScript
+assignFrom(element, {
+    '?. =>': {
+        do: 'builtIns.rangeSelector',
+        get: {
+            value: '?.count',
+            when: [
+                { '<=': 10, merge: { status: 'low', statusMessage: 'Low count' } },
+                { '<': 20, merge: { status: 'medium', statusMessage: 'Medium count' } },
+                { merge: { status: 'high', statusMessage: 'High count!' } }
+            ]
+        }
+    }
+}, { from: vm });
+```
+
+**How it works:**
+
+1. Resolves `value` from the source (e.g., `vm.count`)
+2. Iterates `when` cases in order — first match wins
+3. Each case can have operator keys (`<=`, `<`, `>=`, `>`, `===`, `!==`) as conditions
+4. Multiple operators per case = AND logic (e.g., `{ '>=': 10, '<': 20, merge: {...} }`)
+5. No operator keys = default/catch-all
+6. Merges the matched case's `merge` object into the target via `assignGingerly`
+
+**Supported operators:** `<=`, `<`, `>=`, `>`, `===`, `!==`
+
+**Notes:**
+- Comparison uses JavaScript semantics (`false < true`, strings compare lexicographically)
+- Fully JSON-serializable — no functions, no special types
+- Lazy-loaded on demand like all built-in handlers
+
 ## Typed Path Authoring with `paths`, `sp`, and `md`
 
 For JSON generated config files generated from TypeScript/`.mts`/`mjs` files during a build or server-side rendering, the `paths` utility provides compile-time autocomplete and type safety for `?.`-prefixed path strings. The `sp` tagged template literal ("split into parts") produces arrays suitable for `builtIns.join`. The `md` tagged template literal produces `{prop, val}` objects suitable for `builtIns.microDataJoin`.
@@ -4595,7 +4631,7 @@ assignGingerly(shadowRoot, {
 
 ## Custom Assignment with `static assignTo` Protocol
 
-Classes can opt into custom assignment behavior by defining a `static assignTo` method. When `assignGingerly` encounters a property whose current value is an instance of such a class, it delegates the assignment to `assignTo` instead of performing the default merge/replace logic.
+As [introduced earlier](#example-3b---class-instances-are-normally-replaced), classes can opt into custom assignment behavior by defining a `static assignTo` method. When `assignGingerly` encounters a property whose current value is an instance of such a class, it delegates the assignment to `assignTo` instead of performing the default merge/replace logic. This section covers the full API, method signature, and advanced use cases.
 
 ```JavaScript
 class ReactiveModel {

package/builtInEmoji.js

@@ -20,6 +20,7 @@ export const builtInEmoji = {
     '🔗': 'builtIns.join',
     '🏷️': 'builtIns.microDataJoin',
     '📋': 'builtIns.manageTemplateList',
+    '📊': 'builtIns.rangeSelector',
 };
 
 export default builtInEmoji;

package/builtInEmoji.ts

@@ -28,6 +28,7 @@ export const builtInEmoji: Record<string, string> = {
     '🔗': 'builtIns.join',
     '🏷️': 'builtIns.microDataJoin',
     '📋': 'builtIns.manageTemplateList',
+    '📊': 'builtIns.rangeSelector',
 };
 
 export default builtInEmoji;

package/handlers/rangeSelector.js

@@ -0,0 +1,52 @@
+/**
+ * builtIns.rangeSelector handler for assignFrom.
+ * 
+ * Evaluates a value against a series of range conditions and merges
+ * the matched case's properties into the target.
+ */
+
+import assignGingerly from '../assignGingerly.js';
+
+const OPERATORS = new Set(['<=', '<', '>=', '>', '===', '!==']);
+
+function checkCondition(value, op, threshold) {
+    switch (op) {
+        case '<=': return value <= threshold;
+        case '<': return value < threshold;
+        case '>=': return value >= threshold;
+        case '>': return value > threshold;
+        case '===': return value === threshold;
+        case '!==': return value !== threshold;
+        default: return false;
+    }
+}
+
+function caseMatches(value, caseObj) {
+    for (const key of Object.keys(caseObj)) {
+        if (OPERATORS.has(key)) {
+            if (!checkCondition(value, key, caseObj[key])) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+
+export class RangeSelectorHandler {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async assign(lhsTarget, resolvedParams) {
+        const { value, when } = resolvedParams;
+        if (!Array.isArray(when)) return;
+        for (const caseObj of when) {
+            if (caseMatches(value, caseObj)) {
+                if (caseObj.merge && typeof caseObj.merge === 'object') {
+                    assignGingerly(lhsTarget, caseObj.merge);
+                }
+                return;
+            }
+        }
+    }
+}

package/handlers/rangeSelector.ts

@@ -0,0 +1,90 @@
+/**
+ * builtIns.rangeSelector handler for assignFrom.
+ * 
+ * Evaluates a value against a series of range conditions and merges
+ * the matched case's properties into the target. Useful for converting
+ * imperative if/else-if chains into declarative JSON configs.
+ * 
+ * @example
+ * assignFrom(element, {
+ *     '?. =>': {
+ *         do: 'builtIns.rangeSelector',
+ *         get: {
+ *             value: '?.count',
+ *             when: [
+ *                 { '<=': 10, merge: { status: 'low' } },
+ *                 { '<': 20, merge: { status: 'medium' } },
+ *                 { merge: { status: 'high' } }
+ *             ]
+ *         }
+ *     }
+ * }, { from: vm });
+ */
+
+import type { AssignFromHandler } from '../assignFromAsync.js';
+import assignGingerly from '../assignGingerly.js';
+
+/**
+ * Operator keys recognized in case objects.
+ */
+const OPERATORS = new Set(['<=', '<', '>=', '>', '===', '!==']);
+
+/**
+ * Check if a single operator condition is satisfied.
+ */
+function checkCondition(value: any, op: string, threshold: any): boolean {
+    switch (op) {
+        case '<=': return value <= threshold;
+        case '<': return value < threshold;
+        case '>=': return value >= threshold;
+        case '>': return value > threshold;
+        case '===': return value === threshold;
+        case '!==': return value !== threshold;
+        default: return false;
+    }
+}
+
+/**
+ * Check if all operator conditions in a case object are satisfied (AND logic).
+ * Returns true if no operator keys present (catch-all/default case).
+ */
+function caseMatches(value: any, caseObj: Record<string, any>): boolean {
+    let hasCondition = false;
+    for (const key of Object.keys(caseObj)) {
+        if (OPERATORS.has(key)) {
+            hasCondition = true;
+            if (!checkCondition(value, key, caseObj[key])) {
+                return false;
+            }
+        }
+    }
+    // No operator keys = default/catch-all
+    return true;
+}
+
+/**
+ * RangeSelectorHandler — declarative range-based conditional merge.
+ */
+export class RangeSelectorHandler implements AssignFromHandler {
+    config: any;
+
+    constructor(config: any) {
+        this.config = config;
+    }
+
+    async assign(lhsTarget: any, resolvedParams: any): Promise<void> {
+        const { value, when } = resolvedParams;
+
+        if (!Array.isArray(when)) return;
+
+        // Find first matching case (short-circuit)
+        for (const caseObj of when) {
+            if (caseMatches(value, caseObj)) {
+                if (caseObj.merge && typeof caseObj.merge === 'object') {
+                    assignGingerly(lhsTarget, caseObj.merge);
+                }
+                return; // First match wins
+            }
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.60",
+  "version": "0.0.61",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {

package/processHandlerCommands.js

@@ -17,6 +17,7 @@ const BUILT_IN_MAP = {
     'builtIns.join': './handlers/join.js',
     'builtIns.microDataJoin': './handlers/microDataJoin.js',
     'builtIns.manageTemplateList': './handlers/manageTemplateList.js',
+    'builtIns.rangeSelector': './handlers/rangeSelector.js',
 };
 /**
  * Find a handler class in a dynamically imported module.

package/processHandlerCommands.ts

@@ -21,6 +21,7 @@ const BUILT_IN_MAP: Record<string, string> = {
     'builtIns.join': './handlers/join.js',
     'builtIns.microDataJoin': './handlers/microDataJoin.js',
     'builtIns.manageTemplateList': './handlers/manageTemplateList.js',
+    'builtIns.rangeSelector': './handlers/rangeSelector.js',
 };
 
 /**