Quick Start

Get a self-documenting pipeline running in 3 steps.

Install

npm pnpm yarn

npm install footprintjs

Copy

pnpm add footprintjs

Copy

yarn add footprintjs

Copy

Full Example

examples/getting-started/quick-start.ts

/**
 * Quick Start — Build, run, and observe your first pipeline in under 5 minutes.
 *
 * Run: npx tsx examples/getting-started/quick-start.ts
 */

import { flowChart, FlowChartExecutor } from 'footprintjs';

// ── 1. Define your state ───────────────────────────────────────────────

interface OrderState {
  orderId: string;
  total: number;
  status?: string;
}

// ── 2. Build your flowchart ────────────────────────────────────────────

const chart = flowChart<OrderState>(
  'ValidateOrder',
  async (scope) => {
    scope.status = scope.total > 0 ? 'valid' : 'invalid';
  },
  'validate',
)
  .addFunction(
    'ProcessPayment',
    async (scope) => {
      scope.status = 'paid';
    },
    'process',
  )
  .build();

// ── 3. Run and observe ─────────────────────────────────────────────────

(async () => {

const executor = new FlowChartExecutor(chart);
executor.enableNarrative();
await executor.run({ input: { orderId: 'ORD-001', total: 49.99 } });

// The narrative generates itself — no manual logging
console.log('=== Narrative ===\n');
for (const line of executor.getNarrativeEntries().map(e => e.text)) {
  console.log(line);
}

// Full state snapshot
console.log('\n=== Final State ===\n');
const snapshot = executor.getSnapshot();
console.log(JSON.stringify(snapshot?.sharedState, null, 2));

})().catch(console.error);

Run it:

npx tsx examples/getting-started/quick-start.ts

Output:

=== Narrative ===

Stage 1: The process began with ValidateOrder.
  Step 1: Write status = "valid"
Stage 2: Next, it moved on to ProcessPayment.
  Step 1: Write status = "paid"

=== Final State ===

{
  "orderId": "ORD-001",
  "total": 49.99,
  "status": "paid"
}

Zero manual logging. The narrative generated itself from your code.

What Just Happened?

1. flowChart<OrderState>() — defined two stages with typed state
2. enableNarrative() — turned on the auto-narrative recorder
3. executor.run() — ran the DFS traversal, collecting data as a side effect
4. getNarrative() — read the collected narrative (no post-processing)

Next Steps

• Key Concepts — understand scope, recorders, and the observer pattern
• Building Blocks — all stage types: deciders, forks, selectors, subflows, loops
• Interactive Playground — run examples live in the browser