@tinyshed/tinystore 0.1.1 → 0.2.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/src/records.ts CHANGED
@@ -18,7 +18,7 @@ import {
18
18
  newStoreLogger,
19
19
  } from './logger.ts'
20
20
  import type { Stream } from './session.ts'
21
- import { type Duration, type DurationText, ms } from './time.ts'
21
+ import { type Calendar, type Duration, type DurationText, ms } from './time.ts'
22
22
  import { currentTrace, type Trace } from './trace.ts'
23
23
  import {
24
24
  Empty,
@@ -26,6 +26,7 @@ import {
26
26
  methods,
27
27
  RecordsAggregateAsked,
28
28
  RecordsAppend,
29
+ RecordsAppended,
29
30
  RecordsBatch,
30
31
  RecordsCount,
31
32
  RecordsDamage,
@@ -61,6 +62,8 @@ export interface Event {
61
62
  /** its time, which the file keeps to the nanosecond */
62
63
  at: Date
63
64
  stream: string
65
+ /** what its append named it by: its stream holds one event of an id */
66
+ id?: string
64
67
  /** what happened; `log` for a logger's line */
65
68
  name: string
66
69
  level?: EventLevel
@@ -77,6 +80,11 @@ export interface Event {
77
80
  /** An event to append: its name, what happened, and what it carries beside. */
78
81
  export interface NewEvent {
79
82
  name: string
83
+ /**
84
+ * what names it in its stream, a webhook's delivery or a job's key, 1 to 128 bytes:
85
+ * an append of an id the stream holds writes nothing, and the first event of an id stands
86
+ */
87
+ id?: string
80
88
  fields?: Fields
81
89
  /** its time: now unless given, from what the stream keeps to ten minutes ahead */
82
90
  at?: Date
@@ -157,6 +165,10 @@ export interface Row {
157
165
  export interface Aggregate extends Counted {
158
166
  /** the span of a row: the range is one without it */
159
167
  every?: Duration
168
+ /** rows of a calendar in timeZone, in place of every: 'day' begins each at a local midnight */
169
+ calendar?: Calendar
170
+ /** the IANA zone a calendar's rows are in: 'Europe/Moscow', 'UTC' */
171
+ timeZone?: string
160
172
  /** keys whose every value has rows of its own */
161
173
  by?: readonly string[]
162
174
  /** fields whose numbers a row sums */
@@ -292,12 +304,14 @@ abstract class Reads {
292
304
 
293
305
  /** A row for each span of `every` and each value of the keys of `by`, with its count. */
294
306
  async aggregate(query: Aggregate = {}): Promise<Row[]> {
295
- const { every, by, stats, distinct, ...counted } = query
307
+ const { every, calendar, timeZone, by, stats, distinct, ...counted } = query
296
308
  const asked = queryOf(counted)
297
309
  const answer = await this.ask('records.aggregate', handle =>
298
310
  RecordsAggregateAsked.encode({
299
311
  query: { ...asked, handle },
300
312
  every: every === undefined ? undefined : ms(every),
313
+ calendar,
314
+ timeZone,
301
315
  by: by === undefined ? undefined : [...by],
302
316
  stats: stats === undefined ? undefined : [...stats],
303
317
  distinct: distinct === undefined ? undefined : [...distinct],
@@ -384,23 +398,27 @@ export class Events extends Reads {
384
398
 
385
399
  /**
386
400
  * Writes an event, or a list of them whole or not at all: it returns once
387
- * they are written, and a read finds them at once. A refused event names
388
- * its place in the list and its name.
401
+ * they are written, and a read finds them at once. An event whose id the
402
+ * stream holds, or an earlier event of the list has, is written as
403
+ * nothing: one event answers whether it was written, a list how many of
404
+ * its events were. A refused event names its place in the list and its name.
389
405
  */
390
- append(name: string, fields?: Fields, options?: AppendOptions): Promise<void>
391
- append(events: readonly NewEvent[]): Promise<void>
406
+ append(name: string, fields?: Fields, options?: AppendOptions): Promise<boolean>
407
+ append(events: readonly NewEvent[]): Promise<number>
392
408
  async append(
393
409
  first: string | readonly NewEvent[],
394
410
  fields?: Fields,
395
411
  options?: AppendOptions,
396
- ): Promise<void> {
412
+ ): Promise<boolean | number> {
397
413
  const events = typeof first === 'string' ? [oneEvent(first, fields, options)] : first
398
414
  const encoded = events.map(newEventOf)
399
- await this.#call(
415
+ const answer = await this.#call(
400
416
  'records.append',
401
417
  handle => RecordsAppend.encode({ handle, events: encoded }),
402
418
  'write',
403
419
  )
420
+ const written = events.length - (RecordsAppended.decode(answer).held ?? 0)
421
+ return typeof first === 'string' ? written === 1 : written
404
422
  }
405
423
 
406
424
  /** A logger's lines, each an event of this stream. */
@@ -793,8 +811,12 @@ function newEventOf(event: NewEvent, place: number): Parameters<typeof RecordsNe
793
811
  event.traceId === undefined
794
812
  ? traceOf(currentTrace())
795
813
  : { traceId: event.traceId, spanId: event.spanId }
814
+ if (event.id !== undefined && (typeof event.id !== 'string' || event.id === '')) {
815
+ throw new InvalidError(`${named}: an id is a string of 1 to 128 bytes`)
816
+ }
796
817
  return {
797
818
  name: event.name,
819
+ id: event.id,
798
820
  at: event.at === undefined ? undefined : nanosOf(event.at),
799
821
  level: event.level === undefined ? undefined : levelNumber(event.level, named),
800
822
  message: event.message,
@@ -853,6 +875,9 @@ function eventOf(read: ReturnType<typeof RecordsEvent.decode>): Event {
853
875
  if (read.message !== undefined) {
854
876
  event.message = read.message
855
877
  }
878
+ if (read.id !== undefined) {
879
+ event.id = read.id
880
+ }
856
881
  if (read.traceId !== undefined) {
857
882
  event.traceId = Buffer.from(read.traceId).toString('hex')
858
883
  }
package/src/time.ts CHANGED
@@ -53,6 +53,9 @@ export type DurationText = Offered | (Spelled<Units> & Record<never, never>)
53
53
  /** A length of time: milliseconds, or the text of one, such as '1h30m'. */
54
54
  export type Duration = number | DurationText
55
55
 
56
+ /** A span of a calendar an aggregate's bucket covers in its timeZone: a local day, a week from Monday, a month. */
57
+ export type Calendar = 'day' | 'week' | 'month'
58
+
56
59
  /** A moment: a Date, or unix milliseconds. */
57
60
  export type Time = Date | number
58
61
 
@@ -119,6 +119,13 @@ export const methods = {
119
119
  'metrics.flush': 0x060d,
120
120
  'metrics.instruments': 0x060e,
121
121
  'metrics.ingestPrometheus': 0x060f,
122
+ /**
123
+ * Answers its RESPONSE at once; the store's memory for the whole text is
124
+ * taken before a piece is kept, and the last piece is answered once the text
125
+ * is written, every series or none. A cancel or a lost connection leaves
126
+ * nothing written and lets go of what came.
127
+ */
128
+ 'metrics.uploadPrometheus': 0x0610,
122
129
  'records.open': 0x0501,
123
130
  'records.append': 0x0502,
124
131
  'records.list': 0x0503,
@@ -2780,6 +2787,8 @@ export const JobsQueueOpen = message(
2780
2787
  maxWaiting: [9, uint],
2781
2788
  /** a database's handle: the queue lives in its file; jobs.db when absent */
2782
2789
  database: [10, uint],
2790
+ /** each group's starts, beside the queue's rate */
2791
+ groupRate: [11, JobsRate],
2783
2792
  },
2784
2793
  {
2785
2794
  write(w, v) {
@@ -2835,6 +2844,11 @@ export const JobsQueueOpen = message(
2835
2844
  w.uint(v.database)
2836
2845
  n++
2837
2846
  }
2847
+ if (v.groupRate !== undefined) {
2848
+ w.field(11)
2849
+ JobsRate.write(w, v.groupRate)
2850
+ n++
2851
+ }
2838
2852
  w.closeMap(head, n)
2839
2853
  },
2840
2854
  read(r) {
@@ -2848,6 +2862,7 @@ export const JobsQueueOpen = message(
2848
2862
  let $keep: number | undefined
2849
2863
  let $maxWaiting: number | undefined
2850
2864
  let $database: number | undefined
2865
+ let $groupRate: Read<typeof JobsRate.fields> | undefined
2851
2866
  for (let n = r.message(); n > 0; n--) {
2852
2867
  switch (r.field()) {
2853
2868
  case 1:
@@ -2880,6 +2895,9 @@ export const JobsQueueOpen = message(
2880
2895
  case 10:
2881
2896
  $database = r.uint()
2882
2897
  break
2898
+ case 11:
2899
+ $groupRate = JobsRate.read(r)
2900
+ break
2883
2901
  default:
2884
2902
  r.skip()
2885
2903
  }
@@ -2896,6 +2914,7 @@ export const JobsQueueOpen = message(
2896
2914
  keep: $keep,
2897
2915
  maxWaiting: $maxWaiting,
2898
2916
  database: $database,
2917
+ groupRate: $groupRate,
2899
2918
  }
2900
2919
  },
2901
2920
  },
@@ -6135,6 +6154,10 @@ export const MetricsAggregateAsked = message(
6135
6154
  without: [5, list(str)],
6136
6155
  /** a timer's percentile also gives a point between its bounds */
6137
6156
  estimate: [6, bool],
6157
+ /** day, week or month: buckets of a calendar in timeZone, in place of every */
6158
+ calendar: [7, str],
6159
+ /** an IANA name, UTC among them, which calendar takes */
6160
+ timeZone: [8, str],
6138
6161
  },
6139
6162
  {
6140
6163
  write(w, v) {
@@ -6176,6 +6199,16 @@ export const MetricsAggregateAsked = message(
6176
6199
  w.bool(v.estimate)
6177
6200
  n++
6178
6201
  }
6202
+ if (v.calendar !== undefined) {
6203
+ w.field(7)
6204
+ w.str(v.calendar)
6205
+ n++
6206
+ }
6207
+ if (v.timeZone !== undefined) {
6208
+ w.field(8)
6209
+ w.str(v.timeZone)
6210
+ n++
6211
+ }
6179
6212
  w.closeMap(head, n)
6180
6213
  },
6181
6214
  read(r) {
@@ -6185,6 +6218,8 @@ export const MetricsAggregateAsked = message(
6185
6218
  let $by: string[] | undefined
6186
6219
  let $without: string[] | undefined
6187
6220
  let $estimate: boolean | undefined
6221
+ let $calendar: string | undefined
6222
+ let $timeZone: string | undefined
6188
6223
  for (let n = r.message(); n > 0; n--) {
6189
6224
  switch (r.field()) {
6190
6225
  case 1:
@@ -6217,6 +6252,12 @@ export const MetricsAggregateAsked = message(
6217
6252
  case 6:
6218
6253
  $estimate = r.bool()
6219
6254
  break
6255
+ case 7:
6256
+ $calendar = r.str()
6257
+ break
6258
+ case 8:
6259
+ $timeZone = r.str()
6260
+ break
6220
6261
  default:
6221
6262
  r.skip()
6222
6263
  }
@@ -6229,6 +6270,8 @@ export const MetricsAggregateAsked = message(
6229
6270
  by: $by,
6230
6271
  without: $without,
6231
6272
  estimate: $estimate,
6273
+ calendar: $calendar,
6274
+ timeZone: $timeZone,
6232
6275
  }
6233
6276
  },
6234
6277
  },
@@ -6749,6 +6792,110 @@ export const MetricsExposition = message(
6749
6792
  },
6750
6793
  )
6751
6794
 
6795
+ /**
6796
+ * A text past what one message holds: what metrics.Exposition carries but
6797
+ * the text, whose bytes follow as the client's DATA, a metrics.Piece each.
6798
+ */
6799
+ export const MetricsUpload = message(
6800
+ 'metrics.Upload',
6801
+ {
6802
+ /** the text's bytes, 32 MiB at most: pieces that come to more or fewer are refused */
6803
+ size: [1, uint],
6804
+ labels: [2, names(str)],
6805
+ at: [3, int],
6806
+ keep: [4, uint],
6807
+ },
6808
+ {
6809
+ write(w, v) {
6810
+ const head = w.openMap()
6811
+ let n = 0
6812
+ if (v.size !== undefined) {
6813
+ w.field(1)
6814
+ w.uint(v.size)
6815
+ n++
6816
+ }
6817
+ if (v.labels !== undefined) {
6818
+ w.field(2)
6819
+ writeNames(w, v.labels, str.write)
6820
+ n++
6821
+ }
6822
+ if (v.at !== undefined) {
6823
+ w.field(3)
6824
+ w.int(v.at)
6825
+ n++
6826
+ }
6827
+ if (v.keep !== undefined) {
6828
+ w.field(4)
6829
+ w.uint(v.keep)
6830
+ n++
6831
+ }
6832
+ w.closeMap(head, n)
6833
+ },
6834
+ read(r) {
6835
+ let $size: number | undefined
6836
+ let $labels: Record<string, string> | undefined
6837
+ let $at: number | undefined
6838
+ let $keep: number | undefined
6839
+ for (let n = r.message(); n > 0; n--) {
6840
+ switch (r.field()) {
6841
+ case 1:
6842
+ $size = r.uint()
6843
+ break
6844
+ case 2:
6845
+ $labels = readNames(r, str.read)
6846
+ break
6847
+ case 3:
6848
+ $at = r.int()
6849
+ break
6850
+ case 4:
6851
+ $keep = r.uint()
6852
+ break
6853
+ default:
6854
+ r.skip()
6855
+ }
6856
+ }
6857
+ r.leave()
6858
+ return { size: $size, labels: $labels, at: $at, keep: $keep }
6859
+ },
6860
+ },
6861
+ )
6862
+
6863
+ /**
6864
+ * A piece of an uploaded text, cut anywhere.
6865
+ */
6866
+ export const MetricsPiece = message(
6867
+ 'metrics.Piece',
6868
+ {
6869
+ bytes: [1, bin],
6870
+ },
6871
+ {
6872
+ write(w, v) {
6873
+ const head = w.openMap()
6874
+ let n = 0
6875
+ if (v.bytes !== undefined) {
6876
+ w.field(1)
6877
+ w.bin(v.bytes)
6878
+ n++
6879
+ }
6880
+ w.closeMap(head, n)
6881
+ },
6882
+ read(r) {
6883
+ let $bytes: Uint8Array | undefined
6884
+ for (let n = r.message(); n > 0; n--) {
6885
+ switch (r.field()) {
6886
+ case 1:
6887
+ $bytes = r.bytes()
6888
+ break
6889
+ default:
6890
+ r.skip()
6891
+ }
6892
+ }
6893
+ r.leave()
6894
+ return { bytes: $bytes }
6895
+ },
6896
+ },
6897
+ )
6898
+
6752
6899
  /**
6753
6900
  * A page of names, of a name's labels or of a label's values.
6754
6901
  */
@@ -7979,6 +8126,8 @@ export const RecordsNewEvent = message(
7979
8126
  traceId: [7, bin],
7980
8127
  /** 8 bytes */
7981
8128
  spanId: [8, bin],
8129
+ /** 1 to 128 bytes: an event of an id its stream holds is written as nothing */
8130
+ id: [9, str],
7982
8131
  },
7983
8132
  {
7984
8133
  write(w, v) {
@@ -8024,6 +8173,11 @@ export const RecordsNewEvent = message(
8024
8173
  w.bin(v.spanId)
8025
8174
  n++
8026
8175
  }
8176
+ if (v.id !== undefined) {
8177
+ w.field(9)
8178
+ w.str(v.id)
8179
+ n++
8180
+ }
8027
8181
  w.closeMap(head, n)
8028
8182
  },
8029
8183
  read(r) {
@@ -8035,6 +8189,7 @@ export const RecordsNewEvent = message(
8035
8189
  let $context: string | undefined
8036
8190
  let $traceId: Uint8Array | undefined
8037
8191
  let $spanId: Uint8Array | undefined
8192
+ let $id: string | undefined
8038
8193
  for (let n = r.message(); n > 0; n--) {
8039
8194
  switch (r.field()) {
8040
8195
  case 1:
@@ -8061,6 +8216,9 @@ export const RecordsNewEvent = message(
8061
8216
  case 8:
8062
8217
  $spanId = r.bytes()
8063
8218
  break
8219
+ case 9:
8220
+ $id = r.str()
8221
+ break
8064
8222
  default:
8065
8223
  r.skip()
8066
8224
  }
@@ -8075,6 +8233,7 @@ export const RecordsNewEvent = message(
8075
8233
  context: $context,
8076
8234
  traceId: $traceId,
8077
8235
  spanId: $spanId,
8236
+ id: $id,
8078
8237
  }
8079
8238
  },
8080
8239
  },
@@ -8135,6 +8294,44 @@ export const RecordsAppend = message(
8135
8294
  },
8136
8295
  )
8137
8296
 
8297
+ /**
8298
+ * What an append wrote: none of an event whose id its stream held, or an
8299
+ * earlier event of the append held.
8300
+ */
8301
+ export const RecordsAppended = message(
8302
+ 'records.Appended',
8303
+ {
8304
+ /** the events written as nothing */
8305
+ held: [1, uint],
8306
+ },
8307
+ {
8308
+ write(w, v) {
8309
+ const head = w.openMap()
8310
+ let n = 0
8311
+ if (v.held !== undefined) {
8312
+ w.field(1)
8313
+ w.uint(v.held)
8314
+ n++
8315
+ }
8316
+ w.closeMap(head, n)
8317
+ },
8318
+ read(r) {
8319
+ let $held: number | undefined
8320
+ for (let n = r.message(); n > 0; n--) {
8321
+ switch (r.field()) {
8322
+ case 1:
8323
+ $held = r.uint()
8324
+ break
8325
+ default:
8326
+ r.skip()
8327
+ }
8328
+ }
8329
+ r.leave()
8330
+ return { held: $held }
8331
+ },
8332
+ },
8333
+ )
8334
+
8138
8335
  /**
8139
8336
  * An event as a read gives it.
8140
8337
  */
@@ -8151,6 +8348,7 @@ export const RecordsEvent = message(
8151
8348
  context: [7, str],
8152
8349
  traceId: [8, bin],
8153
8350
  spanId: [9, bin],
8351
+ id: [10, str],
8154
8352
  },
8155
8353
  {
8156
8354
  write(w, v) {
@@ -8201,6 +8399,11 @@ export const RecordsEvent = message(
8201
8399
  w.bin(v.spanId)
8202
8400
  n++
8203
8401
  }
8402
+ if (v.id !== undefined) {
8403
+ w.field(10)
8404
+ w.str(v.id)
8405
+ n++
8406
+ }
8204
8407
  w.closeMap(head, n)
8205
8408
  },
8206
8409
  read(r) {
@@ -8213,6 +8416,7 @@ export const RecordsEvent = message(
8213
8416
  let $context: string | undefined
8214
8417
  let $traceId: Uint8Array | undefined
8215
8418
  let $spanId: Uint8Array | undefined
8419
+ let $id: string | undefined
8216
8420
  for (let n = r.message(); n > 0; n--) {
8217
8421
  switch (r.field()) {
8218
8422
  case 1:
@@ -8242,6 +8446,9 @@ export const RecordsEvent = message(
8242
8446
  case 9:
8243
8447
  $spanId = r.bytes()
8244
8448
  break
8449
+ case 10:
8450
+ $id = r.str()
8451
+ break
8245
8452
  default:
8246
8453
  r.skip()
8247
8454
  }
@@ -8257,6 +8464,7 @@ export const RecordsEvent = message(
8257
8464
  context: $context,
8258
8465
  traceId: $traceId,
8259
8466
  spanId: $spanId,
8467
+ id: $id,
8260
8468
  }
8261
8469
  },
8262
8470
  },
@@ -8684,6 +8892,10 @@ export const RecordsAggregateAsked = message(
8684
8892
  by: [3, list(str)],
8685
8893
  stats: [4, list(str)],
8686
8894
  distinct: [5, list(str)],
8895
+ /** day, week or month: rows of a calendar in timeZone, in place of every */
8896
+ calendar: [6, str],
8897
+ /** an IANA name, UTC among them, which calendar takes */
8898
+ timeZone: [7, str],
8687
8899
  },
8688
8900
  {
8689
8901
  write(w, v) {
@@ -8723,6 +8935,16 @@ export const RecordsAggregateAsked = message(
8723
8935
  }
8724
8936
  n++
8725
8937
  }
8938
+ if (v.calendar !== undefined) {
8939
+ w.field(6)
8940
+ w.str(v.calendar)
8941
+ n++
8942
+ }
8943
+ if (v.timeZone !== undefined) {
8944
+ w.field(7)
8945
+ w.str(v.timeZone)
8946
+ n++
8947
+ }
8726
8948
  w.closeMap(head, n)
8727
8949
  },
8728
8950
  read(r) {
@@ -8731,6 +8953,8 @@ export const RecordsAggregateAsked = message(
8731
8953
  let $by: string[] | undefined
8732
8954
  let $stats: string[] | undefined
8733
8955
  let $distinct: string[] | undefined
8956
+ let $calendar: string | undefined
8957
+ let $timeZone: string | undefined
8734
8958
  for (let n = r.message(); n > 0; n--) {
8735
8959
  switch (r.field()) {
8736
8960
  case 1:
@@ -8766,12 +8990,26 @@ export const RecordsAggregateAsked = message(
8766
8990
  $distinct = items0
8767
8991
  break
8768
8992
  }
8993
+ case 6:
8994
+ $calendar = r.str()
8995
+ break
8996
+ case 7:
8997
+ $timeZone = r.str()
8998
+ break
8769
8999
  default:
8770
9000
  r.skip()
8771
9001
  }
8772
9002
  }
8773
9003
  r.leave()
8774
- return { query: $query, every: $every, by: $by, stats: $stats, distinct: $distinct }
9004
+ return {
9005
+ query: $query,
9006
+ every: $every,
9007
+ by: $by,
9008
+ stats: $stats,
9009
+ distinct: $distinct,
9010
+ calendar: $calendar,
9011
+ timeZone: $timeZone,
9012
+ }
8775
9013
  },
8776
9014
  },
8777
9015
  )