@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,5 +1,25 @@
1
- import { ClosedError } from '../errors.ts';
2
- import type { Child } from '../runtime.ts';
1
+ import { ClosedError, type TinystoreError } from '../errors.ts';
2
+ import type { Detached } from '../runtime.ts';
3
+ /**
4
+ * The error of an open in this process that failed, which the core gives as a
5
+ * message alone: in use when another process holds the directory, as a
6
+ * sidecar does after its last client closed, closed otherwise.
7
+ */
8
+ export declare function openFailure(dir: string, message: string): TinystoreError;
9
+ /**
10
+ * Lets the event loop turn between answers the core in this process gives
11
+ * inside the write that asked. Each such answer resolves its promise in a
12
+ * microtask, so a loop of awaited reads would never let a timer or a socket
13
+ * run (research release-2026-10-23); every `sendsATurn` writes in one turn,
14
+ * the next waits for `setImmediate`, and those after it wait behind it.
15
+ */
16
+ export declare function turning(send: (bytes: Uint8Array) => void): (bytes: Uint8Array) => void;
17
+ /**
18
+ * What a connect gives once it has connected, unless the signal aborts
19
+ * first: the caller is then rejected with the signal's reason, and what
20
+ * connects after is let go, since nobody waits for it.
21
+ */
22
+ export declare function connecting<T>(made: Promise<T>, signal: AbortSignal | undefined, letGo: (late: T) => void): Promise<T>;
3
23
  /** Where an endpoint named in SERVE, or given to connect, is. */
4
24
  export type Address = {
5
25
  kind: 'unix';
@@ -16,9 +36,13 @@ export declare function address(endpoint: string): Address;
16
36
  /**
17
37
  * Starts a sidecar that outlives this process, through node:child_process in
18
38
  * Bun too, since Bun.spawn starts no process that outlives a Ctrl-C of its
19
- * parent's group.
39
+ * parent's group. Its stderr is read while it starts, since a start that
40
+ * fails before its log opens says why there alone, and let go after: a pipe
41
+ * still read would keep this process's event loop alive.
20
42
  */
21
- export declare function spawnDetached(argv: string[]): Child;
43
+ export declare function spawnDetached(argv: string[]): Detached;
44
+ /** Why a process did not start, in the words every SDK uses: not found, permission denied, or the system's own. */
45
+ export declare function notStarted(err: unknown): string;
22
46
  /** How much of a child's stderr is kept, its last lines, to say why it ended. */
23
47
  export declare const stderrKept: number;
24
48
  export declare function lastLines(text: string, n?: number): string;
@@ -1,9 +1,91 @@
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
  import { spawn } from 'node:child_process';
5
6
  import { readdirSync } from 'node:fs';
6
- import { ClosedError } from '../errors.js';
7
+ import { ClosedError, InUseError } from '../errors.js';
8
+ /**
9
+ * The error of an open in this process that failed, which the core gives as a
10
+ * message alone: in use when another process holds the directory, as a
11
+ * sidecar does after its last client closed, closed otherwise.
12
+ */
13
+ export function openFailure(dir, message) {
14
+ const failure = message.includes('in use') ? InUseError : ClosedError;
15
+ return new failure(`cannot open ${dir}: ${message}`);
16
+ }
17
+ /** The writes in a row an event loop's one turn sends the core in this process. */
18
+ const sendsATurn = 64;
19
+ /**
20
+ * Lets the event loop turn between answers the core in this process gives
21
+ * inside the write that asked. Each such answer resolves its promise in a
22
+ * microtask, so a loop of awaited reads would never let a timer or a socket
23
+ * run (research release-2026-10-23); every `sendsATurn` writes in one turn,
24
+ * the next waits for `setImmediate`, and those after it wait behind it.
25
+ */
26
+ export function turning(send) {
27
+ let sent = 0;
28
+ let held;
29
+ const turned = () => {
30
+ sent = 0;
31
+ const sending = held ?? [];
32
+ held = undefined;
33
+ for (const bytes of sending) {
34
+ write(bytes);
35
+ }
36
+ };
37
+ const write = (bytes) => {
38
+ if (held !== undefined) {
39
+ held.push(bytes);
40
+ return;
41
+ }
42
+ if (sent === 0) {
43
+ setImmediate(turned);
44
+ }
45
+ sent++;
46
+ if (sent > sendsATurn) {
47
+ held = [bytes];
48
+ return;
49
+ }
50
+ send(bytes);
51
+ };
52
+ return write;
53
+ }
54
+ /**
55
+ * What a connect gives once it has connected, unless the signal aborts
56
+ * first: the caller is then rejected with the signal's reason, and what
57
+ * connects after is let go, since nobody waits for it.
58
+ */
59
+ export function connecting(made, signal, letGo) {
60
+ if (signal === undefined) {
61
+ return made;
62
+ }
63
+ return new Promise((resolve, reject) => {
64
+ let aborted = false;
65
+ const abort = () => {
66
+ aborted = true;
67
+ reject(signal.reason);
68
+ };
69
+ if (signal.aborted) {
70
+ abort();
71
+ }
72
+ else {
73
+ signal.addEventListener('abort', abort, { once: true });
74
+ }
75
+ made.then(value => {
76
+ signal.removeEventListener('abort', abort);
77
+ if (aborted) {
78
+ letGo(value);
79
+ }
80
+ else {
81
+ resolve(value);
82
+ }
83
+ }, (err) => {
84
+ signal.removeEventListener('abort', abort);
85
+ reject(err);
86
+ });
87
+ });
88
+ }
7
89
  export function address(endpoint) {
8
90
  if (endpoint.startsWith('unix://')) {
9
91
  return { kind: 'unix', path: endpoint.slice('unix://'.length) };
@@ -21,20 +103,50 @@ export function address(endpoint) {
21
103
  /**
22
104
  * Starts a sidecar that outlives this process, through node:child_process in
23
105
  * Bun too, since Bun.spawn starts no process that outlives a Ctrl-C of its
24
- * parent's group.
106
+ * parent's group. Its stderr is read while it starts, since a start that
107
+ * fails before its log opens says why there alone, and let go after: a pipe
108
+ * still read would keep this process's event loop alive.
25
109
  */
26
110
  export function spawnDetached(argv) {
27
- const child = spawn(argv[0], argv.slice(1), {
28
- detached: true,
29
- stdio: 'ignore',
30
- windowsHide: true,
111
+ let child;
112
+ try {
113
+ child = spawn(argv[0], argv.slice(1), {
114
+ detached: true,
115
+ stdio: ['ignore', 'ignore', 'pipe'],
116
+ windowsHide: true,
117
+ });
118
+ }
119
+ catch (err) {
120
+ const exited = Promise.reject(err);
121
+ exited.catch(() => { });
122
+ return { exited, stderr: () => '', release: () => { } };
123
+ }
124
+ const stderr = child.stderr;
125
+ let kept = '';
126
+ stderr.setEncoding('utf8');
127
+ stderr.on('data', (text) => {
128
+ kept = (kept + text).slice(-stderrKept);
31
129
  });
32
- const exited = new Promise(resolve => {
33
- child.once('exit', code => resolve(code ?? -1));
34
- child.once('error', () => resolve(-1));
130
+ stderr.on('error', () => { });
131
+ const exited = new Promise((resolve, reject) => {
132
+ child.once('error', reject);
133
+ // close comes once the child has exited and its stderr has ended
134
+ child.once('close', code => resolve({ code: code ?? -1, stderr: kept }));
35
135
  });
136
+ exited.catch(() => { });
36
137
  child.unref();
37
- return { exited, kill: () => child.kill() };
138
+ return { exited, stderr: () => kept, release: () => stderr.destroy() };
139
+ }
140
+ /** Why a process did not start, in the words every SDK uses: not found, permission denied, or the system's own. */
141
+ export function notStarted(err) {
142
+ const code = err?.code;
143
+ if (code === 'ENOENT') {
144
+ return 'not found';
145
+ }
146
+ if (code === 'EACCES' || code === 'EPERM') {
147
+ return 'permission denied';
148
+ }
149
+ return err instanceof Error ? err.message : String(err);
38
150
  }
39
151
  /** How much of a child's stderr is kept, its last lines, to say why it ended. */
40
152
  export const stderrKept = 16 << 10;
package/dist/runtime.d.ts CHANGED
@@ -29,16 +29,38 @@ export interface PrivateChild extends Child {
29
29
  /** the last lines it wrote to stderr, which say why it ended */
30
30
  stderr(): string;
31
31
  }
32
+ /** A sidecar this process started, which outlives it, while it starts. */
33
+ export interface Detached {
34
+ /**
35
+ * Its exit code once it has exited and its stderr has ended, with the last
36
+ * of what it wrote there; it rejects with why it never started.
37
+ */
38
+ readonly exited: Promise<{
39
+ code: number;
40
+ stderr: string;
41
+ }>;
42
+ /** the last of what it wrote to stderr so far */
43
+ stderr(): string;
44
+ /** Stops reading its stderr once its start is over: what it writes there later goes nowhere. */
45
+ release(): void;
46
+ }
32
47
  export interface Runtime {
33
48
  /** a name and version for the server's logs: tinystore-js on bun/1.4.2 */
34
49
  readonly client: string;
35
50
  readonly windows: boolean;
36
- /** Connects to an endpoint: unix://path, pipe:name, tcp://host:port or tls://host:port. */
37
- connect(endpoint: string, events: TransportEvents, tls?: TlsOptions): Promise<Transport>;
38
- /** Starts a private server whose stdin and stdout carry the frames. */
39
- spawnPrivate(argv: string[], events: TransportEvents): PrivateChild;
40
- /** Starts a process that outlives this one, with no stdio to read. */
41
- spawnDetached(argv: string[]): Child;
51
+ /**
52
+ * Connects to an endpoint: unix://path, pipe:name, tcp://host:port or
53
+ * tls://host:port. A signal that aborts first rejects with its reason and
54
+ * lets the socket go.
55
+ */
56
+ connect(endpoint: string, events: TransportEvents, tls?: TlsOptions, signal?: AbortSignal): Promise<Transport>;
57
+ /**
58
+ * Starts a private server whose stdin and stdout carry the frames, once it
59
+ * has started; it rejects with why it did not.
60
+ */
61
+ spawnPrivate(argv: string[], events: TransportEvents): Promise<PrivateChild>;
62
+ /** Starts a process that outlives this one, its stderr read while it starts. */
63
+ spawnDetached(argv: string[]): Detached;
42
64
  /** A file's bytes, opened, read and closed at once; undefined when it is not there. */
43
65
  readFile(path: string): Promise<Uint8Array | undefined>;
44
66
  /** The executable a name finds on PATH. */
package/dist/session.d.ts CHANGED
@@ -68,9 +68,11 @@ export declare class Stream {
68
68
  /**
69
69
  * Asks the server to stop. A stream whose REQUEST has not left never
70
70
  * leaves; one that has keeps its number until the server's final frame,
71
- * which is dropped.
71
+ * which is dropped. What waits on it fails with `failure`.
72
72
  */
73
- cancel(): void;
73
+ cancel(failure?: Error): void;
74
+ /** Resolves once the server's final frame came, or the connection ended. */
75
+ finishing(): Promise<void>;
74
76
  get cancelled(): boolean;
75
77
  deliver(event: Event): void;
76
78
  /** Ends what waits on the stream with err; events already arrived are read first. */
@@ -101,7 +103,8 @@ export declare class Session {
101
103
  /**
102
104
  * Opens a stream with its REQUEST. End says the REQUEST is the client's
103
105
  * whole side; an upload's DATA follows through the stream otherwise. It
104
- * waits while the streams in flight are all in use.
106
+ * waits for the WELCOME, and while the streams in flight are all in use,
107
+ * each wait until the caller's signal aborts.
105
108
  */
106
109
  open(method: number, body: Uint8Array, end: boolean): Promise<Stream>;
107
110
  /**
@@ -128,9 +131,10 @@ export declare class Session {
128
131
  * Takes the frames whole in the first `length` bytes and says how many
129
132
  * bytes they were: the rest is a frame's first part, which whoever owns
130
133
  * the bytes keeps for its end. Nothing of the bytes is kept here, so their
131
- * owner may write them over once this returns.
134
+ * owner may write them over once this returns, unless they are `kept`:
135
+ * bytes given to the session, whose bodies are views of them.
132
136
  */
133
- read(bytes: Uint8Array, length: number): number;
137
+ read(bytes: Uint8Array, length: number, kept?: boolean): number;
134
138
  /** A frame broke the protocol: the connection ends, and whoever runs it closes it. */
135
139
  fault(err: Error): void;
136
140
  /**
package/dist/session.js CHANGED
@@ -4,9 +4,9 @@
4
4
  // it writes; nothing here waits on a socket, so the same code serves a Unix
5
5
  // socket, a Windows pipe, a child's stdio and TLS.
6
6
  import { createHmac, timingSafeEqual } from 'node:crypto';
7
- import { currentSignal } from './cancel.js';
7
+ import { checkSignal, currentSignal, unlessCancelled } from './cancel.js';
8
8
  import { CancelledError, ClosedError, errorOf, LimitError, ProtocolError, UnavailableError, } from './errors.js';
9
- import { checkHeader, credit, Flag, frame, granted, headerSize, Kind, kindName, parseHeader, putHeader, } from './wire/frame.js';
9
+ import { bodyLength, checkHeader, credit, Flag, frame, granted, headerSize, Kind, kindName, parseHeader, putHeader, } from './wire/frame.js';
10
10
  import { Reader, Writer } from './wire/msgpack.js';
11
11
  import { Failure, GoAway, Hello, Welcome } from './wire/protocol.js';
12
12
  export const protocol = 1;
@@ -48,6 +48,7 @@ export class Stream {
48
48
  #creditWaiters = [];
49
49
  #granting = 0;
50
50
  #cancelled = false;
51
+ #finishing = [];
51
52
  constructor(session, id, method, uploadCredit) {
52
53
  this.#session = session;
53
54
  this.id = id;
@@ -99,15 +100,22 @@ export class Stream {
99
100
  /**
100
101
  * Asks the server to stop. A stream whose REQUEST has not left never
101
102
  * leaves; one that has keeps its number until the server's final frame,
102
- * which is dropped.
103
+ * which is dropped. What waits on it fails with `failure`.
103
104
  */
104
- cancel() {
105
+ cancel(failure = new CancelledError('the call was cancelled')) {
105
106
  if (this.finished || this.#cancelled) {
106
107
  return;
107
108
  }
108
109
  this.#cancelled = true;
109
110
  this.#session.cancel(this);
110
- this.fail(new CancelledError('the call was cancelled'));
111
+ this.fail(failure);
112
+ }
113
+ /** Resolves once the server's final frame came, or the connection ended. */
114
+ finishing() {
115
+ if (this.finished) {
116
+ return Promise.resolve();
117
+ }
118
+ return new Promise(resolve => this.#finishing.push(resolve));
111
119
  }
112
120
  get cancelled() {
113
121
  return this.#cancelled;
@@ -145,6 +153,9 @@ export class Stream {
145
153
  for (const w of this.#creditWaiters.splice(0)) {
146
154
  w.resolve();
147
155
  }
156
+ for (const finished of this.#finishing.splice(0)) {
157
+ finished();
158
+ }
148
159
  this.#unwatch?.();
149
160
  this.#unwatch = undefined;
150
161
  }
@@ -192,7 +203,9 @@ export class Session {
192
203
  #flushing = false;
193
204
  #leave = () => this.#flush();
194
205
  #reader = new Reader(new Uint8Array(0));
195
- #rest;
206
+ // a frame's first part, as long as the whole frame, and how much of it came
207
+ #partial;
208
+ #gathered = 0;
196
209
  #goingAway = false;
197
210
  #ended;
198
211
  #endListeners = [];
@@ -239,17 +252,18 @@ export class Session {
239
252
  /**
240
253
  * Opens a stream with its REQUEST. End says the REQUEST is the client's
241
254
  * whole side; an upload's DATA follows through the stream otherwise. It
242
- * waits while the streams in flight are all in use.
255
+ * waits for the WELCOME, and while the streams in flight are all in use,
256
+ * each wait until the caller's signal aborts.
243
257
  */
244
258
  async open(method, body, end) {
245
259
  const signal = currentSignal();
246
- signal?.throwIfAborted();
247
- const agreed = await this.welcomed;
260
+ checkSignal(signal);
261
+ const agreed = await unlessCancelled(this.welcomed, signal);
248
262
  if (body.length > agreed.maxBody) {
249
263
  throw new LimitError(`a request of ${body.length} bytes, past the ${agreed.maxBody} a body holds`);
250
264
  }
251
265
  while (this.#streams.size >= agreed.inFlight && this.#usable() === undefined) {
252
- await new Promise((resolve, reject) => this.#waitingToOpen.push({ resolve, reject }));
266
+ await this.#streamFreed(signal);
253
267
  }
254
268
  const refused = this.#usable();
255
269
  if (refused !== undefined) {
@@ -268,6 +282,37 @@ export class Session {
268
282
  }
269
283
  return stream;
270
284
  }
285
+ /**
286
+ * Waits for a stream to free; a caller whose signal aborts gives up its
287
+ * place in the line, which the next caller then has.
288
+ */
289
+ #streamFreed(signal) {
290
+ return new Promise((resolve, reject) => {
291
+ const abort = () => {
292
+ const at = this.#waitingToOpen.indexOf(waiter);
293
+ if (at >= 0) {
294
+ this.#waitingToOpen.splice(at, 1);
295
+ }
296
+ reject(new CancelledError('the call was cancelled'));
297
+ };
298
+ const waiter = {
299
+ resolve: () => {
300
+ signal?.removeEventListener('abort', abort);
301
+ resolve();
302
+ },
303
+ reject: err => {
304
+ signal?.removeEventListener('abort', abort);
305
+ reject(err);
306
+ },
307
+ };
308
+ this.#waitingToOpen.push(waiter);
309
+ if (signal?.aborted) {
310
+ abort();
311
+ return;
312
+ }
313
+ signal?.addEventListener('abort', abort, { once: true });
314
+ });
315
+ }
271
316
  /** Why no stream may open now: the connection ended or is going away. */
272
317
  #usable() {
273
318
  if (this.#ended !== undefined) {
@@ -323,7 +368,7 @@ export class Session {
323
368
  }
324
369
  /** A call: one REQUEST, and the RESPONSE that answers it. */
325
370
  async call(method, body, signal) {
326
- signal?.throwIfAborted();
371
+ checkSignal(signal);
327
372
  const stream = await this.open(method, body, true);
328
373
  const unwatch = watch(signal, stream);
329
374
  try {
@@ -401,20 +446,20 @@ export class Session {
401
446
  }
402
447
  cancel(stream) {
403
448
  if (!stream.sent) {
404
- this.#queue = this.#queue.filter(q => q.stream !== stream);
405
449
  this.#release(stream);
406
450
  return;
407
451
  }
408
452
  this.post(frame(Kind.cancel, 0, 0, stream.id, new Uint8Array(0)));
409
453
  }
410
- // takes a stream out of use, dropping what of it has not left: its number
411
- // may be named again at once
454
+ // takes a stream out of use, dropping what of it has not left, its
455
+ // REQUEST too: its number may be named again at once, and a REQUEST left
456
+ // queued would leave on a number the session no longer knows
412
457
  #release(stream) {
413
458
  stream.finish();
414
459
  if (this.#streams.get(stream.id) === stream) {
415
460
  this.#streams.delete(stream.id);
416
461
  }
417
- this.#queue = this.#queue.filter(q => q.stream !== stream || q.request);
462
+ this.#queue = this.#queue.filter(q => q.stream !== stream);
418
463
  this.#waitingToOpen.shift()?.resolve();
419
464
  }
420
465
  /** Takes bytes the transport read: any part of a frame, or several. */
@@ -422,25 +467,62 @@ export class Session {
422
467
  if (this.#ended !== undefined) {
423
468
  return;
424
469
  }
425
- let bytes = chunk;
426
- if (this.#rest !== undefined) {
427
- bytes = new Uint8Array(this.#rest.length + chunk.length);
428
- bytes.set(this.#rest);
429
- bytes.set(chunk, this.#rest.length);
430
- this.#rest = undefined;
470
+ const at = this.#partial === undefined ? 0 : this.#gather(chunk);
471
+ if (at === chunk.length || this.#ended !== undefined) {
472
+ return;
431
473
  }
432
- const at = this.read(bytes, bytes.length);
433
- if (at < bytes.length && this.#ended === undefined) {
434
- this.#rest = bytes.slice(at);
474
+ const rest = chunk.subarray(at);
475
+ const taken = this.read(rest, rest.length);
476
+ if (taken < rest.length && this.#ended === undefined) {
477
+ this.#hold(rest.subarray(taken));
478
+ }
479
+ }
480
+ // Keeps a frame's first part in bytes as long as the whole frame, once
481
+ // its header has come, which `read` has checked: the rest is written
482
+ // behind it as it comes. A mebibyte that came in sixteen pieces was
483
+ // copied again for each piece before (issue #10).
484
+ #hold(part) {
485
+ const length = part.length < headerSize ? headerSize : headerSize + bodyLength(part);
486
+ this.#partial = new Uint8Array(length);
487
+ this.#partial.set(part);
488
+ this.#gathered = part.length;
489
+ }
490
+ // writes the chunk's first bytes behind the frame held, reads the frame
491
+ // once it is whole, and says how many of the chunk's bytes it took
492
+ #gather(chunk) {
493
+ let at = 0;
494
+ for (;;) {
495
+ const partial = this.#partial;
496
+ if (partial === undefined) {
497
+ return at;
498
+ }
499
+ const taken = Math.min(chunk.length - at, partial.length - this.#gathered);
500
+ partial.set(chunk.subarray(at, at + taken), this.#gathered);
501
+ this.#gathered += taken;
502
+ at += taken;
503
+ if (this.#gathered < partial.length) {
504
+ return at;
505
+ }
506
+ this.#partial = undefined;
507
+ if (partial.length === headerSize && bodyLength(partial) > 0) {
508
+ // only its header had come, which says how long the frame is
509
+ this.read(partial, headerSize);
510
+ if (this.#ended === undefined) {
511
+ this.#hold(partial);
512
+ }
513
+ continue;
514
+ }
515
+ this.read(partial, partial.length, true);
435
516
  }
436
517
  }
437
518
  /**
438
519
  * Takes the frames whole in the first `length` bytes and says how many
439
520
  * bytes they were: the rest is a frame's first part, which whoever owns
440
521
  * the bytes keeps for its end. Nothing of the bytes is kept here, so their
441
- * owner may write them over once this returns.
522
+ * owner may write them over once this returns, unless they are `kept`:
523
+ * bytes given to the session, whose bodies are views of them.
442
524
  */
443
- read(bytes, length) {
525
+ read(bytes, length, kept = false) {
444
526
  if (this.#ended !== undefined) {
445
527
  return length;
446
528
  }
@@ -453,7 +535,7 @@ export class Session {
453
535
  if (stop > length) {
454
536
  break;
455
537
  }
456
- this.#take(h, bytes, at + headerSize, stop);
538
+ this.#take(h, bytes, at + headerSize, stop, kept);
457
539
  at = stop;
458
540
  }
459
541
  }
@@ -464,9 +546,9 @@ export class Session {
464
546
  return at;
465
547
  }
466
548
  // takes the frame whose body is the bytes from `from` to `to`
467
- #take(h, bytes, from, to) {
549
+ #take(h, bytes, from, to, kept) {
468
550
  if (this.#agreed !== undefined && (h.kind === Kind.response || h.kind === Kind.data)) {
469
- this.#answer(h, bytes, from, to);
551
+ this.#answer(h, bytes, from, to, kept);
470
552
  return;
471
553
  }
472
554
  const body = bytes.slice(from, to);
@@ -525,7 +607,7 @@ export class Session {
525
607
  this.#credit = agreed.connectionCredit;
526
608
  this.#welcome.resolve(agreed);
527
609
  }
528
- #answer(h, bytes, from, to) {
610
+ #answer(h, bytes, from, to, kept) {
529
611
  const { kind, flags, stream: id } = h;
530
612
  const stream = this.#streams.get(id);
531
613
  if (stream === undefined) {
@@ -536,7 +618,7 @@ export class Session {
536
618
  return;
537
619
  }
538
620
  // a body of its own, since events outlive the read's buffer
539
- const body = bytes.slice(from, to);
621
+ const body = kept ? bytes.subarray(from, to) : bytes.slice(from, to);
540
622
  const end = (flags & Flag.end) !== 0;
541
623
  if (end) {
542
624
  this.#release(stream);
package/dist/sql.d.ts CHANGED
@@ -1,12 +1,12 @@
1
1
  import { type Channel, type TxChannel } from './channels.ts';
2
2
  import type { Connection, Durability, Link } from './connection.ts';
3
3
  import { type Home, type Open, type Via } from './handles.ts';
4
- import { type Queue, type QueueOptions, type TxQueue, type Worker } from './jobs.ts';
4
+ import { Adding, type Queue, type QueueOptions, type TxQueue, type Worker } from './jobs.ts';
5
5
  import { Bucket, type BucketOptions } from './kv.ts';
6
6
  import { Table, type TableOptions } from './query.ts';
7
7
  import type { StandardSchemaV1 } from './schema.ts';
8
8
  import { TableIndex, type TableIndexOptions } from './search.ts';
9
- import type { Stream } from './session.ts';
9
+ import { type Stream } from './session.ts';
10
10
  import type { SqlArg, SqlValue } from './wire/codec.ts';
11
11
  export type { SqlArg, SqlValue };
12
12
  /** A row type's columns: an array of each of its fields. */
@@ -215,8 +215,15 @@ export declare class Database implements Runner, Home {
215
215
  schema: S;
216
216
  }): Table<StandardSchemaV1.InferOutput<S>>;
217
217
  table<T = Row>(name: string, options?: TableOptions): Table<T>;
218
- /** Statements known before they run, written as one: all of them or none, in a shared commit. */
219
- batch(statements: readonly Sql[]): Promise<Done[]>;
218
+ /**
219
+ * Writes known before they run, written as one: all of them or none, in a
220
+ * shared commit, and what each did, in their order. A write is a statement,
221
+ * or a job's add of a queue opened from the database, `queue.adding`, which
222
+ * commits with the rows and changed 1 job, or 0 when its id was taken.
223
+ *
224
+ * await db.batch([sql`update notes set body = ${body} where id = ${id}`, indexing.adding({ noteId: id })])
225
+ */
226
+ batch(writes: readonly (Sql | Adding)[]): Promise<Done[]>;
220
227
  /**
221
228
  * Runs fn in a transaction that holds the writer, for writes that depend on
222
229
  * what its reads found: returning commits, a throw rolls back. It runs
@@ -266,6 +273,12 @@ export declare class SqlTx implements Runner {
266
273
  /** A table inside the transaction: its calls are the transaction's. */
267
274
  table<T = Row>(name: string, options?: TableOptions): Table<T>;
268
275
  rows(statement: Sql, want: Want): Promise<Answered>;
269
- /** Sends the last call: commit, or roll back, and waits for the server's word. */
276
+ /**
277
+ * Sends the last call: commit, or roll back, and waits for the server's
278
+ * word. A commit that left and was not answered, its connection lost or
279
+ * its wait cancelled, may have committed: its outcome is unknown. One that
280
+ * never left, its signal aborted or its connection lost first, was rolled
281
+ * back by the server, and fails as it ended.
282
+ */
270
283
  end(commit: boolean): Promise<void>;
271
284
  }