@tinyshed/tinystore 0.1.0-rc.5 → 0.1.0-rc.6

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 (122) hide show
  1. package/README.md +37 -37
  2. package/bin/tinystore.js +12 -1
  3. package/dist/backup.d.ts +33 -0
  4. package/dist/backup.js +49 -0
  5. package/dist/blobs.d.ts +160 -79
  6. package/dist/blobs.js +510 -217
  7. package/dist/channels.d.ts +90 -0
  8. package/dist/channels.js +291 -0
  9. package/dist/clock.js +3 -3
  10. package/dist/config.d.ts +209 -86
  11. package/dist/config.js +581 -538
  12. package/dist/connection.d.ts +64 -2
  13. package/dist/connection.js +201 -16
  14. package/dist/console.d.ts +27 -3
  15. package/dist/console.js +165 -12
  16. package/dist/dotenv.d.ts +7 -0
  17. package/dist/dotenv.js +79 -0
  18. package/dist/errors.d.ts +61 -1
  19. package/dist/errors.js +81 -1
  20. package/dist/handles.d.ts +44 -2
  21. package/dist/handles.js +81 -2
  22. package/dist/index.d.ts +17 -11
  23. package/dist/index.js +5 -3
  24. package/dist/instruments.d.ts +177 -0
  25. package/dist/instruments.js +819 -0
  26. package/dist/jobs.d.ts +335 -239
  27. package/dist/jobs.js +716 -536
  28. package/dist/json.d.ts +2 -0
  29. package/dist/json.js +122 -0
  30. package/dist/kv.d.ts +130 -243
  31. package/dist/kv.js +273 -640
  32. package/dist/limits.d.ts +80 -0
  33. package/dist/limits.js +139 -0
  34. package/dist/locks.d.ts +62 -0
  35. package/dist/locks.js +237 -0
  36. package/dist/logger.d.ts +45 -9
  37. package/dist/logger.js +150 -38
  38. package/dist/metrics.d.ts +210 -209
  39. package/dist/metrics.js +319 -556
  40. package/dist/once.d.ts +19 -18
  41. package/dist/once.js +74 -63
  42. package/dist/query.d.ts +181 -0
  43. package/dist/query.js +788 -0
  44. package/dist/records.d.ts +241 -150
  45. package/dist/records.js +507 -291
  46. package/dist/runtime/addon.d.ts +14 -0
  47. package/dist/runtime/addon.js +69 -0
  48. package/dist/runtime/bun.js +5 -7
  49. package/dist/runtime/node.js +5 -7
  50. package/dist/runtime/pipe.d.ts +17 -0
  51. package/dist/runtime/pipe.js +133 -0
  52. package/dist/runtime/shared.d.ts +6 -0
  53. package/dist/runtime/shared.js +19 -0
  54. package/dist/runtime.d.ts +5 -2
  55. package/dist/search.d.ts +189 -0
  56. package/dist/search.js +281 -0
  57. package/dist/session.d.ts +31 -3
  58. package/dist/session.js +153 -41
  59. package/dist/sql.d.ts +228 -78
  60. package/dist/sql.js +745 -240
  61. package/dist/store.d.ts +244 -24
  62. package/dist/store.js +270 -67
  63. package/dist/time.d.ts +5 -1
  64. package/dist/time.js +22 -2
  65. package/dist/tx.d.ts +61 -0
  66. package/dist/tx.js +314 -0
  67. package/dist/wire/codec.d.ts +23 -7
  68. package/dist/wire/codec.js +56 -35
  69. package/dist/wire/frame.d.ts +2 -0
  70. package/dist/wire/frame.js +31 -14
  71. package/dist/wire/messages.d.ts +259 -0
  72. package/dist/wire/messages.js +22 -0
  73. package/dist/wire/msgpack.d.ts +49 -1
  74. package/dist/wire/msgpack.js +293 -56
  75. package/dist/wire/protocol.d.ts +2683 -0
  76. package/dist/wire/protocol.js +10846 -0
  77. package/package.json +39 -38
  78. package/src/backup.ts +81 -0
  79. package/src/blobs.ts +678 -301
  80. package/src/channels.ts +377 -0
  81. package/src/clock.ts +4 -4
  82. package/src/config.ts +902 -612
  83. package/src/connection.ts +279 -21
  84. package/src/console.ts +180 -12
  85. package/src/dotenv.ts +82 -0
  86. package/src/errors.ts +105 -0
  87. package/src/handles.ts +157 -8
  88. package/src/index.ts +158 -52
  89. package/src/instruments.ts +1042 -0
  90. package/src/jobs.ts +1017 -733
  91. package/src/json.ts +133 -0
  92. package/src/kv.ts +424 -847
  93. package/src/limits.ts +202 -0
  94. package/src/locks.ts +320 -0
  95. package/src/logger.ts +209 -40
  96. package/src/metrics.ts +557 -752
  97. package/src/once.ts +86 -83
  98. package/src/query.ts +1005 -0
  99. package/src/records.ts +795 -418
  100. package/src/runtime/addon.ts +99 -0
  101. package/src/runtime/bun.ts +5 -7
  102. package/src/runtime/node.ts +5 -7
  103. package/src/runtime/pipe.ts +178 -0
  104. package/src/runtime/shared.ts +20 -0
  105. package/src/runtime.ts +5 -2
  106. package/src/search.ts +480 -0
  107. package/src/session.ts +187 -41
  108. package/src/sql.ts +993 -306
  109. package/src/store.ts +473 -78
  110. package/src/time.ts +48 -3
  111. package/src/tx.ts +426 -0
  112. package/src/wire/codec.ts +78 -37
  113. package/src/wire/frame.ts +44 -14
  114. package/src/wire/messages.ts +25 -0
  115. package/src/wire/msgpack.ts +327 -56
  116. package/src/wire/protocol.ts +11709 -0
  117. package/dist/limiter.d.ts +0 -45
  118. package/dist/limiter.js +0 -68
  119. package/dist/quota.d.ts +0 -44
  120. package/dist/quota.js +0 -98
  121. package/src/limiter.ts +0 -99
  122. package/src/quota.ts +0 -137
package/src/once.ts CHANGED
@@ -1,108 +1,102 @@
1
- // Answers a function gives once a key, as Go's kv.Once keeps them: a request
2
- // sent again is answered as the first was rather than done twice. The server
3
- // lets one call of a key run its function at a time, every client of the
4
- // store included, and keeps what it returned.
1
+ // A function run once a key, its answer kept: a request sent twice is answered
2
+ // as the first was rather than done twice. The core lets one run of a key go
3
+ // at a time, every client of the store included: it answers the kept answer,
4
+ // or hands the run to this client and keeps what it sends back.
5
5
 
6
6
  import { currentSignal } from './cancel.ts'
7
7
  import type { Link } from './connection.ts'
8
- import { OutcomeUnknownError } from './errors.ts'
9
- import { handleOn, ownerText } from './handles.ts'
10
- import type { Values } from './kv.ts'
11
- import { LostError, type Stream, watch } from './session.ts'
12
- import type { Duration } from './time.ts'
8
+ import { OutcomeUnknownError, ProtocolError } from './errors.ts'
9
+ import { checkName, handleOn } from './handles.ts'
10
+ import { callOn, jsonValues, keyText, underField, type Values } from './kv.ts'
11
+ import { ConnectionLostError, type Stream, watch } from './session.ts'
12
+ import { type Duration, ms } from './time.ts'
13
13
  import type { Key } from './wire/codec.ts'
14
- import { KvCall, KvEntry, methods } from './wire/messages.ts'
14
+ import { KvAnswer, KvCall, KvFound, KvOnceOpen, methods } from './wire/protocol.ts'
15
15
 
16
16
  export interface OnceOptions {
17
17
  /** how long an answer is kept: a day when absent */
18
- defaultTtl?: Duration
18
+ keep?: Duration | undefined
19
19
  }
20
20
 
21
- /** Answers kept once a key: open them with `store.kv.once(name)`. */
22
- export class Once<V> {
21
+ /** Answers kept once a key: open them with `store.once(name)`. */
22
+ export class Once<T> {
23
23
  readonly name: string
24
24
  readonly #link: Link
25
25
  readonly #open: Uint8Array
26
- readonly #values: Values<V>
27
- readonly #owners: (string | Uint8Array)[]
26
+ readonly #values: Values<T>
27
+ readonly #under: readonly string[]
28
28
 
29
- /** Answers come from `store.kv.once` and their `of`. */
30
- constructor(
31
- link: Link,
32
- name: string,
33
- open: Uint8Array,
34
- values: Values<V>,
35
- owners: (string | Uint8Array)[],
36
- ) {
29
+ /** Answers come from `store.once` and their `under`. */
30
+ constructor(link: Link, name: string, open: Uint8Array, under: readonly string[]) {
37
31
  this.#link = link
38
32
  this.name = name
39
33
  this.#open = open
40
- this.#values = values
41
- this.#owners = owners
34
+ this.#values = jsonValues as Values<T>
35
+ this.#under = under
42
36
  }
43
37
 
44
38
  /** The answers of a branch, each key apart from the same key elsewhere. */
45
- of(...owners: Key[]): Once<V> {
46
- return new Once(this.#link, this.name, this.#open, this.#values, [
47
- ...this.#owners,
48
- ...owners.map(ownerText),
49
- ])
39
+ under(...owners: Key[]): Once<T> {
40
+ return new Once(this.#link, this.name, this.#open, [...this.#under, ...owners.map(keyText)])
50
41
  }
51
42
 
52
43
  /**
53
- * The answer kept under key, or fn's, which is kept. A call of a key
54
- * another call is running waits for it and gets its answer; a throw of fn
55
- * keeps nothing and is thrown, so the next call runs fn again. A
56
- * connection lost after fn returned and before its answer was kept is
57
- * OutcomeUnknownError.
44
+ * The answer kept for key, or fn's, which is kept. A run of a key that
45
+ * another runs, here or in another process, waits for it and gets its
46
+ * answer; a throw of fn keeps nothing and is thrown, so the next run runs
47
+ * fn again. A connection lost after fn returned and before its answer was
48
+ * kept is OutcomeUnknownError.
58
49
  *
59
50
  * const receipt = await charges.run(requestId, () => pay.charge(order, requestId))
60
51
  */
61
- async run(key: Key, fn: () => V | Promise<V>): Promise<V> {
62
- const { stream, kept } = await this.#claim(key)
63
- if (stream === undefined) {
64
- return await this.#values.decode(kept ?? null)
52
+ async run(key: Key, fn: () => T | Promise<T>): Promise<T> {
53
+ const handed = await this.#claim(key)
54
+ if (!(handed instanceof Run)) {
55
+ return handed.value
65
56
  }
66
- let answer: V
67
- let body: Uint8Array
57
+ let answer: T
58
+ let kept: Uint8Array
68
59
  try {
69
60
  answer = await fn()
70
- body = KvEntry.encode({ found: true, value: await this.#values.encode(answer) })
61
+ kept = KvAnswer.encode({ found: true, value: this.#values.encode(answer) })
71
62
  } catch (err) {
72
- await end(stream, KvEntry.encode({})).catch(() => {})
63
+ await handed.end(KvAnswer.encode({})).catch(() => {})
73
64
  throw err
74
65
  }
75
- await end(stream, body)
66
+ await handed.end(kept)
76
67
  return answer
77
68
  }
78
69
 
79
- /** The answer kept under key, undefined when none is. */
80
- async get(key: Key): Promise<V | undefined> {
81
- const e = await this.#call('kv.get', key, 'read')
82
- return e.found === true ? await this.#values.decode(e.value ?? null) : undefined
70
+ /** The answer kept for key, undefined when none is. */
71
+ async get(key: Key): Promise<T | undefined> {
72
+ const body = await this.#call('kv.once.get', key, 'read')
73
+ const kept = KvAnswer.decode(body)
74
+ return kept.found === true ? this.#values.decode(kept.value ?? null) : undefined
83
75
  }
84
76
 
85
- /** Forgets the answer kept under key, so that the next run runs again. */
86
- async delete(key: Key): Promise<void> {
87
- await this.#call('kv.delete', key, 'write')
77
+ /** Forgets the answer kept for key, so that its next run runs fn again. */
78
+ async delete(key: Key): Promise<boolean> {
79
+ return KvFound.decode(await this.#call('kv.once.delete', key, 'write')).found === true
88
80
  }
89
81
 
90
- // asks for key's run: the answer kept under it, or the stream the server
91
- // handed the run on, which a lost connection asks for again
92
- async #claim(
93
- key: Key,
94
- ): Promise<{ stream?: Stream; kept?: ReturnType<typeof KvEntry.decode>['value'] }> {
82
+ // asks for key's run: the answer kept for it, or the run the core handed
83
+ // over, which a connection lost before the answer asks for again
84
+ async #claim(key: Key): Promise<Run | { value: T }> {
95
85
  return this.#link.run('read', async connection => {
96
- const handle = await handleOn(connection, methods['kv.open'], this.#open)
97
- const ask = KvCall.encode({ handle, owners: this.#ownersField(), key })
98
- const stream = await connection.session.open(methods['kv.run'], ask, false)
86
+ const handle = await handleOn(connection, methods['kv.once.open'], this.#open)
87
+ const call = KvCall.encode({ handle, under: underField(this.#under), key })
88
+ const stream = await connection.session.open(methods['kv.once.run'], call, false)
99
89
  const unwatch = watch(currentSignal(), stream)
100
90
  try {
101
91
  const first = await stream.next()
102
- if (first.end) {
103
- return { kept: KvEntry.decode(first.body).value }
92
+ const offered = KvAnswer.decode(first.body)
93
+ if (!first.end) {
94
+ return new Run(stream)
104
95
  }
105
- return { stream }
96
+ if (offered.found !== true) {
97
+ throw new ProtocolError(`kv once ${this.name}: a run ended without its answer`)
98
+ }
99
+ return { value: this.#values.decode(offered.value ?? null) }
106
100
  } catch (err) {
107
101
  stream.cancel()
108
102
  throw err
@@ -112,31 +106,40 @@ export class Once<V> {
112
106
  })
113
107
  }
114
108
 
115
- async #call(method: 'kv.get' | 'kv.delete', key: Key, idempotence: 'read' | 'write') {
116
- return this.#link.run(idempotence, async connection => {
117
- const handle = await handleOn(connection, methods['kv.open'], this.#open)
118
- const body = KvCall.encode({ handle, owners: this.#ownersField(), key })
119
- return KvEntry.decode(await connection.session.call(methods[method], body))
120
- })
109
+ #call(method: 'kv.once.get' | 'kv.once.delete', key: Key, idempotence: 'read' | 'write') {
110
+ return callOn(this.#link, 'kv.once.open', this.#open, this.#under, method, { key }, idempotence)
121
111
  }
112
+ }
122
113
 
123
- #ownersField(): (string | Uint8Array)[] | undefined {
124
- return this.#owners.length > 0 ? this.#owners : undefined
114
+ /** A run the core handed to this client, until it sends what to keep. */
115
+ class Run {
116
+ readonly #stream: Stream
117
+
118
+ constructor(stream: Stream) {
119
+ this.#stream = stream
125
120
  }
126
- }
127
121
 
128
- // sends what a run keeps as the stream's last DATA, and waits for the
129
- // server's, which comes once it is kept
130
- async function end(stream: Stream, body: Uint8Array): Promise<void> {
131
- try {
132
- await stream.send(body, true)
133
- await stream.next()
134
- } catch (err) {
135
- if (err instanceof LostError) {
136
- throw new OutcomeUnknownError(
137
- `the connection was lost before the answer was kept; the next run may run again: ${err.message}`,
138
- )
122
+ /** Sends the run's answer as the stream's last DATA, and waits for the core's, once it is kept. */
123
+ async end(answer: Uint8Array): Promise<void> {
124
+ try {
125
+ await this.#stream.send(answer, true)
126
+ await this.#stream.next()
127
+ } catch (err) {
128
+ if (err instanceof ConnectionLostError) {
129
+ throw new OutcomeUnknownError(
130
+ `the connection was lost before the answer was kept; the next run may run again: ${err.message}`,
131
+ )
132
+ }
133
+ throw err
139
134
  }
140
- throw err
141
135
  }
142
136
  }
137
+
138
+ /** What a once's open sends, checked before anything leaves. */
139
+ export function onceOpen(name: string, options: OnceOptions = {}): Uint8Array {
140
+ checkName(name, 'once')
141
+ return KvOnceOpen.encode({
142
+ name,
143
+ keep: options.keep === undefined ? undefined : ms(options.keep),
144
+ })
145
+ }