@tinyshed/tinystore 0.1.0-rc.5 → 0.1.0-rc.7
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/config.d.ts
CHANGED
|
@@ -1,110 +1,233 @@
|
|
|
1
1
|
import type { Link } from './connection.ts';
|
|
2
2
|
import { type StandardSchemaV1 } from './schema.ts';
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
import { type DurationText } from './time.ts';
|
|
4
|
+
declare const mark = "~setting";
|
|
5
|
+
declare const layerMark = "~layer";
|
|
6
|
+
type Kind = 'text' | 'integer' | 'number' | 'boolean' | 'duration' | 'object' | 'any' | {
|
|
7
|
+
list: Item;
|
|
6
8
|
};
|
|
7
|
-
type
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
9
|
+
type Item = ({
|
|
10
|
+
kind: Kind;
|
|
11
|
+
} & Rules) | {
|
|
12
|
+
group: Group;
|
|
13
|
+
};
|
|
14
|
+
type Group = Record<string, Node>;
|
|
15
|
+
type Node = Described | {
|
|
16
|
+
group: Group;
|
|
17
|
+
};
|
|
18
|
+
interface Rules {
|
|
19
|
+
min?: number;
|
|
20
|
+
max?: number;
|
|
21
|
+
oneOf?: string[];
|
|
22
|
+
}
|
|
23
|
+
interface Described extends Rules {
|
|
24
|
+
kind: Kind;
|
|
25
|
+
default?: unknown;
|
|
26
|
+
required?: boolean;
|
|
27
|
+
live?: boolean;
|
|
28
|
+
secret?: boolean;
|
|
17
29
|
}
|
|
18
30
|
/**
|
|
19
|
-
* A
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
23
|
-
* db: { url: secret('DATABASE_URL'), pool: 10 }
|
|
24
|
-
* ```
|
|
31
|
+
* A setting its declaration says more of than a default would: its rules, a
|
|
32
|
+
* secret, one a layer must give, or one that may change while the program
|
|
33
|
+
* runs. `V` is what the program reads it as, `Live` whether it may change,
|
|
34
|
+
* and `Given` whether it has a default or is required, as a declaration needs.
|
|
25
35
|
*/
|
|
26
|
-
export
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
36
|
+
export interface Setting<V, Live extends boolean = false, Given extends boolean = true, IsSecret extends boolean = false> {
|
|
37
|
+
readonly [mark]: Described;
|
|
38
|
+
/** what the program reads it as; nothing at run time */
|
|
39
|
+
readonly '~value'?: V;
|
|
40
|
+
readonly '~live'?: Live;
|
|
41
|
+
readonly '~given'?: Given;
|
|
42
|
+
readonly '~secret'?: IsSecret;
|
|
43
|
+
}
|
|
44
|
+
/** A setting's text that prints as *** wherever it goes; `reveal` gives it. */
|
|
45
|
+
export declare class Secret {
|
|
46
|
+
#private;
|
|
47
|
+
constructor(text: string);
|
|
48
|
+
/** The secret's text, where the program hands it to what needs it. */
|
|
49
|
+
reveal(): string;
|
|
50
|
+
toString(): string;
|
|
51
|
+
toJSON(): string;
|
|
52
|
+
}
|
|
53
|
+
/** What a program reads of a declaration: a setting as its value, a group as its settings. */
|
|
54
|
+
export type Value<D> = D extends Setting<infer V, boolean, boolean, boolean> ? V : D extends string ? string : D extends number ? number : D extends boolean ? boolean : D extends null ? null : D extends readonly (infer I)[] ? readonly Value<I>[] : D extends object ? {
|
|
55
|
+
readonly [K in keyof D]: Value<D[K]>;
|
|
56
|
+
} : never;
|
|
57
|
+
type LiveIn<D> = D extends Setting<unknown, infer L, boolean, boolean> ? L : D extends readonly unknown[] ? false : D extends object ? true extends {
|
|
58
|
+
[K in keyof D]: LiveIn<D[K]>;
|
|
59
|
+
}[keyof D] ? true : false : false;
|
|
60
|
+
/** The live settings a change may name, each as the program reads it, at any depth. */
|
|
61
|
+
export type Changes<D> = {
|
|
62
|
+
readonly [K in keyof D as LiveIn<D[K]> extends true ? K : never]?: D[K] extends Setting<infer V, true, boolean, boolean> ? V : Changes<D[K]>;
|
|
63
|
+
};
|
|
64
|
+
/** An object in code over the declaration: any of its settings, at any depth, a secret as text. */
|
|
65
|
+
export type Overlay<D> = {
|
|
66
|
+
readonly [K in keyof D]?: D[K] extends Setting<infer V, boolean, boolean, boolean> ? V extends Secret ? string : V : D[K] extends readonly unknown[] ? Value<D[K]> : D[K] extends object ? Overlay<D[K]> : Value<D[K]>;
|
|
67
|
+
};
|
|
68
|
+
/** A file a config reads: TOML, YAML or JSON by its extension. */
|
|
69
|
+
export interface FileLayer {
|
|
70
|
+
readonly [layerMark]: 'file';
|
|
71
|
+
readonly path: string;
|
|
72
|
+
readonly optional: boolean;
|
|
73
|
+
}
|
|
74
|
+
/** The environment a config reads. */
|
|
75
|
+
export interface EnvLayer {
|
|
76
|
+
readonly [layerMark]: 'env';
|
|
34
77
|
readonly prefix: string;
|
|
78
|
+
/** a setting's own variable, by its path */
|
|
79
|
+
readonly vars: Readonly<Record<string, string>>;
|
|
35
80
|
readonly files: readonly string[];
|
|
36
|
-
|
|
81
|
+
readonly from: Readonly<Record<string, string | undefined>> | undefined;
|
|
37
82
|
}
|
|
38
|
-
/**
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
/**
|
|
45
|
-
export
|
|
46
|
-
readonly
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
/**
|
|
50
|
-
|
|
51
|
-
/**
|
|
52
|
-
|
|
53
|
-
|
|
83
|
+
/** A layer of a config's list: an object in code, a file, the environment, or nothing. */
|
|
84
|
+
export type Layer<D> = FileLayer | EnvLayer | Overlay<D> | false | null | undefined;
|
|
85
|
+
export interface FileOptions {
|
|
86
|
+
/** a file that may be absent: then it declares nothing, and explain says so */
|
|
87
|
+
optional?: boolean | undefined;
|
|
88
|
+
}
|
|
89
|
+
/** Settings' own variables by their paths: `{ port: 'PORT', db: { url: 'DATABASE_URL' } }`. */
|
|
90
|
+
export interface Vars {
|
|
91
|
+
readonly [key: string]: string | Vars;
|
|
92
|
+
}
|
|
93
|
+
export interface EnvOptions {
|
|
94
|
+
/** a setting's variable of its own, in place of its prefixed one */
|
|
95
|
+
vars?: Vars | undefined;
|
|
96
|
+
/** .env files, whose variables count where the process has none; Bun reads .env itself */
|
|
97
|
+
files?: readonly string[] | undefined;
|
|
98
|
+
/** these variables in place of the process's, the only environment read, as a test gives them */
|
|
99
|
+
from?: Readonly<Record<string, string | undefined>> | undefined;
|
|
100
|
+
}
|
|
101
|
+
export interface ConfigOptions<V> {
|
|
102
|
+
/**
|
|
103
|
+
* the program's own check of the whole value, at open and before a change
|
|
104
|
+
* is kept: a Standard Schema such as zod's or valibot's, or a function
|
|
105
|
+
* that throws
|
|
106
|
+
*/
|
|
107
|
+
validate?: StandardSchemaV1 | ((value: V) => unknown) | undefined;
|
|
108
|
+
/** refuses to open while a kept change no longer fits, rather than ignoring it and saying so */
|
|
109
|
+
strict?: boolean | undefined;
|
|
110
|
+
}
|
|
111
|
+
export interface UpdateOptions {
|
|
112
|
+
/** keeps the change only while the config is at this version, else ConflictError */
|
|
113
|
+
ifVersion?: number | undefined;
|
|
114
|
+
}
|
|
115
|
+
/** A setting's line of explain. */
|
|
116
|
+
export interface ExplainLine {
|
|
117
|
+
readonly path: string;
|
|
118
|
+
/** as JSON, a duration spelled, a secret as *** */
|
|
119
|
+
readonly value: string;
|
|
120
|
+
/** the layer that gave it: APP_PORT, app.yaml, layer 2, the declaration, a change */
|
|
121
|
+
readonly from: string;
|
|
122
|
+
/** the values it went over, newest first */
|
|
123
|
+
readonly over: string;
|
|
124
|
+
}
|
|
125
|
+
/** Every setting's line, for console.table, and what was read and not used. */
|
|
126
|
+
export type Explained = readonly ExplainLine[] & {
|
|
127
|
+
readonly notes: readonly string[];
|
|
54
128
|
};
|
|
55
|
-
type
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
129
|
+
type Token = StringConstructor | NumberConstructor | BooleanConstructor;
|
|
130
|
+
type Of<T> = T extends StringConstructor ? string : T extends NumberConstructor ? number : T extends BooleanConstructor ? boolean : never;
|
|
131
|
+
type Primitive = string | number | boolean;
|
|
132
|
+
type Widened<V> = V extends string ? string : V extends number ? number : V extends boolean ? boolean : V extends readonly (infer I)[] ? Widened<I>[] : V;
|
|
133
|
+
/** The bounds of a number: the smallest and the largest it may be. */
|
|
134
|
+
export interface Bounds {
|
|
135
|
+
min?: number | undefined;
|
|
136
|
+
max?: number | undefined;
|
|
137
|
+
}
|
|
138
|
+
/** The bounds of a duration, each a duration's text. */
|
|
139
|
+
export interface DurationBounds {
|
|
140
|
+
min?: DurationText | undefined;
|
|
141
|
+
max?: DurationText | undefined;
|
|
67
142
|
}
|
|
143
|
+
/** A list's default and how many items it holds at least and at most. */
|
|
144
|
+
export interface ListOptions<V> extends Bounds {
|
|
145
|
+
default?: readonly V[] | undefined;
|
|
146
|
+
}
|
|
147
|
+
/**
|
|
148
|
+
* A setting that prints as *** wherever it goes and that only a layer gives:
|
|
149
|
+
* `secret(String)` must be given, `secret('')` has a default.
|
|
150
|
+
*/
|
|
151
|
+
export declare function secret(given: StringConstructor | string): Setting<Secret, false, true, true>;
|
|
152
|
+
/** A setting with no default: a layer must give it, or the config does not open. */
|
|
153
|
+
export declare function required<T extends Token>(type: T): Setting<Of<T>>;
|
|
154
|
+
export declare function required<V>(rule: Setting<V, false, false>): Setting<V>;
|
|
155
|
+
/**
|
|
156
|
+
* A setting that may change while the program runs: its change is kept in
|
|
157
|
+
* the store, goes over every layer until it is reset, and reaches every
|
|
158
|
+
* process. `live(100)`, `live(int(100, { min: 0 }))`, `live(required(String))`.
|
|
159
|
+
*/
|
|
160
|
+
export declare function live<V>(rule: Setting<V, false, true>): Setting<V, true>;
|
|
161
|
+
export declare function live<const V extends Primitive | readonly Primitive[]>(value: V): Setting<Widened<V>, true>;
|
|
162
|
+
/** A whole number in its bounds: `int(8080, { min: 1, max: 65535 })`; `int({ min: 1 })` goes in required. */
|
|
163
|
+
export declare function int(rules?: Bounds): Setting<number, false, false>;
|
|
164
|
+
export declare function int(fallback: number, rules?: Bounds): Setting<number>;
|
|
165
|
+
/**
|
|
166
|
+
* One of a set of texts, its default first: `oneOf('info', ['debug', 'warn', 'error'])`
|
|
167
|
+
* reads as 'info' | 'debug' | 'warn' | 'error'; `oneOf(['eu', 'us'])` goes in required.
|
|
168
|
+
*/
|
|
169
|
+
export declare function oneOf<const O extends readonly [string, ...string[]]>(values: O): Setting<O[number], false, false>;
|
|
170
|
+
export declare function oneOf<const T extends string, const O extends readonly string[]>(fallback: T, others: O): Setting<T | O[number]>;
|
|
171
|
+
/** A duration, read as one is written: `duration('30s')`, `duration({ max: '1h' })` in required. */
|
|
172
|
+
export declare function duration(rules?: DurationBounds): Setting<DurationText, false, false>;
|
|
173
|
+
export declare function duration(fallback: DurationText, rules?: DurationBounds): Setting<DurationText>;
|
|
174
|
+
/**
|
|
175
|
+
* A list: of `String`, `Number` or `Boolean`, of a rule, or of groups, each
|
|
176
|
+
* item checked; its `min` and `max` count its items. A list written as a
|
|
177
|
+
* value, `['localhost']`, needs no `list`.
|
|
178
|
+
*/
|
|
179
|
+
export declare function list<T extends Token>(item: T, options?: ListOptions<Of<T>>): Setting<readonly Of<T>[]>;
|
|
180
|
+
export declare function list<V>(item: Setting<V, false, boolean>, options?: ListOptions<V>): Setting<readonly V[]>;
|
|
181
|
+
export declare function list<G extends object>(item: G, options?: ListOptions<Value<G>>): Setting<readonly Value<G>[]>;
|
|
182
|
+
/** A file a config reads: TOML, YAML or JSON by its extension, a relative path the program's. */
|
|
183
|
+
export declare function file(path: string, options?: FileOptions): FileLayer;
|
|
184
|
+
/**
|
|
185
|
+
* The environment a config reads: `env('APP')` reads APP_ and each setting's
|
|
186
|
+
* path in upper snake case, `APP_LIMITS_RPS` for limits.rps.
|
|
187
|
+
*/
|
|
188
|
+
export declare function env(prefix: string, options?: EnvOptions): EnvLayer;
|
|
68
189
|
/**
|
|
69
|
-
* A
|
|
70
|
-
* Python
|
|
190
|
+
* A setting's variable: the prefix and its path in upper snake case, as Go,
|
|
191
|
+
* Python and the core name it (testdata/config/env.json).
|
|
71
192
|
*
|
|
72
193
|
* 'APP', 'limits.maxRps' → APP_LIMITS_MAX_RPS
|
|
73
194
|
*/
|
|
74
195
|
export declare function envName(prefix: string, path: string): string;
|
|
75
196
|
/**
|
|
76
|
-
*
|
|
77
|
-
*
|
|
78
|
-
* quotes reading \n \r \t \" and \\, single quotes reading nothing, a quoted
|
|
79
|
-
* value over lines; a later name wins.
|
|
197
|
+
* A program's settings as one typed value, read from memory: open one with
|
|
198
|
+
* `store.config(name, [declaration, ...layers])`.
|
|
80
199
|
*/
|
|
81
|
-
export declare
|
|
82
|
-
/** A config: open it with `store.kv.config(name, defaults, ...layers)`. */
|
|
83
|
-
export declare class Config<T extends object> {
|
|
200
|
+
export declare class Config<D> {
|
|
84
201
|
#private;
|
|
85
202
|
readonly name: string;
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
203
|
+
private constructor();
|
|
204
|
+
/** Opens a config from its list: the declaration first, then its layers in order. */
|
|
205
|
+
static open<D>(link: Link, name: string, layers: readonly unknown[], options: ConfigOptions<Value<D>>): Promise<Config<D>>;
|
|
206
|
+
/** The settings as they are now: a read of memory, so read it where it is used. */
|
|
207
|
+
get value(): Value<D>;
|
|
208
|
+
/** The version of the changes the value holds, which `ifVersion` takes. */
|
|
209
|
+
get version(): number;
|
|
210
|
+
/**
|
|
211
|
+
* Changes live settings: the ones `changes` names are kept in the store, go
|
|
212
|
+
* over every layer until they are reset, and reach every handle of the
|
|
213
|
+
* config. The value they make passes validate first; all are kept or none.
|
|
214
|
+
*/
|
|
215
|
+
update(changes: Changes<D>, options?: UpdateOptions): Promise<void>;
|
|
216
|
+
/** Drops the change kept of the setting or the group at `path`, or of every setting. */
|
|
217
|
+
reset(path?: string): Promise<void>;
|
|
218
|
+
/**
|
|
219
|
+
* Calls `watcher` with the settings now, then with each change and the value
|
|
220
|
+
* before it, made in this process or another. It returns the call that stops it.
|
|
221
|
+
*/
|
|
222
|
+
watch(watcher: (next: Value<D>, previous: Value<D> | undefined) => void): () => void;
|
|
223
|
+
/** Every setting with its value, the layer that gave it and what it went over. */
|
|
224
|
+
explain(): Explained;
|
|
92
225
|
/**
|
|
93
|
-
*
|
|
94
|
-
*
|
|
95
|
-
*
|
|
96
|
-
*
|
|
226
|
+
* Stops following the config: the store closes. It resolves once the
|
|
227
|
+
* stream that follows it is cancelled, so that the store's connection
|
|
228
|
+
* ends after its CANCEL: a stream the server still ran would keep a
|
|
229
|
+
* private child, or a sidecar's connection, draining for ten seconds.
|
|
97
230
|
*/
|
|
98
|
-
|
|
99
|
-
/** Forgets what update kept for paths, each a field or a group of them; all of it without paths. */
|
|
100
|
-
reset(...paths: string[]): Promise<void>;
|
|
101
|
-
/** Calls fn with the config now and after each change, whoever made it; the function it returns stops that. */
|
|
102
|
-
watch(fn: (value: T) => void): () => void;
|
|
103
|
-
/** Where each field's value came from, and why a kept value is left out. */
|
|
104
|
-
sources(): Source[];
|
|
105
|
-
/** Follows the config's changes until the store closes; resolves once the first state is read. */
|
|
106
|
-
start(): Promise<void>;
|
|
107
|
-
/** Stops following the config, as the store does when it closes. */
|
|
108
|
-
stop(): void;
|
|
231
|
+
stop(): Promise<void>;
|
|
109
232
|
}
|
|
110
233
|
export {};
|