@tinyshed/tinystore 0.1.0 → 0.2.0-rc.1

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 (71) hide show
  1. package/dist/blobs.d.ts +1 -1
  2. package/dist/blobs.js +13 -5
  3. package/dist/cancel.d.ts +16 -2
  4. package/dist/cancel.js +36 -2
  5. package/dist/channels.js +20 -6
  6. package/dist/config.d.ts +49 -1
  7. package/dist/config.js +86 -7
  8. package/dist/connection.d.ts +52 -10
  9. package/dist/connection.js +305 -73
  10. package/dist/handles.d.ts +10 -1
  11. package/dist/handles.js +27 -4
  12. package/dist/index.d.ts +5 -5
  13. package/dist/jobs.d.ts +35 -1
  14. package/dist/jobs.js +46 -0
  15. package/dist/logger.d.ts +22 -10
  16. package/dist/logger.js +118 -28
  17. package/dist/metrics.d.ts +24 -1
  18. package/dist/metrics.js +24 -1
  19. package/dist/query.js +33 -9
  20. package/dist/records.d.ts +48 -7
  21. package/dist/records.js +22 -3
  22. package/dist/runtime/addon.js +3 -2
  23. package/dist/runtime/bun.js +33 -12
  24. package/dist/runtime/node.js +30 -8
  25. package/dist/runtime/pipe.d.ts +2 -0
  26. package/dist/runtime/pipe.js +45 -20
  27. package/dist/runtime/shared.d.ts +28 -4
  28. package/dist/runtime/shared.js +125 -13
  29. package/dist/runtime.d.ts +28 -6
  30. package/dist/session.d.ts +9 -5
  31. package/dist/session.js +113 -31
  32. package/dist/sql.d.ts +18 -5
  33. package/dist/sql.js +44 -11
  34. package/dist/store.d.ts +25 -11
  35. package/dist/store.js +67 -9
  36. package/dist/time.d.ts +2 -0
  37. package/dist/wire/codec.d.ts +5 -0
  38. package/dist/wire/codec.js +10 -0
  39. package/dist/wire/frame.d.ts +2 -0
  40. package/dist/wire/frame.js +4 -0
  41. package/dist/wire/msgpack.d.ts +7 -3
  42. package/dist/wire/msgpack.js +11 -4
  43. package/dist/wire/protocol.d.ts +280 -36
  44. package/dist/wire/protocol.js +510 -102
  45. package/package.json +9 -8
  46. package/src/blobs.ts +13 -5
  47. package/src/cancel.ts +44 -2
  48. package/src/channels.ts +21 -6
  49. package/src/config.ts +138 -12
  50. package/src/connection.ts +377 -77
  51. package/src/handles.ts +32 -4
  52. package/src/index.ts +6 -1
  53. package/src/jobs.ts +66 -0
  54. package/src/logger.ts +158 -40
  55. package/src/metrics.ts +53 -2
  56. package/src/query.ts +33 -13
  57. package/src/records.ts +73 -10
  58. package/src/runtime/addon.ts +3 -2
  59. package/src/runtime/bun.ts +44 -9
  60. package/src/runtime/node.ts +30 -5
  61. package/src/runtime/pipe.ts +49 -19
  62. package/src/runtime/shared.ts +137 -16
  63. package/src/runtime.ts +31 -6
  64. package/src/session.ts +129 -30
  65. package/src/sql.ts +48 -14
  66. package/src/store.ts +81 -14
  67. package/src/time.ts +3 -0
  68. package/src/wire/codec.ts +11 -0
  69. package/src/wire/frame.ts +5 -0
  70. package/src/wire/msgpack.ts +11 -4
  71. package/src/wire/protocol.ts +532 -104
@@ -1,12 +1,103 @@
1
- // What Bun's runtime and Node's do alike: an endpoint read into an address, a
2
- // sidecar started through node:child_process, which both implement, and the
3
- // last lines of a child's stderr.
1
+ // What Bun's runtime and Node's do alike: the loop's turns between the answers
2
+ // of the core in this process, an endpoint read into an address, a sidecar
3
+ // started through node:child_process, which both implement, and the last
4
+ // lines of a child's stderr.
4
5
 
5
- import { spawn } from 'node:child_process'
6
+ import { type ChildProcess, spawn } from 'node:child_process'
6
7
  import { readdirSync } from 'node:fs'
7
8
 
8
- import { ClosedError } from '../errors.ts'
9
- import type { Child } from '../runtime.ts'
9
+ import { ClosedError, InUseError, type TinystoreError } from '../errors.ts'
10
+ import type { Detached } from '../runtime.ts'
11
+
12
+ /**
13
+ * The error of an open in this process that failed, which the core gives as a
14
+ * message alone: in use when another process holds the directory, as a
15
+ * sidecar does after its last client closed, closed otherwise.
16
+ */
17
+ export function openFailure(dir: string, message: string): TinystoreError {
18
+ const failure = message.includes('in use') ? InUseError : ClosedError
19
+ return new failure(`cannot open ${dir}: ${message}`)
20
+ }
21
+
22
+ /** The writes in a row an event loop's one turn sends the core in this process. */
23
+ const sendsATurn = 64
24
+
25
+ /**
26
+ * Lets the event loop turn between answers the core in this process gives
27
+ * inside the write that asked. Each such answer resolves its promise in a
28
+ * microtask, so a loop of awaited reads would never let a timer or a socket
29
+ * run (research release-2026-10-23); every `sendsATurn` writes in one turn,
30
+ * the next waits for `setImmediate`, and those after it wait behind it.
31
+ */
32
+ export function turning(send: (bytes: Uint8Array) => void): (bytes: Uint8Array) => void {
33
+ let sent = 0
34
+ let held: Uint8Array[] | undefined
35
+ const turned = (): void => {
36
+ sent = 0
37
+ const sending = held ?? []
38
+ held = undefined
39
+ for (const bytes of sending) {
40
+ write(bytes)
41
+ }
42
+ }
43
+ const write = (bytes: Uint8Array): void => {
44
+ if (held !== undefined) {
45
+ held.push(bytes)
46
+ return
47
+ }
48
+ if (sent === 0) {
49
+ setImmediate(turned)
50
+ }
51
+ sent++
52
+ if (sent > sendsATurn) {
53
+ held = [bytes]
54
+ return
55
+ }
56
+ send(bytes)
57
+ }
58
+ return write
59
+ }
60
+
61
+ /**
62
+ * What a connect gives once it has connected, unless the signal aborts
63
+ * first: the caller is then rejected with the signal's reason, and what
64
+ * connects after is let go, since nobody waits for it.
65
+ */
66
+ export function connecting<T>(
67
+ made: Promise<T>,
68
+ signal: AbortSignal | undefined,
69
+ letGo: (late: T) => void,
70
+ ): Promise<T> {
71
+ if (signal === undefined) {
72
+ return made
73
+ }
74
+ return new Promise<T>((resolve, reject) => {
75
+ let aborted = false
76
+ const abort = () => {
77
+ aborted = true
78
+ reject(signal.reason)
79
+ }
80
+ if (signal.aborted) {
81
+ abort()
82
+ } else {
83
+ signal.addEventListener('abort', abort, { once: true })
84
+ }
85
+ made.then(
86
+ value => {
87
+ signal.removeEventListener('abort', abort)
88
+ if (aborted) {
89
+ letGo(value)
90
+ } else {
91
+ resolve(value)
92
+ }
93
+ },
94
+ (err: unknown) => {
95
+ signal.removeEventListener('abort', abort)
96
+ reject(err)
97
+ },
98
+ )
99
+ })
100
+ }
10
101
 
11
102
  /** Where an endpoint named in SERVE, or given to connect, is. */
12
103
  export type Address =
@@ -32,20 +123,50 @@ export function address(endpoint: string): Address {
32
123
  /**
33
124
  * Starts a sidecar that outlives this process, through node:child_process in
34
125
  * Bun too, since Bun.spawn starts no process that outlives a Ctrl-C of its
35
- * parent's group.
126
+ * parent's group. Its stderr is read while it starts, since a start that
127
+ * fails before its log opens says why there alone, and let go after: a pipe
128
+ * still read would keep this process's event loop alive.
36
129
  */
37
- export function spawnDetached(argv: string[]): Child {
38
- const child = spawn(argv[0]!, argv.slice(1), {
39
- detached: true,
40
- stdio: 'ignore',
41
- windowsHide: true,
130
+ export function spawnDetached(argv: string[]): Detached {
131
+ let child: ChildProcess
132
+ try {
133
+ child = spawn(argv[0]!, argv.slice(1), {
134
+ detached: true,
135
+ stdio: ['ignore', 'ignore', 'pipe'],
136
+ windowsHide: true,
137
+ })
138
+ } catch (err) {
139
+ const exited = Promise.reject(err)
140
+ exited.catch(() => {})
141
+ return { exited, stderr: () => '', release: () => {} }
142
+ }
143
+ const stderr = child.stderr!
144
+ let kept = ''
145
+ stderr.setEncoding('utf8')
146
+ stderr.on('data', (text: string) => {
147
+ kept = (kept + text).slice(-stderrKept)
42
148
  })
43
- const exited = new Promise<number>(resolve => {
44
- child.once('exit', code => resolve(code ?? -1))
45
- child.once('error', () => resolve(-1))
149
+ stderr.on('error', () => {})
150
+ const exited = new Promise<{ code: number; stderr: string }>((resolve, reject) => {
151
+ child.once('error', reject)
152
+ // close comes once the child has exited and its stderr has ended
153
+ child.once('close', code => resolve({ code: code ?? -1, stderr: kept }))
46
154
  })
155
+ exited.catch(() => {})
47
156
  child.unref()
48
- return { exited, kill: () => child.kill() }
157
+ return { exited, stderr: () => kept, release: () => stderr.destroy() }
158
+ }
159
+
160
+ /** Why a process did not start, in the words every SDK uses: not found, permission denied, or the system's own. */
161
+ export function notStarted(err: unknown): string {
162
+ const code = (err as { code?: unknown } | undefined)?.code
163
+ if (code === 'ENOENT') {
164
+ return 'not found'
165
+ }
166
+ if (code === 'EACCES' || code === 'EPERM') {
167
+ return 'permission denied'
168
+ }
169
+ return err instanceof Error ? err.message : String(err)
49
170
  }
50
171
 
51
172
  /** How much of a child's stderr is kept, its last lines, to say why it ended. */
package/src/runtime.ts CHANGED
@@ -38,16 +38,41 @@ export interface PrivateChild extends Child {
38
38
  stderr(): string
39
39
  }
40
40
 
41
+ /** A sidecar this process started, which outlives it, while it starts. */
42
+ export interface Detached {
43
+ /**
44
+ * Its exit code once it has exited and its stderr has ended, with the last
45
+ * of what it wrote there; it rejects with why it never started.
46
+ */
47
+ readonly exited: Promise<{ code: number; stderr: string }>
48
+ /** the last of what it wrote to stderr so far */
49
+ stderr(): string
50
+ /** Stops reading its stderr once its start is over: what it writes there later goes nowhere. */
51
+ release(): void
52
+ }
53
+
41
54
  export interface Runtime {
42
55
  /** a name and version for the server's logs: tinystore-js on bun/1.4.2 */
43
56
  readonly client: string
44
57
  readonly windows: boolean
45
- /** Connects to an endpoint: unix://path, pipe:name, tcp://host:port or tls://host:port. */
46
- connect(endpoint: string, events: TransportEvents, tls?: TlsOptions): Promise<Transport>
47
- /** Starts a private server whose stdin and stdout carry the frames. */
48
- spawnPrivate(argv: string[], events: TransportEvents): PrivateChild
49
- /** Starts a process that outlives this one, with no stdio to read. */
50
- spawnDetached(argv: string[]): Child
58
+ /**
59
+ * Connects to an endpoint: unix://path, pipe:name, tcp://host:port or
60
+ * tls://host:port. A signal that aborts first rejects with its reason and
61
+ * lets the socket go.
62
+ */
63
+ connect(
64
+ endpoint: string,
65
+ events: TransportEvents,
66
+ tls?: TlsOptions,
67
+ signal?: AbortSignal,
68
+ ): Promise<Transport>
69
+ /**
70
+ * Starts a private server whose stdin and stdout carry the frames, once it
71
+ * has started; it rejects with why it did not.
72
+ */
73
+ spawnPrivate(argv: string[], events: TransportEvents): Promise<PrivateChild>
74
+ /** Starts a process that outlives this one, its stderr read while it starts. */
75
+ spawnDetached(argv: string[]): Detached
51
76
  /** A file's bytes, opened, read and closed at once; undefined when it is not there. */
52
77
  readFile(path: string): Promise<Uint8Array | undefined>
53
78
  /** The executable a name finds on PATH. */
package/src/session.ts CHANGED
@@ -6,7 +6,7 @@
6
6
 
7
7
  import { createHmac, timingSafeEqual } from 'node:crypto'
8
8
 
9
- import { currentSignal } from './cancel.ts'
9
+ import { checkSignal, currentSignal, unlessCancelled } from './cancel.ts'
10
10
  import {
11
11
  CancelledError,
12
12
  ClosedError,
@@ -18,6 +18,7 @@ import {
18
18
  } from './errors.ts'
19
19
  import type { Read } from './wire/codec.ts'
20
20
  import {
21
+ bodyLength,
21
22
  checkHeader,
22
23
  credit,
23
24
  Flag,
@@ -105,6 +106,7 @@ export class Stream {
105
106
  #creditWaiters: Waiter<void>[] = []
106
107
  #granting = 0
107
108
  #cancelled = false
109
+ #finishing: (() => void)[] = []
108
110
 
109
111
  constructor(session: Session, id: number, method: number, uploadCredit: number) {
110
112
  this.#session = session
@@ -161,15 +163,23 @@ export class Stream {
161
163
  /**
162
164
  * Asks the server to stop. A stream whose REQUEST has not left never
163
165
  * leaves; one that has keeps its number until the server's final frame,
164
- * which is dropped.
166
+ * which is dropped. What waits on it fails with `failure`.
165
167
  */
166
- cancel(): void {
168
+ cancel(failure: Error = new CancelledError('the call was cancelled')): void {
167
169
  if (this.finished || this.#cancelled) {
168
170
  return
169
171
  }
170
172
  this.#cancelled = true
171
173
  this.#session.cancel(this)
172
- this.fail(new CancelledError('the call was cancelled'))
174
+ this.fail(failure)
175
+ }
176
+
177
+ /** Resolves once the server's final frame came, or the connection ended. */
178
+ finishing(): Promise<void> {
179
+ if (this.finished) {
180
+ return Promise.resolve()
181
+ }
182
+ return new Promise(resolve => this.#finishing.push(resolve))
173
183
  }
174
184
 
175
185
  get cancelled(): boolean {
@@ -212,6 +222,9 @@ export class Stream {
212
222
  for (const w of this.#creditWaiters.splice(0)) {
213
223
  w.resolve()
214
224
  }
225
+ for (const finished of this.#finishing.splice(0)) {
226
+ finished()
227
+ }
215
228
  this.#unwatch?.()
216
229
  this.#unwatch = undefined
217
230
  }
@@ -279,7 +292,9 @@ export class Session {
279
292
  readonly #leave = () => this.#flush()
280
293
  readonly #reader = new Reader(new Uint8Array(0))
281
294
 
282
- #rest: Uint8Array | undefined
295
+ // a frame's first part, as long as the whole frame, and how much of it came
296
+ #partial: Uint8Array | undefined
297
+ #gathered = 0
283
298
  #goingAway = false
284
299
  #ended: Error | undefined
285
300
  readonly #endListeners: ((err: Error) => void)[] = []
@@ -341,19 +356,20 @@ export class Session {
341
356
  /**
342
357
  * Opens a stream with its REQUEST. End says the REQUEST is the client's
343
358
  * whole side; an upload's DATA follows through the stream otherwise. It
344
- * waits while the streams in flight are all in use.
359
+ * waits for the WELCOME, and while the streams in flight are all in use,
360
+ * each wait until the caller's signal aborts.
345
361
  */
346
362
  async open(method: number, body: Uint8Array, end: boolean): Promise<Stream> {
347
363
  const signal = currentSignal()
348
- signal?.throwIfAborted()
349
- const agreed = await this.welcomed
364
+ checkSignal(signal)
365
+ const agreed = await unlessCancelled(this.welcomed, signal)
350
366
  if (body.length > agreed.maxBody) {
351
367
  throw new LimitError(
352
368
  `a request of ${body.length} bytes, past the ${agreed.maxBody} a body holds`,
353
369
  )
354
370
  }
355
371
  while (this.#streams.size >= agreed.inFlight && this.#usable() === undefined) {
356
- await new Promise<void>((resolve, reject) => this.#waitingToOpen.push({ resolve, reject }))
372
+ await this.#streamFreed(signal)
357
373
  }
358
374
  const refused = this.#usable()
359
375
  if (refused !== undefined) {
@@ -373,6 +389,38 @@ export class Session {
373
389
  return stream
374
390
  }
375
391
 
392
+ /**
393
+ * Waits for a stream to free; a caller whose signal aborts gives up its
394
+ * place in the line, which the next caller then has.
395
+ */
396
+ #streamFreed(signal: AbortSignal | undefined): Promise<void> {
397
+ return new Promise<void>((resolve, reject) => {
398
+ const abort = () => {
399
+ const at = this.#waitingToOpen.indexOf(waiter)
400
+ if (at >= 0) {
401
+ this.#waitingToOpen.splice(at, 1)
402
+ }
403
+ reject(new CancelledError('the call was cancelled'))
404
+ }
405
+ const waiter: Waiter<void> = {
406
+ resolve: () => {
407
+ signal?.removeEventListener('abort', abort)
408
+ resolve()
409
+ },
410
+ reject: err => {
411
+ signal?.removeEventListener('abort', abort)
412
+ reject(err)
413
+ },
414
+ }
415
+ this.#waitingToOpen.push(waiter)
416
+ if (signal?.aborted) {
417
+ abort()
418
+ return
419
+ }
420
+ signal?.addEventListener('abort', abort, { once: true })
421
+ })
422
+ }
423
+
376
424
  /** Why no stream may open now: the connection ended or is going away. */
377
425
  #usable(): Error | undefined {
378
426
  if (this.#ended !== undefined) {
@@ -437,7 +485,7 @@ export class Session {
437
485
 
438
486
  /** A call: one REQUEST, and the RESPONSE that answers it. */
439
487
  async call(method: number, body: Uint8Array, signal?: AbortSignal): Promise<Uint8Array> {
440
- signal?.throwIfAborted()
488
+ checkSignal(signal)
441
489
  const stream = await this.open(method, body, true)
442
490
  const unwatch = watch(signal, stream)
443
491
  try {
@@ -524,21 +572,21 @@ export class Session {
524
572
 
525
573
  cancel(stream: Stream): void {
526
574
  if (!stream.sent) {
527
- this.#queue = this.#queue.filter(q => q.stream !== stream)
528
575
  this.#release(stream)
529
576
  return
530
577
  }
531
578
  this.post(frame(Kind.cancel, 0, 0, stream.id, new Uint8Array(0)))
532
579
  }
533
580
 
534
- // takes a stream out of use, dropping what of it has not left: its number
535
- // may be named again at once
581
+ // takes a stream out of use, dropping what of it has not left, its
582
+ // REQUEST too: its number may be named again at once, and a REQUEST left
583
+ // queued would leave on a number the session no longer knows
536
584
  #release(stream: Stream): void {
537
585
  stream.finish()
538
586
  if (this.#streams.get(stream.id) === stream) {
539
587
  this.#streams.delete(stream.id)
540
588
  }
541
- this.#queue = this.#queue.filter(q => q.stream !== stream || q.request)
589
+ this.#queue = this.#queue.filter(q => q.stream !== stream)
542
590
  this.#waitingToOpen.shift()?.resolve()
543
591
  }
544
592
 
@@ -547,16 +595,54 @@ export class Session {
547
595
  if (this.#ended !== undefined) {
548
596
  return
549
597
  }
550
- let bytes = chunk
551
- if (this.#rest !== undefined) {
552
- bytes = new Uint8Array(this.#rest.length + chunk.length)
553
- bytes.set(this.#rest)
554
- bytes.set(chunk, this.#rest.length)
555
- this.#rest = undefined
598
+ const at = this.#partial === undefined ? 0 : this.#gather(chunk)
599
+ if (at === chunk.length || this.#ended !== undefined) {
600
+ return
556
601
  }
557
- const at = this.read(bytes, bytes.length)
558
- if (at < bytes.length && this.#ended === undefined) {
559
- this.#rest = bytes.slice(at)
602
+ const rest = chunk.subarray(at)
603
+ const taken = this.read(rest, rest.length)
604
+ if (taken < rest.length && this.#ended === undefined) {
605
+ this.#hold(rest.subarray(taken))
606
+ }
607
+ }
608
+
609
+ // Keeps a frame's first part in bytes as long as the whole frame, once
610
+ // its header has come, which `read` has checked: the rest is written
611
+ // behind it as it comes. A mebibyte that came in sixteen pieces was
612
+ // copied again for each piece before (issue #10).
613
+ #hold(part: Uint8Array): void {
614
+ const length = part.length < headerSize ? headerSize : headerSize + bodyLength(part)
615
+ this.#partial = new Uint8Array(length)
616
+ this.#partial.set(part)
617
+ this.#gathered = part.length
618
+ }
619
+
620
+ // writes the chunk's first bytes behind the frame held, reads the frame
621
+ // once it is whole, and says how many of the chunk's bytes it took
622
+ #gather(chunk: Uint8Array): number {
623
+ let at = 0
624
+ for (;;) {
625
+ const partial = this.#partial
626
+ if (partial === undefined) {
627
+ return at
628
+ }
629
+ const taken = Math.min(chunk.length - at, partial.length - this.#gathered)
630
+ partial.set(chunk.subarray(at, at + taken), this.#gathered)
631
+ this.#gathered += taken
632
+ at += taken
633
+ if (this.#gathered < partial.length) {
634
+ return at
635
+ }
636
+ this.#partial = undefined
637
+ if (partial.length === headerSize && bodyLength(partial) > 0) {
638
+ // only its header had come, which says how long the frame is
639
+ this.read(partial, headerSize)
640
+ if (this.#ended === undefined) {
641
+ this.#hold(partial)
642
+ }
643
+ continue
644
+ }
645
+ this.read(partial, partial.length, true)
560
646
  }
561
647
  }
562
648
 
@@ -564,9 +650,10 @@ export class Session {
564
650
  * Takes the frames whole in the first `length` bytes and says how many
565
651
  * bytes they were: the rest is a frame's first part, which whoever owns
566
652
  * the bytes keeps for its end. Nothing of the bytes is kept here, so their
567
- * owner may write them over once this returns.
653
+ * owner may write them over once this returns, unless they are `kept`:
654
+ * bytes given to the session, whose bodies are views of them.
568
655
  */
569
- read(bytes: Uint8Array, length: number): number {
656
+ read(bytes: Uint8Array, length: number, kept = false): number {
570
657
  if (this.#ended !== undefined) {
571
658
  return length
572
659
  }
@@ -579,7 +666,7 @@ export class Session {
579
666
  if (stop > length) {
580
667
  break
581
668
  }
582
- this.#take(h, bytes, at + headerSize, stop)
669
+ this.#take(h, bytes, at + headerSize, stop, kept)
583
670
  at = stop
584
671
  }
585
672
  } catch (err) {
@@ -590,9 +677,15 @@ export class Session {
590
677
  }
591
678
 
592
679
  // takes the frame whose body is the bytes from `from` to `to`
593
- #take(h: ReturnType<typeof parseHeader>, bytes: Uint8Array, from: number, to: number): void {
680
+ #take(
681
+ h: ReturnType<typeof parseHeader>,
682
+ bytes: Uint8Array,
683
+ from: number,
684
+ to: number,
685
+ kept: boolean,
686
+ ): void {
594
687
  if (this.#agreed !== undefined && (h.kind === Kind.response || h.kind === Kind.data)) {
595
- this.#answer(h, bytes, from, to)
688
+ this.#answer(h, bytes, from, to, kept)
596
689
  return
597
690
  }
598
691
  const body = bytes.slice(from, to)
@@ -659,7 +752,13 @@ export class Session {
659
752
  this.#welcome.resolve(agreed)
660
753
  }
661
754
 
662
- #answer(h: ReturnType<typeof parseHeader>, bytes: Uint8Array, from: number, to: number): void {
755
+ #answer(
756
+ h: ReturnType<typeof parseHeader>,
757
+ bytes: Uint8Array,
758
+ from: number,
759
+ to: number,
760
+ kept: boolean,
761
+ ): void {
663
762
  const { kind, flags, stream: id } = h
664
763
  const stream = this.#streams.get(id)
665
764
  if (stream === undefined) {
@@ -670,7 +769,7 @@ export class Session {
670
769
  return
671
770
  }
672
771
  // a body of its own, since events outlive the read's buffer
673
- const body = bytes.slice(from, to)
772
+ const body = kept ? bytes.subarray(from, to) : bytes.slice(from, to)
674
773
  const end = (flags & Flag.end) !== 0
675
774
  if (end) {
676
775
  this.#release(stream)
package/src/sql.ts CHANGED
@@ -11,7 +11,7 @@ import { join } from 'node:path'
11
11
  import { type Channel, channelParts, type TxChannel, txChannel } from './channels.ts'
12
12
  import type { Connection, Durability, Idempotence, Link } from './connection.ts'
13
13
  import { checkDurability, download } from './connection.ts'
14
- import { errorOf, InvalidError } from './errors.ts'
14
+ import { CancelledError, errorOf, InvalidError, OutcomeUnknownError } from './errors.ts'
15
15
  import {
16
16
  askByCall,
17
17
  checkName,
@@ -22,6 +22,8 @@ import {
22
22
  viaLink,
23
23
  } from './handles.ts'
24
24
  import {
25
+ Adding,
26
+ addingIn,
25
27
  openQueue,
26
28
  type Queue,
27
29
  type QueueOptions,
@@ -34,7 +36,7 @@ import { Bucket, type BucketOptions, bucketOpen, partsOf, type Values, valuesOf
34
36
  import { Table, type TableOptions } from './query.ts'
35
37
  import type { StandardSchemaV1 } from './schema.ts'
36
38
  import { TableIndex, type TableIndexOptions, tableIndexOpen } from './search.ts'
37
- import type { Stream } from './session.ts'
39
+ import { ConnectionLostError, type Stream } from './session.ts'
38
40
  import type { SqlArg, SqlValue } from './wire/codec.ts'
39
41
  import { int64Of } from './wire/msgpack.ts'
40
42
  import {
@@ -889,21 +891,32 @@ export class Database implements Runner, Home {
889
891
  return new Table(this, name, options)
890
892
  }
891
893
 
892
- /** Statements known before they run, written as one: all of them or none, in a shared commit. */
893
- async batch(statements: readonly Sql[]): Promise<Done[]> {
894
- const texts = statements.map(each => {
895
- if (!(each instanceof Sql)) {
896
- throw new InvalidError('a batch takes pieces of SQL: sql`…`')
894
+ /**
895
+ * Writes known before they run, written as one: all of them or none, in a
896
+ * shared commit, and what each did, in their order. A write is a statement,
897
+ * or a job's add of a queue opened from the database, `queue.adding`, which
898
+ * commits with the rows and changed 1 job, or 0 when its id was taken.
899
+ *
900
+ * await db.batch([sql`update notes set body = ${body} where id = ${id}`, indexing.adding({ noteId: id })])
901
+ */
902
+ async batch(writes: readonly (Sql | Adding)[]): Promise<Done[]> {
903
+ const parts = writes.map(each => {
904
+ if (each instanceof Sql) {
905
+ return { text: each.text, values: [...each.values] }
906
+ }
907
+ if (each instanceof Adding) {
908
+ return addingIn(each, this)
897
909
  }
898
- return { text: each.text, values: [...each.values] }
910
+ throw new InvalidError("a batch takes pieces of SQL, sql`…`, and a queue's adding")
899
911
  })
900
912
  this.#refuseAround('a batch')
901
913
  const answered = await this.#link.run('write', async connection => {
902
914
  const handle = await this.handle(connection)
903
- return connection.session.call(
904
- methods['sql.batch'],
905
- SqlBatch.encode({ handle, statements: texts }),
906
- )
915
+ const statements = []
916
+ for (const part of parts) {
917
+ statements.push(typeof part === 'function' ? await part(connection) : part)
918
+ }
919
+ return connection.session.call(methods['sql.batch'], SqlBatch.encode({ handle, statements }))
907
920
  })
908
921
  return (SqlBatched.decode(answered).done ?? []).map(doneOf)
909
922
  }
@@ -1101,11 +1114,32 @@ export class SqlTx implements Runner {
1101
1114
  }
1102
1115
  }
1103
1116
 
1104
- /** Sends the last call: commit, or roll back, and waits for the server's word. */
1117
+ /**
1118
+ * Sends the last call: commit, or roll back, and waits for the server's
1119
+ * word. A commit that left and was not answered, its connection lost or
1120
+ * its wait cancelled, may have committed: its outcome is unknown. One that
1121
+ * never left, its signal aborted or its connection lost first, was rolled
1122
+ * back by the server, and fails as it ended.
1123
+ */
1105
1124
  async end(commit: boolean): Promise<void> {
1106
1125
  await this.#last.catch(() => {})
1126
+ if (this.#stream.cancelled) {
1127
+ // the signal's CANCEL leaves ahead of a commit sent now, and the server rolls back at it
1128
+ throw new CancelledError(
1129
+ `${this.describe}: the transaction was cancelled before its commit left`,
1130
+ )
1131
+ }
1107
1132
  await this.#stream.send(SqlTxCall.encode({ commit }), true)
1108
- await this.#stream.next()
1133
+ try {
1134
+ await this.#stream.next()
1135
+ } catch (err) {
1136
+ if (commit && (err instanceof ConnectionLostError || err instanceof CancelledError)) {
1137
+ throw new OutcomeUnknownError(
1138
+ `${this.describe}: the transaction's commit left with no answer; read what it wrote before running it again: ${err.message}`,
1139
+ )
1140
+ }
1141
+ throw err
1142
+ }
1109
1143
  }
1110
1144
 
1111
1145
  /**