ezship 0.1.16 → 0.1.18
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +60 -56
- package/access.d.mts +4 -4
- package/access.mjs +13 -13
- package/account.mjs +9 -8
- package/bindings.mjs +9 -27
- package/commands.d.mts +65 -67
- package/commands.mjs +1274 -535
- package/connections.d.mts +2 -3
- package/connections.mjs +10 -22
- package/cron.d.mts +1 -1
- package/cron.mjs +1 -1
- package/documents.d.mts +1 -1
- package/documents.mjs +1 -1
- package/editor-types.json.gz +0 -0
- package/editor.mjs +22 -56
- package/ez.mjs +48 -133
- package/package.json +7 -1
- package/paths.d.mts +24 -0
- package/paths.mjs +103 -0
- package/schema.d.mts +45 -49
- package/schema.mjs +364 -219
- package/session.d.mts +2 -3
- package/session.mjs +3 -5
- package/shape.d.mts +2 -2
- package/shape.mjs +1 -1
- package/signup.mjs +2 -2
- package/types.d.mts +73 -73
- package/update-check.mjs +1 -1
- package/workflow.d.mts +8 -2
- package/workflow.mjs +88 -21
package/workflow.mjs
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
// Workflows (docs/adr/
|
|
1
|
+
// Workflows (docs/adr/0227): a Table's status column as a declared state machine, in
|
|
2
2
|
// `global/workflows/<table>.ts`. Zero dependencies. `readWorkflow` reads the names a file declares without
|
|
3
3
|
// running it, so the contract can type the column; `checkWorkflow` checks what the compiled file describes
|
|
4
4
|
// against the schema it runs on, at Push.
|
|
@@ -183,7 +183,7 @@ function objectEntries(tokens, start) {
|
|
|
183
183
|
}
|
|
184
184
|
|
|
185
185
|
/**
|
|
186
|
-
* What a workflow file declares, read without running it (docs/adr/
|
|
186
|
+
* What a workflow file declares, read without running it (docs/adr/0227): the column, the initial state, the
|
|
187
187
|
* state names and the action names, in the order written. An error says what to write out instead.
|
|
188
188
|
* @type {typeof import("./workflow.d.mts").readWorkflow}
|
|
189
189
|
*/
|
|
@@ -312,6 +312,84 @@ export const labelOf = (name) => {
|
|
|
312
312
|
return spaced.charAt(0).toUpperCase() + spaced.slice(1);
|
|
313
313
|
};
|
|
314
314
|
|
|
315
|
+
/**
|
|
316
|
+
* What `ez global check` can say of a workflow without running it (docs/adr/0227): the names the file writes
|
|
317
|
+
* out (`readWorkflow`) against the schema, in the words a Push refuses them with, so the check is the gate
|
|
318
|
+
* for them too. Null when they hold; what only the running file shows is still the Push's to check.
|
|
319
|
+
* @type {typeof import("./workflow.d.mts").checkWorkflowNames}
|
|
320
|
+
*/
|
|
321
|
+
export function checkWorkflowNames(table, shape, schema) {
|
|
322
|
+
const where = `global/workflows/${table}.ts`;
|
|
323
|
+
const def = schema.tables[table];
|
|
324
|
+
if (!def) return null; // reported as a path problem
|
|
325
|
+
const wrong = columnError(where, table, def, shape.column);
|
|
326
|
+
if (wrong) return wrong;
|
|
327
|
+
for (const name of shape.states) {
|
|
328
|
+
const state = stateError(where, table, def, shape.column, name);
|
|
329
|
+
if (state) return state;
|
|
330
|
+
}
|
|
331
|
+
if (shape.states.length > WORKFLOW_LIMITS.states)
|
|
332
|
+
return `${where}: at most ${WORKFLOW_LIMITS.states} states.`;
|
|
333
|
+
if (!shape.states.includes(shape.initial))
|
|
334
|
+
return `${where}: initial "${shape.initial}" is not one of its states.`;
|
|
335
|
+
const fallback = defaultError(where, table, def, shape.column, shape.initial);
|
|
336
|
+
if (fallback) return fallback;
|
|
337
|
+
if (shape.actions.length + shape.automatic.length > WORKFLOW_LIMITS.actions)
|
|
338
|
+
return `${where}: at most ${WORKFLOW_LIMITS.actions} actions.`;
|
|
339
|
+
for (const name of [...shape.actions, ...shape.automatic]) {
|
|
340
|
+
const action = actionError(where, name);
|
|
341
|
+
if (action) return action;
|
|
342
|
+
}
|
|
343
|
+
return null;
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
// What `ez global check` (checkWorkflowNames) and a Push (checkWorkflow) both say of a name, written once.
|
|
347
|
+
|
|
348
|
+
const NAME_SHAPE = "lowercase letters, digits and _, starting with a letter";
|
|
349
|
+
|
|
350
|
+
/**
|
|
351
|
+
* Why the state column's DEFAULT stands against the workflow (a new row starts in the initial state), or null.
|
|
352
|
+
* @param {string} where @param {string} table @param {Declaration["tables"][string]} def @param {string} column
|
|
353
|
+
* @param {string} initial
|
|
354
|
+
*/
|
|
355
|
+
function defaultError(where, table, def, column, initial) {
|
|
356
|
+
const col = def.columns[column];
|
|
357
|
+
return col?.default && !(col.default.kind === "value" && col.default.value === initial)
|
|
358
|
+
? `${where}: ${table}.${column} has a DEFAULT other than the initial state; remove it.`
|
|
359
|
+
: null;
|
|
360
|
+
}
|
|
361
|
+
|
|
362
|
+
/**
|
|
363
|
+
* Why a column cannot hold a workflow's state, or null.
|
|
364
|
+
* @param {string} where @param {string} table @param {Declaration["tables"][string]} def @param {unknown} column
|
|
365
|
+
*/
|
|
366
|
+
function columnError(where, table, def, column) {
|
|
367
|
+
if (typeof column !== "string" || !Object.hasOwn(def.columns, column))
|
|
368
|
+
return `${where}: column "${String(column)}" is not a column of ${table}.`;
|
|
369
|
+
const col = def.columns[column];
|
|
370
|
+
return col.type !== "TEXT" || col.ref || col.sequence
|
|
371
|
+
? `${where}: ${table}.${column} must be a plain TEXT column to hold a state.`
|
|
372
|
+
: null;
|
|
373
|
+
}
|
|
374
|
+
|
|
375
|
+
/**
|
|
376
|
+
* Why a state's name cannot stand in the column (one `columnError` passed), or null.
|
|
377
|
+
* @param {string} where @param {string} table @param {Declaration["tables"][string]} def
|
|
378
|
+
* @param {string} column @param {string} name
|
|
379
|
+
*/
|
|
380
|
+
function stateError(where, table, def, column, name) {
|
|
381
|
+
const values = def.columns[column].values;
|
|
382
|
+
if (!NAME_RE.test(name))
|
|
383
|
+
return `${where}: state "${name}": ${NAME_SHAPE}${values?.includes(name) ? ` (${table}.${column}'s CHECK list holds it, and a published value cannot change: a workflow needs a column whose values are such names)` : ""}.`;
|
|
384
|
+
return values && !values.includes(name)
|
|
385
|
+
? `${where}: state "${name}" is not one of ${table}.${column}'s CHECK values (${values.join(", ")}).`
|
|
386
|
+
: null;
|
|
387
|
+
}
|
|
388
|
+
|
|
389
|
+
/** Why an action's name cannot stand, or null. @param {string} where @param {string} name */
|
|
390
|
+
const actionError = (where, name) =>
|
|
391
|
+
NAME_RE.test(name) ? null : `${where}: action "${name}": ${NAME_SHAPE}.`;
|
|
392
|
+
|
|
315
393
|
/**
|
|
316
394
|
* Checks what a compiled workflow describes (the artifact's `__describe`) against the published schema and
|
|
317
395
|
* returns its normalised form, or why a Push refuses it.
|
|
@@ -323,11 +401,8 @@ export function checkWorkflow(table, raw, schema) {
|
|
|
323
401
|
if (!def) return { error: `${where}: no Table "${table}" in db/schema.sql.` };
|
|
324
402
|
if (!isObject(raw)) return { error: `${where}: export default workflow<"${table}">({ ... }).` };
|
|
325
403
|
const { column, initial, states, actions } = raw;
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
const col = def.columns[column];
|
|
329
|
-
if (col.type !== "TEXT" || col.ref || col.sequence)
|
|
330
|
-
return { error: `${where}: ${table}.${column} must be a plain TEXT column to hold a state.` };
|
|
404
|
+
const wrongColumn = columnError(where, table, def, column);
|
|
405
|
+
if (wrongColumn || typeof column !== "string") return { error: wrongColumn ?? "" };
|
|
331
406
|
if (!isObject(states) || Object.keys(states).length === 0)
|
|
332
407
|
return { error: `${where}: states names at least one state.` };
|
|
333
408
|
const names = Object.keys(states);
|
|
@@ -336,14 +411,8 @@ export function checkWorkflow(table, raw, schema) {
|
|
|
336
411
|
/** @type {WorkflowMeta["states"]} */
|
|
337
412
|
const outStates = {};
|
|
338
413
|
for (const name of names) {
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
error: `${where}: state "${name}": lowercase letters, digits and _, starting with a letter.`,
|
|
342
|
-
};
|
|
343
|
-
if (col.values && !col.values.includes(name))
|
|
344
|
-
return {
|
|
345
|
-
error: `${where}: state "${name}" is not one of ${table}.${column}'s CHECK values (${col.values.join(", ")}).`,
|
|
346
|
-
};
|
|
414
|
+
const wrongState = stateError(where, table, def, column, name);
|
|
415
|
+
if (wrongState) return { error: wrongState };
|
|
347
416
|
const s = states[name];
|
|
348
417
|
if (s !== undefined && s !== null && !isObject(s))
|
|
349
418
|
return { error: `${where}: state "${name}" is { label?, tone? }.` };
|
|
@@ -360,10 +429,8 @@ export function checkWorkflow(table, raw, schema) {
|
|
|
360
429
|
}
|
|
361
430
|
if (typeof initial !== "string" || !names.includes(initial))
|
|
362
431
|
return { error: `${where}: initial "${String(initial)}" is not one of its states.` };
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
error: `${where}: ${table}.${column} has a DEFAULT other than the initial state; remove it.`,
|
|
366
|
-
};
|
|
432
|
+
const fallback = defaultError(where, table, def, column, initial);
|
|
433
|
+
if (fallback) return { error: fallback };
|
|
367
434
|
if (!isObject(actions)) return { error: `${where}: actions is an object of actions.` };
|
|
368
435
|
if (Object.keys(actions).length > WORKFLOW_LIMITS.actions)
|
|
369
436
|
return { error: `${where}: at most ${WORKFLOW_LIMITS.actions} actions.` };
|
|
@@ -371,8 +438,8 @@ export function checkWorkflow(table, raw, schema) {
|
|
|
371
438
|
const outActions = {};
|
|
372
439
|
for (const [name, a] of Object.entries(actions)) {
|
|
373
440
|
const at = `${where}: action "${name}"`;
|
|
374
|
-
|
|
375
|
-
|
|
441
|
+
const wrongName = actionError(where, name);
|
|
442
|
+
if (wrongName) return { error: wrongName };
|
|
376
443
|
if (!isObject(a)) return { error: `${at} is { from, to, ... }.` };
|
|
377
444
|
if (!isStrings(a.from) || a.from.length === 0)
|
|
378
445
|
return { error: `${at}: from lists the states it runs from.` };
|