@voxgig/struct-js 0.1.6 → 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 +870 -179
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.6
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
@@ -846,7 +882,7 @@ function walk(
846
882
  // Merge a list of values into each other. Later values have
847
883
  // precedence. Nodes override scalars. Node kinds (list or map)
848
884
  // override each other, and do *not* merge. The first element is
849
- // modified.
885
+ // modified; the others are not.
850
886
  function merge(val, maxdepth) {
851
887
  // const md: number = null == maxdepth ? MAXDEPTH : maxdepth < 0 ? 0 : maxdepth
852
888
  const md = slice(maxdepth ?? MAXDEPTH, 0)
@@ -889,34 +925,32 @@ function merge(val, maxdepth) {
889
925
  dst[pI] = 0 < pI ? getprop(dst[pI - 1], key) : dst[pI]
890
926
  const tval = dst[pI]
891
927
  const vtype = typify(val)
892
- // Destination empty, so create node (unless override is class instance).
893
- if (NONE === tval && 0 === (T_instance & vtype)) {
894
- cur[pI] = islist(val) ? [] : {}
895
- }
896
928
  // Matching override and destination so continue with their values.
897
- else if (vtype === typify(tval)) {
929
+ if (vtype === typify(tval)) {
898
930
  cur[pI] = tval
899
931
  }
900
- // Override wins.
932
+ // Otherwise the override wins: a plain node is copied, taking
933
+ // nothing from the destination, so no later merge writes into it.
934
+ else if (0 === (T_instance & vtype)) {
935
+ cur[pI] = islist(val) ? [] : {}
936
+ dst[pI] = NONE
937
+ }
938
+ // A class instance is kept as is, so there is nothing to descend.
901
939
  else {
902
940
  cur[pI] = val
903
- // No need to descend when override wins (destination is discarded).
904
941
  val = NONE
905
942
  }
906
943
  }
907
- // console.log('BEFORE-END', pathify(path), '@', pI, key,
908
- // stringify(val, -1, 1), stringify(parent, -1, 1),
909
- // 'CUR=', stringify(cur, -1, 1), 'DST=', stringify(dst, -1, 1))
910
944
  return val
911
945
  }
912
- function after(key, _val, _parent, path) {
946
+ function after(key, _val, parent, path) {
913
947
  const cI = size(path)
914
948
  const target = cur[cI - 1]
915
949
  const value = cur[cI]
916
- // console.log('AFTER-PREP', pathify(path), '@', cI, cur, '|',
917
- // stringify(key, -1, 1), stringify(value, -1, 1), 'T=', stringify(target, -1, 1))
918
950
  setprop(target, key, value)
919
- return value
951
+ // walk writes this back into the override, so below the root it is
952
+ // the override's own child (_lookup keeps a null, getprop would not).
953
+ return 0 === cI ? value : _lookup(parent, key)
920
954
  }
921
955
  // Walk overriding node, creating paths in output as needed.
922
956
  out = walk(obj, before, after, maxdepth)
@@ -932,6 +966,12 @@ function merge(val, maxdepth) {
932
966
  // Set a value using a path. Missing path parts are created.
933
967
  // String paths create only maps. Use a string list to create list parts.
934
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
+ }
935
975
  const pathType = typify(path)
936
976
  const parts =
937
977
  0 < (T_list & pathType)
@@ -965,16 +1005,45 @@ function setpath(store, path, val, injdef) {
965
1005
  }
966
1006
  function getpath(store, path, injdef) {
967
1007
  // Operate on a string array.
968
- const parts = islist(path)
969
- ? path
970
- : 'string' === typeof path
971
- ? path.split(S_DT)
972
- : 'number' === typeof path
973
- ? [strkey(path)]
974
- : 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
+ }
975
1025
  if (NONE === parts) {
976
1026
  return NONE
977
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
+ }
978
1047
  // let root = store
979
1048
  let val = store
980
1049
  const base = getprop(injdef, S_base)
@@ -1387,8 +1456,7 @@ const transform_PACK = (inj, _val, _ref, store) => {
1387
1456
  // TODO: not found ref should removed key (setprop NONE)
1388
1457
  // Reference original spec (enables recursice transformations)
1389
1458
  // Format: ['`$REF`', '`spec-path`']
1390
- const transform_REF = (inj, val, _ref, store) => {
1391
- const { nodes } = inj
1459
+ const transform_REF = (inj, _val, _ref, store) => {
1392
1460
  if (M_VAL !== inj.mode) {
1393
1461
  return NONE
1394
1462
  }
@@ -1399,10 +1467,7 @@ const transform_REF = (inj, val, _ref, store) => {
1399
1467
  const spec = getprop(store, S_DSPEC)()
1400
1468
  const dpath = slice(inj.path, 1)
1401
1469
  const ref = getpath(spec, refpath, {
1402
- // TODO: test relative refs
1403
- // dpath: inj.path.slice(1),
1404
1470
  dpath,
1405
- // dparent: getpath(spec, inj.path.slice(1))
1406
1471
  dparent: getpath(spec, dpath),
1407
1472
  })
1408
1473
  let hasSubRef = false
@@ -1414,30 +1479,20 @@ const transform_REF = (inj, val, _ref, store) => {
1414
1479
  return v
1415
1480
  })
1416
1481
  }
1417
- let tref = clone(ref)
1418
- const cpath = slice(inj.path, -3)
1419
- const tpath = slice(inj.path, -1)
1420
- let tcur = getpath(store, cpath)
1421
- let tval = getpath(store, tpath)
1422
- let rval = NONE
1423
- if (!hasSubRef || NONE !== tval) {
1424
- const tinj = inj.child(0, [getelem(tpath, -1)])
1425
- tinj.path = tpath
1426
- tinj.nodes = slice(inj.nodes, -1)
1427
- tinj.parent = getelem(nodes, -2)
1428
- tinj.val = tref
1429
- tinj.dpath = flatten([cpath])
1430
- tinj.dparent = tcur
1431
- inject(tref, store, tinj)
1432
- rval = tinj.val
1433
- } else {
1434
- rval = NONE
1435
- }
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.
1436
1487
  const grandparent = inj.setval(rval, 2)
1437
- if (islist(grandparent) && inj.prior) {
1438
- 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
+ }
1439
1494
  }
1440
- return val
1495
+ return SKIP
1441
1496
  }
1442
1497
  const transform_FORMAT = (inj, _val, _ref, store) => {
1443
1498
  // console.log('FORMAT-START', inj, _val)
@@ -1601,7 +1656,8 @@ const validate_STRING = (inj) => {
1601
1656
  }
1602
1657
  const validate_TYPE = (inj, _val, ref) => {
1603
1658
  const tname = slice(ref, 1).toLowerCase()
1604
- 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)
1605
1661
  let out = _lookup(inj.dparent, inj.key)
1606
1662
  const t = typify(out)
1607
1663
  // console.log('TYPE', tname, typev, tn(typev), 'O=', t, tn(t), out, 'C=', t & typev)
@@ -1631,7 +1687,7 @@ const validate_CHILD = (inj) => {
1631
1687
  if (NONE == tval) {
1632
1688
  tval = {}
1633
1689
  } else if (!ismap(tval)) {
1634
- inj.errs.push(_invalidTypeMsg(slice(inj.path, -1), S_object, typify(tval), tval), 'V0220')
1690
+ // _validation reports the mismatch, once.
1635
1691
  return NONE
1636
1692
  }
1637
1693
  const ckeys = keysof(tval)
@@ -1659,14 +1715,6 @@ const validate_CHILD = (inj) => {
1659
1715
  return NONE
1660
1716
  }
1661
1717
  if (!islist(inj.dparent)) {
1662
- const msg = _invalidTypeMsg(
1663
- slice(inj.path, -1),
1664
- S_list,
1665
- typify(inj.dparent),
1666
- inj.dparent,
1667
- 'V0230',
1668
- )
1669
- inj.errs.push(msg)
1670
1718
  inj.keyI = size(parent)
1671
1719
  return inj.dparent
1672
1720
  }
@@ -1690,52 +1738,36 @@ const validate_CHILD = (inj) => {
1690
1738
  }
1691
1739
  return NONE
1692
1740
  }
1693
- // TODO: implement SOME, ALL
1694
- // FIX: ONE should mean exactly one, not at least one (=SOME)
1695
- // TODO: implement a generate validate_ALT to do all of these
1696
- // Match at least one of the specified shapes.
1697
- // Syntax: ['`$ONE`', alt0, alt1, ...]
1698
- const validate_ONE = (inj, _val, _ref, store) => {
1699
- const { mode, parent, keyI } = inj
1741
+ const validate_EXACT = (inj) => {
1742
+ const { mode, parent, key, keyI } = inj
1700
1743
  // Only operate in val mode, since parent is a list.
1701
1744
  if (M_VAL === mode) {
1702
1745
  if (!islist(parent) || 0 !== keyI) {
1703
1746
  inj.errs.push(
1704
- 'The $ONE validator at field ' +
1747
+ 'The $EXACT validator at field ' +
1705
1748
  pathify(inj.path, 1, 1) +
1706
1749
  ' must be the first element of an array.',
1707
1750
  )
1708
1751
  return
1709
1752
  }
1753
+ const cval = _slotval(inj)
1710
1754
  inj.keyI = size(inj.keys)
1711
- // Clean up structure, replacing [$ONE, ...] with current
1712
- inj.setval(inj.dparent, 2)
1713
- inj.path = slice(inj.path, -1)
1714
- inj.key = getelem(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)
1715
1758
  let tvals = slice(parent, 1)
1716
1759
  if (0 === size(tvals)) {
1717
1760
  inj.errs.push(
1718
- 'The $ONE validator at field ' +
1761
+ 'The $EXACT validator at field ' +
1719
1762
  pathify(inj.path, 1, 1) +
1720
1763
  ' must have at least one argument.',
1721
1764
  )
1722
- return
1765
+ return SKIP
1723
1766
  }
1724
- // See if we can find a match.
1767
+ // See if we can find an exact value match.
1725
1768
  for (let tval of tvals) {
1726
- // If match, then errs.length = 0
1727
- let terrs = []
1728
- const vstore = merge([{}, store], 1)
1729
- vstore.$TOP = inj.dparent
1730
- const vcurrent = validate(inj.dparent, tval, {
1731
- extra: vstore,
1732
- errs: terrs,
1733
- meta: inj.meta,
1734
- })
1735
- inj.setval(vcurrent, -2)
1736
- // Accept current value if there was a match
1737
- if (0 === size(terrs)) {
1738
- return
1769
+ if (_deepequal(tval, cval)) {
1770
+ return SKIP
1739
1771
  }
1740
1772
  }
1741
1773
  // There was no match.
@@ -1750,55 +1782,74 @@ const validate_ONE = (inj, _val, _ref, store) => {
1750
1782
  inj.errs.push(
1751
1783
  _invalidTypeMsg(
1752
1784
  inj.path,
1753
- (1 < size(tvals) ? 'one of ' : '') + valdesc,
1754
- typify(inj.dparent),
1755
- inj.dparent,
1756
- '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',
1757
1792
  ),
1758
1793
  )
1794
+ return SKIP
1795
+ } else {
1796
+ delprop(parent, key)
1759
1797
  }
1760
1798
  }
1761
- const validate_EXACT = (inj) => {
1762
- const { mode, parent, key, keyI } = inj
1763
- // Only operate in val mode, since parent is a list.
1764
- if (M_VAL === mode) {
1765
- if (!islist(parent) || 0 !== keyI) {
1766
- inj.errs.push(
1767
- 'The $EXACT validator at field ' +
1768
- pathify(inj.path, 1, 1) +
1769
- ' must be the first element of an array.',
1770
- )
1771
- return
1772
- }
1773
- inj.keyI = size(inj.keys)
1774
- // Clean up structure, replacing [$EXACT, ...] with current data parent
1775
- inj.setval(inj.dparent, 2)
1776
- // inj.path = slice(inj.path, 0, size(inj.path) - 1)
1777
- inj.path = slice(inj.path, 0, -1)
1778
- inj.key = getelem(inj.path, -1)
1779
- let tvals = slice(parent, 1)
1780
- if (0 === size(tvals)) {
1781
- inj.errs.push(
1782
- 'The $EXACT validator at field ' +
1783
- pathify(inj.path, 1, 1) +
1784
- ' must have at least one argument.',
1785
- )
1786
- 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
1787
1847
  }
1788
- // See if we can find an exact value match.
1789
- let currentstr = undefined
1790
- for (let tval of tvals) {
1791
- let exactmatch = tval === inj.dparent
1792
- if (!exactmatch && isnode(tval)) {
1793
- currentstr = undefined === currentstr ? stringify(inj.dparent) : currentstr
1794
- const tvalstr = stringify(tval)
1795
- exactmatch = tvalstr === currentstr
1796
- }
1797
- if (exactmatch) {
1798
- return
1799
- }
1848
+ if (_admits(cval, tvals[tI], inj, store)) {
1849
+ admitted++
1800
1850
  }
1801
- // There was no match.
1851
+ }
1852
+ if (admitted < lo || hi < admitted) {
1802
1853
  const valdesc = replace(
1803
1854
  join(
1804
1855
  items(tvals, (n) => stringify(n[1])),
@@ -1808,21 +1859,159 @@ const validate_EXACT = (inj) => {
1808
1859
  (_m, p1) => p1.toLowerCase(),
1809
1860
  )
1810
1861
  inj.errs.push(
1811
- _invalidTypeMsg(
1812
- inj.path,
1813
- (1 < size(inj.path) ? '' : 'value ') +
1814
- 'exactly equal to ' +
1815
- (1 === size(tvals) ? '' : 'one of ') +
1816
- valdesc,
1817
- typify(inj.dparent),
1818
- inj.dparent,
1819
- 'V0110',
1820
- ),
1862
+ _invalidTypeMsg(inj.path, countdesc + ' of ' + valdesc, typify(cval), cval, 'V0310'),
1821
1863
  )
1822
- } else {
1823
- delprop(parent, key)
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
1824
1959
  }
1825
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
+ )
2014
+ }
1826
2015
  // This is the "modify" argument to inject. Use this to perform
1827
2016
  // generic validation. Runs *after* any special commands.
1828
2017
  const _validation = (pval, key, parent, inj) => {
@@ -1934,8 +2123,12 @@ function validate(
1934
2123
  $INSTANCE: validate_TYPE,
1935
2124
  $ANY: validate_ANY,
1936
2125
  $CHILD: validate_CHILD,
1937
- $ONE: validate_ONE,
1938
2126
  $EXACT: validate_EXACT,
2127
+ $NOF: validate_NOF,
2128
+ $ALL: validate_ALL,
2129
+ $LEN: validate_LEN,
2130
+ $RANGE: validate_RANGE,
2131
+ $LIKE: validate_LIKE,
1939
2132
  },
1940
2133
  getdef(extra, {}),
1941
2134
  // A special top level value to collect errors.
@@ -1948,13 +2141,19 @@ function validate(
1948
2141
  )
1949
2142
  let meta = getprop(injdef, 'meta', {})
1950
2143
  setprop(meta, S_BEXACT, getprop(meta, S_BEXACT, false))
1951
- const out = transform(data, spec, {
1952
- meta,
1953
- extra: store,
1954
- modify: _validation,
1955
- handler: _validatehandler,
1956
- errs,
1957
- })
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
+ })
1958
2157
  const generr = 0 < size(errs) && !collect
1959
2158
  if (generr) {
1960
2159
  throw new Error(join(errs, ' | '))
@@ -2032,6 +2231,10 @@ const select_NOT = (inj, _val, _ref, store) => {
2032
2231
  }
2033
2232
  }
2034
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
+ }
2035
2238
  if (M_KEYPRE === inj.mode) {
2036
2239
  const term = _lookup(inj.parent, inj.key)
2037
2240
  // const src = getprop(store, inj.base, store)
@@ -2102,12 +2305,7 @@ function select(children, query) {
2102
2305
  },
2103
2306
  }
2104
2307
  const q = clone(query)
2105
- walk(q, (_k, v) => {
2106
- if (ismap(v)) {
2107
- setprop(v, '`$OPEN`', getprop(v, '`$OPEN`', true))
2108
- }
2109
- return v
2110
- })
2308
+ _openquery(q)
2111
2309
  for (const child of children) {
2112
2310
  injdef.errs = []
2113
2311
  validate(child, clone(q), injdef)
@@ -2117,6 +2315,26 @@ function select(children, query) {
2117
2315
  }
2118
2316
  return results
2119
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
+ }
2120
2338
  // Injection state used for recursive injection into JSON - like data structures.
2121
2339
  class Injection {
2122
2340
  constructor(val, parent) {
@@ -2248,6 +2466,139 @@ function _invalidTypeMsg(path, needtype, vt, v, _whence) {
2248
2466
  '.'
2249
2467
  )
2250
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
+ }
2251
2602
  // Default inject handler for transforms. If the path resolves to a function,
2252
2603
  // call the function passing the injection inj. This is how transforms operate.
2253
2604
  const _injecthandler = (inj, val, ref, store) => {
@@ -2429,9 +2780,12 @@ function injectChild(child, store, inj) {
2429
2780
  class StructUtility {
2430
2781
  constructor() {
2431
2782
  this.clone = clone
2783
+ this.condense = condense
2784
+ this.condenseview = condenseview
2432
2785
  this.delprop = delprop
2433
2786
  this.escre = escre
2434
2787
  this.escurl = escurl
2788
+ this.expand = expand
2435
2789
  this.filter = filter
2436
2790
  this.flatten = flatten
2437
2791
  this.getdef = getdef
@@ -2441,6 +2795,7 @@ class StructUtility {
2441
2795
  this.haskey = haskey
2442
2796
  this.inject = inject
2443
2797
  this.isempty = isempty
2798
+ this.iscondensed = iscondensed
2444
2799
  this.isfunc = isfunc
2445
2800
  this.iskey = iskey
2446
2801
  this.islist = islist
@@ -2496,6 +2851,338 @@ class StructUtility {
2496
2851
  this.injectChild = injectChild
2497
2852
  }
2498
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
+ }
2499
3186
 
2500
3187
  module.exports = {
2501
3188
  StructUtility,
@@ -2509,6 +3196,10 @@ module.exports = {
2509
3196
  re_escape,
2510
3197
 
2511
3198
  clone,
3199
+ condense,
3200
+ condenseview,
3201
+ expand,
3202
+ iscondensed,
2512
3203
  delprop,
2513
3204
  escre,
2514
3205
  escurl,