@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
package/src/time.ts ADDED
@@ -0,0 +1,87 @@
1
+ import { InvalidError } from './errors.ts'
2
+
3
+ /** A duration's units, largest first, in the order its text writes them. */
4
+ type Units = ['w', 'd', 'h', 'm', 's', 'ms']
5
+
6
+ /** One of a duration's units: weeks, days, hours, minutes, seconds, milliseconds. */
7
+ export type Unit = Units[number]
8
+
9
+ /**
10
+ * Every spelling of units each written once, largest first: a number and its
11
+ * unit, then the same of the units after it, or none.
12
+ *
13
+ * ['s', 'ms'] → `${number}s${number}ms` | `${number}s` | `${number}ms`
14
+ */
15
+ type Spelled<U extends readonly string[]> = U extends readonly [
16
+ infer First extends string,
17
+ ...infer Rest extends string[],
18
+ ]
19
+ ? `${number}${First}${Spelled<Rest> | ''}` | Spelled<Rest>
20
+ : never
21
+
22
+ /**
23
+ * A duration's text, '30d', '1h30m', '15m', '1s' or '250ms', which the type
24
+ * checks as it is written, so that '1hr' or '90mins' does not compile. Text
25
+ * from elsewhere, an environment's, is cast as Duration and checked when the
26
+ * call runs.
27
+ */
28
+ export type DurationText = Spelled<Units>
29
+
30
+ /** A length of time: milliseconds, or the text of one, such as '1h30m'. */
31
+ export type Duration = number | DurationText
32
+
33
+ /** A moment: a Date, or unix milliseconds. */
34
+ export type Time = Date | number
35
+
36
+ const units: Record<string, number> = {
37
+ ms: 1,
38
+ s: 1000,
39
+ m: 60_000,
40
+ h: 3_600_000,
41
+ d: 86_400_000,
42
+ w: 604_800_000,
43
+ }
44
+
45
+ /**
46
+ * A duration's milliseconds; each unit once, largest first: 1h30m, not
47
+ * 90m30m. It takes any text, since text cast as a Duration reaches it too.
48
+ */
49
+ export function ms(d: Duration | string): number {
50
+ if (typeof d === 'number') {
51
+ if (!Number.isFinite(d) || d < 0) {
52
+ throw new InvalidError(`a duration of ${d} milliseconds`)
53
+ }
54
+ return Math.round(d)
55
+ }
56
+ const parts = /^(?:(\d+)w)?(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m(?!s))?(?:(\d+)s)?(?:(\d+)ms)?$/.exec(
57
+ d.trim(),
58
+ )
59
+ if (parts === null || d.trim() === '') {
60
+ throw new InvalidError(
61
+ `the duration ${JSON.stringify(d)}; write it as 30d, 1h30m, 15m, 1s or 250ms`,
62
+ )
63
+ }
64
+ const [, w, days, h, m, s, milli] = parts
65
+ return (
66
+ Number(w ?? 0) * units.w! +
67
+ Number(days ?? 0) * units.d! +
68
+ Number(h ?? 0) * units.h! +
69
+ Number(m ?? 0) * units.m! +
70
+ Number(s ?? 0) * units.s! +
71
+ Number(milli ?? 0)
72
+ )
73
+ }
74
+
75
+ /** A moment's unix milliseconds. */
76
+ export function unixMs(t: Time): number {
77
+ const n = typeof t === 'number' ? t : t.getTime()
78
+ if (!Number.isFinite(n)) {
79
+ throw new InvalidError('an invalid Date')
80
+ }
81
+ return Math.trunc(n)
82
+ }
83
+
84
+ /** A moment the server named in unix milliseconds, none for 0 or absent. */
85
+ export function dateOf(unix: number | undefined): Date | undefined {
86
+ return unix === undefined || unix === 0 ? undefined : new Date(unix)
87
+ }
package/src/trace.ts ADDED
@@ -0,0 +1,32 @@
1
+ // The trace a call runs in, as Go's records.WithTrace carries one in a
2
+ // context: a logger's lines and appended records of no trace of their own
3
+ // take it.
4
+
5
+ import { AsyncLocalStorage } from 'node:async_hooks'
6
+
7
+ /** A trace's 16 bytes and the span's 8, as bytes or hex. */
8
+ export interface Trace {
9
+ traceId: Uint8Array | string
10
+ spanId?: Uint8Array | string
11
+ }
12
+
13
+ const carried = new AsyncLocalStorage<Trace>()
14
+
15
+ /**
16
+ * Runs fn in a trace: a logger's lines, and records appended without a trace
17
+ * of their own, inside it and in what it awaits, take its trace and span.
18
+ *
19
+ * ```ts
20
+ * await withTrace({ traceId, spanId }, async () => {
21
+ * log.info('charged') // a record of that trace and span
22
+ * })
23
+ * ```
24
+ */
25
+ export function withTrace<T>(trace: Trace, fn: () => T): T {
26
+ return carried.run(trace, fn)
27
+ }
28
+
29
+ /** The trace the caller runs in, from withTrace. */
30
+ export function currentTrace(): Trace | undefined {
31
+ return carried.getStore()
32
+ }
@@ -0,0 +1,445 @@
1
+ // A message is a map from small integer keys to values; each field's codec
2
+ // says how its value is written and read. A message's fields are declared by
3
+ // the names docs/wire.md gives them, in camelCase, so that the tests read
4
+ // every vector of messages.json through them without a table.
5
+
6
+ import { InvalidError } from '../errors.ts'
7
+ import { Reader, Writer } from './msgpack.ts'
8
+
9
+ /**
10
+ * How a field's value is written and read. In is what a caller may give, Out
11
+ * what a read returns: a key given as a number reads back as its decimal text.
12
+ */
13
+ export interface Codec<Out, In = Out> {
14
+ /** what the value is, which the tests that read vectors go by */
15
+ readonly kind: string
16
+ /** a list's items, or what a nullable holds when it holds something */
17
+ readonly item?: Codec<unknown, never>
18
+ write(w: Writer, value: In): void
19
+ read(r: Reader): Out
20
+ }
21
+
22
+ export const uint: Codec<number> = {
23
+ kind: 'uint',
24
+ write: (w, v) => w.uint(v),
25
+ read: r => r.uint(),
26
+ }
27
+
28
+ /** A signed integer a number holds exactly: unix milliseconds, a count. */
29
+ export const int: Codec<number> = {
30
+ kind: 'int',
31
+ write: (w, v) => w.int(v),
32
+ read: r => r.int(),
33
+ }
34
+
35
+ /** A signed 64-bit integer, read as a bigint: a record's nanoseconds. */
36
+ export const int64: Codec<bigint, bigint | number> = {
37
+ kind: 'int',
38
+ write: (w, v) => w.int(v),
39
+ read: r => r.int64(),
40
+ }
41
+
42
+ export const float: Codec<number> = {
43
+ kind: 'float',
44
+ write: (w, v) => w.float(v),
45
+ read: r => r.float(),
46
+ }
47
+
48
+ export const bool: Codec<boolean> = {
49
+ kind: 'bool',
50
+ write: (w, v) => w.bool(v),
51
+ read: r => r.bool(),
52
+ }
53
+
54
+ export const str: Codec<string> = {
55
+ kind: 'str',
56
+ write: (w, v) => w.str(v),
57
+ read: r => r.str(),
58
+ }
59
+
60
+ /** Bytes, read as a copy that outlives the frame they came in. */
61
+ export const bin: Codec<Uint8Array> = {
62
+ kind: 'bin',
63
+ write: (w, v) => w.bin(v),
64
+ read: r => r.bin().slice(),
65
+ }
66
+
67
+ const utf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true })
68
+
69
+ /** The text bytes spell, or undefined when they are not UTF-8. */
70
+ export function textOf(bytes: Uint8Array): string | undefined {
71
+ try {
72
+ return utf8.decode(bytes)
73
+ } catch {
74
+ return undefined
75
+ }
76
+ }
77
+
78
+ /**
79
+ * Text: a str, or a bin whose bytes are text that is not UTF-8, as another
80
+ * program's output may be. Bytes that are UTF-8 travel as the str they spell.
81
+ */
82
+ export const text: Codec<string | Uint8Array> = {
83
+ kind: 'text',
84
+ write: (w, v) => writeText(w, v),
85
+ read: r => (r.type() === 'bin' ? r.bin().slice() : r.str()),
86
+ }
87
+
88
+ function writeText(w: Writer, v: string | Uint8Array): void {
89
+ if (typeof v === 'string') {
90
+ w.str(v)
91
+ return
92
+ }
93
+ const spelled = textOf(v)
94
+ if (spelled === undefined) {
95
+ w.bin(v)
96
+ return
97
+ }
98
+ w.str(spelled)
99
+ }
100
+
101
+ /** A kv key's text: a str, a bin, or an integer, which is its decimal spelling. */
102
+ export type Key = string | Uint8Array | number | bigint
103
+
104
+ export const key: Codec<string | Uint8Array, Key> = {
105
+ kind: 'key',
106
+ write: (w, v) => {
107
+ if (typeof v === 'number' || typeof v === 'bigint') {
108
+ if (typeof v === 'number' && !Number.isSafeInteger(v)) {
109
+ throw new InvalidError(`the key ${v} is not an integer; a key is text or an integer`)
110
+ }
111
+ w.str(String(v))
112
+ return
113
+ }
114
+ writeText(w, v)
115
+ },
116
+ read: r => {
117
+ switch (r.type()) {
118
+ case 'bin':
119
+ return r.bin().slice()
120
+ case 'int':
121
+ return String(r.int64())
122
+ }
123
+ return r.str()
124
+ },
125
+ }
126
+
127
+ /** A kv value as its row keeps it: nothing, an integer or bytes. */
128
+ export type Raw = null | bigint | Uint8Array
129
+
130
+ export const kvValue: Codec<Raw, Raw | number> = {
131
+ kind: 'kv value',
132
+ write: (w, v) => {
133
+ if (v === null) {
134
+ w.nil()
135
+ } else if (v instanceof Uint8Array) {
136
+ w.bin(v)
137
+ } else {
138
+ w.int(v)
139
+ }
140
+ },
141
+ read: r => {
142
+ if (r.nil()) {
143
+ return null
144
+ }
145
+ return r.type() === 'bin' ? r.bin().slice() : r.int64()
146
+ },
147
+ }
148
+
149
+ /** A value SQLite returns: NULL, an integer, a float, text or bytes. */
150
+ export type SqlValue = null | number | bigint | string | Uint8Array
151
+
152
+ /**
153
+ * A value an SQL statement takes: SQLite's five, a boolean, which it keeps as
154
+ * 1 or 0, and a Date, which sqldb keeps as its unix milliseconds.
155
+ */
156
+ export type SqlArg = SqlValue | boolean | Date | undefined
157
+
158
+ export const sqlValue: Codec<SqlValue | boolean, SqlArg> = {
159
+ kind: 'sql value',
160
+ write: (w, v) => writeSQL(w, v),
161
+ read: r => {
162
+ switch (r.type()) {
163
+ case 'nil':
164
+ r.nil()
165
+ return null
166
+ case 'bool':
167
+ return r.bool()
168
+ case 'int': {
169
+ const n = r.int64()
170
+ return n >= Number.MIN_SAFE_INTEGER && n <= Number.MAX_SAFE_INTEGER ? Number(n) : n
171
+ }
172
+ case 'float':
173
+ return r.float()
174
+ case 'bin':
175
+ return r.bin().slice()
176
+ }
177
+ return r.str()
178
+ },
179
+ }
180
+
181
+ function writeSQL(w: Writer, v: SqlArg): void {
182
+ if (v === null || v === undefined) {
183
+ w.nil()
184
+ } else if (typeof v === 'boolean') {
185
+ w.bool(v)
186
+ } else if (typeof v === 'bigint') {
187
+ w.int(v)
188
+ } else if (typeof v === 'number') {
189
+ if (Number.isNaN(v)) {
190
+ throw new InvalidError('NaN as an SQL argument, which SQLite would keep as NULL')
191
+ }
192
+ if (Number.isInteger(v) && !Object.is(v, -0)) {
193
+ w.int(v)
194
+ } else {
195
+ w.float(v)
196
+ }
197
+ } else if (typeof v === 'string') {
198
+ w.str(v)
199
+ } else if (v instanceof Date) {
200
+ const ms = v.getTime()
201
+ if (Number.isNaN(ms)) {
202
+ throw new InvalidError('an invalid Date as an SQL argument')
203
+ }
204
+ w.int(ms)
205
+ } else {
206
+ w.bin(v)
207
+ }
208
+ }
209
+
210
+ /** Names mapped to text, in the byte order of their UTF-8, which is their code points' order. */
211
+ export function names<V, In = V>(
212
+ value: Codec<V, In>,
213
+ ): Codec<Record<string, V>, Record<string, In>> {
214
+ return {
215
+ kind: value.kind === 'sql value' ? 'sql names' : 'names',
216
+ write: (w, v) => {
217
+ const sorted = Object.keys(v).sort(byCodePoint)
218
+ w.map(sorted.length)
219
+ for (const name of sorted) {
220
+ w.str(name)
221
+ value.write(w, v[name] as In)
222
+ }
223
+ },
224
+ read: r => {
225
+ const named: Record<string, V> = {}
226
+ r.names(name => {
227
+ named[name] = value.read(r)
228
+ })
229
+ return named
230
+ },
231
+ }
232
+ }
233
+
234
+ /** Orders strings as their UTF-8 bytes are ordered, which UTF-16's code units do not. */
235
+ export function byCodePoint(a: string, b: string): number {
236
+ const x = a[Symbol.iterator]()
237
+ const y = b[Symbol.iterator]()
238
+ for (;;) {
239
+ const p = x.next()
240
+ const q = y.next()
241
+ if (p.done || q.done) {
242
+ return (p.done ? 0 : 1) - (q.done ? 0 : 1)
243
+ }
244
+ const d = p.value.codePointAt(0)! - q.value.codePointAt(0)!
245
+ if (d !== 0) {
246
+ return d
247
+ }
248
+ }
249
+ }
250
+
251
+ // a column's values are little-endian, as typed arrays hold them on every
252
+ // platform this SDK runs on; one that holds them otherwise copies value by value
253
+ const littleEndian = new Uint8Array(new Uint16Array([1]).buffer)[0] === 1
254
+
255
+ /** A column of int64s as a bin, eight bytes little-endian each. */
256
+ export const ints: Codec<BigInt64Array, BigInt64Array | readonly (number | bigint)[]> = {
257
+ kind: 'ints',
258
+ write: (w, v) => {
259
+ const column = v instanceof BigInt64Array ? v : BigInt64Array.from(v, n => BigInt(n))
260
+ w.bin(bytesOf(column))
261
+ },
262
+ read: r => {
263
+ const bytes = column(r)
264
+ const values = new BigInt64Array(bytes.length / 8)
265
+ if (littleEndian) {
266
+ new Uint8Array(values.buffer).set(bytes)
267
+ } else {
268
+ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.length)
269
+ values.forEach((_, i) => {
270
+ values[i] = view.getBigInt64(8 * i, true)
271
+ })
272
+ }
273
+ return values
274
+ },
275
+ }
276
+
277
+ /**
278
+ * A column of float64s as a bin, eight bytes of bits little-endian each: the
279
+ * bytes are copied rather than the numbers, so a NaN's payload survives.
280
+ */
281
+ export const floats: Codec<Float64Array, Float64Array | readonly number[]> = {
282
+ kind: 'floats',
283
+ write: (w, v) => {
284
+ w.bin(bytesOf(v instanceof Float64Array ? v : Float64Array.from(v)))
285
+ },
286
+ read: r => {
287
+ const bytes = column(r)
288
+ const values = new Float64Array(bytes.length / 8)
289
+ if (littleEndian) {
290
+ new Uint8Array(values.buffer).set(bytes)
291
+ } else {
292
+ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.length)
293
+ values.forEach((_, i) => {
294
+ values[i] = view.getFloat64(8 * i, true)
295
+ })
296
+ }
297
+ return values
298
+ },
299
+ }
300
+
301
+ function bytesOf(column: BigInt64Array | Float64Array): Uint8Array {
302
+ if (littleEndian) {
303
+ return new Uint8Array(column.buffer, column.byteOffset, column.byteLength)
304
+ }
305
+ const bytes = new Uint8Array(column.length * 8)
306
+ const view = new DataView(bytes.buffer)
307
+ column.forEach((n, i) => {
308
+ if (typeof n === 'bigint') {
309
+ view.setBigInt64(8 * i, n, true)
310
+ } else {
311
+ view.setFloat64(8 * i, n, true)
312
+ }
313
+ })
314
+ return bytes
315
+ }
316
+
317
+ function column(r: Reader): Uint8Array {
318
+ const bytes = r.bin()
319
+ if (bytes.length % 8 !== 0) {
320
+ throw new InvalidError(
321
+ `a column of ${bytes.length} bytes, which holds no whole number of values`,
322
+ )
323
+ }
324
+ return bytes
325
+ }
326
+
327
+ export function list<Out, In>(item: Codec<Out, In>): Codec<Out[], readonly In[]> {
328
+ return {
329
+ kind: `[]${item.kind}`,
330
+ item,
331
+ write: (w, v) => {
332
+ w.array(v.length)
333
+ for (const each of v) {
334
+ item.write(w, each)
335
+ }
336
+ },
337
+ read: r => {
338
+ const items: Out[] = []
339
+ r.items(() => {
340
+ items.push(item.read(r))
341
+ })
342
+ return items
343
+ },
344
+ }
345
+ }
346
+
347
+ /** A value that may be nil in its place, as a settlement's error. */
348
+ export function nullable<Out, In>(value: Codec<Out, In>): Codec<Out | null, In | null> {
349
+ return {
350
+ kind: `${value.kind}?`,
351
+ item: value,
352
+ write: (w, v) => (v === null ? w.nil() : value.write(w, v)),
353
+ read: r => (r.nil() ? null : value.read(r)),
354
+ }
355
+ }
356
+
357
+ type Fields = Record<string, readonly [key: number, codec: Codec<unknown, never>]>
358
+
359
+ type OutOf<C> = C extends Codec<infer O, never> ? O : never
360
+ type InOf<C> = C extends Codec<unknown, infer I> ? I : never
361
+
362
+ /** What a message reads: every field it holds, a field it lacks undefined. */
363
+ export type Read<F extends Fields> = { [K in keyof F]?: OutOf<F[K][1]> }
364
+
365
+ /** What a message is written from: a field undefined is left out. */
366
+ export type Written<F extends Fields> = { [K in keyof F]?: InOf<F[K][1]> | undefined }
367
+
368
+ /**
369
+ * A message: a map of the fields its declaration names, keys ascending. A
370
+ * field is written when its value is not undefined, so an absent field and a
371
+ * zero one stay what the caller said; a key the declaration lacks is skipped
372
+ * as it reads, well formed and within bounds.
373
+ */
374
+ export class Message<F extends Fields> implements Codec<Read<F>, Written<F>> {
375
+ readonly kind = 'message'
376
+ readonly name: string
377
+ readonly fields: F
378
+ readonly #order: { name: string; key: number; codec: Codec<unknown, unknown> }[]
379
+ readonly #byKey: ({ name: string; codec: Codec<unknown, unknown> } | undefined)[] = []
380
+
381
+ constructor(name: string, fields: F) {
382
+ this.name = name
383
+ this.fields = fields
384
+ this.#order = Object.entries(fields)
385
+ .map(([field, [key, codec]]) => ({
386
+ name: field,
387
+ key,
388
+ codec: codec as Codec<unknown, unknown>,
389
+ }))
390
+ .sort((a, b) => a.key - b.key)
391
+ for (const f of this.#order) {
392
+ this.#byKey[f.key] = f
393
+ }
394
+ }
395
+
396
+ write(w: Writer, value: Written<F>): void {
397
+ const held = value as Record<string, unknown>
398
+ let n = 0
399
+ for (const f of this.#order) {
400
+ if (held[f.name] !== undefined) {
401
+ n++
402
+ }
403
+ }
404
+ w.map(n)
405
+ for (const f of this.#order) {
406
+ const v = held[f.name]
407
+ if (v !== undefined) {
408
+ w.uint(f.key)
409
+ f.codec.write(w, v)
410
+ }
411
+ }
412
+ }
413
+
414
+ /** The message's bytes. */
415
+ encode(value: Written<F>): Uint8Array {
416
+ const w = new Writer()
417
+ this.write(w, value)
418
+ return w.bytes()
419
+ }
420
+
421
+ /** Reads a body that is this message and nothing after it. */
422
+ decode(body: Uint8Array): Read<F> {
423
+ const r = new Reader(body)
424
+ const value = this.read(r)
425
+ r.end()
426
+ return value
427
+ }
428
+
429
+ read(r: Reader): Read<F> {
430
+ const read: Record<string, unknown> = {}
431
+ r.fields(key => {
432
+ const f = this.#byKey[key]
433
+ if (f === undefined) {
434
+ return false
435
+ }
436
+ read[f.name] = f.codec.read(r)
437
+ return true
438
+ })
439
+ return read as Read<F>
440
+ }
441
+ }
442
+
443
+ export function message<const F extends Fields>(name: string, fields: F): Message<F> {
444
+ return new Message(name, fields)
445
+ }
@@ -0,0 +1,139 @@
1
+ // A frame is a twelve-byte header, little-endian, and a body:
2
+ //
3
+ // 0 4 5 6 8 12
4
+ // │ body length │ kind │ flags │ method │ stream │ body …
5
+ // u32 u8 u8 u16 u32
6
+
7
+ import { ProtocolError } from '../errors.ts'
8
+
9
+ export const headerSize = 12
10
+
11
+ export const Kind = {
12
+ hello: 1,
13
+ welcome: 2,
14
+ request: 3,
15
+ response: 4,
16
+ data: 5,
17
+ cancel: 6,
18
+ credit: 7,
19
+ ping: 8,
20
+ pong: 9,
21
+ goaway: 10,
22
+ } as const
23
+
24
+ export type Kind = (typeof Kind)[keyof typeof Kind]
25
+
26
+ /** END marks the sender's last frame on its stream; ERROR, only beside END, an error's body. */
27
+ export const Flag = { end: 1, error: 2 } as const
28
+
29
+ export interface Header {
30
+ length: number
31
+ kind: number
32
+ flags: number
33
+ method: number
34
+ stream: number
35
+ }
36
+
37
+ type StreamRule = 'none' | 'own' | 'either'
38
+
39
+ interface Rule {
40
+ name: string
41
+ stream: StreamRule
42
+ flags: number
43
+ /** the length a body must have; undefined when any will do */
44
+ length?: number
45
+ }
46
+
47
+ const rules: Record<number, Rule> = {
48
+ [Kind.hello]: { name: 'HELLO', stream: 'none', flags: 0 },
49
+ [Kind.welcome]: { name: 'WELCOME', stream: 'none', flags: 0 },
50
+ [Kind.request]: { name: 'REQUEST', stream: 'own', flags: Flag.end },
51
+ [Kind.response]: { name: 'RESPONSE', stream: 'own', flags: Flag.end | Flag.error },
52
+ [Kind.data]: { name: 'DATA', stream: 'own', flags: Flag.end | Flag.error },
53
+ [Kind.cancel]: { name: 'CANCEL', stream: 'own', flags: 0, length: 0 },
54
+ [Kind.credit]: { name: 'CREDIT', stream: 'either', flags: 0, length: 4 },
55
+ [Kind.ping]: { name: 'PING', stream: 'none', flags: 0, length: 8 },
56
+ [Kind.pong]: { name: 'PONG', stream: 'none', flags: 0, length: 8 },
57
+ [Kind.goaway]: { name: 'GOAWAY', stream: 'none', flags: 0 },
58
+ }
59
+
60
+ export function kindName(kind: number): string {
61
+ return rules[kind]?.name ?? `kind ${kind}`
62
+ }
63
+
64
+ /** Reads a header from its twelve bytes without checking it. */
65
+ export function parseHeader(bytes: Uint8Array, at = 0): Header {
66
+ const view = new DataView(bytes.buffer, bytes.byteOffset + at, headerSize)
67
+ return {
68
+ length: view.getUint32(0, true),
69
+ kind: view.getUint8(4),
70
+ flags: view.getUint8(5),
71
+ method: view.getUint16(6, true),
72
+ stream: view.getUint32(8, true),
73
+ }
74
+ }
75
+
76
+ /**
77
+ * Refuses a header that breaks the protocol: an unknown kind, a flag its kind
78
+ * does not define, ERROR without END, a method outside a REQUEST or none in
79
+ * one, a stream where the kind names none or none where it names one, and a
80
+ * body of a length the kind cannot have or past the agreed maximum.
81
+ */
82
+ export function checkHeader(h: Header, maxBody: number): void {
83
+ const rule = rules[h.kind]
84
+ if (rule === undefined) {
85
+ throw new ProtocolError(`a frame of kind ${h.kind}`)
86
+ }
87
+ const name = rule.name
88
+ if ((h.flags & ~rule.flags) !== 0) {
89
+ throw new ProtocolError(`flags 0x${h.flags.toString(16)} on a ${name}`)
90
+ }
91
+ if ((h.flags & Flag.error) !== 0 && (h.flags & Flag.end) === 0) {
92
+ throw new ProtocolError(`ERROR without END on stream ${h.stream}`)
93
+ }
94
+ if (h.kind === Kind.request && h.method === 0) {
95
+ throw new ProtocolError(`a REQUEST without a method on stream ${h.stream}`)
96
+ }
97
+ if (h.kind !== Kind.request && h.method !== 0) {
98
+ throw new ProtocolError(`method 0x${h.method.toString(16)} on a ${name}`)
99
+ }
100
+ if ((rule.stream === 'none' && h.stream !== 0) || (rule.stream === 'own' && h.stream === 0)) {
101
+ throw new ProtocolError(`stream ${h.stream} on a ${name}`)
102
+ }
103
+ if (rule.length !== undefined && h.length !== rule.length) {
104
+ throw new ProtocolError(`a ${name} of ${h.length} bytes, not ${rule.length}`)
105
+ }
106
+ if (h.length > maxBody) {
107
+ throw new ProtocolError(`a ${name} of ${h.length} bytes, ${maxBody} agreed`)
108
+ }
109
+ }
110
+
111
+ /** Writes a frame: its header, the body's length its own, then the body. */
112
+ export function frame(
113
+ kind: number,
114
+ flags: number,
115
+ method: number,
116
+ stream: number,
117
+ body: Uint8Array,
118
+ ): Uint8Array {
119
+ const bytes = new Uint8Array(headerSize + body.length)
120
+ const view = new DataView(bytes.buffer)
121
+ view.setUint32(0, body.length, true)
122
+ view.setUint8(4, kind)
123
+ view.setUint8(5, flags)
124
+ view.setUint16(6, method, true)
125
+ view.setUint32(8, stream, true)
126
+ bytes.set(body, headerSize)
127
+ return bytes
128
+ }
129
+
130
+ /** A CREDIT granting n bytes on a stream. */
131
+ export function credit(stream: number, n: number): Uint8Array {
132
+ const body = new Uint8Array(4)
133
+ new DataView(body.buffer).setUint32(0, n, true)
134
+ return frame(Kind.credit, 0, 0, stream, body)
135
+ }
136
+
137
+ export function granted(body: Uint8Array): number {
138
+ return new DataView(body.buffer, body.byteOffset, 4).getUint32(0, true)
139
+ }