@tinyshed/tinystore 0.5.0 → 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/kv.js CHANGED
@@ -404,106 +404,114 @@ export const jsonValues = {
404
404
  }
405
405
  },
406
406
  };
407
+ /** A row of nothing reads as the empty string. */
408
+ const stringValues = {
409
+ encode: v => {
410
+ if (typeof v !== 'string') {
411
+ throw new InvalidError(`a ${typeof v} in a bucket of strings`);
412
+ }
413
+ return tagged(kinds.text, utf8.encode(v));
414
+ },
415
+ decode: raw => {
416
+ if (raw === null) {
417
+ return '';
418
+ }
419
+ const text = textOf(bodyOf(raw, kinds.text, 'text'));
420
+ if (text === undefined) {
421
+ throw new CorruptError('a stored value is text that is not UTF-8');
422
+ }
423
+ return text;
424
+ },
425
+ };
426
+ /** A row of nothing reads as no bytes. */
427
+ const bytesValues = {
428
+ keeps: true,
429
+ encode: v => {
430
+ if (!(v instanceof Uint8Array)) {
431
+ throw new InvalidError(`a ${typeof v} in a bucket of bytes`);
432
+ }
433
+ return tagged(kinds.bytes, v);
434
+ },
435
+ decode: raw => (raw === null ? new Uint8Array(0) : bodyOf(raw, kinds.bytes, 'bytes')),
436
+ };
437
+ const intValues = {
438
+ encode: v => {
439
+ if (typeof v !== 'number' || !Number.isSafeInteger(v)) {
440
+ throw new InvalidError(`${String(v)} is not an integer a number holds exactly; open the bucket with type 'bigint'`);
441
+ }
442
+ return BigInt(v);
443
+ },
444
+ decode: raw => {
445
+ if (typeof raw !== 'bigint') {
446
+ throw new CorruptError(`a stored value is ${describe(raw)} where an integer was written`);
447
+ }
448
+ if (raw > BigInt(Number.MAX_SAFE_INTEGER) || raw < BigInt(Number.MIN_SAFE_INTEGER)) {
449
+ throw new CorruptError(`${raw} does not fit a number exactly; open the bucket with type 'bigint'`);
450
+ }
451
+ return Number(raw);
452
+ },
453
+ };
454
+ const bigintValues = {
455
+ encode: v => {
456
+ if (typeof v !== 'bigint' && !(typeof v === 'number' && Number.isSafeInteger(v))) {
457
+ throw new InvalidError(`${String(v)} is not an integer`);
458
+ }
459
+ return BigInt(v);
460
+ },
461
+ decode: raw => {
462
+ if (typeof raw !== 'bigint') {
463
+ throw new CorruptError(`a stored value is ${describe(raw)} where an integer was written`);
464
+ }
465
+ return raw;
466
+ },
467
+ };
468
+ const floatValues = {
469
+ encode: v => {
470
+ if (typeof v !== 'number') {
471
+ throw new InvalidError(`a ${typeof v} in a bucket of floats`);
472
+ }
473
+ const bytes = new Uint8Array(8);
474
+ new DataView(bytes.buffer).setFloat64(0, v);
475
+ return tagged(kinds.float, bytes);
476
+ },
477
+ decode: raw => {
478
+ const bits = bodyOf(raw, kinds.float, 'a float');
479
+ if (bits.length !== 8) {
480
+ throw new CorruptError(`a float from ${bits.length} bytes rather than 8`);
481
+ }
482
+ return new DataView(bits.buffer, bits.byteOffset, 8).getFloat64(0);
483
+ },
484
+ };
485
+ const boolValues = {
486
+ encode: v => {
487
+ if (typeof v !== 'boolean') {
488
+ throw new InvalidError(`a ${typeof v} in a bucket of booleans`);
489
+ }
490
+ return v ? 1n : 0n;
491
+ },
492
+ decode: raw => {
493
+ if (typeof raw !== 'bigint') {
494
+ throw new CorruptError(`a stored value is ${describe(raw)} where a boolean was written`);
495
+ }
496
+ return raw !== 0n;
497
+ },
498
+ };
407
499
  export function valuesOf(type) {
408
500
  switch (type) {
409
501
  case undefined:
410
502
  return jsonValues;
411
503
  case 'string':
412
- return {
413
- encode: v => {
414
- if (typeof v !== 'string') {
415
- throw new InvalidError(`a ${typeof v} in a bucket of strings`);
416
- }
417
- return tagged(kinds.text, utf8.encode(v));
418
- },
419
- decode: raw => {
420
- if (raw === null) {
421
- return '';
422
- }
423
- const text = textOf(bodyOf(raw, kinds.text, 'text'));
424
- if (text === undefined) {
425
- throw new CorruptError('a stored value is text that is not UTF-8');
426
- }
427
- return text;
428
- },
429
- };
504
+ return stringValues;
430
505
  case 'bytes':
431
- return {
432
- keeps: true,
433
- encode: v => {
434
- if (!(v instanceof Uint8Array)) {
435
- throw new InvalidError(`a ${typeof v} in a bucket of bytes`);
436
- }
437
- return tagged(kinds.bytes, v);
438
- },
439
- decode: raw => (raw === null ? new Uint8Array(0) : bodyOf(raw, kinds.bytes, 'bytes')),
440
- };
506
+ return bytesValues;
441
507
  case 'int':
442
- return {
443
- encode: v => {
444
- if (typeof v !== 'number' || !Number.isSafeInteger(v)) {
445
- throw new InvalidError(`${String(v)} is not an integer a number holds exactly; open the bucket with type 'bigint'`);
446
- }
447
- return BigInt(v);
448
- },
449
- decode: raw => {
450
- if (typeof raw !== 'bigint') {
451
- throw new CorruptError(`a stored value is ${describe(raw)} where an integer was written`);
452
- }
453
- if (raw > BigInt(Number.MAX_SAFE_INTEGER) || raw < BigInt(Number.MIN_SAFE_INTEGER)) {
454
- throw new CorruptError(`${raw} does not fit a number exactly; open the bucket with type 'bigint'`);
455
- }
456
- return Number(raw);
457
- },
458
- };
508
+ return intValues;
459
509
  case 'bigint':
460
- return {
461
- encode: v => {
462
- if (typeof v !== 'bigint' && !(typeof v === 'number' && Number.isSafeInteger(v))) {
463
- throw new InvalidError(`${String(v)} is not an integer`);
464
- }
465
- return BigInt(v);
466
- },
467
- decode: raw => {
468
- if (typeof raw !== 'bigint') {
469
- throw new CorruptError(`a stored value is ${describe(raw)} where an integer was written`);
470
- }
471
- return raw;
472
- },
473
- };
510
+ return bigintValues;
474
511
  case 'float':
475
- return {
476
- encode: v => {
477
- if (typeof v !== 'number') {
478
- throw new InvalidError(`a ${typeof v} in a bucket of floats`);
479
- }
480
- const bytes = new Uint8Array(8);
481
- new DataView(bytes.buffer).setFloat64(0, v);
482
- return tagged(kinds.float, bytes);
483
- },
484
- decode: raw => {
485
- const bits = bodyOf(raw, kinds.float, 'a float');
486
- if (bits.length !== 8) {
487
- throw new CorruptError(`a float from ${bits.length} bytes rather than 8`);
488
- }
489
- return new DataView(bits.buffer, bits.byteOffset, 8).getFloat64(0);
490
- },
491
- };
512
+ return floatValues;
492
513
  case 'bool':
493
- return {
494
- encode: v => {
495
- if (typeof v !== 'boolean') {
496
- throw new InvalidError(`a ${typeof v} in a bucket of booleans`);
497
- }
498
- return v ? 1n : 0n;
499
- },
500
- decode: raw => {
501
- if (typeof raw !== 'bigint') {
502
- throw new CorruptError(`a stored value is ${describe(raw)} where a boolean was written`);
503
- }
504
- return raw !== 0n;
505
- },
506
- };
514
+ return boolValues;
507
515
  }
508
516
  throw new InvalidError(`a bucket's type is string, bytes, int, bigint, float or bool, not ${String(type)}`);
509
517
  }
@@ -12,59 +12,69 @@ import { openFailure, turning } from './shared.js';
12
12
  */
13
13
  export function openAddon(path, dir, options, events) {
14
14
  const addon = createRequire(import.meta.url)(path);
15
- // What the session writes while it reads: its frames wait for the read's
16
- // end, since an answer handed back meanwhile would reach the session in
17
- // the middle of the bytes it is reading.
18
- let reading = false;
19
- const waiting = [];
20
- const take = (bytes) => {
21
- reading = true;
22
- try {
23
- let next = bytes;
24
- while (next !== null && pipe !== undefined) {
25
- events.data(next);
26
- next = pipe.recv();
27
- }
28
- }
29
- finally {
30
- reading = false;
31
- }
32
- const queued = waiting.shift();
33
- if (queued !== undefined) {
34
- send(queued);
35
- }
36
- };
37
- const send = (bytes) => {
38
- if (pipe === undefined) {
39
- return;
40
- }
41
- if (reading) {
42
- waiting.push(bytes);
43
- return;
44
- }
45
- take(pipe.send(bytes));
46
- };
47
- let pipe;
15
+ const reader = new PipeReader(events);
48
16
  try {
49
- pipe = addon.open(dir, options, () => {
50
- if (!reading) {
51
- take(pipe?.recv() ?? null);
52
- }
53
- });
17
+ reader.pipe = addon.open(dir, options, () => reader.woken());
54
18
  }
55
19
  catch (err) {
56
20
  throw openFailure(dir, err.message);
57
21
  }
58
22
  return {
59
- write: turning(send),
23
+ write: turning(bytes => reader.send(bytes)),
60
24
  close() {
61
- const closing = pipe;
25
+ const closing = reader.pipe;
62
26
  if (closing === undefined) {
63
27
  return;
64
28
  }
65
- pipe = undefined;
29
+ reader.pipe = undefined;
66
30
  closing.close();
67
31
  events.end(new ClosedError('the store closed'));
68
32
  },
69
33
  };
70
34
  }
35
+ /** The addon's pipe as the session reads and writes it. */
36
+ class PipeReader {
37
+ pipe;
38
+ #events;
39
+ // What the session writes while it reads: its frames wait for the read's
40
+ // end, since an answer handed back meanwhile would reach the session in
41
+ // the middle of the bytes it is reading.
42
+ #reading = false;
43
+ #waiting = [];
44
+ constructor(events) {
45
+ this.#events = events;
46
+ }
47
+ /** The core's wake: what it has ready, unless a read under way, which reads until nothing is, takes it. */
48
+ woken() {
49
+ if (!this.#reading) {
50
+ this.#take(this.pipe?.recv() ?? null);
51
+ }
52
+ }
53
+ send(bytes) {
54
+ if (this.pipe === undefined) {
55
+ return;
56
+ }
57
+ if (this.#reading) {
58
+ this.#waiting.push(bytes);
59
+ return;
60
+ }
61
+ this.#take(this.pipe.send(bytes));
62
+ }
63
+ #take(bytes) {
64
+ this.#reading = true;
65
+ try {
66
+ let next = bytes;
67
+ while (next !== null && this.pipe !== undefined) {
68
+ this.#events.data(next);
69
+ next = this.pipe.recv();
70
+ }
71
+ }
72
+ finally {
73
+ this.#reading = false;
74
+ }
75
+ const queued = this.#waiting.shift();
76
+ if (queued !== undefined) {
77
+ this.send(queued);
78
+ }
79
+ }
80
+ }
@@ -40,119 +40,148 @@ const room = 1 << 16;
40
40
  */
41
41
  export function openPipe(library, dir, options, events) {
42
42
  const lib = dlopen(library, symbols);
43
+ const pipe = new CorePipe(lib, new Inbox(events));
44
+ const wake = new JSCallback(() => pipe.readOn(undefined), {
45
+ args: [FFIType.ptr],
46
+ returns: FFIType.void,
47
+ threadsafe: true,
48
+ });
49
+ pipe.connection = connect(lib, dir, options, wake);
50
+ // Bun's loop with no timer armed spins while it waits for a threadsafe
51
+ // callback from another thread: a write waiting for its sync burned a
52
+ // whole processor (research release-2026-10-23). A timer armed, however
53
+ // far off, lets the loop sleep until the core wakes it; it also keeps the
54
+ // process alive while the store is open, as a sidecar's socket does.
55
+ const sleeps = setInterval(() => { }, 2 ** 30);
56
+ return {
57
+ write: turning(bytes => pipe.send(bytes)),
58
+ close() {
59
+ const closing = pipe.connection;
60
+ if (closing === null) {
61
+ return;
62
+ }
63
+ pipe.connection = null;
64
+ clearInterval(sleeps);
65
+ lib.symbols.tinystore_close(closing);
66
+ wake.close();
67
+ events.end(new ClosedError('the store closed'));
68
+ },
69
+ };
70
+ }
71
+ /** Opens the store through the core; a store that does not open lets the core and the wake go. */
72
+ function connect(lib, dir, options, wake) {
43
73
  const name = new TextEncoder().encode(dir);
44
74
  const opened = new BigUint64Array(1);
45
75
  const failure = new Uint8Array(1024);
46
- let connection = null;
47
- // where the core writes what it owes: whole frames are read from the
48
- // front, and a frame's first part is held there for its rest
49
- const inbox = new Uint8Array(room);
50
- let held = 0;
76
+ const failed = Number(lib.symbols.tinystore_open(ptr(name), name.length, ptr(options), options.length, wake, null, ptr(opened), ptr(failure), failure.length));
77
+ if (failed > 0) {
78
+ const message = new TextDecoder().decode(failure.subarray(0, failed));
79
+ wake.close();
80
+ lib.close();
81
+ throw openFailure(dir, message);
82
+ }
83
+ return Number(opened[0]);
84
+ }
85
+ /**
86
+ * Where the core writes what it owes: whole frames are read from the front,
87
+ * and a frame's first part is held there for its rest.
88
+ */
89
+ class Inbox {
90
+ #events;
91
+ #inbox = new Uint8Array(room);
92
+ #held = 0;
51
93
  // A frame longer than the inbox, in bytes as long as it is, and how much
52
94
  // of it came: the core writes its rest there, and the session keeps them,
53
95
  // so that a file's mebibyte is written once here rather than copied out
54
96
  // of an inbox grown for it (issue #10).
55
- let large;
56
- let filledLarge = 0;
57
- // where the core writes next, and how many bytes it may
58
- const into = () => large === undefined
59
- ? [inbox, held, inbox.length - held]
60
- : [large, filledLarge, large.length - filledLarge];
61
- // reads what the core wrote where `into` said, and says whether it filled
62
- // that room, which means more may wait
63
- const read = (written) => {
64
- if (large !== undefined) {
65
- filledLarge += written;
66
- if (filledLarge < large.length) {
97
+ #large;
98
+ #filledLarge = 0;
99
+ constructor(events) {
100
+ this.#events = events;
101
+ }
102
+ /** Where the core writes next, and how many bytes it may. */
103
+ into() {
104
+ return this.#large === undefined
105
+ ? [this.#inbox, this.#held, this.#inbox.length - this.#held]
106
+ : [this.#large, this.#filledLarge, this.#large.length - this.#filledLarge];
107
+ }
108
+ /**
109
+ * Reads what the core wrote where `into` said, and says whether it filled
110
+ * that room, which means more may wait.
111
+ */
112
+ read(written) {
113
+ if (this.#large !== undefined) {
114
+ this.#filledLarge += written;
115
+ if (this.#filledLarge < this.#large.length) {
67
116
  return false;
68
117
  }
69
- const whole = large;
70
- large = undefined;
71
- events.frame(whole);
118
+ const whole = this.#large;
119
+ this.#large = undefined;
120
+ this.#events.frame(whole);
72
121
  return true;
73
122
  }
74
- const length = held + written;
75
- const filled = length === inbox.length;
76
- const taken = written === 0 ? 0 : events.frames(inbox, length);
77
- inbox.copyWithin(0, taken, length);
78
- held = length - taken;
79
- const frameLength = held < headerSize ? 0 : headerSize + bodyLength(inbox);
80
- if (frameLength > inbox.length) {
81
- large = new Uint8Array(frameLength);
82
- large.set(inbox.subarray(0, held));
83
- filledLarge = held;
84
- held = 0;
123
+ const length = this.#held + written;
124
+ const filled = length === this.#inbox.length;
125
+ const taken = written === 0 ? 0 : this.#events.frames(this.#inbox, length);
126
+ this.#inbox.copyWithin(0, taken, length);
127
+ this.#held = length - taken;
128
+ const frameLength = this.#held < headerSize ? 0 : headerSize + bodyLength(this.#inbox);
129
+ if (frameLength > this.#inbox.length) {
130
+ this.#large = new Uint8Array(frameLength);
131
+ this.#large.set(this.#inbox.subarray(0, this.#held));
132
+ this.#filledLarge = this.#held;
133
+ this.#held = 0;
85
134
  }
86
135
  return filled;
87
- };
136
+ }
137
+ }
138
+ /** One connection's calls into the core, which write what it owes into the inbox. */
139
+ class CorePipe {
140
+ connection = null;
141
+ #lib;
142
+ #inbox;
88
143
  // What the session writes while it reads: its frames wait for the read's
89
144
  // end, since a call of the core made meanwhile would write over the bytes
90
145
  // being read.
91
- let reading = false;
92
- const waiting = [];
93
- // reads what a call of the core wrote, and on while the core fills the
94
- // room, since no wake comes for what waits; then sends what was written
95
- // meanwhile
96
- const readOn = (written) => {
97
- reading = true;
146
+ #reading = false;
147
+ #waiting = [];
148
+ constructor(lib, inbox) {
149
+ this.#lib = lib;
150
+ this.#inbox = inbox;
151
+ }
152
+ /**
153
+ * Reads what a call of the core wrote, and on while the core fills the
154
+ * room, since no wake comes for what waits; then sends what was written
155
+ * meanwhile.
156
+ */
157
+ readOn(written) {
158
+ this.#reading = true;
98
159
  try {
99
- let filled = written === undefined || read(written);
100
- while (filled && connection !== null) {
101
- const [bytes, at, free] = into();
102
- filled = read(Number(lib.symbols.tinystore_recv(connection, 0, ptr(bytes, at), free)));
160
+ let filled = written === undefined || this.#inbox.read(written);
161
+ while (filled && this.connection !== null) {
162
+ const [bytes, at, free] = this.#inbox.into();
163
+ const read = this.#lib.symbols.tinystore_recv(this.connection, 0, ptr(bytes, at), free);
164
+ filled = this.#inbox.read(Number(read));
103
165
  }
104
166
  }
105
167
  finally {
106
- reading = false;
168
+ this.#reading = false;
107
169
  }
108
- const next = waiting.shift();
170
+ const next = this.#waiting.shift();
109
171
  if (next !== undefined) {
110
- send(next);
172
+ this.send(next);
111
173
  }
112
- };
113
- const send = (bytes) => {
114
- if (connection === null) {
174
+ }
175
+ send(bytes) {
176
+ if (this.connection === null) {
115
177
  return;
116
178
  }
117
- if (reading) {
118
- waiting.push(bytes);
179
+ if (this.#reading) {
180
+ this.#waiting.push(bytes);
119
181
  return;
120
182
  }
121
- const [owed, at, free] = into();
122
- const written = lib.symbols.tinystore_send(connection, ptr(bytes), bytes.length, ptr(owed, at), free);
123
- readOn(Number(written));
124
- };
125
- const wake = new JSCallback(() => readOn(undefined), {
126
- args: [FFIType.ptr],
127
- returns: FFIType.void,
128
- threadsafe: true,
129
- });
130
- const failed = Number(lib.symbols.tinystore_open(ptr(name), name.length, ptr(options), options.length, wake, null, ptr(opened), ptr(failure), failure.length));
131
- if (failed > 0) {
132
- const message = new TextDecoder().decode(failure.subarray(0, failed));
133
- wake.close();
134
- lib.close();
135
- throw openFailure(dir, message);
183
+ const [owed, at, free] = this.#inbox.into();
184
+ const written = this.#lib.symbols.tinystore_send(this.connection, ptr(bytes), bytes.length, ptr(owed, at), free);
185
+ this.readOn(Number(written));
136
186
  }
137
- connection = Number(opened[0]);
138
- // Bun's loop with no timer armed spins while it waits for a threadsafe
139
- // callback from another thread: a write waiting for its sync burned a
140
- // whole processor (research release-2026-10-23). A timer armed, however
141
- // far off, lets the loop sleep until the core wakes it; it also keeps the
142
- // process alive while the store is open, as a sidecar's socket does.
143
- const sleeps = setInterval(() => { }, 2 ** 30);
144
- return {
145
- write: turning(send),
146
- close() {
147
- if (connection === null) {
148
- return;
149
- }
150
- const closing = connection;
151
- connection = null;
152
- clearInterval(sleeps);
153
- lib.symbols.tinystore_close(closing);
154
- wake.close();
155
- events.end(new ClosedError('the store closed'));
156
- },
157
- };
158
187
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tinyshed/tinystore",
3
- "version": "0.5.0",
3
+ "version": "0.5.1",
4
4
  "description": "TinyStore for Bun and Node: kv, jobs, blobs, SQL, records and metrics in one directory, served by a sidecar",
5
5
  "license": "Apache-2.0",
6
6
  "homepage": "https://tinyshed.org/tinystore",
@@ -31,12 +31,12 @@
31
31
  "README.md"
32
32
  ],
33
33
  "optionalDependencies": {
34
- "@tinyshed/tinystore-linux-x64": "0.5.0",
35
- "@tinyshed/tinystore-linux-arm64": "0.5.0",
36
- "@tinyshed/tinystore-linux-x64-musl": "0.5.0",
37
- "@tinyshed/tinystore-linux-arm64-musl": "0.5.0",
38
- "@tinyshed/tinystore-darwin-arm64": "0.5.0",
39
- "@tinyshed/tinystore-darwin-x64": "0.5.0",
40
- "@tinyshed/tinystore-win32-x64": "0.5.0"
34
+ "@tinyshed/tinystore-linux-x64": "0.5.1",
35
+ "@tinyshed/tinystore-linux-arm64": "0.5.1",
36
+ "@tinyshed/tinystore-linux-x64-musl": "0.5.1",
37
+ "@tinyshed/tinystore-linux-arm64-musl": "0.5.1",
38
+ "@tinyshed/tinystore-darwin-arm64": "0.5.1",
39
+ "@tinyshed/tinystore-darwin-x64": "0.5.1",
40
+ "@tinyshed/tinystore-win32-x64": "0.5.1"
41
41
  }
42
42
  }
package/src/kv.ts CHANGED
@@ -631,114 +631,124 @@ export const jsonValues: Values<unknown> = {
631
631
  },
632
632
  }
633
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
+
634
736
  export function valuesOf(type: ValueType | undefined): Values<unknown> {
635
737
  switch (type) {
636
738
  case undefined:
637
739
  return jsonValues
638
740
  case 'string':
639
- return {
640
- encode: v => {
641
- if (typeof v !== 'string') {
642
- throw new InvalidError(`a ${typeof v} in a bucket of strings`)
643
- }
644
- return tagged(kinds.text, utf8.encode(v))
645
- },
646
- decode: raw => {
647
- if (raw === null) {
648
- return ''
649
- }
650
- const text = textOf(bodyOf(raw, kinds.text, 'text'))
651
- if (text === undefined) {
652
- throw new CorruptError('a stored value is text that is not UTF-8')
653
- }
654
- return text
655
- },
656
- }
741
+ return stringValues
657
742
  case 'bytes':
658
- return {
659
- keeps: true,
660
- encode: v => {
661
- if (!(v instanceof Uint8Array)) {
662
- throw new InvalidError(`a ${typeof v} in a bucket of bytes`)
663
- }
664
- return tagged(kinds.bytes, v)
665
- },
666
- decode: raw => (raw === null ? new Uint8Array(0) : bodyOf(raw, kinds.bytes, 'bytes')),
667
- }
743
+ return bytesValues
668
744
  case 'int':
669
- return {
670
- encode: v => {
671
- if (typeof v !== 'number' || !Number.isSafeInteger(v)) {
672
- throw new InvalidError(
673
- `${String(v)} is not an integer a number holds exactly; open the bucket with type 'bigint'`,
674
- )
675
- }
676
- return BigInt(v)
677
- },
678
- decode: raw => {
679
- if (typeof raw !== 'bigint') {
680
- throw new CorruptError(
681
- `a stored value is ${describe(raw)} where an integer was written`,
682
- )
683
- }
684
- if (raw > BigInt(Number.MAX_SAFE_INTEGER) || raw < BigInt(Number.MIN_SAFE_INTEGER)) {
685
- throw new CorruptError(
686
- `${raw} does not fit a number exactly; open the bucket with type 'bigint'`,
687
- )
688
- }
689
- return Number(raw)
690
- },
691
- }
745
+ return intValues
692
746
  case 'bigint':
693
- return {
694
- encode: v => {
695
- if (typeof v !== 'bigint' && !(typeof v === 'number' && Number.isSafeInteger(v))) {
696
- throw new InvalidError(`${String(v)} is not an integer`)
697
- }
698
- return BigInt(v)
699
- },
700
- decode: raw => {
701
- if (typeof raw !== 'bigint') {
702
- throw new CorruptError(
703
- `a stored value is ${describe(raw)} where an integer was written`,
704
- )
705
- }
706
- return raw
707
- },
708
- }
747
+ return bigintValues
709
748
  case 'float':
710
- return {
711
- encode: v => {
712
- if (typeof v !== 'number') {
713
- throw new InvalidError(`a ${typeof v} in a bucket of floats`)
714
- }
715
- const bytes = new Uint8Array(8)
716
- new DataView(bytes.buffer).setFloat64(0, v)
717
- return tagged(kinds.float, bytes)
718
- },
719
- decode: raw => {
720
- const bits = bodyOf(raw, kinds.float, 'a float')
721
- if (bits.length !== 8) {
722
- throw new CorruptError(`a float from ${bits.length} bytes rather than 8`)
723
- }
724
- return new DataView(bits.buffer, bits.byteOffset, 8).getFloat64(0)
725
- },
726
- }
749
+ return floatValues
727
750
  case 'bool':
728
- return {
729
- encode: v => {
730
- if (typeof v !== 'boolean') {
731
- throw new InvalidError(`a ${typeof v} in a bucket of booleans`)
732
- }
733
- return v ? 1n : 0n
734
- },
735
- decode: raw => {
736
- if (typeof raw !== 'bigint') {
737
- throw new CorruptError(`a stored value is ${describe(raw)} where a boolean was written`)
738
- }
739
- return raw !== 0n
740
- },
741
- }
751
+ return boolValues
742
752
  }
743
753
  throw new InvalidError(
744
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
  }
@@ -4,7 +4,7 @@
4
4
  // memory of the core's comes back: it reads our frames where they are and
5
5
  // writes its own where we say. Bun alone: bun:ffi.
6
6
 
7
- import { dlopen, FFIType, JSCallback, type Pointer, ptr } from 'bun:ffi'
7
+ import { dlopen, FFIType, JSCallback, type Library, type Pointer, ptr } from 'bun:ffi'
8
8
 
9
9
  import { ClosedError } from '../errors.ts'
10
10
  import type { Transport } from '../runtime.ts'
@@ -37,6 +37,8 @@ const symbols = {
37
37
  tinystore_close: { args: [FFIType.ptr], returns: FFIType.void },
38
38
  } as const
39
39
 
40
+ type Core = Library<typeof symbols>
41
+
40
42
  /** What the pipe tells the session reading it. */
41
43
  export interface PipeEvents {
42
44
  /**
@@ -65,144 +67,174 @@ export function openPipe(
65
67
  events: PipeEvents,
66
68
  ): Transport {
67
69
  const lib = dlopen(library, symbols)
70
+ const pipe = new CorePipe(lib, new Inbox(events))
71
+ const wake = new JSCallback(() => pipe.readOn(undefined), {
72
+ args: [FFIType.ptr],
73
+ returns: FFIType.void,
74
+ threadsafe: true,
75
+ })
76
+ pipe.connection = connect(lib, dir, options, wake)
77
+ // Bun's loop with no timer armed spins while it waits for a threadsafe
78
+ // callback from another thread: a write waiting for its sync burned a
79
+ // whole processor (research release-2026-10-23). A timer armed, however
80
+ // far off, lets the loop sleep until the core wakes it; it also keeps the
81
+ // process alive while the store is open, as a sidecar's socket does.
82
+ const sleeps = setInterval(() => {}, 2 ** 30)
83
+ return {
84
+ write: turning(bytes => pipe.send(bytes)),
85
+ close() {
86
+ const closing = pipe.connection
87
+ if (closing === null) {
88
+ return
89
+ }
90
+ pipe.connection = null
91
+ clearInterval(sleeps)
92
+ lib.symbols.tinystore_close(closing)
93
+ wake.close()
94
+ events.end(new ClosedError('the store closed'))
95
+ },
96
+ }
97
+ }
98
+
99
+ /** Opens the store through the core; a store that does not open lets the core and the wake go. */
100
+ function connect(lib: Core, dir: string, options: Uint8Array, wake: JSCallback): Pointer {
68
101
  const name = new TextEncoder().encode(dir)
69
102
  const opened = new BigUint64Array(1)
70
103
  const failure = new Uint8Array(1024)
71
- let connection: Pointer | null = null
104
+ const failed = Number(
105
+ lib.symbols.tinystore_open(
106
+ ptr(name),
107
+ name.length,
108
+ ptr(options),
109
+ options.length,
110
+ wake,
111
+ null,
112
+ ptr(opened),
113
+ ptr(failure),
114
+ failure.length,
115
+ ),
116
+ )
117
+ if (failed > 0) {
118
+ const message = new TextDecoder().decode(failure.subarray(0, failed))
119
+ wake.close()
120
+ lib.close()
121
+ throw openFailure(dir, message)
122
+ }
123
+ return Number(opened[0]) as Pointer
124
+ }
72
125
 
73
- // where the core writes what it owes: whole frames are read from the
74
- // front, and a frame's first part is held there for its rest
75
- const inbox = new Uint8Array(room)
76
- let held = 0
126
+ /**
127
+ * Where the core writes what it owes: whole frames are read from the front,
128
+ * and a frame's first part is held there for its rest.
129
+ */
130
+ class Inbox {
131
+ readonly #events: PipeEvents
132
+ readonly #inbox = new Uint8Array(room)
133
+ #held = 0
77
134
  // A frame longer than the inbox, in bytes as long as it is, and how much
78
135
  // of it came: the core writes its rest there, and the session keeps them,
79
136
  // so that a file's mebibyte is written once here rather than copied out
80
137
  // of an inbox grown for it (issue #10).
81
- let large: Uint8Array | undefined
82
- let filledLarge = 0
83
-
84
- // where the core writes next, and how many bytes it may
85
- const into = (): [Uint8Array, number, number] =>
86
- large === undefined
87
- ? [inbox, held, inbox.length - held]
88
- : [large, filledLarge, large.length - filledLarge]
89
-
90
- // reads what the core wrote where `into` said, and says whether it filled
91
- // that room, which means more may wait
92
- const read = (written: number): boolean => {
93
- if (large !== undefined) {
94
- filledLarge += written
95
- if (filledLarge < large.length) {
138
+ #large: Uint8Array | undefined
139
+ #filledLarge = 0
140
+
141
+ constructor(events: PipeEvents) {
142
+ this.#events = events
143
+ }
144
+
145
+ /** Where the core writes next, and how many bytes it may. */
146
+ into(): [Uint8Array, number, number] {
147
+ return this.#large === undefined
148
+ ? [this.#inbox, this.#held, this.#inbox.length - this.#held]
149
+ : [this.#large, this.#filledLarge, this.#large.length - this.#filledLarge]
150
+ }
151
+
152
+ /**
153
+ * Reads what the core wrote where `into` said, and says whether it filled
154
+ * that room, which means more may wait.
155
+ */
156
+ read(written: number): boolean {
157
+ if (this.#large !== undefined) {
158
+ this.#filledLarge += written
159
+ if (this.#filledLarge < this.#large.length) {
96
160
  return false
97
161
  }
98
- const whole = large
99
- large = undefined
100
- events.frame(whole)
162
+ const whole = this.#large
163
+ this.#large = undefined
164
+ this.#events.frame(whole)
101
165
  return true
102
166
  }
103
- const length = held + written
104
- const filled = length === inbox.length
105
- const taken = written === 0 ? 0 : events.frames(inbox, length)
106
- inbox.copyWithin(0, taken, length)
107
- held = length - taken
108
- const frameLength = held < headerSize ? 0 : headerSize + bodyLength(inbox)
109
- if (frameLength > inbox.length) {
110
- large = new Uint8Array(frameLength)
111
- large.set(inbox.subarray(0, held))
112
- filledLarge = held
113
- held = 0
167
+ const length = this.#held + written
168
+ const filled = length === this.#inbox.length
169
+ const taken = written === 0 ? 0 : this.#events.frames(this.#inbox, length)
170
+ this.#inbox.copyWithin(0, taken, length)
171
+ this.#held = length - taken
172
+ const frameLength = this.#held < headerSize ? 0 : headerSize + bodyLength(this.#inbox)
173
+ if (frameLength > this.#inbox.length) {
174
+ this.#large = new Uint8Array(frameLength)
175
+ this.#large.set(this.#inbox.subarray(0, this.#held))
176
+ this.#filledLarge = this.#held
177
+ this.#held = 0
114
178
  }
115
179
  return filled
116
180
  }
181
+ }
117
182
 
183
+ /** One connection's calls into the core, which write what it owes into the inbox. */
184
+ class CorePipe {
185
+ connection: Pointer | null = null
186
+ readonly #lib: Core
187
+ readonly #inbox: Inbox
118
188
  // What the session writes while it reads: its frames wait for the read's
119
189
  // end, since a call of the core made meanwhile would write over the bytes
120
190
  // being read.
121
- let reading = false
122
- const waiting: Uint8Array[] = []
123
-
124
- // reads what a call of the core wrote, and on while the core fills the
125
- // room, since no wake comes for what waits; then sends what was written
126
- // meanwhile
127
- const readOn = (written: number | undefined): void => {
128
- reading = true
191
+ #reading = false
192
+ readonly #waiting: Uint8Array[] = []
193
+
194
+ constructor(lib: Core, inbox: Inbox) {
195
+ this.#lib = lib
196
+ this.#inbox = inbox
197
+ }
198
+
199
+ /**
200
+ * Reads what a call of the core wrote, and on while the core fills the
201
+ * room, since no wake comes for what waits; then sends what was written
202
+ * meanwhile.
203
+ */
204
+ readOn(written: number | undefined): void {
205
+ this.#reading = true
129
206
  try {
130
- let filled = written === undefined || read(written)
131
- while (filled && connection !== null) {
132
- const [bytes, at, free] = into()
133
- filled = read(Number(lib.symbols.tinystore_recv(connection, 0, ptr(bytes, at), free)))
207
+ let filled = written === undefined || this.#inbox.read(written)
208
+ while (filled && this.connection !== null) {
209
+ const [bytes, at, free] = this.#inbox.into()
210
+ const read = this.#lib.symbols.tinystore_recv(this.connection, 0, ptr(bytes, at), free)
211
+ filled = this.#inbox.read(Number(read))
134
212
  }
135
213
  } finally {
136
- reading = false
214
+ this.#reading = false
137
215
  }
138
- const next = waiting.shift()
216
+ const next = this.#waiting.shift()
139
217
  if (next !== undefined) {
140
- send(next)
218
+ this.send(next)
141
219
  }
142
220
  }
143
221
 
144
- const send = (bytes: Uint8Array): void => {
145
- if (connection === null) {
222
+ send(bytes: Uint8Array): void {
223
+ if (this.connection === null) {
146
224
  return
147
225
  }
148
- if (reading) {
149
- waiting.push(bytes)
226
+ if (this.#reading) {
227
+ this.#waiting.push(bytes)
150
228
  return
151
229
  }
152
- const [owed, at, free] = into()
153
- const written = lib.symbols.tinystore_send(
154
- connection,
230
+ const [owed, at, free] = this.#inbox.into()
231
+ const written = this.#lib.symbols.tinystore_send(
232
+ this.connection,
155
233
  ptr(bytes),
156
234
  bytes.length,
157
235
  ptr(owed, at),
158
236
  free,
159
237
  )
160
- readOn(Number(written))
161
- }
162
-
163
- const wake = new JSCallback(() => readOn(undefined), {
164
- args: [FFIType.ptr],
165
- returns: FFIType.void,
166
- threadsafe: true,
167
- })
168
- const failed = Number(
169
- lib.symbols.tinystore_open(
170
- ptr(name),
171
- name.length,
172
- ptr(options),
173
- options.length,
174
- wake,
175
- null,
176
- ptr(opened),
177
- ptr(failure),
178
- failure.length,
179
- ),
180
- )
181
- if (failed > 0) {
182
- const message = new TextDecoder().decode(failure.subarray(0, failed))
183
- wake.close()
184
- lib.close()
185
- throw openFailure(dir, message)
186
- }
187
- connection = Number(opened[0]) as Pointer
188
- // Bun's loop with no timer armed spins while it waits for a threadsafe
189
- // callback from another thread: a write waiting for its sync burned a
190
- // whole processor (research release-2026-10-23). A timer armed, however
191
- // far off, lets the loop sleep until the core wakes it; it also keeps the
192
- // process alive while the store is open, as a sidecar's socket does.
193
- const sleeps = setInterval(() => {}, 2 ** 30)
194
- return {
195
- write: turning(send),
196
- close() {
197
- if (connection === null) {
198
- return
199
- }
200
- const closing = connection
201
- connection = null
202
- clearInterval(sleeps)
203
- lib.symbols.tinystore_close(closing)
204
- wake.close()
205
- events.end(new ClosedError('the store closed'))
206
- },
238
+ this.readOn(Number(written))
207
239
  }
208
240
  }