@nicholasdigital/flow-metrics

A utility library for tracking asynchronous operation flows with lifecycle events, timing, and metadata.

Installation

npm install @nicholasdigital/flow-metrics

Usage

import FlowMetrics from "@nicholasdigital/flow-metrics";

// Start a flow with a custom logger
await FlowMetrics.begin("user-login", {
  log: { userId: 123 },
  meta: { attempts: 1 },
  timeout: 5000, // 5 second timeout
  logFn: async ({ hash, flowId, event, log, meta, logs }) => {
    console.log(`[${event}] ${hash}:`, log);
  },
});

// Add intermediate logs
await FlowMetrics.log("user-login", { step: "validating" });

// Update metadata
await FlowMetrics.updateMeta("user-login", (meta) => ({
  ...meta,
  validated: true,
}));

// Complete the flow
await FlowMetrics.end("user-login", { log: { success: true } });

// Or mark as failed
await FlowMetrics.fail("user-login", { error: "Invalid credentials" });

API

FlowMetrics.begin(hash, options)

Starts a new flow. Automatically cancels any existing flow with the same hash.

Options:

• log - Initial log data (default: {})
• logFn - Async callback for all flow events (default: no-op)
• meta - Initial metadata object (default: {})
• matcher - Function to match specific flows when multiple share a hash (default: () => true)
• timeout - Milliseconds before auto-timeout (default: 10000, set to 0 to disable)

FlowMetrics.log(hash, log, options)

Adds an intermediate log entry and resets the timeout timer.

Options:

• updater - Function to update metadata: (meta) => newMeta
• event - Custom event name (default: "LOG")
• matcher - Function to match specific flow

FlowMetrics.end(hash, options)

Successfully completes a flow.

Options:

• log - Final log data
• updater - Function to update metadata
• matcher - Function to match specific flow

FlowMetrics.fail(hash, log, options)

Marks a flow as failed.

Options:

• updater - Function to update metadata
• matcher - Function to match specific flow

FlowMetrics.updateMeta(hash, updater, options)

Updates flow metadata without adding a visible log entry.

Events

The logFn callback receives these events:

| Event | Description | |-------|-------------| | BEGIN | Flow started | | LOG | Intermediate log added | | UPDATE_META | Metadata updated | | END | Flow completed successfully | | FAIL | Flow failed | | CANCEL | Flow cancelled (new flow started with same hash) | | TIMEOUT | Flow timed out |

Callback Data

The logFn receives an object with:

{
  hash,      // Flow identifier
  flowId,    // Unique UUID for this flow instance
  event,     // Event type (BEGIN, LOG, END, etc.)
  log,       // Current log entry data
  meta,      // Current metadata
  logs,      // Array of all log entries in this flow
}

Each log entry includes timing:

• _createTime - Moment timestamp
• _createTimeDt - Milliseconds since flow began

Concurrent Flows

Use the matcher option to track multiple concurrent flows with the same hash:

// Start flows for different users
await FlowMetrics.begin("data-fetch", {
  meta: { userId: 1 },
  matcher: (flow) => flow.meta.userId === 1,
});

await FlowMetrics.begin("data-fetch", {
  meta: { userId: 2 },
  matcher: (flow) => flow.meta.userId === 2,
});

// End specific flow
await FlowMetrics.end("data-fetch", {
  matcher: (flow) => flow.meta.userId === 1,
});

License

ISC