@tinyshed/tinystore 0.1.0 → 0.2.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/dist/blobs.d.ts +1 -1
  2. package/dist/blobs.js +13 -5
  3. package/dist/cancel.d.ts +16 -2
  4. package/dist/cancel.js +36 -2
  5. package/dist/channels.js +20 -6
  6. package/dist/config.d.ts +49 -1
  7. package/dist/config.js +86 -7
  8. package/dist/connection.d.ts +52 -10
  9. package/dist/connection.js +305 -73
  10. package/dist/handles.d.ts +10 -1
  11. package/dist/handles.js +27 -4
  12. package/dist/index.d.ts +5 -5
  13. package/dist/jobs.d.ts +35 -1
  14. package/dist/jobs.js +46 -0
  15. package/dist/logger.d.ts +22 -10
  16. package/dist/logger.js +118 -28
  17. package/dist/metrics.d.ts +24 -1
  18. package/dist/metrics.js +24 -1
  19. package/dist/query.js +33 -9
  20. package/dist/records.d.ts +48 -7
  21. package/dist/records.js +22 -3
  22. package/dist/runtime/addon.js +3 -2
  23. package/dist/runtime/bun.js +33 -12
  24. package/dist/runtime/node.js +30 -8
  25. package/dist/runtime/pipe.d.ts +2 -0
  26. package/dist/runtime/pipe.js +45 -20
  27. package/dist/runtime/shared.d.ts +28 -4
  28. package/dist/runtime/shared.js +125 -13
  29. package/dist/runtime.d.ts +28 -6
  30. package/dist/session.d.ts +9 -5
  31. package/dist/session.js +113 -31
  32. package/dist/sql.d.ts +18 -5
  33. package/dist/sql.js +44 -11
  34. package/dist/store.d.ts +25 -11
  35. package/dist/store.js +67 -9
  36. package/dist/time.d.ts +2 -0
  37. package/dist/wire/codec.d.ts +5 -0
  38. package/dist/wire/codec.js +10 -0
  39. package/dist/wire/frame.d.ts +2 -0
  40. package/dist/wire/frame.js +4 -0
  41. package/dist/wire/msgpack.d.ts +7 -3
  42. package/dist/wire/msgpack.js +11 -4
  43. package/dist/wire/protocol.d.ts +280 -36
  44. package/dist/wire/protocol.js +510 -102
  45. package/package.json +9 -8
  46. package/src/blobs.ts +13 -5
  47. package/src/cancel.ts +44 -2
  48. package/src/channels.ts +21 -6
  49. package/src/config.ts +138 -12
  50. package/src/connection.ts +377 -77
  51. package/src/handles.ts +32 -4
  52. package/src/index.ts +6 -1
  53. package/src/jobs.ts +66 -0
  54. package/src/logger.ts +158 -40
  55. package/src/metrics.ts +53 -2
  56. package/src/query.ts +33 -13
  57. package/src/records.ts +73 -10
  58. package/src/runtime/addon.ts +3 -2
  59. package/src/runtime/bun.ts +44 -9
  60. package/src/runtime/node.ts +30 -5
  61. package/src/runtime/pipe.ts +49 -19
  62. package/src/runtime/shared.ts +137 -16
  63. package/src/runtime.ts +31 -6
  64. package/src/session.ts +129 -30
  65. package/src/sql.ts +48 -14
  66. package/src/store.ts +81 -14
  67. package/src/time.ts +3 -0
  68. package/src/wire/codec.ts +11 -0
  69. package/src/wire/frame.ts +5 -0
  70. package/src/wire/msgpack.ts +11 -4
  71. package/src/wire/protocol.ts +532 -104
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/time.ts CHANGED
@@ -53,6 +53,9 @@ export type DurationText = Offered | (Spelled<Units> & Record<never, never>)
53
53
  /** A length of time: milliseconds, or the text of one, such as '1h30m'. */
54
54
  export type Duration = number | DurationText
55
55
 
56
+ /** A span of a calendar an aggregate's bucket covers in its timeZone: a local day, a week from Monday, a month. */
57
+ export type Calendar = 'day' | 'week' | 'month'
58
+
56
59
  /** A moment: a Date, or unix milliseconds. */
57
60
  export type Time = Date | number
58
61
 
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 {