@moostjs/event-wf 0.5.33 → 0.6.0

package/skills/moostjs-event-wf/execution.md

@@ -0,0 +1,325 @@
+# Execution & Lifecycle — @moostjs/event-wf
+
+> Starting and resuming workflows, reading output, pause/resume patterns, error handling, and spies.
+
+## Concepts
+
+Workflows execute via `wf.start()` and produce a `TFlowOutput` describing the result. A workflow can complete, pause for input, or fail. Paused workflows can be resumed from serialized state. Spies observe execution in real time.
+
+## API Reference
+
+### `wf.start<I>(schemaId, initialContext, input?)`
+
+Starts a new workflow execution.
+
+```ts
+start<I>(
+  schemaId: string,
+  initialContext: T,
+  input?: I,
+): Promise<TFlowOutput<T, I, IR>>
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `schemaId` | Workflow identifier (matching `@Workflow` path, including controller prefix) |
+| `initialContext` | Initial context object passed to steps |
+| `input` | Optional input for the first step |
+
+```ts
+const result = await wf.start('process-order', {
+  orderId: '123',
+  status: 'new',
+})
+```
+
+### `wf.resume<I>(state, input?)`
+
+Resumes a paused workflow from a saved state.
+
+```ts
+resume<I>(
+  state: { schemaId: string, context: T, indexes: number[] },
+  input?: I,
+): Promise<TFlowOutput<T, I, IR>>
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `state` | State object from a previous `TFlowOutput.state` |
+| `input` | Input for the paused step |
+
+```ts
+const resumed = await wf.resume(previousResult.state, { answer: 'yes' })
+```
+
+### `wf.attachSpy<I>(fn)`
+
+Attaches a spy function to observe workflow execution. Returns a detach function.
+
+```ts
+const detach = wf.attachSpy((event, eventOutput, flowOutput, ms) => {
+  console.log(event, flowOutput.stepId, ms)
+})
+detach() // stop observing
+```
+
+### `wf.detachSpy<I>(fn)`
+
+Removes a previously attached spy function.
+
+### `wf.getWfApp()`
+
+Returns the underlying `WooksWf` instance for advanced low-level access.
+
+## TFlowOutput
+
+Returned by `start()` and `resume()`. Describes the workflow's current state.
+
+```ts
+interface TFlowOutput<T, I, IR> {
+  state: {
+    schemaId: string      // workflow identifier
+    context: T            // current context (with all mutations)
+    indexes: number[]     // position in schema (for resume)
+  }
+  finished: boolean       // true if workflow completed all steps
+  stepId: string          // last executed step ID
+  inputRequired?: IR      // present when a step needs input
+  interrupt?: boolean     // true when paused (input or retriable error)
+  break?: boolean         // true if a break condition ended the flow
+  resume?: (input: I) => Promise<TFlowOutput<T, unknown, IR>>
+  retry?: (input?: I) => Promise<TFlowOutput<T, unknown, IR>>
+  error?: Error           // error if step threw
+  errorList?: unknown     // structured error details from StepRetriableError
+  expires?: number        // TTL in ms (if set by the step)
+}
+```
+
+Key interpretation:
+- `finished: true` — workflow completed all steps
+- `finished: false` + `interrupt: true` — workflow is paused (input needed or retriable error)
+- `finished: true` + `error` — workflow failed with an unrecoverable error
+
+## Pause & Resume
+
+### Pausing a Workflow
+
+A step pauses the workflow by returning an object with `inputRequired`:
+
+```ts
+@Step('collect-address')
+collectAddress(
+  @WorkflowParam('input') input?: TAddress,
+  @WorkflowParam('context') ctx: TRegistrationContext,
+) {
+  if (!input) {
+    return { inputRequired: true }  // pauses the workflow
+  }
+  ctx.address = input
+}
+```
+
+The `inputRequired` value can be anything — a boolean, a form schema, a structured object. Moost passes it through without interpretation.
+
+### Reading Paused Output
+
+```ts
+const result = await wf.start('registration', initialContext)
+
+if (!result.finished) {
+  console.log(result.interrupt)      // true
+  console.log(result.inputRequired)  // whatever the step returned
+  console.log(result.stepId)         // 'collect-address'
+  console.log(result.state)          // serializable state
+}
+```
+
+### Resuming with Convenience Function
+
+```ts
+if (result.inputRequired && result.resume) {
+  const resumed = await result.resume({ street: '123 Main St', city: 'Springfield' })
+}
+```
+
+### Resuming from Stored State
+
+For workflows that span time, serialize the state and resume later:
+
+```ts
+// Store
+await db.save('pending', { state: result.state, inputRequired: result.inputRequired })
+
+// Later, resume
+const saved = await db.load('pending', workflowId)
+const resumed = await wf.resume(saved.state, userInput)
+```
+
+### Multi-Step Pause/Resume
+
+A workflow can pause and resume multiple times:
+
+```ts
+let result = await wf.start('registration', emptyContext)
+result = await wf.resume(result.state, { name: 'Alice' })
+result = await wf.resume(result.state, { email: 'alice@example.com' })
+result = await wf.resume(result.state, { street: '123 Main' })
+console.log(result.finished) // true
+```
+
+### Expiration
+
+Steps can set an expiration time (in milliseconds) for paused state:
+
+```ts
+@Step('collect-payment')
+collectPayment(@WorkflowParam('input') input?: TPayment) {
+  if (!input) {
+    return { inputRequired: { type: 'payment-form' }, expires: 15 * 60 * 1000 }
+  }
+}
+```
+
+The workflow engine does not enforce expiration — it provides the value for your application to check.
+
+## Error Handling
+
+### Regular Errors
+
+Throwing a standard error fails the workflow immediately:
+
+```ts
+@Step('validate')
+validate(@WorkflowParam('context') ctx: TCtx) {
+  if (!ctx.paymentMethodId) throw new Error('No payment method')
+}
+// Output: { finished: true, error: Error(...) } — no resume/retry available
+```
+
+### StepRetriableError
+
+Signals a recoverable failure. The workflow pauses instead of failing:
+
+```ts
+import { StepRetriableError } from '@moostjs/event-wf'
+
+@Step('charge-card')
+chargeCard(@WorkflowParam('input') input?: TPaymentInput) {
+  try {
+    processPayment(input)
+  } catch (e) {
+    throw new StepRetriableError(
+      e as Error,                                              // original error
+      [{ code: 'CARD_DECLINED', message: 'Card declined' }],  // errorList
+      { type: 'payment-form', hint: 'Try a different card' }, // inputRequired
+    )
+  }
+}
+```
+
+**Constructor:**
+
+```ts
+new StepRetriableError(
+  originalError: Error,       // the underlying error
+  errorList?: unknown,        // structured error details (any shape)
+  inputRequired?: IR,         // what input is needed to retry
+  expires?: number,           // optional TTL in ms
+)
+```
+
+**Retriable output:**
+
+```ts
+{
+  finished: false,       // not done — can be retried
+  interrupt: true,       // execution paused
+  error: Error('...'),
+  errorList: [...],
+  inputRequired: { ... },
+  retry: [Function],     // retry from the same step
+  resume: [Function],    // same as retry for retriable errors
+  state: { ... },
+}
+```
+
+**Retrying:**
+
+```ts
+const result = await wf.start('payment', paymentContext)
+if (result.error && result.retry) {
+  const retried = await result.retry(newPaymentInput)
+}
+// Or from stored state:
+const retried = await wf.resume(result.state, newInput)
+```
+
+### When to Use Which
+
+| Scenario | Approach |
+|----------|----------|
+| Invalid configuration, programming bug | `throw new Error(...)` |
+| External service temporarily unavailable | `throw new StepRetriableError(...)` |
+| User input fails validation | `StepRetriableError` with `errorList` and `inputRequired` |
+| Rate limit hit | `StepRetriableError` with `expires` |
+
+## Spies & Observability
+
+### Attaching a Spy
+
+```ts
+const detach = wf.attachSpy((event, eventOutput, flowOutput, ms) => {
+  console.log(`[${event}] step=${flowOutput.stepId} (${ms}ms)`)
+})
+```
+
+### Spy Callback Signature
+
+```ts
+type TWorkflowSpy<T, I, IR> = (
+  event: string,
+  eventOutput: string | undefined | { fn: string | Function, result: boolean },
+  flowOutput: TFlowOutput<T, I, IR>,
+  ms?: number,
+) => void
+```
+
+### Spy Events
+
+| Event | When | eventOutput |
+|-------|------|-------------|
+| `'workflow-start'` | Workflow begins | `undefined` |
+| `'subflow-start'` | Nested sub-workflow begins | `undefined` |
+| `'step'` | A step finishes executing | Step ID (string) |
+| `'eval-condition-fn'` | Step condition evaluated | `{ fn, result }` |
+| `'eval-while-cond'` | Loop condition evaluated | `{ fn, result }` |
+| `'eval-break-fn'` | Break condition evaluated | `{ fn, result }` |
+| `'eval-continue-fn'` | Continue condition evaluated | `{ fn, result }` |
+| `'workflow-end'` | Workflow completes | `undefined` |
+| `'workflow-interrupt'` | Workflow pauses | `undefined` |
+| `'subflow-end'` | Sub-workflow completes | `undefined` |
+
+### Detaching
+
+```ts
+// Option 1: returned function
+const detach = wf.attachSpy(mySpy)
+detach()
+
+// Option 2: explicit
+wf.detachSpy(mySpy)
+```
+
+## Best Practices
+
+- A `retry()` or `resume()` call re-executes only the paused/failed step and continues — it does not re-run previously completed steps.
+- Keep spy callbacks lightweight — they run synchronously during execution. Buffer heavy processing.
+- The `state` object is plain JSON — safe for serialization, database storage, and API responses.
+- Type the `MoostWf` instance generically (`MoostWf<TMyContext>`) to get typed output.
+
+## Gotchas
+
+- `finished: true` with an `error` means unrecoverable failure (regular `throw`). `finished: false` with `error` means retriable (`StepRetriableError`).
+- The `expires` field is informational — the engine does not enforce it. Your application must check and reject stale resumes.
+- `result.resume` and `result.retry` are convenience functions for in-process use. For cross-process resumption, use `wf.resume(state, input)` instead.

package/skills/moostjs-event-wf/integration.md

@@ -0,0 +1,180 @@
+# Integration — @moostjs/event-wf
+
+> Triggering workflows from HTTP/CLI handlers, using Moost features in steps, and multi-adapter setup.
+
+## Concepts
+
+Workflow steps are regular Moost event handlers. The same interceptor, pipe, and DI mechanisms that work with HTTP and CLI handlers work with workflows. This page covers cross-event-type integration.
+
+## Triggering Workflows from HTTP
+
+```ts
+import { Controller, Param } from 'moost'
+import { Post, Body } from '@moostjs/event-http'
+import { MoostWf } from '@moostjs/event-wf'
+
+interface TTicketContext {
+  ticketId: string
+  description: string
+  status: string
+}
+
+@Controller('tickets')
+export class TicketController {
+  constructor(private wf: MoostWf<TTicketContext>) {}
+
+  @Post()
+  async createTicket(@Body() body: { description: string }) {
+    const result = await this.wf.start('support-ticket', {
+      ticketId: generateId(),
+      description: body.description,
+      status: 'new',
+    })
+    return {
+      ticketId: result.state.context.ticketId,
+      finished: result.finished,
+      inputRequired: result.inputRequired,
+      state: result.finished ? undefined : result.state,
+    }
+  }
+
+  @Post(':id/resume')
+  async resumeTicket(
+    @Param('id') id: string,
+    @Body() body: { state: any, input: any },
+  ) {
+    const result = await this.wf.resume(body.state, body.input)
+    return { ticketId: id, finished: result.finished }
+  }
+}
+```
+
+The workflow state is plain JSON — return it directly to clients or store in a database.
+
+## Triggering Workflows from CLI
+
+```ts
+import { Controller } from 'moost'
+import { Cli, CliOption } from '@moostjs/event-cli'
+import { MoostWf } from '@moostjs/event-wf'
+
+@Controller()
+export class DeployCommand {
+  constructor(private wf: MoostWf) {}
+
+  @Cli('deploy :env')
+  async deploy(
+    @Param('env') env: string,
+    @CliOption('dry-run', 'Simulate without applying') dryRun?: boolean,
+  ) {
+    const result = await this.wf.start('deploy', {
+      environment: env,
+      dryRun: !!dryRun,
+    })
+    return result.finished
+      ? `Deployed to ${env} successfully`
+      : `Deploy paused: ${JSON.stringify(result.inputRequired)}`
+  }
+}
+```
+
+## Multi-Adapter Setup
+
+Register both adapters in a single application:
+
+```ts
+import { Moost } from 'moost'
+import { MoostHttp } from '@moostjs/event-http'
+import { MoostWf } from '@moostjs/event-wf'
+
+const app = new Moost()
+
+app.adapter(new MoostHttp()).listen(3000)
+app.adapter(new MoostWf())
+
+app.registerControllers(
+  TicketController,      // HTTP handlers
+  TicketWfController,    // Workflow steps
+).init()
+```
+
+## Interceptors on Workflow Steps
+
+Use `@Intercept` for pre/post logic on steps:
+
+```ts
+import { Intercept } from 'moost'
+
+@Controller()
+export class TicketWfController {
+  @Step('assign')
+  @Intercept(LogStepExecution)
+  assign(@WorkflowParam('context') ctx: TTicketContext) {
+    ctx.assignee = findAvailableAgent()
+  }
+}
+```
+
+All interceptor priority levels work — guards, error handlers, `AFTER_ALL` cleanup. Global interceptors registered with Moost also apply to workflow steps.
+
+## Pipes for Validation
+
+Use `@Pipe` to transform or validate data flowing into steps:
+
+```ts
+import { Pipe } from 'moost'
+
+@Step('process-data')
+processData(
+  @WorkflowParam('input')
+  @Pipe(validateInput)
+  input: TProcessInput,
+) {
+  // input is validated before reaching this point
+}
+```
+
+## Dependency Injection
+
+Workflow controllers support the same DI as the rest of Moost:
+
+```ts
+@Injectable('FOR_EVENT')
+@Controller()
+export class TicketWfController {
+  constructor(
+    private emailService: EmailService,
+    private ticketRepo: TicketRepository,
+  ) {}
+
+  @Step('notify-assignee')
+  async notifyAssignee(@WorkflowParam('context') ctx: TTicketContext) {
+    await this.emailService.send(ctx.assignee!, `Ticket ${ctx.ticketId} assigned`)
+  }
+
+  @Step('save-ticket')
+  async saveTicket(@WorkflowParam('context') ctx: TTicketContext) {
+    await this.ticketRepo.update(ctx.ticketId, { status: ctx.status })
+  }
+}
+```
+
+## Accessing the Underlying WooksWf
+
+For advanced scenarios:
+
+```ts
+const wf = new MoostWf()
+const wooksWf = wf.getWfApp()
+```
+
+## Best Practices
+
+- Inject `MoostWf` via constructor DI to use it from HTTP/CLI controllers — the adapter instance is registered in the DI container.
+- Keep workflow controllers separate from HTTP/CLI controllers for clarity, even though they can be combined.
+- Global interceptors apply to all event types uniformly — use `contextType` checks if you need event-type-specific behavior.
+
+## Gotchas
+
+- When using `MoostWf` from a constructor-injected service, ensure `app.init()` has been called before starting workflows — steps must be registered first.
+- The adapter name is `'workflow'` (`wf.name === 'workflow'`).

package/skills/moostjs-event-wf/schemas.md

@@ -0,0 +1,203 @@
+# Schemas & Flow Control — @moostjs/event-wf
+
+> Defining step sequences, conditional execution, loops, break/continue, and nested sub-workflows.
+
+## Concepts
+
+A workflow schema is an array attached to a `@Workflow` entry point via `@WorkflowSchema`. It declares which steps run, in what order, and under what conditions. Schemas support linear sequences, conditional steps, loops, break/continue flow control, and nesting.
+
+## Linear Schemas
+
+The simplest schema is a flat list of step IDs:
+
+```ts
+@Workflow('deploy')
+@WorkflowSchema(['build', 'test', 'publish'])
+deploy() {}
+```
+
+Steps run one after another in order.
+
+## Conditional Steps
+
+Add a `condition` to run a step only when it evaluates to `true`:
+
+```ts
+@WorkflowSchema<TCampaignContext>([
+  'prepare-audience',
+  { condition: (ctx) => ctx.audienceSize > 0, id: 'request-approval' },
+  { condition: (ctx) => ctx.approved, id: 'send-emails' },
+  'generate-report',
+])
+```
+
+If a condition returns `false`, that step is skipped and execution continues.
+
+## String Conditions
+
+Conditions can be strings evaluated against the workflow context using a `with(ctx)` scope. This makes them serializable for database storage:
+
+```ts
+@WorkflowSchema<TCampaignContext>([
+  'prepare-audience',
+  { condition: 'audienceSize > 0', id: 'request-approval' },
+  { condition: 'approved', id: 'send-emails' },
+])
+```
+
+String conditions reference context fields directly: `'amount > 100'`, `'status === "active"'`, etc. They are evaluated using `new Function()` with context properties as globals.
+
+## Loops
+
+Use `while` with a nested `steps` array to repeat steps until the condition becomes `false`:
+
+```ts
+@WorkflowSchema<TContext>([
+  {
+    while: (ctx) => !ctx.sent && ctx.retries < 3,
+    steps: ['attempt-send', 'increment-retries'],
+  },
+  { condition: (ctx) => !ctx.sent, id: 'log-failure' },
+])
+```
+
+The `while` condition (function or string) is checked before each iteration.
+
+## Break and Continue
+
+Inside a loop's `steps` array:
+
+```ts
+@WorkflowSchema<TProcessContext>([
+  {
+    while: 'running',
+    steps: [
+      'check-temperature',
+      { break: 'temperature > safeLimit' },   // exits the loop
+      'process-batch',
+      { continue: 'skipCooling' },             // skips to next iteration
+      'cool-down',
+    ],
+  },
+  'shutdown',
+])
+```
+
+- **`break`** — exits the loop immediately when the condition is `true`
+- **`continue`** — skips remaining steps in the current iteration and starts the next one
+
+Both accept function or string conditions.
+
+## Nested Sub-Workflows
+
+Group steps with a `steps` array without `while` to apply a shared condition to a block:
+
+```ts
+@WorkflowSchema<TCampaignContext>([
+  'prepare-audience',
+  {
+    condition: (ctx) => ctx.audienceSize > 1000,
+    steps: ['segment-audience', 'schedule-batches', 'warm-up-ips'],
+  },
+  'send-emails',
+])
+```
+
+## Input in Schema
+
+Pass input to a specific step directly from the schema:
+
+```ts
+@WorkflowSchema([
+  { id: 'notify', input: { channel: 'email' } },
+  { id: 'notify', input: { channel: 'sms' } },
+])
+```
+
+The step receives this via `@WorkflowParam('input')`.
+
+## Schema Type Reference
+
+A schema is an array of items (`TWorkflowSchema<T>`). Each item can be:
+
+| Form | Description |
+|------|-------------|
+| `'stepId'` | Run the step unconditionally |
+| `{ id: 'stepId' }` | Run the step (same as string form) |
+| `{ id: 'stepId', condition: fn \| string }` | Run only if condition passes |
+| `{ id: 'stepId', input: value }` | Run with specific input |
+| `{ steps: [...] }` | Nested group of steps |
+| `{ steps: [...], condition: fn \| string }` | Conditional group |
+| `{ steps: [...], while: fn \| string }` | Loop until condition is false |
+| `{ break: fn \| string }` | Exit enclosing loop if condition passes |
+| `{ continue: fn \| string }` | Skip to next loop iteration if condition passes |
+
+## TypeScript Types
+
+```ts
+type TWorkflowSchema<T> = TWorkflowItem<T>[]
+
+type TWorkflowItem<T> =
+  | string                              // simple step ID
+  | TWorkflowStepSchemaObj<T, any>      // step with condition/input
+  | TSubWorkflowSchemaObj<T>            // nested steps
+  | TWorkflowControl<T>                 // break or continue
+
+interface TWorkflowStepSchemaObj<T, I> {
+  id: string
+  condition?: string | ((ctx: T) => boolean | Promise<boolean>)
+  input?: I
+}
+
+interface TSubWorkflowSchemaObj<T> {
+  steps: TWorkflowSchema<T>
+  condition?: string | ((ctx: T) => boolean | Promise<boolean>)
+  while?: string | ((ctx: T) => boolean | Promise<boolean>)
+}
+
+type TWorkflowControl<T> =
+  | { continue: string | ((ctx: T) => boolean | Promise<boolean>) }
+  | { break: string | ((ctx: T) => boolean | Promise<boolean>) }
+```
+
+## Common Patterns
+
+### Pattern: Retry Loop with Break
+
+```ts
+@WorkflowSchema<TContext>([
+  {
+    while: (ctx) => ctx.attempts < ctx.maxAttempts,
+    steps: [
+      'attempt-operation',
+      { break: 'succeeded' },
+      'wait-before-retry',
+    ],
+  },
+  { condition: (ctx) => ctx.succeeded, id: 'report-success' },
+  { condition: (ctx) => !ctx.succeeded, id: 'escalate-failure' },
+])
+```
+
+### Pattern: Type-Safe Conditions
+
+Pass your context type as a generic to get autocomplete and compile-time checks on conditions:
+
+```ts
+@WorkflowSchema<TOnboardingContext>([
+  'verify-email',
+  { condition: (ctx) => ctx.emailVerified, id: 'collect-profile' },  // ctx is typed
+  { condition: (ctx) => ctx.profileComplete, id: 'send-welcome' },
+])
+```
+
+## Best Practices
+
+- Use function conditions for type safety; use string conditions when schemas are stored in a database.
+- Keep schemas flat when possible — deep nesting reduces readability.
+- The `@Workflow` entry point method body should be empty — all logic lives in the steps.
+
+## Gotchas
+
+- String conditions are evaluated with `new Function()` and `with(ctx)`. Only context properties are available as globals — no access to imports or closures.
+- Condition functions can be async (return `Promise<boolean>`).