@tinyshed/tinystore 0.2.0 → 0.3.0

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 CHANGED
@@ -13,8 +13,8 @@ one. Every call, by engine, is in docs/reference/bun.md.
13
13
 
14
14
  <!-- /landing:headline -->
15
15
 
16
- > **Version 0.1, the first release.** Until `1.0`, a minor release may still
17
- > change the API, and its notes say what changed.
16
+ > **Version 0.3.** Until `1.0`, a minor release may still change the API,
17
+ > and its notes say what changed.
18
18
 
19
19
  The SDK starts a small `tinystore` server next to your program, called the
20
20
  sidecar, and talks to it over a local connection, so that several processes
package/dist/index.d.ts CHANGED
@@ -13,7 +13,7 @@ export type { Bucket, BucketOptions, Counters, CountersOptions, Entry, Page as K
13
13
  export type { Allowance, Quota, Rate, RateLimit, RateLimitOptions, WindowUse } from './limits.ts';
14
14
  export type { HoldOptions, Lease, Lock, LockOptions, Permit, Semaphore, SemaphoreOptions, Tried, } from './locks.ts';
15
15
  export { type ConsoleOut, type Logger, type LoggerOptions, logger } from './logger.ts';
16
- export { type Aggregate, type AggregateQuery, type Bucket as MetricsBucket, type Buckets, type Condition as MetricsCondition, type Counter, type Damage as MetricsDamage, type Description as MetricsDescription, exponentialBuckets, type Gauge, type GaugeFuncOptions, type Histogram, type HistogramOptions, type InstrumentLabels, type InstrumentOptions, type LabelPage, type Labels, type LabelValue, type Metrics, type NameInfo, type NamePage, type Newest, type Op as MetricsOp, type PageOptions, type Percentile, type PercentileBucket, type Plan, type PrometheusOptions, type Query as MetricsQuery, type Series, type SeriesInput, type SeriesKind, type Timer, type TimerOptions, type Timing, type ValueBucket, type ValuePage, } from './metrics.ts';
16
+ export { type Aggregate, type AggregatePage, type AggregateQuery, type Bucket as MetricsBucket, type Buckets, type Condition as MetricsCondition, type Counter, type Damage as MetricsDamage, type Description as MetricsDescription, exponentialBuckets, type Gauge, type GaugeFuncOptions, type Histogram, type HistogramOptions, type InstrumentLabels, type InstrumentOptions, type LabelPage, type Labels, type LabelValue, type Metrics, type NameInfo, type NamePage, type Newest, type Op as MetricsOp, type PageOptions, type Percentile, type PercentileBucket, type Plan, type PrometheusOptions, type Query as MetricsQuery, type Series, type SeriesInput, type SeriesKind, type SeriesPage, type Timer, type TimerOptions, type Timing, type ValueBucket, type ValuePage, } from './metrics.ts';
17
17
  export type { Once, OnceOptions } from './once.ts';
18
18
  export type { ColumnType, Query, RowPage, Table, TableOptions, UpsertOptions } from './query.ts';
19
19
  export type { Aggregate as EventsAggregate, AllEvents, AppendOptions, Counted, Damage, Event, EventLevel, Events, EventsOptions, Fields, Level, Levels, Lines, NewEvent, Page as EventsPage, PollBatch, Query as EventsQuery, Row as EventsRow, Stats, StoreLoggerOptions, StreamInfo, TailBatch, TailQuery, Top, } from './records.ts';
package/dist/metrics.d.ts CHANGED
@@ -30,6 +30,10 @@ export interface Query {
30
30
  from?: Time | undefined;
31
31
  /** the range's end, excluded; now, a sample taken now in the range, unless given */
32
32
  to?: Time | undefined;
33
+ /** a page of read or aggregate: this many samples or buckets at most, 100,000 at most; without it, the whole answer or a limit error */
34
+ limit?: number | undefined;
35
+ /** the page after the one whose next this is, read with the same query and limit */
36
+ after?: string | undefined;
33
37
  }
34
38
  /** A series to write: its samples as [time, value] pairs, or as times and values columns. */
35
39
  export interface SeriesInput {
@@ -60,6 +64,18 @@ export interface Series {
60
64
  times: Float64Array;
61
65
  /** the values, whose bytes keep each one's bits: -0 and a NaN's payload survive */
62
66
  values: Float64Array;
67
+ /** a page cut the series here: the page its next reads begins with the rest of it */
68
+ more: boolean;
69
+ }
70
+ /**
71
+ * One page of a read: its series, and next while there is more. Walking it
72
+ * with for await gives its series, then those of each page after it, one
73
+ * page held at a time. Without limit it is the whole answer.
74
+ */
75
+ export interface SeriesPage extends AsyncIterable<Series> {
76
+ series: Series[];
77
+ /** where the page after it begins; absent on the last */
78
+ next?: string;
63
79
  }
64
80
  /** p and a rank: 'p95', 'p99.9'. The ranks offered are those asked most; any other is written the same way. */
65
81
  export type Percentile = 'p50' | 'p75' | 'p90' | 'p95' | 'p99' | 'p99.9' | (`p${number}` & Record<never, never>);
@@ -117,6 +133,17 @@ export interface Aggregate<O extends Op = Op> {
117
133
  labels: Labels;
118
134
  /** a bucket without samples is left out */
119
135
  buckets: Bucket<O>[];
136
+ /** a page cut the group here: the page its next reads begins with the rest of its buckets */
137
+ more: boolean;
138
+ }
139
+ /**
140
+ * One page of an aggregate: its groups, and next while there is more,
141
+ * walked as a SeriesPage is. A page ends between two whole buckets.
142
+ */
143
+ export interface AggregatePage<O extends Op = Op> extends AsyncIterable<Aggregate<O>> {
144
+ groups: Aggregate<O>[];
145
+ /** where the page after it begins; absent on the last */
146
+ next?: string;
120
147
  }
121
148
  /** A series' newest sample in the range. */
122
149
  export interface Newest {
@@ -200,15 +227,19 @@ export declare class Metrics {
200
227
  * await store.metrics.ingestPrometheus(text, { labels: { instance: 'web-1' } })
201
228
  */
202
229
  ingestPrometheus(text: string | Uint8Array, options?: PrometheusOptions): Promise<void>;
203
- /** The samples of each series the query finds, in its range: whole, or a limit error naming its bound. */
204
- read(query: Query): Promise<Series[]>;
230
+ /**
231
+ * The samples of each series the query finds, in its range: without limit
232
+ * the whole answer, or a limit error naming its bound; with limit a page,
233
+ * which may hold fewer samples than limit and still have next.
234
+ */
235
+ read(query: Query): Promise<SeriesPage>;
205
236
  /** The newest sample of each series the query finds, when it has one in the range. */
206
237
  latest(query: Query): Promise<Newest[]>;
207
238
  /**
208
239
  * The buckets of each group of the series the query finds, each one exact
209
240
  * value of op, rounded once; a bucket of count … last has its value.
210
241
  */
211
- aggregate<O extends Op>(query: AggregateQuery<O>): Promise<Aggregate<O>[]>;
242
+ aggregate<O extends Op>(query: AggregateQuery<O>): Promise<AggregatePage<O>>;
212
243
  /** What a read, or an aggregate when given its op, would spend of each bound; it decodes no sample. */
213
244
  explain(query: Query & Partial<Omit<AggregateQuery, keyof Query>>): Promise<Plan>;
214
245
  /** A page of the names the store holds samples of, in the byte order of their text. */
package/dist/metrics.js CHANGED
@@ -61,26 +61,41 @@ export class Metrics {
61
61
  await uploaded(stream, bytes, pieceOf(connection));
62
62
  });
63
63
  }
64
- /** The samples of each series the query finds, in its range: whole, or a limit error naming its bound. */
64
+ /**
65
+ * The samples of each series the query finds, in its range: without limit
66
+ * the whole answer, or a limit error naming its bound; with limit a page,
67
+ * which may hold fewer samples than limit and still have next.
68
+ */
65
69
  async read(query) {
66
- const parts = await this.#download('metrics.read', MetricsQuery.encode(queryOf(query)));
70
+ const parts = (await this.#download('metrics.read', MetricsQuery.encode(queryOf(query)))).map(part => MetricsRead.decode(part));
67
71
  const series = [];
68
72
  let more = false;
69
- for (const piece of parts.flatMap(part => MetricsRead.decode(part).series ?? [])) {
73
+ for (const piece of parts.flatMap(part => part.series ?? [])) {
70
74
  const times = timesOf(piece.times ?? new Uint8Array(0));
71
75
  const values = valuesOf(piece.values ?? new Uint8Array(0));
72
76
  const last = series.at(-1);
73
77
  if (more && last !== undefined) {
74
78
  last.times = joined(last.times, times);
75
79
  last.values = joined(last.values, values);
80
+ last.more = piece.more === true;
76
81
  }
77
82
  else {
78
83
  const kind = (piece.kind ?? 'gauge');
79
- series.push({ name: piece.name ?? '', kind, labels: piece.labels ?? {}, times, values });
84
+ const labels = piece.labels ?? {};
85
+ series.push({
86
+ name: piece.name ?? '',
87
+ kind,
88
+ labels,
89
+ times,
90
+ values,
91
+ more: piece.more === true,
92
+ });
80
93
  }
81
94
  more = piece.more === true;
82
95
  }
83
- return series;
96
+ const next = parts.at(-1)?.next;
97
+ const page = next === undefined ? { series } : { series, next };
98
+ return walked(page, at => at.series, after => this.read({ ...query, after }));
84
99
  }
85
100
  /** The newest sample of each series the query finds, when it has one in the range. */
86
101
  async latest(query) {
@@ -97,21 +112,30 @@ export class Metrics {
97
112
  * value of op, rounded once; a bucket of count … last has its value.
98
113
  */
99
114
  async aggregate(query) {
100
- const parts = await this.#download('metrics.aggregate', MetricsAggregateAsked.encode(aggregateOf(query)));
115
+ const asked = MetricsAggregateAsked.encode(aggregateOf(query));
116
+ const parts = (await this.#download('metrics.aggregate', asked)).map(part => MetricsAggregates.decode(part));
101
117
  const groups = [];
102
118
  let more = false;
103
- for (const piece of parts.flatMap(part => MetricsAggregates.decode(part).groups ?? [])) {
119
+ for (const piece of parts.flatMap(part => part.groups ?? [])) {
104
120
  const buckets = (piece.buckets ?? []).map(bucket => bucketOf(bucket));
105
121
  const last = groups.at(-1);
106
122
  if (more && last !== undefined) {
107
123
  last.buckets.push(...buckets);
124
+ last.more = piece.more === true;
108
125
  }
109
126
  else {
110
- groups.push({ name: piece.name ?? '', labels: piece.labels ?? {}, buckets });
127
+ groups.push({
128
+ name: piece.name ?? '',
129
+ labels: piece.labels ?? {},
130
+ buckets,
131
+ more: piece.more === true,
132
+ });
111
133
  }
112
134
  more = piece.more === true;
113
135
  }
114
- return groups;
136
+ const next = parts.at(-1)?.next;
137
+ const page = next === undefined ? { groups } : { groups, next };
138
+ return walked(page, at => at.groups, after => this.aggregate({ ...query, after }));
115
139
  }
116
140
  /** What a read, or an aggregate when given its op, would spend of each bound; it decodes no sample. */
117
141
  async explain(query) {
@@ -258,6 +282,23 @@ export class Metrics {
258
282
  return got.items.length === 0 ? [got.trailer] : [...got.items, got.trailer];
259
283
  }
260
284
  }
285
+ /**
286
+ * A page that for await walks: its items, then those of each page after it,
287
+ * the next page read only once the walk reaches the end of the one it holds.
288
+ */
289
+ function walked(page, items, readOn) {
290
+ return Object.assign(page, {
291
+ async *[Symbol.asyncIterator]() {
292
+ for (let at = page;;) {
293
+ yield* items(at);
294
+ if (at.next === undefined) {
295
+ return;
296
+ }
297
+ at = await readOn(at.next);
298
+ }
299
+ },
300
+ });
301
+ }
261
302
  /** A query as the wire carries it; a condition given as undefined is refused, never left out. */
262
303
  function queryOf(query) {
263
304
  const where = {};
@@ -273,6 +314,8 @@ function queryOf(query) {
273
314
  since: query.since === undefined ? undefined : ms(query.since),
274
315
  from: query.from === undefined ? undefined : unixMs(query.from),
275
316
  to: query.to === undefined ? undefined : unixMs(query.to),
317
+ limit: query.limit,
318
+ after: query.after,
276
319
  };
277
320
  }
278
321
  function conditionOf(label, condition) {
@@ -406,6 +406,8 @@ export declare const ConfigOpen: import("./codec.ts").Message<{
406
406
  readonly layers: readonly [3, import("./codec.ts").Codec<string, string>];
407
407
  /** a kept change that no longer fits refuses the open */
408
408
  readonly strict: readonly [4, import("./codec.ts").Codec<boolean, boolean>];
409
+ /** as kv.db keeps it, for a command: the last declaration a program opened it with, */
410
+ readonly kept: readonly [5, import("./codec.ts").Codec<boolean, boolean>];
409
411
  }>;
410
412
  /**
411
413
  * Where a value came from: its kind, and only the fields that kind names.
@@ -1298,6 +1300,10 @@ export declare const MetricsQuery: import("./codec.ts").Message<{
1298
1300
  readonly from: readonly [4, import("./codec.ts").Codec<number, number>];
1299
1301
  /** excluded; now, a sample taken now in the range, unless given */
1300
1302
  readonly to: readonly [5, import("./codec.ts").Codec<number, number>];
1303
+ /** a page's samples or buckets at most, 100,000 at most: a page, which read and aggregate take */
1304
+ readonly limit: readonly [6, import("./codec.ts").Codec<number, number>];
1305
+ /** a page's next, with limit */
1306
+ readonly after: readonly [7, import("./codec.ts").Codec<string, string>];
1301
1307
  }>;
1302
1308
  /**
1303
1309
  * A series and its samples, or a part of them: a series longer than a body
@@ -1312,7 +1318,7 @@ export declare const MetricsSeries: import("./codec.ts").Message<{
1312
1318
  readonly times: readonly [4, import("./codec.ts").Codec<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>];
1313
1319
  /** a float64 a sample */
1314
1320
  readonly values: readonly [5, import("./codec.ts").Codec<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>];
1315
- /** the next part goes on with this series */
1321
+ /** the next part goes on with this series; on a page's last, the next page's first */
1316
1322
  readonly more: readonly [6, import("./codec.ts").Codec<boolean, boolean>];
1317
1323
  }>;
1318
1324
  export declare const MetricsRead: import("./codec.ts").Message<{
@@ -1325,7 +1331,7 @@ export declare const MetricsRead: import("./codec.ts").Message<{
1325
1331
  readonly times: readonly [4, import("./codec.ts").Codec<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>];
1326
1332
  /** a float64 a sample */
1327
1333
  readonly values: readonly [5, import("./codec.ts").Codec<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>];
1328
- /** the next part goes on with this series */
1334
+ /** the next part goes on with this series; on a page's last, the next page's first */
1329
1335
  readonly more: readonly [6, import("./codec.ts").Codec<boolean, boolean>];
1330
1336
  }>[], readonly import("./codec.ts").Written<{
1331
1337
  readonly name: readonly [1, import("./codec.ts").Codec<string, string>];
@@ -1336,9 +1342,11 @@ export declare const MetricsRead: import("./codec.ts").Message<{
1336
1342
  readonly times: readonly [4, import("./codec.ts").Codec<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>];
1337
1343
  /** a float64 a sample */
1338
1344
  readonly values: readonly [5, import("./codec.ts").Codec<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>];
1339
- /** the next part goes on with this series */
1345
+ /** the next part goes on with this series; on a page's last, the next page's first */
1340
1346
  readonly more: readonly [6, import("./codec.ts").Codec<boolean, boolean>];
1341
1347
  }>[]>];
1348
+ /** on the last part of a page that has more, to a request that gave limit */
1349
+ readonly next: readonly [2, import("./codec.ts").Codec<string, string>];
1342
1350
  }>;
1343
1351
  /**
1344
1352
  * A series' newest sample in the range.
@@ -1383,6 +1391,10 @@ export declare const MetricsAggregateAsked: import("./codec.ts").Message<{
1383
1391
  readonly from: readonly [4, import("./codec.ts").Codec<number, number>];
1384
1392
  /** excluded; now, a sample taken now in the range, unless given */
1385
1393
  readonly to: readonly [5, import("./codec.ts").Codec<number, number>];
1394
+ /** a page's samples or buckets at most, 100,000 at most: a page, which read and aggregate take */
1395
+ readonly limit: readonly [6, import("./codec.ts").Codec<number, number>];
1396
+ /** a page's next, with limit */
1397
+ readonly after: readonly [7, import("./codec.ts").Codec<string, string>];
1386
1398
  }>];
1387
1399
  readonly every: readonly [2, import("./codec.ts").Codec<number, number>];
1388
1400
  /** count, sum, avg, min, max, increase, rate, delta, first, last, or p and a rank; none for a read's plan */
@@ -1453,6 +1465,7 @@ export declare const MetricsGroup: import("./codec.ts").Message<{
1453
1465
  /** its first step began before the bucket before it */
1454
1466
  readonly gap: readonly [9, import("./codec.ts").Codec<boolean, boolean>];
1455
1467
  }>[]>];
1468
+ /** the next part goes on with this group; on a page's last, the next page's first */
1456
1469
  readonly more: readonly [4, import("./codec.ts").Codec<boolean, boolean>];
1457
1470
  }>;
1458
1471
  export declare const MetricsAggregates: import("./codec.ts").Message<{
@@ -1490,6 +1503,7 @@ export declare const MetricsAggregates: import("./codec.ts").Message<{
1490
1503
  /** its first step began before the bucket before it */
1491
1504
  readonly gap: readonly [9, import("./codec.ts").Codec<boolean, boolean>];
1492
1505
  }>[]>];
1506
+ /** the next part goes on with this group; on a page's last, the next page's first */
1493
1507
  readonly more: readonly [4, import("./codec.ts").Codec<boolean, boolean>];
1494
1508
  }>[], readonly import("./codec.ts").Written<{
1495
1509
  readonly name: readonly [1, import("./codec.ts").Codec<string, string>];
@@ -1525,8 +1539,11 @@ export declare const MetricsAggregates: import("./codec.ts").Message<{
1525
1539
  /** its first step began before the bucket before it */
1526
1540
  readonly gap: readonly [9, import("./codec.ts").Codec<boolean, boolean>];
1527
1541
  }>[]>];
1542
+ /** the next part goes on with this group; on a page's last, the next page's first */
1528
1543
  readonly more: readonly [4, import("./codec.ts").Codec<boolean, boolean>];
1529
1544
  }>[]>];
1545
+ /** on the last part of a page that has more, to a request that gave limit */
1546
+ readonly next: readonly [2, import("./codec.ts").Codec<string, string>];
1530
1547
  }>;
1531
1548
  export declare const MetricsExceeds: import("./codec.ts").Message<{
1532
1549
  /** series, bytes read, samples decoded or answer */
@@ -1524,6 +1524,8 @@ export const ConfigOpen = message('config.Open', {
1524
1524
  layers: [3, str],
1525
1525
  /** a kept change that no longer fits refuses the open */
1526
1526
  strict: [4, bool],
1527
+ /** as kv.db keeps it, for a command: the last declaration a program opened it with, */
1528
+ kept: [5, bool],
1527
1529
  }, {
1528
1530
  write(w, v) {
1529
1531
  const head = w.openMap();
@@ -1548,6 +1550,11 @@ export const ConfigOpen = message('config.Open', {
1548
1550
  w.bool(v.strict);
1549
1551
  n++;
1550
1552
  }
1553
+ if (v.kept !== undefined) {
1554
+ w.field(5);
1555
+ w.bool(v.kept);
1556
+ n++;
1557
+ }
1551
1558
  w.closeMap(head, n);
1552
1559
  },
1553
1560
  read(r) {
@@ -1555,6 +1562,7 @@ export const ConfigOpen = message('config.Open', {
1555
1562
  let $declaration;
1556
1563
  let $layers;
1557
1564
  let $strict;
1565
+ let $kept;
1558
1566
  for (let n = r.message(); n > 0; n--) {
1559
1567
  switch (r.field()) {
1560
1568
  case 1:
@@ -1569,12 +1577,21 @@ export const ConfigOpen = message('config.Open', {
1569
1577
  case 4:
1570
1578
  $strict = r.bool();
1571
1579
  break;
1580
+ case 5:
1581
+ $kept = r.bool();
1582
+ break;
1572
1583
  default:
1573
1584
  r.skip();
1574
1585
  }
1575
1586
  }
1576
1587
  r.leave();
1577
- return { name: $name, declaration: $declaration, layers: $layers, strict: $strict };
1588
+ return {
1589
+ name: $name,
1590
+ declaration: $declaration,
1591
+ layers: $layers,
1592
+ strict: $strict,
1593
+ kept: $kept,
1594
+ };
1578
1595
  },
1579
1596
  });
1580
1597
  /**
@@ -5399,6 +5416,10 @@ export const MetricsQuery = message('metrics.Query', {
5399
5416
  from: [4, int],
5400
5417
  /** excluded; now, a sample taken now in the range, unless given */
5401
5418
  to: [5, int],
5419
+ /** a page's samples or buckets at most, 100,000 at most: a page, which read and aggregate take */
5420
+ limit: [6, uint],
5421
+ /** a page's next, with limit */
5422
+ after: [7, str],
5402
5423
  }, {
5403
5424
  write(w, v) {
5404
5425
  const head = w.openMap();
@@ -5428,6 +5449,16 @@ export const MetricsQuery = message('metrics.Query', {
5428
5449
  w.int(v.to);
5429
5450
  n++;
5430
5451
  }
5452
+ if (v.limit !== undefined) {
5453
+ w.field(6);
5454
+ w.uint(v.limit);
5455
+ n++;
5456
+ }
5457
+ if (v.after !== undefined) {
5458
+ w.field(7);
5459
+ w.str(v.after);
5460
+ n++;
5461
+ }
5431
5462
  w.closeMap(head, n);
5432
5463
  },
5433
5464
  read(r) {
@@ -5436,6 +5467,8 @@ export const MetricsQuery = message('metrics.Query', {
5436
5467
  let $since;
5437
5468
  let $from;
5438
5469
  let $to;
5470
+ let $limit;
5471
+ let $after;
5439
5472
  for (let n = r.message(); n > 0; n--) {
5440
5473
  switch (r.field()) {
5441
5474
  case 1:
@@ -5453,12 +5486,26 @@ export const MetricsQuery = message('metrics.Query', {
5453
5486
  case 5:
5454
5487
  $to = r.int();
5455
5488
  break;
5489
+ case 6:
5490
+ $limit = r.uint();
5491
+ break;
5492
+ case 7:
5493
+ $after = r.str();
5494
+ break;
5456
5495
  default:
5457
5496
  r.skip();
5458
5497
  }
5459
5498
  }
5460
5499
  r.leave();
5461
- return { name: $name, where: $where, since: $since, from: $from, to: $to };
5500
+ return {
5501
+ name: $name,
5502
+ where: $where,
5503
+ since: $since,
5504
+ from: $from,
5505
+ to: $to,
5506
+ limit: $limit,
5507
+ after: $after,
5508
+ };
5462
5509
  },
5463
5510
  });
5464
5511
  /**
@@ -5474,7 +5521,7 @@ export const MetricsSeries = message('metrics.Series', {
5474
5521
  times: [4, bin],
5475
5522
  /** a float64 a sample */
5476
5523
  values: [5, bin],
5477
- /** the next part goes on with this series */
5524
+ /** the next part goes on with this series; on a page's last, the next page's first */
5478
5525
  more: [6, bool],
5479
5526
  }, {
5480
5527
  write(w, v) {
@@ -5556,6 +5603,8 @@ export const MetricsSeries = message('metrics.Series', {
5556
5603
  });
5557
5604
  export const MetricsRead = message('metrics.Read', {
5558
5605
  series: [1, list(MetricsSeries)],
5606
+ /** on the last part of a page that has more, to a request that gave limit */
5607
+ next: [2, str],
5559
5608
  }, {
5560
5609
  write(w, v) {
5561
5610
  const head = w.openMap();
@@ -5568,10 +5617,16 @@ export const MetricsRead = message('metrics.Read', {
5568
5617
  }
5569
5618
  n++;
5570
5619
  }
5620
+ if (v.next !== undefined) {
5621
+ w.field(2);
5622
+ w.str(v.next);
5623
+ n++;
5624
+ }
5571
5625
  w.closeMap(head, n);
5572
5626
  },
5573
5627
  read(r) {
5574
5628
  let $series;
5629
+ let $next;
5575
5630
  for (let n = r.message(); n > 0; n--) {
5576
5631
  switch (r.field()) {
5577
5632
  case 1: {
@@ -5583,12 +5638,15 @@ export const MetricsRead = message('metrics.Read', {
5583
5638
  $series = items0;
5584
5639
  break;
5585
5640
  }
5641
+ case 2:
5642
+ $next = r.str();
5643
+ break;
5586
5644
  default:
5587
5645
  r.skip();
5588
5646
  }
5589
5647
  }
5590
5648
  r.leave();
5591
- return { series: $series };
5649
+ return { series: $series, next: $next };
5592
5650
  },
5593
5651
  });
5594
5652
  /**
@@ -5957,6 +6015,7 @@ export const MetricsGroup = message('metrics.Group', {
5957
6015
  name: [1, str],
5958
6016
  labels: [2, names(str)],
5959
6017
  buckets: [3, list(MetricsBucket)],
6018
+ /** the next part goes on with this group; on a page's last, the next page's first */
5960
6019
  more: [4, bool],
5961
6020
  }, {
5962
6021
  write(w, v) {
@@ -6022,6 +6081,8 @@ export const MetricsGroup = message('metrics.Group', {
6022
6081
  });
6023
6082
  export const MetricsAggregates = message('metrics.Aggregates', {
6024
6083
  groups: [1, list(MetricsGroup)],
6084
+ /** on the last part of a page that has more, to a request that gave limit */
6085
+ next: [2, str],
6025
6086
  }, {
6026
6087
  write(w, v) {
6027
6088
  const head = w.openMap();
@@ -6034,10 +6095,16 @@ export const MetricsAggregates = message('metrics.Aggregates', {
6034
6095
  }
6035
6096
  n++;
6036
6097
  }
6098
+ if (v.next !== undefined) {
6099
+ w.field(2);
6100
+ w.str(v.next);
6101
+ n++;
6102
+ }
6037
6103
  w.closeMap(head, n);
6038
6104
  },
6039
6105
  read(r) {
6040
6106
  let $groups;
6107
+ let $next;
6041
6108
  for (let n = r.message(); n > 0; n--) {
6042
6109
  switch (r.field()) {
6043
6110
  case 1: {
@@ -6049,12 +6116,15 @@ export const MetricsAggregates = message('metrics.Aggregates', {
6049
6116
  $groups = items0;
6050
6117
  break;
6051
6118
  }
6119
+ case 2:
6120
+ $next = r.str();
6121
+ break;
6052
6122
  default:
6053
6123
  r.skip();
6054
6124
  }
6055
6125
  }
6056
6126
  r.leave();
6057
- return { groups: $groups };
6127
+ return { groups: $groups, next: $next };
6058
6128
  },
6059
6129
  });
6060
6130
  export const MetricsExceeds = message('metrics.Exceeds', {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tinyshed/tinystore",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "TinyStore for Bun and Node: kv, jobs, blobs, SQL, records and metrics in one directory, served by a sidecar",
5
5
  "license": "Apache-2.0",
6
6
  "homepage": "https://tinyshed.org/tinystore",
@@ -31,12 +31,12 @@
31
31
  "README.md"
32
32
  ],
33
33
  "optionalDependencies": {
34
- "@tinyshed/tinystore-linux-x64": "0.2.0",
35
- "@tinyshed/tinystore-linux-arm64": "0.2.0",
36
- "@tinyshed/tinystore-linux-x64-musl": "0.2.0",
37
- "@tinyshed/tinystore-linux-arm64-musl": "0.2.0",
38
- "@tinyshed/tinystore-darwin-arm64": "0.2.0",
39
- "@tinyshed/tinystore-darwin-x64": "0.2.0",
40
- "@tinyshed/tinystore-win32-x64": "0.2.0"
34
+ "@tinyshed/tinystore-linux-x64": "0.3.0",
35
+ "@tinyshed/tinystore-linux-arm64": "0.3.0",
36
+ "@tinyshed/tinystore-linux-x64-musl": "0.3.0",
37
+ "@tinyshed/tinystore-linux-arm64-musl": "0.3.0",
38
+ "@tinyshed/tinystore-darwin-arm64": "0.3.0",
39
+ "@tinyshed/tinystore-darwin-x64": "0.3.0",
40
+ "@tinyshed/tinystore-win32-x64": "0.3.0"
41
41
  }
42
42
  }
package/src/index.ts CHANGED
@@ -104,6 +104,7 @@ export type {
104
104
  export { type ConsoleOut, type Logger, type LoggerOptions, logger } from './logger.ts'
105
105
  export {
106
106
  type Aggregate,
107
+ type AggregatePage,
107
108
  type AggregateQuery,
108
109
  type Bucket as MetricsBucket,
109
110
  type Buckets,
@@ -135,6 +136,7 @@ export {
135
136
  type Series,
136
137
  type SeriesInput,
137
138
  type SeriesKind,
139
+ type SeriesPage,
138
140
  type Timer,
139
141
  type TimerOptions,
140
142
  type Timing,
package/src/metrics.ts CHANGED
@@ -92,6 +92,10 @@ export interface Query {
92
92
  from?: Time | undefined
93
93
  /** the range's end, excluded; now, a sample taken now in the range, unless given */
94
94
  to?: Time | undefined
95
+ /** a page of read or aggregate: this many samples or buckets at most, 100,000 at most; without it, the whole answer or a limit error */
96
+ limit?: number | undefined
97
+ /** the page after the one whose next this is, read with the same query and limit */
98
+ after?: string | undefined
95
99
  }
96
100
 
97
101
  /** A series to write: its samples as [time, value] pairs, or as times and values columns. */
@@ -125,6 +129,19 @@ export interface Series {
125
129
  times: Float64Array
126
130
  /** the values, whose bytes keep each one's bits: -0 and a NaN's payload survive */
127
131
  values: Float64Array
132
+ /** a page cut the series here: the page its next reads begins with the rest of it */
133
+ more: boolean
134
+ }
135
+
136
+ /**
137
+ * One page of a read: its series, and next while there is more. Walking it
138
+ * with for await gives its series, then those of each page after it, one
139
+ * page held at a time. Without limit it is the whole answer.
140
+ */
141
+ export interface SeriesPage extends AsyncIterable<Series> {
142
+ series: Series[]
143
+ /** where the page after it begins; absent on the last */
144
+ next?: string
128
145
  }
129
146
 
130
147
  /** p and a rank: 'p95', 'p99.9'. The ranks offered are those asked most; any other is written the same way. */
@@ -209,6 +226,18 @@ export interface Aggregate<O extends Op = Op> {
209
226
  labels: Labels
210
227
  /** a bucket without samples is left out */
211
228
  buckets: Bucket<O>[]
229
+ /** a page cut the group here: the page its next reads begins with the rest of its buckets */
230
+ more: boolean
231
+ }
232
+
233
+ /**
234
+ * One page of an aggregate: its groups, and next while there is more,
235
+ * walked as a SeriesPage is. A page ends between two whole buckets.
236
+ */
237
+ export interface AggregatePage<O extends Op = Op> extends AsyncIterable<Aggregate<O>> {
238
+ groups: Aggregate<O>[]
239
+ /** where the page after it begins; absent on the last */
240
+ next?: string
212
241
  }
213
242
 
214
243
  /** A series' newest sample in the range. */
@@ -348,25 +377,47 @@ export class Metrics {
348
377
  })
349
378
  }
350
379
 
351
- /** The samples of each series the query finds, in its range: whole, or a limit error naming its bound. */
352
- async read(query: Query): Promise<Series[]> {
353
- const parts = await this.#download('metrics.read', MetricsQuery.encode(queryOf(query)))
380
+ /**
381
+ * The samples of each series the query finds, in its range: without limit
382
+ * the whole answer, or a limit error naming its bound; with limit a page,
383
+ * which may hold fewer samples than limit and still have next.
384
+ */
385
+ async read(query: Query): Promise<SeriesPage> {
386
+ const parts = (await this.#download('metrics.read', MetricsQuery.encode(queryOf(query)))).map(
387
+ part => MetricsRead.decode(part),
388
+ )
354
389
  const series: Series[] = []
355
390
  let more = false
356
- for (const piece of parts.flatMap(part => MetricsRead.decode(part).series ?? [])) {
391
+ for (const piece of parts.flatMap(part => part.series ?? [])) {
357
392
  const times = timesOf(piece.times ?? new Uint8Array(0))
358
393
  const values = valuesOf(piece.values ?? new Uint8Array(0))
359
394
  const last = series.at(-1)
360
395
  if (more && last !== undefined) {
361
396
  last.times = joined(last.times, times)
362
397
  last.values = joined(last.values, values)
398
+ last.more = piece.more === true
363
399
  } else {
364
400
  const kind = (piece.kind ?? 'gauge') as SeriesKind
365
- series.push({ name: piece.name ?? '', kind, labels: piece.labels ?? {}, times, values })
401
+ const labels = piece.labels ?? {}
402
+ series.push({
403
+ name: piece.name ?? '',
404
+ kind,
405
+ labels,
406
+ times,
407
+ values,
408
+ more: piece.more === true,
409
+ })
366
410
  }
367
411
  more = piece.more === true
368
412
  }
369
- return series
413
+ const next = parts.at(-1)?.next
414
+ const page: { series: Series[]; next?: string } =
415
+ next === undefined ? { series } : { series, next }
416
+ return walked(
417
+ page,
418
+ at => at.series,
419
+ after => this.read({ ...query, after }),
420
+ )
370
421
  }
371
422
 
372
423
  /** The newest sample of each series the query finds, when it has one in the range. */
@@ -386,24 +437,37 @@ export class Metrics {
386
437
  * The buckets of each group of the series the query finds, each one exact
387
438
  * value of op, rounded once; a bucket of count … last has its value.
388
439
  */
389
- async aggregate<O extends Op>(query: AggregateQuery<O>): Promise<Aggregate<O>[]> {
390
- const parts = await this.#download(
391
- 'metrics.aggregate',
392
- MetricsAggregateAsked.encode(aggregateOf(query)),
440
+ async aggregate<O extends Op>(query: AggregateQuery<O>): Promise<AggregatePage<O>> {
441
+ const asked = MetricsAggregateAsked.encode(aggregateOf(query))
442
+ const parts = (await this.#download('metrics.aggregate', asked)).map(part =>
443
+ MetricsAggregates.decode(part),
393
444
  )
394
445
  const groups: Aggregate<O>[] = []
395
446
  let more = false
396
- for (const piece of parts.flatMap(part => MetricsAggregates.decode(part).groups ?? [])) {
447
+ for (const piece of parts.flatMap(part => part.groups ?? [])) {
397
448
  const buckets = (piece.buckets ?? []).map(bucket => bucketOf(bucket) as Bucket<O>)
398
449
  const last = groups.at(-1)
399
450
  if (more && last !== undefined) {
400
451
  last.buckets.push(...buckets)
452
+ last.more = piece.more === true
401
453
  } else {
402
- groups.push({ name: piece.name ?? '', labels: piece.labels ?? {}, buckets })
454
+ groups.push({
455
+ name: piece.name ?? '',
456
+ labels: piece.labels ?? {},
457
+ buckets,
458
+ more: piece.more === true,
459
+ })
403
460
  }
404
461
  more = piece.more === true
405
462
  }
406
- return groups
463
+ const next = parts.at(-1)?.next
464
+ const page: { groups: Aggregate<O>[]; next?: string } =
465
+ next === undefined ? { groups } : { groups, next }
466
+ return walked(
467
+ page,
468
+ at => at.groups,
469
+ after => this.aggregate({ ...query, after }),
470
+ )
407
471
  }
408
472
 
409
473
  /** What a read, or an aggregate when given its op, would spend of each bound; it decodes no sample. */
@@ -591,6 +655,28 @@ export class Metrics {
591
655
  }
592
656
  }
593
657
 
658
+ /**
659
+ * A page that for await walks: its items, then those of each page after it,
660
+ * the next page read only once the walk reaches the end of the one it holds.
661
+ */
662
+ function walked<P extends { next?: string }, T>(
663
+ page: P,
664
+ items: (page: P) => readonly T[],
665
+ readOn: (after: string) => Promise<P>,
666
+ ): P & AsyncIterable<T> {
667
+ return Object.assign(page, {
668
+ async *[Symbol.asyncIterator](): AsyncGenerator<T> {
669
+ for (let at = page; ; ) {
670
+ yield* items(at)
671
+ if (at.next === undefined) {
672
+ return
673
+ }
674
+ at = await readOn(at.next)
675
+ }
676
+ },
677
+ })
678
+ }
679
+
594
680
  /** A query as the wire carries it; a condition given as undefined is refused, never left out. */
595
681
  function queryOf(query: Query): Parameters<typeof MetricsQuery.encode>[0] {
596
682
  const where: Record<string, { values?: string[]; not?: boolean; prefix?: string }> = {}
@@ -606,6 +692,8 @@ function queryOf(query: Query): Parameters<typeof MetricsQuery.encode>[0] {
606
692
  since: query.since === undefined ? undefined : ms(query.since),
607
693
  from: query.from === undefined ? undefined : unixMs(query.from),
608
694
  to: query.to === undefined ? undefined : unixMs(query.to),
695
+ limit: query.limit,
696
+ after: query.after,
609
697
  }
610
698
  }
611
699
 
@@ -1665,6 +1665,8 @@ export const ConfigOpen = message(
1665
1665
  layers: [3, str],
1666
1666
  /** a kept change that no longer fits refuses the open */
1667
1667
  strict: [4, bool],
1668
+ /** as kv.db keeps it, for a command: the last declaration a program opened it with, */
1669
+ kept: [5, bool],
1668
1670
  },
1669
1671
  {
1670
1672
  write(w, v) {
@@ -1690,6 +1692,11 @@ export const ConfigOpen = message(
1690
1692
  w.bool(v.strict)
1691
1693
  n++
1692
1694
  }
1695
+ if (v.kept !== undefined) {
1696
+ w.field(5)
1697
+ w.bool(v.kept)
1698
+ n++
1699
+ }
1693
1700
  w.closeMap(head, n)
1694
1701
  },
1695
1702
  read(r) {
@@ -1697,6 +1704,7 @@ export const ConfigOpen = message(
1697
1704
  let $declaration: string | undefined
1698
1705
  let $layers: string | undefined
1699
1706
  let $strict: boolean | undefined
1707
+ let $kept: boolean | undefined
1700
1708
  for (let n = r.message(); n > 0; n--) {
1701
1709
  switch (r.field()) {
1702
1710
  case 1:
@@ -1711,12 +1719,21 @@ export const ConfigOpen = message(
1711
1719
  case 4:
1712
1720
  $strict = r.bool()
1713
1721
  break
1722
+ case 5:
1723
+ $kept = r.bool()
1724
+ break
1714
1725
  default:
1715
1726
  r.skip()
1716
1727
  }
1717
1728
  }
1718
1729
  r.leave()
1719
- return { name: $name, declaration: $declaration, layers: $layers, strict: $strict }
1730
+ return {
1731
+ name: $name,
1732
+ declaration: $declaration,
1733
+ layers: $layers,
1734
+ strict: $strict,
1735
+ kept: $kept,
1736
+ }
1720
1737
  },
1721
1738
  },
1722
1739
  )
@@ -5825,6 +5842,10 @@ export const MetricsQuery = message(
5825
5842
  from: [4, int],
5826
5843
  /** excluded; now, a sample taken now in the range, unless given */
5827
5844
  to: [5, int],
5845
+ /** a page's samples or buckets at most, 100,000 at most: a page, which read and aggregate take */
5846
+ limit: [6, uint],
5847
+ /** a page's next, with limit */
5848
+ after: [7, str],
5828
5849
  },
5829
5850
  {
5830
5851
  write(w, v) {
@@ -5855,6 +5876,16 @@ export const MetricsQuery = message(
5855
5876
  w.int(v.to)
5856
5877
  n++
5857
5878
  }
5879
+ if (v.limit !== undefined) {
5880
+ w.field(6)
5881
+ w.uint(v.limit)
5882
+ n++
5883
+ }
5884
+ if (v.after !== undefined) {
5885
+ w.field(7)
5886
+ w.str(v.after)
5887
+ n++
5888
+ }
5858
5889
  w.closeMap(head, n)
5859
5890
  },
5860
5891
  read(r) {
@@ -5863,6 +5894,8 @@ export const MetricsQuery = message(
5863
5894
  let $since: number | undefined
5864
5895
  let $from: number | undefined
5865
5896
  let $to: number | undefined
5897
+ let $limit: number | undefined
5898
+ let $after: string | undefined
5866
5899
  for (let n = r.message(); n > 0; n--) {
5867
5900
  switch (r.field()) {
5868
5901
  case 1:
@@ -5880,12 +5913,26 @@ export const MetricsQuery = message(
5880
5913
  case 5:
5881
5914
  $to = r.int()
5882
5915
  break
5916
+ case 6:
5917
+ $limit = r.uint()
5918
+ break
5919
+ case 7:
5920
+ $after = r.str()
5921
+ break
5883
5922
  default:
5884
5923
  r.skip()
5885
5924
  }
5886
5925
  }
5887
5926
  r.leave()
5888
- return { name: $name, where: $where, since: $since, from: $from, to: $to }
5927
+ return {
5928
+ name: $name,
5929
+ where: $where,
5930
+ since: $since,
5931
+ from: $from,
5932
+ to: $to,
5933
+ limit: $limit,
5934
+ after: $after,
5935
+ }
5889
5936
  },
5890
5937
  },
5891
5938
  )
@@ -5905,7 +5952,7 @@ export const MetricsSeries = message(
5905
5952
  times: [4, bin],
5906
5953
  /** a float64 a sample */
5907
5954
  values: [5, bin],
5908
- /** the next part goes on with this series */
5955
+ /** the next part goes on with this series; on a page's last, the next page's first */
5909
5956
  more: [6, bool],
5910
5957
  },
5911
5958
  {
@@ -5992,6 +6039,8 @@ export const MetricsRead = message(
5992
6039
  'metrics.Read',
5993
6040
  {
5994
6041
  series: [1, list(MetricsSeries)],
6042
+ /** on the last part of a page that has more, to a request that gave limit */
6043
+ next: [2, str],
5995
6044
  },
5996
6045
  {
5997
6046
  write(w, v) {
@@ -6005,10 +6054,16 @@ export const MetricsRead = message(
6005
6054
  }
6006
6055
  n++
6007
6056
  }
6057
+ if (v.next !== undefined) {
6058
+ w.field(2)
6059
+ w.str(v.next)
6060
+ n++
6061
+ }
6008
6062
  w.closeMap(head, n)
6009
6063
  },
6010
6064
  read(r) {
6011
6065
  let $series: Read<typeof MetricsSeries.fields>[] | undefined
6066
+ let $next: string | undefined
6012
6067
  for (let n = r.message(); n > 0; n--) {
6013
6068
  switch (r.field()) {
6014
6069
  case 1: {
@@ -6020,12 +6075,15 @@ export const MetricsRead = message(
6020
6075
  $series = items0
6021
6076
  break
6022
6077
  }
6078
+ case 2:
6079
+ $next = r.str()
6080
+ break
6023
6081
  default:
6024
6082
  r.skip()
6025
6083
  }
6026
6084
  }
6027
6085
  r.leave()
6028
- return { series: $series }
6086
+ return { series: $series, next: $next }
6029
6087
  },
6030
6088
  },
6031
6089
  )
@@ -6418,6 +6476,7 @@ export const MetricsGroup = message(
6418
6476
  name: [1, str],
6419
6477
  labels: [2, names(str)],
6420
6478
  buckets: [3, list(MetricsBucket)],
6479
+ /** the next part goes on with this group; on a page's last, the next page's first */
6421
6480
  more: [4, bool],
6422
6481
  },
6423
6482
  {
@@ -6488,6 +6547,8 @@ export const MetricsAggregates = message(
6488
6547
  'metrics.Aggregates',
6489
6548
  {
6490
6549
  groups: [1, list(MetricsGroup)],
6550
+ /** on the last part of a page that has more, to a request that gave limit */
6551
+ next: [2, str],
6491
6552
  },
6492
6553
  {
6493
6554
  write(w, v) {
@@ -6501,10 +6562,16 @@ export const MetricsAggregates = message(
6501
6562
  }
6502
6563
  n++
6503
6564
  }
6565
+ if (v.next !== undefined) {
6566
+ w.field(2)
6567
+ w.str(v.next)
6568
+ n++
6569
+ }
6504
6570
  w.closeMap(head, n)
6505
6571
  },
6506
6572
  read(r) {
6507
6573
  let $groups: Read<typeof MetricsGroup.fields>[] | undefined
6574
+ let $next: string | undefined
6508
6575
  for (let n = r.message(); n > 0; n--) {
6509
6576
  switch (r.field()) {
6510
6577
  case 1: {
@@ -6516,12 +6583,15 @@ export const MetricsAggregates = message(
6516
6583
  $groups = items0
6517
6584
  break
6518
6585
  }
6586
+ case 2:
6587
+ $next = r.str()
6588
+ break
6519
6589
  default:
6520
6590
  r.skip()
6521
6591
  }
6522
6592
  }
6523
6593
  r.leave()
6524
- return { groups: $groups }
6594
+ return { groups: $groups, next: $next }
6525
6595
  },
6526
6596
  },
6527
6597
  )