@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
@@ -4,12 +4,17 @@
4
4
  * messages into an output buffer and reads the backend's from an input
5
5
  * buffer, for a program that owns its socket (`nish:net`) and its loop.
6
6
  *
7
+ * import { PG_FAILED, PG_NEED_MORE, PgConfig, PgConnection } from "nish/net/postgres";
8
+ * import { secret, wipe } from "nish:secret";
9
+ *
7
10
  * const config = new PgConfig();
8
11
  * config.user = "app";
9
12
  * config.database = "app";
10
13
  * const nonce = new Array<u8>(18);
11
14
  * crypto.getRandomValues(nonce);
15
+ * const password = secret(passwordBytes); // a u8[] the program read from its secret store
12
16
  * const conn = new PgConnection(config, password, nonce);
17
+ * wipe(password); // the connection keeps its own copy
13
18
  * // write conn.outputBuffer()[conn.outputStart() .. conn.outputEnd()), then conn.sent(n)
14
19
  * // read into conn.inputBuffer() at conn.inputEnd(), up to conn.inputRoom() bytes, then conn.received(n)
15
20
  * let event: i32 = conn.next();
@@ -25,18 +30,22 @@
25
30
  * event = conn.next();
26
31
  * }
27
32
  *
28
- * **Events.** `next()` answers `PG_READY` once, when the server has
29
- * authenticated the connection and is ready for queries; `PG_DESCRIBED` when a
30
- * prepared statement has been described (`columns` and `columnType(c)` say
31
- * what its rows hold, `columns` is 0 when it returns none); `PG_ROW` for each
32
- * row, its columns as windows into the input buffer (`colStart(c)`,
33
- * `colLength(c)`, -1 for NULL); `PG_COMPLETE` when an execution has finished
34
- * (`tagIs("UPDATE")`, `tagRows()`); `PG_ERROR` when a statement in the current
35
- * group failed (`lastError`); `PG_NOTICE` for a notice (`lastNotice`);
36
- * `PG_GROUP_DONE` when a group has been answered to its end (`groupFailed`,
37
- * `txStatus`); and `PG_FAILED`, final: the connection broke a rule or the
38
- * server ended it, `failure` says which and `lastError` holds the server's
39
- * reason when it gave one. `PG_NEED_MORE` asks for more input.
33
+ * **Events.**
34
+ *
35
+ * `next()` answers `PG_READY` once, when the server has authenticated the
36
+ * connection and is ready for queries; `PG_DESCRIBED` when a prepared statement
37
+ * has been described (`columns` and `columnType(c)` say what its rows hold,
38
+ * `columns` is 0 when it returns none); `PG_ROW` for each row, its columns as
39
+ * windows into the input buffer (`colStart(c)`, `colLength(c)`, -1 for NULL);
40
+ * `PG_COMPLETE` when an execution has finished (`tagIs("UPDATE")`,
41
+ * `tagRows()`); `PG_ERROR` when a statement in the current group failed
42
+ * (`lastError`); `PG_NOTICE` for a notice (`lastNotice`); `PG_GROUP_DONE` when
43
+ * a group has been answered to its end (`groupFailed`, `txStatus`); and
44
+ * `PG_FAILED`, final: the connection broke a rule or the server ended it,
45
+ * `failure` says which and `lastError` holds the server's reason when it gave
46
+ * one.
47
+ *
48
+ * `PG_NEED_MORE` asks for more input.
40
49
  *
41
50
  * **Windows and buffers.** A column's window, the tag `tagIs` and `tagRows`
42
51
  * read are valid until the next `next()`,
@@ -53,93 +62,101 @@
53
62
  * In a failed group, `PG_DESCRIBED` comes once for each `prepare` the server
54
63
  * parsed before the error: a program that counts them knows which statements
55
64
  * exist (named ones last past the group) and which must be prepared again.
56
- * Up to `maxInFlight` groups may wait for their answers at once; `canSend()`
57
- * says whether another may start, and the builder calls refuse (and write
58
- * nothing) when it may not. Nothing waits for a round trip that the protocol
59
- * does not need: a program prepares a statement and executes it in the same
60
- * flight.
61
65
  *
62
- * **Text results, no copies.** Every parameter is in text format unless it
63
- * is one of the binary integer arrays below, and every result column is text
64
- * unless the bind asks otherwise. A row is read where it
65
- * lies in the input buffer: `next()` frames each message once, validates its
66
- * layout, and records each column's start and length in two reused arrays, so
67
- * a row costs no allocation. `int`, `bool`, `isNull` and `PgText.timestamp`
68
- * decode a column in place; `PgArrayWalker` walks a one-dimensional `text[]`
69
- * in place. `columnText(c)` is the one that allocates, a string. An array
70
- * parameter is a text array literal too: `paramIntArray` writes an `int8[]`
71
- * from an `i64[]` window, and `arrayStart`, `arrayElement`, `arrayInt`,
72
- * `arrayNull` and `arrayEnd` build an array one element at a time into the
73
- * Bind, so a list needs no string built first. A program whose element was
74
- * refused for room can drop the whole bind, unsent, with `bindCancel`.
66
+ * Up to `maxInFlight` groups may wait for their answers at once; `canSend()`
67
+ * says whether another may start, and the builder calls refuse (and write
68
+ * nothing) when it may not. Nothing waits for a round trip that the protocol
69
+ * does not need: a program prepares a statement and executes it in the same
70
+ * flight.
71
+ *
72
+ * **Text results, no copies.** Every parameter is in text format unless it is
73
+ * one of the binary integer arrays below, and every result column is text
74
+ * unless the bind asks otherwise. A row is read where it lies in the input
75
+ * buffer: `next()` frames each message once, validates its layout, and records
76
+ * each column's start and length in two reused arrays, so a row costs no
77
+ * allocation. `int`, `bool`, `isNull` and `PgText.timestamp` decode a column in
78
+ * place; `PgArrayWalker` walks a one-dimensional `text[]` in place.
79
+ * `columnText(c)` is the one that allocates, a string.
80
+ *
81
+ * An array parameter is a text array literal too: `paramIntArray` writes an
82
+ * `int8[]` from an `i64[]` window, and `arrayStart`, `arrayElement`,
83
+ * `arrayInt`, `arrayNull` and `arrayEnd` build an array one element at a time
84
+ * into the Bind, so a list needs no string built first. A program whose element
85
+ * was refused for room can drop the whole bind, unsent, with `bindCancel`.
75
86
  *
76
87
  * **Binary integer arrays.** `paramInt4Array` and `paramInt8Array` send an
77
- * `i64[]` window as an `int4[]` or `int8[]` in PostgreSQL's binary layout:
78
- * four or eight bytes an element and no digits to write or parse, which the
79
- * benchmark (`bench/postgres/arrays.mjs`) measured at about a tenth of the
80
- * text encoder's client CPU, and at 1,000 elements a 51% cut in the server's
81
- * on `unnest` for `int8[]`, 30% for `int4[]`.
82
- * `binaryArrayStart(oid)`, `binaryArrayInt` and `binaryArrayNull` build one
83
- * element at a time, NULLs included, and `arrayEnd` closes it. The Bind's
84
- * format codes stay a single zero word while every parameter is text; the
85
- * first binary one makes `bindEnd` write a code for each, so an all-text bind
86
- * costs nothing more. An `int4` element outside `int4` panics rather than
87
- * wrapping. The element type must match the statement's parameter: the server
88
- * answers a mismatch with `ErrorResponse` (42804) for that execution, and the
89
- * connection goes on.
88
+ * `i64[]` window as an `int4[]` or `int8[]` in PostgreSQL's binary layout: four
89
+ * or eight bytes an element and no digits to write or parse, which the
90
+ * benchmark (`bench/postgres/arrays.mjs`) measured at about a tenth of the text
91
+ * encoder's client CPU, and at 1,000 elements a 51% cut in the server's on
92
+ * `unnest` for `int8[]`, 30% for `int4[]`. `binaryArrayStart(oid)`,
93
+ * `binaryArrayInt` and `binaryArrayNull` build one element at a time, NULLs
94
+ * included, and `arrayEnd` closes it.
95
+ *
96
+ * The Bind's format codes stay a single zero word while every parameter is
97
+ * text; the first binary one makes `bindEnd` write a code for each, so an
98
+ * all-text bind costs nothing more. An `int4` element outside `int4` panics
99
+ * rather than wrapping. The element type must match the statement's parameter:
100
+ * the server answers a mismatch with `ErrorResponse` (42804) for that
101
+ * execution, and the connection goes on.
90
102
  *
91
103
  * **Binary results.** A bind opened with `bindStartBinary` instead of
92
- * `bindStart` asks for every result column in binary format: an `int8` is
93
- * eight bytes, a `timestamptz` eight bytes of microseconds since 2000, a
94
- * `bool` one byte, so there is nothing to parse and less on the wire.
95
- * `binaryInt`, `binaryBool` and `binaryFloat` read them in place, and
96
- * `PgBinary`'s `timestamp` and `iso` write a time as `PgText.timestamp` does.
97
- * A `text` column is the same bytes in either format, so `columnText` and the
98
- * column windows read it unchanged. The program knows which of its binds
99
- * asked for which, and reads each execution's rows with the matching
100
- * decoders. A `PgBatcher` with `binary` set opens each batch this way and
101
- * reads its routing ordinal with `binaryInt`, so its rows are binary too.
102
- * `PgBinaryArray` walks a one-dimensional `int2[]`, `int4[]` or `int8[]`
103
- * column in its binary layout, and refuses any other array (a `text[]` or a
104
- * multi-dimensional one among them).
104
+ * `bindStart` asks for every result column in binary format: an `int8` is eight
105
+ * bytes, a `timestamptz` eight bytes of microseconds since 2000, a `bool` one
106
+ * byte, so there is nothing to parse and less on the wire. `binaryInt`,
107
+ * `binaryBool` and `binaryFloat` read them in place, and `PgBinary`'s
108
+ * `timestamp` and `iso` write a time as `PgText.timestamp` does. A `text`
109
+ * column is the same bytes in either format, so `columnText` and the column
110
+ * windows read it unchanged.
111
+ *
112
+ * The program knows which of its binds asked for which, and reads each
113
+ * execution's rows with the matching decoders. A `PgBatcher` with `binary` set
114
+ * opens each batch this way and reads its routing ordinal with `binaryInt`, so
115
+ * its rows are binary too. `PgBinaryArray` walks a one-dimensional `int2[]`,
116
+ * `int4[]` or `int8[]` column in its binary layout, and refuses any other array
117
+ * (a `text[]` or a multi-dimensional one among them).
105
118
  *
106
- * **Authentication.** SCRAM-SHA-256 (RFC 5802, RFC 7677) or none (`trust`).
107
- * The password arrives as a `Secret<u8[]>`; the connection keeps a copy in a
108
- * holder that is wiped as soon as the proof is computed, or when the
109
- * connection fails or is disposed. The server's signature is checked in
110
- * constant time before `AuthenticationOk` is believed, and an
111
- * `AuthenticationOk` that skips the end of an exchange SCRAM began is refused.
112
- * Cleartext and MD5 passwords, and SASL mechanisms other than SCRAM-SHA-256,
113
- * are refused: with no TLS here the first sends the password as it is, and the
114
- * second is a hash any eavesdropper can replay. The password's bytes are used
115
- * as they are, without SASLprep (RFC 4013): an ASCII password works, and a
116
- * non-ASCII one works only when it is already in the form SASLprep would give
117
- * (PostgreSQL itself falls back to the raw bytes when it cannot prepare one).
118
- * `docs/security/postgres.md` is the record.
119
+ * **Authentication.** SCRAM-SHA-256 (RFC 5802, RFC 7677) or none (`trust`). The
120
+ * password arrives as a `Secret<u8[]>`; the connection keeps a copy in a holder
121
+ * that is wiped as soon as the proof is computed, or when the connection fails
122
+ * or is disposed. The server's signature is checked in constant time before
123
+ * `AuthenticationOk` is believed, and an `AuthenticationOk` that skips the end
124
+ * of an exchange SCRAM began is refused.
125
+ *
126
+ * Cleartext and MD5 passwords, and SASL mechanisms other than SCRAM-SHA-256,
127
+ * are refused: with no TLS here the first sends the password as it is, and the
128
+ * second is a hash any eavesdropper can replay. The password's bytes are used
129
+ * as they are, without SASLprep (RFC 4013): an ASCII password works, and a
130
+ * non-ASCII one works only when it is already in the form SASLprep would give
131
+ * (PostgreSQL itself falls back to the raw bytes when it cannot prepare one).
132
+ * `docs/security/postgres.md` is the record.
119
133
  *
120
134
  * **Caps.** `PgConfig` bounds what a server can make the client hold: the
121
135
  * longest message (`maxMessage`), the widest row (`maxColumns`) and the SCRAM
122
136
  * iteration count (`minIterations`, `maxIterations`); and what a program can
123
- * queue unsent (`maxOutput`), past which a builder call answers false. A
124
- * message longer than the cap, a length below 4, a layout that does not add
125
- * up, a message the protocol does not allow at that point (COPY among them),
126
- * an encoding other than UTF-8, and a `DateStyle` other than ISO or a
127
- * `TimeZone` other than UTC (at startup or after a `SET`), each fail the
128
- * connection with their own `failure` code. The constructor panics on a cap
129
- * out of range, as on a missing user or a short nonce.
137
+ * queue unsent (`maxOutput`), past which a builder call answers false.
138
+ *
139
+ * A message longer than the cap, a length below 4, a layout that does not add
140
+ * up, a message the protocol does not allow at that point (COPY among them), an
141
+ * encoding other than UTF-8, and a `DateStyle` other than ISO or a `TimeZone`
142
+ * other than UTC (at startup or after a `SET`), each fail the connection with
143
+ * their own `failure` code. The constructor panics on a cap out of range, as on
144
+ * a missing user or a short nonce.
130
145
  *
131
146
  * **Pools.** `PgPool` holds up to `size` connections to one server and a FIFO
132
147
  * queue of up to `queueSize` requests, still sans-IO: `wanted()` names a slot
133
148
  * that needs a socket, `connect(slot, nonce)` starts its connection, and the
134
- * program moves its bytes as above through `connection(slot)`. A request is a
135
- * ticket from `request()`; `dispatch()` gives the oldest to the ready
136
- * connection with the fewest groups in flight (or, with `PgConfig.pack`, to the
137
- * first ready one with room, so a burst fills few connections in fuller
138
- * writes), the program builds its group and ends it with `send()`, and `next(slot)` reads that connection's events with
139
- * `ticket` naming the request. Statements given to `register` are prepared on
140
- * each connection ahead of its first request. A connection that fails reports
141
- * `PG_LOST` for each request it took, then `PG_FAILED`; the program closes the
142
- * socket and the slot is built again on its next use.
149
+ * program moves its bytes as above through `connection(slot)`.
150
+ *
151
+ * A request is a ticket from `request()`; `dispatch()` gives the oldest to the
152
+ * ready connection with the fewest groups in flight (or, with `PgConfig.pack`,
153
+ * to the first ready one with room, so a burst fills few connections in fuller
154
+ * writes), the program builds its group and ends it with `send()`, and
155
+ * `next(slot)` reads that connection's events with `ticket` naming the request.
156
+ * Statements given to `register` are prepared on each connection ahead of its
157
+ * first request. A connection that fails reports `PG_LOST` for each request it
158
+ * took, then `PG_FAILED`; the program closes the socket and the slot is built
159
+ * again on its next use.
143
160
  *
144
161
  * **Carrier.** `PgCarrier`, in `nish/net/postgres-carrier`, moves a pool's
145
162
  * bytes on an `HttpHandler`'s loop, so a route handler queries without
@@ -148,23 +165,25 @@
148
165
  *
149
166
  * **Batching.** `PgBatcher` turns many reads of one row shape by key — a user
150
167
  * by id, an article by slug — into one execution of a statement over
151
- * `unnest($1) with ordinality`. `addInt` or `addText` queues a request's key
152
- * and tag; `take(conn)` binds the oldest waiting, each distinct key once (past
153
- * `PG_BATCH_PROBES` slots of its table probe, a key is bound again), up
154
- * to `maxRequests` and `maxBytes`, and answers a run's handle; `row`, `end`
155
- * and `fail` take that execution's events (a handle already answered makes
156
- * them a no-op counted in `stray`, so a server's late event cannot panic),
157
- * routing each row by its ordinal (checked first: a server's ordinal is
158
- * refused before it routes anything), and `next(run)` answers
159
- * `PG_BATCH_ROW`, then `PG_BATCH_DONE`, `PG_BATCH_MISSING` or
160
- * `PG_BATCH_FAILED`, for each request. The statement orders its rows by
161
- * ordinal, so a key's last events come as soon as a later key's row does;
162
- * with `sorted` false it does not (no Sort node, when `orderBy` is ""), rows
163
- * are answered in whatever order they come, and every last event waits for
164
- * the execution's end. It reads no clock, and the batcher
165
- * itself allocates only in its constructor (the connection's output buffer a
166
- * take writes into may still grow, up to its `maxOutput`); when to take is
167
- * the program's.
168
+ * `unnest($1) with ordinality`.
169
+ *
170
+ * `addInt` or `addText` queues a request's key and tag; `take(conn)` binds the
171
+ * oldest waiting, each distinct key once (past `PG_BATCH_PROBES` slots of its
172
+ * table probe, a key is bound again), up to `maxRequests` and `maxBytes`, and
173
+ * answers a run's handle; `row`, `end` and `fail` take that execution's events
174
+ * (a handle already answered makes them a no-op counted in `stray`, so a
175
+ * server's late event cannot panic), routing each row by its ordinal (checked
176
+ * first: a server's ordinal is refused before it routes anything), and
177
+ * `next(run)` answers `PG_BATCH_ROW`, then `PG_BATCH_DONE`, `PG_BATCH_MISSING`
178
+ * or `PG_BATCH_FAILED`, for each request.
179
+ *
180
+ * The statement orders its rows by ordinal, so a key's last events come as soon
181
+ * as a later key's row does; with `sorted` false it does not (no Sort node,
182
+ * when `orderBy` is ""), rows are answered in whatever order they come, and
183
+ * every last event waits for the execution's end. It reads no clock, and the
184
+ * batcher itself allocates only in its constructor (the connection's output
185
+ * buffer a take writes into may still grow, up to its `maxOutput`); when to
186
+ * take is the program's.
168
187
  *
169
188
  * **Batch timing.** `PgBatchClock` is one answer to when: given the time in
170
189
  * microseconds, `check(now, inFlight)` says a batch is due once
@@ -334,7 +353,11 @@ export class PgConfig {
334
353
 
335
354
  /** A server's ErrorResponse or NoticeResponse: the fields a program acts on. */
336
355
  export class PgError {
337
- /** ERROR, FATAL or PANIC; WARNING, NOTICE, DEBUG, INFO or LOG for a notice. Never localised. */
356
+ /**
357
+ * ERROR, FATAL or PANIC; WARNING, NOTICE, DEBUG, INFO or LOG for a notice.
358
+ * Never localised, unless the server sent no `V` field (before 9.6) and the
359
+ * localised `S` field stands in for it.
360
+ */
338
361
  readonly severity: string
339
362
  /** The SQLSTATE, five characters: `23505` is a unique violation. */
340
363
  readonly code: string
@@ -349,6 +372,19 @@ export class PgError {
349
372
  /** The 1-based character position in the statement's text, or "". */
350
373
  readonly position: string
351
374
 
375
+ /**
376
+ * Builds the record from the fields of one ErrorResponse or
377
+ * NoticeResponse; a program reads it from `lastError` or `lastNotice`
378
+ * rather than building one.
379
+ * @param severity The `V` field, never localised; the `S` field, which may be
380
+ * localised, when the server sent no `V` (servers before 9.6).
381
+ * @param code The SQLSTATE, the `C` field.
382
+ * @param message The primary message, the `M` field.
383
+ * @param detail The `D` field, or "" when the server sent none.
384
+ * @param hint The `H` field, or "".
385
+ * @param constraint The `n` field, or "".
386
+ * @param position The `P` field, a 1-based character position as text, or "".
387
+ */
352
388
  constructor(
353
389
  severity: string,
354
390
  code: string,
@@ -390,19 +426,25 @@ const pgAllZero = (bytes: u8[]): boolean => {
390
426
  * The holder outlives the wipe, so that `wiped()` reads the very bytes.
391
427
  */
392
428
  class PgPassword {
429
+ /** @internal Used by `PgConnection.scramContinue` and `PgPool.connect` in this module. */
393
430
  readonly bytes: Secret<u8[]>
394
- /** Whether `wipe()` has run; the bytes are no longer a password. */
431
+ /**
432
+ * Whether `wipe()` has run; the bytes are no longer a password.
433
+ * @internal Used by `PgConnection.dispose`, `PgConnection.scramContinue`, `PgPool.connect` and `PgPool.dispose` in this module.
434
+ */
395
435
  gone: boolean = false
396
436
 
397
437
  constructor(password: Secret<u8[]>) {
398
438
  this.bytes = secret(expose(password, pgCopyBytes))
399
439
  }
400
440
 
441
+ /** @internal Used by `PgConnection.dispose` and `PgPool.dispose` in this module. */
401
442
  wipe(): void {
402
443
  wipe(this.bytes)
403
444
  this.gone = true
404
445
  }
405
446
 
447
+ /** @internal Used by `PgConnection.passwordWiped` and `PgPool.passwordWiped` in this module. */
406
448
  wiped(): boolean {
407
449
  return expose(this.bytes, pgAllZero)
408
450
  }
@@ -669,7 +711,15 @@ export class PgText {
669
711
  this.failed = false
670
712
  }
671
713
 
672
- /** An `int2`, `int4` or `int8` column: an optional `-` and 1 to 19 digits; 0 and `failed` otherwise, and on overflow. */
714
+ /**
715
+ * An `int2`, `int4` or `int8` column: an optional `-` and its digits, in
716
+ * place. Leading zeros are allowed; a value outside `i64` is an overflow.
717
+ * @param b The buffer the column lies in, usually `conn.inputBuffer()`.
718
+ * @param start The column's first byte, as `colStart(c)` gives it.
719
+ * @param length The column's length in bytes; NULL's -1 is refused.
720
+ * @returns The value, or 0 with `failed` set for an empty or out-of-range
721
+ * window, a byte that is not a digit, or an overflow.
722
+ */
673
723
  int(b: u8[], start: i32, length: i32): i64 {
674
724
  const end: i32 = start + length
675
725
  if (length <= 0 || start < 0 || end < start || end > toI32(b.length)) {
@@ -707,7 +757,13 @@ export class PgText {
707
757
  return negative ? acc : -acc
708
758
  }
709
759
 
710
- /** A `bool` column: `t` or `f`; false and `failed` otherwise. */
760
+ /**
761
+ * A `bool` column: `t` or `f`, in place.
762
+ * @param b The buffer the column lies in.
763
+ * @param start The column's first byte.
764
+ * @param length The column's length in bytes; anything but 1 is refused.
765
+ * @returns True for `t`, false for `f`; false with `failed` set otherwise.
766
+ */
711
767
  bool(b: u8[], start: i32, length: i32): boolean {
712
768
  if (length === 1 && start >= 0 && start < toI32(b.length)) {
713
769
  const c: i32 = toI32(b[start])
@@ -728,7 +784,14 @@ export class PgText {
728
784
  * `timestamp` column (the same without `+00`), written to `out[at, at + 24)`
729
785
  * as `2024-01-02T03:04:05.123Z`, the fraction cut to milliseconds. Answers
730
786
  * 24, or -1 and `failed` for anything else: a year outside 0001–9999, BC,
731
- * `infinity`, an offset other than `+00`.
787
+ * `infinity`, an offset other than `+00`. Nothing is allocated.
788
+ * @param b The buffer the column lies in.
789
+ * @param start The column's first byte.
790
+ * @param length The column's length in bytes, at least 19.
791
+ * @param out The buffer to write the 24 ISO 8601 bytes into; the caller owns it.
792
+ * @param at Where in `out` the time starts; `out` needs 24 bytes from there.
793
+ * @returns 24, the bytes written; -1 with `failed` set, and `out` untouched,
794
+ * for a column it does not read or no room in `out`.
732
795
  */
733
796
  timestamp(b: u8[], start: i32, length: i32, out: u8[], at: i32): i32 {
734
797
  if (
@@ -854,6 +917,10 @@ export class PgBinary {
854
917
  * bytes, big-endian two's complement); 0 and `failed` for any other length,
855
918
  * NULL's -1 among them. A `timestamptz` or `timestamp` reads as an `int8`:
856
919
  * microseconds since 2000-01-01 00:00:00 UTC, which `iso` writes out.
920
+ * @param b The buffer the column lies in, usually `conn.inputBuffer()`.
921
+ * @param start The column's first byte, as `colStart(c)` gives it.
922
+ * @param length The column's length in bytes: 2, 4 or 8.
923
+ * @returns The value, sign-extended to 64 bits, or 0 with `failed` set.
857
924
  */
858
925
  int(b: u8[], start: i32, length: i32): i64 {
859
926
  if ((length !== 2 && length !== 4 && length !== 8) || !this.inside(b, start, length)) {
@@ -870,7 +937,13 @@ export class PgBinary {
870
937
  return toI64(v >= 32768 ? v - 65536 : v)
871
938
  }
872
939
 
873
- /** A `bool` column: one byte, 1 or 0; false and `failed` otherwise. */
940
+ /**
941
+ * A `bool` column: one byte, 1 or 0.
942
+ * @param b The buffer the column lies in.
943
+ * @param start The column's first byte.
944
+ * @param length The column's length in bytes; anything but 1 is refused.
945
+ * @returns True for 1, false for 0; false with `failed` set otherwise.
946
+ */
874
947
  bool(b: u8[], start: i32, length: i32): boolean {
875
948
  if (length === 1 && this.inside(b, start, length)) {
876
949
  const c: i32 = toI32(b[start])
@@ -885,7 +958,15 @@ export class PgBinary {
885
958
  return false
886
959
  }
887
960
 
888
- /** A `float8` column: eight bytes, IEEE 754 big-endian; 0 and `failed` otherwise. */
961
+ /**
962
+ * A `float8` column: eight bytes, IEEE 754 big-endian. A `float4` (four
963
+ * bytes) is refused.
964
+ * @param b The buffer the column lies in.
965
+ * @param start The column's first byte.
966
+ * @param length The column's length in bytes; anything but 8 is refused.
967
+ * @returns The value, NaN and the infinities included; 0 with `failed` set
968
+ * for a column that is not eight bytes inside `b`.
969
+ */
889
970
  float(b: u8[], start: i32, length: i32): f64 {
890
971
  if (length !== 8 || !this.inside(b, start, length)) {
891
972
  this.failed = true
@@ -898,6 +979,12 @@ export class PgBinary {
898
979
  * A `timestamptz` or `timestamp` column, written to `out[at, at + 24)` as
899
980
  * `iso` writes it. Answers 24, or -1 and `failed` for a column that is not
900
981
  * eight bytes or a time `iso` refuses.
982
+ * @param b The buffer the column lies in.
983
+ * @param start The column's first byte.
984
+ * @param length The column's length in bytes; anything but 8 is refused.
985
+ * @param out The buffer to write the 24 ISO 8601 bytes into; the caller owns it.
986
+ * @param at Where in `out` the time starts; `out` needs 24 bytes from there.
987
+ * @returns 24, the bytes written, or -1 with `failed` set.
901
988
  */
902
989
  timestamp(b: u8[], start: i32, length: i32, out: u8[], at: i32): i32 {
903
990
  if (length !== 8 || !this.inside(b, start, length)) {
@@ -913,6 +1000,11 @@ export class PgBinary {
913
1000
  * not rounded, to milliseconds, as `PgText.timestamp` cuts the same time.
914
1001
  * Answers 24, or -1 and `failed` with `out` untouched for a year outside
915
1002
  * 0001–9999 (`infinity` and `-infinity` among them) or no room in `out`.
1003
+ * Nothing is allocated.
1004
+ * @param micros Microseconds since 2000-01-01 00:00:00 UTC; negative is before 2000.
1005
+ * @param out The buffer to write into; the caller owns it.
1006
+ * @param at Where in `out` the time starts; `out` needs 24 bytes from there.
1007
+ * @returns 24, the bytes written, or -1 with `failed` set.
916
1008
  */
917
1009
  iso(micros: i64, out: u8[], at: i32): i32 {
918
1010
  if (at < 0 || at > toI32(out.length) - 24) {
@@ -963,16 +1055,17 @@ export class PgBinary {
963
1055
 
964
1056
  /**
965
1057
  * A walk over a one-dimensional `int2[]`, `int4[]` or `int8[]` column in
966
- * PostgreSQL's binary array layout, in place: `begin` the column, then
967
- * `next()` until `PG_ARRAY_END` or `PG_ARRAY_BAD`, and `int()` decodes the
968
- * current element through `binary`. The header is `ndim`, `hasnull` and the
969
- * element OID, then for `ndim` 1 the dimension's length and lower bound (the
970
- * bound is read and not used); each element is a length word and its bytes,
971
- * and a NULL is a length of -1 with no bytes. `ndim` 0 is the empty array.
972
- * Every refusal sets `binary.failed`: an `ndim` above 1, another element
973
- * type, an element whose length is not its type's size, a NULL when
974
- * `hasnull` is 0, a column cut short, or bytes after the last element. The
975
- * walk allocates nothing, and it reads nothing outside the column.
1058
+ * PostgreSQL's binary array layout, in place: `begin` the column, then `next()`
1059
+ * until `PG_ARRAY_END` or `PG_ARRAY_BAD`, and `int()` decodes the current
1060
+ * element through `binary`. The header is `ndim`, `hasnull` and the element
1061
+ * OID, then for `ndim` 1 the dimension's length and lower bound (the bound is
1062
+ * read and not used); each element is a length word and its bytes, and a NULL
1063
+ * is a length of -1 with no bytes. `ndim` 0 is the empty array.
1064
+ *
1065
+ * Every refusal sets `binary.failed`: an `ndim` above 1, another element type,
1066
+ * an element whose length is not its type's size, a NULL when `hasnull` is 0, a
1067
+ * column cut short, or bytes after the last element. The walk allocates
1068
+ * nothing, and it reads nothing outside the column.
976
1069
  */
977
1070
  export class PgBinaryArray {
978
1071
  /** The number of elements the header gives: 0 for an empty array. */
@@ -980,9 +1073,9 @@ export class PgBinaryArray {
980
1073
  /** The element type's OID, 20, 21 or 23, once `begin` has read a header it accepts. */
981
1074
  elementOid: i32 = 0
982
1075
  /** The current element's first byte in the buffer. */
983
- start: i32 = 0
1076
+ private start: i32 = 0
984
1077
  /** The current element's length: its type's size, or 0 for a NULL. */
985
- length: i32 = 0
1078
+ private length: i32 = 0
986
1079
  private binary: PgBinary
987
1080
  private b: u8[]
988
1081
  private pos: i32 = 0
@@ -992,12 +1085,26 @@ export class PgBinaryArray {
992
1085
  private hasNull: boolean = false
993
1086
  private bad: boolean = true
994
1087
 
1088
+ /**
1089
+ * A walker with nothing begun; `next()` answers `PG_ARRAY_BAD` until `begin`.
1090
+ * @param binary The decoders `int()` reads through and whose `failed` every
1091
+ * refusal sets; usually `conn.binary`.
1092
+ */
995
1093
  constructor(binary: PgBinary) {
996
1094
  this.binary = binary
997
1095
  this.b = []
998
1096
  }
999
1097
 
1000
- /** Starts a walk over `b[start, start + length)`; a header this walker does not read is refused. */
1098
+ /**
1099
+ * Starts a walk over `b[start, start + length)`, reading its header; a
1100
+ * header this walker does not read is refused, which sets `binary.failed`
1101
+ * and makes `next()` answer `PG_ARRAY_BAD`. The walker keeps `b` and reads
1102
+ * it until the next `begin`, so the window must stay valid that long: for a
1103
+ * column, until the connection's next `next()`.
1104
+ * @param b The buffer the column lies in, usually `conn.inputBuffer()`.
1105
+ * @param start The column's first byte, as `colStart(c)` gives it.
1106
+ * @param length The column's length in bytes; NULL's -1 is refused.
1107
+ */
1001
1108
  begin(b: u8[], start: i32, length: i32): void {
1002
1109
  this.b = b
1003
1110
  this.count = 0
@@ -1050,7 +1157,13 @@ export class PgBinaryArray {
1050
1157
  return PG_ARRAY_BAD
1051
1158
  }
1052
1159
 
1053
- /** The next element: `PG_ARRAY_ELEMENT`, `PG_ARRAY_NULL`, `PG_ARRAY_END` or `PG_ARRAY_BAD`. */
1160
+ /**
1161
+ * Steps to the next element, which `int()` then reads.
1162
+ * @returns `PG_ARRAY_ELEMENT`, `PG_ARRAY_NULL`, `PG_ARRAY_END` once all
1163
+ * `count` elements have been read and the column ends there, or
1164
+ * `PG_ARRAY_BAD` (with `binary.failed` set) for a layout it refuses; a
1165
+ * refused walk answers `PG_ARRAY_BAD` from then on.
1166
+ */
1054
1167
  next(): i32 {
1055
1168
  if (this.bad) {
1056
1169
  return PG_ARRAY_BAD
@@ -1084,7 +1197,13 @@ export class PgBinaryArray {
1084
1197
  return PG_ARRAY_ELEMENT
1085
1198
  }
1086
1199
 
1087
- /** The current element as an integer, through `PgBinary.int`; a NULL, or a walk that was refused, sets `binary.failed`. */
1200
+ /**
1201
+ * The current element as an integer, through `PgBinary.int`; a NULL, or a
1202
+ * walk that was refused, sets `binary.failed`.
1203
+ * @returns The element, sign-extended to 64 bits, or 0 when this call is
1204
+ * refused, which sets `binary.failed`. The flag is sticky and shared, so
1205
+ * an earlier refusal leaves it set without making this call answer 0.
1206
+ */
1088
1207
  int(): i64 {
1089
1208
  if (this.bad) {
1090
1209
  this.binary.failed = true
@@ -1095,7 +1214,7 @@ export class PgBinaryArray {
1095
1214
  }
1096
1215
 
1097
1216
  /**
1098
- * A walk over a one-dimensional `text[]` column in place: `start` the
1217
+ * A walk over a one-dimensional `text[]` column in place: `begin` the
1099
1218
  * column, then `next()` until `PG_ARRAY_END` or `PG_ARRAY_BAD`. Each element
1100
1219
  * is the window `[start, start + length)` of the column's buffer; a quoted
1101
1220
  * element with a backslash escape in it has `escaped` set, and `copy` writes
@@ -1115,11 +1234,20 @@ export class PgArrayWalker {
1115
1234
  private bad: boolean = false
1116
1235
  private b: u8[]
1117
1236
 
1237
+ /** A walker with nothing begun; `next()` answers `PG_ARRAY_END` until `begin`. */
1118
1238
  constructor() {
1119
1239
  this.b = []
1120
1240
  }
1121
1241
 
1122
- /** Starts a walk over `b[start, start + length)`. */
1242
+ /**
1243
+ * Starts a walk over `b[start, start + length)`, which must be a `{...}`
1244
+ * literal; anything else makes `next()` answer `PG_ARRAY_BAD`. The walker
1245
+ * keeps `b` and reads it until the next `begin`, so for a column the walk
1246
+ * must end before the connection's next `next()`.
1247
+ * @param b The buffer the column lies in, usually `conn.inputBuffer()`.
1248
+ * @param start The column's first byte, as `colStart(c)` gives it.
1249
+ * @param length The column's length in bytes, braces included.
1250
+ */
1123
1251
  begin(b: u8[], start: i32, length: i32): void {
1124
1252
  this.b = b
1125
1253
  this.first = true
@@ -1136,7 +1264,12 @@ export class PgArrayWalker {
1136
1264
  return PG_ARRAY_BAD
1137
1265
  }
1138
1266
 
1139
- /** The next element: `PG_ARRAY_ELEMENT`, `PG_ARRAY_NULL`, `PG_ARRAY_END` or `PG_ARRAY_BAD`. */
1267
+ /**
1268
+ * Steps to the next element, setting `start`, `length` and `escaped`.
1269
+ * @returns `PG_ARRAY_ELEMENT`, `PG_ARRAY_NULL`, `PG_ARRAY_END` or
1270
+ * `PG_ARRAY_BAD`; once `PG_ARRAY_BAD`, the walk answers it until the next
1271
+ * `begin`.
1272
+ */
1140
1273
  next(): i32 {
1141
1274
  if (this.bad) {
1142
1275
  return PG_ARRAY_BAD
@@ -1210,7 +1343,14 @@ export class PgArrayWalker {
1210
1343
  return PG_ARRAY_ELEMENT
1211
1344
  }
1212
1345
 
1213
- /** Writes the current element, unescaped, to `out[at, ...)`; answers its length, or -1 when it does not fit. */
1346
+ /**
1347
+ * Writes the current element, unescaped (each backslash dropped and the
1348
+ * byte after it kept), to `out[at, ...)`. Nothing is allocated.
1349
+ * @param out The buffer to write into; the caller owns it.
1350
+ * @param at Where in `out` the element starts.
1351
+ * @returns The bytes written, at most `length`; -1 when it does not fit,
1352
+ * in which case `out` may hold part of it.
1353
+ */
1214
1354
  copy(out: u8[], at: i32): i32 {
1215
1355
  const b: u8[] = this.b
1216
1356
  let n: i32 = 0
@@ -1307,7 +1447,14 @@ export class PgConnection {
1307
1447
  * A connection that has queued its startup message. `password` is copied,
1308
1448
  * so the caller may wipe its own; `nonce` must be at least 18 bytes from a
1309
1449
  * cryptographic random source (`crypto.getRandomValues`), and is fixed only
1310
- * in a test.
1450
+ * in a test. Panics on a `PgConfig` that is a mistake (no user, a cap out
1451
+ * of range, a NUL in a startup parameter) or a nonce shorter than 18 bytes.
1452
+ * @param config The caps and startup parameters; kept, and read for the
1453
+ * connection's life, so do not change it afterwards.
1454
+ * @param password The role's password as UTF-8 bytes, without SASLprep;
1455
+ * copied into a holder the connection wipes once the SCRAM proof is
1456
+ * computed, or when it fails or is disposed. It may be empty for `trust`.
1457
+ * @param nonce The client nonce: its first 18 bytes are used, base64-encoded.
1311
1458
  */
1312
1459
  constructor(config: PgConfig, password: Secret<u8[]>, nonce: u8[]) {
1313
1460
  if (toI32(nonce.length) < PG_NONCE_BYTES) {
@@ -1354,22 +1501,38 @@ export class PgConnection {
1354
1501
 
1355
1502
  // --- Buffers -----------------------------------------------------------------
1356
1503
 
1357
- /** The input buffer: read from the socket into it at `inputEnd()`. */
1504
+ /**
1505
+ * The input buffer: read from the socket into it at `inputEnd()`. The
1506
+ * connection owns it, and `next()` may replace it with a larger one, so
1507
+ * fetch it again after every `next()`.
1508
+ * @returns The buffer itself, not a copy.
1509
+ */
1358
1510
  inputBuffer(): u8[] {
1359
1511
  return this.input
1360
1512
  }
1361
1513
 
1362
- /** Where the next byte read goes. */
1514
+ /**
1515
+ * Where the next byte read goes.
1516
+ * @returns An index into `inputBuffer()`.
1517
+ */
1363
1518
  inputEnd(): i32 {
1364
1519
  return this.inEnd
1365
1520
  }
1366
1521
 
1367
- /** How many bytes may be read into the input buffer now. */
1522
+ /**
1523
+ * How many bytes may be read into the input buffer now.
1524
+ * @returns The bytes free from `inputEnd()` to the buffer's end; 0 when it
1525
+ * is full, which `next()` mends by compacting or growing it.
1526
+ */
1368
1527
  inputRoom(): i32 {
1369
1528
  return toI32(this.input.length) - this.inEnd
1370
1529
  }
1371
1530
 
1372
- /** Records that `n` bytes were read into the input buffer at `inputEnd()`. */
1531
+ /**
1532
+ * Records that `n` bytes were read into the input buffer at `inputEnd()`.
1533
+ * Panics on a negative `n` or one past `inputRoom()`.
1534
+ * @param n The bytes the read wrote, from 0 to `inputRoom()`.
1535
+ */
1373
1536
  received(n: i32): void {
1374
1537
  if (n < 0 || n > this.inputRoom()) {
1375
1538
  panic("nish/net/postgres: received more than inputRoom()")
@@ -1377,7 +1540,16 @@ export class PgConnection {
1377
1540
  this.inEnd += n
1378
1541
  }
1379
1542
 
1380
- /** Copies what fits of `src[start, start + length)` into the input buffer; answers how much. */
1543
+ /**
1544
+ * Copies what fits of `src[start, start + length)` into the input buffer at
1545
+ * `inputEnd()`, for a program whose bytes arrive in a buffer of its own.
1546
+ * Panics on a window outside `src`.
1547
+ * @param src The bytes to take; the caller keeps them.
1548
+ * @param start The window's first byte in `src`.
1549
+ * @param length The window's length in bytes.
1550
+ * @returns The bytes copied, at most `inputRoom()`; the rest are the
1551
+ * caller's to give again after `next()`.
1552
+ */
1381
1553
  receive(src: u8[], start: i32, length: i32): i32 {
1382
1554
  if (start < 0 || length < 0 || length > toI32(src.length) - start) {
1383
1555
  panic("nish/net/postgres: receive() outside its source")
@@ -1389,22 +1561,39 @@ export class PgConnection {
1389
1561
  return n
1390
1562
  }
1391
1563
 
1392
- /** The output buffer: write `[outputStart(), outputEnd())` to the socket. */
1564
+ /**
1565
+ * The output buffer: write `[outputStart(), outputEnd())` to the socket.
1566
+ * The connection owns it, and a builder call or `sent` may grow or compact
1567
+ * it, so fetch it again after each.
1568
+ * @returns The buffer itself, not a copy.
1569
+ */
1393
1570
  outputBuffer(): u8[] {
1394
1571
  return this.out
1395
1572
  }
1396
1573
 
1397
- /** The first byte not yet sent. */
1574
+ /**
1575
+ * The first byte not yet sent.
1576
+ * @returns An index into `outputBuffer()`.
1577
+ */
1398
1578
  outputStart(): i32 {
1399
1579
  return this.outStart
1400
1580
  }
1401
1581
 
1402
- /** One past the last byte that may be sent: a Bind still open is held back until `bindEnd()` has written its lengths. */
1582
+ /**
1583
+ * One past the last byte that may be sent: a Bind still open is held back
1584
+ * until `bindEnd()` has written its lengths.
1585
+ * @returns An index into `outputBuffer()`; equal to `outputStart()` when
1586
+ * there is nothing to send.
1587
+ */
1403
1588
  outputEnd(): i32 {
1404
1589
  return this.bindAt >= 0 ? this.bindAt : this.outEnd
1405
1590
  }
1406
1591
 
1407
- /** Records that `n` bytes from `outputStart()` were written to the socket. */
1592
+ /**
1593
+ * Records that `n` bytes from `outputStart()` were written to the socket.
1594
+ * Panics on a negative `n` or one past `outputEnd() - outputStart()`.
1595
+ * @param n The bytes the write took.
1596
+ */
1408
1597
  sent(n: i32): void {
1409
1598
  if (n < 0 || n > this.outputEnd() - this.outStart) {
1410
1599
  panic("nish/net/postgres: sent more than was queued")
@@ -1418,7 +1607,12 @@ export class PgConnection {
1418
1607
  }
1419
1608
  }
1420
1609
 
1421
- /** Reports the end of the stream: unless it already has, the connection fails with `PG_ERR_CLOSED`. */
1610
+ /**
1611
+ * Reports the end of the stream (a read of 0 bytes, or a socket error):
1612
+ * unless it already has, the connection fails with `PG_ERR_CLOSED`, which
1613
+ * wipes the password. Input already received and not yet read is dropped.
1614
+ * @returns `PG_FAILED`, as every later `next()` does.
1615
+ */
1422
1616
  closed(): i32 {
1423
1617
  if (this.state !== PG_STATE_FAILED) {
1424
1618
  return this.fail(PG_ERR_CLOSED)
@@ -1431,12 +1625,17 @@ export class PgConnection {
1431
1625
  * once the proof is computed, the connection has failed or `dispose()` has
1432
1626
  * run (and for an empty password). It reads the copy itself, so a test can
1433
1627
  * see the wipe happen; a program has no use for it.
1628
+ * @returns True when the copy holds only zero bytes.
1434
1629
  */
1435
1630
  passwordWiped(): boolean {
1436
1631
  return this.password.wiped()
1437
1632
  }
1438
1633
 
1439
- /** Wipes the password if the connection still holds it. A program that drops a connection before it is ready calls this. */
1634
+ /**
1635
+ * Wipes the password if the connection still holds it. A program that drops
1636
+ * a connection before it is ready calls this. It does not close anything or
1637
+ * queue a Terminate: that is `terminate()`, and the socket is the program's.
1638
+ */
1440
1639
  dispose(): void {
1441
1640
  if (!this.password.gone) {
1442
1641
  this.password.wipe()
@@ -1445,7 +1644,16 @@ export class PgConnection {
1445
1644
 
1446
1645
  // --- Reading -----------------------------------------------------------------
1447
1646
 
1448
- /** The next event from the input. */
1647
+ /**
1648
+ * Reads input until it has an event to answer. Each call may move the
1649
+ * unread input to the start of the buffer or replace the buffer, which ends
1650
+ * the windows the last event gave (`colStart`, the tag) and calls for a
1651
+ * fresh `inputBuffer()`.
1652
+ * @returns `PG_NEED_MORE` when it needs more input; `PG_READY`, `PG_ROW`,
1653
+ * `PG_COMPLETE`, `PG_ERROR`, `PG_GROUP_DONE`, `PG_NOTICE` or
1654
+ * `PG_DESCRIBED` (the module header says what each means); or `PG_FAILED`,
1655
+ * final, with `failure` saying why.
1656
+ */
1449
1657
  next(): i32 {
1450
1658
  while (true) {
1451
1659
  if (this.state === PG_STATE_FAILED) {
@@ -2106,7 +2314,12 @@ export class PgConnection {
2106
2314
  setI32BE(this.out, at + 1, this.outEnd - at - 1)
2107
2315
  }
2108
2316
 
2109
- /** Whether another group may start, or the open one take another message. */
2317
+ /**
2318
+ * Whether another group may start, or the open one take another message.
2319
+ * @returns True once the connection is ready (after `PG_READY`, until
2320
+ * `PG_FAILED`) and either a group is open or fewer than `maxInFlight`
2321
+ * wait for their answers. Room under `maxOutput` is not part of it.
2322
+ */
2110
2323
  canSend(): boolean {
2111
2324
  return this.state === PG_STATE_READY && (this.groupOpen || this.inFlight < this.config.maxInFlight)
2112
2325
  }
@@ -2128,8 +2341,16 @@ export class PgConnection {
2128
2341
  * unnamed one), its parameters' types given by `paramTypes` (OIDs, 0 to let
2129
2342
  * the server infer one, and parameters past the array are inferred too).
2130
2343
  * The server answers `PG_DESCRIBED`. False, and nothing written, when
2131
- * `canSend()` is false, a bind is open, `name` or `sql` holds a NUL, or the
2132
- * message would pass `maxOutput`.
2344
+ * `canSend()` is false, a bind is open, `name` or `sql` holds a NUL, more
2345
+ * than 65535 types are given, or the message would pass `maxOutput`. It
2346
+ * opens a group when none is open; `sync()` ends it.
2347
+ * @param name The statement's name; a named statement lasts until
2348
+ * `closeStatement` or the connection's end, the unnamed one until the next
2349
+ * `prepare("")`.
2350
+ * @param sql The statement's text, `$1`, `$2`, ... for its parameters.
2351
+ * @param paramTypes The parameters' type OIDs (23 `int4`, 20 `int8`, 25
2352
+ * `text`), or 0 for one the server infers; read, not kept.
2353
+ * @returns True when the Parse and Describe were queued.
2133
2354
  */
2134
2355
  prepare(name: string, sql: string, paramTypes: i32[]): boolean {
2135
2356
  const nameLength: i32 = toI32(name.length)
@@ -2156,7 +2377,13 @@ export class PgConnection {
2156
2377
  return true
2157
2378
  }
2158
2379
 
2159
- /** Close: forgets the prepared statement `name`. False as `prepare` is. */
2380
+ /**
2381
+ * Close: forgets the prepared statement `name` on the server. False, and
2382
+ * nothing written, as `prepare` is. It opens a group when none is open.
2383
+ * @param name The statement to close; closing one that does not exist is
2384
+ * not an error to the server.
2385
+ * @returns True when the Close was queued.
2386
+ */
2160
2387
  closeStatement(name: string): boolean {
2161
2388
  if (pgHasNul(name) || toI32(name.length) > PG_MAX_CAP || !this.canOpen(7 + toI32(name.length))) {
2162
2389
  return false
@@ -2170,7 +2397,12 @@ export class PgConnection {
2170
2397
 
2171
2398
  /**
2172
2399
  * Starts a Bind of the prepared statement `name`; its parameters follow, in
2173
- * order, then `bindEnd()`. False as `prepare` is.
2400
+ * order, then `bindEnd()`. False, and nothing written, as `prepare` is. It
2401
+ * opens a group when none is open. Until `bindEnd()` or `bindCancel()`,
2402
+ * `outputEnd()` holds the Bind's bytes back.
2403
+ * @param name A statement prepared on this connection, in this group or an
2404
+ * earlier one.
2405
+ * @returns True when the Bind was opened.
2174
2406
  */
2175
2407
  bindStart(name: string): boolean {
2176
2408
  return this.openBind(name, false)
@@ -2188,6 +2420,8 @@ export class PgConnection {
2188
2420
  * with this when its `binary` is set, and reads their routing ordinals with
2189
2421
  * `binaryInt`. Its `bindEnd()` writes two bytes more, kept free under
2190
2422
  * `maxOutput` from here on. False as `prepare` is.
2423
+ * @param name A statement prepared on this connection.
2424
+ * @returns True when the Bind was opened.
2191
2425
  */
2192
2426
  bindStartBinary(name: string): boolean {
2193
2427
  return this.openBind(name, true)
@@ -2271,7 +2505,12 @@ export class PgConnection {
2271
2505
  // open, the bind has 65535 parameters already, or the parameter would pass
2272
2506
  // `maxOutput`; a program that checked `bindStart()` meets only the last.
2273
2507
 
2274
- /** A text parameter. */
2508
+ /**
2509
+ * A text parameter: the string's bytes as they are. Panics while an array
2510
+ * parameter is open.
2511
+ * @param value The parameter's text; "" is an empty string, not NULL.
2512
+ * @returns True when it was written; false as every `param...` call is.
2513
+ */
2275
2514
  paramText(value: string): boolean {
2276
2515
  const at: i32 = this.startParam(toI32(value.length))
2277
2516
  if (at < 0) {
@@ -2282,7 +2521,16 @@ export class PgConnection {
2282
2521
  return true
2283
2522
  }
2284
2523
 
2285
- /** A text parameter from `bytes[start, start + length)`, UTF-8; false too when the window is not inside `bytes`. */
2524
+ /**
2525
+ * A text parameter from `bytes[start, start + length)`, UTF-8, copied into
2526
+ * the Bind so the caller may reuse `bytes` at once. Panics while an array
2527
+ * parameter is open.
2528
+ * @param bytes The buffer the text lies in.
2529
+ * @param start The text's first byte.
2530
+ * @param length The text's length in bytes.
2531
+ * @returns True when it was written; false as every `param...` call is, and
2532
+ * when the window is not inside `bytes`.
2533
+ */
2286
2534
  paramBytes(bytes: u8[], start: i32, length: i32): boolean {
2287
2535
  this.noArrayOpen()
2288
2536
  if (start < 0 || length < 0 || length > toI32(bytes.length) - start) {
@@ -2299,7 +2547,11 @@ export class PgConnection {
2299
2547
  return true
2300
2548
  }
2301
2549
 
2302
- /** A NULL parameter. */
2550
+ /**
2551
+ * A NULL parameter, of whatever type the statement gives it. Panics while
2552
+ * an array parameter is open.
2553
+ * @returns True when it was written; false as every `param...` call is.
2554
+ */
2303
2555
  paramNull(): boolean {
2304
2556
  if (this.startParam(toI32(0)) < 0) {
2305
2557
  return false
@@ -2308,7 +2560,14 @@ export class PgConnection {
2308
2560
  return true
2309
2561
  }
2310
2562
 
2311
- /** An integer parameter, in decimal. */
2563
+ /**
2564
+ * An integer parameter, in decimal text, which the server reads as the
2565
+ * statement's type (`int2`, `int4`, `int8`, `numeric`, ...). Panics while an
2566
+ * array parameter is open.
2567
+ * @param value The integer; one outside the parameter's type is the
2568
+ * server's error (22003) for that execution.
2569
+ * @returns True when it was written; false as every `param...` call is.
2570
+ */
2312
2571
  paramInt(value: i64): boolean {
2313
2572
  const at: i32 = this.startParam(toI32(20))
2314
2573
  if (at < 0) {
@@ -2327,8 +2586,14 @@ export class PgConnection {
2327
2586
  }
2328
2587
 
2329
2588
  /**
2330
- * An `int8[]` parameter from `values[start, start + count)`, in decimal;
2331
- * panics when the range is not inside `values`.
2589
+ * An `int8[]` parameter from `values[start, start + count)`, in decimal
2590
+ * text (`{1,2,3}`, or `{}` for none); panics when the range is not inside
2591
+ * `values`, or while an array parameter is open.
2592
+ * @param values The integers; read now, not kept.
2593
+ * @param start The first element of the window.
2594
+ * @param count The elements to send, 0 for an empty array.
2595
+ * @returns True when it was written; false, and nothing written, as every
2596
+ * `param...` call is.
2332
2597
  */
2333
2598
  paramIntArray(values: i64[], start: i32, count: i32): boolean {
2334
2599
  if (start < 0 || count < 0 || count > toI32(values.length) - start) {
@@ -2361,7 +2626,14 @@ export class PgConnection {
2361
2626
  return true
2362
2627
  }
2363
2628
 
2364
- /** A `text[]` parameter: every element quoted, `"` and `\` escaped. */
2629
+ /**
2630
+ * A `text[]` parameter: every element quoted, with each double quote and
2631
+ * backslash escaped by a backslash, so no element reads as NULL (build one
2632
+ * with `arrayNull` for that). Panics while an array parameter is open.
2633
+ * @param items The elements, in order; read now, not kept. Empty sends `{}`.
2634
+ * @returns True when it was written; false, and nothing written, as every
2635
+ * `param...` call is.
2636
+ */
2365
2637
  paramTextArray(items: string[]): boolean {
2366
2638
  // Its exact size first, so that room is asked for once and a refusal writes nothing.
2367
2639
  let size: i64 = 2
@@ -2415,7 +2687,12 @@ export class PgConnection {
2415
2687
  /**
2416
2688
  * An `int4[]` parameter in binary from `values[start, start + count)`;
2417
2689
  * false as the `param...` calls are. Panics, writing nothing, when the
2418
- * window is not inside `values` or an element is outside `int4`.
2690
+ * window is not inside `values` or an element is outside `int4`, and while
2691
+ * an array parameter is open.
2692
+ * @param values The integers, each within -2^31..2^31-1; read now, not kept.
2693
+ * @param start The first element of the window.
2694
+ * @param count The elements to send, 0 for an empty array.
2695
+ * @returns True when it was written.
2419
2696
  */
2420
2697
  paramInt4Array(values: i64[], start: i32, count: i32): boolean {
2421
2698
  pgIntWindow(values, start, count)
@@ -2431,7 +2708,11 @@ export class PgConnection {
2431
2708
  /**
2432
2709
  * An `int8[]` parameter in binary from `values[start, start + count)`;
2433
2710
  * false as the `param...` calls are. Panics when the window is not inside
2434
- * `values`.
2711
+ * `values`, and while an array parameter is open.
2712
+ * @param values The integers; read now, not kept.
2713
+ * @param start The first element of the window.
2714
+ * @param count The elements to send, 0 for an empty array.
2715
+ * @returns True when it was written.
2435
2716
  */
2436
2717
  paramInt8Array(values: i64[], start: i32, count: i32): boolean {
2437
2718
  pgIntWindow(values, start, count)
@@ -2485,7 +2766,13 @@ export class PgConnection {
2485
2766
  // with none open and a second `arrayStart()`; `sync()`, `prepare`,
2486
2767
  // `closeStatement` and `bindStart` answer false, the bind being open.
2487
2768
 
2488
- /** Opens an array parameter, `{}` so far; false as the `param...` calls are. */
2769
+ /**
2770
+ * Opens a text array parameter, `{}` so far, which `arrayElement`,
2771
+ * `arrayInt` and `arrayNull` fill and `arrayEnd()` closes. Panics while an
2772
+ * array is open.
2773
+ * @returns True when it was opened; false, and nothing written, as the
2774
+ * `param...` calls are.
2775
+ */
2489
2776
  arrayStart(): boolean {
2490
2777
  if (this.arrayAt >= 0) {
2491
2778
  panic("nish/net/postgres: arrayStart() while an array is open")
@@ -2519,7 +2806,12 @@ export class PgConnection {
2519
2806
  /**
2520
2807
  * A text element from `bytes[start, start + length)`, UTF-8, quoted with
2521
2808
  * `"` and `\` escaped; false, and nothing written, when there is no room.
2522
- * Panics when no array is open or the window is not inside `bytes`.
2809
+ * Panics when no text array is open or the window is not inside `bytes`.
2810
+ * @param bytes The buffer the element lies in; copied, so it may be reused at once.
2811
+ * @param start The element's first byte.
2812
+ * @param length The element's length in bytes; 0 is the empty string.
2813
+ * @returns True when it was written; false leaves the array open with the
2814
+ * elements it has.
2523
2815
  */
2524
2816
  arrayElement(bytes: u8[], start: i32, length: i32): boolean {
2525
2817
  this.arrayOpen()
@@ -2557,7 +2849,11 @@ export class PgConnection {
2557
2849
  return true
2558
2850
  }
2559
2851
 
2560
- /** A NULL element; false, and nothing written, when there is no room. Panics when no array is open. */
2852
+ /**
2853
+ * A NULL element of the open text array. Panics when no text array is open.
2854
+ * @returns True when it was written; false, and nothing written, when there
2855
+ * is no room.
2856
+ */
2561
2857
  arrayNull(): boolean {
2562
2858
  this.arrayOpen()
2563
2859
  if (!this.elementRoom(toI64(4))) {
@@ -2575,7 +2871,13 @@ export class PgConnection {
2575
2871
  this.arrayCount += 1
2576
2872
  }
2577
2873
 
2578
- /** An integer element, in decimal; false, and nothing written, when there is no room. Panics when no array is open. */
2874
+ /**
2875
+ * An integer element of the open text array, in decimal. Panics when no
2876
+ * text array is open.
2877
+ * @param value The element.
2878
+ * @returns True when it was written; false, and nothing written, when there
2879
+ * is no room.
2880
+ */
2579
2881
  arrayInt(value: i64): boolean {
2580
2882
  this.arrayOpen()
2581
2883
  if (!this.elementRoom(toI64(pgDecimalLength(value)))) {
@@ -2592,7 +2894,14 @@ export class PgConnection {
2592
2894
  // The text builder's rules hold, and a text element in a binary array, or a
2593
2895
  // binary element in a text one, panics.
2594
2896
 
2595
- /** Opens a binary array parameter of `elementOid`'s elements; false as the `param...` calls are. Panics on another OID, or while an array is open. */
2897
+ /**
2898
+ * Opens a binary array parameter of `elementOid`'s elements, which
2899
+ * `binaryArrayInt` and `binaryArrayNull` fill and `arrayEnd()` closes.
2900
+ * Panics on another OID, or while an array is open.
2901
+ * @param elementOid 23 for an `int4[]`, 20 for an `int8[]`.
2902
+ * @returns True when it was opened; false, and nothing written, as the
2903
+ * `param...` calls are.
2904
+ */
2596
2905
  binaryArrayStart(elementOid: i32): boolean {
2597
2906
  if (this.arrayAt >= 0) {
2598
2907
  panic("nish/net/postgres: binaryArrayStart() while an array is open")
@@ -2624,6 +2933,8 @@ export class PgConnection {
2624
2933
  * An integer element of the open binary array; false, and nothing written,
2625
2934
  * when there is no room. Panics when no binary array is open, or when it is
2626
2935
  * an `int4[]` and `value` is outside `int4`.
2936
+ * @param value The element: four bytes in an `int4[]`, eight in an `int8[]`.
2937
+ * @returns True when it was written.
2627
2938
  */
2628
2939
  binaryArrayInt(value: i64): boolean {
2629
2940
  this.binaryArrayOpen()
@@ -2646,7 +2957,12 @@ export class PgConnection {
2646
2957
  return true
2647
2958
  }
2648
2959
 
2649
- /** A NULL element of the open binary array, length -1; false, and nothing written, when there is no room. Panics when no binary array is open. */
2960
+ /**
2961
+ * A NULL element of the open binary array, length -1. Panics when no binary
2962
+ * array is open.
2963
+ * @returns True when it was written; false, and nothing written, when there
2964
+ * is no room.
2965
+ */
2650
2966
  binaryArrayNull(): boolean {
2651
2967
  this.binaryArrayOpen()
2652
2968
  if (!this.room(toI32(4))) {
@@ -2658,7 +2974,11 @@ export class PgConnection {
2658
2974
  return true
2659
2975
  }
2660
2976
 
2661
- /** Ends the open array parameter, text or binary; never refused for room, which its elements kept. Panics when no array is open. */
2977
+ /**
2978
+ * Ends the open array parameter, text or binary; never refused for room,
2979
+ * which its elements kept. An array with no elements is sent as the empty
2980
+ * array. Panics when no array is open.
2981
+ */
2662
2982
  arrayEnd(): void {
2663
2983
  if (this.arrayAt < 0) {
2664
2984
  panic("nish/net/postgres: arrayEnd() with no arrayStart()")
@@ -2686,7 +3006,9 @@ export class PgConnection {
2686
3006
  * Ends the Bind (every result column in text, or in binary after
2687
3007
  * `bindStartBinary`) and queues its Execute, for every row. False, and
2688
3008
  * nothing written, when no bind is open; never for room, which the calls
2689
- * before it kept.
3009
+ * before it kept. Panics while an array parameter is open. The Bind's bytes
3010
+ * count toward `outputEnd()` from here on.
3011
+ * @returns True when the Bind and Execute were queued.
2690
3012
  */
2691
3013
  bindEnd(): boolean {
2692
3014
  if (this.bindAt < 0) {
@@ -2723,6 +3045,7 @@ export class PgConnection {
2723
3045
  * Drops the open bind, and the array open in it, unsent, so that a program
2724
3046
  * whose parameter was refused for room can send the group without it; a
2725
3047
  * group the bind opened is closed again. False when no bind is open.
3048
+ * @returns True when an open bind was dropped.
2726
3049
  */
2727
3050
  bindCancel(): boolean {
2728
3051
  if (this.bindAt < 0) {
@@ -2766,7 +3089,12 @@ export class PgConnection {
2766
3089
  this.paramCountAt = from + codes
2767
3090
  }
2768
3091
 
2769
- /** Sync: ends the open group, which the server answers with `PG_GROUP_DONE`. False when no group is open or a bind is; never for room. */
3092
+ /**
3093
+ * Sync: ends the open group, which the server answers with
3094
+ * `PG_GROUP_DONE`; the group stays in `inFlight` until then.
3095
+ * @returns True when the Sync was queued; false when no group is open or a
3096
+ * bind is; never for room.
3097
+ */
2770
3098
  sync(): boolean {
2771
3099
  if (!this.groupOpen || this.bindAt >= 0) {
2772
3100
  return false
@@ -2778,7 +3106,11 @@ export class PgConnection {
2778
3106
  return true
2779
3107
  }
2780
3108
 
2781
- /** Terminate: tells the server the connection is ending; close the socket once it is sent. A bind still open is dropped unsent. */
3109
+ /**
3110
+ * Terminate: tells the server the connection is ending; close the socket
3111
+ * once it is sent. A bind still open is dropped unsent. It is queued in any
3112
+ * state, and is never refused for room.
3113
+ */
2782
3114
  terminate(): void {
2783
3115
  if (this.bindAt >= 0) {
2784
3116
  this.dropBind()
@@ -2790,22 +3122,39 @@ export class PgConnection {
2790
3122
 
2791
3123
  // --- Results -----------------------------------------------------------------
2792
3124
 
2793
- /** Column `c`'s first byte in `inputBuffer()`. */
3125
+ /**
3126
+ * Column `c`'s first byte in `inputBuffer()`, valid until the next `next()`.
3127
+ * @param c The column, 0 to `columns - 1`.
3128
+ * @returns An index into `inputBuffer()`.
3129
+ */
2794
3130
  colStart(c: i32): i32 {
2795
3131
  return this.colStarts[c]
2796
3132
  }
2797
3133
 
2798
- /** Column `c`'s length, -1 for NULL. */
3134
+ /**
3135
+ * Column `c`'s length.
3136
+ * @param c The column, 0 to `columns - 1`.
3137
+ * @returns The length in bytes, or -1 for NULL.
3138
+ */
2799
3139
  colLength(c: i32): i32 {
2800
3140
  return this.colLengths[c]
2801
3141
  }
2802
3142
 
2803
- /** Whether column `c` is NULL. */
3143
+ /**
3144
+ * Whether column `c` of the current row is NULL.
3145
+ * @param c The column, 0 to `columns - 1`.
3146
+ * @returns True when the column is NULL.
3147
+ */
2804
3148
  isNull(c: i32): boolean {
2805
3149
  return this.colLengths[c] < 0
2806
3150
  }
2807
3151
 
2808
- /** Column `c` as a string; the one result read that allocates. "" for NULL. */
3152
+ /**
3153
+ * Column `c` as a string; the one result read that allocates, and the string
3154
+ * outlives the row.
3155
+ * @param c The column, 0 to `columns - 1`.
3156
+ * @returns The column's bytes as a string; "" for NULL and for an empty value.
3157
+ */
2809
3158
  columnText(c: i32): string {
2810
3159
  const length: i32 = this.colLengths[c]
2811
3160
  if (length <= 0) {
@@ -2815,37 +3164,70 @@ export class PgConnection {
2815
3164
  return String.fromBytes(this.input, start, start + length)
2816
3165
  }
2817
3166
 
2818
- /** Column `c` of the statement just described: its type's OID (23 is `int4`, 25 `text`). */
3167
+ /**
3168
+ * Column `c` of the statement just described, after `PG_DESCRIBED`.
3169
+ * @param c The column, 0 to `columns - 1`.
3170
+ * @returns Its type's OID (23 is `int4`, 25 `text`).
3171
+ */
2819
3172
  columnType(c: i32): i32 {
2820
3173
  return this.colTypes[c]
2821
3174
  }
2822
3175
 
2823
- /** Column `c` as an integer; NULL or a bad value sets `text.failed`. */
3176
+ /**
3177
+ * Text column `c` as an integer, through `text.int`; NULL or a bad value
3178
+ * sets `text.failed`.
3179
+ * @param c The column, 0 to `columns - 1`.
3180
+ * @returns The value, or 0 when it sets `text.failed`.
3181
+ */
2824
3182
  int(c: i32): i64 {
2825
3183
  return this.text.int(this.input, this.colStarts[c], this.colLengths[c])
2826
3184
  }
2827
3185
 
2828
- /** Column `c` as a boolean; NULL or a bad value sets `text.failed`. */
3186
+ /**
3187
+ * Text column `c` as a boolean, through `text.bool`; NULL or a bad value
3188
+ * sets `text.failed`.
3189
+ * @param c The column, 0 to `columns - 1`.
3190
+ * @returns True for `t`; false for `f`, and when it sets `text.failed`.
3191
+ */
2829
3192
  bool(c: i32): boolean {
2830
3193
  return this.text.bool(this.input, this.colStarts[c], this.colLengths[c])
2831
3194
  }
2832
3195
 
2833
- /** Binary column `c`, an `int2`, `int4`, `int8` or a time's microseconds, as an integer; NULL or another length sets `binary.failed`. */
3196
+ /**
3197
+ * Binary column `c`, an `int2`, `int4`, `int8` or a time's microseconds
3198
+ * since 2000, as an integer; NULL or another length sets `binary.failed`.
3199
+ * @param c The column, 0 to `columns - 1`.
3200
+ * @returns The value, or 0 when it sets `binary.failed`.
3201
+ */
2834
3202
  binaryInt(c: i32): i64 {
2835
3203
  return this.binary.int(this.input, this.colStarts[c], this.colLengths[c])
2836
3204
  }
2837
3205
 
2838
- /** Binary column `c` as a boolean; NULL or a bad value sets `binary.failed`. */
3206
+ /**
3207
+ * Binary column `c` as a boolean; NULL or a bad value sets `binary.failed`.
3208
+ * @param c The column, 0 to `columns - 1`.
3209
+ * @returns True for 1; false for 0, and when it sets `binary.failed`.
3210
+ */
2839
3211
  binaryBool(c: i32): boolean {
2840
3212
  return this.binary.bool(this.input, this.colStarts[c], this.colLengths[c])
2841
3213
  }
2842
3214
 
2843
- /** Binary column `c`, a `float8`, as an f64; NULL or another length sets `binary.failed`. */
3215
+ /**
3216
+ * Binary column `c`, a `float8`; NULL or another length sets `binary.failed`.
3217
+ * @param c The column, 0 to `columns - 1`.
3218
+ * @returns The value, or 0 when it sets `binary.failed`.
3219
+ */
2844
3220
  binaryFloat(c: i32): f64 {
2845
3221
  return this.binary.float(this.input, this.colStarts[c], this.colLengths[c])
2846
3222
  }
2847
3223
 
2848
- /** Whether the tag of the execution just completed starts with the word `word` (`INSERT`, `SELECT`, ...). */
3224
+ /**
3225
+ * Whether the tag of the execution just completed starts with the word
3226
+ * `word`, read after `PG_COMPLETE` and before the next `next()`.
3227
+ * @param word The command word, as the server spells it (`INSERT`,
3228
+ * `SELECT`, `UPDATE`, ...); case matters, and `INS` does not match `INSERT`.
3229
+ * @returns True when the tag is `word` or begins with `word` and a space.
3230
+ */
2849
3231
  tagIs(word: string): boolean {
2850
3232
  const n: i32 = toI32(word.length)
2851
3233
  if (n > this.tagLength || !pgBytesAre(this.input, this.tagStart, n, word)) {
@@ -2854,7 +3236,13 @@ export class PgConnection {
2854
3236
  return n === this.tagLength || toI32(this.input[this.tagStart + n]) === 32
2855
3237
  }
2856
3238
 
2857
- /** The row count the tag ends with (`INSERT 0 3` is 3, `SELECT 5` is 5), or -1 when it has none or it does not fit an i64. */
3239
+ /**
3240
+ * The row count the tag of the execution just completed ends with, read
3241
+ * after `PG_COMPLETE` and before the next `next()`; `text.failed` is left
3242
+ * as it was.
3243
+ * @returns The count (`INSERT 0 3` is 3, `SELECT 5` is 5), or -1 when the
3244
+ * tag has none (`BEGIN`) or it does not fit an i64.
3245
+ */
2858
3246
  tagRows(): i64 {
2859
3247
  const end: i32 = this.tagStart + this.tagLength
2860
3248
  let p: i32 = end
@@ -2904,15 +3292,27 @@ const PG_SLOT_DRAINING: i32 = 4
2904
3292
 
2905
3293
  /** One of a pool's connections, and the groups it has in flight. */
2906
3294
  class PgPoolSlot {
3295
+ /** @internal Used by `PgPool.dispatch`, `PgPool.wanted`, `PgPool.connect`, `PgPool.next` and `PgPool.anyReady` in this module. */
2907
3296
  state: i32 = 0
3297
+ /** @internal Used by `PgPool.dispatch`, `PgPool.connect`, `PgPool.connection` and `PgPool.dispose` in this module. */
2908
3298
  conn: PgConnection | null = null
2909
- /** How many registered statements this connection has queued, and how many the server has described. */
3299
+ /**
3300
+ * How many registered statements this connection has queued, and how many the server has described.
3301
+ * @internal Used by `PgPool.dispatch`, `PgPool.connect` and `PgPool.next` in this module.
3302
+ */
2910
3303
  queued: i32 = 0
3304
+ /** @internal Used by `PgPool.connect` and `PgPool.next` in this module. */
2911
3305
  described: i32 = 0
2912
- /** The groups in flight, oldest first, in a ring: each one's ticket, and how many of the pool's own prepares lead it. */
3306
+ /**
3307
+ * The groups in flight, oldest first, in a ring: each one's ticket, and how many of the pool's own prepares lead it.
3308
+ * @internal Used by `PgPool.next` in this module.
3309
+ */
2913
3310
  readonly tickets: i32[]
3311
+ /** @internal Used by `PgPool.next` in this module. */
2914
3312
  readonly leads: i32[]
3313
+ /** @internal Used by `PgPool.connect` and `PgPool.next` in this module. */
2915
3314
  head: i32 = 0
3315
+ /** @internal Used by `PgPool.inFlight`, `PgPool.send`, `PgPool.connect` and `PgPool.next` in this module. */
2916
3316
  count: i32 = 0
2917
3317
 
2918
3318
  constructor(ring: i32) {
@@ -2920,6 +3320,7 @@ class PgPoolSlot {
2920
3320
  this.leads = new Array<i32>(ring)
2921
3321
  }
2922
3322
 
3323
+ /** @internal Used by `PgPool.dispatch` and `PgPool.next` in this module. */
2923
3324
  push(ticket: i32, leads: i32): void {
2924
3325
  const at: i32 = (this.head + this.count) % toI32(this.tickets.length)
2925
3326
  this.tickets[at] = ticket
@@ -2927,6 +3328,7 @@ class PgPoolSlot {
2927
3328
  this.count += 1
2928
3329
  }
2929
3330
 
3331
+ /** @internal Used by `PgPool.next` in this module. */
2930
3332
  pop(): void {
2931
3333
  this.head = (this.head + 1) % toI32(this.tickets.length)
2932
3334
  this.count -= 1
@@ -2975,6 +3377,12 @@ export class PgPool {
2975
3377
  * waiting requests (1 to 2^20). `password` is copied and kept until
2976
3378
  * `dispose()`, since a connection is made again after a failure. Panics as
2977
3379
  * `PgConnection` does on `config`, and on a `maxInFlight` over 1024.
3380
+ *
3381
+ * @param config The settings every connection of the pool is made with; kept, not copied.
3382
+ * @param password The password every connection authenticates with. The pool keeps its
3383
+ * own copy, so the caller may wipe this one as soon as the constructor returns.
3384
+ * @param size The most connections the pool makes, from 1 to 1024.
3385
+ * @param queueSize The most requests that may wait for a connection, from 1 to 2^20.
2978
3386
  */
2979
3387
  constructor(config: PgConfig, password: Secret<u8[]>, size: i32, queueSize: i32) {
2980
3388
  pgCheckConfig(config)
@@ -3004,6 +3412,11 @@ export class PgPool {
3004
3412
  * Registers a statement for every connection to prepare before its first
3005
3413
  * request. False when a connection has been made already, `name` or `sql`
3006
3414
  * holds a NUL, or 256 are registered.
3415
+ *
3416
+ * @param name The statement's name, which the program's binds use; no NUL.
3417
+ * @param sql The statement's text, with `$1`, `$2`... for its parameters; no NUL.
3418
+ * @param paramTypes The type OID of each parameter, 0 to let the server infer it; copied.
3419
+ * @returns True when the statement was registered.
3007
3420
  */
3008
3421
  register(name: string, sql: string, paramTypes: i32[]): boolean {
3009
3422
  if (
@@ -3024,7 +3437,12 @@ export class PgPool {
3024
3437
  return true
3025
3438
  }
3026
3439
 
3027
- /** Queues a request and answers its ticket, or `PG_POOL_FULL` when `queueSize` are waiting. */
3440
+ /**
3441
+ * Queues a request and answers its ticket, or `PG_POOL_FULL` when `queueSize` are waiting.
3442
+ *
3443
+ * @returns The request's ticket, from 0 to 2^31-1 and counting up from 0, wrapping to 0
3444
+ * after 2^31-1; or `PG_POOL_FULL`.
3445
+ */
3028
3446
  request(): i32 {
3029
3447
  const room: i32 = toI32(this.queue.length)
3030
3448
  if (this.queueCount === room) {
@@ -3037,12 +3455,21 @@ export class PgPool {
3037
3455
  return ticket
3038
3456
  }
3039
3457
 
3040
- /** The number of requests waiting for a connection. */
3458
+ /**
3459
+ * How many requests wait for a connection.
3460
+ *
3461
+ * @returns The requests queued and not yet given a connection.
3462
+ */
3041
3463
  waiting(): i32 {
3042
3464
  return this.queueCount
3043
3465
  }
3044
3466
 
3045
- /** The number of groups in flight on every connection, sent and not yet done: the `inFlight` a `PgBatchClock` reads. */
3467
+ /**
3468
+ * How many groups are in flight across every connection: the `inFlight` a
3469
+ * `PgBatchClock` reads.
3470
+ *
3471
+ * @returns The groups sent and not yet done, summed over every connection.
3472
+ */
3046
3473
  inFlight(): i32 {
3047
3474
  let n: i32 = 0
3048
3475
  for (const slot of this.slots) {
@@ -3061,6 +3488,8 @@ export class PgPool {
3061
3488
  * waiting requests that the connections already starting cannot take. A
3062
3489
  * request handed out is the program's to end with `send()`: until then no
3063
3490
  * other is handed out.
3491
+ *
3492
+ * @returns The slot the request was handed to, from 0 to `size - 1`, or `PG_POOL_NONE`.
3064
3493
  */
3065
3494
  dispatch(): i32 {
3066
3495
  if (this.building >= 0 || this.queueCount === 0) {
@@ -3117,6 +3546,8 @@ export class PgPool {
3117
3546
  * is none; when a bind is still open, so finish it and call again; and
3118
3547
  * when no message of the group was written, so the request is dropped and
3119
3548
  * gets no events (`PG_LOST` if its connection has failed).
3549
+ *
3550
+ * @returns True when the group's Sync was written and the request is in flight.
3120
3551
  */
3121
3552
  send(): boolean {
3122
3553
  const s: i32 = this.building
@@ -3140,7 +3571,11 @@ export class PgPool {
3140
3571
  return false
3141
3572
  }
3142
3573
 
3143
- /** A slot that needs a socket, or `PG_POOL_NONE`: connect it, then call `connect(slot, nonce)`. */
3574
+ /**
3575
+ * A slot that needs a socket, or `PG_POOL_NONE`: connect it, then call `connect(slot, nonce)`.
3576
+ *
3577
+ * @returns The lowest wanted slot, or `PG_POOL_NONE` when no slot is wanted.
3578
+ */
3144
3579
  wanted(): i32 {
3145
3580
  for (let s: i32 = 0; s < this.size; s++) {
3146
3581
  if (this.slots[s].state === PG_SLOT_WANTED) {
@@ -3155,6 +3590,10 @@ export class PgPool {
3155
3590
  * send its output once the socket is connected, and if the socket fails,
3156
3591
  * call `connection(slot).closed()`. Panics when `slot` is not wanted or the
3157
3592
  * pool is disposed.
3593
+ *
3594
+ * @param slot The slot `wanted()` answered.
3595
+ * @param nonce At least 18 fresh random bytes for the SCRAM client nonce, as the
3596
+ * `PgConnection` constructor takes them; a new one for every connection.
3158
3597
  */
3159
3598
  connect(slot: i32, nonce: u8[]): void {
3160
3599
  if (slot < 0 || slot >= this.size || this.slots[slot].state !== PG_SLOT_WANTED) {
@@ -3173,7 +3612,13 @@ export class PgPool {
3173
3612
  this.started = true
3174
3613
  }
3175
3614
 
3176
- /** The connection in `slot`, its buffers the carrier's to fill and drain; the last one made after it fails. Panics when none was made. */
3615
+ /**
3616
+ * The connection in `slot`, its buffers the carrier's to fill and drain; the last one made
3617
+ * after it fails. Panics when none was made.
3618
+ *
3619
+ * @param slot The slot, from 0 to `size - 1`.
3620
+ * @returns The slot's connection, owned by the pool: a later `connect` on the slot replaces it.
3621
+ */
3177
3622
  connection(slot: i32): PgConnection {
3178
3623
  const conn: PgConnection | null = slot < 0 || slot >= this.size ? null : this.slots[slot].conn
3179
3624
  if (conn === null) {
@@ -3193,6 +3638,9 @@ export class PgPool {
3193
3638
  * server that cannot be reached empties the queue rather than holds it.
3194
3639
  * `PG_NEED_MORE` once `PG_FAILED` was answered, until `connect` builds the
3195
3640
  * slot again. Panics as `connection(slot)` does.
3641
+ *
3642
+ * @param slot The slot whose input the carrier has just filled, from 0 to `size - 1`.
3643
+ * @returns A `PG_` event; `ticket` names the request it is about.
3196
3644
  */
3197
3645
  next(slot: i32): i32 {
3198
3646
  const conn: PgConnection = this.connection(slot)
@@ -3249,7 +3697,13 @@ export class PgPool {
3249
3697
  return false
3250
3698
  }
3251
3699
 
3252
- /** Whether every byte of the pool's copy of the password is zero, as `PgConnection.passwordWiped()` reads its own. */
3700
+ /**
3701
+ * Whether every byte of the pool's copy of the password is zero, as
3702
+ * `PgConnection.passwordWiped()` reads its own: true once it is wiped, and
3703
+ * for an empty password before any wipe.
3704
+ *
3705
+ * @returns True once the pool's copy is wiped; the connections' copies are not read.
3706
+ */
3253
3707
  passwordWiped(): boolean {
3254
3708
  return this.password.wiped()
3255
3709
  }
@@ -3365,23 +3819,46 @@ export class PgBatchConfig {
3365
3819
 
3366
3820
  /** One execution's requests, grouped by key, and how far its rows have been routed. */
3367
3821
  class PgBatchRun {
3368
- /** Key `k`'s requests' tags are `tags[first[k], first[k + 1])`, in the order they were added; grown by `take` to the batch. */
3822
+ /**
3823
+ * Key `k`'s requests' tags are `tags[first[k], first[k + 1])`, in the order they were added; grown by `take` to the batch.
3824
+ * @internal Used by `PgBatcher.take`, `PgBatcher.emit`, `PgBatcher.next` and `PgBatcher.nextUnsorted` in this module.
3825
+ */
3369
3826
  tags: i32[]
3827
+ /** @internal Used by `PgBatcher.take`, `PgBatcher.emit` and `PgBatcher.nextUnsorted` in this module. */
3370
3828
  first: i32[]
3371
- /** Under `sorted` false, whether key `k` has had a row; grown by `take` with `tags`, and empty when sorted. */
3829
+ /**
3830
+ * Under `sorted` false, whether key `k` has had a row; grown by `take` with `tags`, and empty when sorted.
3831
+ * @internal Used by `PgBatcher.take`, `PgBatcher.row` and `PgBatcher.nextUnsorted` in this module.
3832
+ */
3372
3833
  had: boolean[]
3834
+ /** @internal Used by `PgBatcher.row`, `PgBatcher.next` and `PgBatcher.nextUnsorted` in this module. */
3373
3835
  keys: i32 = 0
3374
- /** The key rows are being read for, whether it has had one, and the next of its requests to answer. */
3836
+ /**
3837
+ * The key rows are being read for, whether it has had one, and the next of its requests to answer.
3838
+ * @internal Used by `PgBatcher.row`, `PgBatcher.emit`, `PgBatcher.next` and `PgBatcher.nextUnsorted` in this module.
3839
+ */
3375
3840
  cur: i32 = 0
3841
+ /** @internal Used by `PgBatcher.next` in this module. */
3376
3842
  curRows: boolean = false
3843
+ /** @internal Used by `PgBatcher.emit`, `PgBatcher.next` and `PgBatcher.nextUnsorted` in this module. */
3377
3844
  at: i32 = 0
3378
- /** The key whose `PG_BATCH_ROW` events are owed for the connection's current row; -1 for none. */
3845
+ /**
3846
+ * The key whose `PG_BATCH_ROW` events are owed for the connection's current row; -1 for none.
3847
+ * @internal Used by `PgBatcher.quietRun`, `PgBatcher.row`, `PgBatcher.next` and `PgBatcher.nextUnsorted` in this module.
3848
+ */
3379
3849
  target: i32 = -1
3380
- /** The handle `take` gave for the run's execution, and how many takes it has had, mod `PG_BATCH_USES`. */
3850
+ /**
3851
+ * The handle `take` gave for the run's execution, and how many takes it has had, mod `PG_BATCH_USES`.
3852
+ * @internal Used by `PgBatcher.take` and `PgBatcher.run` in this module.
3853
+ */
3381
3854
  handle: i32 = -1
3855
+ /** @internal Used by `PgBatcher.take` in this module. */
3382
3856
  uses: i32 = 0
3857
+ /** @internal Used by `PgBatcher.take`, `PgBatcher.run`, `PgBatcher.next` and `PgBatcher.nextUnsorted` in this module. */
3383
3858
  open: boolean = false
3859
+ /** @internal Used by `PgBatcher.quietRun`, `PgBatcher.end`, `PgBatcher.fail`, `PgBatcher.next` and `PgBatcher.nextUnsorted` in this module. */
3384
3860
  ended: boolean = false
3861
+ /** @internal Used by `PgBatcher.row`, `PgBatcher.fail`, `PgBatcher.next` and `PgBatcher.nextUnsorted` in this module. */
3385
3862
  failed: boolean = false
3386
3863
 
3387
3864
  constructor() {
@@ -3390,7 +3867,10 @@ class PgBatchRun {
3390
3867
  this.had = []
3391
3868
  }
3392
3869
 
3393
- /** Opens the run for `keys` keys, none of whose rows have been read. */
3870
+ /**
3871
+ * Opens the run for `keys` keys, none of whose rows have been read.
3872
+ * @internal Used by `PgBatcher.take` in this module.
3873
+ */
3394
3874
  reset(keys: i32): void {
3395
3875
  this.open = true
3396
3876
  this.keys = keys
@@ -3407,39 +3887,41 @@ class PgBatchRun {
3407
3887
  }
3408
3888
 
3409
3889
  /**
3410
- * Batches keyed reads of one statement shape, sans-IO like `PgConnection`:
3411
- * it reads no clock and makes no socket. Each request is a key and the
3412
- * caller's `tag`, queued by `addInt` or `addText`. When a connection is free,
3413
- * `take(conn)` binds up to `maxRequests` of them, and up to `maxBytes` of
3414
- * keys, as one execution of `sql`, each distinct key once (a key whose
3415
- * probe of the batcher's table passes 1024 slots, which takes keys chosen to
3416
- * collide, is bound again and answered the same), and answers the
3417
- * execution's run handle. Each `PG_ROW` of that execution goes to
3418
- * `row(run, conn)`, its `PG_COMPLETE` to `end(run)`, and an error or a lost
3419
- * connection to `fail(run)`; after each, `next(run)` answers events until
3420
- * `PG_BATCH_NONE`, `tag` naming the request each is about. Every row goes to
3421
- * every request for its key, and every request gets one last event:
3422
- * `PG_BATCH_DONE`, `PG_BATCH_MISSING` or `PG_BATCH_FAILED`. Sorted (the
3423
- * default), rows come in key order and a key's last events come as soon as
3424
- * a later key's row does; with `sorted` false, rows come in any order, each
3425
- * answered at once, and every last event waits for `end` or `fail`, then
3426
- * comes in key order. A batch with
3427
- * `binary` set comes in binary format: its rows are read with the binary
3428
- * decoders, `binaryInt` for each ordinal, and the caller's `binary.failed`
3429
- * is left as it was.
3890
+ * Batches keyed reads of one statement shape, sans-IO like `PgConnection`: it
3891
+ * reads no clock and makes no socket. Each request is a key and the caller's
3892
+ * `tag`, queued by `addInt` or `addText`. When a connection is free,
3893
+ * `take(conn)` binds up to `maxRequests` of them, and up to `maxBytes` of keys,
3894
+ * as one execution of `sql`, each distinct key once (a key whose probe of the
3895
+ * batcher's table passes 1024 slots, which takes keys chosen to collide, is
3896
+ * bound again and answered the same), and answers the execution's run handle.
3897
+ *
3898
+ * Each `PG_ROW` of that execution goes to `row(run, conn)`, its `PG_COMPLETE`
3899
+ * to `end(run)`, and an error or a lost connection to `fail(run)`; after each,
3900
+ * `next(run)` answers events until `PG_BATCH_NONE`, `tag` naming the request
3901
+ * each is about. Every row goes to every request for its key, and every request
3902
+ * gets one last event: `PG_BATCH_DONE`, `PG_BATCH_MISSING` or
3903
+ * `PG_BATCH_FAILED`.
3904
+ *
3905
+ * Sorted (the default), rows come in key order and a key's last events come as
3906
+ * soon as a later key's row does; with `sorted` false, rows come in any order,
3907
+ * each answered at once, and every last event waits for `end` or `fail`, then
3908
+ * comes in key order. A batch with `binary` set comes in binary format: its
3909
+ * rows are read with the binary decoders, `binaryInt` for each ordinal, and the
3910
+ * caller's `binary.failed` is left as it was.
3430
3911
  *
3431
- * Nothing outlives its execution: a run is free again once the events
3432
- * `end` or `fail` owe are answered, and its handle is then spent. What the
3433
- * server or the network can send after that — a second `PG_COMPLETE`, a row
3434
- * or an error after one, a lost connection — goes to a spent handle, and
3435
- * `row`, `end` and `fail` count it in `stray` and do nothing, even once
3436
- * `take` has given the run out again under a new handle. The ordinal each
3437
- * row carries comes from the server and is checked before it routes
3438
- * anything. What panics is only the program's own misuse: a handle out of
3439
- * the range `take` can give (-1 or any negative, or `runs` * 2^20 or more),
3440
- * or `row`, `end` or `fail` before `next(run)` has answered `PG_BATCH_NONE`
3441
- * for the event before. A handle in that range that `take` never gave is
3442
- * spent like any other: counted in `stray`, not a panic.
3912
+ * Nothing outlives its execution: a run is free again once the events `end` or
3913
+ * `fail` owe are answered, and its handle is then spent. What the server or the
3914
+ * network can send after that — a second `PG_COMPLETE`, a row or an error after
3915
+ * one, a lost connection — goes to a spent handle, and `row`, `end` and `fail`
3916
+ * count it in `stray` and do nothing, even once `take` has given the run out
3917
+ * again under a new handle. The ordinal each row carries comes from the server
3918
+ * and is checked before it routes anything.
3919
+ *
3920
+ * What panics is only the program's own misuse: a handle out of the range
3921
+ * `take` can give (-1 or any negative, or `runs` * 2^20 or more), or `row`,
3922
+ * `end` or `fail` before `next(run)` has answered `PG_BATCH_NONE` for the event
3923
+ * before. A handle in that range that `take` never gave is spent like any
3924
+ * other: counted in `stray`, not a panic.
3443
3925
  */
3444
3926
  export class PgBatcher {
3445
3927
  /** The prepared statement's name. */
@@ -3471,7 +3953,10 @@ export class PgBatcher {
3471
3953
  refused: i32 = 0
3472
3954
  /** The number of `row`, `end` and `fail` calls on a spent handle, each ignored, stopping at 2^31 - 1. */
3473
3955
  stray: i32 = 0
3474
- /** The most requests one execution takes, from `PgBatchConfig.maxRequests`. */
3956
+ /**
3957
+ * The most requests one execution takes, from `PgBatchConfig.maxRequests`.
3958
+ * @internal Used by `PgCarrier.routeBatch` in std/net/postgres-carrier.ts.
3959
+ */
3475
3960
  readonly maxRequests: i32
3476
3961
  private readonly keyType: i32
3477
3962
  private readonly maxBytes: i32
@@ -3481,7 +3966,14 @@ export class PgBatcher {
3481
3966
  private head: i32 = 0
3482
3967
  private count: i32 = 0
3483
3968
 
3484
- /** A batcher for `config`; panics when a name or query is empty or holds a NUL, or a cap is out of range. */
3969
+ /**
3970
+ * A batcher for `config`; panics when a name or query is empty or holds a NUL, or a cap is out
3971
+ * of range.
3972
+ *
3973
+ * @param config The statement shape and caps, read once here: later changes to it do nothing.
3974
+ * `maxRequests` is 1 to 65536, `maxBytes` at least 22, `queueSize` 1 to 2^20, `runs` 1 to
3975
+ * 1024, and `queueBytes` at least 0 (a text batcher with 0 can queue only empty keys).
3976
+ */
3485
3977
  constructor(config: PgBatchConfig) {
3486
3978
  const keyType: i32 = config.keyType
3487
3979
  if (keyType !== PG_BATCH_INT && keyType !== PG_BATCH_TEXT) {
@@ -3547,15 +4039,21 @@ export class PgBatcher {
3547
4039
  }
3548
4040
  }
3549
4041
 
3550
- /** The number of requests waiting for `take`. */
4042
+ /**
4043
+ * How many requests wait for `take`.
4044
+ *
4045
+ * @returns The requests queued and not yet taken into a batch.
4046
+ */
3551
4047
  waiting(): i32 {
3552
4048
  return this.count
3553
4049
  }
3554
4050
 
3555
4051
  /**
3556
- * Drops the oldest waiting request and answers its tag, or -1 when none
3557
- * waits: for a program that cannot reach the server to fail requests
3558
- * rather than hold them.
4052
+ * Drops the oldest waiting request, so that a carrier that cannot reach the
4053
+ * server fails its requests rather than holds them.
4054
+ *
4055
+ * @returns The dropped request's tag, or -1 when none waits.
4056
+ * @internal Used by `PgCarrier.next` in std/net/postgres-carrier.ts.
3559
4057
  */
3560
4058
  shed(): i32 {
3561
4059
  if (this.count === 0) {
@@ -3570,7 +4068,15 @@ export class PgBatcher {
3570
4068
  return tag
3571
4069
  }
3572
4070
 
3573
- /** Queues a request for the int8 `key`; false when `queueSize` are waiting. Panics on a text batcher. */
4071
+ /**
4072
+ * Queues a request for the int8 `key`; false when `queueSize` are waiting. Panics on a text
4073
+ * batcher.
4074
+ *
4075
+ * @param key The key the statement's `q.key` is bound to.
4076
+ * @param tag The caller's own number for the request, which `tag` holds when `next(run)`
4077
+ * answers an event about it; best not -1, which `tag` holds for none.
4078
+ * @returns True when the request was queued.
4079
+ */
3574
4080
  addInt(key: i64, tag: i32): boolean {
3575
4081
  if (this.keyType !== PG_BATCH_INT) {
3576
4082
  panic("nish/net/postgres: PgBatcher.addInt on a text batcher")
@@ -3591,6 +4097,14 @@ export class PgBatcher {
3591
4097
  * the key would not fit in `queueBytes` beside those waiting, or it is too
3592
4098
  * long for one execution's `maxBytes`. Panics on an int8 batcher, or when
3593
4099
  * the window is not inside `bytes`.
4100
+ *
4101
+ * @param bytes The buffer holding the key; only the window is read, and the caller may reuse
4102
+ * the buffer as soon as the call returns.
4103
+ * @param start The index of the key's first byte in `bytes`.
4104
+ * @param length The key's length in bytes, 0 for the empty key.
4105
+ * @param tag The caller's own number for the request, which `tag` holds when `next(run)`
4106
+ * answers an event about it; best not -1, which `tag` holds for none.
4107
+ * @returns True when the request was queued.
3594
4108
  */
3595
4109
  addText(bytes: u8[], start: i32, length: i32, tag: i32): boolean {
3596
4110
  if (this.keyType !== PG_BATCH_TEXT) {
@@ -3684,6 +4198,12 @@ export class PgBatcher {
3684
4198
  * answers -1. The program calls `clock.arrived(now)` for each request it
3685
4199
  * adds. Panics when the clock's waiting count is not this batcher's, or its
3686
4200
  * `maxCount` is below `maxRequests`.
4201
+ *
4202
+ * @param conn The free connection to bind the batch on, as `take` takes it.
4203
+ * @param clock The clock that mirrors this batcher's queue, one `arrived` per request added.
4204
+ * @param nowUs The time now, in the clock's microseconds.
4205
+ * @param inFlight The program's executions or groups still running, for the idle bypass.
4206
+ * @returns The run handle `take` answered, or -1 when no batch was taken.
3687
4207
  */
3688
4208
  takeDue(conn: PgConnection, clock: PgBatchClock, nowUs: i64, inFlight: i32): i32 {
3689
4209
  if (clock.waiting() !== this.count || clock.maxCount < this.maxRequests) {
@@ -3709,6 +4229,10 @@ export class PgBatcher {
3709
4229
  * the connection's `maxOutput`; those not taken stay queued. -1, and
3710
4230
  * nothing written, when none waits, every run is in flight, or `conn`
3711
4231
  * refused the bind or the first key.
4232
+ *
4233
+ * @param conn A connection with no bind open, on which `sql` has been prepared under `name`.
4234
+ * @returns The run handle, from 0 to `runs` * 2^20 - 1, to pass to `row`, `end`, `fail` and
4235
+ * `next` for this execution's events; or -1.
3712
4236
  */
3713
4237
  take(conn: PgConnection): i32 {
3714
4238
  if (this.count === 0) {
@@ -3892,6 +4416,10 @@ export class PgBatcher {
3892
4416
  * one before the key the last row was for): that counts in `refused` and
3893
4417
  * fails the run; and on a spent handle, which counts in `stray`. Panics on a handle
3894
4418
  * `take` cannot give, or when the run's events are not all answered.
4419
+ *
4420
+ * @param r The run handle `take` answered for the execution the row belongs to.
4421
+ * @param conn The connection whose `next()` has just answered `PG_ROW` for that execution.
4422
+ * @returns True when the row was routed, and `next(r)` answers its `PG_BATCH_ROW` events.
3895
4423
  */
3896
4424
  row(r: i32, conn: PgConnection): boolean {
3897
4425
  const run: PgBatchRun | null = this.quietRun(r, "row")
@@ -3935,7 +4463,12 @@ export class PgBatcher {
3935
4463
  return true
3936
4464
  }
3937
4465
 
3938
- /** Ends run `r`'s execution, on its `PG_COMPLETE`: `next(r)` then closes every request left. Ignores a spent handle, and panics, as `row` does. */
4466
+ /**
4467
+ * Ends run `r`'s execution, on its `PG_COMPLETE`: `next(r)` then closes every request left.
4468
+ * Ignores a spent handle, and panics, as `row` does.
4469
+ *
4470
+ * @param r The run handle `take` answered for the execution.
4471
+ */
3939
4472
  end(r: i32): void {
3940
4473
  const run: PgBatchRun | null = this.quietRun(r, "end")
3941
4474
  if (run !== null) {
@@ -3943,7 +4476,12 @@ export class PgBatcher {
3943
4476
  }
3944
4477
  }
3945
4478
 
3946
- /** Fails run `r`'s execution, on its `PG_ERROR` or `PG_LOST`: `next(r)` then answers `PG_BATCH_FAILED` for every request left. Ignores a spent handle, and panics, as `row` does. */
4479
+ /**
4480
+ * Fails run `r`'s execution, on its `PG_ERROR` or `PG_LOST`: `next(r)` then answers
4481
+ * `PG_BATCH_FAILED` for every request left. Ignores a spent handle, and panics, as `row` does.
4482
+ *
4483
+ * @param r The run handle `take` answered for the execution.
4484
+ */
3947
4485
  fail(r: i32): void {
3948
4486
  const run: PgBatchRun | null = this.quietRun(r, "fail")
3949
4487
  if (run !== null) {
@@ -3969,6 +4507,9 @@ export class PgBatcher {
3969
4507
  * Once `end` or `fail` has had all its events the run is over, free for
3970
4508
  * `take` again, and its handle spent: `PG_BATCH_NONE` ever after. Panics
3971
4509
  * on a handle `take` cannot give.
4510
+ *
4511
+ * @param r The run handle `take` answered for the execution.
4512
+ * @returns A `PG_BATCH_*` event: call again until it is `PG_BATCH_NONE`.
3972
4513
  */
3973
4514
  next(r: i32): i32 {
3974
4515
  const found: PgBatchRun | null = this.run(r)
@@ -4120,6 +4661,7 @@ export class PgBatchClock {
4120
4661
  lastReason: i32 = 0
4121
4662
  /** How long the oldest item of the last batch waited, in microseconds. */
4122
4663
  lastWaitUs: i64 = 0
4664
+ /** @internal Used by `PgBatcher.takeDue` in this module. */
4123
4665
  readonly maxCount: i32
4124
4666
  private readonly minCount: i32
4125
4667
  private readonly factor: f64
@@ -4138,7 +4680,12 @@ export class PgBatchClock {
4138
4680
  private last: i64 = 0
4139
4681
  private due: i32 = 0
4140
4682
 
4141
- /** A clock for `config`; panics when a setting is out of the range its field names. */
4683
+ /**
4684
+ * A clock for `config`; panics when a setting is out of the range its field names, or
4685
+ * `minCount` is above `maxCount`.
4686
+ *
4687
+ * @param config The settings, read once here: later changes to it do nothing.
4688
+ */
4142
4689
  constructor(config: PgBatchClockConfig) {
4143
4690
  const factor: f64 = config.factor
4144
4691
  const weight: f64 = config.weight
@@ -4171,7 +4718,11 @@ export class PgBatchClock {
4171
4718
  this.starts = new Array<i64>(5)
4172
4719
  }
4173
4720
 
4174
- /** The number of items waiting. */
4721
+ /**
4722
+ * How many items wait for a batch.
4723
+ *
4724
+ * @returns The items queued and not yet started in a batch.
4725
+ */
4175
4726
  waiting(): i32 {
4176
4727
  return this.count
4177
4728
  }
@@ -4180,6 +4731,9 @@ export class PgBatchClock {
4180
4731
  * Records an item queued at `nowUs`; false when `queueSize` are waiting. A
4181
4732
  * time before the last one given counts as the last one, so a clock that
4182
4733
  * steps back cannot make an item older than its neighbours.
4734
+ *
4735
+ * @param nowUs The time the item was queued, in microseconds from the program's fixed point.
4736
+ * @returns True when the item was recorded.
4183
4737
  */
4184
4738
  arrived(nowUs: i64): boolean {
4185
4739
  const ring: i32 = toI32(this.times.length)
@@ -4201,7 +4755,11 @@ export class PgBatchClock {
4201
4755
  return true
4202
4756
  }
4203
4757
 
4204
- /** The count that starts a batch now: the larger of `minCount` and the average times `factor`, at most `maxCount`. */
4758
+ /**
4759
+ * The count that starts a batch now.
4760
+ *
4761
+ * @returns The larger of `minCount` and the average times `factor`, at most `maxCount`.
4762
+ */
4205
4763
  target(): i32 {
4206
4764
  const scaled: f64 = Math.ceil(this.average * this.factor)
4207
4765
  let target: i32 = this.minCount
@@ -4215,6 +4773,12 @@ export class PgBatchClock {
4215
4773
  * The reason a batch should start at `nowUs`, with `inFlight` batches (or
4216
4774
  * groups) still running, or `PG_CLOCK_WAIT`. It only says; the program
4217
4775
  * starts the batch when a connection is free, then calls `started`.
4776
+ *
4777
+ * @param nowUs The time now, in the clock's microseconds.
4778
+ * @param inFlight The batches or groups still running; 0 or less lets the idle bypass fire.
4779
+ * @returns `PG_CLOCK_COUNT`, `PG_CLOCK_AVERAGE`, `PG_CLOCK_TIMER`, `PG_CLOCK_IDLE`, or
4780
+ * `PG_CLOCK_WAIT`, always `PG_CLOCK_WAIT` when nothing waits. The next `started` records it
4781
+ * as `lastReason`.
4218
4782
  */
4219
4783
  check(nowUs: i64, inFlight: i32): i32 {
4220
4784
  let reason: i32 = PG_CLOCK_WAIT
@@ -4232,7 +4796,11 @@ export class PgBatchClock {
4232
4796
  return reason
4233
4797
  }
4234
4798
 
4235
- /** When the oldest waiting item has waited `maxWaitUs`, in the caller's microseconds; -1 when none waits. */
4799
+ /**
4800
+ * When the oldest waiting item will have waited `maxWaitUs`.
4801
+ *
4802
+ * @returns That time in the caller's microseconds, or -1 when none waits.
4803
+ */
4236
4804
  deadline(): i64 {
4237
4805
  if (this.count === 0) {
4238
4806
  return -1
@@ -4244,6 +4812,10 @@ export class PgBatchClock {
4244
4812
  * Records a batch of the `size` oldest items started at `nowUs`, and moves
4245
4813
  * the average toward it; the first batch sets it. Panics when `size` is
4246
4814
  * below 1 or more than are waiting or than `maxCount`.
4815
+ *
4816
+ * @param size The number of items the batch took, oldest first.
4817
+ * @param nowUs The time the batch started, in the clock's microseconds; `lastWaitUs` is
4818
+ * measured to it, and is 0 when it is before the oldest item's arrival.
4247
4819
  */
4248
4820
  started(size: i32, nowUs: i64): void {
4249
4821
  if (size < 1 || size > this.count || size > this.maxCount) {
@@ -4263,7 +4835,13 @@ export class PgBatchClock {
4263
4835
  this.due = PG_CLOCK_WAIT
4264
4836
  }
4265
4837
 
4266
- /** How many batches have started for `reason`, one of the `PG_CLOCK_*` (`PG_CLOCK_WAIT` counts those started without a due `check`). */
4838
+ /**
4839
+ * How many batches have started for `reason`, one of the `PG_CLOCK_*` (`PG_CLOCK_WAIT` counts
4840
+ * those started without a due `check`). Panics on any other `reason`.
4841
+ *
4842
+ * @param reason `PG_CLOCK_WAIT` to `PG_CLOCK_IDLE`.
4843
+ * @returns The count since the clock was made.
4844
+ */
4267
4845
  startsFor(reason: i32): i64 {
4268
4846
  if (reason < 0 || reason > PG_CLOCK_IDLE) {
4269
4847
  panic("nish/net/postgres: PgBatchClock.startsFor with a reason out of range")
@@ -4312,12 +4890,18 @@ export class PgBatchTurns {
4312
4890
  /** The clock the turns read and record into. */
4313
4891
  readonly clock: PgBatchClock
4314
4892
  /** The number of slots. */
4315
- readonly size: i32
4893
+ private readonly size: i32
4316
4894
  private readonly busy: boolean[]
4317
4895
  private running: i32 = 0
4318
4896
  private woken: i32 = -1
4319
4897
 
4320
- /** Turns over `size` slots (1 to 1024), all free; panics on a size out of range. */
4898
+ /**
4899
+ * Turns over `size` slots (1 to 1024), all free; panics on a size out of range.
4900
+ *
4901
+ * @param clock The clock the program's batches are formed by; kept. `push` and `started`
4902
+ * record into it, so the program does not call its `arrived` or `started` itself.
4903
+ * @param size The number of connections, numbered 0 to `size - 1`.
4904
+ */
4321
4905
  constructor(clock: PgBatchClock, size: i32) {
4322
4906
  if (size < 1 || size > PG_POOL_MAX_SLOTS) {
4323
4907
  panic("nish/net/postgres: a PgBatchTurns size out of range")
@@ -4327,7 +4911,11 @@ export class PgBatchTurns {
4327
4911
  this.busy = new Array<boolean>(size)
4328
4912
  }
4329
4913
 
4330
- /** The slot that collects: the lowest-numbered free one, or `PG_TURNS_NONE` when every slot holds a batch. */
4914
+ /**
4915
+ * The slot that collects the next batch.
4916
+ *
4917
+ * @returns The lowest-numbered free slot, or `PG_TURNS_NONE` when every slot holds a batch.
4918
+ */
4331
4919
  collector(): i32 {
4332
4920
  for (let i: i32 = 0; i < this.size; i++) {
4333
4921
  if (!this.busy[i]) {
@@ -4337,17 +4925,31 @@ export class PgBatchTurns {
4337
4925
  return PG_TURNS_NONE
4338
4926
  }
4339
4927
 
4340
- /** The number of slots holding a batch. */
4928
+ /**
4929
+ * How many slots hold a batch.
4930
+ *
4931
+ * @returns The slots whose batch has `started` and not yet `finished`.
4932
+ */
4341
4933
  inFlight(): i32 {
4342
4934
  return this.running
4343
4935
  }
4344
4936
 
4345
- /** When the collector's timer fires, `PgBatchClock.deadline()`; -1 when nothing waits. */
4937
+ /**
4938
+ * When the collector's timer fires, as `PgBatchClock.deadline()` gives it.
4939
+ *
4940
+ * @returns That time in the caller's microseconds, or -1 when nothing waits.
4941
+ */
4346
4942
  deadline(): i64 {
4347
4943
  return this.clock.deadline()
4348
4944
  }
4349
4945
 
4350
- /** Records an item queued at `nowUs` and answers the slot to wake, or `PG_TURNS_FULL` when the clock is full. */
4946
+ /**
4947
+ * Records an item queued at `nowUs` and answers the slot to wake, or `PG_TURNS_FULL` when the
4948
+ * clock is full.
4949
+ *
4950
+ * @param nowUs The time the item was queued, in the clock's microseconds.
4951
+ * @returns The slot to wake, `PG_TURNS_NONE` when none is to be woken, or `PG_TURNS_FULL`.
4952
+ */
4351
4953
  push(nowUs: i64): i32 {
4352
4954
  if (!this.clock.arrived(nowUs)) {
4353
4955
  return PG_TURNS_FULL
@@ -4355,7 +4957,12 @@ export class PgBatchTurns {
4355
4957
  return this.poll(nowUs)
4356
4958
  }
4357
4959
 
4358
- /** The slot to wake at `nowUs`, when a batch is due and no slot is named already. */
4960
+ /**
4961
+ * The slot to wake at `nowUs`, when a batch is due and no slot is named already.
4962
+ *
4963
+ * @param nowUs The time now, in the clock's microseconds; call at `deadline()`.
4964
+ * @returns The collector's slot, or `PG_TURNS_NONE`.
4965
+ */
4359
4966
  poll(nowUs: i64): i32 {
4360
4967
  if (this.woken >= 0) {
4361
4968
  return PG_TURNS_NONE
@@ -4368,7 +4975,17 @@ export class PgBatchTurns {
4368
4975
  return slot
4369
4976
  }
4370
4977
 
4371
- /** Records `slot` starting a batch of `size` items at `nowUs`, and answers the next slot to wake. Panics on a slot out of range or holding a batch already, or as `PgBatchClock.started`. */
4978
+ /**
4979
+ * Records `slot` starting a batch of `size` items at `nowUs`, and answers the next slot to
4980
+ * wake. Panics on a slot out of range or holding a batch already, or as
4981
+ * `PgBatchClock.started`.
4982
+ *
4983
+ * @param slot The slot that took the batch, from 0 to `size - 1`; it holds the batch until
4984
+ * `finished`.
4985
+ * @param size The number of items the batch took.
4986
+ * @param nowUs The time the batch started, in the clock's microseconds.
4987
+ * @returns The slot to wake, or `PG_TURNS_NONE`.
4988
+ */
4372
4989
  started(slot: i32, size: i32, nowUs: i64): i32 {
4373
4990
  this.free(slot)
4374
4991
  this.clock.started(size, nowUs)
@@ -4380,7 +4997,14 @@ export class PgBatchTurns {
4380
4997
  return this.poll(nowUs)
4381
4998
  }
4382
4999
 
4383
- /** Records `slot`'s batch done at `nowUs`, and answers the slot to wake. Panics on a slot out of range or holding no batch. */
5000
+ /**
5001
+ * Records `slot`'s batch done at `nowUs`, and answers the slot to wake. Panics on a slot out
5002
+ * of range or holding no batch.
5003
+ *
5004
+ * @param slot The slot whose batch is done, from 0 to `size - 1`.
5005
+ * @param nowUs The time now, in the clock's microseconds.
5006
+ * @returns The slot to wake, or `PG_TURNS_NONE`.
5007
+ */
4384
5008
  finished(slot: i32, nowUs: i64): i32 {
4385
5009
  if (slot < 0 || slot >= this.size || !this.busy[slot]) {
4386
5010
  panic("nish/net/postgres: PgBatchTurns.finished on a slot holding no batch")
@@ -4390,7 +5014,12 @@ export class PgBatchTurns {
4390
5014
  return this.poll(nowUs)
4391
5015
  }
4392
5016
 
4393
- /** Gives back a wake that started nothing, so the next push or poll can wake a slot again. */
5017
+ /**
5018
+ * Gives back a wake that started nothing, so the next push or poll can wake a slot again.
5019
+ * Panics on a slot out of range or holding a batch.
5020
+ *
5021
+ * @param slot The slot that was woken and took no batch.
5022
+ */
4394
5023
  release(slot: i32): void {
4395
5024
  this.free(slot)
4396
5025
  if (this.woken === slot) {
@@ -4462,6 +5091,11 @@ const pgTargetFailed = (failure: i32): PgTarget => {
4462
5091
  * empty host, a `,` (more than one host) or a NUL byte is refused, and so is
4463
5092
  * a socket path over 107 bytes (an `@` name over 107 after its `@`), never
4464
5093
  * cut short.
5094
+ *
5095
+ * @param host The host, a socket directory starting with `/`, or an abstract name starting
5096
+ * with `@`; taken as it is, not percent-decoded.
5097
+ * @param port The TCP port, or the number in the socket's name, from 1 to 65535.
5098
+ * @returns The target; read `failure` before anything else.
4465
5099
  */
4466
5100
  export const pgTarget = (host: string, port: i32): PgTarget => {
4467
5101
  if (port < 1 || port > 65535) {
@@ -4519,20 +5153,24 @@ const pgPortValue = (text: string): i32 => {
4519
5153
  }
4520
5154
 
4521
5155
  /**
4522
- * The target a `postgres://` or `postgresql://` URL names, as libpq reads
4523
- * one: `postgres://[user[:password]@][host][:port][/dbname][?key=value&...]`.
4524
- * The host, the port and every query key and value are percent-decoded, so a
4525
- * socket directory is written `%2Ftmp` or passed as `?host=/tmp`; a `host` or
4526
- * `port` in the query overrides the authority's, and other keys are ignored.
4527
- * The user, password and database are not read here, but a bad escape in them
4528
- * still refuses the URL. A `%` without two hex digits after it, `%00`, or a
4529
- * part that decodes to bytes that are not UTF-8 is `PG_TARGET_BAD_ESCAPE`.
5156
+ * The target a `postgres://` or `postgresql://` URL names, as libpq reads one:
5157
+ * `postgres://[user[:password]@][host][:port][/dbname][?key=value&...]`. The
5158
+ * host, the port and every query key and value are percent-decoded, so a socket
5159
+ * directory is written `%2Ftmp` or passed as `?host=/tmp`; a `host` or `port`
5160
+ * in the query overrides the authority's, and other keys are ignored. The user,
5161
+ * password and database are not read here, but a bad escape in them still
5162
+ * refuses the URL. A `%` without two hex digits after it, `%00`, or a part that
5163
+ * decodes to bytes that are not UTF-8 is `PG_TARGET_BAD_ESCAPE`.
5164
+ *
4530
5165
  * The user information ends at the first `@`, as in libpq; a raw `@` after a
4531
- * `?` or after that first `@` in the authority, or a raw NUL byte anywhere,
4532
- * is `PG_TARGET_BAD_HOST`, as is a URL with no host anywhere, where libpq
4533
- * would use its default socket directory. An empty port or query value is
4534
- * refused, where libpq would take it as unset.
4535
- * The decoded host is then resolved as `pgTarget` resolves one.
5166
+ * `?` or after that first `@` in the authority, or a raw NUL byte anywhere, is
5167
+ * `PG_TARGET_BAD_HOST`, as is a URL with no host anywhere, where libpq would
5168
+ * use its default socket directory. An empty port or query value is refused,
5169
+ * where libpq would take it as unset. The decoded host is then resolved as
5170
+ * `pgTarget` resolves one.
5171
+ *
5172
+ * @param url The URL; any user or password it holds is not kept in the target.
5173
+ * @returns The target; read `failure` before anything else.
4536
5174
  */
4537
5175
  export const pgTargetUrl = (url: string): PgTarget => {
4538
5176
  let at: i32 = 0