@voxgig/struct 0.0.1

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.
package/src/struct.ts ADDED
@@ -0,0 +1,1983 @@
1
+ /* Copyright (c) 2025 Voxgig Ltd. MIT LICENSE. */
2
+
3
+ /* Voxgig Struct
4
+ * =============
5
+ *
6
+ * Utility functions to manipulate in-memory JSON-like data
7
+ * structures. These structures assumed to be composed of nested
8
+ * "nodes", where a node is a list or map, and has named or indexed
9
+ * fields. The general design principle is "by-example". Transform
10
+ * specifications mirror the desired output. This implementation is
11
+ * designed for porting to multiple language, and to be tolerant of
12
+ * undefined values.
13
+ *
14
+ * Main utilities
15
+ * - getpath: get the value at a key path deep inside an object.
16
+ * - merge: merge multiple nodes, overriding values in earlier nodes.
17
+ * - walk: walk a node tree, applying a function at each node and leaf.
18
+ * - inject: inject values from a data store into a new data structure.
19
+ * - transform: transform a data structure to an example structure.
20
+ * - validate: valiate a data structure against a shape specification.
21
+ *
22
+ * Minor utilities
23
+ * - isnode, islist, ismap, iskey, isfunc: identify value kinds.
24
+ * - isempty: undefined values, or empty nodes.
25
+ * - keysof: sorted list of node keys (ascending).
26
+ * - haskey: true if key value is defined.
27
+ * - clone: create a copy of a JSON-like data structure.
28
+ * - items: list entries of a map or list as [key, value] pairs.
29
+ * - getprop: safely get a property value by key.
30
+ * - setprop: safely set a property value by key.
31
+ * - stringify: human-friendly string version of a value.
32
+ * - escre: escape a regular expresion string.
33
+ * - escurl: escape a url.
34
+ * - joinurl: join parts of a url, merging forward slashes.
35
+ *
36
+ * This set of functions and supporting utilities is designed to work
37
+ * uniformly across many languages, meaning that some code that may be
38
+ * functionally redundant in specific languages is still retained to
39
+ * keep the code human comparable.
40
+ *
41
+ * NOTE: In this code JSON nulls are in general *not* considered the
42
+ * same as the undefined value in the given language. However most
43
+ * JSON parsers do use the undefined value to represent JSON
44
+ * null. This is ambiguous as JSON null is a separate value, not an
45
+ * undefined value. You should convert such values to a special value
46
+ * to represent JSON null, if this ambiguity creates issues
47
+ * (thankfully in most APIs, JSON nulls are not used). For example,
48
+ * the unit tests use the string "__NULL__" where necessary.
49
+ *
50
+ */
51
+
52
+
53
+ // String constants are explicitly defined.
54
+
55
+ // Mode value for inject step.
56
+ const S_MKEYPRE = 'key:pre'
57
+ const S_MKEYPOST = 'key:post'
58
+ const S_MVAL = 'val'
59
+ const S_MKEY = 'key'
60
+
61
+ // Special keys.
62
+ const S_DKEY = '`$KEY`'
63
+ const S_DMETA = '`$META`'
64
+ const S_DTOP = '$TOP'
65
+ const S_DERRS = '$ERRS'
66
+ const S_DSPEC = '$SPEC'
67
+
68
+ // General strings.
69
+ const S_array = 'array'
70
+ const S_base = 'base'
71
+ const S_boolean = 'boolean'
72
+ const S_function = 'function'
73
+ const S_number = 'number'
74
+ const S_object = 'object'
75
+ const S_string = 'string'
76
+ const S_null = 'null'
77
+ const S_MT = ''
78
+ const S_BT = '`'
79
+ const S_DS = '$'
80
+ const S_DT = '.'
81
+ const S_CN = ':'
82
+ const S_FS = '/'
83
+ const S_KEY = 'KEY'
84
+
85
+
86
+ // The standard undefined value for this language.
87
+ const UNDEF = undefined
88
+
89
+
90
+ // Keys are strings for maps, or integers for lists.
91
+ type PropKey = string | number
92
+
93
+
94
+ // For each key in a node (map or list), perform value injections in
95
+ // three phases: on key value, before child, and then on key value again.
96
+ // This mode is passed via the Injection structure.
97
+ type InjectMode = 'key:pre' | 'key:post' | 'val'
98
+
99
+
100
+ // Handle value injections using backtick escape sequences:
101
+ // - `a.b.c`: insert value at {a:{b:{c:1}}}
102
+ // - `$FOO`: apply transform FOO
103
+ type Injector = (
104
+ inj: Injection, // Injection state.
105
+ val: any, // Injection value specification.
106
+ current: any, // Current source parent value.
107
+ ref: string, // Original injection reference string.
108
+ store: any, // Current source root value.
109
+ ) => any
110
+
111
+
112
+ // Injection state used for recursive injection into JSON - like data structures.
113
+ class Injection {
114
+ mode: InjectMode // Injection mode: key:pre, val, key:post.
115
+ full: boolean // Transform escape was full key name.
116
+ keyI: number // Index of parent key in list of parent keys.
117
+ keys: string[] // List of parent keys.
118
+ key: string // Current parent key.
119
+ val: any // Current child value.
120
+ parent: any // Current parent (in transform specification).
121
+ path: string[] // Path to current node.
122
+ nodes: any[] // Stack of ancestor nodes.
123
+ handler: Injector // Custom handler for injections.
124
+ errs: any[] // Error collector.
125
+ meta: Record<string, any> // Custom meta data.
126
+ base?: string // Base key for data in store, if any.
127
+ modify?: Modify // Modify injection output.
128
+ prior?: Injection
129
+
130
+ constructor(val: any, parent: any, modify?: Modify, errs?: any[]) {
131
+ this.val = val
132
+ this.parent = parent
133
+
134
+ this.mode = S_MVAL as InjectMode
135
+ this.full = false
136
+ this.keyI = 0
137
+ this.keys = [S_DTOP]
138
+ this.key = S_DTOP
139
+ this.path = [S_DTOP]
140
+ this.nodes = [parent]
141
+ this.handler = _injecthandler
142
+ this.base = S_DTOP
143
+ this.modify = modify
144
+ this.errs = errs || []
145
+ this.meta = {}
146
+ }
147
+
148
+ toString(prefix?: string) {
149
+ return 'INJ' + (null == prefix ? '' : S_FS + prefix) + S_CN +
150
+ pad(pathify(this.path)) +
151
+ this.mode + (this.full ? '/full' : '') + S_CN +
152
+ 'key=' + this.keyI + S_FS + this.key + S_FS + this.keys +
153
+ ' p=' + stringify(this.parent, -1, 1) +
154
+ ' m=' + stringify(this.meta, -1, 1) +
155
+ ' r=' + stringify(this.nodes[0]?.[S_DTOP], -1, 1)
156
+ }
157
+
158
+ child(keyI: number, keys: string[]) {
159
+ const key = strkey(keys[keyI])
160
+ const val = this.val
161
+
162
+ const cinj = new Injection(
163
+ getprop(val, key),
164
+ val,
165
+ this.modify,
166
+ this.errs
167
+ )
168
+ cinj.keyI = keyI
169
+ cinj.keys = keys
170
+ cinj.key = key
171
+
172
+ cinj.path = [...(this.path || []), key]
173
+ cinj.nodes = [...(this.nodes || []), val]
174
+
175
+ cinj.mode = this.mode
176
+ cinj.handler = this.handler
177
+ cinj.base = this.base
178
+ cinj.meta = this.meta
179
+ cinj.prior = this
180
+
181
+ return cinj
182
+ }
183
+
184
+ setval(val: any, ancestor?: number) {
185
+ if (null == ancestor || ancestor < 2) {
186
+ return setprop(this.parent, this.key, val)
187
+ }
188
+ else {
189
+ return setprop(getelem(this.nodes, 0 - ancestor), getelem(this.path, 0 - ancestor), val)
190
+ }
191
+ }
192
+ }
193
+
194
+
195
+ // Apply a custom modification to injections.
196
+ type Modify = (
197
+ val: any, // Value.
198
+ key?: PropKey, // Value key, if any,
199
+ parent?: any, // Parent node, if any.
200
+ inj?: Injection, // Injection state, if any.
201
+ current?: any, // Current value in store (matches path).
202
+ store?: any, // Store, if any
203
+ ) => void
204
+
205
+
206
+ // Function applied to each node and leaf when walking a node structure depth first.
207
+ // NOTE: For {a:{b:1}} the call sequence args will be:
208
+ // b, 1, {b:1}, [a,b]
209
+ type WalkApply = (
210
+ // Map keys are strings, list keys are numbers, top key is UNDEF
211
+ key: string | number | undefined,
212
+ val: any,
213
+ parent: any,
214
+ path: string[]
215
+ ) => any
216
+
217
+
218
+ // Value is a node - defined, and a map (hash) or list (array).
219
+ function isnode(val: any) {
220
+ return null != val && S_object == typeof val
221
+ }
222
+
223
+
224
+ // Value is a defined map (hash) with string keys.
225
+ function ismap(val: any) {
226
+ return null != val && S_object == typeof val && !Array.isArray(val)
227
+ }
228
+
229
+
230
+ // Value is a defined list (array) with integer keys (indexes).
231
+ function islist(val: any) {
232
+ return Array.isArray(val)
233
+ }
234
+
235
+
236
+ // Value is a defined string (non-empty) or integer key.
237
+ function iskey(key: any) {
238
+ const keytype = typeof key
239
+ return (S_string === keytype && S_MT !== key) || S_number === keytype
240
+ }
241
+
242
+
243
+ // Check for an "empty" value - undefined, empty string, array, object.
244
+ function isempty(val: any) {
245
+ return null == val || S_MT === val ||
246
+ (Array.isArray(val) && 0 === val.length) ||
247
+ (S_object === typeof val && 0 === Object.keys(val).length)
248
+ }
249
+
250
+
251
+ // Value is a function.
252
+ function isfunc(val: any) {
253
+ return S_function === typeof val
254
+ }
255
+
256
+
257
+ function size(val: any): number {
258
+ if (islist(val)) {
259
+ return val.length
260
+ }
261
+ else if (ismap(val)) {
262
+ return Object.keys(val).length
263
+ }
264
+
265
+ const valtype = typeof val
266
+
267
+ if (S_string == valtype) {
268
+ return val.length
269
+ }
270
+ else if (S_number == typeof val) {
271
+ return Math.floor(val)
272
+ }
273
+ else if (S_boolean == typeof val) {
274
+ return true === val ? 1 : 0
275
+ }
276
+ else {
277
+ return 0
278
+ }
279
+ }
280
+
281
+
282
+ function slice<V extends any>(val: V, start: number, end?: number): V {
283
+ if (islist(val)) {
284
+ const vlen = size(val)
285
+ if (null != start) {
286
+ if (start < 0) {
287
+ end = vlen + start
288
+ if (end < 0) {
289
+ end = 0
290
+ }
291
+ start = 0
292
+ }
293
+
294
+ else if (null != end) {
295
+ if (end < 0) {
296
+ end = vlen + end
297
+ if (end < 0) {
298
+ end = 0
299
+ }
300
+ }
301
+ else if (vlen < end) {
302
+ end = val.length
303
+ }
304
+ }
305
+
306
+ else {
307
+ end = val.length
308
+ }
309
+
310
+ if (vlen < start) {
311
+ start = vlen
312
+ }
313
+
314
+ if (-1 < start && start <= end && end <= vlen) {
315
+ return val.slice(start, end) as V
316
+ }
317
+ }
318
+ }
319
+
320
+ return val
321
+ }
322
+
323
+
324
+ function pad(str: any, padding?: number, padchar?: string): string {
325
+ str = stringify(str)
326
+ padding = null == padding ? 44 : padding
327
+ padchar = null == padchar ? ' ' : ((padchar + ' ')[0])
328
+ return -1 < padding ? str.padEnd(padding, padchar) : str.padStart(0 - padding, padchar)
329
+ }
330
+
331
+
332
+ // Determine the type of a value as a string.
333
+ // Returns one of: 'null', 'string', 'number', 'boolean', 'function', 'array', 'object'
334
+ // Normalizes and simplifies JavaScript's type system for consistency.
335
+ function typify(value: any): string {
336
+ if (value === null || value === undefined) {
337
+ return S_null
338
+ }
339
+
340
+ const type = typeof value
341
+
342
+ if (Array.isArray(value)) {
343
+ return S_array
344
+ }
345
+
346
+ if (type === 'object') {
347
+ return S_object
348
+ }
349
+
350
+ return type
351
+ }
352
+
353
+
354
+ // Get a list element. The key should be an integer, or a string
355
+ // that can parse to an integer only. Negative integers count from the end of the list.
356
+ function getelem(val: any, key: any, alt?: any) {
357
+ let out = UNDEF
358
+
359
+ if (UNDEF === val || UNDEF === key) {
360
+ return alt
361
+ }
362
+
363
+ if (islist(val)) {
364
+ let nkey = parseInt(key)
365
+ if (Number.isInteger(nkey) && ('' + key).match(/^[-0-9]+$/)) {
366
+ if (nkey < 0) {
367
+ key = val.length + nkey
368
+ }
369
+ out = val[key]
370
+ }
371
+ }
372
+
373
+ if (UNDEF === out) {
374
+ return alt
375
+ }
376
+
377
+ return out
378
+ }
379
+
380
+
381
+ // Safely get a property of a node. Undefined arguments return undefined.
382
+ // If the key is not found, return the alternative value, if any.
383
+ // TODO: for arrays. make -i work, such that -1 => last element
384
+ function getprop(val: any, key: any, alt?: any) {
385
+ let out = alt
386
+
387
+ if (UNDEF === val || UNDEF === key) {
388
+ return alt
389
+ }
390
+
391
+ if (isnode(val)) {
392
+ out = val[key]
393
+ }
394
+
395
+ if (UNDEF === out) {
396
+ return alt
397
+ }
398
+
399
+ return out
400
+ }
401
+
402
+
403
+ // Convert different types of keys to string representation.
404
+ // String keys are returned as is.
405
+ // Number keys are converted to strings.
406
+ // Floats are truncated to integers.
407
+ // Booleans, objects, arrays, null, undefined all return empty string.
408
+ function strkey(key: any = UNDEF): string {
409
+ if (UNDEF === key) {
410
+ return S_MT
411
+ }
412
+
413
+ if (typeof key === S_string) {
414
+ return key
415
+ }
416
+
417
+ if (typeof key === S_boolean) {
418
+ return S_MT
419
+ }
420
+
421
+ if (typeof key === S_number) {
422
+ return key % 1 === 0 ? String(key) : String(Math.floor(key))
423
+ }
424
+
425
+ return S_MT
426
+ }
427
+
428
+
429
+ // Sorted keys of a map, or indexes of a list.
430
+ function keysof(val: any): string[] {
431
+ return !isnode(val) ? [] :
432
+ ismap(val) ? Object.keys(val).sort() : val.map((_n: any, i: number) => '' + i)
433
+ }
434
+
435
+
436
+ // Value of property with name key in node val is defined.
437
+ function haskey(val: any, key: any) {
438
+ return UNDEF !== getprop(val, key)
439
+ }
440
+
441
+
442
+ // List the sorted keys of a map or list as an array of tuples of the form [key, value].
443
+ // NOTE: Unlike keysof, list indexes are returned as numbers.
444
+ function items(val: any): [number | string, any][] {
445
+ return keysof(val).map((k: any) => [k, val[k]])
446
+ }
447
+
448
+
449
+ // Escape regular expression.
450
+ function escre(s: string) {
451
+ s = null == s ? S_MT : s
452
+ return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
453
+ }
454
+
455
+
456
+ // Escape URLs.
457
+ function escurl(s: string) {
458
+ s = null == s ? S_MT : s
459
+ return encodeURIComponent(s)
460
+ }
461
+
462
+
463
+ // Concatenate url part strings, merging forward slashes as needed.
464
+ function joinurl(sarr: any[]) {
465
+ return sarr
466
+ .filter(s => null != s && '' !== s)
467
+ .map((s, i) => 0 === i ? s.replace(/\/+$/, '') :
468
+ s.replace(/([^\/])\/+/, '$1/').replace(/^\/+/, '').replace(/\/+$/, ''))
469
+ .filter(s => '' !== s)
470
+ .join('/')
471
+ }
472
+
473
+
474
+ // Safely stringify a value for humans (NOT JSON!).
475
+ function stringify(val: any, maxlen?: number, pretty?: any): string {
476
+ let valstr = S_MT
477
+ pretty = !!pretty
478
+
479
+ if (UNDEF === val) {
480
+ return pretty ? '<>' : valstr
481
+ }
482
+
483
+ try {
484
+ valstr = JSON.stringify(val, function(_key: string, val: any) {
485
+ if (
486
+ val !== null &&
487
+ typeof val === "object" &&
488
+ !Array.isArray(val)
489
+ ) {
490
+ const sortedObj: any = {}
491
+ for (const k of Object.keys(val).sort()) {
492
+ sortedObj[k] = val[k]
493
+ }
494
+ return sortedObj
495
+ }
496
+ return val
497
+ })
498
+ }
499
+ catch (err: any) {
500
+ valstr = S_MT + val
501
+ }
502
+
503
+ valstr = S_string !== typeof valstr ? S_MT + valstr : valstr
504
+ valstr = valstr.replace(/"/g, '')
505
+
506
+ if (null != maxlen && -1 < maxlen) {
507
+ let js = valstr.substring(0, maxlen)
508
+ valstr = maxlen < valstr.length ? (js.substring(0, maxlen - 3) + '...') : valstr
509
+ }
510
+
511
+ if (pretty) {
512
+ let c = [81, 118, 213, 39, 208, 201, 45, 190, 129, 51, 160, 121, 226, 33, 207, 69]
513
+ .map(n => `\x1b[38;5;${n}m`),
514
+ r = '\x1b[0m', d = 0, o = c[0], t = o
515
+ for (const ch of valstr) {
516
+ if (ch === '{' || ch === '[') {
517
+ d++; o = c[d % c.length]; t += o + ch
518
+ } else if (ch === '}' || ch === ']') {
519
+ t += o + ch; d--; o = c[d % c.length]
520
+ } else {
521
+ t += o + ch
522
+ }
523
+ }
524
+ return t + r
525
+
526
+ }
527
+
528
+ return valstr
529
+ }
530
+
531
+
532
+ // Build a human friendly path string.
533
+ function pathify(val: any, startin?: number, endin?: number) {
534
+ let pathstr: string | undefined = UNDEF
535
+
536
+ let path: any[] | undefined = islist(val) ? val :
537
+ S_string == typeof val ? [val] :
538
+ S_number == typeof val ? [val] :
539
+ UNDEF
540
+
541
+ const start = null == startin ? 0 : -1 < startin ? startin : 0
542
+ const end = null == endin ? 0 : -1 < endin ? endin : 0
543
+
544
+ if (UNDEF != path && 0 <= start) {
545
+ path = slice(path, start, path.length - end)
546
+ if (0 === path.length) {
547
+ pathstr = '<root>'
548
+ }
549
+ else {
550
+ pathstr = path
551
+ // .filter((p: any, t: any) => (t = typeof p, S_string === t || S_number === t))
552
+ .filter((p: any) => iskey(p))
553
+ .map((p: any) =>
554
+ 'number' === typeof p ? S_MT + Math.floor(p) :
555
+ p.replace(/\./g, S_MT))
556
+ .join(S_DT)
557
+ }
558
+ }
559
+
560
+ if (UNDEF === pathstr) {
561
+ pathstr = '<unknown-path' + (UNDEF === val ? S_MT : S_CN + stringify(val, 47)) + '>'
562
+ }
563
+
564
+ return pathstr
565
+ }
566
+
567
+
568
+ // Clone a JSON-like data structure.
569
+ // NOTE: function value references are copied, *not* cloned.
570
+ function clone(val: any): any {
571
+ const refs: any[] = []
572
+ const replacer: any = (_k: any, v: any) => S_function === typeof v ?
573
+ (refs.push(v), '`$FUNCTION:' + (refs.length - 1) + '`') : v
574
+ const reviver: any = (_k: any, v: any, m: any) => S_string === typeof v ?
575
+ (m = v.match(/^`\$FUNCTION:([0-9]+)`$/), m ? refs[m[1]] : v) : v
576
+ return UNDEF === val ? UNDEF : JSON.parse(JSON.stringify(val, replacer), reviver)
577
+ }
578
+
579
+
580
+ // Safely set a property. Undefined arguments and invalid keys are ignored.
581
+ // Returns the (possibly modified) parent.
582
+ // If the value is undefined the key will be deleted from the parent.
583
+ // If the parent is a list, and the key is negative, prepend the value.
584
+ // NOTE: If the key is above the list size, append the value; below, prepend.
585
+ // If the value is undefined, remove the list element at index key, and shift the
586
+ // remaining elements down. These rules avoid "holes" in the list.
587
+ function setprop<PARENT>(parent: PARENT, key: any, val: any): PARENT {
588
+ if (!iskey(key)) {
589
+ return parent
590
+ }
591
+
592
+ if (ismap(parent)) {
593
+ key = S_MT + key
594
+ if (UNDEF === val) {
595
+ delete (parent as any)[key]
596
+ }
597
+ else {
598
+ (parent as any)[key] = val
599
+ }
600
+ }
601
+ else if (islist(parent)) {
602
+ // Ensure key is an integer.
603
+ let keyI = +key
604
+
605
+ if (isNaN(keyI)) {
606
+ return parent
607
+ }
608
+
609
+ keyI = Math.floor(keyI)
610
+
611
+ // Delete list element at position keyI, shifting later elements down.
612
+ if (UNDEF === val) {
613
+ if (0 <= keyI && keyI < parent.length) {
614
+ for (let pI = keyI; pI < parent.length - 1; pI++) {
615
+ parent[pI] = parent[pI + 1]
616
+ }
617
+ parent.length = parent.length - 1
618
+ }
619
+ }
620
+
621
+ // Set or append value at position keyI, or append if keyI out of bounds.
622
+ else if (0 <= keyI) {
623
+ parent[parent.length < keyI ? parent.length : keyI] = val
624
+ }
625
+
626
+ // Prepend value if keyI is negative
627
+ else {
628
+ parent.unshift(val)
629
+ }
630
+ }
631
+
632
+ return parent
633
+ }
634
+
635
+
636
+ // Walk a data structure depth first, applying a function to each value.
637
+ function walk(
638
+ // These arguments are the public interface.
639
+ val: any,
640
+ apply: WalkApply,
641
+
642
+ // These areguments are used for recursive state.
643
+ key?: string | number,
644
+ parent?: any,
645
+ path?: string[]
646
+ ): any {
647
+ if (isnode(val)) {
648
+ for (let [ckey, child] of items(val)) {
649
+ setprop(val, ckey, walk(child, apply, ckey, val, [...(path || []), S_MT + ckey]))
650
+ }
651
+ }
652
+
653
+ // Nodes are applied *after* their children.
654
+ // For the root node, key and parent will be undefined.
655
+ return apply(key, val, parent, path || [])
656
+ }
657
+
658
+
659
+ // Merge a list of values into each other. Later values have
660
+ // precedence. Nodes override scalars. Node kinds (list or map)
661
+ // override each other, and do *not* merge. The first element is
662
+ // modified.
663
+ function merge(val: any): any {
664
+ let out: any = UNDEF
665
+
666
+ // Handle edge cases.
667
+ if (!islist(val)) {
668
+ return val
669
+ }
670
+
671
+ const list = val as any[]
672
+ const lenlist = list.length
673
+
674
+ if (0 === lenlist) {
675
+ return UNDEF
676
+ }
677
+ else if (1 === lenlist) {
678
+ return list[0]
679
+ }
680
+
681
+ // Merge a list of values.
682
+ out = getprop(list, 0, {})
683
+
684
+ for (let oI = 1; oI < lenlist; oI++) {
685
+ let obj = list[oI]
686
+
687
+ if (!isnode(obj)) {
688
+ // Nodes win.
689
+ out = obj
690
+ }
691
+ else {
692
+ // Nodes win, also over nodes of a different kind.
693
+ if (!isnode(out) || (ismap(obj) && islist(out)) || (islist(obj) && ismap(out))) {
694
+ out = obj
695
+ }
696
+ else {
697
+ // Node stack. walking down the current obj.
698
+ let cur = [out]
699
+ let cI = 0
700
+
701
+ function merger(
702
+ key: string | number | undefined,
703
+ val: any,
704
+ parent: any,
705
+ path: string[]
706
+ ) {
707
+ if (null == key) {
708
+ return val
709
+ }
710
+
711
+ // Get the curent value at the current path in obj.
712
+ // NOTE: this is not exactly efficient, and should be optimised.
713
+ let lenpath = path.length
714
+ cI = lenpath - 1
715
+ if (UNDEF === cur[cI]) {
716
+ cur[cI] = getpath(slice(path, 0, lenpath - 1), out)
717
+ }
718
+
719
+ // Create node if needed.
720
+ if (!isnode(cur[cI])) {
721
+ cur[cI] = islist(parent) ? [] : {}
722
+ }
723
+
724
+ // Node child is just ahead of us on the stack, since
725
+ // `walk` traverses leaves before nodes.
726
+ if (isnode(val) && !isempty(val)) {
727
+ setprop(cur[cI], key, cur[cI + 1])
728
+ cur[cI + 1] = UNDEF
729
+ }
730
+
731
+ // Scalar child.
732
+ else {
733
+ setprop(cur[cI], key, val)
734
+ }
735
+
736
+ return val
737
+ }
738
+
739
+ // Walk overriding node, creating paths in output as needed.
740
+ walk(obj, merger)
741
+ }
742
+ }
743
+ }
744
+
745
+ return out
746
+ }
747
+
748
+
749
+ // Get a value deep inside a node using a key path. For example the
750
+ // path `a.b` gets the value 1 from {a:{b:1}}. The path can specified
751
+ // as a dotted string, or a string array. If the path starts with a
752
+ // dot (or the first element is ''), the path is considered local, and
753
+ // resolved against the `current` argument, if defined. Integer path
754
+ // parts are used as array indexes. The inj argument allows for
755
+ // custom handling when called from `inject` or `transform`.
756
+ // TODO: change sig to be consistent with getprop
757
+ function getpath(path: string | string[], store: any, current?: any, inj?: Injection) {
758
+
759
+ // Operate on a string array.
760
+ const parts = islist(path) ? path : S_string === typeof path ? path.split(S_DT) : UNDEF
761
+
762
+ if (UNDEF === parts) {
763
+ return UNDEF
764
+ }
765
+
766
+ let root = store
767
+ let val = store
768
+ const base = getprop(inj, S_base)
769
+
770
+ // An empty path (incl empty string) just finds the store.
771
+ if (null == path || null == store || (1 === parts.length && S_MT === parts[0])) {
772
+ // The actual store data may be in a store sub property, defined by inj.base.
773
+ val = getprop(store, base, store)
774
+ }
775
+ else if (0 < parts.length) {
776
+ let pI = 0
777
+
778
+ // Relative path uses `current` argument.
779
+ if (S_MT === parts[0]) {
780
+ pI = 1
781
+ root = current
782
+ }
783
+
784
+ let part = pI < parts.length ? parts[pI] : UNDEF
785
+ let first: any = S_MT === part ? current : getprop(root, part)
786
+
787
+ // At top level, check inj.base, if provided
788
+ val = (UNDEF === first && 0 === pI) ?
789
+ getprop(getprop(root, base), part) :
790
+ first
791
+
792
+ // Move along the path, trying to descend into the store.
793
+ for (pI++; UNDEF !== val && pI < parts.length; pI++) {
794
+ part = parts[pI]
795
+ if (S_MT !== part) {
796
+ val = getprop(val, parts[pI])
797
+ }
798
+ }
799
+ }
800
+
801
+ // Inj may provide a custom handler to modify found value.
802
+ if (null != inj && isfunc(inj.handler)) {
803
+ const ref = pathify(path)
804
+ val = inj.handler(inj, val, current, ref, store)
805
+ }
806
+
807
+ return val
808
+ }
809
+
810
+ // let cI = 0
811
+
812
+ // Inject values from a data store into a node recursively, resolving
813
+ // paths against the store, or current if they are local. THe modify
814
+ // argument allows custom modification of the result. The inj
815
+ // (Injection) argument is used to maintain recursive state.
816
+ function inject(
817
+ val: any,
818
+ store: any,
819
+ modify?: Modify,
820
+ current?: any,
821
+ inj?: Injection,
822
+ ) {
823
+ const valtype = typeof val
824
+
825
+ // Create state if at root of injection. The input value is placed
826
+ // inside a virtual parent holder to simplify edge cases.
827
+ if (UNDEF === inj) {
828
+
829
+ // Set up state assuming we are starting in the virtual parent.
830
+ inj = new Injection(val, { [S_DTOP]: val }, modify, getprop(store, S_DERRS))
831
+ inj.meta.d = 0
832
+ }
833
+
834
+ inj.meta.d++
835
+
836
+ // Resolve current node in store for local paths.
837
+ if (UNDEF === current) {
838
+ // TODO: check store base prop ($TOP)
839
+ current = { $TOP: store }
840
+ }
841
+ else {
842
+ // A provided current is expected to be the containing node of the associated
843
+ // store value.
844
+ const parentkey = getelem(inj.path, -2)
845
+ current = null == parentkey ? current : getprop(current, parentkey)
846
+ }
847
+
848
+ // console.log('' + inj + ' c=' + stringify(current, -1, 1))
849
+
850
+ // Descend into node.
851
+ if (isnode(val)) {
852
+
853
+ // Keys are sorted alphanumerically to ensure determinism.
854
+ // Injection transforms ($FOO) are processed *after* other keys.
855
+ // NOTE: the optional digits suffix of the transform can thus be
856
+ // used to order the transforms.
857
+ let nodekeys = ismap(val) ? [
858
+ ...Object.keys(val).filter(k => !k.includes(S_DS)).sort(),
859
+ ...Object.keys(val).filter(k => k.includes(S_DS)).sort(),
860
+ ] : val.map((_n: any, i: number) => i)
861
+
862
+
863
+ // Each child key-value pair is processed in three injection phases:
864
+ // 1. inj.mode='key:pre' - Key string is injected, returning a possibly altered key.
865
+ // 2. inj.mode='val' - The child value is injected.
866
+ // 3. inj.mode='key:post' - Key string is injected again, allowing child mutation.
867
+ for (let nkI = 0; nkI < nodekeys.length; nkI++) {
868
+
869
+ const childinj = inj.child(nkI, nodekeys)
870
+ const nodekey = childinj.key
871
+ childinj.mode = S_MKEYPRE
872
+
873
+ // Peform the key:pre mode injection on the child key.
874
+ const prekey = _injectstr(nodekey, store, current, childinj)
875
+
876
+ // The injection may modify child processing.
877
+ nkI = childinj.keyI
878
+ nodekeys = childinj.keys
879
+
880
+ // Prevent further processing by returning an undefined prekey
881
+ if (UNDEF !== prekey) {
882
+ childinj.val = getprop(val, prekey)
883
+ childinj.mode = S_MVAL as InjectMode
884
+
885
+ // Perform the val mode injection on the child value.
886
+ // NOTE: return value is not used.
887
+ inject(childinj.val, store, modify, current, childinj)
888
+
889
+ // The injection may modify child processing.
890
+ nkI = childinj.keyI
891
+ nodekeys = childinj.keys
892
+
893
+ // Peform the key:post mode injection on the child key.
894
+ childinj.mode = S_MKEYPOST as InjectMode
895
+ _injectstr(nodekey, store, current, childinj)
896
+
897
+ // The injection may modify child processing.
898
+ nkI = childinj.keyI
899
+ nodekeys = childinj.keys
900
+ }
901
+ }
902
+ }
903
+
904
+ // Inject paths into string scalars.
905
+ else if (S_string === valtype) {
906
+ inj.mode = S_MVAL as InjectMode
907
+ val = _injectstr(val, store, current, inj)
908
+ setprop(inj.parent, inj.key, val)
909
+ }
910
+
911
+ // Custom modification.
912
+ if (modify) {
913
+ let mkey = inj.key
914
+ let mparent = inj.parent
915
+ let mval = getprop(mparent, mkey)
916
+ modify(
917
+ mval,
918
+ mkey,
919
+ mparent,
920
+ inj,
921
+ current,
922
+ store
923
+ )
924
+ }
925
+
926
+ inj.val = val
927
+
928
+ // Original val reference may no longer be correct.
929
+ // This return value is only used as the top level result.
930
+ return getprop(inj.parent, S_DTOP)
931
+ }
932
+
933
+
934
+ // The transform_* functions are special command inject handlers (see Injector).
935
+
936
+ // Delete a key from a map or list.
937
+ const transform_DELETE: Injector = (inj: Injection) => {
938
+ // _setparentprop(inj, UNDEF)
939
+ inj.setval(UNDEF)
940
+ return UNDEF
941
+ }
942
+
943
+
944
+ // Copy value from source data.
945
+ const transform_COPY: Injector = (inj: Injection, _val: any, current: any) => {
946
+ const { mode, key } = inj
947
+
948
+ let out = key
949
+ if (!mode.startsWith(S_MKEY)) {
950
+ out = getprop(current, key)
951
+ inj.setval(out)
952
+ }
953
+
954
+ return out
955
+ }
956
+
957
+
958
+ // As a value, inject the key of the parent node.
959
+ // As a key, defined the name of the key property in the source object.
960
+ const transform_KEY: Injector = (inj: Injection, _val: any, current: any) => {
961
+ const { mode, path, parent } = inj
962
+
963
+ // Do nothing in val mode.
964
+ if (S_MVAL !== mode) {
965
+ return UNDEF
966
+ }
967
+
968
+ // Key is defined by $KEY meta property.
969
+ const keyspec = getprop(parent, S_DKEY)
970
+ if (UNDEF !== keyspec) {
971
+ setprop(parent, S_DKEY, UNDEF)
972
+ return getprop(current, keyspec)
973
+ }
974
+
975
+ // Key is defined within general purpose $META object.
976
+ return getprop(getprop(parent, S_DMETA), S_KEY, getprop(path, path.length - 2))
977
+ }
978
+
979
+
980
+ // Store meta data about a node. Does nothing itself, just used by
981
+ // other injectors, and is removed when called.
982
+ const transform_META: Injector = (inj: Injection) => {
983
+ const { parent } = inj
984
+ setprop(parent, S_DMETA, UNDEF)
985
+ return UNDEF
986
+ }
987
+
988
+
989
+ // Merge a list of objects into the current object.
990
+ // Must be a key in an object. The value is merged over the current object.
991
+ // If the value is an array, the elements are first merged using `merge`.
992
+ // If the value is the empty string, merge the top level store.
993
+ // Format: { '`$MERGE`': '`source-path`' | ['`source-paths`', ...] }
994
+ const transform_MERGE: Injector = (
995
+ inj: Injection, _val: any, current: any
996
+ ) => {
997
+ const { mode, key, parent } = inj
998
+
999
+ if (S_MKEYPRE === mode) { return key }
1000
+
1001
+ // Operate after child values have been transformed.
1002
+ if (S_MKEYPOST === mode) {
1003
+
1004
+ let args = getprop(parent, key)
1005
+ args = S_MT === args ? [current.$TOP] : Array.isArray(args) ? args : [args]
1006
+
1007
+ // Remove the $MERGE command from a parent map.
1008
+ inj.setval(UNDEF)
1009
+
1010
+ // Literals in the parent have precedence, but we still merge onto
1011
+ // the parent object, so that node tree references are not changed.
1012
+ const mergelist = [parent, ...args, clone(parent)]
1013
+
1014
+ merge(mergelist)
1015
+
1016
+ return key
1017
+ }
1018
+
1019
+ // Ensures $MERGE is removed from parent list.
1020
+ return UNDEF
1021
+ }
1022
+
1023
+
1024
+ // Convert a node to a list.
1025
+ // Format: ['`$EACH`', '`source-path-of-node`', child-template]
1026
+ const transform_EACH: Injector = (
1027
+ inj: Injection,
1028
+ _val: any,
1029
+ current: any,
1030
+ _ref: string,
1031
+ store: any
1032
+ ) => {
1033
+
1034
+ // Remove arguments to avoid spurious processing.
1035
+ if (null != inj.keys) {
1036
+ inj.keys.length = 1
1037
+ }
1038
+
1039
+ if (S_MVAL !== inj.mode) {
1040
+ return UNDEF
1041
+ }
1042
+
1043
+ // Get arguments: ['`$EACH`', 'source-path', child-template].
1044
+ const srcpath = getprop(inj.parent, 1)
1045
+ const child = clone(getprop(inj.parent, 2))
1046
+
1047
+ // Source data.
1048
+ const srcstore = getprop(store, inj.base, store)
1049
+ const src = getpath(srcpath, srcstore, current)
1050
+
1051
+ // Create parallel data structures:
1052
+ // source entries :: child templates
1053
+ let tcur: any = []
1054
+ let tval: any = []
1055
+
1056
+ const tkey = inj.path[inj.path.length - 2]
1057
+ const target = inj.nodes[inj.nodes.length - 2] || inj.nodes[inj.nodes.length - 1]
1058
+
1059
+ // Create clones of the child template for each value of the current soruce.
1060
+ if (islist(src)) {
1061
+ tval = src.map(() => clone(child))
1062
+ }
1063
+ else if (ismap(src)) {
1064
+ tval = Object.entries(src).map(n => ({
1065
+ ...clone(child),
1066
+
1067
+ // Make a note of the key for $KEY transforms.
1068
+ [S_DMETA]: { KEY: n[0] }
1069
+ }))
1070
+ }
1071
+
1072
+ let rval = []
1073
+
1074
+ if (0 < size(tval)) {
1075
+ tcur = null == src ? UNDEF : Object.values(src)
1076
+
1077
+ const tpath = slice(inj.path, -1)
1078
+
1079
+ // Parent structure.
1080
+ const ckey = getelem(inj.path, -2)
1081
+ tcur = { [ckey]: tcur }
1082
+
1083
+ if (1 < tpath.length) {
1084
+ const pkey = getelem(inj.path, -3, S_DTOP)
1085
+ tcur = { [pkey]: tcur }
1086
+ }
1087
+
1088
+ const tinj = inj.child(0, [ckey])
1089
+ tinj.path = tpath
1090
+ tinj.nodes = slice(inj.nodes, -1)
1091
+ tinj.parent = tcur
1092
+ tinj.val = tval
1093
+
1094
+ inject(tval, store, inj.modify, tcur, tinj)
1095
+ rval = tinj.val
1096
+ }
1097
+
1098
+ _updateAncestors(inj, target, tkey, rval)
1099
+
1100
+ // Prevent callee from damaging first list entry (since we are in `val` mode).
1101
+ return rval[0]
1102
+ }
1103
+
1104
+
1105
+ // Convert a node to a map.
1106
+ // Format: { '`$PACK`':['`source-path`', child-template]}
1107
+ const transform_PACK: Injector = (
1108
+ inj: Injection,
1109
+ _val: any,
1110
+ current: any,
1111
+ _ref: string,
1112
+ store: any
1113
+ ) => {
1114
+ const { mode, key, path, parent, nodes } = inj
1115
+
1116
+ // Defensive context checks.
1117
+ if (S_MKEYPRE !== mode || S_string !== typeof key || null == path || null == nodes) {
1118
+ return UNDEF
1119
+ }
1120
+
1121
+ // Get arguments.
1122
+ const args = parent[key]
1123
+ const srcpath = args[0] // Path to source data.
1124
+ const child = clone(args[1]) // Child template.
1125
+
1126
+ // Find key and target node.
1127
+ const keyprop = child[S_DKEY]
1128
+ const tkey = getelem(path, -2)
1129
+ const target = nodes[path.length - 2] || nodes[path.length - 1]
1130
+
1131
+ // Source data
1132
+ const srcstore = getprop(store, inj.base, store)
1133
+ let src = getpath(srcpath, srcstore, current)
1134
+
1135
+ // Prepare source as a list.
1136
+ src = islist(src) ? src :
1137
+ ismap(src) ? Object.entries(src)
1138
+ .reduce((a: any[], n: any) =>
1139
+ (n[1][S_DMETA] = { KEY: n[0] }, a.push(n[1]), a), []) :
1140
+ UNDEF
1141
+
1142
+ if (null == src) {
1143
+ return UNDEF
1144
+ }
1145
+
1146
+ // Get key if specified.
1147
+ let childkey: PropKey | undefined = getprop(child, S_DKEY)
1148
+ let keyname = UNDEF === childkey ? keyprop : childkey
1149
+ setprop(child, S_DKEY, UNDEF)
1150
+
1151
+ // Build parallel target object.
1152
+ let tval: any = {}
1153
+ tval = src.reduce((a: any, n: any) => {
1154
+ let kn = getprop(n, keyname)
1155
+ setprop(a, kn, clone(child))
1156
+ const nchild = getprop(a, kn)
1157
+ setprop(nchild, S_DMETA, getprop(n, S_DMETA))
1158
+ return a
1159
+ }, tval)
1160
+
1161
+ let rval = {}
1162
+
1163
+ if (0 < size(tval)) {
1164
+
1165
+ // Build parallel source object.
1166
+ let tcur: any = {}
1167
+ src.reduce((a: any, n: any) => {
1168
+ let kn = getprop(n, keyname)
1169
+ setprop(a, kn, n)
1170
+ return a
1171
+ }, tcur)
1172
+
1173
+ const tpath = slice(inj.path, -1)
1174
+
1175
+ const ckey = getelem(inj.path, -2)
1176
+ tcur = { [ckey]: tcur }
1177
+
1178
+ if (1 < tpath.length) {
1179
+ const pkey = getelem(inj.path, -3, S_DTOP)
1180
+ tcur = { [pkey]: tcur }
1181
+ }
1182
+
1183
+ const tinj = inj.child(0, [ckey])
1184
+ tinj.path = tpath
1185
+ tinj.nodes = slice(inj.nodes, -1)
1186
+ tinj.parent = tcur
1187
+ tinj.val = tval
1188
+
1189
+ inject(tval, store, inj.modify, tcur, tinj)
1190
+ rval = tinj.val
1191
+ }
1192
+
1193
+ _updateAncestors(inj, target, tkey, rval)
1194
+
1195
+ // Drop transform key.
1196
+ return UNDEF
1197
+ }
1198
+
1199
+
1200
+ // Reference original spec (enables recursice transformations)
1201
+ // Format: ['`$REF`', '`spec-path`']
1202
+ const transform_REF: Injector = (
1203
+ inj: Injection,
1204
+ val: any,
1205
+ _current: any,
1206
+ _ref: string,
1207
+ store: any
1208
+ ) => {
1209
+ const { nodes, modify } = inj
1210
+
1211
+ if (S_MVAL !== inj.mode) {
1212
+ return UNDEF
1213
+ }
1214
+
1215
+ // Get arguments: ['`$REF`', 'ref-path'].
1216
+ const refpath = getprop(inj.parent, 1)
1217
+ inj.keyI = inj.keys.length
1218
+
1219
+ // Spec reference.
1220
+ const spec = getprop(store, S_DSPEC)()
1221
+ const ref = getpath(refpath, spec)
1222
+
1223
+ let hasSubRef = false
1224
+ if (isnode(ref)) {
1225
+ walk(ref, (_k: any, v: any) => {
1226
+ if ('`$REF`' === v) {
1227
+ hasSubRef = true
1228
+ }
1229
+ return v
1230
+ })
1231
+ }
1232
+
1233
+ let tref = clone(ref)
1234
+
1235
+ const cpath = slice(inj.path, -3)
1236
+ const tpath = slice(inj.path, -1)
1237
+ let tcur = getpath(cpath, store)
1238
+ let tval = getpath(tpath, store)
1239
+ let rval = UNDEF
1240
+
1241
+ if (!hasSubRef || UNDEF !== tval) {
1242
+ const tinj = inj.child(0, [getelem(tpath, -1)])
1243
+
1244
+ tinj.path = tpath
1245
+ tinj.nodes = slice(inj.nodes, -1)
1246
+ tinj.parent = getelem(nodes, -2)
1247
+ tinj.val = tref
1248
+
1249
+ inject(tref, store, modify, tcur, tinj)
1250
+
1251
+ rval = tinj.val
1252
+ }
1253
+ else {
1254
+ rval = UNDEF
1255
+ }
1256
+
1257
+ const grandparent = inj.setval(rval, 2)
1258
+
1259
+ if (islist(grandparent) && inj.prior) {
1260
+ inj.prior.keyI--
1261
+ }
1262
+
1263
+ return val
1264
+ }
1265
+
1266
+
1267
+ // Transform data using spec.
1268
+ // Only operates on static JSON-like data.
1269
+ // Arrays are treated as if they are objects with indices as keys.
1270
+ function transform(
1271
+ data: any, // Source data to transform into new data (original not mutated)
1272
+ spec: any, // Transform specification; output follows this shape
1273
+ extra?: any, // Additional store of data and transforms.
1274
+ modify?: Modify // Optionally modify individual values.
1275
+ ) {
1276
+ // Clone the spec so that the clone can be modified in place as the transform result.
1277
+ const origspec = spec
1278
+ spec = clone(origspec)
1279
+
1280
+ const extraTransforms: any = {}
1281
+ const extraData = null == extra ? UNDEF : items(extra)
1282
+ .reduce((a: any, n: any[]) =>
1283
+ (n[0].startsWith(S_DS) ? extraTransforms[n[0]] = n[1] : (a[n[0]] = n[1]), a), {})
1284
+
1285
+ const dataClone = merge([
1286
+ isempty(extraData) ? UNDEF : clone(extraData),
1287
+ clone(data),
1288
+ ])
1289
+
1290
+ // Define a top level store that provides transform operations.
1291
+ const store = {
1292
+
1293
+ // The inject function recognises this special location for the root of the source data.
1294
+ // NOTE: to escape data that contains "`$FOO`" keys at the top level,
1295
+ // place that data inside a holding map: { myholder: mydata }.
1296
+ $TOP: dataClone,
1297
+
1298
+ $SPEC: () => origspec,
1299
+
1300
+ // Escape backtick (this also works inside backticks).
1301
+ $BT: () => S_BT,
1302
+
1303
+ // Escape dollar sign (this also works inside backticks).
1304
+ $DS: () => S_DS,
1305
+
1306
+ // Insert current date and time as an ISO string.
1307
+ $WHEN: () => new Date().toISOString(),
1308
+
1309
+ $DELETE: transform_DELETE,
1310
+ $COPY: transform_COPY,
1311
+ $KEY: transform_KEY,
1312
+ $META: transform_META,
1313
+ $MERGE: transform_MERGE,
1314
+ $EACH: transform_EACH,
1315
+ $PACK: transform_PACK,
1316
+ $REF: transform_REF,
1317
+
1318
+ // Custom extra transforms, if any.
1319
+ ...extraTransforms,
1320
+ }
1321
+
1322
+ const out = inject(spec, store, modify, store)
1323
+ return out
1324
+ }
1325
+
1326
+
1327
+ // A required string value. NOTE: Rejects empty strings.
1328
+ const validate_STRING: Injector = (inj: Injection, _val: any, current: any) => {
1329
+ let out = getprop(current, inj.key)
1330
+
1331
+ const t = typify(out)
1332
+ if (S_string !== t) {
1333
+ let msg = _invalidTypeMsg(inj.path, S_string, t, out, 'V1010')
1334
+ inj.errs.push(msg)
1335
+ return UNDEF
1336
+ }
1337
+
1338
+ if (S_MT === out) {
1339
+ let msg = 'Empty string at ' + pathify(inj.path, 1)
1340
+ inj.errs.push(msg)
1341
+ return UNDEF
1342
+ }
1343
+
1344
+ return out
1345
+ }
1346
+
1347
+
1348
+ // A required number value (int or float).
1349
+ const validate_NUMBER: Injector = (inj: Injection, _val: any, current: any) => {
1350
+ let out = getprop(current, inj.key)
1351
+
1352
+ const t = typify(out)
1353
+ if (S_number !== t) {
1354
+ inj.errs.push(_invalidTypeMsg(inj.path, S_number, t, out, 'V1020'))
1355
+ return UNDEF
1356
+ }
1357
+
1358
+ return out
1359
+ }
1360
+
1361
+
1362
+ // A required boolean value.
1363
+ const validate_BOOLEAN: Injector = (inj: Injection, _val: any, current: any) => {
1364
+ let out = getprop(current, inj.key)
1365
+
1366
+ const t = typify(out)
1367
+ if (S_boolean !== t) {
1368
+ inj.errs.push(_invalidTypeMsg(inj.path, S_boolean, t, out, 'V1030'))
1369
+ return UNDEF
1370
+ }
1371
+
1372
+ return out
1373
+ }
1374
+
1375
+
1376
+ // A required object (map) value (contents not validated).
1377
+ const validate_OBJECT: Injector = (inj: Injection, _val: any, current: any) => {
1378
+ let out = getprop(current, inj.key)
1379
+
1380
+ const t = typify(out)
1381
+ if (t !== S_object) {
1382
+ inj.errs.push(_invalidTypeMsg(inj.path, S_object, t, out, 'V1040'))
1383
+ return UNDEF
1384
+ }
1385
+
1386
+ return out
1387
+ }
1388
+
1389
+
1390
+ // A required array (list) value (contents not validated).
1391
+ const validate_ARRAY: Injector = (inj: Injection, _val: any, current: any) => {
1392
+ let out = getprop(current, inj.key)
1393
+
1394
+ const t = typify(out)
1395
+ if (t !== S_array) {
1396
+ inj.errs.push(_invalidTypeMsg(inj.path, S_array, t, out, 'V1050'))
1397
+ return UNDEF
1398
+ }
1399
+
1400
+ return out
1401
+ }
1402
+
1403
+
1404
+ // A required function value.
1405
+ const validate_FUNCTION: Injector = (inj: Injection, _val: any, current: any) => {
1406
+ let out = getprop(current, inj.key)
1407
+
1408
+ const t = typify(out)
1409
+ if (S_function !== t) {
1410
+ inj.errs.push(_invalidTypeMsg(inj.path, S_function, t, out, 'V1060'))
1411
+ return UNDEF
1412
+ }
1413
+
1414
+ return out
1415
+ }
1416
+
1417
+
1418
+ // Allow any value.
1419
+ const validate_ANY: Injector = (inj: Injection, _val: any, current: any) => {
1420
+ return getprop(current, inj.key)
1421
+ }
1422
+
1423
+
1424
+
1425
+ // Specify child values for map or list.
1426
+ // Map syntax: {'`$CHILD`': child-template }
1427
+ // List syntax: ['`$CHILD`', child-template ]
1428
+ const validate_CHILD: Injector = (inj: Injection, _val: any, current: any) => {
1429
+ const { mode, key, parent, keys, path } = inj
1430
+
1431
+ // Setup data structures for validation by cloning child template.
1432
+
1433
+ // Map syntax.
1434
+ if (S_MKEYPRE === mode) {
1435
+ const childtm = getprop(parent, key)
1436
+
1437
+ // Get corresponding current object.
1438
+ const pkey = getprop(path, path.length - 2)
1439
+ let tval = getprop(current, pkey)
1440
+
1441
+ if (UNDEF == tval) {
1442
+ tval = {}
1443
+ }
1444
+ else if (!ismap(tval)) {
1445
+ inj.errs.push(_invalidTypeMsg(
1446
+ slice(inj.path, -1), S_object, typify(tval), tval), 'V0220')
1447
+ return UNDEF
1448
+ }
1449
+
1450
+ const ckeys = keysof(tval)
1451
+ for (let ckey of ckeys) {
1452
+ setprop(parent, ckey, clone(childtm))
1453
+
1454
+ // NOTE: modifying inj! This extends the child value loop in inject.
1455
+ keys.push(ckey)
1456
+ }
1457
+
1458
+ // Remove $CHILD to cleanup ouput.
1459
+ // _setparentprop(inj, UNDEF)
1460
+ inj.setval(UNDEF)
1461
+ return UNDEF
1462
+ }
1463
+
1464
+ // List syntax.
1465
+ if (S_MVAL === mode) {
1466
+
1467
+ if (!islist(parent)) {
1468
+ // $CHILD was not inside a list.
1469
+ inj.errs.push('Invalid $CHILD as value')
1470
+ return UNDEF
1471
+ }
1472
+
1473
+ const childtm = getprop(parent, 1)
1474
+
1475
+ if (UNDEF === current) {
1476
+ // Empty list as default.
1477
+ parent.length = 0
1478
+ return UNDEF
1479
+ }
1480
+
1481
+ if (!islist(current)) {
1482
+ const msg = _invalidTypeMsg(
1483
+ slice(inj.path, -1), S_array, typify(current), current, 'V0230')
1484
+ inj.errs.push(msg)
1485
+ inj.keyI = parent.length
1486
+ return current
1487
+ }
1488
+
1489
+ // Clone children abd reset inj key index.
1490
+ // The inject child loop will now iterate over the cloned children,
1491
+ // validating them againt the current list values.
1492
+ current.map((_n, i) => parent[i] = clone(childtm))
1493
+ parent.length = current.length
1494
+ inj.keyI = 0
1495
+ const out = getprop(current, 0)
1496
+ return out
1497
+ }
1498
+
1499
+ return UNDEF
1500
+ }
1501
+
1502
+
1503
+ // Match at least one of the specified shapes.
1504
+ // Syntax: ['`$ONE`', alt0, alt1, ...]okI
1505
+ const validate_ONE: Injector = (
1506
+ inj: Injection,
1507
+ _val: any,
1508
+ current: any,
1509
+ _ref: string,
1510
+ store: any
1511
+ ) => {
1512
+ const { mode, parent, path, keyI, nodes } = inj
1513
+
1514
+ // Only operate in val mode, since parent is a list.
1515
+ if (S_MVAL === mode) {
1516
+ if (!islist(parent) || 0 !== keyI) {
1517
+ inj.errs.push('The $ONE validator at field ' +
1518
+ pathify(inj.path, 1, 1) +
1519
+ ' must be the first element of an array.')
1520
+ return
1521
+ }
1522
+
1523
+ inj.keyI = inj.keys.length
1524
+
1525
+ // Clean up structure, replacing [$ONE, ...] with current
1526
+ const grandparent = inj.setval(current, 2)
1527
+
1528
+ inj.path = slice(inj.path, -1)
1529
+ inj.key = getelem(inj.path, -1)
1530
+
1531
+ let tvals = slice(parent, 1)
1532
+ if (0 === tvals.length) {
1533
+ inj.errs.push('The $ONE validator at field ' +
1534
+ pathify(inj.path, 1, 1) +
1535
+ ' must have at least one argument.')
1536
+ return
1537
+ }
1538
+
1539
+ // See if we can find a match.
1540
+ for (let tval of tvals) {
1541
+
1542
+ // If match, then errs.length = 0
1543
+ let terrs: any[] = []
1544
+
1545
+ const vstore = { ...store }
1546
+ vstore.$TOP = current
1547
+ const vcurrent = validate(current, tval, vstore, terrs)
1548
+
1549
+ setprop(grandparent, getelem(path, -2), vcurrent)
1550
+
1551
+ // Accept current value if there was a match
1552
+ if (0 === terrs.length) {
1553
+ return
1554
+ }
1555
+ }
1556
+
1557
+ // There was no match.
1558
+
1559
+ const valdesc = tvals
1560
+ .map((v: any) => stringify(v))
1561
+ .join(', ')
1562
+ .replace(/`\$([A-Z]+)`/g, (_m: any, p1: string) => p1.toLowerCase())
1563
+
1564
+ inj.errs.push(_invalidTypeMsg(
1565
+ inj.path,
1566
+ (1 < tvals.length ? 'one of ' : '') + valdesc,
1567
+ typify(current), current, 'V0210'))
1568
+ }
1569
+ }
1570
+
1571
+
1572
+ const validate_EXACT: Injector = (
1573
+ inj: Injection,
1574
+ _val: any,
1575
+ current: any,
1576
+ _ref: string,
1577
+ _store: any
1578
+ ) => {
1579
+ const { mode, parent, key, keyI, path, nodes } = inj
1580
+
1581
+ // Only operate in val mode, since parent is a list.
1582
+ if (S_MVAL === mode) {
1583
+ if (!islist(parent) || 0 !== keyI) {
1584
+ inj.errs.push('The $EXACT validator at field ' +
1585
+ pathify(inj.path, 1, 1) +
1586
+ ' must be the first element of an array.')
1587
+ return
1588
+ }
1589
+
1590
+ inj.keyI = inj.keys.length
1591
+
1592
+ // Clean up structure, replacing [$EXACT, ...] with current
1593
+ inj.setval(current, 2)
1594
+
1595
+ inj.path = slice(inj.path, 0, inj.path.length - 1)
1596
+ inj.key = getelem(inj.path, -1)
1597
+
1598
+ let tvals = slice(parent, 1)
1599
+ if (0 === tvals.length) {
1600
+ inj.errs.push('The $EXACT validator at field ' +
1601
+ pathify(inj.path, 1, 1) +
1602
+ ' must have at least one argument.')
1603
+ return
1604
+ }
1605
+
1606
+ // See if we can find an exact value match.
1607
+ let currentstr: string | undefined = undefined
1608
+ for (let tval of tvals) {
1609
+ let exactmatch = tval === current
1610
+
1611
+ if (!exactmatch && isnode(tval)) {
1612
+ currentstr = undefined === currentstr ? stringify(current) : currentstr
1613
+ const tvalstr = stringify(tval)
1614
+ exactmatch = tvalstr === currentstr
1615
+ }
1616
+
1617
+ if (exactmatch) {
1618
+ return
1619
+ }
1620
+ }
1621
+
1622
+ const valdesc = tvals
1623
+ .map((v: any) => stringify(v))
1624
+ .join(', ')
1625
+ .replace(/`\$([A-Z]+)`/g, (_m: any, p1: string) => p1.toLowerCase())
1626
+
1627
+ inj.errs.push(_invalidTypeMsg(
1628
+ inj.path,
1629
+ (1 < inj.path.length ? '' : 'value ') +
1630
+ 'exactly equal to ' + (1 === tvals.length ? '' : 'one of ') + valdesc,
1631
+ typify(current), current, 'V0110'))
1632
+ }
1633
+ else {
1634
+ setprop(parent, key, UNDEF)
1635
+ }
1636
+ }
1637
+
1638
+
1639
+ // This is the "modify" argument to inject. Use this to perform
1640
+ // generic validation. Runs *after* any special commands.
1641
+ const _validation: Modify = (
1642
+ pval: any,
1643
+ key?: any,
1644
+ parent?: any,
1645
+ inj?: Injection,
1646
+ current?: any,
1647
+ _store?: any
1648
+ ) => {
1649
+
1650
+ if (UNDEF === inj) {
1651
+ return
1652
+ }
1653
+
1654
+ // Current val to verify.
1655
+ const cval = getprop(current, key)
1656
+
1657
+ if (UNDEF === cval || UNDEF === inj) {
1658
+ return
1659
+ }
1660
+
1661
+ const ptype = typify(pval)
1662
+
1663
+ // Delete any special commands remaining.
1664
+ if (S_string === ptype && pval.includes(S_DS)) {
1665
+ return
1666
+ }
1667
+
1668
+ const ctype = typify(cval)
1669
+
1670
+ // Type mismatch.
1671
+ if (ptype !== ctype && UNDEF !== pval) {
1672
+ inj.errs.push(_invalidTypeMsg(inj.path, ptype, ctype, cval, 'V0010'))
1673
+ return
1674
+ }
1675
+
1676
+ if (ismap(cval)) {
1677
+ if (!ismap(pval)) {
1678
+ inj.errs.push(_invalidTypeMsg(inj.path, ptype, ctype, cval, 'V0020'))
1679
+ return
1680
+ }
1681
+
1682
+ const ckeys = keysof(cval)
1683
+ const pkeys = keysof(pval)
1684
+
1685
+ // Empty spec object {} means object can be open (any keys).
1686
+ if (0 < pkeys.length && true !== getprop(pval, '`$OPEN`')) {
1687
+ const badkeys = []
1688
+ for (let ckey of ckeys) {
1689
+ if (!haskey(pval, ckey)) {
1690
+ badkeys.push(ckey)
1691
+ }
1692
+ }
1693
+
1694
+ // Closed object, so reject extra keys not in shape.
1695
+ if (0 < badkeys.length) {
1696
+ const msg =
1697
+ 'Unexpected keys at field ' + pathify(inj.path, 1) + ': ' + badkeys.join(', ')
1698
+ inj.errs.push(msg)
1699
+ }
1700
+ }
1701
+ else {
1702
+ // Object is open, so merge in extra keys.
1703
+ merge([pval, cval])
1704
+ if (isnode(pval)) {
1705
+ setprop(pval, '`$OPEN`', UNDEF)
1706
+ }
1707
+ }
1708
+ }
1709
+ else if (islist(cval)) {
1710
+ if (!islist(pval)) {
1711
+ inj.errs.push(_invalidTypeMsg(inj.path, ptype, ctype, cval, 'V0030'))
1712
+ }
1713
+ }
1714
+ else {
1715
+ // Spec value was a default, copy over data
1716
+ setprop(parent, key, cval)
1717
+ }
1718
+
1719
+ return
1720
+ }
1721
+
1722
+
1723
+
1724
+ // Validate a data structure against a shape specification. The shape
1725
+ // specification follows the "by example" principle. Plain data in
1726
+ // teh shape is treated as default values that also specify the
1727
+ // required type. Thus shape {a:1} validates {a:2}, since the types
1728
+ // (number) match, but not {a:'A'}. Shape {a;1} against data {}
1729
+ // returns {a:1} as a=1 is the default value of the a key. Special
1730
+ // validation commands (in the same syntax as transform ) are also
1731
+ // provided to specify required values. Thus shape {a:'`$STRING`'}
1732
+ // validates {a:'A'} but not {a:1}. Empty map or list means the node
1733
+ // is open, and if missing an empty default is inserted.
1734
+ function validate(
1735
+ data: any, // Source data to transform into new data (original not mutated)
1736
+ spec: any, // Transform specification; output follows this shape
1737
+
1738
+ extra?: any, // Additional custom checks
1739
+
1740
+ // Optionally modify individual values.
1741
+ collecterrs?: any,
1742
+ ) {
1743
+ const errs = null == collecterrs ? [] : collecterrs
1744
+
1745
+ const store = {
1746
+ // Remove the transform commands.
1747
+ $DELETE: null,
1748
+ $COPY: null,
1749
+ $KEY: null,
1750
+ $META: null,
1751
+ $MERGE: null,
1752
+ $EACH: null,
1753
+ $PACK: null,
1754
+
1755
+ $STRING: validate_STRING,
1756
+ $NUMBER: validate_NUMBER,
1757
+ $BOOLEAN: validate_BOOLEAN,
1758
+ $OBJECT: validate_OBJECT,
1759
+ $ARRAY: validate_ARRAY,
1760
+ $FUNCTION: validate_FUNCTION,
1761
+ $ANY: validate_ANY,
1762
+ $CHILD: validate_CHILD,
1763
+ $ONE: validate_ONE,
1764
+ $EXACT: validate_EXACT,
1765
+
1766
+ ...(extra || {}),
1767
+
1768
+ // A special top level value to collect errors.
1769
+ // NOTE: collecterrs paramter always wins.
1770
+ $ERRS: errs,
1771
+ }
1772
+
1773
+ const out = transform(data, spec, store, _validation)
1774
+
1775
+ const generr = (0 < errs.length && null == collecterrs)
1776
+ if (generr) {
1777
+ throw new Error('Invalid data: ' + errs.join(' | '))
1778
+ }
1779
+
1780
+ return out
1781
+ }
1782
+
1783
+
1784
+ // Internal utilities
1785
+ // ==================
1786
+
1787
+
1788
+ // Set inj.key property of inj.parent node, ensuring reference consistency
1789
+ // when needed by implementation language.
1790
+ // function _setparentprop(inj: Injection, val: any) {
1791
+ // setprop(inj.parent, inj.key, val)
1792
+ // }
1793
+
1794
+
1795
+ // Update all references to target in inj.nodes.
1796
+ function _updateAncestors(_inj: Injection, target: any, tkey: any, tval: any) {
1797
+ // SetProp is sufficient in TypeScript as target reference remains consistent even for lists.
1798
+ setprop(target, tkey, tval)
1799
+ }
1800
+
1801
+
1802
+ // Build a type validation error message.
1803
+ function _invalidTypeMsg(path: any, needtype: string, vt: string, v: any, _whence?: string) {
1804
+ let vs = null == v ? 'no value' : stringify(v)
1805
+
1806
+ return 'Expected ' +
1807
+ (1 < path.length ? ('field ' + pathify(path, 1) + ' to be ') : '') +
1808
+ needtype + ', but found ' +
1809
+ (null != v ? vt + ': ' : '') + vs +
1810
+
1811
+ // Uncomment to help debug validation errors.
1812
+ // ' [' + _whence + ']' +
1813
+
1814
+ '.'
1815
+ }
1816
+
1817
+
1818
+ // Default inject handler for transforms. If the path resolves to a function,
1819
+ // call the function passing the injection inj. This is how transforms operate.
1820
+ const _injecthandler: Injector = (
1821
+ inj: Injection,
1822
+ val: any,
1823
+ current: any,
1824
+ ref: string,
1825
+ store: any
1826
+ ): any => {
1827
+ let out = val
1828
+ const iscmd = isfunc(val) && (UNDEF === ref || ref.startsWith(S_DS))
1829
+
1830
+ // Only call val function if it is a special command ($NAME format).
1831
+ if (iscmd) {
1832
+ out = (val as Injector)(inj, val, current, ref, store)
1833
+ }
1834
+
1835
+ // Update parent with value. Ensures references remain in node tree.
1836
+ else if (S_MVAL === inj.mode && inj.full) {
1837
+ // _setparentprop(inj, val)
1838
+ inj.setval(val)
1839
+ }
1840
+
1841
+ return out
1842
+ }
1843
+
1844
+
1845
+ // Inject values from a data store into a string. Not a public utility - used by
1846
+ // `inject`. Inject are marked with `path` where path is resolved
1847
+ // with getpath against the store or current (if defined)
1848
+ // arguments. See `getpath`. Custom injection handling can be
1849
+ // provided by inj.handler (this is used for transform functions).
1850
+ // The path can also have the special syntax $NAME999 where NAME is
1851
+ // upper case letters only, and 999 is any digits, which are
1852
+ // discarded. This syntax specifies the name of a transform, and
1853
+ // optionally allows transforms to be ordered by alphanumeric sorting.
1854
+ function _injectstr(
1855
+ val: string,
1856
+ store: any,
1857
+ current?: any,
1858
+ inj?: Injection
1859
+ ): any {
1860
+ // Can't inject into non-strings
1861
+ if (S_string !== typeof val || S_MT === val) {
1862
+ return S_MT
1863
+ }
1864
+
1865
+ let out: any = val
1866
+
1867
+ // Pattern examples: "`a.b.c`", "`$NAME`", "`$NAME1`"
1868
+ const m = val.match(/^`(\$[A-Z]+|[^`]+)[0-9]*`$/)
1869
+
1870
+ // Full string of the val is an injection.
1871
+ if (m) {
1872
+ if (null != inj) {
1873
+ inj.full = true
1874
+ }
1875
+ let pathref = m[1]
1876
+
1877
+ // Special escapes inside injection.
1878
+ pathref =
1879
+ 3 < pathref.length ? pathref.replace(/\$BT/g, S_BT).replace(/\$DS/g, S_DS) : pathref
1880
+
1881
+ // Get the extracted path reference.
1882
+ out = getpath(pathref, store, current, inj)
1883
+ }
1884
+
1885
+ else {
1886
+ // Check for injections within the string.
1887
+ const partial = (_m: string, ref: string) => {
1888
+ // Special escapes inside injection.
1889
+ ref = 3 < ref.length ? ref.replace(/\$BT/g, S_BT).replace(/\$DS/g, S_DS) : ref
1890
+ if (inj) {
1891
+ inj.full = false
1892
+ }
1893
+ const found = getpath(ref, store, current, inj)
1894
+
1895
+ // Ensure inject value is a string.
1896
+ return UNDEF === found ? S_MT : S_string === typeof found ? found : JSON.stringify(found)
1897
+ }
1898
+
1899
+ out = val.replace(/`([^`]+)`/g, partial)
1900
+
1901
+ // Also call the inj handler on the entire string, providing the
1902
+ // option for custom injection.
1903
+ if (null != inj && isfunc(inj.handler)) {
1904
+ inj.full = true
1905
+ out = inj.handler(inj, out, current, val, store)
1906
+ }
1907
+ }
1908
+
1909
+ return out
1910
+ }
1911
+
1912
+
1913
+ // Define a class to mirror the JavaScript implementation
1914
+ class StructUtility {
1915
+ clone = clone
1916
+ escre = escre
1917
+ escurl = escurl
1918
+ getelem = getelem
1919
+ getpath = getpath
1920
+ getprop = getprop
1921
+ haskey = haskey
1922
+ inject = inject
1923
+ isempty = isempty
1924
+ isfunc = isfunc
1925
+ iskey = iskey
1926
+ islist = islist
1927
+ ismap = ismap
1928
+ isnode = isnode
1929
+ items = items
1930
+ joinurl = joinurl
1931
+ keysof = keysof
1932
+ merge = merge
1933
+ pad = pad
1934
+ pathify = pathify
1935
+ setprop = setprop
1936
+ size = size
1937
+ slice = slice
1938
+ strkey = strkey
1939
+ stringify = stringify
1940
+ transform = transform
1941
+ typify = typify
1942
+ validate = validate
1943
+ walk = walk
1944
+ }
1945
+
1946
+ export {
1947
+ StructUtility,
1948
+ clone,
1949
+ escre,
1950
+ escurl,
1951
+ getelem,
1952
+ getpath,
1953
+ getprop,
1954
+ haskey,
1955
+ inject,
1956
+ isempty,
1957
+ isfunc,
1958
+ iskey,
1959
+ islist,
1960
+ ismap,
1961
+ isnode,
1962
+ items,
1963
+ joinurl,
1964
+ keysof,
1965
+ merge,
1966
+ pad,
1967
+ pathify,
1968
+ setprop,
1969
+ size,
1970
+ slice,
1971
+ strkey,
1972
+ stringify,
1973
+ transform,
1974
+ typify,
1975
+ validate,
1976
+ walk,
1977
+ }
1978
+
1979
+ export type {
1980
+ Injection,
1981
+ Injector,
1982
+ WalkApply
1983
+ }