@mistriwork/engine 1.0.0-rc.10 → 1.0.0-rc.11

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 (73) hide show
  1. package/dist/adapters/adapter.d.ts +33 -0
  2. package/dist/adapters/postgres.d.ts +21 -16
  3. package/dist/adapters/postgres.js +174 -223
  4. package/dist/adapters/postgresCatalog.d.ts +12 -1
  5. package/dist/adapters/postgresCatalog.js +57 -23
  6. package/dist/adapters/postgresCatalogDigest.js +40 -34
  7. package/dist/adapters/postgresCatalogRows.d.ts +2 -0
  8. package/dist/adapters/postgresWriteAhead.d.ts +47 -0
  9. package/dist/adapters/postgresWriteAhead.js +209 -0
  10. package/dist/adapters/scoped/keyRows.js +9 -3
  11. package/dist/adapters/scoped/keyTypes.d.ts +34 -0
  12. package/dist/adapters/scoped/keyTypes.js +66 -0
  13. package/dist/adapters/scoped/postgresScopeCatalog.d.ts +18 -0
  14. package/dist/adapters/scoped/postgresScopeCatalog.js +353 -13
  15. package/dist/adapters/scoped/postgresTriggers.d.ts +137 -0
  16. package/dist/adapters/scoped/postgresTriggers.js +1545 -0
  17. package/dist/adapters/scoped/scopeTriggers.d.ts +122 -0
  18. package/dist/adapters/scoped/scopeTriggers.js +131 -0
  19. package/dist/adapters/scoped/scopedReads.d.ts +3 -1
  20. package/dist/adapters/scoped/scopedReads.js +23 -5
  21. package/dist/adapters/scoped/scopedTransaction.d.ts +76 -6
  22. package/dist/adapters/scoped/scopedTransaction.js +278 -34
  23. package/dist/adapters/scoped/sqliteScopeCatalog.d.ts +17 -1
  24. package/dist/adapters/scoped/sqliteScopeCatalog.js +197 -18
  25. package/dist/adapters/scoped/sqliteTriggerSession.d.ts +64 -0
  26. package/dist/adapters/scoped/sqliteTriggerSession.js +245 -0
  27. package/dist/adapters/scoped/sqliteTriggers.d.ts +20 -0
  28. package/dist/adapters/scoped/sqliteTriggers.js +822 -0
  29. package/dist/adapters/scoped/storedText.d.ts +45 -0
  30. package/dist/adapters/scoped/storedText.js +61 -0
  31. package/dist/adapters/scoped/triggerEffects.d.ts +98 -0
  32. package/dist/adapters/scoped/triggerEffects.js +189 -0
  33. package/dist/adapters/scoped/triggerProof.d.ts +124 -0
  34. package/dist/adapters/scoped/triggerProof.js +366 -0
  35. package/dist/adapters/snapshotRead.d.ts +8 -0
  36. package/dist/adapters/snapshotRead.js +37 -0
  37. package/dist/adapters/sqlite.d.ts +13 -2
  38. package/dist/adapters/sqlite.js +139 -16
  39. package/dist/adapters/sqliteDecimals.d.ts +2 -2
  40. package/dist/adapters/sqliteDecimals.js +2 -8
  41. package/dist/adapters/storeHost.d.ts +4 -1
  42. package/dist/adapters/writeCapture.d.ts +7 -0
  43. package/dist/server/cli/args.d.ts +6 -0
  44. package/dist/server/cli/args.js +6 -0
  45. package/dist/server/columnGrants.d.ts +3 -0
  46. package/dist/server/columnGrants.js +12 -1
  47. package/dist/server/config/profile.d.ts +123 -0
  48. package/dist/server/config/profile.js +236 -0
  49. package/dist/server/connections.d.ts +5 -0
  50. package/dist/server/connections.js +11 -1
  51. package/dist/server/hiddenColumns.js +6 -0
  52. package/dist/server/http/refusalReport.js +16 -4
  53. package/dist/server/migrate/cli.d.ts +50 -3
  54. package/dist/server/migrate/cli.js +199 -14
  55. package/dist/server/migrate/runner.js +5 -1
  56. package/dist/server/shapeonly.js +5 -0
  57. package/dist/shared/aggregate.d.ts +49 -0
  58. package/dist/shared/aggregate.js +107 -0
  59. package/dist/shared/breakdown.js +17 -4
  60. package/dist/shared/decimals.d.ts +37 -0
  61. package/dist/shared/decimals.js +148 -0
  62. package/dist/shared/displayDefaults.js +15 -1
  63. package/dist/shared/filter.d.ts +22 -1
  64. package/dist/shared/filter.js +36 -9
  65. package/dist/shared/money.d.ts +9 -0
  66. package/dist/shared/money.js +17 -0
  67. package/dist/shared/pageModel.d.ts +1 -1
  68. package/dist/shared/refusal.d.ts +16 -0
  69. package/dist/shared/refusal.js +40 -0
  70. package/dist/shared/schema.d.ts +6 -0
  71. package/dist/shared/scopeCatalog.js +4 -0
  72. package/dist/shared/servedApp.d.ts +7 -2
  73. package/package.json +5 -1
@@ -31,12 +31,13 @@ import { migrateBaseline, migrateRepair, migrateUp, migrateValidate, migrationSt
31
31
  import { sayChange } from './snapshot.js';
32
32
  import { resolveTarget, targetDir } from './target.js';
33
33
  import { product } from '../product.js';
34
+ import { claimContext, contextJson, contextLines, fromProfile, projectContext } from '../config/profile.js';
34
35
  const migrateUsage = () => product() +
35
36
  ' migrate <new <name> | diff <name> | check | squash | status | up | validate | baseline | repair> [--app <dir>] ' +
36
37
  '[<db> | --db <target> | --config <path>] [--connection <name>] [--schema <name>] [--migrations <dir>] [--history-table <name>] ' +
37
38
  '[--schema-file <path>] [--dev-url <url>] [--dry-run] [--tool flyway] [--repeatable]';
38
39
  /** The exit codes: what went wrong, for CI. */
39
- const EXIT = { ok: 0, couldNot: 1, invalid: 2, failed: 3, app: 4 };
40
+ const EXIT = { ok: 0, couldNot: 1, invalid: 2, failed: 3, app: 4, stores: 5 };
40
41
  const COMMANDS = ['new', 'diff', 'check', 'squash', 'status', 'up', 'validate', 'baseline', 'repair'];
41
42
  /** The commands that compare the migrations with the desired schema.sql (desired.ts). */
42
43
  const DESIRED = ['diff', 'check', 'squash'];
@@ -52,6 +53,9 @@ const PASSED = {
52
53
  '--policy': true,
53
54
  /* The App's commands module, where it is not the commands.ts beside the manifest: its journal is a store. */
54
55
  '--commands': true,
56
+ /* Its jobs module: the job store and the event deliveries it reads are stores `up --app` makes, and the check
57
+ judges the jobs beside the commands they run. */
58
+ '--jobs': true,
55
59
  };
56
60
  const shown = (path) => {
57
61
  const near = relative(process.cwd(), path);
@@ -82,7 +86,11 @@ export async function runMigrate(argv, write = (line) => process.stdout.write(`$
82
86
  Object.entries(hosted)
83
87
  .map(([word, each]) => ` ${word.padEnd(11)} ${each.says}: ${each.usage.replace(`${product()} migrate `, '')}\n`)
84
88
  .join('') +
85
- 'Exit codes: 1 could not run, 2 files and history disagree, 3 a migration failed, 4 applied but the App no longer checks.\n' +
89
+ 'With --app, status prints the bootstrap plan (migrations, stores, sign-in store, seed, check) and up carries it out:\n' +
90
+ ' the stores the App uses (--commands, --jobs, --policy name its modules), a PostgreSQL auth.store, then the check.\n' +
91
+ ' validate --app exits 2 while any phase is pending. --json prints the plan as data.\n' +
92
+ 'Exit codes: 1 could not run, 2 files and history disagree, 3 a migration failed, 4 applied but the App no longer checks,\n' +
93
+ '5 a store step failed.\n' +
86
94
  'mistri docs migrate is the guide.');
87
95
  return EXIT.ok;
88
96
  }
@@ -98,6 +106,7 @@ export async function runMigrate(argv, write = (line) => process.stdout.write(`$
98
106
  let tool;
99
107
  let dryRun = false;
100
108
  let repeatable = false;
109
+ let json = false;
101
110
  let schemaFile;
102
111
  let devUrl;
103
112
  let sub;
@@ -162,6 +171,10 @@ export async function runMigrate(argv, write = (line) => process.stdout.write(`$
162
171
  repeatable = true;
163
172
  continue;
164
173
  }
174
+ if (arg === '--json') {
175
+ json = true;
176
+ continue;
177
+ }
165
178
  if ((command === 'new' || command === 'diff') && name === undefined && !arg.startsWith('-')) {
166
179
  name = arg;
167
180
  continue;
@@ -194,6 +207,10 @@ export async function runMigrate(argv, write = (line) => process.stdout.write(`$
194
207
  }
195
208
  if (repeatable && command !== 'new')
196
209
  return fail('--repeatable is for new: it names the file R__<name>.sql.');
210
+ if (json && (app === undefined || !['status', 'up', 'validate'].includes(command)))
211
+ return fail('--json is for status, up and validate with --app: it prints the bootstrap plan as data.');
212
+ if (json && tool)
213
+ return fail('--json reads the plan the runner keeps; drop --tool flyway to see it as data.');
197
214
  if (dryRun && !own && !['up', 'baseline', 'repair'].includes(command))
198
215
  return fail(`--dry-run is for up, baseline and repair; ${command} changes nothing.`);
199
216
  if (tool && (command === 'new' || dryRun))
@@ -203,6 +220,10 @@ export async function runMigrate(argv, write = (line) => process.stdout.write(`$
203
220
  const opts = parseArgs(rest);
204
221
  if (opts.unknown)
205
222
  return fail(`unknown option "${opts.unknown}". ${migrateUsage()}`);
223
+ /* With --json the document is stdout's alone: the narration (the SQL, the check's findings) goes to stderr. */
224
+ const print = write;
225
+ if (json)
226
+ write = (line) => process.stderr.write(`${line}\n`);
206
227
  const appDir = app !== undefined ? resolve(app) : undefined;
207
228
  if (appDir !== undefined && !host)
208
229
  return fail("--app reads an App, which is the App framework's part: " +
@@ -230,6 +251,11 @@ export async function runMigrate(argv, write = (line) => process.stdout.write(`$
230
251
  }
231
252
  }
232
253
  const flags = { connection, argument, migrations, table, schemas: opts.schemas };
254
+ /* Where the profile decided the App or its entries, the run says what it read before anything else
255
+ (docs/bootstrap-plan.md B4); --json carries it in the plan. */
256
+ if (loaded && !json && fromProfile(projectContext()) && claimContext())
257
+ for (const line of contextLines(projectContext(), loaded.entries))
258
+ write(line);
233
259
  if (own) {
234
260
  return await own.run({
235
261
  sub: sub,
@@ -273,14 +299,63 @@ export async function runMigrate(argv, write = (line) => process.stdout.write(`$
273
299
  const dialect = dialectOf(target.url);
274
300
  const appFlag = appDir !== undefined ? ` --app ${shown(appDir)}` : '';
275
301
  const where = `${target.connection.name} (${dialect}), history in ${target.table}, migrations in ${shown(target.dir)}`;
302
+ /* The bootstrap plan (docs/bootstrap-plan.md): phase 1 is this file's, the rest the App framework's. Printed
303
+ last, as the run's summary, with the line that says what changed; or, with --json, as the one document. */
304
+ const bootstrap = async (mode, migrations) => {
305
+ const after = await loaded.bootstrap({
306
+ mode,
307
+ migrations,
308
+ registry,
309
+ target: { url: target.url, dialect, schemas: target.schemas },
310
+ rest,
311
+ opts,
312
+ write,
313
+ });
314
+ return { ...after, phases: [migrations, ...after.phases] };
315
+ };
316
+ const sayPlan = (plan, mode, code) => {
317
+ const database = dialect === 'sqlite' ? shown(target.url.replace(/^sqlite:(\/\/)?/i, '')) : target.connection.name;
318
+ const changed = plan.phases.some((phase) => phase.status === 'applied');
319
+ if (json) {
320
+ print(JSON.stringify({
321
+ version: 1,
322
+ app: plan.title,
323
+ connection: target.connection.name,
324
+ dialect,
325
+ mode,
326
+ phases: plan.phases.map((phase) => ({
327
+ phase: phase.phase,
328
+ status: phase.status,
329
+ detail: phase.detail,
330
+ items: phase.items,
331
+ ...(phase.error !== undefined ? { error: phase.error } : {}),
332
+ })),
333
+ changed,
334
+ exit: code,
335
+ context: contextJson(projectContext(), loaded?.entries),
336
+ }));
337
+ return code;
338
+ }
339
+ write('');
340
+ write(`Bootstrap of "${plan.title}" (${dialect}, ${database})`);
341
+ plan.phases.forEach((phase, i) => {
342
+ write(` ${i + 1} ${phase.phase.padEnd(14)} ${phase.status.padEnd(8)} ${phase.detail}`);
343
+ if (phase.error !== undefined)
344
+ write(` ${phase.error}`);
345
+ });
346
+ write(sayChanged(plan.phases, mode, plan.next));
347
+ return code;
348
+ };
276
349
  if (tool) {
277
350
  write(`Running flyway ${FLYWAY_COMMANDS[command]} on ${where}`);
278
351
  const run = () => runFlyway(command, target, dialect, write);
279
352
  const code = command === 'up' || command === 'baseline' || command === 'repair' ? await recordAround(target, run) : await run();
280
353
  if (code !== 0)
281
354
  return command === 'up' ? EXIT.failed : command === 'validate' ? EXIT.invalid : EXIT.couldNot;
282
- if (command === 'up' && loaded)
283
- return (await loaded.check(rest, write)) ? EXIT.ok : EXIT.app;
355
+ if (command === 'up' && loaded) {
356
+ const plan = await bootstrap('up', { phase: 'migrations', status: 'done', detail: 'run by flyway', items: [] });
357
+ return sayPlan(plan, 'up', planExit(plan.phases));
358
+ }
284
359
  return EXIT.ok;
285
360
  }
286
361
  if (command === 'status') {
@@ -291,12 +366,13 @@ export async function runMigrate(argv, write = (line) => process.stdout.write(`$
291
366
  await loaded.types(registry, write);
292
367
  /* Never applied is not a state to report and pass: a deploy script that
293
368
  reads status before serving would serve an App with no tables. */
294
- if (!status.started) {
295
- if (!status.holds && !status.plan.pending.length)
296
- write(`No migrations to apply: ${product()} migrate diff init${appFlag} writes the first from schema.sql.`);
297
- return EXIT.invalid;
298
- }
299
- return EXIT.ok;
369
+ if (!status.started && !status.holds && !status.plan.pending.length)
370
+ write(`No migrations to apply: ${product()} migrate diff init${appFlag} writes the first from schema.sql.`);
371
+ const code = status.started ? EXIT.ok : EXIT.invalid;
372
+ /* A plan is a report: its exit is status's own, whatever is pending. */
373
+ if (loaded)
374
+ return sayPlan(await bootstrap('plan', migrationsPhase(status)), 'plan', code);
375
+ return code;
300
376
  }
301
377
  if (command === 'validate') {
302
378
  const { status, valid } = await migrateValidate(target);
@@ -308,6 +384,12 @@ export async function runMigrate(argv, write = (line) => process.stdout.write(`$
308
384
  write(` pending: ${file.script} is not applied`);
309
385
  sayDrift(status, write);
310
386
  write(valid ? `Valid: ${plural(status.plan.history.versioned.size, 'migration')} applied, nothing pending, no drift.` : 'Not valid.');
387
+ /* With --app, CI's question is whether the database is ready for this App: any phase pending is not. */
388
+ if (loaded) {
389
+ const plan = await bootstrap('plan', migrationsPhase(status));
390
+ const ready = valid && !plan.phases.some((phase) => phase.status === 'pending' || phase.status === 'failed');
391
+ return sayPlan(plan, 'plan', ready ? EXIT.ok : EXIT.invalid);
392
+ }
311
393
  return valid ? EXIT.ok : EXIT.invalid;
312
394
  }
313
395
  if (command === 'baseline') {
@@ -356,12 +438,25 @@ export async function runMigrate(argv, write = (line) => process.stdout.write(`$
356
438
  if (result.status.plan.problems.length) {
357
439
  sayProblems(result.status, write);
358
440
  write('Nothing was applied.');
441
+ if (loaded)
442
+ return sayPlan(await bootstrap('up', migrationsPhase(result.status)), 'up', EXIT.invalid);
359
443
  return EXIT.invalid;
360
444
  }
361
445
  if (result.wouldRun) {
446
+ /* A dry run is the plan: the SQL first, then what up would do after it. */
447
+ const planned = async () => loaded
448
+ ? sayPlan(await bootstrap('plan', {
449
+ phase: 'migrations',
450
+ status: result.wouldRun.length ? 'pending' : 'done',
451
+ detail: result.wouldRun.length
452
+ ? result.wouldRun.map((file) => file.script).join(', ')
453
+ : `up to date${sayVersion(result.status)}`,
454
+ items: result.wouldRun.map((file) => file.script),
455
+ }), 'plan', EXIT.ok)
456
+ : EXIT.ok;
362
457
  if (!result.wouldRun.length) {
363
458
  write('Nothing to apply.');
364
- return EXIT.ok;
459
+ return planned();
365
460
  }
366
461
  for (const file of result.wouldRun) {
367
462
  const how = file.transactional ? 'in one transaction' : 'statement by statement, outside a transaction';
@@ -371,23 +466,43 @@ export async function runMigrate(argv, write = (line) => process.stdout.write(`$
371
466
  write('');
372
467
  }
373
468
  write(`${plural(result.wouldRun.length, 'migration')} would be applied.`);
374
- return EXIT.ok;
469
+ return planned();
375
470
  }
376
471
  for (const { file, ms } of result.applied)
377
472
  write(` applied ${file.script} (${ms} ms)`);
473
+ const applied = result.applied.map(({ file }) => file.script);
378
474
  if (result.failure) {
379
475
  write(` failed ${result.failure.file.script}: ${result.failure.message}`);
380
476
  write(`${plural(result.applied.length, 'migration')} applied before it; the run stopped there.`);
477
+ if (loaded)
478
+ return sayPlan(await bootstrap('up', {
479
+ phase: 'migrations',
480
+ status: 'failed',
481
+ detail: `${result.failure.file.script} failed and was rolled back${applied.length ? `; applied before it: ${applied.join(', ')}` : ''}`,
482
+ items: applied,
483
+ error: result.failure.message,
484
+ }), 'up', EXIT.failed);
381
485
  return EXIT.failed;
382
486
  }
383
487
  if (!result.applied.length) {
384
488
  write(`Nothing to apply: up to date${sayVersion(result.status)}.`);
489
+ if (loaded) {
490
+ const plan = await bootstrap('up', {
491
+ phase: 'migrations',
492
+ status: 'done',
493
+ detail: `up to date${sayVersion(result.status)}`,
494
+ items: [],
495
+ });
496
+ return sayPlan(plan, 'up', planExit(plan.phases));
497
+ }
385
498
  return EXIT.ok;
386
499
  }
387
500
  write(`Applied ${plural(result.applied.length, 'migration')}: now${sayVersion(result.status)}.`);
388
501
  sayDrift(result.status, write);
389
- if (loaded)
390
- return (await loaded.check(rest, write)) ? EXIT.ok : EXIT.app;
502
+ if (loaded) {
503
+ const plan = await bootstrap('up', { phase: 'migrations', status: 'applied', detail: applied.join(', '), items: applied });
504
+ return sayPlan(plan, 'up', planExit(plan.phases));
505
+ }
391
506
  return EXIT.ok;
392
507
  }
393
508
  catch (error) {
@@ -447,6 +562,76 @@ async function runDesired(command, target, options, name, write) {
447
562
  write(`It builds ${file}. A database migrated with the old files no longer matches its history: rebuild it, or ${product()} migrate repair.`);
448
563
  return EXIT.ok;
449
564
  }
565
+ /** Phase 1 as a status reads it: pending files, a failed or disagreeing history, or done. */
566
+ function migrationsPhase(status) {
567
+ const failed = status.plan.history.failed;
568
+ if (status.plan.problems.length || failed.length)
569
+ return {
570
+ phase: 'migrations',
571
+ status: 'failed',
572
+ detail: failed.length
573
+ ? `${failed.map((row) => row.script).join(', ')} failed: ${product()} migrate repair, then up`
574
+ : 'the files and the history disagree; nothing was applied',
575
+ items: failed.map((row) => row.script),
576
+ ...(status.plan.problems.length ? { error: status.plan.problems.join(' ') } : {}),
577
+ };
578
+ const pending = status.plan.pending.map((file) => file.script);
579
+ if (pending.length)
580
+ return { phase: 'migrations', status: 'pending', detail: pending.join(', '), items: pending };
581
+ return {
582
+ phase: 'migrations',
583
+ status: status.started ? 'done' : '—',
584
+ detail: status.started ? `up to date${sayVersion(status)}` : 'none written yet',
585
+ items: [],
586
+ };
587
+ }
588
+ /** The exit of an `up --app` that applied its migrations: 5 when a store step failed, 4 when the check did, else 0. */
589
+ function planExit(phases) {
590
+ const failed = (name) => phases.some((phase) => phase.phase === name && phase.status === 'failed');
591
+ if (failed('stores') || failed('sign-in store'))
592
+ return EXIT.stores;
593
+ if (failed('check'))
594
+ return EXIT.app;
595
+ return EXIT.ok;
596
+ }
597
+ /**
598
+ * The plan's last line: what this run changed, and what it did not (`Changed: 1 migration, 4 stores.`,
599
+ * `Nothing changed.`, `Changed: V1__task.sql. Not changed: stores (failed), check (waiting).`). A plan that only
600
+ * read says which phases `up` would carry out.
601
+ */
602
+ function sayChanged(phases, mode, next) {
603
+ const numbered = phases.map((phase, i) => ({ ...phase, n: i + 1 }));
604
+ if (mode === 'plan') {
605
+ const pending = numbered.filter((phase) => phase.status === 'pending');
606
+ const failed = numbered.filter((phase) => phase.status === 'failed');
607
+ if (failed.length)
608
+ return `Nothing changed. ${failed.map((phase) => phase.phase).join(' and ')} failed: see above.`;
609
+ if (!pending.length)
610
+ return 'Nothing changed, and nothing is pending: the database is ready for this App.';
611
+ const which = pending.map((phase) => phase.n);
612
+ return `Nothing changed. ${next} applies ${which.length === 1 ? which[0] : `${which.slice(0, -1).join(', ')} and ${which[which.length - 1]}`}, then checks.`;
613
+ }
614
+ const failedAny = numbered.some((phase) => phase.status === 'failed');
615
+ const parts = [];
616
+ for (const phase of numbered) {
617
+ /* A migration run that failed part way still applied the files before the one that failed. */
618
+ if (phase.phase === 'migrations' && phase.status === 'failed' && phase.items.length)
619
+ parts.push(phase.items.join(', '));
620
+ if (phase.status !== 'applied')
621
+ continue;
622
+ if (phase.phase === 'migrations')
623
+ parts.push(failedAny ? phase.items.join(', ') || 'no migration' : plural(phase.items.length, 'migration'));
624
+ else if (phase.phase === 'stores')
625
+ parts.push(plural(phase.items.length, 'store'));
626
+ else
627
+ parts.push(phase.phase);
628
+ }
629
+ const not = numbered
630
+ .filter((phase) => phase.status === 'failed' || phase.status === 'waiting')
631
+ .map((phase) => `${phase.phase} (${phase.status})`);
632
+ const head = parts.length ? `Changed: ${parts.join(', ')}.` : 'Nothing changed.';
633
+ return not.length ? `${head} Not changed: ${not.join(', ')}.` : head;
634
+ }
450
635
  function sayVersion(status) {
451
636
  const versions = [...status.plan.history.versioned.keys()];
452
637
  const at = versions.length ? versions[versions.length - 1] : (status.plan.history.baseline?.version ?? undefined);
@@ -13,7 +13,7 @@
13
13
  */
14
14
  import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
15
15
  import { join } from 'node:path';
16
- import { openMigrationDb, quoteIdent, splitPostgres } from './database.js';
16
+ import { dialectOf, openMigrationDb, quoteIdent, splitPostgres, sqlitePath } from './database.js';
17
17
  import { readMigrations } from './files.js';
18
18
  import { BASELINE_DESCRIPTION, historyDdl, historyExists, insertHistory, plan, qualified, readHistory, readRows, } from './history.js';
19
19
  import { carryForward, drift, readSchema, readSnapshot, sorted, writeSnapshot, } from './snapshot.js';
@@ -61,6 +61,10 @@ async function readStatus(db, target) {
61
61
  };
62
62
  }
63
63
  export function migrationStatus(target) {
64
+ /* A SQLite file not made yet is a database with nothing applied, which `up` makes: read as an empty one, so the
65
+ plan of a first App says what is pending instead of refusing (docs/bootstrap-plan.md). A read never makes it. */
66
+ if (dialectOf(target.url) === 'sqlite' && sqlitePath(target.url) !== ':memory:' && !existsSync(sqlitePath(target.url)))
67
+ return withDb({ ...target, url: ':memory:' }, true, (db) => readStatus(db, target));
64
68
  return withDb(target, false, (db) => readStatus(db, target));
65
69
  }
66
70
  /**
@@ -90,6 +90,11 @@ export function shapeOnly(adapter, name) {
90
90
  wrapped.runBreakdown = () => {
91
91
  throw why(name, 'grouping rows');
92
92
  };
93
+ /* A sum or a group is a function of row values, as a breakdown is. */
94
+ if (adapter.aggregate)
95
+ wrapped.aggregate = () => {
96
+ throw why(name, 'summing rows');
97
+ };
93
98
  if (adapter.countBreakdown)
94
99
  wrapped.countBreakdown = from('countBreakdown');
95
100
  /* Profile keeps the numbers and loses the values. "52% null, 4,100
@@ -0,0 +1,49 @@
1
+ import { compileBreakdown } from './breakdown.js';
2
+ import type { RowScope } from './rowScope.js';
3
+ import type { DateUnit, Filter, SqlStyle } from './filter.js';
4
+ import { type DatabaseSchema } from './schema.js';
5
+ /** What an aggregate measures. `avg` is the engine's own mean, a float on SQLite: a command answers its mean from an
6
+ exact sum and count (commandDb.ts) and asks for this one only to order groups by. */
7
+ type AggregateFn = 'count' | 'sum' | 'avg' | 'min' | 'max';
8
+ interface AggregateKey {
9
+ /** The output name the group's value answers under. */
10
+ readonly name: string;
11
+ readonly column: string;
12
+ /** Cut a date or timestamp to a period, as a breakdown's key is. */
13
+ readonly bucket?: DateUnit;
14
+ }
15
+ export interface AggregateMeasure {
16
+ /** The output name. */
17
+ readonly name: string;
18
+ readonly fn: AggregateFn;
19
+ /** Absent only for `count`, which then counts rows. */
20
+ readonly column?: string;
21
+ }
22
+ /** An aggregate over one table, as a transaction is asked it. */
23
+ export interface AggregateRequest {
24
+ readonly table: string;
25
+ readonly filter?: Filter;
26
+ readonly by?: readonly AggregateKey[];
27
+ readonly measures: readonly AggregateMeasure[];
28
+ /** The order of the groups, by output name; the keys ascending when unsaid. */
29
+ readonly orderBy?: readonly {
30
+ readonly name: string;
31
+ readonly direction: 'asc' | 'desc';
32
+ }[];
33
+ /** At most this many groups, bounded as every read is. */
34
+ readonly limit: number;
35
+ }
36
+ export interface AggregateResult {
37
+ /** One row per group, keyed by the output names; one row with no keys. */
38
+ readonly rows: Record<string, unknown>[];
39
+ }
40
+ /** Every column an aggregate's keys and measures read (its where's are a filter's, checked as one). */
41
+ export declare const aggregateColumns: (request: AggregateRequest) => string[];
42
+ /** Names an answer row is never keyed by: assigned on an object they reach its prototype, not a field. */
43
+ export declare const FORBIDDEN_ANSWER_NAMES: ReadonlySet<string>;
44
+ /**
45
+ * The statement an aggregate compiles to. A path the compiler refuses (a period cut of a column that is no date) is
46
+ * the request's fault as written, said as one (RequestFault), never as a read that may succeed on a retry.
47
+ */
48
+ export declare function compileAggregate(schema: DatabaseSchema, request: AggregateRequest, style: SqlStyle, offset?: number | unknown, scope?: RowScope): ReturnType<typeof compileBreakdown>;
49
+ export {};
@@ -0,0 +1,107 @@
1
+ import { compileBreakdown, DATE_UNITS } from './breakdown.js';
2
+ import { RequestFault } from './refusal.js';
3
+ import { findTable } from './schema.js';
4
+ import { PathError } from './viewPaths.js';
5
+ const AGGREGATE_FUNCTIONS = ['count', 'sum', 'avg', 'min', 'max'];
6
+ /** The most keys an aggregate groups by: a breakdown's own bound. */
7
+ const AGGREGATE_KEYS = 3;
8
+ /** Every column an aggregate's keys and measures read (its where's are a filter's, checked as one). */
9
+ export const aggregateColumns = (request) => [
10
+ ...(request.by ?? []).map((key) => key.column),
11
+ ...request.measures.flatMap((measure) => (measure.column === undefined ? [] : [measure.column])),
12
+ ];
13
+ const OUTPUT_NAME = /^[a-z_][a-z0-9_]{0,62}$/i;
14
+ /** Names an answer row is never keyed by: assigned on an object they reach its prototype, not a field. */
15
+ export const FORBIDDEN_ANSWER_NAMES = new Set(['__proto__', 'constructor', 'prototype']);
16
+ /**
17
+ * The breakdown an aggregate is, against `schema`: refused unless the table
18
+ * is there and every column it names is one of that table's own. `table` is
19
+ * the id the schema files it under, as the transaction names it.
20
+ */
21
+ function aggregateBreakdown(schema, request) {
22
+ if (!request || typeof request !== 'object')
23
+ throw new RequestFault('An aggregate names a table and what to measure.');
24
+ const table = typeof request.table === 'string' ? findTable(schema, request.table) : undefined;
25
+ if (!table)
26
+ throw new RequestFault('Unknown resource in aggregate.');
27
+ const own = new Set(table.columns.map((column) => column.name));
28
+ /* A column, never a path: a dot is a reference walked, and a walk under a command's scope can read a table its
29
+ footprint holds as empty (above). */
30
+ const column = (name, what) => {
31
+ if (typeof name !== 'string' || !own.has(name) || name.includes('.'))
32
+ throw new RequestFault(`An aggregate's ${what} names one of "${table.name}"'s own columns; "${String(name).slice(0, 80)}" is not one.`);
33
+ return name;
34
+ };
35
+ const names = new Set();
36
+ const output = (name) => {
37
+ if (typeof name !== 'string' || !OUTPUT_NAME.test(name) || FORBIDDEN_ANSWER_NAMES.has(name) || names.has(name))
38
+ throw new RequestFault('An aggregate answers each key and measure under its own name.');
39
+ names.add(name);
40
+ return name;
41
+ };
42
+ const by = request.by ?? [];
43
+ if (!Array.isArray(by) || by.length > AGGREGATE_KEYS)
44
+ throw new RequestFault(`An aggregate groups by at most ${AGGREGATE_KEYS} columns.`);
45
+ const keys = by.map((key) => {
46
+ if (key.bucket !== undefined && !DATE_UNITS.includes(key.bucket))
47
+ throw new RequestFault(`"${String(key.bucket).slice(0, 40)}" is not a period. Use one of: ${DATE_UNITS.join(', ')}.`);
48
+ return { path: column(key.column, 'key'), alias: output(key.name), ...(key.bucket ? { bucket: key.bucket } : {}) };
49
+ });
50
+ if (!Array.isArray(request.measures) || !request.measures.length)
51
+ throw new RequestFault('An aggregate measures something.');
52
+ const measures = request.measures.map((measure) => {
53
+ if (!AGGREGATE_FUNCTIONS.includes(measure.fn))
54
+ throw new RequestFault(`"${String(measure.fn).slice(0, 40)}" is not an aggregate.`);
55
+ if (measure.column === undefined && measure.fn !== 'count')
56
+ throw new RequestFault(`\`${measure.fn}\` needs a column.`);
57
+ return {
58
+ fn: measure.fn,
59
+ alias: output(measure.name),
60
+ ...(measure.column === undefined ? {} : { path: column(measure.column, 'measure') }),
61
+ };
62
+ });
63
+ const groups = (request.filter?.groups ?? []).map((group) => group.map((condition) => {
64
+ /* A comparison with another column, or rows that point here (`any`), reads past this table's own values:
65
+ neither is a condition a command's where writes (compileWhere), and neither is taken here. */
66
+ if (condition.any !== undefined || condition.other !== undefined)
67
+ throw new RequestFault("An aggregate's where compares the table's own columns with values.");
68
+ return {
69
+ path: column(condition.column, 'where'),
70
+ op: condition.op,
71
+ ...(condition.value === undefined ? {} : { value: condition.value }),
72
+ ...(condition.collation ? { collation: condition.collation } : {}),
73
+ };
74
+ }));
75
+ const orderBy = (request.orderBy?.length ? request.orderBy : keys.map((key) => ({ name: key.alias, direction: 'asc' }))).map((order) => {
76
+ if (!names.has(order.name))
77
+ throw new RequestFault(`An aggregate orders by one of its own keys or measures, not "${String(order.name).slice(0, 80)}".`);
78
+ return { name: order.name, direction: order.direction === 'desc' ? 'desc' : 'asc' };
79
+ });
80
+ /* Which text columns a period may cut is the catalog's to say (declaredDates.ts types them `TEXT as date`), never
81
+ the request's: a raw request naming one more would bucket text that is not a date. */
82
+ const dates = table.columns.filter((c) => / as date(time)?$/.test(c.type)).map((c) => `${table.id}.${c.name}`);
83
+ return {
84
+ base: table.id,
85
+ by: keys,
86
+ ...(dates.length ? { dateColumns: dates } : {}),
87
+ measures,
88
+ ...(groups.length ? { filter: { groups } } : {}),
89
+ ...(orderBy.length ? { orderBy } : {}),
90
+ limit: request.limit,
91
+ };
92
+ }
93
+ /**
94
+ * The statement an aggregate compiles to. A path the compiler refuses (a period cut of a column that is no date) is
95
+ * the request's fault as written, said as one (RequestFault), never as a read that may succeed on a retry.
96
+ */
97
+ export function compileAggregate(schema, request, style, offset = 0, scope) {
98
+ const def = aggregateBreakdown(schema, request);
99
+ try {
100
+ return compileBreakdown(schema, def, style, offset, scope);
101
+ }
102
+ catch (error) {
103
+ if (error instanceof PathError)
104
+ throw new RequestFault(error.message, { cause: error });
105
+ throw error;
106
+ }
107
+ }
@@ -41,6 +41,7 @@ import { isFixedScopeCatalog } from './scopeCatalog.js';
41
41
  import { viewPaths, withViewComputed } from './viewLabels.js';
42
42
  import { tableAtPrefix, tryResolvePath } from './viewPaths.js';
43
43
  import { withViewReferences } from './declaredReferences.js';
44
+ import { declaredScale, exactSqliteSum, sumsExactly } from './decimals.js';
44
45
  import { LABEL_SEGMENT, labelPrefix } from './recordLabel.js';
45
46
  export const MEASURE_FUNCTIONS = ['count', 'sum', 'avg', 'min', 'max', 'median'];
46
47
  export const MEASURE_OPS = ['+', '-', '*', '/'];
@@ -269,8 +270,11 @@ function compileBreakdownFresh(schema, def, style, offset, scope) {
269
270
  bucket: key.bucket,
270
271
  });
271
272
  }
272
- /* One aggregate's SQL, and what its values are. */
273
- const termSql = (term) => {
273
+ /* A measure said as text whose order is a number: an exact SQLite sum, by its output name. */
274
+ const orderedBy = new Map();
275
+ /* One aggregate's SQL, and what its values are. `exact` asks for a decimal column's sum as exact text where the
276
+ engine would add floats (decimals.ts): a measure on its own, never a term of arithmetic, which reads a number. */
277
+ const termSql = (term, exact = false) => {
274
278
  /* The function is written into the statement as a word, so it is one of
275
279
  the words: a structured def arrives from a request (`/api/breakdown`
276
280
  `def`), and anything else there would be SQL of the caller's own,
@@ -303,6 +307,12 @@ function compileBreakdownFresh(schema, def, style, offset, scope) {
303
307
  throw new PathError(refused, term.path, term.path, 0);
304
308
  const resolved = paths.resolve(term.path);
305
309
  const read = aggregateInput(qualify(term.path), resolved.column.type, style.dialect);
310
+ /* SQLite adds a decimal column as floats, a cent off at large totals: summed in its smallest unit instead, and
311
+ said with its places, as PostgreSQL's exact numeric says it. */
312
+ if (exact && term.fn === 'sum' && style.dialect === 'sqlite' && sumsExactly(resolved.column.type)) {
313
+ const sum = exactSqliteSum(read, declaredScale(resolved.column.type), resolved.path);
314
+ return { sql: sum.text, path: resolved.path, type: resolved.column.type, order: sum.total };
315
+ }
306
316
  return {
307
317
  sql: term.fn === 'median' ? `percentile_cont(0.5) WITHIN GROUP (ORDER BY ${read})` : `${term.fn.toUpperCase()}(${read})`,
308
318
  path: resolved.path,
@@ -359,10 +369,12 @@ function compileBreakdownFresh(schema, def, style, offset, scope) {
359
369
  continue;
360
370
  }
361
371
  }
362
- const head = termSql(measure);
372
+ const head = termSql(measure, !measure.steps?.length);
363
373
  if (!measure.steps?.length) {
364
374
  const name = nameFor(measureName(measure, head.path));
365
375
  select.push(`${head.sql} AS ${style.quote(name)}`);
376
+ if (head.order)
377
+ orderedBy.set(name, head.order);
366
378
  columns.push({ name, kind: 'measure', fn: measure.fn, path: head.path, type: head.type });
367
379
  continue;
368
380
  }
@@ -424,7 +436,8 @@ function compileBreakdownFresh(schema, def, style, offset, scope) {
424
436
  }
425
437
  if (o.emptyLast)
426
438
  return `(${style.quote(o.name)} IS NULL) ASC`;
427
- return `${style.quote(o.name)} ${o.direction === 'desc' ? 'DESC' : 'ASC'}`;
439
+ /* An exact sum is text; it sorts by the integer it says, never as text ("9.00" after "10.00"). */
440
+ return `${orderedBy.get(o.name) ?? style.quote(o.name)} ${o.direction === 'desc' ? 'DESC' : 'ASC'}`;
428
441
  });
429
442
  const limit = clampLimit(def.limit);
430
443
  const skip = clampOffset(offset);
@@ -0,0 +1,37 @@
1
+ /** The scale a declared type asks for, when it is a DECIMAL/NUMERIC with one above zero. */
2
+ export declare function declaredScale(type: string | null | undefined): number;
3
+ /** Whether a SQLite sum over a column of this declared type is summed exactly (`exactSqliteSum`). */
4
+ export declare const sumsExactly: (type: string | null | undefined) => boolean;
5
+ /**
6
+ * A SQLite column of `scale` places summed as an integer count of its
7
+ * smallest unit: `total` is that integer (for ordering by it), `text` the
8
+ * decimal it says, null over no rows as `SUM` is. `read` is the column's
9
+ * expression; the scale is a number read off the catalog, never a request's
10
+ * text.
11
+ */
12
+ export declare function exactSqliteSum(read: string, scale: number, label?: string): {
13
+ total: string;
14
+ text: string;
15
+ };
16
+ /** The columns a list of measures sums, for the refusal to name. */
17
+ export declare const summed: (measures: readonly {
18
+ fn?: string;
19
+ path?: string;
20
+ column?: string;
21
+ }[] | undefined) => string[];
22
+ /**
23
+ * Runs a SQLite read whose rows may hold exact sums: a cell that says it was beyond exact range, or SQLite's own
24
+ * `integer overflow` while adding, is the refusal, naming the columns summed (`columns`).
25
+ */
26
+ export declare function readExactly<T extends {
27
+ rows: readonly Record<string, unknown>[];
28
+ }>(run: () => Promise<T>, columns: readonly string[]): Promise<T>;
29
+ /** A decimal as an integer count of units and its places, or undefined when the text is not a plain decimal. */
30
+ export declare function parseDecimal(value: string | number | bigint): {
31
+ units: bigint;
32
+ scale: number;
33
+ } | undefined;
34
+ /** An integer count of units said with `scale` places: `formatDecimal(-5n, 2)` is `-0.05`. */
35
+ export declare function formatDecimal(units: bigint, scale: number): string;
36
+ /** The mean of an exact sum over `count` values, said with `places` places, rounded half to even. */
37
+ export declare function exactAverage(sum: string | number | bigint, count: number | bigint, places: number): string | undefined;