@tinyshed/tinystore 0.4.1 → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/errors.d.ts +79 -20
- package/dist/errors.js +75 -20
- package/dist/index.d.ts +1 -1
- package/dist/kv.d.ts +15 -0
- package/dist/kv.js +149 -91
- package/dist/runtime/addon.js +51 -41
- package/dist/runtime/pipe.js +116 -87
- package/dist/search.d.ts +43 -3
- package/dist/search.js +38 -8
- package/dist/session.js +13 -3
- package/dist/wire/protocol.d.ts +110 -28
- package/dist/wire/protocol.js +247 -103
- package/package.json +8 -8
- package/src/errors.ts +83 -21
- package/src/index.ts +2 -0
- package/src/kv.ts +167 -99
- package/src/runtime/addon.ts +52 -41
- package/src/runtime/pipe.ts +136 -104
- package/src/search.ts +88 -11
- package/src/session.ts +18 -2
- package/src/wire/protocol.ts +258 -109
package/src/kv.ts
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
// its first call on a connection.
|
|
5
5
|
|
|
6
6
|
import type { Connection, Idempotence, Link } from './connection.ts'
|
|
7
|
-
import { CorruptError, InvalidError } from './errors.ts'
|
|
7
|
+
import { ConflictError, CorruptError, InvalidError } from './errors.ts'
|
|
8
8
|
import {
|
|
9
9
|
checkName,
|
|
10
10
|
type Home,
|
|
@@ -46,6 +46,9 @@ import {
|
|
|
46
46
|
*/
|
|
47
47
|
export type ValueType = 'string' | 'bytes' | 'int' | 'bigint' | 'float' | 'bool'
|
|
48
48
|
|
|
49
|
+
/** The tries an update makes while other writes come first, as many as a config's change makes. */
|
|
50
|
+
const updateAttempts = 8
|
|
51
|
+
|
|
49
52
|
export interface BucketOptions {
|
|
50
53
|
/** a key expires this long after it was written, unless its write gives its own */
|
|
51
54
|
ttl?: Duration | undefined
|
|
@@ -196,6 +199,40 @@ export class Bucket<T> {
|
|
|
196
199
|
return this.#ask('kv.create', { key, value: raw, ...writeFields(options) }, 'write', written)
|
|
197
200
|
}
|
|
198
201
|
|
|
202
|
+
/**
|
|
203
|
+
* Writes what `change` makes of the key's value without losing a write
|
|
204
|
+
* made meanwhile: it reads the key, calls `change` with its value, or
|
|
205
|
+
* undefined where it holds none, and writes what `change` returns at the
|
|
206
|
+
* version it read, or creates the key. When another write came first it
|
|
207
|
+
* reads again and calls `change` again, eight times at most, then throws
|
|
208
|
+
* ConflictError: `change` may run more than once, so it must do nothing
|
|
209
|
+
* else. A change that returns undefined, or the very value it was given,
|
|
210
|
+
* writes nothing. It returns the value written, or the one there when
|
|
211
|
+
* nothing was. A key that is there keeps its expiry, and one it creates
|
|
212
|
+
* takes the bucket's, as set and create do.
|
|
213
|
+
*
|
|
214
|
+
* await pinned.update(studentId, courses => [...(courses ?? []), 2518])
|
|
215
|
+
*/
|
|
216
|
+
async update(
|
|
217
|
+
key: Key,
|
|
218
|
+
change: (current: T | undefined) => T | undefined,
|
|
219
|
+
): Promise<T | undefined> {
|
|
220
|
+
for (let attempt = 0; attempt < updateAttempts; attempt++) {
|
|
221
|
+
const entry = await this.entry(key)
|
|
222
|
+
const next = change(entry?.value)
|
|
223
|
+
if (next === undefined || (entry !== undefined && next === entry.value)) {
|
|
224
|
+
return entry?.value
|
|
225
|
+
}
|
|
226
|
+
if (await this.#written(key, next, entry?.version)) {
|
|
227
|
+
return next
|
|
228
|
+
}
|
|
229
|
+
}
|
|
230
|
+
const shown = [this.#home?.describe, `kv bucket ${this.name}`, this.#shownKey(key)]
|
|
231
|
+
throw new ConflictError(
|
|
232
|
+
`${shown.filter(part => part !== undefined).join(': ')}: other writes came first each time it was tried`,
|
|
233
|
+
)
|
|
234
|
+
}
|
|
235
|
+
|
|
199
236
|
/** Puts the key in a bucket used as a set; false when it was there. */
|
|
200
237
|
async add(key: Key, options?: Omit<WriteOptions, 'ifVersion'>): Promise<boolean> {
|
|
201
238
|
return this.#ask('kv.create', { key, ...writeFields(options) }, 'write', written)
|
|
@@ -292,6 +329,27 @@ export class Bucket<T> {
|
|
|
292
329
|
}
|
|
293
330
|
}
|
|
294
331
|
|
|
332
|
+
// one try of an update: false when another write came first, at the key or creating it
|
|
333
|
+
async #written(key: Key, next: T, version: string | undefined): Promise<boolean> {
|
|
334
|
+
try {
|
|
335
|
+
if (version === undefined) {
|
|
336
|
+
return await this.create(key, next)
|
|
337
|
+
}
|
|
338
|
+
await this.set(key, next, { ifVersion: version })
|
|
339
|
+
return true
|
|
340
|
+
} catch (err) {
|
|
341
|
+
if (err instanceof ConflictError) {
|
|
342
|
+
return false
|
|
343
|
+
}
|
|
344
|
+
throw err
|
|
345
|
+
}
|
|
346
|
+
}
|
|
347
|
+
|
|
348
|
+
// the key as the core's errors show it, after its branch's owners
|
|
349
|
+
#shownKey(key: Key): string {
|
|
350
|
+
return `key ${JSON.stringify([...this.#under, keyText(key)].join('/'))}`
|
|
351
|
+
}
|
|
352
|
+
|
|
295
353
|
// a call on one key: its fields written where they leave from, its answer read where it arrived
|
|
296
354
|
#ask<A>(
|
|
297
355
|
method: Method,
|
|
@@ -573,114 +631,124 @@ export const jsonValues: Values<unknown> = {
|
|
|
573
631
|
},
|
|
574
632
|
}
|
|
575
633
|
|
|
634
|
+
/** A row of nothing reads as the empty string. */
|
|
635
|
+
const stringValues: Values<unknown> = {
|
|
636
|
+
encode: v => {
|
|
637
|
+
if (typeof v !== 'string') {
|
|
638
|
+
throw new InvalidError(`a ${typeof v} in a bucket of strings`)
|
|
639
|
+
}
|
|
640
|
+
return tagged(kinds.text, utf8.encode(v))
|
|
641
|
+
},
|
|
642
|
+
decode: raw => {
|
|
643
|
+
if (raw === null) {
|
|
644
|
+
return ''
|
|
645
|
+
}
|
|
646
|
+
const text = textOf(bodyOf(raw, kinds.text, 'text'))
|
|
647
|
+
if (text === undefined) {
|
|
648
|
+
throw new CorruptError('a stored value is text that is not UTF-8')
|
|
649
|
+
}
|
|
650
|
+
return text
|
|
651
|
+
},
|
|
652
|
+
}
|
|
653
|
+
|
|
654
|
+
/** A row of nothing reads as no bytes. */
|
|
655
|
+
const bytesValues: Values<unknown> = {
|
|
656
|
+
keeps: true,
|
|
657
|
+
encode: v => {
|
|
658
|
+
if (!(v instanceof Uint8Array)) {
|
|
659
|
+
throw new InvalidError(`a ${typeof v} in a bucket of bytes`)
|
|
660
|
+
}
|
|
661
|
+
return tagged(kinds.bytes, v)
|
|
662
|
+
},
|
|
663
|
+
decode: raw => (raw === null ? new Uint8Array(0) : bodyOf(raw, kinds.bytes, 'bytes')),
|
|
664
|
+
}
|
|
665
|
+
|
|
666
|
+
const intValues: Values<unknown> = {
|
|
667
|
+
encode: v => {
|
|
668
|
+
if (typeof v !== 'number' || !Number.isSafeInteger(v)) {
|
|
669
|
+
throw new InvalidError(
|
|
670
|
+
`${String(v)} is not an integer a number holds exactly; open the bucket with type 'bigint'`,
|
|
671
|
+
)
|
|
672
|
+
}
|
|
673
|
+
return BigInt(v)
|
|
674
|
+
},
|
|
675
|
+
decode: raw => {
|
|
676
|
+
if (typeof raw !== 'bigint') {
|
|
677
|
+
throw new CorruptError(`a stored value is ${describe(raw)} where an integer was written`)
|
|
678
|
+
}
|
|
679
|
+
if (raw > BigInt(Number.MAX_SAFE_INTEGER) || raw < BigInt(Number.MIN_SAFE_INTEGER)) {
|
|
680
|
+
throw new CorruptError(
|
|
681
|
+
`${raw} does not fit a number exactly; open the bucket with type 'bigint'`,
|
|
682
|
+
)
|
|
683
|
+
}
|
|
684
|
+
return Number(raw)
|
|
685
|
+
},
|
|
686
|
+
}
|
|
687
|
+
|
|
688
|
+
const bigintValues: Values<unknown> = {
|
|
689
|
+
encode: v => {
|
|
690
|
+
if (typeof v !== 'bigint' && !(typeof v === 'number' && Number.isSafeInteger(v))) {
|
|
691
|
+
throw new InvalidError(`${String(v)} is not an integer`)
|
|
692
|
+
}
|
|
693
|
+
return BigInt(v)
|
|
694
|
+
},
|
|
695
|
+
decode: raw => {
|
|
696
|
+
if (typeof raw !== 'bigint') {
|
|
697
|
+
throw new CorruptError(`a stored value is ${describe(raw)} where an integer was written`)
|
|
698
|
+
}
|
|
699
|
+
return raw
|
|
700
|
+
},
|
|
701
|
+
}
|
|
702
|
+
|
|
703
|
+
const floatValues: Values<unknown> = {
|
|
704
|
+
encode: v => {
|
|
705
|
+
if (typeof v !== 'number') {
|
|
706
|
+
throw new InvalidError(`a ${typeof v} in a bucket of floats`)
|
|
707
|
+
}
|
|
708
|
+
const bytes = new Uint8Array(8)
|
|
709
|
+
new DataView(bytes.buffer).setFloat64(0, v)
|
|
710
|
+
return tagged(kinds.float, bytes)
|
|
711
|
+
},
|
|
712
|
+
decode: raw => {
|
|
713
|
+
const bits = bodyOf(raw, kinds.float, 'a float')
|
|
714
|
+
if (bits.length !== 8) {
|
|
715
|
+
throw new CorruptError(`a float from ${bits.length} bytes rather than 8`)
|
|
716
|
+
}
|
|
717
|
+
return new DataView(bits.buffer, bits.byteOffset, 8).getFloat64(0)
|
|
718
|
+
},
|
|
719
|
+
}
|
|
720
|
+
|
|
721
|
+
const boolValues: Values<unknown> = {
|
|
722
|
+
encode: v => {
|
|
723
|
+
if (typeof v !== 'boolean') {
|
|
724
|
+
throw new InvalidError(`a ${typeof v} in a bucket of booleans`)
|
|
725
|
+
}
|
|
726
|
+
return v ? 1n : 0n
|
|
727
|
+
},
|
|
728
|
+
decode: raw => {
|
|
729
|
+
if (typeof raw !== 'bigint') {
|
|
730
|
+
throw new CorruptError(`a stored value is ${describe(raw)} where a boolean was written`)
|
|
731
|
+
}
|
|
732
|
+
return raw !== 0n
|
|
733
|
+
},
|
|
734
|
+
}
|
|
735
|
+
|
|
576
736
|
export function valuesOf(type: ValueType | undefined): Values<unknown> {
|
|
577
737
|
switch (type) {
|
|
578
738
|
case undefined:
|
|
579
739
|
return jsonValues
|
|
580
740
|
case 'string':
|
|
581
|
-
return
|
|
582
|
-
encode: v => {
|
|
583
|
-
if (typeof v !== 'string') {
|
|
584
|
-
throw new InvalidError(`a ${typeof v} in a bucket of strings`)
|
|
585
|
-
}
|
|
586
|
-
return tagged(kinds.text, utf8.encode(v))
|
|
587
|
-
},
|
|
588
|
-
decode: raw => {
|
|
589
|
-
if (raw === null) {
|
|
590
|
-
return ''
|
|
591
|
-
}
|
|
592
|
-
const text = textOf(bodyOf(raw, kinds.text, 'text'))
|
|
593
|
-
if (text === undefined) {
|
|
594
|
-
throw new CorruptError('a stored value is text that is not UTF-8')
|
|
595
|
-
}
|
|
596
|
-
return text
|
|
597
|
-
},
|
|
598
|
-
}
|
|
741
|
+
return stringValues
|
|
599
742
|
case 'bytes':
|
|
600
|
-
return
|
|
601
|
-
keeps: true,
|
|
602
|
-
encode: v => {
|
|
603
|
-
if (!(v instanceof Uint8Array)) {
|
|
604
|
-
throw new InvalidError(`a ${typeof v} in a bucket of bytes`)
|
|
605
|
-
}
|
|
606
|
-
return tagged(kinds.bytes, v)
|
|
607
|
-
},
|
|
608
|
-
decode: raw => (raw === null ? new Uint8Array(0) : bodyOf(raw, kinds.bytes, 'bytes')),
|
|
609
|
-
}
|
|
743
|
+
return bytesValues
|
|
610
744
|
case 'int':
|
|
611
|
-
return
|
|
612
|
-
encode: v => {
|
|
613
|
-
if (typeof v !== 'number' || !Number.isSafeInteger(v)) {
|
|
614
|
-
throw new InvalidError(
|
|
615
|
-
`${String(v)} is not an integer a number holds exactly; open the bucket with type 'bigint'`,
|
|
616
|
-
)
|
|
617
|
-
}
|
|
618
|
-
return BigInt(v)
|
|
619
|
-
},
|
|
620
|
-
decode: raw => {
|
|
621
|
-
if (typeof raw !== 'bigint') {
|
|
622
|
-
throw new CorruptError(
|
|
623
|
-
`a stored value is ${describe(raw)} where an integer was written`,
|
|
624
|
-
)
|
|
625
|
-
}
|
|
626
|
-
if (raw > BigInt(Number.MAX_SAFE_INTEGER) || raw < BigInt(Number.MIN_SAFE_INTEGER)) {
|
|
627
|
-
throw new CorruptError(
|
|
628
|
-
`${raw} does not fit a number exactly; open the bucket with type 'bigint'`,
|
|
629
|
-
)
|
|
630
|
-
}
|
|
631
|
-
return Number(raw)
|
|
632
|
-
},
|
|
633
|
-
}
|
|
745
|
+
return intValues
|
|
634
746
|
case 'bigint':
|
|
635
|
-
return
|
|
636
|
-
encode: v => {
|
|
637
|
-
if (typeof v !== 'bigint' && !(typeof v === 'number' && Number.isSafeInteger(v))) {
|
|
638
|
-
throw new InvalidError(`${String(v)} is not an integer`)
|
|
639
|
-
}
|
|
640
|
-
return BigInt(v)
|
|
641
|
-
},
|
|
642
|
-
decode: raw => {
|
|
643
|
-
if (typeof raw !== 'bigint') {
|
|
644
|
-
throw new CorruptError(
|
|
645
|
-
`a stored value is ${describe(raw)} where an integer was written`,
|
|
646
|
-
)
|
|
647
|
-
}
|
|
648
|
-
return raw
|
|
649
|
-
},
|
|
650
|
-
}
|
|
747
|
+
return bigintValues
|
|
651
748
|
case 'float':
|
|
652
|
-
return
|
|
653
|
-
encode: v => {
|
|
654
|
-
if (typeof v !== 'number') {
|
|
655
|
-
throw new InvalidError(`a ${typeof v} in a bucket of floats`)
|
|
656
|
-
}
|
|
657
|
-
const bytes = new Uint8Array(8)
|
|
658
|
-
new DataView(bytes.buffer).setFloat64(0, v)
|
|
659
|
-
return tagged(kinds.float, bytes)
|
|
660
|
-
},
|
|
661
|
-
decode: raw => {
|
|
662
|
-
const bits = bodyOf(raw, kinds.float, 'a float')
|
|
663
|
-
if (bits.length !== 8) {
|
|
664
|
-
throw new CorruptError(`a float from ${bits.length} bytes rather than 8`)
|
|
665
|
-
}
|
|
666
|
-
return new DataView(bits.buffer, bits.byteOffset, 8).getFloat64(0)
|
|
667
|
-
},
|
|
668
|
-
}
|
|
749
|
+
return floatValues
|
|
669
750
|
case 'bool':
|
|
670
|
-
return
|
|
671
|
-
encode: v => {
|
|
672
|
-
if (typeof v !== 'boolean') {
|
|
673
|
-
throw new InvalidError(`a ${typeof v} in a bucket of booleans`)
|
|
674
|
-
}
|
|
675
|
-
return v ? 1n : 0n
|
|
676
|
-
},
|
|
677
|
-
decode: raw => {
|
|
678
|
-
if (typeof raw !== 'bigint') {
|
|
679
|
-
throw new CorruptError(`a stored value is ${describe(raw)} where a boolean was written`)
|
|
680
|
-
}
|
|
681
|
-
return raw !== 0n
|
|
682
|
-
},
|
|
683
|
-
}
|
|
751
|
+
return boolValues
|
|
684
752
|
}
|
|
685
753
|
throw new InvalidError(
|
|
686
754
|
`a bucket's type is string, bytes, int, bigint, float or bool, not ${String(type)}`,
|
package/src/runtime/addon.ts
CHANGED
|
@@ -40,61 +40,72 @@ export function openAddon(
|
|
|
40
40
|
events: AddonEvents,
|
|
41
41
|
): Transport {
|
|
42
42
|
const addon = createRequire(import.meta.url)(path) as Addon
|
|
43
|
+
const reader = new PipeReader(events)
|
|
44
|
+
try {
|
|
45
|
+
reader.pipe = addon.open(dir, options, () => reader.woken())
|
|
46
|
+
} catch (err) {
|
|
47
|
+
throw openFailure(dir, (err as Error).message)
|
|
48
|
+
}
|
|
49
|
+
return {
|
|
50
|
+
write: turning(bytes => reader.send(bytes)),
|
|
51
|
+
close() {
|
|
52
|
+
const closing = reader.pipe
|
|
53
|
+
if (closing === undefined) {
|
|
54
|
+
return
|
|
55
|
+
}
|
|
56
|
+
reader.pipe = undefined
|
|
57
|
+
closing.close()
|
|
58
|
+
events.end(new ClosedError('the store closed'))
|
|
59
|
+
},
|
|
60
|
+
}
|
|
61
|
+
}
|
|
43
62
|
|
|
63
|
+
/** The addon's pipe as the session reads and writes it. */
|
|
64
|
+
class PipeReader {
|
|
65
|
+
pipe: AddonPipe | undefined
|
|
66
|
+
readonly #events: AddonEvents
|
|
44
67
|
// What the session writes while it reads: its frames wait for the read's
|
|
45
68
|
// end, since an answer handed back meanwhile would reach the session in
|
|
46
69
|
// the middle of the bytes it is reading.
|
|
47
|
-
|
|
48
|
-
|
|
70
|
+
#reading = false
|
|
71
|
+
readonly #waiting: Uint8Array[] = []
|
|
49
72
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
} finally {
|
|
59
|
-
reading = false
|
|
60
|
-
}
|
|
61
|
-
const queued = waiting.shift()
|
|
62
|
-
if (queued !== undefined) {
|
|
63
|
-
send(queued)
|
|
73
|
+
constructor(events: AddonEvents) {
|
|
74
|
+
this.#events = events
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/** The core's wake: what it has ready, unless a read under way, which reads until nothing is, takes it. */
|
|
78
|
+
woken(): void {
|
|
79
|
+
if (!this.#reading) {
|
|
80
|
+
this.#take(this.pipe?.recv() ?? null)
|
|
64
81
|
}
|
|
65
82
|
}
|
|
66
83
|
|
|
67
|
-
|
|
68
|
-
if (pipe === undefined) {
|
|
84
|
+
send(bytes: Uint8Array): void {
|
|
85
|
+
if (this.pipe === undefined) {
|
|
69
86
|
return
|
|
70
87
|
}
|
|
71
|
-
if (reading) {
|
|
72
|
-
waiting.push(bytes)
|
|
88
|
+
if (this.#reading) {
|
|
89
|
+
this.#waiting.push(bytes)
|
|
73
90
|
return
|
|
74
91
|
}
|
|
75
|
-
take(pipe.send(bytes))
|
|
92
|
+
this.#take(this.pipe.send(bytes))
|
|
76
93
|
}
|
|
77
94
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
} catch (err) {
|
|
86
|
-
throw openFailure(dir, (err as Error).message)
|
|
87
|
-
}
|
|
88
|
-
return {
|
|
89
|
-
write: turning(send),
|
|
90
|
-
close() {
|
|
91
|
-
const closing = pipe
|
|
92
|
-
if (closing === undefined) {
|
|
93
|
-
return
|
|
95
|
+
#take(bytes: Uint8Array | null): void {
|
|
96
|
+
this.#reading = true
|
|
97
|
+
try {
|
|
98
|
+
let next = bytes
|
|
99
|
+
while (next !== null && this.pipe !== undefined) {
|
|
100
|
+
this.#events.data(next)
|
|
101
|
+
next = this.pipe.recv()
|
|
94
102
|
}
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
103
|
+
} finally {
|
|
104
|
+
this.#reading = false
|
|
105
|
+
}
|
|
106
|
+
const queued = this.#waiting.shift()
|
|
107
|
+
if (queued !== undefined) {
|
|
108
|
+
this.send(queued)
|
|
109
|
+
}
|
|
99
110
|
}
|
|
100
111
|
}
|