@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.
Files changed (122) hide show
  1. package/README.md +37 -37
  2. package/bin/tinystore.js +12 -1
  3. package/dist/backup.d.ts +33 -0
  4. package/dist/backup.js +49 -0
  5. package/dist/blobs.d.ts +160 -79
  6. package/dist/blobs.js +510 -217
  7. package/dist/channels.d.ts +90 -0
  8. package/dist/channels.js +291 -0
  9. package/dist/clock.js +3 -3
  10. package/dist/config.d.ts +209 -86
  11. package/dist/config.js +581 -538
  12. package/dist/connection.d.ts +64 -2
  13. package/dist/connection.js +201 -16
  14. package/dist/console.d.ts +27 -3
  15. package/dist/console.js +165 -12
  16. package/dist/dotenv.d.ts +7 -0
  17. package/dist/dotenv.js +79 -0
  18. package/dist/errors.d.ts +61 -1
  19. package/dist/errors.js +81 -1
  20. package/dist/handles.d.ts +44 -2
  21. package/dist/handles.js +81 -2
  22. package/dist/index.d.ts +17 -11
  23. package/dist/index.js +5 -3
  24. package/dist/instruments.d.ts +177 -0
  25. package/dist/instruments.js +819 -0
  26. package/dist/jobs.d.ts +335 -239
  27. package/dist/jobs.js +716 -536
  28. package/dist/json.d.ts +2 -0
  29. package/dist/json.js +122 -0
  30. package/dist/kv.d.ts +130 -243
  31. package/dist/kv.js +273 -640
  32. package/dist/limits.d.ts +80 -0
  33. package/dist/limits.js +139 -0
  34. package/dist/locks.d.ts +62 -0
  35. package/dist/locks.js +237 -0
  36. package/dist/logger.d.ts +45 -9
  37. package/dist/logger.js +150 -38
  38. package/dist/metrics.d.ts +210 -209
  39. package/dist/metrics.js +319 -556
  40. package/dist/once.d.ts +19 -18
  41. package/dist/once.js +74 -63
  42. package/dist/query.d.ts +181 -0
  43. package/dist/query.js +788 -0
  44. package/dist/records.d.ts +241 -150
  45. package/dist/records.js +507 -291
  46. package/dist/runtime/addon.d.ts +14 -0
  47. package/dist/runtime/addon.js +69 -0
  48. package/dist/runtime/bun.js +5 -7
  49. package/dist/runtime/node.js +5 -7
  50. package/dist/runtime/pipe.d.ts +17 -0
  51. package/dist/runtime/pipe.js +133 -0
  52. package/dist/runtime/shared.d.ts +6 -0
  53. package/dist/runtime/shared.js +19 -0
  54. package/dist/runtime.d.ts +5 -2
  55. package/dist/search.d.ts +189 -0
  56. package/dist/search.js +281 -0
  57. package/dist/session.d.ts +31 -3
  58. package/dist/session.js +153 -41
  59. package/dist/sql.d.ts +228 -78
  60. package/dist/sql.js +745 -240
  61. package/dist/store.d.ts +244 -24
  62. package/dist/store.js +270 -67
  63. package/dist/time.d.ts +5 -1
  64. package/dist/time.js +22 -2
  65. package/dist/tx.d.ts +61 -0
  66. package/dist/tx.js +314 -0
  67. package/dist/wire/codec.d.ts +23 -7
  68. package/dist/wire/codec.js +56 -35
  69. package/dist/wire/frame.d.ts +2 -0
  70. package/dist/wire/frame.js +31 -14
  71. package/dist/wire/messages.d.ts +259 -0
  72. package/dist/wire/messages.js +22 -0
  73. package/dist/wire/msgpack.d.ts +49 -1
  74. package/dist/wire/msgpack.js +293 -56
  75. package/dist/wire/protocol.d.ts +2683 -0
  76. package/dist/wire/protocol.js +10846 -0
  77. package/package.json +39 -38
  78. package/src/backup.ts +81 -0
  79. package/src/blobs.ts +678 -301
  80. package/src/channels.ts +377 -0
  81. package/src/clock.ts +4 -4
  82. package/src/config.ts +902 -612
  83. package/src/connection.ts +279 -21
  84. package/src/console.ts +180 -12
  85. package/src/dotenv.ts +82 -0
  86. package/src/errors.ts +105 -0
  87. package/src/handles.ts +157 -8
  88. package/src/index.ts +158 -52
  89. package/src/instruments.ts +1042 -0
  90. package/src/jobs.ts +1017 -733
  91. package/src/json.ts +133 -0
  92. package/src/kv.ts +424 -847
  93. package/src/limits.ts +202 -0
  94. package/src/locks.ts +320 -0
  95. package/src/logger.ts +209 -40
  96. package/src/metrics.ts +557 -752
  97. package/src/once.ts +86 -83
  98. package/src/query.ts +1005 -0
  99. package/src/records.ts +795 -418
  100. package/src/runtime/addon.ts +99 -0
  101. package/src/runtime/bun.ts +5 -7
  102. package/src/runtime/node.ts +5 -7
  103. package/src/runtime/pipe.ts +178 -0
  104. package/src/runtime/shared.ts +20 -0
  105. package/src/runtime.ts +5 -2
  106. package/src/search.ts +480 -0
  107. package/src/session.ts +187 -41
  108. package/src/sql.ts +993 -306
  109. package/src/store.ts +473 -78
  110. package/src/time.ts +48 -3
  111. package/src/tx.ts +426 -0
  112. package/src/wire/codec.ts +78 -37
  113. package/src/wire/frame.ts +44 -14
  114. package/src/wire/messages.ts +25 -0
  115. package/src/wire/msgpack.ts +327 -56
  116. package/src/wire/protocol.ts +11709 -0
  117. package/dist/limiter.d.ts +0 -45
  118. package/dist/limiter.js +0 -68
  119. package/dist/quota.d.ts +0 -44
  120. package/dist/quota.js +0 -98
  121. package/src/limiter.ts +0 -99
  122. package/src/quota.ts +0 -137
package/dist/json.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ /** Reads `text`, one JSON value; what is no JSON throws a SyntaxError, as JSON.parse does. */
2
+ export declare function parseJson(text: string): unknown;
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 { Config, type ConfigLayer, type ConfigValue } from './config.ts';
2
- import type { Link } from './connection.ts';
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, methods } from './wire/messages.ts';
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 its values in a row, as Go's codecFor keeps a type's,
13
- * so that Go, Python and this SDK read each other's buckets:
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
- * 'json' JSON text, the default a Go struct, a Python dataclass
16
- * 'string' its UTF-8 bytes string, str
17
- * 'bytes' the bytes []byte, bytes
18
- * 'int' an integer, a number exactly int64, int
19
- * 'bigint' an integer int64, int
20
- * 'float' its eight bytes, big-endian float64, float
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 Kind = 'json' | 'string' | 'bytes' | 'int' | 'bigint' | 'float' | 'bool' | 'none';
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
- /** the expiry a key gets when it is written without its own */
37
- defaultTtl?: Duration;
38
- /** keeps a key this long from its last read; beside defaultTtl it is refused */
39
- sliding?: Duration;
40
- }
41
- export interface CounterOptions {
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
- * keeps changes in the server's memory between flushes this far apart, so
45
- * a crash may lose them: attempts and rates, not money
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
- loseAtMost?: Duration;
32
+ encrypted?: boolean | undefined;
48
33
  }
49
34
  export interface WriteOptions {
50
- ttl?: Duration;
51
- expireAt?: Time;
52
- /** writes only while the key is live at this version: ConflictError otherwise */
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<V> {
56
- value: V;
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
- /** when the key expires; undefined for one that never does */
60
- expires: Date | undefined;
47
+ /** undefined for a key that never expires */
48
+ expiresAt: Date | undefined;
61
49
  }
62
- export interface Scanned<V> extends Entry<V> {
63
- /** the key's text; bytes when it is not UTF-8 */
64
- key: string | Uint8Array;
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
- /** Encodes a bucket's values into what a row keeps, and back. */
67
- export interface Values<V> {
68
- encode(value: V): Raw | Promise<Raw>;
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
- * The answers a function gives once a key, JSON values of type T kept a
100
- * day unless defaultTtl says: `store.kv.once<Receipt>('charges')`.
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
- once<T = unknown>(name: string, options?: OnceOptions): Once<T>;
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
- interface Recorded {
166
- method: keyof typeof methods;
167
- open: Uint8Array;
168
- call: Parameters<typeof KvCall.encode>[0];
169
- settle: (entry: Entry<Raw> & {
170
- found: boolean;
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 bucket's calls inside a batch, a view or a tx go through. */
175
- interface Recorder {
176
- record<T>(call: Omit<Recorded, 'settle'>, settle: (entry: Entry<Raw> & {
177
- found: boolean;
178
- }) => Promise<T>): Promise<T>;
179
- }
180
- type Found = Entry<Raw> & {
181
- found: boolean;
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
- * A bucket's values under one branch of owners, the root when there are
203
- * none: `sessions.of(user.id).get(token)`.
204
- */
205
- export declare class Bucket<V> {
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
- * The bucket's calls inside a batch or a view, whose promises settle with
213
- * it, or inside a tx, whose reads answer at once and writes wait for it.
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
- withTx(tx: Batch | Tx): BucketTx<V>;
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<V | undefined>;
97
+ get(key: Key): Promise<T | undefined>;
218
98
  /** The key's value with its version and expiry, undefined when it holds none. */
219
- getEntry(key: Key): Promise<Entry<V> | undefined>;
99
+ entry(key: Key): Promise<Entry<T> | undefined>;
220
100
  has(key: Key): Promise<boolean>;
221
- /** Writes the value; a live key keeps its expiry unless the options give one. */
222
- set(key: Key, value: V, options?: WriteOptions): Promise<void>;
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
- setIfAbsent(key: Key, value: V, options?: Omit<WriteOptions, 'ifVersion'>): Promise<boolean>;
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
- * Writes the value only where no live key is: created says whether it did,
229
- * and entry is the new key's, or the live one's that was there.
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
- setEntryIfAbsent(key: Key, value: V, options?: Omit<WriteOptions, 'ifVersion'>): Promise<{
232
- created: boolean;
233
- entry: Entry<V>;
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
- * Reads the value and deletes the key in one write: a one-time code read
238
- * and burned. A value that no longer decodes has been taken all the same.
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
- take(key: Key, options?: Pick<WriteOptions, 'ifVersion'>): Promise<V | undefined>;
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
- scan(options?: {
247
- after?: Key;
248
- limit?: number;
249
- }): Promise<Page<Scanned<V>, string | Uint8Array>>;
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 no snapshot
252
- * between pages: a key written during the walk may or may not be met.
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<Scanned<V>>;
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
- * Counters under one branch: an int64 a key, 0 when absent, which add and
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
- constructor(link: Link, name: string, open: Uint8Array, big: boolean, owners: (string | Uint8Array)[]);
277
- of(...owners: Key[]): Counters<N>;
278
- get(key: Key): Promise<N>;
279
- /** Adds n, 1 unless given, and gives the new value. */
280
- add(key: Key, n?: number | bigint): Promise<N>;
281
- /** Keeps the larger of the counter and n, and gives it. */
282
- max(key: Key, n: number | bigint): Promise<N>;
283
- delete(key: Key): Promise<void>;
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 {};