tapable-tracer

Trace the connections and flows between
tapable hooks in real-time.

Collect structured stack traces, and optionally export them as UML diagrams.

Table of Contents

- Overview
- Features
- Installation
- Usage
- Initialize Tracer
- Register Hooks
- Export Frames
- Generate UML
- Tracer Internals
- Configuration
- Global Options
- Per-Hook Options
- Technical Details
- Examples
- License

Overview

Have you ever wondered what the internals of webpack look like?
Below is a UML-style representation of webpack's internal hooks captured at
runtime. This diagram was generated using the tapable-tracer and its
webpack plugin by
tracing dynamically every hook tap and call in the system.

media="(prefers-color-scheme: dark)"
srcset="./assets/webpack-graph-dark.svg"
/>
alt="Webpack hook graph generated via tapable-tracer"
src="./assets/webpack-graph-light.svg"
/>

View the full interactive version here:
- Mermaid Chart Playground
- Mermaid Live Editor
- GitHub Mermaid Preview

Features

- Real-time: Observe hooks as they're tapped and called.
- Structured: Frames represent a directed graph.
- Dynamic: No patching or rewriting needed.
- UML Export: Visualize traces via Mermaid diagrams.
- Configurable: Include or exclude the triggers.
- Customizable: Embed information to be visible on diagrams.
- Universal: Works with any tapable-based code, not just webpack.

Installation

``sh
yarn add tapable-tracer
`

Usage

$3

To start tracing hooks, first create a tracer:

`ts
import { createTracer } from "tapable-tracer";

const tracer = createTracer();
`

$3

To capture hook activity, register each hook with the tracer:

`ts
import { traceHook } from "tapable-tracer";

traceHook(tracer, hook1);
traceHook(tracer, hook2);
`

$3

Export the captured frames as encodable array:

`ts
import { dumpStackTrace } from "tapable-tracer";

const frames = dumpStackTrace(tracer.trace);
`

$3

Generate a Mermaid-compatible diagram code:

`ts
import { generateMermaidUML } from "tapable-tracer/extensions/mermaid";

const uml = generateMermaidUML(frames);
`

$3

tapable-tracer exposes its own hooks (via tapable) for further
instrumentation:

- PreCallHook: Before a Tap.fn
called.
- PostCallHook: After a Tap.fn
completes.
- HandleStackFrameHook:
When a new stack frame is emitted.

Configuration

$3

Pass TracerOptions to
createTracer():

The available options are:

- interceptorName (string): Name of the interceptor to use.
- labelHook (HookLabellerFunction):
Function to label hooks.
- labelTap (TapLabellerFunction):
Function to label taps.

$3

Pass HookTracingOptions to
traceHook():

The available options are:

- includeTrigger (boolean): Whether to include the trigger in the trace.
- key (string): The hook's identifier in a container data-structure
inside the system. Also used as the fallback label for the hook.

Technical Details

The tracer captures three different frame types:

- TapFrame: A tap is registered to a hook.
- TriggerFrame: A delegate is called
before the actual Tap.fn.
- CallFrame: A Tap.fn is called.

Additionally, it uses a CallSite context
object per tap, for storing the hook, tap, and the original callback function.

To capture the frames the tracer uses two separate states:

1. Stack: A stack of CallSite objects that represents the current call stack.
2. Trace: A list of frames that represents the entire trace of the flows.

For tracing a hook, the tracer intercepts the hook's tap, call and loop
events.

When a tap is added:

1. A CallSite object is created for further reference.
2. A TapFrame is created and pushed onto the trace list.
3. The tap.fn function is overridden to capture the call events, by keeping
the CallSite object in the closure.

When a call or loop event occurs:

1. Create and push a TriggerFrame onto the trace list, if the
includeTrigger options is set to true for the hook and the
call was caused by a tap.
2. Push the CallSite object onto the stack.
3. Execute the original callback function.
4. Pop the CallSite object from the stack.
5. Create and push a CallFrame onto the trace list.

$3

License

This project is licensed under the
MIT License.
See the LICENSE file for details.