@mistriwork/engine 1.0.0-rc.22 → 1.0.0-rc.23

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.
@@ -364,6 +364,14 @@ export interface DeleteRequest {
364
364
  table: string;
365
365
  /** The whole primary key, and nothing else. */
366
366
  key: Record<string, string | number>;
367
+ /**
368
+ * Delete only while nothing refers to the row. On a principal's scoped transaction with no bound, a table that is
369
+ * not wholly visible is then no refusal in itself: the references are counted on the writer over every row, and a
370
+ * row anything still refers to is refused, never cascaded. Opt-in per delete (a draft's Start over), because the
371
+ * refusal says whether a row the principal cannot see refers to it; every other scoped delete refuses such a table
372
+ * outright, whatever it holds.
373
+ */
374
+ unreferenced?: true;
367
375
  }
368
376
  export interface DeleteResult {
369
377
  affected: number;
@@ -1,7 +1,8 @@
1
1
  import type { DatabaseSchema } from '../../shared/schema.js';
2
2
  import type { ViewDef } from '../../shared/viewPaths.js';
3
3
  import type { HttpOperationReply, HttpOperations } from '../../shared/httpOperations.js';
4
- import { type Adapter, type QueryRequest, type QueryResult, type ViewResult } from '../adapter.js';
4
+ import { type Adapter, type QueryRequest, type QueryResult, type ScopedReads, type ViewResult } from '../adapter.js';
5
+ import { type RowScope } from '../../shared/rowScope.js';
5
6
  import { type HttpDescription } from './httpDescription.js';
6
7
  import { type EgressPolicy } from './egress.js';
7
8
  import type { CacheStore } from '../cache/cacheStore.js';
@@ -36,6 +37,7 @@ export declare class HttpAdapter implements Adapter {
36
37
  introspect(): Promise<DatabaseSchema>;
37
38
  count(table: string): Promise<number>;
38
39
  close(): Promise<void>;
40
+ scopeReads(input: RowScope): Promise<ScopedReads>;
39
41
  /** A resource's two documented reads, for the explorer's API tab: the list with its declared parameters, and the item by its key. */
40
42
  operations(table: string): HttpOperations;
41
43
  /**
@@ -12,7 +12,8 @@
12
12
  */
13
13
  import { Refusal } from '../../shared/refusal.js';
14
14
  import { compileView } from '../../shared/view.js';
15
- import { ANSI_STYLE } from '../adapter.js';
15
+ import { ANSI_STYLE, } from '../adapter.js';
16
+ import { snapshotRowScope } from '../../shared/rowScope.js';
16
17
  import { describedSchema } from './httpDescription.js';
17
18
  import { HttpSourceError, send } from './egress.js';
18
19
  /* How far a cursor-paged list is walked to reach a deep page, and how many
@@ -104,6 +105,58 @@ export class HttpAdapter {
104
105
  throw new Refusal(`${table} comes from an API that reports no totals, so it cannot be counted.`);
105
106
  }
106
107
  async close() { }
108
+ /* A row policy over an API grants a resource whole or not at all. Its rows
109
+ cannot be narrowed: the narrowing would have to be a filter the API
110
+ declares and enforces, and a policy that silently became a page filter
111
+ here would show rows it meant to hide the moment the API ignored it. So a
112
+ scope that names conditions for an API resource is refused, a resource the
113
+ scope leaves out (or denies) is refused, and a whole grant reads as the
114
+ unscoped adapter does — a view's one-step lookups included, which need
115
+ their targets granted whole as well. Counting refuses as `count` does. */
116
+ async scopeReads(input) {
117
+ this.catalog ??= describedSchema(this.connection.description, this.connection.label);
118
+ const scope = snapshotRowScope(this.catalog, input);
119
+ const whole = (table) => {
120
+ const entry = scope[table];
121
+ if (entry === true)
122
+ return;
123
+ if (entry && typeof entry === 'object')
124
+ throw new Refusal(`${table} comes from an API, so a row policy cannot narrow its rows; grant it whole or not at all.`);
125
+ throw new Refusal(`${table} is not readable under this row policy.`);
126
+ };
127
+ const viewReach = (view) => {
128
+ whole(view.base);
129
+ for (const path of compileView(this.catalog, view, ANSI_STYLE)
130
+ .columns.filter((column) => column.hops === 1)
131
+ .map((column) => column.path.split('.')[0])) {
132
+ const fk = this.catalog.foreignKeys.find((each) => each.from.table === view.base && each.from.columns[0] === path);
133
+ if (fk)
134
+ whole(fk.to.table);
135
+ }
136
+ };
137
+ const uncounted = (table) => {
138
+ whole(table);
139
+ throw new Refusal(`${table} comes from an API that reports no totals, so it cannot be counted.`);
140
+ };
141
+ const noBreakdown = (base) => {
142
+ whole(base);
143
+ throw new Refusal(`${base} comes from an API, so it cannot be summarized.`);
144
+ };
145
+ return Object.freeze({
146
+ query: async (request) => {
147
+ whole(request.table);
148
+ return this.query(request);
149
+ },
150
+ count: async (table) => uncounted(table),
151
+ runView: async (view, offset) => {
152
+ viewReach(view);
153
+ return this.runView(view, offset);
154
+ },
155
+ countView: async (view) => uncounted(view.base),
156
+ runBreakdown: async (breakdown) => noBreakdown(breakdown.base),
157
+ countBreakdown: async (breakdown) => noBreakdown(breakdown.base),
158
+ });
159
+ }
107
160
  /** A resource's two documented reads, for the explorer's API tab: the list with its declared parameters, and the item by its key. */
108
161
  operations(table) {
109
162
  const resource = this.resource(table);
@@ -1670,7 +1670,10 @@ export class PostgresAdapter {
1670
1670
  },
1671
1671
  scope,
1672
1672
  }
1673
- : undefined, scope);
1673
+ : undefined, scope, async (fk, key) => {
1674
+ const statement = referencesStatement(catalog, fk, key, POSTGRES_STYLE);
1675
+ return Number((await write.query(statement.text, statement.params)).rows[0]?.n ?? 0);
1676
+ });
1674
1677
  if (journal?.fixedRecords)
1675
1678
  records = journal.fixedRecords(records);
1676
1679
  const invoke = scopedCommandInvoker(operations, true, journal !== undefined, isRuntimeRelation);
@@ -177,4 +177,11 @@ export interface ScopeOwnRows {
177
177
  * This capability deliberately refuses side effects it cannot bound. */
178
178
  export declare function createScopedTransaction(catalog: ScopeCatalog, records: WriteTransaction, reads: Pick<ScopedReads, 'query' | 'count' | 'aggregate'>, guards: Pick<ScopedReads, 'query' | 'count'>, locks?: ScopeRowLocks, bound?: ScopeBound, own?: ScopeOwnRows, triggers?: ScopedTriggers,
179
179
  /** The principal's rows, for the `via` conditions a write's parents are checked against (viaChecks). */
180
- scope?: RowScope): WriteTransaction;
180
+ scope?: RowScope,
181
+ /**
182
+ * How many rows of any table reference a row, counted on the writer itself over every row (referencesStatement).
183
+ * Where there is no bound, a delete that asks for it (DeleteRequest.unreferenced) is allowed only when this counts none: nothing is then
184
+ * left for a cascade to reach, so no row the principal cannot see is touched, and the row is refused while any
185
+ * reference remains.
186
+ */
187
+ referencesOf?: ScopeBound['references']): WriteTransaction;
@@ -180,7 +180,14 @@ function withOwnRows(schema, scope, made) {
180
180
  * This capability deliberately refuses side effects it cannot bound. */
181
181
  export function createScopedTransaction(catalog, records, reads, guards, locks, bound, own, triggers,
182
182
  /** The principal's rows, for the `via` conditions a write's parents are checked against (viaChecks). */
183
- scope) {
183
+ scope,
184
+ /**
185
+ * How many rows of any table reference a row, counted on the writer itself over every row (referencesStatement).
186
+ * Where there is no bound, a delete that asks for it (DeleteRequest.unreferenced) is allowed only when this counts none: nothing is then
187
+ * left for a cascade to reach, so no row the principal cannot see is touched, and the row is refused while any
188
+ * reference remains.
189
+ */
190
+ referencesOf) {
184
191
  /* The rows this transaction inserted inside the principal's rows, by table, and the reads that count them in
185
192
  (ScopeOwnRows). Rebuilt on each such insert; until the first, the reads are the ones resolved for the request. */
186
193
  const made = new Map();
@@ -617,7 +624,11 @@ scope) {
617
624
  const table = target(request.table, { kind: 'delete' });
618
625
  const children = catalog.schema.foreignKeys.filter((fk) => fk.to.table === table.id);
619
626
  const hidden = children.find((fk) => !bound?.whole.has(fk.from.table));
620
- if (hidden)
627
+ /* With a bound, the tenant's own rule stands: every referencing table whole. Without one, a delete that asks
628
+ for it (request.unreferenced) is not refused for a table not wholly visible: the references are counted on
629
+ the writer below, over every row, and a row anything still references is refused, never cascaded. */
630
+ const counted = bound?.references ?? (request.unreferenced ? referencesOf : undefined);
631
+ if (hidden && (bound || !counted))
621
632
  return refuse(`A scoped command may not delete from "${table.id}": "${hidden.from.table}" references it, and a hidden row might.`);
622
633
  const row = await stored(table, request.key);
623
634
  /* Locked first (stored), so no reference can be made to it while these
@@ -631,7 +642,7 @@ scope) {
631
642
  if (!values.every(comparable))
632
643
  return refuse(`"${table.id}".${fk.to.columns.join('+')} holds a value that is not a text or a number.`);
633
644
  const key = { groups: [Object.entries(request.key).map(([column, value]) => ({ column, op: '=', value }))] };
634
- if ((await bound?.references(fk, key)) !== 0)
645
+ if ((await counted?.(fk, key)) !== 0)
635
646
  return refuse(`A scoped command may not delete the "${table.id}" row ${keyText(request.key)}: "${fk.from.table}" still references it.`);
636
647
  }
637
648
  const afterwards = proof && (await proof.before(table, { kind: 'delete' }, proof.images.delete(row)));
@@ -1356,7 +1356,11 @@ export class SqliteAdapter {
1356
1356
  // A public intake writes exactly its fixed rows; only a principal's own transaction counts its new parents in.
1357
1357
  journal?.fixedRecords ? undefined : { scope, reads: (within, guard) => scopedReads(guard, within) },
1358
1358
  // Triggers the App names, on a principal's own transaction: their effects proven per write (triggerProof.ts).
1359
- accepted, scope);
1359
+ accepted, scope, async (fk, key) => {
1360
+ const statement = referencesStatement(catalog, fk, key, ANSI_STYLE);
1361
+ const [row] = await this.readRows(statement.text, statement.params, true, handle);
1362
+ return Number(row?.n ?? 0);
1363
+ });
1360
1364
  /* Each row the transaction's own statements write, told to the session after the statement and after the
1361
1365
  proof has said what its triggers reached: a trigger the proof did not reach that writes it again later is
1362
1366
  a change SQLite still calls direct. */
@@ -38,6 +38,9 @@ export interface StartupConfig {
38
38
  mount?: Record<string, string>;
39
39
  /** `"basePath": "/tools"`, as written; `--base-path` wins. */
40
40
  basePath?: string;
41
+ /** `"presentation": { "<app>": { name, logo, theme, locale } }`, as written: one deployment's name, logo, theme and
42
+ locale for an App, which the App framework checks and applies (mistri app/appPresentation.ts). Never read by the browser. */
43
+ presentation?: unknown;
41
44
  }
42
45
  /**
43
46
  * Whether the config file a start would read names Apps: read raw, before anything is said of it, so the database
@@ -180,7 +180,9 @@ export async function readStartupConfig(opts, registry, given) {
180
180
  }
181
181
  /* Where the Apps are served, beside which Apps: a deployment's fact,
182
182
  checked with the flags' own rule once the Apps are loaded (main). */
183
- const { mount, basePath } = JSON.parse(await readFile(config.path, 'utf8'));
183
+ const { mount, basePath, presentation } = JSON.parse(await readFile(config.path, 'utf8'));
184
+ if (presentation !== undefined)
185
+ read.presentation = presentation;
184
186
  if (mount !== undefined) {
185
187
  if (!mount || typeof mount !== 'object' || Array.isArray(mount) || Object.values(mount).some((at) => typeof at !== 'string')) {
186
188
  throw new Error(`${config.path}: "mount" must name each App's place by its id, like { "main": "/", "billing": "/billing" }.`);
@@ -2,7 +2,7 @@ import { createBrotliCompress, createGzip, constants as zlib } from 'node:zlib';
2
2
  import { withCancellation } from '../../adapters/statementControl.js';
3
3
  import { parseQuery } from '../../shared/query.js';
4
4
  import { textToView } from '../../shared/viewtext.js';
5
- import { findTable, resolveOrder } from '../../shared/schema.js';
5
+ import { findTable, resolveOrder, tableDialect } from '../../shared/schema.js';
6
6
  import { backrefsTo, resolveAggregate, tryResolvePath } from '../../shared/viewPaths.js';
7
7
  import { CRLF, csvField, csvRecord, jsonRecord } from '../../shared/csv.js';
8
8
  import { readRecords, readView } from '../resourceReadOperations.js';
@@ -120,11 +120,11 @@ export async function exportFile(asked) {
120
120
  if (!may(reached))
121
121
  return refuseTable(answer, reached === UNKNOWN_TABLE ? table.id : reached);
122
122
  /* The order the list reads in, made total with the key; an offset batch reads in it too. */
123
- const order = schema.dialect === 'http' && !query.orderBy?.length ? undefined : resolveOrder(table, query.orderBy).order;
123
+ const order = tableDialect(schema, table) === 'http' && !query.orderBy?.length ? undefined : resolveOrder(table, query.orderBy).order;
124
124
  let step;
125
125
  const read = async (offset, size) => {
126
126
  /* A union pages by offset: its rows have no one key order across branches (unionReads.ts), as the list's. */
127
- const paging = table.union ? undefined : recordsPaging(table, schema.dialect, query.orderBy, wanted, query.filter, step);
127
+ const paging = table.union ? undefined : recordsPaging(table, tableDialect(schema, table), query.orderBy, wanted, query.filter, step);
128
128
  /* Past the first batch with no boundary to resume from, the file goes on by offset in the same total order. */
129
129
  const continued = paging && (!step || paging.continuation) ? paging : undefined;
130
130
  /* An order column the file does not show is read for the boundary and taken out again (settlePage): it never
@@ -1,4 +1,4 @@
1
- import { defaultOrder, resolveOrder, withKey } from '../shared/schema.js';
1
+ import { defaultOrder, resolveOrder, tableDialect, withKey } from '../shared/schema.js';
2
2
  import { continueGroups, keysetAfter, keysetOrder, pageBounds, reversedOrder, } from '../shared/keysetPage.js';
3
3
  /** The groups past (or, read the other way, before) a step's boundary; undefined when it names no exact boundary. */
4
4
  function continuationGroups(table, order, step, dialect) {
@@ -42,7 +42,7 @@ export function viewPaging(schema, table, view, step) {
42
42
  const order = given.length
43
43
  ? withKey(table, given.map((o) => ({ column: o.path, direction: o.direction })))
44
44
  : defaultOrder(table);
45
- if (!keysetOrder(table, order, schema.dialect))
45
+ if (!keysetOrder(table, order, tableDialect(schema, table)))
46
46
  return undefined;
47
47
  // No columns is every column of the base table, the order's among them.
48
48
  const shown = new Set(view.columns.map((c) => c.path));
@@ -52,7 +52,7 @@ export function viewPaging(schema, table, view, step) {
52
52
  orderBy: order.map((o) => ({ path: o.column, direction: o.direction })),
53
53
  ...(extra.length ? { columns: [...view.columns, ...extra.map((path) => ({ path }))] } : {}),
54
54
  };
55
- const planned = step && continuationGroups(table, order, step, schema.dialect);
55
+ const planned = step && continuationGroups(table, order, step, tableDialect(schema, table));
56
56
  if (step && !planned)
57
57
  return { view: read, order, extra };
58
58
  const toPaths = (groups) => groups.map((group) => group.map(({ column, op, value }) => ({ path: column, op, ...(value === undefined ? {} : { value }) })));
@@ -1,3 +1,4 @@
1
+ import { type Dialect } from './database.js';
1
2
  import { type MigrateTarget } from './runner.js';
2
3
  /** The pinned build. A new version is a new line here and new checksums, reviewed like any dependency. */
3
4
  export declare const ATLAS_VERSION = "v1.3.0";
@@ -22,6 +23,24 @@ export declare function atlasUrl(url: string, schema?: string): {
22
23
  url: string;
23
24
  env: Record<string, string>;
24
25
  };
26
+ /**
27
+ * schema.sql built into one scratch database and handed back as a URL: what `mistri check --schema-file` reads in
28
+ * place of the App's database. It is run as the file is, by the same executor a migration is (`schema.sql` is the
29
+ * first migration, firstMigration), so the catalog the describer reads is the one `migrate up` would make, down to
30
+ * how a column's type is spelled. Atlas was tried for this and set aside: it writes the schema back in its own
31
+ * spelling (`BOOLEAN` as `boolean`), so the scratch described differently from the database the same file built.
32
+ * SQLite needs no server; PostgreSQL needs the one `devUrl` names, with CREATEDB, as `migrate diff` does. The caller
33
+ * drops it.
34
+ */
35
+ export declare function schemaDatabase(options: {
36
+ readonly schemaFile: string;
37
+ readonly devUrl?: string;
38
+ readonly schema?: string;
39
+ }): Promise<{
40
+ readonly url: string;
41
+ readonly dialect: Dialect;
42
+ readonly drop: () => Promise<void>;
43
+ }>;
25
44
  interface DesiredOptions {
26
45
  /** The desired schema: `schema.sql` beside the migrations unless named. */
27
46
  readonly schemaFile: string;
@@ -170,6 +170,45 @@ async function scratch(url, devUrl) {
170
170
  }
171
171
  return { built: at(names[0]), dev: at(names[1]), drop };
172
172
  }
173
+ /**
174
+ * schema.sql built into one scratch database and handed back as a URL: what `mistri check --schema-file` reads in
175
+ * place of the App's database. It is run as the file is, by the same executor a migration is (`schema.sql` is the
176
+ * first migration, firstMigration), so the catalog the describer reads is the one `migrate up` would make, down to
177
+ * how a column's type is spelled. Atlas was tried for this and set aside: it writes the schema back in its own
178
+ * spelling (`BOOLEAN` as `boolean`), so the scratch described differently from the database the same file built.
179
+ * SQLite needs no server; PostgreSQL needs the one `devUrl` names, with CREATEDB, as `migrate diff` does. The caller
180
+ * drops it.
181
+ */
182
+ export async function schemaDatabase(options) {
183
+ if (!existsSync(options.schemaFile))
184
+ throw new Error(`there is no ${options.schemaFile}: write the schema you want there, or name it with --schema-file.`);
185
+ const dialect = options.devUrl !== undefined ? dialectOf(options.devUrl) : 'sqlite';
186
+ const text = readFileSync(options.schemaFile, 'utf8');
187
+ const db = await scratch(options.devUrl ?? 'scratch.db', options.devUrl);
188
+ try {
189
+ const schema = dialect === 'postgres' ? (options.schema ?? 'public') : undefined;
190
+ const built = await openMigrationDb(db.built, schema !== undefined ? [schema] : [], true);
191
+ try {
192
+ if (schema !== undefined && schema !== 'public') {
193
+ await built.run(`CREATE SCHEMA IF NOT EXISTS ${quoteIdent('postgres', schema)}`);
194
+ await built.script(`SET search_path TO ${quoteIdent('postgres', schema)};\n${text}`);
195
+ }
196
+ else
197
+ await built.script(dialect === 'sqlite' ? sqliteDesired(text) : text);
198
+ }
199
+ catch (error) {
200
+ throw new Error(`${options.schemaFile} did not run on a scratch ${dialect} database: ${error.message}`);
201
+ }
202
+ finally {
203
+ await built.close();
204
+ }
205
+ return { url: db.built, dialect, drop: db.drop };
206
+ }
207
+ catch (error) {
208
+ await db.drop();
209
+ throw error;
210
+ }
211
+ }
173
212
  /**
174
213
  * What the migrations still lack to reach `schema.sql`, as SQL: empty when
175
214
  * they agree. tablewalk's own tables (`__mistri_*`, and the history table
@@ -1,6 +1,7 @@
1
1
  import { ANSI_STYLE, POSTGRES_STYLE } from '../adapters/adapter.js';
2
- import { findTable } from '../shared/schema.js';
3
- import { parseQuery, explain } from '../shared/query.js';
2
+ import { findTable, tableDialect } from '../shared/schema.js';
3
+ import { andQuery, parseQuery, explain } from '../shared/query.js';
4
+ import { compileWhere } from '../shared/pageWhere.js';
4
5
  import { PathError, explainView, parseViewQuery } from '../shared/view.js';
5
6
  import { textToView, viewToTextWithSchema } from '../shared/viewtext.js';
6
7
  import { breakdownToText, sectionFromText, textToBreakdown } from '../shared/breakdowntext.js';
@@ -204,21 +205,22 @@ export async function dispatchResourceReadHttp(path, body, adapter, schema, opti
204
205
  /* An API reports no totals (adapters/http), and counting one would walk
205
206
  every page of someone else's rate budget: its lists page by whether a
206
207
  full page came back, as a view without a count does. */
208
+ const own = findTable(schema, q.table);
209
+ const dialect = tableDialect(schema, own);
207
210
  const exact = body.exactCount === true || body.count === 'exact';
208
- const countMode = schema.dialect === 'http' || body.count === 'none' || lanes ? 'none' : exact ? 'exact' : 'estimate';
211
+ const countMode = dialect === 'http' || body.count === 'none' || lanes ? 'none' : exact ? 'exact' : 'estimate';
209
212
  /* A filtered total is counted to DEFAULT_COUNT_LIMIT unless the request
210
213
  asks for the exact number or names its own bound: past it the list says
211
214
  "10,000+" and offers to count exactly. Unfiltered, the catalog's
212
215
  estimate or a plain count answers as before. */
213
216
  const countLimit = body.countLimit ?? (!exact && q.filter?.groups?.length ? DEFAULT_COUNT_LIMIT : undefined);
214
- const own = findTable(schema, q.table);
215
217
  /* Lanes are a column of one stored table's rows: a union pages its branches apart, an API answers in its own order. */
216
- if (lanes && (!own || own.union || schema.dialect === 'http' || step || !own.columns.some((column) => column.name === lanes.by))) {
218
+ if (lanes && (!own || own.union || dialect === 'http' || step || !own.columns.some((column) => column.name === lanes.by))) {
217
219
  return refusal(400, [`A board reads its lanes in one read only by a column of ${q.table}'s own rows.`]);
218
220
  }
219
221
  const most = options.rowsMost?.(own?.id ?? q.table);
220
222
  const bounded = (limit) => (most === undefined ? limit : Math.min(clampLimit(limit), most));
221
- const paging = own && !own.union && !lanes ? recordsPaging(own, schema.dialect, q.orderBy, q.columns, q.filter, step) : undefined;
223
+ const paging = own && !own.union && !lanes ? recordsPaging(own, dialect, q.orderBy, q.columns, q.filter, step) : undefined;
222
224
  if (step && !paging?.continuation) {
223
225
  const refused = tooDeep();
224
226
  if (refused)
@@ -484,8 +486,21 @@ export async function dispatchResourceReadHttp(path, body, adapter, schema, opti
484
486
  view = parsed.view;
485
487
  merged = parsed.view;
486
488
  }
487
- if (typeof body.query === 'string' && body.query.trim()) {
488
- const parsed = parseViewQuery(schema, view.base, body.query, options.now(), person);
489
+ /* A page's object condition (pageWhere.ts) joins its query as the text it means, so the one parser reads both
490
+ under this reader's grants. A where that names what the table lacks is refused, never dropped: dropped, the
491
+ read would be wider than the page asked for. */
492
+ let query = typeof body.query === 'string' ? body.query : '';
493
+ if (body.where !== undefined) {
494
+ const table = findTable(schema, view.base);
495
+ if (!table)
496
+ return refusal(400, ['A where needs the view to name its base table.']);
497
+ const where = compileWhere(body.where, table);
498
+ if ('error' in where)
499
+ return refusal(400, [where.error]);
500
+ query = andQuery(where.text, query);
501
+ }
502
+ if (query.trim()) {
503
+ const parsed = parseViewQuery(schema, view.base, query, options.now(), person);
489
504
  errors.push(...parsed.errors);
490
505
  merged = {
491
506
  ...view,
@@ -1,6 +1,6 @@
1
1
  import { ESTIMATE_ABOVE, OPS, Refusal, clampLimit, clampOffset, } from '../adapters/adapter.js';
2
2
  import { snapshotScopedData } from '../adapters/scoped/scopedReads.js';
3
- import { findTable, resolveOrder } from '../shared/schema.js';
3
+ import { findTable, resolveOrder, tableDialect } from '../shared/schema.js';
4
4
  import { withViewComputed, withViewLabels } from '../shared/view.js';
5
5
  import { measureConditions, withBreakdownComputed, withGroupNames } from '../shared/breakdown.js';
6
6
  import { reversedOrder } from '../shared/keysetPage.js';
@@ -292,7 +292,9 @@ export async function readRecords(reader, schema, input, countMode = 'none', cou
292
292
  /* An API answers in its own order. With none asked for, none is sent: the
293
293
  key as a default sort is one most APIs do not document, and would turn
294
294
  every plain list into a refusal (adapters/http). */
295
- const order = snapshotScopedData(schema.dialect === 'http' && !given.orderBy?.length ? { order: [], implicit: true } : resolveOrder(table, given.orderBy));
295
+ const order = snapshotScopedData(tableDialect(schema, table) === 'http' && !given.orderBy?.length
296
+ ? { order: [], implicit: true }
297
+ : resolveOrder(table, given.orderBy));
296
298
  const request = {
297
299
  ...given,
298
300
  table: table.id,
@@ -352,6 +352,24 @@ export function parseCustomList(raw, at) {
352
352
  const MAX_PAGE_PARAMS = 8;
353
353
  const PARAM = /^[a-z][a-z0-9_]{0,31}$/;
354
354
  const LOADER = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
355
+ /* A parameter's kind is how the page reads its text back (sdk/page.tsx): the address always holds text. */
356
+ const PARAM_KINDS = ['id', 'text', 'date', 'date-range'];
357
+ const paramKind = (kind) => PARAM_KINDS.includes(kind) ||
358
+ (Array.isArray(kind) &&
359
+ kind.length > 0 &&
360
+ kind.every((value) => typeof value === 'string' && value !== '') &&
361
+ new Set(kind).size === kind.length);
362
+ /* `params: ['list']` is the names alone, each read as text; `params: { list: 'id' }` gives each a kind. The server keeps
363
+ the names: the address and the loader carry text either way, and the page reads it as its kind. */
364
+ function pageParamNames(raw) {
365
+ if (raw === undefined)
366
+ return [];
367
+ if (Array.isArray(raw))
368
+ return raw;
369
+ if (!isRecord(raw))
370
+ return undefined;
371
+ return Object.values(raw).every(paramKind) ? Object.keys(raw) : undefined;
372
+ }
355
373
  const words = (raw) => Array.isArray(raw) && raw.every((name) => typeof name === 'string' && name.trim() !== '');
356
374
  /**
357
375
  * `definePage({ reads: ['pick_list'], commands: ['pickList'], params: ['list'], component })`:
@@ -374,12 +392,12 @@ export function parsePage(raw, at) {
374
392
  const actions = raw.actions === undefined ? [] : raw.actions;
375
393
  if (!words(actions))
376
394
  throw new Error(`[page-action] ${at} has "actions" that are not a list of action ids: actions: ['startVisit'].`);
377
- const params = raw.params === undefined ? [] : raw.params;
378
- if (!Array.isArray(params) ||
395
+ const params = pageParamNames(raw.params);
396
+ if (!params ||
379
397
  params.length > MAX_PAGE_PARAMS ||
380
398
  params.some((name) => typeof name !== 'string' || !PARAM.test(name)) ||
381
399
  params.includes('period')) {
382
- throw new Error(`[page-params] ${at} has "params" that are not up to ${MAX_PAGE_PARAMS} lowercase words, like params: ['list']; "period" is a dashboard's.`);
400
+ 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.`);
383
401
  }
384
402
  if (raw.loader !== undefined && (typeof raw.loader !== 'string' || !LOADER.test(raw.loader))) {
385
403
  throw new Error(`[page-loader] ${at} has a "loader" that is not a loader's name, as the commands module's defineLoaders() registers it.`);
@@ -0,0 +1,29 @@
1
+ /**
2
+ * A free-form page's object condition (`where={{ status: 'booked', party_size: { gt: 1 } }}`), written out as the
3
+ * query language's own text. One compiler for both ends: the browser compiles a block's `where` into the query it
4
+ * already sends, and the server compiles the `where` a read sends beside its `query` (resourceReadHttp.ts). Either
5
+ * way the result is parsed by the one parser under the reader's grants, so an object condition is held to exactly
6
+ * what the same condition typed as text would be — there is no second path to the database.
7
+ *
8
+ * The server never trusts the browser's types: a key that is not one of the resource's columns, an operator the
9
+ * object form does not have, or a value of the wrong kind for its column is refused with a sentence, not dropped.
10
+ * Dropping it would widen the read silently, and a page that asked for one class's bookings would draw everyone's.
11
+ *
12
+ * Values are written so the parser reads them as what they are: a string is quoted (a quoted value is always
13
+ * text, so `'me'` or `'today'` in a text column is those letters), except digits on a number column, which stay
14
+ * bare so they compare as numbers, ids past 2^53 included, and an ISO day on a date column, bare so it reads as
15
+ * that day (on a timestamp, all of it). A list is a chain of `=` joined by `or`, never `in (…)`: the language
16
+ * splits an `in` list at every comma, quoted or not.
17
+ */
18
+ import { type TableMeta } from './schema.js';
19
+ /**
20
+ * The query text an object condition means on this table, or the sentence that refuses it. A key whose value is
21
+ * `undefined` asks nothing (JSON drops it on the way to the server, so the browser must too); every other key is
22
+ * one condition, and the conditions are joined by `and`. A list of objects is each of them, joined by `and`: a
23
+ * `<Scope>`'s condition and the one a block inside it adds, sent as they were written.
24
+ */
25
+ export declare function compileWhere(where: unknown, table: Pick<TableMeta, 'name' | 'columns'>): {
26
+ text: string;
27
+ } | {
28
+ error: string;
29
+ };
@@ -0,0 +1,160 @@
1
+ /**
2
+ * A free-form page's object condition (`where={{ status: 'booked', party_size: { gt: 1 } }}`), written out as the
3
+ * query language's own text. One compiler for both ends: the browser compiles a block's `where` into the query it
4
+ * already sends, and the server compiles the `where` a read sends beside its `query` (resourceReadHttp.ts). Either
5
+ * way the result is parsed by the one parser under the reader's grants, so an object condition is held to exactly
6
+ * what the same condition typed as text would be — there is no second path to the database.
7
+ *
8
+ * The server never trusts the browser's types: a key that is not one of the resource's columns, an operator the
9
+ * object form does not have, or a value of the wrong kind for its column is refused with a sentence, not dropped.
10
+ * Dropping it would widen the read silently, and a page that asked for one class's bookings would draw everyone's.
11
+ *
12
+ * Values are written so the parser reads them as what they are: a string is quoted (a quoted value is always
13
+ * text, so `'me'` or `'today'` in a text column is those letters), except digits on a number column, which stay
14
+ * bare so they compare as numbers, ids past 2^53 included, and an ISO day on a date column, bare so it reads as
15
+ * that day (on a timestamp, all of it). A list is a chain of `=` joined by `or`, never `in (…)`: the language
16
+ * splits an `in` list at every comma, quoted or not.
17
+ */
18
+ import { columnKind, isFlagColumn } from './schema.js';
19
+ /** The operators of the object form, and the language's word for each. */
20
+ const RANGE = { gt: '>', gte: '>=', lt: '<', lte: '<=' };
21
+ const MATCH = { contains: 'contains', startsWith: 'startswith', endsWith: 'endswith' };
22
+ const WHERE_OPERATORS = ['not', ...Object.keys(RANGE), ...Object.keys(MATCH)];
23
+ const NUMERAL = /^-?\d+(?:\.\d+)?$/;
24
+ const ISO_DAY = /^\d{4}-\d{2}-\d{2}$/;
25
+ /* The language's column token: a name outside it could not be read back as a column. */
26
+ const COLUMN_NAME = /^[\w$]+$/;
27
+ const plain = (value) => typeof value === 'object' && value !== null && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
28
+ const kindOf = (column) => (isFlagColumn(column) ? 'boolean' : columnKind(column.type));
29
+ /* One value in the language, or the sentence that says why it cannot stand for this column. */
30
+ function written(name, kind, value) {
31
+ if (typeof value === 'number') {
32
+ const text = String(value);
33
+ if ((kind === 'number' || kind === 'other') && Number.isFinite(value) && NUMERAL.test(text))
34
+ return { text };
35
+ return { error: `${name} cannot be compared with the number ${text}.` };
36
+ }
37
+ if (typeof value === 'boolean') {
38
+ if (kind === 'boolean' || kind === 'other')
39
+ return { text: String(value) };
40
+ return { error: `${name} holds no yes or no, so it cannot be compared with ${value}.` };
41
+ }
42
+ if (typeof value === 'string') {
43
+ if (kind === 'number') {
44
+ if (NUMERAL.test(value))
45
+ return { text: value };
46
+ return { error: `${name} holds numbers, so it cannot be compared with "${value}".` };
47
+ }
48
+ if (kind === 'boolean')
49
+ return { error: `${name} holds yes or no: compare it with true or false, not "${value}".` };
50
+ if (kind === 'date' && ISO_DAY.test(value))
51
+ return { text: value };
52
+ return { text: `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"` };
53
+ }
54
+ return { error: `${name} cannot be compared with ${value === undefined ? 'undefined' : (JSON.stringify(value) ?? typeof value)}.` };
55
+ }
56
+ function oneOf(name, kind, values, op) {
57
+ if (!values.length)
58
+ return { error: `${name} is asked for one of no values: leave it out, or name at least one.` };
59
+ const parts = [];
60
+ for (const value of values) {
61
+ const got = written(name, kind, value);
62
+ if ('error' in got)
63
+ return got;
64
+ parts.push(`${name} ${op} ${got.text}`);
65
+ }
66
+ if (op === '!=')
67
+ return { text: parts.join(' and ') };
68
+ return { text: parts.length === 1 ? parts[0] : `(${parts.join(' or ')})` };
69
+ }
70
+ function condition(name, kind, value) {
71
+ if (value === null)
72
+ return { text: `${name} is empty` };
73
+ if (Array.isArray(value))
74
+ return oneOf(name, kind, value, '=');
75
+ if (!plain(value))
76
+ return equal(name, kind, value);
77
+ const parts = [];
78
+ for (const [op, operand] of Object.entries(value)) {
79
+ if (operand === undefined)
80
+ continue;
81
+ if (op === 'not') {
82
+ const got = operand === null
83
+ ? { text: `${name} is not empty` }
84
+ : Array.isArray(operand)
85
+ ? oneOf(name, kind, operand, '!=')
86
+ : notEqual(name, kind, operand);
87
+ if ('error' in got)
88
+ return got;
89
+ parts.push(got.text);
90
+ }
91
+ else if (Object.hasOwn(RANGE, op)) {
92
+ if (kind === 'boolean')
93
+ return { error: `${name} holds yes or no, which has no ${op}.` };
94
+ const got = written(name, kind, operand);
95
+ if ('error' in got)
96
+ return got;
97
+ parts.push(`${name} ${RANGE[op]} ${got.text}`);
98
+ }
99
+ else if (Object.hasOwn(MATCH, op)) {
100
+ if (kind !== 'text' && kind !== 'other')
101
+ return { error: `${name} does not hold text, so it has no ${op}.` };
102
+ if (typeof operand !== 'string')
103
+ return { error: `${name} ${op} takes text, not ${JSON.stringify(operand) ?? typeof operand}.` };
104
+ parts.push(`${name} ${MATCH[op]} ${written(name, 'text', operand).text}`);
105
+ }
106
+ else {
107
+ return { error: `${name} has no operator "${op}": the object form has ${WHERE_OPERATORS.join(', ')}.` };
108
+ }
109
+ }
110
+ if (!parts.length)
111
+ return { error: `${name} is given an object with no operator in it: the object form has ${WHERE_OPERATORS.join(', ')}.` };
112
+ return { text: parts.join(' and ') };
113
+ }
114
+ function equal(name, kind, value) {
115
+ const got = written(name, kind, value);
116
+ return 'error' in got ? got : { text: `${name} = ${got.text}` };
117
+ }
118
+ function notEqual(name, kind, value) {
119
+ const got = written(name, kind, value);
120
+ return 'error' in got ? got : { text: `${name} != ${got.text}` };
121
+ }
122
+ /**
123
+ * The query text an object condition means on this table, or the sentence that refuses it. A key whose value is
124
+ * `undefined` asks nothing (JSON drops it on the way to the server, so the browser must too); every other key is
125
+ * one condition, and the conditions are joined by `and`. A list of objects is each of them, joined by `and`: a
126
+ * `<Scope>`'s condition and the one a block inside it adds, sent as they were written.
127
+ */
128
+ export function compileWhere(where, table) {
129
+ if (where === undefined || where === null)
130
+ return { text: '' };
131
+ if (Array.isArray(where)) {
132
+ const parts = [];
133
+ for (const each of where) {
134
+ if (!plain(each))
135
+ return { error: 'A where list holds objects of column names and values, one for each condition joined.' };
136
+ const got = compileWhere(each, table);
137
+ if ('error' in got)
138
+ return got;
139
+ // Every join inside one is an `and` too, and its `or` chains are already in brackets: no brackets needed here.
140
+ if (got.text)
141
+ parts.push(got.text);
142
+ }
143
+ return { text: parts.join(' and ') };
144
+ }
145
+ if (!plain(where))
146
+ return { error: `A where is an object of column names and values, not ${typeof where}.` };
147
+ const parts = [];
148
+ for (const [key, value] of Object.entries(where)) {
149
+ if (value === undefined)
150
+ continue;
151
+ const column = table.columns.find((one) => one.name === key);
152
+ if (!column || !COLUMN_NAME.test(key))
153
+ return { error: `${table.name} has no column "${key}".` };
154
+ const got = condition(key, kindOf(column), value);
155
+ if ('error' in got)
156
+ return got;
157
+ parts.push(got.text);
158
+ }
159
+ return { text: parts.join(' and ') };
160
+ }
@@ -338,6 +338,8 @@ export declare function looksLikeDate(column: ColumnMeta): boolean;
338
338
  export declare function rowName(table: TableMeta): string | undefined;
339
339
  export declare function labelColumn(table: TableMeta): string | undefined;
340
340
  /** Primary key columns, in declaration order. */
341
+ /** The engine `table` is read on: its own source's where an App's catalog merges several (`sourceDialect`), the catalog's otherwise. */
342
+ export declare function tableDialect(schema: Pick<DatabaseSchema, 'dialect'>, table: Pick<TableMeta, 'sourceDialect'> | undefined): Dialect;
341
343
  export declare function primaryKey(table: TableMeta): string[];
342
344
  /**
343
345
  * Where a row's name lives, as a view path.
@@ -244,6 +244,10 @@ export function labelColumn(table) {
244
244
  return firstText?.name ?? table.columns.find((c) => c.primaryKey)?.name;
245
245
  }
246
246
  /** Primary key columns, in declaration order. */
247
+ /** The engine `table` is read on: its own source's where an App's catalog merges several (`sourceDialect`), the catalog's otherwise. */
248
+ export function tableDialect(schema, table) {
249
+ return table?.sourceDialect ?? schema.dialect;
250
+ }
247
251
  export function primaryKey(table) {
248
252
  return table.columns.filter((c) => c.primaryKey).map((c) => c.name);
249
253
  }
@@ -140,6 +140,9 @@ export function captureScopeCatalog(schema) {
140
140
  'deletable',
141
141
  'insertable',
142
142
  'sourceDialect',
143
+ 'filterable',
144
+ 'sortable',
145
+ 'countable',
143
146
  ]);
144
147
  if (!identifier(table.id) ||
145
148
  /* A catalog of several connections says which engine reads each table
@@ -209,6 +212,15 @@ export function captureScopeCatalog(schema) {
209
212
  pair.length !== 2 ||
210
213
  pair.some((name) => typeof name !== 'string' || !table.columns.some((column) => column.name === name)))))
211
214
  return refuse();
215
+ /* What an API can filter and sort by, and that it reports no totals (adapters/http): evidence for which boxes
216
+ a list offers, never a grant, so it is carried and left out of the fingerprint. Only columns this table has. */
217
+ for (const names of [table.filterable, table.sortable])
218
+ if (names !== undefined &&
219
+ (!Array.isArray(names) ||
220
+ names.some((name) => typeof name !== 'string' || !table.columns.some((column) => column.name === name))))
221
+ return refuse();
222
+ if (table.countable !== undefined && table.countable !== false)
223
+ return refuse();
212
224
  // Index advice, as `unique` is address evidence: only columns this table has.
213
225
  if (table.trigram !== undefined &&
214
226
  (!Array.isArray(table.trigram) ||
@@ -626,8 +626,19 @@ export interface ServedDashboardView {
626
626
  icon?: AppIconName;
627
627
  sections: readonly object[];
628
628
  favorite?: true;
629
+ /** A free-form page's manifest; one with a `record` is a tab of that table's record page, never a room of its own. */
630
+ page?: {
631
+ record?: ServedRecordTab;
632
+ };
629
633
  error?: string;
630
634
  }
635
+ /** A free-form page placed as a record's tab (`pages/<list view>/[id]/<tab>.page.tsx`): the list view whose records it
636
+ is a tab of, that view's table by id, and the word the record's address says it by. */
637
+ export interface ServedRecordTab {
638
+ view: string;
639
+ table: string;
640
+ tab: string;
641
+ }
631
642
  /** A signed-in form as the shared client reads it: its words and the command it runs (appModel.ts AppFormView). */
632
643
  export interface ServedFormView {
633
644
  label: string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mistriwork/engine",
3
- "version": "1.0.0-rc.22",
3
+ "version": "1.0.0-rc.23",
4
4
  "description": "The engine both products stand on: the adapters (SQLite, Postgres), the catalog, the query language, keyset pages, the HTTP kit and the shared rules. No React.",
5
5
  "homepage": "https://mistriwork.dev",
6
6
  "bugs": {
@@ -127,6 +127,7 @@
127
127
  "./server/layouts.js": "./dist/server/layouts.js",
128
128
  "./server/migrate/cli.js": "./dist/server/migrate/cli.js",
129
129
  "./server/migrate/database.js": "./dist/server/migrate/database.js",
130
+ "./server/migrate/desired.js": "./dist/server/migrate/desired.js",
130
131
  "./server/migrate/files.js": "./dist/server/migrate/files.js",
131
132
  "./server/migrate/history.js": "./dist/server/migrate/history.js",
132
133
  "./server/migrate/runner.js": "./dist/server/migrate/runner.js",
@@ -216,6 +217,7 @@
216
217
  "./shared/pagePaths.js": "./dist/shared/pagePaths.js",
217
218
  "./shared/pagePlans.js": "./dist/shared/pagePlans.js",
218
219
  "./shared/pageRoutes.js": "./dist/shared/pageRoutes.js",
220
+ "./shared/pageWhere.js": "./dist/shared/pageWhere.js",
219
221
  "./shared/query.js": "./dist/shared/query.js",
220
222
  "./shared/queryDates.js": "./dist/shared/queryDates.js",
221
223
  "./shared/queryOperands.js": "./dist/shared/queryOperands.js",