@mistriwork/engine 1.0.0-rc.16 → 1.0.0-rc.18

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/README.md +5 -0
  2. package/dist/adapters/adapter.d.ts +35 -2
  3. package/dist/adapters/adapter.js +32 -1
  4. package/dist/adapters/postgres.js +8 -4
  5. package/dist/adapters/scoped/scopedReads.js +23 -5
  6. package/dist/adapters/scoped/sqliteTriggers.js +65 -38
  7. package/dist/adapters/sqlite.js +8 -4
  8. package/dist/host.d.ts +46 -0
  9. package/dist/host.js +51 -0
  10. package/dist/server/columnGrants.d.ts +5 -0
  11. package/dist/server/connections.d.ts +1 -0
  12. package/dist/server/connections.js +20 -1
  13. package/dist/server/http/exportRoute.d.ts +74 -0
  14. package/dist/server/http/exportRoute.js +206 -169
  15. package/dist/server/http/firstPaint.d.ts +5 -1
  16. package/dist/server/http/firstPaint.js +4 -4
  17. package/dist/server/http/reply.js +6 -0
  18. package/dist/server/httpConnection.d.ts +4 -2
  19. package/dist/server/httpConnection.js +10 -3
  20. package/dist/server/journal.d.ts +35 -6
  21. package/dist/server/journal.js +79 -8
  22. package/dist/server/journalStore.d.ts +37 -0
  23. package/dist/server/journalStore.js +375 -0
  24. package/dist/server/resourceReadHttp.d.ts +4 -2
  25. package/dist/server/resourceReadHttp.js +40 -4
  26. package/dist/server/resourceReadOperations.d.ts +4 -0
  27. package/dist/server/scaffoldMachine.js +12 -1
  28. package/dist/shared/appListColumns.d.ts +7 -0
  29. package/dist/shared/appListColumns.js +13 -0
  30. package/dist/shared/boardLanes.d.ts +44 -0
  31. package/dist/shared/boardLanes.js +69 -0
  32. package/dist/shared/builtInThemes.js +26 -20
  33. package/dist/shared/dashboardAsks.d.ts +2 -0
  34. package/dist/shared/filter.d.ts +2 -0
  35. package/dist/shared/filter.js +3 -2
  36. package/dist/shared/form.d.ts +24 -1
  37. package/dist/shared/form.js +53 -0
  38. package/dist/shared/keysetPage.js +3 -0
  39. package/dist/shared/listInference.d.ts +91 -0
  40. package/dist/shared/listInference.js +323 -0
  41. package/dist/shared/listPresentations.d.ts +3 -0
  42. package/dist/shared/listQuestion.d.ts +2 -0
  43. package/dist/shared/listQuestion.js +3 -2
  44. package/dist/shared/pageAnatomy.d.ts +27 -3
  45. package/dist/shared/pageAnatomy.js +217 -36
  46. package/dist/shared/pageModel.d.ts +17 -1
  47. package/dist/shared/pageModel.js +8 -0
  48. package/dist/shared/query.d.ts +2 -0
  49. package/dist/shared/query.js +11 -3
  50. package/dist/shared/reads.d.ts +9 -0
  51. package/dist/shared/reads.js +9 -0
  52. package/dist/shared/recordLabel.d.ts +5 -0
  53. package/dist/shared/recordLabel.js +22 -2
  54. package/dist/shared/recordReads.d.ts +30 -0
  55. package/dist/shared/recordReads.js +101 -19
  56. package/dist/shared/referenceSubline.d.ts +18 -0
  57. package/dist/shared/referenceSubline.js +62 -0
  58. package/dist/shared/resourceHttp.d.ts +5 -0
  59. package/dist/shared/rowScope.js +52 -6
  60. package/dist/shared/schema.d.ts +2 -0
  61. package/dist/shared/servedApp.d.ts +19 -1
  62. package/dist/shared/servedApp.js +10 -0
  63. package/dist/shared/themeLooks.js +61 -35
  64. package/dist/shared/themeRecipeWords.d.ts +5 -0
  65. package/dist/shared/themeRecipeWords.js +6 -1
  66. package/dist/shared/themeRecipes.d.ts +5 -0
  67. package/dist/shared/themeRecipes.js +3 -0
  68. package/dist/shared/themeType.js +2 -1
  69. package/dist/shared/view.js +29 -2
  70. package/dist/shared/viewLabels.js +16 -0
  71. package/dist/shared/viewPaths.d.ts +9 -0
  72. package/package.json +6 -1
  73. package/schema/theme.d.ts +8 -4
@@ -0,0 +1,375 @@
1
+ /**
2
+ * The write journal's store: where a connection's Undo history is kept when
3
+ * the database holds it, so a restart does not forget the writes it could
4
+ * still put back (journal.ts).
5
+ *
6
+ * The store is opt-in, like every reserved store: provisioned by an explicit
7
+ * step (`mistri migrate stores`, `provisionStores({ only: ['undo-journal'] })`,
8
+ * or the provisioning functions here for a host that has no App framework),
9
+ * never by opening a connection. A writable connection whose database holds
10
+ * this build's layout keeps its journal there; one that holds none keeps it in
11
+ * memory, as before, and in the database browser says so once, naming the
12
+ * step that provisions it (a journal that silently outlasts nothing is a
13
+ * promise the docs make and the run does not keep). An App says nothing of it:
14
+ * Undo is the Workbench's, an App offers none, so the notice would be an
15
+ * operator chore with nothing to gain, and `mistri check` read it as the App's
16
+ * failure. One that holds another layout keeps it in memory and says why once.
17
+ *
18
+ * It sits in the business database, beside the rows it describes, under the
19
+ * reserved prefix: the catalog never lists it, and a copy of the database
20
+ * carries the history that belongs to it. What is kept is what memory holds —
21
+ * the entry the hidden-column wrapper already stripped — so a hidden value is
22
+ * no more in the store than it was in the journal.
23
+ *
24
+ * Retention is the journal's own depth (the newest `entries` per connection)
25
+ * and an age (`days`): an Undo a week later is an overwrite more often than
26
+ * not, and the revert's check-before-write is the only thing that would stop
27
+ * it. An entry too large to keep is kept as a barrier instead, which is what
28
+ * it is after a restart: a write whose inverse is gone, so no older Undo is
29
+ * offered past it.
30
+ */
31
+ import { statSync } from 'node:fs';
32
+ import { DatabaseSync } from 'node:sqlite';
33
+ import { Refusal } from '../adapters/adapter.js';
34
+ import { layoutRefusal, postgresLayoutVersion, sqliteLayoutVersion } from '../adapters/layoutRefusal.js';
35
+ import { withPostgresMaintenanceTransaction } from '../adapters/postgresMaintenance.js';
36
+ import { storeHostOf, writeViewOf } from '../adapters/storeHost.js';
37
+ import { runtimeName, runtimeSchema, runtimeTable } from '../shared/runtimeTables.js';
38
+ import { attachJournalStore } from './journal.js';
39
+ import { product } from './product.js';
40
+ const WRITE_JOURNAL_VERSION = 1;
41
+ /** The reserved prefix of its tables (`mistri.undo_*` on PostgreSQL). */
42
+ const WRITE_JOURNAL_PREFIX = '__mistri_undo_';
43
+ const META = '__mistri_undo_meta';
44
+ const ENTRY = '__mistri_undo_entry';
45
+ /** How much is kept: the journal's depth per connection, a week, and an entry of at most 4 MiB. */
46
+ export const WRITE_JOURNAL_RETENTION = Object.freeze({ entries: 50, days: 7, bytes: 4 * 1024 * 1024 });
47
+ const DAY_MS = 86_400_000;
48
+ /** Why the store cannot be used: an unprovisioned database is not this; a layout that is not this build's is. */
49
+ class WriteJournalUnavailable extends Refusal {
50
+ constructor(message = 'The write journal store is missing or is not the layout this version expects.') {
51
+ super(message);
52
+ this.name = 'WriteJournalUnavailable';
53
+ }
54
+ }
55
+ /* ---------- SQLite ---------- */
56
+ const sqliteDefinitions = new Map([
57
+ [
58
+ META,
59
+ `CREATE TABLE "${META}" (
60
+ singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
61
+ version INTEGER NOT NULL CHECK (version = ${WRITE_JOURNAL_VERSION})
62
+ )`,
63
+ ],
64
+ [
65
+ ENTRY,
66
+ `CREATE TABLE "${ENTRY}" (
67
+ connection TEXT COLLATE BINARY NOT NULL,
68
+ id INTEGER NOT NULL,
69
+ at INTEGER NOT NULL,
70
+ entry_json TEXT NOT NULL CHECK (json_valid(entry_json)),
71
+ PRIMARY KEY (connection, id)
72
+ )`,
73
+ ],
74
+ ]);
75
+ const underPrefix = `substr(name, 1, ?) = ? COLLATE NOCASE OR substr(tbl_name, 1, ?) = ? COLLATE NOCASE`;
76
+ const prefixArgs = [WRITE_JOURNAL_PREFIX.length, WRITE_JOURNAL_PREFIX, WRITE_JOURNAL_PREFIX.length, WRITE_JOURNAL_PREFIX];
77
+ const sqliteCatalog = (db) => db
78
+ .prepare(`SELECT type, name, tbl_name, sql FROM main.sqlite_schema WHERE ${underPrefix}`)
79
+ .all(...prefixArgs);
80
+ /** Exactly this version's two tables and their key indexes, nothing else under the prefix, and its version row. */
81
+ export function sqliteWriteJournalReady(db) {
82
+ try {
83
+ if (db.prepare(`SELECT 1 FROM temp.sqlite_schema WHERE ${underPrefix} LIMIT 1`).get(...prefixArgs))
84
+ return false;
85
+ const entries = sqliteCatalog(db);
86
+ const tables = entries.filter((entry) => entry.type === 'table');
87
+ if (tables.length !== sqliteDefinitions.size ||
88
+ tables.some((entry) => sqliteDefinitions.get(entry.name) !== entry.sql) ||
89
+ entries.some((entry) => entry.type !== 'table' && !(entry.type === 'index' && entry.sql === null && sqliteDefinitions.has(entry.tbl_name))))
90
+ return false;
91
+ const rows = db.prepare(`SELECT singleton, version FROM main."${META}"`).all();
92
+ return rows.length === 1 && rows[0].singleton === 1 && rows[0].version === WRITE_JOURNAL_VERSION;
93
+ }
94
+ catch {
95
+ return false;
96
+ }
97
+ }
98
+ const inMain = (ddl) => ddl.replace('CREATE TABLE ', 'CREATE TABLE main.');
99
+ /**
100
+ * Explicit maintenance, never run when a connection opens: a file without the
101
+ * store gets this version; the same layout again changes nothing; anything
102
+ * else under the prefix is refused unchanged.
103
+ */
104
+ export function provisionSqliteWriteJournal(existingPath) {
105
+ if (!statSync(existingPath).isFile())
106
+ throw new Refusal('Write journal provisioning requires an existing SQLite file.');
107
+ const db = new DatabaseSync(existingPath);
108
+ try {
109
+ db.exec('PRAGMA busy_timeout = 5000');
110
+ db.exec('BEGIN IMMEDIATE');
111
+ try {
112
+ let provisioned = false;
113
+ if (sqliteCatalog(db).length === 0) {
114
+ for (const ddl of sqliteDefinitions.values())
115
+ db.exec(inMain(ddl));
116
+ db.prepare(`INSERT INTO main."${META}" (singleton, version) VALUES (1, ?)`).run(WRITE_JOURNAL_VERSION);
117
+ provisioned = true;
118
+ }
119
+ if (!sqliteWriteJournalReady(db))
120
+ throw new WriteJournalUnavailable(layoutRefusal('The write journal store', sqliteLayoutVersion(db, META), WRITE_JOURNAL_VERSION));
121
+ db.exec('COMMIT');
122
+ return { version: WRITE_JOURNAL_VERSION, provisioned };
123
+ }
124
+ catch (error) {
125
+ try {
126
+ db.exec('ROLLBACK');
127
+ }
128
+ catch {
129
+ /* Preserve the provisioning failure. */
130
+ }
131
+ throw error;
132
+ }
133
+ }
134
+ finally {
135
+ db.close();
136
+ }
137
+ }
138
+ /* ---------- PostgreSQL ---------- */
139
+ const pgMeta = runtimeTable('postgres', META);
140
+ const pgEntry = runtimeTable('postgres', ENTRY);
141
+ const pgPrefix = runtimeName('postgres', WRITE_JOURNAL_PREFIX.slice(0, -1)) + '_';
142
+ const pgDefinitions = [
143
+ `CREATE TABLE ${pgMeta} (
144
+ singleton integer PRIMARY KEY CHECK (singleton = 1),
145
+ version integer NOT NULL CHECK (version = ${WRITE_JOURNAL_VERSION})
146
+ )`,
147
+ `CREATE TABLE ${pgEntry} (
148
+ connection text COLLATE "C" NOT NULL,
149
+ id bigint NOT NULL,
150
+ at bigint NOT NULL,
151
+ entry jsonb NOT NULL,
152
+ PRIMARY KEY (connection, id)
153
+ )`,
154
+ ];
155
+ /* What the DDL above reads back as, pinned so the attestation is of this layout and not of whatever is there. */
156
+ const PG_LAYOUT = JSON.stringify([
157
+ {
158
+ name: runtimeName('postgres', ENTRY),
159
+ kind: 'r',
160
+ columns: ['connection text C t', 'id bigint - t', 'at bigint - t', 'entry jsonb - t'],
161
+ constraints: ['PRIMARY KEY (connection, id)'],
162
+ },
163
+ {
164
+ name: `${runtimeName('postgres', ENTRY)}_pkey`,
165
+ kind: 'i',
166
+ columns: ['connection text C f', 'id bigint - f'],
167
+ constraints: [],
168
+ },
169
+ {
170
+ name: runtimeName('postgres', META),
171
+ kind: 'r',
172
+ columns: ['singleton integer - t', 'version integer - t'],
173
+ constraints: ['CHECK ((singleton = 1))', `CHECK ((version = ${WRITE_JOURNAL_VERSION}))`, 'PRIMARY KEY (singleton)'],
174
+ },
175
+ {
176
+ name: `${runtimeName('postgres', META)}_pkey`,
177
+ kind: 'i',
178
+ columns: ['singleton integer - f'],
179
+ constraints: [],
180
+ },
181
+ ]);
182
+ /** Every relation under the prefix in the runtime schema, with its columns and constraints, in a fixed order; triggers, rules and row security disqualify it. */
183
+ async function pgRelations(client) {
184
+ const rows = (await client.query(`SELECT c.relname AS name, c.relkind::text AS kind,
185
+ c.relrowsecurity OR c.relhastriggers OR c.relhasrules AS guarded,
186
+ coalesce((SELECT json_agg(a.attname || ' ' || format_type(a.atttypid, a.atttypmod) || ' ' ||
187
+ coalesce((SELECT co.collname FROM pg_collation co WHERE co.oid = a.attcollation AND a.attcollation <> 0
188
+ AND a.attcollation <> (SELECT t.typcollation FROM pg_type t WHERE t.oid = a.atttypid)), '-') || ' ' ||
189
+ CASE WHEN a.attnotnull THEN 't' ELSE 'f' END ORDER BY a.attnum)
190
+ FROM pg_attribute a WHERE a.attrelid = c.oid AND a.attnum > 0 AND NOT a.attisdropped), '[]') AS columns,
191
+ coalesce((SELECT json_agg(pg_get_constraintdef(k.oid) ORDER BY pg_get_constraintdef(k.oid) COLLATE "C")
192
+ FROM pg_constraint k WHERE k.conrelid = c.oid), '[]') AS constraints,
193
+ (SELECT count(*) FROM pg_attrdef d WHERE d.adrelid = c.oid)::int AS defaults
194
+ FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
195
+ WHERE n.nspname = $1 AND substr(c.relname, 1, $2) = $3
196
+ ORDER BY c.relname COLLATE "C"`, [runtimeSchema('postgres'), pgPrefix.length, pgPrefix])).rows;
197
+ if (rows.some((row) => row.guarded || row.defaults))
198
+ return { text: '', count: rows.length };
199
+ return {
200
+ text: JSON.stringify(rows.map(({ name, kind, columns, constraints }) => ({ name, kind, columns, constraints }))),
201
+ count: rows.length,
202
+ };
203
+ }
204
+ /** Whether the reserved relations are exactly this version's layout with its version row. */
205
+ export async function postgresWriteJournalReady(client) {
206
+ try {
207
+ if ((await pgRelations(client)).text !== PG_LAYOUT)
208
+ return false;
209
+ const rows = (await client.query(`SELECT singleton, version FROM ${pgMeta}`)).rows;
210
+ return rows.length === 1 && rows[0].singleton === 1 && rows[0].version === WRITE_JOURNAL_VERSION;
211
+ }
212
+ catch {
213
+ return false;
214
+ }
215
+ }
216
+ /** Explicit maintenance, under the shared migration lock: creates this version
217
+ * where no store exists, changes nothing where it does, refuses anything else. */
218
+ export async function provisionPostgresWriteJournal(url) {
219
+ if (typeof url !== 'string' || !/^postgres(ql)?:\/\//i.test(url))
220
+ throw new Refusal('Write journal provisioning requires a postgres:// URL.');
221
+ return withPostgresMaintenanceTransaction(url, async (client) => {
222
+ let provisioned = false;
223
+ if (!(await pgRelations(client)).count) {
224
+ for (const ddl of pgDefinitions)
225
+ await client.query(ddl);
226
+ await client.query(`INSERT INTO ${pgMeta} (singleton, version) VALUES (1, $1)`, [WRITE_JOURNAL_VERSION]);
227
+ provisioned = true;
228
+ }
229
+ if (!(await postgresWriteJournalReady(client)))
230
+ throw new WriteJournalUnavailable(layoutRefusal('The write journal store', await postgresLayoutVersion(client, pgMeta), WRITE_JOURNAL_VERSION));
231
+ return { version: WRITE_JOURNAL_VERSION, provisioned };
232
+ });
233
+ }
234
+ /* ---------- what is kept ---------- */
235
+ /** The stored form: the entry without the columns that say where and when it is. */
236
+ function stored(entry) {
237
+ const { id: _id, connection: _connection, at: _at, ...rest } = entry;
238
+ const json = JSON.stringify(rest);
239
+ if (Buffer.byteLength(json) <= WRITE_JOURNAL_RETENTION.bytes)
240
+ return json;
241
+ // Kept as what it is after a restart: a write with no inverse left, which blocks every older Undo.
242
+ const { steps, ...plain } = rest;
243
+ return JSON.stringify({
244
+ ...plain,
245
+ revertible: false,
246
+ blocksUndo: true,
247
+ reason: 'This write was too large to keep its Undo across a restart.',
248
+ steps: steps.length ? [{ table: steps[0].table }] : [],
249
+ });
250
+ }
251
+ function revived(connection, id, at, json) {
252
+ const body = (typeof json === 'string' ? JSON.parse(json) : json);
253
+ return { ...body, id: Number(id), connection, at: new Date(Number(at)).toISOString() };
254
+ }
255
+ const atOf = (entry) => {
256
+ const at = Date.parse(entry.at);
257
+ return Number.isFinite(at) ? at : Date.now();
258
+ };
259
+ const oldest = () => Date.now() - WRITE_JOURNAL_RETENTION.days * DAY_MS;
260
+ function sqliteStore(host) {
261
+ const prune = (db, connection) => db
262
+ .prepare(`DELETE FROM main."${ENTRY}" WHERE connection = ? AND (at < ? OR id NOT IN
263
+ (SELECT id FROM main."${ENTRY}" WHERE connection = ? ORDER BY id DESC LIMIT ?))`)
264
+ .run(connection, oldest(), connection, WRITE_JOURNAL_RETENTION.entries);
265
+ return {
266
+ load: (connection) => host.queueWrite((db) => {
267
+ prune(db, connection);
268
+ return db.prepare(`SELECT id, at, entry_json FROM main."${ENTRY}" WHERE connection = ? ORDER BY id`).all(connection).map((row) => revived(connection, row.id, row.at, row.entry_json));
269
+ }),
270
+ append: (entry) => host.queueWrite((db) => {
271
+ db.prepare(`INSERT INTO main."${ENTRY}" (connection, id, at, entry_json) VALUES (?, ?, ?, ?)`).run(entry.connection, entry.id, atOf(entry), stored(entry));
272
+ prune(db, entry.connection);
273
+ }),
274
+ update: (entry) => host.queueWrite((db) => {
275
+ db.prepare(`UPDATE main."${ENTRY}" SET entry_json = ? WHERE connection = ? AND id = ?`).run(stored(entry), entry.connection, entry.id);
276
+ }),
277
+ remove: (connection, id) => host.queueWrite((db) => {
278
+ db.prepare(`DELETE FROM main."${ENTRY}" WHERE connection = ? AND id = ?`).run(connection, id);
279
+ }),
280
+ };
281
+ }
282
+ function postgresStore(host) {
283
+ const prune = (client, connection) => client.query(`DELETE FROM ${pgEntry} WHERE connection = $1 AND (at < $2 OR id NOT IN
284
+ (SELECT id FROM ${pgEntry} WHERE connection = $1 ORDER BY id DESC LIMIT $3))`, [connection, oldest(), WRITE_JOURNAL_RETENTION.entries]);
285
+ return {
286
+ load: (connection) => host.withWriteClient(async (client) => {
287
+ await prune(client, connection);
288
+ const rows = (await client.query(`SELECT id, at, entry FROM ${pgEntry} WHERE connection = $1 ORDER BY id`, [connection]))
289
+ .rows;
290
+ return rows.map((row) => revived(connection, row.id, row.at, row.entry));
291
+ }),
292
+ append: (entry) => host.withWriteClient(async (client) => {
293
+ await client.query(`INSERT INTO ${pgEntry} (connection, id, at, entry) VALUES ($1, $2, $3, $4::jsonb)`, [
294
+ entry.connection,
295
+ entry.id,
296
+ atOf(entry),
297
+ stored(entry),
298
+ ]);
299
+ await prune(client, entry.connection);
300
+ }),
301
+ update: (entry) => host.withWriteClient(async (client) => {
302
+ await client.query(`UPDATE ${pgEntry} SET entry = $1::jsonb WHERE connection = $2 AND id = $3`, [
303
+ stored(entry),
304
+ entry.connection,
305
+ entry.id,
306
+ ]);
307
+ }),
308
+ remove: (connection, id) => host.withWriteClient(async (client) => {
309
+ await client.query(`DELETE FROM ${pgEntry} WHERE connection = $1 AND id = $2`, [connection, id]);
310
+ }),
311
+ };
312
+ }
313
+ /** A database that can hold the store and holds none of it: the journal stays in memory, and the operator is told. */
314
+ const NOT_PROVISIONED = 'not-provisioned';
315
+ /**
316
+ * The store an adapter's database holds; NOT_PROVISIONED where the database
317
+ * could hold it and holds none (the journal then stays in memory); undefined
318
+ * where the adapter has no database to hold one (an HTTP source). An adapter a
319
+ * wrapper narrowed is looked through to the one it wraps. Throws
320
+ * WriteJournalUnavailable for a layout that is not this build's.
321
+ */
322
+ async function writeJournalStoreOf(adapter) {
323
+ const host = storeHostOf(adapter) ?? storeHostOf(writeViewOf(adapter)?.over);
324
+ if (!host)
325
+ return undefined;
326
+ if (host.dialect === 'sqlite') {
327
+ const db = host.reader();
328
+ if (!sqliteCatalog(db).length)
329
+ return NOT_PROVISIONED;
330
+ if (!sqliteWriteJournalReady(db))
331
+ throw new WriteJournalUnavailable(layoutRefusal('The write journal store', sqliteLayoutVersion(db, META), WRITE_JOURNAL_VERSION));
332
+ return sqliteStore(host);
333
+ }
334
+ return host.withReadClient(async (client) => {
335
+ if (!(await pgRelations(client)).count)
336
+ return NOT_PROVISIONED;
337
+ if (!(await postgresWriteJournalReady(client)))
338
+ throw new WriteJournalUnavailable(layoutRefusal('The write journal store', await postgresLayoutVersion(client, pgMeta), WRITE_JOURNAL_VERSION));
339
+ return postgresStore(host);
340
+ });
341
+ }
342
+ /** What an operator needs when a writable connection's database holds no store: what is lost, and the one step that provisions it. */
343
+ function unprovisioned(connection, adapter) {
344
+ const host = storeHostOf(adapter) ?? storeHostOf(writeViewOf(adapter)?.over);
345
+ const target = host?.dialect === 'postgres' ? "postgres: '<the connection's URL>'" : "sqlite: '<the database file>'";
346
+ return (`"${connection}": Undo history is kept in memory for this run, and a restart forgets it: this database holds no undo-journal store. ` +
347
+ `It is provisioned once, never by opening a connection. With the server stopped, run ` +
348
+ `provisionStores({ ${target} }, { only: ['undo-journal'] }) from @mistriwork/mistri/maintenance ` +
349
+ `(or ${host?.dialect === 'postgres' ? 'provisionPostgresWriteJournal' : 'provisionSqliteWriteJournal'} from @mistriwork/engine/server/journalStore.js), then start again.`);
350
+ }
351
+ /**
352
+ * Keep `connection`'s journal in its database when the database holds the
353
+ * store: what it held is read back, and every write from here on is kept
354
+ * there too. Never fatal: a store that is missing or cannot be read leaves the
355
+ * journal in memory, said through `warn` (the caller says it once). Resolves to whether the store is now used.
356
+ */
357
+ export async function keepWriteJournal(connection, adapter, warn = (message) => console.error(message)) {
358
+ try {
359
+ const store = await writeJournalStoreOf(adapter);
360
+ if (store === NOT_PROVISIONED) {
361
+ // Only the browser offers Undo (the header says why an App stays quiet).
362
+ if (product() === 'tablewalk')
363
+ warn(unprovisioned(connection, adapter));
364
+ return false;
365
+ }
366
+ if (!store)
367
+ return false;
368
+ await attachJournalStore(connection, store, warn);
369
+ return true;
370
+ }
371
+ catch (error) {
372
+ warn(`"${connection}": Undo history is kept in memory for this run: ${error.message}`);
373
+ return false;
374
+ }
375
+ }
@@ -24,7 +24,9 @@ export interface AppReads {
24
24
  * request's reader (app/appMe.ts), or nothing where no text compares with
25
25
  * the person.
26
26
  */
27
- person(me: () => Promise<QueryPerson | null>, texts: readonly unknown[], schema: DatabaseSchema, adapter: Adapter): Promise<{
27
+ person(
28
+ /** Given the texts, a lookup may be skipped where they need only the email (app/appMe.ts emailOnly). */
29
+ me: (texts?: readonly unknown[]) => Promise<QueryPerson | null>, texts: readonly unknown[], schema: DatabaseSchema, adapter: Adapter): Promise<{
28
30
  me?: QueryPerson | null;
29
31
  }>;
30
32
  }
@@ -37,7 +39,7 @@ interface ResourceReadHttpOptions {
37
39
  * asked only when the text says `me` (appMe.ts). Absent — the database
38
40
  * browser, a tenant App — `me` is the word it is.
39
41
  */
40
- me?: () => Promise<QueryPerson | null>;
42
+ me?: (texts?: readonly unknown[]) => Promise<QueryPerson | null>;
41
43
  /**
42
44
  * The ISO weekday an App's weeks start on (its `ui.locale`, weekStart.ts),
43
45
  * set on every breakdown in place of whatever the request said. Absent —
@@ -40,7 +40,21 @@ function plainCount(schema, view) {
40
40
  : {};
41
41
  }
42
42
  /* What a batched list's page may say: what `/api/run` reads of a first page. */
43
- const RUN_FIELDS = ['q', 'limit', 'offset', 'count', 'exactCount', 'countLimit'];
43
+ const RUN_FIELDS = ['q', 'limit', 'offset', 'count', 'exactCount', 'countLimit', 'lanes'];
44
+ /** The most rows a lanes read keeps per lane: a board's page, a few times over. */
45
+ const LANE_MOST = 100;
46
+ /** A run's `lanes`, read: absent, refused, or the column and how many of each. */
47
+ function readLanes(raw) {
48
+ if (raw === undefined)
49
+ return undefined;
50
+ const lanes = raw;
51
+ if (!lanes || typeof lanes !== 'object' || Array.isArray(lanes) || Object.keys(lanes).some((key) => key !== 'by' && key !== 'limit'))
52
+ return 'invalid';
53
+ const { by, limit } = lanes;
54
+ if (typeof by !== 'string' || !by || typeof limit !== 'number' || !Number.isInteger(limit) || limit < 1 || limit > LANE_MOST)
55
+ return 'invalid';
56
+ return { by, limit };
57
+ }
44
58
  /** A dashboard is at most a few dozen sections; a batch past this is not one. */
45
59
  export const BREAKDOWN_BATCH = 48;
46
60
  /* How many of a batch's breakdowns read at once: the PostgreSQL read pool's
@@ -122,6 +136,10 @@ export async function dispatchResourceReadHttp(path, body, adapter, schema, opti
122
136
  if (body.count !== undefined && body.count !== 'none' && body.count !== 'exact' && body.count !== 'estimate') {
123
137
  return refusal(400, ['count must be "none", "exact" or "estimate".']);
124
138
  }
139
+ /* A board's lanes, each its first page, in one statement (adapter.ts lanesStatement): a list of one table, no total. */
140
+ const lanes = readLanes(body.lanes);
141
+ if (lanes === 'invalid')
142
+ return refusal(400, [`lanes is { by: a column, limit: 1 to ${LANE_MOST} }.`]);
125
143
  const text = String(body.q ?? '');
126
144
  const person = await personFor(text);
127
145
  const parsed = parseQuery(text, { schema, now: options.now(), ...person });
@@ -139,6 +157,14 @@ export async function dispatchResourceReadHttp(path, body, adapter, schema, opti
139
157
  const asView = textToView(schema, text, { id: 'bar', name: '', now: options.now(), ...person });
140
158
  if (asView.view && !asView.errors.length) {
141
159
  const base = findTable(schema, asView.view.base);
160
+ /* A list that names a path (`customer_id.name`) is a view, and its lanes are read the same one way. */
161
+ if (lanes) {
162
+ if (!base || base.union || step || !base.columns.some((column) => column.name === lanes.by))
163
+ return refusal(400, [`A board reads its lanes in one read only by a column of ${asView.view.base}'s own rows.`]);
164
+ const most = options.rowsMost?.(asView.view.base);
165
+ const bounded = most === undefined ? body : { ...body, limit: Math.min(clampLimit(body.limit ?? asView.view.limit), most) };
166
+ return runViewForBar(adapter, schema, { ...asView.view, lanes }, bounded, app, 'none');
167
+ }
142
168
  /* A union pages by offset: its rows have no one key order across branches (unionReads.ts). */
143
169
  const paging = base && !base.union ? viewPaging(schema, base, asView.view, step) : undefined;
144
170
  if (step && !paging?.continuation) {
@@ -179,22 +205,32 @@ export async function dispatchResourceReadHttp(path, body, adapter, schema, opti
179
205
  every page of someone else's rate budget: its lists page by whether a
180
206
  full page came back, as a view without a count does. */
181
207
  const exact = body.exactCount === true || body.count === 'exact';
182
- const countMode = schema.dialect === 'http' || body.count === 'none' ? 'none' : exact ? 'exact' : 'estimate';
208
+ const countMode = schema.dialect === 'http' || body.count === 'none' || lanes ? 'none' : exact ? 'exact' : 'estimate';
183
209
  /* A filtered total is counted to DEFAULT_COUNT_LIMIT unless the request
184
210
  asks for the exact number or names its own bound: past it the list says
185
211
  "10,000+" and offers to count exactly. Unfiltered, the catalog's
186
212
  estimate or a plain count answers as before. */
187
213
  const countLimit = body.countLimit ?? (!exact && q.filter?.groups?.length ? DEFAULT_COUNT_LIMIT : undefined);
188
214
  const own = findTable(schema, q.table);
215
+ /* Lanes are a column of one stored table's rows: a union pages its branches apart, an API answers in its own order. */
216
+ if (lanes && (!own || own.union || schema.dialect === 'http' || step || !own.columns.some((column) => column.name === lanes.by))) {
217
+ return refusal(400, [`A board reads its lanes in one read only by a column of ${q.table}'s own rows.`]);
218
+ }
189
219
  const most = options.rowsMost?.(own?.id ?? q.table);
190
220
  const bounded = (limit) => (most === undefined ? limit : Math.min(clampLimit(limit), most));
191
- const paging = own && !own.union ? recordsPaging(own, schema.dialect, q.orderBy, q.columns, q.filter, step) : undefined;
221
+ const paging = own && !own.union && !lanes ? recordsPaging(own, schema.dialect, q.orderBy, q.columns, q.filter, step) : undefined;
192
222
  if (step && !paging?.continuation) {
193
223
  const refused = tooDeep();
194
224
  if (refused)
195
225
  return refused;
196
226
  }
197
- const { result, total, order, request: { limit, offset }, } = await readRecords(adapter, schema, { ...q, ...(paging?.columns ? { columns: paging.columns } : {}), limit: bounded(body.limit ?? q.limit), offset: body.offset }, countMode, countLimit, paging?.continuation);
227
+ const { result, total, order, request: { limit, offset }, } = await readRecords(adapter, schema, {
228
+ ...q,
229
+ ...(paging?.columns ? { columns: paging.columns } : {}),
230
+ ...(lanes ? { lanes } : {}),
231
+ limit: bounded(body.limit ?? q.limit),
232
+ offset: body.offset,
233
+ }, countMode, countLimit, paging?.continuation);
198
234
  const settled = paging ? settlePage(paging.order, paging.extra, result) : undefined;
199
235
  return sendData(path, {
200
236
  table: q.table,
@@ -96,6 +96,10 @@ export declare function readView(reader: ResourceReader, schema: DatabaseSchema,
96
96
  filter?: (import("../shared/viewPaths.js").ViewFilter & StructuredFilter<"path">) | undefined;
97
97
  orderBy?: import("../shared/viewPaths.js").ViewOrder[];
98
98
  limit?: number;
99
+ lanes?: {
100
+ by: string;
101
+ limit: number;
102
+ };
99
103
  text?: string;
100
104
  connection?: string;
101
105
  source?: 'config' | 'saved';
@@ -24,7 +24,9 @@ const said = (value) => value
24
24
  .toLowerCase()
25
25
  .replace(/[\s-]+/g, '_');
26
26
  /* Words that call the work off: the exits. */
27
- const EXIT = /^(cancell?ed|rejected|declined|denied|lost|closed_lost|void|voided|withdrawn|abandoned|failed|expired|refunded|no_show|dismissed|discarded|dropped|disqualified|unqualified|churned|terminated|aborted|wont_fix|duplicate|spam)$/;
27
+ const EXIT = /^(cancell?ed|rejected|declined|denied|lost|closed_lost|void|voided|withdrawn|abandoned|failed|expired|refunded|no_show|noshow|missed|skipped|dismissed|discarded|dropped|disqualified|unqualified|churned|terminated|aborted|wont_fix|duplicate|spam)$/;
28
+ /* Words that say the work is done: the path's end. */
29
+ const DONE = /^(done|complete|completed|finished|resolved|closed|fulfilled|delivered|collected)$/;
28
30
  /* Words that park the work: a side state, left the way it was entered. */
29
31
  const HOLD = /^(on_hold|hold|paused|blocked|stalled|deferred|snoozed|backordered|waiting|waiting_\w+)$/;
30
32
  /* The verb that leads into a state, by the state's word: what a person does to put the record there. */
@@ -99,6 +101,15 @@ export function draftMachine(table, column) {
99
101
  if (states.length < 3 || states.length > 10 || column.flag || !states.every((state) => /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(state)))
100
102
  return undefined;
101
103
  const exits = states.filter((state, i) => i > 0 && EXIT.test(said(state)));
104
+ /* The work ends where it is done. Past `completed`, only a step this file knows a verb for (invoiced, archived)
105
+ goes on; a word it does not know there is another way the work ended — read as a step, a visit's `missed`
106
+ listed after `completed` became `completed → markMissed`, a way out of a finished visit. */
107
+ const done = states.findIndex((state) => DONE.test(said(state)));
108
+ if (done !== -1)
109
+ for (const state of states.slice(done + 1))
110
+ if (!exits.includes(state) && !HOLD.test(said(state)) && !INTO[said(state)])
111
+ exits.push(state);
112
+ exits.sort((a, b) => states.indexOf(a) - states.indexOf(b));
102
113
  const holdStates = states.filter((state, i) => i > 0 && !exits.includes(state) && HOLD.test(said(state)));
103
114
  const path = states.filter((state) => !exits.includes(state) && !holdStates.includes(state));
104
115
  if (path.length < 2)
@@ -1,3 +1,10 @@
1
1
  import type { AppListPresentation } from './listPresentations.js';
2
+ /**
3
+ * The columns a presentation draws with their display rule's second line (`subtitle`), so a list reads it with the
4
+ * row: a card's title, its figure and its captioned lines, and a board card's title. A one-line place — a badge, a
5
+ * description, a card's summary and foot, a board card's line, chip and facts — has no room for one, and `check` says
6
+ * so where a subtitled column stands there (`subtitle-unseen`).
7
+ */
8
+ export declare function listSecondLineColumns(list: AppListPresentation): string[];
2
9
  /** A split reads through its own show, and the columns of its rows when it chooses them. */
3
10
  export declare function listPresentationColumns(list: AppListPresentation): string[];
@@ -6,6 +6,19 @@
6
6
  * homes it installs at load — into the first script it downloads.
7
7
  */
8
8
  import { cardsColumns } from './appCards.js';
9
+ /**
10
+ * The columns a presentation draws with their display rule's second line (`subtitle`), so a list reads it with the
11
+ * row: a card's title, its figure and its captioned lines, and a board card's title. A one-line place — a badge, a
12
+ * description, a card's summary and foot, a board card's line, chip and facts — has no room for one, and `check` says
13
+ * so where a subtitled column stands there (`subtitle-unseen`).
14
+ */
15
+ export function listSecondLineColumns(list) {
16
+ if (list.kind === 'cards')
17
+ return [...new Set([list.primary, ...(list.value ? [list.value] : []), ...(list.lines ?? [])])];
18
+ if (list.kind === 'board')
19
+ return [list.primary];
20
+ return [];
21
+ }
9
22
  /** A split reads through its own show, and the columns of its rows when it chooses them. */
10
23
  export function listPresentationColumns(list) {
11
24
  if (list.kind === 'split') {
@@ -0,0 +1,44 @@
1
+ /** A lane's cards are read this many at a time; "Show more" reads the next. */
2
+ export declare const LANE_PAGE = 20;
3
+ export declare const LANE_COUNT = "lane_cards";
4
+ export declare const LANE_SUM = "lane_amount";
5
+ export declare const LANE_CURRENCY = "lane_currency";
6
+ /** The lane breakdown's question: the list's conditions, without its show, sort or page, counted (and summed) by the lane column. */
7
+ export declare function laneCountsText(query: string | undefined, by: string, amount?: string, currencyBy?: string): string | null;
8
+ /** What the list's read adds to read as a board's lanes: the first page of each lane, one statement, no total. */
9
+ export declare const laneWindow: (by: string) => {
10
+ limit: number;
11
+ count: 'none';
12
+ lanes: {
13
+ by: string;
14
+ limit: number;
15
+ };
16
+ };
17
+ type AmountRule = {
18
+ format?: string;
19
+ currencyColumn?: string;
20
+ };
21
+ /**
22
+ * What a card is worth: the board's `sum`, else the first money its card shows (a line, a fact on its foot), and
23
+ * the column that says each card's currency where it says its own. `rule` is a column's display rule where it
24
+ * says money or a number, else null.
25
+ */
26
+ export declare function boardAmount(spec: {
27
+ sum?: string;
28
+ lines?: readonly string[];
29
+ footer?: ReadonlyArray<{
30
+ column: string;
31
+ }>;
32
+ }, rule: (column: string) => AmountRule | null): {
33
+ amount?: string;
34
+ said?: AmountRule;
35
+ currencyBy?: string;
36
+ };
37
+ /**
38
+ * The lists this browser reads as boards (kit LayoutSwitch.tsx), said to the server too, so a page it opens on one
39
+ * carries the board's reads rather than the list's: the view ids, each encoded, joined by commas.
40
+ */
41
+ export declare const BOARD_COOKIE = "mistri_boards";
42
+ /** The views a request's Cookie header says are read as boards. */
43
+ export declare function boardsInCookie(header: string | undefined): ReadonlySet<string>;
44
+ export {};