assign-gingerly 0.0.90 → 0.0.91

package/README.md

@@ -102,6 +102,8 @@ assignFrom adds support for:
 5.  Looped substitution with `where_x_in` / `where_y_in` / `where_z_in` for expanding template patterns into multiple concrete assignments.
 6.  Dynamic substitutions via the `substitutions` option for injecting runtime string values into path segments. See [docs/substitutions.md](docs/substitutions.md).
 7.  Spread merging via the `"..."` key.
+8.  Boolean coercion / negation of a resolved value via a leading `!` marker: `'!!?.isOpen'` resolves `?.isOpen` then coerces to a real boolean, `'!?.isOpen'` negates it (`!!!` negates, and so on). Only honored in front of a `?.` path, `$0` reference, or protocol — a plain literal like `'!important'` is left untouched. Nullish coerces to `false`, which makes `!!` the safe way to feed an optional source value into a boolean sink (`hidden`, `disabled`, `classList.toggle`'s force argument, …).
+9.  Multiple invocations of one `withMethods` method via the ` =*` operator — see [docs/multi-invoke.md](docs/multi-invoke.md).
 
 Example:
 
@@ -853,6 +855,7 @@ While we are in the business of passing values of object A into object B, we mig
 | ` ?=` | Ternary | Conditional assignment (assignFrom only) — [details](docs/ternary-assignment.md) | `'?.text ?=': ['?.cond', 'yes', 'no']` |
 | ` =>` | Handler | Invoke a handler plugin (assignFrom only) | `'?.el =>': { do: 'builtIns.lazyLoad', ... }` |
 | ` =&` | Sync op | Compute a value synchronously and assign it back (assignFrom only) — no dynamic import, no await, ever | `'?.text =&': { join: ['?.first', ' ', '?.last'] }` |
+| ` =*` | Multi-invoke | Call a `withMethods` method once per argument-list (assignFrom only) — [details](docs/multi-invoke.md) | `` '?.classList?.toggle =*': [['a', '!!?.x'], ['b', '!!?.y']] `` |
 
 All operators use a space before the suffix to distinguish them from property names. They compose with `?.` nested paths and `withMethods`.
 
@@ -957,6 +960,45 @@ The `=!` command syntax is `<path> =!` where the path uses the `?.` nested notat
 
 For existing values, the toggle is performed using JavaScript's logical NOT operator (`!value`), regardless of what type it is.
 
+## Example 5a - Conditional class lists with the `!!` marker and `=*` command
+
+The imperative pattern
+
+```JS
+if (vm.isOpen) el.classList.add('isOpenCls');
+else           el.classList.remove('isOpenCls');
+```
+
+is just `el.classList.toggle('isOpenCls', vm.isOpen)`. In `assignFrom` that is a `toggle`
+call in `withMethods` with a resolved force argument — and the `!!` marker coerces the
+resolved value to a real boolean so a missing source value *removes* the class instead of
+flipping it:
+
+```TypeScript
+assignFrom(el, {
+    '?.classList?.toggle': ['isOpenCls', '!!?.isOpen']
+}, { from: vm, withMethods: ['toggle'] });
+```
+
+For several classes at once, the `=*` operator runs the method once per argument-list:
+
+```TypeScript
+const vm = { isOpen: true, isLoading: false, hasError: true };
+
+assignFrom(el, {
+    '?.classList?.toggle =*': [
+        ['isOpenCls',  '!!?.isOpen'],
+        ['loadingCls', '!!?.isLoading'],
+        ['errorCls',   '!!?.hasError'],
+    ]
+}, { from: vm, withMethods: ['toggle'] });
+
+// toggle('isOpenCls', true); toggle('loadingCls', false); toggle('errorCls', true)
+```
+
+See [docs/multi-invoke.md](docs/multi-invoke.md) for the full `=*` semantics, including its
+interaction with `where_x_in`.
+
 ## Example 6 - Deleting properties with -= command
 
 The `-=` command allows us to delete properties from objects:

package/assignFrom.js

@@ -57,6 +57,21 @@ export function parseSyncOpCommand(key) {
         return null;
     return key.substring(0, key.length - 3); // Remove ' =&' suffix
 }
+/**
+ * Check if a key ends with the multi-invoke operator ' =*'.
+ */
+export function isMultiInvokeCommand(key) {
+    return key.endsWith(' =*');
+}
+/**
+ * Parse a =* multi-invoke command and extract the base LHS path — the path a
+ * `withMethods` method sits at, to be called once per argument-list on the RHS.
+ */
+export function parseMultiInvokeCommand(key) {
+    if (!isMultiInvokeCommand(key))
+        return null;
+    return key.substring(0, key.length - 3); // Remove ' =*' suffix
+}
 /**
  * Throws if a resolved sync-op value (or anything nested inside it) is a thenable.
  *
@@ -338,12 +353,19 @@ export function expandSubstitutions(pattern, options) {
     return mergeHandlerDuplicates(entries);
 }
 /**
- * Convert entries to an object, merging duplicate handler (` =>`) keys into arrays.
+ * Convert entries to an object. Duplicate keys — which `where_x_in` expansion can
+ * produce — are collapsed with last-wins, except:
+ *  - ` =>` handler keys merge into the Multiple Handlers array form.
+ *  - ` =*` multi-invoke keys concatenate their argument-list arrays, so an
+ *    expanded pattern still invokes the method once per expansion.
  */
 export function mergeHandlerDuplicates(entries) {
     const result = {};
     for (const [key, value] of entries) {
-        if (key.endsWith(' =>') && key in result) {
+        if (key in result && key.endsWith(' =*') && Array.isArray(result[key]) && Array.isArray(value)) {
+            result[key] = result[key].concat(value);
+        }
+        else if (key.endsWith(' =>') && key in result) {
             const existing = result[key];
             if (Array.isArray(existing)) {
                 existing.push(value);
@@ -389,6 +411,7 @@ export function categorizeKeys(expandedPattern) {
     const idRefHandlerKeys = [];
     const ternaryKeys = [];
     const syncOpKeys = [];
+    const multiInvokeKeys = [];
     for (const key of Object.keys(expandedPattern)) {
         if (isHandlerCommand(key)) {
             if (key.startsWith('#[')) {
@@ -404,6 +427,9 @@ export function categorizeKeys(expandedPattern) {
         else if (isSyncOpCommand(key)) {
             syncOpKeys.push(key);
         }
+        else if (isMultiInvokeCommand(key)) {
+            multiInvokeKeys.push(key);
+        }
         else if (key.startsWith('#[')) {
             idRefNormalKeys.push(key);
         }
@@ -411,7 +437,7 @@ export function categorizeKeys(expandedPattern) {
             normalPattern[key] = expandedPattern[key];
         }
     }
-    return { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys, syncOpKeys };
+    return { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys, syncOpKeys, multiInvokeKeys };
 }
 /**
  * Merge pin and at into a single lookup map for resolveIdVariable.
@@ -469,7 +495,7 @@ export function assignFrom(target, pattern, options, permissionProcessor) {
     // Expand looped substitution variables
     const expandedPattern = expandSubstitutions(pattern, options);
     // Categorize keys
-    const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys, syncOpKeys } = categorizeKeys(expandedPattern);
+    const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys, syncOpKeys, multiInvokeKeys } = categorizeKeys(expandedPattern);
     const resolveOptions = { ...options, root: target, permissionProcessor };
     // Process ?= ternary keys (sync)
     if (ternaryKeys.length > 0) {
@@ -517,6 +543,26 @@ export function assignFrom(target, pattern, options, permissionProcessor) {
             }
         }
     }
+    // Process =* multi-invoke keys (sync): call a withMethods method sitting at the
+    // base path once per argument-list on the RHS. Each argument-list is resolved
+    // against `from` (so `?.` paths and `!!` markers work), then delegated to
+    // assignGingerly as a single array-valued key — which spreads it as call args.
+    if (multiInvokeKeys.length > 0) {
+        for (const key of multiInvokeKeys) {
+            const basePath = parseMultiInvokeCommand(key);
+            if (basePath === null)
+                continue;
+            const callList = expandedPattern[key];
+            if (!Array.isArray(callList)) {
+                throw new Error(`assignFrom: multi-invoke command "${key}" requires an array of argument-lists`);
+            }
+            for (const rawArgs of callList) {
+                const argList = Array.isArray(rawArgs) ? rawArgs : [rawArgs];
+                const resolved = getValues({ __args: argList }, options.from, resolveOptions).__args;
+                assignGingerly(target, { [basePath]: resolved }, options, permissionProcessor);
+            }
+        }
+    }
     // Process normal keys via getValues (sync) + assignGingerly
     if (Object.keys(normalPattern).length > 0) {
         // Resolve #[x] references on RHS values before getValues

package/assignFrom.ts

@@ -67,6 +67,22 @@ export function parseSyncOpCommand(key: string): string | null {
     return key.substring(0, key.length - 3); // Remove ' =&' suffix
 }
 
+/**
+ * Check if a key ends with the multi-invoke operator ' =*'.
+ */
+export function isMultiInvokeCommand(key: string): boolean {
+    return key.endsWith(' =*');
+}
+
+/**
+ * Parse a =* multi-invoke command and extract the base LHS path — the path a
+ * `withMethods` method sits at, to be called once per argument-list on the RHS.
+ */
+export function parseMultiInvokeCommand(key: string): string | null {
+    if (!isMultiInvokeCommand(key)) return null;
+    return key.substring(0, key.length - 3); // Remove ' =*' suffix
+}
+
 /**
  * Throws if a resolved sync-op value (or anything nested inside it) is a thenable.
  *
@@ -349,12 +365,18 @@ export function expandSubstitutions(
 }
 
 /**
- * Convert entries to an object, merging duplicate handler (` =>`) keys into arrays.
+ * Convert entries to an object. Duplicate keys — which `where_x_in` expansion can
+ * produce — are collapsed with last-wins, except:
+ *  - ` =>` handler keys merge into the Multiple Handlers array form.
+ *  - ` =*` multi-invoke keys concatenate their argument-list arrays, so an
+ *    expanded pattern still invokes the method once per expansion.
  */
 export function mergeHandlerDuplicates(entries: [string, any][]): Record<string, any> {
   const result: Record<string, any> = {};
   for (const [key, value] of entries) {
-    if (key.endsWith(' =>') && key in result) {
+    if (key in result && key.endsWith(' =*') && Array.isArray(result[key]) && Array.isArray(value)) {
+      result[key] = (result[key] as any[]).concat(value);
+    } else if (key.endsWith(' =>') && key in result) {
       const existing = result[key];
       if (Array.isArray(existing)) {
         existing.push(value);
@@ -400,6 +422,7 @@ export function categorizeKeys(expandedPattern: Record<string, any>) {
   const idRefHandlerKeys: string[] = [];
   const ternaryKeys: string[] = [];
   const syncOpKeys: string[] = [];
+  const multiInvokeKeys: string[] = [];
 
   for (const key of Object.keys(expandedPattern)) {
     if (isHandlerCommand(key)) {
@@ -412,6 +435,8 @@ export function categorizeKeys(expandedPattern: Record<string, any>) {
       ternaryKeys.push(key);
     } else if (isSyncOpCommand(key)) {
       syncOpKeys.push(key);
+    } else if (isMultiInvokeCommand(key)) {
+      multiInvokeKeys.push(key);
     } else if (key.startsWith('#[')) {
       idRefNormalKeys.push(key);
     } else {
@@ -419,7 +444,7 @@ export function categorizeKeys(expandedPattern: Record<string, any>) {
     }
   }
 
-  return { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys, syncOpKeys };
+  return { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys, syncOpKeys, multiInvokeKeys };
 }
 
 /**
@@ -495,7 +520,7 @@ export function assignFrom(
   const expandedPattern = expandSubstitutions(pattern, options);
 
   // Categorize keys
-  const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys, syncOpKeys } = categorizeKeys(expandedPattern);
+  const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys, syncOpKeys, multiInvokeKeys } = categorizeKeys(expandedPattern);
 
   const resolveOptions = { ...options, root: target, permissionProcessor } as any;
 
@@ -547,6 +572,26 @@ export function assignFrom(
     }
   }
 
+  // Process =* multi-invoke keys (sync): call a withMethods method sitting at the
+  // base path once per argument-list on the RHS. Each argument-list is resolved
+  // against `from` (so `?.` paths and `!!` markers work), then delegated to
+  // assignGingerly as a single array-valued key — which spreads it as call args.
+  if (multiInvokeKeys.length > 0) {
+    for (const key of multiInvokeKeys) {
+      const basePath = parseMultiInvokeCommand(key);
+      if (basePath === null) continue;
+      const callList = expandedPattern[key];
+      if (!Array.isArray(callList)) {
+        throw new Error(`assignFrom: multi-invoke command "${key}" requires an array of argument-lists`);
+      }
+      for (const rawArgs of callList) {
+        const argList = Array.isArray(rawArgs) ? rawArgs : [rawArgs];
+        const resolved = getValues({ __args: argList }, options.from, resolveOptions).__args;
+        assignGingerly(target, { [basePath]: resolved }, options, permissionProcessor);
+      }
+    }
+  }
+
   // Process normal keys via getValues (sync) + assignGingerly
   if (Object.keys(normalPattern).length > 0) {
     // Resolve #[x] references on RHS values before getValues

package/assignFromAsync.js

@@ -21,14 +21,14 @@
  */
 import { resolveValues } from './resolve/resolveValues.js';
 import assignGingerly from './assignGingerly.js';
-import { expandSubstitutions, categorizeKeys, handleSpreads } from './assignFrom.js';
+import { expandSubstitutions, categorizeKeys, handleSpreads, parseMultiInvokeCommand } from './assignFrom.js';
 // Module cache for processHandlerCommands — avoids await on dynamic import after first call
 let _processHandlerCommands;
 export async function assignFromAsync(target, pattern, options, permissionProcessor) {
     // First: expand looped substitution variables (${x}, ${y}, ${z})
     const expandedPattern = expandSubstitutions(pattern, options);
     // Categorize keys
-    const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys } = categorizeKeys(expandedPattern);
+    const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, multiInvokeKeys } = categorizeKeys(expandedPattern);
     // Process normal keys via resolveValues + assignGingerly
     if (Object.keys(normalPattern).length > 0) {
         const resolved = await resolveValues(normalPattern, options.from, {
@@ -44,6 +44,28 @@ export async function assignFromAsync(target, pattern, options, permissionProces
         handleSpreads(resolved);
         assignGingerly(target, resolved, options, permissionProcessor);
     }
+    // Process =* multi-invoke keys: call a withMethods method sitting at the base
+    // path once per argument-list on the RHS (see assignFrom for the sync form).
+    if (multiInvokeKeys && multiInvokeKeys.length > 0) {
+        const { withMethods, aka, akaMethods, substitutions, protocols, from } = options;
+        for (const key of multiInvokeKeys) {
+            const basePath = parseMultiInvokeCommand(key);
+            if (basePath === null)
+                continue;
+            const callList = expandedPattern[key];
+            if (!Array.isArray(callList)) {
+                throw new Error(`assignFrom: multi-invoke command "${key}" requires an array of argument-lists`);
+            }
+            for (const rawArgs of callList) {
+                const argList = Array.isArray(rawArgs) ? rawArgs : [rawArgs];
+                const resolved = await resolveValues({ __args: argList }, from, {
+                    withMethods, aka, akaMethods, substitutions, protocols,
+                    root: target, permissionProcessor
+                });
+                assignGingerly(target, { [basePath]: resolved.__args }, options, permissionProcessor);
+            }
+        }
+    }
     // Process #[x] normal keys — resolve element, then apply remaining path + value
     if (idRefNormalKeys.length > 0 && (options.pin || options.at)) {
         const ids = { ...options.pin, ...options.at };

package/assignFromAsync.ts

@@ -24,7 +24,7 @@ import {IAssignGingerlyOptions} from './types/assign-gingerly/types.js';
 import assignGingerly from './assignGingerly.js';
 import type { PermissionProcessor, AssignFromHandler, AssignFromHandlerConstructor } from './types/assign-gingerly/types.js';
 import {
-  expandSubstitutions, categorizeKeys, handleSpreads, isHandlerCommand
+  expandSubstitutions, categorizeKeys, handleSpreads, isHandlerCommand, parseMultiInvokeCommand
 } from './assignFrom.js';
 
 export interface AssignFromOptions extends IAssignGingerlyOptions {
@@ -61,7 +61,7 @@ export async function assignFromAsync(
   const expandedPattern = expandSubstitutions(pattern, options);
 
   // Categorize keys
-  const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys } = categorizeKeys(expandedPattern);
+  const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, multiInvokeKeys } = categorizeKeys(expandedPattern);
 
   // Process normal keys via resolveValues + assignGingerly
   if (Object.keys(normalPattern).length > 0) {
@@ -81,6 +81,28 @@ export async function assignFromAsync(
     assignGingerly(target, resolved, options, permissionProcessor);
   }
 
+  // Process =* multi-invoke keys: call a withMethods method sitting at the base
+  // path once per argument-list on the RHS (see assignFrom for the sync form).
+  if (multiInvokeKeys && multiInvokeKeys.length > 0) {
+    const { withMethods, aka, akaMethods, substitutions, protocols, from } = options;
+    for (const key of multiInvokeKeys) {
+      const basePath = parseMultiInvokeCommand(key);
+      if (basePath === null) continue;
+      const callList = expandedPattern[key];
+      if (!Array.isArray(callList)) {
+        throw new Error(`assignFrom: multi-invoke command "${key}" requires an array of argument-lists`);
+      }
+      for (const rawArgs of callList) {
+        const argList = Array.isArray(rawArgs) ? rawArgs : [rawArgs];
+        const resolved = await resolveValues({ __args: argList }, from, {
+          withMethods, aka, akaMethods, substitutions, protocols,
+          root: target, permissionProcessor
+        });
+        assignGingerly(target, { [basePath]: resolved.__args }, options, permissionProcessor);
+      }
+    }
+  }
+
   // Process #[x] normal keys — resolve element, then apply remaining path + value
   if (idRefNormalKeys.length > 0 && (options.pin || options.at)) {
     const ids = { ...options.pin, ...options.at };

package/package.json

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

package/resolve/getValues.js

@@ -188,6 +188,80 @@ function navigatePath(source, parts, withMethods, permissionProcessor) {
 function hasProtocol(value) {
     return value.includes('://');
 }
+/**
+ * Detect a leading run of `!` characters used as a boolean coercion / negation
+ * marker (`!` = negate, `!!` = coerce to boolean, `!!!` = negate, …). Returns the
+ * count and the remaining string, or null when the value does not start with `!`.
+ *
+ * The marker is only *honored* when the remainder is itself a resolvable
+ * reference (see `looksLikeReference`); otherwise the original string is a plain
+ * literal — e.g. a CSS `!important` passes through untouched.
+ */
+function parseNegationMarker(value) {
+    let count = 0;
+    while (count < value.length && value.charCodeAt(count) === 33 /* '!' */)
+        count++;
+    if (count === 0)
+        return null;
+    return { count, rest: value.slice(count) };
+}
+/**
+ * Whether a string should be resolved as a value reference rather than kept as a
+ * literal: a `?.` path, a `$0` root reference, or a recognized protocol.
+ */
+function looksLikeReference(value, protocols) {
+    return value.startsWith('?.')
+        || value.startsWith('$0')
+        || (!!protocols && hasProtocol(value));
+}
+/**
+ * Resolve a single reference string (`?.` path, `$0` root ref, or protocol) to
+ * its value. Callers must confirm `looksLikeReference(value)` first.
+ */
+function resolveReferenceString(value, source, aliasMap, withMethods, protocols, options, substitutionMap) {
+    const permissionProcessor = options?.permissionProcessor;
+    if (value.startsWith('?.')) {
+        const substituted = applySubstitutions(value, substitutionMap);
+        const aliased = applyAliases(substituted, aliasMap);
+        const parts = parseCachedPath(aliased);
+        return parts.length === 0 ? source : navigatePath(source, parts, withMethods, permissionProcessor);
+    }
+    if (value.startsWith('$0')) {
+        const rootRef = resolveRootReference(value, source, options?.root);
+        if (rootRef === null)
+            return source;
+        const substitutedPath = applySubstitutions(rootRef.path, substitutionMap);
+        const aliased = applyAliases(substitutedPath, aliasMap);
+        const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
+        const parts = parseCachedPath(normalizedPath);
+        return parts.length === 0 ? rootRef.source : navigatePath(rootRef.source, parts, withMethods, permissionProcessor);
+    }
+    // protocol — looksLikeReference already ensured protocols is defined
+    return getProtocolValue(value, protocols, options);
+}
+/**
+ * Resolve a string RHS value: a reference (`?.` / `$0` / protocol), a
+ * `!`-prefixed coercion/negation of a reference, or a plain literal.
+ */
+function resolveStringValue(value, source, aliasMap, withMethods, protocols, options, substitutionMap) {
+    // A leading `!` run can only be a coercion/negation marker or a literal —
+    // no `?.` path, `$0` ref, or protocol name starts with `!`. Check it first so
+    // `hasProtocol` inside `looksLikeReference` can't misread `!!proto://x`.
+    if (value.charCodeAt(0) === 33 /* '!' */) {
+        const neg = parseNegationMarker(value);
+        if (neg !== null && looksLikeReference(neg.rest, protocols)) {
+            let resolved = resolveReferenceString(neg.rest, source, aliasMap, withMethods, protocols, options, substitutionMap);
+            for (let i = 0; i < neg.count; i++)
+                resolved = !resolved;
+            return resolved;
+        }
+        return value;
+    }
+    if (looksLikeReference(value, protocols)) {
+        return resolveReferenceString(value, source, aliasMap, withMethods, protocols, options, substitutionMap);
+    }
+    return value;
+}
 /**
  * Resolve a protocol-prefixed value synchronously.
  */
@@ -212,30 +286,10 @@ function getProtocolValue(value, protocols, options) {
  * Recurses into nested arrays and plain objects.
  */
 function getArray(arr, source, aliasMap, withMethods, protocols, options, substitutionMap) {
-    const permissionProcessor = options?.permissionProcessor;
     const result = [];
     for (const item of arr) {
-        if (typeof item === 'string' && item.startsWith('?.')) {
-            const substituted = applySubstitutions(item, substitutionMap);
-            const aliased = applyAliases(substituted, aliasMap);
-            const parts = parseCachedPath(aliased);
-            result.push(parts.length === 0 ? source : navigatePath(source, parts, withMethods, permissionProcessor));
-        }
-        else if (typeof item === 'string' && item.startsWith('$0')) {
-            const rootRef = resolveRootReference(item, source, options?.root);
-            if (rootRef === null) {
-                result.push(source);
-            }
-            else {
-                const substitutedPath = applySubstitutions(rootRef.path, substitutionMap);
-                const aliased = applyAliases(substitutedPath, aliasMap);
-                const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
-                const parts = parseCachedPath(normalizedPath);
-                result.push(parts.length === 0 ? rootRef.source : navigatePath(rootRef.source, parts, withMethods, permissionProcessor));
-            }
-        }
-        else if (typeof item === 'string' && protocols && hasProtocol(item)) {
-            result.push(getProtocolValue(item, protocols, options));
+        if (typeof item === 'string') {
+            result.push(resolveStringValue(item, source, aliasMap, withMethods, protocols, options, substitutionMap));
         }
         else if (Array.isArray(item)) {
             result.push(getArray(item, source, aliasMap, withMethods, protocols, options, substitutionMap));
@@ -271,30 +325,10 @@ export function getValues(pattern, source, options) {
     const { aliasMap, withMethods } = normalizeAliasOptions(options);
     const substitutionMap = resolveSubstitutions(options?.substitutions, source, options);
     const protocols = options?.protocols;
-    const permissionProcessor = options?.permissionProcessor;
     const result = {};
     for (const [key, value] of Object.entries(pattern)) {
-        if (typeof value === 'string' && value.startsWith('?.')) {
-            const substituted = applySubstitutions(value, substitutionMap);
-            const aliased = applyAliases(substituted, aliasMap);
-            const parts = parseCachedPath(aliased);
-            result[key] = parts.length === 0 ? source : navigatePath(source, parts, withMethods, permissionProcessor);
-        }
-        else if (typeof value === 'string' && value.startsWith('$0')) {
-            const rootRef = resolveRootReference(value, source, options?.root);
-            if (rootRef === null) {
-                result[key] = source;
-            }
-            else {
-                const substitutedPath = applySubstitutions(rootRef.path, substitutionMap);
-                const aliased = applyAliases(substitutedPath, aliasMap);
-                const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
-                const parts = parseCachedPath(normalizedPath);
-                result[key] = parts.length === 0 ? rootRef.source : navigatePath(rootRef.source, parts, withMethods, permissionProcessor);
-            }
-        }
-        else if (typeof value === 'string' && protocols && hasProtocol(value)) {
-            result[key] = getProtocolValue(value, protocols, options);
+        if (typeof value === 'string') {
+            result[key] = resolveStringValue(value, source, aliasMap, withMethods, protocols, options, substitutionMap);
         }
         else if (Array.isArray(value)) {
             result[key] = getArray(value, source, aliasMap, withMethods, protocols, options, substitutionMap);
@@ -323,6 +357,15 @@ export function getValues(pattern, source, options) {
  * @returns The resolved value, or undefined if any segment is nullish
  */
 export function getValue(path, source, options) {
+    // Leading `!` run: coerce/negate the resolved reference (`!` negate, `!!` boolean, …).
+    // Only honored in front of a `?.` path or `$0` root reference — otherwise literal.
+    const neg = parseNegationMarker(path);
+    if (neg !== null && (neg.rest.startsWith('?.') || neg.rest.startsWith('$0'))) {
+        let resolved = getValue(neg.rest, source, options);
+        for (let i = 0; i < neg.count; i++)
+            resolved = !resolved;
+        return resolved;
+    }
     const rootRef = resolveRootReference(path, source, options?.root);
     if (rootRef) {
         path = rootRef.path;

package/resolve/getValues.ts

@@ -227,6 +227,99 @@ function hasProtocol(value: string): boolean {
     return value.includes('://');
 }
 
+/**
+ * Detect a leading run of `!` characters used as a boolean coercion / negation
+ * marker (`!` = negate, `!!` = coerce to boolean, `!!!` = negate, …). Returns the
+ * count and the remaining string, or null when the value does not start with `!`.
+ *
+ * The marker is only *honored* when the remainder is itself a resolvable
+ * reference (see `looksLikeReference`); otherwise the original string is a plain
+ * literal — e.g. a CSS `!important` passes through untouched.
+ */
+function parseNegationMarker(value: string): { count: number; rest: string } | null {
+    let count = 0;
+    while (count < value.length && value.charCodeAt(count) === 33 /* '!' */) count++;
+    if (count === 0) return null;
+    return { count, rest: value.slice(count) };
+}
+
+/**
+ * Whether a string should be resolved as a value reference rather than kept as a
+ * literal: a `?.` path, a `$0` root reference, or a recognized protocol.
+ */
+function looksLikeReference(
+    value: string,
+    protocols: Record<string, (key: string) => any> | undefined
+): boolean {
+    return value.startsWith('?.')
+        || value.startsWith('$0')
+        || (!!protocols && hasProtocol(value));
+}
+
+/**
+ * Resolve a single reference string (`?.` path, `$0` root ref, or protocol) to
+ * its value. Callers must confirm `looksLikeReference(value)` first.
+ */
+function resolveReferenceString(
+    value: string,
+    source: any,
+    aliasMap: Map<string, string>,
+    withMethods: Set<string> | undefined,
+    protocols: Record<string, (key: string) => any> | undefined,
+    options: GetValuesOptions | undefined,
+    substitutionMap: Map<string, string> | undefined
+): any {
+    const permissionProcessor = options?.permissionProcessor;
+    if (value.startsWith('?.')) {
+        const substituted = applySubstitutions(value, substitutionMap);
+        const aliased = applyAliases(substituted, aliasMap);
+        const parts = parseCachedPath(aliased);
+        return parts.length === 0 ? source : navigatePath(source, parts, withMethods, permissionProcessor);
+    }
+    if (value.startsWith('$0')) {
+        const rootRef = resolveRootReference(value, source, options?.root);
+        if (rootRef === null) return source;
+        const substitutedPath = applySubstitutions(rootRef.path, substitutionMap);
+        const aliased = applyAliases(substitutedPath, aliasMap);
+        const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
+        const parts = parseCachedPath(normalizedPath);
+        return parts.length === 0 ? rootRef.source : navigatePath(rootRef.source, parts, withMethods, permissionProcessor);
+    }
+    // protocol — looksLikeReference already ensured protocols is defined
+    return getProtocolValue(value, protocols!, options);
+}
+
+/**
+ * Resolve a string RHS value: a reference (`?.` / `$0` / protocol), a
+ * `!`-prefixed coercion/negation of a reference, or a plain literal.
+ */
+function resolveStringValue(
+    value: string,
+    source: any,
+    aliasMap: Map<string, string>,
+    withMethods: Set<string> | undefined,
+    protocols: Record<string, (key: string) => any> | undefined,
+    options: GetValuesOptions | undefined,
+    substitutionMap: Map<string, string> | undefined
+): any {
+    // A leading `!` run can only be a coercion/negation marker or a literal —
+    // no `?.` path, `$0` ref, or protocol name starts with `!`. Check it first so
+    // `hasProtocol` inside `looksLikeReference` can't misread `!!proto://x`.
+    if (value.charCodeAt(0) === 33 /* '!' */) {
+        const neg = parseNegationMarker(value);
+        if (neg !== null && looksLikeReference(neg.rest, protocols)) {
+            let resolved = resolveReferenceString(neg.rest, source, aliasMap, withMethods, protocols, options, substitutionMap);
+            for (let i = 0; i < neg.count; i++) resolved = !resolved;
+            return resolved;
+        }
+        return value;
+    }
+    if (looksLikeReference(value, protocols)) {
+        return resolveReferenceString(value, source, aliasMap, withMethods, protocols, options, substitutionMap);
+    }
+    return value;
+}
+
 /**
  * Resolve a protocol-prefixed value synchronously.
  */
@@ -268,27 +361,10 @@ function getArray(
     options?: GetValuesOptions,
     substitutionMap?: Map<string, string>
 ): any[] {
-    const permissionProcessor = options?.permissionProcessor;
     const result: any[] = [];
     for (const item of arr) {
-        if (typeof item === 'string' && item.startsWith('?.')) {
-            const substituted = applySubstitutions(item, substitutionMap);
-            const aliased = applyAliases(substituted, aliasMap);
-            const parts = parseCachedPath(aliased);
-            result.push(parts.length === 0 ? source : navigatePath(source, parts, withMethods, permissionProcessor));
-        } else if (typeof item === 'string' && item.startsWith('$0')) {
-            const rootRef = resolveRootReference(item, source, options?.root);
-            if (rootRef === null) {
-                result.push(source);
-            } else {
-                const substitutedPath = applySubstitutions(rootRef.path, substitutionMap);
-                const aliased = applyAliases(substitutedPath, aliasMap);
-                const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
-                const parts = parseCachedPath(normalizedPath);
-                result.push(parts.length === 0 ? rootRef.source : navigatePath(rootRef.source, parts, withMethods, permissionProcessor));
-            }
-        } else if (typeof item === 'string' && protocols && hasProtocol(item)) {
-            result.push(getProtocolValue(item, protocols, options));
+        if (typeof item === 'string') {
+            result.push(resolveStringValue(item, source, aliasMap, withMethods, protocols, options, substitutionMap));
         } else if (Array.isArray(item)) {
             result.push(getArray(item, source, aliasMap, withMethods, protocols, options, substitutionMap));
         } else if (item && typeof item === 'object') {
@@ -326,28 +402,11 @@ export function getValues(
     const substitutionMap = resolveSubstitutions(options?.substitutions, source, options);
 
     const protocols = options?.protocols;
-    const permissionProcessor = options?.permissionProcessor;
 
     const result: Record<string, any> = {};
     for (const [key, value] of Object.entries(pattern)) {
-        if (typeof value === 'string' && value.startsWith('?.')) {
-            const substituted = applySubstitutions(value, substitutionMap);
-            const aliased = applyAliases(substituted, aliasMap);
-            const parts = parseCachedPath(aliased);
-            result[key] = parts.length === 0 ? source : navigatePath(source, parts, withMethods, permissionProcessor);
-        } else if (typeof value === 'string' && value.startsWith('$0')) {
-            const rootRef = resolveRootReference(value, source, options?.root);
-            if (rootRef === null) {
-                result[key] = source;
-            } else {
-                const substitutedPath = applySubstitutions(rootRef.path, substitutionMap);
-                const aliased = applyAliases(substitutedPath, aliasMap);
-                const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
-                const parts = parseCachedPath(normalizedPath);
-                result[key] = parts.length === 0 ? rootRef.source : navigatePath(rootRef.source, parts, withMethods, permissionProcessor);
-            }
-        } else if (typeof value === 'string' && protocols && hasProtocol(value)) {
-            result[key] = getProtocolValue(value, protocols, options);
+        if (typeof value === 'string') {
+            result[key] = resolveStringValue(value, source, aliasMap, withMethods, protocols, options, substitutionMap);
         } else if (Array.isArray(value)) {
             result[key] = getArray(value, source, aliasMap, withMethods, protocols, options, substitutionMap);
         } else if (typeof value === 'object' && value !== null) {
@@ -377,6 +436,15 @@ export function getValue(
     source: any,
     options?: GetValuesOptions
 ): any {
+    // Leading `!` run: coerce/negate the resolved reference (`!` negate, `!!` boolean, …).
+    // Only honored in front of a `?.` path or `$0` root reference — otherwise literal.
+    const neg = parseNegationMarker(path);
+    if (neg !== null && (neg.rest.startsWith('?.') || neg.rest.startsWith('$0'))) {
+        let resolved = getValue(neg.rest, source, options);
+        for (let i = 0; i < neg.count; i++) resolved = !resolved;
+        return resolved;
+    }
+
     const rootRef = resolveRootReference(path, source, options?.root);
     if (rootRef) {
         path = rootRef.path;