assign-gingerly 0.0.95 → 0.0.96

package/README.md

@@ -82,7 +82,7 @@ The third fundamental utility function is:
 **`assignFrom` is synchronous** — it resolves paths, expands substitutions, handles spreads, processes `#[x]` refs, and runs inferred assignments all without yielding to the event loop. Handler commands (` =>`), `beVigilant`, and `enhance` are fire-and-forget (kicked off asynchronously in the background).
 
 **`assignFromAsync`** is the awaitable variant for when you need to:
-- Use async protocol handlers (e.g., `fetch`-based resolution)
+- Use async protocol handlers (e.g., `fetch`-based resolution — protocols are introduced just below, and covered in full in [Protocol Resolution](#protocol-resolution-in-getvalues-and-assignfrom) later in this doc)
 - `await` handler completion before proceeding
 - Wait for `enhance` (EMC JSON imports) to finish
 
@@ -97,7 +97,7 @@ assignFrom adds support for:
 
 1.  Resolving RHS path strings against a source object (`from`).
 2.  Target-relative root references via `$0` so paths can resolve from the first argument passed to `assignFrom`/`assignFromAsync` (the target object) instead of the `from` object.
-3.  Protocol resolution (`globalThis://`, `localStorage://`, custom sync protocols).
+3.  Protocol resolution (`globalThis://`, `localStorage://`, custom sync protocols) — don't worry if this is unfamiliar yet, it's explained in full in [Protocol Resolution in `getValues` and `assignFrom`](#protocol-resolution-in-getvalues-and-assignfrom) later in this doc.
 4.  Handler plugins via the ` =>` operator for custom logic (fire-and-forget in sync mode, awaitable in async mode).
 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).

package/index.js

@@ -8,6 +8,7 @@ export { buildCSSQuery } from './buildCSSQuery.js';
 export { resolveTemplate } from './resolve/resolveTemplate.js';
 export { getHost } from './getHost.js';
 export { resolveValues, resolveValue } from './resolve/resolveValues.js';
+export { getValues, getValue, hasProtocol, parseProtocolRef, isPlainObject } from './resolve/getValues.js';
 export { assignFromAsync } from './assignFromAsync.js';
 export { assignFrom } from './assignFrom.js';
 export { assignFeatures, FeaturesRegistry, captureFeatureInitVals, PropertyBag, suggestFeatureInfo, getFeatureInfoSuggestions } from './assignFeatures.js';

package/index.ts

@@ -8,6 +8,7 @@ export {buildCSSQuery} from './buildCSSQuery.js';
 export {resolveTemplate} from './resolve/resolveTemplate.js';
 export {getHost} from './getHost.js';
 export {resolveValues, resolveValue} from './resolve/resolveValues.js';
+export {getValues, getValue, hasProtocol, parseProtocolRef, isPlainObject} from './resolve/getValues.js';
 export {assignFromAsync} from './assignFromAsync.js';
 export {assignFrom} from './assignFrom.js';
 export {assignFeatures, FeaturesRegistry, captureFeatureInitVals, PropertyBag, suggestFeatureInfo, getFeatureInfoSuggestions} from './assignFeatures.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.95",
+  "version": "0.0.96",
   "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

@@ -183,11 +183,47 @@ function navigatePath(source, parts, withMethods, permissionProcessor) {
     return current;
 }
 /**
- * Checks if a string value looks like a protocol reference.
+ * Whether a string carries a protocol prefix (contains `://`).
+ *
+ * Exported as the single source of truth for the outer USL grammar, so
+ * downstream packages (and resolveValues) don't re-implement the check.
  */
-function hasProtocol(value) {
+export function hasProtocol(value) {
     return value.includes('://');
 }
+/**
+ * Split a protocol-prefixed value string into its outer-grammar parts:
+ * `‹protocol›://‹key›?.‹path›`.
+ *
+ * - `protocol` is the text before `://` (`''` when there is no `://`).
+ * - `key` is the text between `://` and the first `?.` (or end of string).
+ * - `path` is the `?.`-onward remainder (starting with `?.`), or `null`.
+ *
+ * Pure string parsing — no handler lookup, no resolution. Shared by the sync
+ * (`getProtocolValue`) and async (`resolveProtocolValue`) resolvers.
+ */
+export function parseProtocolRef(value) {
+    const protoEnd = value.indexOf('://');
+    if (protoEnd === -1)
+        return { protocol: '', key: value, path: null };
+    const protocol = value.substring(0, protoEnd);
+    const rest = value.substring(protoEnd + 3);
+    const pathStart = rest.indexOf('?.');
+    const key = pathStart === -1 ? rest : rest.substring(0, pathStart);
+    const path = pathStart === -1 ? null : rest.substring(pathStart);
+    return { protocol, key, path };
+}
+/**
+ * Whether a value is a plain object (prototype is `Object.prototype` or `null`),
+ * as opposed to an array, a class instance, or a primitive. Used to decide
+ * whether a nested value should be recursed into as a pattern.
+ */
+export function isPlainObject(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
 /**
  * Detect a leading run of `!` characters used as a boolean coercion / negation
  * marker (`!` = negate, `!!` = coerce to boolean, `!!!` = negate, …). Returns the
@@ -266,15 +302,10 @@ function resolveStringValue(value, source, aliasMap, withMethods, protocols, opt
  * Resolve a protocol-prefixed value synchronously.
  */
 function getProtocolValue(value, protocols, options) {
-    const protoEnd = value.indexOf('://');
-    const protocol = value.substring(0, protoEnd);
+    const { protocol, key, path } = parseProtocolRef(value);
     const handler = protocols[protocol];
     if (!handler)
         return value; // not a recognized protocol
-    const rest = value.substring(protoEnd + 3);
-    const pathStart = rest.indexOf('?.');
-    const key = pathStart === -1 ? rest : rest.substring(0, pathStart);
-    const path = pathStart === -1 ? null : rest.substring(pathStart);
     const resolved = handler(key);
     if (path) {
         return getValue(path, resolved, options);
@@ -295,13 +326,7 @@ function getArray(arr, source, aliasMap, withMethods, protocols, options, substi
             result.push(getArray(item, source, aliasMap, withMethods, protocols, options, substitutionMap));
         }
         else if (item && typeof item === 'object') {
-            const proto = Object.getPrototypeOf(item);
-            if (proto === Object.prototype || proto === null) {
-                result.push(getValues(item, source, options));
-            }
-            else {
-                result.push(item);
-            }
+            result.push(isPlainObject(item) ? getValues(item, source, options) : item);
         }
         else {
             result.push(item);
@@ -334,13 +359,7 @@ export function getValues(pattern, source, options) {
             result[key] = getArray(value, source, aliasMap, withMethods, protocols, options, substitutionMap);
         }
         else if (typeof value === 'object' && value !== null) {
-            const proto = Object.getPrototypeOf(value);
-            if (proto === Object.prototype || proto === null) {
-                result[key] = getValues(value, source, options);
-            }
-            else {
-                result[key] = value;
-            }
+            result[key] = isPlainObject(value) ? getValues(value, source, options) : value;
         }
         else {
             result[key] = value;

package/resolve/getValues.ts

@@ -17,7 +17,7 @@
  * }, source, { withMethods: ['querySelector'], aka: { q: 'querySelector' } });
  */
 
-import type { GetValuesOptions, PermissionProcessor } from '../types/assign-gingerly/types.js';
+import type { GetValuesOptions, ParsedProtocolRef, PermissionProcessor, SyncProtocolHandlers } from '../types/assign-gingerly/types.js';
 
 export function normalizeAliasOptions(options?: {
     aka?: Record<string, string>;
@@ -221,12 +221,48 @@ function navigatePath(
 }
 
 /**
- * Checks if a string value looks like a protocol reference.
+ * Whether a string carries a protocol prefix (contains `://`).
+ *
+ * Exported as the single source of truth for the outer USL grammar, so
+ * downstream packages (and resolveValues) don't re-implement the check.
  */
-function hasProtocol(value: string): boolean {
+export function hasProtocol(value: string): boolean {
     return value.includes('://');
 }
 
+/**
+ * Split a protocol-prefixed value string into its outer-grammar parts:
+ * `‹protocol›://‹key›?.‹path›`.
+ *
+ * - `protocol` is the text before `://` (`''` when there is no `://`).
+ * - `key` is the text between `://` and the first `?.` (or end of string).
+ * - `path` is the `?.`-onward remainder (starting with `?.`), or `null`.
+ *
+ * Pure string parsing — no handler lookup, no resolution. Shared by the sync
+ * (`getProtocolValue`) and async (`resolveProtocolValue`) resolvers.
+ */
+export function parseProtocolRef(value: string): ParsedProtocolRef {
+    const protoEnd = value.indexOf('://');
+    if (protoEnd === -1) return { protocol: '', key: value, path: null };
+    const protocol = value.substring(0, protoEnd);
+    const rest = value.substring(protoEnd + 3);
+    const pathStart = rest.indexOf('?.');
+    const key = pathStart === -1 ? rest : rest.substring(0, pathStart);
+    const path = pathStart === -1 ? null : rest.substring(pathStart);
+    return { protocol, key, path };
+}
+
+/**
+ * Whether a value is a plain object (prototype is `Object.prototype` or `null`),
+ * as opposed to an array, a class instance, or a primitive. Used to decide
+ * whether a nested value should be recursed into as a pattern.
+ */
+export function isPlainObject(value: any): boolean {
+    if (!value || typeof value !== 'object') return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+
 /**
  * Detect a leading run of `!` characters used as a boolean coercion / negation
  * marker (`!` = negate, `!!` = coerce to boolean, `!!!` = negate, …). Returns the
@@ -249,7 +285,7 @@ function parseNegationMarker(value: string): { count: number; rest: string } | n
  */
 function looksLikeReference(
     value: string,
-    protocols: Record<string, (key: string) => any> | undefined
+    protocols: SyncProtocolHandlers | undefined
 ): boolean {
     return value.startsWith('?.')
         || value.startsWith('$0')
@@ -265,7 +301,7 @@ function resolveReferenceString(
     source: any,
     aliasMap: Map<string, string>,
     withMethods: Set<string> | undefined,
-    protocols: Record<string, (key: string) => any> | undefined,
+    protocols: SyncProtocolHandlers | undefined,
     options: GetValuesOptions | undefined,
     substitutionMap: Map<string, string> | undefined
 ): any {
@@ -298,7 +334,7 @@ function resolveStringValue(
     source: any,
     aliasMap: Map<string, string>,
     withMethods: Set<string> | undefined,
-    protocols: Record<string, (key: string) => any> | undefined,
+    protocols: SyncProtocolHandlers | undefined,
     options: GetValuesOptions | undefined,
     substitutionMap: Map<string, string> | undefined
 ): any {
@@ -325,21 +361,14 @@ function resolveStringValue(
  */
 function getProtocolValue(
     value: string,
-    protocols: Record<string, (key: string) => any>,
+    protocols: SyncProtocolHandlers,
     options?: GetValuesOptions
 ): any {
-    const protoEnd = value.indexOf('://');
-    const protocol = value.substring(0, protoEnd);
+    const { protocol, key, path } = parseProtocolRef(value);
 
     const handler = protocols[protocol];
     if (!handler) return value; // not a recognized protocol
 
-    const rest = value.substring(protoEnd + 3);
-
-    const pathStart = rest.indexOf('?.');
-    const key = pathStart === -1 ? rest : rest.substring(0, pathStart);
-    const path = pathStart === -1 ? null : rest.substring(pathStart);
-
     const resolved = handler(key);
 
     if (path) {
@@ -357,7 +386,7 @@ function getArray(
     source: any,
     aliasMap: Map<string, string>,
     withMethods: Set<string> | undefined,
-    protocols: Record<string, (key: string) => any> | undefined,
+    protocols: SyncProtocolHandlers | undefined,
     options?: GetValuesOptions,
     substitutionMap?: Map<string, string>
 ): any[] {
@@ -368,12 +397,7 @@ function getArray(
         } else if (Array.isArray(item)) {
             result.push(getArray(item, source, aliasMap, withMethods, protocols, options, substitutionMap));
         } else if (item && typeof item === 'object') {
-            const proto = Object.getPrototypeOf(item);
-            if (proto === Object.prototype || proto === null) {
-                result.push(getValues(item, source, options));
-            } else {
-                result.push(item);
-            }
+            result.push(isPlainObject(item) ? getValues(item, source, options) : item);
         } else {
             result.push(item);
         }
@@ -410,12 +434,7 @@ export function getValues(
         } else if (Array.isArray(value)) {
             result[key] = getArray(value, source, aliasMap, withMethods, protocols, options, substitutionMap);
         } else if (typeof value === 'object' && value !== null) {
-            const proto = Object.getPrototypeOf(value);
-            if (proto === Object.prototype || proto === null) {
-                result[key] = getValues(value, source, options);
-            } else {
-                result[key] = value;
-            }
+            result[key] = isPlainObject(value) ? getValues(value, source, options) : value;
         } else {
             result[key] = value;
         }

package/resolve/resolveValues.js

@@ -4,30 +4,24 @@
  * Thin async wrapper around getValues that adds support for async protocol handlers.
  * For synchronous-only use cases, import getValues/getValue directly for better performance.
  *
+ * The outer-grammar primitives (`hasProtocol`, `parseProtocolRef`, `isPlainObject`)
+ * live in getValues.js and are re-exported here for convenience.
+ *
  * Re-exports ResolveValuesOptions for backward compatibility.
  */
-import { getValue, getValues } from './getValues.js';
+import { getValue, getValues, hasProtocol, isPlainObject, parseProtocolRef } from './getValues.js';
 // Re-export getValue as resolveValue for backward compatibility
 export { getValue as resolveValue };
-/**
- * Checks if a string value looks like a protocol reference.
- */
-function hasProtocol(value) {
-    return value.includes('://');
-}
+// Re-export the shared outer-grammar primitives (defined in getValues.js)
+export { hasProtocol, parseProtocolRef, isPlainObject };
 /**
  * Resolves a protocol-prefixed value asynchronously.
  */
 async function resolveProtocolValue(value, protocols, options) {
-    const protoEnd = value.indexOf('://');
-    const protocol = value.substring(0, protoEnd);
+    const { protocol, key, path } = parseProtocolRef(value);
     const handler = protocols[protocol];
     if (!handler)
         return value;
-    const rest = value.substring(protoEnd + 3);
-    const pathStart = rest.indexOf('?.');
-    const key = pathStart === -1 ? rest : rest.substring(0, pathStart);
-    const path = pathStart === -1 ? null : rest.substring(pathStart);
     const resolved = await handler(key);
     if (path) {
         return getValue(path, resolved, options);
@@ -52,8 +46,7 @@ async function resolveArray(arr, source, protocols, options) {
             result.push(await resolveArray(item, source, protocols, options));
         }
         else if (item && typeof item === 'object') {
-            const proto = Object.getPrototypeOf(item);
-            if (proto === Object.prototype || proto === null) {
+            if (isPlainObject(item)) {
                 result.push(options?.protocols ? await resolveValues(item, source, options) : getValues(item, source, options));
             }
             else {
@@ -93,8 +86,7 @@ export async function resolveValues(pattern, source, options) {
             result[key] = await resolveArray(value, source, protocols, options);
         }
         else if (typeof value === 'object' && value !== null) {
-            const proto = Object.getPrototypeOf(value);
-            if (proto === Object.prototype || proto === null) {
+            if (isPlainObject(value)) {
                 result[key] = options?.protocols ? await resolveValues(value, source, options) : getValues(value, source, options);
             }
             else {

package/resolve/resolveValues.ts

@@ -1,126 +1,116 @@
-/**
- * resolveValues.ts — Async value resolution for path strings.
- * 
- * Thin async wrapper around getValues that adds support for async protocol handlers.
- * For synchronous-only use cases, import getValues/getValue directly for better performance.
- * 
- * Re-exports ResolveValuesOptions for backward compatibility.
- */
-
-import { getValue, getValues } from './getValues.js';
-import type { ResolveValuesOptions } from '../types/assign-gingerly/types.js';
-
-export type { ResolveValuesOptions };
-
-// Re-export getValue as resolveValue for backward compatibility
-export { getValue as resolveValue };
-
-/**
- * Checks if a string value looks like a protocol reference.
- */
-function hasProtocol(value: string): boolean {
-    return value.includes('://');
-}
-
-
-/**
- * Resolves a protocol-prefixed value asynchronously.
- */
-async function resolveProtocolValue(
-    value: string,
-    protocols: Record<string, (key: string) => any | Promise<any>>,
-    options?: ResolveValuesOptions
-): Promise<any> {
-    const protoEnd = value.indexOf('://');
-    const protocol = value.substring(0, protoEnd);
-
-    const handler = protocols[protocol];
-    if (!handler) return value;
-
-    const rest = value.substring(protoEnd + 3);
-    const pathStart = rest.indexOf('?.');
-    const key = pathStart === -1 ? rest : rest.substring(0, pathStart);
-    const path = pathStart === -1 ? null : rest.substring(pathStart);
-
-    const resolved = await handler(key);
-
-    if (path) {
-        return getValue(path, resolved, options);
-    }
-    return resolved;
-}
-
-/**
- * Resolve path strings and protocol references within an array (async).
- */
-async function resolveArray(
-    arr: any[],
-    source: any,
-    protocols: Record<string, (key: string) => any | Promise<any>> | undefined,
-    options?: ResolveValuesOptions
-): Promise<any[]> {
-    const result: any[] = [];
-    for (const item of arr) {
-        if (typeof item === 'string') {
-            if (protocols && hasProtocol(item)) {
-                result.push(await resolveProtocolValue(item, protocols, options));
-            } else {
-                result.push(getValue(item, source, options));
-            }
-        } else if (Array.isArray(item)) {
-            result.push(await resolveArray(item, source, protocols, options));
-        } else if (item && typeof item === 'object') {
-            const proto = Object.getPrototypeOf(item);
-            if (proto === Object.prototype || proto === null) {
-                result.push(options?.protocols ? await resolveValues(item, source, options) : getValues(item, source, options));
-            } else {
-                result.push(item);
-            }
-        } else {
-            result.push(item);
-        }
-    }
-    return result;
-}
-
-/**
- * Async resolve RHS path strings in a pattern object against a source object.
- * 
- * Supports async protocol handlers (e.g., fetch, IndexedDB).
- * For synchronous-only patterns, use `getValues` from 'assign-gingerly/getValues.js' instead.
- * 
- * @param pattern - Object whose RHS values may contain `?.` path strings
- * @param source - Object to resolve paths against
- * @param options - Optional withMethods, aka, and protocol handlers
- * @returns New object with path strings replaced by resolved values
- */
-export async function resolveValues(
-    pattern: Record<string, any>,
-    source: any,
-    options?: ResolveValuesOptions
-): Promise<Record<string, any>> {
-    const protocols = options?.protocols;
-
-    const result: Record<string, any> = {};
-    for (const [key, value] of Object.entries(pattern)) {
-        if (typeof value === 'string') {
-            if (protocols && hasProtocol(value)) {
-                result[key] = await resolveProtocolValue(value, protocols, options);
-            } else {
-                result[key] = getValue(value, source, options);
-            }
-        } else if (Array.isArray(value)) {
-            result[key] = await resolveArray(value, source, protocols, options);
-        } else if (typeof value === 'object' && value !== null) {
-            const proto = Object.getPrototypeOf(value);
-            if (proto === Object.prototype || proto === null) {
-                result[key] = options?.protocols ? await resolveValues(value, source, options) : getValues(value, source, options);
-            } else {
-                result[key] = value;
-            }
-        } else {
-            result[key] = value;
-        }
-    }
-    return result;
-}
+/**
+ * resolveValues.ts — Async value resolution for path strings.
+ *
+ * Thin async wrapper around getValues that adds support for async protocol handlers.
+ * For synchronous-only use cases, import getValues/getValue directly for better performance.
+ *
+ * The outer-grammar primitives (`hasProtocol`, `parseProtocolRef`, `isPlainObject`)
+ * live in getValues.js and are re-exported here for convenience.
+ *
+ * Re-exports ResolveValuesOptions for backward compatibility.
+ */
+
+import { getValue, getValues, hasProtocol, isPlainObject, parseProtocolRef } from './getValues.js';
+import type { ProtocolHandlers, ResolveValuesOptions } from '../types/assign-gingerly/types.js';
+
+export type { ResolveValuesOptions };
+
+// Re-export getValue as resolveValue for backward compatibility
+export { getValue as resolveValue };
+
+// Re-export the shared outer-grammar primitives (defined in getValues.js)
+export { hasProtocol, parseProtocolRef, isPlainObject };
+
+/**
+ * Resolves a protocol-prefixed value asynchronously.
+ */
+async function resolveProtocolValue(
+    value: string,
+    protocols: ProtocolHandlers,
+    options?: ResolveValuesOptions
+): Promise<any> {
+    const { protocol, key, path } = parseProtocolRef(value);
+
+    const handler = protocols[protocol];
+    if (!handler) return value;
+
+    const resolved = await handler(key);
+
+    if (path) {
+        return getValue(path, resolved, options);
+    }
+    return resolved;
+}
+
+/**
+ * Resolve path strings and protocol references within an array (async).
+ */
+async function resolveArray(
+    arr: any[],
+    source: any,
+    protocols: ProtocolHandlers | undefined,
+    options?: ResolveValuesOptions
+): Promise<any[]> {
+    const result: any[] = [];
+    for (const item of arr) {
+        if (typeof item === 'string') {
+            if (protocols && hasProtocol(item)) {
+                result.push(await resolveProtocolValue(item, protocols, options));
+            } else {
+                result.push(getValue(item, source, options));
+            }
+        } else if (Array.isArray(item)) {
+            result.push(await resolveArray(item, source, protocols, options));
+        } else if (item && typeof item === 'object') {
+            if (isPlainObject(item)) {
+                result.push(options?.protocols ? await resolveValues(item, source, options) : getValues(item, source, options));
+            } else {
+                result.push(item);
+            }
+        } else {
+            result.push(item);
+        }
+    }
+    return result;
+}
+
+/**
+ * Async resolve RHS path strings in a pattern object against a source object.
+ *
+ * Supports async protocol handlers (e.g., fetch, IndexedDB).
+ * For synchronous-only patterns, use `getValues` from 'assign-gingerly/getValues.js' instead.
+ *
+ * @param pattern - Object whose RHS values may contain `?.` path strings
+ * @param source - Object to resolve paths against
+ * @param options - Optional withMethods, aka, and protocol handlers
+ * @returns New object with path strings replaced by resolved values
+ */
+export async function resolveValues(
+    pattern: Record<string, any>,
+    source: any,
+    options?: ResolveValuesOptions
+): Promise<Record<string, any>> {
+    const protocols = options?.protocols;
+
+    const result: Record<string, any> = {};
+    for (const [key, value] of Object.entries(pattern)) {
+        if (typeof value === 'string') {
+            if (protocols && hasProtocol(value)) {
+                result[key] = await resolveProtocolValue(value, protocols, options);
+            } else {
+                result[key] = getValue(value, source, options);
+            }
+        } else if (Array.isArray(value)) {
+            result[key] = await resolveArray(value, source, protocols, options);
+        } else if (typeof value === 'object' && value !== null) {
+            if (isPlainObject(value)) {
+                result[key] = options?.protocols ? await resolveValues(value, source, options) : getValues(value, source, options);
+            } else {
+                result[key] = value;
+            }
+        } else {
+            result[key] = value;
+        }
+    }
+    return result;
+}

package/types/assign-gingerly/types.d.ts

@@ -406,7 +406,7 @@ export interface AssignFromOptions {
   from: any;
 
   /** Protocol handlers (sync or async) */
-  protocols?: Record<string, (key: string) => any | Promise<any>>;
+  protocols?: ProtocolHandlers;
 
   /** Method names to call during path evaluation (append `|` to a path segment for a zero-argument call) */
   withMethods?: string[] | Set<string>;
@@ -480,6 +480,37 @@ export interface AssignFromOptions {
   [key: string]: any;
 }
 
+/**
+ * A protocol handler resolves the key portion of a protocol-prefixed value
+ * (the text between `://` and the first `?.`) to a value. May be sync or async.
+ */
+export type ProtocolHandler = (key: string) => any | Promise<any>;
+
+/**
+ * A synchronous-only protocol handler, as accepted by getValues / getValue /
+ * assignFrom. For handlers that may return a Promise, use ProtocolHandler.
+ */
+export type SyncProtocolHandler = (key: string) => any;
+
+/** Map of protocol name (the text before `://`) to a handler (sync or async). */
+export type ProtocolHandlers = Record<string, ProtocolHandler>;
+
+/** Map of protocol name to a synchronous handler. */
+export type SyncProtocolHandlers = Record<string, SyncProtocolHandler>;
+
+/**
+ * The outer grammar of a protocol-prefixed value string,
+ * `‹protocol›://‹key›?.‹path›`, as produced by `parseProtocolRef`.
+ */
+export interface ParsedProtocolRef {
+    /** Text before `://`; `''` when the value contains no `://`. */
+    protocol: string;
+    /** Text between `://` and the first `?.` (or the end of the string). */
+    key: string;
+    /** Text from the first `?.` onward (always starts with `?.`), or `null`. */
+    path: string | null;
+}
+
 /**
  * Options for synchronous value resolution (getValues / getValue).
  * Extends IAssignGingerlyOptions with synchronous protocol handlers.
@@ -507,7 +538,7 @@ export interface GetValuesOptions extends IAssignGingerlyOptions {
    *     localStorage: (key) => JSON.parse(localStorage.getItem(key) || 'null')
    * }
    */
-  protocols?: Record<string, (key: string) => any>;
+  protocols?: SyncProtocolHandlers;
 }
 
 /**
@@ -530,7 +561,7 @@ export interface ResolveValuesOptions extends IAssignGingerlyOptions {
    * Protocol handlers for resolving protocol-prefixed values (e.g., 'globalThis://key').
    * Each handler receives the key portion and returns the resolved value (sync or async).
    */
-  protocols?: Record<string, (key: string) => any | Promise<any>>;
+  protocols?: ProtocolHandlers;
 }
 
 /**