@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/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
- /** A value of T with any of its fields, at any depth, left out. */
4
- export type DeepPartial<T> = {
5
- [K in keyof T]?: T[K] extends readonly unknown[] ? T[K] : T[K] extends object ? DeepPartial<T[K]> : T[K];
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 Kind = 'string' | 'number' | 'boolean';
8
- /** A field of a config's defaults made by `secret` or `required`, in place of its value. */
9
- export declare class Setting<V> {
10
- readonly kind: Kind;
11
- /** absent for a field a layer has to give */
12
- readonly fallback: V | undefined;
13
- readonly secret: boolean;
14
- /** its own variable, read in place of the prefix and its path */
15
- readonly variable: string | undefined;
16
- constructor(kind: Kind, fallback: V | undefined, secret: boolean, variable: string | undefined);
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 secret: never kept by update, and shown as *** by sources(). It reads
20
- * its own variable when given one, and is required without a default.
21
- *
22
- * ```ts
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 declare function secret(variable?: string, fallback?: string): Setting<string>;
27
- /** A field a layer has to give, or the config does not open: a string unless kind says. */
28
- export declare function required(): Setting<string>;
29
- export declare function required(kind: StringConstructor): Setting<string>;
30
- export declare function required(kind: NumberConstructor): Setting<number>;
31
- export declare function required(kind: BooleanConstructor): Setting<boolean>;
32
- /** The environment as a layer of a config, which `fromEnv` makes. */
33
- export declare class FromEnv {
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
- constructor(prefix: string, files: readonly string[]);
81
+ readonly from: Readonly<Record<string, string | undefined>> | undefined;
37
82
  }
38
- /**
39
- * The environment as a config's layer: `fromEnv('APP')` reads db.pool from
40
- * APP_DB_POOL, and `fromEnv()` from DB_POOL. The .env files given are read
41
- * first, the process's own variables over them, a missing file skipped.
42
- */
43
- export declare function fromEnv(prefix?: string, ...files: string[]): FromEnv;
44
- /** A config's check, which `validate` makes. */
45
- export declare class Validate {
46
- readonly schema: StandardSchemaV1;
47
- constructor(schema: StandardSchemaV1);
48
- }
49
- /** Checks a config each time it is made, with zod's, valibot's or another Standard Schema. */
50
- export declare function validate(schema: StandardSchemaV1): Validate;
51
- /** A config's value, as its defaults make it: each Setting its value's type. */
52
- export type ConfigValue<D extends object> = {
53
- [K in keyof D]: FieldValue<D[K]>;
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 FieldValue<F> = F extends Setting<infer V> ? V : F extends readonly unknown[] | Date ? F : F extends object ? ConfigValue<F> : F;
56
- /** What a config takes after its defaults, each over the one before. */
57
- export type ConfigLayer<V> = DeepPartial<V> | FromEnv | Validate;
58
- /** Where a field's value came from. */
59
- export interface Source {
60
- path: string;
61
- /** its JSON, or *** for a secret */
62
- value: string;
63
- /** 'default', 'file', 'env NAME' or 'kept' */
64
- from: string;
65
- /** why a kept value is left out, when it is */
66
- ignored?: string;
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 field's variable: the prefix and its path in upper snake case, as Go's and
70
- * Python's configs name it.
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
- * The variables of a .env file, as Go's and Python's configs read one: NAME=value
77
- * lines, export before a name, # comments, a comment after a space, double
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 function parseDotenv(text: string): Record<string, string>;
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
- /** Configs come from `store.kv.config`, which lays their layers and waits for the first state. */
87
- constructor(link: Link, name: string, defaults: object);
88
- /** The config now, frozen: update changes it. */
89
- get value(): T;
90
- /** Lays each layer over the defaults, the one before it under it, and checks what is required. */
91
- lay(layers: readonly unknown[]): Promise<void>;
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
- * Changes the fields change names, at any depth; each one that changed is
94
- * checked, kept, and seen by every store watching the config. A change the
95
- * schema refuses, one of a secret, or one leaving a required field empty, is
96
- * InvalidError and keeps nothing.
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
- update(change: DeepPartial<T>): Promise<void>;
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 {};