@voxgig/struct-js 0.1.7 → 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.
Files changed (3) hide show
  1. package/README.md +27 -7
  2. package/package.json +1 -1
  3. package/src/struct.js +857 -163
package/README.md CHANGED
@@ -56,8 +56,9 @@ module.exports = {
56
56
  // 6 regex functions
57
57
  re_compile, re_find, re_find_all, re_replace, re_test, re_escape,
58
58
 
59
- // 42 utility functions (48 canonical = these 42 + the 6 re_* above)
60
- clone, delprop, escre, escurl, filter, flatten, getdef, getelem,
59
+ // 46 utility functions (52 canonical = these 46 + the 6 re_* above)
60
+ clone, condense, condenseview, expand, iscondensed, delprop, escre,
61
+ escurl, filter, flatten, getdef, getelem,
61
62
  getpath, getprop, haskey, inject, isempty, isfunc, iskey, islist,
62
63
  ismap, isnode, items, join, jsonify, keysof, merge, pad, pathify,
63
64
  select, setpath, setprop, size, slice, strkey, stringify,
@@ -613,8 +614,27 @@ Used as backtick-quoted strings inside a `validate` spec.
613
614
 
614
615
  ```
615
616
  $MAP $LIST $STRING $NUMBER $INTEGER $DECIMAL $BOOLEAN
616
- $NULL $NIL $FUNCTION $INSTANCE $ANY $CHILD $ONE $EXACT
617
- ```
617
+ $NULL $NIL $FUNCTION $INSTANCE $ANY $CHILD $EXACT
618
+ $NOF $ALL $LEN $RANGE $LIKE
619
+ ```
620
+
621
+ `` ['`$NOF`', n, spec, …] `` holds when as many specs admit the value as `n`
622
+ allows, where `n` is an integer or an object with `min`, `max` or both;
623
+ `` ['`$ALL`', spec, …] `` holds when every spec admits it. There is no
624
+ `$ONE`: write `` ['`$ONE`', a, b] `` as `` ['`$NOF`', { min: 1 }, a, b] ``.
625
+ `` ['`$LEN`', n, spec?] `` holds when the value's length is within `n`, a
626
+ bound written as for `$NOF`: a string counts code points (not the UTF-16
627
+ units `.length` counts), an array its elements, and an object its keys.
628
+ `` ['`$RANGE`', bound, spec?] `` holds when the value is a number within
629
+ `bound`, an object of `min` or `gt` and `max` or `lt`.
630
+ `` ['`$LIKE`', pattern, spec?] `` holds when the value is a string the
631
+ pattern finds, with JavaScript's `RegExp`, anywhere in it unless the
632
+ pattern is anchored. `$LEN`, `$RANGE` and `$LIKE` take at most one spec,
633
+ which must also admit the value. `min` and `max` include their bound, while
634
+ `gt` and `lt` exclude it.
635
+ A spec that names any other checker, such as the misspelling
636
+ `` '`$string`' ``, is rejected before any data is read. See the
637
+ [top-level README](../README.md) for what each checker accepts.
618
638
 
619
639
 
620
640
  ## Notes
@@ -638,7 +658,7 @@ JavaScript arrays satisfy this natively.
638
658
 
639
659
  ### Difference from canonical TypeScript
640
660
 
641
- The exported function surface is identical (48 canonical functions,
661
+ The exported function surface is identical (52 canonical functions,
642
662
  including the six `re_*` regex helpers). The only export difference is
643
663
  `Injection`: the JS port exports it as a runtime value, whereas TypeScript
644
664
  exports it only as a type. Otherwise functionally identical -- both run on
@@ -646,7 +666,7 @@ V8.
646
666
 
647
667
  ### Test status
648
668
 
649
- 90/90 tests pass against the shared corpus.
669
+ 119/119 tests pass against the shared corpus.
650
670
 
651
671
 
652
672
  ## Regex
@@ -658,7 +678,7 @@ this is the ECMAScript `RegExp` built-in.
658
678
 
659
679
  | Function | Maps to |
660
680
  |---|---|
661
- | `re_compile(pattern, flags?)` | `new RegExp(pattern, flags ?? 'g')` |
681
+ | `re_compile(pattern, flags?)` | `new RegExp(pattern, flags)` |
662
682
  | `re_test(pattern, input)` | `pattern.test(input)` |
663
683
  | `re_find(pattern, input)` | `input.match(pattern)` (non-global pattern) |
664
684
  | `re_find_all(pattern, input)` | `[...input.matchAll(pattern)]` |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@voxgig/struct-js",
3
- "version": "0.1.7",
3
+ "version": "0.2.0",
4
4
  "description": "JSON data structure manipulations — JavaScript port",
5
5
  "main": "src/struct.js",
6
6
  "type": "commonjs",
package/src/struct.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /* Copyright (c) 2025-2026 Voxgig Ltd. MIT LICENSE. */
2
- // VERSION: @voxgig/struct-js 0.1.7
2
+ // VERSION: @voxgig/struct-js 0.2.0
3
3
  /* Voxgig Struct
4
4
  * =============
5
5
  *
@@ -149,7 +149,7 @@ const NONE = undefined
149
149
  const SKIP = { '`$SKIP`': true }
150
150
  const DELETE = { '`$DELETE`': true }
151
151
  // Regular expression constants
152
- const R_INTEGER_KEY = /^[-0-9]+$/ // Match integer keys (including <0).
152
+ const R_INTEGER_KEY = /^(0|-?[1-9][0-9]*)$/ // Integer keys as String(n) prints them (including <0).
153
153
  const R_ESCAPE_REGEXP = /[.*+?^${}()|[\]\\]/g // Chars that need escaping in regexp.
154
154
  const R_QUOTES = /"/g // Double quotes for removal.
155
155
  const R_DOT = /\./g // Dots in path strings.
@@ -158,6 +158,7 @@ const R_META_PATH = /^([^$]+)\$([=~])(.+)$/ // Meta path syntax.
158
158
  const R_DOUBLE_DOLLAR = /\$\$/g // Double dollar escape sequence.
159
159
  const R_TRANSFORM_NAME = /`\$([A-Z]+)`/g // Transform command names.
160
160
  const R_INJECTION_FULL = /^`(\$[A-Z]+|[^`]*)[0-9]*`$/ // Full string injection pattern.
161
+ const R_CHECKER_NAME = /^\$[A-Z]+$/ // Validate checker name.
161
162
  const R_BT_ESCAPE = /\$BT/g // Backtick escape sequence.
162
163
  const R_DS_ESCAPE = /\$DS/g // Dollar sign escape sequence.
163
164
  const R_INJECTION_PARTIAL = /`([^`]+)`/g // Partial string injection pattern.
@@ -334,20 +335,52 @@ function typify(value) {
334
335
  // Anything else (e.g. bigint) is considered T_any
335
336
  return T_any
336
337
  }
337
- // Get a list element. The key should be an integer, or a string
338
- // 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) {
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
+ // The stored value; a plain map yields own properties only, never __proto__.
346
+ function _readprop(val, key) {
347
+ if (islist(val)) {
348
+ const keyI = _listkey(key)
349
+ return 0 <= keyI ? val[keyI] : NONE
350
+ }
351
+ if (S_string !== typeof key && S_number !== typeof key) {
352
+ return NONE
353
+ }
354
+ if (0 < (T_instance & typify(val))) {
355
+ return val[key]
356
+ }
357
+ return Object.prototype.hasOwnProperty.call(val, key) ? val[key] : NONE
358
+ }
359
+ function _setown(obj, key, val) {
360
+ if ('__proto__' === key) {
361
+ Object.defineProperty(obj, key, {
362
+ value: val,
363
+ enumerable: true,
364
+ writable: true,
365
+ configurable: true,
366
+ })
367
+ } else {
368
+ obj[key] = val
369
+ }
370
+ }
371
+ // Get a list element; a negative integer key counts from the end.
339
372
  function getelem(val, key, alt) {
340
373
  let out = NONE
341
374
  if (NONE === val || NONE === key) {
342
375
  return alt
343
376
  }
344
377
  if (islist(val)) {
345
- let nkey = parseInt(key)
346
- if (Number.isInteger(nkey) && ('' + key).match(R_INTEGER_KEY)) {
347
- if (nkey < 0) {
348
- key = val.length + nkey
349
- }
350
- out = val[key]
378
+ let keyI = _listkey(key)
379
+ if (keyI < 0) {
380
+ keyI = val.length + keyI
381
+ }
382
+ if (0 <= keyI) {
383
+ out = val[keyI]
351
384
  }
352
385
  }
353
386
  // Group A: a stored JSON null is treated as "no value".
@@ -364,7 +397,7 @@ function getprop(val, key, alt) {
364
397
  return alt
365
398
  }
366
399
  if (isnode(val)) {
367
- out = val[key]
400
+ out = _readprop(val, key)
368
401
  }
369
402
  if (null == out) {
370
403
  return alt
@@ -376,7 +409,7 @@ function getprop(val, key, alt) {
376
409
  // absent. Group A's getprop conflates them.
377
410
  function _lookup(val, key) {
378
411
  if (NONE === val || NONE === key) return NONE
379
- if (isnode(val)) return val[key]
412
+ if (isnode(val)) return _readprop(val, key)
380
413
  return NONE
381
414
  }
382
415
  // Convert different types of keys to string representation.
@@ -709,7 +742,7 @@ function jm(...kv) {
709
742
  // with value null" from "slot beyond end of kv".
710
743
  let k = i < kv.length ? kv[i] : '$KEY' + i
711
744
  k = 'string' === typeof k ? k : stringify(k)
712
- o[k] = i + 1 < kv.length ? kv[i + 1] : null
745
+ _setown(o, k, i + 1 < kv.length ? kv[i + 1] : null)
713
746
  }
714
747
  return o
715
748
  }
@@ -732,16 +765,19 @@ function delprop(parent, key) {
732
765
  if (!iskey(key)) {
733
766
  return parent
734
767
  }
768
+ if (iscondensed(parent)) {
769
+ throw new Error(
770
+ 'struct: condensed structures are immutable - ' + 'expand() first, then modify the copy',
771
+ )
772
+ }
735
773
  if (ismap(parent)) {
736
774
  key = strkey(key)
737
775
  delete parent[key]
738
776
  } else if (islist(parent)) {
739
- // Ensure key is an integer.
740
- let keyI = +key
777
+ const keyI = _listkey(key)
741
778
  if (isNaN(keyI)) {
742
779
  return parent
743
780
  }
744
- keyI = Math.floor(keyI)
745
781
  // Delete list element at position keyI, shifting later elements down.
746
782
  const psize = size(parent)
747
783
  if (0 <= keyI && keyI < psize) {
@@ -762,18 +798,18 @@ function setprop(parent, key, val) {
762
798
  if (!iskey(key)) {
763
799
  return parent
764
800
  }
801
+ if (iscondensed(parent)) {
802
+ throw new Error(
803
+ 'struct: condensed structures are immutable - ' + 'expand() first, then modify the copy',
804
+ )
805
+ }
765
806
  if (ismap(parent)) {
766
- key = S_MT + key
767
- const pany = parent
768
- pany[key] = val
807
+ _setown(parent, S_MT + key, val)
769
808
  } else if (islist(parent)) {
770
- // Ensure key is an integer.
771
- let keyI = +key
809
+ const keyI = _listkey(key)
772
810
  if (isNaN(keyI)) {
773
811
  return parent
774
812
  }
775
- keyI = Math.floor(keyI)
776
- // TODO: DELETE list element
777
813
  // Set or append value at position keyI, or append if keyI out of bounds.
778
814
  if (0 <= keyI) {
779
815
  parent[slice(keyI, 0, size(parent) + 1)] = val
@@ -930,6 +966,12 @@ function merge(val, maxdepth) {
930
966
  // Set a value using a path. Missing path parts are created.
931
967
  // String paths create only maps. Use a string list to create list parts.
932
968
  function setpath(store, path, val, injdef) {
969
+ // Same contract as setprop/delprop: a condensed store is immutable.
970
+ if (iscondensed(store)) {
971
+ throw new Error(
972
+ 'struct: condensed structures are immutable - ' + 'expand() first, then modify the copy',
973
+ )
974
+ }
933
975
  const pathType = typify(path)
934
976
  const parts =
935
977
  0 < (T_list & pathType)
@@ -963,16 +1005,45 @@ function setpath(store, path, val, injdef) {
963
1005
  }
964
1006
  function getpath(store, path, injdef) {
965
1007
  // Operate on a string array.
966
- const parts = islist(path)
967
- ? path
968
- : 'string' === typeof path
969
- ? path.split(S_DT)
970
- : 'number' === typeof path
971
- ? [strkey(path)]
972
- : NONE
1008
+ let parts = NONE
1009
+ if (islist(path)) {
1010
+ parts = []
1011
+ for (const part of path) {
1012
+ if (S_number === typeof part) {
1013
+ parts.push(S_MT + part)
1014
+ } else if (S_string === typeof part) {
1015
+ parts.push(part)
1016
+ } else {
1017
+ return NONE
1018
+ }
1019
+ }
1020
+ } else if (S_string === typeof path) {
1021
+ parts = path.split(S_DT)
1022
+ } else if (S_number === typeof path) {
1023
+ parts = [S_MT + path]
1024
+ }
973
1025
  if (NONE === parts) {
974
1026
  return NONE
975
1027
  }
1028
+ // TRANSPARENT CONDENSED READ. A condensed store answers the same path with
1029
+ // the same value as the ordinary node it was built from - the caller does
1030
+ // not need to know which it holds. Only the nodes ON the path are touched,
1031
+ // so this never materialises the whole structure.
1032
+ if (iscondensed(store)) {
1033
+ // The fast path applies only when there are no injection options to
1034
+ // honour. base/dparent/dpath/meta change what the walk below resolves
1035
+ // against, and silently ignoring them would make a condensed store
1036
+ // answer differently from the node it was built from - the opposite of
1037
+ // the transparent-read contract. Rare enough to be worth materialising.
1038
+ if (null == injdef || null == getprop(injdef, S_base)) {
1039
+ const found = condenseResolve(store, store[S_condroot], parts)
1040
+ const val = 0 > found ? undefined : condenseMaterialise(store, found)
1041
+ // Group A null-as-absent: an ordinary getpath observes a stored null
1042
+ // through getprop and reports it as absent, so this must too.
1043
+ return null == val ? undefined : val
1044
+ }
1045
+ store = expand(store)
1046
+ }
976
1047
  // let root = store
977
1048
  let val = store
978
1049
  const base = getprop(injdef, S_base)
@@ -1385,8 +1456,7 @@ const transform_PACK = (inj, _val, _ref, store) => {
1385
1456
  // TODO: not found ref should removed key (setprop NONE)
1386
1457
  // Reference original spec (enables recursice transformations)
1387
1458
  // Format: ['`$REF`', '`spec-path`']
1388
- const transform_REF = (inj, val, _ref, store) => {
1389
- const { nodes } = inj
1459
+ const transform_REF = (inj, _val, _ref, store) => {
1390
1460
  if (M_VAL !== inj.mode) {
1391
1461
  return NONE
1392
1462
  }
@@ -1397,10 +1467,7 @@ const transform_REF = (inj, val, _ref, store) => {
1397
1467
  const spec = getprop(store, S_DSPEC)()
1398
1468
  const dpath = slice(inj.path, 1)
1399
1469
  const ref = getpath(spec, refpath, {
1400
- // TODO: test relative refs
1401
- // dpath: inj.path.slice(1),
1402
1470
  dpath,
1403
- // dparent: getpath(spec, inj.path.slice(1))
1404
1471
  dparent: getpath(spec, dpath),
1405
1472
  })
1406
1473
  let hasSubRef = false
@@ -1412,30 +1479,20 @@ const transform_REF = (inj, val, _ref, store) => {
1412
1479
  return v
1413
1480
  })
1414
1481
  }
1415
- let tref = clone(ref)
1416
- const cpath = slice(inj.path, -3)
1417
- const tpath = slice(inj.path, -1)
1418
- let tcur = getpath(store, cpath)
1419
- let tval = getpath(store, tpath)
1420
- let rval = NONE
1421
- if (!hasSubRef || NONE !== tval) {
1422
- const tinj = inj.child(0, [getelem(tpath, -1)])
1423
- tinj.path = tpath
1424
- tinj.nodes = slice(inj.nodes, -1)
1425
- tinj.parent = getelem(nodes, -2)
1426
- tinj.val = tref
1427
- tinj.dpath = flatten([cpath])
1428
- tinj.dparent = tcur
1429
- inject(tref, store, tinj)
1430
- rval = tinj.val
1431
- } else {
1432
- rval = NONE
1433
- }
1482
+ // A recursive reference stops where the data does.
1483
+ const tval = getpath(store, slice(inj.path, -1))
1484
+ const rval = !hasSubRef || NONE !== tval ? clone(ref) : NONE
1485
+ // The enclosing loop injects the referenced spec in this list's place, so
1486
+ // neither this pass nor this element leaves a value for modify to check.
1434
1487
  const grandparent = inj.setval(rval, 2)
1435
- if (islist(grandparent) && inj.prior) {
1436
- inj.prior.keyI--
1488
+ const prior = inj.prior
1489
+ if (prior) {
1490
+ prior.modify = NONE
1491
+ if (islist(grandparent) || NONE !== rval) {
1492
+ prior.keyI--
1493
+ }
1437
1494
  }
1438
- return val
1495
+ return SKIP
1439
1496
  }
1440
1497
  const transform_FORMAT = (inj, _val, _ref, store) => {
1441
1498
  // console.log('FORMAT-START', inj, _val)
@@ -1599,7 +1656,8 @@ const validate_STRING = (inj) => {
1599
1656
  }
1600
1657
  const validate_TYPE = (inj, _val, ref) => {
1601
1658
  const tname = slice(ref, 1).toLowerCase()
1602
- const typev = 1 << (31 - TYPENAME.indexOf(tname))
1659
+ // $NIL is absent or null.
1660
+ const typev = (1 << (31 - TYPENAME.indexOf(tname))) | (S_nil === tname ? T_null : 0)
1603
1661
  let out = _lookup(inj.dparent, inj.key)
1604
1662
  const t = typify(out)
1605
1663
  // console.log('TYPE', tname, typev, tn(typev), 'O=', t, tn(t), out, 'C=', t & typev)
@@ -1629,7 +1687,7 @@ const validate_CHILD = (inj) => {
1629
1687
  if (NONE == tval) {
1630
1688
  tval = {}
1631
1689
  } else if (!ismap(tval)) {
1632
- inj.errs.push(_invalidTypeMsg(slice(inj.path, -1), S_object, typify(tval), tval), 'V0220')
1690
+ // _validation reports the mismatch, once.
1633
1691
  return NONE
1634
1692
  }
1635
1693
  const ckeys = keysof(tval)
@@ -1657,14 +1715,6 @@ const validate_CHILD = (inj) => {
1657
1715
  return NONE
1658
1716
  }
1659
1717
  if (!islist(inj.dparent)) {
1660
- const msg = _invalidTypeMsg(
1661
- slice(inj.path, -1),
1662
- S_list,
1663
- typify(inj.dparent),
1664
- inj.dparent,
1665
- 'V0230',
1666
- )
1667
- inj.errs.push(msg)
1668
1718
  inj.keyI = size(parent)
1669
1719
  return inj.dparent
1670
1720
  }
@@ -1688,51 +1738,36 @@ const validate_CHILD = (inj) => {
1688
1738
  }
1689
1739
  return NONE
1690
1740
  }
1691
- // TODO: implement SOME, ALL
1692
- // FIX: ONE should mean exactly one, not at least one (=SOME)
1693
- // TODO: implement a generate validate_ALT to do all of these
1694
- // Match at least one of the specified shapes.
1695
- // Syntax: ['`$ONE`', alt0, alt1, ...]
1696
- const validate_ONE = (inj, _val, _ref, store) => {
1697
- const { mode, parent, keyI } = inj
1741
+ const validate_EXACT = (inj) => {
1742
+ const { mode, parent, key, keyI } = inj
1698
1743
  // Only operate in val mode, since parent is a list.
1699
1744
  if (M_VAL === mode) {
1700
1745
  if (!islist(parent) || 0 !== keyI) {
1701
1746
  inj.errs.push(
1702
- 'The $ONE validator at field ' +
1747
+ 'The $EXACT validator at field ' +
1703
1748
  pathify(inj.path, 1, 1) +
1704
1749
  ' must be the first element of an array.',
1705
1750
  )
1706
1751
  return
1707
1752
  }
1753
+ const cval = _slotval(inj)
1708
1754
  inj.keyI = size(inj.keys)
1709
- // Clean up structure, replacing [$ONE, ...] with current
1710
- inj.setval(inj.dparent, 2)
1711
- inj.path = slice(inj.path, -1)
1755
+ // Replace [$EXACT, ...] with the data value; SKIP keeps inject off the detached list.
1756
+ inj.setval(cval, 2)
1757
+ inj.path = slice(inj.path, 0, -1)
1712
1758
  let tvals = slice(parent, 1)
1713
1759
  if (0 === size(tvals)) {
1714
1760
  inj.errs.push(
1715
- 'The $ONE validator at field ' +
1761
+ 'The $EXACT validator at field ' +
1716
1762
  pathify(inj.path, 1, 1) +
1717
1763
  ' must have at least one argument.',
1718
1764
  )
1719
- return
1765
+ return SKIP
1720
1766
  }
1721
- // See if we can find a match.
1767
+ // See if we can find an exact value match.
1722
1768
  for (let tval of tvals) {
1723
- // If match, then errs.length = 0
1724
- let terrs = []
1725
- const vstore = merge([{}, store], 1)
1726
- vstore.$TOP = inj.dparent
1727
- const vcurrent = validate(inj.dparent, tval, {
1728
- extra: vstore,
1729
- errs: terrs,
1730
- meta: inj.meta,
1731
- })
1732
- inj.setval(vcurrent, -2)
1733
- // Accept current value if there was a match
1734
- if (0 === size(terrs)) {
1735
- return
1769
+ if (_deepequal(tval, cval)) {
1770
+ return SKIP
1736
1771
  }
1737
1772
  }
1738
1773
  // There was no match.
@@ -1747,55 +1782,74 @@ const validate_ONE = (inj, _val, _ref, store) => {
1747
1782
  inj.errs.push(
1748
1783
  _invalidTypeMsg(
1749
1784
  inj.path,
1750
- (1 < size(tvals) ? 'one of ' : '') + valdesc,
1751
- typify(inj.dparent),
1752
- inj.dparent,
1753
- 'V0210',
1785
+ (1 < size(inj.path) ? '' : 'value ') +
1786
+ 'exactly equal to ' +
1787
+ (1 === size(tvals) ? '' : 'one of ') +
1788
+ valdesc,
1789
+ typify(cval),
1790
+ cval,
1791
+ 'V0110',
1754
1792
  ),
1755
1793
  )
1794
+ return SKIP
1795
+ } else {
1796
+ delprop(parent, key)
1756
1797
  }
1757
1798
  }
1758
- const validate_EXACT = (inj) => {
1759
- const { mode, parent, key, keyI } = inj
1760
- // Only operate in val mode, since parent is a list.
1761
- if (M_VAL === mode) {
1762
- if (!islist(parent) || 0 !== keyI) {
1763
- inj.errs.push(
1764
- 'The $EXACT validator at field ' +
1765
- pathify(inj.path, 1, 1) +
1766
- ' must be the first element of an array.',
1767
- )
1768
- return
1769
- }
1770
- inj.keyI = size(inj.keys)
1771
- // Clean up structure, replacing [$EXACT, ...] with current data parent
1772
- inj.setval(inj.dparent, 2)
1773
- // inj.path = slice(inj.path, 0, size(inj.path) - 1)
1774
- inj.path = slice(inj.path, 0, -1)
1775
- inj.key = getelem(inj.path, -1)
1776
- let tvals = slice(parent, 1)
1777
- if (0 === size(tvals)) {
1778
- inj.errs.push(
1779
- 'The $EXACT validator at field ' +
1780
- pathify(inj.path, 1, 1) +
1781
- ' must have at least one argument.',
1782
- )
1783
- return
1799
+ // Count the specs that admit the value: ['`$NOF`', count, spec, ...], where
1800
+ // count is an integer, or a map holding min, max or both.
1801
+ const validate_NOF = (inj, _val, _ref, store) => _validatecount(inj, store, '$NOF', true)
1802
+ // Every spec admits the value: ['`$ALL`', spec, ...].
1803
+ const validate_ALL = (inj, _val, _ref, store) => _validatecount(inj, store, '$ALL', false)
1804
+ // The counting list directives. Without a count, every spec has to admit.
1805
+ function _validatecount(inj, store, name, counted) {
1806
+ const { mode, parent, keyI } = inj
1807
+ if (M_VAL !== mode) {
1808
+ return NONE
1809
+ }
1810
+ if (!islist(parent) || 0 !== keyI) {
1811
+ inj.errs.push(
1812
+ 'The ' +
1813
+ name +
1814
+ ' validator at field ' +
1815
+ pathify(inj.path, 1, 1) +
1816
+ ' must be the first element of an array.',
1817
+ )
1818
+ return NONE
1819
+ }
1820
+ const cval = _slotval(inj)
1821
+ inj.keyI = size(inj.keys)
1822
+ // Replace the directive's list with the data value. Each return is SKIP, so
1823
+ // that inject leaves the detached list alone and validates nothing in it.
1824
+ inj.setval(cval, 2)
1825
+ inj.path = slice(inj.path, -1)
1826
+ const count = counted ? _lookup(parent, 1) : NONE
1827
+ const tvals = slice(parent, counted ? 2 : 1)
1828
+ const numtvals = size(tvals)
1829
+ const field = 'The ' + name + ' validator at field ' + pathify(inj.path, 1)
1830
+ if (0 === numtvals) {
1831
+ inj.errs.push(
1832
+ field + (counted ? ' must have a count and' : ' must have') + ' at least one argument.',
1833
+ )
1834
+ return SKIP
1835
+ }
1836
+ const [lo, hi, countdesc] = counted ? _nofcount(count, numtvals) : [numtvals, numtvals, 'all']
1837
+ if (NONE === countdesc) {
1838
+ inj.errs.push(field + ' has an invalid count: ' + stringify(count) + '.')
1839
+ return SKIP
1840
+ }
1841
+ let admitted = 0
1842
+ for (let tI = 0; tI < numtvals; tI++) {
1843
+ const left = numtvals - tI
1844
+ // Stop once the specs left cannot change the verdict.
1845
+ if (hi < admitted || admitted + left < lo || (lo <= admitted && admitted + left <= hi)) {
1846
+ break
1784
1847
  }
1785
- // See if we can find an exact value match.
1786
- let currentstr = undefined
1787
- for (let tval of tvals) {
1788
- let exactmatch = tval === inj.dparent
1789
- if (!exactmatch && isnode(tval)) {
1790
- currentstr = undefined === currentstr ? stringify(inj.dparent) : currentstr
1791
- const tvalstr = stringify(tval)
1792
- exactmatch = tvalstr === currentstr
1793
- }
1794
- if (exactmatch) {
1795
- return
1796
- }
1848
+ if (_admits(cval, tvals[tI], inj, store)) {
1849
+ admitted++
1797
1850
  }
1798
- // There was no match.
1851
+ }
1852
+ if (admitted < lo || hi < admitted) {
1799
1853
  const valdesc = replace(
1800
1854
  join(
1801
1855
  items(tvals, (n) => stringify(n[1])),
@@ -1805,20 +1859,158 @@ const validate_EXACT = (inj) => {
1805
1859
  (_m, p1) => p1.toLowerCase(),
1806
1860
  )
1807
1861
  inj.errs.push(
1808
- _invalidTypeMsg(
1809
- inj.path,
1810
- (1 < size(inj.path) ? '' : 'value ') +
1811
- 'exactly equal to ' +
1812
- (1 === size(tvals) ? '' : 'one of ') +
1813
- valdesc,
1814
- typify(inj.dparent),
1815
- inj.dparent,
1816
- 'V0110',
1817
- ),
1862
+ _invalidTypeMsg(inj.path, countdesc + ' of ' + valdesc, typify(cval), cval, 'V0310'),
1818
1863
  )
1819
- } else {
1820
- delprop(parent, key)
1821
1864
  }
1865
+ return SKIP
1866
+ }
1867
+ // The value's length is within a bound: ['`$LEN`', bound, spec?], where the
1868
+ // bound is as for a $NOF count. A string's length is in code points.
1869
+ const validate_LEN = (inj, _val, _ref, store) => _validatebound(inj, store, '$LEN')
1870
+ // The value is a number within a bound: ['`$RANGE`', bound, spec?], where the
1871
+ // bound holds min or gt, max or lt, or one of each.
1872
+ const validate_RANGE = (inj, _val, _ref, store) => _validatebound(inj, store, '$RANGE')
1873
+ const validate_LIKE = (inj, _val, _ref, store) => _validatebound(inj, store, '$LIKE')
1874
+ // The bounding list directives: a bound or pattern, then at most one spec that also admits.
1875
+ function _validatebound(inj, store, name) {
1876
+ const { mode, parent, keyI } = inj
1877
+ if (M_VAL !== mode) {
1878
+ return NONE
1879
+ }
1880
+ if (!islist(parent) || 0 !== keyI) {
1881
+ inj.errs.push(
1882
+ 'The ' +
1883
+ name +
1884
+ ' validator at field ' +
1885
+ pathify(inj.path, 1, 1) +
1886
+ ' must be the first element of an array.',
1887
+ )
1888
+ return NONE
1889
+ }
1890
+ const cval = _slotval(inj)
1891
+ inj.keyI = size(inj.keys)
1892
+ // As for the counting directives: SKIP keeps inject off the detached list.
1893
+ inj.setval(cval, 2)
1894
+ inj.path = slice(inj.path, -1)
1895
+ const field = 'The ' + name + ' validator at field ' + pathify(inj.path, 1)
1896
+ const nargs = size(parent) - 1
1897
+ const islen = '$LEN' === name
1898
+ const islike = '$LIKE' === name
1899
+ const argname = islike ? 'pattern' : 'bound'
1900
+ if (nargs < 1 || 2 < nargs) {
1901
+ inj.errs.push(field + ' must have a ' + argname + ' and at most one spec.')
1902
+ return SKIP
1903
+ }
1904
+ const bound = _lookup(parent, 1)
1905
+ const like = islike ? _likere(bound) : NONE
1906
+ const [lo, hi, desc] = islen
1907
+ ? _lenbound(bound)
1908
+ : [0, 0, islike ? (NONE === like ? NONE : 'like /' + bound + '/') : _rangedesc(bound)]
1909
+ if (NONE === desc) {
1910
+ inj.errs.push(field + ' has an invalid ' + argname + ': ' + stringify(bound) + '.')
1911
+ return SKIP
1912
+ }
1913
+ const ctype = typify(cval)
1914
+ if (2 === nargs && !_admits(cval, _lookup(parent, 2), inj, store)) {
1915
+ const specdesc = replace(stringify(_lookup(parent, 2)), R_TRANSFORM_NAME, (_m, p1) =>
1916
+ p1.toLowerCase(),
1917
+ )
1918
+ inj.errs.push(_invalidTypeMsg(inj.path, specdesc, ctype, cval, 'V0410'))
1919
+ return SKIP
1920
+ }
1921
+ if (0 === ((islen ? T_string | T_list | T_map : islike ? T_string : T_number) & ctype)) {
1922
+ const needtype = islen ? 'string, list or map' : islike ? S_string : S_number
1923
+ inj.errs.push(_invalidTypeMsg(inj.path, needtype, ctype, cval, 'V0420'))
1924
+ return SKIP
1925
+ }
1926
+ const len = islen ? (S_string === typeof cval ? Array.from(cval).length : size(cval)) : 0
1927
+ const inbound = islen
1928
+ ? lo <= len && (-1 === hi || len <= hi)
1929
+ : islike
1930
+ ? re_test(like, cval)
1931
+ : _inrange(bound, cval)
1932
+ if (!inbound) {
1933
+ const needtype = (1 < size(inj.path) ? '' : 'value ') + desc
1934
+ inj.errs.push(_invalidTypeMsg(inj.path, needtype, ctype, cval, 'V0430'))
1935
+ }
1936
+ return SKIP
1937
+ }
1938
+ // The bounds of a $LEN bound, with -1 for no maximum, and the words for it,
1939
+ // which are absent when the bound is invalid.
1940
+ function _lenbound(bound) {
1941
+ const [lo, hi, countdesc] = _nofcount(bound, -1)
1942
+ if (NONE === countdesc) {
1943
+ return [0, 0, NONE]
1944
+ }
1945
+ const desc =
1946
+ 'of length ' +
1947
+ (lo === hi ? lo : -1 === hi ? 'at least ' + lo : 0 === lo ? 'at most ' + hi : lo + ' to ' + hi)
1948
+ return [lo, hi, desc]
1949
+ }
1950
+ // A $LIKE pattern compiled by the port's own regex engine; absent unless it compiles.
1951
+ function _likere(pattern) {
1952
+ if (S_string !== typeof pattern) {
1953
+ return NONE
1954
+ }
1955
+ try {
1956
+ return re_compile(pattern)
1957
+ } catch {
1958
+ return NONE
1959
+ }
1960
+ }
1961
+ // The words for a $RANGE bound, which are absent when the bound is invalid.
1962
+ function _rangedesc(bound) {
1963
+ if (!ismap(bound)) {
1964
+ return NONE
1965
+ }
1966
+ const min = _lookup(bound, 'min')
1967
+ const max = _lookup(bound, 'max')
1968
+ const gt = _lookup(bound, 'gt')
1969
+ const lt = _lookup(bound, 'lt')
1970
+ const lower = NONE === min ? gt : min
1971
+ const upper = NONE === max ? lt : max
1972
+ const isnum = (n) => NONE === n || 0 < (T_number & typify(n))
1973
+ const valid =
1974
+ 0 < size(bound) &&
1975
+ size(bound) === [min, max, gt, lt].filter((n) => NONE !== n).length &&
1976
+ (NONE === min || NONE === gt) &&
1977
+ (NONE === max || NONE === lt) &&
1978
+ isnum(min) &&
1979
+ isnum(max) &&
1980
+ isnum(gt) &&
1981
+ isnum(lt) &&
1982
+ (NONE === lower || NONE === upper || lower <= upper)
1983
+ if (!valid) {
1984
+ return NONE
1985
+ }
1986
+ return join(
1987
+ [
1988
+ NONE !== min
1989
+ ? 'at least ' + stringify(min)
1990
+ : NONE !== gt
1991
+ ? 'greater than ' + stringify(gt)
1992
+ : NONE,
1993
+ NONE !== max
1994
+ ? 'at most ' + stringify(max)
1995
+ : NONE !== lt
1996
+ ? 'less than ' + stringify(lt)
1997
+ : NONE,
1998
+ ],
1999
+ ' and ',
2000
+ )
2001
+ }
2002
+ // A number within a valid $RANGE bound.
2003
+ function _inrange(bound, val) {
2004
+ const min = _lookup(bound, 'min')
2005
+ const max = _lookup(bound, 'max')
2006
+ const gt = _lookup(bound, 'gt')
2007
+ const lt = _lookup(bound, 'lt')
2008
+ return (
2009
+ (NONE === min || min <= val) &&
2010
+ (NONE === max || val <= max) &&
2011
+ (NONE === gt || gt < val) &&
2012
+ (NONE === lt || val < lt)
2013
+ )
1822
2014
  }
1823
2015
  // This is the "modify" argument to inject. Use this to perform
1824
2016
  // generic validation. Runs *after* any special commands.
@@ -1931,8 +2123,12 @@ function validate(
1931
2123
  $INSTANCE: validate_TYPE,
1932
2124
  $ANY: validate_ANY,
1933
2125
  $CHILD: validate_CHILD,
1934
- $ONE: validate_ONE,
1935
2126
  $EXACT: validate_EXACT,
2127
+ $NOF: validate_NOF,
2128
+ $ALL: validate_ALL,
2129
+ $LEN: validate_LEN,
2130
+ $RANGE: validate_RANGE,
2131
+ $LIKE: validate_LIKE,
1936
2132
  },
1937
2133
  getdef(extra, {}),
1938
2134
  // A special top level value to collect errors.
@@ -1945,13 +2141,19 @@ function validate(
1945
2141
  )
1946
2142
  let meta = getprop(injdef, 'meta', {})
1947
2143
  setprop(meta, S_BEXACT, getprop(meta, S_BEXACT, false))
1948
- const out = transform(data, spec, {
1949
- meta,
1950
- extra: store,
1951
- modify: _validation,
1952
- handler: _validatehandler,
1953
- errs,
1954
- })
2144
+ // A spec that names an unknown checker validates nothing.
2145
+ const numerrs = size(errs)
2146
+ _checknames(spec, store, [], errs)
2147
+ const out =
2148
+ numerrs < size(errs)
2149
+ ? clone(data)
2150
+ : transform(data, spec, {
2151
+ meta,
2152
+ extra: store,
2153
+ modify: _validation,
2154
+ handler: _validatehandler,
2155
+ errs,
2156
+ })
1955
2157
  const generr = 0 < size(errs) && !collect
1956
2158
  if (generr) {
1957
2159
  throw new Error(join(errs, ' | '))
@@ -2029,6 +2231,10 @@ const select_NOT = (inj, _val, _ref, store) => {
2029
2231
  }
2030
2232
  }
2031
2233
  const select_CMP = (inj, _val, ref, store) => {
2234
+ // The list form of $LIKE is validate's checker; the key form is this operator.
2235
+ if (M_VAL === inj.mode && '$LIKE' === ref) {
2236
+ return validate_LIKE(inj, _val, ref, store)
2237
+ }
2032
2238
  if (M_KEYPRE === inj.mode) {
2033
2239
  const term = _lookup(inj.parent, inj.key)
2034
2240
  // const src = getprop(store, inj.base, store)
@@ -2099,12 +2305,7 @@ function select(children, query) {
2099
2305
  },
2100
2306
  }
2101
2307
  const q = clone(query)
2102
- walk(q, (_k, v) => {
2103
- if (ismap(v)) {
2104
- setprop(v, '`$OPEN`', getprop(v, '`$OPEN`', true))
2105
- }
2106
- return v
2107
- })
2308
+ _openquery(q)
2108
2309
  for (const child of children) {
2109
2310
  injdef.errs = []
2110
2311
  validate(child, clone(q), injdef)
@@ -2114,6 +2315,26 @@ function select(children, query) {
2114
2315
  }
2115
2316
  return results
2116
2317
  }
2318
+ // Open every map in a select query, so a child may hold keys the query does
2319
+ // not name, but leave a directive's literals as written: what $EXACT
2320
+ // compares, and the count or bound of $NOF, $LEN and $RANGE.
2321
+ function _openquery(q) {
2322
+ if (ismap(q)) {
2323
+ setprop(q, '`$OPEN`', getprop(q, '`$OPEN`', true))
2324
+ for (const key of keysof(q)) {
2325
+ _openquery(q[key])
2326
+ }
2327
+ } else if (islist(q)) {
2328
+ const head = q[0]
2329
+ const exact = '`$EXACT`' === head
2330
+ const bounded = '`$NOF`' === head || '`$LEN`' === head || '`$RANGE`' === head
2331
+ for (let i = 0; i < size(q); i++) {
2332
+ if (0 === i || !(exact || (bounded && 1 === i))) {
2333
+ _openquery(q[i])
2334
+ }
2335
+ }
2336
+ }
2337
+ }
2117
2338
  // Injection state used for recursive injection into JSON - like data structures.
2118
2339
  class Injection {
2119
2340
  constructor(val, parent) {
@@ -2245,6 +2466,139 @@ function _invalidTypeMsg(path, needtype, vt, v, _whence) {
2245
2466
  '.'
2246
2467
  )
2247
2468
  }
2469
+ // Names a validate spec may use besides its checkers: transform's that it keeps, and $OPEN.
2470
+ const VALIDATE_NAMES = [
2471
+ '$TOP',
2472
+ '$SPEC',
2473
+ '$BT',
2474
+ '$DS',
2475
+ '$WHEN',
2476
+ '$ANNO',
2477
+ '$REF',
2478
+ '$FORMAT',
2479
+ '$APPLY',
2480
+ '$OPEN',
2481
+ ]
2482
+ // Report each checker the spec names that validate lacks; $EXACT's arguments are literals.
2483
+ function _checknames(spec, store, path, errs) {
2484
+ const name = _refname(spec)
2485
+ if (NONE !== name) {
2486
+ if (_unknownname(name, store)) {
2487
+ errs.push('Unknown validator ' + name + ' at field ' + pathify(path) + '.')
2488
+ }
2489
+ return
2490
+ }
2491
+ if (islist(spec) && '$EXACT' === _refname(spec[0])) {
2492
+ return
2493
+ }
2494
+ for (const key of keysof(spec)) {
2495
+ if (ismap(spec)) {
2496
+ _checknames(key, store, path, errs)
2497
+ }
2498
+ _checknames(spec[key], store, flatten([path, key]), errs)
2499
+ }
2500
+ }
2501
+ // The name a whole-string reference gives, when it is a checker name in any case.
2502
+ function _refname(val) {
2503
+ const m = S_string === typeof val ? re_find(R_INJECTION_FULL, val) : null
2504
+ return null != m && re_test(R_CHECKER_NAME, m[1].toUpperCase()) ? m[1] : NONE
2505
+ }
2506
+ // Unknown: undefined and upper case, or a defined name in another case. Null disables a name.
2507
+ function _unknownname(name, store) {
2508
+ const known = (n) => VALIDATE_NAMES.includes(n) || null != _lookup(store, n)
2509
+ const upper = name.toUpperCase()
2510
+ return !known(name) && (upper === name || known(upper))
2511
+ }
2512
+ // The data value at a list directive's slot. The directive's own dparent was
2513
+ // read with getprop, which reports a stored null as absent.
2514
+ function _slotval(inj) {
2515
+ const prior = inj.prior
2516
+ return NONE === prior ? inj.dparent : _lookup(prior.dparent, prior.key)
2517
+ }
2518
+ // JSON equality: numbers by value, lists in order, maps by key in any order.
2519
+ function _deepequal(a, b) {
2520
+ if (a === b) {
2521
+ return true
2522
+ }
2523
+ const atype = typify(a)
2524
+ if (atype !== typify(b) || 0 === ((T_list | T_map) & atype)) {
2525
+ return false
2526
+ }
2527
+ const akeys = keysof(a)
2528
+ const bkeys = keysof(b)
2529
+ if (size(akeys) !== size(bkeys)) {
2530
+ return false
2531
+ }
2532
+ for (let kI = 0; kI < size(akeys); kI++) {
2533
+ const k = akeys[kI]
2534
+ if (k !== bkeys[kI] || !_deepequal(a[k], b[k])) {
2535
+ return false
2536
+ }
2537
+ }
2538
+ return true
2539
+ }
2540
+ // Every member val has is in out, unchanged. A member only out has is a
2541
+ // default the spec supplied, and is ignored.
2542
+ function _keeps(val, out) {
2543
+ if (NONE === val) {
2544
+ return true
2545
+ }
2546
+ if (0 === ((T_list | T_map) & typify(val)) || islist(val) !== islist(out) || !isnode(out)) {
2547
+ return _deepequal(val, out)
2548
+ }
2549
+ for (const k of keysof(val)) {
2550
+ if (!_keeps(val[k], _lookup(out, k))) {
2551
+ return false
2552
+ }
2553
+ }
2554
+ return true
2555
+ }
2556
+ // A spec admits a value when validating the value against it finds no error
2557
+ // and gives back the value as it is.
2558
+ function _admits(val, spec, inj, store) {
2559
+ const terrs = []
2560
+ const vstore = merge([{}, store], 1)
2561
+ vstore.$TOP = val
2562
+ const out = validate(val, spec, {
2563
+ extra: vstore,
2564
+ errs: terrs,
2565
+ meta: inj.meta,
2566
+ })
2567
+ return 0 === size(terrs) && _keeps(val, out)
2568
+ }
2569
+ // The bounds of a $NOF count, and the words for it, which are absent when
2570
+ // the count is invalid. Without a max, the bound is the number of specs.
2571
+ function _nofcount(count, numtvals) {
2572
+ const isnat = (n) => 0 < (T_integer & typify(n)) && 0 <= n
2573
+ if (isnat(count)) {
2574
+ return [count, count, 0 === count ? 'none' : 'exactly ' + count]
2575
+ }
2576
+ const min = _lookup(count, 'min')
2577
+ const max = _lookup(count, 'max')
2578
+ const valid =
2579
+ ismap(count) &&
2580
+ 0 < size(count) &&
2581
+ size(count) === (NONE === min ? 0 : 1) + (NONE === max ? 0 : 1) &&
2582
+ (NONE === min || isnat(min)) &&
2583
+ (NONE === max || isnat(max)) &&
2584
+ (NONE === min || NONE === max || min <= max)
2585
+ if (!valid) {
2586
+ return [0, 0, NONE]
2587
+ }
2588
+ const lo = NONE === min ? 0 : min
2589
+ const hi = NONE === max ? numtvals : max
2590
+ const desc =
2591
+ NONE === max
2592
+ ? 'at least ' + lo
2593
+ : 0 === hi
2594
+ ? 'none'
2595
+ : NONE === min
2596
+ ? 'at most ' + hi
2597
+ : lo === hi
2598
+ ? 'exactly ' + lo
2599
+ : lo + ' to ' + hi
2600
+ return [lo, hi, desc]
2601
+ }
2248
2602
  // Default inject handler for transforms. If the path resolves to a function,
2249
2603
  // call the function passing the injection inj. This is how transforms operate.
2250
2604
  const _injecthandler = (inj, val, ref, store) => {
@@ -2426,9 +2780,12 @@ function injectChild(child, store, inj) {
2426
2780
  class StructUtility {
2427
2781
  constructor() {
2428
2782
  this.clone = clone
2783
+ this.condense = condense
2784
+ this.condenseview = condenseview
2429
2785
  this.delprop = delprop
2430
2786
  this.escre = escre
2431
2787
  this.escurl = escurl
2788
+ this.expand = expand
2432
2789
  this.filter = filter
2433
2790
  this.flatten = flatten
2434
2791
  this.getdef = getdef
@@ -2438,6 +2795,7 @@ class StructUtility {
2438
2795
  this.haskey = haskey
2439
2796
  this.inject = inject
2440
2797
  this.isempty = isempty
2798
+ this.iscondensed = iscondensed
2441
2799
  this.isfunc = isfunc
2442
2800
  this.iskey = iskey
2443
2801
  this.islist = islist
@@ -2493,6 +2851,338 @@ class StructUtility {
2493
2851
  this.injectChild = injectChild
2494
2852
  }
2495
2853
  }
2854
+ const CONDENSE_VERSION = 1
2855
+ const CONDENSE_MAP = 0
2856
+ const CONDENSE_LIST = 1
2857
+ const CONDENSE_STR = 2
2858
+ const CONDENSE_NUM = 3
2859
+ const CONDENSE_TRUE = 4
2860
+ const CONDENSE_FALSE = 5
2861
+ const CONDENSE_NULL = 6
2862
+ const S_condense = '$condense'
2863
+ const S_condsym = 'sym'
2864
+ const S_condnode = 'node'
2865
+ const S_condroot = 'root'
2866
+ function condenseCmp(a, b) {
2867
+ let i = 0
2868
+ let j = 0
2869
+ while (i < a.length && j < b.length) {
2870
+ const ca = a.codePointAt(i)
2871
+ const cb = b.codePointAt(j)
2872
+ if (ca !== cb) {
2873
+ return ca < cb ? -1 : 1
2874
+ }
2875
+ i += 0xffff < ca ? 2 : 1
2876
+ j += 0xffff < cb ? 2 : 1
2877
+ }
2878
+ return a.length - i - (b.length - j)
2879
+ }
2880
+ function iscondensed(val) {
2881
+ // The version must MATCH, not merely be numeric: a future profile would
2882
+ // otherwise be decoded under this one's schema.
2883
+ return (
2884
+ ismap(val) &&
2885
+ CONDENSE_VERSION === val[S_condense] &&
2886
+ islist(val[S_condsym]) &&
2887
+ islist(val[S_condnode]) &&
2888
+ 'number' === typeof val[S_condroot]
2889
+ )
2890
+ }
2891
+ // Condense any JSON-shaped node. Pure: the same input always produces a
2892
+ // byte-identical result, on every port.
2893
+ function condense(val) {
2894
+ // Pass one: every distinct map key and string value, once, sorted.
2895
+ const symset = Object.create(null)
2896
+ const collect = (n) => {
2897
+ if (ismap(n)) {
2898
+ const keys = keysof(n)
2899
+ for (let i = 0; i < keys.length; i++) {
2900
+ symset[keys[i]] = true
2901
+ collect(n[keys[i]])
2902
+ }
2903
+ } else if (islist(n)) {
2904
+ for (let i = 0; i < n.length; i++) {
2905
+ collect(n[i])
2906
+ }
2907
+ } else if ('string' === typeof n) {
2908
+ symset[n] = true
2909
+ }
2910
+ }
2911
+ collect(val)
2912
+ const sym = Object.keys(symset).sort(condenseCmp)
2913
+ const symid = Object.create(null)
2914
+ for (let i = 0; i < sym.length; i++) {
2915
+ symid[sym[i]] = i
2916
+ }
2917
+ // Pass two: build post-order, interning on the canonical encoding. Because
2918
+ // children are built first, identical subtrees have already been interned
2919
+ // by the time a parent references them, so sharing costs nothing extra.
2920
+ const node = []
2921
+ const seen = Object.create(null)
2922
+ const intern = (enc) => {
2923
+ // The kind tag leads every encoding, so a string node and a number node
2924
+ // can never collide on the same joined key.
2925
+ const enckey = enc.join(',')
2926
+ const hit = seen[enckey]
2927
+ if (undefined !== hit) {
2928
+ return hit
2929
+ }
2930
+ const idx = node.length
2931
+ node.push(enc)
2932
+ seen[enckey] = idx
2933
+ return idx
2934
+ }
2935
+ const build = (n) => {
2936
+ if (ismap(n)) {
2937
+ const enc = [CONDENSE_MAP]
2938
+ // Code-point order, not keysof's code-unit order, so the key ids ascend for bisection.
2939
+ const keys = keysof(n).sort(condenseCmp)
2940
+ for (let i = 0; i < keys.length; i++) {
2941
+ enc.push(symid[keys[i]])
2942
+ enc.push(build(n[keys[i]]))
2943
+ }
2944
+ return intern(enc)
2945
+ }
2946
+ if (islist(n)) {
2947
+ const enc = [CONDENSE_LIST]
2948
+ for (let i = 0; i < n.length; i++) {
2949
+ enc.push(build(n[i]))
2950
+ }
2951
+ return intern(enc)
2952
+ }
2953
+ if ('string' === typeof n) {
2954
+ return intern([CONDENSE_STR, symid[n]])
2955
+ }
2956
+ if ('number' === typeof n) {
2957
+ return intern([CONDENSE_NUM, n])
2958
+ }
2959
+ if (true === n) {
2960
+ return intern([CONDENSE_TRUE])
2961
+ }
2962
+ if (false === n) {
2963
+ return intern([CONDENSE_FALSE])
2964
+ }
2965
+ return intern([CONDENSE_NULL])
2966
+ }
2967
+ const root = build(val)
2968
+ const out = {}
2969
+ out[S_condense] = CONDENSE_VERSION
2970
+ out[S_condsym] = sym
2971
+ out[S_condnode] = node
2972
+ out[S_condroot] = root
2973
+ return out
2974
+ }
2975
+ // Resolve a symbol to its id by bisecting the sorted symbol table. -1 when
2976
+ // the string does not occur anywhere in the structure, which is itself a fast
2977
+ // negative answer for a key lookup.
2978
+ function condenseSymId(cond, key) {
2979
+ const sym = cond[S_condsym]
2980
+ let lo = 0
2981
+ let hi = sym.length - 1
2982
+ while (lo <= hi) {
2983
+ const mid = (lo + hi) >> 1
2984
+ if (sym[mid] === key) {
2985
+ return mid
2986
+ }
2987
+ if (0 > condenseCmp(sym[mid], key)) {
2988
+ lo = mid + 1
2989
+ } else {
2990
+ hi = mid - 1
2991
+ }
2992
+ }
2993
+ return -1
2994
+ }
2995
+ // The node index of `key` inside node `idx`, or -1. Touches only this node.
2996
+ function condenseChild(cond, idx, key) {
2997
+ const enc = cond[S_condnode][idx]
2998
+ if (null == enc || (S_string !== typeof key && S_number !== typeof key)) {
2999
+ return -1
3000
+ }
3001
+ if (CONDENSE_MAP === enc[0]) {
3002
+ const symid = condenseSymId(cond, S_MT + key)
3003
+ if (0 > symid) {
3004
+ return -1
3005
+ }
3006
+ // Pairs live at [1,2], [3,4], ... with keys ascending: bisect the pairs.
3007
+ let lo = 0
3008
+ let hi = (enc.length - 1) / 2 - 1
3009
+ while (lo <= hi) {
3010
+ const mid = (lo + hi) >> 1
3011
+ const k = enc[1 + mid * 2]
3012
+ if (k === symid) {
3013
+ return enc[2 + mid * 2]
3014
+ }
3015
+ if (k < symid) {
3016
+ lo = mid + 1
3017
+ } else {
3018
+ hi = mid - 1
3019
+ }
3020
+ }
3021
+ return -1
3022
+ }
3023
+ if (CONDENSE_LIST === enc[0]) {
3024
+ // Canonical integer keys ONLY. Unary + would accept "01", "1e0", " 1"
3025
+ // and "+1", which an ordinary list lookup treats as plain (absent)
3026
+ // properties - condensing must not change which value a path selects.
3027
+ const k = S_MT + key
3028
+ if (!/^(0|[1-9][0-9]*)$/.test(k)) {
3029
+ return -1
3030
+ }
3031
+ const i = +k
3032
+ if (i >= enc.length - 1) {
3033
+ return -1
3034
+ }
3035
+ return enc[1 + i]
3036
+ }
3037
+ return -1
3038
+ }
3039
+ // Walk a path from a starting node, returning the node index or -1.
3040
+ function condenseResolve(cond, idx, path) {
3041
+ const parts = islist(path)
3042
+ ? path
3043
+ : 'string' === typeof path
3044
+ ? '' === path
3045
+ ? []
3046
+ : path.split(S_DT)
3047
+ : null == path
3048
+ ? []
3049
+ : [S_MT + path]
3050
+ let at = idx
3051
+ for (let i = 0; i < parts.length; i++) {
3052
+ if (0 > at) {
3053
+ return -1
3054
+ }
3055
+ if (S_MT === parts[i]) {
3056
+ continue
3057
+ }
3058
+ at = condenseChild(cond, at, parts[i])
3059
+ }
3060
+ return at
3061
+ }
3062
+ function condenseMaterialise(cond, idx) {
3063
+ const sym = cond[S_condsym]
3064
+ const node = cond[S_condnode]
3065
+ const rebuild = (i) => {
3066
+ const enc = node[i]
3067
+ if (null == enc) {
3068
+ return undefined
3069
+ }
3070
+ const kind = enc[0]
3071
+ if (CONDENSE_MAP === kind) {
3072
+ const out = {}
3073
+ for (let j = 1; j < enc.length; j += 2) {
3074
+ _setown(out, sym[enc[j]], rebuild(enc[j + 1]))
3075
+ }
3076
+ return out
3077
+ }
3078
+ if (CONDENSE_LIST === kind) {
3079
+ const out = []
3080
+ for (let j = 1; j < enc.length; j++) {
3081
+ out.push(rebuild(enc[j]))
3082
+ }
3083
+ return out
3084
+ }
3085
+ if (CONDENSE_STR === kind) {
3086
+ return sym[enc[1]]
3087
+ }
3088
+ if (CONDENSE_NUM === kind) {
3089
+ return enc[1]
3090
+ }
3091
+ if (CONDENSE_TRUE === kind) {
3092
+ return true
3093
+ }
3094
+ if (CONDENSE_FALSE === kind) {
3095
+ return false
3096
+ }
3097
+ return null
3098
+ }
3099
+ return 0 > idx ? undefined : rebuild(idx)
3100
+ }
3101
+ // Fully materialise a condensed structure. The escape hatch: correct for any
3102
+ // caller, but it gives up every benefit of condensing, so prefer a view or a
3103
+ // path read.
3104
+ function expand(cond) {
3105
+ if (!iscondensed(cond)) {
3106
+ return cond
3107
+ }
3108
+ return condenseMaterialise(cond, cond[S_condroot])
3109
+ }
3110
+ // The keys of node `idx`, WITHOUT materialising any of its values. This is
3111
+ // the point of the whole exercise for enumeration: listing the names in a
3112
+ // large collection should cost a symbol-table read, not a full decode.
3113
+ function condenseKeys(cond, idx) {
3114
+ const enc = cond[S_condnode][idx]
3115
+ if (null == enc) {
3116
+ return []
3117
+ }
3118
+ const sym = cond[S_condsym]
3119
+ const out = []
3120
+ if (CONDENSE_MAP === enc[0]) {
3121
+ for (let j = 1; j < enc.length; j += 2) {
3122
+ out.push(sym[enc[j]])
3123
+ }
3124
+ return out
3125
+ }
3126
+ if (CONDENSE_LIST === enc[0]) {
3127
+ for (let j = 1; j < enc.length; j++) {
3128
+ out.push(S_MT + (j - 1))
3129
+ }
3130
+ return out
3131
+ }
3132
+ return []
3133
+ }
3134
+ // A cursor into a condensed structure. Reads resolve by integer index and
3135
+ // touch only the nodes on the path, so the cost of a lookup is proportional
3136
+ // to path depth and result size, never to total structure size.
3137
+ function condenseview(cond, idx, memo) {
3138
+ const start = null == idx ? (iscondensed(cond) ? cond[S_condroot] : -1) : idx
3139
+ // Shared materialisations, handed out ONLY by ref(). Threaded through at()
3140
+ // so every cursor into the same structure shares one memo - otherwise
3141
+ // ref() would hand out a different object per cursor and quietly stop
3142
+ // being the shared-reference escape hatch it claims to be.
3143
+ const refmemo = null == memo ? {} : memo
3144
+ const view = {
3145
+ // The value at path, materialised. Scalars come back directly; a
3146
+ // container comes back as an independent copy.
3147
+ get: (path) => condenseMaterialise(cond, condenseResolve(cond, start, path)),
3148
+ // Key names at path, with no value decoding at all.
3149
+ keys: (path) => {
3150
+ const at = condenseResolve(cond, start, path)
3151
+ return 0 > at ? [] : condenseKeys(cond, at)
3152
+ },
3153
+ has: (path) => 0 <= condenseResolve(cond, start, path),
3154
+ // Chainable cursor. Cheap: no decoding happens here.
3155
+ at: (path) => condenseview(cond, condenseResolve(cond, start, path), refmemo),
3156
+ value: () => condenseMaterialise(cond, start),
3157
+ size: () => {
3158
+ const enc = 0 > start ? null : cond[S_condnode][start]
3159
+ if (null == enc) {
3160
+ return 0
3161
+ }
3162
+ if (CONDENSE_MAP === enc[0]) {
3163
+ return (enc.length - 1) / 2
3164
+ }
3165
+ if (CONDENSE_LIST === enc[0]) {
3166
+ return enc.length - 1
3167
+ }
3168
+ return 0
3169
+ },
3170
+ exists: () => 0 <= start,
3171
+ // DANGER, and named to say so. Returns a SHARED materialisation: the same
3172
+ // object for the same node, every time. Mutating it corrupts every other
3173
+ // reader of that node, including ones reached by a different path,
3174
+ // because the structure is a DAG. Use value() unless a profile says this
3175
+ // matters.
3176
+ ref: () => {
3177
+ const k = S_MT + start
3178
+ if (undefined === refmemo[k]) {
3179
+ refmemo[k] = condenseMaterialise(cond, start)
3180
+ }
3181
+ return refmemo[k]
3182
+ },
3183
+ }
3184
+ return view
3185
+ }
2496
3186
 
2497
3187
  module.exports = {
2498
3188
  StructUtility,
@@ -2506,6 +3196,10 @@ module.exports = {
2506
3196
  re_escape,
2507
3197
 
2508
3198
  clone,
3199
+ condense,
3200
+ condenseview,
3201
+ expand,
3202
+ iscondensed,
2509
3203
  delprop,
2510
3204
  escre,
2511
3205
  escurl,