footprint

footprint.js — The Flowchart Pattern for Backend Code

footprint.js structures backend logic as a graph of named functions with transactional state. The code becomes self-explainable: every run auto-generates a causal trace of what happened and why.

Core principle: All data collection happens during the single DFS traversal pass — never post-process or walk the tree again.

npm install footprintjs

---

Quick Start

import { flowChart, FlowChartExecutor } from 'footprintjs';

interface OrderState {
  orderId: string;
  amount: number;
  paymentStatus: string;
}

const chart = flowChart<OrderState>('ReceiveOrder', (scope) => {
    scope.orderId = 'ORD-123';
    scope.amount = 49.99;
  }, 'receive-order', { description: 'Receive and validate the incoming order' })
  .addFunction('ProcessPayment', (scope) => {
    const amount = scope.amount;
    scope.paymentStatus = amount < 100 ? 'approved' : 'review';
  }, 'process-payment', 'Charge customer and record payment status')
  .build();

const executor = new FlowChartExecutor(chart);
await executor.run({ input: { orderId: 'ORD-123' } });

console.log(executor.getNarrativeEntries());
// Stage 1: The process began with ReceiveOrder.
//   Step 1: Write orderId = "ORD-123"
//   Step 2: Write amount = 49.99
// Stage 2: Next, it moved on to ProcessPayment.
//   Step 1: Read amount = 49.99
//   Step 2: Write paymentStatus = "approved"

---

FlowChartBuilder API

Always chain from flowChart<T>() (recommended) or flowChart().

Linear Stages

import { flowChart } from 'footprintjs';

interface MyState {
  valueA: string;
  valueB: number;
  valueC: boolean;
}

const chart = flowChart<MyState>('StageA', fnA, 'stage-a', { description: 'Description of A' })
  .addFunction('StageB', fnB, 'stage-b', 'Description of B')
  .addFunction('StageC', fnC, 'stage-c', 'Description of C')
  .build();

Parameters: (name: string, fn: PipelineStageFunction, id: string, description?: string)