@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/kv.ts
ADDED
|
@@ -0,0 +1,1093 @@
|
|
|
1
|
+
// The application's current state in kv.db, as Go's kv package keeps it:
|
|
2
|
+
// buckets of one value type by key, keys in branches, expiry by the store's
|
|
3
|
+
// clock, versions that never repeat. A handle opens with its first call.
|
|
4
|
+
|
|
5
|
+
import { Config, type ConfigOptions } from './config.ts'
|
|
6
|
+
import type { Connection, Link } from './connection.ts'
|
|
7
|
+
import { ConflictError, CorruptError, InvalidError } from './errors.ts'
|
|
8
|
+
import { checkName, handleOn, ownerText, type Page, type Settled, settle } from './handles.ts'
|
|
9
|
+
import { Limiter, type LimiterOptions, limiterOpen, type Rate } from './limiter.ts'
|
|
10
|
+
import { Once, type OnceOptions } from './once.ts'
|
|
11
|
+
import { Quota, quotaOpen } from './quota.ts'
|
|
12
|
+
import { check, isSchema, type StandardSchemaV1 } from './schema.ts'
|
|
13
|
+
import { type Duration, dateOf, ms, type Time, unixMs } from './time.ts'
|
|
14
|
+
import { type Key, type Raw, textOf } from './wire/codec.ts'
|
|
15
|
+
import { KvBucket, KvCall, KvCalls, KvEntry, KvPage, KvResults, methods } from './wire/messages.ts'
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* How a bucket keeps its values in a row, as Go's codecFor keeps a type's,
|
|
19
|
+
* so that Go, Python and this SDK read each other's buckets:
|
|
20
|
+
*
|
|
21
|
+
* 'json' JSON text, the default a Go struct, a Python dataclass
|
|
22
|
+
* 'string' its UTF-8 bytes string, str
|
|
23
|
+
* 'bytes' the bytes []byte, bytes
|
|
24
|
+
* 'int' an integer, a number exactly int64, int
|
|
25
|
+
* 'bigint' an integer int64, int
|
|
26
|
+
* 'float' its eight bytes, big-endian float64, float
|
|
27
|
+
* 'bool' 1 or 0 bool, bool
|
|
28
|
+
* 'none' nothing: a bucket of them is a set struct{}, None
|
|
29
|
+
*/
|
|
30
|
+
export type Kind = 'json' | 'string' | 'bytes' | 'int' | 'bigint' | 'float' | 'bool' | 'none'
|
|
31
|
+
|
|
32
|
+
interface KindValue {
|
|
33
|
+
json: unknown
|
|
34
|
+
string: string
|
|
35
|
+
bytes: Uint8Array
|
|
36
|
+
int: number
|
|
37
|
+
bigint: bigint
|
|
38
|
+
float: number
|
|
39
|
+
bool: boolean
|
|
40
|
+
none: null
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
export interface BucketOptions {
|
|
44
|
+
/** the expiry a key gets when it is written without its own */
|
|
45
|
+
defaultTtl?: Duration
|
|
46
|
+
/** keeps a key this long from its last read; beside defaultTtl it is refused */
|
|
47
|
+
sliding?: Duration
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
export interface CounterOptions {
|
|
51
|
+
defaultTtl?: Duration
|
|
52
|
+
/**
|
|
53
|
+
* keeps changes in the server's memory between flushes this far apart, so
|
|
54
|
+
* a crash may lose them: attempts and rates, not money
|
|
55
|
+
*/
|
|
56
|
+
loseAtMost?: Duration
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
export interface WriteOptions {
|
|
60
|
+
ttl?: Duration
|
|
61
|
+
expireAt?: Time
|
|
62
|
+
/** writes only while the key is live at this version: ConflictError otherwise */
|
|
63
|
+
ifVersion?: string
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
export interface Entry<V> {
|
|
67
|
+
value: V
|
|
68
|
+
/** compared only for equality: give it back to ifVersion */
|
|
69
|
+
version: string
|
|
70
|
+
/** when the key expires; undefined for one that never does */
|
|
71
|
+
expires: Date | undefined
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
export interface Scanned<V> extends Entry<V> {
|
|
75
|
+
/** the key's text; bytes when it is not UTF-8 */
|
|
76
|
+
key: string | Uint8Array
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/** Encodes a bucket's values into what a row keeps, and back. */
|
|
80
|
+
export interface Values<V> {
|
|
81
|
+
encode(value: V): Raw | Promise<Raw>
|
|
82
|
+
decode(raw: Raw): V | Promise<V>
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
export class Kv {
|
|
86
|
+
readonly #link: Link
|
|
87
|
+
readonly #configs = new Set<Config<object>>()
|
|
88
|
+
|
|
89
|
+
constructor(link: Link) {
|
|
90
|
+
this.#link = link
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* The config name, shaped and typed as its defaults: then a file's values,
|
|
95
|
+
* then the environment, then what update kept, each over the one before.
|
|
96
|
+
* It resolves once the server's state is read, and follows every change
|
|
97
|
+
* from then on, whoever makes it, until the store closes.
|
|
98
|
+
*
|
|
99
|
+
* ```ts
|
|
100
|
+
* const cfg = await store.kv.config('app', { port: 8080, origins: ['localhost'] })
|
|
101
|
+
* cfg.value.port // PORT=3000 in .env makes it 3000
|
|
102
|
+
* await cfg.update({ port: 4000 }) // kept: 4000 after a restart too
|
|
103
|
+
* ```
|
|
104
|
+
*/
|
|
105
|
+
async config<T extends object>(
|
|
106
|
+
name: string,
|
|
107
|
+
defaults: T,
|
|
108
|
+
options: ConfigOptions<T> = {},
|
|
109
|
+
): Promise<Config<T>> {
|
|
110
|
+
const config = new Config(this.#link, name, defaults, options)
|
|
111
|
+
this.#configs.add(config as unknown as Config<object>)
|
|
112
|
+
try {
|
|
113
|
+
await config.start()
|
|
114
|
+
} catch (err) {
|
|
115
|
+
this.#configs.delete(config as unknown as Config<object>)
|
|
116
|
+
throw err
|
|
117
|
+
}
|
|
118
|
+
return config
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/** A limiter of requests by key: `store.kv.limiter('api', { rate: '100/s', burst: 20 })`. */
|
|
122
|
+
limiter(name: string, options: LimiterOptions): Limiter {
|
|
123
|
+
return new Limiter(this.#link, name, limiterOpen(name, options), [])
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* A quota of uses by key, its windows by name, each counted from a key's
|
|
128
|
+
* first use and all of them together or none:
|
|
129
|
+
* `store.kv.quota('ai', { session: '100/5h', weekly: '300/7d' })`.
|
|
130
|
+
*/
|
|
131
|
+
quota<W extends string>(name: string, windows: Record<W, Rate>): Quota<W> {
|
|
132
|
+
return new Quota(this.#link, name, quotaOpen(name, windows), [])
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* The answers a function gives once a key, JSON values of type T kept a
|
|
137
|
+
* day unless defaultTtl says: `store.kv.once<Receipt>('charges')`.
|
|
138
|
+
*/
|
|
139
|
+
once<T = unknown>(name: string, options?: OnceOptions): Once<T>
|
|
140
|
+
/** Answers each read is checked by, zod's, valibot's or another Standard Schema. */
|
|
141
|
+
once<S extends StandardSchemaV1>(
|
|
142
|
+
name: string,
|
|
143
|
+
schema: S,
|
|
144
|
+
options?: OnceOptions,
|
|
145
|
+
): Once<StandardSchemaV1.InferOutput<S>>
|
|
146
|
+
once(name: string, of?: StandardSchemaV1 | OnceOptions, options?: OnceOptions): Once<unknown> {
|
|
147
|
+
checkName(name, 'once')
|
|
148
|
+
let values: Values<unknown> = jsonValues
|
|
149
|
+
if (isSchema(of)) {
|
|
150
|
+
values = schemaValues(of)
|
|
151
|
+
} else if (of !== undefined) {
|
|
152
|
+
options = of
|
|
153
|
+
}
|
|
154
|
+
const open = KvBucket.encode({
|
|
155
|
+
name,
|
|
156
|
+
once: true,
|
|
157
|
+
defaultTtl: options?.defaultTtl === undefined ? undefined : ms(options.defaultTtl),
|
|
158
|
+
})
|
|
159
|
+
return new Once(this.#link, name, open, values, [])
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/** Stops following configs, as the store does when it closes. */
|
|
163
|
+
stop(): void {
|
|
164
|
+
for (const config of this.#configs) {
|
|
165
|
+
config.stop()
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
/** A bucket of JSON values of type T. */
|
|
170
|
+
bucket<T = unknown>(name: string, options?: BucketOptions): Bucket<T>
|
|
171
|
+
/** A bucket of values kept as their kind says. */
|
|
172
|
+
bucket<K extends Kind>(name: string, kind: K, options?: BucketOptions): Bucket<KindValue[K]>
|
|
173
|
+
/** A bucket of JSON values each read is checked by, zod's, valibot's or another Standard Schema. */
|
|
174
|
+
bucket<S extends StandardSchemaV1>(
|
|
175
|
+
name: string,
|
|
176
|
+
schema: S,
|
|
177
|
+
options?: BucketOptions,
|
|
178
|
+
): Bucket<StandardSchemaV1.InferOutput<S>>
|
|
179
|
+
bucket(
|
|
180
|
+
name: string,
|
|
181
|
+
of?: Kind | StandardSchemaV1 | BucketOptions,
|
|
182
|
+
options?: BucketOptions,
|
|
183
|
+
): Bucket<unknown> {
|
|
184
|
+
checkName(name, 'bucket')
|
|
185
|
+
let values: Values<unknown> = jsonValues
|
|
186
|
+
if (typeof of === 'string') {
|
|
187
|
+
values = valuesOf(of)
|
|
188
|
+
} else if (isSchema(of)) {
|
|
189
|
+
values = schemaValues(of)
|
|
190
|
+
} else if (of !== undefined) {
|
|
191
|
+
options = of
|
|
192
|
+
}
|
|
193
|
+
if (options?.defaultTtl !== undefined && options.sliding !== undefined) {
|
|
194
|
+
throw new InvalidError(`bucket ${name}: sliding and defaultTtl are one or the other`)
|
|
195
|
+
}
|
|
196
|
+
const open = KvBucket.encode({
|
|
197
|
+
name,
|
|
198
|
+
defaultTtl: options?.defaultTtl === undefined ? undefined : ms(options.defaultTtl),
|
|
199
|
+
sliding: options?.sliding === undefined ? undefined : ms(options.sliding),
|
|
200
|
+
})
|
|
201
|
+
return new Bucket(this.#link, name, open, values, [])
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
/** Counters, an int64 a key read as a number, 0 when absent. */
|
|
205
|
+
counters(name: string, options?: CounterOptions): Counters<number>
|
|
206
|
+
/** Counters read as bigints, for values past 2^53. */
|
|
207
|
+
counters(name: string, kind: 'bigint', options?: CounterOptions): Counters<bigint>
|
|
208
|
+
counters(
|
|
209
|
+
name: string,
|
|
210
|
+
of?: 'int' | 'bigint' | CounterOptions,
|
|
211
|
+
options?: CounterOptions,
|
|
212
|
+
): Counters<number | bigint> {
|
|
213
|
+
checkName(name, 'counters')
|
|
214
|
+
const big = of === 'bigint'
|
|
215
|
+
if (typeof of === 'object') {
|
|
216
|
+
options = of
|
|
217
|
+
}
|
|
218
|
+
const open = KvBucket.encode({
|
|
219
|
+
name,
|
|
220
|
+
counters: true,
|
|
221
|
+
defaultTtl: options?.defaultTtl === undefined ? undefined : ms(options.defaultTtl),
|
|
222
|
+
loseAtMost: options?.loseAtMost === undefined ? undefined : ms(options.loseAtMost),
|
|
223
|
+
})
|
|
224
|
+
return new Counters(this.#link, name, open, big, [])
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
/**
|
|
228
|
+
* Runs the calls fn asks for in one transaction, all or none: the calls of
|
|
229
|
+
* buckets it takes through withTx, whose promises settle once the batch
|
|
230
|
+
* has. fn returns before anything is sent, since no transaction is held
|
|
231
|
+
* across the network: a call cannot wait for another's answer inside it.
|
|
232
|
+
* What fn returns comes back answered, an array's promises each:
|
|
233
|
+
*
|
|
234
|
+
* const [code] = await store.kv.batch(tx => [codes.withTx(tx).take(k), used.withTx(tx).set(k, 1)])
|
|
235
|
+
*/
|
|
236
|
+
batch<const T = void>(fn: (tx: Batch) => T): Promise<Settled<T>> {
|
|
237
|
+
return runCalls(this.#link, 'batch', fn)
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
/**
|
|
241
|
+
* Reads the gets and hases fn asks for from one snapshot, and gives back
|
|
242
|
+
* what fn returns, answered as batch answers it:
|
|
243
|
+
*
|
|
244
|
+
* const [profile, prefs] = await store.kv.view(tx => [a.withTx(tx).get(id), b.withTx(tx).get(id)])
|
|
245
|
+
*/
|
|
246
|
+
view<const T = void>(fn: (tx: Batch) => T): Promise<Settled<T>> {
|
|
247
|
+
return runCalls(this.#link, 'view', fn)
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
/**
|
|
251
|
+
* Runs fn as one transaction that reads before it decides what to write,
|
|
252
|
+
* as Go's Tx does, without holding the writer across the network: a read
|
|
253
|
+
* goes to the server at once, a write waits, and when fn returns the writes
|
|
254
|
+
* commit in one batch that first checks every key fn read is still as it
|
|
255
|
+
* read it. When another write changed one meanwhile, fn runs again, five
|
|
256
|
+
* times at most before ConflictError, so it does nothing else that must
|
|
257
|
+
* happen once. It gives back what fn returns.
|
|
258
|
+
*
|
|
259
|
+
* const userId = await store.kv.tx(async tx => {
|
|
260
|
+
* const userId = await codes.withTx(tx).take(digest(code))
|
|
261
|
+
* if (userId === undefined) throw new InvalidCode()
|
|
262
|
+
* sessions.withTx(tx).of(userId).set(digest(token), { device })
|
|
263
|
+
* return userId
|
|
264
|
+
* })
|
|
265
|
+
*/
|
|
266
|
+
async tx<T>(fn: (tx: Tx) => T | Promise<T>): Promise<T> {
|
|
267
|
+
for (let run = 1; ; run++) {
|
|
268
|
+
const tx = new Tx(this.#link)
|
|
269
|
+
const returned = await fn(tx)
|
|
270
|
+
try {
|
|
271
|
+
await tx.commit()
|
|
272
|
+
return returned
|
|
273
|
+
} catch (err) {
|
|
274
|
+
if (run >= txRuns || !tx.stale(err)) {
|
|
275
|
+
throw err
|
|
276
|
+
}
|
|
277
|
+
}
|
|
278
|
+
}
|
|
279
|
+
}
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
/** How many times tx runs its function before a key it read that keeps changing is ConflictError. */
|
|
283
|
+
const txRuns = 5
|
|
284
|
+
|
|
285
|
+
/** The calls a batch or a view gathered, in their order. */
|
|
286
|
+
export class Batch {
|
|
287
|
+
readonly kind: 'batch' | 'view'
|
|
288
|
+
readonly calls: Recorded[] = []
|
|
289
|
+
#done = false
|
|
290
|
+
readonly #made = new WeakSet<Promise<unknown>>()
|
|
291
|
+
|
|
292
|
+
constructor(kind: 'batch' | 'view') {
|
|
293
|
+
this.kind = kind
|
|
294
|
+
}
|
|
295
|
+
|
|
296
|
+
/** Whether the promise is one of this batch's calls', rather than an async function's. */
|
|
297
|
+
made(promise: Promise<unknown>): boolean {
|
|
298
|
+
return this.#made.has(promise)
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
record<T>(
|
|
302
|
+
call: Omit<Recorded, 'settle'>,
|
|
303
|
+
settle: (entry: Entry<Raw> & { found: boolean }) => Promise<T>,
|
|
304
|
+
) {
|
|
305
|
+
if (this.#done) {
|
|
306
|
+
throw new InvalidError(
|
|
307
|
+
`a ${this.kind} takes its calls while its function runs, before it is sent`,
|
|
308
|
+
)
|
|
309
|
+
}
|
|
310
|
+
if (this.kind === 'view' && call.method !== 'kv.get' && call.method !== 'kv.has') {
|
|
311
|
+
throw new InvalidError(`${call.method} in a view, which reads`)
|
|
312
|
+
}
|
|
313
|
+
let resolve!: (v: T) => void
|
|
314
|
+
let reject!: (e: unknown) => void
|
|
315
|
+
const settled = new Promise<T>((res, rej) => {
|
|
316
|
+
resolve = res
|
|
317
|
+
reject = rej
|
|
318
|
+
})
|
|
319
|
+
// a caller need not await a call it only wanted done
|
|
320
|
+
settled.catch(() => {})
|
|
321
|
+
this.#made.add(settled)
|
|
322
|
+
this.calls.push({
|
|
323
|
+
...call,
|
|
324
|
+
settle: async entry => {
|
|
325
|
+
try {
|
|
326
|
+
resolve(await settle(entry))
|
|
327
|
+
} catch (err) {
|
|
328
|
+
reject(err)
|
|
329
|
+
}
|
|
330
|
+
},
|
|
331
|
+
fail: reject,
|
|
332
|
+
})
|
|
333
|
+
return settled
|
|
334
|
+
}
|
|
335
|
+
|
|
336
|
+
close(): void {
|
|
337
|
+
this.#done = true
|
|
338
|
+
}
|
|
339
|
+
}
|
|
340
|
+
|
|
341
|
+
interface Recorded {
|
|
342
|
+
method: keyof typeof methods
|
|
343
|
+
open: Uint8Array
|
|
344
|
+
call: Parameters<typeof KvCall.encode>[0]
|
|
345
|
+
settle: (entry: Entry<Raw> & { found: boolean }) => Promise<void>
|
|
346
|
+
fail?: (err: unknown) => void
|
|
347
|
+
}
|
|
348
|
+
|
|
349
|
+
/** What a bucket's calls inside a batch, a view or a tx go through. */
|
|
350
|
+
interface Recorder {
|
|
351
|
+
record<T>(
|
|
352
|
+
call: Omit<Recorded, 'settle'>,
|
|
353
|
+
settle: (entry: Entry<Raw> & { found: boolean }) => Promise<T>,
|
|
354
|
+
): Promise<T>
|
|
355
|
+
}
|
|
356
|
+
|
|
357
|
+
type Found = Entry<Raw> & { found: boolean }
|
|
358
|
+
|
|
359
|
+
/** A key a tx read: the call that read it, and what it found, which its commit checks. */
|
|
360
|
+
interface Read {
|
|
361
|
+
call: Omit<Recorded, 'settle'>
|
|
362
|
+
version: Uint8Array | undefined
|
|
363
|
+
entry: Found
|
|
364
|
+
}
|
|
365
|
+
|
|
366
|
+
const absent: Found = { found: false, value: null, version: '', expires: undefined }
|
|
367
|
+
|
|
368
|
+
/**
|
|
369
|
+
* A transaction of store.kv.tx: a read goes to the server at once and is
|
|
370
|
+
* remembered with its version, so that a key read again answers the same; a
|
|
371
|
+
* write waits for the commit, and a key read after it answers what it wrote.
|
|
372
|
+
*/
|
|
373
|
+
export class Tx implements Recorder {
|
|
374
|
+
readonly #link: Link
|
|
375
|
+
readonly #reads = new Map<string, Promise<Read>>()
|
|
376
|
+
readonly #writes = new Map<string, { call: Omit<Recorded, 'settle'>; entry: Found }>()
|
|
377
|
+
#checks = 0
|
|
378
|
+
#done = false
|
|
379
|
+
|
|
380
|
+
constructor(link: Link) {
|
|
381
|
+
this.#link = link
|
|
382
|
+
}
|
|
383
|
+
|
|
384
|
+
record<T>(call: Omit<Recorded, 'settle'>, settle: (entry: Found) => Promise<T>): Promise<T> {
|
|
385
|
+
if (this.#done) {
|
|
386
|
+
throw new InvalidError('a tx takes its calls while its function runs, before it commits')
|
|
387
|
+
}
|
|
388
|
+
const at = placeOf(call)
|
|
389
|
+
switch (call.method) {
|
|
390
|
+
case 'kv.get':
|
|
391
|
+
case 'kv.has':
|
|
392
|
+
return this.#read(at, call).then(settle)
|
|
393
|
+
case 'kv.take': {
|
|
394
|
+
const read = this.#read(at, call)
|
|
395
|
+
this.#writes.set(at, { call: { ...call, method: 'kv.delete' }, entry: absent })
|
|
396
|
+
return read.then(settle)
|
|
397
|
+
}
|
|
398
|
+
case 'kv.set': {
|
|
399
|
+
// a set's value is what the bucket encoded, which a read decodes
|
|
400
|
+
const value = (call.call.value ?? null) as Raw
|
|
401
|
+
const entry: Found = { found: true, value, version: '', expires: undefined }
|
|
402
|
+
this.#writes.set(at, { call, entry })
|
|
403
|
+
return settle(entry)
|
|
404
|
+
}
|
|
405
|
+
case 'kv.delete':
|
|
406
|
+
this.#writes.set(at, { call, entry: absent })
|
|
407
|
+
return settle(absent)
|
|
408
|
+
}
|
|
409
|
+
throw new InvalidError(`${call.method} in a tx`)
|
|
410
|
+
}
|
|
411
|
+
|
|
412
|
+
#read(at: string, call: Omit<Recorded, 'settle'>): Promise<Found> {
|
|
413
|
+
const written = this.#writes.get(at)
|
|
414
|
+
if (written !== undefined) {
|
|
415
|
+
return Promise.resolve(written.entry)
|
|
416
|
+
}
|
|
417
|
+
let reading = this.#reads.get(at)
|
|
418
|
+
if (reading === undefined) {
|
|
419
|
+
reading = this.#fetch(call)
|
|
420
|
+
// a read fn never awaited still fails the commit, which awaits it
|
|
421
|
+
reading.catch(() => {})
|
|
422
|
+
this.#reads.set(at, reading)
|
|
423
|
+
}
|
|
424
|
+
return reading.then(read => read.entry)
|
|
425
|
+
}
|
|
426
|
+
|
|
427
|
+
async #fetch(call: Omit<Recorded, 'settle'>): Promise<Read> {
|
|
428
|
+
const ask = { owners: call.call.owners, key: call.call.key }
|
|
429
|
+
const e = await this.#link.run('read', async connection => {
|
|
430
|
+
const handle = await handleOn(connection, methods['kv.open'], call.open)
|
|
431
|
+
const body = await connection.session.call(
|
|
432
|
+
methods['kv.get'],
|
|
433
|
+
KvCall.encode({ ...ask, handle }),
|
|
434
|
+
)
|
|
435
|
+
return KvEntry.decode(body)
|
|
436
|
+
})
|
|
437
|
+
return {
|
|
438
|
+
call: { method: 'kv.get', open: call.open, call: ask },
|
|
439
|
+
version: e.version,
|
|
440
|
+
entry: entryOfWire(e),
|
|
441
|
+
}
|
|
442
|
+
}
|
|
443
|
+
|
|
444
|
+
/**
|
|
445
|
+
* Sends what fn wrote in one batch, after a check of each key it read: a
|
|
446
|
+
* key it found at the version it found, a key it found absent still
|
|
447
|
+
* absent. A tx that only read checks its reads from one snapshot.
|
|
448
|
+
*/
|
|
449
|
+
async commit(): Promise<void> {
|
|
450
|
+
this.#done = true
|
|
451
|
+
const calls: Omit<Recorded, 'settle'>[] = []
|
|
452
|
+
for (const reading of this.#reads.values()) {
|
|
453
|
+
const read = await reading
|
|
454
|
+
const still = read.entry.found ? { ifVersion: read.version } : { ifAbsent: true }
|
|
455
|
+
calls.push({ ...read.call, call: { ...read.call.call, ...still } })
|
|
456
|
+
}
|
|
457
|
+
this.#checks = calls.length
|
|
458
|
+
for (const write of this.#writes.values()) {
|
|
459
|
+
calls.push(write.call)
|
|
460
|
+
}
|
|
461
|
+
if (calls.length === 0) {
|
|
462
|
+
return
|
|
463
|
+
}
|
|
464
|
+
const writes = this.#writes.size > 0
|
|
465
|
+
await this.#link.run(writes ? 'write' : 'read', async connection => {
|
|
466
|
+
const encoded = []
|
|
467
|
+
for (const call of calls) {
|
|
468
|
+
const handle = await handleOn(connection, methods['kv.open'], call.open)
|
|
469
|
+
encoded.push({ method: methods[call.method], ...call.call, handle })
|
|
470
|
+
}
|
|
471
|
+
const method = writes ? methods['kv.batch'] : methods['kv.view']
|
|
472
|
+
await connection.session.call(method, KvCalls.encode({ calls: encoded }))
|
|
473
|
+
})
|
|
474
|
+
}
|
|
475
|
+
|
|
476
|
+
/** Whether the commit failed for a key fn read that changed since, which another run reads anew. */
|
|
477
|
+
stale(err: unknown): boolean {
|
|
478
|
+
return err instanceof ConflictError && Number(err.what.call) < this.#checks
|
|
479
|
+
}
|
|
480
|
+
}
|
|
481
|
+
|
|
482
|
+
/**
|
|
483
|
+
* A key's place as one text: its bucket's open and its owners included, an
|
|
484
|
+
* integer its decimal spelling, as the store keeps it.
|
|
485
|
+
*/
|
|
486
|
+
function placeOf(call: Omit<Recorded, 'settle'>): string {
|
|
487
|
+
const part = (p: Key | undefined) =>
|
|
488
|
+
p instanceof Uint8Array ? `b${Buffer.from(p).toString('base64')}` : `t${String(p ?? '')}`
|
|
489
|
+
const owners = call.call.owners ?? []
|
|
490
|
+
return [Buffer.from(call.open).toString('base64'), ...owners.map(part), part(call.call.key)].join(
|
|
491
|
+
'\u0000',
|
|
492
|
+
)
|
|
493
|
+
}
|
|
494
|
+
|
|
495
|
+
async function runCalls<T>(
|
|
496
|
+
link: Link,
|
|
497
|
+
kind: 'batch' | 'view',
|
|
498
|
+
fn: (tx: Batch) => T,
|
|
499
|
+
): Promise<Settled<T>> {
|
|
500
|
+
const tx = new Batch(kind)
|
|
501
|
+
const returned = fn(tx)
|
|
502
|
+
tx.close()
|
|
503
|
+
if (returned instanceof Promise && !tx.made(returned)) {
|
|
504
|
+
throw new InvalidError(
|
|
505
|
+
`a ${kind}'s function returns before anything is sent; it cannot await inside`,
|
|
506
|
+
)
|
|
507
|
+
}
|
|
508
|
+
if (tx.calls.length > 0) {
|
|
509
|
+
await sendCalls(link, kind, tx)
|
|
510
|
+
}
|
|
511
|
+
return settle(returned)
|
|
512
|
+
}
|
|
513
|
+
|
|
514
|
+
async function sendCalls(link: Link, kind: 'batch' | 'view', tx: Batch): Promise<void> {
|
|
515
|
+
try {
|
|
516
|
+
const results = await link.run(kind === 'view' ? 'read' : 'write', async connection => {
|
|
517
|
+
const calls = []
|
|
518
|
+
for (const call of tx.calls) {
|
|
519
|
+
const handle = await handleOn(connection, methods['kv.open'], call.open)
|
|
520
|
+
calls.push({ method: methods[call.method], ...call.call, handle })
|
|
521
|
+
}
|
|
522
|
+
const body = await connection.session.call(methods[`kv.${kind}`], KvCalls.encode({ calls }))
|
|
523
|
+
return KvResults.decode(body).entries ?? []
|
|
524
|
+
})
|
|
525
|
+
await Promise.all(tx.calls.map((call, i) => call.settle(entryOfWire(results[i] ?? {}))))
|
|
526
|
+
} catch (err) {
|
|
527
|
+
for (const call of tx.calls) {
|
|
528
|
+
call.fail?.(err)
|
|
529
|
+
}
|
|
530
|
+
throw err
|
|
531
|
+
}
|
|
532
|
+
}
|
|
533
|
+
|
|
534
|
+
function entryOfWire(e: ReturnType<typeof KvEntry.decode>): Entry<Raw> & { found: boolean } {
|
|
535
|
+
return {
|
|
536
|
+
found: e.found ?? false,
|
|
537
|
+
value: e.value ?? null,
|
|
538
|
+
version: versionText(e.version),
|
|
539
|
+
expires: dateOf(e.expires),
|
|
540
|
+
}
|
|
541
|
+
}
|
|
542
|
+
|
|
543
|
+
/** A version's bytes as text, each byte a code unit, so that any bytes go back as they came. */
|
|
544
|
+
function versionText(version: Uint8Array | undefined): string {
|
|
545
|
+
return version === undefined ? '' : String.fromCharCode(...version)
|
|
546
|
+
}
|
|
547
|
+
|
|
548
|
+
function versionBytes(version: string): Uint8Array {
|
|
549
|
+
return Uint8Array.from(version, c => c.charCodeAt(0))
|
|
550
|
+
}
|
|
551
|
+
|
|
552
|
+
function writeFields(options: WriteOptions | undefined) {
|
|
553
|
+
return {
|
|
554
|
+
ttl: options?.ttl === undefined ? undefined : ms(options.ttl),
|
|
555
|
+
expireAt: options?.expireAt === undefined ? undefined : unixMs(options.expireAt),
|
|
556
|
+
ifVersion: options?.ifVersion === undefined ? undefined : versionBytes(options.ifVersion),
|
|
557
|
+
}
|
|
558
|
+
}
|
|
559
|
+
|
|
560
|
+
/**
|
|
561
|
+
* A bucket's values under one branch of owners, the root when there are
|
|
562
|
+
* none: `sessions.of(user.id).get(token)`.
|
|
563
|
+
*/
|
|
564
|
+
export class Bucket<V> {
|
|
565
|
+
readonly name: string
|
|
566
|
+
readonly #link: Link
|
|
567
|
+
readonly #open: Uint8Array
|
|
568
|
+
readonly #values: Values<V>
|
|
569
|
+
readonly #owners: (string | Uint8Array)[]
|
|
570
|
+
|
|
571
|
+
constructor(
|
|
572
|
+
link: Link,
|
|
573
|
+
name: string,
|
|
574
|
+
open: Uint8Array,
|
|
575
|
+
values: Values<V>,
|
|
576
|
+
owners: (string | Uint8Array)[],
|
|
577
|
+
) {
|
|
578
|
+
this.#link = link
|
|
579
|
+
this.name = name
|
|
580
|
+
this.#open = open
|
|
581
|
+
this.#values = values
|
|
582
|
+
this.#owners = owners
|
|
583
|
+
}
|
|
584
|
+
|
|
585
|
+
/** The branch below this one that the owners name. */
|
|
586
|
+
of(...owners: Key[]): Bucket<V> {
|
|
587
|
+
return new Bucket(this.#link, this.name, this.#open, this.#values, [
|
|
588
|
+
...this.#owners,
|
|
589
|
+
...owners.map(ownerText),
|
|
590
|
+
])
|
|
591
|
+
}
|
|
592
|
+
|
|
593
|
+
/**
|
|
594
|
+
* The bucket's calls inside a batch or a view, whose promises settle with
|
|
595
|
+
* it, or inside a tx, whose reads answer at once and writes wait for it.
|
|
596
|
+
*/
|
|
597
|
+
withTx(tx: Batch | Tx): BucketTx<V> {
|
|
598
|
+
return new BucketTx(tx, this.#open, this.#values, this.#owners)
|
|
599
|
+
}
|
|
600
|
+
|
|
601
|
+
async #call(
|
|
602
|
+
method: keyof typeof methods,
|
|
603
|
+
fields: Omit<Parameters<typeof KvCall.encode>[0], 'handle' | 'owners'>,
|
|
604
|
+
idempotence: 'read' | 'write',
|
|
605
|
+
) {
|
|
606
|
+
return this.#link.run(idempotence, async (connection: Connection) => {
|
|
607
|
+
const handle = await handleOn(connection, methods['kv.open'], this.#open)
|
|
608
|
+
const body = KvCall.encode({
|
|
609
|
+
handle,
|
|
610
|
+
owners: this.#owners.length > 0 ? this.#owners : undefined,
|
|
611
|
+
...fields,
|
|
612
|
+
})
|
|
613
|
+
return KvEntry.decode(await connection.session.call(methods[method], body))
|
|
614
|
+
})
|
|
615
|
+
}
|
|
616
|
+
|
|
617
|
+
/** The key's value, undefined when it holds none. */
|
|
618
|
+
async get(key: Key): Promise<V | undefined> {
|
|
619
|
+
const entry = await this.getEntry(key)
|
|
620
|
+
return entry?.value
|
|
621
|
+
}
|
|
622
|
+
|
|
623
|
+
/** The key's value with its version and expiry, undefined when it holds none. */
|
|
624
|
+
async getEntry(key: Key): Promise<Entry<V> | undefined> {
|
|
625
|
+
const e = await this.#call('kv.get', { key }, 'read')
|
|
626
|
+
if (e.found !== true) {
|
|
627
|
+
return undefined
|
|
628
|
+
}
|
|
629
|
+
return {
|
|
630
|
+
value: await this.#values.decode(e.value ?? null),
|
|
631
|
+
version: versionText(e.version),
|
|
632
|
+
expires: dateOf(e.expires),
|
|
633
|
+
}
|
|
634
|
+
}
|
|
635
|
+
|
|
636
|
+
async has(key: Key): Promise<boolean> {
|
|
637
|
+
return (await this.#call('kv.has', { key }, 'read')).found === true
|
|
638
|
+
}
|
|
639
|
+
|
|
640
|
+
/** Writes the value; a live key keeps its expiry unless the options give one. */
|
|
641
|
+
async set(key: Key, value: V, options?: WriteOptions): Promise<void> {
|
|
642
|
+
await this.setEntry(key, value, options)
|
|
643
|
+
}
|
|
644
|
+
|
|
645
|
+
/** Writes the value and gives its new version and expiry. */
|
|
646
|
+
async setEntry(key: Key, value: V, options?: WriteOptions): Promise<Entry<V>> {
|
|
647
|
+
const raw = await this.#values.encode(value)
|
|
648
|
+
const e = await this.#call('kv.set', { key, value: raw, ...writeFields(options) }, 'write')
|
|
649
|
+
return { value, version: versionText(e.version), expires: dateOf(e.expires) }
|
|
650
|
+
}
|
|
651
|
+
|
|
652
|
+
/** Writes the value only where no live key is, and says whether it did. */
|
|
653
|
+
async setIfAbsent(
|
|
654
|
+
key: Key,
|
|
655
|
+
value: V,
|
|
656
|
+
options?: Omit<WriteOptions, 'ifVersion'>,
|
|
657
|
+
): Promise<boolean> {
|
|
658
|
+
return (await this.setEntryIfAbsent(key, value, options)).created
|
|
659
|
+
}
|
|
660
|
+
|
|
661
|
+
/**
|
|
662
|
+
* Writes the value only where no live key is: created says whether it did,
|
|
663
|
+
* and entry is the new key's, or the live one's that was there.
|
|
664
|
+
*/
|
|
665
|
+
async setEntryIfAbsent(
|
|
666
|
+
key: Key,
|
|
667
|
+
value: V,
|
|
668
|
+
options?: Omit<WriteOptions, 'ifVersion'>,
|
|
669
|
+
): Promise<{ created: boolean; entry: Entry<V> }> {
|
|
670
|
+
const raw = await this.#values.encode(value)
|
|
671
|
+
const e = await this.#call(
|
|
672
|
+
'kv.set',
|
|
673
|
+
{ key, value: raw, ifAbsent: true, ...writeFields(options) },
|
|
674
|
+
'write',
|
|
675
|
+
)
|
|
676
|
+
const created = e.found === true
|
|
677
|
+
return {
|
|
678
|
+
created,
|
|
679
|
+
entry: {
|
|
680
|
+
value: created ? value : await this.#values.decode(e.value ?? null),
|
|
681
|
+
version: versionText(e.version),
|
|
682
|
+
expires: dateOf(e.expires),
|
|
683
|
+
},
|
|
684
|
+
}
|
|
685
|
+
}
|
|
686
|
+
|
|
687
|
+
async delete(key: Key, options?: Pick<WriteOptions, 'ifVersion'>): Promise<void> {
|
|
688
|
+
await this.#call('kv.delete', { key, ...writeFields(options) }, 'write')
|
|
689
|
+
}
|
|
690
|
+
|
|
691
|
+
/**
|
|
692
|
+
* Reads the value and deletes the key in one write: a one-time code read
|
|
693
|
+
* and burned. A value that no longer decodes has been taken all the same.
|
|
694
|
+
*/
|
|
695
|
+
async take(key: Key, options?: Pick<WriteOptions, 'ifVersion'>): Promise<V | undefined> {
|
|
696
|
+
const e = await this.#call('kv.take', { key, ...writeFields(options) }, 'write')
|
|
697
|
+
return e.found === true ? this.#values.decode(e.value ?? null) : undefined
|
|
698
|
+
}
|
|
699
|
+
|
|
700
|
+
/** Gives a live key a new expiry, keeping its value and version; false when it holds none. */
|
|
701
|
+
async touch(key: Key, options: WriteOptions): Promise<boolean> {
|
|
702
|
+
return (await this.#call('kv.touch', { key, ...writeFields(options) }, 'write')).found === true
|
|
703
|
+
}
|
|
704
|
+
|
|
705
|
+
/** Removes this branch's keys and every branch under it, at once however many. */
|
|
706
|
+
async clear(): Promise<void> {
|
|
707
|
+
await this.#call('kv.clear', {}, 'write')
|
|
708
|
+
}
|
|
709
|
+
|
|
710
|
+
/** One page of this branch's own keys, in the byte order of their text. */
|
|
711
|
+
async scan(options?: {
|
|
712
|
+
after?: Key
|
|
713
|
+
limit?: number
|
|
714
|
+
}): Promise<Page<Scanned<V>, string | Uint8Array>> {
|
|
715
|
+
const { items, page } = await this.#link.run('read', async connection => {
|
|
716
|
+
const handle = await handleOn(connection, methods['kv.open'], this.#open)
|
|
717
|
+
const stream = await connection.session.open(
|
|
718
|
+
methods['kv.scan'],
|
|
719
|
+
KvCall.encode({
|
|
720
|
+
handle,
|
|
721
|
+
owners: this.#owners.length > 0 ? this.#owners : undefined,
|
|
722
|
+
after: options?.after,
|
|
723
|
+
limit: options?.limit,
|
|
724
|
+
}),
|
|
725
|
+
true,
|
|
726
|
+
)
|
|
727
|
+
const items: ReturnType<typeof KvEntry.decode>[] = []
|
|
728
|
+
for (;;) {
|
|
729
|
+
const event = await stream.next()
|
|
730
|
+
if (event.kind === 'response') {
|
|
731
|
+
continue
|
|
732
|
+
}
|
|
733
|
+
stream.consumed(event.body.length)
|
|
734
|
+
if (event.end) {
|
|
735
|
+
return { items, page: KvPage.decode(event.body) }
|
|
736
|
+
}
|
|
737
|
+
items.push(KvEntry.decode(event.body))
|
|
738
|
+
}
|
|
739
|
+
})
|
|
740
|
+
const decoded: Scanned<V>[] = []
|
|
741
|
+
for (const e of items) {
|
|
742
|
+
decoded.push({
|
|
743
|
+
key: e.key ?? '',
|
|
744
|
+
value: await this.#values.decode(e.value ?? null),
|
|
745
|
+
version: versionText(e.version),
|
|
746
|
+
expires: dateOf(e.expires),
|
|
747
|
+
})
|
|
748
|
+
}
|
|
749
|
+
return { items: decoded, next: page.more === true ? (page.after ?? '') : undefined }
|
|
750
|
+
}
|
|
751
|
+
|
|
752
|
+
/**
|
|
753
|
+
* Walks this branch's own keys a page at a time, holding no snapshot
|
|
754
|
+
* between pages: a key written during the walk may or may not be met.
|
|
755
|
+
*/
|
|
756
|
+
async *all(options?: { limit?: number }): AsyncGenerator<Scanned<V>> {
|
|
757
|
+
let after: Key | undefined
|
|
758
|
+
for (;;) {
|
|
759
|
+
const page = await this.scan({ ...(after === undefined ? {} : { after }), ...options })
|
|
760
|
+
yield* page.items
|
|
761
|
+
if (page.next === undefined) {
|
|
762
|
+
return
|
|
763
|
+
}
|
|
764
|
+
after = page.next
|
|
765
|
+
}
|
|
766
|
+
}
|
|
767
|
+
}
|
|
768
|
+
|
|
769
|
+
/** A bucket's calls inside a batch or a view. */
|
|
770
|
+
export class BucketTx<V> {
|
|
771
|
+
readonly #tx: Recorder
|
|
772
|
+
readonly #open: Uint8Array
|
|
773
|
+
readonly #values: Values<V>
|
|
774
|
+
readonly #owners: (string | Uint8Array)[]
|
|
775
|
+
|
|
776
|
+
constructor(tx: Recorder, open: Uint8Array, values: Values<V>, owners: (string | Uint8Array)[]) {
|
|
777
|
+
this.#tx = tx
|
|
778
|
+
this.#open = open
|
|
779
|
+
this.#values = values
|
|
780
|
+
this.#owners = owners
|
|
781
|
+
}
|
|
782
|
+
|
|
783
|
+
of(...owners: Key[]): BucketTx<V> {
|
|
784
|
+
return new BucketTx(this.#tx, this.#open, this.#values, [
|
|
785
|
+
...this.#owners,
|
|
786
|
+
...owners.map(ownerText),
|
|
787
|
+
])
|
|
788
|
+
}
|
|
789
|
+
|
|
790
|
+
#record<T>(
|
|
791
|
+
method: Recorded['method'],
|
|
792
|
+
fields: Omit<Parameters<typeof KvCall.encode>[0], 'handle' | 'owners'>,
|
|
793
|
+
settle: (e: Entry<Raw> & { found: boolean }) => Promise<T>,
|
|
794
|
+
): Promise<T> {
|
|
795
|
+
const owners = this.#owners.length > 0 ? this.#owners : undefined
|
|
796
|
+
return this.#tx.record({ method, open: this.#open, call: { owners, ...fields } }, settle)
|
|
797
|
+
}
|
|
798
|
+
|
|
799
|
+
get(key: Key): Promise<V | undefined> {
|
|
800
|
+
return this.#record('kv.get', { key }, async e =>
|
|
801
|
+
e.found ? this.#values.decode(e.value) : undefined,
|
|
802
|
+
)
|
|
803
|
+
}
|
|
804
|
+
|
|
805
|
+
has(key: Key): Promise<boolean> {
|
|
806
|
+
return this.#record('kv.has', { key }, async e => e.found)
|
|
807
|
+
}
|
|
808
|
+
|
|
809
|
+
set(key: Key, value: V, options?: WriteOptions): Promise<void> {
|
|
810
|
+
return this.#record(
|
|
811
|
+
'kv.set',
|
|
812
|
+
{ key, value: this.#encodeNow(value), ...writeFields(options) },
|
|
813
|
+
async () => {},
|
|
814
|
+
)
|
|
815
|
+
}
|
|
816
|
+
|
|
817
|
+
delete(key: Key, options?: Pick<WriteOptions, 'ifVersion'>): Promise<void> {
|
|
818
|
+
return this.#record('kv.delete', { key, ...writeFields(options) }, async () => {})
|
|
819
|
+
}
|
|
820
|
+
|
|
821
|
+
take(key: Key): Promise<V | undefined> {
|
|
822
|
+
return this.#record('kv.take', { key }, async e =>
|
|
823
|
+
e.found ? this.#values.decode(e.value) : undefined,
|
|
824
|
+
)
|
|
825
|
+
}
|
|
826
|
+
|
|
827
|
+
// a batch is sent once its function returns, so a value is encoded as it is given
|
|
828
|
+
#encodeNow(value: V): Raw {
|
|
829
|
+
const raw = this.#values.encode(value)
|
|
830
|
+
if (raw instanceof Promise) {
|
|
831
|
+
throw new InvalidError('a bucket whose values encode asynchronously takes no batch')
|
|
832
|
+
}
|
|
833
|
+
return raw
|
|
834
|
+
}
|
|
835
|
+
}
|
|
836
|
+
|
|
837
|
+
/**
|
|
838
|
+
* Counters under one branch: an int64 a key, 0 when absent, which add and
|
|
839
|
+
* max change in one write; a sum past the int64 range is refused.
|
|
840
|
+
*/
|
|
841
|
+
export class Counters<N extends number | bigint> {
|
|
842
|
+
readonly name: string
|
|
843
|
+
readonly #link: Link
|
|
844
|
+
readonly #open: Uint8Array
|
|
845
|
+
readonly #big: boolean
|
|
846
|
+
readonly #owners: (string | Uint8Array)[]
|
|
847
|
+
|
|
848
|
+
constructor(
|
|
849
|
+
link: Link,
|
|
850
|
+
name: string,
|
|
851
|
+
open: Uint8Array,
|
|
852
|
+
big: boolean,
|
|
853
|
+
owners: (string | Uint8Array)[],
|
|
854
|
+
) {
|
|
855
|
+
this.#link = link
|
|
856
|
+
this.name = name
|
|
857
|
+
this.#open = open
|
|
858
|
+
this.#big = big
|
|
859
|
+
this.#owners = owners
|
|
860
|
+
}
|
|
861
|
+
|
|
862
|
+
of(...owners: Key[]): Counters<N> {
|
|
863
|
+
return new Counters(this.#link, this.name, this.#open, this.#big, [
|
|
864
|
+
...this.#owners,
|
|
865
|
+
...owners.map(ownerText),
|
|
866
|
+
])
|
|
867
|
+
}
|
|
868
|
+
|
|
869
|
+
async #call(method: keyof typeof methods, key: Key | undefined, n?: number | bigint): Promise<N> {
|
|
870
|
+
const e = await this.#link.run(method === 'kv.get' ? 'read' : 'write', async connection => {
|
|
871
|
+
const handle = await handleOn(connection, methods['kv.open'], this.#open)
|
|
872
|
+
const body = KvCall.encode({
|
|
873
|
+
handle,
|
|
874
|
+
owners: this.#owners.length > 0 ? this.#owners : undefined,
|
|
875
|
+
key,
|
|
876
|
+
n,
|
|
877
|
+
})
|
|
878
|
+
return KvEntry.decode(await connection.session.call(methods[method], body))
|
|
879
|
+
})
|
|
880
|
+
const value = typeof e.value === 'bigint' ? e.value : 0n
|
|
881
|
+
return (this.#big ? value : numberOf(value, this.name)) as N
|
|
882
|
+
}
|
|
883
|
+
|
|
884
|
+
get(key: Key): Promise<N> {
|
|
885
|
+
return this.#call('kv.get', key)
|
|
886
|
+
}
|
|
887
|
+
|
|
888
|
+
/** Adds n, 1 unless given, and gives the new value. */
|
|
889
|
+
add(key: Key, n: number | bigint = 1): Promise<N> {
|
|
890
|
+
return this.#call('kv.add', key, n)
|
|
891
|
+
}
|
|
892
|
+
|
|
893
|
+
/** Keeps the larger of the counter and n, and gives it. */
|
|
894
|
+
max(key: Key, n: number | bigint): Promise<N> {
|
|
895
|
+
return this.#call('kv.max', key, n)
|
|
896
|
+
}
|
|
897
|
+
|
|
898
|
+
async delete(key: Key): Promise<void> {
|
|
899
|
+
await this.#call('kv.delete', key)
|
|
900
|
+
}
|
|
901
|
+
|
|
902
|
+
async clear(): Promise<void> {
|
|
903
|
+
await this.#call('kv.clear', undefined)
|
|
904
|
+
}
|
|
905
|
+
}
|
|
906
|
+
|
|
907
|
+
function numberOf(n: bigint, bucket: string): number {
|
|
908
|
+
if (n > BigInt(Number.MAX_SAFE_INTEGER) || n < BigInt(Number.MIN_SAFE_INTEGER)) {
|
|
909
|
+
throw new CorruptError(
|
|
910
|
+
`${n} does not fit a number exactly: open counters ${bucket} as 'bigint'`,
|
|
911
|
+
{ bucket },
|
|
912
|
+
)
|
|
913
|
+
}
|
|
914
|
+
return Number(n)
|
|
915
|
+
}
|
|
916
|
+
|
|
917
|
+
const utf8 = new TextEncoder()
|
|
918
|
+
|
|
919
|
+
const jsonValues: Values<unknown> = {
|
|
920
|
+
encode: value => {
|
|
921
|
+
let text: string | undefined
|
|
922
|
+
try {
|
|
923
|
+
text = JSON.stringify(value)
|
|
924
|
+
} catch (err) {
|
|
925
|
+
throw new InvalidError(`a value JSON cannot write: ${(err as Error).message}`)
|
|
926
|
+
}
|
|
927
|
+
if (text === undefined) {
|
|
928
|
+
throw new InvalidError('a value JSON cannot write: undefined, a function or a symbol')
|
|
929
|
+
}
|
|
930
|
+
return utf8.encode(text)
|
|
931
|
+
},
|
|
932
|
+
decode: raw => {
|
|
933
|
+
if (!(raw instanceof Uint8Array)) {
|
|
934
|
+
throw new CorruptError(`a stored value is ${describe(raw)} where JSON was written`)
|
|
935
|
+
}
|
|
936
|
+
const text = textOf(raw)
|
|
937
|
+
try {
|
|
938
|
+
return JSON.parse(text ?? '')
|
|
939
|
+
} catch (err) {
|
|
940
|
+
throw new CorruptError(`a stored value is not JSON any more: ${(err as Error).message}`)
|
|
941
|
+
}
|
|
942
|
+
},
|
|
943
|
+
}
|
|
944
|
+
|
|
945
|
+
function schemaValues<S extends StandardSchemaV1>(schema: S): Values<unknown> {
|
|
946
|
+
return {
|
|
947
|
+
encode: jsonValues.encode,
|
|
948
|
+
decode: async raw => {
|
|
949
|
+
const checked = await check(schema, await jsonValues.decode(raw))
|
|
950
|
+
if ('issues' in checked) {
|
|
951
|
+
throw new CorruptError(
|
|
952
|
+
`a stored value does not meet the bucket's schema: ${checked.issues}`,
|
|
953
|
+
)
|
|
954
|
+
}
|
|
955
|
+
return checked.value
|
|
956
|
+
},
|
|
957
|
+
}
|
|
958
|
+
}
|
|
959
|
+
|
|
960
|
+
function valuesOf(kind: Kind): Values<unknown> {
|
|
961
|
+
switch (kind) {
|
|
962
|
+
case 'json':
|
|
963
|
+
return jsonValues
|
|
964
|
+
case 'string':
|
|
965
|
+
return {
|
|
966
|
+
encode: v => {
|
|
967
|
+
if (typeof v !== 'string') {
|
|
968
|
+
throw new InvalidError(`a ${typeof v} in a bucket of strings`)
|
|
969
|
+
}
|
|
970
|
+
return utf8.encode(v)
|
|
971
|
+
},
|
|
972
|
+
decode: raw => {
|
|
973
|
+
const text = raw === null ? '' : raw instanceof Uint8Array ? textOf(raw) : undefined
|
|
974
|
+
if (text === undefined) {
|
|
975
|
+
throw new CorruptError(`a stored value is ${describe(raw)}, which is no UTF-8 string`)
|
|
976
|
+
}
|
|
977
|
+
return text
|
|
978
|
+
},
|
|
979
|
+
}
|
|
980
|
+
case 'bytes':
|
|
981
|
+
return {
|
|
982
|
+
encode: v => {
|
|
983
|
+
if (!(v instanceof Uint8Array)) {
|
|
984
|
+
throw new InvalidError(`a ${typeof v} in a bucket of bytes`)
|
|
985
|
+
}
|
|
986
|
+
return v
|
|
987
|
+
},
|
|
988
|
+
decode: raw => {
|
|
989
|
+
if (raw !== null && !(raw instanceof Uint8Array)) {
|
|
990
|
+
throw new CorruptError(`a stored value is ${describe(raw)} where bytes were written`)
|
|
991
|
+
}
|
|
992
|
+
return raw ?? new Uint8Array(0)
|
|
993
|
+
},
|
|
994
|
+
}
|
|
995
|
+
case 'int':
|
|
996
|
+
return {
|
|
997
|
+
encode: v => {
|
|
998
|
+
if (typeof v !== 'number' || !Number.isSafeInteger(v)) {
|
|
999
|
+
throw new InvalidError(
|
|
1000
|
+
`${String(v)} is not an integer a number holds exactly; open the bucket as 'bigint'`,
|
|
1001
|
+
)
|
|
1002
|
+
}
|
|
1003
|
+
return BigInt(v)
|
|
1004
|
+
},
|
|
1005
|
+
decode: raw => {
|
|
1006
|
+
if (typeof raw !== 'bigint') {
|
|
1007
|
+
throw new CorruptError(
|
|
1008
|
+
`a stored value is ${describe(raw)} where an integer was written`,
|
|
1009
|
+
)
|
|
1010
|
+
}
|
|
1011
|
+
if (raw > BigInt(Number.MAX_SAFE_INTEGER) || raw < BigInt(Number.MIN_SAFE_INTEGER)) {
|
|
1012
|
+
throw new CorruptError(
|
|
1013
|
+
`${raw} does not fit a number exactly; open the bucket as 'bigint'`,
|
|
1014
|
+
)
|
|
1015
|
+
}
|
|
1016
|
+
return Number(raw)
|
|
1017
|
+
},
|
|
1018
|
+
}
|
|
1019
|
+
case 'bigint':
|
|
1020
|
+
return {
|
|
1021
|
+
encode: v => {
|
|
1022
|
+
if (typeof v !== 'bigint' && !(typeof v === 'number' && Number.isSafeInteger(v))) {
|
|
1023
|
+
throw new InvalidError(`${String(v)} is not an integer`)
|
|
1024
|
+
}
|
|
1025
|
+
return BigInt(v)
|
|
1026
|
+
},
|
|
1027
|
+
decode: raw => {
|
|
1028
|
+
if (typeof raw !== 'bigint') {
|
|
1029
|
+
throw new CorruptError(
|
|
1030
|
+
`a stored value is ${describe(raw)} where an integer was written`,
|
|
1031
|
+
)
|
|
1032
|
+
}
|
|
1033
|
+
return raw
|
|
1034
|
+
},
|
|
1035
|
+
}
|
|
1036
|
+
case 'float':
|
|
1037
|
+
return {
|
|
1038
|
+
encode: v => {
|
|
1039
|
+
if (typeof v !== 'number') {
|
|
1040
|
+
throw new InvalidError(`a ${typeof v} in a bucket of floats`)
|
|
1041
|
+
}
|
|
1042
|
+
const bytes = new Uint8Array(8)
|
|
1043
|
+
new DataView(bytes.buffer).setFloat64(0, v)
|
|
1044
|
+
return bytes
|
|
1045
|
+
},
|
|
1046
|
+
decode: raw => {
|
|
1047
|
+
if (!(raw instanceof Uint8Array) || raw.length !== 8) {
|
|
1048
|
+
throw new CorruptError(
|
|
1049
|
+
`a stored value is ${describe(raw)} where a float's eight bytes were written`,
|
|
1050
|
+
)
|
|
1051
|
+
}
|
|
1052
|
+
return new DataView(raw.buffer, raw.byteOffset, 8).getFloat64(0)
|
|
1053
|
+
},
|
|
1054
|
+
}
|
|
1055
|
+
case 'bool':
|
|
1056
|
+
return {
|
|
1057
|
+
encode: v => {
|
|
1058
|
+
if (typeof v !== 'boolean') {
|
|
1059
|
+
throw new InvalidError(`a ${typeof v} in a bucket of booleans`)
|
|
1060
|
+
}
|
|
1061
|
+
return v ? 1n : 0n
|
|
1062
|
+
},
|
|
1063
|
+
decode: raw => {
|
|
1064
|
+
if (typeof raw !== 'bigint') {
|
|
1065
|
+
throw new CorruptError(`a stored value is ${describe(raw)} where a boolean was written`)
|
|
1066
|
+
}
|
|
1067
|
+
return raw !== 0n
|
|
1068
|
+
},
|
|
1069
|
+
}
|
|
1070
|
+
case 'none':
|
|
1071
|
+
return {
|
|
1072
|
+
encode: v => {
|
|
1073
|
+
if (v !== null) {
|
|
1074
|
+
throw new InvalidError('a bucket of none keeps no value: set null')
|
|
1075
|
+
}
|
|
1076
|
+
return null
|
|
1077
|
+
},
|
|
1078
|
+
decode: raw => {
|
|
1079
|
+
if (raw !== null) {
|
|
1080
|
+
throw new CorruptError(`a stored value is ${describe(raw)} in a bucket that keeps none`)
|
|
1081
|
+
}
|
|
1082
|
+
return null
|
|
1083
|
+
},
|
|
1084
|
+
}
|
|
1085
|
+
}
|
|
1086
|
+
}
|
|
1087
|
+
|
|
1088
|
+
function describe(raw: Raw): string {
|
|
1089
|
+
if (raw === null) {
|
|
1090
|
+
return 'nothing'
|
|
1091
|
+
}
|
|
1092
|
+
return typeof raw === 'bigint' ? 'an integer' : `${raw.length} bytes`
|
|
1093
|
+
}
|