@amritk/nish-aarch64-darwin 0.35.0 → 0.36.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 (119) hide show
  1. package/INSTALL.md +6 -1
  2. package/bin/nish +0 -0
  3. package/docs/AI.md +9 -2
  4. package/package.json +1 -1
  5. package/runtime/nish.d.ts +4612 -430
  6. package/runtime/vite.d.ts +30 -0
  7. package/runtime/vite.mjs +150 -0
  8. package/scripts/build.sh +108 -13
  9. package/std/base64.ts +34 -5
  10. package/std/bytes.ts +256 -40
  11. package/std/cli-args.ts +296 -70
  12. package/std/cli-flags.ts +184 -19
  13. package/std/cli.ts +475 -54
  14. package/std/collections.ts +121 -23
  15. package/std/compress/checksum.ts +44 -14
  16. package/std/compress/deflate.ts +224 -111
  17. package/std/compress/gzip.ts +217 -53
  18. package/std/compress/zlib.ts +63 -7
  19. package/std/crypto/aes.ts +80 -9
  20. package/std/crypto/base64url.ts +22 -0
  21. package/std/crypto/bcrypt-batch.ts +88 -21
  22. package/std/crypto/bcrypt.ts +60 -0
  23. package/std/crypto/chacha20poly1305.ts +53 -0
  24. package/std/crypto/ct.ts +32 -13
  25. package/std/crypto/ed25519.ts +47 -0
  26. package/std/crypto/hkdf.ts +198 -13
  27. package/std/crypto/hmac.ts +235 -31
  28. package/std/crypto/jwt.ts +192 -63
  29. package/std/crypto/p256.ts +159 -16
  30. package/std/crypto/p384.ts +28 -3
  31. package/std/crypto/pki-roots.ts +32 -2
  32. package/std/crypto/pki.ts +81 -15
  33. package/std/crypto/rsa.ts +33 -3
  34. package/std/crypto/sha1.ts +3 -0
  35. package/std/crypto/sha256.ts +24 -1
  36. package/std/crypto/sha512.ts +99 -14
  37. package/std/crypto/x25519.ts +152 -14
  38. package/std/crypto/x509-random.ts +10 -0
  39. package/std/crypto/x509.ts +67 -7
  40. package/std/json-equal.ts +19 -0
  41. package/std/json-format.ts +112 -13
  42. package/std/json-number.ts +64 -14
  43. package/std/json-pointer.ts +23 -1
  44. package/std/json-tokenizer.ts +100 -29
  45. package/std/json-typed.ts +713 -66
  46. package/std/json-value.ts +400 -124
  47. package/std/json.ts +138 -10
  48. package/std/map.ts +25 -7
  49. package/std/math.ts +36 -4
  50. package/std/net/buffer-pool.ts +42 -11
  51. package/std/net/dns-config.ts +109 -23
  52. package/std/net/dns-message.ts +62 -7
  53. package/std/net/dns-resolver.ts +247 -53
  54. package/std/net/dns.ts +203 -35
  55. package/std/net/fetch.ts +151 -61
  56. package/std/net/handler.ts +278 -80
  57. package/std/net/hpack.ts +262 -52
  58. package/std/net/http-compress.ts +125 -15
  59. package/std/net/http-fields.ts +85 -9
  60. package/std/net/http1-client-codec.ts +100 -19
  61. package/std/net/http1-codec.ts +235 -27
  62. package/std/net/http1-server.ts +343 -85
  63. package/std/net/http2-frame.ts +272 -35
  64. package/std/net/http2-tls.ts +135 -34
  65. package/std/net/http2.ts +247 -106
  66. package/std/net/http3-frame.ts +154 -17
  67. package/std/net/http3-server.ts +246 -96
  68. package/std/net/http3.ts +307 -115
  69. package/std/net/outbound.ts +37 -3
  70. package/std/net/postgres-carrier.ts +144 -8
  71. package/std/net/postgres.ts +723 -103
  72. package/std/net/prefork.ts +164 -31
  73. package/std/net/qpack.ts +105 -18
  74. package/std/net/quic-conn-ack.ts +59 -12
  75. package/std/net/quic-conn-cid.ts +124 -27
  76. package/std/net/quic-conn-params.ts +70 -10
  77. package/std/net/quic-datagram.ts +43 -3
  78. package/std/net/quic-frame.ts +286 -12
  79. package/std/net/quic-listener.ts +101 -32
  80. package/std/net/quic-packet.ts +302 -21
  81. package/std/net/quic-recovery.ts +228 -44
  82. package/std/net/quic-stream.ts +353 -91
  83. package/std/net/quic.ts +489 -171
  84. package/std/net/router.ts +87 -40
  85. package/std/net/tls/client.ts +166 -51
  86. package/std/net/tls/codec.ts +413 -56
  87. package/std/net/tls/record-client.ts +110 -55
  88. package/std/net/tls/record-server.ts +159 -59
  89. package/std/net/tls/record.ts +109 -12
  90. package/std/net/tls/schedule.ts +235 -26
  91. package/std/net/tls/ticket.ts +159 -40
  92. package/std/net/tls/verify.ts +49 -3
  93. package/std/net/tls-tcp.ts +250 -45
  94. package/std/net/tls.ts +221 -59
  95. package/std/net/upstream.ts +81 -45
  96. package/std/net/url.ts +97 -13
  97. package/std/net/websocket.ts +122 -12
  98. package/std/net/webtransport.ts +220 -89
  99. package/std/pair.ts +10 -2
  100. package/std/random.ts +34 -9
  101. package/std/regex.ts +352 -198
  102. package/std/region.ts +70 -15
  103. package/std/secret.ts +52 -11
  104. package/std/sort.ts +17 -2
  105. package/std/sqlite.ts +256 -35
  106. package/std/sync/ring.ts +205 -35
  107. package/std/sync/shm.ts +194 -16
  108. package/std/term-io.ts +137 -64
  109. package/std/term-pixels.ts +144 -19
  110. package/std/term-probe.ts +66 -25
  111. package/std/term-rate.ts +128 -57
  112. package/std/term.ts +332 -121
  113. package/std/testing.ts +130 -32
  114. package/std/text.ts +73 -7
  115. package/std/threads.ts +229 -41
  116. package/std/yaml-json.ts +94 -82
  117. package/std/yaml-lines.ts +47 -15
  118. package/std/yaml-write.ts +24 -16
  119. package/std/yaml.ts +764 -384
@@ -9,6 +9,17 @@
9
9
  * one module (§4.1). Under Node, and under `tsc`, `Map` and `Set` are the
10
10
  * platform's, so nothing here runs there.
11
11
  *
12
+ * const counts = new Map<string, i32>()
13
+ * const seen = new Set<string>()
14
+ * for (const w of ["to", "be", "or", "not", "to", "be"]) {
15
+ * counts.set(w, (counts.get(w) ?? 0) + 1)
16
+ * seen.add(w)
17
+ * }
18
+ * for (const w of counts.keys()) {
19
+ * console.log(`${w} ${counts.get(w) ?? 0}`) // "to 2", "be 2", "or 1", ...
20
+ * }
21
+ * seen.size // 4, and seen.has("or") is true
22
+ *
12
23
  * **The layout is §2's.** Entries sit in insertion order in parallel arrays,
13
24
  * `entryKeys`, `entryValues` and `entryHashes`, and `entryHashes` holds the
14
25
  * full 32-bit hash of each. The bucket table `slots` is open addressing with
@@ -274,22 +285,23 @@ export class Map<K, V> {
274
285
  /** How many entries are live. The one field a program may read, and it may not write it. */
275
286
  size: number = 0
276
287
  /** Bucket -> fingerprint and entry index plus one; see the header. */
277
- slots: u32[]
288
+ private slots: u32[]
278
289
  /** `slots.length - 1`: the table is a power of two. */
279
- mask: i32 = 7
290
+ private mask: i32 = 7
280
291
  /** Live entries, as an `i32` for the load and compaction arithmetic. */
281
- live: i32 = 0
282
- entryKeys: K[]
283
- entryValues: V[]
292
+ private live: i32 = 0
293
+ private entryKeys: K[]
294
+ private entryValues: V[]
284
295
  /** The full hash of each entry; 0 once the entry is deleted. */
285
- entryHashes: u32[]
296
+ private entryHashes: u32[]
286
297
  /**
287
298
  * How many `for...of` loops are walking the table now. While it is above 0
288
299
  * a rebuild doubles rather than compacts, and `clear` marks entries dead
289
300
  * rather than truncating, so no entry moves under a walk's cursor (§6.2).
290
301
  */
291
- walks: i32 = 0
302
+ private walks: i32 = 0
292
303
 
304
+ /** An empty map. */
293
305
  constructor() {
294
306
  this.slots = new Array<u32>(INITIAL_SLOTS)
295
307
  this.entryKeys = []
@@ -297,16 +309,36 @@ export class Map<K, V> {
297
309
  this.entryHashes = []
298
310
  }
299
311
 
300
- /** The packed probe result for `key`: see `probeTable`, `foundAt` and `absentAt`. */
312
+ /**
313
+ * The packed probe result for `key`: see `probeTable`, `foundAt` and
314
+ * `absentAt`.
315
+ *
316
+ * @internal Called by name by the code the compiler writes for a `Map`,
317
+ * src/emit-map.ts.
318
+ */
301
319
  probe(key: K): i64 {
302
320
  return probeTable(this.slots, this.mask, this.entryHashes, this.entryKeys, key)
303
321
  }
304
322
 
323
+ /**
324
+ * Whether the map has an entry for `key`.
325
+ *
326
+ * @param key - the key to look for, compared by SameValueZero: `===`, except
327
+ * that NaN equals NaN.
328
+ * @returns true when there is an entry.
329
+ */
305
330
  has(key: K): boolean {
306
331
  return this.probe(key) >= 0
307
332
  }
308
333
 
309
- /** Set `key` to `value`, in place when it is there and at the end when it is not: one probe. */
334
+ /**
335
+ * Set `key` to `value`, in place when it is there and at the end when it is
336
+ * not: one probe.
337
+ *
338
+ * @param key - the entry's key.
339
+ * @param value - the value to store.
340
+ * @returns the map itself, so that calls chain.
341
+ */
310
342
  set(key: K, value: V): Map<K, V> {
311
343
  const found = this.probe(key)
312
344
  if (found >= 0) {
@@ -317,6 +349,12 @@ export class Map<K, V> {
317
349
  return this
318
350
  }
319
351
 
352
+ /**
353
+ * Removes the entry for `key`, if there is one; the others keep their order.
354
+ *
355
+ * @param key - the key to remove.
356
+ * @returns true when there was an entry to remove.
357
+ */
320
358
  delete(key: K): boolean {
321
359
  const found = this.probe(key)
322
360
  if (found < 0) {
@@ -351,20 +389,30 @@ export class Map<K, V> {
351
389
  * entered, `walkNext` for the first live entry and after each pass,
352
390
  * `keyAt` or `valueAt` for the loop variable, and `walkClose` on every edge
353
391
  * that leaves the loop. Two stores a loop, and none per entry.
392
+ *
393
+ * @internal Called by name by the code the compiler writes for a `Map`,
394
+ * src/emit-map.ts.
354
395
  */
355
396
  walkOpen(): void {
356
397
  this.walks = this.walks + 1
357
398
  }
358
399
 
400
+ /** @internal Called by name by the code the compiler writes for a `Map`, src/emit-map.ts. */
359
401
  walkNext(from: i32): i32 {
360
402
  return nextLive(this.entryHashes, from)
361
403
  }
362
404
 
405
+ /** @internal Called by name by the code the compiler writes for a `Map`, src/emit-map.ts. */
363
406
  walkClose(): void {
364
407
  this.walks = this.walks - 1
365
408
  }
366
409
 
367
- /** The key of entry `index`, which `walkNext` answered. */
410
+ /**
411
+ * The key of entry `index`, which `walkNext` answered.
412
+ *
413
+ * @internal Called by name by the code the compiler writes for a `Map`,
414
+ * src/emit-map.ts.
415
+ */
368
416
  keyAt(index: i32): K {
369
417
  if (index < 0 || index >= toI32(this.entryKeys.length)) {
370
418
  panic("Map: no entry at this index")
@@ -372,7 +420,12 @@ export class Map<K, V> {
372
420
  return this.entryKeys[index]
373
421
  }
374
422
 
375
- /** The value of the entry a probe found, or a walk reached. */
423
+ /**
424
+ * The value of the entry a probe found, or a walk reached.
425
+ *
426
+ * @internal Called by name by the code the compiler writes for a `Map`,
427
+ * src/emit-map.ts.
428
+ */
376
429
  valueAt(index: i32): V {
377
430
  if (index < 0 || index >= toI32(this.entryValues.length)) {
378
431
  panic("Map: no entry at this index")
@@ -380,14 +433,25 @@ export class Map<K, V> {
380
433
  return this.entryValues[index]
381
434
  }
382
435
 
383
- /** Overwrite the value of the entry a probe found; it keeps its place. */
436
+ /**
437
+ * Overwrite the value of the entry a probe found; it keeps its place.
438
+ *
439
+ * @internal Called by name by the code the compiler writes for a `Map`,
440
+ * src/emit-map.ts.
441
+ */
384
442
  setValueAt(index: i32, value: V): void {
385
443
  if (index >= 0 && index < toI32(this.entryValues.length)) {
386
444
  this.entryValues[index] = value
387
445
  }
388
446
  }
389
447
 
390
- /** Append an entry for `key` at the empty bucket an absent probe result names, reusing its hash. */
448
+ /**
449
+ * Append an entry for `key` at the empty bucket an absent probe result names,
450
+ * reusing its hash.
451
+ *
452
+ * @internal Called by name by the code the compiler writes for a `Map`,
453
+ * src/emit-map.ts.
454
+ */
391
455
  insertAt(absent: i64, key: K, value: V): void {
392
456
  const packed = -1 - absent
393
457
  let bucket = toI32(packed >> 32)
@@ -421,7 +485,7 @@ export class Map<K, V> {
421
485
  * While a loop walks the table it always doubles and moves no entry, and the
422
486
  * first rebuild after the walk compacts (§6.2).
423
487
  */
424
- rebuild(): void {
488
+ private rebuild(): void {
425
489
  const used = toI32(this.entryKeys.length)
426
490
  const walking = this.walks > 0
427
491
  const slots = rebuiltSlots(this.slots, walking ? used : this.live, used)
@@ -443,6 +507,9 @@ export class Map<K, V> {
443
507
  * safe under a walk as the doubling a walk already allows (§6.2). A count
444
508
  * that is not positive, or not a number, does nothing, as `reserve` does
445
509
  * under Node; one past the entry cap is the cap.
510
+ *
511
+ * @internal Called by name by the code the compiler writes for `reserve` from
512
+ * `nish/map`, src/emit-map.ts.
446
513
  */
447
514
  reserveSlots(n: number): void {
448
515
  if (!(n > 0)) {
@@ -468,29 +535,43 @@ export class Map<K, V> {
468
535
  export class Set<T> {
469
536
  /** How many elements are live. The one field a program may read, and it may not write it. */
470
537
  size: number = 0
471
- slots: u32[]
472
- mask: i32 = 7
473
- live: i32 = 0
474
- entryKeys: T[]
475
- entryHashes: u32[]
538
+ private slots: u32[]
539
+ private mask: i32 = 7
540
+ private live: i32 = 0
541
+ private entryKeys: T[]
542
+ private entryHashes: u32[]
476
543
  /** `Map`'s walk count: how many `for...of` loops are walking the table now. */
477
- walks: i32 = 0
544
+ private walks: i32 = 0
478
545
 
546
+ /** An empty set. */
479
547
  constructor() {
480
548
  this.slots = new Array<u32>(INITIAL_SLOTS)
481
549
  this.entryKeys = []
482
550
  this.entryHashes = []
483
551
  }
484
552
 
553
+ /** @internal Called by name by the code the compiler writes for a `Set`, src/emit-map.ts. */
485
554
  probe(key: T): i64 {
486
555
  return probeTable(this.slots, this.mask, this.entryHashes, this.entryKeys, key)
487
556
  }
488
557
 
558
+ /**
559
+ * Whether `key` is in the set.
560
+ *
561
+ * @param key - the key to look for, compared by SameValueZero: `===`, except
562
+ * that NaN equals NaN.
563
+ * @returns true when it is.
564
+ */
489
565
  has(key: T): boolean {
490
566
  return this.probe(key) >= 0
491
567
  }
492
568
 
493
- /** Add `key` at the end when it is not there already: one probe. */
569
+ /**
570
+ * Add `key` at the end when it is not there already: one probe.
571
+ *
572
+ * @param key - the key to add.
573
+ * @returns the set itself, so that calls chain.
574
+ */
494
575
  add(key: T): Set<T> {
495
576
  const found = this.probe(key)
496
577
  if (found < 0) {
@@ -499,6 +580,12 @@ export class Set<T> {
499
580
  return this
500
581
  }
501
582
 
583
+ /**
584
+ * Removes `key`, if it is there; the others keep their order.
585
+ *
586
+ * @param key - the key to remove.
587
+ * @returns true when there was a key to remove.
588
+ */
502
589
  delete(key: T): boolean {
503
590
  const found = this.probe(key)
504
591
  if (found < 0) {
@@ -510,6 +597,7 @@ export class Set<T> {
510
597
  return true
511
598
  }
512
599
 
600
+ /** Removes every key, keeping the table's memory. */
513
601
  clear(): void {
514
602
  clearSlots(this.slots)
515
603
  if (this.walks > 0) {
@@ -522,19 +610,28 @@ export class Set<T> {
522
610
  this.size = 0
523
611
  }
524
612
 
525
- /** `Map`'s walk: `for (const x of s)`, `s.keys()` and `s.values()` are all this one. */
613
+ /**
614
+ * `Map`'s walk: `for (const x of s)`, `s.keys()` and `s.values()` are all
615
+ * this one.
616
+ *
617
+ * @internal Called by name by the code the compiler writes for a `Set`,
618
+ * src/emit-map.ts.
619
+ */
526
620
  walkOpen(): void {
527
621
  this.walks = this.walks + 1
528
622
  }
529
623
 
624
+ /** @internal Called by name by the code the compiler writes for a `Set`, src/emit-map.ts. */
530
625
  walkNext(from: i32): i32 {
531
626
  return nextLive(this.entryHashes, from)
532
627
  }
533
628
 
629
+ /** @internal Called by name by the code the compiler writes for a `Set`, src/emit-map.ts. */
534
630
  walkClose(): void {
535
631
  this.walks = this.walks - 1
536
632
  }
537
633
 
634
+ /** @internal Called by name by the code the compiler writes for a `Set`, src/emit-map.ts. */
538
635
  keyAt(index: i32): T {
539
636
  if (index < 0 || index >= toI32(this.entryKeys.length)) {
540
637
  panic("Set: no entry at this index")
@@ -542,6 +639,7 @@ export class Set<T> {
542
639
  return this.entryKeys[index]
543
640
  }
544
641
 
642
+ /** @internal Called by name by the code the compiler writes for a `Set`, src/emit-map.ts. */
545
643
  insertAt(absent: i64, key: T): void {
546
644
  const packed = -1 - absent
547
645
  let bucket = toI32(packed >> 32)
@@ -567,7 +665,7 @@ export class Set<T> {
567
665
  }
568
666
  }
569
667
 
570
- rebuild(): void {
668
+ private rebuild(): void {
571
669
  const used = toI32(this.entryKeys.length)
572
670
  const walking = this.walks > 0
573
671
  const slots = rebuiltSlots(this.slots, walking ? used : this.live, used)
@@ -9,12 +9,13 @@
9
9
  * let c: u32 = crc.update(toU32(0), body, 0, 100);
10
10
  * c = crc.update(c, body, 100, toI32(body.length) - 100); // the same as one call
11
11
  *
12
- * A module has no global state, so CRC-32's tables live in a `Crc32` object:
13
- * build one and keep it, because building it is 4,096 table entries (about
14
- * ten microseconds) and an update of a 5 KB body is under one. `crc32`
15
- * is the one-off convenience that builds a table for one call.
12
+ * **Keep a `Crc32`.** A module has no global state, so CRC-32's tables live
13
+ * in a `Crc32` object: build one and keep it, because building it is 4,096
14
+ * table entries (about ten microseconds) and an update of a 5 KB body is
15
+ * under one. `crc32` is the one-off convenience that builds a table for one
16
+ * call.
16
17
  *
17
- * CRC-32 is slicing-by-8: eight 256-entry tables, eight bytes per step with
18
+ * **CRC-32 is slicing-by-8**: eight 256-entry tables, eight bytes per step with
18
19
  * one table read per byte and no dependency between the reads of a step
19
20
  * (Kounavis and Berry, "A Systematic Approach to Building High Performance
20
21
  * Software-based CRC Generators", 2005). From 80 bytes on it is also braided
@@ -23,13 +24,14 @@
23
24
  * reductions to once every 5,552 bytes, the most that cannot overflow 32 bits
24
25
  * (RFC 1950 §9 and zlib's `NMAX`).
25
26
  *
26
- * Neither is a cryptographic hash: both detect accidental corruption only.
27
+ * **Neither is a cryptographic hash**: both detect accidental corruption only.
27
28
  * Written from the specifications, not ported from another implementation.
28
29
  *
29
- * The table reads in `update` are `nish:unsafe`'s `uncheckedGet`: every index
30
- * is a byte plus a multiple of 256 below 2,048, and both tables are built here
31
- * at exactly that length and never replaced, which is the whole proof. The input
32
- * window is checked once, before the loop.
30
+ * **What is unchecked.** The table reads in `update` are `nish:unsafe`'s
31
+ * `uncheckedGet`: every index is a byte plus a multiple of 256 below 2,048,
32
+ * and both tables are built here at exactly that length and never replaced,
33
+ * which is the whole proof. The input window is checked once, before the
34
+ * loop.
33
35
  */
34
36
  import { uncheckedGet, uncheckedSet } from "nish:unsafe"
35
37
 
@@ -103,12 +105,12 @@ const checksumWindow = (what: string, buf: u8[], off: i32, len: i32): void => {
103
105
  */
104
106
  export class Crc32 {
105
107
  /** `table[k * 256 + b]`: the CRC of byte `b` followed by `k` zero bytes. */
106
- readonly table: u32[]
108
+ private readonly table: u32[]
107
109
  /**
108
110
  * `braid[k * 256 + b]`: the same, followed by the 32 bytes of the other
109
111
  * four braids' words as well, which a braid steps over.
110
112
  */
111
- readonly braid: u32[]
113
+ private readonly braid: u32[]
112
114
 
113
115
  /** Builds the eight tables and their braided form. */
114
116
  constructor() {
@@ -151,7 +153,15 @@ export class Crc32 {
151
153
  /**
152
154
  * The CRC-32 of the bytes `crc` was the CRC of, followed by
153
155
  * `buf[off .. off + len)`. Start a new checksum from 0. A window outside
154
- * `buf` panics.
156
+ * `buf` panics. Neither the object nor `buf` is changed.
157
+ *
158
+ * @param crc The CRC-32 of the bytes before this window, as the last
159
+ * `update` answered it, or 0 to start a new checksum.
160
+ * @param buf The array that holds the bytes to add.
161
+ * @param off Where in `buf` the bytes start.
162
+ * @param len How many bytes to add; 0 answers `crc` unchanged.
163
+ * @returns The CRC-32 of everything so far, to pass as `crc` to the next
164
+ * `update`, or to use as the finished checksum.
155
165
  */
156
166
  update(crc: u32, buf: u8[], off: i32, len: i32): u32 {
157
167
  checksumWindow("Crc32.update", buf, off, len)
@@ -258,6 +268,11 @@ const crc32Walk = (t: u32[], bt: u32[], crc: u32, buf: u8[], off: i32, len: i32)
258
268
  * The CRC-32 of `buf[off .. off + len)`. It builds a `Crc32` for the one
259
269
  * call, which costs about as much as checksumming 5 KB: keep a `Crc32` for
260
270
  * anything repeated. A window outside `buf` panics.
271
+ *
272
+ * @param buf The array that holds the bytes to checksum.
273
+ * @param off Where in `buf` the bytes start.
274
+ * @param len How many bytes to checksum; 0 answers 0.
275
+ * @returns The CRC-32 of the window, the value gzip's trailer carries.
261
276
  */
262
277
  export const crc32 = (buf: u8[], off: i32, len: i32): u32 => new Crc32().update(toU32(0), buf, off, len)
263
278
 
@@ -265,6 +280,14 @@ export const crc32 = (buf: u8[], off: i32, len: i32): u32 => new Crc32().update(
265
280
  * The Adler-32 of the bytes `adler` was the Adler-32 of, followed by
266
281
  * `buf[off .. off + len)` (RFC 1950 §9). Start a new checksum from 1. A
267
282
  * window outside `buf` panics.
283
+ *
284
+ * @param adler The Adler-32 of the bytes before this window, as the last
285
+ * call answered it, or 1 to start a new checksum.
286
+ * @param buf The array that holds the bytes to add.
287
+ * @param off Where in `buf` the bytes start.
288
+ * @param len How many bytes to add; 0 answers `adler` unchanged.
289
+ * @returns The Adler-32 of everything so far, to pass as `adler` to the
290
+ * next call, or to use as the finished checksum.
268
291
  */
269
292
  export const adler32Update = (adler: u32, buf: u8[], off: i32, len: i32): u32 => {
270
293
  checksumWindow("adler32Update", buf, off, len)
@@ -299,5 +322,12 @@ export const adler32Update = (adler: u32, buf: u8[], off: i32, len: i32): u32 =>
299
322
  return (s2 << 16) | s1
300
323
  }
301
324
 
302
- /** The Adler-32 of `buf[off .. off + len)`. A window outside `buf` panics. */
325
+ /**
326
+ * The Adler-32 of `buf[off .. off + len)`. A window outside `buf` panics.
327
+ *
328
+ * @param buf The array that holds the bytes to checksum.
329
+ * @param off Where in `buf` the bytes start.
330
+ * @param len How many bytes to checksum; 0 answers 1.
331
+ * @returns The Adler-32 of the window, the value zlib's trailer carries.
332
+ */
303
333
  export const adler32 = (buf: u8[], off: i32, len: i32): u32 => adler32Update(toU32(1), buf, off, len)