@tinyshed/tinystore 0.1.0-rc.5 → 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/query.ts ADDED
@@ -0,0 +1,1005 @@
1
+ // A table's queries, built from pieces into the SQL a person would write: the
2
+ // builder adds the ands, the parentheses, the placeholders and the quotes
3
+ // around names, and nothing else. It runs in this process; the server sees
4
+ // the text and the values, as it would a statement written by hand.
5
+
6
+ import { CorruptError, InvalidError } from './errors.ts'
7
+ import { check, type StandardSchemaV1 } from './schema.ts'
8
+ import {
9
+ type Condition,
10
+ cellOf,
11
+ conditionOf,
12
+ type Done,
13
+ type Embeddable,
14
+ grouped,
15
+ identOf,
16
+ joinedWith,
17
+ placeholders,
18
+ type Row,
19
+ type Runner,
20
+ Sql,
21
+ type SqlArg,
22
+ type SqlValue,
23
+ } from './sql.ts'
24
+
25
+ /** How a column SQLite keeps otherwise reads in JavaScript. */
26
+ export type ColumnType = 'bool' | 'time' | 'json' | 'bigint'
27
+
28
+ export interface TableOptions {
29
+ /** the columns SQLite keeps as 0 or 1, unix milliseconds, JSON text or an integer past 2^53 */
30
+ types?: Record<string, ColumnType>
31
+ /** a Standard Schema, zod's or valibot's, that checks each row read */
32
+ schema?: StandardSchemaV1
33
+ }
34
+
35
+ /** What an upsert does when the row's key is taken. */
36
+ export interface UpsertOptions<T> {
37
+ /** the columns whose value, taken, makes the insert an update: the key */
38
+ conflict: string | readonly string[]
39
+ /** the columns the update sets from the row; none other changes */
40
+ update: readonly (keyof T & string)[]
41
+ /** the condition the row that holds the key must meet, its owner's, or it stays as it is */
42
+ where?: Condition | undefined
43
+ }
44
+
45
+ /** A page of a query's rows, and the cursor that reads the next; none after the last. */
46
+ export interface RowPage<T> {
47
+ rows: T[]
48
+ next?: string
49
+ }
50
+
51
+ type Direction = 'asc' | 'desc'
52
+
53
+ /** A condition of a query, and whether it may stand in an and without parentheses. */
54
+ interface Kept {
55
+ piece: Sql
56
+ bare: boolean
57
+ }
58
+
59
+ interface Parts {
60
+ table: string
61
+ alias?: string | undefined
62
+ select?: Sql | undefined
63
+ joins: Sql[]
64
+ conditions: Kept[]
65
+ groups: string[]
66
+ having: Kept[]
67
+ order: { piece: Sql; column?: string | undefined; direction: Direction }[]
68
+ limit?: number | undefined
69
+ offset?: number | undefined
70
+ includes: Included[]
71
+ }
72
+
73
+ /** A query whose rows each row of another holds as a list under a name. */
74
+ interface Included {
75
+ name: string
76
+ parts: Parts
77
+ /** how the included rows read: their table's types and schema */
78
+ source: Source
79
+ /** the names of the columns its select gives, in their order */
80
+ columns: string[]
81
+ }
82
+
83
+ /** How a table reads and writes: its runner, its name, and how its rows read. */
84
+ interface Source {
85
+ runner: Runner
86
+ types: Record<string, ColumnType>
87
+ schema?: StandardSchemaV1 | undefined
88
+ }
89
+
90
+ /**
91
+ * A query on a table: a value, each call returning a new one, so that the
92
+ * first stays as it was. `all`, `one`, `scalar`, `count`, `each` and `list`
93
+ * read; `update` and `delete` write.
94
+ *
95
+ * const urgent = await orders
96
+ * .where({ status: 'pending', deleted: false })
97
+ * .where(sql.or(sql`amount >= ${1000}`, { priority: 'high' }))
98
+ * .orderBy('created_at', 'desc')
99
+ * .limit(50)
100
+ * .all()
101
+ */
102
+ export class Query<T = Row> implements Embeddable {
103
+ readonly #source: Source
104
+ readonly #parts: Parts
105
+
106
+ /** Queries come from `db.table`. */
107
+ constructor(source: Source, parts: Parts) {
108
+ this.#source = source
109
+ this.#parts = parts
110
+ }
111
+
112
+ /**
113
+ * Adds a condition with and: equal values, `null` as is null and a list
114
+ * as in (…); a piece of SQL from `sql`; or text and the values of its ?s.
115
+ * `undefined` is InvalidError, never a filter left out.
116
+ */
117
+ where(condition: Condition | string, ...values: unknown[]): Query<T> {
118
+ return this.#with({ conditions: [...this.#parts.conditions, ...kept(condition, values)] })
119
+ }
120
+
121
+ /** The columns a row holds, as SQL text, and the shape of the row they make. */
122
+ select<R = Row>(columns: string | Sql): Query<R> {
123
+ const select = typeof columns === 'string' ? new Sql(columns, []) : columns
124
+ return new Query<R>(this.#source, { ...this.#parts, select })
125
+ }
126
+
127
+ /**
128
+ * Gives each row the rows of another query as a list under `name`, from
129
+ * the same statement: the query names the row it belongs to in its
130
+ * `where`, by this table's alias, names its columns with `select`, and has
131
+ * a `limit`, which counts for each row. Every value comes back as it is
132
+ * kept, bytes and integers past 2^53 among them.
133
+ *
134
+ * const latest = db.table<Post>('posts as p').select<{ id: string; title: string }>('p.id, p.title')
135
+ * .where('p.author_id = u.id').orderBy('p.id', 'desc').limit(3)
136
+ * const authors = await db.table<User>('users as u').include('posts', latest).all()
137
+ */
138
+ include<N extends string, C>(name: N, query: Query<C>): Query<T & Record<N, C[]>> {
139
+ const describe = `the included ${JSON.stringify(name)}`
140
+ const parts = query.parts
141
+ if (parts.select === undefined) {
142
+ throw new InvalidError(`${describe}: it names its columns with select('p.id, p.title')`)
143
+ }
144
+ if (parts.limit === undefined) {
145
+ throw new InvalidError(`${describe}: it needs a limit, which counts for each row`)
146
+ }
147
+ if (parts.includes.length > 0) {
148
+ throw new InvalidError(`${describe}: an included query includes nothing itself`)
149
+ }
150
+ const included = {
151
+ name,
152
+ parts,
153
+ source: query.source,
154
+ columns: namesOf(parts.select.text, describe),
155
+ }
156
+ const taken = this.#parts.includes.some(each => each.name === name)
157
+ if (taken || name.length === 0) {
158
+ throw new InvalidError(`${describe}: an included list has a name of its own`)
159
+ }
160
+ return new Query<T & Record<N, C[]>>(this.#source, {
161
+ ...this.#parts,
162
+ includes: [...this.#parts.includes, included],
163
+ })
164
+ }
165
+
166
+ /** Joins a table, `'users as u'`, on a condition as SQL text or a piece of SQL. */
167
+ join(table: string, on: string | Sql): Query<T> {
168
+ return this.#joined('join', table, on)
169
+ }
170
+
171
+ /** Joins a table whose columns may be null where no row of it meets the condition. */
172
+ leftJoin(table: string, on: string | Sql): Query<T> {
173
+ return this.#joined('left join', table, on)
174
+ }
175
+
176
+ /** Groups the rows by columns, quoted as names. */
177
+ groupBy(...columns: string[]): Query<T> {
178
+ return this.#with({ groups: [...this.#parts.groups, ...columns.map(identOf)] })
179
+ }
180
+
181
+ /** A condition on the groups, as `where` takes one. */
182
+ having(condition: Condition | string, ...values: unknown[]): Query<T> {
183
+ return this.#with({ having: [...this.#parts.having, ...kept(condition, values)] })
184
+ }
185
+
186
+ /**
187
+ * Orders the rows by a column, quoted as a name, so that a sort a request
188
+ * chooses cannot be SQL, or by a piece of SQL: `` orderBy(sql`lower(title)`) ``.
189
+ */
190
+ orderBy(column: string | Sql, direction: Direction = 'asc'): Query<T> {
191
+ if (direction !== 'asc' && direction !== 'desc') {
192
+ throw new InvalidError(`an order is asc or desc, not ${JSON.stringify(direction)}`)
193
+ }
194
+ const order =
195
+ column instanceof Sql
196
+ ? { piece: column, direction }
197
+ : { piece: new Sql(identOf(column), []), column, direction }
198
+ return this.#with({ order: [...this.#parts.order, order] })
199
+ }
200
+
201
+ limit(rows: number): Query<T> {
202
+ return this.#with({ limit: whole(rows, 'a limit') })
203
+ }
204
+
205
+ offset(rows: number): Query<T> {
206
+ return this.#with({ offset: whole(rows, 'an offset') })
207
+ }
208
+
209
+ /** The text and the values the query sends, to read or to log. */
210
+ toSQL(): { text: string; values: SqlArg[] } {
211
+ const rendered = render(this.#parts)
212
+ return { text: rendered.text, values: [...rendered.values] }
213
+ }
214
+
215
+ /** The query inside another piece of SQL: a subquery, in parentheses. */
216
+ embedded(): Sql {
217
+ const rendered = render(this.#parts)
218
+ return new Sql(`(${rendered.text})`, rendered.values)
219
+ }
220
+
221
+ async all(): Promise<T[]> {
222
+ const answered = await this.#source.runner.rows(render(this.#parts), 'all')
223
+ return this.#rows(answered.columns, answered.rows)
224
+ }
225
+
226
+ async one(): Promise<T | undefined> {
227
+ const answered = await this.#source.runner.rows(render(this.#parts), 'one')
228
+ return (await this.#rows(answered.columns, answered.rows))[0]
229
+ }
230
+
231
+ async scalar<V = SqlValue>(): Promise<V> {
232
+ const answered = await this.#source.runner.rows(render(this.#parts), 'scalar')
233
+ return answered.rows[0]?.[0] as V
234
+ }
235
+
236
+ /** Every row the conditions match, without the order and the limit. */
237
+ async count(): Promise<number> {
238
+ const counted = {
239
+ ...this.#parts,
240
+ select: new Sql('count(*)', []),
241
+ order: [],
242
+ limit: undefined,
243
+ offset: undefined,
244
+ includes: [],
245
+ }
246
+ const statement =
247
+ counted.groups.length === 0
248
+ ? render(counted)
249
+ : new Sql(
250
+ `select count(*) from (${render({ ...counted, select: new Sql('1', []) }).text})`,
251
+ render(counted).values,
252
+ )
253
+ const answered = await this.#source.runner.rows(statement, 'scalar')
254
+ return Number(answered.rows[0]?.[0] ?? 0)
255
+ }
256
+
257
+ /** The rows one at a time, as their parts arrive. */
258
+ async *each(): AsyncGenerator<T> {
259
+ const runner = this.#source.runner as Runner & {
260
+ each?: (statement: Sql) => AsyncGenerator<Row>
261
+ }
262
+ if (runner.each === undefined) {
263
+ yield* await this.all()
264
+ return
265
+ }
266
+ for await (const row of runner.each(render(this.#parts))) {
267
+ yield (await this.#rows(Object.keys(row), [Object.values(row)]))[0]!
268
+ }
269
+ }
270
+
271
+ /**
272
+ * A page after the last row of the one before, by the query's order,
273
+ * which ends in a unique column so that no row is read twice or skipped.
274
+ * `next` reads the next page, and only of this query.
275
+ *
276
+ * const first = await orders.orderBy('created_at', 'desc').orderBy('id', 'desc').list({ limit: 50 })
277
+ * const second = await orders.orderBy('created_at', 'desc').orderBy('id', 'desc').list({ limit: 50, after: first.next })
278
+ */
279
+ async list(
280
+ options: { limit?: number | undefined; after?: string | undefined } = {},
281
+ ): Promise<RowPage<T>> {
282
+ const order = this.#parts.order
283
+ if (order.length === 0 || order.some(each => each.column === undefined)) {
284
+ throw new InvalidError(
285
+ 'a page is read by the query order, of columns by their names: orderBy(…) first',
286
+ )
287
+ }
288
+ const limit = whole(options.limit ?? 100, 'a page limit')
289
+ const digest = digestOf(render({ ...this.#parts, limit: undefined, offset: undefined }))
290
+ let parts: Parts = { ...this.#parts, limit, offset: undefined }
291
+ if (options.after !== undefined) {
292
+ const after = cursorOf(options.after, digest)
293
+ parts = {
294
+ ...parts,
295
+ conditions: [...parts.conditions, { piece: keyset(order, after), bare: true }],
296
+ }
297
+ }
298
+ const answered = await this.#source.runner.rows(render(parts), 'all')
299
+ const rows = await this.#rows(answered.columns, answered.rows)
300
+ if (answered.rows.length < limit) {
301
+ return { rows }
302
+ }
303
+ const last = answered.rows[answered.rows.length - 1]!
304
+ const values = order.map(each => {
305
+ const name = each.column!.split('.').pop()!
306
+ const at = answered.columns.indexOf(name)
307
+ if (at < 0) {
308
+ throw new InvalidError(
309
+ `the page is ordered by ${each.column}, which its rows lack: select it`,
310
+ )
311
+ }
312
+ return last[at] ?? null
313
+ })
314
+ return { rows, next: cursorText(values, digest) }
315
+ }
316
+
317
+ /** SQLite's plan for the query, a line a step. */
318
+ async explain(): Promise<string[]> {
319
+ const rendered = render(this.#parts)
320
+ const answered = await this.#source.runner.rows(
321
+ new Sql(`explain query plan ${rendered.text}`, rendered.values),
322
+ 'all',
323
+ )
324
+ const detail = answered.columns.indexOf('detail')
325
+ return answered.rows.map(row => String(row[detail] ?? ''))
326
+ }
327
+
328
+ /** Sets columns of the rows the conditions match, and says how many changed. */
329
+ async update(values: { [K in keyof T]?: T[K] | Sql } & Record<string, unknown>): Promise<Done> {
330
+ this.#refuseEveryRow('an update')
331
+ const names = Object.keys(values)
332
+ if (names.length === 0) {
333
+ throw new InvalidError('an update sets at least one column')
334
+ }
335
+ const sets: string[] = []
336
+ const out: SqlArg[] = []
337
+ for (const name of names) {
338
+ const value = values[name]
339
+ if (value instanceof Sql) {
340
+ sets.push(`${identOf(name)} = ${value.text}`)
341
+ out.push(...value.values)
342
+ } else {
343
+ sets.push(`${identOf(name)} = ?`)
344
+ out.push(fieldOf(value, name, this.#source.types))
345
+ }
346
+ }
347
+ const where = conditionsText(this.#parts.conditions)
348
+ return this.#source.runner.exec(
349
+ new Sql(`update ${tableName(this.#parts)} set ${sets.join(', ')} where ${where.text}`, [
350
+ ...out,
351
+ ...where.values,
352
+ ]),
353
+ )
354
+ }
355
+
356
+ /** Deletes the rows the conditions match, and says how many it deleted. */
357
+ async delete(): Promise<Done> {
358
+ this.#refuseEveryRow('a delete')
359
+ const where = conditionsText(this.#parts.conditions)
360
+ return this.#source.runner.exec(
361
+ new Sql(`delete from ${tableName(this.#parts)} where ${where.text}`, where.values),
362
+ )
363
+ }
364
+
365
+ /** A row as the table's types and schema read it. */
366
+ protected async read(row: Row): Promise<T> {
367
+ return (await readAs(this.#source, row)) as T
368
+ }
369
+
370
+ protected get source(): Source {
371
+ return this.#source
372
+ }
373
+
374
+ protected get parts(): Parts {
375
+ return this.#parts
376
+ }
377
+
378
+ async #rows(columns: readonly string[], rows: readonly SqlValue[][]): Promise<T[]> {
379
+ const includes = this.#parts.includes
380
+ const out: T[] = []
381
+ for (const values of rows) {
382
+ const row: Row = {}
383
+ const lists: Record<string, unknown[]> = {}
384
+ for (const [at, column] of columns.entries()) {
385
+ const included = includes.find(each => each.name === column)
386
+ if (included === undefined) {
387
+ row[column] = values[at] ?? null
388
+ } else {
389
+ lists[column] = await includedRows(included, values[at] ?? null)
390
+ }
391
+ }
392
+ out.push({ ...((await this.read(row)) as object), ...lists } as T)
393
+ }
394
+ return out
395
+ }
396
+
397
+ #with(changed: Partial<Parts>): Query<T> {
398
+ return new Query<T>(this.#source, { ...this.#parts, ...changed })
399
+ }
400
+
401
+ #joined(kind: string, table: string, on: string | Sql): Query<T> {
402
+ const condition = typeof on === 'string' ? new Sql(on, []) : on
403
+ const ref = tableRef(table)
404
+ const join = new Sql(`${kind} ${ref.text} on ${condition.text}`, condition.values)
405
+ return this.#with({ joins: [...this.#parts.joins, join] })
406
+ }
407
+
408
+ /** Refuses an update or a delete of every row, which SQL says plainly. */
409
+ #refuseEveryRow(what: string): void {
410
+ const conditions = this.#parts.conditions.filter(each => each.piece.text !== '1')
411
+ if (conditions.length === 0) {
412
+ throw new InvalidError(`${what} without a condition: every row is said in SQL, delete from …`)
413
+ }
414
+ if (this.#parts.joins.length > 0) {
415
+ throw new InvalidError(`${what} of a join: write it in SQL`)
416
+ }
417
+ }
418
+ }
419
+
420
+ /**
421
+ * A table: its queries, and its rows' inserts and upserts.
422
+ *
423
+ * const notes = db.table<Note>('notes', { types: { done: 'bool', tags: 'json', created_at: 'time' } })
424
+ * const note = await notes.insert({ id: uuidv7(), author_id: userId, title: 'Buy milk', done: false, tags: [], created_at: new Date() })
425
+ */
426
+ export class Table<T = Row> extends Query<T> {
427
+ readonly name: string
428
+
429
+ /** Tables come from `db.table` and `tx.table`. */
430
+ constructor(runner: Runner, name: string, options: TableOptions = {}) {
431
+ const ref = tableRef(name)
432
+ super(
433
+ { runner, types: options.types ?? {}, schema: options.schema },
434
+ emptyParts(ref.name, ref.alias),
435
+ )
436
+ this.name = ref.name
437
+ }
438
+
439
+ /** Inserts a row and gives it back as the file keeps it; a list of rows is one write, all of them or none. */
440
+ insert(row: Partial<T>): Promise<T>
441
+ insert(rows: readonly Partial<T>[]): Promise<T[]>
442
+ async insert(given: Partial<T> | readonly Partial<T>[]): Promise<T | T[]> {
443
+ const rows = Array.isArray(given) ? (given as readonly Partial<T>[]) : [given as Partial<T>]
444
+ if (rows.length === 0) {
445
+ return []
446
+ }
447
+ const statement = insertOf(
448
+ this.name,
449
+ rows as readonly Record<string, unknown>[],
450
+ this.source.types,
451
+ )
452
+ const answered = await this.source.runner.rows(
453
+ new Sql(`${statement.text} returning *`, statement.values),
454
+ 'all',
455
+ )
456
+ const read: T[] = []
457
+ for (const values of answered.rows) {
458
+ const row: Row = {}
459
+ answered.columns.forEach((column, at) => {
460
+ row[column] = values[at] ?? null
461
+ })
462
+ read.push(await this.read(row))
463
+ }
464
+ return Array.isArray(given) ? read : read[0]!
465
+ }
466
+
467
+ /**
468
+ * Inserts a row, or, when its key is taken, sets the columns `update`
469
+ * names on the row that holds it, if that row meets `where`. It gives
470
+ * back the row as the file keeps it, or undefined when `where` kept it.
471
+ */
472
+ async upsert(row: Partial<T>, options: UpsertOptions<T>): Promise<T | undefined> {
473
+ const conflict = (
474
+ typeof options.conflict === 'string' ? [options.conflict] : [...options.conflict]
475
+ ).map(identOf)
476
+ if (options.update.length === 0) {
477
+ throw new InvalidError('an upsert names the columns its update sets')
478
+ }
479
+ const insert = insertOf(this.name, [row as Record<string, unknown>], this.source.types)
480
+ const sets = options.update
481
+ .map(name => `${identOf(name)} = excluded.${identOf(name)}`)
482
+ .join(', ')
483
+ let text = `${insert.text} on conflict (${conflict.join(', ')}) do update set ${sets}`
484
+ const values = [...insert.values]
485
+ if (options.where !== undefined) {
486
+ // in an upsert's update, a column is the row's that holds the key
487
+ const where = conditionOf(options.where)
488
+ text += ` where ${where.text}`
489
+ values.push(...where.values)
490
+ }
491
+ const answered = await this.source.runner.rows(new Sql(`${text} returning *`, values), 'one')
492
+ if (answered.rows.length === 0) {
493
+ return undefined
494
+ }
495
+ const read: Row = {}
496
+ answered.columns.forEach((column, at) => {
497
+ read[column] = answered.rows[0]![at] ?? null
498
+ })
499
+ return this.read(read)
500
+ }
501
+ }
502
+
503
+ function emptyParts(table: string, alias?: string): Parts {
504
+ return {
505
+ table,
506
+ alias,
507
+ joins: [],
508
+ conditions: [],
509
+ groups: [],
510
+ having: [],
511
+ order: [],
512
+ includes: [],
513
+ }
514
+ }
515
+
516
+ /** A row as a table's types and schema read it. */
517
+ async function readAs(source: Source, row: Row): Promise<unknown> {
518
+ const typed: Record<string, unknown> = { ...row }
519
+ for (const [column, type] of Object.entries(source.types)) {
520
+ if (column in typed) {
521
+ typed[column] = typedOf(typed[column] as SqlValue, type, column)
522
+ }
523
+ }
524
+ if (source.schema === undefined) {
525
+ return typed
526
+ }
527
+ const checked = await check(source.schema, typed)
528
+ if ('issues' in checked) {
529
+ throw new InvalidError(`a row does not meet the table's schema: ${checked.issues}`)
530
+ }
531
+ return checked.value
532
+ }
533
+
534
+ /** The rows a row's included query gave, read as that query's table reads them. */
535
+ async function includedRows(included: Included, kept: SqlValue): Promise<unknown[]> {
536
+ if (kept === null) {
537
+ return []
538
+ }
539
+ if (typeof kept !== 'string') {
540
+ throw new CorruptError(`the included ${JSON.stringify(included.name)} came back as no text`)
541
+ }
542
+ const rows: unknown[] = []
543
+ for (const values of literalRows(kept)) {
544
+ const row: Row = {}
545
+ included.columns.forEach((column, at) => {
546
+ row[column] = values[at] ?? null
547
+ })
548
+ rows.push(await readAs(included.source, row))
549
+ }
550
+ return rows
551
+ }
552
+
553
+ /**
554
+ * The names of the columns a select's text gives, in their order: a column's
555
+ * own name, or what follows its `as`. An expression without a name is
556
+ * refused, since its rows could not be given their fields.
557
+ */
558
+ export function namesOf(select: string, describe: string): string[] {
559
+ const name = `("(?:[^"]|"")+"|[A-Za-z_][\\w$]*)`
560
+ const aliased = new RegExp(`\\s+as\\s+${name}\\s*$`, 'i')
561
+ const column = new RegExp(`^(?:${name}\\.)?${name}$`)
562
+ const bare = (quoted: string) =>
563
+ quoted.startsWith('"') ? quoted.slice(1, -1).replaceAll('""', '"') : quoted
564
+ const names: string[] = []
565
+ for (const item of itemsOf(select)) {
566
+ const found = aliased.exec(item)?.[1] ?? column.exec(item)?.[2]
567
+ if (found === undefined) {
568
+ throw new InvalidError(
569
+ `${describe}: the column ${JSON.stringify(item)} needs a name: write it as … as name`,
570
+ )
571
+ }
572
+ if (names.includes(bare(found))) {
573
+ throw new InvalidError(`${describe}: two columns named ${bare(found)}`)
574
+ }
575
+ names.push(bare(found))
576
+ }
577
+ return names
578
+ }
579
+
580
+ /** A select's items: its text cut at the commas outside quotes and parentheses. */
581
+ function itemsOf(select: string): string[] {
582
+ const items: string[] = []
583
+ let [depth, from, at] = [0, 0, 0]
584
+ while (at < select.length) {
585
+ const c = select[at] as string
586
+ if (c === "'" || c === '"' || c === '`') {
587
+ at = select.indexOf(c, at + 1)
588
+ if (at < 0) {
589
+ break
590
+ }
591
+ } else if (c === '(') {
592
+ depth++
593
+ } else if (c === ')') {
594
+ depth--
595
+ } else if (c === ',' && depth === 0) {
596
+ items.push(select.slice(from, at).trim())
597
+ from = at + 1
598
+ }
599
+ at++
600
+ }
601
+ items.push(select.slice(from).trim())
602
+ return items
603
+ }
604
+
605
+ /**
606
+ * An included query as one value of its row: its rows as SQL literals,
607
+ * `(1,'a'),(2,NULL)`, in the query's order. SQLite's quote() writes an
608
+ * integer, a float, a text and bytes so that each reads back as it is kept,
609
+ * where JSON would lose bytes and the last digits of a float.
610
+ */
611
+ function includedText(included: Included): Sql {
612
+ const child = included.parts
613
+ const order = child.order.map((each, at) => ({ ...each, alias: `"$o${at + 1}"` }))
614
+ const select = child.select as Sql
615
+ const inner = render({
616
+ ...child,
617
+ select: new Sql(
618
+ [select.text, ...order.map(each => `${each.piece.text} as ${each.alias}`)].join(', '),
619
+ [...select.values, ...order.flatMap(each => each.piece.values)],
620
+ ),
621
+ })
622
+ const row = included.columns.map(literalOf).join(" || ',' || ")
623
+ const ordered =
624
+ order.length === 0
625
+ ? ''
626
+ : ` order by ${order.map(each => `${each.alias} ${each.direction}`).join(', ')}`
627
+ return new Sql(
628
+ `(select group_concat('(' || ${row} || ')', ','${ordered}) from (${inner.text}))`,
629
+ inner.values,
630
+ )
631
+ }
632
+
633
+ /** A column as an SQL literal that keeps it whole: quote() cuts a text at a zero byte, so such a text goes as its bytes. */
634
+ function literalOf(column: string): string {
635
+ const c = `"${column.replaceAll('"', '""')}"`
636
+ return `case when typeof(${c}) = 'text' and instr(cast(${c} as blob), x'00') > 0 then 'T' || quote(cast(${c} as blob)) else quote(${c}) end`
637
+ }
638
+
639
+ /** The rows an included query gave, read from their literals: `(1,'it''s',NULL),(2,X'00ff',1.5)`. */
640
+ export function literalRows(text: string): SqlValue[][] {
641
+ const reader = new Literals(text)
642
+ const rows: SqlValue[][] = []
643
+ while (!reader.done) {
644
+ reader.expect('(')
645
+ const row = [reader.literal()]
646
+ while (reader.next === ',') {
647
+ reader.expect(',')
648
+ row.push(reader.literal())
649
+ }
650
+ reader.expect(')')
651
+ rows.push(row)
652
+ if (!reader.done) {
653
+ reader.expect(',')
654
+ }
655
+ }
656
+ return rows
657
+ }
658
+
659
+ /** A reader of SQL literals as SQLite's quote() writes them. */
660
+ class Literals {
661
+ readonly #text: string
662
+ #at = 0
663
+
664
+ constructor(text: string) {
665
+ this.#text = text
666
+ }
667
+
668
+ get done(): boolean {
669
+ return this.#at >= this.#text.length
670
+ }
671
+
672
+ get next(): string | undefined {
673
+ return this.#text[this.#at]
674
+ }
675
+
676
+ expect(wanted: string): void {
677
+ if (this.next !== wanted) {
678
+ throw this.#broken()
679
+ }
680
+ this.#at++
681
+ }
682
+
683
+ literal(): SqlValue {
684
+ switch (this.next) {
685
+ case "'":
686
+ return this.#quoted()
687
+ case 'X':
688
+ return this.#hex()
689
+ case 'T':
690
+ this.#at++
691
+ return new TextDecoder().decode(this.#hex())
692
+ }
693
+ if (this.#text.startsWith('NULL', this.#at)) {
694
+ this.#at += 4
695
+ return null
696
+ }
697
+ return this.#number()
698
+ }
699
+
700
+ /** A text in single quotes, a quote inside it doubled. */
701
+ #quoted(): string {
702
+ let value = ''
703
+ for (this.#at++; ; this.#at++) {
704
+ const end = this.#text.indexOf("'", this.#at)
705
+ if (end < 0) {
706
+ throw this.#broken()
707
+ }
708
+ value += this.#text.slice(this.#at, end)
709
+ this.#at = end + 1
710
+ if (this.next !== "'") {
711
+ return value
712
+ }
713
+ value += "'"
714
+ }
715
+ }
716
+
717
+ /** Bytes as `X'00ff'`. */
718
+ #hex(): Uint8Array {
719
+ const end = this.#text.indexOf("'", this.#at + 2)
720
+ const digits = this.#text.slice(this.#at + 2, Math.max(end, 0))
721
+ if (
722
+ !this.#text.startsWith("X'", this.#at) ||
723
+ end < 0 ||
724
+ !/^(?:[0-9A-Fa-f]{2})*$/.test(digits)
725
+ ) {
726
+ throw this.#broken()
727
+ }
728
+ this.#at = end + 1
729
+ return new Uint8Array(Buffer.from(digits, 'hex'))
730
+ }
731
+
732
+ /** An integer, a bigint past 2^53, or a float, which quote() writes with a point or an exponent. */
733
+ #number(): number | bigint {
734
+ let end = this.#at
735
+ while (end < this.#text.length && this.#text[end] !== ',' && this.#text[end] !== ')') {
736
+ end++
737
+ }
738
+ const word = this.#text.slice(this.#at, end)
739
+ if (/^-?\d+$/.test(word)) {
740
+ this.#at = end
741
+ const whole = BigInt(word)
742
+ return whole >= Number.MIN_SAFE_INTEGER && whole <= Number.MAX_SAFE_INTEGER
743
+ ? Number(whole)
744
+ : whole
745
+ }
746
+ if (word.length === 0 || Number.isNaN(Number(word))) {
747
+ throw this.#broken()
748
+ }
749
+ this.#at = end
750
+ return Number(word)
751
+ }
752
+
753
+ #broken(): CorruptError {
754
+ const shown = this.#text.slice(this.#at, this.#at + 20)
755
+ return new CorruptError(`included rows that do not read at ${this.#at}: ${shown}`)
756
+ }
757
+ }
758
+
759
+ /** `'orders'` or `'orders as o'`, quoted as names. */
760
+ function tableRef(text: string): { name: string; alias?: string | undefined; text: string } {
761
+ const matched =
762
+ /^\s*([A-Za-z_][\w$]*(?:\.[A-Za-z_][\w$]*)?)(?:\s+(?:as\s+)?([A-Za-z_][\w$]*))?\s*$/i.exec(text)
763
+ if (matched === null) {
764
+ throw new InvalidError(
765
+ `the table ${JSON.stringify(text)}: a table is its name, and an alias after as`,
766
+ )
767
+ }
768
+ const [, name, alias] = matched
769
+ return {
770
+ name: name!,
771
+ alias,
772
+ text: alias === undefined ? identOf(name!) : `${identOf(name!)} as ${identOf(alias)}`,
773
+ }
774
+ }
775
+
776
+ function tableName(parts: Parts): string {
777
+ return identOf(parts.table)
778
+ }
779
+
780
+ /** A condition `where` takes, as the pieces an and joins. */
781
+ function kept(condition: Condition | string, values: unknown[]): Kept[] {
782
+ if (typeof condition === 'string') {
783
+ const counted = placeholders(condition)
784
+ if (counted.positional !== values.length || counted.named.length > 0 || counted.numbered) {
785
+ throw new InvalidError(
786
+ `${counted.positional} placeholders and ${values.length} values: each ? takes one value`,
787
+ )
788
+ }
789
+ return [
790
+ {
791
+ piece: new Sql(
792
+ condition,
793
+ values.map((value, at) => cellOf(value, `value ${at + 1}`)),
794
+ ),
795
+ bare: false,
796
+ },
797
+ ]
798
+ }
799
+ if (values.length > 0) {
800
+ throw new InvalidError('a condition that is not text carries its values: pass it alone')
801
+ }
802
+ if (condition instanceof Sql) {
803
+ return [{ piece: condition, bare: condition.bare || grouped(condition.text) }]
804
+ }
805
+ return Object.keys(condition)
806
+ .sort()
807
+ .map(name => ({ piece: conditionOf({ [name]: condition[name] }), bare: true }))
808
+ }
809
+
810
+ function conditionsText(conditions: readonly Kept[]): Sql {
811
+ return joinedWith(
812
+ conditions.map(each =>
813
+ each.bare ? new Sql(each.piece.text, each.piece.values, true) : each.piece,
814
+ ),
815
+ 'and',
816
+ )
817
+ }
818
+
819
+ /** The query as one statement. */
820
+ function render(parts: Parts): Sql {
821
+ const values: SqlArg[] = []
822
+ const from =
823
+ parts.alias === undefined
824
+ ? identOf(parts.table)
825
+ : `${identOf(parts.table)} as ${identOf(parts.alias)}`
826
+ let columns = '*'
827
+ if (parts.select !== undefined) {
828
+ columns = parts.select.text
829
+ values.push(...parts.select.values)
830
+ } else if (parts.joins.length > 0 || parts.includes.length > 0) {
831
+ columns = `${identOf(parts.alias ?? parts.table)}.*`
832
+ }
833
+ for (const included of parts.includes) {
834
+ const list = includedText(included)
835
+ columns += `, ${list.text} as ${identOf(included.name)}`
836
+ values.push(...list.values)
837
+ }
838
+ let text = `select ${columns} from ${from}`
839
+ for (const join of parts.joins) {
840
+ text += ` ${join.text}`
841
+ values.push(...join.values)
842
+ }
843
+ if (parts.conditions.length > 0) {
844
+ const where = conditionsText(parts.conditions)
845
+ text += ` where ${where.text}`
846
+ values.push(...where.values)
847
+ }
848
+ if (parts.groups.length > 0) {
849
+ text += ` group by ${parts.groups.join(', ')}`
850
+ }
851
+ if (parts.having.length > 0) {
852
+ const having = conditionsText(parts.having)
853
+ text += ` having ${having.text}`
854
+ values.push(...having.values)
855
+ }
856
+ if (parts.order.length > 0) {
857
+ text += ` order by ${parts.order.map(each => `${each.piece.text} ${each.direction}`).join(', ')}`
858
+ values.push(...parts.order.flatMap(each => each.piece.values))
859
+ }
860
+ if (parts.limit !== undefined) {
861
+ text += ' limit cast(? as integer)'
862
+ values.push(parts.limit)
863
+ }
864
+ if (parts.offset !== undefined) {
865
+ text += `${parts.limit === undefined ? ' limit -1' : ''} offset cast(? as integer)`
866
+ values.push(parts.offset)
867
+ }
868
+ return new Sql(text, values)
869
+ }
870
+
871
+ /** The condition that starts a page after a row's order values. */
872
+ function keyset(order: Parts['order'], after: readonly SqlValue[]): Sql {
873
+ const alternatives: string[] = []
874
+ const values: SqlArg[] = []
875
+ order.forEach((each, at) => {
876
+ const equal = order.slice(0, at).map(earlier => `${earlier.piece.text} = ?`)
877
+ values.push(...after.slice(0, at))
878
+ const past = `${each.piece.text} ${each.direction === 'asc' ? '>' : '<'} ?`
879
+ values.push(after[at] ?? null)
880
+ alternatives.push(equal.length === 0 ? past : `(${[...equal, past].join(' and ')})`)
881
+ })
882
+ return new Sql(`(${alternatives.join(' or ')})`, values)
883
+ }
884
+
885
+ /** A short digest of a query, which a cursor carries so that another query refuses it. */
886
+ function digestOf(statement: Sql): string {
887
+ let hash = 0x811c9dc5
888
+ const text = `${statement.text}\u0000${JSON.stringify(statement.values, (_, v) => (typeof v === 'bigint' ? `${v}n` : v))}`
889
+ for (let at = 0; at < text.length; at++) {
890
+ hash ^= text.charCodeAt(at)
891
+ hash = Math.imul(hash, 0x01000193) >>> 0
892
+ }
893
+ return hash.toString(36)
894
+ }
895
+
896
+ function cursorText(values: readonly SqlValue[], digest: string): string {
897
+ const json = JSON.stringify({ q: digest, v: values }, (_, v) =>
898
+ typeof v === 'bigint' ? { n: String(v) } : v,
899
+ )
900
+ return Buffer.from(json).toString('base64url')
901
+ }
902
+
903
+ function cursorOf(cursor: string, digest: string): SqlValue[] {
904
+ let read: { q?: string; v?: unknown[] }
905
+ try {
906
+ read = JSON.parse(Buffer.from(cursor, 'base64url').toString())
907
+ } catch {
908
+ throw new InvalidError('a cursor that is not one: pass the next of a page')
909
+ }
910
+ if (read.q !== digest || !Array.isArray(read.v)) {
911
+ throw new InvalidError(
912
+ "a cursor of another query: a page's next reads only the query that made it",
913
+ )
914
+ }
915
+ return read.v.map(v =>
916
+ typeof v === 'object' && v !== null && 'n' in v
917
+ ? BigInt((v as { n: string }).n)
918
+ : (v as SqlValue),
919
+ )
920
+ }
921
+
922
+ /** An insert of rows of the same columns, the first row's. */
923
+ function insertOf(
924
+ table: string,
925
+ rows: readonly Record<string, unknown>[],
926
+ types: Record<string, ColumnType>,
927
+ ): Sql {
928
+ const names = Object.keys(rows[0]!).filter(name => rows[0]![name] !== undefined)
929
+ if (names.length === 0) {
930
+ throw new InvalidError('a row to insert with no column')
931
+ }
932
+ const values: SqlArg[] = []
933
+ const tuples = rows.map((row, at) => {
934
+ const extra = Object.keys(row).filter(name => !names.includes(name) && row[name] !== undefined)
935
+ if (extra.length > 0) {
936
+ throw new InvalidError(
937
+ `row ${at + 1} has ${extra.join(', ')}, which the first row has not: insert rows of one shape`,
938
+ )
939
+ }
940
+ for (const name of names) {
941
+ values.push(fieldOf(row[name], name, types))
942
+ }
943
+ return `(${names.map(() => '?').join(', ')})`
944
+ })
945
+ return new Sql(
946
+ `insert into ${identOf(table)} (${names.map(identOf).join(', ')}) values ${tuples.join(', ')}`,
947
+ values,
948
+ )
949
+ }
950
+
951
+ /** A row's field as it is written: an array or an object as its JSON. */
952
+ function fieldOf(value: unknown, name: string, types: Record<string, ColumnType>): SqlArg {
953
+ if (value === undefined) {
954
+ throw new InvalidError(
955
+ `${name} is undefined, which never sets a column to null: leave the field out, or say null`,
956
+ )
957
+ }
958
+ if (
959
+ types[name] === 'json' ||
960
+ (typeof value === 'object' &&
961
+ value !== null &&
962
+ !(value instanceof Date) &&
963
+ !(value instanceof Uint8Array))
964
+ ) {
965
+ return JSON.stringify(value)
966
+ }
967
+ return cellOf(value, name)
968
+ }
969
+
970
+ /** A stored value as its column's type reads it. */
971
+ function typedOf(value: SqlValue, type: ColumnType, column: string): unknown {
972
+ if (value === null) {
973
+ return null
974
+ }
975
+ switch (type) {
976
+ case 'bool':
977
+ if (value === 0 || value === 1) {
978
+ return value === 1
979
+ }
980
+ break
981
+ case 'time':
982
+ if (typeof value === 'number' || typeof value === 'bigint') {
983
+ return new Date(Number(value))
984
+ }
985
+ break
986
+ case 'json':
987
+ if (typeof value === 'string') {
988
+ return JSON.parse(value)
989
+ }
990
+ break
991
+ case 'bigint':
992
+ if (typeof value === 'number' || typeof value === 'bigint') {
993
+ return BigInt(value)
994
+ }
995
+ break
996
+ }
997
+ throw new InvalidError(`column ${column}: ${String(value)} does not read as ${type}`)
998
+ }
999
+
1000
+ function whole(n: number, what: string): number {
1001
+ if (!Number.isSafeInteger(n) || n < 0) {
1002
+ throw new InvalidError(`${what} of ${n}: a whole number`)
1003
+ }
1004
+ return n
1005
+ }