@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.
- package/LICENSE +202 -0
- package/README.md +262 -0
- package/bin/tinystore.js +50 -0
- package/dist/background.d.ts +30 -0
- package/dist/background.js +93 -0
- package/dist/blobs.d.ts +98 -0
- package/dist/blobs.js +299 -0
- package/dist/cancel.d.ts +14 -0
- package/dist/cancel.js +22 -0
- package/dist/clock.d.ts +21 -0
- package/dist/clock.js +35 -0
- package/dist/config.d.ts +60 -0
- package/dist/config.js +417 -0
- package/dist/connection.d.ts +78 -0
- package/dist/connection.js +405 -0
- package/dist/console.d.ts +48 -0
- package/dist/console.js +195 -0
- package/dist/errors.d.ts +103 -0
- package/dist/errors.js +158 -0
- package/dist/handles.d.ts +28 -0
- package/dist/handles.js +37 -0
- package/dist/index.d.ts +21 -0
- package/dist/index.js +7 -0
- package/dist/jobs.d.ts +304 -0
- package/dist/jobs.js +684 -0
- package/dist/kv.d.ts +283 -0
- package/dist/kv.js +815 -0
- package/dist/limiter.d.ts +45 -0
- package/dist/limiter.js +68 -0
- package/dist/logger.d.ts +96 -0
- package/dist/logger.js +243 -0
- package/dist/metrics.d.ts +249 -0
- package/dist/metrics.js +610 -0
- package/dist/once.d.ts +31 -0
- package/dist/once.js +116 -0
- package/dist/quota.d.ts +44 -0
- package/dist/quota.js +98 -0
- package/dist/records.d.ts +182 -0
- package/dist/records.js +346 -0
- package/dist/runtime/bun.d.ts +2 -0
- package/dist/runtime/bun.js +164 -0
- package/dist/runtime/node.d.ts +2 -0
- package/dist/runtime/node.js +157 -0
- package/dist/runtime/shared.d.ts +25 -0
- package/dist/runtime/shared.js +45 -0
- package/dist/runtime.d.ts +48 -0
- package/dist/runtime.js +4 -0
- package/dist/schema.d.ts +39 -0
- package/dist/schema.js +21 -0
- package/dist/session.d.ts +120 -0
- package/dist/session.js +546 -0
- package/dist/sql.d.ts +121 -0
- package/dist/sql.js +342 -0
- package/dist/store.d.ts +103 -0
- package/dist/store.js +153 -0
- package/dist/time.d.ts +35 -0
- package/dist/time.js +44 -0
- package/dist/trace.d.ts +18 -0
- package/dist/trace.js +22 -0
- package/dist/wire/codec.d.ts +90 -0
- package/dist/wire/codec.js +383 -0
- package/dist/wire/frame.d.ts +41 -0
- package/dist/wire/frame.js +102 -0
- package/dist/wire/messages.d.ts +1403 -0
- package/dist/wire/messages.js +472 -0
- package/dist/wire/msgpack.d.ts +93 -0
- package/dist/wire/msgpack.js +680 -0
- package/package.json +40 -0
- package/src/background.ts +108 -0
- package/src/blobs.ts +437 -0
- package/src/cancel.ts +26 -0
- package/src/clock.ts +45 -0
- package/src/config.ts +501 -0
- package/src/connection.ts +512 -0
- package/src/console.ts +228 -0
- package/src/errors.ts +211 -0
- package/src/handles.ts +68 -0
- package/src/index.ts +92 -0
- package/src/jobs.ts +963 -0
- package/src/kv.ts +1093 -0
- package/src/limiter.ts +99 -0
- package/src/logger.ts +326 -0
- package/src/metrics.ts +896 -0
- package/src/once.ts +142 -0
- package/src/quota.ts +137 -0
- package/src/records.ts +537 -0
- package/src/runtime/bun.ts +190 -0
- package/src/runtime/node.ts +177 -0
- package/src/runtime/shared.ts +61 -0
- package/src/runtime.ts +57 -0
- package/src/schema.ts +69 -0
- package/src/session.ts +665 -0
- package/src/sql.ts +478 -0
- package/src/store.ts +219 -0
- package/src/time.ts +87 -0
- package/src/trace.ts +32 -0
- package/src/wire/codec.ts +445 -0
- package/src/wire/frame.ts +139 -0
- package/src/wire/messages.ts +562 -0
- 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
|
+
}
|