@voxgig/struct 0.2.2 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +26 -6
- package/dist/StructUtility.d.ts +25 -1
- package/dist/StructUtility.js +495 -6
- package/dist/StructUtility.js.map +1 -1
- package/package.json +6 -5
- package/src/StructUtility.ts +557 -6
package/src/StructUtility.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/* Copyright (c) 2025-2026 Voxgig Ltd. MIT LICENSE. */
|
|
2
2
|
|
|
3
|
-
// VERSION: @voxgig/struct 0.
|
|
3
|
+
// VERSION: @voxgig/struct 0.3.1
|
|
4
4
|
|
|
5
5
|
/* Voxgig Struct
|
|
6
6
|
* =============
|
|
@@ -912,6 +912,21 @@ function delprop<PARENT>(parent: PARENT, key: any): PARENT {
|
|
|
912
912
|
return parent
|
|
913
913
|
}
|
|
914
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
|
+
|
|
915
930
|
if (ismap(parent)) {
|
|
916
931
|
key = strkey(key)
|
|
917
932
|
delete (parent as any)[key]
|
|
@@ -949,6 +964,21 @@ function setprop<PARENT>(parent: PARENT, key: any, val: any): PARENT {
|
|
|
949
964
|
return parent
|
|
950
965
|
}
|
|
951
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
|
+
|
|
952
982
|
if (ismap(parent)) {
|
|
953
983
|
key = S_MT + key
|
|
954
984
|
const pany = parent as any
|
|
@@ -1173,6 +1203,13 @@ function setpath(
|
|
|
1173
1203
|
val: any,
|
|
1174
1204
|
injdef?: Partial<Injection>,
|
|
1175
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
|
+
|
|
1176
1213
|
const pathType = typify(path)
|
|
1177
1214
|
|
|
1178
1215
|
const parts =
|
|
@@ -1225,6 +1262,26 @@ function getpath(store: any, path: number | string | string[], injdef?: Partial<
|
|
|
1225
1262
|
return NONE
|
|
1226
1263
|
}
|
|
1227
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
|
+
|
|
1228
1285
|
// let root = store
|
|
1229
1286
|
let val = store
|
|
1230
1287
|
const base = getprop(injdef, S_base)
|
|
@@ -2105,15 +2162,26 @@ const validate_CHILD: Injector = (inj: Injection) => {
|
|
|
2105
2162
|
return inj.dparent
|
|
2106
2163
|
}
|
|
2107
2164
|
|
|
2108
|
-
// Clone children
|
|
2165
|
+
// Clone children and reset inj key index.
|
|
2109
2166
|
// The inject child loop will now iterate over the cloned children,
|
|
2110
|
-
// validating them
|
|
2167
|
+
// validating them against the current list values.
|
|
2111
2168
|
items(inj.dparent, (n) => setprop(parent, n[0], clone(childtm)))
|
|
2112
2169
|
slice(parent, 0, inj.dparent.length, true)
|
|
2113
|
-
inj.keyI = 0
|
|
2114
2170
|
|
|
2115
|
-
|
|
2116
|
-
|
|
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
|
|
2117
2185
|
}
|
|
2118
2186
|
|
|
2119
2187
|
return NONE
|
|
@@ -3023,9 +3091,12 @@ function injectChild(child: any, store: any, inj: Injection): Injection {
|
|
|
3023
3091
|
|
|
3024
3092
|
class StructUtility {
|
|
3025
3093
|
clone = clone
|
|
3094
|
+
condense = condense
|
|
3095
|
+
condenseview = condenseview
|
|
3026
3096
|
delprop = delprop
|
|
3027
3097
|
escre = escre
|
|
3028
3098
|
escurl = escurl
|
|
3099
|
+
expand = expand
|
|
3029
3100
|
filter = filter
|
|
3030
3101
|
flatten = flatten
|
|
3031
3102
|
getdef = getdef
|
|
@@ -3035,6 +3106,7 @@ class StructUtility {
|
|
|
3035
3106
|
haskey = haskey
|
|
3036
3107
|
inject = inject
|
|
3037
3108
|
isempty = isempty
|
|
3109
|
+
iscondensed = iscondensed
|
|
3038
3110
|
isfunc = isfunc
|
|
3039
3111
|
iskey = iskey
|
|
3040
3112
|
islist = islist
|
|
@@ -3060,6 +3132,13 @@ class StructUtility {
|
|
|
3060
3132
|
validate = validate
|
|
3061
3133
|
walk = walk
|
|
3062
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
|
+
|
|
3063
3142
|
SKIP = SKIP
|
|
3064
3143
|
DELETE = DELETE
|
|
3065
3144
|
|
|
@@ -3088,9 +3167,481 @@ class StructUtility {
|
|
|
3088
3167
|
injectChild = injectChild
|
|
3089
3168
|
}
|
|
3090
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
|
+
|
|
3091
3638
|
export {
|
|
3092
3639
|
StructUtility,
|
|
3093
3640
|
clone,
|
|
3641
|
+
condense,
|
|
3642
|
+
condenseview,
|
|
3643
|
+
expand,
|
|
3644
|
+
iscondensed,
|
|
3094
3645
|
delprop,
|
|
3095
3646
|
escre,
|
|
3096
3647
|
escurl,
|