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