@pikku/core 0.12.92 → 0.12.94

package/src/wirings/workflow/graph/wire-workflow-graph.ts

@@ -2,12 +2,19 @@ export interface PikkuWorkflowGraphConfig<
   FuncMap extends Record<string, string>,
   T,
 > {
+  /** Keeps the graph in the codebase but out of the build. */
   disabled?: true
+  /** Unique across the project. It is how the graph is started and how its runs are grouped. */
   name?: string
+  /** What the graph does, for whoever is reading it rather than editing it. */
   description?: string
+  /** Filters this graph in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
+  /** The graph's steps, keyed by node id, each naming a function. `pikku meta` lists the names available here. */
   nodes: FuncMap
+  /** Per-node settings — retries, timeouts, the edges between them. */
   config?: T
+  /** Free text carried onto the rendered graph, for a reader who needs the reasoning the shape cannot show. */
   notes?: string[]
 }
 

package/src/wirings/workflow/scenario-cookie-jar.ts

@@ -4,6 +4,12 @@ export interface ScenarioCookieJar {
   readonly empty: boolean
 }
 
+/**
+ * A cookie store for a scenario run, so a step that signs in leaves the session
+ * cookie behind for the steps after it.
+ *
+ * @example snippet: scenarioCookieJar
+ */
 export const createCookieJar = (apiUrl: string): ScenarioCookieJar => {
   const jar = new Map<string, string>()
   const origin = new URL(apiUrl).origin

package/src/wirings/workflow/scenario-poll.ts

@@ -3,6 +3,12 @@ export interface PollOptions {
   intervalMs?: number
 }
 
+/**
+ * Retries an assertion until it passes or the timeout runs out — for the
+ * eventually-consistent parts of a scenario (a queued job, a projection).
+ *
+ * @example snippet: scenarioPolling
+ */
 export const pollUntil = async <T>(
   attempt: () => Promise<T | undefined> | T | undefined,
   { timeoutMs = 15_000, intervalMs = 250 }: PollOptions = {}

package/src/wirings/workflow/scenario-step-guards.ts

@@ -3,6 +3,12 @@ import type {
   ScenarioEnvironment,
 } from './scenario-step.types.js'
 
+/**
+ * The environment the current scenario run targets, or a throw explaining that
+ * the run carries none. Use it in a step that needs the target's URLs.
+ *
+ * @example snippet: scenarioHttpStep
+ */
 export const requireScenarioEnv = (
   scenarioStep: PikkuScenarioStepWire | undefined
 ): ScenarioEnvironment => {

package/src/wirings/workflow/workflow-errors.ts

@@ -15,6 +15,10 @@ export class WorkflowAsyncException extends Error {
   }
 }
 
+/**
+ * Thrown inside a workflow step when the run has been cancelled, so the step
+ * stops rather than finishing work nobody wants.
+ */
 export class WorkflowCancelledException extends Error {
   constructor(
     public readonly runId: string,