@tinyshed/tinystore 0.1.0-rc.4 → 0.1.0-rc.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (122) hide show
  1. package/README.md +37 -37
  2. package/bin/tinystore.js +12 -1
  3. package/dist/backup.d.ts +33 -0
  4. package/dist/backup.js +49 -0
  5. package/dist/blobs.d.ts +160 -79
  6. package/dist/blobs.js +510 -217
  7. package/dist/channels.d.ts +90 -0
  8. package/dist/channels.js +291 -0
  9. package/dist/clock.js +3 -3
  10. package/dist/config.d.ts +209 -86
  11. package/dist/config.js +581 -538
  12. package/dist/connection.d.ts +64 -2
  13. package/dist/connection.js +201 -16
  14. package/dist/console.d.ts +27 -3
  15. package/dist/console.js +165 -12
  16. package/dist/dotenv.d.ts +7 -0
  17. package/dist/dotenv.js +79 -0
  18. package/dist/errors.d.ts +61 -1
  19. package/dist/errors.js +81 -1
  20. package/dist/handles.d.ts +44 -2
  21. package/dist/handles.js +81 -2
  22. package/dist/index.d.ts +17 -11
  23. package/dist/index.js +5 -3
  24. package/dist/instruments.d.ts +177 -0
  25. package/dist/instruments.js +819 -0
  26. package/dist/jobs.d.ts +335 -239
  27. package/dist/jobs.js +716 -536
  28. package/dist/json.d.ts +2 -0
  29. package/dist/json.js +122 -0
  30. package/dist/kv.d.ts +130 -243
  31. package/dist/kv.js +273 -640
  32. package/dist/limits.d.ts +80 -0
  33. package/dist/limits.js +139 -0
  34. package/dist/locks.d.ts +62 -0
  35. package/dist/locks.js +237 -0
  36. package/dist/logger.d.ts +45 -9
  37. package/dist/logger.js +150 -38
  38. package/dist/metrics.d.ts +210 -209
  39. package/dist/metrics.js +319 -556
  40. package/dist/once.d.ts +19 -18
  41. package/dist/once.js +74 -63
  42. package/dist/query.d.ts +181 -0
  43. package/dist/query.js +788 -0
  44. package/dist/records.d.ts +241 -150
  45. package/dist/records.js +507 -291
  46. package/dist/runtime/addon.d.ts +14 -0
  47. package/dist/runtime/addon.js +69 -0
  48. package/dist/runtime/bun.js +5 -7
  49. package/dist/runtime/node.js +5 -7
  50. package/dist/runtime/pipe.d.ts +17 -0
  51. package/dist/runtime/pipe.js +133 -0
  52. package/dist/runtime/shared.d.ts +6 -0
  53. package/dist/runtime/shared.js +19 -0
  54. package/dist/runtime.d.ts +5 -2
  55. package/dist/search.d.ts +189 -0
  56. package/dist/search.js +281 -0
  57. package/dist/session.d.ts +31 -3
  58. package/dist/session.js +153 -41
  59. package/dist/sql.d.ts +228 -78
  60. package/dist/sql.js +745 -240
  61. package/dist/store.d.ts +244 -24
  62. package/dist/store.js +270 -67
  63. package/dist/time.d.ts +5 -1
  64. package/dist/time.js +22 -2
  65. package/dist/tx.d.ts +61 -0
  66. package/dist/tx.js +314 -0
  67. package/dist/wire/codec.d.ts +23 -7
  68. package/dist/wire/codec.js +56 -35
  69. package/dist/wire/frame.d.ts +2 -0
  70. package/dist/wire/frame.js +31 -14
  71. package/dist/wire/messages.d.ts +259 -0
  72. package/dist/wire/messages.js +22 -0
  73. package/dist/wire/msgpack.d.ts +49 -1
  74. package/dist/wire/msgpack.js +293 -56
  75. package/dist/wire/protocol.d.ts +2683 -0
  76. package/dist/wire/protocol.js +10846 -0
  77. package/package.json +39 -38
  78. package/src/backup.ts +81 -0
  79. package/src/blobs.ts +678 -301
  80. package/src/channels.ts +377 -0
  81. package/src/clock.ts +4 -4
  82. package/src/config.ts +902 -612
  83. package/src/connection.ts +279 -21
  84. package/src/console.ts +180 -12
  85. package/src/dotenv.ts +82 -0
  86. package/src/errors.ts +105 -0
  87. package/src/handles.ts +157 -8
  88. package/src/index.ts +158 -52
  89. package/src/instruments.ts +1042 -0
  90. package/src/jobs.ts +1017 -733
  91. package/src/json.ts +133 -0
  92. package/src/kv.ts +424 -847
  93. package/src/limits.ts +202 -0
  94. package/src/locks.ts +320 -0
  95. package/src/logger.ts +209 -40
  96. package/src/metrics.ts +557 -752
  97. package/src/once.ts +86 -83
  98. package/src/query.ts +1005 -0
  99. package/src/records.ts +795 -418
  100. package/src/runtime/addon.ts +99 -0
  101. package/src/runtime/bun.ts +5 -7
  102. package/src/runtime/node.ts +5 -7
  103. package/src/runtime/pipe.ts +178 -0
  104. package/src/runtime/shared.ts +20 -0
  105. package/src/runtime.ts +5 -2
  106. package/src/search.ts +480 -0
  107. package/src/session.ts +187 -41
  108. package/src/sql.ts +993 -306
  109. package/src/store.ts +473 -78
  110. package/src/time.ts +48 -3
  111. package/src/tx.ts +426 -0
  112. package/src/wire/codec.ts +78 -37
  113. package/src/wire/frame.ts +44 -14
  114. package/src/wire/messages.ts +25 -0
  115. package/src/wire/msgpack.ts +327 -56
  116. package/src/wire/protocol.ts +11709 -0
  117. package/dist/limiter.d.ts +0 -45
  118. package/dist/limiter.js +0 -68
  119. package/dist/quota.d.ts +0 -44
  120. package/dist/quota.js +0 -98
  121. package/src/limiter.ts +0 -99
  122. package/src/quota.ts +0 -137
package/src/sql.ts CHANGED
@@ -1,75 +1,447 @@
1
- // The application's own SQLite databases, sql/<name>.db, as Go's sqldb keeps
2
- // them: the application writes every query, the server owns the file, its
3
- // connections and its migrations, which the first open applies and every
4
- // later one checks. An open without migrations takes the file as it is.
1
+ // The application's own SQLite databases, sql/<name>.db, as docs/guides/sql/README.md
2
+ // has them: the application writes its SQL, or builds it with a table's
3
+ // queries, and the server owns the file, its connections and its migrations,
4
+ // which every open applies and checks. A statement leaves as its text and the
5
+ // values of its ?s, each as SQLite keeps it.
5
6
 
7
+ import { AsyncLocalStorage } from 'node:async_hooks'
6
8
  import { readdir, readFile } from 'node:fs/promises'
7
9
  import { join } from 'node:path'
8
10
 
9
- import type { Connection, Link } from './connection.ts'
10
- import { InvalidError } from './errors.ts'
11
- import { checkName, handleOn, type Settled, settle } from './handles.ts'
12
- import { watch } from './session.ts'
11
+ import { type Channel, channelParts, type TxChannel, txChannel } from './channels.ts'
12
+ import type { Connection, Durability, Idempotence, Link } from './connection.ts'
13
+ import { checkDurability, download } from './connection.ts'
14
+ import { errorOf, InvalidError } from './errors.ts'
15
+ import {
16
+ askByCall,
17
+ checkName,
18
+ type Home,
19
+ handleOn,
20
+ type Open,
21
+ type Via,
22
+ viaLink,
23
+ } from './handles.ts'
24
+ import {
25
+ openQueue,
26
+ type Queue,
27
+ type QueueOptions,
28
+ queueParts,
29
+ queueVia,
30
+ type TxQueue,
31
+ type Worker,
32
+ } from './jobs.ts'
33
+ import { Bucket, type BucketOptions, bucketOpen, partsOf, type Values, valuesOf } from './kv.ts'
34
+ import { Table, type TableOptions } from './query.ts'
35
+ import type { StandardSchemaV1 } from './schema.ts'
36
+ import { TableIndex, type TableIndexOptions, tableIndexOpen } from './search.ts'
37
+ import type { Stream } from './session.ts'
13
38
  import type { SqlArg, SqlValue } from './wire/codec.ts'
39
+ import { int64Of } from './wire/msgpack.ts'
14
40
  import {
15
- type JobsJob,
16
41
  methods,
42
+ SearchDropped,
43
+ SearchName,
44
+ SqlBatch,
45
+ SqlBatched,
17
46
  SqlColumns,
18
- SqlDatabase,
19
47
  SqlDone,
20
- SqlResults,
21
- SqlRow,
48
+ SqlOpen,
49
+ SqlQuery,
50
+ SqlRows,
22
51
  SqlStatement,
23
- SqlStatements,
24
- } from './wire/messages.ts'
52
+ SqlTxAnswer,
53
+ SqlTxCall,
54
+ SqlTxOpen,
55
+ } from './wire/protocol.ts'
25
56
 
26
57
  export type { SqlArg, SqlValue }
27
58
 
28
- /** A row as SQLite returned it, by its columns' names. */
59
+ /** A row type's columns: an array of each of its fields. */
60
+ export type Columns<T> = { [K in keyof T]: T[K][] }
61
+
62
+ /** A row as SQLite gave it, by its columns' names. */
29
63
  export type Row = Record<string, SqlValue>
30
64
 
31
65
  /**
32
- * A database's migrations: a directory whose .sql files they are, at its root
33
- * or in its one directory, or the files themselves by name.
66
+ * A database's migrations: a directory of .sql files named 0001_notes.sql,
67
+ * 0002_tags.sql, or the files themselves by name, for a program bundled into
68
+ * one file. A relative directory is the working directory's.
34
69
  */
35
- export type Migrations = string | Record<string, string> | readonly { name: string; text: string }[]
70
+ export type Migrations = string | Record<string, string> | readonly { name: string; sql: string }[]
36
71
 
37
- export interface SqlOptions {
38
- /** what the first open applies, on an admin connection, and every later open checks */
72
+ export interface DatabaseOptions {
73
+ /** applied when the file has not, and checked at every open; without them the file opens as it is */
39
74
  migrations?: Migrations
75
+ /**
76
+ * How far this database's commits go before they return, where the
77
+ * store's own is not this file's: `'os'` for what may be lost to a power
78
+ * loss, beside a store of what may not. Its buckets and queues commit
79
+ * with it. A database open already keeps what it was opened with.
80
+ */
81
+ durability?: Durability
40
82
  }
41
83
 
42
- /** What a write changed: the rows, and the rowid of the last it inserted. */
84
+ /** What a write changed: the rows, and SQLite's rowid of the row it inserted, 0 when none. */
43
85
  export interface Done {
44
86
  changes: number
45
- lastId: number
87
+ lastInsertRowid: number | bigint
46
88
  }
47
89
 
48
90
  /**
49
- * A statement's text and arguments, in any of the three ways a call takes
50
- * them: positional after the text, one object of named ones, or a template
51
- * whose values are its arguments.
91
+ * A statement in any of the ways a call takes it: a template whose values are
92
+ * its values, the text and the values of its ?s, the text and one object of
93
+ * named values, or a piece of SQL from `sql`.
52
94
  *
95
+ * db.all`select * from notes where id = ${id}`
53
96
  * db.all('select * from notes where id = ?', id)
54
97
  * db.all('select * from notes where id = :id', { id })
55
- * db.all`select * from notes where id = ${id}`
56
98
  */
57
- export type Statement = [sql: string | TemplateStringsArray, ...args: unknown[]]
99
+ export type Statement = [text: string | TemplateStringsArray | Sql, ...values: unknown[]]
100
+
101
+ /**
102
+ * A piece of SQL and the values of its ?s, which are always values and never
103
+ * SQL. `sql` makes one; a call, a batch and a table's query take it.
104
+ */
105
+ export class Sql {
106
+ readonly text: string
107
+ readonly values: readonly SqlArg[]
108
+ /** whether it stands beside others in an and or an or without parentheses: one column's comparison */
109
+ readonly bare: boolean
110
+
111
+ /** Pieces come from `sql`. */
112
+ constructor(text: string, values: readonly SqlArg[], bare = false) {
113
+ this.text = text
114
+ this.values = values
115
+ this.bare = bare
116
+ }
117
+ }
118
+
119
+ /** Whether text is one group in parentheses, or a bare 0 or 1, which may stand beside others as it is. */
120
+ export function grouped(text: string): boolean {
121
+ if (!text.startsWith('(') || !text.endsWith(')')) {
122
+ return /^[01]$/.test(text)
123
+ }
124
+ let depth = 0
125
+ for (let at = 0; at < text.length; at++) {
126
+ if (text[at] === '(') depth++
127
+ if (text[at] === ')') depth--
128
+ if (depth === 0 && at < text.length - 1) {
129
+ return false
130
+ }
131
+ }
132
+ return true
133
+ }
134
+
135
+ /** Pieces joined with and or or, each in parentheses unless it may stand as it is. */
136
+ export function joinedWith(pieces: readonly Sql[], joiner: string): Sql {
137
+ const several = pieces.length > 1
138
+ return new Sql(
139
+ pieces
140
+ .map(each =>
141
+ several && !each.bare && !standsAlone(each.text) ? `(${each.text})` : each.text,
142
+ )
143
+ .join(` ${joiner} `),
144
+ pieces.flatMap(each => each.values),
145
+ )
146
+ }
147
+
148
+ /**
149
+ * Whether a piece of SQL keeps its meaning beside others in an and or an or:
150
+ * one group, or text with no and or or of its own outside quotes, comments
151
+ * and parentheses, which would bind with its neighbours'.
152
+ */
153
+ export function standsAlone(text: string): boolean {
154
+ if (grouped(text)) {
155
+ return true
156
+ }
157
+ let depth = 0
158
+ for (let at = 0; at < text.length; at++) {
159
+ const c = text[at]!
160
+ if (c === "'" || c === '"' || c === '`') {
161
+ at = closing(text, at, c)
162
+ } else if (c === '-' && text[at + 1] === '-') {
163
+ at = text.indexOf('\n', at)
164
+ if (at < 0) break
165
+ } else if (c === '/' && text[at + 1] === '*') {
166
+ at = text.indexOf('*/', at + 2)
167
+ if (at < 0) break
168
+ at++
169
+ } else if (c === '(') {
170
+ depth++
171
+ } else if (c === ')') {
172
+ depth--
173
+ } else if (depth === 0 && /[a-z]/i.test(c) && !/[a-z0-9_$]/i.test(text[at - 1] ?? '')) {
174
+ const word = /^[a-z_][a-z0-9_$]*/i.exec(text.slice(at))![0]
175
+ if (/^(and|or)$/i.test(word)) {
176
+ return false
177
+ }
178
+ at += word.length - 1
179
+ }
180
+ }
181
+ return true
182
+ }
183
+
184
+ /** Something that writes itself as SQL inside another piece: a table's query. */
185
+ export interface Embeddable {
186
+ /** its text and values, wrapped as a subquery is */
187
+ embedded(): Sql
188
+ }
189
+
190
+ function isEmbeddable(value: unknown): value is Embeddable {
191
+ return (
192
+ typeof value === 'object' &&
193
+ value !== null &&
194
+ typeof (value as Embeddable).embedded === 'function'
195
+ )
196
+ }
197
+
198
+ /** A piece of SQL from a template, or from text and the values of its ?s. */
199
+ function piece(first: TemplateStringsArray | string, values: unknown[]): Sql {
200
+ if (typeof first === 'string') {
201
+ const counted = placeholders(first)
202
+ if (counted.named.length > 0 || counted.numbered) {
203
+ throw new InvalidError(`a piece of SQL takes its values at ? alone: ${first}`)
204
+ }
205
+ if (counted.positional !== values.length) {
206
+ throw new InvalidError(
207
+ `${counted.positional} placeholders and ${values.length} values: each ? takes one value`,
208
+ )
209
+ }
210
+ return new Sql(
211
+ first,
212
+ values.map((value, at) => cellOf(value, `value ${at + 1}`)),
213
+ )
214
+ }
215
+ let text = first[0] ?? ''
216
+ const out: SqlArg[] = []
217
+ values.forEach((value, at) => {
218
+ if (value instanceof Sql) {
219
+ text += value.text
220
+ out.push(...value.values)
221
+ } else if (isEmbeddable(value)) {
222
+ const inner = value.embedded()
223
+ text += inner.text
224
+ out.push(...inner.values)
225
+ } else {
226
+ text += '?'
227
+ out.push(cellOf(value, `value ${at + 1}`))
228
+ }
229
+ text += first[at + 1] ?? ''
230
+ })
231
+ return new Sql(text, out)
232
+ }
233
+
234
+ /** A condition: equal values in an object, or a piece of SQL. */
235
+ export type Condition = Sql | Record<string, unknown>
236
+
237
+ /**
238
+ * A piece of SQL: `` sql`total >= ${min}` ``, or `sql('total >= ?', min)`.
239
+ * Its helpers build the pieces a query's conditions are made of.
240
+ */
241
+ export interface SqlTag {
242
+ (strings: TemplateStringsArray, ...values: unknown[]): Sql
243
+ (text: string, ...values: unknown[]): Sql
244
+ /** conditions joined with or, in parentheses; an empty or finds nothing */
245
+ or(...conditions: Condition[]): Sql
246
+ /** conditions joined with and, in parentheses; an empty and finds everything */
247
+ and(...conditions: Condition[]): Sql
248
+ /** a list for in (…), as one value SQLite reads with json_each: any length, the same statement */
249
+ list(values: readonly unknown[]): Sql
250
+ /** a value kept as its JSON */
251
+ json(value: unknown): Sql
252
+ /** a name, quoted, never SQL: a column a request chooses */
253
+ ident(name: string): Sql
254
+ /** a JSON list in column `name` holding `value` */
255
+ has(name: string, value: unknown): Sql
256
+ }
257
+
258
+ export const sql: SqlTag = Object.assign(
259
+ (first: TemplateStringsArray | string, ...values: unknown[]) => piece(first, values),
260
+ {
261
+ or: (...conditions: Condition[]) => group(conditions, 'or', '0'),
262
+ and: (...conditions: Condition[]) => group(conditions, 'and', '1'),
263
+ list: (values: readonly unknown[]) =>
264
+ new Sql('(select value from json_each(?))', [JSON.stringify(values.map(listed))]),
265
+ json: (value: unknown) => new Sql('?', [JSON.stringify(value)]),
266
+ ident: (name: string) => new Sql(identOf(name), []),
267
+ has: (name: string, value: unknown) =>
268
+ new Sql(`exists (select 1 from json_each(${identOf(name)}) where value = ?)`, [
269
+ cellOf(value, `${name}'s value`),
270
+ ]),
271
+ },
272
+ )
273
+
274
+ /** A list's item as JSON keeps it: a Date as its milliseconds, bytes refused. */
275
+ function listed(value: unknown): unknown {
276
+ if (value instanceof Date) {
277
+ return value.getTime()
278
+ }
279
+ if (typeof value === 'bigint') {
280
+ return Number(value)
281
+ }
282
+ if (value === undefined || value instanceof Uint8Array) {
283
+ throw new InvalidError('a list for in (…) holds text, numbers, booleans and null')
284
+ }
285
+ return value
286
+ }
287
+
288
+ function group(conditions: Condition[], joiner: 'or' | 'and', empty: string): Sql {
289
+ const pieces = conditions.map(conditionOf)
290
+ if (pieces.length === 0) {
291
+ return new Sql(empty, [])
292
+ }
293
+ const joined = joinedWith(pieces, joiner)
294
+ return new Sql(`(${joined.text})`, joined.values)
295
+ }
296
+
297
+ /** A condition as a piece of SQL: equal values written in the order of their columns' names. */
298
+ export function conditionOf(condition: Condition | string): Sql {
299
+ if (condition instanceof Sql) {
300
+ return condition
301
+ }
302
+ if (typeof condition === 'string') {
303
+ return piece(condition, [])
304
+ }
305
+ const names = Object.keys(condition).sort()
306
+ const pieces = names.map(name => equal(name, condition[name]))
307
+ if (pieces.length === 1) {
308
+ return pieces[0]!
309
+ }
310
+ return group(pieces, 'and', '1')
311
+ }
58
312
 
59
- function statementOf(given: Statement): {
60
- sql: string
61
- args?: SqlArg[]
62
- named?: Record<string, SqlArg>
313
+ function equal(name: string, value: unknown): Sql {
314
+ const column = identOf(name)
315
+ if (value === undefined) {
316
+ throw new InvalidError(
317
+ `${name} is undefined, which a filter never leaves out: a missing value is a bug, or an if`,
318
+ )
319
+ }
320
+ if (value === null) {
321
+ return new Sql(`${column} is null`, [], true)
322
+ }
323
+ if (Array.isArray(value)) {
324
+ const list = sql.list(value)
325
+ return new Sql(`${column} in ${list.text}`, list.values, true)
326
+ }
327
+ return new Sql(`${column} = ?`, [cellOf(value, name)], true)
328
+ }
329
+
330
+ /** A name as SQL quotes it: "u"."created_at", each part on its own. */
331
+ export function identOf(name: string): string {
332
+ if (name.length === 0 || name.includes('\0')) {
333
+ throw new InvalidError(`the name ${JSON.stringify(name)}: a name is text without NUL`)
334
+ }
335
+ return name
336
+ .split('.')
337
+ .map(part => `"${part.replaceAll('"', '""')}"`)
338
+ .join('.')
339
+ }
340
+
341
+ /**
342
+ * A value as it leaves: SQLite's five, a boolean, kept as 1 or 0, and a Date,
343
+ * kept as its unix milliseconds. Anything that would arrive changed is
344
+ * refused here, before anything is sent.
345
+ */
346
+ export function cellOf(value: unknown, where: string): SqlArg {
347
+ if (value === undefined) {
348
+ throw new InvalidError(`${where} is undefined: a value that is missing is null, said so`)
349
+ }
350
+ if (typeof value === 'number' && Number.isInteger(value) && !Number.isSafeInteger(value)) {
351
+ throw new InvalidError(
352
+ `${where}, ${value}, is past 2^53, where a number has lost digits: pass a bigint`,
353
+ )
354
+ }
355
+ if (
356
+ value === null ||
357
+ typeof value === 'string' ||
358
+ typeof value === 'number' ||
359
+ typeof value === 'boolean' ||
360
+ typeof value === 'bigint' ||
361
+ value instanceof Uint8Array ||
362
+ value instanceof Date
363
+ ) {
364
+ return value
365
+ }
366
+ if (Array.isArray(value)) {
367
+ throw new InvalidError(
368
+ `${where} is an array: a list for in (…) is sql.list(…), a JSON value sql.json(…)`,
369
+ )
370
+ }
371
+ throw new InvalidError(`${where} is an object: a JSON value is sql.json(…)`)
372
+ }
373
+
374
+ /** What a text's placeholders are, counted outside quotes and comments. */
375
+ export function placeholders(text: string): {
376
+ positional: number
377
+ named: string[]
378
+ numbered: boolean
63
379
  } {
380
+ let positional = 0
381
+ let numbered = false
382
+ const named: string[] = []
383
+ for (let at = 0; at < text.length; at++) {
384
+ const c = text[at]!
385
+ if (c === "'" || c === '"' || c === '`') {
386
+ at = closing(text, at, c)
387
+ } else if (c === '[') {
388
+ at = text.indexOf(']', at + 1)
389
+ if (at < 0) break
390
+ } else if (c === '-' && text[at + 1] === '-') {
391
+ at = text.indexOf('\n', at)
392
+ if (at < 0) break
393
+ } else if (c === '/' && text[at + 1] === '*') {
394
+ at = text.indexOf('*/', at + 2)
395
+ if (at < 0) break
396
+ at++
397
+ } else if (c === '?') {
398
+ if (/[0-9]/.test(text[at + 1] ?? '')) {
399
+ numbered = true
400
+ } else {
401
+ positional++
402
+ }
403
+ } else if ((c === ':' || c === '@' || c === '$') && /[A-Za-z_]/.test(text[at + 1] ?? '')) {
404
+ const name = /^[A-Za-z_][A-Za-z0-9_]*/.exec(text.slice(at + 1))![0]
405
+ if (!named.includes(name)) {
406
+ named.push(name)
407
+ }
408
+ at += name.length
409
+ }
410
+ }
411
+ return { positional, named, numbered }
412
+ }
413
+
414
+ /** The index past a quoted run that starts at `at`, a doubled quote inside it kept. */
415
+ function closing(text: string, at: number, quote: string): number {
416
+ for (let next = at + 1; next < text.length; next++) {
417
+ if (text[next] === quote) {
418
+ if (text[next + 1] === quote) {
419
+ next++
420
+ continue
421
+ }
422
+ return next
423
+ }
424
+ }
425
+ return text.length
426
+ }
427
+
428
+ /** A statement as a piece of SQL, in whichever way it was given. */
429
+ export function statementOf(given: Statement): Sql {
64
430
  const [first, ...rest] = given
431
+ if (first instanceof Sql) {
432
+ if (rest.length > 0) {
433
+ throw new InvalidError('a piece of SQL carries its values: pass it alone')
434
+ }
435
+ return first
436
+ }
65
437
  if (typeof first !== 'string') {
66
- return { sql: first.join('?'), args: rest as SqlArg[] }
438
+ return piece(first, rest)
67
439
  }
68
440
  const only = rest[0]
69
441
  if (rest.length === 1 && isNamed(only)) {
70
- return { sql: first, named: only as Record<string, SqlArg> }
442
+ return namedPiece(first, only as Record<string, unknown>)
71
443
  }
72
- return { sql: first, args: rest as SqlArg[] }
444
+ return piece(first, rest)
73
445
  }
74
446
 
75
447
  function isNamed(value: unknown): boolean {
@@ -78,100 +450,248 @@ function isNamed(value: unknown): boolean {
78
450
  value !== null &&
79
451
  !(value instanceof Date) &&
80
452
  !(value instanceof Uint8Array) &&
453
+ !(value instanceof Sql) &&
81
454
  !Array.isArray(value)
82
455
  )
83
456
  }
84
457
 
85
- /** Opens a database by its name, applying or checking its migrations. */
86
- export async function openDatabase(
87
- link: Link,
88
- name: string,
89
- options?: SqlOptions,
90
- ): Promise<Database> {
91
- checkName(name, 'database')
92
- const migrations =
93
- options?.migrations === undefined ? undefined : await migrationFiles(options.migrations)
94
- const open = SqlDatabase.encode({ name, migrations })
95
- const db = new Database(link, name, open)
96
- await link.run('write', connection => db.handle(connection))
97
- return db
458
+ /** Text with :name values, which SQLite numbers in the order the names first appear. */
459
+ function namedPiece(text: string, values: Record<string, unknown>): Sql {
460
+ const counted = placeholders(text)
461
+ if (counted.positional > 0 || counted.numbered) {
462
+ throw new InvalidError('named values and ? in one statement: give the values one way')
463
+ }
464
+ return new Sql(
465
+ text,
466
+ counted.named.map(name => cellOf(values[name], `:${name}`)),
467
+ )
468
+ }
469
+
470
+ /** Whether a statement may write, which says whether a lost connection may send it again. */
471
+ function mayWrite(text: string): boolean {
472
+ return /\b(insert|update|delete|replace|returning|create|drop|alter|vacuum|reindex|analyze)\b/i.test(
473
+ text,
474
+ )
98
475
  }
99
476
 
100
- async function migrationFiles(given: Migrations): Promise<{ name: string; text: string }[]> {
477
+ async function migrationFiles(given: Migrations): Promise<{ name: string; sql: string }[]> {
101
478
  if (typeof given !== 'string') {
102
479
  const files = Array.isArray(given)
103
- ? [...given]
104
- : Object.entries(given).map(([name, text]) => ({ name, text }))
480
+ ? [...(given as readonly { name: string; sql: string }[])]
481
+ : Object.entries(given as Record<string, string>).map(([name, sql]) => ({ name, sql }))
105
482
  return files.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
106
483
  }
107
- let dir = given
108
- let entries = await readdir(dir, { withFileTypes: true })
109
- if (!entries.some(e => e.isFile() && e.name.endsWith('.sql'))) {
110
- const dirs = entries.filter(e => e.isDirectory())
111
- if (dirs.length === 1) {
112
- dir = join(dir, dirs[0]!.name)
113
- entries = await readdir(dir, { withFileTypes: true })
114
- }
115
- }
484
+ const entries = await readdir(given, { withFileTypes: true })
116
485
  const names = entries
117
- .filter(e => e.isFile() && e.name.endsWith('.sql'))
118
- .map(e => e.name)
486
+ .filter(entry => entry.isFile() && entry.name.endsWith('.sql'))
487
+ .map(entry => entry.name)
119
488
  .sort()
120
- if (names.length === 0) {
121
- throw new InvalidError(`no .sql migrations in ${given}`)
122
- }
123
489
  return Promise.all(
124
- names.map(async name => ({ name, text: await readFile(join(dir, name), 'utf8') })),
490
+ names.map(async name => ({ name, sql: await readFile(join(given, name), 'utf8') })),
125
491
  )
126
492
  }
127
493
 
128
- /** Reads a query's rows as objects, refusing two columns of one name, which one object cannot hold. */
129
- function rowsOf<T>(columns: string[], rows: SqlValue[][]): T[] {
494
+ /** Opens a database by its name, its migrations applied and checked before it resolves. */
495
+ export async function openDatabase(
496
+ link: Link,
497
+ workers: Set<Worker>,
498
+ name: string,
499
+ options: DatabaseOptions = {},
500
+ ): Promise<Database> {
501
+ checkName(name, 'database')
502
+ checkDurability(options.durability, `sql ${name}`)
503
+ const migrations =
504
+ options.migrations === undefined ? undefined : await migrationFiles(options.migrations)
505
+ const open = SqlOpen.encode({ name, migrations, durability: options.durability })
506
+ const db = new Database(link, workers, name, open)
507
+ await link.run('read', connection => db.handle(connection))
508
+ return db
509
+ }
510
+
511
+ /** A query's rows as objects, refusing two columns of one name, which one object cannot hold. */
512
+ export function rowsOf<T>(columns: readonly string[], rows: readonly SqlValue[][]): T[] {
130
513
  if (new Set(columns).size !== columns.length) {
131
- const twice = columns.find((c, i) => columns.indexOf(c) !== i)
514
+ const twice = columns.find((column, at) => columns.indexOf(column) !== at)
132
515
  throw new InvalidError(`two columns named ${twice}: name them apart with as`)
133
516
  }
134
517
  return rows.map(values => {
135
518
  const row: Record<string, SqlValue> = {}
136
- columns.forEach((column, i) => {
137
- row[column] = values[i] ?? null
519
+ columns.forEach((column, at) => {
520
+ row[column] = values[at] ?? null
138
521
  })
139
522
  return row as T
140
523
  })
141
524
  }
142
525
 
143
- function one<T>(rows: T[]): T | undefined {
144
- if (rows.length > 1) {
145
- throw new InvalidError(`a query for one row answered ${rows.length}`)
526
+ /** What one query answered: its columns, and its rows' values. */
527
+ interface Answered {
528
+ columns: string[]
529
+ rows: SqlValue[][]
530
+ }
531
+
532
+ function joined(parts: Uint8Array[]): Answered {
533
+ const answered: Answered = { columns: [], rows: [] }
534
+ for (const body of parts) {
535
+ const part = SqlRows.decode(body)
536
+ if (answered.columns.length === 0) {
537
+ answered.columns = [...(part.columns ?? [])]
538
+ }
539
+ for (const row of part.rows ?? []) {
540
+ answered.rows.push(row as SqlValue[])
541
+ }
146
542
  }
147
- return rows[0]
543
+ return answered
148
544
  }
149
545
 
150
- function scalar<T>(columns: string[], rows: SqlValue[][]): T {
151
- if (rows.length === 0) {
152
- throw new InvalidError('a scalar query answered no row; one always answers, as count(*) does')
546
+ /**
547
+ * A statement's rows by their columns, from the parts of its answer: each
548
+ * column the values `all` gives, in an array sized at the first part. A part
549
+ * packs a column of numbers eight bytes a row, little-endian, as a typed
550
+ * array of every machine Bun and Node run on is.
551
+ */
552
+ function columnsOf(parts: readonly Uint8Array[]): Record<string, SqlValue[]> {
553
+ const names: string[] = []
554
+ const columns: SqlValue[][] = []
555
+ let at = 0
556
+ for (const body of parts) {
557
+ const part = SqlColumns.decode(body)
558
+ for (const [index, held] of (part.columns ?? []).entries()) {
559
+ if (columns.length <= index) {
560
+ names.push(held.name ?? '')
561
+ columns.push(new Array(part.total ?? 0))
562
+ }
563
+ const into = columns[index] as SqlValue[]
564
+ if (held.reals !== undefined) {
565
+ takeReals(into, at, held.reals)
566
+ } else if (held.integers !== undefined) {
567
+ takeIntegers(into, at, held.integers, held.nulls)
568
+ } else {
569
+ const values = held.values ?? []
570
+ for (let row = 0; row < values.length; row++) {
571
+ into[at + row] = values[row] as SqlValue
572
+ }
573
+ }
574
+ }
575
+ at += part.rows ?? 0
153
576
  }
154
- if (columns.length !== 1 || rows.length > 1) {
155
- throw new InvalidError(
156
- `a scalar query answered ${rows.length} rows of ${columns.length} columns`,
157
- )
577
+ if (new Set(names).size !== names.length) {
578
+ const twice = names.find((name, index) => names.indexOf(name) !== index)
579
+ throw new InvalidError(`two columns named ${twice}: name them apart with as`)
580
+ }
581
+ return Object.fromEntries(names.map((name, index) => [name, columns[index] as SqlValue[]]))
582
+ }
583
+
584
+ /**
585
+ * A copy of packed bytes that starts at 0 of its own buffer, as a view of
586
+ * wider elements needs; a Buffer's slice copies nothing.
587
+ */
588
+ function aligned(packed: Uint8Array): ArrayBuffer {
589
+ return new Uint8Array(packed).buffer
590
+ }
591
+
592
+ /**
593
+ * Takes a part's float64s into a column, from its row `at`. A NaN among them
594
+ * is a NULL: SQLite keeps no NaN, and the server writes one where a row
595
+ * holds NULL.
596
+ */
597
+ function takeReals(into: SqlValue[], at: number, reals: Uint8Array) {
598
+ const floats = new Float64Array(aligned(reals))
599
+ for (let row = 0; row < floats.length; row++) {
600
+ const real = floats[row] as number
601
+ into[at + row] = Number.isNaN(real) ? null : real
158
602
  }
159
- return rows[0]![0] as T
160
603
  }
161
604
 
162
605
  /**
163
- * A database. What a call's name starts with says where it runs: exec and
164
- * its kin may write and run on the file's one writer, grouped with the other
165
- * writes; all, one, scalar and each read, on readers that refuse to write.
606
+ * Takes a part's int64s into a column, from its row `at`, each as `all`
607
+ * gives an integer: a number, or a bigint past what a number holds exactly.
166
608
  */
167
- export class Database {
609
+ function takeIntegers(
610
+ into: SqlValue[],
611
+ at: number,
612
+ integers: Uint8Array,
613
+ nulls: Uint8Array | undefined,
614
+ ) {
615
+ const words = new Int32Array(aligned(integers))
616
+ for (let row = 0; row < words.length / 2; row++) {
617
+ const isNull = nulls !== undefined && (((nulls[row >> 3] as number) >> (row & 7)) & 1) === 1
618
+ into[at + row] = isNull
619
+ ? null
620
+ : int64Of(words[2 * row + 1] as number, (words[2 * row] as number) >>> 0)
621
+ }
622
+ }
623
+
624
+ function doneOf(done: {
625
+ changes?: number | undefined
626
+ lastInsertRowid?: bigint | undefined
627
+ }): Done {
628
+ const rowid = done.lastInsertRowid ?? 0n
629
+ const exact = rowid >= BigInt(Number.MIN_SAFE_INTEGER) && rowid <= BigInt(Number.MAX_SAFE_INTEGER)
630
+ return { changes: done.changes ?? 0, lastInsertRowid: exact ? Number(rowid) : rowid }
631
+ }
632
+
633
+ type Want = 'all' | 'one' | 'scalar'
634
+
635
+ /** What reads and writes a database: the database itself, or a transaction of it. */
636
+ export interface Runner {
637
+ readonly describe: string
638
+ rows(statement: Sql, want: Want): Promise<Answered>
639
+ exec(statement: Sql): Promise<Done>
640
+ }
641
+
642
+ /** The reads every runner shares: all, one and scalar over its rows. */
643
+ async function all<T>(runner: Runner, statement: Sql): Promise<T[]> {
644
+ const answered = await runner.rows(statement, 'all')
645
+ return rowsOf<T>(answered.columns, answered.rows)
646
+ }
647
+
648
+ async function one<T>(runner: Runner, statement: Sql): Promise<T | undefined> {
649
+ const answered = await runner.rows(statement, 'one')
650
+ return rowsOf<T>(answered.columns, answered.rows)[0]
651
+ }
652
+
653
+ async function scalar<T>(runner: Runner, statement: Sql): Promise<T> {
654
+ const answered = await runner.rows(statement, 'scalar')
655
+ return answered.rows[0]?.[0] as T
656
+ }
657
+
658
+ /** A transaction whose function is running. */
659
+ interface Running {
660
+ database: Database
661
+ /** set once the function returned or threw: what it left running is outside the transaction */
662
+ ended: boolean
663
+ }
664
+
665
+ // The transactions whose functions the caller runs inside, as its async
666
+ // context carries them: a thread's own stack, for a runtime of one thread.
667
+ const running = new AsyncLocalStorage<readonly Running[]>()
668
+
669
+ /** Whether the caller runs inside the function of a database's transaction. */
670
+ export function insideDatabaseTx(): boolean {
671
+ return running.getStore()?.some(each => !each.ended) === true
672
+ }
673
+
674
+ /**
675
+ * An application's database: `await store.database('app', { migrations })`.
676
+ * The verb says what comes back: all the rows, one or none, one value, or
677
+ * what a write changed. A write with `returning` goes through a read's verb
678
+ * and runs on the writer, its rows given once it is durable.
679
+ */
680
+ export class Database implements Runner, Home {
168
681
  readonly name: string
682
+ readonly describe: string
169
683
  readonly #link: Link
170
684
  readonly #open: Uint8Array
685
+ readonly #workers: Set<Worker>
686
+ /** the buckets and queues kept in the file, by their open: a transaction opens them first */
687
+ readonly #guests = new Map<string, { method: number; open: Open }>()
171
688
 
172
- constructor(link: Link, name: string, open: Uint8Array) {
689
+ /** Databases come from `store.database`. */
690
+ constructor(link: Link, workers: Set<Worker>, name: string, open: Uint8Array) {
173
691
  this.#link = link
692
+ this.#workers = workers
174
693
  this.name = name
694
+ this.describe = `sql ${name}`
175
695
  this.#open = open
176
696
  }
177
697
 
@@ -179,300 +699,467 @@ export class Database {
179
699
  return handleOn(connection, methods['sql.open'], this.#open)
180
700
  }
181
701
 
182
- async #query(given: Statement, write: boolean, signal?: AbortSignal) {
183
- const statement = statementOf(given)
184
- return this.#link.run(write ? 'write' : 'read', async connection => {
185
- const handle = await this.handle(connection)
186
- const stream = await connection.session.open(
187
- methods['sql.query'],
188
- SqlStatement.encode({ handle, ...statement, write: write || undefined }),
189
- true,
702
+ keep(
703
+ method: number,
704
+ bytes: Uint8Array,
705
+ make: (connection: Connection) => Promise<Uint8Array>,
706
+ ): Open {
707
+ const key = `${method}:${Buffer.from(bytes).toString('base64')}`
708
+ const kept = this.#guests.get(key)
709
+ if (kept !== undefined) {
710
+ return kept.open
711
+ }
712
+ this.#guests.set(key, { method, open: make })
713
+ return make
714
+ }
715
+
716
+ via(what: string): Via {
717
+ const link = viaLink(this.#link)
718
+ return {
719
+ call: async (openMethod, open, method, body, idempotence) => {
720
+ this.#refuseAround(what)
721
+ return link.call(openMethod, open, method, body, idempotence)
722
+ },
723
+ ask: async (openMethod, open, method, write, read, idempotence) => {
724
+ this.#refuseAround(what)
725
+ return link.ask(openMethod, open, method, write, read, idempotence)
726
+ },
727
+ }
728
+ }
729
+
730
+ /**
731
+ * Refuses a call made around the database's transaction from inside its
732
+ * function. It would wait for the writer the transaction holds until the
733
+ * server rolled the transaction back, and then commit alone.
734
+ */
735
+ #refuseAround(what: string): void {
736
+ if (running.getStore()?.some(each => each.database === this && !each.ended)) {
737
+ throw new InvalidError(
738
+ `${this.describe}: ${what}: made around the database's transaction from inside it, where it would wait for the writer the transaction holds: make it through the transaction, as tx.exec or tx.with(queue).add`,
190
739
  )
191
- const unwatch = watch(signal, stream)
192
- try {
193
- const head = await stream.next()
194
- const columns = SqlColumns.decode(head.body).columns ?? []
195
- const rows: SqlValue[][] = []
196
- for (;;) {
197
- const event = await stream.next()
198
- stream.consumed(event.body.length)
199
- if (event.end) {
200
- return { columns, rows }
201
- }
202
- rows.push((SqlRow.decode(event.body).values ?? []) as SqlValue[])
203
- }
204
- } finally {
205
- unwatch()
206
- }
207
- })
740
+ }
208
741
  }
209
742
 
210
- /** Every row a query answers, held in memory: the server refuses past 64 MiB of them. */
743
+ /**
744
+ * A bucket of values by key kept in this database's file, beside its
745
+ * tables, as `store.bucket` keeps one in kv.db: the same calls, and its
746
+ * writes commit with the rows in `db.tx`, through `tx.with(bucket)`.
747
+ *
748
+ * const sessions = db.bucket<Session>('sessions', { idle: '30d' })
749
+ */
750
+ bucket<T = unknown>(name: string, options?: BucketOptions): Bucket<T> {
751
+ const bytes = bucketOpen(name, options)
752
+ const open = this.keep(methods['kv.bucket.open'], bytes, async connection =>
753
+ bucketOpen(name, options, await this.handle(connection)),
754
+ )
755
+ return new Bucket<T>(this.#link, name, open, valuesOf(options?.type) as Values<T>, [], this)
756
+ }
757
+
758
+ /**
759
+ * A queue of jobs kept in this database's file, as `store.queue` keeps one
760
+ * in jobs.db: the same calls and workers, and its jobs commit with the
761
+ * rows in `db.tx`, through `tx.with(queue)`. It shares the database's
762
+ * writer, which is the point and its cost.
763
+ *
764
+ * const emails = db.queue<Email>('emails', { attempts: 5 })
765
+ */
766
+ queue<S extends StandardSchemaV1>(
767
+ name: string,
768
+ options: QueueOptions & { schema: S },
769
+ ): Queue<StandardSchemaV1.InferOutput<S>>
770
+ queue<T = unknown>(name: string, options?: QueueOptions): Queue<T>
771
+ queue(name: string, options: QueueOptions & { schema?: StandardSchemaV1 } = {}): Queue<unknown> {
772
+ return openQueue(this.#link, this.#workers, name, options, this)
773
+ }
774
+
775
+ /**
776
+ * An index of a table of this database, kept in its file: its rows found
777
+ * again by their words, vectors or both, each hit's value its row as
778
+ * `all` reads it. The table owns the rows and the index follows them:
779
+ * every change of a row, by any statement, trigger or migration, reaches
780
+ * it in the commit that makes it, and one by a process beside the store
781
+ * within a second.
782
+ *
783
+ * const articles = db.searchIndex<Article>('articles_search', { table: 'articles', fields: { title: 2, body: 1 } })
784
+ */
785
+ searchIndex<T = Row>(name: string, options: TableIndexOptions): TableIndex<T> {
786
+ const bytes = tableIndexOpen(name, options)
787
+ const open = this.keep(methods['search.open'], bytes, async connection =>
788
+ tableIndexOpen(name, options, await this.handle(connection)),
789
+ )
790
+ return new TableIndex<T>(this.via(`index ${name}`), name, open)
791
+ }
792
+
793
+ /** Drops a table's index this database keeps, its triggers off the table; says whether there was one. */
794
+ async dropSearchIndex(name: string): Promise<boolean> {
795
+ const answer = await this.#link.run('write', async connection =>
796
+ connection.session.call(
797
+ methods['search.dropIndex'],
798
+ SearchName.encode({ name, database: await this.handle(connection) }),
799
+ ),
800
+ )
801
+ return SearchDropped.decode(answer).dropped ?? false
802
+ }
803
+
804
+ /** Every row a statement gives: `db.all<Note>\`select * from notes where author_id = ${id}\`` */
211
805
  async all<T = Row>(...statement: Statement): Promise<T[]> {
212
- const { columns, rows } = await this.#query(statement, false)
213
- return rowsOf<T>(columns, rows)
806
+ return all<T>(this, statementOf(statement))
214
807
  }
215
808
 
216
- /** The one row a query answers, undefined for none; two is InvalidError. */
809
+ /** The one row a statement gives, or undefined; two are InvalidError, and a write that gave them rolls back. */
217
810
  async one<T = Row>(...statement: Statement): Promise<T | undefined> {
218
- return one(await this.all<T>(...statement))
811
+ return one<T>(this, statementOf(statement))
219
812
  }
220
813
 
221
- /** The one value of a query that always answers one row, as count(*) does. */
814
+ /** The one value of the one row a statement gives, as count(*) does; null as SQL answers it. */
222
815
  async scalar<T = SqlValue>(...statement: Statement): Promise<T> {
223
- const { columns, rows } = await this.#query(statement, false)
224
- return scalar<T>(columns, rows)
816
+ return scalar<T>(this, statementOf(statement))
225
817
  }
226
818
 
227
- /** The columns and rows of a query as SQLite returned them, arrays rather than objects. */
228
- query(...statement: Statement): Promise<{ columns: string[]; rows: SqlValue[][] }> {
229
- return this.#query(statement, false)
819
+ /**
820
+ * What `all` gives, by its columns: an array a column where `all` gives
821
+ * an object a row, for rows by the thousand, a chart's points. It comes
822
+ * faster, and a chart takes it as it is.
823
+ *
824
+ * const { ts, cpu } = await db.columns<Sample>`select ts, cpu from samples where host = ${host} order by ts`
825
+ */
826
+ async columns<T = Row>(...statement: Statement): Promise<Columns<T>> {
827
+ const piece = statementOf(statement)
828
+ const parts = await this.#answered(piece, methods['sql.columns'], handle =>
829
+ SqlStatement.encode({ handle, text: piece.text, values: [...piece.values] }),
830
+ )
831
+ return columnsOf(parts) as Columns<T>
230
832
  }
231
833
 
232
834
  /**
233
- * Reads a query's rows one at a time as they arrive, within the credit
234
- * the client grants: the client holds a row and the frames in flight.
835
+ * The rows a statement gives, one at a time as their parts arrive: an
836
+ * export that holds one part, not every row. The server reads them from
837
+ * one snapshot, at most 64 MiB.
235
838
  */
236
839
  async *each<T = Row>(...statement: Statement): AsyncGenerator<T> {
237
- const { sql, args, named } = statementOf(statement)
840
+ this.#refuseAround('a read')
841
+ const piece = statementOf(statement)
238
842
  const connection = await this.#link.connection()
239
843
  const handle = await this.handle(connection)
240
- const stream = await connection.session.open(
241
- methods['sql.query'],
242
- SqlStatement.encode({ handle, sql, args, named }),
243
- true,
244
- )
245
- let ended = false
844
+ const body = SqlQuery.encode({
845
+ handle,
846
+ text: piece.text,
847
+ values: [...piece.values],
848
+ want: 'all',
849
+ })
850
+ const stream = await connection.session.open(methods['sql.query'], body, true)
246
851
  try {
247
- const columns = SqlColumns.decode((await stream.next()).body).columns ?? []
248
- rowsOf(columns, [])
852
+ const head = await stream.next()
853
+ if (head.end) {
854
+ const whole = joined([head.body])
855
+ yield* rowsOf<T>(whole.columns, whole.rows)
856
+ return
857
+ }
858
+ let columns: string[] = []
249
859
  for (;;) {
250
860
  const event = await stream.next()
251
861
  stream.consumed(event.body.length)
862
+ const part = joined([event.body])
863
+ if (columns.length === 0) {
864
+ columns = part.columns
865
+ }
866
+ yield* rowsOf<T>(columns, part.rows)
252
867
  if (event.end) {
253
- ended = true
254
868
  return
255
869
  }
256
- yield rowsOf<T>(columns, [(SqlRow.decode(event.body).values ?? []) as SqlValue[]])[0]!
257
870
  }
258
871
  } finally {
259
- if (!ended) {
260
- stream.cancel()
261
- }
872
+ stream.cancel()
262
873
  }
263
874
  }
264
875
 
265
- /** Runs a statement on the writer and says what it changed. */
266
- async exec(...statement: Statement): Promise<Done> {
267
- const given = statementOf(statement)
268
- return this.#link.run('write', async connection => {
876
+ /**
877
+ * A table of the database, typed where it opens: its rows' inserts and
878
+ * upserts, and queries built without SQL text. It costs nothing until its
879
+ * first call; open each once, in the module that owns it.
880
+ *
881
+ * const notes = db.table<Note>('notes', { types: { done: 'bool', created_at: 'time' } })
882
+ */
883
+ table<S extends StandardSchemaV1>(
884
+ name: string,
885
+ options: TableOptions & { schema: S },
886
+ ): Table<StandardSchemaV1.InferOutput<S>>
887
+ table<T = Row>(name: string, options?: TableOptions): Table<T>
888
+ table(name: string, options?: TableOptions): Table<unknown> {
889
+ return new Table(this, name, options)
890
+ }
891
+
892
+ /** Statements known before they run, written as one: all of them or none, in a shared commit. */
893
+ async batch(statements: readonly Sql[]): Promise<Done[]> {
894
+ const texts = statements.map(each => {
895
+ if (!(each instanceof Sql)) {
896
+ throw new InvalidError('a batch takes pieces of SQL: sql`…`')
897
+ }
898
+ return { text: each.text, values: [...each.values] }
899
+ })
900
+ this.#refuseAround('a batch')
901
+ const answered = await this.#link.run('write', async connection => {
269
902
  const handle = await this.handle(connection)
270
- const body = await connection.session.call(
271
- methods['sql.exec'],
272
- SqlStatement.encode({ handle, ...given }),
903
+ return connection.session.call(
904
+ methods['sql.batch'],
905
+ SqlBatch.encode({ handle, statements: texts }),
273
906
  )
274
- const done = SqlDone.decode(body)
275
- return { changes: done.changes ?? 0, lastId: done.lastId ?? 0 }
276
907
  })
908
+ return (SqlBatched.decode(answered).done ?? []).map(doneOf)
277
909
  }
278
910
 
279
- /** The rows a write's returning clause answers, run on the writer. */
280
- async execAll<T = Row>(...statement: Statement): Promise<T[]> {
281
- const { columns, rows } = await this.#query(statement, true)
282
- return rowsOf<T>(columns, rows)
911
+ /**
912
+ * Runs fn in a transaction that holds the writer, for writes that depend on
913
+ * what its reads found: returning commits, a throw rolls back. It runs
914
+ * once, five seconds at most, past which the server rolls it back; inside
915
+ * it, call nothing that waits on the world.
916
+ *
917
+ * await db.tx(async tx => {
918
+ * const left = await tx.scalar<number>`select stock from items where sku = ${sku}`
919
+ * if (left < 1) throw new SoldOut()
920
+ * await tx.exec`update items set stock = stock - 1 where sku = ${sku}`
921
+ * })
922
+ */
923
+ async tx<T>(fn: (tx: SqlTx) => T | Promise<T>): Promise<T> {
924
+ this.#refuseAround('a transaction')
925
+ const connection = await this.#link.connection()
926
+ const handle = await this.handle(connection)
927
+ const guests = await this.#openGuests(connection)
928
+ const stream = await connection.session.open(
929
+ methods['sql.tx'],
930
+ SqlTxOpen.encode({ handle }),
931
+ false,
932
+ )
933
+ await stream.next()
934
+ const tx = new SqlTx(stream, this, connection, guests)
935
+ const inside: Running = { database: this, ended: false }
936
+ let value: T
937
+ try {
938
+ value = await running.run([...(running.getStore() ?? []), inside], () => fn(tx))
939
+ } catch (err) {
940
+ inside.ended = true
941
+ await tx.end(false).catch(() => {})
942
+ throw err
943
+ }
944
+ inside.ended = true
945
+ await tx.end(true)
946
+ return value
283
947
  }
284
948
 
285
- async execOne<T = Row>(...statement: Statement): Promise<T | undefined> {
286
- return one(await this.execAll<T>(...statement))
949
+ /**
950
+ * Opens on `connection` the buckets and queues kept in the file, before a
951
+ * transaction holds its writer: a first open writes the file, and would
952
+ * wait for the writer the transaction holds. One that fails is told when
953
+ * the transaction takes it in.
954
+ */
955
+ async #openGuests(connection: Connection): Promise<Guests> {
956
+ const guests: Guests = new Map()
957
+ const kept = [...this.#guests.values()]
958
+ const settled = await Promise.allSettled(
959
+ kept.map(guest => handleOn(connection, guest.method, guest.open)),
960
+ )
961
+ settled.forEach((outcome, at) => {
962
+ const open = kept[at]?.open
963
+ if (open !== undefined) {
964
+ guests.set(open, outcome.status === 'fulfilled' ? undefined : outcome.reason)
965
+ }
966
+ })
967
+ return guests
287
968
  }
288
969
 
289
- async execScalar<T = SqlValue>(...statement: Statement): Promise<T> {
290
- const { columns, rows } = await this.#query(statement, true)
291
- return scalar<T>(columns, rows)
970
+ async rows(statement: Sql, want: Want): Promise<Answered> {
971
+ const parts = await this.#answered(statement, methods['sql.query'], handle =>
972
+ SqlQuery.encode({ handle, text: statement.text, values: [...statement.values], want }),
973
+ )
974
+ return joined(parts)
292
975
  }
293
976
 
294
- /**
295
- * Runs the statements fn asks for in one transaction, all or none: a
296
- * failure names its statement as `call`. fn returns before anything is
297
- * sent, since no transaction is held across the network, and what it
298
- * returns comes back answered, an array's promises each:
299
- *
300
- * const [note] = await db.batch(tx => [tx.one`insert into notes (title) values (${t}) returning *`])
301
- */
302
- batch<const T = void>(fn: (tx: SqlBatch) => T): Promise<Settled<T>> {
303
- return this.#run(false, fn)
977
+ /** The parts of a statement's answer, all of them: a read may be asked again of another connection, a write not. */
978
+ async #answered(
979
+ statement: Sql,
980
+ method: number,
981
+ asked: (handle: number) => Uint8Array,
982
+ ): Promise<Uint8Array[]> {
983
+ this.#refuseAround('a statement')
984
+ const idempotence: Idempotence = mayWrite(statement.text) ? 'write' : 'read'
985
+ return this.#link.run(idempotence, async connection => {
986
+ const body = asked(await this.handle(connection))
987
+ const { items, trailer } = await download(connection, method, body)
988
+ return [...items, trailer]
989
+ })
304
990
  }
305
991
 
306
- /**
307
- * Runs the reads fn asks for from one snapshot, and gives back what fn
308
- * returns, answered as batch answers it:
309
- *
310
- * const [notes, total] = await db.view(tx => [tx.all`select * from notes`, tx.scalar`select count(*) from notes`])
311
- */
312
- view<const T = void>(fn: (tx: SqlBatch) => T): Promise<Settled<T>> {
313
- return this.#run(true, fn)
992
+ /** Runs a write once it is durable; writes from many callers share a commit, each failing alone. */
993
+ async exec(...statement: Statement): Promise<Done> {
994
+ this.#refuseAround('a write')
995
+ const piece = statementOf(statement)
996
+ const answered = await this.#link.run('write', async connection => {
997
+ const handle = await this.handle(connection)
998
+ const body = SqlStatement.encode({ handle, text: piece.text, values: [...piece.values] })
999
+ return connection.session.call(methods['sql.exec'], body)
1000
+ })
1001
+ return doneOf(SqlDone.decode(answered))
314
1002
  }
1003
+ }
315
1004
 
316
- async #run<T>(read: boolean, fn: (tx: SqlBatch) => T): Promise<Settled<T>> {
317
- const tx = new SqlBatch(read, this.name)
318
- const returned = fn(tx)
319
- tx.close()
320
- if (returned instanceof Promise && !tx.made(returned)) {
321
- throw new InvalidError(
322
- 'a batch function returns before anything is sent; it cannot await inside',
323
- )
324
- }
325
- if (tx.statements.length > 0 || tx.jobs.length > 0) {
326
- await this.#send(read, tx)
1005
+ /** The buckets and queues a transaction opened before it began, each with why its open failed, if it did. */
1006
+ type Guests = Map<Open, unknown>
1007
+
1008
+ /**
1009
+ * A database's transaction, from `db.tx`: its reads see its writes, and a
1010
+ * call that fails leaves it as it was before the call. Its calls go one at a
1011
+ * time, in order.
1012
+ */
1013
+ export class SqlTx implements Runner {
1014
+ readonly describe: string
1015
+ readonly #stream: Stream
1016
+ readonly #database: Database
1017
+ readonly #connection: Connection
1018
+ readonly #guests: Guests
1019
+ readonly #via: Via
1020
+ #last: Promise<unknown> = Promise.resolve()
1021
+
1022
+ /** Transactions come from `db.tx`. */
1023
+ constructor(stream: Stream, database: Database, connection: Connection, guests: Guests) {
1024
+ this.#stream = stream
1025
+ this.#database = database
1026
+ this.#connection = connection
1027
+ this.#guests = guests
1028
+ this.describe = database.describe
1029
+ const call: Via['call'] = async (openMethod, open, method, body) => {
1030
+ const handle = await handleOn(this.#connection, openMethod, open)
1031
+ return this.#nested(method, body(handle))
327
1032
  }
328
- return settle(returned)
1033
+ this.#via = { call, ask: (...asked) => askByCall(call, ...asked) }
329
1034
  }
330
1035
 
331
- async #send(read: boolean, tx: SqlBatch): Promise<void> {
332
- try {
333
- const results = await this.#link.run(read ? 'read' : 'write', async connection => {
334
- const handle = await this.handle(connection)
335
- const jobs = []
336
- for (const queued of tx.jobs) {
337
- const queue = await handleOn(connection, methods['jobs.open'], queued.open)
338
- jobs.push({ handle: queue, jobs: [queued.job] })
339
- }
340
- const body = await connection.session.call(
341
- methods['sql.batch'],
342
- SqlStatements.encode({
343
- handle,
344
- statements: tx.statements.map(s => s.statement),
345
- read: read || undefined,
346
- jobs: jobs.length > 0 ? jobs : undefined,
347
- }),
348
- )
349
- return SqlResults.decode(body).results ?? []
350
- })
351
- tx.statements.forEach((s, i) => {
352
- s.settle(results[i] ?? {})
1036
+ /**
1037
+ * A bucket or a queue opened from this database, inside the transaction:
1038
+ * what it writes commits with the rows or not at all, and what it reads
1039
+ * sees what the transaction wrote.
1040
+ *
1041
+ * await db.tx(async tx => {
1042
+ * const order = await tx.table<Order>('orders').insert({ user_id, total })
1043
+ * await tx.with(emails).add({ order: order.id, to })
1044
+ * })
1045
+ */
1046
+ with<T>(bucket: Bucket<T>): Bucket<T>
1047
+ with<T>(queue: Queue<T>): TxQueue<T>
1048
+ with<T>(channel: Channel<T>): TxChannel<T>
1049
+ with(
1050
+ handle: Bucket<unknown> | Queue<unknown> | Channel<unknown>,
1051
+ ): Bucket<unknown> | TxQueue<unknown> | TxChannel<unknown> {
1052
+ const channel = channelParts(handle)
1053
+ if (channel !== undefined) {
1054
+ // a message published here is handed over once the transaction commits, at the writer
1055
+ return txChannel(channel.name, channel.branch, async body => {
1056
+ await this.#nested(methods['channels.publish'], body)
353
1057
  })
354
- for (const queued of tx.jobs) {
355
- queued.settle()
356
- }
357
- } catch (err) {
358
- for (const s of [...tx.statements, ...tx.jobs]) {
359
- s.fail(err)
360
- }
361
- throw err
362
1058
  }
1059
+ const bucket = partsOf(handle)
1060
+ if (bucket?.values !== undefined && bucket.openMethod === 'kv.bucket.open') {
1061
+ this.#takes(bucket.home, bucket.open, `kv bucket ${bucket.name}`)
1062
+ const { link, name, open, values, under, home } = bucket
1063
+ return new Bucket(link, name, open, values, under, home, this.#via)
1064
+ }
1065
+ const queue = queueParts(handle)
1066
+ if (queue !== undefined) {
1067
+ this.#takes(queue.source.home, queue.source.open, `jobs queue ${queue.name}`)
1068
+ return queueVia(queue, this.#via)
1069
+ }
1070
+ throw new InvalidError(
1071
+ `${this.describe}: a transaction takes in a bucket or a queue opened from its database`,
1072
+ )
363
1073
  }
364
- }
365
1074
 
366
- type Result = ReturnType<typeof SqlResults.decode>['results'] extends (infer R)[] | undefined
367
- ? R
368
- : never
1075
+ async all<T = Row>(...statement: Statement): Promise<T[]> {
1076
+ return all<T>(this, statementOf(statement))
1077
+ }
369
1078
 
370
- interface Batched {
371
- statement: Parameters<typeof SqlStatement.encode>[0]
372
- settle: (result: Result) => void
373
- fail: (err: unknown) => void
374
- }
1079
+ async one<T = Row>(...statement: Statement): Promise<T | undefined> {
1080
+ return one<T>(this, statementOf(statement))
1081
+ }
375
1082
 
376
- /** A job a batch enqueues after its statements, on a queue that lives in its database. */
377
- interface Queued {
378
- /** the queue's jobs.open, whose handle the batch opens on its connection */
379
- open: Uint8Array
380
- job: Parameters<typeof JobsJob.encode>[0]
381
- settle: () => void
382
- fail: (err: unknown) => void
383
- }
1083
+ async scalar<T = SqlValue>(...statement: Statement): Promise<T> {
1084
+ return scalar<T>(this, statementOf(statement))
1085
+ }
384
1086
 
385
- /** The statements of a batch or a view, whose promises settle with it. */
386
- export class SqlBatch {
387
- readonly read: boolean
388
- /** the database the batch runs in, whose queues alone take its jobs */
389
- readonly database: string
390
- readonly statements: Batched[] = []
391
- readonly jobs: Queued[] = []
392
- #done = false
393
- readonly #made = new WeakSet<Promise<unknown>>()
1087
+ async exec(...statement: Statement): Promise<Done> {
1088
+ return this.#call(statementOf(statement), 'exec').then(answer => doneOf(answer.done ?? {}))
1089
+ }
394
1090
 
395
- constructor(read: boolean, database: string) {
396
- this.read = read
397
- this.database = database
1091
+ /** A table inside the transaction: its calls are the transaction's. */
1092
+ table<T = Row>(name: string, options?: TableOptions): Table<T> {
1093
+ return new Table<T>(this, name, options)
398
1094
  }
399
1095
 
400
- close(): void {
401
- this.#done = true
1096
+ async rows(statement: Sql, want: Want): Promise<Answered> {
1097
+ const answer = await this.#call(statement, want)
1098
+ return {
1099
+ columns: [...(answer.rows?.columns ?? [])],
1100
+ rows: (answer.rows?.rows ?? []) as SqlValue[][],
1101
+ }
402
1102
  }
403
1103
 
404
- /** Whether the promise is one of this batch's statements', rather than an async function's. */
405
- made(promise: Promise<unknown>): boolean {
406
- return this.#made.has(promise)
1104
+ /** Sends the last call: commit, or roll back, and waits for the server's word. */
1105
+ async end(commit: boolean): Promise<void> {
1106
+ await this.#last.catch(() => {})
1107
+ await this.#stream.send(SqlTxCall.encode({ commit }), true)
1108
+ await this.#stream.next()
407
1109
  }
408
1110
 
409
1111
  /**
410
- * Adds a job to the batch, for a queue's withTx: a program writes
411
- * `queue.withTx(tx).enqueue(value)`, on a queue opened `in` this database.
1112
+ * Refuses a handle kept elsewhere, whose writes would not commit with the
1113
+ * rows, and one made after the transaction began, whose first open would
1114
+ * wait for the writer the transaction holds.
412
1115
  */
413
- enqueue(open: Uint8Array, job: Queued['job']): Promise<void> {
414
- if (this.read) {
415
- throw new InvalidError('a job in a view, which reads')
1116
+ #takes(home: Home | undefined, open: Open, what: string): void {
1117
+ if (home !== this.#database) {
1118
+ const kept = home === undefined ? 'the store' : home.describe
1119
+ throw new InvalidError(
1120
+ `${what}: kept in ${kept}, outside this transaction of ${this.describe}`,
1121
+ )
416
1122
  }
417
- const { promise, settle, fail } = this.#promise<void>()
418
- this.jobs.push({ open, job, settle: () => settle(undefined), fail })
419
- return promise
420
- }
421
-
422
- #promise<T>(): { promise: Promise<T>; settle: (v: T) => void; fail: (err: unknown) => void } {
423
- if (this.#done) {
1123
+ if (!this.#guests.has(open)) {
424
1124
  throw new InvalidError(
425
- 'a batch takes its statements while its function runs, before it is sent',
1125
+ `${this.describe}: ${what}: made after the transaction began; make it before db.tx, which opens it first`,
426
1126
  )
427
1127
  }
428
- let settle!: (v: T) => void
429
- let fail!: (e: unknown) => void
430
- const promise = new Promise<T>((res, rej) => {
431
- settle = res
432
- fail = rej
433
- })
434
- // a caller need not await a call it only wanted done
435
- promise.catch(() => {})
436
- this.#made.add(promise)
437
- return { promise, settle, fail }
438
- }
439
-
440
- #record<T>(given: Statement, rows: boolean, settle: (result: Result) => T): Promise<T> {
441
- const statement = statementOf(given)
442
- const { promise: settled, settle: resolve, fail: reject } = this.#promise<T>()
443
- this.statements.push({
444
- statement: { ...statement, rows: rows && !this.read ? true : undefined },
445
- settle: result => {
446
- try {
447
- resolve(settle(result))
448
- } catch (err) {
449
- reject(err)
450
- }
451
- },
452
- fail: reject,
453
- })
454
- return settled
455
- }
456
-
457
- exec(...statement: Statement): Promise<Done> {
458
- return this.#record(statement, false, r => ({ changes: r.changes ?? 0, lastId: r.lastId ?? 0 }))
1128
+ const failed = this.#guests.get(open)
1129
+ if (failed !== undefined) {
1130
+ throw failed
1131
+ }
459
1132
  }
460
1133
 
461
- all<T = Row>(...statement: Statement): Promise<T[]> {
462
- return this.#record(statement, true, r =>
463
- rowsOf<T>(r.columns ?? [], (r.rows ?? []) as SqlValue[][]),
464
- )
1134
+ /** A call of kv or jobs in the transaction: its method and its request, and the method's answer. */
1135
+ async #nested(method: number, body: Uint8Array): Promise<Uint8Array> {
1136
+ const answer = await this.#send(SqlTxCall.encode({ want: 'call', method, body }))
1137
+ return answer.body ?? new Uint8Array(0)
465
1138
  }
466
1139
 
467
- one<T = Row>(...statement: Statement): Promise<T | undefined> {
468
- return this.#record(statement, true, r =>
469
- one(rowsOf<T>(r.columns ?? [], (r.rows ?? []) as SqlValue[][])),
1140
+ #call(statement: Sql, want: Want | 'exec') {
1141
+ return this.#send(
1142
+ SqlTxCall.encode({ text: statement.text, values: [...statement.values], want }),
470
1143
  )
471
1144
  }
472
1145
 
473
- scalar<T = SqlValue>(...statement: Statement): Promise<T> {
474
- return this.#record(statement, true, r =>
475
- scalar<T>(r.columns ?? [], (r.rows ?? []) as SqlValue[][]),
476
- )
1146
+ #send(body: Uint8Array) {
1147
+ const call = async () => {
1148
+ await this.#stream.send(body, false)
1149
+ const event = await this.#stream.next()
1150
+ this.#stream.consumed(event.body.length)
1151
+ const answer = SqlTxAnswer.decode(event.body)
1152
+ if (answer.failure !== undefined) {
1153
+ throw errorOf(
1154
+ answer.failure.code ?? 'internal',
1155
+ answer.failure.message ?? '',
1156
+ answer.failure.what ?? {},
1157
+ )
1158
+ }
1159
+ return answer
1160
+ }
1161
+ const next = this.#last.catch(() => {}).then(call)
1162
+ this.#last = next
1163
+ return next
477
1164
  }
478
1165
  }