@voxgig/struct 0.3.6 → 0.3.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,58 +1,5 @@
1
1
  /* Copyright (c) 2025-2026 Voxgig Ltd. MIT LICENSE. */
2
2
 
3
- // VERSION: @voxgig/struct 0.3.6
4
-
5
- /* Voxgig Struct
6
- * =============
7
- *
8
- * Utility functions to manipulate in-memory JSON-like data
9
- * structures. These structures assumed to be composed of nested
10
- * "nodes", where a node is a list or map, and has named or indexed
11
- * fields. The general design principle is "by-example". Transform
12
- * specifications mirror the desired output. This implementation is
13
- * designed for porting to multiple language, and to be tolerant of
14
- * undefined values.
15
- *
16
- * Main utilities
17
- * - getpath: get the value at a key path deep inside an object.
18
- * - merge: merge multiple nodes, overriding values in earlier nodes.
19
- * - walk: walk a node tree, applying a function at each node and leaf.
20
- * - inject: inject values from a data store into a new data structure.
21
- * - transform: transform a data structure to an example structure.
22
- * - validate: valiate a data structure against a shape specification.
23
- *
24
- * Minor utilities
25
- * - isnode, islist, ismap, iskey, isfunc: identify value kinds.
26
- * - isempty: undefined values, or empty nodes.
27
- * - keysof: sorted list of node keys (ascending).
28
- * - haskey: true if key value is defined.
29
- * - clone: create a copy of a JSON-like data structure.
30
- * - items: list entries of a map or list as [key, value] pairs.
31
- * - getprop: safely get a property value by key.
32
- * - setprop: safely set a property value by key.
33
- * - stringify: human-friendly string version of a value.
34
- * - escre: escape a regular expresion string.
35
- * - escurl: escape a url.
36
- * - join: join parts of a url, merging forward slashes.
37
- *
38
- * This set of functions and supporting utilities is designed to work
39
- * uniformly across many languages, meaning that some code that may be
40
- * functionally redundant in specific languages is still retained to
41
- * keep the code human comparable.
42
- *
43
- * NOTE: Lists are assumed to be mutable and reference stable.
44
- *
45
- * NOTE: In this code JSON nulls are in general *not* considered the
46
- * same as the undefined value in the given language. However most
47
- * JSON parsers do use the undefined value to represent JSON
48
- * null. This is ambiguous as JSON null is a separate value, not an
49
- * undefined value. You should convert such values to a special value
50
- * to represent JSON null, if this ambiguity creates issues
51
- * (thankfully in most APIs, JSON nulls are not used). For example,
52
- * the unit tests use the string "__NULL__" where necessary.
53
- *
54
- */
55
-
56
3
  // String constants are explicitly defined.
57
4
 
58
5
  // Mode value for inject step (bitfield).
@@ -60,7 +7,6 @@ const M_KEYPRE = 1
60
7
  const M_KEYPOST = 2
61
8
  const M_VAL = 4
62
9
 
63
- // Special strings.
64
10
  const S_BKEY = '`$KEY`'
65
11
  const S_BANNO = '`$ANNO`'
66
12
  const S_BEXACT = '`$EXACT`'
@@ -71,7 +17,6 @@ const S_DTOP = '$TOP'
71
17
  const S_DERRS = '$ERRS'
72
18
  const S_DSPEC = '$SPEC'
73
19
 
74
- // General strings.
75
20
  const S_list = 'list'
76
21
  const S_base = 'base'
77
22
  const S_boolean = 'boolean'
@@ -91,7 +36,6 @@ const S_map = 'map'
91
36
  const S_scalar = 'scalar'
92
37
  const S_node = 'node'
93
38
 
94
- // Character strings.
95
39
  const S_BT = '`'
96
40
  const S_CN = ':'
97
41
  const S_CS = ']'
@@ -105,7 +49,6 @@ const S_SP = ' '
105
49
  const S_CM = ','
106
50
  const S_VIZ = ': '
107
51
 
108
- // Types
109
52
  let t = 31
110
53
  const T_any = (1 << t--) - 1
111
54
  const T_noval = 1 << t-- // Means property absent, undefined. Also NOT a scalar!
@@ -116,7 +59,7 @@ const T_number = 1 << t--
116
59
  const T_string = 1 << t--
117
60
  const T_function = 1 << t--
118
61
  const T_symbol = 1 << t--
119
- const T_null = 1 << t-- // The actual JSON null value.
62
+ const T_null = 1 << t--
120
63
  t -= 7
121
64
  const T_list = 1 << t--
122
65
  const T_map = 1 << t--
@@ -157,25 +100,22 @@ const TYPENAME = [
157
100
  // The standard undefined value for this language.
158
101
  const NONE = undefined
159
102
 
160
- // Private markers
161
103
  const SKIP = { '`$SKIP`': true }
162
104
  const DELETE = { '`$DELETE`': true }
163
105
 
164
- // Regular expression constants
165
- const R_INTEGER_KEY = /^[-0-9]+$/ // Match integer keys (including <0).
106
+ const R_INTEGER_KEY = /^[-0-9]+$/
166
107
  const R_ESCAPE_REGEXP = /[.*+?^${}()|[\]\\]/g // Chars that need escaping in regexp.
167
- const R_QUOTES = /"/g // Double quotes for removal.
168
- const R_DOT = /\./g // Dots in path strings.
169
- const R_CLONE_REF = /^`\$REF:([0-9]+)`$/ // Copy reference in cloning.
170
- const R_META_PATH = /^([^$]+)\$([=~])(.+)$/ // Meta path syntax.
171
- const R_DOUBLE_DOLLAR = /\$\$/g // Double dollar escape sequence.
172
- const R_TRANSFORM_NAME = /`\$([A-Z]+)`/g // Transform command names.
173
- const R_INJECTION_FULL = /^`(\$[A-Z]+|[^`]*)[0-9]*`$/ // Full string injection pattern.
174
- const R_BT_ESCAPE = /\$BT/g // Backtick escape sequence.
175
- const R_DS_ESCAPE = /\$DS/g // Dollar sign escape sequence.
176
- const R_INJECTION_PARTIAL = /`([^`]+)`/g // Partial string injection pattern.
177
-
178
- // Default max depth (for walk etc).
108
+ const R_QUOTES = /"/g
109
+ const R_DOT = /\./g
110
+ const R_CLONE_REF = /^`\$REF:([0-9]+)`$/
111
+ const R_META_PATH = /^([^$]+)\$([=~])(.+)$/
112
+ const R_DOUBLE_DOLLAR = /\$\$/g
113
+ const R_TRANSFORM_NAME = /`\$([A-Z]+)`/g
114
+ const R_INJECTION_FULL = /^`(\$[A-Z]+|[^`]*)[0-9]*`$/
115
+ const R_BT_ESCAPE = /\$BT/g
116
+ const R_DS_ESCAPE = /\$DS/g
117
+ const R_INJECTION_PARTIAL = /`([^`]+)`/g
118
+
179
119
  const MAXDEPTH = 32
180
120
 
181
121
  // Keys are strings for maps, or integers for lists.
@@ -184,36 +124,21 @@ type PropKey = string | number
184
124
  // Type that can be indexed by both string and number keys.
185
125
  type Indexable = { [key: string]: any } & { [key: number]: any }
186
126
 
187
- // For each key in a node (map or list), perform value injections in
188
- // three phases: on key value, before child, and then on key value again.
189
- // This mode is passed via the Injection structure.
190
127
  type InjectMode = number
191
128
 
192
129
  // Handle value injections using backtick escape sequences:
193
130
  // - `a.b.c`: insert value at {a:{b:{c:1}}}
194
131
  // - `$FOO`: apply transform FOO
195
132
  type Injector = (
196
- inj: Injection, // Injection state.
197
- val: any, // Injection value specification.
133
+ inj: Injection,
134
+ val: any,
198
135
  ref: string, // Original injection reference string.
199
- store: any, // Current source root value.
136
+ store: any,
200
137
  ) => any
201
138
 
202
139
  // Apply a custom modification to injections.
203
- type Modify = (
204
- val: any, // Value.
205
- key?: PropKey, // Value key, if any,
206
- parent?: any, // Parent node, if any.
207
- inj?: Injection, // Injection state, if any.
208
- store?: any, // Store, if any
209
- ) => void
210
-
211
- // Function applied to each node and leaf when walking a node structure depth first.
212
- // For {a:{b:1}} the call sequence args will be: b, 1, {b:1}, [a,b].
213
- // NOTE: the `path` array passed to the callback is reused across calls during
214
- // a single walk (one shared array per depth). It is valid only for the
215
- // duration of the callback invocation. If a callback needs to retain the
216
- // path, it MUST clone it (e.g. `path.slice()`).
140
+ type Modify = (val: any, key?: PropKey, parent?: any, inj?: Injection, store?: any) => void
141
+
217
142
  type WalkApply = (
218
143
  // Map keys are strings, list keys are numbers, top key is NONE
219
144
  key: string | number | undefined,
@@ -268,7 +193,6 @@ function isempty(val: any) {
268
193
  )
269
194
  }
270
195
 
271
- // Value is a function.
272
196
  function isfunc(val: any): val is (...args: any[]) => any {
273
197
  return S_function === typeof val
274
198
  }
@@ -295,13 +219,6 @@ function size(val: any): number {
295
219
  }
296
220
  }
297
221
 
298
- // Extract part of an array or string into a new value, from the start
299
- // point to the end point. If no end is specified, extract to the
300
- // full length of the value. Negative arguments count from the end of
301
- // the value. For numbers, perform min and max bounding, where start
302
- // is inclusive, and end is *exclusive*.
303
- // NOTE: input lists are not mutated by default. Use the mutate
304
- // argument to mutate lists in place.
305
222
  function slice<V>(val: V, start?: number, end?: number, mutate?: boolean): V {
306
223
  if (S_number === typeof val) {
307
224
  start = null == start || S_number !== typeof start ? Number.MIN_SAFE_INTEGER : start
@@ -364,7 +281,6 @@ function slice<V>(val: V, start?: number, end?: number, mutate?: boolean): V {
364
281
  return val
365
282
  }
366
283
 
367
- // String padding.
368
284
  function pad(str: any, padding?: number, padchar?: string): string {
369
285
  str = S_string === typeof str ? str : stringify(str)
370
286
  padding = null == padding ? 44 : padding
@@ -533,11 +449,6 @@ function items(val: any, apply?: (item: [string, any]) => any): any[] {
533
449
  return out
534
450
  }
535
451
 
536
- // To replicate the array spread operator:
537
- // a=1, b=[2,3], c=[4,5]
538
- // [a,...b,c] -> [1,2,3,[4,5]]
539
- // flatten([a,b,[c]]) -> [1,2,3,[4,5]]
540
- // NOTE: [c] ensures c is not expanded
541
452
  function flatten(list: any[], depth?: number) {
542
453
  if (!islist(list)) {
543
454
  return list
@@ -558,7 +469,6 @@ function filter(val: any, check: (item: [string, any]) => boolean): any[] {
558
469
  return out
559
470
  }
560
471
 
561
- // Escape regular expression.
562
472
  function escre(s: string) {
563
473
  return re_replace(R_ESCAPE_REGEXP, s, '\\$&')
564
474
  }
@@ -568,7 +478,6 @@ function re_escape(s: string) {
568
478
  return escre(s)
569
479
  }
570
480
 
571
- // Escape URLs.
572
481
  function escurl(s: string) {
573
482
  s = null == s ? S_MT : s
574
483
  return encodeURIComponent(s)
@@ -580,8 +489,6 @@ function escurl(s: string) {
580
489
  // uses these helpers instead of host-language regex methods directly.
581
490
  // ===========================================================================
582
491
 
583
- // Compile a regex (or return as-is if already compiled). Cached behaviour is
584
- // up to the port; in TS we just construct a RegExp.
585
492
  function re_compile(pattern: string | RegExp, flags?: string): RegExp {
586
493
  if (pattern instanceof RegExp) {
587
494
  return pattern
@@ -637,7 +544,6 @@ function re_replace(
637
544
  return input.replace(re, replacement)
638
545
  }
639
546
 
640
- // Boolean test for any match.
641
547
  function re_test(pattern: string | RegExp, input: string): boolean {
642
548
  const re = pattern instanceof RegExp ? pattern : new RegExp(pattern)
643
549
  return re.test(input)
@@ -700,9 +606,6 @@ function join(arr: any[], sep?: string, url?: boolean) {
700
606
  return out
701
607
  }
702
608
 
703
- // Output JSON in a "standard" format, with 2 space indents, each property on a new line,
704
- // and spaces after {[: and before ]}. Any "wierd" values (NaN, etc) are output as null.
705
- // In general, the behaivor of of JavaScript's JSON.stringify(val,null,2) is followed.
706
609
  function jsonify(val: any, flags?: { indent?: number; offset?: number }) {
707
610
  let str = S_null
708
611
 
@@ -901,26 +804,11 @@ function jt(...v: any[]): any[] {
901
804
  return a
902
805
  }
903
806
 
904
- // Safely delete a property from an object or array element.
905
- // Undefined arguments and invalid keys are ignored.
906
- // Returns the (possibly modified) parent.
907
- // For objects, the property is deleted using the delete operator.
908
- // For arrays, the element at the index is removed and remaining elements are shifted down.
909
- // NOTE: parent list may be new list, thus update references.
910
807
  function delprop<PARENT>(parent: PARENT, key: any): PARENT {
911
808
  if (!iskey(key)) {
912
809
  return parent
913
810
  }
914
811
 
915
- // A condensed structure is a DAG: one subtree can be reached by many
916
- // references, so an in-place write would be visible through all of them.
917
- // Raising is the decided contract (design Q1) - it can be relaxed to
918
- // copy-on-write later without breaking any caller, where the reverse is not
919
- // true. expand() gives an ordinary mutable copy.
920
- //
921
- // Checked AFTER the key validation: both helpers define an invalid key as
922
- // ignored, so a call that cannot write must not start throwing merely
923
- // because the store is condensed.
924
812
  if (iscondensed(parent as any)) {
925
813
  throw new Error(
926
814
  'struct: condensed structures are immutable - ' + 'expand() first, then modify the copy',
@@ -931,7 +819,6 @@ function delprop<PARENT>(parent: PARENT, key: any): PARENT {
931
819
  key = strkey(key)
932
820
  delete (parent as any)[key]
933
821
  } else if (islist(parent)) {
934
- // Ensure key is an integer.
935
822
  let keyI = +key
936
823
 
937
824
  if (isNaN(keyI)) {
@@ -964,15 +851,6 @@ function setprop<PARENT>(parent: PARENT, key: any, val: any): PARENT {
964
851
  return parent
965
852
  }
966
853
 
967
- // A condensed structure is a DAG: one subtree can be reached by many
968
- // references, so an in-place write would be visible through all of them.
969
- // Raising is the decided contract (design Q1) - it can be relaxed to
970
- // copy-on-write later without breaking any caller, where the reverse is not
971
- // true. expand() gives an ordinary mutable copy.
972
- //
973
- // Checked AFTER the key validation: both helpers define an invalid key as
974
- // ignored, so a call that cannot write must not start throwing merely
975
- // because the store is condensed.
976
854
  if (iscondensed(parent as any)) {
977
855
  throw new Error(
978
856
  'struct: condensed structures are immutable - ' + 'expand() first, then modify the copy',
@@ -984,7 +862,6 @@ function setprop<PARENT>(parent: PARENT, key: any, val: any): PARENT {
984
862
  const pany = parent as any
985
863
  pany[key] = val
986
864
  } else if (islist(parent)) {
987
- // Ensure key is an integer.
988
865
  let keyI = +key
989
866
 
990
867
  if (isNaN(keyI)) {
@@ -993,15 +870,10 @@ function setprop<PARENT>(parent: PARENT, key: any, val: any): PARENT {
993
870
 
994
871
  keyI = Math.floor(keyI)
995
872
 
996
- // TODO: DELETE list element
997
-
998
873
  // Set or append value at position keyI, or append if keyI out of bounds.
999
874
  if (0 <= keyI) {
1000
875
  parent[slice(keyI, 0, size(parent) + 1)] = val
1001
- }
1002
-
1003
- // Prepend value if keyI is negative
1004
- else {
876
+ } else {
1005
877
  parent.unshift(val)
1006
878
  }
1007
879
  }
@@ -1009,26 +881,15 @@ function setprop<PARENT>(parent: PARENT, key: any, val: any): PARENT {
1009
881
  return parent
1010
882
  }
1011
883
 
1012
- // Walk a data structure depth first, applying a function to each value.
1013
- // The `path` argument passed to the before/after callbacks is a single
1014
- // mutable array per depth, shared across all callback invocations for the
1015
- // lifetime of this top-level walk call. Callbacks that need to store the
1016
- // path MUST clone it (e.g. `path.slice()`); the contents will otherwise
1017
- // be overwritten by subsequent visits.
1018
884
  function walk(
1019
- // These arguments are the public interface.
1020
885
  val: any,
1021
886
 
1022
- // Before descending into a node.
1023
887
  before?: WalkApply,
1024
888
 
1025
- // After descending into a node.
1026
889
  after?: WalkApply,
1027
890
 
1028
- // Maximum recursive depth, default: 32. Use null for infinite depth.
1029
891
  maxdepth?: number,
1030
892
 
1031
- // These areguments are used for recursive state.
1032
893
  key?: string | number,
1033
894
  parent?: any,
1034
895
  path?: string[],
@@ -1087,13 +948,11 @@ function walk(
1087
948
  // Merge a list of values into each other. Later values have
1088
949
  // precedence. Nodes override scalars. Node kinds (list or map)
1089
950
  // override each other, and do *not* merge. The first element is
1090
- // modified.
951
+ // modified; the others are not.
1091
952
  function merge(val: any, maxdepth?: number): any {
1092
- // const md: number = null == maxdepth ? MAXDEPTH : maxdepth < 0 ? 0 : maxdepth
1093
953
  const md: number = slice(maxdepth ?? MAXDEPTH, 0)
1094
954
  let out: any = NONE
1095
955
 
1096
- // Handle edge cases.
1097
956
  if (!islist(val)) {
1098
957
  return val
1099
958
  }
@@ -1107,14 +966,12 @@ function merge(val: any, maxdepth?: number): any {
1107
966
  return list[0]
1108
967
  }
1109
968
 
1110
- // Merge a list of values.
1111
969
  out = getprop(list, 0, {})
1112
970
 
1113
971
  for (let oI = 1; oI < lenlist; oI++) {
1114
972
  const obj = list[oI]
1115
973
 
1116
974
  if (!isnode(obj)) {
1117
- // Nodes win.
1118
975
  out = obj
1119
976
  } else {
1120
977
  // Current value at path end in overriding node.
@@ -1128,10 +985,7 @@ function merge(val: any, maxdepth?: number): any {
1128
985
 
1129
986
  if (md <= pI) {
1130
987
  setprop(cur[pI - 1], key, val)
1131
- }
1132
-
1133
- // Scalars just override directly.
1134
- else if (!isnode(val)) {
988
+ } else if (!isnode(val)) {
1135
989
  cur[pI] = val
1136
990
  }
1137
991
 
@@ -1143,47 +997,41 @@ function merge(val: any, maxdepth?: number): any {
1143
997
 
1144
998
  const vtype = typify(val)
1145
999
 
1146
- // Destination empty, so create node (unless override is class instance).
1147
- if (NONE === tval && 0 === (T_instance & vtype)) {
1148
- cur[pI] = islist(val) ? [] : {}
1149
- }
1150
-
1151
1000
  // Matching override and destination so continue with their values.
1152
- else if (vtype === typify(tval)) {
1001
+ if (vtype === typify(tval)) {
1153
1002
  cur[pI] = tval
1154
1003
  }
1155
1004
 
1156
- // Override wins.
1157
- else {
1005
+ // Otherwise the override wins: a plain node is copied, taking
1006
+ // nothing from the destination, so no later merge writes into it.
1007
+ else if (0 === (T_instance & vtype)) {
1008
+ cur[pI] = islist(val) ? [] : {}
1009
+ dst[pI] = NONE
1010
+ } else {
1158
1011
  cur[pI] = val
1159
1012
 
1160
- // No need to descend when override wins (destination is discarded).
1013
+ // A class instance is kept as is, so there is nothing to descend.
1161
1014
  val = NONE
1162
1015
  }
1163
1016
  }
1164
1017
 
1165
- // console.log('BEFORE-END', pathify(path), '@', pI, key,
1166
- // stringify(val, -1, 1), stringify(parent, -1, 1),
1167
- // 'CUR=', stringify(cur, -1, 1), 'DST=', stringify(dst, -1, 1))
1168
-
1169
1018
  return val
1170
1019
  }
1171
1020
 
1172
- function after(key: string | number | undefined, _val: any, _parent: any, path: string[]) {
1021
+ function after(key: string | number | undefined, _val: any, parent: any, path: string[]) {
1173
1022
  const cI = size(path)
1174
1023
  const target = cur[cI - 1]
1175
1024
  const value = cur[cI]
1176
1025
 
1177
- // console.log('AFTER-PREP', pathify(path), '@', cI, cur, '|',
1178
- // stringify(key, -1, 1), stringify(value, -1, 1), 'T=', stringify(target, -1, 1))
1179
-
1180
1026
  setprop(target, key, value)
1181
- return value
1027
+
1028
+ // walk writes this back into the override, so below the root it is
1029
+ // the override's own child (_lookup keeps a null, getprop would not).
1030
+ return 0 === cI ? value : _lookup(parent, key)
1182
1031
  }
1183
1032
 
1184
1033
  // Walk overriding node, creating paths in output as needed.
1185
1034
  out = walk(obj, before, after, maxdepth)
1186
- // console.log('WALK-DONE', out, obj)
1187
1035
  }
1188
1036
  }
1189
1037
 
@@ -1249,7 +1097,6 @@ function setpath(
1249
1097
  }
1250
1098
 
1251
1099
  function getpath(store: any, path: number | string | string[], injdef?: Partial<Injection>) {
1252
- // Operate on a string array.
1253
1100
  const parts = islist(path)
1254
1101
  ? path
1255
1102
  : 'string' === typeof path
@@ -1282,7 +1129,6 @@ function getpath(store: any, path: number | string | string[], injdef?: Partial<
1282
1129
  store = expand(store)
1283
1130
  }
1284
1131
 
1285
- // let root = store
1286
1132
  let val = store
1287
1133
  const base = getprop(injdef, S_base)
1288
1134
  const src = getprop(store, base, store)
@@ -1293,7 +1139,6 @@ function getpath(store: any, path: number | string | string[], injdef?: Partial<
1293
1139
  if (null == path || null == store || (1 === numparts && S_MT === parts[0])) {
1294
1140
  val = src
1295
1141
  } else if (0 < numparts) {
1296
- // Check for $ACTIONs
1297
1142
  if (1 === numparts) {
1298
1143
  val = getprop(store, parts[0])
1299
1144
  }
@@ -1345,7 +1190,6 @@ function getpath(store: any, path: number | string | string[], injdef?: Partial<
1345
1190
  if (0 === ascends) {
1346
1191
  val = dparent
1347
1192
  } else {
1348
- // const fullpath = slice(dpath, 0 - ascends).concat(parts.slice(pI + 1))
1349
1193
  const fullpath = flatten([slice(dpath, 0 - ascends), parts.slice(pI + 1)])
1350
1194
 
1351
1195
  if (ascends <= size(dpath)) {
@@ -1373,15 +1217,9 @@ function getpath(store: any, path: number | string | string[], injdef?: Partial<
1373
1217
  val = handler(injdef, val, ref, store)
1374
1218
  }
1375
1219
 
1376
- // console.log('GETPATH', path, val)
1377
-
1378
1220
  return val
1379
1221
  }
1380
1222
 
1381
- // Inject values from a data store into a node recursively, resolving
1382
- // paths against the store, or current if they are local. The modify
1383
- // argument allows custom modification of the result. The inj
1384
- // (Injection) argument is used to maintain recursive state.
1385
1223
  function inject(val: any, store: any, injdef?: Partial<Injection>) {
1386
1224
  const valtype = typeof val
1387
1225
  let inj: Injection = injdef as Injection
@@ -1389,7 +1227,6 @@ function inject(val: any, store: any, injdef?: Partial<Injection>) {
1389
1227
  // Create state if at root of injection. The input value is placed
1390
1228
  // inside a virtual parent holder to simplify edge cases.
1391
1229
  if (NONE === injdef || null == injdef.mode) {
1392
- // Set up state assuming we are starting in the virtual parent.
1393
1230
  inj = new Injection(val, { [S_DTOP]: val })
1394
1231
  inj.dparent = store
1395
1232
  inj.errs = getprop(store, S_DERRS, [])
@@ -1408,13 +1245,7 @@ function inject(val: any, store: any, injdef?: Partial<Injection>) {
1408
1245
  // console.log('INJ-START', val, inj.mode, inj.key, inj.val,
1409
1246
  // 't=', inj.path, 'P=', inj.parent, 'dp=', inj.dparent, 'ST=', store.$TOP)
1410
1247
 
1411
- // Descend into node.
1412
1248
  if (isnode(val)) {
1413
- // Keys are sorted alphanumerically to ensure determinism.
1414
- // Injection transforms ($FOO) are processed *after* other keys.
1415
- // NOTE: the optional digits suffix of the transform can thus be
1416
- // used to order the transforms.
1417
-
1418
1249
  let nodekeys: any[]
1419
1250
  nodekeys = keysof(val)
1420
1251
 
@@ -1427,10 +1258,6 @@ function inject(val: any, store: any, injdef?: Partial<Injection>) {
1427
1258
  nodekeys = keysof(val)
1428
1259
  }
1429
1260
 
1430
- // Each child key-value pair is processed in three injection phases:
1431
- // 1. inj.mode=M_KEYPRE - Key string is injected, returning a possibly altered key.
1432
- // 2. inj.mode=M_VAL - The child value is injected.
1433
- // 3. inj.mode=M_KEYPOST - Key string is injected again, allowing child mutation.
1434
1261
  for (let nkI = 0; nkI < nodekeys.length; nkI++) {
1435
1262
  const childinj = inj.child(nkI, nodekeys)
1436
1263
  const nodekey = childinj.key
@@ -1465,10 +1292,7 @@ function inject(val: any, store: any, injdef?: Partial<Injection>) {
1465
1292
  nodekeys = childinj.keys
1466
1293
  }
1467
1294
  }
1468
- }
1469
-
1470
- // Inject paths into string scalars.
1471
- else if (S_string === valtype) {
1295
+ } else if (S_string === valtype) {
1472
1296
  inj.mode = M_VAL
1473
1297
  val = _injectstr(val, store, inj)
1474
1298
  if (SKIP !== val) {
@@ -1476,7 +1300,6 @@ function inject(val: any, store: any, injdef?: Partial<Injection>) {
1476
1300
  }
1477
1301
  }
1478
1302
 
1479
- // Custom modification.
1480
1303
  if (inj.modify && SKIP !== val) {
1481
1304
  const mkey = inj.key
1482
1305
  const mparent = inj.parent
@@ -1485,24 +1308,18 @@ function inject(val: any, store: any, injdef?: Partial<Injection>) {
1485
1308
  inj.modify(mval, mkey, mparent, inj, store)
1486
1309
  }
1487
1310
 
1488
- // console.log('INJ-VAL', val)
1489
-
1490
1311
  inj.val = val
1491
1312
 
1492
- // Original val reference may no longer be correct.
1493
- // This return value is only used as the top level result.
1494
1313
  return _lookup(inj.parent, S_DTOP)
1495
1314
  }
1496
1315
 
1497
1316
  // The transform_* functions are special command inject handlers (see Injector).
1498
1317
 
1499
- // Delete a key from a map or list.
1500
1318
  const transform_DELETE: Injector = (inj: Injection) => {
1501
1319
  inj.setval(NONE)
1502
1320
  return NONE
1503
1321
  }
1504
1322
 
1505
- // Copy value from source data.
1506
1323
  const transform_COPY: Injector = (inj: Injection, _val: any) => {
1507
1324
  const ijname = 'COPY'
1508
1325
 
@@ -1533,8 +1350,6 @@ const transform_KEY: Injector = (inj: Injection) => {
1533
1350
  return getprop(inj.dparent, keyspec)
1534
1351
  }
1535
1352
 
1536
- // Key is defined within general purpose $META object.
1537
- // return getprop(getprop(parent, S_BANNO), S_KEY, getprop(path, path.length - 2))
1538
1353
  return _lookup(_lookup(parent, S_BANNO), S_KEY) ?? getelem(path, -2)
1539
1354
  }
1540
1355
 
@@ -1571,8 +1386,6 @@ const transform_MERGE: Injector = (inj: Injection) => {
1571
1386
  // Remove the $MERGE command from a parent map.
1572
1387
  inj.setval(NONE)
1573
1388
 
1574
- // Literals in the parent have precedence, but we still merge onto
1575
- // the parent object, so that node tree references are not changed.
1576
1389
  const mergelist = flatten([[parent], args, [clone(parent)]])
1577
1390
 
1578
1391
  merge(mergelist)
@@ -1593,14 +1406,12 @@ const transform_EACH: Injector = (inj: Injection, _val: any, _ref: string, store
1593
1406
  // Remove remaining keys to avoid spurious processing.
1594
1407
  slice(inj.keys, 0, 1, true)
1595
1408
 
1596
- // const [err, srcpath, child] = injectorArgs([T_string, T_any], inj)
1597
1409
  const [err, srcpath, child] = injectorArgs([T_string, T_any], slice(inj.parent, 1))
1598
1410
  if (NONE !== err) {
1599
1411
  inj.errs.push('$' + ijname + ': ' + err)
1600
1412
  return NONE
1601
1413
  }
1602
1414
 
1603
- // Source data.
1604
1415
  const srcstore = getprop(store, inj.base, store)
1605
1416
 
1606
1417
  const src = getpath(srcstore, srcpath, inj)
@@ -1640,7 +1451,6 @@ const transform_EACH: Injector = (inj: Injection, _val: any, _ref: string, store
1640
1451
  const tpath = slice(inj.path, -1)
1641
1452
  const dpath = flatten([S_DTOP, srcpath.split(S_DT), '$:' + ckey])
1642
1453
 
1643
- // Parent structure.
1644
1454
  tcur = { [ckey]: tcur }
1645
1455
 
1646
1456
  if (1 < size(tpath)) {
@@ -1664,10 +1474,8 @@ const transform_EACH: Injector = (inj: Injection, _val: any, _ref: string, store
1664
1474
  rval = tinj.val
1665
1475
  }
1666
1476
 
1667
- // _updateAncestors(inj, target, tkey, rval)
1668
1477
  setprop(target, tkey, rval)
1669
1478
 
1670
- // Prevent callee from damaging first list entry (since we are in `val` mode).
1671
1479
  return rval[0]
1672
1480
  }
1673
1481
 
@@ -1682,7 +1490,6 @@ const transform_PACK: Injector = (inj: Injection, _val: any, _ref: string, store
1682
1490
  return NONE
1683
1491
  }
1684
1492
 
1685
- // Get arguments.
1686
1493
  const args = getprop(parent, key)
1687
1494
  const [err, srcpath, origchildspec] = injectorArgs([T_string, T_any], args)
1688
1495
  if (NONE !== err) {
@@ -1690,16 +1497,13 @@ const transform_PACK: Injector = (inj: Injection, _val: any, _ref: string, store
1690
1497
  return NONE
1691
1498
  }
1692
1499
 
1693
- // Find key and target node.
1694
1500
  const tkey = getelem(path, -2)
1695
1501
  const pathsize = size(path)
1696
1502
  const target = getelem(nodes, pathsize - 2, () => getelem(nodes, pathsize - 1))
1697
1503
 
1698
- // Source data
1699
1504
  const srcstore = getprop(store, inj.base, store)
1700
1505
  let src = getpath(srcstore, srcpath, inj)
1701
1506
 
1702
- // Prepare source as a list.
1703
1507
  if (!islist(src)) {
1704
1508
  if (ismap(src)) {
1705
1509
  src = items(src, (item: [string, any]) => {
@@ -1715,13 +1519,11 @@ const transform_PACK: Injector = (inj: Injection, _val: any, _ref: string, store
1715
1519
  return NONE
1716
1520
  }
1717
1521
 
1718
- // Get keypath.
1719
1522
  const keypath = getprop(origchildspec, S_BKEY)
1720
1523
  const childspec = delprop(origchildspec, S_BKEY)
1721
1524
 
1722
1525
  const child = getprop(childspec, S_BVAL, childspec)
1723
1526
 
1724
- // Build parallel target object.
1725
1527
  const tval: any = {}
1726
1528
 
1727
1529
  items(src, (item: [string, any]) => {
@@ -1751,7 +1553,6 @@ const transform_PACK: Injector = (inj: Injection, _val: any, _ref: string, store
1751
1553
  let rval = {}
1752
1554
 
1753
1555
  if (!isempty(tval)) {
1754
- // Build parallel source object.
1755
1556
  const tsrc: any = {}
1756
1557
  src.reduce((a: any, n: any, i: any) => {
1757
1558
  const kn =
@@ -1792,16 +1593,11 @@ const transform_PACK: Injector = (inj: Injection, _val: any, _ref: string, store
1792
1593
  rval = tinj.val
1793
1594
  }
1794
1595
 
1795
- // _updateAncestors(inj, target, tkey, rval)
1796
1596
  setprop(target, tkey, rval)
1797
1597
 
1798
- // Drop transform key.
1799
1598
  return NONE
1800
1599
  }
1801
1600
 
1802
- // TODO: not found ref should removed key (setprop NONE)
1803
- // Reference original spec (enables recursice transformations)
1804
- // Format: ['`$REF`', '`spec-path`']
1805
1601
  const transform_REF: Injector = (inj: Injection, val: any, _ref: string, store: any) => {
1806
1602
  const { nodes } = inj
1807
1603
 
@@ -1813,13 +1609,10 @@ const transform_REF: Injector = (inj: Injection, val: any, _ref: string, store:
1813
1609
  const refpath = _lookup(inj.parent, 1)
1814
1610
  inj.keyI = size(inj.keys)
1815
1611
 
1816
- // Spec reference.
1817
1612
  const spec = getprop(store, S_DSPEC)()
1818
1613
 
1819
1614
  const dpath = slice(inj.path, 1)
1820
1615
  const ref = getpath(spec, refpath, {
1821
- // TODO: test relative refs
1822
- // dpath: inj.path.slice(1),
1823
1616
  dpath,
1824
1617
  // dparent: getpath(spec, inj.path.slice(1))
1825
1618
  dparent: getpath(spec, dpath),
@@ -1871,8 +1664,6 @@ const transform_REF: Injector = (inj: Injection, val: any, _ref: string, store:
1871
1664
  }
1872
1665
 
1873
1666
  const transform_FORMAT: Injector = (inj: Injection, _val: any, _ref: string, store: any) => {
1874
- // console.log('FORMAT-START', inj, _val)
1875
-
1876
1667
  // Remove remaining keys to avoid spurious processing.
1877
1668
  slice(inj.keys, 0, 1, true)
1878
1669
 
@@ -1880,12 +1671,9 @@ const transform_FORMAT: Injector = (inj: Injection, _val: any, _ref: string, sto
1880
1671
  return NONE
1881
1672
  }
1882
1673
 
1883
- // Get arguments: ['`$FORMAT`', 'name', child].
1884
- // TODO: EACH and PACK should accept customm functions too
1885
1674
  const name = _lookup(inj.parent, 1)
1886
1675
  const child = _lookup(inj.parent, 2)
1887
1676
 
1888
- // Source data.
1889
1677
  const tkey = getelem(inj.path, -2)
1890
1678
  const target = getelem(inj.nodes, -2, () => getelem(inj.nodes, -1))
1891
1679
 
@@ -1902,7 +1690,6 @@ const transform_FORMAT: Injector = (inj: Injection, _val: any, _ref: string, sto
1902
1690
  const out = walk(resolved, formatter)
1903
1691
 
1904
1692
  setprop(target, tkey, out)
1905
- // _updateAncestors(inj, target, tkey, out)
1906
1693
 
1907
1694
  return out
1908
1695
  }
@@ -1950,7 +1737,6 @@ const transform_APPLY: Injector = (inj: Injection, _val: any, _ref: string, stor
1950
1737
  return NONE
1951
1738
  }
1952
1739
 
1953
- // const [err, apply, child] = injectorArgs([T_function, T_any], inj)
1954
1740
  const [err, apply, child] = injectorArgs([T_function, T_any], slice(inj.parent, 1))
1955
1741
  if (NONE !== err) {
1956
1742
  inj.errs.push('$' + ijname + ': ' + err)
@@ -2033,7 +1819,6 @@ function transform(
2033
1819
  $APPLY: transform_APPLY,
2034
1820
  },
2035
1821
 
2036
- // Custom extra transforms, if any.
2037
1822
  extraTransforms,
2038
1823
 
2039
1824
  {
@@ -2090,7 +1875,6 @@ const validate_TYPE: Injector = (inj: Injection, _val: any, ref: string) => {
2090
1875
  return out
2091
1876
  }
2092
1877
 
2093
- // Allow any value.
2094
1878
  const validate_ANY: Injector = (inj: Injection) => {
2095
1879
  const out = _lookup(inj.dparent, inj.key)
2096
1880
  return out
@@ -2104,11 +1888,9 @@ const validate_CHILD: Injector = (inj: Injection) => {
2104
1888
 
2105
1889
  // Setup data structures for validation by cloning child template.
2106
1890
 
2107
- // Map syntax.
2108
1891
  if (M_KEYPRE === mode) {
2109
1892
  const childtm = getprop(parent, key)
2110
1893
 
2111
- // Get corresponding current object.
2112
1894
  const pkey = getelem(path, -2)
2113
1895
  let tval = getprop(inj.dparent, pkey)
2114
1896
 
@@ -2127,15 +1909,12 @@ const validate_CHILD: Injector = (inj: Injection) => {
2127
1909
  keys.push(ckey)
2128
1910
  }
2129
1911
 
2130
- // Remove $CHILD to cleanup ouput.
2131
1912
  inj.setval(NONE)
2132
1913
  return NONE
2133
1914
  }
2134
1915
 
2135
- // List syntax.
2136
1916
  if (M_VAL === mode) {
2137
1917
  if (!islist(parent)) {
2138
- // $CHILD was not inside a list.
2139
1918
  inj.errs.push('Invalid $CHILD as value')
2140
1919
  return NONE
2141
1920
  }
@@ -2143,8 +1922,6 @@ const validate_CHILD: Injector = (inj: Injection) => {
2143
1922
  const childtm = _lookup(parent, 1)
2144
1923
 
2145
1924
  if (NONE === inj.dparent) {
2146
- // Empty list as default.
2147
- // parent.length = 0
2148
1925
  slice(parent, 0, 0, true)
2149
1926
  return NONE
2150
1927
  }
@@ -2187,11 +1964,6 @@ const validate_CHILD: Injector = (inj: Injection) => {
2187
1964
  return NONE
2188
1965
  }
2189
1966
 
2190
- // TODO: implement SOME, ALL
2191
- // FIX: ONE should mean exactly one, not at least one (=SOME)
2192
- // TODO: implement a generate validate_ALT to do all of these
2193
- // Match at least one of the specified shapes.
2194
- // Syntax: ['`$ONE`', alt0, alt1, ...]
2195
1967
  const validate_ONE: Injector = (inj: Injection, _val: any, _ref: string, store: any) => {
2196
1968
  const { mode, parent, keyI } = inj
2197
1969
 
@@ -2211,8 +1983,9 @@ const validate_ONE: Injector = (inj: Injection, _val: any, _ref: string, store:
2211
1983
  // Clean up structure, replacing [$ONE, ...] with current
2212
1984
  inj.setval(inj.dparent, 2)
2213
1985
 
1986
+ // Path shortens for the message only: `modify` reads
1987
+ // getprop(inj.parent, inj.key), and inj.parent is still this list.
2214
1988
  inj.path = slice(inj.path, -1)
2215
- inj.key = getelem(inj.path, -1)
2216
1989
 
2217
1990
  const tvals = slice(parent, 1)
2218
1991
  if (0 === size(tvals)) {
@@ -2224,9 +1997,7 @@ const validate_ONE: Injector = (inj: Injection, _val: any, _ref: string, store:
2224
1997
  return
2225
1998
  }
2226
1999
 
2227
- // See if we can find a match.
2228
2000
  for (const tval of tvals) {
2229
- // If match, then errs.length = 0
2230
2001
  const terrs: any[] = []
2231
2002
 
2232
2003
  const vstore = merge([{}, store], 1)
@@ -2246,7 +2017,6 @@ const validate_ONE: Injector = (inj: Injection, _val: any, _ref: string, store:
2246
2017
  }
2247
2018
  }
2248
2019
 
2249
- // There was no match.
2250
2020
  const valdesc = replace(
2251
2021
  join(
2252
2022
  items(tvals, (n) => stringify(n[1])),
@@ -2287,7 +2057,6 @@ const validate_EXACT: Injector = (inj: Injection) => {
2287
2057
  // Clean up structure, replacing [$EXACT, ...] with current data parent
2288
2058
  inj.setval(inj.dparent, 2)
2289
2059
 
2290
- // inj.path = slice(inj.path, 0, size(inj.path) - 1)
2291
2060
  inj.path = slice(inj.path, 0, -1)
2292
2061
  inj.key = getelem(inj.path, -1)
2293
2062
 
@@ -2301,7 +2070,6 @@ const validate_EXACT: Injector = (inj: Injection) => {
2301
2070
  return
2302
2071
  }
2303
2072
 
2304
- // See if we can find an exact value match.
2305
2073
  let currentstr: string | undefined = undefined
2306
2074
  for (const tval of tvals) {
2307
2075
  let exactmatch = tval === inj.dparent
@@ -2317,7 +2085,6 @@ const validate_EXACT: Injector = (inj: Injection) => {
2317
2085
  }
2318
2086
  }
2319
2087
 
2320
- // There was no match.
2321
2088
  const valdesc = replace(
2322
2089
  join(
2323
2090
  items(tvals, (n) => stringify(n[1])),
@@ -2355,10 +2122,8 @@ const _validation: Modify = (pval: any, key?: any, parent?: any, inj?: Injection
2355
2122
  return
2356
2123
  }
2357
2124
 
2358
- // select needs exact matches
2359
2125
  const exact = getprop(inj.meta, S_BEXACT, false)
2360
2126
 
2361
- // Current val to verify.
2362
2127
  const cval = getprop(inj.dparent, key)
2363
2128
 
2364
2129
  if (NONE === inj || (!exact && NONE === cval)) {
@@ -2374,7 +2139,6 @@ const _validation: Modify = (pval: any, key?: any, parent?: any, inj?: Injection
2374
2139
 
2375
2140
  const ctype = typify(cval)
2376
2141
 
2377
- // Type mismatch.
2378
2142
  if (ptype !== ctype && NONE !== pval) {
2379
2143
  inj.errs.push(_invalidTypeMsg(inj.path, typename(ptype), ctype, cval, 'V0010'))
2380
2144
  return
@@ -2430,16 +2194,6 @@ const _validation: Modify = (pval: any, key?: any, parent?: any, inj?: Injection
2430
2194
  return
2431
2195
  }
2432
2196
 
2433
- // Validate a data structure against a shape specification. The shape
2434
- // specification follows the "by example" principle. Plain data in
2435
- // teh shape is treated as default values that also specify the
2436
- // required type. Thus shape {a:1} validates {a:2}, since the types
2437
- // (number) match, but not {a:'A'}. Shape {a;1} against data {}
2438
- // returns {a:1} as a=1 is the default value of the a key. Special
2439
- // validation commands (in the same syntax as transform ) are also
2440
- // provided to specify required values. Thus shape {a:'`$STRING`'}
2441
- // validates {a:'A'} but not {a:1}. Empty map or list means the node
2442
- // is open, and if missing an empty default is inserted.
2443
2197
  function validate(
2444
2198
  data: any, // Source data to transform into new data (original not mutated)
2445
2199
  spec: any, // Transform specification; output follows this shape
@@ -2453,7 +2207,6 @@ function validate(
2453
2207
  const store = merge(
2454
2208
  [
2455
2209
  {
2456
- // Remove the transform commands.
2457
2210
  $DELETE: null,
2458
2211
  $COPY: null,
2459
2212
  $KEY: null,
@@ -2604,11 +2357,8 @@ const select_NOT: Injector = (inj: Injection, _val: any, _ref: string, store: an
2604
2357
  const select_CMP: Injector = (inj: Injection, _val: any, ref: string, store: any) => {
2605
2358
  if (M_KEYPRE === inj.mode) {
2606
2359
  const term = _lookup(inj.parent, inj.key)
2607
- // const src = getprop(store, inj.base, store)
2608
2360
  const gkey = getelem(inj.path, -2)
2609
2361
 
2610
- // const tval = getprop(src, gkey)
2611
-
2612
2362
  const ppath = slice(inj.path, -1)
2613
2363
  const point = getpath(store, ppath)
2614
2364
 
@@ -2647,10 +2397,6 @@ const select_CMP: Injector = (inj: Injection, _val: any, ref: string, store: any
2647
2397
  return NONE
2648
2398
  }
2649
2399
 
2650
- // Select children from a top-level object that match a MongoDB-style query.
2651
- // Supports $and, $or, and equality comparisons.
2652
- // For arrays, children are elements; for objects, children are values.
2653
- // TODO: swap arg order for consistency
2654
2400
  function select(children: any, query: any): any[] {
2655
2401
  if (!isnode(children)) {
2656
2402
  return []
@@ -2708,20 +2454,20 @@ class Injection {
2708
2454
  mode: InjectMode // Injection mode: M_KEYPRE, M_VAL, M_KEYPOST.
2709
2455
  full: boolean // Transform escape was full key name.
2710
2456
  keyI: number // Index of parent key in list of parent keys.
2711
- keys: string[] // List of parent keys.
2712
- key: string // Current parent key.
2713
- val: any // Current child value.
2457
+ keys: string[]
2458
+ key: string
2459
+ val: any
2714
2460
  parent: any // Current parent (in transform specification).
2715
- path: string[] // Path to current node.
2716
- nodes: any[] // Stack of ancestor nodes.
2717
- handler: Injector // Custom handler for injections.
2718
- errs: any[] // Error collector.
2461
+ path: string[]
2462
+ nodes: any[]
2463
+ handler: Injector
2464
+ errs: any[]
2719
2465
  meta: Record<string, any> // Custom meta data. NOTE: do not merge, values must remain as-is.
2720
2466
  dparent: any // Current data parent node (contains current data value).
2721
- dpath: string[] // Current data value path
2467
+ dpath: string[]
2722
2468
  base?: string // Base key for data in store, if any.
2723
- modify?: Modify // Modify injection output.
2724
- prior?: Injection // Parent (aka prior) injection.
2469
+ modify?: Modify
2470
+ prior?: Injection
2725
2471
  extra?: any
2726
2472
 
2727
2473
  constructor(val: any, parent: any) {
@@ -2799,7 +2545,6 @@ class Injection {
2799
2545
  }
2800
2546
  }
2801
2547
 
2802
- // TODO: is this needed?
2803
2548
  return this.dparent
2804
2549
  }
2805
2550
 
@@ -2842,7 +2587,6 @@ class Injection {
2842
2587
  parent = NONE === val ? delprop(aval, akey) : setprop(aval, akey, val)
2843
2588
  }
2844
2589
 
2845
- // console.log('SETVAL', val, this.key, this.parent)
2846
2590
  return parent
2847
2591
  }
2848
2592
  }
@@ -2850,12 +2594,6 @@ class Injection {
2850
2594
  // Internal utilities
2851
2595
  // ==================
2852
2596
 
2853
- // // Update all references to target in inj.nodes.
2854
- // function _updateAncestors(_inj: Injection, target: any, tkey: any, tval: any) {
2855
- // // SetProp is sufficient in TypeScript as target reference remains consistent even for lists.
2856
- // setprop(target, tkey, tval)
2857
- // }
2858
-
2859
2597
  // Build a type validation error message.
2860
2598
  function _invalidTypeMsg(path: any, needtype: string, vt: number, v: any, _whence?: string) {
2861
2599
  const vs = null == v ? 'no value' : stringify(v)
@@ -2880,9 +2618,6 @@ const _injecthandler: Injector = (inj: Injection, val: any, ref: string, store:
2880
2618
  let out = val
2881
2619
  const iscmd = isfunc(val) && (NONE === ref || ref.startsWith(S_DS))
2882
2620
 
2883
- // Only call val function if it is a special command ($NAME format).
2884
- // TODO: OR if meta.'$CALL'
2885
-
2886
2621
  if (iscmd) {
2887
2622
  out = (val as Injector)(inj, val, ref, store)
2888
2623
  }
@@ -2917,24 +2652,13 @@ const _validatehandler: Injector = (inj: Injection, val: any, ref: string, store
2917
2652
  return out
2918
2653
  }
2919
2654
 
2920
- // Inject values from a data store into a string. Not a public utility - used by
2921
- // `inject`. Inject are marked with `path` where path is resolved
2922
- // with getpath against the store or current (if defined)
2923
- // arguments. See `getpath`. Custom injection handling can be
2924
- // provided by inj.handler (this is used for transform functions).
2925
- // The path can also have the special syntax $NAME999 where NAME is
2926
- // upper case letters only, and 999 is any digits, which are
2927
- // discarded. This syntax specifies the name of a transform, and
2928
- // optionally allows transforms to be ordered by alphanumeric sorting.
2929
2655
  function _injectstr(val: string, store: any, inj?: Injection): any {
2930
- // Can't inject into non-strings
2931
2656
  if (S_string !== typeof val || S_MT === val) {
2932
2657
  return S_MT
2933
2658
  }
2934
2659
 
2935
2660
  let out: any = val
2936
2661
 
2937
- // Pattern examples: "`a.b.c`", "`$NAME`", "`$NAME1`"
2938
2662
  const m = re_find(R_INJECTION_FULL, val)
2939
2663
 
2940
2664
  // Full string of the val is an injection.
@@ -2944,18 +2668,14 @@ function _injectstr(val: string, store: any, inj?: Injection): any {
2944
2668
  }
2945
2669
  let pathref = m[1]
2946
2670
 
2947
- // Special escapes inside injection.
2948
2671
  if (3 < size(pathref)) {
2949
2672
  pathref = re_replace(R_DS_ESCAPE, re_replace(R_BT_ESCAPE, pathref, S_BT), S_DS)
2950
2673
  }
2951
2674
 
2952
- // Get the extracted path reference.
2953
2675
  out = getpath(store, pathref, inj)
2954
2676
  } else {
2955
2677
  // Check for injections within the string.
2956
2678
  const partial = (_m: string, ref: string) => {
2957
- // Special escapes inside injection.
2958
-
2959
2679
  if (3 < size(ref)) {
2960
2680
  ref = re_replace(R_DS_ESCAPE, re_replace(R_BT_ESCAPE, ref, S_BT), S_DS)
2961
2681
  }
@@ -2966,7 +2686,6 @@ function _injectstr(val: string, store: any, inj?: Injection): any {
2966
2686
 
2967
2687
  const found = getpath(store, ref, inj)
2968
2688
 
2969
- // Ensure inject value is a string.
2970
2689
  return NONE === found ? S_MT : S_string === typeof found ? found : JSON.stringify(found)
2971
2690
  }
2972
2691
 
@@ -3040,13 +2759,11 @@ function checkPlacement(
3040
2759
  return true
3041
2760
  }
3042
2761
 
3043
- // function injectorArgs(argTypes: number[], inj: Injection): any {
3044
2762
  function injectorArgs(argTypes: number[], args: any[]): any {
3045
2763
  const numargs = size(argTypes)
3046
2764
  const found = new Array(1 + numargs)
3047
2765
  found[0] = NONE
3048
2766
  for (let argI = 0; argI < numargs; argI++) {
3049
- // const arg = inj.parent[1 + argI]
3050
2767
  const arg = args[argI]
3051
2768
  const argType = typify(arg)
3052
2769
  if (0 === (argTypes[argI] & argType)) {
@@ -3083,7 +2800,6 @@ function injectChild(child: any, store: any, inj: Injection): Injection {
3083
2800
  }
3084
2801
  }
3085
2802
 
3086
- // console.log('FORMAT-INJECT-CHILD', child)
3087
2803
  inject(child, store, cinj)
3088
2804
 
3089
2805
  return cinj
@@ -3167,57 +2883,6 @@ class StructUtility {
3167
2883
  injectChild = injectChild
3168
2884
  }
3169
2885
 
3170
- // ---------------------------------------------------------------------------
3171
- // CONDENSED STRUCTURES
3172
- //
3173
- // A condensed structure holds the same information as a JSON-shaped node in a
3174
- // fraction of the space, and can be read WITHOUT materialising it. Three
3175
- // mechanisms, all in one format:
3176
- //
3177
- // intern a symbol table holds each distinct map key and string value once
3178
- // share identical subtrees become ONE node with many references (a DAG)
3179
- // lazy a reader resolves a path by walking integer indexes, touching
3180
- // only the nodes on that path
3181
- //
3182
- // The shape:
3183
- //
3184
- // { "$condense": 1, format version
3185
- // "sym": [ ... ], distinct strings, sorted (so lookup can bisect)
3186
- // "node": [ ... ], integer-encoded nodes, children before parents
3187
- // "root": 12 } index into node[]
3188
- //
3189
- // Each node is one of:
3190
- //
3191
- // map [0, k0, v0, k1, v1, ...] k ascending symbol ids, v node refs
3192
- // list [1, v0, v1, ...] node refs
3193
- // string [2, symId]
3194
- // number [3, value]
3195
- // true [4] false [5] null [6]
3196
- //
3197
- // Two properties are load-bearing rather than incidental:
3198
- //
3199
- // Map keys ascend, because keysof() sorts. That makes output byte-stable
3200
- // (generators depend on it) and lets a key lookup bisect rather than scan.
3201
- //
3202
- // References are integer indexes into a post-order table, so every ref
3203
- // points BACKWARDS. Sharing is therefore free — two identical subtrees
3204
- // intern to one node and two refs, with no dedup pass at read time — and a
3205
- // reader can never loop.
3206
- //
3207
- // The transport is JSON arrays of integers on purpose. The FORMAT is defined
3208
- // here, but TOKENIZING is left to each language's own JSON parser: mature,
3209
- // fast, memory-safe, already present, and nothing to keep in parity across
3210
- // ports. A binary profile ($condense: 2) is a future option, deliberately
3211
- // deferred - it is worth perhaps 2-3x and costs a hand-written decoder per
3212
- // language.
3213
- //
3214
- // IMMUTABILITY. Sharing makes a condensed structure a DAG, so a mutation
3215
- // through one reference would be visible through every other. Rather than
3216
- // make that hazard the caller's problem, it is designed out: mutating
3217
- // helpers RAISE on a condensed node, and expand()/value() always return an
3218
- // independent copy. ref() is the one opt-in escape hatch and is named to be
3219
- // alarming.
3220
-
3221
2886
  const CONDENSE_VERSION = 1
3222
2887
 
3223
2888
  const CONDENSE_MAP = 0
@@ -3233,18 +2898,6 @@ const S_condsym = 'sym'
3233
2898
  const S_condnode = 'node'
3234
2899
  const S_condroot = 'root'
3235
2900
 
3236
- // Is this a condensed structure? Checked structurally rather than by a marker
3237
- // alone, so an ordinary map that happens to carry a `$condense` key is not
3238
- // mistaken for one.
3239
- // Compare by UNICODE CODE POINT, not by UTF-16 code unit.
3240
- //
3241
- // JavaScript's default string sort compares UTF-16 code units, which orders
3242
- // an astral character BEFORE a high-BMP one; Python, Go and Rust all compare
3243
- // by code point (equivalently, by UTF-8 bytes). A symbol table sorted the
3244
- // JavaScript way would make two conforming ports emit different bytes for the
3245
- // same input, which is exactly the byte-stability the format promises. Code
3246
- // point order is the portable choice, so it is specified rather than
3247
- // inherited.
3248
2901
  function condenseCmp(a: string, b: string): number {
3249
2902
  let i = 0
3250
2903
  let j = 0
@@ -3260,12 +2913,6 @@ function condenseCmp(a: string, b: string): number {
3260
2913
  return a.length - i - (b.length - j)
3261
2914
  }
3262
2915
 
3263
- // Assign a key that may be `__proto__`.
3264
- //
3265
- // Plain assignment to `__proto__` invokes the inherited setter instead of
3266
- // creating an own property, so a model carrying that key or string value
3267
- // would be silently corrupted - it is valid JSON and Seneca-adjacent data
3268
- // really does use `$`-ish and `__`-ish names.
3269
2916
  function condenseSet(obj: any, key: string, val: any) {
3270
2917
  if ('__proto__' === key) {
3271
2918
  Object.defineProperty(obj, key, {
@@ -3477,13 +3124,6 @@ function condenseResolve(cond: any, idx: number, path: any): number {
3477
3124
  return at
3478
3125
  }
3479
3126
 
3480
- // Materialise node `idx` as an ordinary JSON-shaped value.
3481
- //
3482
- // Containers are rebuilt on every call and never memoised: sharing is an
3483
- // implementation detail, and handing the same object out twice would let a
3484
- // caller mutating one reference corrupt every other. The cost is that
3485
- // expansion reproduces the original tree - which is exactly the size it was
3486
- // before condensing, so it is bounded by the input.
3487
3127
  function condenseMaterialise(cond: any, idx: number): any {
3488
3128
  const sym = (cond as any)[S_condsym]
3489
3129
  const node = (cond as any)[S_condnode]