@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/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)}`,
@@ -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
- let reading = false
48
- const waiting: Uint8Array[] = []
70
+ #reading = false
71
+ readonly #waiting: Uint8Array[] = []
49
72
 
50
- const take = (bytes: Uint8Array | null): void => {
51
- reading = true
52
- try {
53
- let next = bytes
54
- while (next !== null && pipe !== undefined) {
55
- events.data(next)
56
- next = pipe.recv()
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
- const send = (bytes: Uint8Array): void => {
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
- let pipe: AddonPipe | undefined
79
- try {
80
- pipe = addon.open(dir, options, () => {
81
- if (!reading) {
82
- take(pipe?.recv() ?? null)
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
- pipe = undefined
96
- closing.close()
97
- events.end(new ClosedError('the store closed'))
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
  }