@tinyshed/tinystore 0.1.0 → 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 (69) 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 +4 -4
  13. package/dist/jobs.d.ts +33 -1
  14. package/dist/jobs.js +45 -0
  15. package/dist/logger.d.ts +22 -10
  16. package/dist/logger.js +118 -28
  17. package/dist/metrics.d.ts +19 -0
  18. package/dist/metrics.js +22 -1
  19. package/dist/query.js +33 -9
  20. package/dist/records.d.ts +30 -2
  21. package/dist/records.js +8 -0
  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/wire/codec.d.ts +5 -0
  37. package/dist/wire/codec.js +10 -0
  38. package/dist/wire/frame.d.ts +2 -0
  39. package/dist/wire/frame.js +4 -0
  40. package/dist/wire/msgpack.d.ts +7 -3
  41. package/dist/wire/msgpack.js +11 -4
  42. package/dist/wire/protocol.d.ts +246 -36
  43. package/dist/wire/protocol.js +387 -101
  44. package/package.json +9 -8
  45. package/src/blobs.ts +13 -5
  46. package/src/cancel.ts +44 -2
  47. package/src/channels.ts +21 -6
  48. package/src/config.ts +138 -12
  49. package/src/connection.ts +377 -77
  50. package/src/handles.ts +32 -4
  51. package/src/index.ts +5 -0
  52. package/src/jobs.ts +63 -0
  53. package/src/logger.ts +158 -40
  54. package/src/metrics.ts +46 -1
  55. package/src/query.ts +33 -13
  56. package/src/records.ts +40 -2
  57. package/src/runtime/addon.ts +3 -2
  58. package/src/runtime/bun.ts +44 -9
  59. package/src/runtime/node.ts +30 -5
  60. package/src/runtime/pipe.ts +49 -19
  61. package/src/runtime/shared.ts +137 -16
  62. package/src/runtime.ts +31 -6
  63. package/src/session.ts +129 -30
  64. package/src/sql.ts +48 -14
  65. package/src/store.ts +81 -14
  66. package/src/wire/codec.ts +11 -0
  67. package/src/wire/frame.ts +5 -0
  68. package/src/wire/msgpack.ts +11 -4
  69. package/src/wire/protocol.ts +404 -103
package/src/records.ts CHANGED
@@ -238,6 +238,9 @@ abstract class Reads {
238
238
  body: (handle: number | undefined) => Uint8Array,
239
239
  ): Promise<Stream>
240
240
 
241
+ /** Keeps a stream that follows the store for its close to cancel; it returns what lets it go. */
242
+ protected abstract follow(stream: Stream): () => void
243
+
241
244
  /** One page, from one moment of the file: `{ events, next }`. */
242
245
  async list(query?: Query): Promise<Page> {
243
246
  const asked = queryOf(query)
@@ -338,6 +341,7 @@ abstract class Reads {
338
341
  const stream = await this.opened('records.tail', handle =>
339
342
  RecordsQuery.encode({ ...asked, handle }),
340
343
  )
344
+ const unfollow = this.follow(stream)
341
345
  try {
342
346
  for (;;) {
343
347
  const event = await stream.next()
@@ -350,6 +354,7 @@ abstract class Reads {
350
354
  }
351
355
  } finally {
352
356
  stream.cancel()
357
+ unfollow()
353
358
  }
354
359
  }
355
360
  }
@@ -452,6 +457,10 @@ export class Events extends Reads {
452
457
  })
453
458
  }
454
459
 
460
+ protected follow(stream: Stream): () => void {
461
+ return this.#link.follow(stream)
462
+ }
463
+
455
464
  #call(
456
465
  method: Method,
457
466
  body: (handle: number) => Uint8Array,
@@ -550,6 +559,10 @@ export class AllEvents extends Reads {
550
559
  streamOf(connection, methods[method], body(undefined), true),
551
560
  )
552
561
  }
562
+
563
+ protected follow(stream: Stream): () => void {
564
+ return this.#link.follow(stream)
565
+ }
553
566
  }
554
567
 
555
568
  /** A writer's stream, and the bytes a piece of it carries. */
@@ -713,10 +726,35 @@ function linesIn(bytes: Uint8Array): number {
713
726
  return lines
714
727
  }
715
728
 
716
- /** What a store's logger is told: a logger's options, and how long its stream keeps. */
717
- export interface StoreLoggerOptions extends LoggerOptions {
729
+ /** What a store's logger is told: a logger's options, how long its stream keeps, and the levels it keeps and prints. */
730
+ export interface StoreLoggerOptions extends Omit<LoggerOptions, 'level'> {
718
731
  /** how long the stream keeps its events, as store.events takes it */
719
732
  keep?: Duration
733
+ /**
734
+ * the least level kept and printed, every level when absent, or each
735
+ * apart: `{ store: 'info', console: 'warn' }` keeps every line from info
736
+ * and prints warnings and errors. LOG_LEVEL wins over the level kept, and
737
+ * LOG_CONSOLE_LEVEL over the level printed
738
+ */
739
+ level?: Level | Levels
740
+ }
741
+
742
+ /**
743
+ * The least levels a store's logger keeps and prints, each part left out as
744
+ * the option is: no store keeps every level, and no console prints what is
745
+ * kept, following the config `log`'s changes of it.
746
+ *
747
+ * ```ts
748
+ * { level: 'info' } // keeps info+, prints info+
749
+ * { level: { store: 'info', console: 'warn' } } // keeps info+, prints warn+
750
+ * { level: { console: 'warn' } } // keeps every level, prints warn+
751
+ * ```
752
+ */
753
+ export interface Levels {
754
+ /** the least level kept; LOG_LEVEL and the config `log` win over it */
755
+ store?: Level
756
+ /** the least level printed; LOG_CONSOLE_LEVEL wins over it */
757
+ console?: Level
720
758
  }
721
759
 
722
760
  /**
@@ -7,6 +7,7 @@ import { createRequire } from 'node:module'
7
7
 
8
8
  import { ClosedError } from '../errors.ts'
9
9
  import type { Transport } from '../runtime.ts'
10
+ import { openFailure, turning } from './shared.ts'
10
11
 
11
12
  /** What tinystore.node exports: crates/ffi built with `node`. */
12
13
  interface Addon {
@@ -82,10 +83,10 @@ export function openAddon(
82
83
  }
83
84
  })
84
85
  } catch (err) {
85
- throw new ClosedError(`cannot open ${dir}: ${(err as Error).message}`)
86
+ throw openFailure(dir, (err as Error).message)
86
87
  }
87
88
  return {
88
- write: send,
89
+ write: turning(send),
89
90
  close() {
90
91
  const closing = pipe
91
92
  if (closing === undefined) {
@@ -8,7 +8,14 @@ import net from 'node:net'
8
8
  import manifest from '../../package.json' with { type: 'json' }
9
9
  import { ClosedError } from '../errors.ts'
10
10
  import type { PrivateChild, Runtime, TlsOptions, Transport, TransportEvents } from '../runtime.ts'
11
- import { address, exitedWith, platformPackage, spawnDetached, stderrKept } from './shared.ts'
11
+ import {
12
+ address,
13
+ connecting,
14
+ exitedWith,
15
+ platformPackage,
16
+ spawnDetached,
17
+ stderrKept,
18
+ } from './shared.ts'
12
19
 
13
20
  export const bunRuntime: Runtime = {
14
21
  get client() {
@@ -37,18 +44,19 @@ async function connect(
37
44
  endpoint: string,
38
45
  events: TransportEvents,
39
46
  tls?: TlsOptions,
47
+ signal?: AbortSignal,
40
48
  ): Promise<Transport> {
41
49
  const at = address(endpoint)
42
50
  switch (at.kind) {
43
51
  case 'pipe':
44
- return connectPipe(at.path, events)
52
+ return connectPipe(at.path, events, signal)
45
53
  case 'unix': {
46
54
  const path = at.path
47
- return connectSocket(socket => Bun.connect({ unix: path, socket }), events)
55
+ return connectSocket(socket => Bun.connect({ unix: path, socket }), events, signal)
48
56
  }
49
57
  case 'tcp': {
50
58
  const { host, port } = at
51
- return connectSocket(socket => Bun.connect({ hostname: host, port, socket }), events)
59
+ return connectSocket(socket => Bun.connect({ hostname: host, port, socket }), events, signal)
52
60
  }
53
61
  case 'tls': {
54
62
  const { host, port } = at
@@ -59,6 +67,7 @@ async function connect(
59
67
  return connectSocket(
60
68
  socket => Bun.connect({ hostname: host, port, tls: verify, socket }),
61
69
  events,
70
+ signal,
62
71
  )
63
72
  }
64
73
  }
@@ -76,11 +85,14 @@ interface Handlers {
76
85
 
77
86
  /**
78
87
  * A socket's write may take part of the bytes: the rest waits for its drain,
79
- * in order, so the session hands a whole frame over and forgets it.
88
+ * in order, so the session hands a whole frame over and forgets it. Bun's
89
+ * connect takes no signal: one that aborts first rejects at once, and the
90
+ * socket connected after is ended.
80
91
  */
81
92
  async function connectSocket(
82
93
  dial: (handlers: Handlers) => Promise<Socket>,
83
94
  events: TransportEvents,
95
+ signal?: AbortSignal,
84
96
  ): Promise<Transport> {
85
97
  const waiting: Uint8Array[] = []
86
98
  let ended = false
@@ -103,13 +115,14 @@ async function connectSocket(
103
115
  return
104
116
  }
105
117
  }
106
- socket = await dial({
118
+ const dialled = dial({
107
119
  data: (_, data) => events.data(data),
108
120
  drain: () => pump(),
109
121
  end: () => end(new ClosedError('the server ended the connection')),
110
122
  close: (_, err) => end(err ?? new ClosedError('the connection closed')),
111
123
  error: (_, err) => end(err),
112
124
  })
125
+ socket = await connecting(dialled, signal, late => late.end())
113
126
  return {
114
127
  write: bytes => {
115
128
  waiting.push(bytes)
@@ -121,7 +134,11 @@ async function connectSocket(
121
134
  }
122
135
  }
123
136
 
124
- function connectPipe(path: string, events: TransportEvents): Promise<Transport> {
137
+ function connectPipe(
138
+ path: string,
139
+ events: TransportEvents,
140
+ signal?: AbortSignal,
141
+ ): Promise<Transport> {
125
142
  return new Promise((resolve, reject) => {
126
143
  const socket = net.createConnection(path)
127
144
  let connected = false
@@ -132,17 +149,35 @@ function connectPipe(path: string, events: TransportEvents): Promise<Transport>
132
149
  events.end(err)
133
150
  }
134
151
  }
152
+ const abort = () => {
153
+ reject(signal?.reason)
154
+ socket.destroy()
155
+ }
156
+ if (signal?.aborted) {
157
+ abort()
158
+ return
159
+ }
160
+ signal?.addEventListener('abort', abort, { once: true })
135
161
  socket.once('connect', () => {
136
162
  connected = true
163
+ signal?.removeEventListener('abort', abort)
137
164
  resolve({ write: bytes => socket.write(bytes), close: () => socket.end() })
138
165
  })
139
166
  socket.on('data', (data: Uint8Array) => events.data(data))
140
- socket.on('error', err => (connected ? end(err) : reject(err)))
167
+ socket.on('error', err => {
168
+ if (connected) {
169
+ end(err)
170
+ return
171
+ }
172
+ signal?.removeEventListener('abort', abort)
173
+ reject(err)
174
+ })
141
175
  socket.on('close', () => end(new ClosedError('the pipe closed')))
142
176
  })
143
177
  }
144
178
 
145
- function spawnPrivate(argv: string[], events: TransportEvents): PrivateChild {
179
+ // async, so that the throw of a Bun.spawn that cannot start is its rejection
180
+ async function spawnPrivate(argv: string[], events: TransportEvents): Promise<PrivateChild> {
146
181
  const proc = Bun.spawn(argv, { stdin: 'pipe', stdout: 'pipe', stderr: 'pipe', windowsHide: true })
147
182
  let kept = ''
148
183
  // a pipe nobody drains stops the server once it fills, so stderr is read to its end
@@ -39,20 +39,22 @@ function connect(
39
39
  endpoint: string,
40
40
  events: TransportEvents,
41
41
  options?: TlsOptions,
42
+ signal?: AbortSignal,
42
43
  ): Promise<Transport> {
43
44
  const at = address(endpoint)
44
45
  switch (at.kind) {
45
46
  case 'pipe':
46
47
  case 'unix':
47
- return connected(net.createConnection(at.path), 'connect', events)
48
+ return connected(net.createConnection(at.path), 'connect', events, signal)
48
49
  case 'tcp':
49
50
  return connected(
50
51
  net.createConnection({ host: at.host, port: at.port, noDelay: true }),
51
52
  'connect',
52
53
  events,
54
+ signal,
53
55
  )
54
56
  case 'tls':
55
- return connected(connectTLS(at.host, at.port, options), 'secureConnect', events)
57
+ return connected(connectTLS(at.host, at.port, options), 'secureConnect', events, signal)
56
58
  }
57
59
  }
58
60
 
@@ -78,12 +80,13 @@ function connectTLS(host: string, port: number, options?: TlsOptions): tls.TLSSo
78
80
  /**
79
81
  * A transport once the socket is ready: a socket's write queues what the
80
82
  * kernel does not take yet, in order, so the session hands a whole frame over
81
- * and forgets it.
83
+ * and forgets it. A signal that aborts before then destroys the socket.
82
84
  */
83
85
  function connected(
84
86
  socket: net.Socket,
85
87
  ready: 'connect' | 'secureConnect',
86
88
  events: TransportEvents,
89
+ signal?: AbortSignal,
87
90
  ): Promise<Transport> {
88
91
  return new Promise((resolve, reject) => {
89
92
  let open = false
@@ -94,19 +97,41 @@ function connected(
94
97
  events.end(err)
95
98
  }
96
99
  }
100
+ const abort = () => {
101
+ reject(signal?.reason)
102
+ socket.destroy()
103
+ }
104
+ if (signal?.aborted) {
105
+ abort()
106
+ return
107
+ }
108
+ signal?.addEventListener('abort', abort, { once: true })
97
109
  socket.once(ready, () => {
98
110
  open = true
111
+ signal?.removeEventListener('abort', abort)
99
112
  resolve({ write: bytes => void socket.write(bytes), close: () => void socket.end() })
100
113
  })
101
114
  socket.on('data', (data: Uint8Array) => events.data(data))
102
- socket.on('error', err => (open ? end(err) : reject(err)))
115
+ socket.on('error', err => {
116
+ if (open) {
117
+ end(err)
118
+ return
119
+ }
120
+ signal?.removeEventListener('abort', abort)
121
+ reject(err)
122
+ })
103
123
  socket.on('end', () => end(new ClosedError('the server ended the connection')))
104
124
  socket.on('close', () => end(new ClosedError('the connection closed')))
105
125
  })
106
126
  }
107
127
 
108
- function spawnPrivate(argv: string[], events: TransportEvents): PrivateChild {
128
+ async function spawnPrivate(argv: string[], events: TransportEvents): Promise<PrivateChild> {
109
129
  const proc = spawn(argv[0]!, argv.slice(1), { stdio: 'pipe', windowsHide: true })
130
+ // a child that cannot start says so after the spawn, by its error
131
+ await new Promise((resolve, reject) => {
132
+ proc.once('spawn', resolve)
133
+ proc.once('error', reject)
134
+ })
110
135
  let kept = ''
111
136
  // a pipe nobody drains stops the server once it fills, so stderr is read to its end
112
137
  proc.stderr.setEncoding('utf8')
@@ -8,6 +8,8 @@ import { dlopen, FFIType, JSCallback, type Pointer, ptr } from 'bun:ffi'
8
8
 
9
9
  import { ClosedError } from '../errors.ts'
10
10
  import type { Transport } from '../runtime.ts'
11
+ import { bodyLength, headerSize } from '../wire/frame.ts'
12
+ import { openFailure, turning } from './shared.ts'
11
13
 
12
14
  const symbols = {
13
15
  tinystore_open: {
@@ -43,14 +45,14 @@ export interface PipeEvents {
43
45
  * read: nothing of them may be kept.
44
46
  */
45
47
  frames(bytes: Uint8Array, length: number): number
48
+ /** Reads one whole frame in bytes of its own, which the session may keep. */
49
+ frame(bytes: Uint8Array): void
46
50
  /** the store closed; called once */
47
51
  end(err: Error): void
48
52
  }
49
53
 
50
- /** The room for what the core owes, to begin with and once a large frame has passed. */
54
+ /** The room for what the core owes: a frame longer than it is written into bytes of its own. */
51
55
  const room = 1 << 16
52
- /** Room past this is given back once nothing is held in it. */
53
- const kept = 1 << 20
54
56
 
55
57
  /**
56
58
  * Opens a pipe to the store in a directory, the core loaded from `library`.
@@ -70,24 +72,45 @@ export function openPipe(
70
72
 
71
73
  // where the core writes what it owes: whole frames are read from the
72
74
  // front, and a frame's first part is held there for its rest
73
- let inbox = new Uint8Array(room)
75
+ const inbox = new Uint8Array(room)
74
76
  let held = 0
77
+ // A frame longer than the inbox, in bytes as long as it is, and how much
78
+ // of it came: the core writes its rest there, and the session keeps them,
79
+ // so that a file's mebibyte is written once here rather than copied out
80
+ // of an inbox grown for it (issue #10).
81
+ let large: Uint8Array | undefined
82
+ let filledLarge = 0
75
83
 
76
- // reads the frames among the `written` bytes behind what is held, and
77
- // says whether the core filled the room, which means more may wait
84
+ // where the core writes next, and how many bytes it may
85
+ const into = (): [Uint8Array, number, number] =>
86
+ large === undefined
87
+ ? [inbox, held, inbox.length - held]
88
+ : [large, filledLarge, large.length - filledLarge]
89
+
90
+ // reads what the core wrote where `into` said, and says whether it filled
91
+ // that room, which means more may wait
78
92
  const read = (written: number): boolean => {
93
+ if (large !== undefined) {
94
+ filledLarge += written
95
+ if (filledLarge < large.length) {
96
+ return false
97
+ }
98
+ const whole = large
99
+ large = undefined
100
+ events.frame(whole)
101
+ return true
102
+ }
79
103
  const length = held + written
80
104
  const filled = length === inbox.length
81
105
  const taken = written === 0 ? 0 : events.frames(inbox, length)
82
106
  inbox.copyWithin(0, taken, length)
83
107
  held = length - taken
84
- if (held === inbox.length) {
85
- // a frame longer than the room: twice the room, until it fits
86
- const grown = new Uint8Array(inbox.length * 2)
87
- grown.set(inbox)
88
- inbox = grown
89
- } else if (held === 0 && inbox.length > kept) {
90
- inbox = new Uint8Array(room)
108
+ const frameLength = held < headerSize ? 0 : headerSize + bodyLength(inbox)
109
+ if (frameLength > inbox.length) {
110
+ large = new Uint8Array(frameLength)
111
+ large.set(inbox.subarray(0, held))
112
+ filledLarge = held
113
+ held = 0
91
114
  }
92
115
  return filled
93
116
  }
@@ -106,8 +129,8 @@ export function openPipe(
106
129
  try {
107
130
  let filled = written === undefined || read(written)
108
131
  while (filled && connection !== null) {
109
- const free = inbox.length - held
110
- filled = read(Number(lib.symbols.tinystore_recv(connection, 0, ptr(inbox, held), free)))
132
+ const [bytes, at, free] = into()
133
+ filled = read(Number(lib.symbols.tinystore_recv(connection, 0, ptr(bytes, at), free)))
111
134
  }
112
135
  } finally {
113
136
  reading = false
@@ -126,12 +149,12 @@ export function openPipe(
126
149
  waiting.push(bytes)
127
150
  return
128
151
  }
129
- const free = inbox.length - held
152
+ const [owed, at, free] = into()
130
153
  const written = lib.symbols.tinystore_send(
131
154
  connection,
132
155
  ptr(bytes),
133
156
  bytes.length,
134
- ptr(inbox, held),
157
+ ptr(owed, at),
135
158
  free,
136
159
  )
137
160
  readOn(Number(written))
@@ -159,17 +182,24 @@ export function openPipe(
159
182
  const message = new TextDecoder().decode(failure.subarray(0, failed))
160
183
  wake.close()
161
184
  lib.close()
162
- throw new ClosedError(`cannot open ${dir}: ${message}`)
185
+ throw openFailure(dir, message)
163
186
  }
164
187
  connection = Number(opened[0]) as Pointer
188
+ // Bun's loop with no timer armed spins while it waits for a threadsafe
189
+ // callback from another thread: a write waiting for its sync burned a
190
+ // whole processor (research release-2026-10-23). A timer armed, however
191
+ // far off, lets the loop sleep until the core wakes it; it also keeps the
192
+ // process alive while the store is open, as a sidecar's socket does.
193
+ const sleeps = setInterval(() => {}, 2 ** 30)
165
194
  return {
166
- write: send,
195
+ write: turning(send),
167
196
  close() {
168
197
  if (connection === null) {
169
198
  return
170
199
  }
171
200
  const closing = connection
172
201
  connection = null
202
+ clearInterval(sleeps)
173
203
  lib.symbols.tinystore_close(closing)
174
204
  wake.close()
175
205
  events.end(new ClosedError('the store closed'))
@@ -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. */