@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/session.ts CHANGED
@@ -6,7 +6,7 @@
6
6
 
7
7
  import { createHmac, timingSafeEqual } from 'node:crypto'
8
8
 
9
- import { currentSignal } from './cancel.ts'
9
+ import { checkSignal, currentSignal, unlessCancelled } from './cancel.ts'
10
10
  import {
11
11
  CancelledError,
12
12
  ClosedError,
@@ -18,6 +18,7 @@ import {
18
18
  } from './errors.ts'
19
19
  import type { Read } from './wire/codec.ts'
20
20
  import {
21
+ bodyLength,
21
22
  checkHeader,
22
23
  credit,
23
24
  Flag,
@@ -105,6 +106,7 @@ export class Stream {
105
106
  #creditWaiters: Waiter<void>[] = []
106
107
  #granting = 0
107
108
  #cancelled = false
109
+ #finishing: (() => void)[] = []
108
110
 
109
111
  constructor(session: Session, id: number, method: number, uploadCredit: number) {
110
112
  this.#session = session
@@ -161,15 +163,23 @@ export class Stream {
161
163
  /**
162
164
  * Asks the server to stop. A stream whose REQUEST has not left never
163
165
  * leaves; one that has keeps its number until the server's final frame,
164
- * which is dropped.
166
+ * which is dropped. What waits on it fails with `failure`.
165
167
  */
166
- cancel(): void {
168
+ cancel(failure: Error = new CancelledError('the call was cancelled')): void {
167
169
  if (this.finished || this.#cancelled) {
168
170
  return
169
171
  }
170
172
  this.#cancelled = true
171
173
  this.#session.cancel(this)
172
- this.fail(new CancelledError('the call was cancelled'))
174
+ this.fail(failure)
175
+ }
176
+
177
+ /** Resolves once the server's final frame came, or the connection ended. */
178
+ finishing(): Promise<void> {
179
+ if (this.finished) {
180
+ return Promise.resolve()
181
+ }
182
+ return new Promise(resolve => this.#finishing.push(resolve))
173
183
  }
174
184
 
175
185
  get cancelled(): boolean {
@@ -212,6 +222,9 @@ export class Stream {
212
222
  for (const w of this.#creditWaiters.splice(0)) {
213
223
  w.resolve()
214
224
  }
225
+ for (const finished of this.#finishing.splice(0)) {
226
+ finished()
227
+ }
215
228
  this.#unwatch?.()
216
229
  this.#unwatch = undefined
217
230
  }
@@ -279,7 +292,9 @@ export class Session {
279
292
  readonly #leave = () => this.#flush()
280
293
  readonly #reader = new Reader(new Uint8Array(0))
281
294
 
282
- #rest: Uint8Array | undefined
295
+ // a frame's first part, as long as the whole frame, and how much of it came
296
+ #partial: Uint8Array | undefined
297
+ #gathered = 0
283
298
  #goingAway = false
284
299
  #ended: Error | undefined
285
300
  readonly #endListeners: ((err: Error) => void)[] = []
@@ -341,19 +356,20 @@ export class Session {
341
356
  /**
342
357
  * Opens a stream with its REQUEST. End says the REQUEST is the client's
343
358
  * whole side; an upload's DATA follows through the stream otherwise. It
344
- * waits while the streams in flight are all in use.
359
+ * waits for the WELCOME, and while the streams in flight are all in use,
360
+ * each wait until the caller's signal aborts.
345
361
  */
346
362
  async open(method: number, body: Uint8Array, end: boolean): Promise<Stream> {
347
363
  const signal = currentSignal()
348
- signal?.throwIfAborted()
349
- const agreed = await this.welcomed
364
+ checkSignal(signal)
365
+ const agreed = await unlessCancelled(this.welcomed, signal)
350
366
  if (body.length > agreed.maxBody) {
351
367
  throw new LimitError(
352
368
  `a request of ${body.length} bytes, past the ${agreed.maxBody} a body holds`,
353
369
  )
354
370
  }
355
371
  while (this.#streams.size >= agreed.inFlight && this.#usable() === undefined) {
356
- await new Promise<void>((resolve, reject) => this.#waitingToOpen.push({ resolve, reject }))
372
+ await this.#streamFreed(signal)
357
373
  }
358
374
  const refused = this.#usable()
359
375
  if (refused !== undefined) {
@@ -373,6 +389,38 @@ export class Session {
373
389
  return stream
374
390
  }
375
391
 
392
+ /**
393
+ * Waits for a stream to free; a caller whose signal aborts gives up its
394
+ * place in the line, which the next caller then has.
395
+ */
396
+ #streamFreed(signal: AbortSignal | undefined): Promise<void> {
397
+ return new Promise<void>((resolve, reject) => {
398
+ const abort = () => {
399
+ const at = this.#waitingToOpen.indexOf(waiter)
400
+ if (at >= 0) {
401
+ this.#waitingToOpen.splice(at, 1)
402
+ }
403
+ reject(new CancelledError('the call was cancelled'))
404
+ }
405
+ const waiter: Waiter<void> = {
406
+ resolve: () => {
407
+ signal?.removeEventListener('abort', abort)
408
+ resolve()
409
+ },
410
+ reject: err => {
411
+ signal?.removeEventListener('abort', abort)
412
+ reject(err)
413
+ },
414
+ }
415
+ this.#waitingToOpen.push(waiter)
416
+ if (signal?.aborted) {
417
+ abort()
418
+ return
419
+ }
420
+ signal?.addEventListener('abort', abort, { once: true })
421
+ })
422
+ }
423
+
376
424
  /** Why no stream may open now: the connection ended or is going away. */
377
425
  #usable(): Error | undefined {
378
426
  if (this.#ended !== undefined) {
@@ -437,7 +485,7 @@ export class Session {
437
485
 
438
486
  /** A call: one REQUEST, and the RESPONSE that answers it. */
439
487
  async call(method: number, body: Uint8Array, signal?: AbortSignal): Promise<Uint8Array> {
440
- signal?.throwIfAborted()
488
+ checkSignal(signal)
441
489
  const stream = await this.open(method, body, true)
442
490
  const unwatch = watch(signal, stream)
443
491
  try {
@@ -524,21 +572,21 @@ export class Session {
524
572
 
525
573
  cancel(stream: Stream): void {
526
574
  if (!stream.sent) {
527
- this.#queue = this.#queue.filter(q => q.stream !== stream)
528
575
  this.#release(stream)
529
576
  return
530
577
  }
531
578
  this.post(frame(Kind.cancel, 0, 0, stream.id, new Uint8Array(0)))
532
579
  }
533
580
 
534
- // takes a stream out of use, dropping what of it has not left: its number
535
- // may be named again at once
581
+ // takes a stream out of use, dropping what of it has not left, its
582
+ // REQUEST too: its number may be named again at once, and a REQUEST left
583
+ // queued would leave on a number the session no longer knows
536
584
  #release(stream: Stream): void {
537
585
  stream.finish()
538
586
  if (this.#streams.get(stream.id) === stream) {
539
587
  this.#streams.delete(stream.id)
540
588
  }
541
- this.#queue = this.#queue.filter(q => q.stream !== stream || q.request)
589
+ this.#queue = this.#queue.filter(q => q.stream !== stream)
542
590
  this.#waitingToOpen.shift()?.resolve()
543
591
  }
544
592
 
@@ -547,16 +595,54 @@ export class Session {
547
595
  if (this.#ended !== undefined) {
548
596
  return
549
597
  }
550
- let bytes = chunk
551
- if (this.#rest !== undefined) {
552
- bytes = new Uint8Array(this.#rest.length + chunk.length)
553
- bytes.set(this.#rest)
554
- bytes.set(chunk, this.#rest.length)
555
- this.#rest = undefined
598
+ const at = this.#partial === undefined ? 0 : this.#gather(chunk)
599
+ if (at === chunk.length || this.#ended !== undefined) {
600
+ return
556
601
  }
557
- const at = this.read(bytes, bytes.length)
558
- if (at < bytes.length && this.#ended === undefined) {
559
- this.#rest = bytes.slice(at)
602
+ const rest = chunk.subarray(at)
603
+ const taken = this.read(rest, rest.length)
604
+ if (taken < rest.length && this.#ended === undefined) {
605
+ this.#hold(rest.subarray(taken))
606
+ }
607
+ }
608
+
609
+ // Keeps a frame's first part in bytes as long as the whole frame, once
610
+ // its header has come, which `read` has checked: the rest is written
611
+ // behind it as it comes. A mebibyte that came in sixteen pieces was
612
+ // copied again for each piece before (issue #10).
613
+ #hold(part: Uint8Array): void {
614
+ const length = part.length < headerSize ? headerSize : headerSize + bodyLength(part)
615
+ this.#partial = new Uint8Array(length)
616
+ this.#partial.set(part)
617
+ this.#gathered = part.length
618
+ }
619
+
620
+ // writes the chunk's first bytes behind the frame held, reads the frame
621
+ // once it is whole, and says how many of the chunk's bytes it took
622
+ #gather(chunk: Uint8Array): number {
623
+ let at = 0
624
+ for (;;) {
625
+ const partial = this.#partial
626
+ if (partial === undefined) {
627
+ return at
628
+ }
629
+ const taken = Math.min(chunk.length - at, partial.length - this.#gathered)
630
+ partial.set(chunk.subarray(at, at + taken), this.#gathered)
631
+ this.#gathered += taken
632
+ at += taken
633
+ if (this.#gathered < partial.length) {
634
+ return at
635
+ }
636
+ this.#partial = undefined
637
+ if (partial.length === headerSize && bodyLength(partial) > 0) {
638
+ // only its header had come, which says how long the frame is
639
+ this.read(partial, headerSize)
640
+ if (this.#ended === undefined) {
641
+ this.#hold(partial)
642
+ }
643
+ continue
644
+ }
645
+ this.read(partial, partial.length, true)
560
646
  }
561
647
  }
562
648
 
@@ -564,9 +650,10 @@ export class Session {
564
650
  * Takes the frames whole in the first `length` bytes and says how many
565
651
  * bytes they were: the rest is a frame's first part, which whoever owns
566
652
  * the bytes keeps for its end. Nothing of the bytes is kept here, so their
567
- * owner may write them over once this returns.
653
+ * owner may write them over once this returns, unless they are `kept`:
654
+ * bytes given to the session, whose bodies are views of them.
568
655
  */
569
- read(bytes: Uint8Array, length: number): number {
656
+ read(bytes: Uint8Array, length: number, kept = false): number {
570
657
  if (this.#ended !== undefined) {
571
658
  return length
572
659
  }
@@ -579,7 +666,7 @@ export class Session {
579
666
  if (stop > length) {
580
667
  break
581
668
  }
582
- this.#take(h, bytes, at + headerSize, stop)
669
+ this.#take(h, bytes, at + headerSize, stop, kept)
583
670
  at = stop
584
671
  }
585
672
  } catch (err) {
@@ -590,9 +677,15 @@ export class Session {
590
677
  }
591
678
 
592
679
  // takes the frame whose body is the bytes from `from` to `to`
593
- #take(h: ReturnType<typeof parseHeader>, bytes: Uint8Array, from: number, to: number): void {
680
+ #take(
681
+ h: ReturnType<typeof parseHeader>,
682
+ bytes: Uint8Array,
683
+ from: number,
684
+ to: number,
685
+ kept: boolean,
686
+ ): void {
594
687
  if (this.#agreed !== undefined && (h.kind === Kind.response || h.kind === Kind.data)) {
595
- this.#answer(h, bytes, from, to)
688
+ this.#answer(h, bytes, from, to, kept)
596
689
  return
597
690
  }
598
691
  const body = bytes.slice(from, to)
@@ -659,7 +752,13 @@ export class Session {
659
752
  this.#welcome.resolve(agreed)
660
753
  }
661
754
 
662
- #answer(h: ReturnType<typeof parseHeader>, bytes: Uint8Array, from: number, to: number): void {
755
+ #answer(
756
+ h: ReturnType<typeof parseHeader>,
757
+ bytes: Uint8Array,
758
+ from: number,
759
+ to: number,
760
+ kept: boolean,
761
+ ): void {
663
762
  const { kind, flags, stream: id } = h
664
763
  const stream = this.#streams.get(id)
665
764
  if (stream === undefined) {
@@ -670,7 +769,7 @@ export class Session {
670
769
  return
671
770
  }
672
771
  // a body of its own, since events outlive the read's buffer
673
- const body = bytes.slice(from, to)
772
+ const body = kept ? bytes.subarray(from, to) : bytes.slice(from, to)
674
773
  const end = (flags & Flag.end) !== 0
675
774
  if (end) {
676
775
  this.#release(stream)
package/src/sql.ts CHANGED
@@ -11,7 +11,7 @@ import { join } from 'node:path'
11
11
  import { type Channel, channelParts, type TxChannel, txChannel } from './channels.ts'
12
12
  import type { Connection, Durability, Idempotence, Link } from './connection.ts'
13
13
  import { checkDurability, download } from './connection.ts'
14
- import { errorOf, InvalidError } from './errors.ts'
14
+ import { CancelledError, errorOf, InvalidError, OutcomeUnknownError } from './errors.ts'
15
15
  import {
16
16
  askByCall,
17
17
  checkName,
@@ -22,6 +22,8 @@ import {
22
22
  viaLink,
23
23
  } from './handles.ts'
24
24
  import {
25
+ Adding,
26
+ addingIn,
25
27
  openQueue,
26
28
  type Queue,
27
29
  type QueueOptions,
@@ -34,7 +36,7 @@ import { Bucket, type BucketOptions, bucketOpen, partsOf, type Values, valuesOf
34
36
  import { Table, type TableOptions } from './query.ts'
35
37
  import type { StandardSchemaV1 } from './schema.ts'
36
38
  import { TableIndex, type TableIndexOptions, tableIndexOpen } from './search.ts'
37
- import type { Stream } from './session.ts'
39
+ import { ConnectionLostError, type Stream } from './session.ts'
38
40
  import type { SqlArg, SqlValue } from './wire/codec.ts'
39
41
  import { int64Of } from './wire/msgpack.ts'
40
42
  import {
@@ -889,21 +891,32 @@ export class Database implements Runner, Home {
889
891
  return new Table(this, name, options)
890
892
  }
891
893
 
892
- /** Statements known before they run, written as one: all of them or none, in a shared commit. */
893
- async batch(statements: readonly Sql[]): Promise<Done[]> {
894
- const texts = statements.map(each => {
895
- if (!(each instanceof Sql)) {
896
- throw new InvalidError('a batch takes pieces of SQL: sql`…`')
894
+ /**
895
+ * Writes known before they run, written as one: all of them or none, in a
896
+ * shared commit, and what each did, in their order. A write is a statement,
897
+ * or a job's add of a queue opened from the database, `queue.adding`, which
898
+ * commits with the rows and changed 1 job, or 0 when its id was taken.
899
+ *
900
+ * await db.batch([sql`update notes set body = ${body} where id = ${id}`, indexing.adding({ noteId: id })])
901
+ */
902
+ async batch(writes: readonly (Sql | Adding)[]): Promise<Done[]> {
903
+ const parts = writes.map(each => {
904
+ if (each instanceof Sql) {
905
+ return { text: each.text, values: [...each.values] }
906
+ }
907
+ if (each instanceof Adding) {
908
+ return addingIn(each, this)
897
909
  }
898
- return { text: each.text, values: [...each.values] }
910
+ throw new InvalidError("a batch takes pieces of SQL, sql`…`, and a queue's adding")
899
911
  })
900
912
  this.#refuseAround('a batch')
901
913
  const answered = await this.#link.run('write', async connection => {
902
914
  const handle = await this.handle(connection)
903
- return connection.session.call(
904
- methods['sql.batch'],
905
- SqlBatch.encode({ handle, statements: texts }),
906
- )
915
+ const statements = []
916
+ for (const part of parts) {
917
+ statements.push(typeof part === 'function' ? await part(connection) : part)
918
+ }
919
+ return connection.session.call(methods['sql.batch'], SqlBatch.encode({ handle, statements }))
907
920
  })
908
921
  return (SqlBatched.decode(answered).done ?? []).map(doneOf)
909
922
  }
@@ -1101,11 +1114,32 @@ export class SqlTx implements Runner {
1101
1114
  }
1102
1115
  }
1103
1116
 
1104
- /** Sends the last call: commit, or roll back, and waits for the server's word. */
1117
+ /**
1118
+ * Sends the last call: commit, or roll back, and waits for the server's
1119
+ * word. A commit that left and was not answered, its connection lost or
1120
+ * its wait cancelled, may have committed: its outcome is unknown. One that
1121
+ * never left, its signal aborted or its connection lost first, was rolled
1122
+ * back by the server, and fails as it ended.
1123
+ */
1105
1124
  async end(commit: boolean): Promise<void> {
1106
1125
  await this.#last.catch(() => {})
1126
+ if (this.#stream.cancelled) {
1127
+ // the signal's CANCEL leaves ahead of a commit sent now, and the server rolls back at it
1128
+ throw new CancelledError(
1129
+ `${this.describe}: the transaction was cancelled before its commit left`,
1130
+ )
1131
+ }
1107
1132
  await this.#stream.send(SqlTxCall.encode({ commit }), true)
1108
- await this.#stream.next()
1133
+ try {
1134
+ await this.#stream.next()
1135
+ } catch (err) {
1136
+ if (commit && (err instanceof ConnectionLostError || err instanceof CancelledError)) {
1137
+ throw new OutcomeUnknownError(
1138
+ `${this.describe}: the transaction's commit left with no answer; read what it wrote before running it again: ${err.message}`,
1139
+ )
1140
+ }
1141
+ throw err
1142
+ }
1109
1143
  }
1110
1144
 
1111
1145
  /**
package/src/store.ts CHANGED
@@ -1,11 +1,16 @@
1
+ import { type Stats, statSync } from 'node:fs'
2
+ import { dirname, resolve } from 'node:path'
3
+
1
4
  import { type Backup, type BackupOptions, backup } from './backup.ts'
2
5
  import { type Files, type FilesOptions, openFiles } from './blobs.ts'
6
+ import { currentSignal } from './cancel.ts'
3
7
  import { Channel } from './channels.ts'
4
8
  import { Clock } from './clock.ts'
5
9
  import { Config, type ConfigOptions, type Layer, type Value } from './config.ts'
6
10
  import {
7
11
  asking,
8
12
  checkDurability,
13
+ checkMaxSeries,
9
14
  type Durability,
10
15
  embedded,
11
16
  Link,
@@ -99,6 +104,11 @@ export interface OpenOptions {
99
104
  * unless asked for; a sidecar found running keeps its own.
100
105
  */
101
106
  selfMetrics?: SelfMetrics
107
+ /**
108
+ * The metrics series the store holds at most: a new series past them is
109
+ * a LimitError. 100,000 unless given; a sidecar found running keeps its own.
110
+ */
111
+ maxSeries?: number
102
112
  /** The tinystore binary: TINYSTORE_BIN, this platform's package, or PATH's when absent. */
103
113
  binary?: string
104
114
  /**
@@ -113,12 +123,14 @@ export interface OpenOptions {
113
123
  */
114
124
  clock?: Time
115
125
  /**
116
- * How far a commit of the store's files goes before it returns: `'full'`
117
- * unless given. `'os'` does not wait for the disk, so a write returns in
118
- * microseconds, survives this program's crash, and may be lost with the
119
- * last others to a power loss. It is the store's, set by whoever opens it
120
- * first: a sidecar found running with another is refused. A database may
121
- * say its own, `store.database('audit', { durability: 'full' })`.
126
+ * How far a commit of the store's files goes before it returns. Unless
127
+ * given, kv, jobs, files, search and every database commit `'full'`, and
128
+ * records and metrics `'os'`; given, every file commits so. `'os'` does
129
+ * not wait for the disk, so a write returns in microseconds, survives this
130
+ * program's crash, and may be lost with the last others to a power loss.
131
+ * It is the store's, set by whoever opens it first: a sidecar found
132
+ * running with another, or with none when this asks one, is refused. A
133
+ * database may say its own, `store.database('audit', { durability: 'full' })`.
122
134
  */
123
135
  durability?: Durability
124
136
  /**
@@ -486,9 +498,11 @@ export class Store implements AsyncDisposable {
486
498
  /**
487
499
  * Stops every worker, each once its handlers under way have answered,
488
500
  * ingests the instruments' last values, hands over the loggers' lines and
489
- * cancels every config's stream, then closes the connection. A private child is waited for until it has
490
- * exited, so that the directory is free once this returns; the directory's
491
- * sidecar goes once it has been idle.
501
+ * cancels every config's stream, then every subscription, `each` loop,
502
+ * tail and watch, whose loops end `ClosedError`, and closes the
503
+ * connection. A private child is waited for until it has exited, so that
504
+ * the directory is free once this returns; the directory's sidecar goes
505
+ * once it has been idle.
492
506
  */
493
507
  async close(): Promise<void> {
494
508
  this.#closing = true
@@ -529,7 +543,11 @@ const runtime: Runtime = typeof Bun === 'undefined' ? nodeRuntime : bunRuntime
529
543
  /**
530
544
  * Opens the store in a directory through its sidecar, found through SERVE or
531
545
  * started, or through a private child when asked. It returns once the server
532
- * has answered, so that a directory that cannot be served fails here.
546
+ * has answered, so that a directory that cannot be served fails here. Under
547
+ * withSignal it stops waiting once the signal aborts, CancelledError saying
548
+ * what it waited for, and keeps no connection:
549
+ *
550
+ * const store = await withSignal(AbortSignal.timeout(2000), () => open('./data'))
533
551
  */
534
552
  export async function open(dir: string, options: OpenOptions = {}): Promise<Store> {
535
553
  return openWith(runtime, dir, options)
@@ -551,11 +569,13 @@ export async function openWith(
551
569
  const clock = options.clock === undefined ? undefined : new Date(unixMs(options.clock))
552
570
  const durability = options.durability
553
571
  checkDurability(durability, 'open')
572
+ checkMaxSeries(options.maxSeries)
554
573
  const started = {
555
574
  durability,
556
575
  encryptionKeyFile: options.encryptionKeyFile,
557
576
  node: options.node,
558
577
  selfMetrics: options.selfMetrics,
578
+ maxSeries: options.maxSeries,
559
579
  }
560
580
  const dial =
561
581
  options.embedded === true
@@ -564,27 +584,45 @@ export async function openWith(
564
584
  ? privateChild(runtime, dir, binary, clock, started)
565
585
  : sidecar(runtime, dir, binary, { idle, ...started })
566
586
  const link = new Link(asking(dial, dir, durability))
567
- await link.connection()
587
+ await reached(link, `open ${dir}`)
568
588
  return new Store(link)
569
589
  }
570
590
 
571
591
  /**
572
592
  * Connects to a remote server: tls:// checks the server's certificate before
573
593
  * the token leaves; tcp:// sends the token in the clear, for a network its
574
- * operator trusts.
594
+ * operator trusts. Under withSignal it stops waiting once the signal aborts,
595
+ * as open does.
575
596
  */
576
597
  export async function connect(url: string, options: ConnectOptions): Promise<Store> {
577
598
  const link = new Link(remote(runtime, url, options.token, options.tls))
578
- await link.connection()
599
+ await reached(link, `connect ${url}`)
579
600
  return new Store(link)
580
601
  }
581
602
 
603
+ /**
604
+ * Waits for the link's first connection under the caller's signal. A caller
605
+ * who gives up, or a dial that fails, closes the link, which stops the dial
606
+ * and closes what it made.
607
+ */
608
+ async function reached(link: Link, of: string): Promise<void> {
609
+ try {
610
+ await link.connection(currentSignal(), of)
611
+ } catch (err) {
612
+ await link.close()
613
+ throw err
614
+ }
615
+ }
616
+
582
617
  // two letters or more before a colon: an address, never a Windows drive
583
618
  const address = /^([a-z][a-z0-9+.-]+):/i
584
619
 
585
620
  /**
586
621
  * Refuses an address where a directory belongs: open('tcp://…') would make a
587
- * folder of that name and start a server in it, rather than reach the one meant.
622
+ * folder of that name and start a server in it, rather than reach the one
623
+ * meant. Refuses a directory that is a file, or sits under one, in the core's
624
+ * words, before a server starts or the core loads, so that every way says it
625
+ * alike.
588
626
  *
589
627
  * open('tcp://db.internal:7070') → use connect
590
628
  * open('pipe:tinystore-d761f24b7e59') → open the directory it serves
@@ -602,6 +640,35 @@ function checkDirectory(dir: string): void {
602
640
  `open takes a store's directory, and ${dir} is an address: open the directory its server serves, and it is found through SERVE`,
603
641
  )
604
642
  }
643
+ const absolute = resolve(dir)
644
+ const file = fileInTheWay(absolute)
645
+ if (file === absolute) {
646
+ throw new InvalidError(`store ${absolute} is a file, not a directory`)
647
+ }
648
+ if (file !== undefined) {
649
+ throw new InvalidError(`store ${absolute}: ${file} is a file, not a directory`)
650
+ }
651
+ }
652
+
653
+ /**
654
+ * The first of a directory and the folders above it that is there, when it
655
+ * is a file: what keeps the directory from being made.
656
+ */
657
+ function fileInTheWay(dir: string): string | undefined {
658
+ for (let path = dir; ; path = dirname(path)) {
659
+ let found: Stats | undefined
660
+ try {
661
+ found = statSync(path)
662
+ } catch {
663
+ found = undefined
664
+ }
665
+ if (found !== undefined) {
666
+ return found.isDirectory() ? undefined : path
667
+ }
668
+ if (dirname(path) === path) {
669
+ return undefined
670
+ }
671
+ }
605
672
  }
606
673
 
607
674
  function findBinary(runtime: Runtime, given: string | undefined): string {
package/src/wire/codec.ts CHANGED
@@ -463,6 +463,17 @@ export class Message<F extends Fields> implements Codec<Read<F>, Written<F>> {
463
463
  return value
464
464
  }
465
465
 
466
+ /**
467
+ * Reads a body as `decode` does, for a body nothing else holds: its bins
468
+ * are views of it rather than copies, as a file's bytes are of a get's.
469
+ */
470
+ view(body: Uint8Array): Read<F> {
471
+ const r = new Reader(body, 0, body.length, true)
472
+ const value = this.read(r)
473
+ r.end()
474
+ return value
475
+ }
476
+
466
477
  #read(r: Reader): Read<F> {
467
478
  const read: Record<string, unknown> = {}
468
479
  r.fields(key => {
package/src/wire/frame.ts CHANGED
@@ -75,6 +75,11 @@ export function parseHeader(bytes: Uint8Array, at = 0): Header {
75
75
  }
76
76
  }
77
77
 
78
+ /** The body's length a header at `at` says, its twelve bytes there and not checked. */
79
+ export function bodyLength(bytes: Uint8Array, at = 0): number {
80
+ return uint32At(bytes, at)
81
+ }
82
+
78
83
  /** Writes a header where its twelve bytes were kept, once its body's length is known. */
79
84
  export function putHeader(
80
85
  bytes: Uint8Array,
@@ -469,12 +469,19 @@ export class Reader {
469
469
  readonly #seen = new Array<number>(maxDepth + 1).fill(0)
470
470
  /** The numbers past those, rare enough to be kept in a set, made when one comes. */
471
471
  readonly #others: (Set<number> | undefined)[] = []
472
+ /** Whether `bytes()` gives views of the bytes, which nothing else holds, rather than copies. */
473
+ readonly #views: boolean
472
474
 
473
- /** Reads a message that is the bytes from `at` to `end`: all of them unless said. */
474
- constructor(bytes: Uint8Array, at = 0, end = bytes.length) {
475
+ /**
476
+ * Reads a message that is the bytes from `at` to `end`: all of them unless
477
+ * said. With `views`, the bytes are the reader's alone, and the bins it
478
+ * reads keep them rather than copy them.
479
+ */
480
+ constructor(bytes: Uint8Array, at = 0, end = bytes.length, views = false) {
475
481
  this.#bytes = bytes
476
482
  this.#at = at
477
483
  this.#end = end
484
+ this.#views = views
478
485
  }
479
486
 
480
487
  /** Turns to another message, for a reader kept from one answer to the next. */
@@ -746,11 +753,11 @@ export class Reader {
746
753
  return this.#bytes.subarray(at, at + n)
747
754
  }
748
755
 
749
- /** Reads a bin as bytes of its own, which outlive the body. */
756
+ /** Reads a bin as bytes of its own, which outlive the body: a view where the body is the reader's. */
750
757
  bytes(): Uint8Array {
751
758
  const n = this.#binLength()
752
759
  const at = this.#take(n)
753
- return this.#bytes.slice(at, at + n)
760
+ return this.#views ? this.#bytes.subarray(at, at + n) : this.#bytes.slice(at, at + n)
754
761
  }
755
762
 
756
763
  #binLength(): number {