@tinyshed/tinystore 0.1.0-rc.1

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 (100) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +262 -0
  3. package/bin/tinystore.js +50 -0
  4. package/dist/background.d.ts +30 -0
  5. package/dist/background.js +93 -0
  6. package/dist/blobs.d.ts +98 -0
  7. package/dist/blobs.js +299 -0
  8. package/dist/cancel.d.ts +14 -0
  9. package/dist/cancel.js +22 -0
  10. package/dist/clock.d.ts +21 -0
  11. package/dist/clock.js +35 -0
  12. package/dist/config.d.ts +60 -0
  13. package/dist/config.js +417 -0
  14. package/dist/connection.d.ts +78 -0
  15. package/dist/connection.js +405 -0
  16. package/dist/console.d.ts +48 -0
  17. package/dist/console.js +195 -0
  18. package/dist/errors.d.ts +103 -0
  19. package/dist/errors.js +158 -0
  20. package/dist/handles.d.ts +28 -0
  21. package/dist/handles.js +37 -0
  22. package/dist/index.d.ts +21 -0
  23. package/dist/index.js +7 -0
  24. package/dist/jobs.d.ts +304 -0
  25. package/dist/jobs.js +684 -0
  26. package/dist/kv.d.ts +283 -0
  27. package/dist/kv.js +815 -0
  28. package/dist/limiter.d.ts +45 -0
  29. package/dist/limiter.js +68 -0
  30. package/dist/logger.d.ts +96 -0
  31. package/dist/logger.js +243 -0
  32. package/dist/metrics.d.ts +249 -0
  33. package/dist/metrics.js +610 -0
  34. package/dist/once.d.ts +31 -0
  35. package/dist/once.js +116 -0
  36. package/dist/quota.d.ts +44 -0
  37. package/dist/quota.js +98 -0
  38. package/dist/records.d.ts +182 -0
  39. package/dist/records.js +346 -0
  40. package/dist/runtime/bun.d.ts +2 -0
  41. package/dist/runtime/bun.js +164 -0
  42. package/dist/runtime/node.d.ts +2 -0
  43. package/dist/runtime/node.js +157 -0
  44. package/dist/runtime/shared.d.ts +25 -0
  45. package/dist/runtime/shared.js +45 -0
  46. package/dist/runtime.d.ts +48 -0
  47. package/dist/runtime.js +4 -0
  48. package/dist/schema.d.ts +39 -0
  49. package/dist/schema.js +21 -0
  50. package/dist/session.d.ts +120 -0
  51. package/dist/session.js +546 -0
  52. package/dist/sql.d.ts +121 -0
  53. package/dist/sql.js +342 -0
  54. package/dist/store.d.ts +103 -0
  55. package/dist/store.js +153 -0
  56. package/dist/time.d.ts +35 -0
  57. package/dist/time.js +44 -0
  58. package/dist/trace.d.ts +18 -0
  59. package/dist/trace.js +22 -0
  60. package/dist/wire/codec.d.ts +90 -0
  61. package/dist/wire/codec.js +383 -0
  62. package/dist/wire/frame.d.ts +41 -0
  63. package/dist/wire/frame.js +102 -0
  64. package/dist/wire/messages.d.ts +1403 -0
  65. package/dist/wire/messages.js +472 -0
  66. package/dist/wire/msgpack.d.ts +93 -0
  67. package/dist/wire/msgpack.js +680 -0
  68. package/package.json +40 -0
  69. package/src/background.ts +108 -0
  70. package/src/blobs.ts +437 -0
  71. package/src/cancel.ts +26 -0
  72. package/src/clock.ts +45 -0
  73. package/src/config.ts +501 -0
  74. package/src/connection.ts +512 -0
  75. package/src/console.ts +228 -0
  76. package/src/errors.ts +211 -0
  77. package/src/handles.ts +68 -0
  78. package/src/index.ts +92 -0
  79. package/src/jobs.ts +963 -0
  80. package/src/kv.ts +1093 -0
  81. package/src/limiter.ts +99 -0
  82. package/src/logger.ts +326 -0
  83. package/src/metrics.ts +896 -0
  84. package/src/once.ts +142 -0
  85. package/src/quota.ts +137 -0
  86. package/src/records.ts +537 -0
  87. package/src/runtime/bun.ts +190 -0
  88. package/src/runtime/node.ts +177 -0
  89. package/src/runtime/shared.ts +61 -0
  90. package/src/runtime.ts +57 -0
  91. package/src/schema.ts +69 -0
  92. package/src/session.ts +665 -0
  93. package/src/sql.ts +478 -0
  94. package/src/store.ts +219 -0
  95. package/src/time.ts +87 -0
  96. package/src/trace.ts +32 -0
  97. package/src/wire/codec.ts +445 -0
  98. package/src/wire/frame.ts +139 -0
  99. package/src/wire/messages.ts +562 -0
  100. package/src/wire/msgpack.ts +712 -0
@@ -0,0 +1,249 @@
1
+ import { type Link } from './connection.ts';
2
+ import { type LimitError } from './errors.ts';
3
+ import { type Duration, type Time } from './time.ts';
4
+ export type SeriesKind = 'gauge' | 'counter';
5
+ /**
6
+ * What tells the series of one name apart: a host, a route, a status. A label
7
+ * whose name begins with __ is the store's own, and refused.
8
+ */
9
+ export type Labels = Record<string, string>;
10
+ export interface SeriesInput {
11
+ /** the metric: 'http_requests_total' */
12
+ name: string;
13
+ kind: SeriesKind;
14
+ labels?: Labels;
15
+ /** samples as [time, value] pairs, or as columns: unix milliseconds and their values */
16
+ samples: readonly (readonly [time: Time, value: number])[] | {
17
+ times: readonly number[] | BigInt64Array;
18
+ values: readonly number[] | Float64Array;
19
+ };
20
+ }
21
+ export interface Series {
22
+ name: string;
23
+ kind: SeriesKind;
24
+ labels: Labels;
25
+ /** unix milliseconds, in time order */
26
+ times: number[];
27
+ /** the values, their bits as they were ingested: -0 and a NaN's payload survive */
28
+ values: Float64Array;
29
+ }
30
+ /**
31
+ * The series of a name, of labels, or of both, each matched exactly, and
32
+ * their samples over the last `since` or from `from` to `to`.
33
+ *
34
+ * ```ts
35
+ * { name: 'cpu', since: '1h' } // the last hour of every cpu series
36
+ * { match: { host: 'web-1' }, from: start, to: end } // every series of web-1
37
+ * ```
38
+ */
39
+ /**
40
+ * What a label's value must be beyond equality, made by oneOf, noneOf or
41
+ * prefix: an object of the SDK's own, so that a stored value is never read as
42
+ * a query.
43
+ */
44
+ export declare class Condition {
45
+ readonly kind: 'one_of' | 'none_of' | 'prefix';
46
+ readonly values: readonly string[];
47
+ constructor(kind: Condition['kind'], values: readonly string[]);
48
+ }
49
+ /** The label is one of the values. */
50
+ export declare function oneOf(...values: string[]): Condition;
51
+ /** The label is none of the values, or the series has none. */
52
+ export declare function noneOf(...values: string[]): Condition;
53
+ /** The label's value begins with the prefix. */
54
+ export declare function prefix(start: string): Condition;
55
+ /** What a read or an aggregate would spend, each use beside its limit. */
56
+ export interface Plan {
57
+ series: number;
58
+ blocks: number;
59
+ /** the blocks an aggregate answers from their summaries, decoding none of their samples */
60
+ summarized: number;
61
+ bytes: number;
62
+ decoded: number;
63
+ limits: {
64
+ series: number;
65
+ blocks: number;
66
+ bytes: number;
67
+ decoded: number;
68
+ answered: number;
69
+ };
70
+ /** the limit the call would reach, which it would end with; undefined when it fits */
71
+ stops: LimitError | undefined;
72
+ }
73
+ export interface Range {
74
+ name?: string;
75
+ /** labels a series holds, each exactly */
76
+ match?: Labels;
77
+ /**
78
+ * labels under a condition: `{ status: oneOf('500', '502'), env: noneOf('dev'), host: prefix('api-') }`;
79
+ * a plain value is equality. A range of noneOf alone is refused, since it would scan every series.
80
+ */
81
+ where?: Record<string, Condition | string>;
82
+ /** the span before now the range covers: '1h', '15m', or milliseconds */
83
+ since?: Duration;
84
+ /** the range's start, included; the oldest sample kept when absent */
85
+ from?: Time;
86
+ /** excluded; the open end when absent */
87
+ to?: Time;
88
+ /** each narrows the server's: series matched, blocks decoded, bytes fetched, samples decoded, answered */
89
+ limits?: {
90
+ series?: number;
91
+ blocks?: number;
92
+ bytes?: number;
93
+ decoded?: number;
94
+ answered?: number;
95
+ };
96
+ }
97
+ /**
98
+ * Each computed exactly and rounded once, a group's too: avg is the mean of
99
+ * every sample, rate a counter's increase a second, delta a gauge's last
100
+ * sample less its first.
101
+ */
102
+ export type AggregateOp = 'count' | 'sum' | 'min' | 'max' | 'avg' | 'increase' | 'rate' | 'delta';
103
+ /**
104
+ * An aggregate's buckets and, to join series, what groups them: by these
105
+ * labels, or without them, each group one result. `by: []` joins every series
106
+ * of a name. A group never joins two names or two kinds.
107
+ */
108
+ export interface AggregateRange extends Range {
109
+ width: Duration;
110
+ op: AggregateOp;
111
+ by?: string[];
112
+ without?: string[];
113
+ }
114
+ export interface Bucket {
115
+ from: Date;
116
+ to: Date;
117
+ /** the samples it counted */
118
+ count: number;
119
+ /** the resets among them, a counter's */
120
+ resets: number;
121
+ /** computed exactly and rounded once */
122
+ value: number;
123
+ /** the value overflowed to an infinity */
124
+ overflow: boolean;
125
+ /** retention cut the bucket, which counted only its samples from the cutoff on */
126
+ partial: boolean;
127
+ }
128
+ export interface Aggregate {
129
+ name: string;
130
+ kind: SeriesKind;
131
+ labels: Labels;
132
+ /** only buckets holding samples */
133
+ buckets: Bucket[];
134
+ }
135
+ export declare class Metrics {
136
+ #private;
137
+ /** instruments' flushes that failed, and why the last did */
138
+ failures: number;
139
+ lastFailure: Error | undefined;
140
+ constructor(link: Link);
141
+ /** Stores series and their samples, all or none; a refused series is named by its labels. */
142
+ ingest(series: SeriesInput | readonly SeriesInput[]): Promise<void>;
143
+ /** Every sample of the series a range matches, exactly, read whole before the first leaves the server. */
144
+ read(range: Range): Promise<Series[]>;
145
+ /** Buckets of a width from the range's start, each computed exactly: a counter's increase counts its resets. */
146
+ aggregate(range: AggregateRange): Promise<Aggregate[]>;
147
+ /**
148
+ * What read(range), or aggregate(range) when it names an op, would spend
149
+ * of its limits, found without a payload fetched or a sample decoded: the
150
+ * series, the blocks, those an aggregate answers from their summaries, the
151
+ * bytes and the samples, beside the limits; stops is the LimitError the
152
+ * call would end with, undefined when it fits.
153
+ */
154
+ explain(range: Range & Partial<Pick<AggregateRange, 'width' | 'op' | 'by' | 'without'>>): Promise<Plan>;
155
+ /** Removes one series and everything it holds, whether it still reads or not. */
156
+ drop(series: {
157
+ name: string;
158
+ labels?: Labels;
159
+ }): Promise<{
160
+ found: boolean;
161
+ unreadableGroups: number;
162
+ }>;
163
+ /** A counter: its total since this process started, ingested every flush; a restart is a reset. */
164
+ counter(name: string): Counter;
165
+ /** A gauge: its value at each flush. */
166
+ gauge(name: string): Gauge;
167
+ /** A gauge read by a function at each flush; a function that throws skips that sample. */
168
+ gaugeFunc(name: string, read: () => number | Promise<number>): void;
169
+ /**
170
+ * A timer: how many durations it measured and their sum in milliseconds,
171
+ * ingested every flush as the counters name_count and name_sum, and the
172
+ * longest since the flush before as the gauge name_max, left out when it
173
+ * measured none. A range's mean is its sum's increase over its count's.
174
+ */
175
+ timer(name: string): Timer;
176
+ /**
177
+ * Ingests every instrument's value now, as the timer does every 15 s. A
178
+ * series the store refuses is left out from then on, said once, so that one
179
+ * bad instrument keeps no other out.
180
+ */
181
+ flush(): Promise<void>;
182
+ /** Stops flushing every 15 s and ingests the instruments' last values; the store's close calls it. */
183
+ stop(): Promise<void>;
184
+ get instruments(): number;
185
+ }
186
+ interface Instrument {
187
+ name: string;
188
+ kind: SeriesKind;
189
+ /** by the canonical spelling of each label set */
190
+ series: Map<string, {
191
+ labels: Labels;
192
+ value: number;
193
+ }>;
194
+ /** the spellings of the label sets the store refused, whose writes are left out */
195
+ refused: Set<string>;
196
+ read?: () => number | Promise<number>;
197
+ /** the error a gauge's function last threw, said once while it stays the same */
198
+ lastRead: string | undefined;
199
+ }
200
+ interface TimerInstrument {
201
+ name: string;
202
+ /** by the canonical spelling of each label set */
203
+ series: Map<string, Timing>;
204
+ refused: Set<string>;
205
+ }
206
+ interface Timing {
207
+ labels: Labels;
208
+ count: number;
209
+ /** milliseconds */
210
+ sum: number;
211
+ /** milliseconds, since the flush before */
212
+ longest: number;
213
+ /** since the flush before */
214
+ measured: boolean;
215
+ }
216
+ export declare class Counter {
217
+ #private;
218
+ constructor(instrument: Instrument, labels: Labels);
219
+ /** The counter of these labels besides its own: the same labels in any order are one series. */
220
+ with(labels: Labels): Counter;
221
+ inc(): void;
222
+ add(n: number): void;
223
+ }
224
+ export declare class Gauge {
225
+ #private;
226
+ constructor(instrument: Instrument, labels: Labels);
227
+ with(labels: Labels): Gauge;
228
+ set(value: number): void;
229
+ add(n: number): void;
230
+ inc(): void;
231
+ dec(): void;
232
+ }
233
+ /** A timer of labels; record and measure add a duration to the next flush. */
234
+ export declare class Timer {
235
+ #private;
236
+ constructor(timer: TimerInstrument, labels: Labels);
237
+ /** The timer of these labels besides its own: the same labels in any order are one series. */
238
+ with(labels: Labels): Timer;
239
+ /** Adds one duration: milliseconds, their fractions kept, or text such as '250ms'. */
240
+ record(d: Duration): void;
241
+ /**
242
+ * Runs fn and records how long it took, whether it returned or threw: its
243
+ * result comes back, and what it threw is thrown again.
244
+ *
245
+ * const user = await latency.with({ route: '/users' }).measure(() => users.get(id))
246
+ */
247
+ measure<R>(fn: () => R | Promise<R>): Promise<R>;
248
+ }
249
+ export {};