@voxgig/sdkgen 4.30.0 → 4.30.1

package/project/.sdk/tm/ts/src/utility/StructUtility.ts

@@ -1,61 +1,8 @@
 // VENDORED: @voxgig/struct 0.3.4 (typescript/src/StructUtility.ts)
-// Source: https://github.com/voxgig/struct @ 3110e839a3f35b2fbdb047bf0c24f29d144027ea  [tag: sdk-20260917-1242-0]
+// Source: https://github.com/voxgig/struct @ 3a42881b1d26c75ebbed9f1897f0ba94cf3cf780  [tag: sdk-20260925-1316-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 /* Copyright (c) 2025-2026 Voxgig Ltd. MIT LICENSE. */
 
-// VERSION: @voxgig/struct 0.3.6
-
-/* Voxgig Struct
- * =============
- *
- * Utility functions to manipulate in-memory JSON-like data
- * structures. These structures assumed to be composed of nested
- * "nodes", where a node is a list or map, and has named or indexed
- * fields.  The general design principle is "by-example". Transform
- * specifications mirror the desired output.  This implementation is
- * designed for porting to multiple language, and to be tolerant of
- * undefined values.
- *
- * Main utilities
- * - getpath: get the value at a key path deep inside an object.
- * - merge: merge multiple nodes, overriding values in earlier nodes.
- * - walk: walk a node tree, applying a function at each node and leaf.
- * - inject: inject values from a data store into a new data structure.
- * - transform: transform a data structure to an example structure.
- * - validate: valiate a data structure against a shape specification.
- *
- * Minor utilities
- * - isnode, islist, ismap, iskey, isfunc: identify value kinds.
- * - isempty: undefined values, or empty nodes.
- * - keysof: sorted list of node keys (ascending).
- * - haskey: true if key value is defined.
- * - clone: create a copy of a JSON-like data structure.
- * - items: list entries of a map or list as [key, value] pairs.
- * - getprop: safely get a property value by key.
- * - setprop: safely set a property value by key.
- * - stringify: human-friendly string version of a value.
- * - escre: escape a regular expresion string.
- * - escurl: escape a url.
- * - join: join parts of a url, merging forward slashes.
- *
- * This set of functions and supporting utilities is designed to work
- * uniformly across many languages, meaning that some code that may be
- * functionally redundant in specific languages is still retained to
- * keep the code human comparable.
- *
- * NOTE: Lists are assumed to be mutable and reference stable.
- *
- * NOTE: In this code JSON nulls are in general *not* considered the
- * same as the undefined value in the given language. However most
- * JSON parsers do use the undefined value to represent JSON
- * null. This is ambiguous as JSON null is a separate value, not an
- * undefined value. You should convert such values to a special value
- * to represent JSON null, if this ambiguity creates issues
- * (thankfully in most APIs, JSON nulls are not used). For example,
- * the unit tests use the string "__NULL__" where necessary.
- *
- */
-
 // String constants are explicitly defined.
 
 // Mode value for inject step (bitfield).
@@ -63,7 +10,6 @@ const M_KEYPRE = 1
 const M_KEYPOST = 2
 const M_VAL = 4
 
-// Special strings.
 const S_BKEY = '`$KEY`'
 const S_BANNO = '`$ANNO`'
 const S_BEXACT = '`$EXACT`'
@@ -74,7 +20,6 @@ const S_DTOP = '$TOP'
 const S_DERRS = '$ERRS'
 const S_DSPEC = '$SPEC'
 
-// General strings.
 const S_list = 'list'
 const S_base = 'base'
 const S_boolean = 'boolean'
@@ -94,7 +39,6 @@ const S_map = 'map'
 const S_scalar = 'scalar'
 const S_node = 'node'
 
-// Character strings.
 const S_BT = '`'
 const S_CN = ':'
 const S_CS = ']'
@@ -108,7 +52,6 @@ const S_SP = ' '
 const S_CM = ','
 const S_VIZ = ': '
 
-// Types
 let t = 31
 const T_any = (1 << t--) - 1
 const T_noval = 1 << t-- // Means property absent, undefined. Also NOT a scalar!
@@ -119,7 +62,7 @@ const T_number = 1 << t--
 const T_string = 1 << t--
 const T_function = 1 << t--
 const T_symbol = 1 << t--
-const T_null = 1 << t-- // The actual JSON null value.
+const T_null = 1 << t--
 t -= 7
 const T_list = 1 << t--
 const T_map = 1 << t--
@@ -160,25 +103,22 @@ const TYPENAME = [
 // The standard undefined value for this language.
 const NONE = undefined
 
-// Private markers
 const SKIP = { '`$SKIP`': true }
 const DELETE = { '`$DELETE`': true }
 
-// Regular expression constants
-const R_INTEGER_KEY = /^[-0-9]+$/ // Match integer keys (including <0).
+const R_INTEGER_KEY = /^[-0-9]+$/
 const R_ESCAPE_REGEXP = /[.*+?^${}()|[\]\\]/g // Chars that need escaping in regexp.
-const R_QUOTES = /"/g // Double quotes for removal.
-const R_DOT = /\./g // Dots in path strings.
-const R_CLONE_REF = /^`\$REF:([0-9]+)`$/ // Copy reference in cloning.
-const R_META_PATH = /^([^$]+)\$([=~])(.+)$/ // Meta path syntax.
-const R_DOUBLE_DOLLAR = /\$\$/g // Double dollar escape sequence.
-const R_TRANSFORM_NAME = /`\$([A-Z]+)`/g // Transform command names.
-const R_INJECTION_FULL = /^`(\$[A-Z]+|[^`]*)[0-9]*`$/ // Full string injection pattern.
-const R_BT_ESCAPE = /\$BT/g // Backtick escape sequence.
-const R_DS_ESCAPE = /\$DS/g // Dollar sign escape sequence.
-const R_INJECTION_PARTIAL = /`([^`]+)`/g // Partial string injection pattern.
-
-// Default max depth (for walk etc).
+const R_QUOTES = /"/g
+const R_DOT = /\./g
+const R_CLONE_REF = /^`\$REF:([0-9]+)`$/
+const R_META_PATH = /^([^$]+)\$([=~])(.+)$/
+const R_DOUBLE_DOLLAR = /\$\$/g
+const R_TRANSFORM_NAME = /`\$([A-Z]+)`/g
+const R_INJECTION_FULL = /^`(\$[A-Z]+|[^`]*)[0-9]*`$/
+const R_BT_ESCAPE = /\$BT/g
+const R_DS_ESCAPE = /\$DS/g
+const R_INJECTION_PARTIAL = /`([^`]+)`/g
+
 const MAXDEPTH = 32
 
 // Keys are strings for maps, or integers for lists.
@@ -187,36 +127,21 @@ type PropKey = string | number
 // Type that can be indexed by both string and number keys.
 type Indexable = { [key: string]: any } & { [key: number]: any }
 
-// For each key in a node (map or list), perform value injections in
-// three phases: on key value, before child, and then on key value again.
-// This mode is passed via the Injection structure.
 type InjectMode = number
 
 // Handle value injections using backtick escape sequences:
 // - `a.b.c`: insert value at {a:{b:{c:1}}}
 // - `$FOO`: apply transform FOO
 type Injector = (
-  inj: Injection, // Injection state.
-  val: any, // Injection value specification.
+  inj: Injection,
+  val: any,
   ref: string, // Original injection reference string.
-  store: any, // Current source root value.
+  store: any,
 ) => any
 
 // Apply a custom modification to injections.
-type Modify = (
-  val: any, // Value.
-  key?: PropKey, // Value key, if any,
-  parent?: any, // Parent node, if any.
-  inj?: Injection, // Injection state, if any.
-  store?: any, // Store, if any
-) => void
-
-// Function applied to each node and leaf when walking a node structure depth first.
-// For {a:{b:1}} the call sequence args will be: b, 1, {b:1}, [a,b].
-// NOTE: the `path` array passed to the callback is reused across calls during
-// a single walk (one shared array per depth). It is valid only for the
-// duration of the callback invocation. If a callback needs to retain the
-// path, it MUST clone it (e.g. `path.slice()`).
+type Modify = (val: any, key?: PropKey, parent?: any, inj?: Injection, store?: any) => void
+
 type WalkApply = (
   // Map keys are strings, list keys are numbers, top key is NONE
   key: string | number | undefined,
@@ -271,7 +196,6 @@ function isempty(val: any) {
   )
 }
 
-// Value is a function.
 function isfunc(val: any): val is (...args: any[]) => any {
   return S_function === typeof val
 }
@@ -298,13 +222,6 @@ function size(val: any): number {
   }
 }
 
-// Extract part of an array or string into a new value, from the start
-// point to the end point.  If no end is specified, extract to the
-// full length of the value. Negative arguments count from the end of
-// the value. For numbers, perform min and max bounding, where start
-// is inclusive, and end is *exclusive*.
-// NOTE: input lists are not mutated by default. Use the mutate
-// argument to mutate lists in place.
 function slice<V>(val: V, start?: number, end?: number, mutate?: boolean): V {
   if (S_number === typeof val) {
     start = null == start || S_number !== typeof start ? Number.MIN_SAFE_INTEGER : start
@@ -367,7 +284,6 @@ function slice<V>(val: V, start?: number, end?: number, mutate?: boolean): V {
   return val
 }
 
-// String padding.
 function pad(str: any, padding?: number, padchar?: string): string {
   str = S_string === typeof str ? str : stringify(str)
   padding = null == padding ? 44 : padding
@@ -536,11 +452,6 @@ function items(val: any, apply?: (item: [string, any]) => any): any[] {
   return out
 }
 
-// To replicate the array spread operator:
-// a=1, b=[2,3], c=[4,5]
-// [a,...b,c] -> [1,2,3,[4,5]]
-// flatten([a,b,[c]]) -> [1,2,3,[4,5]]
-// NOTE: [c] ensures c is not expanded
 function flatten(list: any[], depth?: number) {
   if (!islist(list)) {
     return list
@@ -561,7 +472,6 @@ function filter(val: any, check: (item: [string, any]) => boolean): any[] {
   return out
 }
 
-// Escape regular expression.
 function escre(s: string) {
   return re_replace(R_ESCAPE_REGEXP, s, '\\$&')
 }
@@ -571,7 +481,6 @@ function re_escape(s: string) {
   return escre(s)
 }
 
-// Escape URLs.
 function escurl(s: string) {
   s = null == s ? S_MT : s
   return encodeURIComponent(s)
@@ -583,8 +492,6 @@ function escurl(s: string) {
 // uses these helpers instead of host-language regex methods directly.
 // ===========================================================================
 
-// Compile a regex (or return as-is if already compiled). Cached behaviour is
-// up to the port; in TS we just construct a RegExp.
 function re_compile(pattern: string | RegExp, flags?: string): RegExp {
   if (pattern instanceof RegExp) {
     return pattern
@@ -640,7 +547,6 @@ function re_replace(
   return input.replace(re, replacement)
 }
 
-// Boolean test for any match.
 function re_test(pattern: string | RegExp, input: string): boolean {
   const re = pattern instanceof RegExp ? pattern : new RegExp(pattern)
   return re.test(input)
@@ -703,9 +609,6 @@ function join(arr: any[], sep?: string, url?: boolean) {
   return out
 }
 
-// Output JSON in a "standard" format, with 2 space indents, each property on a new line,
-// and spaces after {[: and before ]}. Any "wierd" values (NaN, etc) are output as null.
-// In general, the behaivor of of JavaScript's JSON.stringify(val,null,2) is followed.
 function jsonify(val: any, flags?: { indent?: number; offset?: number }) {
   let str = S_null
 
@@ -904,26 +807,11 @@ function jt(...v: any[]): any[] {
   return a
 }
 
-// Safely delete a property from an object or array element.
-// Undefined arguments and invalid keys are ignored.
-// Returns the (possibly modified) parent.
-// For objects, the property is deleted using the delete operator.
-// For arrays, the element at the index is removed and remaining elements are shifted down.
-// NOTE: parent list may be new list, thus update references.
 function delprop<PARENT>(parent: PARENT, key: any): PARENT {
   if (!iskey(key)) {
     return parent
   }
 
-  // A condensed structure is a DAG: one subtree can be reached by many
-  // references, so an in-place write would be visible through all of them.
-  // Raising is the decided contract (design Q1) - it can be relaxed to
-  // copy-on-write later without breaking any caller, where the reverse is not
-  // true. expand() gives an ordinary mutable copy.
-  //
-  // Checked AFTER the key validation: both helpers define an invalid key as
-  // ignored, so a call that cannot write must not start throwing merely
-  // because the store is condensed.
   if (iscondensed(parent as any)) {
     throw new Error(
       'struct: condensed structures are immutable - ' + 'expand() first, then modify the copy',
@@ -934,7 +822,6 @@ function delprop<PARENT>(parent: PARENT, key: any): PARENT {
     key = strkey(key)
     delete (parent as any)[key]
   } else if (islist(parent)) {
-    // Ensure key is an integer.
     let keyI = +key
 
     if (isNaN(keyI)) {
@@ -967,15 +854,6 @@ function setprop<PARENT>(parent: PARENT, key: any, val: any): PARENT {
     return parent
   }
 
-  // A condensed structure is a DAG: one subtree can be reached by many
-  // references, so an in-place write would be visible through all of them.
-  // Raising is the decided contract (design Q1) - it can be relaxed to
-  // copy-on-write later without breaking any caller, where the reverse is not
-  // true. expand() gives an ordinary mutable copy.
-  //
-  // Checked AFTER the key validation: both helpers define an invalid key as
-  // ignored, so a call that cannot write must not start throwing merely
-  // because the store is condensed.
   if (iscondensed(parent as any)) {
     throw new Error(
       'struct: condensed structures are immutable - ' + 'expand() first, then modify the copy',
@@ -987,7 +865,6 @@ function setprop<PARENT>(parent: PARENT, key: any, val: any): PARENT {
     const pany = parent as any
     pany[key] = val
   } else if (islist(parent)) {
-    // Ensure key is an integer.
     let keyI = +key
 
     if (isNaN(keyI)) {
@@ -996,15 +873,10 @@ function setprop<PARENT>(parent: PARENT, key: any, val: any): PARENT {
 
     keyI = Math.floor(keyI)
 
-    // TODO: DELETE list element
-
     // Set or append value at position keyI, or append if keyI out of bounds.
     if (0 <= keyI) {
       parent[slice(keyI, 0, size(parent) + 1)] = val
-    }
-
-    // Prepend value if keyI is negative
-    else {
+    } else {
       parent.unshift(val)
     }
   }
@@ -1012,26 +884,15 @@ function setprop<PARENT>(parent: PARENT, key: any, val: any): PARENT {
   return parent
 }
 
-// Walk a data structure depth first, applying a function to each value.
-// The `path` argument passed to the before/after callbacks is a single
-// mutable array per depth, shared across all callback invocations for the
-// lifetime of this top-level walk call. Callbacks that need to store the
-// path MUST clone it (e.g. `path.slice()`); the contents will otherwise
-// be overwritten by subsequent visits.
 function walk(
-  // These arguments are the public interface.
   val: any,
 
-  // Before descending into a node.
   before?: WalkApply,
 
-  // After descending into a node.
   after?: WalkApply,
 
-  // Maximum recursive depth, default: 32. Use null for infinite depth.
   maxdepth?: number,
 
-  // These areguments are used for recursive state.
   key?: string | number,
   parent?: any,
   path?: string[],
@@ -1092,11 +953,9 @@ function walk(
 // override each other, and do *not* merge.  The first element is
 // modified.
 function merge(val: any, maxdepth?: number): any {
-  // const md: number = null == maxdepth ? MAXDEPTH : maxdepth < 0 ? 0 : maxdepth
   const md: number = slice(maxdepth ?? MAXDEPTH, 0)
   let out: any = NONE
 
-  // Handle edge cases.
   if (!islist(val)) {
     return val
   }
@@ -1110,14 +969,12 @@ function merge(val: any, maxdepth?: number): any {
     return list[0]
   }
 
-  // Merge a list of values.
   out = getprop(list, 0, {})
 
   for (let oI = 1; oI < lenlist; oI++) {
     const obj = list[oI]
 
     if (!isnode(obj)) {
-      // Nodes win.
       out = obj
     } else {
       // Current value at path end in overriding node.
@@ -1131,10 +988,7 @@ function merge(val: any, maxdepth?: number): any {
 
         if (md <= pI) {
           setprop(cur[pI - 1], key, val)
-        }
-
-        // Scalars just override directly.
-        else if (!isnode(val)) {
+        } else if (!isnode(val)) {
           cur[pI] = val
         }
 
@@ -1154,10 +1008,7 @@ function merge(val: any, maxdepth?: number): any {
           // Matching override and destination so continue with their values.
           else if (vtype === typify(tval)) {
             cur[pI] = tval
-          }
-
-          // Override wins.
-          else {
+          } else {
             cur[pI] = val
 
             // No need to descend when override wins (destination is discarded).
@@ -1186,7 +1037,6 @@ function merge(val: any, maxdepth?: number): any {
 
       // Walk overriding node, creating paths in output as needed.
       out = walk(obj, before, after, maxdepth)
-      // console.log('WALK-DONE', out, obj)
     }
   }
 
@@ -1252,7 +1102,6 @@ function setpath(
 }
 
 function getpath(store: any, path: number | string | string[], injdef?: Partial<Injection>) {
-  // Operate on a string array.
   const parts = islist(path)
     ? path
     : 'string' === typeof path
@@ -1285,7 +1134,6 @@ function getpath(store: any, path: number | string | string[], injdef?: Partial<
     store = expand(store)
   }
 
-  // let root = store
   let val = store
   const base = getprop(injdef, S_base)
   const src = getprop(store, base, store)
@@ -1296,7 +1144,6 @@ function getpath(store: any, path: number | string | string[], injdef?: Partial<
   if (null == path || null == store || (1 === numparts && S_MT === parts[0])) {
     val = src
   } else if (0 < numparts) {
-    // Check for $ACTIONs
     if (1 === numparts) {
       val = getprop(store, parts[0])
     }
@@ -1348,7 +1195,6 @@ function getpath(store: any, path: number | string | string[], injdef?: Partial<
             if (0 === ascends) {
               val = dparent
             } else {
-              // const fullpath = slice(dpath, 0 - ascends).concat(parts.slice(pI + 1))
               const fullpath = flatten([slice(dpath, 0 - ascends), parts.slice(pI + 1)])
 
               if (ascends <= size(dpath)) {
@@ -1376,15 +1222,9 @@ function getpath(store: any, path: number | string | string[], injdef?: Partial<
     val = handler(injdef, val, ref, store)
   }
 
-  // console.log('GETPATH', path, val)
-
   return val
 }
 
-// Inject values from a data store into a node recursively, resolving
-// paths against the store, or current if they are local. The modify
-// argument allows custom modification of the result.  The inj
-// (Injection) argument is used to maintain recursive state.
 function inject(val: any, store: any, injdef?: Partial<Injection>) {
   const valtype = typeof val
   let inj: Injection = injdef as Injection
@@ -1392,7 +1232,6 @@ function inject(val: any, store: any, injdef?: Partial<Injection>) {
   // Create state if at root of injection.  The input value is placed
   // inside a virtual parent holder to simplify edge cases.
   if (NONE === injdef || null == injdef.mode) {
-    // Set up state assuming we are starting in the virtual parent.
     inj = new Injection(val, { [S_DTOP]: val })
     inj.dparent = store
     inj.errs = getprop(store, S_DERRS, [])
@@ -1411,13 +1250,7 @@ function inject(val: any, store: any, injdef?: Partial<Injection>) {
   // console.log('INJ-START', val, inj.mode, inj.key, inj.val,
   //  't=', inj.path, 'P=', inj.parent, 'dp=', inj.dparent, 'ST=', store.$TOP)
 
-  // Descend into node.
   if (isnode(val)) {
-    // Keys are sorted alphanumerically to ensure determinism.
-    // Injection transforms ($FOO) are processed *after* other keys.
-    // NOTE: the optional digits suffix of the transform can thus be
-    // used to order the transforms.
-
     let nodekeys: any[]
     nodekeys = keysof(val)
 
@@ -1430,10 +1263,6 @@ function inject(val: any, store: any, injdef?: Partial<Injection>) {
       nodekeys = keysof(val)
     }
 
-    // Each child key-value pair is processed in three injection phases:
-    // 1. inj.mode=M_KEYPRE - Key string is injected, returning a possibly altered key.
-    // 2. inj.mode=M_VAL - The child value is injected.
-    // 3. inj.mode=M_KEYPOST - Key string is injected again, allowing child mutation.
     for (let nkI = 0; nkI < nodekeys.length; nkI++) {
       const childinj = inj.child(nkI, nodekeys)
       const nodekey = childinj.key
@@ -1468,10 +1297,7 @@ function inject(val: any, store: any, injdef?: Partial<Injection>) {
         nodekeys = childinj.keys
       }
     }
-  }
-
-  // Inject paths into string scalars.
-  else if (S_string === valtype) {
+  } else if (S_string === valtype) {
     inj.mode = M_VAL
     val = _injectstr(val, store, inj)
     if (SKIP !== val) {
@@ -1479,7 +1305,6 @@ function inject(val: any, store: any, injdef?: Partial<Injection>) {
     }
   }
 
-  // Custom modification.
   if (inj.modify && SKIP !== val) {
     const mkey = inj.key
     const mparent = inj.parent
@@ -1488,24 +1313,18 @@ function inject(val: any, store: any, injdef?: Partial<Injection>) {
     inj.modify(mval, mkey, mparent, inj, store)
   }
 
-  // console.log('INJ-VAL', val)
-
   inj.val = val
 
-  // Original val reference may no longer be correct.
-  // This return value is only used as the top level result.
   return _lookup(inj.parent, S_DTOP)
 }
 
 // The transform_* functions are special command inject handlers (see Injector).
 
-// Delete a key from a map or list.
 const transform_DELETE: Injector = (inj: Injection) => {
   inj.setval(NONE)
   return NONE
 }
 
-// Copy value from source data.
 const transform_COPY: Injector = (inj: Injection, _val: any) => {
   const ijname = 'COPY'
 
@@ -1536,8 +1355,6 @@ const transform_KEY: Injector = (inj: Injection) => {
     return getprop(inj.dparent, keyspec)
   }
 
-  // Key is defined within general purpose $META object.
-  // return getprop(getprop(parent, S_BANNO), S_KEY, getprop(path, path.length - 2))
   return _lookup(_lookup(parent, S_BANNO), S_KEY) ?? getelem(path, -2)
 }
 
@@ -1574,8 +1391,6 @@ const transform_MERGE: Injector = (inj: Injection) => {
     // Remove the $MERGE command from a parent map.
     inj.setval(NONE)
 
-    // Literals in the parent have precedence, but we still merge onto
-    // the parent object, so that node tree references are not changed.
     const mergelist = flatten([[parent], args, [clone(parent)]])
 
     merge(mergelist)
@@ -1596,14 +1411,12 @@ const transform_EACH: Injector = (inj: Injection, _val: any, _ref: string, store
   // Remove remaining keys to avoid spurious processing.
   slice(inj.keys, 0, 1, true)
 
-  // const [err, srcpath, child] = injectorArgs([T_string, T_any], inj)
   const [err, srcpath, child] = injectorArgs([T_string, T_any], slice(inj.parent, 1))
   if (NONE !== err) {
     inj.errs.push('$' + ijname + ': ' + err)
     return NONE
   }
 
-  // Source data.
   const srcstore = getprop(store, inj.base, store)
 
   const src = getpath(srcstore, srcpath, inj)
@@ -1643,7 +1456,6 @@ const transform_EACH: Injector = (inj: Injection, _val: any, _ref: string, store
     const tpath = slice(inj.path, -1)
     const dpath = flatten([S_DTOP, srcpath.split(S_DT), '$:' + ckey])
 
-    // Parent structure.
     tcur = { [ckey]: tcur }
 
     if (1 < size(tpath)) {
@@ -1667,10 +1479,8 @@ const transform_EACH: Injector = (inj: Injection, _val: any, _ref: string, store
     rval = tinj.val
   }
 
-  // _updateAncestors(inj, target, tkey, rval)
   setprop(target, tkey, rval)
 
-  // Prevent callee from damaging first list entry (since we are in `val` mode).
   return rval[0]
 }
 
@@ -1685,7 +1495,6 @@ const transform_PACK: Injector = (inj: Injection, _val: any, _ref: string, store
     return NONE
   }
 
-  // Get arguments.
   const args = getprop(parent, key)
   const [err, srcpath, origchildspec] = injectorArgs([T_string, T_any], args)
   if (NONE !== err) {
@@ -1693,16 +1502,13 @@ const transform_PACK: Injector = (inj: Injection, _val: any, _ref: string, store
     return NONE
   }
 
-  // Find key and target node.
   const tkey = getelem(path, -2)
   const pathsize = size(path)
   const target = getelem(nodes, pathsize - 2, () => getelem(nodes, pathsize - 1))
 
-  // Source data
   const srcstore = getprop(store, inj.base, store)
   let src = getpath(srcstore, srcpath, inj)
 
-  // Prepare source as a list.
   if (!islist(src)) {
     if (ismap(src)) {
       src = items(src, (item: [string, any]) => {
@@ -1718,13 +1524,11 @@ const transform_PACK: Injector = (inj: Injection, _val: any, _ref: string, store
     return NONE
   }
 
-  // Get keypath.
   const keypath = getprop(origchildspec, S_BKEY)
   const childspec = delprop(origchildspec, S_BKEY)
 
   const child = getprop(childspec, S_BVAL, childspec)
 
-  // Build parallel target object.
   const tval: any = {}
 
   items(src, (item: [string, any]) => {
@@ -1754,7 +1558,6 @@ const transform_PACK: Injector = (inj: Injection, _val: any, _ref: string, store
   let rval = {}
 
   if (!isempty(tval)) {
-    // Build parallel source object.
     const tsrc: any = {}
     src.reduce((a: any, n: any, i: any) => {
       const kn =
@@ -1795,16 +1598,11 @@ const transform_PACK: Injector = (inj: Injection, _val: any, _ref: string, store
     rval = tinj.val
   }
 
-  // _updateAncestors(inj, target, tkey, rval)
   setprop(target, tkey, rval)
 
-  // Drop transform key.
   return NONE
 }
 
-// TODO: not found ref should removed key (setprop NONE)
-// Reference original spec (enables recursice transformations)
-// Format: ['`$REF`', '`spec-path`']
 const transform_REF: Injector = (inj: Injection, val: any, _ref: string, store: any) => {
   const { nodes } = inj
 
@@ -1816,13 +1614,10 @@ const transform_REF: Injector = (inj: Injection, val: any, _ref: string, store:
   const refpath = _lookup(inj.parent, 1)
   inj.keyI = size(inj.keys)
 
-  // Spec reference.
   const spec = getprop(store, S_DSPEC)()
 
   const dpath = slice(inj.path, 1)
   const ref = getpath(spec, refpath, {
-    // TODO: test relative refs
-    // dpath: inj.path.slice(1),
     dpath,
     // dparent: getpath(spec, inj.path.slice(1))
     dparent: getpath(spec, dpath),
@@ -1874,8 +1669,6 @@ const transform_REF: Injector = (inj: Injection, val: any, _ref: string, store:
 }
 
 const transform_FORMAT: Injector = (inj: Injection, _val: any, _ref: string, store: any) => {
-  // console.log('FORMAT-START', inj, _val)
-
   // Remove remaining keys to avoid spurious processing.
   slice(inj.keys, 0, 1, true)
 
@@ -1883,12 +1676,9 @@ const transform_FORMAT: Injector = (inj: Injection, _val: any, _ref: string, sto
     return NONE
   }
 
-  // Get arguments: ['`$FORMAT`', 'name', child].
-  // TODO: EACH and PACK should accept customm functions too
   const name = _lookup(inj.parent, 1)
   const child = _lookup(inj.parent, 2)
 
-  // Source data.
   const tkey = getelem(inj.path, -2)
   const target = getelem(inj.nodes, -2, () => getelem(inj.nodes, -1))
 
@@ -1905,7 +1695,6 @@ const transform_FORMAT: Injector = (inj: Injection, _val: any, _ref: string, sto
   const out = walk(resolved, formatter)
 
   setprop(target, tkey, out)
-  // _updateAncestors(inj, target, tkey, out)
 
   return out
 }
@@ -1953,7 +1742,6 @@ const transform_APPLY: Injector = (inj: Injection, _val: any, _ref: string, stor
     return NONE
   }
 
-  // const [err, apply, child] = injectorArgs([T_function, T_any], inj)
   const [err, apply, child] = injectorArgs([T_function, T_any], slice(inj.parent, 1))
   if (NONE !== err) {
     inj.errs.push('$' + ijname + ': ' + err)
@@ -2036,7 +1824,6 @@ function transform(
         $APPLY: transform_APPLY,
       },
 
-      // Custom extra transforms, if any.
       extraTransforms,
 
       {
@@ -2093,7 +1880,6 @@ const validate_TYPE: Injector = (inj: Injection, _val: any, ref: string) => {
   return out
 }
 
-// Allow any value.
 const validate_ANY: Injector = (inj: Injection) => {
   const out = _lookup(inj.dparent, inj.key)
   return out
@@ -2107,11 +1893,9 @@ const validate_CHILD: Injector = (inj: Injection) => {
 
   // Setup data structures for validation by cloning child template.
 
-  // Map syntax.
   if (M_KEYPRE === mode) {
     const childtm = getprop(parent, key)
 
-    // Get corresponding current object.
     const pkey = getelem(path, -2)
     let tval = getprop(inj.dparent, pkey)
 
@@ -2130,15 +1914,12 @@ const validate_CHILD: Injector = (inj: Injection) => {
       keys.push(ckey)
     }
 
-    // Remove $CHILD to cleanup ouput.
     inj.setval(NONE)
     return NONE
   }
 
-  // List syntax.
   if (M_VAL === mode) {
     if (!islist(parent)) {
-      // $CHILD was not inside a list.
       inj.errs.push('Invalid $CHILD as value')
       return NONE
     }
@@ -2146,8 +1927,6 @@ const validate_CHILD: Injector = (inj: Injection) => {
     const childtm = _lookup(parent, 1)
 
     if (NONE === inj.dparent) {
-      // Empty list as default.
-      // parent.length = 0
       slice(parent, 0, 0, true)
       return NONE
     }
@@ -2190,11 +1969,6 @@ const validate_CHILD: Injector = (inj: Injection) => {
   return NONE
 }
 
-// TODO: implement SOME, ALL
-// FIX: ONE should mean exactly one, not at least one (=SOME)
-// TODO: implement a generate validate_ALT to do all of these
-// Match at least one of the specified shapes.
-// Syntax: ['`$ONE`', alt0, alt1, ...]
 const validate_ONE: Injector = (inj: Injection, _val: any, _ref: string, store: any) => {
   const { mode, parent, keyI } = inj
 
@@ -2214,8 +1988,9 @@ const validate_ONE: Injector = (inj: Injection, _val: any, _ref: string, store:
     // Clean up structure, replacing [$ONE, ...] with current
     inj.setval(inj.dparent, 2)
 
+    // Path shortens for the message only: `modify` reads
+    // getprop(inj.parent, inj.key), and inj.parent is still this list.
     inj.path = slice(inj.path, -1)
-    inj.key = getelem(inj.path, -1)
 
     const tvals = slice(parent, 1)
     if (0 === size(tvals)) {
@@ -2227,9 +2002,7 @@ const validate_ONE: Injector = (inj: Injection, _val: any, _ref: string, store:
       return
     }
 
-    // See if we can find a match.
     for (const tval of tvals) {
-      // If match, then errs.length = 0
       const terrs: any[] = []
 
       const vstore = merge([{}, store], 1)
@@ -2249,7 +2022,6 @@ const validate_ONE: Injector = (inj: Injection, _val: any, _ref: string, store:
       }
     }
 
-    // There was no match.
     const valdesc = replace(
       join(
         items(tvals, (n) => stringify(n[1])),
@@ -2290,7 +2062,6 @@ const validate_EXACT: Injector = (inj: Injection) => {
     // Clean up structure, replacing [$EXACT, ...] with current data parent
     inj.setval(inj.dparent, 2)
 
-    // inj.path = slice(inj.path, 0, size(inj.path) - 1)
     inj.path = slice(inj.path, 0, -1)
     inj.key = getelem(inj.path, -1)
 
@@ -2304,7 +2075,6 @@ const validate_EXACT: Injector = (inj: Injection) => {
       return
     }
 
-    // See if we can find an exact value match.
     let currentstr: string | undefined = undefined
     for (const tval of tvals) {
       let exactmatch = tval === inj.dparent
@@ -2320,7 +2090,6 @@ const validate_EXACT: Injector = (inj: Injection) => {
       }
     }
 
-    // There was no match.
     const valdesc = replace(
       join(
         items(tvals, (n) => stringify(n[1])),
@@ -2358,10 +2127,8 @@ const _validation: Modify = (pval: any, key?: any, parent?: any, inj?: Injection
     return
   }
 
-  // select needs exact matches
   const exact = getprop(inj.meta, S_BEXACT, false)
 
-  // Current val to verify.
   const cval = getprop(inj.dparent, key)
 
   if (NONE === inj || (!exact && NONE === cval)) {
@@ -2377,7 +2144,6 @@ const _validation: Modify = (pval: any, key?: any, parent?: any, inj?: Injection
 
   const ctype = typify(cval)
 
-  // Type mismatch.
   if (ptype !== ctype && NONE !== pval) {
     inj.errs.push(_invalidTypeMsg(inj.path, typename(ptype), ctype, cval, 'V0010'))
     return
@@ -2433,16 +2199,6 @@ const _validation: Modify = (pval: any, key?: any, parent?: any, inj?: Injection
   return
 }
 
-// Validate a data structure against a shape specification.  The shape
-// specification follows the "by example" principle.  Plain data in
-// teh shape is treated as default values that also specify the
-// required type.  Thus shape {a:1} validates {a:2}, since the types
-// (number) match, but not {a:'A'}.  Shape {a;1} against data {}
-// returns {a:1} as a=1 is the default value of the a key.  Special
-// validation commands (in the same syntax as transform ) are also
-// provided to specify required values.  Thus shape {a:'`$STRING`'}
-// validates {a:'A'} but not {a:1}. Empty map or list means the node
-// is open, and if missing an empty default is inserted.
 function validate(
   data: any, // Source data to transform into new data (original not mutated)
   spec: any, // Transform specification; output follows this shape
@@ -2456,7 +2212,6 @@ function validate(
   const store = merge(
     [
       {
-        // Remove the transform commands.
         $DELETE: null,
         $COPY: null,
         $KEY: null,
@@ -2607,11 +2362,8 @@ const select_NOT: Injector = (inj: Injection, _val: any, _ref: string, store: an
 const select_CMP: Injector = (inj: Injection, _val: any, ref: string, store: any) => {
   if (M_KEYPRE === inj.mode) {
     const term = _lookup(inj.parent, inj.key)
-    // const src = getprop(store, inj.base, store)
     const gkey = getelem(inj.path, -2)
 
-    // const tval = getprop(src, gkey)
-
     const ppath = slice(inj.path, -1)
     const point = getpath(store, ppath)
 
@@ -2650,10 +2402,6 @@ const select_CMP: Injector = (inj: Injection, _val: any, ref: string, store: any
   return NONE
 }
 
-// Select children from a top-level object that match a MongoDB-style query.
-// Supports $and, $or, and equality comparisons.
-// For arrays, children are elements; for objects, children are values.
-// TODO: swap arg order for consistency
 function select(children: any, query: any): any[] {
   if (!isnode(children)) {
     return []
@@ -2711,20 +2459,20 @@ class Injection {
   mode: InjectMode // Injection mode: M_KEYPRE, M_VAL, M_KEYPOST.
   full: boolean // Transform escape was full key name.
   keyI: number // Index of parent key in list of parent keys.
-  keys: string[] // List of parent keys.
-  key: string // Current parent key.
-  val: any // Current child value.
+  keys: string[]
+  key: string
+  val: any
   parent: any // Current parent (in transform specification).
-  path: string[] // Path to current node.
-  nodes: any[] // Stack of ancestor nodes.
-  handler: Injector // Custom handler for injections.
-  errs: any[] // Error collector.
+  path: string[]
+  nodes: any[]
+  handler: Injector
+  errs: any[]
   meta: Record<string, any> // Custom meta data. NOTE: do not merge, values must remain as-is.
   dparent: any // Current data parent node (contains current data value).
-  dpath: string[] // Current data value path
+  dpath: string[]
   base?: string // Base key for data in store, if any.
-  modify?: Modify // Modify injection output.
-  prior?: Injection // Parent (aka prior) injection.
+  modify?: Modify
+  prior?: Injection
   extra?: any
 
   constructor(val: any, parent: any) {
@@ -2802,7 +2550,6 @@ class Injection {
       }
     }
 
-    // TODO: is this needed?
     return this.dparent
   }
 
@@ -2845,7 +2592,6 @@ class Injection {
       parent = NONE === val ? delprop(aval, akey) : setprop(aval, akey, val)
     }
 
-    // console.log('SETVAL', val, this.key, this.parent)
     return parent
   }
 }
@@ -2853,12 +2599,6 @@ class Injection {
 // Internal utilities
 // ==================
 
-// // Update all references to target in inj.nodes.
-// function _updateAncestors(_inj: Injection, target: any, tkey: any, tval: any) {
-//   // SetProp is sufficient in TypeScript as target reference remains consistent even for lists.
-//   setprop(target, tkey, tval)
-// }
-
 // Build a type validation error message.
 function _invalidTypeMsg(path: any, needtype: string, vt: number, v: any, _whence?: string) {
   const vs = null == v ? 'no value' : stringify(v)
@@ -2883,9 +2623,6 @@ const _injecthandler: Injector = (inj: Injection, val: any, ref: string, store:
   let out = val
   const iscmd = isfunc(val) && (NONE === ref || ref.startsWith(S_DS))
 
-  // Only call val function if it is a special command ($NAME format).
-  // TODO: OR if meta.'$CALL'
-
   if (iscmd) {
     out = (val as Injector)(inj, val, ref, store)
   }
@@ -2920,24 +2657,13 @@ const _validatehandler: Injector = (inj: Injection, val: any, ref: string, store
   return out
 }
 
-// Inject values from a data store into a string. Not a public utility - used by
-// `inject`.  Inject are marked with `path` where path is resolved
-// with getpath against the store or current (if defined)
-// arguments. See `getpath`.  Custom injection handling can be
-// provided by inj.handler (this is used for transform functions).
-// The path can also have the special syntax $NAME999 where NAME is
-// upper case letters only, and 999 is any digits, which are
-// discarded. This syntax specifies the name of a transform, and
-// optionally allows transforms to be ordered by alphanumeric sorting.
 function _injectstr(val: string, store: any, inj?: Injection): any {
-  // Can't inject into non-strings
   if (S_string !== typeof val || S_MT === val) {
     return S_MT
   }
 
   let out: any = val
 
-  // Pattern examples: "`a.b.c`", "`$NAME`", "`$NAME1`"
   const m = re_find(R_INJECTION_FULL, val)
 
   // Full string of the val is an injection.
@@ -2947,18 +2673,14 @@ function _injectstr(val: string, store: any, inj?: Injection): any {
     }
     let pathref = m[1]
 
-    // Special escapes inside injection.
     if (3 < size(pathref)) {
       pathref = re_replace(R_DS_ESCAPE, re_replace(R_BT_ESCAPE, pathref, S_BT), S_DS)
     }
 
-    // Get the extracted path reference.
     out = getpath(store, pathref, inj)
   } else {
     // Check for injections within the string.
     const partial = (_m: string, ref: string) => {
-      // Special escapes inside injection.
-
       if (3 < size(ref)) {
         ref = re_replace(R_DS_ESCAPE, re_replace(R_BT_ESCAPE, ref, S_BT), S_DS)
       }
@@ -2969,7 +2691,6 @@ function _injectstr(val: string, store: any, inj?: Injection): any {
 
       const found = getpath(store, ref, inj)
 
-      // Ensure inject value is a string.
       return NONE === found ? S_MT : S_string === typeof found ? found : JSON.stringify(found)
     }
 
@@ -3043,13 +2764,11 @@ function checkPlacement(
   return true
 }
 
-// function injectorArgs(argTypes: number[], inj: Injection): any {
 function injectorArgs(argTypes: number[], args: any[]): any {
   const numargs = size(argTypes)
   const found = new Array(1 + numargs)
   found[0] = NONE
   for (let argI = 0; argI < numargs; argI++) {
-    // const arg = inj.parent[1 + argI]
     const arg = args[argI]
     const argType = typify(arg)
     if (0 === (argTypes[argI] & argType)) {
@@ -3086,7 +2805,6 @@ function injectChild(child: any, store: any, inj: Injection): Injection {
     }
   }
 
-  // console.log('FORMAT-INJECT-CHILD', child)
   inject(child, store, cinj)
 
   return cinj
@@ -3170,57 +2888,6 @@ class StructUtility {
   injectChild = injectChild
 }
 
-// ---------------------------------------------------------------------------
-// CONDENSED STRUCTURES
-//
-// A condensed structure holds the same information as a JSON-shaped node in a
-// fraction of the space, and can be read WITHOUT materialising it. Three
-// mechanisms, all in one format:
-//
-//   intern  a symbol table holds each distinct map key and string value once
-//   share   identical subtrees become ONE node with many references (a DAG)
-//   lazy    a reader resolves a path by walking integer indexes, touching
-//           only the nodes on that path
-//
-// The shape:
-//
-//   { "$condense": 1,      format version
-//     "sym":  [ ... ],     distinct strings, sorted (so lookup can bisect)
-//     "node": [ ... ],     integer-encoded nodes, children before parents
-//     "root": 12 }         index into node[]
-//
-// Each node is one of:
-//
-//   map     [0, k0, v0, k1, v1, ...]   k ascending symbol ids, v node refs
-//   list    [1, v0, v1, ...]           node refs
-//   string  [2, symId]
-//   number  [3, value]
-//   true    [4]        false [5]        null [6]
-//
-// Two properties are load-bearing rather than incidental:
-//
-//   Map keys ascend, because keysof() sorts. That makes output byte-stable
-//   (generators depend on it) and lets a key lookup bisect rather than scan.
-//
-//   References are integer indexes into a post-order table, so every ref
-//   points BACKWARDS. Sharing is therefore free — two identical subtrees
-//   intern to one node and two refs, with no dedup pass at read time — and a
-//   reader can never loop.
-//
-// The transport is JSON arrays of integers on purpose. The FORMAT is defined
-// here, but TOKENIZING is left to each language's own JSON parser: mature,
-// fast, memory-safe, already present, and nothing to keep in parity across
-// ports. A binary profile ($condense: 2) is a future option, deliberately
-// deferred - it is worth perhaps 2-3x and costs a hand-written decoder per
-// language.
-//
-// IMMUTABILITY. Sharing makes a condensed structure a DAG, so a mutation
-// through one reference would be visible through every other. Rather than
-// make that hazard the caller's problem, it is designed out: mutating
-// helpers RAISE on a condensed node, and expand()/value() always return an
-// independent copy. ref() is the one opt-in escape hatch and is named to be
-// alarming.
-
 const CONDENSE_VERSION = 1
 
 const CONDENSE_MAP = 0
@@ -3236,18 +2903,6 @@ const S_condsym = 'sym'
 const S_condnode = 'node'
 const S_condroot = 'root'
 
-// Is this a condensed structure? Checked structurally rather than by a marker
-// alone, so an ordinary map that happens to carry a `$condense` key is not
-// mistaken for one.
-// Compare by UNICODE CODE POINT, not by UTF-16 code unit.
-//
-// JavaScript's default string sort compares UTF-16 code units, which orders
-// an astral character BEFORE a high-BMP one; Python, Go and Rust all compare
-// by code point (equivalently, by UTF-8 bytes). A symbol table sorted the
-// JavaScript way would make two conforming ports emit different bytes for the
-// same input, which is exactly the byte-stability the format promises. Code
-// point order is the portable choice, so it is specified rather than
-// inherited.
 function condenseCmp(a: string, b: string): number {
   let i = 0
   let j = 0
@@ -3263,12 +2918,6 @@ function condenseCmp(a: string, b: string): number {
   return a.length - i - (b.length - j)
 }
 
-// Assign a key that may be `__proto__`.
-//
-// Plain assignment to `__proto__` invokes the inherited setter instead of
-// creating an own property, so a model carrying that key or string value
-// would be silently corrupted - it is valid JSON and Seneca-adjacent data
-// really does use `$`-ish and `__`-ish names.
 function condenseSet(obj: any, key: string, val: any) {
   if ('__proto__' === key) {
     Object.defineProperty(obj, key, {
@@ -3480,13 +3129,6 @@ function condenseResolve(cond: any, idx: number, path: any): number {
   return at
 }
 
-// Materialise node `idx` as an ordinary JSON-shaped value.
-//
-// Containers are rebuilt on every call and never memoised: sharing is an
-// implementation detail, and handing the same object out twice would let a
-// caller mutating one reference corrupt every other. The cost is that
-// expansion reproduces the original tree - which is exactly the size it was
-// before condensing, so it is bounded by the input.
 function condenseMaterialise(cond: any, idx: number): any {
   const sym = (cond as any)[S_condsym]
   const node = (cond as any)[S_condnode]