@amritk/nish-aarch64-darwin 0.35.0 → 0.37.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (128) hide show
  1. package/INSTALL.md +73 -59
  2. package/bin/nish +0 -0
  3. package/docs/AI.md +50 -4
  4. package/package.json +1 -1
  5. package/runtime/async.d.mts +2 -0
  6. package/runtime/async.mjs +7 -0
  7. package/runtime/nish.d.ts +4849 -430
  8. package/runtime/nish.h +25 -0
  9. package/runtime/page.d.ts +53 -0
  10. package/runtime/page.mjs +146 -0
  11. package/runtime/runtime-async.c +557 -0
  12. package/runtime/runtime-wasm.c +63 -7
  13. package/runtime/vite.d.ts +30 -0
  14. package/runtime/vite.mjs +150 -0
  15. package/scripts/build.sh +252 -15
  16. package/std/README.md +107 -82
  17. package/std/base64.ts +34 -5
  18. package/std/bytes.ts +279 -59
  19. package/std/cli-args.ts +296 -70
  20. package/std/cli-flags.ts +184 -19
  21. package/std/cli.ts +475 -54
  22. package/std/collections.ts +121 -23
  23. package/std/compress/checksum.ts +44 -14
  24. package/std/compress/deflate.ts +224 -111
  25. package/std/compress/gzip.ts +217 -53
  26. package/std/compress/zlib.ts +63 -7
  27. package/std/crypto/aes.ts +128 -52
  28. package/std/crypto/base64url.ts +29 -5
  29. package/std/crypto/bcrypt-batch.ts +101 -34
  30. package/std/crypto/bcrypt.ts +93 -27
  31. package/std/crypto/chacha20poly1305.ts +69 -14
  32. package/std/crypto/ct.ts +32 -13
  33. package/std/crypto/ed25519.ts +66 -16
  34. package/std/crypto/hkdf.ts +198 -13
  35. package/std/crypto/hmac.ts +242 -37
  36. package/std/crypto/jwt.ts +204 -72
  37. package/std/crypto/p256.ts +222 -72
  38. package/std/crypto/p384.ts +51 -23
  39. package/std/crypto/pki-roots.ts +32 -2
  40. package/std/crypto/pki.ts +99 -30
  41. package/std/crypto/rsa.ts +56 -22
  42. package/std/crypto/sha1.ts +3 -0
  43. package/std/crypto/sha256.ts +24 -1
  44. package/std/crypto/sha512.ts +99 -14
  45. package/std/crypto/x25519.ts +163 -24
  46. package/std/crypto/x509-random.ts +10 -0
  47. package/std/crypto/x509.ts +133 -66
  48. package/std/host/ring.ts +124 -0
  49. package/std/json-equal.ts +31 -11
  50. package/std/json-format.ts +112 -13
  51. package/std/json-number.ts +76 -26
  52. package/std/json-pointer.ts +23 -1
  53. package/std/json-tokenizer.ts +126 -51
  54. package/std/json-typed.ts +757 -96
  55. package/std/json-value.ts +438 -157
  56. package/std/json.ts +170 -38
  57. package/std/map.ts +25 -7
  58. package/std/math.ts +36 -4
  59. package/std/net/buffer-pool.ts +42 -11
  60. package/std/net/dns-config.ts +109 -23
  61. package/std/net/dns-message.ts +62 -7
  62. package/std/net/dns-resolver.ts +247 -53
  63. package/std/net/dns.ts +203 -35
  64. package/std/net/fetch.ts +1267 -290
  65. package/std/net/handler.ts +296 -80
  66. package/std/net/hpack.ts +290 -77
  67. package/std/net/http-compress.ts +152 -36
  68. package/std/net/http-fields.ts +85 -9
  69. package/std/net/http1-client-codec.ts +129 -44
  70. package/std/net/http1-codec.ts +279 -114
  71. package/std/net/http1-server.ts +409 -139
  72. package/std/net/http2-frame.ts +289 -51
  73. package/std/net/http2-tls.ts +152 -49
  74. package/std/net/http2.ts +314 -160
  75. package/std/net/http3-frame.ts +165 -27
  76. package/std/net/http3-server.ts +282 -131
  77. package/std/net/http3.ts +377 -173
  78. package/std/net/outbound.ts +37 -3
  79. package/std/net/postgres-carrier.ts +144 -8
  80. package/std/net/postgres.ts +898 -260
  81. package/std/net/prefork.ts +202 -65
  82. package/std/net/qpack.ts +120 -32
  83. package/std/net/quic-conn-ack.ts +60 -12
  84. package/std/net/quic-conn-cid.ts +135 -27
  85. package/std/net/quic-conn-params.ts +109 -22
  86. package/std/net/quic-datagram.ts +50 -3
  87. package/std/net/quic-frame.ts +333 -23
  88. package/std/net/quic-listener.ts +161 -75
  89. package/std/net/quic-packet.ts +373 -73
  90. package/std/net/quic-recovery.ts +287 -65
  91. package/std/net/quic-stream.ts +436 -146
  92. package/std/net/quic.ts +693 -323
  93. package/std/net/router.ts +87 -40
  94. package/std/net/tls/client.ts +167 -51
  95. package/std/net/tls/codec.ts +494 -68
  96. package/std/net/tls/record-client.ts +140 -73
  97. package/std/net/tls/record-server.ts +233 -105
  98. package/std/net/tls/record.ts +142 -36
  99. package/std/net/tls/schedule.ts +235 -26
  100. package/std/net/tls/ticket.ts +161 -40
  101. package/std/net/tls/verify.ts +57 -10
  102. package/std/net/tls-tcp.ts +308 -95
  103. package/std/net/tls.ts +276 -102
  104. package/std/net/upstream.ts +81 -45
  105. package/std/net/url.ts +109 -22
  106. package/std/net/websocket.ts +140 -26
  107. package/std/net/webtransport.ts +243 -106
  108. package/std/pair.ts +10 -2
  109. package/std/random.ts +42 -15
  110. package/std/regex.ts +422 -257
  111. package/std/region.ts +70 -15
  112. package/std/secret.ts +52 -11
  113. package/std/sort.ts +17 -2
  114. package/std/sqlite.ts +256 -35
  115. package/std/sync/ring.ts +229 -56
  116. package/std/sync/shm.ts +203 -23
  117. package/std/term-io.ts +154 -78
  118. package/std/term-pixels.ts +144 -19
  119. package/std/term-probe.ts +77 -35
  120. package/std/term-rate.ts +199 -118
  121. package/std/term.ts +400 -175
  122. package/std/testing.ts +130 -32
  123. package/std/text.ts +84 -17
  124. package/std/threads.ts +248 -56
  125. package/std/yaml-json.ts +111 -97
  126. package/std/yaml-lines.ts +47 -15
  127. package/std/yaml-write.ts +45 -30
  128. package/std/yaml.ts +764 -384
package/std/sqlite.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  /**
2
- * `std/sqlite` — SQLite, the database in a file, from a Nish program.
2
+ * `nish/sqlite` (the file `std/sqlite.ts`) — SQLite, the database in a file,
3
+ * from a Nish program.
3
4
  *
4
5
  * import { openDatabase, OPEN_READWRITE, OPEN_CREATE } from "nish/sqlite"
5
6
  *
@@ -10,6 +11,15 @@
10
11
  * insert.step().expect("insert")
11
12
  * insert.reset().expect("reset")
12
13
  *
14
+ * const rows = db.prepare("SELECT id, name FROM t ORDER BY id").expect("prepare")
15
+ * const buf = new Array<u8>(64)
16
+ * while (rows.step().expect("step")) {
17
+ * const n = rows.columnInto(1, buf, 0).expect("name")
18
+ * // n > buf.length means nothing was copied: grow buf and read again
19
+ * console.log(`${rows.columnI64(0)} ${String.fromBytes(buf, 0, n)}`)
20
+ * }
21
+ * db.close().expect("close") // finalizes `insert` and `rows` too
22
+ *
13
23
  * It is the SQLite C library, vendored in `runtime/sqlite/` and linked into a
14
24
  * program that imports this module (`scripts/build.sh`), with one small C
15
25
  * adapter beside it (`runtime/sqlite/nish-sqlite.c`). A connection and a
@@ -18,9 +28,9 @@
18
28
  * `finalize` answers `MISUSE` instead of reaching freed memory.
19
29
  *
20
30
  * **The loop allocates nothing.** Every call a row makes — bind, `step`,
21
- * `reset`, `columnI64`, `columnF64`, `columnInto` — answers a `Result` of two
22
- * scalars, which travels as one machine word, and copies nothing but what it
23
- * is asked for: `columnInto` copies a text or blob column into the caller's
31
+ * `reset`, `columnI64`, `columnF64`, `columnInto` — answers a bare scalar or a
32
+ * `Result` of two scalars, which travels as one machine word, and copies
33
+ * nothing but what it is asked for: `columnInto` copies a text or blob column into the caller's
24
34
  * `u8[]` with one `memcpy`. `columnText` is the convenience that allocates a
25
35
  * string. Building a `SqliteError` allocates, which is why the hot calls answer
26
36
  * the bare result code and `error(code)` builds the message only for the
@@ -29,7 +39,10 @@
29
39
  * **Results are SQLite's own codes**, extended (`SQLITE_CONSTRAINT_UNIQUE`
30
40
  * rather than `SQLITE_CONSTRAINT`), so a program can compare them with the
31
41
  * constants below or with SQLite's documentation. `SqliteError.code` is the
32
- * primary code, the low byte.
42
+ * primary code, the low byte. `openDatabase` and `prepare` answer a built
43
+ * `SqliteError`, since they run once and the caller nearly always wants the
44
+ * message; every other call answers `Err` with the bare extended code, and
45
+ * `Database.error` or `Statement.error` turns it into a `SqliteError`.
33
46
  *
34
47
  * **Closing is explicit.** `close` finalizes every statement the connection
35
48
  * still has, so a statement never outlives its database; `finalize` frees one
@@ -151,7 +164,11 @@ export const OPEN_MEMORY: i32 = 0x80
151
164
  /** Refuse a path whose last component is a symbolic link. */
152
165
  export const OPEN_NOFOLLOW: i32 = 0x01000000
153
166
 
154
- /** The SQLite version linked in, such as `3.50.4`. */
167
+ /**
168
+ * The version of the SQLite library linked into this program.
169
+ *
170
+ * @returns The version string, such as `3.50.4`.
171
+ */
155
172
  export const sqliteVersion = (): string => sqlite3_libversion()
156
173
 
157
174
  /** A failure, with SQLite's message for it. Built only when asked for, by `error(code)`. */
@@ -163,6 +180,13 @@ export class SqliteError {
163
180
  /** SQLite's message, such as `UNIQUE constraint failed: t.id`. */
164
181
  message: string
165
182
 
183
+ /**
184
+ * Builds the error from an extended code, keeping its low byte as `code`.
185
+ *
186
+ * @param extendedCode The extended result code, such as 2067 for
187
+ * `SQLITE_CONSTRAINT_UNIQUE`; a primary code is its own extended code.
188
+ * @param message The text to report, usually SQLite's message for the code.
189
+ */
166
190
  constructor(extendedCode: i32, message: string) {
167
191
  this.code = extendedCode & 0xff
168
192
  this.extendedCode = extendedCode
@@ -197,7 +221,12 @@ const messageFor = (code: i32, connection: string): string => {
197
221
  * `OPEN_READWRITE` or `OPEN_READWRITE | OPEN_CREATE`, with any of `OPEN_URI`,
198
222
  * `OPEN_MEMORY` and `OPEN_NOFOLLOW`; anything else is `SQLITE_MISUSE`. The
199
223
  * path `:memory:` is a database of its own that lives as long as the
200
- * connection.
224
+ * connection. A failed open leaves nothing open behind it.
225
+ *
226
+ * @param path The file to open, a `file:` URI under `OPEN_URI`, or `:memory:`.
227
+ * @param flags The `OPEN_*` bits, combined with `|`.
228
+ * @returns The connection, or a `SqliteError` with SQLite's code and message,
229
+ * such as `SQLITE_CANTOPEN` for a file that cannot be opened.
201
230
  */
202
231
  export const openDatabase = (path: string, flags: i32): Result<Database, SqliteError> => {
203
232
  const h: i32 = nishsqlite_open(path, flags)
@@ -210,28 +239,56 @@ export const openDatabase = (path: string, flags: i32): Result<Database, SqliteE
210
239
  /** A connection. Close it with `close`, which finalizes its statements too. */
211
240
  export class Database {
212
241
  /** The adapter's handle; 0 names nothing. */
213
- handle: i32
242
+ private handle: i32
214
243
 
244
+ /**
245
+ * Wraps an adapter handle. A program gets a `Database` from `openDatabase`
246
+ * rather than building one. With a handle that names no connection, a call
247
+ * that can fail fails with `SQLITE_MISUSE`; `lastInsertRowid` and `changes`
248
+ * answer 0, and `error` answers a message.
249
+ *
250
+ * @param handle The adapter's connection handle.
251
+ */
215
252
  constructor(handle: i32) {
216
253
  this.handle = handle
217
254
  }
218
255
 
219
- /** Runs every statement of `sql` in turn, discarding any rows. */
256
+ /**
257
+ * Runs every statement of `sql` in turn, discarding any rows. It stops at
258
+ * the first statement that fails, so the ones before it have run.
259
+ *
260
+ * @param sql One or more SQL statements, separated by `;`.
261
+ * @returns `Ok()`, or `Err` with the extended result code of the failure.
262
+ */
220
263
  exec(sql: string): Result<void, i32> {
221
264
  return done(nishsqlite_exec(this.handle, sql))
222
265
  }
223
266
 
224
- /** `exec("BEGIN")`. */
267
+ /**
268
+ * Starts a transaction: `exec("BEGIN")`.
269
+ *
270
+ * @returns `Ok()`, or `Err` with the extended result code, such as
271
+ * `SQLITE_ERROR` inside a transaction already.
272
+ */
225
273
  begin(): Result<void, i32> {
226
274
  return this.exec("BEGIN")
227
275
  }
228
276
 
229
- /** `exec("COMMIT")`. */
277
+ /**
278
+ * Commits the open transaction: `exec("COMMIT")`.
279
+ *
280
+ * @returns `Ok()`, or `Err` with the extended result code, such as
281
+ * `SQLITE_BUSY` when another connection holds the lock.
282
+ */
230
283
  commit(): Result<void, i32> {
231
284
  return this.exec("COMMIT")
232
285
  }
233
286
 
234
- /** `exec("ROLLBACK")`. */
287
+ /**
288
+ * Undoes the open transaction: `exec("ROLLBACK")`.
289
+ *
290
+ * @returns `Ok()`, or `Err` with the extended result code.
291
+ */
235
292
  rollback(): Result<void, i32> {
236
293
  return this.exec("ROLLBACK")
237
294
  }
@@ -239,7 +296,12 @@ export class Database {
239
296
  /**
240
297
  * Compiles the first statement of `sql`, to be bound, stepped and reset as
241
298
  * often as wanted; text after it is ignored. Text with no statement in it is
242
- * `SQLITE_MISUSE`.
299
+ * `SQLITE_MISUSE`. The statement belongs to this connection, and `close`
300
+ * finalizes it.
301
+ *
302
+ * @param sql The statement, with `?` or `?N` for each parameter.
303
+ * @returns The statement, or a `SqliteError` with the code and message, such
304
+ * as a syntax error's `SQLITE_ERROR`.
243
305
  */
244
306
  prepare(sql: string): Result<Statement, SqliteError> {
245
307
  const s: i32 = nishsqlite_prepare(this.handle, sql)
@@ -249,22 +311,46 @@ export class Database {
249
311
  return Ok(new Statement(s))
250
312
  }
251
313
 
252
- /** The error for `code`, which this connection's last call answered. Ask before the next call. */
314
+ /**
315
+ * The error for `code`, which this connection's last call answered. Ask
316
+ * before the next call, since the next call replaces the connection's
317
+ * message. Allocates the `SqliteError`.
318
+ *
319
+ * @param code The extended result code an `Err` carried.
320
+ * @returns The error, with SQLite's message for it.
321
+ */
253
322
  error(code: i32): SqliteError {
254
323
  return new SqliteError(code, messageFor(code, nishsqlite_errmsg(this.handle)))
255
324
  }
256
325
 
257
- /** The rowid of the last row an INSERT on this connection made, 0 before any. */
326
+ /**
327
+ * The rowid of the last row an INSERT on this connection made.
328
+ *
329
+ * @returns The rowid, or 0 before any INSERT and for a closed connection.
330
+ */
258
331
  lastInsertRowid(): i64 {
259
332
  return nishsqlite_last_insert_rowid(this.handle)
260
333
  }
261
334
 
262
- /** The rows the last INSERT, UPDATE or DELETE changed. */
335
+ /**
336
+ * How many rows the last INSERT, UPDATE or DELETE on this connection
337
+ * changed.
338
+ *
339
+ * @returns The row count, or 0 for a closed connection.
340
+ */
263
341
  changes(): i64 {
264
342
  return nishsqlite_changes(this.handle)
265
343
  }
266
344
 
267
- /** Finalizes every statement of this connection and closes it; the handles name nothing after. */
345
+ /**
346
+ * Finalizes every statement of this connection and closes it; the handles
347
+ * name nothing after. A close that fails has still finalized the
348
+ * statements, but leaves the connection open, its message readable through
349
+ * `error`.
350
+ *
351
+ * @returns `Ok()`, or `Err` with the extended result code, such as
352
+ * `SQLITE_MISUSE` for a connection already closed.
353
+ */
268
354
  close(): Result<void, i32> {
269
355
  return done(nishsqlite_close(this.handle))
270
356
  }
@@ -276,48 +362,117 @@ export class Database {
276
362
  */
277
363
  export class Statement {
278
364
  /** The adapter's handle. */
279
- handle: i32
365
+ private handle: i32
280
366
 
367
+ /**
368
+ * Wraps an adapter handle. A program gets a `Statement` from
369
+ * `Database.prepare` rather than building one. With a handle that names no
370
+ * statement, a call that can fail fails with `SQLITE_MISUSE`, and the
371
+ * other column readers answer as for a column that is not there: 0,
372
+ * `SQLITE_NULL`, or `null`.
373
+ *
374
+ * @param handle The adapter's statement handle.
375
+ */
281
376
  constructor(handle: i32) {
282
377
  this.handle = handle
283
378
  }
284
379
 
285
- /** Binds an integer to parameter `i`. */
380
+ /**
381
+ * Binds an integer to parameter `i`.
382
+ *
383
+ * @param i The parameter's index, from 1.
384
+ * @param v The value.
385
+ * @returns `Ok()`, or `Err` with `SQLITE_RANGE` for an index the statement
386
+ * has no parameter at, `SQLITE_MISUSE` for a finalized statement or one
387
+ * stepped since its last `reset`: finished or not, it refuses binds until
388
+ * `reset`.
389
+ */
286
390
  bindI64(i: i32, v: i64): Result<void, i32> {
287
391
  return done(nishsqlite_bind_i64(this.handle, i, v))
288
392
  }
289
393
 
290
- /** Binds a floating-point value to parameter `i`. */
394
+ /**
395
+ * Binds a floating-point value to parameter `i`.
396
+ *
397
+ * @param i The parameter's index, from 1.
398
+ * @param v The value.
399
+ * @returns `Ok()`, or `Err` with the code, as for `bindI64`.
400
+ */
291
401
  bindF64(i: i32, v: f64): Result<void, i32> {
292
402
  return done(nishsqlite_bind_f64(this.handle, i, v))
293
403
  }
294
404
 
295
- /** Binds SQL NULL to parameter `i`. */
405
+ /**
406
+ * Binds SQL NULL to parameter `i`.
407
+ *
408
+ * @param i The parameter's index, from 1.
409
+ * @returns `Ok()`, or `Err` with the code, as for `bindI64`.
410
+ */
296
411
  bindNull(i: i32): Result<void, i32> {
297
412
  return done(nishsqlite_bind_null(this.handle, i))
298
413
  }
299
414
 
300
- /** Binds `text` to parameter `i`; SQLite copies it. */
415
+ /**
416
+ * Binds `text` to parameter `i`; SQLite copies it, so the string need not
417
+ * outlive the call. The text ends at its first NUL.
418
+ *
419
+ * @param i The parameter's index, from 1.
420
+ * @param text The value.
421
+ * @returns `Ok()`, or `Err` with the code, as for `bindI64`, or
422
+ * `SQLITE_TOOBIG` or `SQLITE_NOMEM` from SQLite.
423
+ */
301
424
  bindText(i: i32, text: string): Result<void, i32> {
302
425
  return done(nishsqlite_bind_text(this.handle, i, text))
303
426
  }
304
427
 
305
- /** Binds `buf[off, off + len)` as text, copied; a window outside `buf` is `SQLITE_MISUSE`. */
428
+ /**
429
+ * Binds `buf[off, off + len)` as text, copied, so `buf` may change after
430
+ * the call; a window outside `buf` is `SQLITE_MISUSE`. The bytes should be
431
+ * UTF-8 and may hold a NUL.
432
+ *
433
+ * @param i The parameter's index, from 1.
434
+ * @param buf The bytes to read from.
435
+ * @param off Where the text starts in `buf`, in bytes.
436
+ * @param len The text's length in bytes.
437
+ * @returns `Ok()`, or `Err` with the code, as for `bindI64`, or
438
+ * `SQLITE_TOOBIG` or `SQLITE_NOMEM` from SQLite.
439
+ */
306
440
  bindTextBytes(i: i32, buf: readonly u8[], off: i32, len: i32): Result<void, i32> {
307
441
  return done(nishsqlite_bind_bytes(this.handle, i, buf, toU64(buf.length), off, len, 0))
308
442
  }
309
443
 
310
- /** Binds `buf[off, off + len)` as a blob, copied; a window outside `buf` is `SQLITE_MISUSE`. */
444
+ /**
445
+ * Binds `buf[off, off + len)` as a blob, copied, so `buf` may change after
446
+ * the call; a window outside `buf` is `SQLITE_MISUSE`.
447
+ *
448
+ * @param i The parameter's index, from 1.
449
+ * @param buf The bytes to read from.
450
+ * @param off Where the blob starts in `buf`, in bytes.
451
+ * @param len The blob's length in bytes.
452
+ * @returns `Ok()`, or `Err` with the code, as for `bindI64`, or
453
+ * `SQLITE_TOOBIG` or `SQLITE_NOMEM` from SQLite.
454
+ */
311
455
  bindBlob(i: i32, buf: readonly u8[], off: i32, len: i32): Result<void, i32> {
312
456
  return done(nishsqlite_bind_bytes(this.handle, i, buf, toU64(buf.length), off, len, 1))
313
457
  }
314
458
 
315
- /** Clears every parameter back to NULL. */
459
+ /**
460
+ * Clears every parameter back to NULL. `reset` keeps the bindings, so this
461
+ * is the call for a run that must not see the last one's values.
462
+ *
463
+ * @returns `Ok()`, or `Err` with `SQLITE_MISUSE` for a finalized statement.
464
+ */
316
465
  clearBindings(): Result<void, i32> {
317
466
  return done(nishsqlite_clear_bindings(this.handle))
318
467
  }
319
468
 
320
- /** Runs the statement to its next row: `true` with a row to read, `false` when it has finished. */
469
+ /**
470
+ * Runs the statement to its next row. Call `reset` to run it again from
471
+ * the start, with the same bindings.
472
+ *
473
+ * @returns `true` with a row to read, `false` when it has finished, or `Err`
474
+ * with the extended result code, such as `SQLITE_CONSTRAINT_UNIQUE`.
475
+ */
321
476
  step(): Result<boolean, i32> {
322
477
  const rc: i32 = nishsqlite_step(this.handle)
323
478
  if (rc === SQLITE_ROW) {
@@ -329,42 +484,94 @@ export class Statement {
329
484
  return Err(rc)
330
485
  }
331
486
 
332
- /** Rewinds the statement to run again, keeping its bindings. */
487
+ /**
488
+ * Rewinds the statement to run again, keeping its bindings. A failure of
489
+ * the last `step` is not answered again here: `step` already answered it.
490
+ *
491
+ * @returns `Ok()`, or `Err` with `SQLITE_MISUSE` for a finalized statement.
492
+ */
333
493
  reset(): Result<void, i32> {
334
494
  return done(nishsqlite_reset(this.handle))
335
495
  }
336
496
 
337
- /** Frees the statement; its handle names nothing after. */
497
+ /**
498
+ * Frees the statement early; its handle names nothing after. Without this,
499
+ * `Database.close` frees it.
500
+ *
501
+ * @returns `Ok()`, or `Err` with `SQLITE_MISUSE` for a statement already
502
+ * finalized or whose connection is closed.
503
+ */
338
504
  finalize(): Result<void, i32> {
339
505
  return done(nishsqlite_finalize(this.handle))
340
506
  }
341
507
 
342
- /** The number of columns a row has. */
508
+ /**
509
+ * The number of columns a row of this statement has, known from `prepare`
510
+ * on, before the first `step`.
511
+ *
512
+ * @returns The column count, or 0 for a statement that returns no rows (an
513
+ * INSERT, say) and for a finalized one.
514
+ */
343
515
  columnCount(): i32 {
344
516
  return nishsqlite_column_count(this.handle)
345
517
  }
346
518
 
347
- /** The type of column `c` in this row, `SQLITE_INTEGER` to `SQLITE_NULL`; `SQLITE_NULL` for a column that is not there. */
519
+ /**
520
+ * The type of column `c` in the current row.
521
+ *
522
+ * @param c The column's index, from 0.
523
+ * @returns One of `SQLITE_INTEGER` to `SQLITE_NULL`; `SQLITE_NULL` for a
524
+ * column that is not there or when no row is current.
525
+ */
348
526
  columnType(c: i32): i32 {
349
527
  return nishsqlite_column_type(this.handle, c)
350
528
  }
351
529
 
352
- /** Column `c` as an integer, converted as SQLite converts; 0 for NULL or a column that is not there. */
530
+ /**
531
+ * Column `c` of the current row as an integer, converted as SQLite
532
+ * converts (text `"12abc"` is 12, a float is truncated).
533
+ *
534
+ * @param c The column's index, from 0.
535
+ * @returns The value; 0 for NULL, a column that is not there, or when no
536
+ * row is current.
537
+ */
353
538
  columnI64(c: i32): i64 {
354
539
  return nishsqlite_column_i64(this.handle, c)
355
540
  }
356
541
 
357
- /** Column `c` as a floating-point value; 0 for NULL or a column that is not there. */
542
+ /**
543
+ * Column `c` of the current row as a floating-point value, converted as
544
+ * SQLite converts.
545
+ *
546
+ * @param c The column's index, from 0.
547
+ * @returns The value; 0 for NULL, a column that is not there, or when no
548
+ * row is current.
549
+ */
358
550
  columnF64(c: i32): f64 {
359
551
  return nishsqlite_column_f64(this.handle, c)
360
552
  }
361
553
 
362
- /** The bytes `columnInto` would copy for column `c`. */
554
+ /**
555
+ * How many bytes `columnInto` would copy for column `c`: a blob's length,
556
+ * or anything else's length as text. Ask it to size a buffer before the
557
+ * copy.
558
+ *
559
+ * @param c The column's index, from 0.
560
+ * @returns The length in bytes, without a terminating NUL; 0 for NULL, a
561
+ * column that is not there, or when no row is current.
562
+ */
363
563
  columnBytes(c: i32): i32 {
364
564
  return nishsqlite_column_bytes(this.handle, c)
365
565
  }
366
566
 
367
- /** Column `c` as a new string, cut at its first NUL; `null` for NULL or a column that is not there. Allocates. */
567
+ /**
568
+ * Column `c` of the current row as a new string, cut at its first NUL.
569
+ * Allocates on every call; `columnInto` is the call for a hot loop.
570
+ *
571
+ * @param c The column's index, from 0.
572
+ * @returns The text, or `null` for NULL, a column that is not there, or
573
+ * when no row is current.
574
+ */
368
575
  columnText(c: i32): string | null {
369
576
  return nishsqlite_column_text(this.handle, c)
370
577
  }
@@ -375,6 +582,13 @@ export class Statement {
375
582
  * a length larger than `buf.length - at` means nothing was written and
376
583
  * says how much room is needed. `SQLITE_RANGE` for a column that is not
377
584
  * there, `SQLITE_MISUSE` for an `at` outside `0..buf.length`.
585
+ *
586
+ * @param c The column's index, from 0.
587
+ * @param buf The caller's buffer, written in place.
588
+ * @param at Where in `buf` the copy starts, in bytes.
589
+ * @returns The column's length in bytes (0 for NULL, or when no row is
590
+ * current), or `Err` with `SQLITE_RANGE`, `SQLITE_MISUSE`, or
591
+ * `SQLITE_NOMEM` when SQLite cannot convert the value to text.
378
592
  */
379
593
  columnInto(c: i32, buf: u8[], at: i32): Result<i32, i32> {
380
594
  const n: i32 = nishsqlite_column_into(this.handle, c, buf, toU64(buf.length), at)
@@ -384,7 +598,14 @@ export class Statement {
384
598
  return Ok(n)
385
599
  }
386
600
 
387
- /** The error for `code`, which this statement's last call answered. Ask before the next call. */
601
+ /**
602
+ * The error for `code`, which this statement's last call answered. Ask
603
+ * before the next call, since the next call on the connection replaces its
604
+ * message. Allocates the `SqliteError`.
605
+ *
606
+ * @param code The extended result code an `Err` carried.
607
+ * @returns The error, with SQLite's message for it.
608
+ */
388
609
  error(code: i32): SqliteError {
389
610
  return new SqliteError(code, messageFor(code, nishsqlite_stmt_errmsg(this.handle)))
390
611
  }