@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.
- package/dist/adapters/adapter.d.ts +6 -0
- package/dist/adapters/postgres.js +13 -7
- package/dist/adapters/postgresPool.d.ts +28 -0
- package/dist/adapters/postgresPool.js +36 -3
- package/dist/adapters/scoped/scopedReads.js +5 -1
- package/dist/adapters/scoped/scopedTransaction.js +3 -1
- package/dist/adapters/serverSettings.d.ts +2 -0
- package/dist/adapters/sqlite.js +7 -5
- package/dist/server/cli/args.d.ts +2 -1
- package/dist/server/cli/args.js +13 -2
- package/dist/server/columnGrants.d.ts +3 -0
- package/dist/server/columnGrants.js +29 -4
- package/dist/server/connections.d.ts +1 -1
- package/dist/server/connections.js +2 -0
- package/dist/server/http/probes.d.ts +10 -1
- package/dist/server/http/probes.js +6 -2
- package/dist/server/http/recordWrites.js +7 -1
- package/dist/server/http/refusalReport.js +7 -1
- package/dist/server/http/serverCore.d.ts +2 -1
- package/dist/server/migrate/cli.js +7 -0
- package/dist/server/poolConfig.d.ts +4 -0
- package/dist/server/poolConfig.js +20 -7
- package/dist/server/resourceReadHttp.js +7 -2
- package/dist/server/resourceReadOperations.js +5 -1
- package/dist/shared/aggregate.js +7 -1
- package/dist/shared/appComponents.js +1 -1
- package/dist/shared/autoBucket.d.ts +29 -5
- package/dist/shared/autoBucket.js +49 -14
- package/dist/shared/computedParse.d.ts +2 -0
- package/dist/shared/computedParse.js +1 -1
- package/dist/shared/computedWhere.d.ts +47 -0
- package/dist/shared/computedWhere.js +159 -0
- package/dist/shared/filter.d.ts +5 -0
- package/dist/shared/filter.js +4 -0
- package/dist/shared/query.js +20 -22
- package/dist/shared/queryDates.d.ts +16 -0
- package/dist/shared/queryDates.js +29 -0
- package/dist/shared/queryOperands.d.ts +24 -0
- package/dist/shared/queryOperands.js +36 -0
- package/dist/shared/refusal.d.ts +8 -0
- package/dist/shared/refusal.js +15 -0
- package/dist/shared/resourceHttp.d.ts +1 -1
- package/dist/shared/rowCondition.d.ts +5 -0
- package/dist/shared/rowCondition.js +80 -0
- package/dist/shared/schema.d.ts +10 -0
- package/dist/shared/schema.js +8 -0
- package/dist/shared/scopeCatalog.d.ts +1 -1
- package/dist/shared/scopeCatalog.js +13 -1
- package/dist/shared/servedApp.d.ts +19 -0
- package/dist/shared/structuredFilter.d.ts +3 -0
- package/dist/shared/viewLabels.d.ts +6 -1
- package/dist/shared/viewLabels.js +1 -1
- package/package.json +2 -1
- 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
|
|
4
|
-
*
|
|
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
|
|
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 "
|
|
34
|
-
if (
|
|
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 {
|
|
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,
|
|
363
|
-
: dispatchResourceReadHttp('/api/breakdown', { def, text, limit, offset }, adapter, schema,
|
|
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
|
-
|
|
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) {
|
package/dist/shared/aggregate.js
CHANGED
|
@@ -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
|
|
30
|
-
* to today's, and the read periods added up into the unit the span is drawn in.
|
|
31
|
-
*
|
|
32
|
-
*
|
|
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
|
-
*
|
|
136
|
-
* to
|
|
137
|
-
*
|
|
138
|
-
*
|
|
139
|
-
*
|
|
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
|
|
145
|
-
if (
|
|
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
|
-
|
|
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
|
|
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 (
|
|
154
|
-
const label = bucketKey(key, unit);
|
|
155
|
-
into.set(label, (into.get(label) ?? 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
|
+
}
|
package/dist/shared/filter.d.ts
CHANGED
|
@@ -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;
|
package/dist/shared/filter.js
CHANGED
|
@@ -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 = [];
|
package/dist/shared/query.js
CHANGED
|
@@ -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
|