@tinyshed/tinystore 0.1.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 (100) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +262 -0
  3. package/bin/tinystore.js +50 -0
  4. package/dist/background.d.ts +30 -0
  5. package/dist/background.js +93 -0
  6. package/dist/blobs.d.ts +98 -0
  7. package/dist/blobs.js +299 -0
  8. package/dist/cancel.d.ts +14 -0
  9. package/dist/cancel.js +22 -0
  10. package/dist/clock.d.ts +21 -0
  11. package/dist/clock.js +35 -0
  12. package/dist/config.d.ts +60 -0
  13. package/dist/config.js +417 -0
  14. package/dist/connection.d.ts +78 -0
  15. package/dist/connection.js +405 -0
  16. package/dist/console.d.ts +48 -0
  17. package/dist/console.js +195 -0
  18. package/dist/errors.d.ts +103 -0
  19. package/dist/errors.js +158 -0
  20. package/dist/handles.d.ts +28 -0
  21. package/dist/handles.js +37 -0
  22. package/dist/index.d.ts +21 -0
  23. package/dist/index.js +7 -0
  24. package/dist/jobs.d.ts +304 -0
  25. package/dist/jobs.js +684 -0
  26. package/dist/kv.d.ts +283 -0
  27. package/dist/kv.js +815 -0
  28. package/dist/limiter.d.ts +45 -0
  29. package/dist/limiter.js +68 -0
  30. package/dist/logger.d.ts +96 -0
  31. package/dist/logger.js +243 -0
  32. package/dist/metrics.d.ts +249 -0
  33. package/dist/metrics.js +610 -0
  34. package/dist/once.d.ts +31 -0
  35. package/dist/once.js +116 -0
  36. package/dist/quota.d.ts +44 -0
  37. package/dist/quota.js +98 -0
  38. package/dist/records.d.ts +182 -0
  39. package/dist/records.js +346 -0
  40. package/dist/runtime/bun.d.ts +2 -0
  41. package/dist/runtime/bun.js +164 -0
  42. package/dist/runtime/node.d.ts +2 -0
  43. package/dist/runtime/node.js +157 -0
  44. package/dist/runtime/shared.d.ts +25 -0
  45. package/dist/runtime/shared.js +45 -0
  46. package/dist/runtime.d.ts +48 -0
  47. package/dist/runtime.js +4 -0
  48. package/dist/schema.d.ts +39 -0
  49. package/dist/schema.js +21 -0
  50. package/dist/session.d.ts +120 -0
  51. package/dist/session.js +546 -0
  52. package/dist/sql.d.ts +121 -0
  53. package/dist/sql.js +342 -0
  54. package/dist/store.d.ts +103 -0
  55. package/dist/store.js +153 -0
  56. package/dist/time.d.ts +35 -0
  57. package/dist/time.js +44 -0
  58. package/dist/trace.d.ts +18 -0
  59. package/dist/trace.js +22 -0
  60. package/dist/wire/codec.d.ts +90 -0
  61. package/dist/wire/codec.js +383 -0
  62. package/dist/wire/frame.d.ts +41 -0
  63. package/dist/wire/frame.js +102 -0
  64. package/dist/wire/messages.d.ts +1403 -0
  65. package/dist/wire/messages.js +472 -0
  66. package/dist/wire/msgpack.d.ts +93 -0
  67. package/dist/wire/msgpack.js +680 -0
  68. package/package.json +40 -0
  69. package/src/background.ts +108 -0
  70. package/src/blobs.ts +437 -0
  71. package/src/cancel.ts +26 -0
  72. package/src/clock.ts +45 -0
  73. package/src/config.ts +501 -0
  74. package/src/connection.ts +512 -0
  75. package/src/console.ts +228 -0
  76. package/src/errors.ts +211 -0
  77. package/src/handles.ts +68 -0
  78. package/src/index.ts +92 -0
  79. package/src/jobs.ts +963 -0
  80. package/src/kv.ts +1093 -0
  81. package/src/limiter.ts +99 -0
  82. package/src/logger.ts +326 -0
  83. package/src/metrics.ts +896 -0
  84. package/src/once.ts +142 -0
  85. package/src/quota.ts +137 -0
  86. package/src/records.ts +537 -0
  87. package/src/runtime/bun.ts +190 -0
  88. package/src/runtime/node.ts +177 -0
  89. package/src/runtime/shared.ts +61 -0
  90. package/src/runtime.ts +57 -0
  91. package/src/schema.ts +69 -0
  92. package/src/session.ts +665 -0
  93. package/src/sql.ts +478 -0
  94. package/src/store.ts +219 -0
  95. package/src/time.ts +87 -0
  96. package/src/trace.ts +32 -0
  97. package/src/wire/codec.ts +445 -0
  98. package/src/wire/frame.ts +139 -0
  99. package/src/wire/messages.ts +562 -0
  100. package/src/wire/msgpack.ts +712 -0
package/src/once.ts ADDED
@@ -0,0 +1,142 @@
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.
5
+
6
+ import { currentSignal } from './cancel.ts'
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'
13
+ import type { Key } from './wire/codec.ts'
14
+ import { KvCall, KvEntry, methods } from './wire/messages.ts'
15
+
16
+ export interface OnceOptions {
17
+ /** how long an answer is kept: a day when absent */
18
+ defaultTtl?: Duration
19
+ }
20
+
21
+ /** Answers kept once a key: open them with `store.kv.once(name)`. */
22
+ export class Once<V> {
23
+ readonly name: string
24
+ readonly #link: Link
25
+ readonly #open: Uint8Array
26
+ readonly #values: Values<V>
27
+ readonly #owners: (string | Uint8Array)[]
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
+ ) {
37
+ this.#link = link
38
+ this.name = name
39
+ this.#open = open
40
+ this.#values = values
41
+ this.#owners = owners
42
+ }
43
+
44
+ /** 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
+ ])
50
+ }
51
+
52
+ /**
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.
58
+ *
59
+ * const receipt = await charges.run(requestId, () => pay.charge(order, requestId))
60
+ */
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)
65
+ }
66
+ let answer: V
67
+ let body: Uint8Array
68
+ try {
69
+ answer = await fn()
70
+ body = KvEntry.encode({ found: true, value: await this.#values.encode(answer) })
71
+ } catch (err) {
72
+ await end(stream, KvEntry.encode({})).catch(() => {})
73
+ throw err
74
+ }
75
+ await end(stream, body)
76
+ return answer
77
+ }
78
+
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
83
+ }
84
+
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')
88
+ }
89
+
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'] }> {
95
+ 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)
99
+ const unwatch = watch(currentSignal(), stream)
100
+ try {
101
+ const first = await stream.next()
102
+ if (first.end) {
103
+ return { kept: KvEntry.decode(first.body).value }
104
+ }
105
+ return { stream }
106
+ } catch (err) {
107
+ stream.cancel()
108
+ throw err
109
+ } finally {
110
+ unwatch()
111
+ }
112
+ })
113
+ }
114
+
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
+ })
121
+ }
122
+
123
+ #ownersField(): (string | Uint8Array)[] | undefined {
124
+ return this.#owners.length > 0 ? this.#owners : undefined
125
+ }
126
+ }
127
+
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
+ )
139
+ }
140
+ throw err
141
+ }
142
+ }
package/src/quota.ts ADDED
@@ -0,0 +1,137 @@
1
+ // A quota of uses by key, as Go's kv.Quota keeps one: several windows, each
2
+ // starting at a key's first use after the last ended, checked and counted
3
+ // together in one durable write, or not counted at all.
4
+
5
+ import type { Link } from './connection.ts'
6
+ import { InvalidError } from './errors.ts'
7
+ import { checkName, handleOn, ownerText } from './handles.ts'
8
+ import { type Rate, rateOf } from './limiter.ts'
9
+ import { dateOf } from './time.ts'
10
+ import type { Key } from './wire/codec.ts'
11
+ import { KvAllowance, KvBucket, KvCall, methods } from './wire/messages.ts'
12
+
13
+ /** One window of a key: what it used of its limit, and when it resets. */
14
+ export interface WindowUsage {
15
+ used: number
16
+ limit: number
17
+ left: number
18
+ /** when the window ends and the next use starts another; undefined before it starts */
19
+ resetAt: Date | undefined
20
+ }
21
+
22
+ /** What a quota answers a key: what a limiter answers, and each window by its name. */
23
+ export interface QuotaUsage<W extends string = string> {
24
+ ok: boolean
25
+ /** how many more uses would pass now */
26
+ left: number
27
+ /** milliseconds until a refused use would pass; 0 when ok */
28
+ retryAfter: number
29
+ windows: Record<W, WindowUsage>
30
+ }
31
+
32
+ /** A quota: open it with `store.kv.quota(name, { session: '100/5h', weekly: '300/7d' })`. */
33
+ export class Quota<W extends string = string> {
34
+ readonly name: string
35
+ readonly #link: Link
36
+ readonly #open: Uint8Array
37
+ readonly #owners: (string | Uint8Array)[]
38
+
39
+ /** Quotas come from `store.kv.quota` and their `of`. */
40
+ constructor(link: Link, name: string, open: Uint8Array, owners: (string | Uint8Array)[]) {
41
+ this.#link = link
42
+ this.name = name
43
+ this.#open = open
44
+ this.#owners = owners
45
+ }
46
+
47
+ /** The quota of a branch, each key apart from the same key elsewhere. */
48
+ of(...owners: Key[]): Quota<W> {
49
+ return new Quota(this.#link, this.name, this.#open, [...this.#owners, ...owners.map(ownerText)])
50
+ }
51
+
52
+ /**
53
+ * Uses n of key's every window, one unless given, or none when one has no
54
+ * room for them; more than a window's limit is InvalidError.
55
+ *
56
+ * const { ok, retryAfter, windows } = await ai.allow(user.id)
57
+ */
58
+ async allow(key: Key, n = 1): Promise<QuotaUsage<W>> {
59
+ return usageOf(await this.#call('kv.allow', key, n, 'write'))
60
+ }
61
+
62
+ /** Key's windows without using them: ok says whether one more use would pass now. */
63
+ async get(key: Key): Promise<QuotaUsage<W>> {
64
+ return usageOf(await this.#call('kv.usage', key, 1, 'read'))
65
+ }
66
+
67
+ /** Gives n uses back, one unless given, to each of key's windows that has not reset since. */
68
+ async refund(key: Key, n = 1): Promise<void> {
69
+ await this.#call('kv.refund', key, n, 'write')
70
+ }
71
+
72
+ /** Forgets key's windows, so that its next use starts each anew. */
73
+ async delete(key: Key): Promise<void> {
74
+ await this.#call('kv.delete', key, 1, 'write')
75
+ }
76
+
77
+ async #call(
78
+ method: 'kv.allow' | 'kv.usage' | 'kv.refund' | 'kv.delete',
79
+ key: Key,
80
+ n: number,
81
+ idempotence: 'read' | 'write',
82
+ ) {
83
+ return this.#link.run(idempotence, async connection => {
84
+ const handle = await handleOn(connection, methods['kv.open'], this.#open)
85
+ const body = KvCall.encode({
86
+ handle,
87
+ owners: this.#owners.length > 0 ? this.#owners : undefined,
88
+ key,
89
+ n: n === 1 ? undefined : n,
90
+ })
91
+ return await connection.session.call(methods[method], body)
92
+ })
93
+ }
94
+ }
95
+
96
+ function usageOf<W extends string>(body: Uint8Array): QuotaUsage<W> {
97
+ const answer = KvAllowance.decode(body)
98
+ const windows = {} as Record<W, WindowUsage>
99
+ for (const w of answer.windows ?? []) {
100
+ windows[(w.name ?? '') as W] = {
101
+ used: w.used ?? 0,
102
+ limit: w.limit ?? 0,
103
+ left: w.left ?? 0,
104
+ resetAt: dateOf(w.resetAt),
105
+ }
106
+ }
107
+ return {
108
+ ok: answer.ok === true,
109
+ left: answer.left ?? 0,
110
+ retryAfter: answer.retryAfter ?? 0,
111
+ windows,
112
+ }
113
+ }
114
+
115
+ /** A quota's open: its name and windows, checked before anything leaves. */
116
+ export function quotaOpen(name: string, windows: Record<string, Rate>): Uint8Array {
117
+ checkName(name, 'quota')
118
+ const spans = Object.entries(windows)
119
+ if (spans.length < 1 || spans.length > 8) {
120
+ throw new InvalidError(`quota ${name}: ${spans.length} windows, not one to eight`)
121
+ }
122
+ return KvBucket.encode({
123
+ name,
124
+ windows: spans.map(([window, rate]) => {
125
+ if (!/^[a-z][a-z0-9_]{0,31}$/.test(window)) {
126
+ throw new InvalidError(
127
+ `quota ${name}: a window name is [a-z][a-z0-9_]{0,31}, not ${window}`,
128
+ )
129
+ }
130
+ const { count, per } = rateOf(rate)
131
+ if (count < 1 || per < 1) {
132
+ throw new InvalidError(`quota ${name}: a window of ${rate}`)
133
+ }
134
+ return { name: window, limit: count, per }
135
+ }),
136
+ })
137
+ }