@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/dist/sql.js CHANGED
@@ -1,342 +1,847 @@
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.
6
+ import { AsyncLocalStorage } from 'node:async_hooks';
5
7
  import { readdir, readFile } from 'node:fs/promises';
6
8
  import { join } from 'node:path';
7
- import { InvalidError } from './errors.js';
8
- import { checkName, handleOn, settle } from './handles.js';
9
- import { watch } from './session.js';
10
- import { methods, SqlColumns, SqlDatabase, SqlDone, SqlResults, SqlRow, SqlStatement, SqlStatements, } from './wire/messages.js';
11
- function statementOf(given) {
9
+ import { channelParts, txChannel } from './channels.js';
10
+ import { checkDurability, download } from './connection.js';
11
+ import { errorOf, InvalidError } from './errors.js';
12
+ import { askByCall, checkName, handleOn, viaLink, } from './handles.js';
13
+ import { openQueue, queueParts, queueVia, } from './jobs.js';
14
+ import { Bucket, bucketOpen, partsOf, valuesOf } from './kv.js';
15
+ import { Table } from './query.js';
16
+ import { TableIndex, tableIndexOpen } from './search.js';
17
+ import { int64Of } from './wire/msgpack.js';
18
+ import { methods, SearchDropped, SearchName, SqlBatch, SqlBatched, SqlColumns, SqlDone, SqlOpen, SqlQuery, SqlRows, SqlStatement, SqlTxAnswer, SqlTxCall, SqlTxOpen, } from './wire/protocol.js';
19
+ /**
20
+ * A piece of SQL and the values of its ?s, which are always values and never
21
+ * SQL. `sql` makes one; a call, a batch and a table's query take it.
22
+ */
23
+ export class Sql {
24
+ text;
25
+ values;
26
+ /** whether it stands beside others in an and or an or without parentheses: one column's comparison */
27
+ bare;
28
+ /** Pieces come from `sql`. */
29
+ constructor(text, values, bare = false) {
30
+ this.text = text;
31
+ this.values = values;
32
+ this.bare = bare;
33
+ }
34
+ }
35
+ /** Whether text is one group in parentheses, or a bare 0 or 1, which may stand beside others as it is. */
36
+ export function grouped(text) {
37
+ if (!text.startsWith('(') || !text.endsWith(')')) {
38
+ return /^[01]$/.test(text);
39
+ }
40
+ let depth = 0;
41
+ for (let at = 0; at < text.length; at++) {
42
+ if (text[at] === '(')
43
+ depth++;
44
+ if (text[at] === ')')
45
+ depth--;
46
+ if (depth === 0 && at < text.length - 1) {
47
+ return false;
48
+ }
49
+ }
50
+ return true;
51
+ }
52
+ /** Pieces joined with and or or, each in parentheses unless it may stand as it is. */
53
+ export function joinedWith(pieces, joiner) {
54
+ const several = pieces.length > 1;
55
+ return new Sql(pieces
56
+ .map(each => several && !each.bare && !standsAlone(each.text) ? `(${each.text})` : each.text)
57
+ .join(` ${joiner} `), pieces.flatMap(each => each.values));
58
+ }
59
+ /**
60
+ * Whether a piece of SQL keeps its meaning beside others in an and or an or:
61
+ * one group, or text with no and or or of its own outside quotes, comments
62
+ * and parentheses, which would bind with its neighbours'.
63
+ */
64
+ export function standsAlone(text) {
65
+ if (grouped(text)) {
66
+ return true;
67
+ }
68
+ let depth = 0;
69
+ for (let at = 0; at < text.length; at++) {
70
+ const c = text[at];
71
+ if (c === "'" || c === '"' || c === '`') {
72
+ at = closing(text, at, c);
73
+ }
74
+ else if (c === '-' && text[at + 1] === '-') {
75
+ at = text.indexOf('\n', at);
76
+ if (at < 0)
77
+ break;
78
+ }
79
+ else if (c === '/' && text[at + 1] === '*') {
80
+ at = text.indexOf('*/', at + 2);
81
+ if (at < 0)
82
+ break;
83
+ at++;
84
+ }
85
+ else if (c === '(') {
86
+ depth++;
87
+ }
88
+ else if (c === ')') {
89
+ depth--;
90
+ }
91
+ else if (depth === 0 && /[a-z]/i.test(c) && !/[a-z0-9_$]/i.test(text[at - 1] ?? '')) {
92
+ const word = /^[a-z_][a-z0-9_$]*/i.exec(text.slice(at))[0];
93
+ if (/^(and|or)$/i.test(word)) {
94
+ return false;
95
+ }
96
+ at += word.length - 1;
97
+ }
98
+ }
99
+ return true;
100
+ }
101
+ function isEmbeddable(value) {
102
+ return (typeof value === 'object' &&
103
+ value !== null &&
104
+ typeof value.embedded === 'function');
105
+ }
106
+ /** A piece of SQL from a template, or from text and the values of its ?s. */
107
+ function piece(first, values) {
108
+ if (typeof first === 'string') {
109
+ const counted = placeholders(first);
110
+ if (counted.named.length > 0 || counted.numbered) {
111
+ throw new InvalidError(`a piece of SQL takes its values at ? alone: ${first}`);
112
+ }
113
+ if (counted.positional !== values.length) {
114
+ throw new InvalidError(`${counted.positional} placeholders and ${values.length} values: each ? takes one value`);
115
+ }
116
+ return new Sql(first, values.map((value, at) => cellOf(value, `value ${at + 1}`)));
117
+ }
118
+ let text = first[0] ?? '';
119
+ const out = [];
120
+ values.forEach((value, at) => {
121
+ if (value instanceof Sql) {
122
+ text += value.text;
123
+ out.push(...value.values);
124
+ }
125
+ else if (isEmbeddable(value)) {
126
+ const inner = value.embedded();
127
+ text += inner.text;
128
+ out.push(...inner.values);
129
+ }
130
+ else {
131
+ text += '?';
132
+ out.push(cellOf(value, `value ${at + 1}`));
133
+ }
134
+ text += first[at + 1] ?? '';
135
+ });
136
+ return new Sql(text, out);
137
+ }
138
+ export const sql = Object.assign((first, ...values) => piece(first, values), {
139
+ or: (...conditions) => group(conditions, 'or', '0'),
140
+ and: (...conditions) => group(conditions, 'and', '1'),
141
+ list: (values) => new Sql('(select value from json_each(?))', [JSON.stringify(values.map(listed))]),
142
+ json: (value) => new Sql('?', [JSON.stringify(value)]),
143
+ ident: (name) => new Sql(identOf(name), []),
144
+ has: (name, value) => new Sql(`exists (select 1 from json_each(${identOf(name)}) where value = ?)`, [
145
+ cellOf(value, `${name}'s value`),
146
+ ]),
147
+ });
148
+ /** A list's item as JSON keeps it: a Date as its milliseconds, bytes refused. */
149
+ function listed(value) {
150
+ if (value instanceof Date) {
151
+ return value.getTime();
152
+ }
153
+ if (typeof value === 'bigint') {
154
+ return Number(value);
155
+ }
156
+ if (value === undefined || value instanceof Uint8Array) {
157
+ throw new InvalidError('a list for in (…) holds text, numbers, booleans and null');
158
+ }
159
+ return value;
160
+ }
161
+ function group(conditions, joiner, empty) {
162
+ const pieces = conditions.map(conditionOf);
163
+ if (pieces.length === 0) {
164
+ return new Sql(empty, []);
165
+ }
166
+ const joined = joinedWith(pieces, joiner);
167
+ return new Sql(`(${joined.text})`, joined.values);
168
+ }
169
+ /** A condition as a piece of SQL: equal values written in the order of their columns' names. */
170
+ export function conditionOf(condition) {
171
+ if (condition instanceof Sql) {
172
+ return condition;
173
+ }
174
+ if (typeof condition === 'string') {
175
+ return piece(condition, []);
176
+ }
177
+ const names = Object.keys(condition).sort();
178
+ const pieces = names.map(name => equal(name, condition[name]));
179
+ if (pieces.length === 1) {
180
+ return pieces[0];
181
+ }
182
+ return group(pieces, 'and', '1');
183
+ }
184
+ function equal(name, value) {
185
+ const column = identOf(name);
186
+ if (value === undefined) {
187
+ throw new InvalidError(`${name} is undefined, which a filter never leaves out: a missing value is a bug, or an if`);
188
+ }
189
+ if (value === null) {
190
+ return new Sql(`${column} is null`, [], true);
191
+ }
192
+ if (Array.isArray(value)) {
193
+ const list = sql.list(value);
194
+ return new Sql(`${column} in ${list.text}`, list.values, true);
195
+ }
196
+ return new Sql(`${column} = ?`, [cellOf(value, name)], true);
197
+ }
198
+ /** A name as SQL quotes it: "u"."created_at", each part on its own. */
199
+ export function identOf(name) {
200
+ if (name.length === 0 || name.includes('\0')) {
201
+ throw new InvalidError(`the name ${JSON.stringify(name)}: a name is text without NUL`);
202
+ }
203
+ return name
204
+ .split('.')
205
+ .map(part => `"${part.replaceAll('"', '""')}"`)
206
+ .join('.');
207
+ }
208
+ /**
209
+ * A value as it leaves: SQLite's five, a boolean, kept as 1 or 0, and a Date,
210
+ * kept as its unix milliseconds. Anything that would arrive changed is
211
+ * refused here, before anything is sent.
212
+ */
213
+ export function cellOf(value, where) {
214
+ if (value === undefined) {
215
+ throw new InvalidError(`${where} is undefined: a value that is missing is null, said so`);
216
+ }
217
+ if (typeof value === 'number' && Number.isInteger(value) && !Number.isSafeInteger(value)) {
218
+ throw new InvalidError(`${where}, ${value}, is past 2^53, where a number has lost digits: pass a bigint`);
219
+ }
220
+ if (value === null ||
221
+ typeof value === 'string' ||
222
+ typeof value === 'number' ||
223
+ typeof value === 'boolean' ||
224
+ typeof value === 'bigint' ||
225
+ value instanceof Uint8Array ||
226
+ value instanceof Date) {
227
+ return value;
228
+ }
229
+ if (Array.isArray(value)) {
230
+ throw new InvalidError(`${where} is an array: a list for in (…) is sql.list(…), a JSON value sql.json(…)`);
231
+ }
232
+ throw new InvalidError(`${where} is an object: a JSON value is sql.json(…)`);
233
+ }
234
+ /** What a text's placeholders are, counted outside quotes and comments. */
235
+ export function placeholders(text) {
236
+ let positional = 0;
237
+ let numbered = false;
238
+ const named = [];
239
+ for (let at = 0; at < text.length; at++) {
240
+ const c = text[at];
241
+ if (c === "'" || c === '"' || c === '`') {
242
+ at = closing(text, at, c);
243
+ }
244
+ else if (c === '[') {
245
+ at = text.indexOf(']', at + 1);
246
+ if (at < 0)
247
+ break;
248
+ }
249
+ else if (c === '-' && text[at + 1] === '-') {
250
+ at = text.indexOf('\n', at);
251
+ if (at < 0)
252
+ break;
253
+ }
254
+ else if (c === '/' && text[at + 1] === '*') {
255
+ at = text.indexOf('*/', at + 2);
256
+ if (at < 0)
257
+ break;
258
+ at++;
259
+ }
260
+ else if (c === '?') {
261
+ if (/[0-9]/.test(text[at + 1] ?? '')) {
262
+ numbered = true;
263
+ }
264
+ else {
265
+ positional++;
266
+ }
267
+ }
268
+ else if ((c === ':' || c === '@' || c === '$') && /[A-Za-z_]/.test(text[at + 1] ?? '')) {
269
+ const name = /^[A-Za-z_][A-Za-z0-9_]*/.exec(text.slice(at + 1))[0];
270
+ if (!named.includes(name)) {
271
+ named.push(name);
272
+ }
273
+ at += name.length;
274
+ }
275
+ }
276
+ return { positional, named, numbered };
277
+ }
278
+ /** The index past a quoted run that starts at `at`, a doubled quote inside it kept. */
279
+ function closing(text, at, quote) {
280
+ for (let next = at + 1; next < text.length; next++) {
281
+ if (text[next] === quote) {
282
+ if (text[next + 1] === quote) {
283
+ next++;
284
+ continue;
285
+ }
286
+ return next;
287
+ }
288
+ }
289
+ return text.length;
290
+ }
291
+ /** A statement as a piece of SQL, in whichever way it was given. */
292
+ export function statementOf(given) {
12
293
  const [first, ...rest] = given;
294
+ if (first instanceof Sql) {
295
+ if (rest.length > 0) {
296
+ throw new InvalidError('a piece of SQL carries its values: pass it alone');
297
+ }
298
+ return first;
299
+ }
13
300
  if (typeof first !== 'string') {
14
- return { sql: first.join('?'), args: rest };
301
+ return piece(first, rest);
15
302
  }
16
303
  const only = rest[0];
17
304
  if (rest.length === 1 && isNamed(only)) {
18
- return { sql: first, named: only };
305
+ return namedPiece(first, only);
19
306
  }
20
- return { sql: first, args: rest };
307
+ return piece(first, rest);
21
308
  }
22
309
  function isNamed(value) {
23
310
  return (typeof value === 'object' &&
24
311
  value !== null &&
25
312
  !(value instanceof Date) &&
26
313
  !(value instanceof Uint8Array) &&
314
+ !(value instanceof Sql) &&
27
315
  !Array.isArray(value));
28
316
  }
29
- /** Opens a database by its name, applying or checking its migrations. */
30
- export async function openDatabase(link, name, options) {
31
- checkName(name, 'database');
32
- const migrations = options?.migrations === undefined ? undefined : await migrationFiles(options.migrations);
33
- const open = SqlDatabase.encode({ name, migrations });
34
- const db = new Database(link, name, open);
35
- await link.run('write', connection => db.handle(connection));
36
- return db;
317
+ /** Text with :name values, which SQLite numbers in the order the names first appear. */
318
+ function namedPiece(text, values) {
319
+ const counted = placeholders(text);
320
+ if (counted.positional > 0 || counted.numbered) {
321
+ throw new InvalidError('named values and ? in one statement: give the values one way');
322
+ }
323
+ return new Sql(text, counted.named.map(name => cellOf(values[name], `:${name}`)));
324
+ }
325
+ /** Whether a statement may write, which says whether a lost connection may send it again. */
326
+ function mayWrite(text) {
327
+ return /\b(insert|update|delete|replace|returning|create|drop|alter|vacuum|reindex|analyze)\b/i.test(text);
37
328
  }
38
329
  async function migrationFiles(given) {
39
330
  if (typeof given !== 'string') {
40
331
  const files = Array.isArray(given)
41
332
  ? [...given]
42
- : Object.entries(given).map(([name, text]) => ({ name, text }));
333
+ : Object.entries(given).map(([name, sql]) => ({ name, sql }));
43
334
  return files.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
44
335
  }
45
- let dir = given;
46
- let entries = await readdir(dir, { withFileTypes: true });
47
- if (!entries.some(e => e.isFile() && e.name.endsWith('.sql'))) {
48
- const dirs = entries.filter(e => e.isDirectory());
49
- if (dirs.length === 1) {
50
- dir = join(dir, dirs[0].name);
51
- entries = await readdir(dir, { withFileTypes: true });
52
- }
53
- }
336
+ const entries = await readdir(given, { withFileTypes: true });
54
337
  const names = entries
55
- .filter(e => e.isFile() && e.name.endsWith('.sql'))
56
- .map(e => e.name)
338
+ .filter(entry => entry.isFile() && entry.name.endsWith('.sql'))
339
+ .map(entry => entry.name)
57
340
  .sort();
58
- if (names.length === 0) {
59
- throw new InvalidError(`no .sql migrations in ${given}`);
60
- }
61
- return Promise.all(names.map(async (name) => ({ name, text: await readFile(join(dir, name), 'utf8') })));
341
+ return Promise.all(names.map(async (name) => ({ name, sql: await readFile(join(given, name), 'utf8') })));
62
342
  }
63
- /** Reads a query's rows as objects, refusing two columns of one name, which one object cannot hold. */
64
- function rowsOf(columns, rows) {
343
+ /** Opens a database by its name, its migrations applied and checked before it resolves. */
344
+ export async function openDatabase(link, workers, name, options = {}) {
345
+ checkName(name, 'database');
346
+ checkDurability(options.durability, `sql ${name}`);
347
+ const migrations = options.migrations === undefined ? undefined : await migrationFiles(options.migrations);
348
+ const open = SqlOpen.encode({ name, migrations, durability: options.durability });
349
+ const db = new Database(link, workers, name, open);
350
+ await link.run('read', connection => db.handle(connection));
351
+ return db;
352
+ }
353
+ /** A query's rows as objects, refusing two columns of one name, which one object cannot hold. */
354
+ export function rowsOf(columns, rows) {
65
355
  if (new Set(columns).size !== columns.length) {
66
- const twice = columns.find((c, i) => columns.indexOf(c) !== i);
356
+ const twice = columns.find((column, at) => columns.indexOf(column) !== at);
67
357
  throw new InvalidError(`two columns named ${twice}: name them apart with as`);
68
358
  }
69
359
  return rows.map(values => {
70
360
  const row = {};
71
- columns.forEach((column, i) => {
72
- row[column] = values[i] ?? null;
361
+ columns.forEach((column, at) => {
362
+ row[column] = values[at] ?? null;
73
363
  });
74
364
  return row;
75
365
  });
76
366
  }
77
- function one(rows) {
78
- if (rows.length > 1) {
79
- throw new InvalidError(`a query for one row answered ${rows.length}`);
367
+ function joined(parts) {
368
+ const answered = { columns: [], rows: [] };
369
+ for (const body of parts) {
370
+ const part = SqlRows.decode(body);
371
+ if (answered.columns.length === 0) {
372
+ answered.columns = [...(part.columns ?? [])];
373
+ }
374
+ for (const row of part.rows ?? []) {
375
+ answered.rows.push(row);
376
+ }
377
+ }
378
+ return answered;
379
+ }
380
+ /**
381
+ * A statement's rows by their columns, from the parts of its answer: each
382
+ * column the values `all` gives, in an array sized at the first part. A part
383
+ * packs a column of numbers eight bytes a row, little-endian, as a typed
384
+ * array of every machine Bun and Node run on is.
385
+ */
386
+ function columnsOf(parts) {
387
+ const names = [];
388
+ const columns = [];
389
+ let at = 0;
390
+ for (const body of parts) {
391
+ const part = SqlColumns.decode(body);
392
+ for (const [index, held] of (part.columns ?? []).entries()) {
393
+ if (columns.length <= index) {
394
+ names.push(held.name ?? '');
395
+ columns.push(new Array(part.total ?? 0));
396
+ }
397
+ const into = columns[index];
398
+ if (held.reals !== undefined) {
399
+ takeReals(into, at, held.reals);
400
+ }
401
+ else if (held.integers !== undefined) {
402
+ takeIntegers(into, at, held.integers, held.nulls);
403
+ }
404
+ else {
405
+ const values = held.values ?? [];
406
+ for (let row = 0; row < values.length; row++) {
407
+ into[at + row] = values[row];
408
+ }
409
+ }
410
+ }
411
+ at += part.rows ?? 0;
412
+ }
413
+ if (new Set(names).size !== names.length) {
414
+ const twice = names.find((name, index) => names.indexOf(name) !== index);
415
+ throw new InvalidError(`two columns named ${twice}: name them apart with as`);
80
416
  }
81
- return rows[0];
417
+ return Object.fromEntries(names.map((name, index) => [name, columns[index]]));
82
418
  }
83
- function scalar(columns, rows) {
84
- if (rows.length === 0) {
85
- throw new InvalidError('a scalar query answered no row; one always answers, as count(*) does');
419
+ /**
420
+ * A copy of packed bytes that starts at 0 of its own buffer, as a view of
421
+ * wider elements needs; a Buffer's slice copies nothing.
422
+ */
423
+ function aligned(packed) {
424
+ return new Uint8Array(packed).buffer;
425
+ }
426
+ /**
427
+ * Takes a part's float64s into a column, from its row `at`. A NaN among them
428
+ * is a NULL: SQLite keeps no NaN, and the server writes one where a row
429
+ * holds NULL.
430
+ */
431
+ function takeReals(into, at, reals) {
432
+ const floats = new Float64Array(aligned(reals));
433
+ for (let row = 0; row < floats.length; row++) {
434
+ const real = floats[row];
435
+ into[at + row] = Number.isNaN(real) ? null : real;
86
436
  }
87
- if (columns.length !== 1 || rows.length > 1) {
88
- throw new InvalidError(`a scalar query answered ${rows.length} rows of ${columns.length} columns`);
437
+ }
438
+ /**
439
+ * Takes a part's int64s into a column, from its row `at`, each as `all`
440
+ * gives an integer: a number, or a bigint past what a number holds exactly.
441
+ */
442
+ function takeIntegers(into, at, integers, nulls) {
443
+ const words = new Int32Array(aligned(integers));
444
+ for (let row = 0; row < words.length / 2; row++) {
445
+ const isNull = nulls !== undefined && ((nulls[row >> 3] >> (row & 7)) & 1) === 1;
446
+ into[at + row] = isNull
447
+ ? null
448
+ : int64Of(words[2 * row + 1], words[2 * row] >>> 0);
89
449
  }
90
- return rows[0][0];
450
+ }
451
+ function doneOf(done) {
452
+ const rowid = done.lastInsertRowid ?? 0n;
453
+ const exact = rowid >= BigInt(Number.MIN_SAFE_INTEGER) && rowid <= BigInt(Number.MAX_SAFE_INTEGER);
454
+ return { changes: done.changes ?? 0, lastInsertRowid: exact ? Number(rowid) : rowid };
455
+ }
456
+ /** The reads every runner shares: all, one and scalar over its rows. */
457
+ async function all(runner, statement) {
458
+ const answered = await runner.rows(statement, 'all');
459
+ return rowsOf(answered.columns, answered.rows);
460
+ }
461
+ async function one(runner, statement) {
462
+ const answered = await runner.rows(statement, 'one');
463
+ return rowsOf(answered.columns, answered.rows)[0];
464
+ }
465
+ async function scalar(runner, statement) {
466
+ const answered = await runner.rows(statement, 'scalar');
467
+ return answered.rows[0]?.[0];
468
+ }
469
+ // The transactions whose functions the caller runs inside, as its async
470
+ // context carries them: a thread's own stack, for a runtime of one thread.
471
+ const running = new AsyncLocalStorage();
472
+ /** Whether the caller runs inside the function of a database's transaction. */
473
+ export function insideDatabaseTx() {
474
+ return running.getStore()?.some(each => !each.ended) === true;
91
475
  }
92
476
  /**
93
- * A database. What a call's name starts with says where it runs: exec and
94
- * its kin may write and run on the file's one writer, grouped with the other
95
- * writes; all, one, scalar and each read, on readers that refuse to write.
477
+ * An application's database: `await store.database('app', { migrations })`.
478
+ * The verb says what comes back: all the rows, one or none, one value, or
479
+ * what a write changed. A write with `returning` goes through a read's verb
480
+ * and runs on the writer, its rows given once it is durable.
96
481
  */
97
482
  export class Database {
98
483
  name;
484
+ describe;
99
485
  #link;
100
486
  #open;
101
- constructor(link, name, open) {
487
+ #workers;
488
+ /** the buckets and queues kept in the file, by their open: a transaction opens them first */
489
+ #guests = new Map();
490
+ /** Databases come from `store.database`. */
491
+ constructor(link, workers, name, open) {
102
492
  this.#link = link;
493
+ this.#workers = workers;
103
494
  this.name = name;
495
+ this.describe = `sql ${name}`;
104
496
  this.#open = open;
105
497
  }
106
498
  handle(connection) {
107
499
  return handleOn(connection, methods['sql.open'], this.#open);
108
500
  }
109
- async #query(given, write, signal) {
110
- const statement = statementOf(given);
111
- return this.#link.run(write ? 'write' : 'read', async (connection) => {
112
- const handle = await this.handle(connection);
113
- const stream = await connection.session.open(methods['sql.query'], SqlStatement.encode({ handle, ...statement, write: write || undefined }), true);
114
- const unwatch = watch(signal, stream);
115
- try {
116
- const head = await stream.next();
117
- const columns = SqlColumns.decode(head.body).columns ?? [];
118
- const rows = [];
119
- for (;;) {
120
- const event = await stream.next();
121
- stream.consumed(event.body.length);
122
- if (event.end) {
123
- return { columns, rows };
124
- }
125
- rows.push((SqlRow.decode(event.body).values ?? []));
126
- }
127
- }
128
- finally {
129
- unwatch();
130
- }
131
- });
501
+ keep(method, bytes, make) {
502
+ const key = `${method}:${Buffer.from(bytes).toString('base64')}`;
503
+ const kept = this.#guests.get(key);
504
+ if (kept !== undefined) {
505
+ return kept.open;
506
+ }
507
+ this.#guests.set(key, { method, open: make });
508
+ return make;
509
+ }
510
+ via(what) {
511
+ const link = viaLink(this.#link);
512
+ return {
513
+ call: async (openMethod, open, method, body, idempotence) => {
514
+ this.#refuseAround(what);
515
+ return link.call(openMethod, open, method, body, idempotence);
516
+ },
517
+ ask: async (openMethod, open, method, write, read, idempotence) => {
518
+ this.#refuseAround(what);
519
+ return link.ask(openMethod, open, method, write, read, idempotence);
520
+ },
521
+ };
132
522
  }
133
- /** Every row a query answers, held in memory: the server refuses past 64 MiB of them. */
523
+ /**
524
+ * Refuses a call made around the database's transaction from inside its
525
+ * function. It would wait for the writer the transaction holds until the
526
+ * server rolled the transaction back, and then commit alone.
527
+ */
528
+ #refuseAround(what) {
529
+ if (running.getStore()?.some(each => each.database === this && !each.ended)) {
530
+ throw new InvalidError(`${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`);
531
+ }
532
+ }
533
+ /**
534
+ * A bucket of values by key kept in this database's file, beside its
535
+ * tables, as `store.bucket` keeps one in kv.db: the same calls, and its
536
+ * writes commit with the rows in `db.tx`, through `tx.with(bucket)`.
537
+ *
538
+ * const sessions = db.bucket<Session>('sessions', { idle: '30d' })
539
+ */
540
+ bucket(name, options) {
541
+ const bytes = bucketOpen(name, options);
542
+ const open = this.keep(methods['kv.bucket.open'], bytes, async (connection) => bucketOpen(name, options, await this.handle(connection)));
543
+ return new Bucket(this.#link, name, open, valuesOf(options?.type), [], this);
544
+ }
545
+ queue(name, options = {}) {
546
+ return openQueue(this.#link, this.#workers, name, options, this);
547
+ }
548
+ /**
549
+ * An index of a table of this database, kept in its file: its rows found
550
+ * again by their words, vectors or both, each hit's value its row as
551
+ * `all` reads it. The table owns the rows and the index follows them:
552
+ * every change of a row, by any statement, trigger or migration, reaches
553
+ * it in the commit that makes it, and one by a process beside the store
554
+ * within a second.
555
+ *
556
+ * const articles = db.searchIndex<Article>('articles_search', { table: 'articles', fields: { title: 2, body: 1 } })
557
+ */
558
+ searchIndex(name, options) {
559
+ const bytes = tableIndexOpen(name, options);
560
+ const open = this.keep(methods['search.open'], bytes, async (connection) => tableIndexOpen(name, options, await this.handle(connection)));
561
+ return new TableIndex(this.via(`index ${name}`), name, open);
562
+ }
563
+ /** Drops a table's index this database keeps, its triggers off the table; says whether there was one. */
564
+ async dropSearchIndex(name) {
565
+ const answer = await this.#link.run('write', async (connection) => connection.session.call(methods['search.dropIndex'], SearchName.encode({ name, database: await this.handle(connection) })));
566
+ return SearchDropped.decode(answer).dropped ?? false;
567
+ }
568
+ /** Every row a statement gives: `db.all<Note>\`select * from notes where author_id = ${id}\`` */
134
569
  async all(...statement) {
135
- const { columns, rows } = await this.#query(statement, false);
136
- return rowsOf(columns, rows);
570
+ return all(this, statementOf(statement));
137
571
  }
138
- /** The one row a query answers, undefined for none; two is InvalidError. */
572
+ /** The one row a statement gives, or undefined; two are InvalidError, and a write that gave them rolls back. */
139
573
  async one(...statement) {
140
- return one(await this.all(...statement));
574
+ return one(this, statementOf(statement));
141
575
  }
142
- /** The one value of a query that always answers one row, as count(*) does. */
576
+ /** The one value of the one row a statement gives, as count(*) does; null as SQL answers it. */
143
577
  async scalar(...statement) {
144
- const { columns, rows } = await this.#query(statement, false);
145
- return scalar(columns, rows);
578
+ return scalar(this, statementOf(statement));
146
579
  }
147
- /** The columns and rows of a query as SQLite returned them, arrays rather than objects. */
148
- query(...statement) {
149
- return this.#query(statement, false);
580
+ /**
581
+ * What `all` gives, by its columns: an array a column where `all` gives
582
+ * an object a row, for rows by the thousand, a chart's points. It comes
583
+ * faster, and a chart takes it as it is.
584
+ *
585
+ * const { ts, cpu } = await db.columns<Sample>`select ts, cpu from samples where host = ${host} order by ts`
586
+ */
587
+ async columns(...statement) {
588
+ const piece = statementOf(statement);
589
+ const parts = await this.#answered(piece, methods['sql.columns'], handle => SqlStatement.encode({ handle, text: piece.text, values: [...piece.values] }));
590
+ return columnsOf(parts);
150
591
  }
151
592
  /**
152
- * Reads a query's rows one at a time as they arrive, within the credit
153
- * the client grants: the client holds a row and the frames in flight.
593
+ * The rows a statement gives, one at a time as their parts arrive: an
594
+ * export that holds one part, not every row. The server reads them from
595
+ * one snapshot, at most 64 MiB.
154
596
  */
155
597
  async *each(...statement) {
156
- const { sql, args, named } = statementOf(statement);
598
+ this.#refuseAround('a read');
599
+ const piece = statementOf(statement);
157
600
  const connection = await this.#link.connection();
158
601
  const handle = await this.handle(connection);
159
- const stream = await connection.session.open(methods['sql.query'], SqlStatement.encode({ handle, sql, args, named }), true);
160
- let ended = false;
602
+ const body = SqlQuery.encode({
603
+ handle,
604
+ text: piece.text,
605
+ values: [...piece.values],
606
+ want: 'all',
607
+ });
608
+ const stream = await connection.session.open(methods['sql.query'], body, true);
161
609
  try {
162
- const columns = SqlColumns.decode((await stream.next()).body).columns ?? [];
163
- rowsOf(columns, []);
610
+ const head = await stream.next();
611
+ if (head.end) {
612
+ const whole = joined([head.body]);
613
+ yield* rowsOf(whole.columns, whole.rows);
614
+ return;
615
+ }
616
+ let columns = [];
164
617
  for (;;) {
165
618
  const event = await stream.next();
166
619
  stream.consumed(event.body.length);
620
+ const part = joined([event.body]);
621
+ if (columns.length === 0) {
622
+ columns = part.columns;
623
+ }
624
+ yield* rowsOf(columns, part.rows);
167
625
  if (event.end) {
168
- ended = true;
169
626
  return;
170
627
  }
171
- yield rowsOf(columns, [(SqlRow.decode(event.body).values ?? [])])[0];
172
628
  }
173
629
  }
174
630
  finally {
175
- if (!ended) {
176
- stream.cancel();
177
- }
631
+ stream.cancel();
178
632
  }
179
633
  }
180
- /** Runs a statement on the writer and says what it changed. */
181
- async exec(...statement) {
182
- const given = statementOf(statement);
183
- return this.#link.run('write', async (connection) => {
634
+ table(name, options) {
635
+ return new Table(this, name, options);
636
+ }
637
+ /** Statements known before they run, written as one: all of them or none, in a shared commit. */
638
+ async batch(statements) {
639
+ const texts = statements.map(each => {
640
+ if (!(each instanceof Sql)) {
641
+ throw new InvalidError('a batch takes pieces of SQL: sql`…`');
642
+ }
643
+ return { text: each.text, values: [...each.values] };
644
+ });
645
+ this.#refuseAround('a batch');
646
+ const answered = await this.#link.run('write', async (connection) => {
184
647
  const handle = await this.handle(connection);
185
- const body = await connection.session.call(methods['sql.exec'], SqlStatement.encode({ handle, ...given }));
186
- const done = SqlDone.decode(body);
187
- return { changes: done.changes ?? 0, lastId: done.lastId ?? 0 };
648
+ return connection.session.call(methods['sql.batch'], SqlBatch.encode({ handle, statements: texts }));
188
649
  });
189
- }
190
- /** The rows a write's returning clause answers, run on the writer. */
191
- async execAll(...statement) {
192
- const { columns, rows } = await this.#query(statement, true);
193
- return rowsOf(columns, rows);
194
- }
195
- async execOne(...statement) {
196
- return one(await this.execAll(...statement));
197
- }
198
- async execScalar(...statement) {
199
- const { columns, rows } = await this.#query(statement, true);
200
- return scalar(columns, rows);
650
+ return (SqlBatched.decode(answered).done ?? []).map(doneOf);
201
651
  }
202
652
  /**
203
- * Runs the statements fn asks for in one transaction, all or none: a
204
- * failure names its statement as `call`. fn returns before anything is
205
- * sent, since no transaction is held across the network, and what it
206
- * returns comes back answered, an array's promises each:
653
+ * Runs fn in a transaction that holds the writer, for writes that depend on
654
+ * what its reads found: returning commits, a throw rolls back. It runs
655
+ * once, five seconds at most, past which the server rolls it back; inside
656
+ * it, call nothing that waits on the world.
207
657
  *
208
- * const [note] = await db.batch(tx => [tx.one`insert into notes (title) values (${t}) returning *`])
658
+ * await db.tx(async tx => {
659
+ * const left = await tx.scalar<number>`select stock from items where sku = ${sku}`
660
+ * if (left < 1) throw new SoldOut()
661
+ * await tx.exec`update items set stock = stock - 1 where sku = ${sku}`
662
+ * })
209
663
  */
210
- batch(fn) {
211
- return this.#run(false, fn);
664
+ async tx(fn) {
665
+ this.#refuseAround('a transaction');
666
+ const connection = await this.#link.connection();
667
+ const handle = await this.handle(connection);
668
+ const guests = await this.#openGuests(connection);
669
+ const stream = await connection.session.open(methods['sql.tx'], SqlTxOpen.encode({ handle }), false);
670
+ await stream.next();
671
+ const tx = new SqlTx(stream, this, connection, guests);
672
+ const inside = { database: this, ended: false };
673
+ let value;
674
+ try {
675
+ value = await running.run([...(running.getStore() ?? []), inside], () => fn(tx));
676
+ }
677
+ catch (err) {
678
+ inside.ended = true;
679
+ await tx.end(false).catch(() => { });
680
+ throw err;
681
+ }
682
+ inside.ended = true;
683
+ await tx.end(true);
684
+ return value;
212
685
  }
213
686
  /**
214
- * Runs the reads fn asks for from one snapshot, and gives back what fn
215
- * returns, answered as batch answers it:
216
- *
217
- * const [notes, total] = await db.view(tx => [tx.all`select * from notes`, tx.scalar`select count(*) from notes`])
687
+ * Opens on `connection` the buckets and queues kept in the file, before a
688
+ * transaction holds its writer: a first open writes the file, and would
689
+ * wait for the writer the transaction holds. One that fails is told when
690
+ * the transaction takes it in.
218
691
  */
219
- view(fn) {
220
- return this.#run(true, fn);
692
+ async #openGuests(connection) {
693
+ const guests = new Map();
694
+ const kept = [...this.#guests.values()];
695
+ const settled = await Promise.allSettled(kept.map(guest => handleOn(connection, guest.method, guest.open)));
696
+ settled.forEach((outcome, at) => {
697
+ const open = kept[at]?.open;
698
+ if (open !== undefined) {
699
+ guests.set(open, outcome.status === 'fulfilled' ? undefined : outcome.reason);
700
+ }
701
+ });
702
+ return guests;
703
+ }
704
+ async rows(statement, want) {
705
+ const parts = await this.#answered(statement, methods['sql.query'], handle => SqlQuery.encode({ handle, text: statement.text, values: [...statement.values], want }));
706
+ return joined(parts);
707
+ }
708
+ /** The parts of a statement's answer, all of them: a read may be asked again of another connection, a write not. */
709
+ async #answered(statement, method, asked) {
710
+ this.#refuseAround('a statement');
711
+ const idempotence = mayWrite(statement.text) ? 'write' : 'read';
712
+ return this.#link.run(idempotence, async (connection) => {
713
+ const body = asked(await this.handle(connection));
714
+ const { items, trailer } = await download(connection, method, body);
715
+ return [...items, trailer];
716
+ });
221
717
  }
222
- async #run(read, fn) {
223
- const tx = new SqlBatch(read, this.name);
224
- const returned = fn(tx);
225
- tx.close();
226
- if (returned instanceof Promise && !tx.made(returned)) {
227
- throw new InvalidError('a batch function returns before anything is sent; it cannot await inside');
228
- }
229
- if (tx.statements.length > 0 || tx.jobs.length > 0) {
230
- await this.#send(read, tx);
231
- }
232
- return settle(returned);
718
+ /** Runs a write once it is durable; writes from many callers share a commit, each failing alone. */
719
+ async exec(...statement) {
720
+ this.#refuseAround('a write');
721
+ const piece = statementOf(statement);
722
+ const answered = await this.#link.run('write', async (connection) => {
723
+ const handle = await this.handle(connection);
724
+ const body = SqlStatement.encode({ handle, text: piece.text, values: [...piece.values] });
725
+ return connection.session.call(methods['sql.exec'], body);
726
+ });
727
+ return doneOf(SqlDone.decode(answered));
233
728
  }
234
- async #send(read, tx) {
235
- try {
236
- const results = await this.#link.run(read ? 'read' : 'write', async (connection) => {
237
- const handle = await this.handle(connection);
238
- const jobs = [];
239
- for (const queued of tx.jobs) {
240
- const queue = await handleOn(connection, methods['jobs.open'], queued.open);
241
- jobs.push({ handle: queue, jobs: [queued.job] });
242
- }
243
- const body = await connection.session.call(methods['sql.batch'], SqlStatements.encode({
244
- handle,
245
- statements: tx.statements.map(s => s.statement),
246
- read: read || undefined,
247
- jobs: jobs.length > 0 ? jobs : undefined,
248
- }));
249
- return SqlResults.decode(body).results ?? [];
250
- });
251
- tx.statements.forEach((s, i) => {
252
- s.settle(results[i] ?? {});
729
+ }
730
+ /**
731
+ * A database's transaction, from `db.tx`: its reads see its writes, and a
732
+ * call that fails leaves it as it was before the call. Its calls go one at a
733
+ * time, in order.
734
+ */
735
+ export class SqlTx {
736
+ describe;
737
+ #stream;
738
+ #database;
739
+ #connection;
740
+ #guests;
741
+ #via;
742
+ #last = Promise.resolve();
743
+ /** Transactions come from `db.tx`. */
744
+ constructor(stream, database, connection, guests) {
745
+ this.#stream = stream;
746
+ this.#database = database;
747
+ this.#connection = connection;
748
+ this.#guests = guests;
749
+ this.describe = database.describe;
750
+ const call = async (openMethod, open, method, body) => {
751
+ const handle = await handleOn(this.#connection, openMethod, open);
752
+ return this.#nested(method, body(handle));
753
+ };
754
+ this.#via = { call, ask: (...asked) => askByCall(call, ...asked) };
755
+ }
756
+ with(handle) {
757
+ const channel = channelParts(handle);
758
+ if (channel !== undefined) {
759
+ // a message published here is handed over once the transaction commits, at the writer
760
+ return txChannel(channel.name, channel.branch, async (body) => {
761
+ await this.#nested(methods['channels.publish'], body);
253
762
  });
254
- for (const queued of tx.jobs) {
255
- queued.settle();
256
- }
257
763
  }
258
- catch (err) {
259
- for (const s of [...tx.statements, ...tx.jobs]) {
260
- s.fail(err);
261
- }
262
- throw err;
764
+ const bucket = partsOf(handle);
765
+ if (bucket?.values !== undefined && bucket.openMethod === 'kv.bucket.open') {
766
+ this.#takes(bucket.home, bucket.open, `kv bucket ${bucket.name}`);
767
+ const { link, name, open, values, under, home } = bucket;
768
+ return new Bucket(link, name, open, values, under, home, this.#via);
769
+ }
770
+ const queue = queueParts(handle);
771
+ if (queue !== undefined) {
772
+ this.#takes(queue.source.home, queue.source.open, `jobs queue ${queue.name}`);
773
+ return queueVia(queue, this.#via);
263
774
  }
775
+ throw new InvalidError(`${this.describe}: a transaction takes in a bucket or a queue opened from its database`);
264
776
  }
265
- }
266
- /** The statements of a batch or a view, whose promises settle with it. */
267
- export class SqlBatch {
268
- read;
269
- /** the database the batch runs in, whose queues alone take its jobs */
270
- database;
271
- statements = [];
272
- jobs = [];
273
- #done = false;
274
- #made = new WeakSet();
275
- constructor(read, database) {
276
- this.read = read;
277
- this.database = database;
777
+ async all(...statement) {
778
+ return all(this, statementOf(statement));
278
779
  }
279
- close() {
280
- this.#done = true;
780
+ async one(...statement) {
781
+ return one(this, statementOf(statement));
281
782
  }
282
- /** Whether the promise is one of this batch's statements', rather than an async function's. */
283
- made(promise) {
284
- return this.#made.has(promise);
783
+ async scalar(...statement) {
784
+ return scalar(this, statementOf(statement));
285
785
  }
286
- /**
287
- * Adds a job to the batch, for a queue's withTx: a program writes
288
- * `queue.withTx(tx).enqueue(value)`, on a queue opened `in` this database.
289
- */
290
- enqueue(open, job) {
291
- if (this.read) {
292
- throw new InvalidError('a job in a view, which reads');
293
- }
294
- const { promise, settle, fail } = this.#promise();
295
- this.jobs.push({ open, job, settle: () => settle(undefined), fail });
296
- return promise;
297
- }
298
- #promise() {
299
- if (this.#done) {
300
- throw new InvalidError('a batch takes its statements while its function runs, before it is sent');
301
- }
302
- let settle;
303
- let fail;
304
- const promise = new Promise((res, rej) => {
305
- settle = res;
306
- fail = rej;
307
- });
308
- // a caller need not await a call it only wanted done
309
- promise.catch(() => { });
310
- this.#made.add(promise);
311
- return { promise, settle, fail };
312
- }
313
- #record(given, rows, settle) {
314
- const statement = statementOf(given);
315
- const { promise: settled, settle: resolve, fail: reject } = this.#promise();
316
- this.statements.push({
317
- statement: { ...statement, rows: rows && !this.read ? true : undefined },
318
- settle: result => {
319
- try {
320
- resolve(settle(result));
321
- }
322
- catch (err) {
323
- reject(err);
324
- }
325
- },
326
- fail: reject,
327
- });
328
- return settled;
786
+ async exec(...statement) {
787
+ return this.#call(statementOf(statement), 'exec').then(answer => doneOf(answer.done ?? {}));
329
788
  }
330
- exec(...statement) {
331
- return this.#record(statement, false, r => ({ changes: r.changes ?? 0, lastId: r.lastId ?? 0 }));
789
+ /** A table inside the transaction: its calls are the transaction's. */
790
+ table(name, options) {
791
+ return new Table(this, name, options);
332
792
  }
333
- all(...statement) {
334
- return this.#record(statement, true, r => rowsOf(r.columns ?? [], (r.rows ?? [])));
793
+ async rows(statement, want) {
794
+ const answer = await this.#call(statement, want);
795
+ return {
796
+ columns: [...(answer.rows?.columns ?? [])],
797
+ rows: (answer.rows?.rows ?? []),
798
+ };
335
799
  }
336
- one(...statement) {
337
- return this.#record(statement, true, r => one(rowsOf(r.columns ?? [], (r.rows ?? []))));
800
+ /** Sends the last call: commit, or roll back, and waits for the server's word. */
801
+ async end(commit) {
802
+ await this.#last.catch(() => { });
803
+ await this.#stream.send(SqlTxCall.encode({ commit }), true);
804
+ await this.#stream.next();
338
805
  }
339
- scalar(...statement) {
340
- return this.#record(statement, true, r => scalar(r.columns ?? [], (r.rows ?? [])));
806
+ /**
807
+ * Refuses a handle kept elsewhere, whose writes would not commit with the
808
+ * rows, and one made after the transaction began, whose first open would
809
+ * wait for the writer the transaction holds.
810
+ */
811
+ #takes(home, open, what) {
812
+ if (home !== this.#database) {
813
+ const kept = home === undefined ? 'the store' : home.describe;
814
+ throw new InvalidError(`${what}: kept in ${kept}, outside this transaction of ${this.describe}`);
815
+ }
816
+ if (!this.#guests.has(open)) {
817
+ throw new InvalidError(`${this.describe}: ${what}: made after the transaction began; make it before db.tx, which opens it first`);
818
+ }
819
+ const failed = this.#guests.get(open);
820
+ if (failed !== undefined) {
821
+ throw failed;
822
+ }
823
+ }
824
+ /** A call of kv or jobs in the transaction: its method and its request, and the method's answer. */
825
+ async #nested(method, body) {
826
+ const answer = await this.#send(SqlTxCall.encode({ want: 'call', method, body }));
827
+ return answer.body ?? new Uint8Array(0);
828
+ }
829
+ #call(statement, want) {
830
+ return this.#send(SqlTxCall.encode({ text: statement.text, values: [...statement.values], want }));
831
+ }
832
+ #send(body) {
833
+ const call = async () => {
834
+ await this.#stream.send(body, false);
835
+ const event = await this.#stream.next();
836
+ this.#stream.consumed(event.body.length);
837
+ const answer = SqlTxAnswer.decode(event.body);
838
+ if (answer.failure !== undefined) {
839
+ throw errorOf(answer.failure.code ?? 'internal', answer.failure.message ?? '', answer.failure.what ?? {});
840
+ }
841
+ return answer;
842
+ };
843
+ const next = this.#last.catch(() => { }).then(call);
844
+ this.#last = next;
845
+ return next;
341
846
  }
342
847
  }