@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.
Files changed (4) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +696 -0
  3. package/package.json +50 -0
  4. 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/).