@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.
Files changed (122) hide show
  1. package/README.md +37 -37
  2. package/bin/tinystore.js +12 -1
  3. package/dist/backup.d.ts +33 -0
  4. package/dist/backup.js +49 -0
  5. package/dist/blobs.d.ts +160 -79
  6. package/dist/blobs.js +510 -217
  7. package/dist/channels.d.ts +90 -0
  8. package/dist/channels.js +291 -0
  9. package/dist/clock.js +3 -3
  10. package/dist/config.d.ts +209 -86
  11. package/dist/config.js +581 -538
  12. package/dist/connection.d.ts +64 -2
  13. package/dist/connection.js +201 -16
  14. package/dist/console.d.ts +27 -3
  15. package/dist/console.js +165 -12
  16. package/dist/dotenv.d.ts +7 -0
  17. package/dist/dotenv.js +79 -0
  18. package/dist/errors.d.ts +61 -1
  19. package/dist/errors.js +81 -1
  20. package/dist/handles.d.ts +44 -2
  21. package/dist/handles.js +81 -2
  22. package/dist/index.d.ts +17 -11
  23. package/dist/index.js +5 -3
  24. package/dist/instruments.d.ts +177 -0
  25. package/dist/instruments.js +819 -0
  26. package/dist/jobs.d.ts +335 -239
  27. package/dist/jobs.js +716 -536
  28. package/dist/json.d.ts +2 -0
  29. package/dist/json.js +122 -0
  30. package/dist/kv.d.ts +130 -243
  31. package/dist/kv.js +273 -640
  32. package/dist/limits.d.ts +80 -0
  33. package/dist/limits.js +139 -0
  34. package/dist/locks.d.ts +62 -0
  35. package/dist/locks.js +237 -0
  36. package/dist/logger.d.ts +45 -9
  37. package/dist/logger.js +150 -38
  38. package/dist/metrics.d.ts +210 -209
  39. package/dist/metrics.js +319 -556
  40. package/dist/once.d.ts +19 -18
  41. package/dist/once.js +74 -63
  42. package/dist/query.d.ts +181 -0
  43. package/dist/query.js +788 -0
  44. package/dist/records.d.ts +241 -150
  45. package/dist/records.js +507 -291
  46. package/dist/runtime/addon.d.ts +14 -0
  47. package/dist/runtime/addon.js +69 -0
  48. package/dist/runtime/bun.js +5 -7
  49. package/dist/runtime/node.js +5 -7
  50. package/dist/runtime/pipe.d.ts +17 -0
  51. package/dist/runtime/pipe.js +133 -0
  52. package/dist/runtime/shared.d.ts +6 -0
  53. package/dist/runtime/shared.js +19 -0
  54. package/dist/runtime.d.ts +5 -2
  55. package/dist/search.d.ts +189 -0
  56. package/dist/search.js +281 -0
  57. package/dist/session.d.ts +31 -3
  58. package/dist/session.js +153 -41
  59. package/dist/sql.d.ts +228 -78
  60. package/dist/sql.js +745 -240
  61. package/dist/store.d.ts +244 -24
  62. package/dist/store.js +270 -67
  63. package/dist/time.d.ts +5 -1
  64. package/dist/time.js +22 -2
  65. package/dist/tx.d.ts +61 -0
  66. package/dist/tx.js +314 -0
  67. package/dist/wire/codec.d.ts +23 -7
  68. package/dist/wire/codec.js +56 -35
  69. package/dist/wire/frame.d.ts +2 -0
  70. package/dist/wire/frame.js +31 -14
  71. package/dist/wire/messages.d.ts +259 -0
  72. package/dist/wire/messages.js +22 -0
  73. package/dist/wire/msgpack.d.ts +49 -1
  74. package/dist/wire/msgpack.js +293 -56
  75. package/dist/wire/protocol.d.ts +2683 -0
  76. package/dist/wire/protocol.js +10846 -0
  77. package/package.json +39 -38
  78. package/src/backup.ts +81 -0
  79. package/src/blobs.ts +678 -301
  80. package/src/channels.ts +377 -0
  81. package/src/clock.ts +4 -4
  82. package/src/config.ts +902 -612
  83. package/src/connection.ts +279 -21
  84. package/src/console.ts +180 -12
  85. package/src/dotenv.ts +82 -0
  86. package/src/errors.ts +105 -0
  87. package/src/handles.ts +157 -8
  88. package/src/index.ts +158 -52
  89. package/src/instruments.ts +1042 -0
  90. package/src/jobs.ts +1017 -733
  91. package/src/json.ts +133 -0
  92. package/src/kv.ts +424 -847
  93. package/src/limits.ts +202 -0
  94. package/src/locks.ts +320 -0
  95. package/src/logger.ts +209 -40
  96. package/src/metrics.ts +557 -752
  97. package/src/once.ts +86 -83
  98. package/src/query.ts +1005 -0
  99. package/src/records.ts +795 -418
  100. package/src/runtime/addon.ts +99 -0
  101. package/src/runtime/bun.ts +5 -7
  102. package/src/runtime/node.ts +5 -7
  103. package/src/runtime/pipe.ts +178 -0
  104. package/src/runtime/shared.ts +20 -0
  105. package/src/runtime.ts +5 -2
  106. package/src/search.ts +480 -0
  107. package/src/session.ts +187 -41
  108. package/src/sql.ts +993 -306
  109. package/src/store.ts +473 -78
  110. package/src/time.ts +48 -3
  111. package/src/tx.ts +426 -0
  112. package/src/wire/codec.ts +78 -37
  113. package/src/wire/frame.ts +44 -14
  114. package/src/wire/messages.ts +25 -0
  115. package/src/wire/msgpack.ts +327 -56
  116. package/src/wire/protocol.ts +11709 -0
  117. package/dist/limiter.d.ts +0 -45
  118. package/dist/limiter.js +0 -68
  119. package/dist/quota.d.ts +0 -44
  120. package/dist/quota.js +0 -98
  121. package/src/limiter.ts +0 -99
  122. package/src/quota.ts +0 -137
package/src/kv.ts CHANGED
@@ -1,926 +1,532 @@
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 ConfigLayer, type ConfigValue } 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'
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 { KvBucket, KvCall, KvCalls, KvEntry, KvPage, KvResults, methods } from './wire/messages.ts'
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 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:
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
- * '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
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 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
- }
46
+ export type ValueType = 'string' | 'bytes' | 'int' | 'bigint' | 'float' | 'bool'
42
47
 
43
48
  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
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
- * keeps changes in the server's memory between flushes this far apart, so
54
- * a crash may lose them: attempts and rates, not money
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
- loseAtMost?: Duration
62
+ encrypted?: boolean | undefined
57
63
  }
58
64
 
59
65
  export interface WriteOptions {
60
- ttl?: Duration
61
- expireAt?: Time
62
- /** writes only while the key is live at this version: ConflictError otherwise */
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<V> {
67
- value: V
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
- /** when the key expires; undefined for one that never does */
71
- expires: Date | undefined
79
+ /** undefined for a key that never expires */
80
+ expiresAt: Date | undefined
72
81
  }
73
82
 
74
- export interface Scanned<V> extends Entry<V> {
75
- /** the key's text; bytes when it is not UTF-8 */
76
- key: string | Uint8Array
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
- /** 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 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
- * Runs fn as one transaction that reads before it decides what to write,
256
- * as Go's Tx does, without holding the writer across the network: a read
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
- async tx<T>(fn: (tx: Tx) => T | Promise<T>): Promise<T> {
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
- interface Recorded {
346
- method: keyof typeof methods
347
- open: Uint8Array
348
- call: Parameters<typeof KvCall.encode>[0]
349
- settle: (entry: Entry<Raw> & { found: boolean }) => Promise<void>
350
- fail?: (err: unknown) => void
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 bucket's calls inside a batch, a view or a tx go through. */
354
- interface Recorder {
355
- record<T>(
356
- call: Omit<Recorded, 'settle'>,
357
- settle: (entry: Entry<Raw> & { found: boolean }) => Promise<T>,
358
- ): Promise<T>
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
- type Found = Entry<Raw> & { found: boolean }
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
- /** A key a tx read: the call that read it, and what it found, which its commit checks. */
364
- interface Read {
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
- const absent: Found = { found: false, value: null, version: '', expires: undefined }
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 #reads = new Map<string, Promise<Read>>()
380
- readonly #writes = new Map<string, { call: Omit<Recorded, 'settle'>; entry: Found }>()
381
- #checks = 0
382
- #done = false
383
-
384
- constructor(link: Link) {
385
- this.#link = link
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
- * Sends what fn wrote in one batch, after a check of each key it read: a
450
- * key it found at the version it found, a key it found absent still
451
- * absent. A tx that only read checks its reads from one snapshot.
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: Uint8Array,
579
- values: Values<V>,
580
- owners: (string | Uint8Array)[],
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.#owners = owners
587
- }
588
-
589
- /** The branch below this one that the owners name. */
590
- of(...owners: Key[]): Bucket<V> {
591
- return new Bucket(this.#link, this.name, this.#open, this.#values, [
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
- async #call(
606
- method: keyof typeof methods,
607
- fields: Omit<Parameters<typeof KvCall.encode>[0], 'handle' | 'owners'>,
608
- idempotence: 'read' | 'write',
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
- async get(key: Key): Promise<V | undefined> {
623
- const entry = await this.getEntry(key)
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
- async getEntry(key: Key): Promise<Entry<V> | undefined> {
629
- const e = await this.#call('kv.get', { key }, 'read')
630
- if (e.found !== true) {
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
- async has(key: Key): Promise<boolean> {
641
- return (await this.#call('kv.has', { key }, 'read')).found === true
182
+ has(key: Key): Promise<boolean> {
183
+ return this.#ask('kv.has', { key }, 'read', found)
642
184
  }
643
185
 
644
- /** Writes the value; a live key keeps its expiry unless the options give one. */
645
- async set(key: Key, value: V, options?: WriteOptions): Promise<void> {
646
- await this.setEntry(key, value, options)
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 and gives its new version and expiry. */
650
- async setEntry(key: Key, value: V, options?: WriteOptions): Promise<Entry<V>> {
651
- const raw = await this.#values.encode(value)
652
- const e = await this.#call('kv.set', { key, value: raw, ...writeFields(options) }, 'write')
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
- /** Writes the value only where no live key is, and says whether it did. */
657
- async setIfAbsent(
658
- key: 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
- * Writes the value only where no live key is: created says whether it did,
667
- * and entry is the new key's, or the live one's that was there.
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 setEntryIfAbsent(
670
- key: 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
- async delete(key: Key, options?: Pick<WriteOptions, 'ifVersion'>): Promise<void> {
692
- await this.#call('kv.delete', { key, ...writeFields(options) }, 'write')
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
- * Reads the value and deletes the key in one write: a one-time code read
697
- * and burned. A value that no longer decodes has been taken all the same.
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 take(key: Key, options?: Pick<WriteOptions, 'ifVersion'>): Promise<V | undefined> {
700
- const e = await this.#call('kv.take', { key, ...writeFields(options) }, 'write')
701
- return e.found === true ? this.#values.decode(e.value ?? null) : undefined
702
- }
703
-
704
- /** Gives a live key a new expiry, keeping its value and version; false when it holds none. */
705
- async touch(key: Key, options: WriteOptions): Promise<boolean> {
706
- return (await this.#call('kv.touch', { key, ...writeFields(options) }, 'write')).found === true
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
- await this.#call('kv.clear', {}, 'write')
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 scan(options?: {
716
- after?: Key
717
- limit?: number
718
- }): Promise<Page<Scanned<V>, string | Uint8Array>> {
719
- const { items, page } = await this.#link.run('read', async connection => {
720
- const handle = await handleOn(connection, methods['kv.open'], this.#open)
721
- const stream = await connection.session.open(
722
- methods['kv.scan'],
723
- KvCall.encode({
724
- handle,
725
- owners: this.#owners.length > 0 ? this.#owners : undefined,
726
- after: options?.after,
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 no snapshot
758
- * between pages: a key written during the walk may or may not be met.
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<Scanned<V>> {
761
- let after: Key | undefined
262
+ async *all(options?: { limit?: number | undefined }): AsyncGenerator<Entry<T>> {
263
+ let after: string | undefined
762
264
  for (;;) {
763
- const page = await this.scan({ ...(after === undefined ? {} : { after }), ...options })
764
- yield* page.items
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
- /** A bucket's calls inside a batch or a view. */
774
- export class BucketTx<V> {
775
- readonly #tx: Recorder
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 #values: Values<V>
778
- readonly #owners: (string | Uint8Array)[]
333
+ readonly #under: readonly string[]
779
334
 
780
- constructor(tx: Recorder, open: Uint8Array, values: Values<V>, owners: (string | Uint8Array)[]) {
781
- this.#tx = tx
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.#values = values
784
- this.#owners = owners
340
+ this.#under = under
341
+ parts.set(this, { link, name, open, openMethod: 'kv.counters.open', under })
785
342
  }
786
343
 
787
- of(...owners: Key[]): BucketTx<V> {
788
- return new BucketTx(this.#tx, this.#open, this.#values, [
789
- ...this.#owners,
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
- #record<T>(
795
- method: Recorded['method'],
796
- fields: Omit<Parameters<typeof KvCall.encode>[0], 'handle' | 'owners'>,
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<V | undefined> {
804
- return this.#record('kv.get', { key }, async e =>
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
- has(key: Key): Promise<boolean> {
810
- return this.#record('kv.has', { key }, async e => e.found)
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
- set(key: Key, value: V, options?: WriteOptions): Promise<void> {
814
- return this.#record(
815
- 'kv.set',
816
- { key, value: this.#encodeNow(value), ...writeFields(options) },
817
- async () => {},
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
- delete(key: Key, options?: Pick<WriteOptions, 'ifVersion'>): Promise<void> {
822
- return this.#record('kv.delete', { key, ...writeFields(options) }, async () => {})
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
- take(key: Key): Promise<V | undefined> {
826
- return this.#record('kv.take', { key }, async e =>
827
- e.found ? this.#values.decode(e.value) : undefined,
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
- * Counters under one branch: an int64 a key, 0 when absent, which add and
843
- * max change in one write; a sum past the int64 range is refused.
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 class Counters<N extends number | bigint> {
846
- readonly name: string
847
- readonly #link: Link
848
- readonly #open: Uint8Array
849
- readonly #big: boolean
850
- readonly #owners: (string | Uint8Array)[]
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
- constructor(
853
- link: Link,
854
- name: string,
855
- open: Uint8Array,
856
- big: boolean,
857
- owners: (string | Uint8Array)[],
858
- ) {
859
- this.#link = link
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
- of(...owners: Key[]): Counters<N> {
867
- return new Counters(this.#link, this.name, this.#open, this.#big, [
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
- async #call(method: keyof typeof methods, key: Key | undefined, n?: number | bigint): Promise<N> {
874
- const e = await this.#link.run(method === 'kv.get' ? 'read' : 'write', async connection => {
875
- const handle = await handleOn(connection, methods['kv.open'], this.#open)
876
- const body = KvCall.encode({
877
- handle,
878
- owners: this.#owners.length > 0 ? this.#owners : undefined,
879
- key,
880
- n,
881
- })
882
- return KvEntry.decode(await connection.session.call(methods[method], body))
883
- })
884
- const value = typeof e.value === 'bigint' ? e.value : 0n
885
- return (this.#big ? value : numberOf(value, this.name)) as N
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
- get(key: Key): Promise<N> {
889
- return this.#call('kv.get', key)
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
- /** Adds n, 1 unless given, and gives the new value. */
893
- add(key: Key, n: number | bigint = 1): Promise<N> {
894
- return this.#call('kv.add', key, n)
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
- /** Keeps the larger of the counter and n, and gives it. */
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
- async delete(key: Key): Promise<void> {
903
- await this.#call('kv.delete', key)
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
- async clear(): Promise<void> {
907
- await this.#call('kv.clear', undefined)
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, bucket: string): number {
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
- const jsonValues: Values<unknown> = {
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 (!(raw instanceof Uint8Array)) {
938
- throw new CorruptError(`a stored value is ${describe(raw)} where JSON was written`)
543
+ if (raw === null) {
544
+ return null
939
545
  }
940
- const text = textOf(raw)
546
+ const json = bodyOf(raw, kinds.json, 'JSON')
941
547
  try {
942
- return JSON.parse(text ?? '')
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 schemaValues<S extends StandardSchemaV1>(schema: S): Values<unknown> {
950
- return {
951
- encode: jsonValues.encode,
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
- const text = raw === null ? '' : raw instanceof Uint8Array ? textOf(raw) : undefined
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(`a stored value is ${describe(raw)}, which is no UTF-8 string`)
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 as 'bigint'`,
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 as 'bigint'`,
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
- if (!(raw instanceof Uint8Array) || raw.length !== 8) {
1052
- throw new CorruptError(
1053
- `a stored value is ${describe(raw)} where a float's eight bytes were written`,
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(raw.buffer, raw.byteOffset, 8).getFloat64(0)
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 {