@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/blobs.ts CHANGED
@@ -159,7 +159,8 @@ export class Files {
159
159
  handle => BlobsAt.encode({ handle, folder: this.#folder, path }),
160
160
  'read',
161
161
  )
162
- const got = BlobsGot.decode(answer)
162
+ // the answer is this call's alone: the file's bytes stay where they came
163
+ const got = BlobsGot.view(answer)
163
164
  if (got.info === undefined) {
164
165
  return undefined
165
166
  }
@@ -516,11 +517,14 @@ export class Upload implements AsyncDisposable {
516
517
  export class FileBytes {
517
518
  readonly size: number
518
519
  readonly #stream: () => ReadableStream<Uint8Array>
520
+ /** its bytes when they came with the get, which each read copies once */
521
+ readonly #held: Uint8Array | undefined
519
522
 
520
523
  /** File bytes come from `files.get` and `slice`. */
521
- constructor(size: number, stream: () => ReadableStream<Uint8Array>) {
524
+ constructor(size: number, stream: () => ReadableStream<Uint8Array>, held?: Uint8Array) {
522
525
  this.size = size
523
526
  this.#stream = stream
527
+ this.#held = held
524
528
  }
525
529
 
526
530
  /** Its bytes as they come, the credit of each given back once it is taken. */
@@ -529,6 +533,10 @@ export class FileBytes {
529
533
  }
530
534
 
531
535
  async bytes(): Promise<Uint8Array<ArrayBuffer>> {
536
+ if (this.#held !== undefined) {
537
+ // a copy, which a Buffer's slice under Node is not
538
+ return new Uint8Array(this.#held)
539
+ }
532
540
  const whole = new Uint8Array(this.size)
533
541
  let at = 0
534
542
  for await (const piece of this.stream() as AsyncIterable<Uint8Array>) {
@@ -573,7 +581,7 @@ export class StoredFile extends FileBytes implements FileInfo {
573
581
  whole: Uint8Array | undefined,
574
582
  read: (offset?: number, length?: number) => ReadableStream<Uint8Array>,
575
583
  ) {
576
- super(info.size, () => (whole === undefined ? read() : streamOf(whole)))
584
+ super(info.size, () => (whole === undefined ? read() : streamOf(whole)), whole)
577
585
  this.path = info.path
578
586
  this.etag = info.etag
579
587
  this.contentType = info.contentType
@@ -595,7 +603,7 @@ export class StoredFile extends FileBytes implements FileInfo {
595
603
  const whole = this.#whole
596
604
  if (whole !== undefined) {
597
605
  const bytes = whole.subarray(from, to)
598
- return new FileBytes(bytes.length, () => streamOf(bytes))
606
+ return new FileBytes(bytes.length, () => streamOf(bytes), bytes)
599
607
  }
600
608
  return new FileBytes(to - from, () => this.#read(from, to - from))
601
609
  }
@@ -615,7 +623,7 @@ function streamOf(bytes: Uint8Array): ReadableStream<Uint8Array> {
615
623
  return new ReadableStream<Uint8Array>({
616
624
  start(controller) {
617
625
  if (bytes.length > 0) {
618
- controller.enqueue(bytes.slice())
626
+ controller.enqueue(new Uint8Array(bytes))
619
627
  }
620
628
  controller.close()
621
629
  },
package/src/cancel.ts CHANGED
@@ -3,12 +3,15 @@
3
3
 
4
4
  import { AsyncLocalStorage } from 'node:async_hooks'
5
5
 
6
+ import { CancelledError } from './errors.ts'
7
+
6
8
  const carried = new AsyncLocalStorage<AbortSignal>()
7
9
 
8
10
  /**
9
11
  * 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
+ * scan, open and connect too, rejects once the signal aborts, its stream
13
+ * cancelled on the wire, with CancelledError. A call given a signal of its
14
+ * own, as work and put take one, keeps that one.
12
15
  *
13
16
  * ```ts
14
17
  * await withSignal(AbortSignal.timeout(2000), async () => {
@@ -24,3 +27,42 @@ export function withSignal<T>(signal: AbortSignal, fn: () => T): T {
24
27
  export function currentSignal(): AbortSignal | undefined {
25
28
  return carried.getStore()
26
29
  }
30
+
31
+ /**
32
+ * Runs fn under no caller's signal: a dial that every caller of a store
33
+ * shares stops for none of theirs, only for the store's close.
34
+ */
35
+ export function withoutSignal<T>(fn: () => T): T {
36
+ return carried.exit(fn)
37
+ }
38
+
39
+ /** Throws the CancelledError of a call whose signal has aborted, rather than the signal's own reason. */
40
+ export function checkSignal(signal: AbortSignal | undefined): void {
41
+ if (signal?.aborted) {
42
+ throw new CancelledError('the call was cancelled')
43
+ }
44
+ }
45
+
46
+ /**
47
+ * What a promise gives, unless the signal aborts first: the caller then
48
+ * stops waiting with the error `cancelled` makes, and the promise goes on
49
+ * for whoever else waits on it.
50
+ */
51
+ export function unlessCancelled<T>(
52
+ promise: Promise<T>,
53
+ signal: AbortSignal | undefined,
54
+ cancelled: () => Error = () => new CancelledError('the call was cancelled'),
55
+ ): Promise<T> {
56
+ if (signal === undefined) {
57
+ return promise
58
+ }
59
+ if (signal.aborted) {
60
+ promise.catch(() => {})
61
+ return Promise.reject(cancelled())
62
+ }
63
+ return new Promise<T>((resolve, reject) => {
64
+ const abort = () => reject(cancelled())
65
+ signal.addEventListener('abort', abort, { once: true })
66
+ promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort))
67
+ })
68
+ }
package/src/channels.ts CHANGED
@@ -121,10 +121,11 @@ export class Channel<T> {
121
121
  }
122
122
  throw err
123
123
  }
124
- if (!first) {
125
- await told.missed({ reason: 'reconnect' })
126
- }
124
+ const unfollow = this.#link.follow(stream)
127
125
  try {
126
+ if (!first) {
127
+ await told.missed({ reason: 'reconnect' })
128
+ }
128
129
  for (;;) {
129
130
  const event = await stream.next()
130
131
  if (event.end) {
@@ -145,6 +146,7 @@ export class Channel<T> {
145
146
  }
146
147
  } finally {
147
148
  stream.cancel()
149
+ unfollow()
148
150
  }
149
151
  }
150
152
  }
@@ -171,6 +173,7 @@ export class Subscription {
171
173
  readonly #asked: Uint8Array
172
174
  readonly #shown: string
173
175
  #stream: Stream | undefined
176
+ #unfollow = () => {}
174
177
  #stopped = false
175
178
  #done: Promise<void> = Promise.resolve()
176
179
 
@@ -199,9 +202,16 @@ export class Subscription {
199
202
  handler: (message: Message<unknown>) => unknown,
200
203
  options: SubscribeOptions | undefined,
201
204
  ) {
202
- this.#stream = await subscribed(this.#link, this.#asked)
205
+ this.#take(await subscribed(this.#link, this.#asked))
203
206
  const told = new Told(this.#shown, options?.onMissed, options?.onError)
204
- this.#done = this.#run(handler, told)
207
+ this.#done = this.#run(handler, told).finally(() => this.#unfollow())
208
+ }
209
+
210
+ /** Makes a stream the subscription's, which the store's close cancels. */
211
+ #take(stream: Stream): void {
212
+ this.#unfollow()
213
+ this.#stream = stream
214
+ this.#unfollow = this.#link.follow(stream)
205
215
  }
206
216
 
207
217
  async #run(handler: (message: Message<unknown>) => unknown, told: Told): Promise<void> {
@@ -222,7 +232,12 @@ export class Subscription {
222
232
  if (!(made instanceof Stream)) {
223
233
  return told.ended(made, this.#stopped)
224
234
  }
225
- this.#stream = made
235
+ this.#take(made)
236
+ // a stop while it subscribed again cancelled the stream before this one
237
+ if (this.#stopped) {
238
+ made.cancel()
239
+ return
240
+ }
226
241
  await told.missed({ reason: 'reconnect' })
227
242
  }
228
243
  }
package/src/config.ts CHANGED
@@ -11,12 +11,15 @@ import { readFile } from 'node:fs/promises'
11
11
 
12
12
  import type { Connection, Idempotence, Link } from './connection.ts'
13
13
  import { CancelledError, ConflictError, InvalidError, UnavailableError } from './errors.ts'
14
+ import { unsent } from './handles.ts'
14
15
  import { check, isSchema, type StandardSchemaV1 } from './schema.ts'
15
16
  import { ConnectionLostError, type Stream } from './session.ts'
16
17
  import { type DurationText, ms, spelled } from './time.ts'
17
18
  import type { Read } from './wire/codec.ts'
18
19
  import {
20
+ type ConfigLine,
19
21
  ConfigOpen,
22
+ type ConfigOrigin,
20
23
  ConfigReset,
21
24
  ConfigUpdate,
22
25
  ConfigValue,
@@ -225,8 +228,43 @@ export interface ExplainLine {
225
228
  readonly from: string
226
229
  /** the values it went over, newest first */
227
230
  readonly over: string
231
+ /**
232
+ * Every value the setting was given, newest first: its own, then the ones
233
+ * it went over. `from` is `String(given[0].from)`. It is empty from a
234
+ * server before 0.1.1. `console.table` and a spread leave it out, and JSON
235
+ * keeps it.
236
+ */
237
+ readonly given: readonly ExplainGiven[]
238
+ }
239
+
240
+ /** A value a setting was given, and where it came from. */
241
+ export interface ExplainGiven {
242
+ /** as JSON, a duration spelled, a secret as *** */
243
+ readonly value: string
244
+ readonly from: ExplainOrigin
228
245
  }
229
246
 
247
+ /**
248
+ * Where a value came from: the declaration, a layer in the list by its place,
249
+ * the declaration 1, a file, a variable, or a change. `String(origin)` is the
250
+ * text a line's `from` says: `the declaration`, `layer 2`, `app.yaml`,
251
+ * `APP_PORT in .env`, `a change, version 7, 2026-10-13 14:03:05 UTC`. A kind
252
+ * from a newer server is kept as it was sent, and its text is the kind.
253
+ */
254
+ export type ExplainOrigin =
255
+ | { readonly kind: 'declaration' }
256
+ | { readonly kind: 'layer'; readonly place: number }
257
+ | { readonly kind: 'file'; readonly path: string }
258
+ | {
259
+ readonly kind: 'env'
260
+ readonly variable: string
261
+ /** the .env file that set the variable */
262
+ readonly dotenv?: string
263
+ /** the file a NAME_FILE variable named */
264
+ readonly file?: string
265
+ }
266
+ | { readonly kind: 'change'; readonly version: number; readonly at: Date }
267
+
230
268
  /** Every setting's line, for console.table, and what was read and not used. */
231
269
  export type Explained = readonly ExplainLine[] & { readonly notes: readonly string[] }
232
270
 
@@ -728,6 +766,91 @@ function merged(value: unknown, changes: unknown): unknown {
728
766
 
729
767
  type Watcher<V> = (next: V, previous: V | undefined) => void
730
768
  type Answer = Read<typeof ConfigValue.fields>
769
+ type SentLine = Read<typeof ConfigLine.fields>
770
+ type SentOrigin = Read<typeof ConfigOrigin.fields>
771
+
772
+ /**
773
+ * A line as the store sent it. `given` is not enumerable, so that
774
+ * `console.table(config.explain())` shows the four columns it always showed,
775
+ * and toJSON gives it back to JSON.stringify.
776
+ */
777
+ function explainLine(line: SentLine): ExplainLine {
778
+ const shown = {
779
+ path: line.path ?? '',
780
+ value: line.value ?? '',
781
+ from: line.from ?? '',
782
+ over: (line.over ?? []).join(', '),
783
+ }
784
+ const given = (line.given ?? []).map(each => ({
785
+ value: each.value ?? '',
786
+ from: explainOrigin(each.from ?? {}),
787
+ }))
788
+ const json = {
789
+ toJSON() {
790
+ return { ...shown, given }
791
+ },
792
+ }
793
+ return Object.defineProperties(shown, {
794
+ given: { value: given },
795
+ toJSON: { value: json.toJSON },
796
+ }) as ExplainLine
797
+ }
798
+
799
+ const originMethods = {
800
+ toString(this: ExplainOrigin): string {
801
+ return originText(this)
802
+ },
803
+ }
804
+
805
+ /** Where a value came from, only the fields its kind names, its text the core's `from`. */
806
+ export function explainOrigin(sent: SentOrigin): ExplainOrigin {
807
+ return Object.defineProperty(originOf(sent), 'toString', { value: originMethods.toString })
808
+ }
809
+
810
+ function originOf(sent: SentOrigin): ExplainOrigin {
811
+ switch (sent.kind) {
812
+ case 'layer':
813
+ return { kind: 'layer', place: sent.place ?? 0 }
814
+ case 'file':
815
+ return { kind: 'file', path: sent.path ?? '' }
816
+ case 'env':
817
+ return {
818
+ kind: 'env',
819
+ variable: sent.variable ?? '',
820
+ ...(sent.dotenv === undefined ? {} : { dotenv: sent.dotenv }),
821
+ ...(sent.file === undefined ? {} : { file: sent.file }),
822
+ }
823
+ case 'change':
824
+ return { kind: 'change', version: sent.version ?? 0, at: new Date(sent.at ?? 0) }
825
+ case 'declaration':
826
+ case undefined:
827
+ return { kind: 'declaration' }
828
+ default:
829
+ // a kind from a newer server, kept as it was sent
830
+ return { kind: sent.kind } as unknown as ExplainOrigin
831
+ }
832
+ }
833
+
834
+ /** The text the core's `from` says: crates/tinystore/src/kv/config/explain.rs, Origin's Display. */
835
+ function originText(origin: ExplainOrigin): string {
836
+ switch (origin.kind) {
837
+ case 'declaration':
838
+ return 'the declaration'
839
+ case 'layer':
840
+ return `layer ${origin.place}`
841
+ case 'file':
842
+ return origin.path
843
+ case 'env':
844
+ if (origin.dotenv !== undefined) {
845
+ return `${origin.variable} in ${origin.dotenv}`
846
+ }
847
+ return origin.file === undefined ? origin.variable : `${origin.variable}, ${origin.file}`
848
+ case 'change':
849
+ return `a change, version ${origin.version}, ${origin.at.toISOString().slice(0, 19).replace('T', ' ')} UTC`
850
+ }
851
+ // a kind from a newer server says itself
852
+ return (origin as { kind: string }).kind
853
+ }
731
854
 
732
855
  /**
733
856
  * A program's settings as one typed value, read from memory: open one with
@@ -854,7 +977,10 @@ export class Config<D> {
854
977
  }
855
978
  }
856
979
 
857
- /** Every setting with its value, the layer that gave it and what it went over. */
980
+ /**
981
+ * Every setting with its value, the layer that gave it and what it went
982
+ * over, as text, and in `given` as data.
983
+ */
858
984
  explain(): Explained {
859
985
  const refused =
860
986
  this.#refused === undefined ? [] : [`a value validate refused: ${this.#refused.message}`]
@@ -893,11 +1019,16 @@ export class Config<D> {
893
1019
  #handleOn(connection: Connection): Promise<number> {
894
1020
  let handle = this.#handles.get(connection)
895
1021
  if (handle === undefined) {
896
- handle = connection.session.call(methods['config.open'], this.#open).then(async body => {
897
- const opened = ConfigValue.decode(body)
898
- await this.#take(opened)
899
- return opened.handle ?? 0
900
- })
1022
+ handle = connection.session.call(methods['config.open'], this.#open).then(
1023
+ async body => {
1024
+ const opened = ConfigValue.decode(body)
1025
+ await this.#take(opened)
1026
+ return opened.handle ?? 0
1027
+ },
1028
+ (err: unknown) => {
1029
+ throw unsent(err)
1030
+ },
1031
+ )
901
1032
  this.#handles.set(connection, handle)
902
1033
  handle.catch(() => this.#handles.delete(connection))
903
1034
  }
@@ -931,12 +1062,7 @@ export class Config<D> {
931
1062
  this.#refused = undefined
932
1063
  this.#value = next
933
1064
  this.#version = version
934
- this.#lines = (answer.lines ?? []).map(line => ({
935
- path: line.path ?? '',
936
- value: line.value ?? '',
937
- from: line.from ?? '',
938
- over: (line.over ?? []).join(', '),
939
- }))
1065
+ this.#lines = (answer.lines ?? []).map(explainLine)
940
1066
  this.#notes = answer.notes ?? []
941
1067
  for (const wake of this.#newer.splice(0)) {
942
1068
  wake()