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