@tinyshed/tinystore 0.1.0-rc.7 → 0.1.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 (70) hide show
  1. package/README.md +2 -2
  2. package/dist/blobs.d.ts +1 -1
  3. package/dist/blobs.js +13 -5
  4. package/dist/cancel.d.ts +16 -2
  5. package/dist/cancel.js +36 -2
  6. package/dist/channels.js +20 -6
  7. package/dist/config.d.ts +49 -1
  8. package/dist/config.js +86 -7
  9. package/dist/connection.d.ts +52 -10
  10. package/dist/connection.js +305 -73
  11. package/dist/handles.d.ts +10 -1
  12. package/dist/handles.js +27 -4
  13. package/dist/index.d.ts +4 -4
  14. package/dist/jobs.d.ts +33 -1
  15. package/dist/jobs.js +45 -0
  16. package/dist/logger.d.ts +22 -10
  17. package/dist/logger.js +118 -28
  18. package/dist/metrics.d.ts +19 -0
  19. package/dist/metrics.js +22 -1
  20. package/dist/query.js +33 -9
  21. package/dist/records.d.ts +30 -2
  22. package/dist/records.js +8 -0
  23. package/dist/runtime/addon.js +3 -2
  24. package/dist/runtime/bun.js +33 -12
  25. package/dist/runtime/node.js +30 -8
  26. package/dist/runtime/pipe.d.ts +2 -0
  27. package/dist/runtime/pipe.js +45 -20
  28. package/dist/runtime/shared.d.ts +28 -4
  29. package/dist/runtime/shared.js +125 -13
  30. package/dist/runtime.d.ts +28 -6
  31. package/dist/session.d.ts +9 -5
  32. package/dist/session.js +113 -31
  33. package/dist/sql.d.ts +18 -5
  34. package/dist/sql.js +44 -11
  35. package/dist/store.d.ts +25 -11
  36. package/dist/store.js +67 -9
  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 +246 -36
  44. package/dist/wire/protocol.js +387 -101
  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 +5 -0
  53. package/src/jobs.ts +63 -0
  54. package/src/logger.ts +158 -40
  55. package/src/metrics.ts +46 -1
  56. package/src/query.ts +33 -13
  57. package/src/records.ts +40 -2
  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/wire/codec.ts +11 -0
  68. package/src/wire/frame.ts +5 -0
  69. package/src/wire/msgpack.ts +11 -4
  70. package/src/wire/protocol.ts +404 -103
package/dist/query.js CHANGED
@@ -676,18 +676,31 @@ function render(parts) {
676
676
  }
677
677
  return new Sql(text, values);
678
678
  }
679
- /** The condition that starts a page after a row's order values. */
679
+ /**
680
+ * The condition that starts a page after a row's order values. SQLite orders
681
+ * a null before every value, first in ascending order and last in descending,
682
+ * and a comparison with a null is never true: equal is `is`, and past a null
683
+ * is every value ascending and nothing descending.
684
+ */
680
685
  function keyset(order, after) {
681
686
  const alternatives = [];
682
687
  const values = [];
683
688
  order.forEach((each, at) => {
684
- const equal = order.slice(0, at).map(earlier => `${earlier.piece.text} = ?`);
689
+ const column = each.piece.text;
690
+ const value = after[at] ?? null;
691
+ if (value === null && each.direction === 'desc') {
692
+ return;
693
+ }
694
+ const equal = order.slice(0, at).map(earlier => `${earlier.piece.text} is ?`);
685
695
  values.push(...after.slice(0, at));
686
- const past = `${each.piece.text} ${each.direction === 'asc' ? '>' : '<'} ?`;
687
- values.push(after[at] ?? null);
696
+ let past = `${column} is not null`;
697
+ if (value !== null) {
698
+ past = each.direction === 'asc' ? `${column} > ?` : `(${column} < ? or ${column} is null)`;
699
+ values.push(value);
700
+ }
688
701
  alternatives.push(equal.length === 0 ? past : `(${[...equal, past].join(' and ')})`);
689
702
  });
690
- return new Sql(`(${alternatives.join(' or ')})`, values);
703
+ return new Sql(alternatives.length === 0 ? '0' : `(${alternatives.join(' or ')})`, values);
691
704
  }
692
705
  /** A short digest of a query, which a cursor carries so that another query refuses it. */
693
706
  function digestOf(statement) {
@@ -699,8 +712,14 @@ function digestOf(statement) {
699
712
  }
700
713
  return hash.toString(36);
701
714
  }
715
+ /** A cursor of order values: a bigint, and an infinity JSON has no number for, as their text. */
702
716
  function cursorText(values, digest) {
703
- const json = JSON.stringify({ q: digest, v: values }, (_, v) => typeof v === 'bigint' ? { n: String(v) } : v);
717
+ const json = JSON.stringify({ q: digest, v: values }, (_, v) => {
718
+ if (typeof v === 'bigint') {
719
+ return { n: String(v) };
720
+ }
721
+ return typeof v === 'number' && !Number.isFinite(v) ? { r: String(v) } : v;
722
+ });
704
723
  return Buffer.from(json).toString('base64url');
705
724
  }
706
725
  function cursorOf(cursor, digest) {
@@ -714,9 +733,14 @@ function cursorOf(cursor, digest) {
714
733
  if (read.q !== digest || !Array.isArray(read.v)) {
715
734
  throw new InvalidError("a cursor of another query: a page's next reads only the query that made it");
716
735
  }
717
- return read.v.map(v => typeof v === 'object' && v !== null && 'n' in v
718
- ? BigInt(v.n)
719
- : v);
736
+ return read.v.map(v => {
737
+ if (typeof v === 'object' && v !== null && 'n' in v) {
738
+ return BigInt(v.n);
739
+ }
740
+ return typeof v === 'object' && v !== null && 'r' in v
741
+ ? Number(v.r)
742
+ : v;
743
+ });
720
744
  }
721
745
  /** An insert of rows of the same columns, the first row's. */
722
746
  function insertOf(table, rows, types) {
package/dist/records.d.ts CHANGED
@@ -147,6 +147,8 @@ type Method = keyof typeof methods;
147
147
  declare abstract class Reads {
148
148
  protected abstract ask(method: Method, body: (handle: number | undefined) => Uint8Array): Promise<Uint8Array>;
149
149
  protected abstract opened(method: Method, body: (handle: number | undefined) => Uint8Array): Promise<Stream>;
150
+ /** Keeps a stream that follows the store for its close to cancel; it returns what lets it go. */
151
+ protected abstract follow(stream: Stream): () => void;
150
152
  /** One page, from one moment of the file: `{ events, next }`. */
151
153
  list(query?: Query): Promise<Page>;
152
154
  /** Every event the query finds, a page after another. */
@@ -204,6 +206,7 @@ export declare class Events extends Reads {
204
206
  lines(): Lines;
205
207
  protected ask(method: Method, body: (handle: number | undefined) => Uint8Array): Promise<Uint8Array>;
206
208
  protected opened(method: Method, body: (handle: number | undefined) => Uint8Array): Promise<Stream>;
209
+ protected follow(stream: Stream): () => void;
207
210
  }
208
211
  /** Every stream's events, to read: `store.events()`. */
209
212
  export declare class AllEvents extends Reads {
@@ -235,6 +238,7 @@ export declare class AllEvents extends Reads {
235
238
  */
236
239
  drop(damage: Damage): Promise<void>;
237
240
  protected opened(method: Method, body: (handle: number | undefined) => Uint8Array): Promise<Stream>;
241
+ protected follow(stream: Stream): () => void;
238
242
  }
239
243
  /** A writer's stream, and the bytes a piece of it carries. */
240
244
  interface Opened {
@@ -260,10 +264,34 @@ export declare class Lines {
260
264
  */
261
265
  end(): Promise<void>;
262
266
  }
263
- /** What a store's logger is told: a logger's options, and how long its stream keeps. */
264
- export interface StoreLoggerOptions extends LoggerOptions {
267
+ /** What a store's logger is told: a logger's options, how long its stream keeps, and the levels it keeps and prints. */
268
+ export interface StoreLoggerOptions extends Omit<LoggerOptions, 'level'> {
265
269
  /** how long the stream keeps its events, as store.events takes it */
266
270
  keep?: Duration;
271
+ /**
272
+ * the least level kept and printed, every level when absent, or each
273
+ * apart: `{ store: 'info', console: 'warn' }` keeps every line from info
274
+ * and prints warnings and errors. LOG_LEVEL wins over the level kept, and
275
+ * LOG_CONSOLE_LEVEL over the level printed
276
+ */
277
+ level?: Level | Levels;
278
+ }
279
+ /**
280
+ * The least levels a store's logger keeps and prints, each part left out as
281
+ * the option is: no store keeps every level, and no console prints what is
282
+ * kept, following the config `log`'s changes of it.
283
+ *
284
+ * ```ts
285
+ * { level: 'info' } // keeps info+, prints info+
286
+ * { level: { store: 'info', console: 'warn' } } // keeps info+, prints warn+
287
+ * { level: { console: 'warn' } } // keeps every level, prints warn+
288
+ * ```
289
+ */
290
+ export interface Levels {
291
+ /** the least level kept; LOG_LEVEL and the config `log` win over it */
292
+ store?: Level;
293
+ /** the least level printed; LOG_CONSOLE_LEVEL wins over it */
294
+ console?: Level;
267
295
  }
268
296
  /**
269
297
  * A logger of `stream` that keeps its lines there through an append of their
package/dist/records.js CHANGED
@@ -110,6 +110,7 @@ class Reads {
110
110
  async *tail(query) {
111
111
  const asked = queryOf(query);
112
112
  const stream = await this.opened('records.tail', handle => RecordsQuery.encode({ ...asked, handle }));
113
+ const unfollow = this.follow(stream);
113
114
  try {
114
115
  for (;;) {
115
116
  const event = await stream.next();
@@ -123,6 +124,7 @@ class Reads {
123
124
  }
124
125
  finally {
125
126
  stream.cancel();
127
+ unfollow();
126
128
  }
127
129
  }
128
130
  }
@@ -191,6 +193,9 @@ export class Events extends Reads {
191
193
  return streamOf(connection, methods[method], body(handle), true);
192
194
  });
193
195
  }
196
+ follow(stream) {
197
+ return this.#link.follow(stream);
198
+ }
194
199
  #call(method, body, idempotence) {
195
200
  return this.#via.call(methods['records.open'], this.#open, methods[method], body, idempotence);
196
201
  }
@@ -263,6 +268,9 @@ export class AllEvents extends Reads {
263
268
  opened(method, body) {
264
269
  return this.#link.run('read', connection => streamOf(connection, methods[method], body(undefined), true));
265
270
  }
271
+ follow(stream) {
272
+ return this.#link.follow(stream);
273
+ }
266
274
  }
267
275
  /**
268
276
  * A writer of another program's output into a stream, as `events.lines()`
@@ -4,6 +4,7 @@
4
4
  // Node alone: Bun loads the C library through bun:ffi instead.
5
5
  import { createRequire } from 'node:module';
6
6
  import { ClosedError } from '../errors.js';
7
+ import { openFailure, turning } from './shared.js';
7
8
  /**
8
9
  * Opens a pipe to the store in a directory, the core loaded from the addon
9
10
  * at `path`. `options` is the wire's store.Options, how this process opens
@@ -52,10 +53,10 @@ export function openAddon(path, dir, options, events) {
52
53
  });
53
54
  }
54
55
  catch (err) {
55
- throw new ClosedError(`cannot open ${dir}: ${err.message}`);
56
+ throw openFailure(dir, err.message);
56
57
  }
57
58
  return {
58
- write: send,
59
+ write: turning(send),
59
60
  close() {
60
61
  const closing = pipe;
61
62
  if (closing === undefined) {
@@ -5,7 +5,7 @@
5
5
  import net from 'node:net';
6
6
  import manifest from '../../package.json' with { type: 'json' };
7
7
  import { ClosedError } from '../errors.js';
8
- import { address, exitedWith, platformPackage, spawnDetached, stderrKept } from './shared.js';
8
+ import { address, connecting, exitedWith, platformPackage, spawnDetached, stderrKept, } from './shared.js';
9
9
  export const bunRuntime = {
10
10
  get client() {
11
11
  return `tinystore-js/${manifest.version} bun/${Bun.version}`;
@@ -29,18 +29,18 @@ export const bunRuntime = {
29
29
  which: name => Bun.which(name) ?? undefined,
30
30
  packaged,
31
31
  };
32
- async function connect(endpoint, events, tls) {
32
+ async function connect(endpoint, events, tls, signal) {
33
33
  const at = address(endpoint);
34
34
  switch (at.kind) {
35
35
  case 'pipe':
36
- return connectPipe(at.path, events);
36
+ return connectPipe(at.path, events, signal);
37
37
  case 'unix': {
38
38
  const path = at.path;
39
- return connectSocket(socket => Bun.connect({ unix: path, socket }), events);
39
+ return connectSocket(socket => Bun.connect({ unix: path, socket }), events, signal);
40
40
  }
41
41
  case 'tcp': {
42
42
  const { host, port } = at;
43
- return connectSocket(socket => Bun.connect({ hostname: host, port, socket }), events);
43
+ return connectSocket(socket => Bun.connect({ hostname: host, port, socket }), events, signal);
44
44
  }
45
45
  case 'tls': {
46
46
  const { host, port } = at;
@@ -48,15 +48,17 @@ async function connect(endpoint, events, tls) {
48
48
  serverName: tls?.serverName ?? host,
49
49
  ...(tls?.ca === undefined ? {} : { ca: tls.ca }),
50
50
  };
51
- return connectSocket(socket => Bun.connect({ hostname: host, port, tls: verify, socket }), events);
51
+ return connectSocket(socket => Bun.connect({ hostname: host, port, tls: verify, socket }), events, signal);
52
52
  }
53
53
  }
54
54
  }
55
55
  /**
56
56
  * A socket's write may take part of the bytes: the rest waits for its drain,
57
- * in order, so the session hands a whole frame over and forgets it.
57
+ * in order, so the session hands a whole frame over and forgets it. Bun's
58
+ * connect takes no signal: one that aborts first rejects at once, and the
59
+ * socket connected after is ended.
58
60
  */
59
- async function connectSocket(dial, events) {
61
+ async function connectSocket(dial, events, signal) {
60
62
  const waiting = [];
61
63
  let ended = false;
62
64
  const end = (err) => {
@@ -78,13 +80,14 @@ async function connectSocket(dial, events) {
78
80
  return;
79
81
  }
80
82
  };
81
- socket = await dial({
83
+ const dialled = dial({
82
84
  data: (_, data) => events.data(data),
83
85
  drain: () => pump(),
84
86
  end: () => end(new ClosedError('the server ended the connection')),
85
87
  close: (_, err) => end(err ?? new ClosedError('the connection closed')),
86
88
  error: (_, err) => end(err),
87
89
  });
90
+ socket = await connecting(dialled, signal, late => late.end());
88
91
  return {
89
92
  write: bytes => {
90
93
  waiting.push(bytes);
@@ -95,7 +98,7 @@ async function connectSocket(dial, events) {
95
98
  close: () => socket?.end(),
96
99
  };
97
100
  }
98
- function connectPipe(path, events) {
101
+ function connectPipe(path, events, signal) {
99
102
  return new Promise((resolve, reject) => {
100
103
  const socket = net.createConnection(path);
101
104
  let connected = false;
@@ -106,16 +109,34 @@ function connectPipe(path, events) {
106
109
  events.end(err);
107
110
  }
108
111
  };
112
+ const abort = () => {
113
+ reject(signal?.reason);
114
+ socket.destroy();
115
+ };
116
+ if (signal?.aborted) {
117
+ abort();
118
+ return;
119
+ }
120
+ signal?.addEventListener('abort', abort, { once: true });
109
121
  socket.once('connect', () => {
110
122
  connected = true;
123
+ signal?.removeEventListener('abort', abort);
111
124
  resolve({ write: bytes => socket.write(bytes), close: () => socket.end() });
112
125
  });
113
126
  socket.on('data', (data) => events.data(data));
114
- socket.on('error', err => (connected ? end(err) : reject(err)));
127
+ socket.on('error', err => {
128
+ if (connected) {
129
+ end(err);
130
+ return;
131
+ }
132
+ signal?.removeEventListener('abort', abort);
133
+ reject(err);
134
+ });
115
135
  socket.on('close', () => end(new ClosedError('the pipe closed')));
116
136
  });
117
137
  }
118
- function spawnPrivate(argv, events) {
138
+ // async, so that the throw of a Bun.spawn that cannot start is its rejection
139
+ async function spawnPrivate(argv, events) {
119
140
  const proc = Bun.spawn(argv, { stdin: 'pipe', stdout: 'pipe', stderr: 'pipe', windowsHide: true });
120
141
  let kept = '';
121
142
  // a pipe nobody drains stops the server once it fills, so stderr is read to its end
@@ -31,16 +31,16 @@ export const nodeRuntime = {
31
31
  which,
32
32
  packaged,
33
33
  };
34
- function connect(endpoint, events, options) {
34
+ function connect(endpoint, events, options, signal) {
35
35
  const at = address(endpoint);
36
36
  switch (at.kind) {
37
37
  case 'pipe':
38
38
  case 'unix':
39
- return connected(net.createConnection(at.path), 'connect', events);
39
+ return connected(net.createConnection(at.path), 'connect', events, signal);
40
40
  case 'tcp':
41
- return connected(net.createConnection({ host: at.host, port: at.port, noDelay: true }), 'connect', events);
41
+ return connected(net.createConnection({ host: at.host, port: at.port, noDelay: true }), 'connect', events, signal);
42
42
  case 'tls':
43
- return connected(connectTLS(at.host, at.port, options), 'secureConnect', events);
43
+ return connected(connectTLS(at.host, at.port, options), 'secureConnect', events, signal);
44
44
  }
45
45
  }
46
46
  /**
@@ -64,9 +64,9 @@ function connectTLS(host, port, options) {
64
64
  /**
65
65
  * A transport once the socket is ready: a socket's write queues what the
66
66
  * kernel does not take yet, in order, so the session hands a whole frame over
67
- * and forgets it.
67
+ * and forgets it. A signal that aborts before then destroys the socket.
68
68
  */
69
- function connected(socket, ready, events) {
69
+ function connected(socket, ready, events, signal) {
70
70
  return new Promise((resolve, reject) => {
71
71
  let open = false;
72
72
  let ended = false;
@@ -76,18 +76,40 @@ function connected(socket, ready, events) {
76
76
  events.end(err);
77
77
  }
78
78
  };
79
+ const abort = () => {
80
+ reject(signal?.reason);
81
+ socket.destroy();
82
+ };
83
+ if (signal?.aborted) {
84
+ abort();
85
+ return;
86
+ }
87
+ signal?.addEventListener('abort', abort, { once: true });
79
88
  socket.once(ready, () => {
80
89
  open = true;
90
+ signal?.removeEventListener('abort', abort);
81
91
  resolve({ write: bytes => void socket.write(bytes), close: () => void socket.end() });
82
92
  });
83
93
  socket.on('data', (data) => events.data(data));
84
- socket.on('error', err => (open ? end(err) : reject(err)));
94
+ socket.on('error', err => {
95
+ if (open) {
96
+ end(err);
97
+ return;
98
+ }
99
+ signal?.removeEventListener('abort', abort);
100
+ reject(err);
101
+ });
85
102
  socket.on('end', () => end(new ClosedError('the server ended the connection')));
86
103
  socket.on('close', () => end(new ClosedError('the connection closed')));
87
104
  });
88
105
  }
89
- function spawnPrivate(argv, events) {
106
+ async function spawnPrivate(argv, events) {
90
107
  const proc = spawn(argv[0], argv.slice(1), { stdio: 'pipe', windowsHide: true });
108
+ // a child that cannot start says so after the spawn, by its error
109
+ await new Promise((resolve, reject) => {
110
+ proc.once('spawn', resolve);
111
+ proc.once('error', reject);
112
+ });
91
113
  let kept = '';
92
114
  // a pipe nobody drains stops the server once it fills, so stderr is read to its end
93
115
  proc.stderr.setEncoding('utf8');
@@ -7,6 +7,8 @@ export interface PipeEvents {
7
7
  * read: nothing of them may be kept.
8
8
  */
9
9
  frames(bytes: Uint8Array, length: number): number;
10
+ /** Reads one whole frame in bytes of its own, which the session may keep. */
11
+ frame(bytes: Uint8Array): void;
10
12
  /** the store closed; called once */
11
13
  end(err: Error): void;
12
14
  }
@@ -5,6 +5,8 @@
5
5
  // writes its own where we say. Bun alone: bun:ffi.
6
6
  import { dlopen, FFIType, JSCallback, ptr } from 'bun:ffi';
7
7
  import { ClosedError } from '../errors.js';
8
+ import { bodyLength, headerSize } from '../wire/frame.js';
9
+ import { openFailure, turning } from './shared.js';
8
10
  const symbols = {
9
11
  tinystore_open: {
10
12
  args: [
@@ -30,10 +32,8 @@ const symbols = {
30
32
  },
31
33
  tinystore_close: { args: [FFIType.ptr], returns: FFIType.void },
32
34
  };
33
- /** The room for what the core owes, to begin with and once a large frame has passed. */
35
+ /** The room for what the core owes: a frame longer than it is written into bytes of its own. */
34
36
  const room = 1 << 16;
35
- /** Room past this is given back once nothing is held in it. */
36
- const kept = 1 << 20;
37
37
  /**
38
38
  * Opens a pipe to the store in a directory, the core loaded from `library`.
39
39
  * `options` is the wire's store.Options, how this process opens the store.
@@ -46,24 +46,42 @@ export function openPipe(library, dir, options, events) {
46
46
  let connection = null;
47
47
  // where the core writes what it owes: whole frames are read from the
48
48
  // front, and a frame's first part is held there for its rest
49
- let inbox = new Uint8Array(room);
49
+ const inbox = new Uint8Array(room);
50
50
  let held = 0;
51
- // reads the frames among the `written` bytes behind what is held, and
52
- // says whether the core filled the room, which means more may wait
51
+ // A frame longer than the inbox, in bytes as long as it is, and how much
52
+ // of it came: the core writes its rest there, and the session keeps them,
53
+ // so that a file's mebibyte is written once here rather than copied out
54
+ // of an inbox grown for it (issue #10).
55
+ let large;
56
+ let filledLarge = 0;
57
+ // where the core writes next, and how many bytes it may
58
+ const into = () => large === undefined
59
+ ? [inbox, held, inbox.length - held]
60
+ : [large, filledLarge, large.length - filledLarge];
61
+ // reads what the core wrote where `into` said, and says whether it filled
62
+ // that room, which means more may wait
53
63
  const read = (written) => {
64
+ if (large !== undefined) {
65
+ filledLarge += written;
66
+ if (filledLarge < large.length) {
67
+ return false;
68
+ }
69
+ const whole = large;
70
+ large = undefined;
71
+ events.frame(whole);
72
+ return true;
73
+ }
54
74
  const length = held + written;
55
75
  const filled = length === inbox.length;
56
76
  const taken = written === 0 ? 0 : events.frames(inbox, length);
57
77
  inbox.copyWithin(0, taken, length);
58
78
  held = length - taken;
59
- if (held === inbox.length) {
60
- // a frame longer than the room: twice the room, until it fits
61
- const grown = new Uint8Array(inbox.length * 2);
62
- grown.set(inbox);
63
- inbox = grown;
64
- }
65
- else if (held === 0 && inbox.length > kept) {
66
- inbox = new Uint8Array(room);
79
+ const frameLength = held < headerSize ? 0 : headerSize + bodyLength(inbox);
80
+ if (frameLength > inbox.length) {
81
+ large = new Uint8Array(frameLength);
82
+ large.set(inbox.subarray(0, held));
83
+ filledLarge = held;
84
+ held = 0;
67
85
  }
68
86
  return filled;
69
87
  };
@@ -80,8 +98,8 @@ export function openPipe(library, dir, options, events) {
80
98
  try {
81
99
  let filled = written === undefined || read(written);
82
100
  while (filled && connection !== null) {
83
- const free = inbox.length - held;
84
- filled = read(Number(lib.symbols.tinystore_recv(connection, 0, ptr(inbox, held), free)));
101
+ const [bytes, at, free] = into();
102
+ filled = read(Number(lib.symbols.tinystore_recv(connection, 0, ptr(bytes, at), free)));
85
103
  }
86
104
  }
87
105
  finally {
@@ -100,8 +118,8 @@ export function openPipe(library, dir, options, events) {
100
118
  waiting.push(bytes);
101
119
  return;
102
120
  }
103
- const free = inbox.length - held;
104
- const written = lib.symbols.tinystore_send(connection, ptr(bytes), bytes.length, ptr(inbox, held), free);
121
+ const [owed, at, free] = into();
122
+ const written = lib.symbols.tinystore_send(connection, ptr(bytes), bytes.length, ptr(owed, at), free);
105
123
  readOn(Number(written));
106
124
  };
107
125
  const wake = new JSCallback(() => readOn(undefined), {
@@ -114,17 +132,24 @@ export function openPipe(library, dir, options, events) {
114
132
  const message = new TextDecoder().decode(failure.subarray(0, failed));
115
133
  wake.close();
116
134
  lib.close();
117
- throw new ClosedError(`cannot open ${dir}: ${message}`);
135
+ throw openFailure(dir, message);
118
136
  }
119
137
  connection = Number(opened[0]);
138
+ // Bun's loop with no timer armed spins while it waits for a threadsafe
139
+ // callback from another thread: a write waiting for its sync burned a
140
+ // whole processor (research release-2026-10-23). A timer armed, however
141
+ // far off, lets the loop sleep until the core wakes it; it also keeps the
142
+ // process alive while the store is open, as a sidecar's socket does.
143
+ const sleeps = setInterval(() => { }, 2 ** 30);
120
144
  return {
121
- write: send,
145
+ write: turning(send),
122
146
  close() {
123
147
  if (connection === null) {
124
148
  return;
125
149
  }
126
150
  const closing = connection;
127
151
  connection = null;
152
+ clearInterval(sleeps);
128
153
  lib.symbols.tinystore_close(closing);
129
154
  wake.close();
130
155
  events.end(new ClosedError('the store closed'));
@@ -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;