ezship 0.1.16 → 0.1.17

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/workflow.mjs CHANGED
@@ -1,4 +1,4 @@
1
- // Workflows (docs/adr/0103): a Table's status column as a declared state machine, in
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/0103): the column, the initial state, the
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
- if (typeof column !== "string" || !Object.hasOwn(def.columns, column))
327
- return { error: `${where}: column "${String(column)}" is not a column of ${table}.` };
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
- if (!NAME_RE.test(name))
340
- return {
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
- if (col.default && !(col.default.kind === "value" && col.default.value === initial))
364
- return {
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
- if (!NAME_RE.test(name))
375
- return { error: `${at}: lowercase letters, digits and _, starting with a letter.` };
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.` };