@tinyshed/tinystore 0.1.0-rc.5 → 0.1.0-rc.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +37 -37
- package/bin/tinystore.js +12 -1
- package/dist/backup.d.ts +33 -0
- package/dist/backup.js +49 -0
- package/dist/blobs.d.ts +160 -79
- package/dist/blobs.js +510 -217
- package/dist/channels.d.ts +90 -0
- package/dist/channels.js +291 -0
- package/dist/clock.js +3 -3
- package/dist/config.d.ts +209 -86
- package/dist/config.js +581 -538
- package/dist/connection.d.ts +64 -2
- package/dist/connection.js +201 -16
- package/dist/console.d.ts +27 -3
- package/dist/console.js +165 -12
- package/dist/dotenv.d.ts +7 -0
- package/dist/dotenv.js +79 -0
- package/dist/errors.d.ts +61 -1
- package/dist/errors.js +81 -1
- package/dist/handles.d.ts +44 -2
- package/dist/handles.js +81 -2
- package/dist/index.d.ts +17 -11
- package/dist/index.js +5 -3
- package/dist/instruments.d.ts +177 -0
- package/dist/instruments.js +819 -0
- package/dist/jobs.d.ts +335 -239
- package/dist/jobs.js +716 -536
- package/dist/json.d.ts +2 -0
- package/dist/json.js +122 -0
- package/dist/kv.d.ts +130 -243
- package/dist/kv.js +273 -640
- package/dist/limits.d.ts +80 -0
- package/dist/limits.js +139 -0
- package/dist/locks.d.ts +62 -0
- package/dist/locks.js +237 -0
- package/dist/logger.d.ts +45 -9
- package/dist/logger.js +150 -38
- package/dist/metrics.d.ts +210 -209
- package/dist/metrics.js +319 -556
- package/dist/once.d.ts +19 -18
- package/dist/once.js +74 -63
- package/dist/query.d.ts +181 -0
- package/dist/query.js +788 -0
- package/dist/records.d.ts +241 -150
- package/dist/records.js +507 -291
- package/dist/runtime/addon.d.ts +14 -0
- package/dist/runtime/addon.js +69 -0
- package/dist/runtime/bun.js +5 -7
- package/dist/runtime/node.js +5 -7
- package/dist/runtime/pipe.d.ts +17 -0
- package/dist/runtime/pipe.js +133 -0
- package/dist/runtime/shared.d.ts +6 -0
- package/dist/runtime/shared.js +19 -0
- package/dist/runtime.d.ts +5 -2
- package/dist/search.d.ts +189 -0
- package/dist/search.js +281 -0
- package/dist/session.d.ts +31 -3
- package/dist/session.js +153 -41
- package/dist/sql.d.ts +228 -78
- package/dist/sql.js +745 -240
- package/dist/store.d.ts +244 -24
- package/dist/store.js +270 -67
- package/dist/time.d.ts +5 -1
- package/dist/time.js +22 -2
- package/dist/tx.d.ts +61 -0
- package/dist/tx.js +314 -0
- package/dist/wire/codec.d.ts +23 -7
- package/dist/wire/codec.js +56 -35
- package/dist/wire/frame.d.ts +2 -0
- package/dist/wire/frame.js +31 -14
- package/dist/wire/messages.d.ts +259 -0
- package/dist/wire/messages.js +22 -0
- package/dist/wire/msgpack.d.ts +49 -1
- package/dist/wire/msgpack.js +293 -56
- package/dist/wire/protocol.d.ts +2683 -0
- package/dist/wire/protocol.js +10846 -0
- package/package.json +39 -38
- package/src/backup.ts +81 -0
- package/src/blobs.ts +678 -301
- package/src/channels.ts +377 -0
- package/src/clock.ts +4 -4
- package/src/config.ts +902 -612
- package/src/connection.ts +279 -21
- package/src/console.ts +180 -12
- package/src/dotenv.ts +82 -0
- package/src/errors.ts +105 -0
- package/src/handles.ts +157 -8
- package/src/index.ts +158 -52
- package/src/instruments.ts +1042 -0
- package/src/jobs.ts +1017 -733
- package/src/json.ts +133 -0
- package/src/kv.ts +424 -847
- package/src/limits.ts +202 -0
- package/src/locks.ts +320 -0
- package/src/logger.ts +209 -40
- package/src/metrics.ts +557 -752
- package/src/once.ts +86 -83
- package/src/query.ts +1005 -0
- package/src/records.ts +795 -418
- package/src/runtime/addon.ts +99 -0
- package/src/runtime/bun.ts +5 -7
- package/src/runtime/node.ts +5 -7
- package/src/runtime/pipe.ts +178 -0
- package/src/runtime/shared.ts +20 -0
- package/src/runtime.ts +5 -2
- package/src/search.ts +480 -0
- package/src/session.ts +187 -41
- package/src/sql.ts +993 -306
- package/src/store.ts +473 -78
- package/src/time.ts +48 -3
- package/src/tx.ts +426 -0
- package/src/wire/codec.ts +78 -37
- package/src/wire/frame.ts +44 -14
- package/src/wire/messages.ts +25 -0
- package/src/wire/msgpack.ts +327 -56
- package/src/wire/protocol.ts +11709 -0
- package/dist/limiter.d.ts +0 -45
- package/dist/limiter.js +0 -68
- package/dist/quota.d.ts +0 -44
- package/dist/quota.js +0 -98
- package/src/limiter.ts +0 -99
- package/src/quota.ts +0 -137
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import type { Transport } from '../runtime.ts';
|
|
2
|
+
/** What the pipe tells the session reading it. */
|
|
3
|
+
export interface AddonEvents {
|
|
4
|
+
/** bytes the core wrote: any part of a frame, or several */
|
|
5
|
+
data(bytes: Uint8Array): void;
|
|
6
|
+
/** the store closed; called once */
|
|
7
|
+
end(err: Error): void;
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* Opens a pipe to the store in a directory, the core loaded from the addon
|
|
11
|
+
* at `path`. `options` is the wire's store.Options, how this process opens
|
|
12
|
+
* the store.
|
|
13
|
+
*/
|
|
14
|
+
export declare function openAddon(path: string, dir: string, options: Uint8Array, events: AddonEvents): Transport;
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
// The core in this process under Node, through its addon, tinystore.node:
|
|
2
|
+
// the frames a socket would carry go to the addon's send, which hands back
|
|
3
|
+
// what is ready at once, and the core's wake tells the loop to read the rest.
|
|
4
|
+
// Node alone: Bun loads the C library through bun:ffi instead.
|
|
5
|
+
import { createRequire } from 'node:module';
|
|
6
|
+
import { ClosedError } from '../errors.js';
|
|
7
|
+
/**
|
|
8
|
+
* Opens a pipe to the store in a directory, the core loaded from the addon
|
|
9
|
+
* at `path`. `options` is the wire's store.Options, how this process opens
|
|
10
|
+
* the store.
|
|
11
|
+
*/
|
|
12
|
+
export function openAddon(path, dir, options, events) {
|
|
13
|
+
const addon = createRequire(import.meta.url)(path);
|
|
14
|
+
// What the session writes while it reads: its frames wait for the read's
|
|
15
|
+
// end, since an answer handed back meanwhile would reach the session in
|
|
16
|
+
// the middle of the bytes it is reading.
|
|
17
|
+
let reading = false;
|
|
18
|
+
const waiting = [];
|
|
19
|
+
const take = (bytes) => {
|
|
20
|
+
reading = true;
|
|
21
|
+
try {
|
|
22
|
+
let next = bytes;
|
|
23
|
+
while (next !== null && pipe !== undefined) {
|
|
24
|
+
events.data(next);
|
|
25
|
+
next = pipe.recv();
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
finally {
|
|
29
|
+
reading = false;
|
|
30
|
+
}
|
|
31
|
+
const queued = waiting.shift();
|
|
32
|
+
if (queued !== undefined) {
|
|
33
|
+
send(queued);
|
|
34
|
+
}
|
|
35
|
+
};
|
|
36
|
+
const send = (bytes) => {
|
|
37
|
+
if (pipe === undefined) {
|
|
38
|
+
return;
|
|
39
|
+
}
|
|
40
|
+
if (reading) {
|
|
41
|
+
waiting.push(bytes);
|
|
42
|
+
return;
|
|
43
|
+
}
|
|
44
|
+
take(pipe.send(bytes));
|
|
45
|
+
};
|
|
46
|
+
let pipe;
|
|
47
|
+
try {
|
|
48
|
+
pipe = addon.open(dir, options, () => {
|
|
49
|
+
if (!reading) {
|
|
50
|
+
take(pipe?.recv() ?? null);
|
|
51
|
+
}
|
|
52
|
+
});
|
|
53
|
+
}
|
|
54
|
+
catch (err) {
|
|
55
|
+
throw new ClosedError(`cannot open ${dir}: ${err.message}`);
|
|
56
|
+
}
|
|
57
|
+
return {
|
|
58
|
+
write: send,
|
|
59
|
+
close() {
|
|
60
|
+
const closing = pipe;
|
|
61
|
+
if (closing === undefined) {
|
|
62
|
+
return;
|
|
63
|
+
}
|
|
64
|
+
pipe = undefined;
|
|
65
|
+
closing.close();
|
|
66
|
+
events.end(new ClosedError('the store closed'));
|
|
67
|
+
},
|
|
68
|
+
};
|
|
69
|
+
}
|
package/dist/runtime/bun.js
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
import net from 'node:net';
|
|
6
6
|
import manifest from '../../package.json' with { type: 'json' };
|
|
7
7
|
import { ClosedError } from '../errors.js';
|
|
8
|
-
import { address, exitedWith, spawnDetached, stderrKept } from './shared.js';
|
|
8
|
+
import { address, exitedWith, platformPackage, spawnDetached, stderrKept } from './shared.js';
|
|
9
9
|
export const bunRuntime = {
|
|
10
10
|
get client() {
|
|
11
11
|
return `tinystore-js/${manifest.version} bun/${Bun.version}`;
|
|
@@ -27,7 +27,7 @@ export const bunRuntime = {
|
|
|
27
27
|
}
|
|
28
28
|
},
|
|
29
29
|
which: name => Bun.which(name) ?? undefined,
|
|
30
|
-
|
|
30
|
+
packaged,
|
|
31
31
|
};
|
|
32
32
|
async function connect(endpoint, events, tls) {
|
|
33
33
|
const at = address(endpoint);
|
|
@@ -151,12 +151,10 @@ function spawnPrivate(argv, events) {
|
|
|
151
151
|
stderr: () => kept,
|
|
152
152
|
};
|
|
153
153
|
}
|
|
154
|
-
/**
|
|
155
|
-
function
|
|
156
|
-
const name = `@tinyshed/tinystore-${process.platform}-${process.arch}`;
|
|
157
|
-
const binary = process.platform === 'win32' ? 'tinystore.exe' : 'tinystore';
|
|
154
|
+
/** A file of the platform's package, installed beside this one. */
|
|
155
|
+
function packaged(file) {
|
|
158
156
|
try {
|
|
159
|
-
return Bun.resolveSync(`${
|
|
157
|
+
return Bun.resolveSync(`${platformPackage()}/${file}`, import.meta.dir);
|
|
160
158
|
}
|
|
161
159
|
catch {
|
|
162
160
|
return undefined;
|
package/dist/runtime/node.js
CHANGED
|
@@ -10,7 +10,7 @@ import { delimiter, join } from 'node:path';
|
|
|
10
10
|
import tls from 'node:tls';
|
|
11
11
|
import manifest from '../../package.json' with { type: 'json' };
|
|
12
12
|
import { ClosedError } from '../errors.js';
|
|
13
|
-
import { address, exitedWith, spawnDetached, stderrKept } from './shared.js';
|
|
13
|
+
import { address, exitedWith, platformPackage, spawnDetached, stderrKept } from './shared.js';
|
|
14
14
|
export const nodeRuntime = {
|
|
15
15
|
client: `tinystore-js/${manifest.version} node/${process.versions.node}`,
|
|
16
16
|
windows: process.platform === 'win32',
|
|
@@ -29,7 +29,7 @@ export const nodeRuntime = {
|
|
|
29
29
|
}
|
|
30
30
|
},
|
|
31
31
|
which,
|
|
32
|
-
|
|
32
|
+
packaged,
|
|
33
33
|
};
|
|
34
34
|
function connect(endpoint, events, options) {
|
|
35
35
|
const at = address(endpoint);
|
|
@@ -144,12 +144,10 @@ function executable(path, windows) {
|
|
|
144
144
|
return false;
|
|
145
145
|
}
|
|
146
146
|
}
|
|
147
|
-
/**
|
|
148
|
-
function
|
|
149
|
-
const name = `@tinyshed/tinystore-${process.platform}-${process.arch}`;
|
|
150
|
-
const binary = process.platform === 'win32' ? 'tinystore.exe' : 'tinystore';
|
|
147
|
+
/** A file of the platform's package, installed beside this one. */
|
|
148
|
+
function packaged(file) {
|
|
151
149
|
try {
|
|
152
|
-
return createRequire(import.meta.url).resolve(`${
|
|
150
|
+
return createRequire(import.meta.url).resolve(`${platformPackage()}/${file}`);
|
|
153
151
|
}
|
|
154
152
|
catch {
|
|
155
153
|
return undefined;
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import type { Transport } from '../runtime.ts';
|
|
2
|
+
/** What the pipe tells the session reading it. */
|
|
3
|
+
export interface PipeEvents {
|
|
4
|
+
/**
|
|
5
|
+
* Reads the frames whole in the first `length` bytes and says how many
|
|
6
|
+
* bytes they were. The bytes are the pipe's, written over by its next
|
|
7
|
+
* read: nothing of them may be kept.
|
|
8
|
+
*/
|
|
9
|
+
frames(bytes: Uint8Array, length: number): number;
|
|
10
|
+
/** the store closed; called once */
|
|
11
|
+
end(err: Error): void;
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Opens a pipe to the store in a directory, the core loaded from `library`.
|
|
15
|
+
* `options` is the wire's store.Options, how this process opens the store.
|
|
16
|
+
*/
|
|
17
|
+
export declare function openPipe(library: string, dir: string, options: Uint8Array, events: PipeEvents): Transport;
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
// The core in this process, through its C ABI: the frames a socket would
|
|
2
|
+
// carry go to tinystore_send, and those the core owes are written into bytes
|
|
3
|
+
// of ours, by that call or by tinystore_recv once the core wakes us. No
|
|
4
|
+
// memory of the core's comes back: it reads our frames where they are and
|
|
5
|
+
// writes its own where we say. Bun alone: bun:ffi.
|
|
6
|
+
import { dlopen, FFIType, JSCallback, ptr } from 'bun:ffi';
|
|
7
|
+
import { ClosedError } from '../errors.js';
|
|
8
|
+
const symbols = {
|
|
9
|
+
tinystore_open: {
|
|
10
|
+
args: [
|
|
11
|
+
FFIType.ptr,
|
|
12
|
+
FFIType.u64,
|
|
13
|
+
FFIType.ptr,
|
|
14
|
+
FFIType.u64,
|
|
15
|
+
FFIType.function,
|
|
16
|
+
FFIType.ptr,
|
|
17
|
+
FFIType.ptr,
|
|
18
|
+
FFIType.ptr,
|
|
19
|
+
FFIType.u64,
|
|
20
|
+
],
|
|
21
|
+
returns: FFIType.u64_fast,
|
|
22
|
+
},
|
|
23
|
+
tinystore_send: {
|
|
24
|
+
args: [FFIType.ptr, FFIType.ptr, FFIType.u64, FFIType.ptr, FFIType.u64],
|
|
25
|
+
returns: FFIType.u64_fast,
|
|
26
|
+
},
|
|
27
|
+
tinystore_recv: {
|
|
28
|
+
args: [FFIType.ptr, FFIType.u32, FFIType.ptr, FFIType.u64],
|
|
29
|
+
returns: FFIType.u64_fast,
|
|
30
|
+
},
|
|
31
|
+
tinystore_close: { args: [FFIType.ptr], returns: FFIType.void },
|
|
32
|
+
};
|
|
33
|
+
/** The room for what the core owes, to begin with and once a large frame has passed. */
|
|
34
|
+
const room = 1 << 16;
|
|
35
|
+
/** Room past this is given back once nothing is held in it. */
|
|
36
|
+
const kept = 1 << 20;
|
|
37
|
+
/**
|
|
38
|
+
* Opens a pipe to the store in a directory, the core loaded from `library`.
|
|
39
|
+
* `options` is the wire's store.Options, how this process opens the store.
|
|
40
|
+
*/
|
|
41
|
+
export function openPipe(library, dir, options, events) {
|
|
42
|
+
const lib = dlopen(library, symbols);
|
|
43
|
+
const name = new TextEncoder().encode(dir);
|
|
44
|
+
const opened = new BigUint64Array(1);
|
|
45
|
+
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
|
+
let inbox = new Uint8Array(room);
|
|
50
|
+
let held = 0;
|
|
51
|
+
// reads the frames among the `written` bytes behind what is held, and
|
|
52
|
+
// says whether the core filled the room, which means more may wait
|
|
53
|
+
const read = (written) => {
|
|
54
|
+
const length = held + written;
|
|
55
|
+
const filled = length === inbox.length;
|
|
56
|
+
const taken = written === 0 ? 0 : events.frames(inbox, length);
|
|
57
|
+
inbox.copyWithin(0, taken, length);
|
|
58
|
+
held = length - taken;
|
|
59
|
+
if (held === inbox.length) {
|
|
60
|
+
// a frame longer than the room: twice the room, until it fits
|
|
61
|
+
const grown = new Uint8Array(inbox.length * 2);
|
|
62
|
+
grown.set(inbox);
|
|
63
|
+
inbox = grown;
|
|
64
|
+
}
|
|
65
|
+
else if (held === 0 && inbox.length > kept) {
|
|
66
|
+
inbox = new Uint8Array(room);
|
|
67
|
+
}
|
|
68
|
+
return filled;
|
|
69
|
+
};
|
|
70
|
+
// What the session writes while it reads: its frames wait for the read's
|
|
71
|
+
// end, since a call of the core made meanwhile would write over the bytes
|
|
72
|
+
// being read.
|
|
73
|
+
let reading = false;
|
|
74
|
+
const waiting = [];
|
|
75
|
+
// reads what a call of the core wrote, and on while the core fills the
|
|
76
|
+
// room, since no wake comes for what waits; then sends what was written
|
|
77
|
+
// meanwhile
|
|
78
|
+
const readOn = (written) => {
|
|
79
|
+
reading = true;
|
|
80
|
+
try {
|
|
81
|
+
let filled = written === undefined || read(written);
|
|
82
|
+
while (filled && connection !== null) {
|
|
83
|
+
const free = inbox.length - held;
|
|
84
|
+
filled = read(Number(lib.symbols.tinystore_recv(connection, 0, ptr(inbox, held), free)));
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
finally {
|
|
88
|
+
reading = false;
|
|
89
|
+
}
|
|
90
|
+
const next = waiting.shift();
|
|
91
|
+
if (next !== undefined) {
|
|
92
|
+
send(next);
|
|
93
|
+
}
|
|
94
|
+
};
|
|
95
|
+
const send = (bytes) => {
|
|
96
|
+
if (connection === null) {
|
|
97
|
+
return;
|
|
98
|
+
}
|
|
99
|
+
if (reading) {
|
|
100
|
+
waiting.push(bytes);
|
|
101
|
+
return;
|
|
102
|
+
}
|
|
103
|
+
const free = inbox.length - held;
|
|
104
|
+
const written = lib.symbols.tinystore_send(connection, ptr(bytes), bytes.length, ptr(inbox, held), free);
|
|
105
|
+
readOn(Number(written));
|
|
106
|
+
};
|
|
107
|
+
const wake = new JSCallback(() => readOn(undefined), {
|
|
108
|
+
args: [FFIType.ptr],
|
|
109
|
+
returns: FFIType.void,
|
|
110
|
+
threadsafe: true,
|
|
111
|
+
});
|
|
112
|
+
const failed = Number(lib.symbols.tinystore_open(ptr(name), name.length, ptr(options), options.length, wake, null, ptr(opened), ptr(failure), failure.length));
|
|
113
|
+
if (failed > 0) {
|
|
114
|
+
const message = new TextDecoder().decode(failure.subarray(0, failed));
|
|
115
|
+
wake.close();
|
|
116
|
+
lib.close();
|
|
117
|
+
throw new ClosedError(`cannot open ${dir}: ${message}`);
|
|
118
|
+
}
|
|
119
|
+
connection = Number(opened[0]);
|
|
120
|
+
return {
|
|
121
|
+
write: send,
|
|
122
|
+
close() {
|
|
123
|
+
if (connection === null) {
|
|
124
|
+
return;
|
|
125
|
+
}
|
|
126
|
+
const closing = connection;
|
|
127
|
+
connection = null;
|
|
128
|
+
lib.symbols.tinystore_close(closing);
|
|
129
|
+
wake.close();
|
|
130
|
+
events.end(new ClosedError('the store closed'));
|
|
131
|
+
},
|
|
132
|
+
};
|
|
133
|
+
}
|
package/dist/runtime/shared.d.ts
CHANGED
|
@@ -23,3 +23,9 @@ export declare function spawnDetached(argv: string[]): Child;
|
|
|
23
23
|
export declare const stderrKept: number;
|
|
24
24
|
export declare function lastLines(text: string, n?: number): string;
|
|
25
25
|
export declare function exitedWith(code: number, stderr: string): ClosedError;
|
|
26
|
+
/**
|
|
27
|
+
* The package that carries this platform's executable and libraries:
|
|
28
|
+
* `@tinyshed/tinystore-linux-x64`, or `-musl` after it where Linux's C
|
|
29
|
+
* library is musl, as npm chose it by its `libc` at install.
|
|
30
|
+
*/
|
|
31
|
+
export declare function platformPackage(): string;
|
package/dist/runtime/shared.js
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
// sidecar started through node:child_process, which both implement, and the
|
|
3
3
|
// last lines of a child's stderr.
|
|
4
4
|
import { spawn } from 'node:child_process';
|
|
5
|
+
import { readdirSync } from 'node:fs';
|
|
5
6
|
import { ClosedError } from '../errors.js';
|
|
6
7
|
export function address(endpoint) {
|
|
7
8
|
if (endpoint.startsWith('unix://')) {
|
|
@@ -43,3 +44,21 @@ export function lastLines(text, n = 5) {
|
|
|
43
44
|
export function exitedWith(code, stderr) {
|
|
44
45
|
return new ClosedError(`the private server exited with ${code}${stderr === '' ? '' : `: ${lastLines(stderr)}`}`);
|
|
45
46
|
}
|
|
47
|
+
/**
|
|
48
|
+
* The package that carries this platform's executable and libraries:
|
|
49
|
+
* `@tinyshed/tinystore-linux-x64`, or `-musl` after it where Linux's C
|
|
50
|
+
* library is musl, as npm chose it by its `libc` at install.
|
|
51
|
+
*/
|
|
52
|
+
export function platformPackage() {
|
|
53
|
+
const musl = process.platform === 'linux' && runsOnMusl();
|
|
54
|
+
return `@tinyshed/tinystore-${process.platform}-${process.arch}${musl ? '-musl' : ''}`;
|
|
55
|
+
}
|
|
56
|
+
/** Whether this Linux runs musl: its loader, `ld-musl-<arch>.so.1`, is in /lib. */
|
|
57
|
+
function runsOnMusl() {
|
|
58
|
+
try {
|
|
59
|
+
return readdirSync('/lib').some(name => name.startsWith('ld-musl-'));
|
|
60
|
+
}
|
|
61
|
+
catch {
|
|
62
|
+
return false;
|
|
63
|
+
}
|
|
64
|
+
}
|
package/dist/runtime.d.ts
CHANGED
|
@@ -43,6 +43,9 @@ export interface Runtime {
|
|
|
43
43
|
readFile(path: string): Promise<Uint8Array | undefined>;
|
|
44
44
|
/** The executable a name finds on PATH. */
|
|
45
45
|
which(name: string): string | undefined;
|
|
46
|
-
/**
|
|
47
|
-
|
|
46
|
+
/**
|
|
47
|
+
* A file this platform's package carries, `bin/tinystore` or the core's
|
|
48
|
+
* library in `lib/`, installed beside this one; undefined without it.
|
|
49
|
+
*/
|
|
50
|
+
packaged(file: string): string | undefined;
|
|
48
51
|
}
|
package/dist/search.d.ts
ADDED
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
import type { Link } from './connection.ts';
|
|
2
|
+
import { type Open, type Via } from './handles.ts';
|
|
3
|
+
import type { Key } from './wire/codec.ts';
|
|
4
|
+
/** How an index reads its documents and combines its halves, given where it opens. */
|
|
5
|
+
export interface IndexOptions {
|
|
6
|
+
/** the fields whose words are read, each with what a word found there weighs, or a list that weighs each 1 */
|
|
7
|
+
fields?: Record<string, number> | readonly string[] | undefined;
|
|
8
|
+
/** the fields a search may keep its hits to */
|
|
9
|
+
filters?: readonly string[] | undefined;
|
|
10
|
+
/** a misspelt word read as the index's nearest; on unless false */
|
|
11
|
+
typoTolerance?: boolean | undefined;
|
|
12
|
+
/** a vector the program's model gives each document, and `recall` for searches from clusters */
|
|
13
|
+
vectors?: {
|
|
14
|
+
dimensions: number;
|
|
15
|
+
recall?: number | undefined;
|
|
16
|
+
} | undefined;
|
|
17
|
+
/** how a search by words and a vector at once combines them unless it says */
|
|
18
|
+
hybrid?: {
|
|
19
|
+
vectorWeight?: number | undefined;
|
|
20
|
+
rerank?: boolean | undefined;
|
|
21
|
+
} | undefined;
|
|
22
|
+
/** whether a change that needs every document read again waits for `store.reindex` */
|
|
23
|
+
rebuild?: 'automatic' | 'manual' | undefined;
|
|
24
|
+
}
|
|
25
|
+
/** A vector the program's own model gave, of the index's dimensions. */
|
|
26
|
+
export type Vector = readonly number[] | Float32Array;
|
|
27
|
+
/** A value a `where` matches: text, a number, a boolean, one of a list, a range, or `null` for none. */
|
|
28
|
+
export type WhereValue = string | number | bigint | boolean | null | readonly (string | number | bigint | boolean)[] | {
|
|
29
|
+
gt?: number | bigint;
|
|
30
|
+
gte?: number | bigint;
|
|
31
|
+
lt?: number | bigint;
|
|
32
|
+
lte?: number | bigint;
|
|
33
|
+
};
|
|
34
|
+
/**
|
|
35
|
+
* What a search keeps its hits to, as sqldb's `where` reads an object: each
|
|
36
|
+
* field equal to its value, one of a list, within a range, or `null` for
|
|
37
|
+
* none, every field named passing; `search.or` and `search.and` group them.
|
|
38
|
+
*/
|
|
39
|
+
export type Where = Readonly<Record<string, WhereValue>> | Group;
|
|
40
|
+
/** Conditions joined: `search.or(…)`, `search.and(…)`. */
|
|
41
|
+
export declare class Group {
|
|
42
|
+
readonly join: 'or' | 'and';
|
|
43
|
+
readonly parts: readonly Where[];
|
|
44
|
+
/** A group comes from `search.or` and `search.and`. */
|
|
45
|
+
constructor(join: 'or' | 'and', parts: readonly Where[]);
|
|
46
|
+
}
|
|
47
|
+
/** What a search asks: its words, its vector, or both, and what it keeps to. */
|
|
48
|
+
export interface Query {
|
|
49
|
+
text?: string | undefined;
|
|
50
|
+
vector?: Vector | undefined;
|
|
51
|
+
where?: Where | undefined;
|
|
52
|
+
/** this search's way of combining its words and its vector, in place of the index's */
|
|
53
|
+
hybrid?: {
|
|
54
|
+
vectorWeight?: number | undefined;
|
|
55
|
+
rerank?: boolean | undefined;
|
|
56
|
+
} | undefined;
|
|
57
|
+
/** 10 unless said; offset and limit together 1000 at most */
|
|
58
|
+
limit?: number | undefined;
|
|
59
|
+
offset?: number | undefined;
|
|
60
|
+
}
|
|
61
|
+
/** A document a search found, and the score that ordered it among this search's hits. */
|
|
62
|
+
export interface Hit<T> {
|
|
63
|
+
id: string;
|
|
64
|
+
value: T;
|
|
65
|
+
score: number;
|
|
66
|
+
}
|
|
67
|
+
/** What a search found, the best first, and the text it read in fact when a word was misspelt. */
|
|
68
|
+
export interface Found<T> {
|
|
69
|
+
hits: Hit<T>[];
|
|
70
|
+
corrected?: string | undefined;
|
|
71
|
+
}
|
|
72
|
+
/** Where an index stands: serving what it was opened with, read again beside it, or a rebuild that failed. */
|
|
73
|
+
export type IndexStatus = {
|
|
74
|
+
state: 'ready';
|
|
75
|
+
} | {
|
|
76
|
+
state: 'rebuilding';
|
|
77
|
+
done: number;
|
|
78
|
+
} | {
|
|
79
|
+
state: 'failed';
|
|
80
|
+
error: string;
|
|
81
|
+
};
|
|
82
|
+
/** An index as `store.indexes()` lists it. */
|
|
83
|
+
export interface IndexInfo {
|
|
84
|
+
name: string;
|
|
85
|
+
documents: number;
|
|
86
|
+
vectors: number;
|
|
87
|
+
/** when a program last opened it */
|
|
88
|
+
opened?: Date | undefined;
|
|
89
|
+
status: IndexStatus;
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* How a table's index reads a table of its database: its columns of text,
|
|
93
|
+
* those a search may filter by, and a column of vectors the program fills.
|
|
94
|
+
*/
|
|
95
|
+
export interface TableIndexOptions {
|
|
96
|
+
/** the table whose rows the index holds and follows */
|
|
97
|
+
table: string;
|
|
98
|
+
/** the column of unique values a row is found by, the table's primary key unless said */
|
|
99
|
+
key?: string | undefined;
|
|
100
|
+
/** the columns whose words are read, each with what a word found there weighs, or a list that weighs each 1 */
|
|
101
|
+
fields: Record<string, number> | readonly string[];
|
|
102
|
+
/** the columns a search may keep its hits to; a boolean is the 1 or 0 SQLite keeps */
|
|
103
|
+
filters?: readonly string[] | undefined;
|
|
104
|
+
typoTolerance?: boolean | undefined;
|
|
105
|
+
/** a column of blobs of little-endian floats, one a row or null, and `recall` for searches from clusters */
|
|
106
|
+
vectors?: {
|
|
107
|
+
column: string;
|
|
108
|
+
dimensions: number;
|
|
109
|
+
recall?: number | undefined;
|
|
110
|
+
} | undefined;
|
|
111
|
+
hybrid?: {
|
|
112
|
+
vectorWeight?: number | undefined;
|
|
113
|
+
rerank?: boolean | undefined;
|
|
114
|
+
} | undefined;
|
|
115
|
+
rebuild?: 'automatic' | 'manual' | undefined;
|
|
116
|
+
}
|
|
117
|
+
/** A document `setMany` sets: its id, its value, and its vector, or `null` for none. */
|
|
118
|
+
export interface IndexDocument<T> {
|
|
119
|
+
id: Key;
|
|
120
|
+
value: T;
|
|
121
|
+
vector?: Vector | null | undefined;
|
|
122
|
+
}
|
|
123
|
+
/** The calls of an index that a call names. */
|
|
124
|
+
type Method = 'search.set' | 'search.setMany' | 'search.delete' | 'search.get' | 'search.search' | 'search.status';
|
|
125
|
+
/** What every index answers: its searches, and where it stands. */
|
|
126
|
+
declare abstract class Searchable<T> {
|
|
127
|
+
#private;
|
|
128
|
+
readonly name: string;
|
|
129
|
+
constructor(via: Via, name: string, open: Open);
|
|
130
|
+
/**
|
|
131
|
+
* The best ten, or `limit`, by `text`'s words, a string being a search
|
|
132
|
+
* by its words; by a vector; or by both, each half's best hundred scaled
|
|
133
|
+
* and summed at the index's `vectorWeight`; kept to what `where` passes.
|
|
134
|
+
* Of equal scores the one set first comes first.
|
|
135
|
+
*/
|
|
136
|
+
search(query: string | Query): Promise<Found<T>>;
|
|
137
|
+
/** Where the index stands; a search never waits, and answers by the settings it serves. */
|
|
138
|
+
status(): Promise<IndexStatus>;
|
|
139
|
+
/** Waits until the index serves the settings it was opened with; a rebuild that failed throws why. */
|
|
140
|
+
ready(): Promise<void>;
|
|
141
|
+
protected call(method: Method, body: (handle: number) => Uint8Array, idempotence: 'read' | 'write'): Promise<Uint8Array>;
|
|
142
|
+
}
|
|
143
|
+
/** Documents of one type by id, found again by their words, vectors or both: `store.index(name, options)`. */
|
|
144
|
+
export declare class SearchIndex<T> extends Searchable<T> {
|
|
145
|
+
/** An index comes from `store.index` and `store.reindex`. */
|
|
146
|
+
constructor(link: Link, name: string, open: Uint8Array);
|
|
147
|
+
/**
|
|
148
|
+
* Sets the document `id` to `value`, replacing it whole; the next search
|
|
149
|
+
* sees it. On an index with vectors a set gives its vector, or `null` for
|
|
150
|
+
* a document only its words find.
|
|
151
|
+
*/
|
|
152
|
+
set(id: Key, value: T, options?: {
|
|
153
|
+
vector?: Vector | null | undefined;
|
|
154
|
+
}): Promise<void>;
|
|
155
|
+
/** Sets every document in one commit, all of them or none: 1,000 and 16 MiB at most. */
|
|
156
|
+
setMany(documents: readonly IndexDocument<T>[]): Promise<void>;
|
|
157
|
+
/** Deletes the document `id`; says whether there was one. */
|
|
158
|
+
delete(id: Key): Promise<boolean>;
|
|
159
|
+
/** The document `id`, or undefined. */
|
|
160
|
+
get(id: Key): Promise<T | undefined>;
|
|
161
|
+
}
|
|
162
|
+
/**
|
|
163
|
+
* A table's rows found again by their words, vectors or both, each hit's
|
|
164
|
+
* value its row as `db.all` reads it: `db.searchIndex(name, options)`. The
|
|
165
|
+
* table owns the rows, and every change of one reaches the index in the
|
|
166
|
+
* commit that makes it.
|
|
167
|
+
*/
|
|
168
|
+
export declare class TableIndex<T> extends Searchable<T> {
|
|
169
|
+
}
|
|
170
|
+
/** The open of a table's index: its name, its table and settings, and its database's handle. */
|
|
171
|
+
export declare function tableIndexOpen(name: string, options: TableIndexOptions, database?: number, reindex?: boolean): Uint8Array;
|
|
172
|
+
/** The open of an index: its name, settings, and whether it reads the index again. */
|
|
173
|
+
export declare function indexOpen(name: string, options?: IndexOptions, reindex?: boolean): Uint8Array;
|
|
174
|
+
/** Drops an index and every document it holds; says whether there was one. */
|
|
175
|
+
export declare function dropIndex(link: Link, name: string): Promise<boolean>;
|
|
176
|
+
/** Every index the store holds, by name. */
|
|
177
|
+
export declare function listIndexes(link: Link): Promise<IndexInfo[]>;
|
|
178
|
+
/**
|
|
179
|
+
* A `where` as the wire takes it, a JSON list of conditions joined by and:
|
|
180
|
+
* `{"eq":[path,value]}`, `{"in":[path,[values]]}`, `{"missing":path}`,
|
|
181
|
+
* `{"range":[path,{"gt"|"gte"|"lt"|"lte":n}]}`, `{"or":[…]}`, `{"and":[…]}`.
|
|
182
|
+
*/
|
|
183
|
+
export declare function whereJson(where: Where): string;
|
|
184
|
+
/** The conditions a `where` groups: `search.or({ category: 'boots' }, { tags: 'sale' })`. */
|
|
185
|
+
export declare const search: {
|
|
186
|
+
or: (...parts: Where[]) => Group;
|
|
187
|
+
and: (...parts: Where[]) => Group;
|
|
188
|
+
};
|
|
189
|
+
export {};
|