@tinyshed/tinystore 0.1.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 (100) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +262 -0
  3. package/bin/tinystore.js +50 -0
  4. package/dist/background.d.ts +30 -0
  5. package/dist/background.js +93 -0
  6. package/dist/blobs.d.ts +98 -0
  7. package/dist/blobs.js +299 -0
  8. package/dist/cancel.d.ts +14 -0
  9. package/dist/cancel.js +22 -0
  10. package/dist/clock.d.ts +21 -0
  11. package/dist/clock.js +35 -0
  12. package/dist/config.d.ts +60 -0
  13. package/dist/config.js +417 -0
  14. package/dist/connection.d.ts +78 -0
  15. package/dist/connection.js +405 -0
  16. package/dist/console.d.ts +48 -0
  17. package/dist/console.js +195 -0
  18. package/dist/errors.d.ts +103 -0
  19. package/dist/errors.js +158 -0
  20. package/dist/handles.d.ts +28 -0
  21. package/dist/handles.js +37 -0
  22. package/dist/index.d.ts +21 -0
  23. package/dist/index.js +7 -0
  24. package/dist/jobs.d.ts +304 -0
  25. package/dist/jobs.js +684 -0
  26. package/dist/kv.d.ts +283 -0
  27. package/dist/kv.js +815 -0
  28. package/dist/limiter.d.ts +45 -0
  29. package/dist/limiter.js +68 -0
  30. package/dist/logger.d.ts +96 -0
  31. package/dist/logger.js +243 -0
  32. package/dist/metrics.d.ts +249 -0
  33. package/dist/metrics.js +610 -0
  34. package/dist/once.d.ts +31 -0
  35. package/dist/once.js +116 -0
  36. package/dist/quota.d.ts +44 -0
  37. package/dist/quota.js +98 -0
  38. package/dist/records.d.ts +182 -0
  39. package/dist/records.js +346 -0
  40. package/dist/runtime/bun.d.ts +2 -0
  41. package/dist/runtime/bun.js +164 -0
  42. package/dist/runtime/node.d.ts +2 -0
  43. package/dist/runtime/node.js +157 -0
  44. package/dist/runtime/shared.d.ts +25 -0
  45. package/dist/runtime/shared.js +45 -0
  46. package/dist/runtime.d.ts +48 -0
  47. package/dist/runtime.js +4 -0
  48. package/dist/schema.d.ts +39 -0
  49. package/dist/schema.js +21 -0
  50. package/dist/session.d.ts +120 -0
  51. package/dist/session.js +546 -0
  52. package/dist/sql.d.ts +121 -0
  53. package/dist/sql.js +342 -0
  54. package/dist/store.d.ts +103 -0
  55. package/dist/store.js +153 -0
  56. package/dist/time.d.ts +35 -0
  57. package/dist/time.js +44 -0
  58. package/dist/trace.d.ts +18 -0
  59. package/dist/trace.js +22 -0
  60. package/dist/wire/codec.d.ts +90 -0
  61. package/dist/wire/codec.js +383 -0
  62. package/dist/wire/frame.d.ts +41 -0
  63. package/dist/wire/frame.js +102 -0
  64. package/dist/wire/messages.d.ts +1403 -0
  65. package/dist/wire/messages.js +472 -0
  66. package/dist/wire/msgpack.d.ts +93 -0
  67. package/dist/wire/msgpack.js +680 -0
  68. package/package.json +40 -0
  69. package/src/background.ts +108 -0
  70. package/src/blobs.ts +437 -0
  71. package/src/cancel.ts +26 -0
  72. package/src/clock.ts +45 -0
  73. package/src/config.ts +501 -0
  74. package/src/connection.ts +512 -0
  75. package/src/console.ts +228 -0
  76. package/src/errors.ts +211 -0
  77. package/src/handles.ts +68 -0
  78. package/src/index.ts +92 -0
  79. package/src/jobs.ts +963 -0
  80. package/src/kv.ts +1093 -0
  81. package/src/limiter.ts +99 -0
  82. package/src/logger.ts +326 -0
  83. package/src/metrics.ts +896 -0
  84. package/src/once.ts +142 -0
  85. package/src/quota.ts +137 -0
  86. package/src/records.ts +537 -0
  87. package/src/runtime/bun.ts +190 -0
  88. package/src/runtime/node.ts +177 -0
  89. package/src/runtime/shared.ts +61 -0
  90. package/src/runtime.ts +57 -0
  91. package/src/schema.ts +69 -0
  92. package/src/session.ts +665 -0
  93. package/src/sql.ts +478 -0
  94. package/src/store.ts +219 -0
  95. package/src/time.ts +87 -0
  96. package/src/trace.ts +32 -0
  97. package/src/wire/codec.ts +445 -0
  98. package/src/wire/frame.ts +139 -0
  99. package/src/wire/messages.ts +562 -0
  100. package/src/wire/msgpack.ts +712 -0
@@ -0,0 +1,108 @@
1
+ // What the SDK does in the background, an instrument's flush or a logger's
2
+ // write, has no caller to tell when it fails. It says so as Go's
3
+ // tinystore.Store does, in TinyStore's own lines: once, again when the
4
+ // failure changes or ten minutes on, and once more when the work recovers.
5
+
6
+ import type { Fields } from './records.ts'
7
+
8
+ /** A failure repeated within this long is counted rather than said again. */
9
+ const quiet = 10 * 60_000
10
+
11
+ /** Where TinyStore's own lines go: the console of a logger of stream tinystore, or a test's. */
12
+ export type Say = (level: 'info' | 'warn', message: string, fields: Fields) => void
13
+
14
+ /**
15
+ * A background work's failures, said as Go's failureLog logs them:
16
+ *
17
+ * 00:00 disk full → warn "background work failed" failures=1
18
+ * 00:01…00:09 the same → counted
19
+ * 00:10 disk full → warn failures=11
20
+ * 00:11 success → info "background work recovered" failures=11
21
+ */
22
+ export class FailureLog {
23
+ readonly #work: string
24
+ readonly #say: Say
25
+ readonly #now: () => number
26
+ #last = ''
27
+ #saidAt = 0
28
+ #failures = 0
29
+
30
+ constructor(work: string, say: Say, now: () => number = Date.now) {
31
+ this.#work = work
32
+ this.#say = say
33
+ this.#now = now
34
+ }
35
+
36
+ failed(err: unknown): void {
37
+ this.#failures++
38
+ const error = messageOf(err)
39
+ if (error === this.#last && this.#now() - this.#saidAt < quiet) {
40
+ return
41
+ }
42
+ this.#say('warn', 'background work failed', {
43
+ work: this.#work,
44
+ error,
45
+ failures: this.#failures,
46
+ })
47
+ this.#last = error
48
+ this.#saidAt = this.#now()
49
+ }
50
+
51
+ succeeded(): void {
52
+ if (this.#failures > 0) {
53
+ this.#say('info', 'background work recovered', {
54
+ work: this.#work,
55
+ failures: this.#failures,
56
+ })
57
+ }
58
+ this.#last = ''
59
+ this.#failures = 0
60
+ }
61
+ }
62
+
63
+ /**
64
+ * The lines a logger dropped for want of room, said at a flush and at most
65
+ * once in a quiet period: a burst is one line, and a logger that keeps
66
+ * dropping says how many every ten minutes rather than every second.
67
+ */
68
+ export class DropNotice {
69
+ readonly #stream: string
70
+ readonly #buffer: number
71
+ readonly #say: Say
72
+ readonly #now: () => number
73
+ #unsaid = 0
74
+ #saidAt: number | undefined
75
+
76
+ constructor(stream: string, buffer: number, say: Say, now: () => number = Date.now) {
77
+ this.#stream = stream
78
+ this.#buffer = buffer
79
+ this.#say = say
80
+ this.#now = now
81
+ }
82
+
83
+ dropped(): void {
84
+ this.#unsaid++
85
+ }
86
+
87
+ sayIfDue(): void {
88
+ if (this.#unsaid === 0) {
89
+ return
90
+ }
91
+ if (this.#saidAt !== undefined && this.#now() - this.#saidAt < quiet) {
92
+ return
93
+ }
94
+ // logger, since a console line's own stream is tinystore's
95
+ this.#say('warn', 'log lines dropped', {
96
+ logger: this.#stream,
97
+ dropped: this.#unsaid,
98
+ buffer: this.#buffer,
99
+ })
100
+ this.#unsaid = 0
101
+ this.#saidAt = this.#now()
102
+ }
103
+ }
104
+
105
+ /** An error's message, as Go's err.Error() reads, without the class JavaScript puts first. */
106
+ export function messageOf(err: unknown): string {
107
+ return err instanceof Error ? err.message : String(err)
108
+ }
package/src/blobs.ts ADDED
@@ -0,0 +1,437 @@
1
+ // The application's files in blobs/, as Go's blobs package keeps them:
2
+ // objects under keys that are paths, their bytes streamed both ways in DATA
3
+ // of 64 KiB at most, a whole read checked against the object's hash.
4
+
5
+ import { type Connection, download, type Link } from './connection.ts'
6
+ import { ClosedError, InvalidError, OutcomeUnknownError } from './errors.ts'
7
+ import { checkName, handleOn, type Page } from './handles.ts'
8
+ import { LostError, type Stream, watch } from './session.ts'
9
+ import { type Duration, dateOf, ms, type Time, unixMs } from './time.ts'
10
+ import type { Key } from './wire/codec.ts'
11
+ import {
12
+ BlobsBucket,
13
+ BlobsCall,
14
+ BlobsObject,
15
+ BlobsPage,
16
+ BlobsTotal,
17
+ methods,
18
+ } from './wire/messages.ts'
19
+
20
+ /** The most a DATA frame carries, so that no transfer holds the connection long. */
21
+ const chunk = 64 << 10
22
+
23
+ export interface BlobObject {
24
+ /** its path under the folder that returned it */
25
+ key: string
26
+ size: number
27
+ /** quoted, as an HTTP header carries it: equal bytes, one ETag */
28
+ etag: string
29
+ contentType: string | undefined
30
+ modified: Date
31
+ /** undefined for an object that does not expire */
32
+ expires: Date | undefined
33
+ meta: Record<string, string>
34
+ }
35
+
36
+ export interface WriteOptions {
37
+ contentType?: string
38
+ /** replaces all of an object's meta; a copy keeps its source's when absent */
39
+ meta?: Record<string, string>
40
+ ttl?: Duration
41
+ expireAt?: Time
42
+ /** writes only while the key holds a live object with one of these ETags, as If-Match spells them */
43
+ ifMatch?: string
44
+ /** writes only where no live object is */
45
+ ifNoneMatch?: boolean
46
+ }
47
+
48
+ export interface PutOptions extends WriteOptions {
49
+ /** the body's length, when it cannot say itself: one that disagrees leaves nothing */
50
+ size?: number
51
+ signal?: AbortSignal
52
+ }
53
+
54
+ /** What a put takes: bytes, text, a Blob or a file, or a stream of bytes. */
55
+ export type Body =
56
+ | Uint8Array
57
+ | ArrayBuffer
58
+ | string
59
+ | Blob
60
+ | ReadableStream<Uint8Array>
61
+ | AsyncIterable<Uint8Array>
62
+
63
+ /** An object being read: what it is, and its bytes as a stream to consume or cancel. */
64
+ export interface Download extends BlobObject {
65
+ /** its bytes; a whole read whose bytes changed ends with CorruptError before its last */
66
+ readonly body: ReadableStream<Uint8Array>
67
+ bytes(): Promise<Uint8Array>
68
+ text(): Promise<string>
69
+ json(): Promise<unknown>
70
+ }
71
+
72
+ export class Blobs {
73
+ readonly #link: Link
74
+
75
+ constructor(link: Link) {
76
+ this.#link = link
77
+ }
78
+
79
+ bucket(name: string, options?: { defaultTtl?: Duration; maxSize?: number }): BlobBucket {
80
+ checkName(name, 'bucket')
81
+ const open = BlobsBucket.encode({
82
+ name,
83
+ defaultTtl: options?.defaultTtl === undefined ? undefined : ms(options.defaultTtl),
84
+ maxSize: options?.maxSize,
85
+ })
86
+ return new BlobBucket(this.#link, name, open, [])
87
+ }
88
+ }
89
+
90
+ function ownerText(owner: Key): string | Uint8Array {
91
+ if (typeof owner === 'number' || typeof owner === 'bigint') {
92
+ if (typeof owner === 'number' && !Number.isSafeInteger(owner)) {
93
+ throw new InvalidError(`the owner ${owner} is not an integer; an owner is text or an integer`)
94
+ }
95
+ return String(owner)
96
+ }
97
+ return owner
98
+ }
99
+
100
+ const lossy = new TextDecoder()
101
+
102
+ function objectOf(o: ReturnType<typeof BlobsObject.decode>): BlobObject {
103
+ const meta: Record<string, string> = {}
104
+ for (const [name, value] of Object.entries(o.meta ?? {})) {
105
+ meta[name] = typeof value === 'string' ? value : lossy.decode(value)
106
+ }
107
+ return {
108
+ key: o.key ?? '',
109
+ size: o.size ?? 0,
110
+ etag: o.etag ?? '',
111
+ contentType: o.contentType,
112
+ modified: new Date(o.modified ?? 0),
113
+ expires: dateOf(o.expires),
114
+ meta,
115
+ }
116
+ }
117
+
118
+ function writeFields(options: WriteOptions | undefined) {
119
+ return {
120
+ contentType: options?.contentType,
121
+ meta: options?.meta,
122
+ ttl: options?.ttl === undefined ? undefined : ms(options.ttl),
123
+ expireAt: options?.expireAt === undefined ? undefined : unixMs(options.expireAt),
124
+ ifMatch: options?.ifMatch,
125
+ ifNoneMatch: options?.ifNoneMatch === true ? true : undefined,
126
+ }
127
+ }
128
+
129
+ type CallFields = Omit<Parameters<typeof BlobsCall.encode>[0], 'handle' | 'owners'>
130
+
131
+ /** A bucket's objects under one folder of owners, the root when there are none. */
132
+ export class BlobBucket {
133
+ readonly name: string
134
+ readonly #link: Link
135
+ readonly #open: Uint8Array
136
+ readonly #owners: (string | Uint8Array)[]
137
+
138
+ constructor(link: Link, name: string, open: Uint8Array, owners: (string | Uint8Array)[]) {
139
+ this.#link = link
140
+ this.name = name
141
+ this.#open = open
142
+ this.#owners = owners
143
+ }
144
+
145
+ /** The folder below this one that the owners name, each a segment: `of('users', 7)`. */
146
+ of(...owners: Key[]): BlobBucket {
147
+ return new BlobBucket(this.#link, this.name, this.#open, [
148
+ ...this.#owners,
149
+ ...owners.map(ownerText),
150
+ ])
151
+ }
152
+
153
+ async #call(connection: Connection, fields: CallFields) {
154
+ const handle = await handleOn(connection, methods['blobs.open'], this.#open)
155
+ return BlobsCall.encode({
156
+ handle,
157
+ owners: this.#owners.length > 0 ? this.#owners : undefined,
158
+ ...fields,
159
+ })
160
+ }
161
+
162
+ async #one(method: keyof typeof methods, fields: CallFields, idempotence: 'read' | 'write') {
163
+ return this.#link.run(idempotence, async connection =>
164
+ connection.session.call(methods[method], await this.#call(connection, fields)),
165
+ )
166
+ }
167
+
168
+ /** The object at a key, undefined when it holds none. */
169
+ async stat(key: string): Promise<BlobObject | undefined> {
170
+ const o = BlobsObject.decode(await this.#one('blobs.stat', { key }, 'read'))
171
+ return o.found === true ? objectOf(o) : undefined
172
+ }
173
+
174
+ async delete(key: string, options?: Pick<WriteOptions, 'ifMatch'>): Promise<void> {
175
+ await this.#one('blobs.delete', { key, ifMatch: options?.ifMatch }, 'write')
176
+ }
177
+
178
+ /** Writes to a key an object naming the source's bytes, which are neither read nor written. */
179
+ async copy(from: string, to: string, options?: WriteOptions): Promise<BlobObject> {
180
+ return objectOf(
181
+ BlobsObject.decode(
182
+ await this.#one('blobs.copy', { key: from, to, ...writeFields(options) }, 'write'),
183
+ ),
184
+ )
185
+ }
186
+
187
+ /** Copy and the source's removal in one write. */
188
+ async move(from: string, to: string, options?: WriteOptions): Promise<BlobObject> {
189
+ return objectOf(
190
+ BlobsObject.decode(
191
+ await this.#one('blobs.move', { key: from, to, ...writeFields(options) }, 'write'),
192
+ ),
193
+ )
194
+ }
195
+
196
+ /** The objects under this folder and their bytes, counted from their rows. */
197
+ async usage(): Promise<{ objects: number; bytes: number }> {
198
+ const total = BlobsTotal.decode(await this.#one('blobs.usage', {}, 'read'))
199
+ return { objects: total.objects ?? 0, bytes: total.bytes ?? 0 }
200
+ }
201
+
202
+ /** Removes this folder's objects and every folder's under it, at once however many. */
203
+ async clear(): Promise<void> {
204
+ await this.#one('blobs.clear', {}, 'write')
205
+ }
206
+
207
+ /** A page of the objects under this folder, its folders included, in the byte order of their paths. */
208
+ async scan(options?: {
209
+ prefix?: string
210
+ after?: string
211
+ limit?: number
212
+ }): Promise<Page<BlobObject, string>> {
213
+ const got = await this.#link.run('read', async connection =>
214
+ download(
215
+ connection,
216
+ methods['blobs.scan'],
217
+ await this.#call(connection, {
218
+ prefix: options?.prefix,
219
+ after: options?.after,
220
+ limit: options?.limit,
221
+ }),
222
+ ),
223
+ )
224
+ const page = BlobsPage.decode(got.trailer)
225
+ return {
226
+ items: got.items.map(item => objectOf(BlobsObject.decode(item))),
227
+ next: page.more === true ? (page.after ?? '') : undefined,
228
+ }
229
+ }
230
+
231
+ async *all(options?: { prefix?: string; limit?: number }): AsyncGenerator<BlobObject> {
232
+ let after: string | undefined
233
+ for (;;) {
234
+ const page = await this.scan({ ...options, ...(after === undefined ? {} : { after }) })
235
+ yield* page.items
236
+ if (page.next === undefined) {
237
+ return
238
+ }
239
+ after = page.next
240
+ }
241
+ }
242
+
243
+ /**
244
+ * Writes an object, returning once it is durable: whatever the key held is
245
+ * replaced at the commit, whole, and an upload that does not commit leaves
246
+ * nothing. A Blob, a file among them, gives its size and its type.
247
+ */
248
+ async put(key: string, body: Body, options?: PutOptions): Promise<BlobObject> {
249
+ const source = sourceOf(body, options?.size)
250
+ const fields = {
251
+ ...writeFields(options),
252
+ contentType: options?.contentType ?? source.contentType,
253
+ }
254
+ return this.#link.run(
255
+ 'write',
256
+ async connection => {
257
+ const request = await this.#call(connection, { key, size: source.size, ...fields })
258
+ return upload(connection, request, source, options?.signal)
259
+ },
260
+ options?.signal,
261
+ )
262
+ }
263
+
264
+ /**
265
+ * Reads an object, undefined when the key holds none: what it is at once,
266
+ * and its bytes as its body is read. A range, from offset and length bytes
267
+ * long, is not checked against the object's hash.
268
+ */
269
+ async get(
270
+ key: string,
271
+ options?: { offset?: number; length?: number; signal?: AbortSignal },
272
+ ): Promise<Download | undefined> {
273
+ return this.#link.run(
274
+ 'read',
275
+ async connection => {
276
+ const request = await this.#call(connection, {
277
+ key,
278
+ offset: options?.offset,
279
+ length: options?.length,
280
+ })
281
+ const stream = await connection.session.open(methods['blobs.get'], request, true)
282
+ const unwatch = watch(options?.signal, stream)
283
+ const head = await stream.next().catch(err => {
284
+ unwatch()
285
+ throw err
286
+ })
287
+ const o = BlobsObject.decode(head.body)
288
+ if (head.end || o.found !== true) {
289
+ unwatch()
290
+ return undefined
291
+ }
292
+ return downloadOf(objectOf(o), stream, unwatch)
293
+ },
294
+ options?.signal,
295
+ )
296
+ }
297
+ }
298
+
299
+ /**
300
+ * A body as chunks of 64 KiB at most, its size and type when it knows them,
301
+ * and whether it reads again for a second try.
302
+ */
303
+ interface Source {
304
+ size: number | undefined
305
+ contentType: string | undefined
306
+ replayable: boolean
307
+ chunks(): AsyncIterable<Uint8Array>
308
+ }
309
+
310
+ function sourceOf(body: Body, size: number | undefined): Source {
311
+ if (typeof body === 'string') {
312
+ body = new TextEncoder().encode(body)
313
+ }
314
+ if (body instanceof ArrayBuffer) {
315
+ body = new Uint8Array(body)
316
+ }
317
+ if (body instanceof Uint8Array) {
318
+ const bytes = body
319
+ return {
320
+ size: size ?? bytes.length,
321
+ contentType: undefined,
322
+ replayable: true,
323
+ chunks: () => sliced(bytes),
324
+ }
325
+ }
326
+ if (body instanceof Blob) {
327
+ const blob = body
328
+ const contentType = blob.type === '' ? undefined : blob.type
329
+ return {
330
+ size: size ?? blob.size,
331
+ contentType,
332
+ replayable: true,
333
+ chunks: () => rechunked(blob.stream()),
334
+ }
335
+ }
336
+ const stream = body
337
+ return { size, contentType: undefined, replayable: false, chunks: () => rechunked(stream) }
338
+ }
339
+
340
+ async function* sliced(bytes: Uint8Array): AsyncGenerator<Uint8Array> {
341
+ for (let at = 0; at < bytes.length; at += chunk) {
342
+ yield bytes.subarray(at, at + chunk)
343
+ }
344
+ }
345
+
346
+ async function* rechunked(
347
+ stream: AsyncIterable<Uint8Array> | ReadableStream<Uint8Array>,
348
+ ): AsyncGenerator<Uint8Array> {
349
+ for await (const piece of stream as AsyncIterable<Uint8Array>) {
350
+ yield* sliced(piece)
351
+ }
352
+ }
353
+
354
+ /**
355
+ * Sends a put's REQUEST, its bytes as DATA and the DATA that ends them, and
356
+ * waits for the object the commit wrote. A connection lost before that last
357
+ * DATA has left aborted the upload, which left nothing; lost after it, the
358
+ * commit's outcome is unknown.
359
+ */
360
+ async function upload(
361
+ connection: Connection,
362
+ request: Uint8Array,
363
+ source: Source,
364
+ signal?: AbortSignal,
365
+ ) {
366
+ const stream = await connection.session.open(methods['blobs.put'], request, false)
367
+ const unwatch = watch(signal, stream)
368
+ let ended = false
369
+ try {
370
+ let last: Uint8Array | undefined
371
+ for await (const piece of source.chunks()) {
372
+ if (piece.length === 0) {
373
+ continue
374
+ }
375
+ if (last !== undefined) {
376
+ await stream.send(last, false)
377
+ }
378
+ last = piece
379
+ }
380
+ ended = true
381
+ await stream.send(last ?? new Uint8Array(0), true)
382
+ const answer = await stream.next()
383
+ return objectOf(BlobsObject.decode(answer.body))
384
+ } catch (err) {
385
+ if (err instanceof LostError) {
386
+ if (ended) {
387
+ throw new OutcomeUnknownError(
388
+ `the connection was lost as the upload committed: ${err.message}`,
389
+ )
390
+ }
391
+ if (!source.replayable) {
392
+ throw new ClosedError(
393
+ `the connection was lost during the upload, which left nothing: ${err.message}`,
394
+ )
395
+ }
396
+ // the server aborted what it had of it, so the whole body goes again
397
+ throw new LostError(err.message, false)
398
+ }
399
+ stream.cancel()
400
+ throw err
401
+ } finally {
402
+ unwatch()
403
+ }
404
+ }
405
+
406
+ function downloadOf(object: BlobObject, stream: Stream, unwatch: () => void): Download {
407
+ const body = new ReadableStream<Uint8Array>({
408
+ async pull(controller) {
409
+ try {
410
+ const event = await stream.next()
411
+ stream.consumed(event.body.length)
412
+ if (event.body.length > 0) {
413
+ controller.enqueue(event.body)
414
+ }
415
+ if (event.end) {
416
+ unwatch()
417
+ controller.close()
418
+ }
419
+ } catch (err) {
420
+ unwatch()
421
+ controller.error(err)
422
+ }
423
+ },
424
+ cancel() {
425
+ unwatch()
426
+ stream.cancel()
427
+ },
428
+ })
429
+ const bytes = async () => new Uint8Array(await new Response(body).arrayBuffer())
430
+ return {
431
+ ...object,
432
+ body,
433
+ bytes,
434
+ text: async () => new TextDecoder().decode(await bytes()),
435
+ json: async () => JSON.parse(new TextDecoder().decode(await bytes())),
436
+ }
437
+ }
package/src/cancel.ts ADDED
@@ -0,0 +1,26 @@
1
+ // The signal a call runs under, as a Go call carries its context: every call
2
+ // made inside withSignal, and inside what it awaits, ends when it aborts.
3
+
4
+ import { AsyncLocalStorage } from 'node:async_hooks'
5
+
6
+ const carried = new AsyncLocalStorage<AbortSignal>()
7
+
8
+ /**
9
+ * Runs fn under a signal: every call it makes, a kv get, a statement, a
10
+ * scan, rejects once the signal aborts, its stream cancelled on the wire. A
11
+ * call given a signal of its own, as work and put take one, keeps that one.
12
+ *
13
+ * ```ts
14
+ * await withSignal(AbortSignal.timeout(2000), async () => {
15
+ * const notes = await app.all`select * from notes`
16
+ * })
17
+ * ```
18
+ */
19
+ export function withSignal<T>(signal: AbortSignal, fn: () => T): T {
20
+ return carried.run(signal, fn)
21
+ }
22
+
23
+ /** The signal the caller runs under, from withSignal. */
24
+ export function currentSignal(): AbortSignal | undefined {
25
+ return carried.getStore()
26
+ }
package/src/clock.ts ADDED
@@ -0,0 +1,45 @@
1
+ // A test's clock: the time a private server opened with `clock` runs on, which
2
+ // a test moves forward rather than waits for.
3
+
4
+ import type { Link } from './connection.ts'
5
+ import { type Duration, ms, type Time, unixMs } from './time.ts'
6
+ import { Clock as ClockMessage, methods } from './wire/messages.ts'
7
+
8
+ /**
9
+ * The clock of a store opened with `{ private: true, clock }`. Moving it
10
+ * forward expires keys, makes jobs due and ages records at once, as Go's
11
+ * tinystore.Options.Clock does; a store on the system's time refuses it with
12
+ * InvalidError.
13
+ *
14
+ * await using store = await open(dir, { private: true, clock: new Date('2026-10-03T09:00:00Z') })
15
+ * await store.clock.advance('1h')
16
+ */
17
+ export class Clock {
18
+ readonly #link: Link
19
+
20
+ constructor(link: Link) {
21
+ this.#link = link
22
+ }
23
+
24
+ /** The time the server's clock reads. */
25
+ now(): Promise<Date> {
26
+ return this.#move({})
27
+ }
28
+
29
+ /** Moves the clock forward by a while, and gives the time it then reads. */
30
+ advance(by: Duration): Promise<Date> {
31
+ return this.#move({ advance: ms(by) })
32
+ }
33
+
34
+ /** Sets the clock to a time, which may not be before its own, and gives it. */
35
+ set(to: Time): Promise<Date> {
36
+ return this.#move({ at: unixMs(to) })
37
+ }
38
+
39
+ async #move(fields: Parameters<typeof ClockMessage.encode>[0]): Promise<Date> {
40
+ const body = await this.#link.run('write', connection =>
41
+ connection.session.call(methods['server.clock'], ClockMessage.encode(fields)),
42
+ )
43
+ return new Date(Number(ClockMessage.decode(body).at ?? 0))
44
+ }
45
+ }