@mistriwork/engine 1.0.0-rc.75 → 1.0.0-rc.78

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 (54) hide show
  1. package/dist/adapters/adapter.d.ts +6 -0
  2. package/dist/adapters/postgres.js +13 -7
  3. package/dist/adapters/postgresPool.d.ts +28 -0
  4. package/dist/adapters/postgresPool.js +36 -3
  5. package/dist/adapters/scoped/scopedReads.js +5 -1
  6. package/dist/adapters/scoped/scopedTransaction.js +3 -1
  7. package/dist/adapters/serverSettings.d.ts +2 -0
  8. package/dist/adapters/sqlite.js +7 -5
  9. package/dist/server/cli/args.d.ts +2 -1
  10. package/dist/server/cli/args.js +13 -2
  11. package/dist/server/columnGrants.d.ts +3 -0
  12. package/dist/server/columnGrants.js +29 -4
  13. package/dist/server/connections.d.ts +1 -1
  14. package/dist/server/connections.js +2 -0
  15. package/dist/server/http/probes.d.ts +10 -1
  16. package/dist/server/http/probes.js +6 -2
  17. package/dist/server/http/recordWrites.js +7 -1
  18. package/dist/server/http/refusalReport.js +7 -1
  19. package/dist/server/http/serverCore.d.ts +2 -1
  20. package/dist/server/migrate/cli.js +7 -0
  21. package/dist/server/poolConfig.d.ts +4 -0
  22. package/dist/server/poolConfig.js +20 -7
  23. package/dist/server/resourceReadHttp.js +7 -2
  24. package/dist/server/resourceReadOperations.js +5 -1
  25. package/dist/shared/aggregate.js +7 -1
  26. package/dist/shared/appComponents.js +1 -1
  27. package/dist/shared/autoBucket.d.ts +29 -5
  28. package/dist/shared/autoBucket.js +49 -14
  29. package/dist/shared/computedParse.d.ts +2 -0
  30. package/dist/shared/computedParse.js +1 -1
  31. package/dist/shared/computedWhere.d.ts +47 -0
  32. package/dist/shared/computedWhere.js +159 -0
  33. package/dist/shared/filter.d.ts +5 -0
  34. package/dist/shared/filter.js +4 -0
  35. package/dist/shared/query.js +20 -22
  36. package/dist/shared/queryDates.d.ts +16 -0
  37. package/dist/shared/queryDates.js +29 -0
  38. package/dist/shared/queryOperands.d.ts +24 -0
  39. package/dist/shared/queryOperands.js +36 -0
  40. package/dist/shared/refusal.d.ts +8 -0
  41. package/dist/shared/refusal.js +15 -0
  42. package/dist/shared/resourceHttp.d.ts +1 -1
  43. package/dist/shared/rowCondition.d.ts +5 -0
  44. package/dist/shared/rowCondition.js +80 -0
  45. package/dist/shared/schema.d.ts +10 -0
  46. package/dist/shared/schema.js +8 -0
  47. package/dist/shared/scopeCatalog.d.ts +1 -1
  48. package/dist/shared/scopeCatalog.js +13 -1
  49. package/dist/shared/servedApp.d.ts +19 -0
  50. package/dist/shared/structuredFilter.d.ts +3 -0
  51. package/dist/shared/viewLabels.d.ts +6 -1
  52. package/dist/shared/viewLabels.js +1 -1
  53. package/package.json +2 -1
  54. package/schema/model.d.ts +12 -3
@@ -1,13 +1,15 @@
1
1
  /**
2
2
  * A connection's `"pool"` and `"replicas"` in tablewalk.json, checked where the file is read:
3
- * `{ "read": n, "write": m }`, each a whole number from 1 to 64 and either
4
- * one optional, on a PostgreSQL connection. Apart from the loader because
3
+ * `{ "read": n, "write": m, "idleSeconds": s, "minIdle": k }`: the sizes each a
4
+ * whole number from 1 to 64, the idle window whole seconds from 1 to a day, the
5
+ * warm count 0 to 64, every one optional, on a PostgreSQL connection. Apart from the loader because
5
6
  * the rule is the pool's (postgresPool.ts holds the bounds); the loader only
6
7
  * asks it, as it asks httpConnection.ts about an API's fields.
7
8
  */
8
- import { isReaderCount, MAX_READERS } from '../adapters/postgresPool.js';
9
+ import { isIdleSeconds, isMinIdle, isReaderCount, MAX_IDLE_SECONDS, MAX_READERS } from '../adapters/postgresPool.js';
9
10
  import { isWriterCount, MAX_WRITERS } from '../adapters/writeLanes.js';
10
11
  import { MAX_REPLICAS } from '../adapters/replicas.js';
12
+ const POOL_KEYS = ['read', 'write', 'idleSeconds', 'minIdle'];
11
13
  /**
12
14
  * Refused rather than clamped or ignored, as `writable` is: a number quietly
13
15
  * overridden is a capacity plan that is not the one in the file. An HTTP
@@ -28,12 +30,18 @@ export function poolOf(entry, http, path) {
28
30
  throw new Error(`${where} has "pool": ${JSON.stringify(written)}. It must be an object such as { "read": 16, "write": 8 }.`);
29
31
  }
30
32
  const pool = written;
31
- const stray = Object.keys(pool).find((key) => key !== 'read' && key !== 'write');
33
+ const stray = Object.keys(pool).find((key) => !POOL_KEYS.includes(key));
32
34
  if (stray !== undefined)
33
- throw new Error(`${where} has "pool.${stray}". A pool takes "read" and "write".`);
34
- if (pool.read === undefined && pool.write === undefined) {
35
+ throw new Error(`${where} has "pool.${stray}". A pool takes "read", "write", "idleSeconds" and "minIdle".`);
36
+ if (!POOL_KEYS.some((key) => pool[key] !== undefined)) {
35
37
  throw new Error(`${where} has an empty "pool". Say how many connections may read or write at once, such as { "read": 16, "write": 8 }.`);
36
38
  }
39
+ if (pool.idleSeconds !== undefined && !isIdleSeconds(pool.idleSeconds)) {
40
+ throw new Error(`${where} has "pool": { "idleSeconds": ${JSON.stringify(pool.idleSeconds)} }. It must be whole seconds from 1 to ${MAX_IDLE_SECONDS}, without quotes.`);
41
+ }
42
+ if (pool.minIdle !== undefined && !isMinIdle(pool.minIdle)) {
43
+ throw new Error(`${where} has "pool": { "minIdle": ${JSON.stringify(pool.minIdle)} }. It must be a whole number from 0 to ${MAX_READERS}, without quotes.`);
44
+ }
37
45
  if (pool.read !== undefined && !isReaderCount(pool.read)) {
38
46
  throw new Error(`${where} has "pool": { "read": ${JSON.stringify(pool.read)} }. It must be a whole number from 1 to ${MAX_READERS}, without quotes.`);
39
47
  }
@@ -45,7 +53,12 @@ export function poolOf(entry, http, path) {
45
53
  if (!/^postgres(ql)?:\/\//i.test(url))
46
54
  throw new Error(`${where} is not a PostgreSQL connection; SQLite has no pool. Remove "pool".`);
47
55
  }
48
- return { ...(pool.read !== undefined ? { read: pool.read } : {}), ...(pool.write !== undefined ? { write: pool.write } : {}) };
56
+ return {
57
+ ...(pool.read !== undefined ? { read: pool.read } : {}),
58
+ ...(pool.write !== undefined ? { write: pool.write } : {}),
59
+ ...(pool.idleSeconds !== undefined ? { idleSeconds: pool.idleSeconds } : {}),
60
+ ...(pool.minIdle !== undefined ? { minIdle: pool.minIdle } : {}),
61
+ };
49
62
  }
50
63
  /**
51
64
  * A connection's `"replicas"`: `["postgres://…", "${REPLICA_URL}", …]`, read
@@ -353,14 +353,19 @@ export async function dispatchResourceReadHttp(path, body, adapter, schema, opti
353
353
  }
354
354
  const results = Array.from({ length: items.length });
355
355
  const queue = items.map((item, at) => ({ item, at }));
356
+ /* An item's route knows its own last wave, not the batch's: the others are
357
+ still queued, or between their reads, when it says so, and a tenant App's
358
+ fence that left with it refuses every read after (TenantReadContext.lastWave).
359
+ Only a batch of one is that route alone. */
360
+ const each = items.length === 1 ? options : { ...options, lastWave: undefined };
356
361
  const one = async () => {
357
362
  for (let next = queue.shift(); next; next = queue.shift()) {
358
363
  const page = run(next.item);
359
364
  const { def, text, limit, offset } = next.item;
360
365
  try {
361
366
  results[next.at] = (await (page
362
- ? dispatchResourceReadHttp('/api/run', Object.fromEntries(RUN_FIELDS.filter((field) => page[field] !== undefined).map((field) => [field, page[field]])), adapter, schema, options)
363
- : dispatchResourceReadHttp('/api/breakdown', { def, text, limit, offset }, adapter, schema, options)));
367
+ ? dispatchResourceReadHttp('/api/run', Object.fromEntries(RUN_FIELDS.filter((field) => page[field] !== undefined).map((field) => [field, page[field]])), adapter, schema, each)
368
+ : dispatchResourceReadHttp('/api/breakdown', { def, text, limit, offset }, adapter, schema, each)));
364
369
  }
365
370
  catch (error) {
366
371
  /* A request's own refusal (a ResourceReadError: the provider's are
@@ -91,7 +91,11 @@ export function assertStructuredReadFilter(filter, field) {
91
91
  if (typeof filter !== 'object' || Array.isArray(filter))
92
92
  fail();
93
93
  const given = filter;
94
- if (Object.keys(given).some((key) => key !== 'groups') || !Array.isArray(given.groups))
94
+ /* A column filter may carry the computed columns its conditions name (Filter.computed): its shape is checked here,
95
+ each expression where it is written (computedWhere.ts checkedComputed), never on the strength of this check. */
96
+ const computed = given.computed;
97
+ const carriesComputed = field === 'column' && computed !== undefined && computed !== null && typeof computed === 'object' && !Array.isArray(computed);
98
+ if (Object.keys(given).some((key) => key !== 'groups' && !(key === 'computed' && carriesComputed)) || !Array.isArray(given.groups))
95
99
  fail();
96
100
  const scalar = (value) => value === null || typeof value === 'string' || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value));
97
101
  for (const group of given.groups) {
@@ -1,4 +1,5 @@
1
1
  import { compileBreakdown, DATE_UNITS } from './breakdown.js';
2
+ import { checkedComputed } from './computedWhere.js';
2
3
  import { RequestFault } from './refusal.js';
3
4
  import { findTable } from './schema.js';
4
5
  import { PathError } from './viewPaths.js';
@@ -60,13 +61,17 @@ function aggregateBreakdown(schema, request) {
60
61
  ...(measure.column === undefined ? {} : { path: column(measure.column, 'measure') }),
61
62
  };
62
63
  });
64
+ /* A computed column its where names is written as its expression over the table's own columns, as a view writes
65
+ one (ViewDef.expressions); checked first, as a single-table read's is (computedWhere.ts). Keys and measures
66
+ stay the table's own columns. */
67
+ const computed = request.filter ? checkedComputed(request.filter, table) : new Map();
63
68
  const groups = (request.filter?.groups ?? []).map((group) => group.map((condition) => {
64
69
  /* A comparison with another column, rows that point here (`any`), or another table's rows (`within`), reads past this table's own values:
65
70
  neither is a condition a command's where writes (compileWhere), and neither is taken here. */
66
71
  if (condition.any !== undefined || condition.other !== undefined || condition.within !== undefined)
67
72
  throw new RequestFault("An aggregate's where compares the table's own columns with values.");
68
73
  return {
69
- path: column(condition.column, 'where'),
74
+ path: computed.has(condition.column) ? condition.column : column(condition.column, 'where'),
70
75
  op: condition.op,
71
76
  ...(condition.value === undefined ? {} : { value: condition.value }),
72
77
  ...(condition.collation ? { collation: condition.collation } : {}),
@@ -86,6 +91,7 @@ function aggregateBreakdown(schema, request) {
86
91
  ...(dates.length ? { dateColumns: dates } : {}),
87
92
  measures,
88
93
  ...(groups.length ? { filter: { groups } } : {}),
94
+ ...(computed.size ? { expressions: Object.fromEntries([...computed].map(([name, def]) => [name, { ...def, on: '' }])) } : {}),
89
95
  ...(orderBy.length ? { orderBy } : {}),
90
96
  limit: request.limit,
91
97
  };
@@ -428,7 +428,7 @@ export function parsePage(raw, at) {
428
428
  params.length > MAX_PAGE_PARAMS ||
429
429
  params.some((name) => typeof name !== 'string' || !PARAM.test(name)) ||
430
430
  params.includes('period')) {
431
- throw new Error(`[page-params] ${at} has "params" that are not up to ${MAX_PAGE_PARAMS} lowercase words, each 'id', 'text', 'date', 'date-range' or a list of its values, like params: { list: 'id' }; "period" is a dashboard's.`);
431
+ throw new Error(`[page-params] ${at} has "params" that are not up to ${MAX_PAGE_PARAMS} lowercase words, each 'id', 'text', 'date', 'date-range' or a list of its values, like params: { list: 'id' }; "period" is a dashboard's address word, so a page's own window is named "window": params: { window: ['last-30-days', 'last-90-days'] }, read by a windowed <Metric window="window" over="close_date" previous spark />.`);
432
432
  }
433
433
  if (raw.loader !== undefined && (typeof raw.loader !== 'string' || !LOADER.test(raw.loader))) {
434
434
  throw new Error(`[page-loader] ${at} has a "loader" that is not a loader's name, as the commands module's defineLoaders() registers it.`);
@@ -25,12 +25,36 @@ export declare function unitForSpan(days: number): AutoUnit;
25
25
  export declare function readUnit(base: AutoUnit, addsUp: boolean): AutoUnit;
26
26
  /** The label of the period a day, month or quarter label falls in, spelled as the server spells it. */
27
27
  export declare function bucketKey(key: string, unit: AutoUnit, weekStart?: number): string;
28
+ interface FillOptions {
29
+ /** The unit the rows are keyed in: their keys are spelled as the server spells it (`2026-03-14`, `2026-03`, `2026-Q1`). */
30
+ unit: AutoUnit;
31
+ /** The first instant to fill from, its period included; absent, the first row's. */
32
+ from?: Date;
33
+ /** The last instant to fill to, its period included; absent, the last row's. */
34
+ to?: Date;
35
+ /** The zone `from` and `to` are read in, the App's: absent, their local fields. */
36
+ timeZone?: string;
37
+ /** The field a row's period is under: `key`, or the server's name for it (`day(created_at)`). */
38
+ key?: string;
39
+ /** The fields a filled period holds as 0: absent, the first row's numeric ones, else `value`. */
40
+ zero?: readonly string[];
41
+ weekStart?: number;
42
+ }
43
+ /**
44
+ * Rows keyed by period with the periods that held no rows put back as zero, marked `filled: true`, from `from`'s
45
+ * period to `to`'s (or the rows' own first and last), in order. A count of nothing is 0: a line drawn through only
46
+ * the days that had rows said a quiet week was a steady one. The periods are the App's calendar's (`timeZone`), so a
47
+ * moment near midnight falls on the day the people using the App say it did. Rows whose keys the unit does not spell
48
+ * come back as they came; only a count or a sum is honestly filled with 0, which the caller decides.
49
+ */
50
+ export declare function fillBuckets<R extends Record<string, unknown>>(rows: readonly R[], { unit, from, to, timeZone, key, zero, weekStart }: FillOptions): Array<R | (Record<string, unknown> & {
51
+ filled: true;
52
+ })>;
28
53
  /**
29
- * A trend's points over its window: the periods that held no rows put back as zero, from the window's first period
30
- * to today's, and the read periods added up into the unit the span is drawn in. A count of nothing is 0, and a line
31
- * drawn through only the days that had rows said a quiet week was a steady one; three busy days of a week drew no
32
- * line at all. Only a count or a sum adds up so: any other measure's points are drawn as read, and labels the read
33
- * unit does not spell are left as they came.
54
+ * A trend's points over its window: the periods that held no rows put back as zero (`fillBuckets`), from the window's
55
+ * first period to today's, and the read periods added up into the unit the span is drawn in. Three busy days of a
56
+ * week drew no line at all before. Only a count or a sum adds up so: any other measure's points are drawn as read,
57
+ * and labels the read unit does not spell are left as they came.
34
58
  */
35
59
  export declare function trendPoints<R extends {
36
60
  key: unknown;
@@ -131,28 +131,63 @@ const SPELLED = {
131
131
  };
132
132
  /** The local calendar day of a date, as the server spells a day. */
133
133
  const localDay = (d) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
134
+ /** The calendar day an instant falls on in a zone, as the server spells a day; with no zone, its local fields (the wall
135
+ clock `dateWindow` computes a zoned window in, `zonedNow`). */
136
+ function dayIn(d, timeZone) {
137
+ if (!timeZone)
138
+ return localDay(d);
139
+ const parts = new Intl.DateTimeFormat('en-US', { timeZone, year: 'numeric', month: '2-digit', day: '2-digit' }).formatToParts(d);
140
+ const get = (type) => parts.find((p) => p.type === type)?.value ?? '';
141
+ return `${get('year')}-${get('month')}-${get('day')}`;
142
+ }
143
+ /** The label of the period an instant falls in, in a zone. */
144
+ const periodOf = (d, unit, timeZone, weekStart) => bucketKey(dayIn(d, timeZone), unit, weekStart);
134
145
  /**
135
- * A trend's points over its window: the periods that held no rows put back as zero, from the window's first period
136
- * to today's, and the read periods added up into the unit the span is drawn in. A count of nothing is 0, and a line
137
- * drawn through only the days that had rows said a quiet week was a steady one; three busy days of a week drew no
138
- * line at all. Only a count or a sum adds up so: any other measure's points are drawn as read, and labels the read
139
- * unit does not spell are left as they came.
146
+ * Rows keyed by period with the periods that held no rows put back as zero, marked `filled: true`, from `from`'s
147
+ * period to `to`'s (or the rows' own first and last), in order. A count of nothing is 0: a line drawn through only
148
+ * the days that had rows said a quiet week was a steady one. The periods are the App's calendar's (`timeZone`), so a
149
+ * moment near midnight falls on the day the people using the App say it did. Rows whose keys the unit does not spell
150
+ * come back as they came; only a count or a sum is honestly filled with 0, which the caller decides.
151
+ */
152
+ export function fillBuckets(rows, { unit, from, to, timeZone, key = 'key', zero, weekStart = 1 }) {
153
+ const keys = rows.map((row) => String(row[key] ?? ''));
154
+ if (keys.some((k) => !SPELLED[unit].test(k)))
155
+ return [...rows];
156
+ const ends = [from, to].flatMap((d) => (d ? [periodOf(d, unit, timeZone, weekStart)] : []));
157
+ const sorted = [...keys, ...ends].sort();
158
+ if (!sorted.length)
159
+ return [...rows];
160
+ const numeric = rows.length ? Object.keys(rows[0]).filter((field) => field !== key && typeof rows[0][field] === 'number') : [];
161
+ const zeros = Object.fromEntries((zero ?? (numeric.length ? numeric : ['value'])).map((field) => [field, 0]));
162
+ const held = new Map(rows.map((row, i) => [keys[i], row]));
163
+ const out = [];
164
+ for (let at = sorted[0], n = 0; at <= sorted[sorted.length - 1] && n < 5000; at = nextKey(at, unit), n++)
165
+ /* The period first, as the server writes a row: the hook reads a row's measure as the column after its groups. */
166
+ out.push(held.get(at) ?? { [key]: at, ...zeros, filled: true });
167
+ return out;
168
+ }
169
+ /**
170
+ * A trend's points over its window: the periods that held no rows put back as zero (`fillBuckets`), from the window's
171
+ * first period to today's, and the read periods added up into the unit the span is drawn in. Three busy days of a
172
+ * week drew no line at all before. Only a count or a sum adds up so: any other measure's points are drawn as read,
173
+ * and labels the read unit does not spell are left as they came.
140
174
  */
141
175
  export function trendPoints(rows, read, unit, measure, window, now) {
142
176
  if (!/^(count|sum\s+[\w.$+]+)(\s+as\s+[\w$]+)?$/i.test((measure ?? 'count').trim()))
143
177
  return [...rows];
144
- const keys = rows.map((row) => String(row.key ?? ''));
145
- if (keys.some((key) => !SPELLED[read].test(key)))
178
+ const keyed = rows.map((row) => ({ key: String(row.key ?? ''), value: Number(row.value) || 0 }));
179
+ if (keyed.some((row) => !SPELLED[read].test(row.key)))
146
180
  return [...rows];
147
- const ends = window ? [window.start, new Date(Math.min(window.end.getTime() - 1, now.getTime()))] : [];
148
- const sorted = [...keys, ...ends.map((d) => bucketKey(localDay(d), read))].sort();
149
- if (!sorted.length)
181
+ if (!keyed.length && !window)
150
182
  return [...rows];
151
- const held = new Map(rows.map((row) => [String(row.key), Number(row.value) || 0]));
183
+ const filled = fillBuckets(keyed, {
184
+ unit: read,
185
+ ...(window ? { from: window.start, to: new Date(Math.min(window.end.getTime() - 1, now.getTime())) } : {}),
186
+ });
152
187
  const into = new Map();
153
- for (let key = sorted[0], n = 0; key <= sorted[sorted.length - 1] && n < 5000; key = nextKey(key, read), n++) {
154
- const label = bucketKey(key, unit);
155
- into.set(label, (into.get(label) ?? 0) + (held.get(key) ?? 0));
188
+ for (const row of filled) {
189
+ const label = bucketKey(String(row.key), unit);
190
+ into.set(label, (into.get(label) ?? 0) + (Number(row.value) || 0));
156
191
  }
157
192
  return [...into].map(([key, value]) => ({ key, value }));
158
193
  }
@@ -5,6 +5,8 @@
5
5
  * the first page reaches is drawn into the first page's chunk, so the parser lived there for a form's live lines.
6
6
  */
7
7
  import { type ComputedNode } from './computed.js';
8
+ /** The functions an expression may call: each written alike on every engine and worked out alike in JavaScript. */
9
+ export declare const COMPUTED_FUNCTIONS: readonly ["coalesce", "round", "min", "max", "abs", "concat"];
8
10
  /**
9
11
  * An expression's tree, or why it is not one. `isColumn` says which bare
10
12
  * words are names: a word on the right of `=` or `!=` that is not one is a
@@ -6,7 +6,7 @@
6
6
  */
7
7
  import { ComputedError } from './computed.js';
8
8
  /** The functions an expression may call: each written alike on every engine and worked out alike in JavaScript. */
9
- const COMPUTED_FUNCTIONS = ['coalesce', 'round', 'min', 'max', 'abs', 'concat'];
9
+ export const COMPUTED_FUNCTIONS = ['coalesce', 'round', 'min', 'max', 'abs', 'concat'];
10
10
  const isFunction = (word) => COMPUTED_FUNCTIONS.includes(word);
11
11
  /* The greatest number of places `round` keeps: past it a figure is no longer one an engine says exactly. */
12
12
  const ROUND_PLACES = 10;
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Computed columns in a single-table read's filter: `db.tasks.where('is_overdue')` in a handler or a loader.
3
+ *
4
+ * A computed column is no column of the table (computed.ts), so a read that names one carries its expression on the
5
+ * filter (`Filter.computed`), and the adapter writes that expression where a condition names it, with the same
6
+ * compiler a view uses (`compileComputed`). The expression is what the reader's catalog served, its constants folded:
7
+ * the caller resolved it, never the person asking. It is still checked here, node by node, before a word of it reaches
8
+ * a statement, because `compileComputed` writes a function's name, an operator, a unit and a JSON key as text: anything
9
+ * the parser would never have produced is refused, and so is a read of anything but one of the table's own columns.
10
+ * What it reads is worked out from the expression (`computedReads`), never taken from the request, so a grant check
11
+ * of those reads (columnGrants.ts) is a check of what the statement reads.
12
+ */
13
+ import { type ComputedNode, type ComputedType } from './computed.js';
14
+ import { type Condition, type Filter, type SqlStyle } from './filter.js';
15
+ import { type DatabaseSchema, type TableMeta } from './schema.js';
16
+ /** The computed columns a filter's conditions may name, by name: each one's type and its expression, constants folded. */
17
+ export type FilterComputed = Readonly<Record<string, {
18
+ readonly type: ComputedType;
19
+ readonly expr: ComputedNode;
20
+ }>>;
21
+ /** Whether a filter carries computed columns, so the adapter needs the table's columns to write them. */
22
+ export declare const asksComputed: (filter: Filter | undefined) => boolean;
23
+ /** Whether a single-table read's filter needs the catalog: it asks about other rows, or names a computed column. */
24
+ export declare const readsCatalog: (filter: Filter | undefined) => boolean;
25
+ /** The table a computed column is written over; a catalog that cannot say it refuses the read, never drops the condition. */
26
+ export declare function computedTable(schema: DatabaseSchema | undefined, id: string): TableMeta;
27
+ /**
28
+ * The filter's computed columns, each checked against the table: a name that is no column of it, a type, and an
29
+ * expression of the parser's own shapes reading only the table's stored columns. Its constants are folded already:
30
+ * `today`, `now` and `me` are the request's, said by whoever resolved the column, so an unfolded one is refused.
31
+ */
32
+ export declare function checkedComputed(filter: Filter, table: TableMeta): Map<string, {
33
+ type: ComputedType;
34
+ expr: ComputedNode;
35
+ reads: string[];
36
+ }>;
37
+ /**
38
+ * The filter as buildWhere takes it, with its computed columns written where a condition names one: the filter
39
+ * without them, a column resolver that writes the expression in place of the name, and a types reader that says
40
+ * nothing of a computed name (it has no catalog type, so it compares by the operator as written). `column` is how
41
+ * the read writes its own columns; the expression's reads are written through it too.
42
+ */
43
+ export declare function withComputedWhere(filter: Filter, table: TableMeta, style: SqlStyle, column?: (name: string, condition?: Condition) => string, types?: (name: string) => string | undefined): {
44
+ filter: Filter;
45
+ column: (name: string, condition?: Condition) => string;
46
+ types?: (name: string) => string | undefined;
47
+ };
@@ -0,0 +1,159 @@
1
+ /**
2
+ * Computed columns in a single-table read's filter: `db.tasks.where('is_overdue')` in a handler or a loader.
3
+ *
4
+ * A computed column is no column of the table (computed.ts), so a read that names one carries its expression on the
5
+ * filter (`Filter.computed`), and the adapter writes that expression where a condition names it, with the same
6
+ * compiler a view uses (`compileComputed`). The expression is what the reader's catalog served, its constants folded:
7
+ * the caller resolved it, never the person asking. It is still checked here, node by node, before a word of it reaches
8
+ * a statement, because `compileComputed` writes a function's name, an operator, a unit and a JSON key as text: anything
9
+ * the parser would never have produced is refused, and so is a read of anything but one of the table's own columns.
10
+ * What it reads is worked out from the expression (`computedReads`), never taken from the request, so a grant check
11
+ * of those reads (columnGrants.ts) is a check of what the statement reads.
12
+ */
13
+ import { COMPUTED_TYPES, compileComputed, computedKind, computedReads } from './computed.js';
14
+ import { COMPUTED_FUNCTIONS } from './computedParse.js';
15
+ import { asksAboutRows } from './filter.js';
16
+ import { RequestFault } from './refusal.js';
17
+ import { findTable } from './schema.js';
18
+ import { columnRead } from './viewLabels.js';
19
+ const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
20
+ const OPS = new Set(['+', '-', '*', '/', '=', '!=', '<', '<=', '>', '>=', 'and', 'or']);
21
+ const UNITS = new Set(['minute', 'hour', 'day', 'week', 'month', 'year']);
22
+ const FUNCTIONS = new Set(COMPUTED_FUNCTIONS);
23
+ const DAY = /^\d{4}-\d{2}-\d{2}$/;
24
+ const INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?Z$/;
25
+ const refuse = (detail) => {
26
+ throw new RequestFault(`This read cannot use that computed column: ${detail}.`);
27
+ };
28
+ /** Whether a filter carries computed columns, so the adapter needs the table's columns to write them. */
29
+ export const asksComputed = (filter) => filter?.computed !== undefined &&
30
+ filter.computed !== null &&
31
+ typeof filter.computed === 'object' &&
32
+ Object.keys(filter.computed).length > 0;
33
+ /** Whether a single-table read's filter needs the catalog: it asks about other rows, or names a computed column. */
34
+ export const readsCatalog = (filter) => asksAboutRows(filter) || asksComputed(filter);
35
+ /** The table a computed column is written over; a catalog that cannot say it refuses the read, never drops the condition. */
36
+ export function computedTable(schema, id) {
37
+ const table = schema && findTable(schema, id);
38
+ if (!table)
39
+ throw new RequestFault('This read cannot use a computed column.');
40
+ return table;
41
+ }
42
+ /**
43
+ * The filter's computed columns, each checked against the table: a name that is no column of it, a type, and an
44
+ * expression of the parser's own shapes reading only the table's stored columns. Its constants are folded already:
45
+ * `today`, `now` and `me` are the request's, said by whoever resolved the column, so an unfolded one is refused.
46
+ */
47
+ export function checkedComputed(filter, table) {
48
+ const out = new Map();
49
+ const given = filter.computed;
50
+ if (given === undefined)
51
+ return out;
52
+ if (given === null || typeof given !== 'object' || Array.isArray(given))
53
+ refuse('not a map of columns');
54
+ const stored = new Set(table.columns.map((column) => column.name));
55
+ for (const [name, def] of Object.entries(given)) {
56
+ if (!IDENTIFIER.test(name) || stored.has(name))
57
+ refuse(`"${name}" is a column of ${table.name} or no name`);
58
+ if (def === null || typeof def !== 'object')
59
+ refuse(`"${name}" has no definition`);
60
+ if (!COMPUTED_TYPES.includes(def.type))
61
+ refuse(`"${name}" has no type`);
62
+ let size = 0;
63
+ const node = (n) => {
64
+ if (++size > 500)
65
+ refuse(`"${name}" is too large`);
66
+ if (n === null || typeof n !== 'object')
67
+ refuse(`"${name}" is not an expression`);
68
+ const at = n;
69
+ switch (at.k) {
70
+ case 'path':
71
+ if (typeof at.path !== 'string' || !stored.has(at.path))
72
+ refuse(`"${name}" reads what is not a column of ${table.name}`);
73
+ return;
74
+ case 'json':
75
+ if (typeof at.column !== 'string' || !stored.has(at.column))
76
+ refuse(`"${name}" reads what is not a column of ${table.name}`);
77
+ if (!Array.isArray(at.keys) || !at.keys.length || !at.keys.every((key) => typeof key === 'string' && IDENTIFIER.test(key)))
78
+ refuse(`"${name}" names a member that is no identifier`);
79
+ return;
80
+ case 'number':
81
+ if (typeof at.value !== 'number' || !Number.isFinite(at.value))
82
+ refuse(`"${name}" has a figure that is no number`);
83
+ return;
84
+ case 'text':
85
+ if (typeof at.value !== 'string')
86
+ refuse(`"${name}" has text that is no text`);
87
+ return;
88
+ case 'bool':
89
+ if (typeof at.value !== 'boolean')
90
+ refuse(`"${name}" has a yes-or-no that is neither`);
91
+ return;
92
+ case 'date':
93
+ if (typeof at.value !== 'string' || !DAY.test(at.value))
94
+ refuse(`"${name}" has a day that is no day`);
95
+ return;
96
+ case 'instant':
97
+ if (typeof at.value !== 'string' || !INSTANT.test(at.value))
98
+ refuse(`"${name}" has an instant that is no instant`);
99
+ return;
100
+ case 'nobody':
101
+ return;
102
+ case 'not':
103
+ case 'neg':
104
+ return node(at.of);
105
+ case 'empty':
106
+ if (typeof at.negate !== 'boolean')
107
+ refuse(`"${name}" is not an expression`);
108
+ return node(at.of);
109
+ case 'span':
110
+ if (typeof at.unit !== 'string' || !UNITS.has(at.unit))
111
+ refuse(`"${name}" moves by no unit`);
112
+ return node(at.of);
113
+ case 'call':
114
+ if (typeof at.fn !== 'string' || !FUNCTIONS.has(at.fn))
115
+ refuse(`"${name}" calls no function an expression knows`);
116
+ if (!Array.isArray(at.args) || !at.args.length)
117
+ refuse(`"${name}" calls a function with nothing`);
118
+ return at.args.forEach(node);
119
+ case 'op':
120
+ if (typeof at.op !== 'string' || !OPS.has(at.op))
121
+ refuse(`"${name}" has no operator an expression knows`);
122
+ node(at.left);
123
+ return node(at.right);
124
+ /* `today`, `now` and `me` are this request's: folded by whoever resolved the column, never left for the statement. */
125
+ default:
126
+ refuse(`"${name}" is not an expression with its constants said`);
127
+ }
128
+ };
129
+ node(def.expr);
130
+ const kindOf = (path) => columnRead(table.columns.find((column) => column.name === path))?.kind;
131
+ try {
132
+ computedKind(def.expr, kindOf);
133
+ }
134
+ catch {
135
+ refuse(`"${name}" does not type`);
136
+ }
137
+ out.set(name, { type: def.type, expr: def.expr, reads: computedReads(def.expr) });
138
+ }
139
+ return out;
140
+ }
141
+ /**
142
+ * The filter as buildWhere takes it, with its computed columns written where a condition names one: the filter
143
+ * without them, a column resolver that writes the expression in place of the name, and a types reader that says
144
+ * nothing of a computed name (it has no catalog type, so it compares by the operator as written). `column` is how
145
+ * the read writes its own columns; the expression's reads are written through it too.
146
+ */
147
+ export function withComputedWhere(filter, table, style, column = (name) => style.quote(name), types) {
148
+ const computed = checkedComputed(filter, table);
149
+ const { computed: _carried, ...rest } = filter;
150
+ if (!computed.size)
151
+ return { filter: rest, column, types };
152
+ const kindOf = (path) => columnRead(table.columns.find((c) => c.name === path));
153
+ const written = new Map([...computed].map(([name, def]) => [name, `(${compileComputed(def, style, (path) => column(path), kindOf)})`]));
154
+ return {
155
+ filter: rest,
156
+ column: (name, condition) => written.get(name) ?? column(name, condition),
157
+ types: types && ((name) => (written.has(name) ? undefined : types(name))),
158
+ };
159
+ }
@@ -1,3 +1,4 @@
1
+ import type { FilterComputed } from './computedWhere.js';
1
2
  /** One condition in a filter. Values are bound, never interpolated. */
2
3
  export interface Condition {
3
4
  column: string;
@@ -161,6 +162,10 @@ export declare const OPS: ReadonlySet<string>;
161
162
  */
162
163
  export interface Filter {
163
164
  groups: Condition[][];
165
+ /** The computed columns its conditions name, each its type and expression with the request's constants folded
166
+ (computedWhere.ts): a handler's or a loader's own read only, resolved from the reader's catalog by the server.
167
+ An adapter writes them through `withComputedWhere`; anywhere else one is refused, never dropped. */
168
+ computed?: FilterComputed;
164
169
  }
165
170
  export interface SqlFragment {
166
171
  text: string;
@@ -248,6 +248,10 @@ via = false,
248
248
  inline,
249
249
  /** How a `within` condition's subquery is read (`Condition.within`): its relation, scoped where the read is. Absent, one is refused. */
250
250
  within) {
251
+ /* Before anything: a computed column read where nobody wrote its expression would be a column by that name, or no
252
+ condition at all if the groups were empty. Refused, never dropped. */
253
+ if (filter?.computed !== undefined)
254
+ throw new RequestFault('This read cannot use a computed column.');
251
255
  if (!filter?.groups.length)
252
256
  return { text: '', params: [] };
253
257
  const params = [];
@@ -2,9 +2,9 @@ import { MAX_LIMIT } from './reads.js';
2
2
  import { LIKE_ESCAPE, likePattern } from './like.js';
3
3
  import { distance, nearest } from './suggest.js';
4
4
  import { columnKind, findTable } from './schema.js';
5
- import { dateWindow } from './queryDates.js';
5
+ import { bindDate, dateWindow } from './queryDates.js';
6
6
  import { maskQuoted } from './maskQuoted.js';
7
- import { ME_SET, TENANT_FIELD, columnOperand, meOperand, meSetOperand, tenantHolds, tenantOperand, } from './queryOperands.js';
7
+ import { ME_SET, TENANT_FIELD, chosenOperand, columnOperand, meOperand, meSetOperand, tenantHolds, tenantOperand, } from './queryOperands.js';
8
8
  import { CHOICES_TYPE, TAGS_TYPE } from './tagLists.js';
9
9
  import { DEFINED_PATH_TYPE } from './definedFields.js';
10
10
  const RANGE_OPS = new Set(['<', '<=', '>', '>=']);
@@ -503,26 +503,6 @@ function readsAsItself(text) {
503
503
  function unescapeValue(text) {
504
504
  return text.replace(/\\(["'\\])/g, '$1');
505
505
  }
506
- /**
507
- * Dates are bound as ISO strings because both target dialects compare them
508
- * correctly that way: Postgres casts on the way in, and SQLite's documented
509
- * text-date format is exactly ISO-8601. A `Date` object handed to a driver
510
- * is at the mercy of whatever it decides to do with the local timezone.
511
- */
512
- function bindDate(d) {
513
- const pad = (n) => String(n).padStart(2, '0');
514
- const day = `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
515
- /* A midnight boundary is bound as the bare day. Text comparison sorts
516
- '2026-08-30' before '2026-08-30 00:00:00', so appending the zero time
517
- made every bare-DATE column compare wrong at the boundary — SQLite
518
- counted a task due *today* as `< today`, i.e. overdue. Bare, the bound
519
- is right for every storage shape at once: it sorts before any datetime
520
- of its day, and a driver casting for a real date/timestamp column reads
521
- it as midnight exactly as before. */
522
- if (!d.getHours() && !d.getMinutes() && !d.getSeconds())
523
- return day;
524
- return `${day} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
525
- }
526
506
  function coerce(column, value, quoted, op) {
527
507
  const kind = column ? columnKind(column.type) : 'other';
528
508
  if (quoted)
@@ -808,6 +788,15 @@ function compileClause(raw, ctx) {
808
788
  const groups = item.quoted ? undefined : (column?.states ?? ctx.states?.[name])?.groups;
809
789
  if (groups && Object.hasOwn(groups, item.value))
810
790
  return { error: `"${item.value}" is a group of ${name}'s states; ask it with is: ${name} is ${item.value}.` };
791
+ const fromChoice = chosenOperand(ctx, item.value, item.quoted);
792
+ if (fromChoice) {
793
+ if (fromChoice.error)
794
+ return { error: fromChoice.error };
795
+ /* Nothing chosen is in no list: left out, as a null profile value is. */
796
+ if (fromChoice.value !== undefined)
797
+ values.push(coerce(column, String(fromChoice.value), false));
798
+ continue;
799
+ }
811
800
  const fromTenant = tenantOperand(ctx, column, item.value, item.quoted);
812
801
  if (fromTenant) {
813
802
  if (fromTenant.error)
@@ -874,6 +863,15 @@ function compileClause(raw, ctx) {
874
863
  if (!quoted && value === 'me' && ctx.me === undefined)
875
864
  return { error: NO_ONE_HERE };
876
865
  /* The reader's tenant profile (`country = tenant.country`), read once for this request; a null value matches no row. */
866
+ /* The person's App choice (`site_id = chosen.site`), proven readable for this request; nothing chosen matches no row. */
867
+ const fromChoice = chosenOperand(ctx, value, quoted);
868
+ if (fromChoice) {
869
+ if (fromChoice.error)
870
+ return { error: fromChoice.error };
871
+ if (fromChoice.none)
872
+ return { conditions: [{ column: name, op: 'in', value: [] }] };
873
+ return { conditions: [{ column: name, op, value: coerce(column, String(fromChoice.value), false) }] };
874
+ }
877
875
  const fromTenant = tenantOperand(ctx, column, value, quoted);
878
876
  if (fromTenant) {
879
877
  if (fromTenant.error)
@@ -7,6 +7,22 @@ interface DateWindow {
7
7
  export declare const DATE_ARITHMETIC: RegExp;
8
8
  /** The day `today ± N units` names, from `today` (YYYY-MM-DD); a month or a year past the month's end lands on its last day. */
9
9
  export declare function shiftedDay(today: string, sign: string, count: number, unit: string): string;
10
+ /**
11
+ * Dates are bound as ISO strings because both target dialects compare them
12
+ * correctly that way: Postgres casts on the way in, and SQLite's documented
13
+ * text-date format is exactly ISO-8601. A `Date` object handed to a driver
14
+ * is at the mercy of whatever it decides to do with the local timezone.
15
+ */
16
+ export declare function bindDate(d: Date): string;
17
+ /**
18
+ * A window's bounds as a read compares against them (bindDate): `start` is in it, `end` is the first moment after it,
19
+ * so `last 30 days` on Nov 20 is 2026-10-21 to 2026-11-21. A custom dashboard section is handed these beside the
20
+ * phrase, to say or draw the span its rows were narrowed to without parsing the grammar itself.
21
+ */
22
+ export declare function windowBounds(phrase: string, now: Date): {
23
+ start: string;
24
+ end: string;
25
+ } | undefined;
10
26
  /**
11
27
  * `now` is a parameter rather than a call to the clock, so the compiler is a
12
28
  * pure function of its inputs. That is what makes the tests below able to