@voxgig/struct 0.3.6 → 0.4.0

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,23 @@ 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|-?[1-9][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_CHECKER_NAME = /^\$[A-Z]+$/
116
+ const R_BT_ESCAPE = /\$BT/g
117
+ const R_DS_ESCAPE = /\$DS/g
118
+ const R_INJECTION_PARTIAL = /`([^`]+)`/g
119
+
179
120
  const MAXDEPTH = 32
180
121
 
181
122
  // Keys are strings for maps, or integers for lists.
@@ -184,36 +125,21 @@ type PropKey = string | number
184
125
  // Type that can be indexed by both string and number keys.
185
126
  type Indexable = { [key: string]: any } & { [key: number]: any }
186
127
 
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
128
  type InjectMode = number
191
129
 
192
130
  // Handle value injections using backtick escape sequences:
193
131
  // - `a.b.c`: insert value at {a:{b:{c:1}}}
194
132
  // - `$FOO`: apply transform FOO
195
133
  type Injector = (
196
- inj: Injection, // Injection state.
197
- val: any, // Injection value specification.
134
+ inj: Injection,
135
+ val: any,
198
136
  ref: string, // Original injection reference string.
199
- store: any, // Current source root value.
137
+ store: any,
200
138
  ) => any
201
139
 
202
140
  // 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()`).
141
+ type Modify = (val: any, key?: PropKey, parent?: any, inj?: Injection, store?: any) => void
142
+
217
143
  type WalkApply = (
218
144
  // Map keys are strings, list keys are numbers, top key is NONE
219
145
  key: string | number | undefined,
@@ -268,7 +194,6 @@ function isempty(val: any) {
268
194
  )
269
195
  }
270
196
 
271
- // Value is a function.
272
197
  function isfunc(val: any): val is (...args: any[]) => any {
273
198
  return S_function === typeof val
274
199
  }
@@ -295,13 +220,6 @@ function size(val: any): number {
295
220
  }
296
221
  }
297
222
 
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
223
  function slice<V>(val: V, start?: number, end?: number, mutate?: boolean): V {
306
224
  if (S_number === typeof val) {
307
225
  start = null == start || S_number !== typeof start ? Number.MIN_SAFE_INTEGER : start
@@ -364,7 +282,6 @@ function slice<V>(val: V, start?: number, end?: number, mutate?: boolean): V {
364
282
  return val
365
283
  }
366
284
 
367
- // String padding.
368
285
  function pad(str: any, padding?: number, padchar?: string): string {
369
286
  str = S_string === typeof str ? str : stringify(str)
370
287
  padding = null == padding ? 44 : padding
@@ -418,8 +335,43 @@ function typify(value: any): number {
418
335
  return T_any
419
336
  }
420
337
 
421
- // Get a list element. The key should be an integer, or a string
422
- // that can parse to an integer only. Negative integers count from the end of the list.
338
+ // A list key's index: an integral number, or the string String(n) prints, else NaN.
339
+ function _listkey(key: any): number {
340
+ if (S_number === typeof key) {
341
+ return Number.isInteger(key) ? key + 0 : NaN
342
+ }
343
+ return S_string === typeof key && R_INTEGER_KEY.test(key) ? +key : NaN
344
+ }
345
+
346
+ // The stored value; a plain map yields own properties only, never __proto__.
347
+ function _readprop(val: any, key: any): any {
348
+ if (islist(val)) {
349
+ const keyI = _listkey(key)
350
+ return 0 <= keyI ? val[keyI] : NONE
351
+ }
352
+ if (S_string !== typeof key && S_number !== typeof key) {
353
+ return NONE
354
+ }
355
+ if (0 < (T_instance & typify(val))) {
356
+ return (val as any)[key]
357
+ }
358
+ return Object.prototype.hasOwnProperty.call(val, key) ? (val as any)[key] : NONE
359
+ }
360
+
361
+ function _setown(obj: any, key: string, val: any) {
362
+ if ('__proto__' === key) {
363
+ Object.defineProperty(obj, key, {
364
+ value: val,
365
+ enumerable: true,
366
+ writable: true,
367
+ configurable: true,
368
+ })
369
+ } else {
370
+ obj[key] = val
371
+ }
372
+ }
373
+
374
+ // Get a list element; a negative integer key counts from the end.
423
375
  function getelem(val: any, key: any, alt?: any) {
424
376
  let out = NONE
425
377
 
@@ -428,12 +380,12 @@ function getelem(val: any, key: any, alt?: any) {
428
380
  }
429
381
 
430
382
  if (islist(val)) {
431
- const nkey = parseInt(key)
432
- if (Number.isInteger(nkey) && re_test(R_INTEGER_KEY, '' + key)) {
433
- if (nkey < 0) {
434
- key = val.length + nkey
435
- }
436
- out = val[key]
383
+ let keyI = _listkey(key)
384
+ if (keyI < 0) {
385
+ keyI = val.length + keyI
386
+ }
387
+ if (0 <= keyI) {
388
+ out = val[keyI]
437
389
  }
438
390
  }
439
391
 
@@ -455,7 +407,7 @@ function getprop(val: any, key: any, alt?: any) {
455
407
  }
456
408
 
457
409
  if (isnode(val)) {
458
- out = val[key]
410
+ out = _readprop(val, key)
459
411
  }
460
412
 
461
413
  // JSON null at a key is treated as "no value" for the default-substitution
@@ -476,7 +428,7 @@ function getprop(val: any, key: any, alt?: any) {
476
428
  // null as absent (Group A) per UNDEF_SPEC.md.
477
429
  function _lookup(val: any, key: any): any {
478
430
  if (NONE === val || NONE === key) return NONE
479
- if (isnode(val)) return val[key]
431
+ if (isnode(val)) return _readprop(val, key)
480
432
  return NONE
481
433
  }
482
434
 
@@ -533,11 +485,6 @@ function items(val: any, apply?: (item: [string, any]) => any): any[] {
533
485
  return out
534
486
  }
535
487
 
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
488
  function flatten(list: any[], depth?: number) {
542
489
  if (!islist(list)) {
543
490
  return list
@@ -558,7 +505,6 @@ function filter(val: any, check: (item: [string, any]) => boolean): any[] {
558
505
  return out
559
506
  }
560
507
 
561
- // Escape regular expression.
562
508
  function escre(s: string) {
563
509
  return re_replace(R_ESCAPE_REGEXP, s, '\\$&')
564
510
  }
@@ -568,7 +514,6 @@ function re_escape(s: string) {
568
514
  return escre(s)
569
515
  }
570
516
 
571
- // Escape URLs.
572
517
  function escurl(s: string) {
573
518
  s = null == s ? S_MT : s
574
519
  return encodeURIComponent(s)
@@ -580,8 +525,6 @@ function escurl(s: string) {
580
525
  // uses these helpers instead of host-language regex methods directly.
581
526
  // ===========================================================================
582
527
 
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
528
  function re_compile(pattern: string | RegExp, flags?: string): RegExp {
586
529
  if (pattern instanceof RegExp) {
587
530
  return pattern
@@ -637,7 +580,6 @@ function re_replace(
637
580
  return input.replace(re, replacement)
638
581
  }
639
582
 
640
- // Boolean test for any match.
641
583
  function re_test(pattern: string | RegExp, input: string): boolean {
642
584
  const re = pattern instanceof RegExp ? pattern : new RegExp(pattern)
643
585
  return re.test(input)
@@ -700,9 +642,6 @@ function join(arr: any[], sep?: string, url?: boolean) {
700
642
  return out
701
643
  }
702
644
 
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
645
  function jsonify(val: any, flags?: { indent?: number; offset?: number }) {
707
646
  let str = S_null
708
647
 
@@ -886,7 +825,7 @@ function jm(...kv: any[]): Record<string, any> {
886
825
  // with value null" from "slot beyond end of kv".
887
826
  let k = i < kv.length ? kv[i] : '$KEY' + i
888
827
  k = 'string' === typeof k ? k : stringify(k)
889
- o[k] = i + 1 < kv.length ? kv[i + 1] : null
828
+ _setown(o, k, i + 1 < kv.length ? kv[i + 1] : null)
890
829
  }
891
830
  return o
892
831
  }
@@ -901,26 +840,11 @@ function jt(...v: any[]): any[] {
901
840
  return a
902
841
  }
903
842
 
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
843
  function delprop<PARENT>(parent: PARENT, key: any): PARENT {
911
844
  if (!iskey(key)) {
912
845
  return parent
913
846
  }
914
847
 
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
848
  if (iscondensed(parent as any)) {
925
849
  throw new Error(
926
850
  'struct: condensed structures are immutable - ' + 'expand() first, then modify the copy',
@@ -931,15 +855,12 @@ function delprop<PARENT>(parent: PARENT, key: any): PARENT {
931
855
  key = strkey(key)
932
856
  delete (parent as any)[key]
933
857
  } else if (islist(parent)) {
934
- // Ensure key is an integer.
935
- let keyI = +key
858
+ const keyI = _listkey(key)
936
859
 
937
860
  if (isNaN(keyI)) {
938
861
  return parent
939
862
  }
940
863
 
941
- keyI = Math.floor(keyI)
942
-
943
864
  // Delete list element at position keyI, shifting later elements down.
944
865
  const psize = size(parent)
945
866
  if (0 <= keyI && keyI < psize) {
@@ -964,15 +885,6 @@ function setprop<PARENT>(parent: PARENT, key: any, val: any): PARENT {
964
885
  return parent
965
886
  }
966
887
 
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
888
  if (iscondensed(parent as any)) {
977
889
  throw new Error(
978
890
  'struct: condensed structures are immutable - ' + 'expand() first, then modify the copy',
@@ -980,28 +892,18 @@ function setprop<PARENT>(parent: PARENT, key: any, val: any): PARENT {
980
892
  }
981
893
 
982
894
  if (ismap(parent)) {
983
- key = S_MT + key
984
- const pany = parent as any
985
- pany[key] = val
895
+ _setown(parent, S_MT + key, val)
986
896
  } else if (islist(parent)) {
987
- // Ensure key is an integer.
988
- let keyI = +key
897
+ const keyI = _listkey(key)
989
898
 
990
899
  if (isNaN(keyI)) {
991
900
  return parent
992
901
  }
993
902
 
994
- keyI = Math.floor(keyI)
995
-
996
- // TODO: DELETE list element
997
-
998
903
  // Set or append value at position keyI, or append if keyI out of bounds.
999
904
  if (0 <= keyI) {
1000
905
  parent[slice(keyI, 0, size(parent) + 1)] = val
1001
- }
1002
-
1003
- // Prepend value if keyI is negative
1004
- else {
906
+ } else {
1005
907
  parent.unshift(val)
1006
908
  }
1007
909
  }
@@ -1009,26 +911,15 @@ function setprop<PARENT>(parent: PARENT, key: any, val: any): PARENT {
1009
911
  return parent
1010
912
  }
1011
913
 
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
914
  function walk(
1019
- // These arguments are the public interface.
1020
915
  val: any,
1021
916
 
1022
- // Before descending into a node.
1023
917
  before?: WalkApply,
1024
918
 
1025
- // After descending into a node.
1026
919
  after?: WalkApply,
1027
920
 
1028
- // Maximum recursive depth, default: 32. Use null for infinite depth.
1029
921
  maxdepth?: number,
1030
922
 
1031
- // These areguments are used for recursive state.
1032
923
  key?: string | number,
1033
924
  parent?: any,
1034
925
  path?: string[],
@@ -1087,13 +978,11 @@ function walk(
1087
978
  // Merge a list of values into each other. Later values have
1088
979
  // precedence. Nodes override scalars. Node kinds (list or map)
1089
980
  // override each other, and do *not* merge. The first element is
1090
- // modified.
981
+ // modified; the others are not.
1091
982
  function merge(val: any, maxdepth?: number): any {
1092
- // const md: number = null == maxdepth ? MAXDEPTH : maxdepth < 0 ? 0 : maxdepth
1093
983
  const md: number = slice(maxdepth ?? MAXDEPTH, 0)
1094
984
  let out: any = NONE
1095
985
 
1096
- // Handle edge cases.
1097
986
  if (!islist(val)) {
1098
987
  return val
1099
988
  }
@@ -1107,14 +996,12 @@ function merge(val: any, maxdepth?: number): any {
1107
996
  return list[0]
1108
997
  }
1109
998
 
1110
- // Merge a list of values.
1111
999
  out = getprop(list, 0, {})
1112
1000
 
1113
1001
  for (let oI = 1; oI < lenlist; oI++) {
1114
1002
  const obj = list[oI]
1115
1003
 
1116
1004
  if (!isnode(obj)) {
1117
- // Nodes win.
1118
1005
  out = obj
1119
1006
  } else {
1120
1007
  // Current value at path end in overriding node.
@@ -1128,10 +1015,7 @@ function merge(val: any, maxdepth?: number): any {
1128
1015
 
1129
1016
  if (md <= pI) {
1130
1017
  setprop(cur[pI - 1], key, val)
1131
- }
1132
-
1133
- // Scalars just override directly.
1134
- else if (!isnode(val)) {
1018
+ } else if (!isnode(val)) {
1135
1019
  cur[pI] = val
1136
1020
  }
1137
1021
 
@@ -1143,47 +1027,41 @@ function merge(val: any, maxdepth?: number): any {
1143
1027
 
1144
1028
  const vtype = typify(val)
1145
1029
 
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
1030
  // Matching override and destination so continue with their values.
1152
- else if (vtype === typify(tval)) {
1031
+ if (vtype === typify(tval)) {
1153
1032
  cur[pI] = tval
1154
1033
  }
1155
1034
 
1156
- // Override wins.
1157
- else {
1035
+ // Otherwise the override wins: a plain node is copied, taking
1036
+ // nothing from the destination, so no later merge writes into it.
1037
+ else if (0 === (T_instance & vtype)) {
1038
+ cur[pI] = islist(val) ? [] : {}
1039
+ dst[pI] = NONE
1040
+ } else {
1158
1041
  cur[pI] = val
1159
1042
 
1160
- // No need to descend when override wins (destination is discarded).
1043
+ // A class instance is kept as is, so there is nothing to descend.
1161
1044
  val = NONE
1162
1045
  }
1163
1046
  }
1164
1047
 
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
1048
  return val
1170
1049
  }
1171
1050
 
1172
- function after(key: string | number | undefined, _val: any, _parent: any, path: string[]) {
1051
+ function after(key: string | number | undefined, _val: any, parent: any, path: string[]) {
1173
1052
  const cI = size(path)
1174
1053
  const target = cur[cI - 1]
1175
1054
  const value = cur[cI]
1176
1055
 
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
1056
  setprop(target, key, value)
1181
- return value
1057
+
1058
+ // walk writes this back into the override, so below the root it is
1059
+ // the override's own child (_lookup keeps a null, getprop would not).
1060
+ return 0 === cI ? value : _lookup(parent, key)
1182
1061
  }
1183
1062
 
1184
1063
  // Walk overriding node, creating paths in output as needed.
1185
1064
  out = walk(obj, before, after, maxdepth)
1186
- // console.log('WALK-DONE', out, obj)
1187
1065
  }
1188
1066
  }
1189
1067
 
@@ -1249,14 +1127,23 @@ function setpath(
1249
1127
  }
1250
1128
 
1251
1129
  function getpath(store: any, path: number | string | string[], injdef?: Partial<Injection>) {
1252
- // Operate on a string array.
1253
- const parts = islist(path)
1254
- ? path
1255
- : 'string' === typeof path
1256
- ? path.split(S_DT)
1257
- : 'number' === typeof path
1258
- ? [strkey(path)]
1259
- : NONE
1130
+ let parts: any = NONE
1131
+ if (islist(path)) {
1132
+ parts = []
1133
+ for (const part of path) {
1134
+ if (S_number === typeof part) {
1135
+ parts.push(S_MT + part)
1136
+ } else if (S_string === typeof part) {
1137
+ parts.push(part)
1138
+ } else {
1139
+ return NONE
1140
+ }
1141
+ }
1142
+ } else if (S_string === typeof path) {
1143
+ parts = (path as string).split(S_DT)
1144
+ } else if (S_number === typeof path) {
1145
+ parts = [S_MT + path]
1146
+ }
1260
1147
 
1261
1148
  if (NONE === parts) {
1262
1149
  return NONE
@@ -1282,7 +1169,6 @@ function getpath(store: any, path: number | string | string[], injdef?: Partial<
1282
1169
  store = expand(store)
1283
1170
  }
1284
1171
 
1285
- // let root = store
1286
1172
  let val = store
1287
1173
  const base = getprop(injdef, S_base)
1288
1174
  const src = getprop(store, base, store)
@@ -1293,7 +1179,6 @@ function getpath(store: any, path: number | string | string[], injdef?: Partial<
1293
1179
  if (null == path || null == store || (1 === numparts && S_MT === parts[0])) {
1294
1180
  val = src
1295
1181
  } else if (0 < numparts) {
1296
- // Check for $ACTIONs
1297
1182
  if (1 === numparts) {
1298
1183
  val = getprop(store, parts[0])
1299
1184
  }
@@ -1345,7 +1230,6 @@ function getpath(store: any, path: number | string | string[], injdef?: Partial<
1345
1230
  if (0 === ascends) {
1346
1231
  val = dparent
1347
1232
  } else {
1348
- // const fullpath = slice(dpath, 0 - ascends).concat(parts.slice(pI + 1))
1349
1233
  const fullpath = flatten([slice(dpath, 0 - ascends), parts.slice(pI + 1)])
1350
1234
 
1351
1235
  if (ascends <= size(dpath)) {
@@ -1373,15 +1257,9 @@ function getpath(store: any, path: number | string | string[], injdef?: Partial<
1373
1257
  val = handler(injdef, val, ref, store)
1374
1258
  }
1375
1259
 
1376
- // console.log('GETPATH', path, val)
1377
-
1378
1260
  return val
1379
1261
  }
1380
1262
 
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
1263
  function inject(val: any, store: any, injdef?: Partial<Injection>) {
1386
1264
  const valtype = typeof val
1387
1265
  let inj: Injection = injdef as Injection
@@ -1389,7 +1267,6 @@ function inject(val: any, store: any, injdef?: Partial<Injection>) {
1389
1267
  // Create state if at root of injection. The input value is placed
1390
1268
  // inside a virtual parent holder to simplify edge cases.
1391
1269
  if (NONE === injdef || null == injdef.mode) {
1392
- // Set up state assuming we are starting in the virtual parent.
1393
1270
  inj = new Injection(val, { [S_DTOP]: val })
1394
1271
  inj.dparent = store
1395
1272
  inj.errs = getprop(store, S_DERRS, [])
@@ -1408,13 +1285,7 @@ function inject(val: any, store: any, injdef?: Partial<Injection>) {
1408
1285
  // console.log('INJ-START', val, inj.mode, inj.key, inj.val,
1409
1286
  // 't=', inj.path, 'P=', inj.parent, 'dp=', inj.dparent, 'ST=', store.$TOP)
1410
1287
 
1411
- // Descend into node.
1412
1288
  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
1289
  let nodekeys: any[]
1419
1290
  nodekeys = keysof(val)
1420
1291
 
@@ -1427,10 +1298,6 @@ function inject(val: any, store: any, injdef?: Partial<Injection>) {
1427
1298
  nodekeys = keysof(val)
1428
1299
  }
1429
1300
 
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
1301
  for (let nkI = 0; nkI < nodekeys.length; nkI++) {
1435
1302
  const childinj = inj.child(nkI, nodekeys)
1436
1303
  const nodekey = childinj.key
@@ -1465,10 +1332,7 @@ function inject(val: any, store: any, injdef?: Partial<Injection>) {
1465
1332
  nodekeys = childinj.keys
1466
1333
  }
1467
1334
  }
1468
- }
1469
-
1470
- // Inject paths into string scalars.
1471
- else if (S_string === valtype) {
1335
+ } else if (S_string === valtype) {
1472
1336
  inj.mode = M_VAL
1473
1337
  val = _injectstr(val, store, inj)
1474
1338
  if (SKIP !== val) {
@@ -1476,7 +1340,6 @@ function inject(val: any, store: any, injdef?: Partial<Injection>) {
1476
1340
  }
1477
1341
  }
1478
1342
 
1479
- // Custom modification.
1480
1343
  if (inj.modify && SKIP !== val) {
1481
1344
  const mkey = inj.key
1482
1345
  const mparent = inj.parent
@@ -1485,24 +1348,18 @@ function inject(val: any, store: any, injdef?: Partial<Injection>) {
1485
1348
  inj.modify(mval, mkey, mparent, inj, store)
1486
1349
  }
1487
1350
 
1488
- // console.log('INJ-VAL', val)
1489
-
1490
1351
  inj.val = val
1491
1352
 
1492
- // Original val reference may no longer be correct.
1493
- // This return value is only used as the top level result.
1494
1353
  return _lookup(inj.parent, S_DTOP)
1495
1354
  }
1496
1355
 
1497
1356
  // The transform_* functions are special command inject handlers (see Injector).
1498
1357
 
1499
- // Delete a key from a map or list.
1500
1358
  const transform_DELETE: Injector = (inj: Injection) => {
1501
1359
  inj.setval(NONE)
1502
1360
  return NONE
1503
1361
  }
1504
1362
 
1505
- // Copy value from source data.
1506
1363
  const transform_COPY: Injector = (inj: Injection, _val: any) => {
1507
1364
  const ijname = 'COPY'
1508
1365
 
@@ -1533,8 +1390,6 @@ const transform_KEY: Injector = (inj: Injection) => {
1533
1390
  return getprop(inj.dparent, keyspec)
1534
1391
  }
1535
1392
 
1536
- // Key is defined within general purpose $META object.
1537
- // return getprop(getprop(parent, S_BANNO), S_KEY, getprop(path, path.length - 2))
1538
1393
  return _lookup(_lookup(parent, S_BANNO), S_KEY) ?? getelem(path, -2)
1539
1394
  }
1540
1395
 
@@ -1571,8 +1426,6 @@ const transform_MERGE: Injector = (inj: Injection) => {
1571
1426
  // Remove the $MERGE command from a parent map.
1572
1427
  inj.setval(NONE)
1573
1428
 
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
1429
  const mergelist = flatten([[parent], args, [clone(parent)]])
1577
1430
 
1578
1431
  merge(mergelist)
@@ -1593,14 +1446,12 @@ const transform_EACH: Injector = (inj: Injection, _val: any, _ref: string, store
1593
1446
  // Remove remaining keys to avoid spurious processing.
1594
1447
  slice(inj.keys, 0, 1, true)
1595
1448
 
1596
- // const [err, srcpath, child] = injectorArgs([T_string, T_any], inj)
1597
1449
  const [err, srcpath, child] = injectorArgs([T_string, T_any], slice(inj.parent, 1))
1598
1450
  if (NONE !== err) {
1599
1451
  inj.errs.push('$' + ijname + ': ' + err)
1600
1452
  return NONE
1601
1453
  }
1602
1454
 
1603
- // Source data.
1604
1455
  const srcstore = getprop(store, inj.base, store)
1605
1456
 
1606
1457
  const src = getpath(srcstore, srcpath, inj)
@@ -1640,7 +1491,6 @@ const transform_EACH: Injector = (inj: Injection, _val: any, _ref: string, store
1640
1491
  const tpath = slice(inj.path, -1)
1641
1492
  const dpath = flatten([S_DTOP, srcpath.split(S_DT), '$:' + ckey])
1642
1493
 
1643
- // Parent structure.
1644
1494
  tcur = { [ckey]: tcur }
1645
1495
 
1646
1496
  if (1 < size(tpath)) {
@@ -1664,10 +1514,8 @@ const transform_EACH: Injector = (inj: Injection, _val: any, _ref: string, store
1664
1514
  rval = tinj.val
1665
1515
  }
1666
1516
 
1667
- // _updateAncestors(inj, target, tkey, rval)
1668
1517
  setprop(target, tkey, rval)
1669
1518
 
1670
- // Prevent callee from damaging first list entry (since we are in `val` mode).
1671
1519
  return rval[0]
1672
1520
  }
1673
1521
 
@@ -1682,7 +1530,6 @@ const transform_PACK: Injector = (inj: Injection, _val: any, _ref: string, store
1682
1530
  return NONE
1683
1531
  }
1684
1532
 
1685
- // Get arguments.
1686
1533
  const args = getprop(parent, key)
1687
1534
  const [err, srcpath, origchildspec] = injectorArgs([T_string, T_any], args)
1688
1535
  if (NONE !== err) {
@@ -1690,16 +1537,13 @@ const transform_PACK: Injector = (inj: Injection, _val: any, _ref: string, store
1690
1537
  return NONE
1691
1538
  }
1692
1539
 
1693
- // Find key and target node.
1694
1540
  const tkey = getelem(path, -2)
1695
1541
  const pathsize = size(path)
1696
1542
  const target = getelem(nodes, pathsize - 2, () => getelem(nodes, pathsize - 1))
1697
1543
 
1698
- // Source data
1699
1544
  const srcstore = getprop(store, inj.base, store)
1700
1545
  let src = getpath(srcstore, srcpath, inj)
1701
1546
 
1702
- // Prepare source as a list.
1703
1547
  if (!islist(src)) {
1704
1548
  if (ismap(src)) {
1705
1549
  src = items(src, (item: [string, any]) => {
@@ -1715,13 +1559,11 @@ const transform_PACK: Injector = (inj: Injection, _val: any, _ref: string, store
1715
1559
  return NONE
1716
1560
  }
1717
1561
 
1718
- // Get keypath.
1719
1562
  const keypath = getprop(origchildspec, S_BKEY)
1720
1563
  const childspec = delprop(origchildspec, S_BKEY)
1721
1564
 
1722
1565
  const child = getprop(childspec, S_BVAL, childspec)
1723
1566
 
1724
- // Build parallel target object.
1725
1567
  const tval: any = {}
1726
1568
 
1727
1569
  items(src, (item: [string, any]) => {
@@ -1751,7 +1593,6 @@ const transform_PACK: Injector = (inj: Injection, _val: any, _ref: string, store
1751
1593
  let rval = {}
1752
1594
 
1753
1595
  if (!isempty(tval)) {
1754
- // Build parallel source object.
1755
1596
  const tsrc: any = {}
1756
1597
  src.reduce((a: any, n: any, i: any) => {
1757
1598
  const kn =
@@ -1792,19 +1633,12 @@ const transform_PACK: Injector = (inj: Injection, _val: any, _ref: string, store
1792
1633
  rval = tinj.val
1793
1634
  }
1794
1635
 
1795
- // _updateAncestors(inj, target, tkey, rval)
1796
1636
  setprop(target, tkey, rval)
1797
1637
 
1798
- // Drop transform key.
1799
1638
  return NONE
1800
1639
  }
1801
1640
 
1802
- // TODO: not found ref should removed key (setprop NONE)
1803
- // Reference original spec (enables recursice transformations)
1804
- // Format: ['`$REF`', '`spec-path`']
1805
- const transform_REF: Injector = (inj: Injection, val: any, _ref: string, store: any) => {
1806
- const { nodes } = inj
1807
-
1641
+ const transform_REF: Injector = (inj: Injection, _val: any, _ref: string, store: any) => {
1808
1642
  if (M_VAL !== inj.mode) {
1809
1643
  return NONE
1810
1644
  }
@@ -1813,15 +1647,11 @@ const transform_REF: Injector = (inj: Injection, val: any, _ref: string, store:
1813
1647
  const refpath = _lookup(inj.parent, 1)
1814
1648
  inj.keyI = size(inj.keys)
1815
1649
 
1816
- // Spec reference.
1817
1650
  const spec = getprop(store, S_DSPEC)()
1818
1651
 
1819
1652
  const dpath = slice(inj.path, 1)
1820
1653
  const ref = getpath(spec, refpath, {
1821
- // TODO: test relative refs
1822
- // dpath: inj.path.slice(1),
1823
1654
  dpath,
1824
- // dparent: getpath(spec, inj.path.slice(1))
1825
1655
  dparent: getpath(spec, dpath),
1826
1656
  })
1827
1657
 
@@ -1835,44 +1665,26 @@ const transform_REF: Injector = (inj: Injection, val: any, _ref: string, store:
1835
1665
  })
1836
1666
  }
1837
1667
 
1838
- const tref = clone(ref)
1839
-
1840
- const cpath = slice(inj.path, -3)
1841
- const tpath = slice(inj.path, -1)
1842
- const tcur = getpath(store, cpath)
1843
- const tval = getpath(store, tpath)
1844
- let rval = NONE
1845
-
1846
- if (!hasSubRef || NONE !== tval) {
1847
- const tinj = inj.child(0, [getelem(tpath, -1)])
1848
-
1849
- tinj.path = tpath
1850
- tinj.nodes = slice(inj.nodes, -1)
1851
- tinj.parent = getelem(nodes, -2)
1852
- tinj.val = tref
1853
-
1854
- tinj.dpath = flatten([cpath])
1855
- tinj.dparent = tcur
1856
-
1857
- inject(tref, store, tinj)
1858
-
1859
- rval = tinj.val
1860
- } else {
1861
- rval = NONE
1862
- }
1668
+ // A recursive reference stops where the data does.
1669
+ const tval = getpath(store, slice(inj.path, -1))
1670
+ const rval = !hasSubRef || NONE !== tval ? clone(ref) : NONE
1863
1671
 
1672
+ // The enclosing loop injects the referenced spec in this list's place, so
1673
+ // neither this pass nor this element leaves a value for modify to check.
1864
1674
  const grandparent = inj.setval(rval, 2)
1865
1675
 
1866
- if (islist(grandparent) && inj.prior) {
1867
- inj.prior.keyI--
1676
+ const prior = inj.prior
1677
+ if (prior) {
1678
+ prior.modify = NONE
1679
+ if (islist(grandparent) || NONE !== rval) {
1680
+ prior.keyI--
1681
+ }
1868
1682
  }
1869
1683
 
1870
- return val
1684
+ return SKIP
1871
1685
  }
1872
1686
 
1873
1687
  const transform_FORMAT: Injector = (inj: Injection, _val: any, _ref: string, store: any) => {
1874
- // console.log('FORMAT-START', inj, _val)
1875
-
1876
1688
  // Remove remaining keys to avoid spurious processing.
1877
1689
  slice(inj.keys, 0, 1, true)
1878
1690
 
@@ -1880,12 +1692,9 @@ const transform_FORMAT: Injector = (inj: Injection, _val: any, _ref: string, sto
1880
1692
  return NONE
1881
1693
  }
1882
1694
 
1883
- // Get arguments: ['`$FORMAT`', 'name', child].
1884
- // TODO: EACH and PACK should accept customm functions too
1885
1695
  const name = _lookup(inj.parent, 1)
1886
1696
  const child = _lookup(inj.parent, 2)
1887
1697
 
1888
- // Source data.
1889
1698
  const tkey = getelem(inj.path, -2)
1890
1699
  const target = getelem(inj.nodes, -2, () => getelem(inj.nodes, -1))
1891
1700
 
@@ -1902,7 +1711,6 @@ const transform_FORMAT: Injector = (inj: Injection, _val: any, _ref: string, sto
1902
1711
  const out = walk(resolved, formatter)
1903
1712
 
1904
1713
  setprop(target, tkey, out)
1905
- // _updateAncestors(inj, target, tkey, out)
1906
1714
 
1907
1715
  return out
1908
1716
  }
@@ -1950,7 +1758,6 @@ const transform_APPLY: Injector = (inj: Injection, _val: any, _ref: string, stor
1950
1758
  return NONE
1951
1759
  }
1952
1760
 
1953
- // const [err, apply, child] = injectorArgs([T_function, T_any], inj)
1954
1761
  const [err, apply, child] = injectorArgs([T_function, T_any], slice(inj.parent, 1))
1955
1762
  if (NONE !== err) {
1956
1763
  inj.errs.push('$' + ijname + ': ' + err)
@@ -2033,7 +1840,6 @@ function transform(
2033
1840
  $APPLY: transform_APPLY,
2034
1841
  },
2035
1842
 
2036
- // Custom extra transforms, if any.
2037
1843
  extraTransforms,
2038
1844
 
2039
1845
  {
@@ -2075,7 +1881,9 @@ const validate_STRING: Injector = (inj: Injection) => {
2075
1881
 
2076
1882
  const validate_TYPE: Injector = (inj: Injection, _val: any, ref: string) => {
2077
1883
  const tname = slice(ref, 1).toLowerCase()
2078
- const typev = 1 << (31 - TYPENAME.indexOf(tname))
1884
+
1885
+ // $NIL is absent or null.
1886
+ const typev = (1 << (31 - TYPENAME.indexOf(tname))) | (S_nil === tname ? T_null : 0)
2079
1887
  const out = _lookup(inj.dparent, inj.key)
2080
1888
 
2081
1889
  const t = typify(out)
@@ -2090,7 +1898,6 @@ const validate_TYPE: Injector = (inj: Injection, _val: any, ref: string) => {
2090
1898
  return out
2091
1899
  }
2092
1900
 
2093
- // Allow any value.
2094
1901
  const validate_ANY: Injector = (inj: Injection) => {
2095
1902
  const out = _lookup(inj.dparent, inj.key)
2096
1903
  return out
@@ -2104,18 +1911,16 @@ const validate_CHILD: Injector = (inj: Injection) => {
2104
1911
 
2105
1912
  // Setup data structures for validation by cloning child template.
2106
1913
 
2107
- // Map syntax.
2108
1914
  if (M_KEYPRE === mode) {
2109
1915
  const childtm = getprop(parent, key)
2110
1916
 
2111
- // Get corresponding current object.
2112
1917
  const pkey = getelem(path, -2)
2113
1918
  let tval = getprop(inj.dparent, pkey)
2114
1919
 
2115
1920
  if (NONE == tval) {
2116
1921
  tval = {}
2117
1922
  } else if (!ismap(tval)) {
2118
- inj.errs.push(_invalidTypeMsg(slice(inj.path, -1), S_object, typify(tval), tval), 'V0220')
1923
+ // _validation reports the mismatch, once.
2119
1924
  return NONE
2120
1925
  }
2121
1926
 
@@ -2127,15 +1932,12 @@ const validate_CHILD: Injector = (inj: Injection) => {
2127
1932
  keys.push(ckey)
2128
1933
  }
2129
1934
 
2130
- // Remove $CHILD to cleanup ouput.
2131
1935
  inj.setval(NONE)
2132
1936
  return NONE
2133
1937
  }
2134
1938
 
2135
- // List syntax.
2136
1939
  if (M_VAL === mode) {
2137
1940
  if (!islist(parent)) {
2138
- // $CHILD was not inside a list.
2139
1941
  inj.errs.push('Invalid $CHILD as value')
2140
1942
  return NONE
2141
1943
  }
@@ -2143,21 +1945,11 @@ const validate_CHILD: Injector = (inj: Injection) => {
2143
1945
  const childtm = _lookup(parent, 1)
2144
1946
 
2145
1947
  if (NONE === inj.dparent) {
2146
- // Empty list as default.
2147
- // parent.length = 0
2148
1948
  slice(parent, 0, 0, true)
2149
1949
  return NONE
2150
1950
  }
2151
1951
 
2152
1952
  if (!islist(inj.dparent)) {
2153
- const msg = _invalidTypeMsg(
2154
- slice(inj.path, -1),
2155
- S_list,
2156
- typify(inj.dparent),
2157
- inj.dparent,
2158
- 'V0230',
2159
- )
2160
- inj.errs.push(msg)
2161
1953
  inj.keyI = size(parent)
2162
1954
  return inj.dparent
2163
1955
  }
@@ -2187,66 +1979,45 @@ const validate_CHILD: Injector = (inj: Injection) => {
2187
1979
  return NONE
2188
1980
  }
2189
1981
 
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
- const validate_ONE: Injector = (inj: Injection, _val: any, _ref: string, store: any) => {
2196
- const { mode, parent, keyI } = inj
1982
+ const validate_EXACT: Injector = (inj: Injection) => {
1983
+ const { mode, parent, key, keyI } = inj
2197
1984
 
2198
1985
  // Only operate in val mode, since parent is a list.
2199
1986
  if (M_VAL === mode) {
2200
1987
  if (!islist(parent) || 0 !== keyI) {
2201
1988
  inj.errs.push(
2202
- 'The $ONE validator at field ' +
1989
+ 'The $EXACT validator at field ' +
2203
1990
  pathify(inj.path, 1, 1) +
2204
1991
  ' must be the first element of an array.',
2205
1992
  )
2206
1993
  return
2207
1994
  }
2208
1995
 
1996
+ const cval = _slotval(inj)
1997
+
2209
1998
  inj.keyI = size(inj.keys)
2210
1999
 
2211
- // Clean up structure, replacing [$ONE, ...] with current
2212
- inj.setval(inj.dparent, 2)
2000
+ // Replace [$EXACT, ...] with the data value; SKIP keeps inject off the detached list.
2001
+ inj.setval(cval, 2)
2213
2002
 
2214
- inj.path = slice(inj.path, -1)
2215
- inj.key = getelem(inj.path, -1)
2003
+ inj.path = slice(inj.path, 0, -1)
2216
2004
 
2217
2005
  const tvals = slice(parent, 1)
2218
2006
  if (0 === size(tvals)) {
2219
2007
  inj.errs.push(
2220
- 'The $ONE validator at field ' +
2008
+ 'The $EXACT validator at field ' +
2221
2009
  pathify(inj.path, 1, 1) +
2222
2010
  ' must have at least one argument.',
2223
2011
  )
2224
- return
2012
+ return SKIP
2225
2013
  }
2226
2014
 
2227
- // See if we can find a match.
2228
2015
  for (const tval of tvals) {
2229
- // If match, then errs.length = 0
2230
- const terrs: any[] = []
2231
-
2232
- const vstore = merge([{}, store], 1)
2233
- vstore.$TOP = inj.dparent
2234
-
2235
- const vcurrent = validate(inj.dparent, tval, {
2236
- extra: vstore,
2237
- errs: terrs,
2238
- meta: inj.meta,
2239
- })
2240
-
2241
- inj.setval(vcurrent, -2)
2242
-
2243
- // Accept current value if there was a match
2244
- if (0 === size(terrs)) {
2245
- return
2016
+ if (_deepequal(tval, cval)) {
2017
+ return SKIP
2246
2018
  }
2247
2019
  }
2248
2020
 
2249
- // There was no match.
2250
2021
  const valdesc = replace(
2251
2022
  join(
2252
2023
  items(tvals, (n) => stringify(n[1])),
@@ -2259,65 +2030,94 @@ const validate_ONE: Injector = (inj: Injection, _val: any, _ref: string, store:
2259
2030
  inj.errs.push(
2260
2031
  _invalidTypeMsg(
2261
2032
  inj.path,
2262
- (1 < size(tvals) ? 'one of ' : '') + valdesc,
2263
- typify(inj.dparent),
2264
- inj.dparent,
2265
- 'V0210',
2033
+ (1 < size(inj.path) ? '' : 'value ') +
2034
+ 'exactly equal to ' +
2035
+ (1 === size(tvals) ? '' : 'one of ') +
2036
+ valdesc,
2037
+ typify(cval),
2038
+ cval,
2039
+ 'V0110',
2266
2040
  ),
2267
2041
  )
2042
+
2043
+ return SKIP
2044
+ } else {
2045
+ delprop(parent, key)
2268
2046
  }
2269
2047
  }
2270
2048
 
2271
- const validate_EXACT: Injector = (inj: Injection) => {
2272
- const { mode, parent, key, keyI } = inj
2049
+ // Count the specs that admit the value: ['`$NOF`', count, spec, ...], where
2050
+ // count is an integer, or a map holding min, max or both.
2051
+ const validate_NOF: Injector = (inj: Injection, _val: any, _ref: string, store: any) =>
2052
+ _validatecount(inj, store, '$NOF', true)
2273
2053
 
2274
- // Only operate in val mode, since parent is a list.
2275
- if (M_VAL === mode) {
2276
- if (!islist(parent) || 0 !== keyI) {
2277
- inj.errs.push(
2278
- 'The $EXACT validator at field ' +
2279
- pathify(inj.path, 1, 1) +
2280
- ' must be the first element of an array.',
2281
- )
2282
- return
2283
- }
2054
+ // Every spec admits the value: ['`$ALL`', spec, ...].
2055
+ const validate_ALL: Injector = (inj: Injection, _val: any, _ref: string, store: any) =>
2056
+ _validatecount(inj, store, '$ALL', false)
2284
2057
 
2285
- inj.keyI = size(inj.keys)
2058
+ // The counting list directives. Without a count, every spec has to admit.
2059
+ function _validatecount(inj: Injection, store: any, name: string, counted: boolean): any {
2060
+ const { mode, parent, keyI } = inj
2286
2061
 
2287
- // Clean up structure, replacing [$EXACT, ...] with current data parent
2288
- inj.setval(inj.dparent, 2)
2062
+ if (M_VAL !== mode) {
2063
+ return NONE
2064
+ }
2289
2065
 
2290
- // inj.path = slice(inj.path, 0, size(inj.path) - 1)
2291
- inj.path = slice(inj.path, 0, -1)
2292
- inj.key = getelem(inj.path, -1)
2066
+ if (!islist(parent) || 0 !== keyI) {
2067
+ inj.errs.push(
2068
+ 'The ' +
2069
+ name +
2070
+ ' validator at field ' +
2071
+ pathify(inj.path, 1, 1) +
2072
+ ' must be the first element of an array.',
2073
+ )
2074
+ return NONE
2075
+ }
2293
2076
 
2294
- const tvals = slice(parent, 1)
2295
- if (0 === size(tvals)) {
2296
- inj.errs.push(
2297
- 'The $EXACT validator at field ' +
2298
- pathify(inj.path, 1, 1) +
2299
- ' must have at least one argument.',
2300
- )
2301
- return
2302
- }
2077
+ const cval = _slotval(inj)
2303
2078
 
2304
- // See if we can find an exact value match.
2305
- let currentstr: string | undefined = undefined
2306
- for (const tval of tvals) {
2307
- let exactmatch = tval === inj.dparent
2079
+ inj.keyI = size(inj.keys)
2308
2080
 
2309
- if (!exactmatch && isnode(tval)) {
2310
- currentstr = undefined === currentstr ? stringify(inj.dparent) : currentstr
2311
- const tvalstr = stringify(tval)
2312
- exactmatch = tvalstr === currentstr
2313
- }
2081
+ // Replace the directive's list with the data value. Each return is SKIP, so
2082
+ // that inject leaves the detached list alone and validates nothing in it.
2083
+ inj.setval(cval, 2)
2314
2084
 
2315
- if (exactmatch) {
2316
- return
2317
- }
2085
+ inj.path = slice(inj.path, -1)
2086
+
2087
+ const count = counted ? _lookup(parent, 1) : NONE
2088
+ const tvals = slice(parent, counted ? 2 : 1)
2089
+ const numtvals = size(tvals)
2090
+ const field = 'The ' + name + ' validator at field ' + pathify(inj.path, 1)
2091
+
2092
+ if (0 === numtvals) {
2093
+ inj.errs.push(
2094
+ field + (counted ? ' must have a count and' : ' must have') + ' at least one argument.',
2095
+ )
2096
+ return SKIP
2097
+ }
2098
+
2099
+ const [lo, hi, countdesc] = counted ? _nofcount(count, numtvals) : [numtvals, numtvals, 'all']
2100
+
2101
+ if (NONE === countdesc) {
2102
+ inj.errs.push(field + ' has an invalid count: ' + stringify(count) + '.')
2103
+ return SKIP
2104
+ }
2105
+
2106
+ let admitted = 0
2107
+ for (let tI = 0; tI < numtvals; tI++) {
2108
+ const left = numtvals - tI
2109
+
2110
+ // Stop once the specs left cannot change the verdict.
2111
+ if (hi < admitted || admitted + left < lo || (lo <= admitted && admitted + left <= hi)) {
2112
+ break
2318
2113
  }
2319
2114
 
2320
- // There was no match.
2115
+ if (_admits(cval, tvals[tI], inj, store)) {
2116
+ admitted++
2117
+ }
2118
+ }
2119
+
2120
+ if (admitted < lo || hi < admitted) {
2321
2121
  const valdesc = replace(
2322
2122
  join(
2323
2123
  items(tvals, (n) => stringify(n[1])),
@@ -2328,20 +2128,200 @@ const validate_EXACT: Injector = (inj: Injection) => {
2328
2128
  )
2329
2129
 
2330
2130
  inj.errs.push(
2331
- _invalidTypeMsg(
2332
- inj.path,
2333
- (1 < size(inj.path) ? '' : 'value ') +
2334
- 'exactly equal to ' +
2335
- (1 === size(tvals) ? '' : 'one of ') +
2336
- valdesc,
2337
- typify(inj.dparent),
2338
- inj.dparent,
2339
- 'V0110',
2340
- ),
2131
+ _invalidTypeMsg(inj.path, countdesc + ' of ' + valdesc, typify(cval), cval, 'V0310'),
2341
2132
  )
2342
- } else {
2343
- delprop(parent, key)
2344
2133
  }
2134
+
2135
+ return SKIP
2136
+ }
2137
+
2138
+ // The value's length is within a bound: ['`$LEN`', bound, spec?], where the
2139
+ // bound is as for a $NOF count. A string's length is in code points.
2140
+ const validate_LEN: Injector = (inj: Injection, _val: any, _ref: string, store: any) =>
2141
+ _validatebound(inj, store, '$LEN')
2142
+
2143
+ // The value is a number within a bound: ['`$RANGE`', bound, spec?], where the
2144
+ // bound holds min or gt, max or lt, or one of each.
2145
+ const validate_RANGE: Injector = (inj: Injection, _val: any, _ref: string, store: any) =>
2146
+ _validatebound(inj, store, '$RANGE')
2147
+
2148
+ const validate_LIKE: Injector = (inj: Injection, _val: any, _ref: string, store: any) =>
2149
+ _validatebound(inj, store, '$LIKE')
2150
+
2151
+ // The bounding list directives: a bound or pattern, then at most one spec that also admits.
2152
+ function _validatebound(inj: Injection, store: any, name: string): any {
2153
+ const { mode, parent, keyI } = inj
2154
+
2155
+ if (M_VAL !== mode) {
2156
+ return NONE
2157
+ }
2158
+
2159
+ if (!islist(parent) || 0 !== keyI) {
2160
+ inj.errs.push(
2161
+ 'The ' +
2162
+ name +
2163
+ ' validator at field ' +
2164
+ pathify(inj.path, 1, 1) +
2165
+ ' must be the first element of an array.',
2166
+ )
2167
+ return NONE
2168
+ }
2169
+
2170
+ const cval = _slotval(inj)
2171
+
2172
+ inj.keyI = size(inj.keys)
2173
+
2174
+ // As for the counting directives: SKIP keeps inject off the detached list.
2175
+ inj.setval(cval, 2)
2176
+
2177
+ inj.path = slice(inj.path, -1)
2178
+
2179
+ const field = 'The ' + name + ' validator at field ' + pathify(inj.path, 1)
2180
+ const nargs = size(parent) - 1
2181
+ const islen = '$LEN' === name
2182
+ const islike = '$LIKE' === name
2183
+ const argname = islike ? 'pattern' : 'bound'
2184
+
2185
+ if (nargs < 1 || 2 < nargs) {
2186
+ inj.errs.push(field + ' must have a ' + argname + ' and at most one spec.')
2187
+ return SKIP
2188
+ }
2189
+
2190
+ const bound = _lookup(parent, 1)
2191
+ const like = islike ? _likere(bound) : NONE
2192
+ const [lo, hi, desc] = islen
2193
+ ? _lenbound(bound)
2194
+ : [0, 0, islike ? (NONE === like ? NONE : 'like /' + bound + '/') : _rangedesc(bound)]
2195
+
2196
+ if (NONE === desc) {
2197
+ inj.errs.push(field + ' has an invalid ' + argname + ': ' + stringify(bound) + '.')
2198
+ return SKIP
2199
+ }
2200
+
2201
+ const ctype = typify(cval)
2202
+
2203
+ if (2 === nargs && !_admits(cval, _lookup(parent, 2), inj, store)) {
2204
+ const specdesc = replace(
2205
+ stringify(_lookup(parent, 2)),
2206
+ R_TRANSFORM_NAME,
2207
+ (_m: any, p1: string) => p1.toLowerCase(),
2208
+ )
2209
+ inj.errs.push(_invalidTypeMsg(inj.path, specdesc, ctype, cval, 'V0410'))
2210
+ return SKIP
2211
+ }
2212
+
2213
+ if (0 === ((islen ? T_string | T_list | T_map : islike ? T_string : T_number) & ctype)) {
2214
+ const needtype = islen ? 'string, list or map' : islike ? S_string : S_number
2215
+ inj.errs.push(_invalidTypeMsg(inj.path, needtype, ctype, cval, 'V0420'))
2216
+ return SKIP
2217
+ }
2218
+
2219
+ const len = islen
2220
+ ? S_string === typeof cval
2221
+ ? Array.from(cval as string).length
2222
+ : size(cval)
2223
+ : 0
2224
+ const inbound = islen
2225
+ ? lo <= len && (-1 === hi || len <= hi)
2226
+ : islike
2227
+ ? re_test(like as RegExp, cval)
2228
+ : _inrange(bound, cval)
2229
+
2230
+ if (!inbound) {
2231
+ const needtype = (1 < size(inj.path) ? '' : 'value ') + desc
2232
+ inj.errs.push(_invalidTypeMsg(inj.path, needtype, ctype, cval, 'V0430'))
2233
+ }
2234
+
2235
+ return SKIP
2236
+ }
2237
+
2238
+ // The bounds of a $LEN bound, with -1 for no maximum, and the words for it,
2239
+ // which are absent when the bound is invalid.
2240
+ function _lenbound(bound: any): [number, number, string | undefined] {
2241
+ const [lo, hi, countdesc] = _nofcount(bound, -1)
2242
+
2243
+ if (NONE === countdesc) {
2244
+ return [0, 0, NONE]
2245
+ }
2246
+
2247
+ const desc =
2248
+ 'of length ' +
2249
+ (lo === hi ? lo : -1 === hi ? 'at least ' + lo : 0 === lo ? 'at most ' + hi : lo + ' to ' + hi)
2250
+
2251
+ return [lo, hi, desc]
2252
+ }
2253
+
2254
+ // A $LIKE pattern compiled by the port's own regex engine; absent unless it compiles.
2255
+ function _likere(pattern: any): RegExp | undefined {
2256
+ if (S_string !== typeof pattern) {
2257
+ return NONE
2258
+ }
2259
+ try {
2260
+ return re_compile(pattern)
2261
+ } catch {
2262
+ return NONE
2263
+ }
2264
+ }
2265
+
2266
+ // The words for a $RANGE bound, which are absent when the bound is invalid.
2267
+ function _rangedesc(bound: any): string | undefined {
2268
+ if (!ismap(bound)) {
2269
+ return NONE
2270
+ }
2271
+
2272
+ const min = _lookup(bound, 'min')
2273
+ const max = _lookup(bound, 'max')
2274
+ const gt = _lookup(bound, 'gt')
2275
+ const lt = _lookup(bound, 'lt')
2276
+ const lower = NONE === min ? gt : min
2277
+ const upper = NONE === max ? lt : max
2278
+ const isnum = (n: any) => NONE === n || 0 < (T_number & typify(n))
2279
+
2280
+ const valid =
2281
+ 0 < size(bound) &&
2282
+ size(bound) === [min, max, gt, lt].filter((n) => NONE !== n).length &&
2283
+ (NONE === min || NONE === gt) &&
2284
+ (NONE === max || NONE === lt) &&
2285
+ isnum(min) &&
2286
+ isnum(max) &&
2287
+ isnum(gt) &&
2288
+ isnum(lt) &&
2289
+ (NONE === lower || NONE === upper || lower <= upper)
2290
+
2291
+ if (!valid) {
2292
+ return NONE
2293
+ }
2294
+
2295
+ return join(
2296
+ [
2297
+ NONE !== min
2298
+ ? 'at least ' + stringify(min)
2299
+ : NONE !== gt
2300
+ ? 'greater than ' + stringify(gt)
2301
+ : NONE,
2302
+ NONE !== max
2303
+ ? 'at most ' + stringify(max)
2304
+ : NONE !== lt
2305
+ ? 'less than ' + stringify(lt)
2306
+ : NONE,
2307
+ ],
2308
+ ' and ',
2309
+ )
2310
+ }
2311
+
2312
+ // A number within a valid $RANGE bound.
2313
+ function _inrange(bound: any, val: number): boolean {
2314
+ const min = _lookup(bound, 'min')
2315
+ const max = _lookup(bound, 'max')
2316
+ const gt = _lookup(bound, 'gt')
2317
+ const lt = _lookup(bound, 'lt')
2318
+
2319
+ return (
2320
+ (NONE === min || min <= val) &&
2321
+ (NONE === max || val <= max) &&
2322
+ (NONE === gt || gt < val) &&
2323
+ (NONE === lt || val < lt)
2324
+ )
2345
2325
  }
2346
2326
 
2347
2327
  // This is the "modify" argument to inject. Use this to perform
@@ -2355,10 +2335,8 @@ const _validation: Modify = (pval: any, key?: any, parent?: any, inj?: Injection
2355
2335
  return
2356
2336
  }
2357
2337
 
2358
- // select needs exact matches
2359
2338
  const exact = getprop(inj.meta, S_BEXACT, false)
2360
2339
 
2361
- // Current val to verify.
2362
2340
  const cval = getprop(inj.dparent, key)
2363
2341
 
2364
2342
  if (NONE === inj || (!exact && NONE === cval)) {
@@ -2374,7 +2352,6 @@ const _validation: Modify = (pval: any, key?: any, parent?: any, inj?: Injection
2374
2352
 
2375
2353
  const ctype = typify(cval)
2376
2354
 
2377
- // Type mismatch.
2378
2355
  if (ptype !== ctype && NONE !== pval) {
2379
2356
  inj.errs.push(_invalidTypeMsg(inj.path, typename(ptype), ctype, cval, 'V0010'))
2380
2357
  return
@@ -2430,16 +2407,6 @@ const _validation: Modify = (pval: any, key?: any, parent?: any, inj?: Injection
2430
2407
  return
2431
2408
  }
2432
2409
 
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
2410
  function validate(
2444
2411
  data: any, // Source data to transform into new data (original not mutated)
2445
2412
  spec: any, // Transform specification; output follows this shape
@@ -2453,7 +2420,6 @@ function validate(
2453
2420
  const store = merge(
2454
2421
  [
2455
2422
  {
2456
- // Remove the transform commands.
2457
2423
  $DELETE: null,
2458
2424
  $COPY: null,
2459
2425
  $KEY: null,
@@ -2475,8 +2441,12 @@ function validate(
2475
2441
  $INSTANCE: validate_TYPE,
2476
2442
  $ANY: validate_ANY,
2477
2443
  $CHILD: validate_CHILD,
2478
- $ONE: validate_ONE,
2479
2444
  $EXACT: validate_EXACT,
2445
+ $NOF: validate_NOF,
2446
+ $ALL: validate_ALL,
2447
+ $LEN: validate_LEN,
2448
+ $RANGE: validate_RANGE,
2449
+ $LIKE: validate_LIKE,
2480
2450
  },
2481
2451
 
2482
2452
  getdef(extra, {}),
@@ -2493,13 +2463,20 @@ function validate(
2493
2463
  const meta = getprop(injdef, 'meta', {})
2494
2464
  setprop(meta, S_BEXACT, getprop(meta, S_BEXACT, false))
2495
2465
 
2496
- const out = transform(data, spec, {
2497
- meta,
2498
- extra: store,
2499
- modify: _validation,
2500
- handler: _validatehandler,
2501
- errs,
2502
- })
2466
+ // A spec that names an unknown checker validates nothing.
2467
+ const numerrs = size(errs)
2468
+ _checknames(spec, store, [], errs)
2469
+
2470
+ const out =
2471
+ numerrs < size(errs)
2472
+ ? clone(data)
2473
+ : transform(data, spec, {
2474
+ meta,
2475
+ extra: store,
2476
+ modify: _validation,
2477
+ handler: _validatehandler,
2478
+ errs,
2479
+ })
2503
2480
 
2504
2481
  const generr = 0 < size(errs) && !collect
2505
2482
  if (generr) {
@@ -2602,13 +2579,15 @@ const select_NOT: Injector = (inj: Injection, _val: any, _ref: string, store: an
2602
2579
  }
2603
2580
 
2604
2581
  const select_CMP: Injector = (inj: Injection, _val: any, ref: string, store: any) => {
2582
+ // The list form of $LIKE is validate's checker; the key form is this operator.
2583
+ if (M_VAL === inj.mode && '$LIKE' === ref) {
2584
+ return validate_LIKE(inj, _val, ref, store)
2585
+ }
2586
+
2605
2587
  if (M_KEYPRE === inj.mode) {
2606
2588
  const term = _lookup(inj.parent, inj.key)
2607
- // const src = getprop(store, inj.base, store)
2608
2589
  const gkey = getelem(inj.path, -2)
2609
2590
 
2610
- // const tval = getprop(src, gkey)
2611
-
2612
2591
  const ppath = slice(inj.path, -1)
2613
2592
  const point = getpath(store, ppath)
2614
2593
 
@@ -2647,10 +2626,6 @@ const select_CMP: Injector = (inj: Injection, _val: any, ref: string, store: any
2647
2626
  return NONE
2648
2627
  }
2649
2628
 
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
2629
  function select(children: any, query: any): any[] {
2655
2630
  if (!isnode(children)) {
2656
2631
  return []
@@ -2683,12 +2658,7 @@ function select(children: any, query: any): any[] {
2683
2658
 
2684
2659
  const q = clone(query)
2685
2660
 
2686
- walk(q, (_k: PropKey | undefined, v: any) => {
2687
- if (ismap(v)) {
2688
- setprop(v, '`$OPEN`', getprop(v, '`$OPEN`', true))
2689
- }
2690
- return v
2691
- })
2661
+ _openquery(q)
2692
2662
 
2693
2663
  for (const child of children) {
2694
2664
  injdef.errs = []
@@ -2703,25 +2673,46 @@ function select(children: any, query: any): any[] {
2703
2673
  return results
2704
2674
  }
2705
2675
 
2676
+ // Open every map in a select query, so a child may hold keys the query does
2677
+ // not name, but leave a directive's literals as written: what $EXACT
2678
+ // compares, and the count or bound of $NOF, $LEN and $RANGE.
2679
+ function _openquery(q: any): void {
2680
+ if (ismap(q)) {
2681
+ setprop(q, '`$OPEN`', getprop(q, '`$OPEN`', true))
2682
+ for (const key of keysof(q)) {
2683
+ _openquery(q[key])
2684
+ }
2685
+ } else if (islist(q)) {
2686
+ const head = q[0]
2687
+ const exact = '`$EXACT`' === head
2688
+ const bounded = '`$NOF`' === head || '`$LEN`' === head || '`$RANGE`' === head
2689
+ for (let i = 0; i < size(q); i++) {
2690
+ if (0 === i || !(exact || (bounded && 1 === i))) {
2691
+ _openquery(q[i])
2692
+ }
2693
+ }
2694
+ }
2695
+ }
2696
+
2706
2697
  // Injection state used for recursive injection into JSON - like data structures.
2707
2698
  class Injection {
2708
2699
  mode: InjectMode // Injection mode: M_KEYPRE, M_VAL, M_KEYPOST.
2709
2700
  full: boolean // Transform escape was full key name.
2710
2701
  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.
2702
+ keys: string[]
2703
+ key: string
2704
+ val: any
2714
2705
  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.
2706
+ path: string[]
2707
+ nodes: any[]
2708
+ handler: Injector
2709
+ errs: any[]
2719
2710
  meta: Record<string, any> // Custom meta data. NOTE: do not merge, values must remain as-is.
2720
2711
  dparent: any // Current data parent node (contains current data value).
2721
- dpath: string[] // Current data value path
2712
+ dpath: string[]
2722
2713
  base?: string // Base key for data in store, if any.
2723
- modify?: Modify // Modify injection output.
2724
- prior?: Injection // Parent (aka prior) injection.
2714
+ modify?: Modify
2715
+ prior?: Injection
2725
2716
  extra?: any
2726
2717
 
2727
2718
  constructor(val: any, parent: any) {
@@ -2799,7 +2790,6 @@ class Injection {
2799
2790
  }
2800
2791
  }
2801
2792
 
2802
- // TODO: is this needed?
2803
2793
  return this.dparent
2804
2794
  }
2805
2795
 
@@ -2842,7 +2832,6 @@ class Injection {
2842
2832
  parent = NONE === val ? delprop(aval, akey) : setprop(aval, akey, val)
2843
2833
  }
2844
2834
 
2845
- // console.log('SETVAL', val, this.key, this.parent)
2846
2835
  return parent
2847
2836
  }
2848
2837
  }
@@ -2850,12 +2839,6 @@ class Injection {
2850
2839
  // Internal utilities
2851
2840
  // ==================
2852
2841
 
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
2842
  // Build a type validation error message.
2860
2843
  function _invalidTypeMsg(path: any, needtype: string, vt: number, v: any, _whence?: string) {
2861
2844
  const vs = null == v ? 'no value' : stringify(v)
@@ -2874,15 +2857,173 @@ function _invalidTypeMsg(path: any, needtype: string, vt: number, v: any, _whenc
2874
2857
  )
2875
2858
  }
2876
2859
 
2860
+ // Names a validate spec may use besides its checkers: transform's that it keeps, and $OPEN.
2861
+ const VALIDATE_NAMES = [
2862
+ '$TOP',
2863
+ '$SPEC',
2864
+ '$BT',
2865
+ '$DS',
2866
+ '$WHEN',
2867
+ '$ANNO',
2868
+ '$REF',
2869
+ '$FORMAT',
2870
+ '$APPLY',
2871
+ '$OPEN',
2872
+ ]
2873
+
2874
+ // Report each checker the spec names that validate lacks; $EXACT's arguments are literals.
2875
+ function _checknames(spec: any, store: any, path: string[], errs: any[]): void {
2876
+ const name = _refname(spec)
2877
+ if (NONE !== name) {
2878
+ if (_unknownname(name, store)) {
2879
+ errs.push('Unknown validator ' + name + ' at field ' + pathify(path) + '.')
2880
+ }
2881
+ return
2882
+ }
2883
+
2884
+ if (islist(spec) && '$EXACT' === _refname(spec[0])) {
2885
+ return
2886
+ }
2887
+
2888
+ for (const key of keysof(spec)) {
2889
+ if (ismap(spec)) {
2890
+ _checknames(key, store, path, errs)
2891
+ }
2892
+ _checknames(spec[key], store, flatten([path, key]), errs)
2893
+ }
2894
+ }
2895
+
2896
+ // The name a whole-string reference gives, when it is a checker name in any case.
2897
+ function _refname(val: any): string | undefined {
2898
+ const m = S_string === typeof val ? re_find(R_INJECTION_FULL, val) : null
2899
+ return null != m && re_test(R_CHECKER_NAME, m[1].toUpperCase()) ? m[1] : NONE
2900
+ }
2901
+
2902
+ // Unknown: undefined and upper case, or a defined name in another case. Null disables a name.
2903
+ function _unknownname(name: string, store: any): boolean {
2904
+ const known = (n: string) => VALIDATE_NAMES.includes(n) || null != _lookup(store, n)
2905
+ const upper = name.toUpperCase()
2906
+ return !known(name) && (upper === name || known(upper))
2907
+ }
2908
+
2909
+ // The data value at a list directive's slot. The directive's own dparent was
2910
+ // read with getprop, which reports a stored null as absent.
2911
+ function _slotval(inj: Injection): any {
2912
+ const prior = inj.prior
2913
+ return NONE === prior ? inj.dparent : _lookup(prior.dparent, prior.key)
2914
+ }
2915
+
2916
+ // JSON equality: numbers by value, lists in order, maps by key in any order.
2917
+ function _deepequal(a: any, b: any): boolean {
2918
+ if (a === b) {
2919
+ return true
2920
+ }
2921
+
2922
+ const atype = typify(a)
2923
+ if (atype !== typify(b) || 0 === ((T_list | T_map) & atype)) {
2924
+ return false
2925
+ }
2926
+
2927
+ const akeys = keysof(a)
2928
+ const bkeys = keysof(b)
2929
+ if (size(akeys) !== size(bkeys)) {
2930
+ return false
2931
+ }
2932
+
2933
+ for (let kI = 0; kI < size(akeys); kI++) {
2934
+ const k = akeys[kI]
2935
+ if (k !== bkeys[kI] || !_deepequal(a[k], b[k])) {
2936
+ return false
2937
+ }
2938
+ }
2939
+
2940
+ return true
2941
+ }
2942
+
2943
+ // Every member val has is in out, unchanged. A member only out has is a
2944
+ // default the spec supplied, and is ignored.
2945
+ function _keeps(val: any, out: any): boolean {
2946
+ if (NONE === val) {
2947
+ return true
2948
+ }
2949
+
2950
+ if (0 === ((T_list | T_map) & typify(val)) || islist(val) !== islist(out) || !isnode(out)) {
2951
+ return _deepequal(val, out)
2952
+ }
2953
+
2954
+ for (const k of keysof(val)) {
2955
+ if (!_keeps(val[k], _lookup(out, k))) {
2956
+ return false
2957
+ }
2958
+ }
2959
+
2960
+ return true
2961
+ }
2962
+
2963
+ // A spec admits a value when validating the value against it finds no error
2964
+ // and gives back the value as it is.
2965
+ function _admits(val: any, spec: any, inj: Injection, store: any): boolean {
2966
+ const terrs: any[] = []
2967
+
2968
+ const vstore = merge([{}, store], 1)
2969
+ vstore.$TOP = val
2970
+
2971
+ const out = validate(val, spec, {
2972
+ extra: vstore,
2973
+ errs: terrs,
2974
+ meta: inj.meta,
2975
+ })
2976
+
2977
+ return 0 === size(terrs) && _keeps(val, out)
2978
+ }
2979
+
2980
+ // The bounds of a $NOF count, and the words for it, which are absent when
2981
+ // the count is invalid. Without a max, the bound is the number of specs.
2982
+ function _nofcount(count: any, numtvals: number): [number, number, string | undefined] {
2983
+ const isnat = (n: any) => 0 < (T_integer & typify(n)) && 0 <= n
2984
+
2985
+ if (isnat(count)) {
2986
+ return [count, count, 0 === count ? 'none' : 'exactly ' + count]
2987
+ }
2988
+
2989
+ const min = _lookup(count, 'min')
2990
+ const max = _lookup(count, 'max')
2991
+
2992
+ const valid =
2993
+ ismap(count) &&
2994
+ 0 < size(count) &&
2995
+ size(count) === (NONE === min ? 0 : 1) + (NONE === max ? 0 : 1) &&
2996
+ (NONE === min || isnat(min)) &&
2997
+ (NONE === max || isnat(max)) &&
2998
+ (NONE === min || NONE === max || min <= max)
2999
+
3000
+ if (!valid) {
3001
+ return [0, 0, NONE]
3002
+ }
3003
+
3004
+ const lo = NONE === min ? 0 : min
3005
+ const hi = NONE === max ? numtvals : max
3006
+
3007
+ const desc =
3008
+ NONE === max
3009
+ ? 'at least ' + lo
3010
+ : 0 === hi
3011
+ ? 'none'
3012
+ : NONE === min
3013
+ ? 'at most ' + hi
3014
+ : lo === hi
3015
+ ? 'exactly ' + lo
3016
+ : lo + ' to ' + hi
3017
+
3018
+ return [lo, hi, desc]
3019
+ }
3020
+
2877
3021
  // Default inject handler for transforms. If the path resolves to a function,
2878
3022
  // call the function passing the injection inj. This is how transforms operate.
2879
3023
  const _injecthandler: Injector = (inj: Injection, val: any, ref: string, store: any): any => {
2880
3024
  let out = val
2881
3025
  const iscmd = isfunc(val) && (NONE === ref || ref.startsWith(S_DS))
2882
3026
 
2883
- // Only call val function if it is a special command ($NAME format).
2884
- // TODO: OR if meta.'$CALL'
2885
-
2886
3027
  if (iscmd) {
2887
3028
  out = (val as Injector)(inj, val, ref, store)
2888
3029
  }
@@ -2917,24 +3058,13 @@ const _validatehandler: Injector = (inj: Injection, val: any, ref: string, store
2917
3058
  return out
2918
3059
  }
2919
3060
 
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
3061
  function _injectstr(val: string, store: any, inj?: Injection): any {
2930
- // Can't inject into non-strings
2931
3062
  if (S_string !== typeof val || S_MT === val) {
2932
3063
  return S_MT
2933
3064
  }
2934
3065
 
2935
3066
  let out: any = val
2936
3067
 
2937
- // Pattern examples: "`a.b.c`", "`$NAME`", "`$NAME1`"
2938
3068
  const m = re_find(R_INJECTION_FULL, val)
2939
3069
 
2940
3070
  // Full string of the val is an injection.
@@ -2944,18 +3074,14 @@ function _injectstr(val: string, store: any, inj?: Injection): any {
2944
3074
  }
2945
3075
  let pathref = m[1]
2946
3076
 
2947
- // Special escapes inside injection.
2948
3077
  if (3 < size(pathref)) {
2949
3078
  pathref = re_replace(R_DS_ESCAPE, re_replace(R_BT_ESCAPE, pathref, S_BT), S_DS)
2950
3079
  }
2951
3080
 
2952
- // Get the extracted path reference.
2953
3081
  out = getpath(store, pathref, inj)
2954
3082
  } else {
2955
3083
  // Check for injections within the string.
2956
3084
  const partial = (_m: string, ref: string) => {
2957
- // Special escapes inside injection.
2958
-
2959
3085
  if (3 < size(ref)) {
2960
3086
  ref = re_replace(R_DS_ESCAPE, re_replace(R_BT_ESCAPE, ref, S_BT), S_DS)
2961
3087
  }
@@ -2966,7 +3092,6 @@ function _injectstr(val: string, store: any, inj?: Injection): any {
2966
3092
 
2967
3093
  const found = getpath(store, ref, inj)
2968
3094
 
2969
- // Ensure inject value is a string.
2970
3095
  return NONE === found ? S_MT : S_string === typeof found ? found : JSON.stringify(found)
2971
3096
  }
2972
3097
 
@@ -3040,13 +3165,11 @@ function checkPlacement(
3040
3165
  return true
3041
3166
  }
3042
3167
 
3043
- // function injectorArgs(argTypes: number[], inj: Injection): any {
3044
3168
  function injectorArgs(argTypes: number[], args: any[]): any {
3045
3169
  const numargs = size(argTypes)
3046
3170
  const found = new Array(1 + numargs)
3047
3171
  found[0] = NONE
3048
3172
  for (let argI = 0; argI < numargs; argI++) {
3049
- // const arg = inj.parent[1 + argI]
3050
3173
  const arg = args[argI]
3051
3174
  const argType = typify(arg)
3052
3175
  if (0 === (argTypes[argI] & argType)) {
@@ -3083,7 +3206,6 @@ function injectChild(child: any, store: any, inj: Injection): Injection {
3083
3206
  }
3084
3207
  }
3085
3208
 
3086
- // console.log('FORMAT-INJECT-CHILD', child)
3087
3209
  inject(child, store, cinj)
3088
3210
 
3089
3211
  return cinj
@@ -3167,57 +3289,6 @@ class StructUtility {
3167
3289
  injectChild = injectChild
3168
3290
  }
3169
3291
 
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
3292
  const CONDENSE_VERSION = 1
3222
3293
 
3223
3294
  const CONDENSE_MAP = 0
@@ -3233,18 +3304,6 @@ const S_condsym = 'sym'
3233
3304
  const S_condnode = 'node'
3234
3305
  const S_condroot = 'root'
3235
3306
 
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
3307
  function condenseCmp(a: string, b: string): number {
3249
3308
  let i = 0
3250
3309
  let j = 0
@@ -3260,25 +3319,6 @@ function condenseCmp(a: string, b: string): number {
3260
3319
  return a.length - i - (b.length - j)
3261
3320
  }
3262
3321
 
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
- function condenseSet(obj: any, key: string, val: any) {
3270
- if ('__proto__' === key) {
3271
- Object.defineProperty(obj, key, {
3272
- value: val,
3273
- enumerable: true,
3274
- writable: true,
3275
- configurable: true,
3276
- })
3277
- } else {
3278
- obj[key] = val
3279
- }
3280
- }
3281
-
3282
3322
  function iscondensed(val: any): boolean {
3283
3323
  // The version must MATCH, not merely be numeric: a future profile would
3284
3324
  // otherwise be decoded under this one's schema.
@@ -3343,8 +3383,8 @@ function condense(val: any): any {
3343
3383
  const build = (n: any): number => {
3344
3384
  if (ismap(n)) {
3345
3385
  const enc: any[] = [CONDENSE_MAP]
3346
- // keysof sorts, so the key ids ascend and lookup can bisect.
3347
- const keys = keysof(n)
3386
+ // Code-point order, not keysof's code-unit order, so the key ids ascend for bisection.
3387
+ const keys = keysof(n).sort(condenseCmp)
3348
3388
  for (let i = 0; i < keys.length; i++) {
3349
3389
  enc.push(symid[keys[i]])
3350
3390
  enc.push(build((n as any)[keys[i]]))
@@ -3407,7 +3447,7 @@ function condenseSymId(cond: any, key: string): number {
3407
3447
  // The node index of `key` inside node `idx`, or -1. Touches only this node.
3408
3448
  function condenseChild(cond: any, idx: number, key: any): number {
3409
3449
  const enc = (cond as any)[S_condnode][idx]
3410
- if (null == enc) {
3450
+ if (null == enc || (S_string !== typeof key && S_number !== typeof key)) {
3411
3451
  return -1
3412
3452
  }
3413
3453
 
@@ -3477,13 +3517,6 @@ function condenseResolve(cond: any, idx: number, path: any): number {
3477
3517
  return at
3478
3518
  }
3479
3519
 
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
3520
  function condenseMaterialise(cond: any, idx: number): any {
3488
3521
  const sym = (cond as any)[S_condsym]
3489
3522
  const node = (cond as any)[S_condnode]
@@ -3497,7 +3530,7 @@ function condenseMaterialise(cond: any, idx: number): any {
3497
3530
  if (CONDENSE_MAP === kind) {
3498
3531
  const out: any = {}
3499
3532
  for (let j = 1; j < enc.length; j += 2) {
3500
- condenseSet(out, sym[enc[j]], rebuild(enc[j + 1]))
3533
+ _setown(out, sym[enc[j]], rebuild(enc[j + 1]))
3501
3534
  }
3502
3535
  return out
3503
3536
  }