@amritk/nish-aarch64-darwin 0.35.0 → 0.37.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.
Files changed (128) hide show
  1. package/INSTALL.md +73 -59
  2. package/bin/nish +0 -0
  3. package/docs/AI.md +50 -4
  4. package/package.json +1 -1
  5. package/runtime/async.d.mts +2 -0
  6. package/runtime/async.mjs +7 -0
  7. package/runtime/nish.d.ts +4849 -430
  8. package/runtime/nish.h +25 -0
  9. package/runtime/page.d.ts +53 -0
  10. package/runtime/page.mjs +146 -0
  11. package/runtime/runtime-async.c +557 -0
  12. package/runtime/runtime-wasm.c +63 -7
  13. package/runtime/vite.d.ts +30 -0
  14. package/runtime/vite.mjs +150 -0
  15. package/scripts/build.sh +252 -15
  16. package/std/README.md +107 -82
  17. package/std/base64.ts +34 -5
  18. package/std/bytes.ts +279 -59
  19. package/std/cli-args.ts +296 -70
  20. package/std/cli-flags.ts +184 -19
  21. package/std/cli.ts +475 -54
  22. package/std/collections.ts +121 -23
  23. package/std/compress/checksum.ts +44 -14
  24. package/std/compress/deflate.ts +224 -111
  25. package/std/compress/gzip.ts +217 -53
  26. package/std/compress/zlib.ts +63 -7
  27. package/std/crypto/aes.ts +128 -52
  28. package/std/crypto/base64url.ts +29 -5
  29. package/std/crypto/bcrypt-batch.ts +101 -34
  30. package/std/crypto/bcrypt.ts +93 -27
  31. package/std/crypto/chacha20poly1305.ts +69 -14
  32. package/std/crypto/ct.ts +32 -13
  33. package/std/crypto/ed25519.ts +66 -16
  34. package/std/crypto/hkdf.ts +198 -13
  35. package/std/crypto/hmac.ts +242 -37
  36. package/std/crypto/jwt.ts +204 -72
  37. package/std/crypto/p256.ts +222 -72
  38. package/std/crypto/p384.ts +51 -23
  39. package/std/crypto/pki-roots.ts +32 -2
  40. package/std/crypto/pki.ts +99 -30
  41. package/std/crypto/rsa.ts +56 -22
  42. package/std/crypto/sha1.ts +3 -0
  43. package/std/crypto/sha256.ts +24 -1
  44. package/std/crypto/sha512.ts +99 -14
  45. package/std/crypto/x25519.ts +163 -24
  46. package/std/crypto/x509-random.ts +10 -0
  47. package/std/crypto/x509.ts +133 -66
  48. package/std/host/ring.ts +124 -0
  49. package/std/json-equal.ts +31 -11
  50. package/std/json-format.ts +112 -13
  51. package/std/json-number.ts +76 -26
  52. package/std/json-pointer.ts +23 -1
  53. package/std/json-tokenizer.ts +126 -51
  54. package/std/json-typed.ts +757 -96
  55. package/std/json-value.ts +438 -157
  56. package/std/json.ts +170 -38
  57. package/std/map.ts +25 -7
  58. package/std/math.ts +36 -4
  59. package/std/net/buffer-pool.ts +42 -11
  60. package/std/net/dns-config.ts +109 -23
  61. package/std/net/dns-message.ts +62 -7
  62. package/std/net/dns-resolver.ts +247 -53
  63. package/std/net/dns.ts +203 -35
  64. package/std/net/fetch.ts +1267 -290
  65. package/std/net/handler.ts +296 -80
  66. package/std/net/hpack.ts +290 -77
  67. package/std/net/http-compress.ts +152 -36
  68. package/std/net/http-fields.ts +85 -9
  69. package/std/net/http1-client-codec.ts +129 -44
  70. package/std/net/http1-codec.ts +279 -114
  71. package/std/net/http1-server.ts +409 -139
  72. package/std/net/http2-frame.ts +289 -51
  73. package/std/net/http2-tls.ts +152 -49
  74. package/std/net/http2.ts +314 -160
  75. package/std/net/http3-frame.ts +165 -27
  76. package/std/net/http3-server.ts +282 -131
  77. package/std/net/http3.ts +377 -173
  78. package/std/net/outbound.ts +37 -3
  79. package/std/net/postgres-carrier.ts +144 -8
  80. package/std/net/postgres.ts +898 -260
  81. package/std/net/prefork.ts +202 -65
  82. package/std/net/qpack.ts +120 -32
  83. package/std/net/quic-conn-ack.ts +60 -12
  84. package/std/net/quic-conn-cid.ts +135 -27
  85. package/std/net/quic-conn-params.ts +109 -22
  86. package/std/net/quic-datagram.ts +50 -3
  87. package/std/net/quic-frame.ts +333 -23
  88. package/std/net/quic-listener.ts +161 -75
  89. package/std/net/quic-packet.ts +373 -73
  90. package/std/net/quic-recovery.ts +287 -65
  91. package/std/net/quic-stream.ts +436 -146
  92. package/std/net/quic.ts +693 -323
  93. package/std/net/router.ts +87 -40
  94. package/std/net/tls/client.ts +167 -51
  95. package/std/net/tls/codec.ts +494 -68
  96. package/std/net/tls/record-client.ts +140 -73
  97. package/std/net/tls/record-server.ts +233 -105
  98. package/std/net/tls/record.ts +142 -36
  99. package/std/net/tls/schedule.ts +235 -26
  100. package/std/net/tls/ticket.ts +161 -40
  101. package/std/net/tls/verify.ts +57 -10
  102. package/std/net/tls-tcp.ts +308 -95
  103. package/std/net/tls.ts +276 -102
  104. package/std/net/upstream.ts +81 -45
  105. package/std/net/url.ts +109 -22
  106. package/std/net/websocket.ts +140 -26
  107. package/std/net/webtransport.ts +243 -106
  108. package/std/pair.ts +10 -2
  109. package/std/random.ts +42 -15
  110. package/std/regex.ts +422 -257
  111. package/std/region.ts +70 -15
  112. package/std/secret.ts +52 -11
  113. package/std/sort.ts +17 -2
  114. package/std/sqlite.ts +256 -35
  115. package/std/sync/ring.ts +229 -56
  116. package/std/sync/shm.ts +203 -23
  117. package/std/term-io.ts +154 -78
  118. package/std/term-pixels.ts +144 -19
  119. package/std/term-probe.ts +77 -35
  120. package/std/term-rate.ts +199 -118
  121. package/std/term.ts +400 -175
  122. package/std/testing.ts +130 -32
  123. package/std/text.ts +84 -17
  124. package/std/threads.ts +248 -56
  125. package/std/yaml-json.ts +111 -97
  126. package/std/yaml-lines.ts +47 -15
  127. package/std/yaml-write.ts +45 -30
  128. package/std/yaml.ts +764 -384
package/std/bytes.ts CHANGED
@@ -8,31 +8,37 @@
8
8
  *
9
9
  * import { getU32BE, setU16LE } from "nish/bytes";
10
10
  *
11
- * const header: u8[] = [0, 0, 1, 0, 0, 0];
12
- * const length = getU32BE(header, 0); // 256
13
- * setU16LE(header, 4, toU16(513)); // header[4] = 1, header[5] = 2
11
+ * export const main = (): i32 => {
12
+ * const header: u8[] = [0, 0, 1, 0, 0, 0];
13
+ * const length = getU32BE(header, 0); // 256
14
+ * setU16LE(header, 4, toU16(513)); // header[4] = 1, header[5] = 2
15
+ * return toI32(length);
16
+ * };
14
17
  *
15
- * Every function takes the array and the offset of its first byte; the `LE`
18
+ * **Every function takes the array and the offset of its first byte; the `LE`
16
19
  * name puts the least significant byte there, the `BE` name the most
17
- * significant. The widths are `u16`, `u32` and `u64`, the signed `i32` and
20
+ * significant.** The widths are `u16`, `u32` and `u64`, the signed `i32` and
18
21
  * `i64`, which are the same bytes read as two's complement, and `f64`, whose
19
22
  * bytes are its IEEE 754 bits (`f64ToBits`). There is no `f32`: the language
20
23
  * has no bit cast for one.
21
24
  *
22
- * Each access is an ordinary index, so an offset whose bytes do not all lie in
23
- * the array panics `index`, naming the first byte that does not. A guard in
24
- * the caller does not yet remove these checks: in a loop guarded by
25
- * `off + 3 < b.length`, the checker proves an index it can see but not one
26
- * inside a call, and after `getU32LE` inlines, LLVM keeps the checks on
27
- * `off + 1` to `off + 3`, because the guard compares the length truncated to
28
- * `i32` and the checks compare it unsigned at 64 bits. A loop that needs them
29
- * gone indexes the bytes itself. `getU64BE`, and with it `getI64BE` and
30
- * `getF64BE`, is the exception: it checks the whole range once and reads the
31
- * eight bytes unchecked, which lowers to one load and a byte swap. An offset
32
- * outside the range still goes byte by byte, so it panics as the others do.
33
- *
34
- * The in-range answers are byte for byte those of the copies `std/` keeps for
35
- * itself: `sha256LoadWord` (`std/crypto/sha256.ts`) for `getU32BE`,
25
+ * **Each access is an ordinary index**, so an offset whose bytes do not all lie
26
+ * in the array panics `index`, naming the first byte that does not.
27
+ *
28
+ * A guard in the caller does not yet remove these checks: in a loop guarded by
29
+ * `off + 3 < b.length`, the checker proves an index it can see but not one
30
+ * inside a call, and after `getU32LE` inlines, LLVM keeps the checks on `off +
31
+ * 1` to `off + 3`, because the guard compares the length truncated to `i32` and
32
+ * the checks compare it unsigned at 64 bits. A loop that needs them gone
33
+ * indexes the bytes itself.
34
+ *
35
+ * `getU64BE`, and with it `getI64BE` and `getF64BE`, is the exception: it
36
+ * checks the whole range once and reads the eight bytes unchecked, which lowers
37
+ * to one load and a byte swap. An offset outside the range still goes byte by
38
+ * byte, so it panics as the others do.
39
+ *
40
+ * **The in-range answers are byte for byte those of the copies `std/` keeps for
41
+ * itself**: `sha256LoadWord` (`std/crypto/sha256.ts`) for `getU32BE`,
36
42
  * `chacha20Word` and `poly1305Le64` (`std/crypto/chacha20poly1305.ts`) for
37
43
  * `getU32LE` and `getU64LE`, `loadWord` and `storeWord` (`std/crypto/sha512.ts`)
38
44
  * for `getU64BE` and `setU64BE`, `http2FramePut32` (`std/net/http2-frame.ts`)
@@ -41,8 +47,8 @@
41
47
  * TLS word helpers read zero past the end and drop bytes written there, which
42
48
  * their callers rely on, where this module panics.
43
49
  *
44
- * Under Node (`docs/RUN_UNDER_NODE.md`) the `u16` and `u32` functions are
45
- * expected to answer as they do natively, because the top byte of a `u32` is
50
+ * **Under Node (`docs/RUN_UNDER_NODE.md`) the `u16` and `u32` functions are
51
+ * expected to answer as they do natively**, because the top byte of a `u32` is
46
52
  * multiplied in rather than shifted and each byte written is masked before
47
53
  * its `toU8`: there `<<` turns bit 31 into a sign and the prelude's `toU8`
48
54
  * and `toU32` saturate, and natively the multiply and the mask fold into the
@@ -52,40 +58,81 @@
52
58
  * 64-bit functions and `f64` meet its BigInt `u64` and `i64`, which `toU8`
53
59
  * refuses.
54
60
  *
55
- * The module also has the runs a parser walks and the copy it makes of them.
61
+ * **The module also has the runs a parser walks and the copy it makes of
62
+ * them.**
56
63
  * `skipBlank`, `skipDigits`, `skipJsonText` and `skipJsonPlain` each answer
57
64
  * the first index in a range whose byte is not in their class — JSON's blanks,
58
65
  * the ASCII digits, the bytes a JSON string holds as themselves, the bytes a
59
66
  * JSON writer copies without an escape — and `copyBytes` copies a
60
67
  * window of one array into another, or into itself, as one move:
61
68
  *
62
- * const text: u8[] = [32, 32, 52, 50, 44]; // " 42,"
63
- * const start = skipBlank(text, 0, 5); // 2
64
- * const end = skipDigits(text, start, 5); // 4
69
+ * import { skipBlank, skipDigits } from "nish/bytes";
65
70
  *
66
- * The four runs clamp their range and never panic; `copyBytes` panics on a
67
- * range outside its array. Natively each is a runtime kernel
71
+ * export const main = (): i32 => {
72
+ * const text: u8[] = [32, 32, 52, 50, 44]; // " 42,"
73
+ * const start = skipBlank(text, 0, 5); // 2
74
+ * const end = skipDigits(text, start, 5); // 4
75
+ * return end - start;
76
+ * };
77
+ *
78
+ * **The four runs clamp their range and never panic; `copyBytes` panics on a
79
+ * range outside its array.** Natively each is a runtime kernel
68
80
  * (docs/LANGUAGE.md, "Byte runs"), and the runs are variable-time: they are
69
81
  * for text, never for secret data.
70
82
  */
71
83
 
72
- /** The `u16` whose low byte is `b[off]` and high byte `b[off + 1]`. */
84
+ /**
85
+ * The `u16` whose low byte is `b[off]` and high byte `b[off + 1]`.
86
+ *
87
+ * @param b The bytes the number is read from; they are not changed.
88
+ * @param off Where in `b` its first byte is; it covers `b[off]` to
89
+ * `b[off + 1]`, and a byte of those outside `b` panics `index`.
90
+ * @returns The number read.
91
+ */
73
92
  export const getU16LE = (b: u8[], off: i32): u16 => toU16(b[off]) | (toU16(b[off + 1]) << 8)
74
93
 
75
- /** The `u16` whose high byte is `b[off]` and low byte `b[off + 1]`. */
94
+ /**
95
+ * The `u16` whose high byte is `b[off]` and low byte `b[off + 1]`.
96
+ *
97
+ * @param b The bytes the number is read from; they are not changed.
98
+ * @param off Where in `b` its first byte is; it covers `b[off]` to
99
+ * `b[off + 1]`, and a byte of those outside `b` panics `index`.
100
+ * @returns The number read.
101
+ */
76
102
  export const getU16BE = (b: u8[], off: i32): u16 => (toU16(b[off]) << 8) | toU16(b[off + 1])
77
103
 
78
- /** The `u32` whose bytes, least significant first, are `b[off]` to `b[off + 3]`. */
104
+ /**
105
+ * The `u32` whose bytes, least significant first, are `b[off]` to `b[off + 3]`.
106
+ *
107
+ * @param b The bytes the number is read from; they are not changed.
108
+ * @param off Where in `b` its first byte is; it covers `b[off]` to
109
+ * `b[off + 3]`, and a byte of those outside `b` panics `index`.
110
+ * @returns The number read.
111
+ */
79
112
  export const getU32LE = (b: u8[], off: i32): u32 =>
80
113
  (toU32(b[off]) | (toU32(b[off + 1]) << 8) | (toU32(b[off + 2]) << 16)) +
81
114
  toU32(b[off + 3]) * toU32(0x1000000)
82
115
 
83
- /** The `u32` whose bytes, most significant first, are `b[off]` to `b[off + 3]`. */
116
+ /**
117
+ * The `u32` whose bytes, most significant first, are `b[off]` to `b[off + 3]`.
118
+ *
119
+ * @param b The bytes the number is read from; they are not changed.
120
+ * @param off Where in `b` its first byte is; it covers `b[off]` to
121
+ * `b[off + 3]`, and a byte of those outside `b` panics `index`.
122
+ * @returns The number read.
123
+ */
84
124
  export const getU32BE = (b: u8[], off: i32): u32 =>
85
125
  toU32(b[off]) * toU32(0x1000000) +
86
126
  ((toU32(b[off + 1]) << 16) | (toU32(b[off + 2]) << 8) | toU32(b[off + 3]))
87
127
 
88
- /** The `u64` whose bytes, least significant first, are `b[off]` to `b[off + 7]`. */
128
+ /**
129
+ * The `u64` whose bytes, least significant first, are `b[off]` to `b[off + 7]`.
130
+ *
131
+ * @param b The bytes the number is read from; they are not changed.
132
+ * @param off Where in `b` its first byte is; it covers `b[off]` to
133
+ * `b[off + 7]`, and a byte of those outside `b` panics `index`.
134
+ * @returns The number read.
135
+ */
89
136
  export const getU64LE = (b: u8[], off: i32): u64 => {
90
137
  let v = toU64(0)
91
138
  for (let i: i32 = 0; i < 8; i++) {
@@ -108,6 +155,11 @@ const getU64BEByByte = (b: u8[], off: i32): u64 => {
108
155
  * The fast path's ors are grouped in pairs, which LLVM folds into one load and
109
156
  * a `bswap`; a flat chain of eight `or`s stayed byte by byte. The byte loop is
110
157
  * its own function so its last load is not merged with the fast path's.
158
+ *
159
+ * @param b The bytes the number is read from; they are not changed.
160
+ * @param off Where in `b` its first byte is; it covers `b[off]` to
161
+ * `b[off + 7]`, and a byte of those outside `b` panics `index`.
162
+ * @returns The number read.
111
163
  */
112
164
  export const getU64BE = (b: u8[], off: i32): u64 => {
113
165
  if (off >= 0 && off < 2147483640 && off + 8 <= toI32(b.length)) {
@@ -123,37 +175,100 @@ export const getU64BE = (b: u8[], off: i32): u64 => {
123
175
  return getU64BEByByte(b, off)
124
176
  }
125
177
 
126
- /** `getU32LE`'s bits as a two's-complement `i32`. */
178
+ /**
179
+ * `getU32LE`'s bits as a two's-complement `i32`.
180
+ *
181
+ * @param b The bytes the number is read from; they are not changed.
182
+ * @param off Where in `b` its first byte is; it covers `b[off]` to
183
+ * `b[off + 3]`, and a byte of those outside `b` panics `index`.
184
+ * @returns The number read, from -2^31 to 2^31 - 1.
185
+ */
127
186
  export const getI32LE = (b: u8[], off: i32): i32 => toI32(getU32LE(b, off))
128
187
 
129
- /** `getU32BE`'s bits as a two's-complement `i32`. */
188
+ /**
189
+ * `getU32BE`'s bits as a two's-complement `i32`.
190
+ *
191
+ * @param b The bytes the number is read from; they are not changed.
192
+ * @param off Where in `b` its first byte is; it covers `b[off]` to
193
+ * `b[off + 3]`, and a byte of those outside `b` panics `index`.
194
+ * @returns The number read, from -2^31 to 2^31 - 1.
195
+ */
130
196
  export const getI32BE = (b: u8[], off: i32): i32 => toI32(getU32BE(b, off))
131
197
 
132
- /** `getU64LE`'s bits as a two's-complement `i64`. */
198
+ /**
199
+ * `getU64LE`'s bits as a two's-complement `i64`.
200
+ *
201
+ * @param b The bytes the number is read from; they are not changed.
202
+ * @param off Where in `b` its first byte is; it covers `b[off]` to
203
+ * `b[off + 7]`, and a byte of those outside `b` panics `index`.
204
+ * @returns The number read, from -2^63 to 2^63 - 1.
205
+ */
133
206
  export const getI64LE = (b: u8[], off: i32): i64 => toI64(getU64LE(b, off))
134
207
 
135
- /** `getU64BE`'s bits as a two's-complement `i64`. */
208
+ /**
209
+ * `getU64BE`'s bits as a two's-complement `i64`.
210
+ *
211
+ * @param b The bytes the number is read from; they are not changed.
212
+ * @param off Where in `b` its first byte is; it covers `b[off]` to
213
+ * `b[off + 7]`, and a byte of those outside `b` panics `index`.
214
+ * @returns The number read, from -2^63 to 2^63 - 1.
215
+ */
136
216
  export const getI64BE = (b: u8[], off: i32): i64 => toI64(getU64BE(b, off))
137
217
 
138
- /** The `f64` whose IEEE 754 bits are `getU64LE`'s. */
218
+ /**
219
+ * The `f64` whose IEEE 754 bits are `getU64LE`'s.
220
+ *
221
+ * @param b The bytes the number is read from; they are not changed.
222
+ * @param off Where in `b` its first byte is; it covers `b[off]` to
223
+ * `b[off + 7]`, and a byte of those outside `b` panics `index`.
224
+ * @returns The double whose bits the eight bytes are.
225
+ */
139
226
  export const getF64LE = (b: u8[], off: i32): f64 => bitsToF64(toI64(getU64LE(b, off)))
140
227
 
141
- /** The `f64` whose IEEE 754 bits are `getU64BE`'s. */
228
+ /**
229
+ * The `f64` whose IEEE 754 bits are `getU64BE`'s.
230
+ *
231
+ * @param b The bytes the number is read from; they are not changed.
232
+ * @param off Where in `b` its first byte is; it covers `b[off]` to
233
+ * `b[off + 7]`, and a byte of those outside `b` panics `index`.
234
+ * @returns The double whose bits the eight bytes are.
235
+ */
142
236
  export const getF64BE = (b: u8[], off: i32): f64 => bitsToF64(toI64(getU64BE(b, off)))
143
237
 
144
- /** Writes `v` into `b[off]` and `b[off + 1]`, low byte first. */
238
+ /**
239
+ * Writes `v` into `b[off]` and `b[off + 1]`, low byte first.
240
+ *
241
+ * @param b The bytes written into; only the two at `off` change.
242
+ * @param off Where in `b` the first byte goes; it covers `b[off]` to
243
+ * `b[off + 1]`, and a byte of those outside `b` panics `index`.
244
+ * @param v The number to store.
245
+ */
145
246
  export const setU16LE = (b: u8[], off: i32, v: u16): void => {
146
247
  b[off] = toU8(v & 255)
147
248
  b[off + 1] = toU8((v >> 8) & 255)
148
249
  }
149
250
 
150
- /** Writes `v` into `b[off]` and `b[off + 1]`, high byte first. */
251
+ /**
252
+ * Writes `v` into `b[off]` and `b[off + 1]`, high byte first.
253
+ *
254
+ * @param b The bytes written into; only the two at `off` change.
255
+ * @param off Where in `b` the first byte goes; it covers `b[off]` to
256
+ * `b[off + 1]`, and a byte of those outside `b` panics `index`.
257
+ * @param v The number to store.
258
+ */
151
259
  export const setU16BE = (b: u8[], off: i32, v: u16): void => {
152
260
  b[off] = toU8((v >> 8) & 255)
153
261
  b[off + 1] = toU8(v & 255)
154
262
  }
155
263
 
156
- /** Writes `v` into `b[off]` to `b[off + 3]`, least significant byte first. */
264
+ /**
265
+ * Writes `v` into `b[off]` to `b[off + 3]`, least significant byte first.
266
+ *
267
+ * @param b The bytes written into; only the four at `off` change.
268
+ * @param off Where in `b` the first byte goes; it covers `b[off]` to
269
+ * `b[off + 3]`, and a byte of those outside `b` panics `index`.
270
+ * @param v The number to store.
271
+ */
157
272
  export const setU32LE = (b: u8[], off: i32, v: u32): void => {
158
273
  b[off] = toU8(v & 255)
159
274
  b[off + 1] = toU8((v >> 8) & 255)
@@ -161,7 +276,14 @@ export const setU32LE = (b: u8[], off: i32, v: u32): void => {
161
276
  b[off + 3] = toU8((v >> 24) & 255)
162
277
  }
163
278
 
164
- /** Writes `v` into `b[off]` to `b[off + 3]`, most significant byte first. */
279
+ /**
280
+ * Writes `v` into `b[off]` to `b[off + 3]`, most significant byte first.
281
+ *
282
+ * @param b The bytes written into; only the four at `off` change.
283
+ * @param off Where in `b` the first byte goes; it covers `b[off]` to
284
+ * `b[off + 3]`, and a byte of those outside `b` panics `index`.
285
+ * @param v The number to store.
286
+ */
165
287
  export const setU32BE = (b: u8[], off: i32, v: u32): void => {
166
288
  b[off] = toU8((v >> 24) & 255)
167
289
  b[off + 1] = toU8((v >> 16) & 255)
@@ -169,36 +291,96 @@ export const setU32BE = (b: u8[], off: i32, v: u32): void => {
169
291
  b[off + 3] = toU8(v & 255)
170
292
  }
171
293
 
172
- /** Writes `v` into `b[off]` to `b[off + 7]`, least significant byte first. */
294
+ /**
295
+ * Writes `v` into `b[off]` to `b[off + 7]`, least significant byte first.
296
+ *
297
+ * @param b The bytes written into; only the eight at `off` change.
298
+ * @param off Where in `b` the first byte goes; it covers `b[off]` to
299
+ * `b[off + 7]`, and a byte of those outside `b` panics `index`.
300
+ * @param v The number to store.
301
+ */
173
302
  export const setU64LE = (b: u8[], off: i32, v: u64): void => {
174
303
  for (let i: i32 = 0; i < 8; i++) {
175
304
  b[off + i] = toU8((v >> toU64(i * 8)) & toU64(255))
176
305
  }
177
306
  }
178
307
 
179
- /** Writes `v` into `b[off]` to `b[off + 7]`, most significant byte first. */
308
+ /**
309
+ * Writes `v` into `b[off]` to `b[off + 7]`, most significant byte first.
310
+ *
311
+ * @param b The bytes written into; only the eight at `off` change.
312
+ * @param off Where in `b` the first byte goes; it covers `b[off]` to
313
+ * `b[off + 7]`, and a byte of those outside `b` panics `index`.
314
+ * @param v The number to store.
315
+ */
180
316
  export const setU64BE = (b: u8[], off: i32, v: u64): void => {
181
317
  for (let i: i32 = 0; i < 8; i++) {
182
318
  b[off + i] = toU8((v >> toU64((7 - i) * 8)) & toU64(255))
183
319
  }
184
320
  }
185
321
 
186
- /** Writes `v`'s two's-complement bits as `setU32LE` does. */
322
+ /**
323
+ * Writes `v`'s two's-complement bits as `setU32LE` does.
324
+ *
325
+ * @param b The bytes written into; only the four at `off` change.
326
+ * @param off Where in `b` the first byte goes; it covers `b[off]` to
327
+ * `b[off + 3]`, and a byte of those outside `b` panics `index`.
328
+ * @param v The number to store; a negative one is stored as its two's
329
+ * complement.
330
+ */
187
331
  export const setI32LE = (b: u8[], off: i32, v: i32): void => setU32LE(b, off, toU32(v))
188
332
 
189
- /** Writes `v`'s two's-complement bits as `setU32BE` does. */
333
+ /**
334
+ * Writes `v`'s two's-complement bits as `setU32BE` does.
335
+ *
336
+ * @param b The bytes written into; only the four at `off` change.
337
+ * @param off Where in `b` the first byte goes; it covers `b[off]` to
338
+ * `b[off + 3]`, and a byte of those outside `b` panics `index`.
339
+ * @param v The number to store; a negative one is stored as its two's
340
+ * complement.
341
+ */
190
342
  export const setI32BE = (b: u8[], off: i32, v: i32): void => setU32BE(b, off, toU32(v))
191
343
 
192
- /** Writes `v`'s two's-complement bits as `setU64LE` does. */
344
+ /**
345
+ * Writes `v`'s two's-complement bits as `setU64LE` does.
346
+ *
347
+ * @param b The bytes written into; only the eight at `off` change.
348
+ * @param off Where in `b` the first byte goes; it covers `b[off]` to
349
+ * `b[off + 7]`, and a byte of those outside `b` panics `index`.
350
+ * @param v The number to store; a negative one is stored as its two's
351
+ * complement.
352
+ */
193
353
  export const setI64LE = (b: u8[], off: i32, v: i64): void => setU64LE(b, off, toU64(v))
194
354
 
195
- /** Writes `v`'s two's-complement bits as `setU64BE` does. */
355
+ /**
356
+ * Writes `v`'s two's-complement bits as `setU64BE` does.
357
+ *
358
+ * @param b The bytes written into; only the eight at `off` change.
359
+ * @param off Where in `b` the first byte goes; it covers `b[off]` to
360
+ * `b[off + 7]`, and a byte of those outside `b` panics `index`.
361
+ * @param v The number to store; a negative one is stored as its two's
362
+ * complement.
363
+ */
196
364
  export const setI64BE = (b: u8[], off: i32, v: i64): void => setU64BE(b, off, toU64(v))
197
365
 
198
- /** Writes `v`'s IEEE 754 bits as `setU64LE` does. */
366
+ /**
367
+ * Writes `v`'s IEEE 754 bits as `setU64LE` does.
368
+ *
369
+ * @param b The bytes written into; only the eight at `off` change.
370
+ * @param off Where in `b` the first byte goes; it covers `b[off]` to
371
+ * `b[off + 7]`, and a byte of those outside `b` panics `index`.
372
+ * @param v The double to store, as its IEEE 754 bits.
373
+ */
199
374
  export const setF64LE = (b: u8[], off: i32, v: f64): void => setU64LE(b, off, toU64(f64ToBits(v)))
200
375
 
201
- /** Writes `v`'s IEEE 754 bits as `setU64BE` does. */
376
+ /**
377
+ * Writes `v`'s IEEE 754 bits as `setU64BE` does.
378
+ *
379
+ * @param b The bytes written into; only the eight at `off` change.
380
+ * @param off Where in `b` the first byte goes; it covers `b[off]` to
381
+ * `b[off + 7]`, and a byte of those outside `b` panics `index`.
382
+ * @param v The double to store, as its IEEE 754 bits.
383
+ */
202
384
  export const setF64BE = (b: u8[], off: i32, v: f64): void => setU64BE(b, off, toU64(f64ToBits(v)))
203
385
 
204
386
  // ---- Byte-class runs and the byte copy (WP38 S6a) ----------------------------------------
@@ -245,13 +427,30 @@ const bytesRunStart = (from: i32, end: i32): i32 => {
245
427
  * or 32 bytes at a time (docs/LANGUAGE.md, "Byte runs"). It is
246
428
  * **variable-time**: how long it takes says how long the run is, so it is
247
429
  * never for secret data.
430
+ *
431
+ * @param b The bytes scanned; they are not changed.
432
+ * @param from Where the scan starts, clamped into `[0, to]`.
433
+ * @param to Where the scan stops, exclusive, clamped into `[0, b.length]`.
434
+ * @returns The index of the first byte in the clamped range that is not a
435
+ * blank, or
436
+ * the clamped `to` when there is none.
248
437
  */
249
438
  export const skipBlank = (b: u8[], from: i32, to: i32): i32 => {
250
439
  const end: i32 = bytesRunEnd(b, to)
251
440
  return skipBlankWalk(b, bytesRunStart(from, end), end)
252
441
  }
253
442
 
254
- /** `skipBlank` for the ASCII digits `0` to `9`: the same clamps, the same kernel family, `nish_bytes_skip_digits`. */
443
+ /**
444
+ * `skipBlank` for the ASCII digits `0` to `9`: the same clamps, the same
445
+ * kernel family, `nish_bytes_skip_digits`.
446
+ *
447
+ * @param b The bytes scanned; they are not changed.
448
+ * @param from Where the scan starts, clamped into `[0, to]`.
449
+ * @param to Where the scan stops, exclusive, clamped into `[0, b.length]`.
450
+ * @returns The index of the first byte in the clamped range that is not a
451
+ * digit, or
452
+ * the clamped `to` when there is none.
453
+ */
255
454
  export const skipDigits = (b: u8[], from: i32, to: i32): i32 => {
256
455
  const end: i32 = bytesRunEnd(b, to)
257
456
  return skipDigitsWalk(b, bytesRunStart(from, end), end)
@@ -260,14 +459,22 @@ export const skipDigits = (b: u8[], from: i32, to: i32): i32 => {
260
459
  /**
261
460
  * `skipBlank` for the bytes a JSON string holds as themselves: printable ASCII
262
461
  * other than `"` and `\`, and every well-formed UTF-8 sequence (RFC 3629 §4)
263
- * that ends before `to`. The run stops at the first quote, backslash or
264
- * control byte, and at the lead byte of a sequence that is malformed — an
265
- * overlong form, a surrogate, a code point past U+10FFFF, a stray continuation
266
- * byte — or cut short by `to`. So a whole JSON string body with no escape is
267
- * one call, and where it stops is the byte a decoder has to look at. Natively
268
- * the scan is `nish_bytes_skip_json_text`: blocks of ASCII 16 or 32 bytes at a
269
- * time, each multi-byte sequence a byte at a time. Variable-time, as
270
- * `skipBlank` is.
462
+ * that ends before `to`. The run stops at the first quote, backslash or control
463
+ * byte, and at the lead byte of a sequence that is malformed — an overlong
464
+ * form, a surrogate, a code point past U+10FFFF, a stray continuation byte — or
465
+ * cut short by `to`.
466
+ *
467
+ * So a whole JSON string body with no escape is one call, and where it stops is
468
+ * the byte a decoder has to look at. Natively the scan is
469
+ * `nish_bytes_skip_json_text`: blocks of ASCII 16 or 32 bytes at a time, each
470
+ * multi-byte sequence a byte at a time. Variable-time, as `skipBlank` is.
471
+ *
472
+ * @param b The bytes scanned; they are not changed.
473
+ * @param from Where the scan starts, clamped into `[0, to]`.
474
+ * @param to Where the scan stops, exclusive, clamped into `[0, b.length]`.
475
+ * @returns The index of the first byte in the clamped range that is not in
476
+ * the run, or
477
+ * the clamped `to` when there is none.
271
478
  */
272
479
  export const skipJsonText = (b: u8[], from: i32, to: i32): i32 => {
273
480
  const end: i32 = bytesRunEnd(b, to)
@@ -283,6 +490,13 @@ export const skipJsonText = (b: u8[], from: i32, to: i32): i32 => {
283
490
  * the bytes of a string through as they are. Natively the scan is
284
491
  * `nish_bytes_skip_json_plain`, 16 bytes at a time. Variable-time, as
285
492
  * `skipBlank` is.
493
+ *
494
+ * @param b The bytes scanned; they are not changed.
495
+ * @param from Where the scan starts, clamped into `[0, to]`.
496
+ * @param to Where the scan stops, exclusive, clamped into `[0, b.length]`.
497
+ * @returns The index of the first byte in the clamped range that a JSON
498
+ * writer must escape, or
499
+ * the clamped `to` when there is none.
286
500
  */
287
501
  export const skipJsonPlain = (b: u8[], from: i32, to: i32): i32 => {
288
502
  const end: i32 = bytesRunEnd(b, to)
@@ -300,6 +514,12 @@ export const skipJsonPlain = (b: u8[], from: i32, to: i32): i32 => {
300
514
  * `0 <= from <= from + count <= src.length` and the same for `at` in `dst` —
301
515
  * panics `copyBytes` before any byte is written. Natively the copy is one
302
516
  * `llvm.memmove`.
517
+ *
518
+ * @param dst The array written into; only `dst[at..at+count)` changes.
519
+ * @param at Where in `dst` the first copied byte goes.
520
+ * @param src The array copied from, which may be `dst` itself.
521
+ * @param from Where in `src` the copied bytes start.
522
+ * @param count How many bytes to copy; zero copies nothing.
303
523
  */
304
524
  export const copyBytes = (dst: u8[], at: i32, src: readonly u8[], from: i32, count: i32): void => {
305
525
  if (count < 0 || at < 0 || from < 0 || at > toI32(dst.length) - count || from > toI32(src.length) - count) {