@tinyshed/tinystore 0.1.0-rc.4 → 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
package/dist/json.d.ts
ADDED
package/dist/json.js
ADDED
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
// JSON as JSON.parse reads it, but an integer past 2^53 a bigint, as an SQL
|
|
2
|
+
// answer's is: a number would round it, and an id of 19 digits must come back
|
|
3
|
+
// as it went in.
|
|
4
|
+
/** Reads `text`, one JSON value; what is no JSON throws a SyntaxError, as JSON.parse does. */
|
|
5
|
+
export function parseJson(text) {
|
|
6
|
+
const reading = new Reading(text);
|
|
7
|
+
const value = reading.value();
|
|
8
|
+
reading.space();
|
|
9
|
+
if (reading.at !== text.length) {
|
|
10
|
+
throw new SyntaxError(`JSON past its value at ${reading.at}`);
|
|
11
|
+
}
|
|
12
|
+
return value;
|
|
13
|
+
}
|
|
14
|
+
const number = /-?(?:0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?/y;
|
|
15
|
+
class Reading {
|
|
16
|
+
at = 0;
|
|
17
|
+
#text;
|
|
18
|
+
constructor(text) {
|
|
19
|
+
this.#text = text;
|
|
20
|
+
}
|
|
21
|
+
space() {
|
|
22
|
+
while (this.at < this.#text.length && ' \t\n\r'.includes(this.#text[this.at])) {
|
|
23
|
+
this.at++;
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
value() {
|
|
27
|
+
this.space();
|
|
28
|
+
const first = this.#text[this.at];
|
|
29
|
+
switch (first) {
|
|
30
|
+
case '{':
|
|
31
|
+
return this.#object();
|
|
32
|
+
case '[':
|
|
33
|
+
return this.#array();
|
|
34
|
+
case '"':
|
|
35
|
+
return this.#string();
|
|
36
|
+
}
|
|
37
|
+
for (const [word, value] of [
|
|
38
|
+
['true', true],
|
|
39
|
+
['false', false],
|
|
40
|
+
['null', null],
|
|
41
|
+
]) {
|
|
42
|
+
if (this.#text.startsWith(word, this.at)) {
|
|
43
|
+
this.at += word.length;
|
|
44
|
+
return value;
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
return this.#number();
|
|
48
|
+
}
|
|
49
|
+
#object() {
|
|
50
|
+
const object = {};
|
|
51
|
+
this.at++;
|
|
52
|
+
this.space();
|
|
53
|
+
if (this.#text[this.at] === '}') {
|
|
54
|
+
this.at++;
|
|
55
|
+
return object;
|
|
56
|
+
}
|
|
57
|
+
for (;;) {
|
|
58
|
+
this.space();
|
|
59
|
+
const key = this.#string();
|
|
60
|
+
this.space();
|
|
61
|
+
this.#expect(':');
|
|
62
|
+
object[key] = this.value();
|
|
63
|
+
this.space();
|
|
64
|
+
if (this.#text[this.at] === '}') {
|
|
65
|
+
this.at++;
|
|
66
|
+
return object;
|
|
67
|
+
}
|
|
68
|
+
this.#expect(',');
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
#array() {
|
|
72
|
+
const array = [];
|
|
73
|
+
this.at++;
|
|
74
|
+
this.space();
|
|
75
|
+
if (this.#text[this.at] === ']') {
|
|
76
|
+
this.at++;
|
|
77
|
+
return array;
|
|
78
|
+
}
|
|
79
|
+
for (;;) {
|
|
80
|
+
array.push(this.value());
|
|
81
|
+
this.space();
|
|
82
|
+
if (this.#text[this.at] === ']') {
|
|
83
|
+
this.at++;
|
|
84
|
+
return array;
|
|
85
|
+
}
|
|
86
|
+
this.#expect(',');
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
/** A string, its escapes read by JSON.parse, which knows them all. */
|
|
90
|
+
#string() {
|
|
91
|
+
this.#expect('"', false);
|
|
92
|
+
let end = this.at + 1;
|
|
93
|
+
while (end < this.#text.length && this.#text[end] !== '"') {
|
|
94
|
+
end += this.#text[end] === '\\' ? 2 : 1;
|
|
95
|
+
}
|
|
96
|
+
if (end >= this.#text.length) {
|
|
97
|
+
throw new SyntaxError(`a JSON string not ended, from ${this.at}`);
|
|
98
|
+
}
|
|
99
|
+
const read = JSON.parse(this.#text.slice(this.at, end + 1));
|
|
100
|
+
this.at = end + 1;
|
|
101
|
+
return read;
|
|
102
|
+
}
|
|
103
|
+
#number() {
|
|
104
|
+
number.lastIndex = this.at;
|
|
105
|
+
const found = number.exec(this.#text);
|
|
106
|
+
if (found === null) {
|
|
107
|
+
throw new SyntaxError(`no JSON value at ${this.at}`);
|
|
108
|
+
}
|
|
109
|
+
this.at += found[0].length;
|
|
110
|
+
const read = Number(found[0]);
|
|
111
|
+
const whole = found[1] === undefined && found[2] === undefined;
|
|
112
|
+
return whole && !Number.isSafeInteger(read) ? BigInt(found[0]) : read;
|
|
113
|
+
}
|
|
114
|
+
#expect(char, skip = true) {
|
|
115
|
+
if (this.#text[this.at] !== char) {
|
|
116
|
+
throw new SyntaxError(`JSON wants ${char} at ${this.at}`);
|
|
117
|
+
}
|
|
118
|
+
if (skip) {
|
|
119
|
+
this.at++;
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
}
|
package/dist/kv.d.ts
CHANGED
|
@@ -1,286 +1,173 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import type
|
|
3
|
-
import { type Page, type Settled } from './handles.ts';
|
|
4
|
-
import { Limiter, type LimiterOptions, type Rate } from './limiter.ts';
|
|
5
|
-
import { Once, type OnceOptions } from './once.ts';
|
|
6
|
-
import { Quota } from './quota.ts';
|
|
7
|
-
import { type StandardSchemaV1 } from './schema.ts';
|
|
1
|
+
import type { Idempotence, Link } from './connection.ts';
|
|
2
|
+
import { type Home, type Open, type Via } from './handles.ts';
|
|
8
3
|
import { type Duration, type Time } from './time.ts';
|
|
9
|
-
import { type Key, type Raw } from './wire/codec.ts';
|
|
10
|
-
import { KvCall,
|
|
4
|
+
import { type Key, type Raw, type Written } from './wire/codec.ts';
|
|
5
|
+
import { KvCall, KvEntry, type Method } from './wire/protocol.ts';
|
|
11
6
|
/**
|
|
12
|
-
* How a bucket keeps
|
|
13
|
-
* so that
|
|
7
|
+
* How a bucket keeps a value that is not JSON, as the core keeps a Rust type,
|
|
8
|
+
* so that every language reads the others' rows:
|
|
14
9
|
*
|
|
15
|
-
* '
|
|
16
|
-
* '
|
|
17
|
-
* '
|
|
18
|
-
* '
|
|
19
|
-
* '
|
|
20
|
-
* '
|
|
21
|
-
* 'bool' 1 or 0 bool, bool
|
|
22
|
-
* 'none' nothing: a bucket of them is a set struct{}, None
|
|
10
|
+
* 'string' its UTF-8 bytes
|
|
11
|
+
* 'bytes' the bytes
|
|
12
|
+
* 'int' an integer a number holds exactly
|
|
13
|
+
* 'bigint' an integer past what a number holds
|
|
14
|
+
* 'float' its eight bytes, big-endian, every bit kept
|
|
15
|
+
* 'bool' 1 or 0
|
|
23
16
|
*/
|
|
24
|
-
export type
|
|
25
|
-
interface KindValue {
|
|
26
|
-
json: unknown;
|
|
27
|
-
string: string;
|
|
28
|
-
bytes: Uint8Array;
|
|
29
|
-
int: number;
|
|
30
|
-
bigint: bigint;
|
|
31
|
-
float: number;
|
|
32
|
-
bool: boolean;
|
|
33
|
-
none: null;
|
|
34
|
-
}
|
|
17
|
+
export type ValueType = 'string' | 'bytes' | 'int' | 'bigint' | 'float' | 'bool';
|
|
35
18
|
export interface BucketOptions {
|
|
36
|
-
/**
|
|
37
|
-
|
|
38
|
-
/**
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
defaultTtl?: Duration;
|
|
19
|
+
/** a key expires this long after it was written, unless its write gives its own */
|
|
20
|
+
ttl?: Duration | undefined;
|
|
21
|
+
/** a key expires this long after it was last read or written; not beside ttl */
|
|
22
|
+
idle?: Duration | undefined;
|
|
23
|
+
/** how values are kept when they are not JSON */
|
|
24
|
+
type?: ValueType | undefined;
|
|
43
25
|
/**
|
|
44
|
-
*
|
|
45
|
-
*
|
|
26
|
+
* Keeps every value sealed with the store's encryption key, as a password or a
|
|
27
|
+
* token is kept: the file holds what nobody reads without the key. The
|
|
28
|
+
* store seals and opens, so this program never holds the key. A key is not
|
|
29
|
+
* sealed, so a secret is a value and never a key, and a name keeps whether
|
|
30
|
+
* it is encrypted.
|
|
46
31
|
*/
|
|
47
|
-
|
|
32
|
+
encrypted?: boolean | undefined;
|
|
48
33
|
}
|
|
49
34
|
export interface WriteOptions {
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
/**
|
|
35
|
+
/** the key expires this long from now */
|
|
36
|
+
ttl?: Duration | undefined;
|
|
37
|
+
/** the key expires at this time */
|
|
38
|
+
expiresAt?: Time | undefined;
|
|
39
|
+
/** writes only while the key is at this version: ConflictError otherwise */
|
|
53
40
|
ifVersion?: string;
|
|
54
41
|
}
|
|
55
|
-
export interface Entry<
|
|
56
|
-
|
|
42
|
+
export interface Entry<T> {
|
|
43
|
+
key: string;
|
|
44
|
+
value: T;
|
|
57
45
|
/** compared only for equality: give it back to ifVersion */
|
|
58
46
|
version: string;
|
|
59
|
-
/**
|
|
60
|
-
|
|
47
|
+
/** undefined for a key that never expires */
|
|
48
|
+
expiresAt: Date | undefined;
|
|
61
49
|
}
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
50
|
+
/** A page of a branch's keys, and where the next starts when there is one. */
|
|
51
|
+
export interface Page<T> {
|
|
52
|
+
entries: Entry<T>[];
|
|
53
|
+
next: string | undefined;
|
|
65
54
|
}
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
decode(raw: Raw): V | Promise<V>;
|
|
70
|
-
}
|
|
71
|
-
export declare class Kv {
|
|
72
|
-
#private;
|
|
73
|
-
constructor(link: Link);
|
|
74
|
-
/**
|
|
75
|
-
* The config name, shaped and typed as its defaults, then each layer over
|
|
76
|
-
* the one before: a file's values, `fromEnv`, and what update kept over
|
|
77
|
-
* them all. It resolves once the server's state is read, and follows every
|
|
78
|
-
* change from then on, whoever makes it, until the store closes.
|
|
79
|
-
*
|
|
80
|
-
* ```ts
|
|
81
|
-
* const cfg = await store.kv.config('app', {
|
|
82
|
-
* port: 8080,
|
|
83
|
-
* db: { url: secret('DATABASE_URL'), pool: 10 },
|
|
84
|
-
* }, file, fromEnv('APP'))
|
|
85
|
-
* cfg.value.port // APP_PORT=3000 makes it 3000
|
|
86
|
-
* await cfg.update({ port: 4000 }) // kept: 4000 after a restart too
|
|
87
|
-
* ```
|
|
88
|
-
*/
|
|
89
|
-
config<D extends object>(name: string, defaults: D, ...layers: ConfigLayer<ConfigValue<D>>[]): Promise<Config<ConfigValue<D>>>;
|
|
90
|
-
/** A limiter of requests by key: `store.kv.limiter('api', { rate: '100/s', burst: 20 })`. */
|
|
91
|
-
limiter(name: string, options: LimiterOptions): Limiter;
|
|
92
|
-
/**
|
|
93
|
-
* A quota of uses by key, its windows by name, each counted from a key's
|
|
94
|
-
* first use and all of them together or none:
|
|
95
|
-
* `store.kv.quota('ai', { session: '100/5h', weekly: '300/7d' })`.
|
|
96
|
-
*/
|
|
97
|
-
quota<W extends string>(name: string, windows: Record<W, Rate>): Quota<W>;
|
|
55
|
+
export interface CountersOptions {
|
|
56
|
+
/** a counter lasts this long from its first add */
|
|
57
|
+
ttl?: Duration | undefined;
|
|
98
58
|
/**
|
|
99
|
-
*
|
|
100
|
-
*
|
|
59
|
+
* keeps counts in memory and writes them this often, so that an add costs
|
|
60
|
+
* no commit and a crash loses at most this span: attempts and hits, not money
|
|
101
61
|
*/
|
|
102
|
-
|
|
103
|
-
/** Answers each read is checked by, zod's, valibot's or another Standard Schema. */
|
|
104
|
-
once<S extends StandardSchemaV1>(name: string, schema: S, options?: OnceOptions): Once<StandardSchemaV1.InferOutput<S>>;
|
|
105
|
-
/** Stops following configs, as the store does when it closes. */
|
|
106
|
-
stop(): void;
|
|
107
|
-
/** A bucket of JSON values of type T. */
|
|
108
|
-
bucket<T = unknown>(name: string, options?: BucketOptions): Bucket<T>;
|
|
109
|
-
/** A bucket of values kept as their kind says. */
|
|
110
|
-
bucket<K extends Kind>(name: string, kind: K, options?: BucketOptions): Bucket<KindValue[K]>;
|
|
111
|
-
/** A bucket of JSON values each read is checked by, zod's, valibot's or another Standard Schema. */
|
|
112
|
-
bucket<S extends StandardSchemaV1>(name: string, schema: S, options?: BucketOptions): Bucket<StandardSchemaV1.InferOutput<S>>;
|
|
113
|
-
/** Counters, an int64 a key read as a number, 0 when absent. */
|
|
114
|
-
counters(name: string, options?: CounterOptions): Counters<number>;
|
|
115
|
-
/** Counters read as bigints, for values past 2^53. */
|
|
116
|
-
counters(name: string, kind: 'bigint', options?: CounterOptions): Counters<bigint>;
|
|
117
|
-
/**
|
|
118
|
-
* Runs the calls fn asks for in one transaction, all or none: the calls of
|
|
119
|
-
* buckets it takes through withTx, whose promises settle once the batch
|
|
120
|
-
* has. fn returns before anything is sent, since no transaction is held
|
|
121
|
-
* across the network: a call cannot wait for another's answer inside it.
|
|
122
|
-
* What fn returns comes back answered, an array's promises each:
|
|
123
|
-
*
|
|
124
|
-
* const [code] = await store.kv.batch(tx => [codes.withTx(tx).take(k), used.withTx(tx).set(k, 1)])
|
|
125
|
-
*/
|
|
126
|
-
batch<const T = void>(fn: (tx: Batch) => T): Promise<Settled<T>>;
|
|
127
|
-
/**
|
|
128
|
-
* Reads the gets and hases fn asks for from one snapshot, and gives back
|
|
129
|
-
* what fn returns, answered as batch answers it:
|
|
130
|
-
*
|
|
131
|
-
* const [profile, prefs] = await store.kv.view(tx => [a.withTx(tx).get(id), b.withTx(tx).get(id)])
|
|
132
|
-
*/
|
|
133
|
-
view<const T = void>(fn: (tx: Batch) => T): Promise<Settled<T>>;
|
|
134
|
-
/**
|
|
135
|
-
* Runs fn as one transaction that reads before it decides what to write,
|
|
136
|
-
* as Go's Tx does, without holding the writer across the network: a read
|
|
137
|
-
* goes to the server at once, a write waits, and when fn returns the writes
|
|
138
|
-
* commit in one batch that first checks every key fn read is still as it
|
|
139
|
-
* read it. When another write changed one meanwhile, fn runs again, five
|
|
140
|
-
* times at most before ConflictError, so it does nothing else that must
|
|
141
|
-
* happen once. It gives back what fn returns.
|
|
142
|
-
*
|
|
143
|
-
* const userId = await store.kv.tx(async tx => {
|
|
144
|
-
* const userId = await codes.withTx(tx).take(digest(code))
|
|
145
|
-
* if (userId === undefined) throw new InvalidCode()
|
|
146
|
-
* sessions.withTx(tx).of(userId).set(digest(token), { device })
|
|
147
|
-
* return userId
|
|
148
|
-
* })
|
|
149
|
-
*/
|
|
150
|
-
tx<T>(fn: (tx: Tx) => T | Promise<T>): Promise<T>;
|
|
151
|
-
}
|
|
152
|
-
/** The calls a batch or a view gathered, in their order. */
|
|
153
|
-
export declare class Batch {
|
|
154
|
-
#private;
|
|
155
|
-
readonly kind: 'batch' | 'view';
|
|
156
|
-
readonly calls: Recorded[];
|
|
157
|
-
constructor(kind: 'batch' | 'view');
|
|
158
|
-
/** Whether the promise is one of this batch's calls', rather than an async function's. */
|
|
159
|
-
made(promise: Promise<unknown>): boolean;
|
|
160
|
-
record<T>(call: Omit<Recorded, 'settle'>, settle: (entry: Entry<Raw> & {
|
|
161
|
-
found: boolean;
|
|
162
|
-
}) => Promise<T>): Promise<T>;
|
|
163
|
-
close(): void;
|
|
62
|
+
flushEvery?: Duration | undefined;
|
|
164
63
|
}
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
}) => Promise<void>;
|
|
172
|
-
fail?: (err: unknown) => void;
|
|
64
|
+
/** Turns a bucket's values into what a row keeps, and back. */
|
|
65
|
+
export interface Values<T> {
|
|
66
|
+
encode(value: T): Raw;
|
|
67
|
+
decode(raw: Raw): T;
|
|
68
|
+
/** decode returns the bytes it was given, which must then be a copy of the answer's */
|
|
69
|
+
readonly keeps?: boolean;
|
|
173
70
|
}
|
|
174
|
-
/** What a
|
|
175
|
-
interface
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
/**
|
|
184
|
-
* A transaction of store.kv.tx: a read goes to the server at once and is
|
|
185
|
-
* remembered with its version, so that a key read again answers the same; a
|
|
186
|
-
* write waits for the commit, and a key read after it answers what it wrote.
|
|
187
|
-
*/
|
|
188
|
-
export declare class Tx implements Recorder {
|
|
189
|
-
#private;
|
|
190
|
-
constructor(link: Link);
|
|
191
|
-
record<T>(call: Omit<Recorded, 'settle'>, settle: (entry: Found) => Promise<T>): Promise<T>;
|
|
192
|
-
/**
|
|
193
|
-
* Sends what fn wrote in one batch, after a check of each key it read: a
|
|
194
|
-
* key it found at the version it found, a key it found absent still
|
|
195
|
-
* absent. A tx that only read checks its reads from one snapshot.
|
|
196
|
-
*/
|
|
197
|
-
commit(): Promise<void>;
|
|
198
|
-
/** Whether the commit failed for a key fn read that changed since, which another run reads anew. */
|
|
199
|
-
stale(err: unknown): boolean;
|
|
71
|
+
/** What a transaction needs of a handle it takes in. */
|
|
72
|
+
export interface Parts {
|
|
73
|
+
readonly link: Link;
|
|
74
|
+
readonly name: string;
|
|
75
|
+
readonly open: Open;
|
|
76
|
+
readonly openMethod: Method;
|
|
77
|
+
readonly under: readonly string[];
|
|
78
|
+
/** the database whose file keeps the handle; the store's own when undefined */
|
|
79
|
+
readonly home?: Home | undefined;
|
|
200
80
|
}
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
*/
|
|
205
|
-
export declare class Bucket<
|
|
81
|
+
export declare function partsOf(handle: object): (Parts & {
|
|
82
|
+
values?: Values<unknown>;
|
|
83
|
+
}) | undefined;
|
|
84
|
+
/** A bucket's values under one branch of owners, the bucket's own when there are none. */
|
|
85
|
+
export declare class Bucket<T> {
|
|
206
86
|
#private;
|
|
207
87
|
readonly name: string;
|
|
208
|
-
constructor(link: Link, name: string, open: Uint8Array, values: Values<V>, owners: (string | Uint8Array)[]);
|
|
209
|
-
/** The branch below this one that the owners name. */
|
|
210
|
-
of(...owners: Key[]): Bucket<V>;
|
|
211
88
|
/**
|
|
212
|
-
*
|
|
213
|
-
*
|
|
89
|
+
* Buckets come from `store.bucket`, `db.bucket` and their `under`; inside
|
|
90
|
+
* a database's transaction, from `tx.with(bucket)`, whose calls go through
|
|
91
|
+
* the transaction.
|
|
214
92
|
*/
|
|
215
|
-
|
|
93
|
+
constructor(link: Link, name: string, open: Open, values: Values<T>, under: readonly string[], home?: Home, via?: Via);
|
|
94
|
+
/** The branch the owners name below this one: whose keys these are. */
|
|
95
|
+
under(...owners: Key[]): Bucket<T>;
|
|
216
96
|
/** The key's value, undefined when it holds none. */
|
|
217
|
-
get(key: Key): Promise<
|
|
97
|
+
get(key: Key): Promise<T | undefined>;
|
|
218
98
|
/** The key's value with its version and expiry, undefined when it holds none. */
|
|
219
|
-
|
|
99
|
+
entry(key: Key): Promise<Entry<T> | undefined>;
|
|
220
100
|
has(key: Key): Promise<boolean>;
|
|
221
|
-
/** Writes the value; a
|
|
222
|
-
set(key: Key, value:
|
|
223
|
-
/** Writes the value and gives its new version and expiry. */
|
|
224
|
-
setEntry(key: Key, value: V, options?: WriteOptions): Promise<Entry<V>>;
|
|
101
|
+
/** Writes the value; a key that exists keeps its expiry unless the options give one. */
|
|
102
|
+
set(key: Key, value: T, options?: WriteOptions): Promise<void>;
|
|
225
103
|
/** Writes the value only where no live key is, and says whether it did. */
|
|
226
|
-
|
|
104
|
+
create(key: Key, value: T, options?: Omit<WriteOptions, 'ifVersion'>): Promise<boolean>;
|
|
105
|
+
/** Puts the key in a bucket used as a set; false when it was there. */
|
|
106
|
+
add(key: Key, options?: Omit<WriteOptions, 'ifVersion'>): Promise<boolean>;
|
|
227
107
|
/**
|
|
228
|
-
*
|
|
229
|
-
*
|
|
108
|
+
* Reads the value and removes the key in one commit: of two callers taking
|
|
109
|
+
* a one-time code at once, one gets it.
|
|
230
110
|
*/
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
}>;
|
|
235
|
-
delete(key: Key, options?: Pick<WriteOptions, 'ifVersion'>): Promise<void>;
|
|
111
|
+
take(key: Key, options?: Pick<WriteOptions, 'ifVersion'>): Promise<T | undefined>;
|
|
112
|
+
/** Removes the key, and says whether it was there. */
|
|
113
|
+
delete(key: Key, options?: Pick<WriteOptions, 'ifVersion'>): Promise<boolean>;
|
|
236
114
|
/**
|
|
237
|
-
*
|
|
238
|
-
*
|
|
115
|
+
* Gives a live key a new expiry, a span from now or a time, keeping its
|
|
116
|
+
* value; false when it holds none.
|
|
239
117
|
*/
|
|
240
|
-
|
|
241
|
-
/** Gives a live key a new expiry, keeping its value and version; false when it holds none. */
|
|
242
|
-
touch(key: Key, options: WriteOptions): Promise<boolean>;
|
|
118
|
+
expire(key: Key, when: Duration | Date, options?: Pick<WriteOptions, 'ifVersion'>): Promise<boolean>;
|
|
243
119
|
/** Removes this branch's keys and every branch under it, at once however many. */
|
|
244
120
|
clear(): Promise<void>;
|
|
245
|
-
/** One page of this branch's own keys, in the byte order of their text
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
}): Promise<Page<
|
|
121
|
+
/** One page of this branch's own keys, in the byte order of their text: `"10"` before `"9"`. */
|
|
122
|
+
list(options?: {
|
|
123
|
+
limit?: number | undefined;
|
|
124
|
+
after?: Key | undefined;
|
|
125
|
+
}): Promise<Page<T>>;
|
|
250
126
|
/**
|
|
251
|
-
* Walks this branch's own keys a page at a time, holding
|
|
252
|
-
*
|
|
127
|
+
* Walks this branch's own keys a page at a time, holding nothing between
|
|
128
|
+
* pages: a key written during the walk may or may not be met. It renews no
|
|
129
|
+
* idle key.
|
|
253
130
|
*/
|
|
254
131
|
all(options?: {
|
|
255
|
-
limit?: number;
|
|
256
|
-
}): AsyncGenerator<
|
|
257
|
-
}
|
|
258
|
-
/** A bucket's calls inside a batch or a view. */
|
|
259
|
-
export declare class BucketTx<V> {
|
|
260
|
-
#private;
|
|
261
|
-
constructor(tx: Recorder, open: Uint8Array, values: Values<V>, owners: (string | Uint8Array)[]);
|
|
262
|
-
of(...owners: Key[]): BucketTx<V>;
|
|
263
|
-
get(key: Key): Promise<V | undefined>;
|
|
264
|
-
has(key: Key): Promise<boolean>;
|
|
265
|
-
set(key: Key, value: V, options?: WriteOptions): Promise<void>;
|
|
266
|
-
delete(key: Key, options?: Pick<WriteOptions, 'ifVersion'>): Promise<void>;
|
|
267
|
-
take(key: Key): Promise<V | undefined>;
|
|
132
|
+
limit?: number | undefined;
|
|
133
|
+
}): AsyncGenerator<Entry<T>>;
|
|
268
134
|
}
|
|
269
|
-
/**
|
|
270
|
-
|
|
271
|
-
* max change in one write; a sum past the int64 range is refused.
|
|
272
|
-
*/
|
|
273
|
-
export declare class Counters<N extends number | bigint> {
|
|
135
|
+
/** Numbers by key that only add up: 0 for one never added to or expired. */
|
|
136
|
+
export declare class Counters {
|
|
274
137
|
#private;
|
|
275
138
|
readonly name: string;
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
/** Adds n, 1 unless given, and gives the new
|
|
280
|
-
add(key: Key, n?: number | bigint): Promise<
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
delete(key: Key): Promise<
|
|
139
|
+
/** Counters come from `store.counters` and their `under`. */
|
|
140
|
+
constructor(link: Link, name: string, open: Uint8Array, under: readonly string[]);
|
|
141
|
+
under(...owners: Key[]): Counters;
|
|
142
|
+
/** Adds n, 1 unless given, and gives the new count. */
|
|
143
|
+
add(key: Key, n?: number | bigint): Promise<number>;
|
|
144
|
+
get(key: Key): Promise<number>;
|
|
145
|
+
/** Removes the counter, and says whether it was there. */
|
|
146
|
+
delete(key: Key): Promise<boolean>;
|
|
147
|
+
/** Removes this branch's counters and every branch's under it. */
|
|
284
148
|
clear(): Promise<void>;
|
|
285
149
|
}
|
|
150
|
+
/**
|
|
151
|
+
* What a bucket's open sends, checked before anything leaves; `database` is
|
|
152
|
+
* the handle of the database whose file keeps it.
|
|
153
|
+
*/
|
|
154
|
+
export declare function bucketOpen(name: string, options?: BucketOptions, database?: number): Uint8Array;
|
|
155
|
+
export declare function countersOpen(name: string, options?: CountersOptions): Uint8Array;
|
|
156
|
+
type Call = Written<typeof KvCall.fields>;
|
|
157
|
+
type CallFields = Omit<Call, 'handle' | 'under'>;
|
|
158
|
+
/** Calls a method of a handle's branch on the link's connection, the handle opened there first. */
|
|
159
|
+
export declare function callOn(link: Link, openMethod: Method, open: Open, under: readonly string[], method: Method, fields: CallFields, idempotence: Idempotence): Promise<Uint8Array>;
|
|
160
|
+
/** A branch's owners as a call sends them: none at the root. */
|
|
161
|
+
export declare function underField(under: readonly string[]): string[] | undefined;
|
|
162
|
+
export declare function writeFields(options: WriteOptions | undefined): CallFields;
|
|
163
|
+
type Found = ReturnType<typeof KvEntry.decode>;
|
|
164
|
+
export declare function entryOf<T>(key: Key, found: Found, values: Values<T>): Entry<T>;
|
|
165
|
+
/** A version's bytes as text, each byte a code unit, so that any bytes go back as they came. */
|
|
166
|
+
export declare function versionText(version: Uint8Array | undefined): string;
|
|
167
|
+
export declare function versionBytes(version: string): Uint8Array;
|
|
168
|
+
/** A key or an owner as the server spells it: an integer its decimal text, bytes the text they spell. */
|
|
169
|
+
export declare function keyText(key: Key): string;
|
|
170
|
+
/** JSON, what a bucket keeps unless its type says otherwise; a row of nothing, a set's member, reads as null. */
|
|
171
|
+
export declare const jsonValues: Values<unknown>;
|
|
172
|
+
export declare function valuesOf(type: ValueType | undefined): Values<unknown>;
|
|
286
173
|
export {};
|