@voxgig/struct 0.1.0 → 0.2.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.
package/README.md ADDED
@@ -0,0 +1,888 @@
1
+ # Struct for TypeScript
2
+
3
+ > The canonical implementation. Every other language port matches
4
+ > the behaviour defined here. When the shared test corpus
5
+ > ([`../build/test/`](../build/test/)) and another port disagree, the
6
+ > corpus -- generated from this code -- is right.
7
+
8
+ For motivation, language-neutral concepts, and the cross-language
9
+ parity matrix, see the [top-level README](../README.md) and
10
+ [REPORT.md](../design/REPORT.md).
11
+
12
+
13
+ ## Install
14
+
15
+ ```bash
16
+ npm install @voxgig/struct
17
+ ```
18
+
19
+ Package: `@voxgig/struct`. Entry: `dist/StructUtility.js`. Types:
20
+ `dist/StructUtility.d.ts`. Module type: CommonJS.
21
+
22
+
23
+ ## Quick start
24
+
25
+ ```ts
26
+ import {
27
+ getpath, setpath, merge, walk,
28
+ inject, transform, validate, select,
29
+ } from '@voxgig/struct'
30
+
31
+ // Read a deep value.
32
+ getpath({ db: { host: 'localhost' } }, 'db.host')
33
+ // => 'localhost'
34
+
35
+ // Build by example: spec mirrors the desired output, with backtick
36
+ // references into the data.
37
+ transform(
38
+ { user: { first: 'Ada', last: 'Lovelace' }, age: 36 },
39
+ { name: '`user.first`', surname: '`user.last`', years: '`age`' }
40
+ )
41
+ // => { name: 'Ada', surname: 'Lovelace', years: 36 }
42
+
43
+ // Check the shape of incoming data.
44
+ validate(
45
+ { name: 'Ada', age: 36 },
46
+ { name: '`$STRING`', age: '`$INTEGER`' }
47
+ )
48
+ // => { name: 'Ada', age: 36 } (throws on mismatch)
49
+ ```
50
+
51
+
52
+ ## Imports
53
+
54
+ ```ts
55
+ import {
56
+ // 29 minor utilities
57
+ typename, getdef, isnode, ismap, islist, iskey, isempty, isfunc,
58
+ size, slice, pad, typify, getelem, getprop, strkey, keysof,
59
+ haskey, items, flatten, filter, escre, escurl, join, jsonify,
60
+ stringify, pathify, clone, delprop, setprop,
61
+
62
+ // 8 major utilities
63
+ walk, merge, setpath, getpath, inject, transform, validate, select,
64
+
65
+ // 2 builders
66
+ jm, jt,
67
+
68
+ // 3 injection helpers
69
+ checkPlacement, injectorArgs, injectChild,
70
+
71
+ // sentinels
72
+ SKIP, DELETE,
73
+
74
+ // 15 type bit-flags
75
+ T_any, T_noval, T_boolean, T_decimal, T_integer, T_number, T_string,
76
+ T_function, T_symbol, T_null, T_list, T_map, T_instance, T_scalar,
77
+ T_node,
78
+
79
+ // walk/inject mode flags
80
+ M_KEYPRE, M_KEYPOST, M_VAL, MODENAME,
81
+
82
+ // class wrapper
83
+ StructUtility,
84
+
85
+ // type-only
86
+ Injection,
87
+ } from '@voxgig/struct'
88
+ ```
89
+
90
+
91
+ ## Function reference
92
+
93
+ Every function is documented with its TypeScript signature, a one-line
94
+ description, and a usage example. Source:
95
+ [`src/StructUtility.ts`](./src/StructUtility.ts).
96
+
97
+ ### Predicates
98
+
99
+ ```ts
100
+ function isnode(val: any): val is Indexable
101
+ function ismap(val: any): val is { [key: string]: any }
102
+ function islist(val: any): val is any[]
103
+ function iskey(key: any): key is string | number
104
+ function isempty(val: any): boolean
105
+ function isfunc(val: any): val is Function
106
+ ```
107
+
108
+ <!-- example: minor/isnode#map -->
109
+ ```ts
110
+ isnode({ a: 1 }) // true
111
+ ```
112
+ <!-- => true -->
113
+
114
+ ```ts
115
+ isnode([1, 2]) // true
116
+ isnode('a') // false
117
+ ```
118
+
119
+ <!-- example: minor/ismap#map -->
120
+ ```ts
121
+ ismap({ a: 1 }) // true
122
+ ```
123
+
124
+ <!-- => true -->
125
+
126
+ ```ts
127
+ ismap([1]) // false
128
+ ```
129
+
130
+ <!-- example: minor/islist#list -->
131
+ ```ts
132
+ islist([1, 2]) // true
133
+ ```
134
+
135
+ <!-- => true -->
136
+
137
+ ```ts
138
+ islist({ a: 1 }) // false
139
+ ```
140
+
141
+ <!-- example: minor/iskey#str -->
142
+ ```ts
143
+ iskey('name') // true
144
+ ```
145
+
146
+ <!-- => true -->
147
+
148
+ ```ts
149
+ iskey(0) // true
150
+ iskey('') // false
151
+ iskey(true) // false
152
+ ```
153
+
154
+ <!-- example: minor/isempty#empty -->
155
+ ```ts
156
+ isempty([]) // true
157
+ ```
158
+
159
+ <!-- => true -->
160
+
161
+ ```ts
162
+ isempty(null) // true
163
+ isempty('') // true
164
+ isempty({}) // true
165
+ isempty(0) // false
166
+
167
+ isfunc(() => 1) // true
168
+ isfunc('foo') // false
169
+ ```
170
+
171
+ ### Type inspection
172
+
173
+ ```ts
174
+ function typify(value: any): number
175
+ function typename(t: number): string
176
+ ```
177
+
178
+ `typify` returns a bit-field combining a "kind" flag (`T_scalar` or
179
+ `T_node`) with a specific type flag. `typename` looks up a
180
+ human-friendly name.
181
+
182
+ <!-- example: minor/typify#int -->
183
+ ```ts
184
+ typify(1) // T_scalar | T_number | T_integer (201326720)
185
+ ```
186
+
187
+ <!-- => 201326720 -->
188
+
189
+ ```ts
190
+ typify(42) // T_scalar | T_number | T_integer
191
+ typify('hi') // T_scalar | T_string
192
+ typify(null) // T_scalar | T_null
193
+ typify(undefined) // T_noval
194
+ typify({}) // T_node | T_map
195
+ typify([]) // T_node | T_list
196
+ ```
197
+
198
+ <!-- example: minor/typename#map -->
199
+ ```ts
200
+ typename(8192) // "map" (8192 === T_map)
201
+ ```
202
+
203
+ <!-- => "map" -->
204
+
205
+ ```ts
206
+ typename(typify(42)) // "integer"
207
+ typename(typify('hi')) // "string"
208
+ typename(typify({})) // "map"
209
+ ```
210
+
211
+ ### Size, slice, pad
212
+
213
+ ```ts
214
+ function size(val: any): number
215
+ function slice<V>(val: V, start?: number, end?: number, mutate?: boolean): V
216
+ function pad(str: any, padding?: number, padchar?: string): string
217
+ ```
218
+
219
+ <!-- example: minor/size#three -->
220
+ ```ts
221
+ size([1, 2, 3]) // 3
222
+ ```
223
+ <!-- => 3 -->
224
+
225
+ ```ts
226
+ size({ a: 1, b: 2 }) // 2
227
+ size('abc') // 3
228
+ size(7.9) // 7
229
+ ```
230
+
231
+ `slice` keeps the first *N*; a negative `start` drops the last *|start|*
232
+ items, and `end` is exclusive:
233
+
234
+ <!-- example: minor/slice#mid -->
235
+ ```ts
236
+ slice([1, 2, 3, 4, 5], 1, 4) // [2, 3, 4]
237
+ ```
238
+ <!-- => [2, 3, 4] -->
239
+
240
+ <!-- example: minor/slice#strhead -->
241
+ ```ts
242
+ slice('abcdef', -3) // 'abc' (drops the last 3)
243
+ ```
244
+ <!-- => "abc" -->
245
+
246
+ ```ts
247
+ slice(10, 0, 5) // 4 (number bounding; end is exclusive)
248
+ ```
249
+
250
+ <!-- example: minor/pad#right -->
251
+ ```ts
252
+ pad('a', 3) // 'a '
253
+ ```
254
+ <!-- => "a " -->
255
+
256
+ ```ts
257
+ pad('hi', 5) // 'hi '
258
+ pad('hi', -5) // ' hi'
259
+ pad('hi', 5, '*') // 'hi***'
260
+ ```
261
+
262
+ ### Property access
263
+
264
+ ```ts
265
+ function getprop(val: any, key: any, alt?: any): any
266
+ function setprop<P>(parent: P, key: any, val: any): P
267
+ function delprop<P>(parent: P, key: any): P
268
+ function getelem(val: any, key: any, alt?: any): any
269
+ function getdef(val: any, alt: any): any
270
+ function haskey(val: any, key: any): boolean
271
+ function keysof(val: any): string[]
272
+ function items(val: any): [string, any][]
273
+ function items<T>(val: any, apply: (item: [string, any]) => T): T[]
274
+ function strkey(key?: any): string
275
+ ```
276
+
277
+ <!-- example: minor/getprop#hit -->
278
+ ```ts
279
+ getprop({ x: 1 }, 'x') // 1
280
+ ```
281
+ <!-- => 1 -->
282
+
283
+ ```ts
284
+ getprop({ a: 1 }, 'b', 'default') // 'default'
285
+ getprop([10, 20, 30], 1) // 20
286
+ ```
287
+
288
+ <!-- example: minor/setprop#set -->
289
+ ```ts
290
+ setprop({ a: 1 }, 'b', 2) // { a: 1, b: 2 }
291
+ ```
292
+
293
+ <!-- => {"a": 1, "b": 2} -->
294
+
295
+ ```ts
296
+ setprop([1, 2, 3], 0, 9) // [9, 2, 3]
297
+ ```
298
+
299
+ <!-- example: minor/delprop#del -->
300
+ ```ts
301
+ delprop({ a: 1, b: 2 }, 'a') // { b: 2 }
302
+ ```
303
+
304
+ <!-- => {"b": 2} -->
305
+
306
+ <!-- example: minor/getelem#neg -->
307
+ ```ts
308
+ getelem([10, 20, 30], -1) // 30
309
+ ```
310
+
311
+ <!-- => 30 -->
312
+
313
+ ```ts
314
+ getelem([1, 2, 3], 5, 'none') // 'none'
315
+
316
+ getdef(undefined, 'fallback') // 'fallback'
317
+ getdef('value', 'fallback') // 'value'
318
+ ```
319
+
320
+ <!-- example: minor/haskey#hit -->
321
+ ```ts
322
+ haskey({ a: 1 }, 'a') // true
323
+ ```
324
+
325
+ <!-- => true -->
326
+
327
+ ```ts
328
+ haskey({ a: undefined }, 'a') // false
329
+
330
+ keysof([10, 20, 30]) // ['0', '1', '2']
331
+ ```
332
+
333
+ <!-- example: minor/keysof#sorted -->
334
+ ```ts
335
+ keysof({ b: 4, a: 5 }) // ['a', 'b'] (sorted)
336
+ ```
337
+ <!-- => ["a", "b"] -->
338
+
339
+ <!-- example: minor/items#map -->
340
+ ```ts
341
+ items({ a: 1, b: 2 }) // [['a', 1], ['b', 2]]
342
+ ```
343
+
344
+ <!-- => [["a", 1], ["b", 2]] -->
345
+
346
+ ```ts
347
+ items([10, 20]) // [['0', 10], ['1', 20]]
348
+ items({ a: 1 }, ([k, v]) => `${k}=${v}`)
349
+ // ['a=1']
350
+ ```
351
+
352
+ <!-- example: minor/strkey#num -->
353
+ ```ts
354
+ strkey(2.2) // '2'
355
+ ```
356
+
357
+ <!-- => "2" -->
358
+
359
+ ```ts
360
+ strkey(1) // '1'
361
+ strkey('foo') // 'foo'
362
+ strkey(true) // '' (invalid keys -> '')
363
+ ```
364
+
365
+ ### Path operations
366
+
367
+ ```ts
368
+ function getpath(store: any, path: number | string | string[], injdef?: Partial<Injection>): any
369
+ function setpath(store: any, path: number | string | string[], val: any, injdef?: Partial<Injection>): any
370
+ function pathify(val: any, startin?: number, endin?: number): string
371
+ ```
372
+
373
+ <!-- example: getpath/basic#deep -->
374
+ ```ts
375
+ getpath({ a: { b: { c: 42 } } }, 'a.b.c') // 42
376
+ ```
377
+ <!-- => 42 -->
378
+
379
+ ```ts
380
+ getpath({ a: { b: { c: 42 } } }, ['a', 'b', 'c'])
381
+ getpath({ a: [10, 20] }, 'a.1') // 20
382
+ getpath({ a: 1 }, 'missing') // undefined
383
+
384
+ const store = {}
385
+ setpath(store, 'db.host', 'localhost')
386
+ // store === { db: { host: 'localhost' } }
387
+
388
+ setpath({ a: [1, 2, 3] }, 'a.1', 99)
389
+ // { a: [1, 99, 3] }
390
+ ```
391
+
392
+ <!-- example: minor/setpath#nested -->
393
+ ```ts
394
+ setpath({ a: 1, b: 2 }, 'b', 22) // { a: 1, b: 22 }
395
+ ```
396
+
397
+ <!-- => {"a": 1, "b": 22} -->
398
+
399
+ <!-- example: minor/pathify#parts -->
400
+ ```ts
401
+ pathify(['a', 'b', 'c']) // 'a.b.c'
402
+ ```
403
+
404
+ <!-- => "a.b.c" -->
405
+
406
+ ```ts
407
+ pathify('a.b.c') // 'abc' (a plain string is not split on dots)
408
+ pathify(['a', 'b', 'c'], 1) // 'b.c'
409
+ ```
410
+
411
+ ### Tree operations
412
+
413
+ ```ts
414
+ function walk(
415
+ val: any,
416
+ before?: WalkApply,
417
+ after?: WalkApply,
418
+ maxdepth?: number,
419
+ // recursive state args:
420
+ key?, parent?, path?, pool?
421
+ ): any
422
+
423
+ function merge(val: any[], maxdepth?: number): any
424
+ function clone(val: any): any
425
+ function flatten(list: any[], depth?: number): any[]
426
+ function filter(val: any, check: (item: [string, any]) => boolean): any[]
427
+
428
+ type WalkApply = (
429
+ key: string | number | undefined,
430
+ val: any,
431
+ parent: any,
432
+ path: string[]
433
+ ) => any
434
+ ```
435
+
436
+ ```ts
437
+ // Replace nulls with 'DEFAULT' on ascend.
438
+ walk(tree, undefined, (key, val, parent, path) =>
439
+ val === null ? 'DEFAULT' : val
440
+ )
441
+ ```
442
+
443
+ Last input wins; maps deep-merge; lists merge by index:
444
+
445
+ <!-- example: merge#basic -->
446
+ ```ts
447
+ merge([
448
+ { a: 1, b: 2, k: [10, 20], x: { y: 5, z: 6 } },
449
+ { b: 3, d: 4, e: 8, k: [11], x: { y: 7 } },
450
+ ])
451
+ // { a: 1, b: 3, d: 4, e: 8, k: [11, 20], x: { y: 7, z: 6 } }
452
+ ```
453
+
454
+ <!-- => {"a": 1, "b": 3, "d": 4, "e": 8, "k": [11, 20], "x": {"y": 7, "z": 6}} -->
455
+
456
+ <!-- example: minor/clone#deep -->
457
+ ```ts
458
+ clone({ a: { b: [1, 2] } }) // { a: { b: [1, 2] } } (a deep copy)
459
+ ```
460
+
461
+ <!-- => {"a": {"b": [1, 2]}} -->
462
+
463
+ <!-- example: minor/flatten#nested -->
464
+ ```ts
465
+ flatten([1, [2, [3]]]) // [1, 2, [3]] (one level by default)
466
+ ```
467
+
468
+ <!-- => [1, 2, [3]] -->
469
+
470
+ ```ts
471
+ flatten([1, [2, [3, [4]]]]) // [1, 2, [3, [4]]]
472
+ flatten([1, [2, [3, [4]]]], 2) // [1, 2, 3, [4]]
473
+ ```
474
+
475
+ `filter` passes each `[key, value]` pair to the check and returns the
476
+ matching **values** (not the pairs):
477
+
478
+ <!-- example: minor/filter#gt3 -->
479
+ ```ts
480
+ filter([1, 2, 3, 4, 5], ([k, v]) => v > 3)
481
+ // [4, 5]
482
+ ```
483
+ <!-- => [4, 5] -->
484
+
485
+ ### String / URL / JSON
486
+
487
+ ```ts
488
+ function escre(s: string): string
489
+ function escurl(s: string): string
490
+ function join(arr: any[], sep?: string, url?: boolean): string
491
+ function jsonify(val: any, flags?: { indent?: number, offset?: number }): string
492
+ function stringify(val: any, maxlen?: number, pretty?: any): string
493
+ ```
494
+
495
+ <!-- example: minor/escre#dots -->
496
+ ```ts
497
+ escre('a.b+c') // 'a\\.b\\+c'
498
+ ```
499
+
500
+ <!-- => "a\\.b\\+c" -->
501
+
502
+ <!-- example: minor/escurl#space -->
503
+ ```ts
504
+ escurl('hello world?') // 'hello%20world%3F'
505
+ ```
506
+
507
+ <!-- => "hello%20world%3F" -->
508
+
509
+ <!-- example: minor/join#sep -->
510
+ ```ts
511
+ join(['a', 'b', 'c'], '/') // 'a/b/c'
512
+ ```
513
+
514
+ <!-- => "a/b/c" -->
515
+
516
+ ```ts
517
+ join(['http:', '/foo/', '/bar'], '/', true)
518
+ // 'http:/foo/bar' (URL-mode collapses)
519
+ ```
520
+
521
+ `jsonify` pretty-prints by default (indent 2); pass `{ indent: 0 }` for the
522
+ compact form:
523
+
524
+ <!-- example: minor/jsonify#map -->
525
+ ```ts
526
+ jsonify({ a: 1 })
527
+ // {
528
+ // "a": 1
529
+ // }
530
+ ```
531
+ <!-- => "{\n \"a\": 1\n}" -->
532
+
533
+ <!-- example: minor/jsonify#compact -->
534
+ ```ts
535
+ jsonify({ a: 1, b: 2 }, { indent: 0 }) // '{"a":1,"b":2}'
536
+ ```
537
+ <!-- => "{\"a\":1,\"b\":2}" -->
538
+
539
+ `stringify` is the compact, quote-light form — keys are sorted and object
540
+ braces are kept; the second argument caps the length (the `...` counts):
541
+
542
+ <!-- example: minor/stringify#brace -->
543
+ ```ts
544
+ stringify({ a: 1, b: [2, 3] }) // '{a:1,b:[2,3]}'
545
+ ```
546
+ <!-- => "{a:1,b:[2,3]}" -->
547
+
548
+ <!-- example: minor/stringify#max -->
549
+ ```ts
550
+ stringify('verylongstring', 5) // 've...'
551
+ ```
552
+ <!-- => "ve..." -->
553
+
554
+ ### Injection / transform / validate / select
555
+
556
+ ```ts
557
+ function inject(
558
+ val: any,
559
+ store: any,
560
+ injdef?: Partial<Injection>,
561
+ ): any
562
+
563
+ function transform(
564
+ data: any, // source data
565
+ spec: any, // by-example output shape
566
+ injdef?: Partial<Injection>
567
+ ): any
568
+
569
+ function validate(
570
+ data: any, // input to check
571
+ spec: any, // expected shape with checker tokens
572
+ injdef?: Partial<Injection>
573
+ ): any
574
+
575
+ function select(children: any, query: any): any[]
576
+ ```
577
+
578
+ <!-- example: inject#basic -->
579
+ ```ts
580
+ // Backtick refs in strings are replaced by store values.
581
+ inject({ x: '`a`', y: 2 }, { a: 1 }) // { x: 1, y: 2 }
582
+ ```
583
+
584
+ <!-- => {"x": 1, "y": 2} -->
585
+
586
+ ```ts
587
+ inject(
588
+ { greeting: 'hello `name`', age: '`years`' },
589
+ { name: 'Ada', years: 36 }
590
+ )
591
+ // { greeting: 'hello Ada', age: 36 }
592
+
593
+ // Build a result by example.
594
+ transform(
595
+ { hold: { x: 1 }, top: 99 },
596
+ { a: '`hold.x`', b: '`top`' }
597
+ )
598
+ // { a: 1, b: 99 }
599
+ ```
600
+
601
+ Transform commands drive structural ops. A command like `$EACH` appears in
602
+ **value** position — as the first element of a list `['`$EACH`', path, subspec]`
603
+ — mapping the sub-spec over every entry at `path`:
604
+
605
+ <!-- example: transform/each#basic -->
606
+ ```ts
607
+ transform(
608
+ { v: 1, a: [{ q: 13 }, { q: 23 }] },
609
+ { x: { y: ['`$EACH`', 'a', { q: '`$COPY`', r: '`.q`', p: '`...v`' }] } }
610
+ )
611
+ // { x: { y: [ { q: 13, r: 13, p: 1 }, { q: 23, r: 23, p: 1 } ] } }
612
+ ```
613
+ <!-- => {"x": {"y": [{"q": 13, "r": 13, "p": 1}, {"q": 23, "r": 23, "p": 1}]}} -->
614
+
615
+ Putting a command in **key** position (or, for `$APPLY`, directly under a map)
616
+ is an error — commands must be list values:
617
+
618
+ <!-- example: transform/apply#badkey -->
619
+ ```ts
620
+ transform({}, { x: '`$APPLY`' })
621
+ // throws: $APPLY: invalid placement in parent map, expected: list.
622
+ ```
623
+ <!-- throws: invalid placement in parent map -->
624
+
625
+ <!-- example: validate#shape -->
626
+ ```ts
627
+ // Validate against a shape (throws on mismatch).
628
+ validate(
629
+ { name: 'Ada', age: 36 },
630
+ { name: '`$STRING`', age: '`$INTEGER`' }
631
+ )
632
+ // { name: 'Ada', age: 36 }
633
+ ```
634
+
635
+ <!-- => {"name": "Ada", "age": 36} -->
636
+
637
+ <!-- example: select#query -->
638
+ ```ts
639
+ // Find children matching a query.
640
+ select(
641
+ { a: { name: 'Alice', age: 30 }, b: { name: 'Bob', age: 25 } },
642
+ { age: 30 }
643
+ )
644
+ // [{ name: 'Alice', age: 30, $KEY: 'a' }]
645
+ ```
646
+
647
+ <!-- => [{"name": "Alice", "age": 30, "$KEY": "a"}] -->
648
+
649
+ ### Builders
650
+
651
+ ```ts
652
+ function jm(...kv: any[]): Record<string, any>
653
+ function jt(...v: any[]): any[]
654
+ ```
655
+
656
+ ```ts
657
+ jm('a', 1, 'b', 2) // { a: 1, b: 2 }
658
+ jt(1, 2, 3) // [1, 2, 3]
659
+ ```
660
+
661
+ Useful for building literal-looking JSON shapes inside expressions.
662
+
663
+ ### Injection helpers
664
+
665
+ These are exposed for callers writing custom injectors or modify
666
+ hooks; most users will not need them directly.
667
+
668
+ ```ts
669
+ function checkPlacement(
670
+ modes: number, // bitmask of M_KEYPRE | M_KEYPOST | M_VAL
671
+ ijname: string, // injection name (transform/validate command)
672
+ parentTypes: number, // expected parent types
673
+ inj: Injection
674
+ ): boolean
675
+
676
+ function injectorArgs(argTypes: number[], args: any[]): any
677
+ function injectChild(child: any, store: any, inj: Injection): Injection
678
+ ```
679
+
680
+
681
+ ## Constants
682
+
683
+ ### Sentinels
684
+
685
+ ```ts
686
+ SKIP // emit nothing for this key
687
+ DELETE // remove this key from the parent
688
+ ```
689
+
690
+ Returned from a transform / inject step to signal these structural
691
+ operations to the caller.
692
+
693
+ ### Type bit-flags
694
+
695
+ `typify(val)` returns a bit-field combining a kind flag with a
696
+ specific type:
697
+
698
+ ```ts
699
+ T_any // wildcard / no constraint
700
+ T_noval // property absent / undefined (NOT a scalar)
701
+ T_boolean // boolean scalar
702
+ T_decimal // non-integer numeric scalar
703
+ T_integer // integer numeric scalar
704
+ T_number // any number (set together with T_integer/T_decimal)
705
+ T_string // string scalar
706
+ T_function // function value
707
+ T_symbol // symbolic atom (for languages that have them)
708
+ T_null // JSON null (distinct from absent)
709
+ T_list // list node (array)
710
+ T_map // map node (object)
711
+ T_instance // class instance (non-plain object)
712
+ T_scalar // bit set on every scalar type
713
+ T_node // bit set on every node type
714
+ ```
715
+
716
+ ```ts
717
+ const t = typify('hi')
718
+ 0 < (T_string & t) // true
719
+ 0 < (T_scalar & t) // true
720
+ typename(t) // 'string'
721
+ ```
722
+
723
+ ### Walk / inject phase flags
724
+
725
+ ```ts
726
+ M_KEYPRE // about to descend into a child by key
727
+ M_KEYPOST // returned from descending into a child by key
728
+ M_VAL // visiting the value of a leaf
729
+ MODENAME // string[] — human names by mode flag
730
+ ```
731
+
732
+
733
+ ## Transform commands
734
+
735
+ Quote inside a `transform` spec, e.g. `` '`$COPY`' ``.
736
+
737
+ | Command | Purpose |
738
+ |-----------|-------------------------------------------------------------------|
739
+ | `$DELETE` | Remove the current key from the output. |
740
+ | `$COPY` | Copy the matching value from `data` at the current path. |
741
+ | `$KEY` | Emit the current key under another name. |
742
+ | `$ANNO` | Annotate the current node with extra fields. |
743
+ | `$MERGE` | Deep-merge several sub-specs into the current node. |
744
+ | `$EACH` | Apply a sub-spec to every entry of a list or map. |
745
+ | `$PACK` | Repack a node by rewriting its keys / shape. |
746
+ | `$REF` | Resolve a named reference inside the spec. |
747
+ | `$FORMAT` | Render a templated string using values from `data`. |
748
+ | `$APPLY` | Call a function (from `extra` / `injdef`) on the current value. |
749
+ | `$DS` | Emit a literal `$` (escape the dollar sign). |
750
+ | `$WHEN` | Insert the current date and time as an ISO-8601 string. |
751
+
752
+
753
+ ## Validate checkers
754
+
755
+ Quote inside a `validate` spec, e.g. `` '`$STRING`' ``.
756
+
757
+ | Checker | Accepts |
758
+ |-------------|-----------------------------------------------------------------|
759
+ | `$MAP` | A map. |
760
+ | `$LIST` | A list. |
761
+ | `$STRING` | A string. |
762
+ | `$NUMBER` | A number (integer or decimal). |
763
+ | `$INTEGER` | An integer. |
764
+ | `$DECIMAL` | A non-integer number. |
765
+ | `$BOOLEAN` | A boolean. |
766
+ | `$NULL` | JSON null. |
767
+ | `$NIL` | Null or absent (lenient). |
768
+ | `$FUNCTION` | A callable function. |
769
+ | `$INSTANCE` | A class instance. |
770
+ | `$ANY` | Any value (placeholder for "no constraint"). |
771
+ | `$CHILD` | Apply a sub-spec to every direct child. |
772
+ | `$ONE` | Match exactly one of a list of alternative sub-specs. |
773
+ | `$EXACT` | Match a literal value exactly (no shape coercion). |
774
+
775
+
776
+ ## `StructUtility` class
777
+
778
+ Wraps every function and constant as instance properties. Useful
779
+ when you want to inject the API surface (e.g. for stubbing in tests):
780
+
781
+ ```ts
782
+ import { StructUtility } from '@voxgig/struct'
783
+
784
+ const su = new StructUtility()
785
+ su.getpath({ a: { b: 1 } }, 'a.b') // 1
786
+ su.merge([{ a: 1 }, { b: 2 }]) // { a: 1, b: 2 }
787
+ ```
788
+
789
+
790
+ ## Notes
791
+
792
+ ### `null` versus `undefined`
793
+
794
+ TypeScript distinguishes the two; `struct` preserves the
795
+ distinction:
796
+
797
+ - `undefined` means "absent". `getprop` returns `undefined` for a
798
+ missing key, and most predicates treat `undefined` as not-a-node.
799
+ - `null` is the JSON null value -- a defined scalar. `typify(null)`
800
+ returns `T_scalar | T_null`.
801
+
802
+ Most JSON parsers conflate them; if your data source returns `null`
803
+ for absent fields, convert them before passing into `struct` -- or
804
+ adopt the `'__NULL__'` placeholder used by the shared test corpus.
805
+
806
+ ### Lists are mutable and reference-stable
807
+
808
+ `walk`, `merge`, `inject`, and `setpath` all rely on lists being
809
+ reference-stable: a mutation through one reference is visible to
810
+ every holder. This is JavaScript's natural behaviour; no wrapper
811
+ needed.
812
+
813
+ ### Path syntax
814
+
815
+ Paths can be:
816
+
817
+ - a dot-separated string: `'a.b.0.c'`
818
+ - an array: `['a', 'b', 0, 'c']`
819
+
820
+ Integer-looking string keys index into lists; everything else
821
+ indexes maps.
822
+
823
+ ### `walk` paths are reused
824
+
825
+ The `path` array passed to a `WalkApply` callback is reused across
826
+ calls (one shared array per depth). Clone it (`path.slice()`) if
827
+ you need to retain it past the callback.
828
+
829
+
830
+ ## Regex
831
+
832
+ The library exposes a uniform six-function regex API across every
833
+ port (see `/design/REGEX_API.md` for the contract and `/design/REGEX.md` for the
834
+ supported dialect). On TypeScript the canonical implementation is
835
+ ECMAScript `RegExp`.
836
+
837
+ ### API
838
+
839
+ | Function | Maps to |
840
+ |---|---|
841
+ | `re_compile(pattern, flags?)` | `new RegExp(pattern, flags ?? 'g')` |
842
+ | `re_test(pattern, input)` | `pattern.test(input)` |
843
+ | `re_find(pattern, input)` | `input.match(pattern)` (non-global pattern) |
844
+ | `re_find_all(pattern, input)` | `[...input.matchAll(pattern)]` |
845
+ | `re_replace(pattern, input, rep)` | `input.replace(pattern, rep)` (global pattern) |
846
+ | `re_escape(s)` | escape `[.*+?^${}()|[\]\\]` in `s` |
847
+
848
+ ### Dialect
849
+
850
+ Patterns must stay inside the **RE2 subset** documented in `/design/REGEX.md`:
851
+ literals + escapes, `.`, `^`/`$`, `* + ? {n} {n,} {n,m}` (greedy + lazy),
852
+ character classes incl. `\d \w \s` etc., `\b`/`\B`, `(...)` / `(?:...)` /
853
+ `(?<name>...)`, alternation. ECMAScript `RegExp` supports backreferences
854
+ and lookaround, but other ports do not — using those will not be
855
+ portable.
856
+
857
+ ### Sharp edges
858
+
859
+ - **Catastrophic backtracking.** ECMAScript `RegExp` uses backtracking;
860
+ nested quantifiers (e.g. `(a+)+`) against a non-matching suffix can be
861
+ exponential in the input length. The discovery panel measures ~180 ms
862
+ on Node 22 for `^(a+)+$` against 22 a's plus `!`. RE2-style engines
863
+ finish the same case in under 0.1 ms. Write linear-friendly patterns
864
+ (`a+` instead of `(a+)+`) and keep injected user input in
865
+ character classes, not in alternations.
866
+ - **Zero-width `replace`.** `re_replace("a*", "abc", "X")` returns
867
+ `"XXbXcX"` here — the ECMA convention shared by every port whose
868
+ host engine is PCRE/ECMA/.NET/Java/Onigmo, plus the in-tree
869
+ Thompson NFA ports (Rust / C / Lua / Zig). Go is the exception:
870
+ RE2 returns `"XbXcX"`. Don't rely on cross-port identity of
871
+ zero-width replacement output — see `/design/REGEX_PATHOLOGICAL.md`.
872
+
873
+ See `/design/REGEX_PATHOLOGICAL.md` for the cross-port pathological-input
874
+ panel and per-port outcomes.
875
+
876
+
877
+ ## Build and test
878
+
879
+ ```bash
880
+ cd typescript
881
+ npm install
882
+ npm run build # tsc -> dist/
883
+ npm test # node --test on dist-test/
884
+ ```
885
+
886
+ Tests live in [`test/`](./test/) and read fixtures from
887
+ [`../build/test/`](../build/test/). The test runner consumes the
888
+ shared JSONIC corpus shared by every language port.