@tinyshed/tinystore 0.1.0-rc.4 → 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
@@ -0,0 +1,377 @@
1
+ // Channels, as docs/guides/channels/README.md has them: messages a program publishes
2
+ // on a named channel, which every subscriber listening at that moment
3
+ // receives, in memory and at most once. A subscription's handler is called
4
+ // one message at a time; a slow one lets the store's log run ahead and is
5
+ // told what it missed, and a connection lost is subscribed again and told
6
+ // that messages may have been lost meanwhile.
7
+
8
+ import { AsyncLocalStorage } from 'node:async_hooks'
9
+
10
+ import type { Link } from './connection.ts'
11
+ import { ClosedError, InvalidError, UnavailableError } from './errors.ts'
12
+ import { checkName } from './handles.ts'
13
+ import { keyText } from './kv.ts'
14
+ import { sayOwn } from './logger.ts'
15
+ import { ConnectionLostError, Stream } from './session.ts'
16
+ import type { Key } from './wire/codec.ts'
17
+ import { ChannelsBatch, ChannelsPublish, ChannelsSubscribe, methods } from './wire/protocol.ts'
18
+
19
+ /** A message as a subscriber receives it: what was published, and the branch it was published under. */
20
+ export interface Message<T> {
21
+ value: T
22
+ branch: string[]
23
+ }
24
+
25
+ /**
26
+ * Messages a subscriber may have lost: it fell behind its branch's log, and
27
+ * `count` says how many; or its connection was lost and made again, and how
28
+ * many is unknown.
29
+ */
30
+ export interface Missed {
31
+ reason: 'behind' | 'reconnect'
32
+ count?: number | undefined
33
+ }
34
+
35
+ export interface SubscribeOptions {
36
+ /** take every branch below this one too */
37
+ recursive?: boolean | undefined
38
+ /** told what was missed, in line with the messages; the store's log says it when absent */
39
+ onMissed?: ((missed: Missed) => unknown) | undefined
40
+ /** told what the handler threw, with the message; the store's log says it when absent */
41
+ onError?: ((error: unknown, message: Message<unknown>) => unknown) | undefined
42
+ }
43
+
44
+ export interface EachOptions {
45
+ recursive?: boolean | undefined
46
+ onMissed?: ((missed: Missed) => unknown) | undefined
47
+ }
48
+
49
+ /** How long a subscription without onMissed or onError waits between two lines of the store's log. */
50
+ const quiet = 60_000
51
+
52
+ /** A channel of messages of one type, or one of its branches: open it with `store.channel(name)`. */
53
+ export class Channel<T> {
54
+ readonly name: string
55
+ readonly branch: readonly string[]
56
+ readonly #link: Link
57
+
58
+ /** A channel comes from `store.channel` and its `under`. */
59
+ constructor(link: Link, name: string, branch: readonly string[] = []) {
60
+ if (branch.length === 0) {
61
+ checkName(name, 'channel')
62
+ }
63
+ this.#link = link
64
+ this.name = name
65
+ this.branch = branch
66
+ }
67
+
68
+ /** The branch of owners under this one: whose messages these are. */
69
+ under(...owners: Key[]): Channel<T> {
70
+ return new Channel(this.#link, this.name, [...this.branch, ...owners.map(keyText)])
71
+ }
72
+
73
+ /**
74
+ * Hands value to every subscriber of this branch, and of the branches above
75
+ * it listened to recursive, that listens now. It answers once the store
76
+ * has the message, not once anyone handled it.
77
+ */
78
+ async publish(value: T): Promise<void> {
79
+ const body = publishBody(this.name, this.branch, value)
80
+ await this.#link.run('write', connection =>
81
+ connection.session.call(methods['channels.publish'], body),
82
+ )
83
+ }
84
+
85
+ /**
86
+ * Calls handler with each message published from now on, one at a time
87
+ * and in order: it answers once the store has the subscription, so that a
88
+ * message published after it arrives.
89
+ *
90
+ * const sub = await chat.under(roomId).subscribe(m => show(m.value), { onMissed: () => reload() })
91
+ * await sub.stop()
92
+ */
93
+ async subscribe(
94
+ handler: (message: Message<T>) => unknown,
95
+ options?: SubscribeOptions,
96
+ ): Promise<Subscription> {
97
+ const subscription = new Subscription(
98
+ this.#link,
99
+ this.#asked(options?.recursive),
100
+ this.#shown(),
101
+ )
102
+ await subscription.start(handler as (message: Message<unknown>) => unknown, options)
103
+ return subscription
104
+ }
105
+
106
+ /**
107
+ * The messages published from now on, as a loop: it listens from its first
108
+ * turn, and break ends it. A throw in the loop's body ends it too.
109
+ *
110
+ * for await (const m of chat.under(roomId).each()) await save(m.value)
111
+ */
112
+ async *each(options?: EachOptions): AsyncGenerator<Message<T>> {
113
+ const told = new Told(this.#shown(), options?.onMissed, undefined)
114
+ for (let first = true; ; first = false) {
115
+ let stream: Stream
116
+ try {
117
+ stream = await subscribed(this.#link, this.#asked(options?.recursive))
118
+ } catch (err) {
119
+ if (!first && again(err)) {
120
+ continue
121
+ }
122
+ throw err
123
+ }
124
+ if (!first) {
125
+ await told.missed({ reason: 'reconnect' })
126
+ }
127
+ try {
128
+ for (;;) {
129
+ const event = await stream.next()
130
+ if (event.end) {
131
+ return
132
+ }
133
+ const batch = ChannelsBatch.decode(event.body)
134
+ if ((batch.missed ?? 0) > 0) {
135
+ await told.missed({ reason: 'behind', count: batch.missed })
136
+ }
137
+ for (const message of batch.messages ?? []) {
138
+ yield messageOf<T>(message)
139
+ }
140
+ stream.consumed(event.body.length)
141
+ }
142
+ } catch (err) {
143
+ if (!again(err)) {
144
+ throw err
145
+ }
146
+ } finally {
147
+ stream.cancel()
148
+ }
149
+ }
150
+ }
151
+
152
+ #asked(recursive: boolean | undefined): Uint8Array {
153
+ return ChannelsSubscribe.encode({
154
+ name: this.name,
155
+ under: [...this.branch],
156
+ recursive: recursive === true,
157
+ })
158
+ }
159
+
160
+ #shown(): string {
161
+ return shown(this.name, this.branch)
162
+ }
163
+ }
164
+
165
+ /**
166
+ * A subscription whose handler is called with each message: `stop` ends
167
+ * it, and the store's close does.
168
+ */
169
+ export class Subscription {
170
+ readonly #link: Link
171
+ readonly #asked: Uint8Array
172
+ readonly #shown: string
173
+ #stream: Stream | undefined
174
+ #stopped = false
175
+ #done: Promise<void> = Promise.resolve()
176
+
177
+ /** A subscription comes from `channel.subscribe`. */
178
+ constructor(link: Link, asked: Uint8Array, shown: string) {
179
+ this.#link = link
180
+ this.#asked = asked
181
+ this.#shown = shown
182
+ }
183
+
184
+ /**
185
+ * No call starts after it, and it answers once the running call ended;
186
+ * called from inside the subscription's own handler, it answers at once.
187
+ */
188
+ async stop(): Promise<void> {
189
+ this.#stopped = true
190
+ this.#stream?.cancel()
191
+ if (inside.getStore() === this) {
192
+ return
193
+ }
194
+ await this.#done
195
+ }
196
+
197
+ /** Registers the subscription, then runs its handler in the background. */
198
+ async start(
199
+ handler: (message: Message<unknown>) => unknown,
200
+ options: SubscribeOptions | undefined,
201
+ ) {
202
+ this.#stream = await subscribed(this.#link, this.#asked)
203
+ const told = new Told(this.#shown, options?.onMissed, options?.onError)
204
+ this.#done = this.#run(handler, told)
205
+ }
206
+
207
+ async #run(handler: (message: Message<unknown>) => unknown, told: Told): Promise<void> {
208
+ for (;;) {
209
+ const stream = this.#stream
210
+ if (stream === undefined || this.#stopped) {
211
+ return
212
+ }
213
+ try {
214
+ await this.#deliver(stream, handler, told)
215
+ return
216
+ } catch (err) {
217
+ if (this.#stopped || !again(err)) {
218
+ return told.ended(err, this.#stopped)
219
+ }
220
+ }
221
+ const made = await subscribed(this.#link, this.#asked).catch((err: unknown) => err)
222
+ if (!(made instanceof Stream)) {
223
+ return told.ended(made, this.#stopped)
224
+ }
225
+ this.#stream = made
226
+ await told.missed({ reason: 'reconnect' })
227
+ }
228
+ }
229
+
230
+ /** Reads the stream's batches and calls the handler, one message at a time. */
231
+ async #deliver(stream: Stream, handler: (message: Message<unknown>) => unknown, told: Told) {
232
+ for (;;) {
233
+ const event = await stream.next()
234
+ if (event.end) {
235
+ return
236
+ }
237
+ const batch = ChannelsBatch.decode(event.body)
238
+ if ((batch.missed ?? 0) > 0 && !this.#stopped) {
239
+ await told.missed({ reason: 'behind', count: batch.missed })
240
+ }
241
+ for (const each of batch.messages ?? []) {
242
+ if (this.#stopped) {
243
+ return
244
+ }
245
+ const message = messageOf<unknown>(each)
246
+ try {
247
+ await inside.run(this, () => handler(message))
248
+ } catch (err) {
249
+ await told.failed(err, message)
250
+ }
251
+ }
252
+ stream.consumed(event.body.length)
253
+ }
254
+ }
255
+ }
256
+
257
+ // The subscription whose handler the caller runs inside, so that its stop
258
+ // answers at once there rather than wait for itself.
259
+ const inside = new AsyncLocalStorage<Subscription>()
260
+
261
+ /** Opens a subscription's stream and waits for the RESPONSE that says the store has it. */
262
+ function subscribed(link: Link, asked: Uint8Array): Promise<Stream> {
263
+ return link.run('read', async connection => {
264
+ const stream = await connection.session.open(methods['channels.subscribe'], asked, true)
265
+ try {
266
+ await stream.next()
267
+ return stream
268
+ } catch (err) {
269
+ stream.cancel()
270
+ throw err
271
+ }
272
+ })
273
+ }
274
+
275
+ /** Whether a subscription ended by its connection subscribes again on another. */
276
+ function again(err: unknown): boolean {
277
+ return err instanceof ConnectionLostError || err instanceof UnavailableError
278
+ }
279
+
280
+ function messageOf<T>(message: {
281
+ under?: string[] | undefined
282
+ value?: string | undefined
283
+ }): Message<T> {
284
+ return { value: JSON.parse(message.value ?? 'null') as T, branch: message.under ?? [] }
285
+ }
286
+
287
+ /** What tells a subscription's missed messages and its handler's throws: its own, or the store's log once a minute. */
288
+ class Told {
289
+ readonly #shown: string
290
+ readonly #onMissed: SubscribeOptions['onMissed']
291
+ readonly #onError: SubscribeOptions['onError']
292
+ #said = Number.NEGATIVE_INFINITY
293
+
294
+ constructor(
295
+ shown: string,
296
+ onMissed: SubscribeOptions['onMissed'],
297
+ onError: SubscribeOptions['onError'],
298
+ ) {
299
+ this.#shown = shown
300
+ this.#onMissed = onMissed
301
+ this.#onError = onError
302
+ }
303
+
304
+ async missed(missed: Missed): Promise<void> {
305
+ if (this.#onMissed !== undefined) {
306
+ await this.#onMissed(missed)
307
+ } else if (this.#speaks()) {
308
+ sayOwn('warn', 'a subscriber may have missed messages', { channel: this.#shown, ...missed })
309
+ }
310
+ }
311
+
312
+ async failed(error: unknown, message: Message<unknown>): Promise<void> {
313
+ if (this.#onError !== undefined) {
314
+ await this.#onError(error, message)
315
+ } else if (this.#speaks()) {
316
+ sayOwn('warn', "a subscriber's handler threw", { channel: this.#shown, error })
317
+ }
318
+ }
319
+
320
+ /** Says why the subscription ended, unless it was stopped or its store closed. */
321
+ ended(err: unknown, stopped: boolean): void {
322
+ if (!stopped && !(err instanceof ClosedError && !(err instanceof ConnectionLostError))) {
323
+ sayOwn('warn', 'a subscription ended', { channel: this.#shown, error: err })
324
+ }
325
+ }
326
+
327
+ #speaks(): boolean {
328
+ const now = Date.now()
329
+ if (now - this.#said < quiet) {
330
+ return false
331
+ }
332
+ this.#said = now
333
+ return true
334
+ }
335
+ }
336
+
337
+ /** A channel's branch as an error names it: `channel chat: under "room-7"`. */
338
+ function shown(name: string, branch: readonly string[]): string {
339
+ if (branch.length === 0) {
340
+ return `channel ${name}`
341
+ }
342
+ return `channel ${name}: under ${branch.map(owner => JSON.stringify(owner)).join(' ')}`
343
+ }
344
+
345
+ /** A publish's body: its channel, its branch and its value as JSON. */
346
+ export function publishBody(name: string, branch: readonly string[], value: unknown): Uint8Array {
347
+ const json = JSON.stringify(value)
348
+ if (json === undefined) {
349
+ throw new InvalidError(`${shown(name, branch)}: a message that does not write as JSON`)
350
+ }
351
+ return ChannelsPublish.encode({ name, under: [...branch], value: json })
352
+ }
353
+
354
+ /** A channel inside a transaction: its messages are handed over once the transaction commits. */
355
+ export interface TxChannel<T> {
356
+ under(...owners: Key[]): TxChannel<T>
357
+ publish(value: T): Promise<void>
358
+ }
359
+
360
+ /** A channel's name and branch, when handle is a channel. */
361
+ export function channelParts(
362
+ handle: unknown,
363
+ ): { name: string; branch: readonly string[] } | undefined {
364
+ return handle instanceof Channel ? { name: handle.name, branch: handle.branch } : undefined
365
+ }
366
+
367
+ /** A channel inside a transaction, its publishes sent by send. */
368
+ export function txChannel<T>(
369
+ name: string,
370
+ branch: readonly string[],
371
+ send: (body: Uint8Array) => Promise<void>,
372
+ ): TxChannel<T> {
373
+ return {
374
+ under: (...owners) => txChannel(name, [...branch, ...owners.map(keyText)], send),
375
+ publish: value => send(publishBody(name, branch, value)),
376
+ }
377
+ }
package/src/clock.ts CHANGED
@@ -3,7 +3,7 @@
3
3
 
4
4
  import type { Link } from './connection.ts'
5
5
  import { type Duration, ms, type Time, unixMs } from './time.ts'
6
- import { Clock as ClockMessage, methods } from './wire/messages.ts'
6
+ import { methods, ServerClock } from './wire/protocol.ts'
7
7
 
8
8
  /**
9
9
  * The clock of a store opened with `{ private: true, clock }`. Moving it
@@ -36,10 +36,10 @@ export class Clock {
36
36
  return this.#move({ at: unixMs(to) })
37
37
  }
38
38
 
39
- async #move(fields: Parameters<typeof ClockMessage.encode>[0]): Promise<Date> {
39
+ async #move(fields: Parameters<typeof ServerClock.encode>[0]): Promise<Date> {
40
40
  const body = await this.#link.run('write', connection =>
41
- connection.session.call(methods['server.clock'], ClockMessage.encode(fields)),
41
+ connection.session.call(methods['server.clock'], ServerClock.encode(fields)),
42
42
  )
43
- return new Date(Number(ClockMessage.decode(body).at ?? 0))
43
+ return new Date(Number(ServerClock.decode(body).at ?? 0))
44
44
  }
45
45
  }