@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
@@ -173,7 +173,7 @@ const chunks = (items, size) => {
173
173
  * room asks (`rooms`, an App's: firstPaintRooms.ts). Each round's requests
174
174
  * are asked together.
175
175
  */
176
- export async function firstPaint({ path, search, loop: asked, most = MOST, budget = BUDGET, rooms, }) {
176
+ export async function firstPaint({ path, search, loop: asked, most = MOST, budget = BUDGET, rooms, cookie, }) {
177
177
  const carried = new Carried();
178
178
  /* Past the budget every answer still out is none: the client asks it. */
179
179
  const controller = new AbortController();
@@ -193,14 +193,14 @@ export async function firstPaint({ path, search, loop: asked, most = MOST, budge
193
193
  return Promise.race([answer, late]);
194
194
  };
195
195
  try {
196
- return await answered(carried, path, search, loop, most, rooms);
196
+ return await answered(carried, path, search, loop, most, rooms, cookie);
197
197
  }
198
198
  finally {
199
199
  clearTimeout(timer);
200
200
  controller.abort();
201
201
  }
202
202
  }
203
- async function answered(carried, path, search, loop, most, rooms) {
203
+ async function answered(carried, path, search, loop, most, rooms, cookie) {
204
204
  const ask = async (method, target, body) => carried.read(method, target, body, await loop(method, target, body));
205
205
  const done = () => ({ json: carried.json(most) });
206
206
  /* A page that is all its own reads is asked for before who-am-I (boot.js). */
@@ -224,7 +224,7 @@ async function answered(carried, path, search, loop, most, rooms) {
224
224
  ]));
225
225
  if (!me || !runtime || !rooms)
226
226
  return done();
227
- const room = await rooms.room({ path, search, requested, me, runtime, ask });
227
+ const room = await rooms.room({ path, search, requested, me, runtime, ask, ...(cookie ? { cookie } : {}) });
228
228
  if (!room)
229
229
  return done();
230
230
  const { app: selected, plan } = room;
@@ -75,6 +75,12 @@ export function send(res, status, body) {
75
75
  }
76
76
  if (res.destroyed || res.writableEnded)
77
77
  return;
78
+ /* A reply already under way — a streamed export whose policy context failed after its rows went
79
+ (exportRoute.ts) — cannot become an error: it is cut, and the client sees a failed download. */
80
+ if (res.headersSent) {
81
+ res.destroy();
82
+ return;
83
+ }
78
84
  /* While the dev observer runs, a failure says where its trace is: the
79
85
  "Open in observer" link beside the refusal (observe/mount.ts). */
80
86
  const observe = traceLink && status >= 400 && body && typeof body === 'object' && !Array.isArray(body)
@@ -28,9 +28,11 @@ export interface HttpConnectionConfig {
28
28
  * An entry's HTTP fields, checked: the resolved block for an `http`
29
29
  * connection, undefined for a database. Throws naming the field, because a
30
30
  * config someone wrote is refused rather than half-read. Service kinds
31
- * (`cache`, `webhook`, …) are read by serviceConnections.ts before this is asked.
31
+ * (`cache`, `webhook`, …) are read by serviceConnections.ts before this is asked;
32
+ * `kinds` are the ones the reader's sections know, so an unknown kind is answered
33
+ * with the list this reader takes rather than one written down once and outgrown.
32
34
  */
33
- export declare function httpConnectionOf(entry: Record<string, unknown>, path: string): HttpConnectionConfig | undefined;
35
+ export declare function httpConnectionOf(entry: Record<string, unknown>, path: string, kinds?: readonly string[]): HttpConnectionConfig | undefined;
34
36
  /**
35
37
  * Open an HTTP connection: read its description, resolve its credential and
36
38
  * hand both to the adapter. `secrets: false` — a URL a browser supplied —
@@ -23,6 +23,11 @@ import { HttpAdapter } from '../adapters/http/httpAdapter.js';
23
23
  import { readDescription } from '../adapters/http/httpDescription.js';
24
24
  import { expandEnvReferences } from './auth/credentials.js';
25
25
  import { product } from './product.js';
26
+ /** `"a", "b" and "c"`. */
27
+ const listed = (words) => {
28
+ const quoted = words.map((word) => JSON.stringify(word));
29
+ return quoted.length < 2 ? quoted.join('') : `${quoted.slice(0, -1).join(', ')} and ${quoted.at(-1)}`;
30
+ };
26
31
  const HTTP_ONLY = ['description', 'auth', 'insecure', 'allowLinkLocal', 'cache'];
27
32
  /* RFC 9110's token, minus the headers the request itself owns. */
28
33
  const HEADER_NAME = /^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/;
@@ -33,9 +38,11 @@ const MAX_CACHE_TTL_SECONDS = 86_400;
33
38
  * An entry's HTTP fields, checked: the resolved block for an `http`
34
39
  * connection, undefined for a database. Throws naming the field, because a
35
40
  * config someone wrote is refused rather than half-read. Service kinds
36
- * (`cache`, `webhook`, …) are read by serviceConnections.ts before this is asked.
41
+ * (`cache`, `webhook`, …) are read by serviceConnections.ts before this is asked;
42
+ * `kinds` are the ones the reader's sections know, so an unknown kind is answered
43
+ * with the list this reader takes rather than one written down once and outgrown.
37
44
  */
38
- export function httpConnectionOf(entry, path) {
45
+ export function httpConnectionOf(entry, path, kinds = ['cache']) {
39
46
  const where = `${path}: connection "${String(entry.name)}"`;
40
47
  if (entry.kind === undefined) {
41
48
  const stray = HTTP_ONLY.find((key) => entry[key] !== undefined);
@@ -48,7 +55,7 @@ export function httpConnectionOf(entry, path) {
48
55
  throw new Error(`${where} has "kind": "search". Search providers are not part of ${product()}: they are packs (Typesense is @mistriwork/search-typesense, SQLite FTS5 is @mistriwork/search-sqlite, Postgres tsvector is @mistriwork/search-postgres), which ship after 1.0. Remove the entry, and a text filter runs on the database.`);
49
56
  }
50
57
  if (entry.kind !== 'http') {
51
- throw new Error(`${where} has "kind": ${JSON.stringify(entry.kind)}. The kinds are "http", "cache" and "webhook"; a database needs none.`);
58
+ throw new Error(`${where} has "kind": ${JSON.stringify(entry.kind)}. The kinds are ${listed(['http', ...[...kinds].sort()])}; a database needs none.`);
52
59
  }
53
60
  // Writes to an API arrive with their own slice; until then a flag saying otherwise would be a promise nothing keeps.
54
61
  if (entry.writable === true)
@@ -16,11 +16,13 @@
16
16
  *
17
17
  * Three things it deliberately does not do.
18
18
  *
19
- * It is **not persisted**. The browser's undo stack makes this argument and it
20
- * is the right one: a stack that outlives the process invites undoing
21
- * something from an hour ago, by which time the row has very likely moved on
22
- * and the "undo" is an overwrite wearing a friendly name. In-session is the
23
- * honest scope.
19
+ * It is **kept in memory unless the database holds its store**. A stack that
20
+ * outlives the process invites undoing something from an hour ago, by which
21
+ * time the row has very likely moved on and the "undo" is an overwrite
22
+ * wearing a friendly name. Where the store is provisioned (journalStore.ts)
23
+ * the history survives a restart all the same, bounded by depth and a week,
24
+ * and the check below is what keeps an old Undo honest; where it is not, the
25
+ * journal is this process's alone, as it always was.
24
26
  *
25
27
  * It **checks before it writes**. Putting the old value back over a newer one
26
28
  * is not an undo, it is a silent overwrite — so the row is re-read first and
@@ -72,6 +74,32 @@ export interface JournalEntry {
72
74
  blocksUndo?: boolean;
73
75
  steps: WriteStep[];
74
76
  }
77
+ /**
78
+ * Where a connection's journal is kept beside memory (journalStore.ts). The
79
+ * calls below stay synchronous: memory is what they answer from, and each
80
+ * change is written behind them, in order, on one chain per connection. A
81
+ * write the store refused is said through `warn` and stays in memory; the
82
+ * revert's check-before-write is what an Undo relies on either way.
83
+ */
84
+ export interface JournalStore {
85
+ /** The entries kept for `connection`, oldest first, after retention has pruned what is past it. */
86
+ load(connection: string): Promise<JournalEntry[]>;
87
+ append(entry: JournalEntry): Promise<void>;
88
+ /** The entry's state changed (an Undo started or became uncertain, a quarantine). */
89
+ update(entry: JournalEntry): Promise<void>;
90
+ remove(connection: string, id: number): Promise<void>;
91
+ }
92
+ /**
93
+ * Keep `connection`'s journal in `store` from now on. The first time, what the
94
+ * store holds becomes the history: an Undo the last process left in progress
95
+ * reads as uncertain, since nothing says whether it landed. Again (a
96
+ * reconnect), the store is swapped and memory, already kept, stays.
97
+ */
98
+ export declare function attachJournalStore(connection: string, store: JournalStore, warn?: (message: string) => void): Promise<void>;
99
+ /** Every change written behind so far, landed or refused: before a reply that reports one, and before a close. */
100
+ export declare function flushJournal(connection?: string): Promise<void>;
101
+ /** Whether `connection`'s journal is kept in its database. */
102
+ export declare function journalKept(connection: string): boolean;
75
103
  /** Record a write that landed. Returns the entry, mostly for tests. */
76
104
  export declare function recordWrite(connection: string, entry: Omit<JournalEntry, 'id' | 'at' | 'connection'>): JournalEntry;
77
105
  /** The most recent first, which is the order anyone asks about them in. */
@@ -81,7 +109,8 @@ export declare function lastRevertible(connection: string): JournalEntry | undef
81
109
  /** Entries are newest first. Never silently step past an unresolved Undo. */
82
110
  export declare function latestRevertible(entries: readonly JournalEntry[]): JournalEntry | undefined;
83
111
  export declare function forget(connection: string, id: number): void;
84
- /** Testing seam: a fresh process is the normal state, and tests want it too. */
112
+ /** Testing seam: a fresh process is the normal state, and tests want it too.
113
+ * What a store keeps is left there, as a process that ended leaves it. */
85
114
  export declare function clearJournal(connection?: string): void;
86
115
  /** Fail closed without publishing another entry (or consulting a clock). The
87
116
  * caller supplies already verified ownership; no record values are introduced. */
@@ -16,11 +16,13 @@
16
16
  *
17
17
  * Three things it deliberately does not do.
18
18
  *
19
- * It is **not persisted**. The browser's undo stack makes this argument and it
20
- * is the right one: a stack that outlives the process invites undoing
21
- * something from an hour ago, by which time the row has very likely moved on
22
- * and the "undo" is an overwrite wearing a friendly name. In-session is the
23
- * honest scope.
19
+ * It is **kept in memory unless the database holds its store**. A stack that
20
+ * outlives the process invites undoing something from an hour ago, by which
21
+ * time the row has very likely moved on and the "undo" is an overwrite
22
+ * wearing a friendly name. Where the store is provisioned (journalStore.ts)
23
+ * the history survives a restart all the same, bounded by depth and a week,
24
+ * and the check below is what keeps an old Undo honest; where it is not, the
25
+ * journal is this process's alone, as it always was.
24
26
  *
25
27
  * It **checks before it writes**. Putting the old value back over a newer one
26
28
  * is not an undo, it is a silent overwrite — so the row is re-read first and
@@ -45,6 +47,60 @@ const entriesFor = (connection) => {
45
47
  journals.set(connection, []);
46
48
  return journals.get(connection);
47
49
  };
50
+ const kept = new Map();
51
+ function persist(connection, work) {
52
+ const at = kept.get(connection);
53
+ if (!at)
54
+ return;
55
+ at.chain = at.chain
56
+ .then(() => work(at.store))
57
+ .catch((error) => at.warn(`"${connection}": the write journal store refused a change: ${error.message}`));
58
+ }
59
+ /**
60
+ * Keep `connection`'s journal in `store` from now on. The first time, what the
61
+ * store holds becomes the history: an Undo the last process left in progress
62
+ * reads as uncertain, since nothing says whether it landed. Again (a
63
+ * reconnect), the store is swapped and memory, already kept, stays.
64
+ */
65
+ export async function attachJournalStore(connection, store, warn = (message) => console.error(message)) {
66
+ const current = kept.get(connection);
67
+ if (current) {
68
+ await current.chain;
69
+ current.store = store;
70
+ current.warn = warn;
71
+ return;
72
+ }
73
+ const loaded = await store.load(connection);
74
+ const ids = new Set(loaded.map((entry) => entry.id));
75
+ const unkept = entriesFor(connection).filter((entry) => !ids.has(entry.id));
76
+ const list = [...loaded, ...unkept].sort((a, b) => a.id - b.id).slice(-DEPTH);
77
+ journals.set(connection, list);
78
+ for (const entry of list)
79
+ nextId = Math.max(nextId, entry.id + 1);
80
+ kept.set(connection, { store, chain: Promise.resolve(), warn });
81
+ for (const entry of loaded) {
82
+ if (entry.undoState !== 'pending')
83
+ continue;
84
+ Object.assign(entry, { undoState: 'unknown', revertible: false, reason: undoUncertain });
85
+ persist(connection, (each) => each.update(entry));
86
+ }
87
+ for (const entry of unkept)
88
+ persist(connection, (each) => each.append(entry));
89
+ await flushJournal(connection);
90
+ }
91
+ /** Every change written behind so far, landed or refused: before a reply that reports one, and before a close. */
92
+ export async function flushJournal(connection) {
93
+ const chains = connection === undefined ? [...kept.values()] : kept.has(connection) ? [kept.get(connection)] : [];
94
+ for (const at of chains) {
95
+ let seen;
96
+ while (seen !== at.chain)
97
+ await (seen = at.chain);
98
+ }
99
+ }
100
+ /** Whether `connection`'s journal is kept in its database. */
101
+ export function journalKept(connection) {
102
+ return kept.has(connection);
103
+ }
48
104
  /** Record a write that landed. Returns the entry, mostly for tests. */
49
105
  export function recordWrite(connection, entry) {
50
106
  const full = {
@@ -57,6 +113,7 @@ export function recordWrite(connection, entry) {
57
113
  list.push(full);
58
114
  if (list.length > DEPTH)
59
115
  list.shift();
116
+ persist(connection, (store) => store.append(full));
60
117
  return full;
61
118
  }
62
119
  /** The most recent first, which is the order anyone asks about them in. */
@@ -82,13 +139,19 @@ export function forget(connection, id) {
82
139
  const at = list.findIndex((e) => e.id === id);
83
140
  if (at !== -1)
84
141
  list.splice(at, 1);
142
+ persist(connection, (store) => store.remove(connection, id));
85
143
  }
86
- /** Testing seam: a fresh process is the normal state, and tests want it too. */
144
+ /** Testing seam: a fresh process is the normal state, and tests want it too.
145
+ * What a store keeps is left there, as a process that ended leaves it. */
87
146
  export function clearJournal(connection) {
88
- if (connection === undefined)
147
+ if (connection === undefined) {
89
148
  journals.clear();
90
- else
149
+ kept.clear();
150
+ }
151
+ else {
91
152
  journals.delete(connection);
153
+ kept.delete(connection);
154
+ }
92
155
  }
93
156
  /** Fail closed without publishing another entry (or consulting a clock). The
94
157
  * caller supplies already verified ownership; no record values are introduced. */
@@ -99,6 +162,7 @@ export function quarantineHistory(connection, owner) {
99
162
  entry.revertible = false;
100
163
  entry.undoState = 'unknown';
101
164
  entry.reason = 'Newer write history could not be confirmed. Refresh and reconcile before further editing.';
165
+ persist(connection, (store) => store.update(entry));
102
166
  }
103
167
  }
104
168
  const keyFilter = (key) => ({
@@ -171,6 +235,9 @@ export async function revert(adapter, connection, entry, errorMessage = (error)
171
235
  return { reverted: false, outcome: 'not_applied', entry, errors: [errorMessage(error)] };
172
236
  }
173
237
  canonical.undoState = 'pending';
238
+ // Kept before the inverse runs: a process that stops mid-Undo leaves it uncertain, never offered again as if untried.
239
+ persist(connection, (store) => store.update(canonical));
240
+ await flushJournal(connection);
174
241
  try {
175
242
  const result = await revertOwned(adapter, connection, owned, errorMessage);
176
243
  if (result.outcome === 'unknown') {
@@ -189,6 +256,10 @@ export async function revert(adapter, connection, entry, errorMessage = (error)
189
256
  finally {
190
257
  if (canonical.undoState === 'pending')
191
258
  delete canonical.undoState;
259
+ // An applied Undo was forgotten (revertOwned); anything else says its state again.
260
+ if (entriesFor(connection).includes(canonical))
261
+ persist(connection, (store) => store.update(canonical));
262
+ await flushJournal(connection);
192
263
  }
193
264
  }
194
265
  const undoUncertain = 'The Undo outcome could not be confirmed. Refresh and reconcile the records; do not retry this Undo.';
@@ -0,0 +1,37 @@
1
+ import { DatabaseSync } from 'node:sqlite';
2
+ import { type Adapter } from '../adapters/adapter.js';
3
+ import type { PgQuery } from '../adapters/postgresPool.js';
4
+ declare const WRITE_JOURNAL_VERSION = 1;
5
+ /** How much is kept: the journal's depth per connection, a week, and an entry of at most 4 MiB. */
6
+ export declare const WRITE_JOURNAL_RETENTION: Readonly<{
7
+ entries: 50;
8
+ days: 7;
9
+ bytes: number;
10
+ }>;
11
+ /** Exactly this version's two tables and their key indexes, nothing else under the prefix, and its version row. */
12
+ export declare function sqliteWriteJournalReady(db: DatabaseSync): boolean;
13
+ /**
14
+ * Explicit maintenance, never run when a connection opens: a file without the
15
+ * store gets this version; the same layout again changes nothing; anything
16
+ * else under the prefix is refused unchanged.
17
+ */
18
+ export declare function provisionSqliteWriteJournal(existingPath: string): {
19
+ version: typeof WRITE_JOURNAL_VERSION;
20
+ provisioned: boolean;
21
+ };
22
+ /** Whether the reserved relations are exactly this version's layout with its version row. */
23
+ export declare function postgresWriteJournalReady(client: PgQuery): Promise<boolean>;
24
+ /** Explicit maintenance, under the shared migration lock: creates this version
25
+ * where no store exists, changes nothing where it does, refuses anything else. */
26
+ export declare function provisionPostgresWriteJournal(url: string): Promise<{
27
+ version: typeof WRITE_JOURNAL_VERSION;
28
+ provisioned: boolean;
29
+ }>;
30
+ /**
31
+ * Keep `connection`'s journal in its database when the database holds the
32
+ * store: what it held is read back, and every write from here on is kept
33
+ * there too. Never fatal: a store that is missing or cannot be read leaves the
34
+ * journal in memory, said through `warn` (the caller says it once). Resolves to whether the store is now used.
35
+ */
36
+ export declare function keepWriteJournal(connection: string, adapter: Adapter, warn?: (message: string) => void): Promise<boolean>;
37
+ export {};