@voxgig/struct 0.2.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  /* Copyright (c) 2025-2026 Voxgig Ltd. MIT LICENSE. */
2
2
 
3
- // VERSION: @voxgig/struct 0.2.1
3
+ // VERSION: @voxgig/struct 0.3.0
4
4
 
5
5
  /* Voxgig Struct
6
6
  * =============
@@ -747,10 +747,14 @@ function stringify(val: any, maxlen?: number, pretty?: any): string {
747
747
  try {
748
748
  valstr = JSON.stringify(val, function (_key: string, val: any) {
749
749
  if (val !== null && typeof val === 'object' && !Array.isArray(val)) {
750
+ // Emit map keys in sorted order (deterministic output). Building the
751
+ // sorted copy directly avoids the intermediate key/tuple arrays that
752
+ // items() would allocate for every node.
753
+ const keys = Object.keys(val).sort()
750
754
  const sortedObj: any = {}
751
- items(val, (n) => {
752
- sortedObj[n[0]] = val[n[0]]
753
- })
755
+ for (let i = 0; i < keys.length; i++) {
756
+ sortedObj[keys[i]] = val[keys[i]]
757
+ }
754
758
  return sortedObj
755
759
  }
756
760
  return val
@@ -839,13 +843,37 @@ function pathify(val: any, startin?: number, endin?: number) {
839
843
  // NOTE: function and instance values are copied, *not* cloned.
840
844
  function clone(val: any): any {
841
845
  const refs: any[] = []
842
- const reftype = T_function | T_instance
843
- const replacer: any = (_k: any, v: any) =>
844
- 0 < (reftype & typify(v)) ? (refs.push(v), '`$REF:' + (refs.length - 1) + '`') : v
846
+ // Copy (don't clone) functions and non-plain-object instances by reference.
847
+ // This inlines `0 < ((T_function | T_instance) & typify(v))` — the same set
848
+ // of values (functions, class instances, bigints) — without a typify() call
849
+ // per value, which dominated clone's cost.
850
+ const replacer: any = (_k: any, v: any) => {
851
+ const t = typeof v
852
+ if (
853
+ S_function === t ||
854
+ 'bigint' === t ||
855
+ (S_object === t &&
856
+ null !== v &&
857
+ !Array.isArray(v) &&
858
+ v.constructor instanceof Function &&
859
+ 'Object' !== v.constructor.name &&
860
+ 'Array' !== v.constructor.name)
861
+ ) {
862
+ return (refs.push(v), '`$REF:' + (refs.length - 1) + '`')
863
+ }
864
+ return v
865
+ }
845
866
  const reviver: any = (_k: any, v: any, m: any) =>
846
867
  S_string === typeof v ? ((m = re_find(R_CLONE_REF, v)), m ? refs[m[1]] : v) : v
847
- const out = NONE === val ? NONE : JSON.parse(JSON.stringify(val, replacer), reviver)
848
- return out
868
+ if (NONE === val) {
869
+ return NONE
870
+ }
871
+ const json = JSON.stringify(val, replacer)
872
+ // A reviver forces V8 off its native JSON.parse fast path (a large cost). It
873
+ // is only needed to swap `$REF:n` placeholders back for the copied-by-ref
874
+ // functions/instances the replacer captured — so when none were captured,
875
+ // parse without it.
876
+ return 0 === refs.length ? JSON.parse(json) : JSON.parse(json, reviver)
849
877
  }
850
878
 
851
879
  // Define a JSON Object using function arguments.
@@ -884,6 +912,21 @@ function delprop<PARENT>(parent: PARENT, key: any): PARENT {
884
912
  return parent
885
913
  }
886
914
 
915
+ // A condensed structure is a DAG: one subtree can be reached by many
916
+ // references, so an in-place write would be visible through all of them.
917
+ // Raising is the decided contract (design Q1) - it can be relaxed to
918
+ // copy-on-write later without breaking any caller, where the reverse is not
919
+ // true. expand() gives an ordinary mutable copy.
920
+ //
921
+ // Checked AFTER the key validation: both helpers define an invalid key as
922
+ // ignored, so a call that cannot write must not start throwing merely
923
+ // because the store is condensed.
924
+ if (iscondensed(parent as any)) {
925
+ throw new Error(
926
+ 'struct: condensed structures are immutable - ' + 'expand() first, then modify the copy',
927
+ )
928
+ }
929
+
887
930
  if (ismap(parent)) {
888
931
  key = strkey(key)
889
932
  delete (parent as any)[key]
@@ -921,6 +964,21 @@ function setprop<PARENT>(parent: PARENT, key: any, val: any): PARENT {
921
964
  return parent
922
965
  }
923
966
 
967
+ // A condensed structure is a DAG: one subtree can be reached by many
968
+ // references, so an in-place write would be visible through all of them.
969
+ // Raising is the decided contract (design Q1) - it can be relaxed to
970
+ // copy-on-write later without breaking any caller, where the reverse is not
971
+ // true. expand() gives an ordinary mutable copy.
972
+ //
973
+ // Checked AFTER the key validation: both helpers define an invalid key as
974
+ // ignored, so a call that cannot write must not start throwing merely
975
+ // because the store is condensed.
976
+ if (iscondensed(parent as any)) {
977
+ throw new Error(
978
+ 'struct: condensed structures are immutable - ' + 'expand() first, then modify the copy',
979
+ )
980
+ }
981
+
924
982
  if (ismap(parent)) {
925
983
  key = S_MT + key
926
984
  const pany = parent as any
@@ -1006,9 +1064,18 @@ function walk(
1006
1064
  childPath[i] = path[i]
1007
1065
  }
1008
1066
 
1009
- for (const [ckey, child] of items(out)) {
1067
+ // Iterate the sorted keys directly (as items() would order them) without
1068
+ // building the intermediate [key, value] tuple array items() allocates for
1069
+ // every node.
1070
+ const ckeys = keysof(out)
1071
+ for (let cI = 0; cI < ckeys.length; cI++) {
1072
+ const ckey = ckeys[cI]
1010
1073
  childPath[depth] = S_MT + ckey
1011
- setprop(out, ckey, walk(child, before, after, maxdepth, ckey, out, childPath, pool))
1074
+ setprop(
1075
+ out,
1076
+ ckey,
1077
+ walk((out as any)[ckey], before, after, maxdepth, ckey, out, childPath, pool),
1078
+ )
1012
1079
  }
1013
1080
  }
1014
1081
 
@@ -1074,13 +1141,15 @@ function merge(val: any, maxdepth?: number): any {
1074
1141
  dst[pI] = 0 < pI ? getprop(dst[pI - 1], key) : dst[pI]
1075
1142
  const tval = dst[pI]
1076
1143
 
1144
+ const vtype = typify(val)
1145
+
1077
1146
  // Destination empty, so create node (unless override is class instance).
1078
- if (NONE === tval && 0 === (T_instance & typify(val))) {
1147
+ if (NONE === tval && 0 === (T_instance & vtype)) {
1079
1148
  cur[pI] = islist(val) ? [] : {}
1080
1149
  }
1081
1150
 
1082
1151
  // Matching override and destination so continue with their values.
1083
- else if (typify(val) === typify(tval)) {
1152
+ else if (vtype === typify(tval)) {
1084
1153
  cur[pI] = tval
1085
1154
  }
1086
1155
 
@@ -1134,6 +1203,13 @@ function setpath(
1134
1203
  val: any,
1135
1204
  injdef?: Partial<Injection>,
1136
1205
  ) {
1206
+ // Same contract as setprop/delprop: a condensed store is immutable.
1207
+ if (iscondensed(store)) {
1208
+ throw new Error(
1209
+ 'struct: condensed structures are immutable - ' + 'expand() first, then modify the copy',
1210
+ )
1211
+ }
1212
+
1137
1213
  const pathType = typify(path)
1138
1214
 
1139
1215
  const parts =
@@ -1186,6 +1262,26 @@ function getpath(store: any, path: number | string | string[], injdef?: Partial<
1186
1262
  return NONE
1187
1263
  }
1188
1264
 
1265
+ // TRANSPARENT CONDENSED READ. A condensed store answers the same path with
1266
+ // the same value as the ordinary node it was built from - the caller does
1267
+ // not need to know which it holds. Only the nodes ON the path are touched,
1268
+ // so this never materialises the whole structure.
1269
+ if (iscondensed(store)) {
1270
+ // The fast path applies only when there are no injection options to
1271
+ // honour. base/dparent/dpath/meta change what the walk below resolves
1272
+ // against, and silently ignoring them would make a condensed store
1273
+ // answer differently from the node it was built from - the opposite of
1274
+ // the transparent-read contract. Rare enough to be worth materialising.
1275
+ if (null == injdef || null == getprop(injdef, S_base)) {
1276
+ const found = condenseResolve(store, (store as any)[S_condroot], parts)
1277
+ const val = 0 > found ? undefined : condenseMaterialise(store, found)
1278
+ // Group A null-as-absent: an ordinary getpath observes a stored null
1279
+ // through getprop and reports it as absent, so this must too.
1280
+ return null == val ? undefined : val
1281
+ }
1282
+ store = expand(store)
1283
+ }
1284
+
1189
1285
  // let root = store
1190
1286
  let val = store
1191
1287
  const base = getprop(injdef, S_base)
@@ -1229,8 +1325,10 @@ function getpath(store: any, path: number | string | string[], injdef?: Partial<
1229
1325
  part = stringify(getpath(getprop(injdef, 'meta'), slice(part, 6, -1)))
1230
1326
  }
1231
1327
 
1232
- // $$ escapes $
1233
- part = re_replace(R_DOUBLE_DOLLAR, part, '$')
1328
+ // $$ escapes $ (skip the regex for the common no-`$$` segment).
1329
+ if (-1 !== part.indexOf('$$')) {
1330
+ part = re_replace(R_DOUBLE_DOLLAR, part, '$')
1331
+ }
1234
1332
 
1235
1333
  if (S_MT === part) {
1236
1334
  let ascends = 0
@@ -2064,15 +2162,26 @@ const validate_CHILD: Injector = (inj: Injection) => {
2064
2162
  return inj.dparent
2065
2163
  }
2066
2164
 
2067
- // Clone children abd reset inj key index.
2165
+ // Clone children and reset inj key index.
2068
2166
  // The inject child loop will now iterate over the cloned children,
2069
- // validating them againt the current list values.
2167
+ // validating them against the current list values.
2070
2168
  items(inj.dparent, (n) => setprop(parent, n[0], clone(childtm)))
2071
2169
  slice(parent, 0, inj.dparent.length, true)
2072
- inj.keyI = 0
2073
2170
 
2074
- const out = getprop(inj.dparent, 0)
2075
- return out
2171
+ // NOTE: modifying inj! This extends the child value loop in inject
2172
+ // to cover every cloned child.
2173
+ for (let ckeyI = size(keys); ckeyI < size(parent); ckeyI++) {
2174
+ keys.push(strkey(ckeyI))
2175
+ }
2176
+
2177
+ // Restart the child value loop at the first element (the loop
2178
+ // increments keyI on resume) so that the first element is also
2179
+ // validated against the child template.
2180
+ inj.keyI = -1
2181
+
2182
+ // SKIP leaves the cloned child template in place at the first
2183
+ // element so the resumed loop can validate it.
2184
+ return SKIP
2076
2185
  }
2077
2186
 
2078
2187
  return NONE
@@ -2982,9 +3091,12 @@ function injectChild(child: any, store: any, inj: Injection): Injection {
2982
3091
 
2983
3092
  class StructUtility {
2984
3093
  clone = clone
3094
+ condense = condense
3095
+ condenseview = condenseview
2985
3096
  delprop = delprop
2986
3097
  escre = escre
2987
3098
  escurl = escurl
3099
+ expand = expand
2988
3100
  filter = filter
2989
3101
  flatten = flatten
2990
3102
  getdef = getdef
@@ -2994,6 +3106,7 @@ class StructUtility {
2994
3106
  haskey = haskey
2995
3107
  inject = inject
2996
3108
  isempty = isempty
3109
+ iscondensed = iscondensed
2997
3110
  isfunc = isfunc
2998
3111
  iskey = iskey
2999
3112
  islist = islist
@@ -3019,6 +3132,13 @@ class StructUtility {
3019
3132
  validate = validate
3020
3133
  walk = walk
3021
3134
 
3135
+ re_compile = re_compile
3136
+ re_find = re_find
3137
+ re_find_all = re_find_all
3138
+ re_replace = re_replace
3139
+ re_test = re_test
3140
+ re_escape = re_escape
3141
+
3022
3142
  SKIP = SKIP
3023
3143
  DELETE = DELETE
3024
3144
 
@@ -3047,9 +3167,481 @@ class StructUtility {
3047
3167
  injectChild = injectChild
3048
3168
  }
3049
3169
 
3170
+ // ---------------------------------------------------------------------------
3171
+ // CONDENSED STRUCTURES
3172
+ //
3173
+ // A condensed structure holds the same information as a JSON-shaped node in a
3174
+ // fraction of the space, and can be read WITHOUT materialising it. Three
3175
+ // mechanisms, all in one format:
3176
+ //
3177
+ // intern a symbol table holds each distinct map key and string value once
3178
+ // share identical subtrees become ONE node with many references (a DAG)
3179
+ // lazy a reader resolves a path by walking integer indexes, touching
3180
+ // only the nodes on that path
3181
+ //
3182
+ // The shape:
3183
+ //
3184
+ // { "$condense": 1, format version
3185
+ // "sym": [ ... ], distinct strings, sorted (so lookup can bisect)
3186
+ // "node": [ ... ], integer-encoded nodes, children before parents
3187
+ // "root": 12 } index into node[]
3188
+ //
3189
+ // Each node is one of:
3190
+ //
3191
+ // map [0, k0, v0, k1, v1, ...] k ascending symbol ids, v node refs
3192
+ // list [1, v0, v1, ...] node refs
3193
+ // string [2, symId]
3194
+ // number [3, value]
3195
+ // true [4] false [5] null [6]
3196
+ //
3197
+ // Two properties are load-bearing rather than incidental:
3198
+ //
3199
+ // Map keys ascend, because keysof() sorts. That makes output byte-stable
3200
+ // (generators depend on it) and lets a key lookup bisect rather than scan.
3201
+ //
3202
+ // References are integer indexes into a post-order table, so every ref
3203
+ // points BACKWARDS. Sharing is therefore free — two identical subtrees
3204
+ // intern to one node and two refs, with no dedup pass at read time — and a
3205
+ // reader can never loop.
3206
+ //
3207
+ // The transport is JSON arrays of integers on purpose. The FORMAT is defined
3208
+ // here, but TOKENIZING is left to each language's own JSON parser: mature,
3209
+ // fast, memory-safe, already present, and nothing to keep in parity across
3210
+ // ports. A binary profile ($condense: 2) is a future option, deliberately
3211
+ // deferred - it is worth perhaps 2-3x and costs a hand-written decoder per
3212
+ // language.
3213
+ //
3214
+ // IMMUTABILITY. Sharing makes a condensed structure a DAG, so a mutation
3215
+ // through one reference would be visible through every other. Rather than
3216
+ // make that hazard the caller's problem, it is designed out: mutating
3217
+ // helpers RAISE on a condensed node, and expand()/value() always return an
3218
+ // independent copy. ref() is the one opt-in escape hatch and is named to be
3219
+ // alarming.
3220
+
3221
+ const CONDENSE_VERSION = 1
3222
+
3223
+ const CONDENSE_MAP = 0
3224
+ const CONDENSE_LIST = 1
3225
+ const CONDENSE_STR = 2
3226
+ const CONDENSE_NUM = 3
3227
+ const CONDENSE_TRUE = 4
3228
+ const CONDENSE_FALSE = 5
3229
+ const CONDENSE_NULL = 6
3230
+
3231
+ const S_condense = '$condense'
3232
+ const S_condsym = 'sym'
3233
+ const S_condnode = 'node'
3234
+ const S_condroot = 'root'
3235
+
3236
+ // Is this a condensed structure? Checked structurally rather than by a marker
3237
+ // alone, so an ordinary map that happens to carry a `$condense` key is not
3238
+ // mistaken for one.
3239
+ // Compare by UNICODE CODE POINT, not by UTF-16 code unit.
3240
+ //
3241
+ // JavaScript's default string sort compares UTF-16 code units, which orders
3242
+ // an astral character BEFORE a high-BMP one; Python, Go and Rust all compare
3243
+ // by code point (equivalently, by UTF-8 bytes). A symbol table sorted the
3244
+ // JavaScript way would make two conforming ports emit different bytes for the
3245
+ // same input, which is exactly the byte-stability the format promises. Code
3246
+ // point order is the portable choice, so it is specified rather than
3247
+ // inherited.
3248
+ function condenseCmp(a: string, b: string): number {
3249
+ let i = 0
3250
+ let j = 0
3251
+ while (i < a.length && j < b.length) {
3252
+ const ca = a.codePointAt(i) as number
3253
+ const cb = b.codePointAt(j) as number
3254
+ if (ca !== cb) {
3255
+ return ca < cb ? -1 : 1
3256
+ }
3257
+ i += 0xffff < ca ? 2 : 1
3258
+ j += 0xffff < cb ? 2 : 1
3259
+ }
3260
+ return a.length - i - (b.length - j)
3261
+ }
3262
+
3263
+ // Assign a key that may be `__proto__`.
3264
+ //
3265
+ // Plain assignment to `__proto__` invokes the inherited setter instead of
3266
+ // creating an own property, so a model carrying that key or string value
3267
+ // would be silently corrupted - it is valid JSON and Seneca-adjacent data
3268
+ // really does use `$`-ish and `__`-ish names.
3269
+ function condenseSet(obj: any, key: string, val: any) {
3270
+ if ('__proto__' === key) {
3271
+ Object.defineProperty(obj, key, {
3272
+ value: val,
3273
+ enumerable: true,
3274
+ writable: true,
3275
+ configurable: true,
3276
+ })
3277
+ } else {
3278
+ obj[key] = val
3279
+ }
3280
+ }
3281
+
3282
+ function iscondensed(val: any): boolean {
3283
+ // The version must MATCH, not merely be numeric: a future profile would
3284
+ // otherwise be decoded under this one's schema.
3285
+ return (
3286
+ ismap(val) &&
3287
+ CONDENSE_VERSION === (val as any)[S_condense] &&
3288
+ islist((val as any)[S_condsym]) &&
3289
+ islist((val as any)[S_condnode]) &&
3290
+ 'number' === typeof (val as any)[S_condroot]
3291
+ )
3292
+ }
3293
+
3294
+ // Condense any JSON-shaped node. Pure: the same input always produces a
3295
+ // byte-identical result, on every port.
3296
+ function condense(val: any): any {
3297
+ // Pass one: every distinct map key and string value, once, sorted.
3298
+ const symset: { [sym: string]: boolean } = Object.create(null)
3299
+
3300
+ const collect = (n: any) => {
3301
+ if (ismap(n)) {
3302
+ const keys = keysof(n)
3303
+ for (let i = 0; i < keys.length; i++) {
3304
+ symset[keys[i]] = true
3305
+ collect((n as any)[keys[i]])
3306
+ }
3307
+ } else if (islist(n)) {
3308
+ for (let i = 0; i < n.length; i++) {
3309
+ collect(n[i])
3310
+ }
3311
+ } else if ('string' === typeof n) {
3312
+ symset[n] = true
3313
+ }
3314
+ }
3315
+ collect(val)
3316
+
3317
+ const sym = Object.keys(symset).sort(condenseCmp)
3318
+ const symid: { [sym: string]: number } = Object.create(null)
3319
+ for (let i = 0; i < sym.length; i++) {
3320
+ symid[sym[i]] = i
3321
+ }
3322
+
3323
+ // Pass two: build post-order, interning on the canonical encoding. Because
3324
+ // children are built first, identical subtrees have already been interned
3325
+ // by the time a parent references them, so sharing costs nothing extra.
3326
+ const node: any[][] = []
3327
+ const seen: { [enc: string]: number } = Object.create(null)
3328
+
3329
+ const intern = (enc: any[]): number => {
3330
+ // The kind tag leads every encoding, so a string node and a number node
3331
+ // can never collide on the same joined key.
3332
+ const enckey = enc.join(',')
3333
+ const hit = seen[enckey]
3334
+ if (undefined !== hit) {
3335
+ return hit
3336
+ }
3337
+ const idx = node.length
3338
+ node.push(enc)
3339
+ seen[enckey] = idx
3340
+ return idx
3341
+ }
3342
+
3343
+ const build = (n: any): number => {
3344
+ if (ismap(n)) {
3345
+ const enc: any[] = [CONDENSE_MAP]
3346
+ // keysof sorts, so the key ids ascend and lookup can bisect.
3347
+ const keys = keysof(n)
3348
+ for (let i = 0; i < keys.length; i++) {
3349
+ enc.push(symid[keys[i]])
3350
+ enc.push(build((n as any)[keys[i]]))
3351
+ }
3352
+ return intern(enc)
3353
+ }
3354
+ if (islist(n)) {
3355
+ const enc: any[] = [CONDENSE_LIST]
3356
+ for (let i = 0; i < n.length; i++) {
3357
+ enc.push(build(n[i]))
3358
+ }
3359
+ return intern(enc)
3360
+ }
3361
+ if ('string' === typeof n) {
3362
+ return intern([CONDENSE_STR, symid[n]])
3363
+ }
3364
+ if ('number' === typeof n) {
3365
+ return intern([CONDENSE_NUM, n])
3366
+ }
3367
+ if (true === n) {
3368
+ return intern([CONDENSE_TRUE])
3369
+ }
3370
+ if (false === n) {
3371
+ return intern([CONDENSE_FALSE])
3372
+ }
3373
+ return intern([CONDENSE_NULL])
3374
+ }
3375
+
3376
+ const root = build(val)
3377
+
3378
+ const out: any = {}
3379
+ out[S_condense] = CONDENSE_VERSION
3380
+ out[S_condsym] = sym
3381
+ out[S_condnode] = node
3382
+ out[S_condroot] = root
3383
+ return out
3384
+ }
3385
+
3386
+ // Resolve a symbol to its id by bisecting the sorted symbol table. -1 when
3387
+ // the string does not occur anywhere in the structure, which is itself a fast
3388
+ // negative answer for a key lookup.
3389
+ function condenseSymId(cond: any, key: string): number {
3390
+ const sym = (cond as any)[S_condsym]
3391
+ let lo = 0
3392
+ let hi = sym.length - 1
3393
+ while (lo <= hi) {
3394
+ const mid = (lo + hi) >> 1
3395
+ if (sym[mid] === key) {
3396
+ return mid
3397
+ }
3398
+ if (0 > condenseCmp(sym[mid], key)) {
3399
+ lo = mid + 1
3400
+ } else {
3401
+ hi = mid - 1
3402
+ }
3403
+ }
3404
+ return -1
3405
+ }
3406
+
3407
+ // The node index of `key` inside node `idx`, or -1. Touches only this node.
3408
+ function condenseChild(cond: any, idx: number, key: any): number {
3409
+ const enc = (cond as any)[S_condnode][idx]
3410
+ if (null == enc) {
3411
+ return -1
3412
+ }
3413
+
3414
+ if (CONDENSE_MAP === enc[0]) {
3415
+ const symid = condenseSymId(cond, S_MT + key)
3416
+ if (0 > symid) {
3417
+ return -1
3418
+ }
3419
+ // Pairs live at [1,2], [3,4], ... with keys ascending: bisect the pairs.
3420
+ let lo = 0
3421
+ let hi = (enc.length - 1) / 2 - 1
3422
+ while (lo <= hi) {
3423
+ const mid = (lo + hi) >> 1
3424
+ const k = enc[1 + mid * 2]
3425
+ if (k === symid) {
3426
+ return enc[2 + mid * 2]
3427
+ }
3428
+ if (k < symid) {
3429
+ lo = mid + 1
3430
+ } else {
3431
+ hi = mid - 1
3432
+ }
3433
+ }
3434
+ return -1
3435
+ }
3436
+
3437
+ if (CONDENSE_LIST === enc[0]) {
3438
+ // Canonical integer keys ONLY. Unary + would accept "01", "1e0", " 1"
3439
+ // and "+1", which an ordinary list lookup treats as plain (absent)
3440
+ // properties - condensing must not change which value a path selects.
3441
+ const k = S_MT + key
3442
+ if (!/^(0|[1-9][0-9]*)$/.test(k)) {
3443
+ return -1
3444
+ }
3445
+ const i = +k
3446
+ if (i >= enc.length - 1) {
3447
+ return -1
3448
+ }
3449
+ return enc[1 + i]
3450
+ }
3451
+
3452
+ return -1
3453
+ }
3454
+
3455
+ // Walk a path from a starting node, returning the node index or -1.
3456
+ function condenseResolve(cond: any, idx: number, path: any): number {
3457
+ const parts = islist(path)
3458
+ ? path
3459
+ : 'string' === typeof path
3460
+ ? '' === path
3461
+ ? []
3462
+ : path.split(S_DT)
3463
+ : null == path
3464
+ ? []
3465
+ : [S_MT + path]
3466
+
3467
+ let at = idx
3468
+ for (let i = 0; i < parts.length; i++) {
3469
+ if (0 > at) {
3470
+ return -1
3471
+ }
3472
+ if (S_MT === parts[i]) {
3473
+ continue
3474
+ }
3475
+ at = condenseChild(cond, at, parts[i])
3476
+ }
3477
+ return at
3478
+ }
3479
+
3480
+ // Materialise node `idx` as an ordinary JSON-shaped value.
3481
+ //
3482
+ // Containers are rebuilt on every call and never memoised: sharing is an
3483
+ // implementation detail, and handing the same object out twice would let a
3484
+ // caller mutating one reference corrupt every other. The cost is that
3485
+ // expansion reproduces the original tree - which is exactly the size it was
3486
+ // before condensing, so it is bounded by the input.
3487
+ function condenseMaterialise(cond: any, idx: number): any {
3488
+ const sym = (cond as any)[S_condsym]
3489
+ const node = (cond as any)[S_condnode]
3490
+
3491
+ const rebuild = (i: number): any => {
3492
+ const enc = node[i]
3493
+ if (null == enc) {
3494
+ return undefined
3495
+ }
3496
+ const kind = enc[0]
3497
+ if (CONDENSE_MAP === kind) {
3498
+ const out: any = {}
3499
+ for (let j = 1; j < enc.length; j += 2) {
3500
+ condenseSet(out, sym[enc[j]], rebuild(enc[j + 1]))
3501
+ }
3502
+ return out
3503
+ }
3504
+ if (CONDENSE_LIST === kind) {
3505
+ const out: any[] = []
3506
+ for (let j = 1; j < enc.length; j++) {
3507
+ out.push(rebuild(enc[j]))
3508
+ }
3509
+ return out
3510
+ }
3511
+ if (CONDENSE_STR === kind) {
3512
+ return sym[enc[1]]
3513
+ }
3514
+ if (CONDENSE_NUM === kind) {
3515
+ return enc[1]
3516
+ }
3517
+ if (CONDENSE_TRUE === kind) {
3518
+ return true
3519
+ }
3520
+ if (CONDENSE_FALSE === kind) {
3521
+ return false
3522
+ }
3523
+ return null
3524
+ }
3525
+
3526
+ return 0 > idx ? undefined : rebuild(idx)
3527
+ }
3528
+
3529
+ // Fully materialise a condensed structure. The escape hatch: correct for any
3530
+ // caller, but it gives up every benefit of condensing, so prefer a view or a
3531
+ // path read.
3532
+ function expand(cond: any): any {
3533
+ if (!iscondensed(cond)) {
3534
+ return cond
3535
+ }
3536
+ return condenseMaterialise(cond, (cond as any)[S_condroot])
3537
+ }
3538
+
3539
+ // The keys of node `idx`, WITHOUT materialising any of its values. This is
3540
+ // the point of the whole exercise for enumeration: listing the names in a
3541
+ // large collection should cost a symbol-table read, not a full decode.
3542
+ function condenseKeys(cond: any, idx: number): string[] {
3543
+ const enc = (cond as any)[S_condnode][idx]
3544
+ if (null == enc) {
3545
+ return []
3546
+ }
3547
+ const sym = (cond as any)[S_condsym]
3548
+ const out: string[] = []
3549
+ if (CONDENSE_MAP === enc[0]) {
3550
+ for (let j = 1; j < enc.length; j += 2) {
3551
+ out.push(sym[enc[j]])
3552
+ }
3553
+ return out
3554
+ }
3555
+ if (CONDENSE_LIST === enc[0]) {
3556
+ for (let j = 1; j < enc.length; j++) {
3557
+ out.push(S_MT + (j - 1))
3558
+ }
3559
+ return out
3560
+ }
3561
+ return []
3562
+ }
3563
+
3564
+ // A cursor into a condensed structure. Reads resolve by integer index and
3565
+ // touch only the nodes on the path, so the cost of a lookup is proportional
3566
+ // to path depth and result size, never to total structure size.
3567
+ type CondenseView = {
3568
+ get: (path?: any) => any
3569
+ keys: (path?: any) => string[]
3570
+ has: (path?: any) => boolean
3571
+ at: (path?: any) => CondenseView
3572
+ value: () => any
3573
+ size: () => number
3574
+ exists: () => boolean
3575
+ ref: () => any
3576
+ }
3577
+
3578
+ function condenseview(cond: any, idx?: number, memo?: any): CondenseView {
3579
+ const start = null == idx ? (iscondensed(cond) ? (cond as any)[S_condroot] : -1) : idx
3580
+
3581
+ // Shared materialisations, handed out ONLY by ref(). Threaded through at()
3582
+ // so every cursor into the same structure shares one memo - otherwise
3583
+ // ref() would hand out a different object per cursor and quietly stop
3584
+ // being the shared-reference escape hatch it claims to be.
3585
+ const refmemo: { [idx: string]: any } = null == memo ? {} : memo
3586
+
3587
+ const view: CondenseView = {
3588
+ // The value at path, materialised. Scalars come back directly; a
3589
+ // container comes back as an independent copy.
3590
+ get: (path?: any) => condenseMaterialise(cond, condenseResolve(cond, start, path)),
3591
+
3592
+ // Key names at path, with no value decoding at all.
3593
+ keys: (path?: any) => {
3594
+ const at = condenseResolve(cond, start, path)
3595
+ return 0 > at ? [] : condenseKeys(cond, at)
3596
+ },
3597
+
3598
+ has: (path?: any) => 0 <= condenseResolve(cond, start, path),
3599
+
3600
+ // Chainable cursor. Cheap: no decoding happens here.
3601
+ at: (path?: any) => condenseview(cond, condenseResolve(cond, start, path), refmemo),
3602
+
3603
+ value: () => condenseMaterialise(cond, start),
3604
+
3605
+ size: () => {
3606
+ const enc = 0 > start ? null : (cond as any)[S_condnode][start]
3607
+ if (null == enc) {
3608
+ return 0
3609
+ }
3610
+ if (CONDENSE_MAP === enc[0]) {
3611
+ return (enc.length - 1) / 2
3612
+ }
3613
+ if (CONDENSE_LIST === enc[0]) {
3614
+ return enc.length - 1
3615
+ }
3616
+ return 0
3617
+ },
3618
+
3619
+ exists: () => 0 <= start,
3620
+
3621
+ // DANGER, and named to say so. Returns a SHARED materialisation: the same
3622
+ // object for the same node, every time. Mutating it corrupts every other
3623
+ // reader of that node, including ones reached by a different path,
3624
+ // because the structure is a DAG. Use value() unless a profile says this
3625
+ // matters.
3626
+ ref: () => {
3627
+ const k = S_MT + start
3628
+ if (undefined === refmemo[k]) {
3629
+ refmemo[k] = condenseMaterialise(cond, start)
3630
+ }
3631
+ return refmemo[k]
3632
+ },
3633
+ }
3634
+
3635
+ return view
3636
+ }
3637
+
3050
3638
  export {
3051
3639
  StructUtility,
3052
3640
  clone,
3641
+ condense,
3642
+ condenseview,
3643
+ expand,
3644
+ iscondensed,
3053
3645
  delprop,
3054
3646
  escre,
3055
3647
  escurl,