@voxgig/struct-js 0.1.2
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/LICENSE +21 -0
- package/README.md +696 -0
- package/package.json +50 -0
- package/src/struct.js +2580 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 voxgig
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,696 @@
|
|
|
1
|
+
# Struct for JavaScript
|
|
2
|
+
|
|
3
|
+
> Plain JavaScript port; runtime-identical to the canonical
|
|
4
|
+
> TypeScript implementation.
|
|
5
|
+
|
|
6
|
+
For motivation, language-neutral concepts, and the cross-language
|
|
7
|
+
parity matrix, see the [top-level README](../README.md) and
|
|
8
|
+
[REPORT.md](../design/REPORT.md).
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
The JS source is a single CommonJS module:
|
|
14
|
+
[`src/struct.js`](./src/struct.js). Inside the monorepo:
|
|
15
|
+
|
|
16
|
+
```js
|
|
17
|
+
const struct = require('./javascript/src/struct.js')
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
When packaged the public name is `@voxgig/struct-js` (see
|
|
21
|
+
[`package.json`](./package.json)). It was `@voxgig/structjs` up to 0.1.1;
|
|
22
|
+
that name ends there and is not published again.
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
## Quick start
|
|
26
|
+
|
|
27
|
+
```js
|
|
28
|
+
const {
|
|
29
|
+
getpath, setpath, merge, walk,
|
|
30
|
+
inject, transform, validate, select,
|
|
31
|
+
} = require('./javascript/src/struct.js')
|
|
32
|
+
|
|
33
|
+
getpath({ db: { host: 'localhost' } }, 'db.host')
|
|
34
|
+
// 'localhost'
|
|
35
|
+
|
|
36
|
+
transform(
|
|
37
|
+
{ user: { first: 'Ada', last: 'Lovelace' }, age: 36 },
|
|
38
|
+
{ name: '`user.first`', surname: '`user.last`', years: '`age`' }
|
|
39
|
+
)
|
|
40
|
+
// { name: 'Ada', surname: 'Lovelace', years: 36 }
|
|
41
|
+
|
|
42
|
+
validate(
|
|
43
|
+
{ name: 'Ada', age: 36 },
|
|
44
|
+
{ name: '`$STRING`', age: '`$INTEGER`' }
|
|
45
|
+
)
|
|
46
|
+
// { name: 'Ada', age: 36 } (throws on mismatch)
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
## Module exports
|
|
51
|
+
|
|
52
|
+
```js
|
|
53
|
+
module.exports = {
|
|
54
|
+
StructUtility, Injection,
|
|
55
|
+
|
|
56
|
+
// 6 regex functions
|
|
57
|
+
re_compile, re_find, re_find_all, re_replace, re_test, re_escape,
|
|
58
|
+
|
|
59
|
+
// 42 utility functions (48 canonical = these 42 + the 6 re_* above)
|
|
60
|
+
clone, delprop, escre, escurl, filter, flatten, getdef, getelem,
|
|
61
|
+
getpath, getprop, haskey, inject, isempty, isfunc, iskey, islist,
|
|
62
|
+
ismap, isnode, items, join, jsonify, keysof, merge, pad, pathify,
|
|
63
|
+
select, setpath, setprop, size, slice, strkey, stringify,
|
|
64
|
+
transform, typify, typename, validate, walk, jm, jt,
|
|
65
|
+
checkPlacement, injectorArgs, injectChild,
|
|
66
|
+
|
|
67
|
+
// sentinels
|
|
68
|
+
SKIP, DELETE,
|
|
69
|
+
|
|
70
|
+
// 15 type bit-flags
|
|
71
|
+
T_any, T_noval, T_boolean, T_decimal, T_integer, T_number, T_string,
|
|
72
|
+
T_function, T_symbol, T_null, T_list, T_map, T_instance, T_scalar,
|
|
73
|
+
T_node,
|
|
74
|
+
|
|
75
|
+
// mode flags
|
|
76
|
+
M_KEYPRE, M_KEYPOST, M_VAL, MODENAME,
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
## Function reference
|
|
82
|
+
|
|
83
|
+
Source: [`src/struct.js`](./src/struct.js).
|
|
84
|
+
|
|
85
|
+
### Predicates
|
|
86
|
+
|
|
87
|
+
```js
|
|
88
|
+
isnode(val) // true for maps and lists
|
|
89
|
+
ismap(val) // true for plain objects
|
|
90
|
+
islist(val) // true for arrays
|
|
91
|
+
iskey(key) // true for non-empty strings or numbers
|
|
92
|
+
isempty(val) // true for null/undefined/''/{}/[]
|
|
93
|
+
isfunc(val) // true for functions
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
<!-- example: minor/isnode#map -->
|
|
97
|
+
```js
|
|
98
|
+
isnode({ a: 1 }) // true
|
|
99
|
+
```
|
|
100
|
+
<!-- => true -->
|
|
101
|
+
|
|
102
|
+
```js
|
|
103
|
+
isnode([1]) // true
|
|
104
|
+
isnode('x') // false
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
<!-- example: minor/ismap#map -->
|
|
108
|
+
```js
|
|
109
|
+
ismap({ a: 1 }) // true
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
<!-- => true -->
|
|
113
|
+
|
|
114
|
+
```js
|
|
115
|
+
ismap([1]) // false
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
<!-- example: minor/islist#list -->
|
|
119
|
+
```js
|
|
120
|
+
islist([1, 2]) // true
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
<!-- => true -->
|
|
124
|
+
|
|
125
|
+
```js
|
|
126
|
+
islist({ a: 1 }) // false
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
<!-- example: minor/iskey#str -->
|
|
130
|
+
```js
|
|
131
|
+
iskey('name') // true
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
<!-- => true -->
|
|
135
|
+
|
|
136
|
+
```js
|
|
137
|
+
iskey(0) // true
|
|
138
|
+
iskey('') // false
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
<!-- example: minor/isempty#empty -->
|
|
142
|
+
```js
|
|
143
|
+
isempty([]) // true
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
<!-- => true -->
|
|
147
|
+
|
|
148
|
+
```js
|
|
149
|
+
isempty(null) // true
|
|
150
|
+
isempty(0) // false
|
|
151
|
+
isfunc(() => 1) // true
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### Type inspection
|
|
155
|
+
|
|
156
|
+
```js
|
|
157
|
+
typify(val) // -> int bitfield
|
|
158
|
+
typename(t) // -> human-friendly type name
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
<!-- example: minor/typify#int -->
|
|
162
|
+
```js
|
|
163
|
+
typify(1) // T_scalar | T_number | T_integer (201326720)
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
<!-- => 201326720 -->
|
|
167
|
+
|
|
168
|
+
```js
|
|
169
|
+
typify(42) // T_scalar | T_number | T_integer
|
|
170
|
+
typify('hi') // T_scalar | T_string
|
|
171
|
+
typify(undefined) // T_noval
|
|
172
|
+
typify(null) // T_scalar | T_null
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
<!-- example: minor/typename#map -->
|
|
176
|
+
```js
|
|
177
|
+
typename(8192) // 'map' (8192 === T_map)
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
<!-- => "map" -->
|
|
181
|
+
|
|
182
|
+
```js
|
|
183
|
+
typename(typify('hi')) // 'string'
|
|
184
|
+
typename(typify({})) // 'map'
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
### Size, slice, pad
|
|
188
|
+
|
|
189
|
+
```js
|
|
190
|
+
size(val) // -> int
|
|
191
|
+
slice(val, start?, end?, mutate?) // sub-section of list/string/number
|
|
192
|
+
pad(str, padding?, padchar?) // pad to width; negative -> left
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
<!-- example: minor/size#three -->
|
|
196
|
+
```js
|
|
197
|
+
size([1,2,3]) // 3
|
|
198
|
+
```
|
|
199
|
+
<!-- => 3 -->
|
|
200
|
+
|
|
201
|
+
```js
|
|
202
|
+
size({a:1,b:2}) // 2
|
|
203
|
+
size('abc') // 3
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
`slice` keeps the first *N*; a negative `start` drops the last *|start|*
|
|
207
|
+
items, and `end` is exclusive:
|
|
208
|
+
|
|
209
|
+
<!-- example: minor/slice#mid -->
|
|
210
|
+
```js
|
|
211
|
+
slice([1,2,3,4,5], 1, 4) // [2, 3, 4]
|
|
212
|
+
```
|
|
213
|
+
<!-- => [2, 3, 4] -->
|
|
214
|
+
|
|
215
|
+
<!-- example: minor/slice#strhead -->
|
|
216
|
+
```js
|
|
217
|
+
slice('abcdef', -3) // 'abc' (drops the last 3)
|
|
218
|
+
```
|
|
219
|
+
<!-- => "abc" -->
|
|
220
|
+
|
|
221
|
+
<!-- example: minor/pad#right -->
|
|
222
|
+
```js
|
|
223
|
+
pad('a', 3) // 'a '
|
|
224
|
+
```
|
|
225
|
+
<!-- => "a " -->
|
|
226
|
+
|
|
227
|
+
```js
|
|
228
|
+
pad('hi', 5) // 'hi '
|
|
229
|
+
pad('hi', -5, '*') // '***hi'
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
### Property access
|
|
233
|
+
|
|
234
|
+
```js
|
|
235
|
+
getprop(val, key, alt?) // -> any
|
|
236
|
+
setprop(parent, key, val) // mutates and returns parent
|
|
237
|
+
delprop(parent, key) // mutates and returns parent
|
|
238
|
+
getelem(list, key, alt?) // list lookup; -1 from end
|
|
239
|
+
getdef(val, alt) // val unless undefined
|
|
240
|
+
haskey(val, key) // -> bool
|
|
241
|
+
keysof(val) // sorted keys
|
|
242
|
+
items(val) // [[key,val], ...]
|
|
243
|
+
items(val, fn) // map over entries
|
|
244
|
+
strkey(key) // canonical string form
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
<!-- example: minor/getprop#hit -->
|
|
248
|
+
```js
|
|
249
|
+
getprop({x:1}, 'x') // 1
|
|
250
|
+
```
|
|
251
|
+
<!-- => 1 -->
|
|
252
|
+
|
|
253
|
+
```js
|
|
254
|
+
getprop({a:1}, 'b', 'def') // 'def'
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
<!-- example: minor/setprop#set -->
|
|
258
|
+
```js
|
|
259
|
+
setprop({a:1}, 'b', 2) // { a:1, b:2 }
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
<!-- => {"a": 1, "b": 2} -->
|
|
263
|
+
|
|
264
|
+
<!-- example: minor/delprop#del -->
|
|
265
|
+
```js
|
|
266
|
+
delprop({a:1, b:2}, 'a') // { b:2 }
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
<!-- => {"b": 2} -->
|
|
270
|
+
|
|
271
|
+
<!-- example: minor/getelem#neg -->
|
|
272
|
+
```js
|
|
273
|
+
getelem([10,20,30], -1) // 30
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
<!-- => 30 -->
|
|
277
|
+
|
|
278
|
+
```js
|
|
279
|
+
getdef(undefined, 'fb') // 'fb'
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
<!-- example: minor/haskey#hit -->
|
|
283
|
+
```js
|
|
284
|
+
haskey({a:1}, 'a') // true
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
<!-- => true -->
|
|
288
|
+
|
|
289
|
+
<!-- example: minor/items#map -->
|
|
290
|
+
```js
|
|
291
|
+
items({a:1, b:2}) // [['a',1], ['b',2]]
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
<!-- => [["a", 1], ["b", 2]] -->
|
|
295
|
+
|
|
296
|
+
<!-- example: minor/strkey#num -->
|
|
297
|
+
```js
|
|
298
|
+
strkey(2.2) // '2'
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
<!-- => "2" -->
|
|
302
|
+
|
|
303
|
+
```js
|
|
304
|
+
strkey(1) // '1'
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
<!-- example: minor/keysof#sorted -->
|
|
308
|
+
```js
|
|
309
|
+
keysof({b:4, a:5}) // ['a','b'] (sorted)
|
|
310
|
+
```
|
|
311
|
+
<!-- => ["a", "b"] -->
|
|
312
|
+
|
|
313
|
+
### Path operations
|
|
314
|
+
|
|
315
|
+
```js
|
|
316
|
+
getpath(store, path, injdef?) // -> any
|
|
317
|
+
setpath(store, path, val, injdef?) // mutates and returns store
|
|
318
|
+
pathify(val, startin?, endin?) // canonical dotted string
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
<!-- example: getpath/basic#deep -->
|
|
322
|
+
```js
|
|
323
|
+
getpath({ a: { b: { c: 42 } } }, 'a.b.c') // 42
|
|
324
|
+
```
|
|
325
|
+
<!-- => 42 -->
|
|
326
|
+
|
|
327
|
+
```js
|
|
328
|
+
getpath({ a: [10,20] }, 'a.1') // 20
|
|
329
|
+
getpath({}, 'missing') // undefined
|
|
330
|
+
|
|
331
|
+
const store = {}
|
|
332
|
+
setpath(store, 'db.host', 'localhost')
|
|
333
|
+
// store === { db: { host: 'localhost' } }
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
<!-- example: minor/setpath#nested -->
|
|
337
|
+
```js
|
|
338
|
+
setpath({ a: 1, b: 2 }, 'b', 22) // { a: 1, b: 22 }
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
<!-- => {"a": 1, "b": 22} -->
|
|
342
|
+
|
|
343
|
+
<!-- example: minor/pathify#parts -->
|
|
344
|
+
```js
|
|
345
|
+
pathify(['a','b','c']) // 'a.b.c'
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
<!-- => "a.b.c" -->
|
|
349
|
+
|
|
350
|
+
### Tree operations
|
|
351
|
+
|
|
352
|
+
```js
|
|
353
|
+
walk(val, before?, after?, maxdepth?)
|
|
354
|
+
// before/after :: (key, val, parent, path) => any
|
|
355
|
+
merge(list, maxdepth?)
|
|
356
|
+
clone(val)
|
|
357
|
+
flatten(list, depth?)
|
|
358
|
+
filter(val, check)
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
```js
|
|
362
|
+
walk(tree, undefined, (k, v) => v == null ? 'X' : v)
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
Last input wins; maps deep-merge; lists merge by index:
|
|
366
|
+
|
|
367
|
+
<!-- example: merge#basic -->
|
|
368
|
+
```js
|
|
369
|
+
merge([
|
|
370
|
+
{ a:1, b:2, k:[10,20], x:{y:5,z:6} },
|
|
371
|
+
{ b:3, d:4, e:8, k:[11], x:{y:7} },
|
|
372
|
+
])
|
|
373
|
+
// { a:1, b:3, d:4, e:8, k:[11,20], x:{y:7,z:6} }
|
|
374
|
+
```
|
|
375
|
+
|
|
376
|
+
<!-- => {"a": 1, "b": 3, "d": 4, "e": 8, "k": [11, 20], "x": {"y": 7, "z": 6}} -->
|
|
377
|
+
|
|
378
|
+
<!-- example: minor/clone#deep -->
|
|
379
|
+
```js
|
|
380
|
+
clone({ a:{ b:[1,2] } }) // { a:{ b:[1,2] } } (a deep copy)
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
<!-- => {"a": {"b": [1, 2]}} -->
|
|
384
|
+
|
|
385
|
+
<!-- example: minor/flatten#nested -->
|
|
386
|
+
```js
|
|
387
|
+
flatten([1,[2,[3]]]) // [1, 2, [3]] (one level by default)
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
<!-- => [1, 2, [3]] -->
|
|
391
|
+
|
|
392
|
+
```js
|
|
393
|
+
flatten([1,[2,[3,[4]]]]) // [1, 2, [3, [4]]]
|
|
394
|
+
flatten([1,[2,[3,[4]]]], 2) // [1, 2, 3, [4]]
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
`filter` passes each `[key, value]` pair to the check and returns the
|
|
398
|
+
matching **values** (not the pairs):
|
|
399
|
+
|
|
400
|
+
<!-- example: minor/filter#gt3 -->
|
|
401
|
+
```js
|
|
402
|
+
filter([1, 2, 3, 4, 5], ([k, v]) => v > 3)
|
|
403
|
+
// [4, 5]
|
|
404
|
+
```
|
|
405
|
+
<!-- => [4, 5] -->
|
|
406
|
+
|
|
407
|
+
### String / URL / JSON
|
|
408
|
+
|
|
409
|
+
```js
|
|
410
|
+
escre(s) // escape regex metachars
|
|
411
|
+
escurl(s) // URL-encode
|
|
412
|
+
join(arr, sep?, url?) // join parts
|
|
413
|
+
jsonify(val, flags?) // JSON serialise
|
|
414
|
+
stringify(val, maxlen?, pretty?) // human-friendly compact
|
|
415
|
+
```
|
|
416
|
+
|
|
417
|
+
<!-- example: minor/escre#dots -->
|
|
418
|
+
```js
|
|
419
|
+
escre('a.b+c') // 'a\\.b\\+c'
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
<!-- => "a\\.b\\+c" -->
|
|
423
|
+
|
|
424
|
+
<!-- example: minor/escurl#space -->
|
|
425
|
+
```js
|
|
426
|
+
escurl('hello world?') // 'hello%20world%3F'
|
|
427
|
+
```
|
|
428
|
+
|
|
429
|
+
<!-- => "hello%20world%3F" -->
|
|
430
|
+
|
|
431
|
+
<!-- example: minor/join#sep -->
|
|
432
|
+
```js
|
|
433
|
+
join(['a','b','c'], '/') // 'a/b/c'
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
<!-- => "a/b/c" -->
|
|
437
|
+
|
|
438
|
+
```js
|
|
439
|
+
join(['http:', '/foo/'], '/', true) // 'http:/foo/'
|
|
440
|
+
```
|
|
441
|
+
|
|
442
|
+
`jsonify` pretty-prints by default (indent 2); pass `{ indent: 0 }` for the
|
|
443
|
+
compact form:
|
|
444
|
+
|
|
445
|
+
<!-- example: minor/jsonify#map -->
|
|
446
|
+
```js
|
|
447
|
+
jsonify({ a: 1 })
|
|
448
|
+
// {
|
|
449
|
+
// "a": 1
|
|
450
|
+
// }
|
|
451
|
+
```
|
|
452
|
+
<!-- => "{\n \"a\": 1\n}" -->
|
|
453
|
+
|
|
454
|
+
<!-- example: minor/jsonify#compact -->
|
|
455
|
+
```js
|
|
456
|
+
jsonify({ a: 1, b: 2 }, { indent: 0 }) // '{"a":1,"b":2}'
|
|
457
|
+
```
|
|
458
|
+
<!-- => "{\"a\":1,\"b\":2}" -->
|
|
459
|
+
|
|
460
|
+
`stringify` is the compact, quote-light form — keys are sorted and object
|
|
461
|
+
braces are kept; the second argument caps the length (the `...` counts):
|
|
462
|
+
|
|
463
|
+
<!-- example: minor/stringify#brace -->
|
|
464
|
+
```js
|
|
465
|
+
stringify({ a: 1, b: [2, 3] }) // '{a:1,b:[2,3]}'
|
|
466
|
+
```
|
|
467
|
+
<!-- => "{a:1,b:[2,3]}" -->
|
|
468
|
+
|
|
469
|
+
<!-- example: minor/stringify#max -->
|
|
470
|
+
```js
|
|
471
|
+
stringify('verylongstring', 5) // 've...'
|
|
472
|
+
```
|
|
473
|
+
<!-- => "ve..." -->
|
|
474
|
+
|
|
475
|
+
### Inject / transform / validate / select
|
|
476
|
+
|
|
477
|
+
```js
|
|
478
|
+
inject(val, store, injdef?)
|
|
479
|
+
transform(data, spec, injdef?)
|
|
480
|
+
validate(data, spec, injdef?)
|
|
481
|
+
select(children, query)
|
|
482
|
+
```
|
|
483
|
+
|
|
484
|
+
<!-- example: inject#basic -->
|
|
485
|
+
```js
|
|
486
|
+
inject({ x: '`a`', y: 2 }, { a: 1 }) // { x: 1, y: 2 }
|
|
487
|
+
```
|
|
488
|
+
|
|
489
|
+
<!-- => {"x": 1, "y": 2} -->
|
|
490
|
+
|
|
491
|
+
```js
|
|
492
|
+
inject(
|
|
493
|
+
{ greeting: 'hello `name`' },
|
|
494
|
+
{ name: 'Ada' }
|
|
495
|
+
)
|
|
496
|
+
// { greeting: 'hello Ada' }
|
|
497
|
+
|
|
498
|
+
transform(
|
|
499
|
+
{ hold: { x: 1 }, top: 99 },
|
|
500
|
+
{ a: '`hold.x`', b: '`top`' }
|
|
501
|
+
)
|
|
502
|
+
// { a: 1, b: 99 }
|
|
503
|
+
```
|
|
504
|
+
|
|
505
|
+
<!-- example: validate#shape -->
|
|
506
|
+
```js
|
|
507
|
+
validate(
|
|
508
|
+
{ name: 'Ada', age: 36 },
|
|
509
|
+
{ name: '`$STRING`', age: '`$INTEGER`' }
|
|
510
|
+
)
|
|
511
|
+
// { name: 'Ada', age: 36 } (throws on mismatch)
|
|
512
|
+
```
|
|
513
|
+
|
|
514
|
+
<!-- => {"age": 36, "name": "Ada"} -->
|
|
515
|
+
|
|
516
|
+
<!-- example: select#query -->
|
|
517
|
+
```js
|
|
518
|
+
select(
|
|
519
|
+
{ a: { name: 'Alice', age: 30 }, b: { name: 'Bob', age: 25 } },
|
|
520
|
+
{ age: 30 }
|
|
521
|
+
)
|
|
522
|
+
// [{ name: 'Alice', age: 30, $KEY: 'a' }]
|
|
523
|
+
```
|
|
524
|
+
|
|
525
|
+
<!-- => [{"$KEY": "a", "age": 30, "name": "Alice"}] -->
|
|
526
|
+
|
|
527
|
+
Transform commands drive structural ops. A command like `$EACH` appears in
|
|
528
|
+
**value** position — as the first element of a list `['`$EACH`', path, subspec]`
|
|
529
|
+
— mapping the sub-spec over every entry at `path`:
|
|
530
|
+
|
|
531
|
+
<!-- example: transform/each#basic -->
|
|
532
|
+
```js
|
|
533
|
+
transform(
|
|
534
|
+
{ v: 1, a: [{ q: 13 }, { q: 23 }] },
|
|
535
|
+
{ x: { y: ['`$EACH`', 'a', { q: '`$COPY`', r: '`.q`', p: '`...v`' }] } }
|
|
536
|
+
)
|
|
537
|
+
// { x: { y: [ { q: 13, r: 13, p: 1 }, { q: 23, r: 23, p: 1 } ] } }
|
|
538
|
+
```
|
|
539
|
+
<!-- => {"x": {"y": [{"p": 1, "q": 13, "r": 13}, {"p": 1, "q": 23, "r": 23}]}} -->
|
|
540
|
+
|
|
541
|
+
Putting a command in **key** position (or, for `$APPLY`, directly under a map)
|
|
542
|
+
is an error — commands must be list values:
|
|
543
|
+
|
|
544
|
+
<!-- example: transform/apply#badkey -->
|
|
545
|
+
```js
|
|
546
|
+
transform({}, { x: '`$APPLY`' })
|
|
547
|
+
// throws: $APPLY: invalid placement in parent map, expected: list.
|
|
548
|
+
```
|
|
549
|
+
<!-- throws: invalid placement in parent map -->
|
|
550
|
+
|
|
551
|
+
### Builders
|
|
552
|
+
|
|
553
|
+
```js
|
|
554
|
+
jm('a', 1, 'b', 2) // { a: 1, b: 2 }
|
|
555
|
+
jt(1, 2, 3) // [1, 2, 3]
|
|
556
|
+
```
|
|
557
|
+
|
|
558
|
+
### Injection helpers
|
|
559
|
+
|
|
560
|
+
Exposed for callers writing custom injectors:
|
|
561
|
+
|
|
562
|
+
```js
|
|
563
|
+
checkPlacement(modes, ijname, parentTypes, inj) // -> bool
|
|
564
|
+
injectorArgs(argTypes, args) // -> any
|
|
565
|
+
injectChild(child, store, inj) // -> Injection
|
|
566
|
+
```
|
|
567
|
+
|
|
568
|
+
|
|
569
|
+
## Constants
|
|
570
|
+
|
|
571
|
+
### Sentinels
|
|
572
|
+
|
|
573
|
+
```js
|
|
574
|
+
SKIP // emit nothing for this key
|
|
575
|
+
DELETE // remove this key from the parent
|
|
576
|
+
```
|
|
577
|
+
|
|
578
|
+
### Type bit-flags
|
|
579
|
+
|
|
580
|
+
```js
|
|
581
|
+
T_any T_noval T_boolean T_decimal T_integer T_number T_string
|
|
582
|
+
T_function T_symbol T_null T_list T_map T_instance T_scalar T_node
|
|
583
|
+
```
|
|
584
|
+
|
|
585
|
+
`typify(val)` returns a bit-field combining a kind flag (`T_scalar`
|
|
586
|
+
or `T_node`) with a specific type flag.
|
|
587
|
+
|
|
588
|
+
### Walk / inject phase flags
|
|
589
|
+
|
|
590
|
+
```js
|
|
591
|
+
M_KEYPRE // pre-descent
|
|
592
|
+
M_KEYPOST // post-descent
|
|
593
|
+
M_VAL // leaf-value visit
|
|
594
|
+
MODENAME // string[] mapping mode flags to names
|
|
595
|
+
```
|
|
596
|
+
|
|
597
|
+
|
|
598
|
+
## Transform commands
|
|
599
|
+
|
|
600
|
+
Used as backtick-quoted strings inside a `transform` spec.
|
|
601
|
+
|
|
602
|
+
```
|
|
603
|
+
$DELETE $COPY $KEY $META $ANNO
|
|
604
|
+
$MERGE $EACH $PACK $REF $FORMAT $APPLY
|
|
605
|
+
```
|
|
606
|
+
|
|
607
|
+
See the [top-level README](../README.md) for purpose of each.
|
|
608
|
+
|
|
609
|
+
|
|
610
|
+
## Validate checkers
|
|
611
|
+
|
|
612
|
+
Used as backtick-quoted strings inside a `validate` spec.
|
|
613
|
+
|
|
614
|
+
```
|
|
615
|
+
$MAP $LIST $STRING $NUMBER $INTEGER $DECIMAL $BOOLEAN
|
|
616
|
+
$NULL $NIL $FUNCTION $INSTANCE $ANY $CHILD $ONE $EXACT
|
|
617
|
+
```
|
|
618
|
+
|
|
619
|
+
|
|
620
|
+
## Notes
|
|
621
|
+
|
|
622
|
+
### `null` versus `undefined`
|
|
623
|
+
|
|
624
|
+
JavaScript distinguishes the two natively; `struct` preserves the
|
|
625
|
+
distinction:
|
|
626
|
+
|
|
627
|
+
- `undefined` -> "absent". `getprop` returns it for a missing key.
|
|
628
|
+
- `null` -> JSON null, a defined scalar.
|
|
629
|
+
|
|
630
|
+
If your JSON parser returns `null` for absent fields, convert to
|
|
631
|
+
`undefined` (or use `'__NULL__'` placeholders) before passing in.
|
|
632
|
+
|
|
633
|
+
### Lists mutate in place
|
|
634
|
+
|
|
635
|
+
`merge`, `setpath`, and `inject` rely on lists being reference-stable
|
|
636
|
+
-- a mutation through one reference is visible to every holder.
|
|
637
|
+
JavaScript arrays satisfy this natively.
|
|
638
|
+
|
|
639
|
+
### Difference from canonical TypeScript
|
|
640
|
+
|
|
641
|
+
The exported function surface is identical (48 canonical functions,
|
|
642
|
+
including the six `re_*` regex helpers). The only export difference is
|
|
643
|
+
`Injection`: the JS port exports it as a runtime value, whereas TypeScript
|
|
644
|
+
exports it only as a type. Otherwise functionally identical -- both run on
|
|
645
|
+
V8.
|
|
646
|
+
|
|
647
|
+
### Test status
|
|
648
|
+
|
|
649
|
+
90/90 tests pass against the shared corpus.
|
|
650
|
+
|
|
651
|
+
|
|
652
|
+
## Regex
|
|
653
|
+
|
|
654
|
+
Uniform six-function regex API (see `/design/REGEX_API.md`). On JavaScript
|
|
655
|
+
this is the ECMAScript `RegExp` built-in.
|
|
656
|
+
|
|
657
|
+
### API
|
|
658
|
+
|
|
659
|
+
| Function | Maps to |
|
|
660
|
+
|---|---|
|
|
661
|
+
| `re_compile(pattern, flags?)` | `new RegExp(pattern, flags ?? 'g')` |
|
|
662
|
+
| `re_test(pattern, input)` | `pattern.test(input)` |
|
|
663
|
+
| `re_find(pattern, input)` | `input.match(pattern)` (non-global pattern) |
|
|
664
|
+
| `re_find_all(pattern, input)` | `[...input.matchAll(pattern)]` |
|
|
665
|
+
| `re_replace(pattern, input, rep)` | `input.replace(pattern, rep)` (global pattern) |
|
|
666
|
+
| `re_escape(s)` | escape `[.*+?^${}()|[\]\\]` in `s` |
|
|
667
|
+
|
|
668
|
+
### Dialect
|
|
669
|
+
|
|
670
|
+
Patterns must stay inside the **RE2 subset** documented in `/design/REGEX.md`.
|
|
671
|
+
`RegExp` itself supports backreferences and lookaround, but other ports
|
|
672
|
+
do not, so using those will not be portable.
|
|
673
|
+
|
|
674
|
+
### Sharp edges
|
|
675
|
+
|
|
676
|
+
- **Catastrophic backtracking.** `RegExp` is a backtracking engine;
|
|
677
|
+
nested quantifiers like `(a+)+` against a non-matching suffix can be
|
|
678
|
+
exponential in input length (the discovery panel reports ~180 ms on
|
|
679
|
+
Node 22 vs <0.1 ms on RE2-style engines). Prefer flat patterns and
|
|
680
|
+
character classes over alternations.
|
|
681
|
+
- **Zero-width `replace`.** `re_replace("a*", "abc", "X")` returns
|
|
682
|
+
`"XXbXcX"` — the ECMA convention shared by all PCRE/ECMA/.NET/Java/Onigmo engines plus the in-tree Thompson ports. Go (RE2) returns `"XbXcX"` instead; see `/design/REGEX_PATHOLOGICAL.md`.
|
|
683
|
+
|
|
684
|
+
See `/design/REGEX_PATHOLOGICAL.md` for the cross-port pathological-input
|
|
685
|
+
panel.
|
|
686
|
+
|
|
687
|
+
|
|
688
|
+
## Build and test
|
|
689
|
+
|
|
690
|
+
```bash
|
|
691
|
+
cd javascript
|
|
692
|
+
make test # runs the shared .aon corpus
|
|
693
|
+
```
|
|
694
|
+
|
|
695
|
+
Tests live in [`test/`](./test/) and read fixtures from
|
|
696
|
+
[`../build/test/`](../build/test/).
|