@servicetitan/journey 1.0.0

package/src/core/registry.ts

@@ -0,0 +1,162 @@
+import { defaultRuntime } from './runtime';
+import type {
+    JourneyDef,
+    JourneyEvent,
+    JourneyHandle,
+    JourneySink,
+    JourneyState,
+    JourneyStepOptions,
+    JourneyStepRef,
+    JourneyStepTarget,
+    StepHandle,
+    TagValue,
+} from './types';
+
+export type { JourneyHandle, JourneySink };
+
+/** Look up an open journey by name. */
+export function getOpenJourney(name: string): JourneyState | undefined {
+    return defaultRuntime.getOpenJourney(name);
+}
+
+/** First open journey among `names` (order preserved), or null. */
+export function firstOpenJourney(names: readonly string[]): string | null {
+    return defaultRuntime.firstOpenJourney(names);
+}
+
+/**
+ * Active step for soft-ambient HTTP attribution, or null when 0 or 2+ steps are in flight
+ * app-wide. Untagged traffic is attributed to that lone step even if unrelated — prefer
+ * `step.tag()` when the page has background instrumented requests. Adapters call this when
+ * a request has no explicit stamp.
+ */
+export function activeJourneyStep(): JourneyStepRef | null {
+    return defaultRuntime.activeJourneyStep();
+}
+
+/**
+ * Record a finished backend request against a captured step.
+ * 5xx / network / slow (over threshold) mark Bad; 4xx is not counted. Fail-fast on breach.
+ */
+export function reportBackendRequest(
+    step: JourneyStepRef | undefined,
+    status: number | undefined,
+    durationMs: number,
+    requestKey: string
+): void {
+    defaultRuntime.reportBackendRequest(step, status, durationMs, requestKey);
+}
+
+/**
+ * Run one step of a named journey. Runs untraced (noop handle) when no matching journey is open.
+ * `journey` may be a name, null, or an ordered candidate list.
+ * Prefer `defineJourney(...).step` when you own the journey config.
+ */
+export async function journeyStep<T>(
+    journey: JourneyStepTarget,
+    stepName: string,
+    fn: (step: StepHandle) => T | Promise<T>,
+    opts?: JourneyStepOptions
+): Promise<T> {
+    return defaultRuntime.journeyStep(journey, stepName, fn, opts);
+}
+
+/**
+ * journeyStep deferred by one microtask so a parent `<JourneyScope>` opens first
+ * (React runs child mount effects before parent). Use for mount-effect steps only.
+ */
+export async function journeyMountStep<T>(
+    journey: JourneyStepTarget,
+    stepName: string,
+    fn: (step: StepHandle) => T | Promise<T>,
+    opts?: JourneyStepOptions
+): Promise<T> {
+    return defaultRuntime.journeyMountStep(journey, stepName, fn, opts);
+}
+
+/** Replace the sink list (e.g. host bootstrap or tests). Pass `[]` to disable emission. */
+export function setJourneySinks(next: readonly JourneySink[]): void {
+    defaultRuntime.setSinks(next);
+}
+
+/** Append a sink alongside the current ones. */
+export function addJourneySink(sink: JourneySink): void {
+    defaultRuntime.addSink(sink);
+}
+
+/** Emit a terminal journey event to every configured sink. */
+export function emitJourneyEvent(payload: JourneyEvent): void {
+    defaultRuntime.emit(payload);
+}
+
+/** Merge custom tags onto an open journey. No-op if not open. Prefer `handle.setTags`. */
+export function setJourneyTags(name: string | null, tags: Record<string, TagValue>): void {
+    defaultRuntime.setJourneyTags(name, tags);
+}
+
+/** Begin a journey. Restarts (closes) an already-open journey of the same name. */
+export function startJourney(def: JourneyDef): void {
+    defaultRuntime.startJourney(def);
+}
+
+/** Fail-fast: record reason and emit immediately. Idempotent via `closed`. */
+export function failJourneyNow(journey: JourneyState, reason: string): void {
+    defaultRuntime.failJourneyNow(journey, reason);
+}
+
+/** Mark a named journey Bad for a custom reason (fail-fast). Prefer `handle.fail`. */
+export function failJourney(name: string, reason: string): void {
+    defaultRuntime.failJourney(name, reason);
+}
+
+/** Successful end. Outcome stays Bad if a breach already occurred. No-op when name is null. Prefer `handle.complete`. */
+export function completeJourney(name: string | null, tags?: Record<string, TagValue>): void {
+    defaultRuntime.completeJourney(name, tags);
+}
+
+/** User left before finishing. Stays Bad if a breach already occurred (breach-anchored). Prefer `handle.exclude`. */
+export function excludeJourney(name: string): void {
+    defaultRuntime.excludeJourney(name);
+}
+
+/** Turn a journey config into a handle with bound lifecycle methods. Preferred public API. */
+export function defineJourney(def: JourneyDef): JourneyHandle {
+    const ensureStarted = () => {
+        if (!getOpenJourney(def.name)) {
+            startJourney(def);
+        }
+    };
+
+    const handle: JourneyHandle = {
+        ...def,
+        start(tags) {
+            startJourney(def);
+            if (tags) {
+                setJourneyTags(def.name, tags);
+            }
+        },
+        step(stepName, fn, opts) {
+            ensureStarted();
+            return journeyStep(def.name, stepName, fn, opts);
+        },
+        async mountStep(stepName, fn, opts) {
+            // Defer so a parent <JourneyScope> opens first (child effects run before parent).
+            await Promise.resolve();
+            ensureStarted();
+            return journeyStep(def.name, stepName, fn, opts);
+        },
+        complete(tags) {
+            completeJourney(def.name, tags);
+        },
+        fail(reason) {
+            failJourney(def.name, reason);
+        },
+        exclude() {
+            excludeJourney(def.name);
+        },
+        setTags(tags) {
+            setJourneyTags(def.name, tags);
+        },
+    };
+    return handle;
+}

package/src/core/runtime.ts

@@ -0,0 +1,489 @@
+import {
+    longestEndpointMatch,
+    sortEndpointsByLongestMatch,
+    type AppRequestTimeouts,
+} from '../endpoint-policy';
+import { JourneyStepTag } from './step-tag';
+import type {
+    JourneyDef,
+    JourneyEvent,
+    JourneySink,
+    JourneyState,
+    JourneyStepEvent,
+    JourneyStepOptions,
+    JourneyStepRef,
+    JourneyStepTarget,
+    Outcome,
+    StepHandle,
+    StepRecord,
+    TagValue,
+} from './types';
+
+const DEFAULT_REQUEST_TIMEOUTS: AppRequestTimeouts = { defaultMs: 4_000, endpoints: [] };
+
+const noopStep: StepHandle = {
+    name: null,
+    setAttribute() {},
+    setTags() {},
+    complete() {},
+    fail() {},
+    tag: () => ({}),
+};
+
+function toName(target: string | { readonly name: string }): string {
+    return typeof target === 'string' ? target : target.name;
+}
+
+/** @internal Private — not part of the public package API. */
+export interface JourneyRuntimeOptions {
+    /** Initial sinks. Defaults to `[]` — package bootstrap installs Datadog on the default runtime. */
+    sinks?: readonly JourneySink[];
+    requestTimeouts?: AppRequestTimeouts;
+}
+
+/**
+ * @internal Private — not part of the public package API.
+ * Isolated journey engine (open journeys, ambient steps, sinks, request thresholds).
+ * App code should keep using free helpers (`defineJourney`, `journeyStep`, …) — they
+ * bind to the process default runtime. Prefer `resetJourney()` in tests.
+ */
+export interface JourneyRuntime {
+    getRequestTimeouts(): AppRequestTimeouts;
+    setRequestTimeouts(next: AppRequestTimeouts): void;
+
+    setSinks(next: readonly JourneySink[]): void;
+    addSink(sink: JourneySink): void;
+    emit(payload: JourneyEvent): void;
+
+    getOpenJourney(name: string): JourneyState | undefined;
+    firstOpenJourney(names: readonly string[]): string | null;
+    setJourneyTags(name: string | null, tags: Record<string, TagValue>): void;
+    startJourney(def: JourneyDef): void;
+    failJourneyNow(journey: JourneyState, reason: string): void;
+    failJourney(name: string, reason: string): void;
+    completeJourney(name: string | null, tags?: Record<string, TagValue>): void;
+    excludeJourney(name: string): void;
+
+    activeJourneyStep(): JourneyStepRef | null;
+    journeyStep<T>(
+        journey: JourneyStepTarget,
+        stepName: string,
+        fn: (step: StepHandle) => T | Promise<T>,
+        opts?: JourneyStepOptions
+    ): Promise<T>;
+    journeyMountStep<T>(
+        journey: JourneyStepTarget,
+        stepName: string,
+        fn: (step: StepHandle) => T | Promise<T>,
+        opts?: JourneyStepOptions
+    ): Promise<T>;
+
+    reportBackendRequest(
+        step: JourneyStepRef | undefined,
+        status: number | undefined,
+        durationMs: number,
+        requestKey: string
+    ): void;
+
+    /** Close open journeys, clear ambient steps, restore default timeouts/sinks. */
+    reset(options?: JourneyRuntimeOptions): void;
+}
+
+/**
+ * @internal Private — not part of the public package API.
+ * Build an isolated engine. Rarely needed — apps use the default via free helpers.
+ */
+export function createJourneyRuntime(options: JourneyRuntimeOptions = {}): JourneyRuntime {
+    const journeys = new Map<string, JourneyState>();
+    const inFlight = new Set<StepRecord>();
+    let sinks: JourneySink[] = [...(options.sinks ?? [])];
+    let requestTimeouts: AppRequestTimeouts = {
+        defaultMs: options.requestTimeouts?.defaultMs ?? DEFAULT_REQUEST_TIMEOUTS.defaultMs,
+        endpoints: sortEndpointsByLongestMatch(
+            options.requestTimeouts?.endpoints ?? DEFAULT_REQUEST_TIMEOUTS.endpoints
+        ),
+    };
+
+    function getInFlightSteps(journey: JourneyState): StepRecord[] {
+        const out: StepRecord[] = [];
+        for (const step of inFlight) {
+            if (step.journey === journey) {
+                out.push(step);
+            }
+        }
+        return out;
+    }
+
+    function enterStep(step: StepRecord): void {
+        inFlight.add(step);
+    }
+
+    function leaveStep(step: StepRecord): void {
+        inFlight.delete(step);
+    }
+
+    function clearCountdown(journey: JourneyState): void {
+        if (journey.timer != null) {
+            clearTimeout(journey.timer);
+            journey.timer = null;
+        }
+    }
+
+    function emit(payload: JourneyEvent): void {
+        for (const sink of sinks) {
+            try {
+                sink(payload);
+            } catch {
+                // One sinking throw must not block the remaining sinks.
+            }
+        }
+    }
+
+    function finish(journey: JourneyState, outcome: Outcome, reason?: string): void {
+        if (journey.closed) {
+            return;
+        }
+        journey.closed = true;
+        journeys.delete(journey.name);
+        clearCountdown(journey);
+
+        for (const step of getInFlightSteps(journey)) {
+            if (step.durationMs === 0) {
+                step.durationMs = Math.round(globalThis.performance.now() - step.startedAt);
+            }
+        }
+
+        let finalReason = journey.reason ?? reason;
+        let finalOutcome = outcome;
+        const durationMs = Math.round(globalThis.performance.now() - journey.startedAt);
+        if (journey.timeoutMs > 0 && durationMs > journey.timeoutMs) {
+            finalOutcome = 'bad';
+            finalReason = finalReason ?? 'journey-timeout';
+        }
+
+        const steps: JourneyStepEvent[] = journey.steps.map(s => ({
+            name: s.name,
+            startMs: Math.round(s.startedAt - journey.startedAt),
+            durationMs: s.durationMs,
+            outcome: s.outcome,
+            ...(s.reason ? { reason: s.reason } : {}),
+            ...(s.httpStatus !== undefined ? { httpStatus: s.httpStatus } : {}),
+            ...(Object.keys(s.attributes).length ? { attributes: s.attributes } : {}),
+        }));
+
+        emit({
+            journey: {
+                name: journey.name,
+                team: journey.team,
+                group: journey.group,
+                service: journey.service,
+                outcome: finalOutcome,
+                ...(finalOutcome === 'bad' && finalReason ? { reason: finalReason } : {}),
+                durationMs,
+                steps,
+                ...(journey.expected ? { expected: journey.expected } : {}),
+                ...(Object.keys(journey.tags).length ? { tags: journey.tags } : {}),
+            },
+        });
+    }
+
+    function armCountdown(journey: JourneyState): void {
+        if (journey.timeoutMs <= 0) {
+            return;
+        }
+        journey.timer = setTimeout(() => {
+            finish(journey, 'bad', 'journey-timeout');
+        }, journey.timeoutMs);
+    }
+
+    function resolveRequestTimeoutMs(journey: JourneyState, key: string): number {
+        const own = longestEndpointMatch(journey.endpoints, key);
+        if (own?.timeoutMs) {
+            return own.timeoutMs;
+        }
+
+        const app = longestEndpointMatch(requestTimeouts.endpoints, key);
+        if (app?.timeoutMs) {
+            return app.timeoutMs;
+        }
+
+        if (journey.requestTimeoutMs != null) {
+            return journey.requestTimeoutMs;
+        }
+
+        return requestTimeouts.defaultMs;
+    }
+
+    function shouldIgnoreRequest(journey: JourneyState, key: string): boolean {
+        const own = longestEndpointMatch(journey.endpoints, key);
+        if (own) {
+            return own.ignore === true;
+        }
+        return longestEndpointMatch(requestTimeouts.endpoints, key)?.ignore === true;
+    }
+
+    function resolveJourneyName(journey: JourneyStepTarget): string | null {
+        if (journey == null) {
+            return null;
+        }
+        if (typeof journey === 'string' || !Array.isArray(journey)) {
+            return toName(journey as string | { readonly name: string });
+        }
+        return api.firstOpenJourney(journey.map(toName));
+    }
+
+    function createStepHandle(journeyName: string, step: StepRecord): StepHandle {
+        return {
+            name: journeyName,
+            setAttribute(key, value) {
+                step.attributes[key] = value;
+            },
+            setTags(tags) {
+                api.setJourneyTags(journeyName, tags);
+            },
+            complete(tags) {
+                api.completeJourney(journeyName, tags);
+            },
+            fail(reason) {
+                api.failJourney(journeyName, reason);
+            },
+            // Box in JourneyStepTag — raw StepRecord is circular and blows jQuery/axios deep-merge.
+            tag: () => ({ journeyStep: new JourneyStepTag(step) }),
+        };
+    }
+
+    const api: JourneyRuntime = {
+        getRequestTimeouts() {
+            return requestTimeouts;
+        },
+
+        setRequestTimeouts(next) {
+            requestTimeouts = {
+                ...next,
+                endpoints: sortEndpointsByLongestMatch(next.endpoints),
+            };
+        },
+
+        setSinks(next) {
+            sinks = [...next];
+        },
+
+        addSink(sink) {
+            sinks.push(sink);
+        },
+
+        emit,
+
+        getOpenJourney(name) {
+            return journeys.get(name);
+        },
+
+        firstOpenJourney(names) {
+            for (const name of names) {
+                if (journeys.has(name)) {
+                    return name;
+                }
+            }
+            return null;
+        },
+
+        setJourneyTags(name, tags) {
+            const journey = name ? journeys.get(name) : undefined;
+            if (journey) {
+                Object.assign(journey.tags, tags);
+            }
+        },
+
+        startJourney(def) {
+            const existing = journeys.get(def.name);
+            if (existing) {
+                finish(existing, existing.verdict === 'bad' ? 'bad' : 'excluded');
+            }
+
+            const journey: JourneyState = {
+                name: def.name,
+                team: def.team,
+                group: def.group,
+                service: def.service,
+                verdict: 'good',
+                startedAt: globalThis.performance.now(),
+                timeoutMs: def.timeoutMs ?? 0,
+                stepTimeoutMs: def.stepTimeoutMs,
+                reason: null,
+                steps: [],
+                expected: def.steps ? [...def.steps] : null,
+                tags: { ...(def.tags ?? {}) },
+                requestTimeoutMs: def.requestTimeoutMs,
+                endpoints: sortEndpointsByLongestMatch(def.endpoints),
+                timer: null,
+                closed: false,
+            };
+            journeys.set(def.name, journey);
+            armCountdown(journey);
+        },
+
+        failJourneyNow(journey, reason) {
+            if (journey.closed) {
+                return;
+            }
+            journey.verdict = 'bad';
+            journey.reason ??= reason;
+            finish(journey, 'bad');
+        },
+
+        failJourney(name, reason) {
+            const journey = journeys.get(name);
+            if (journey) {
+                api.failJourneyNow(journey, reason);
+            }
+        },
+
+        completeJourney(name, tags) {
+            if (!name) {
+                return;
+            }
+            if (tags) {
+                api.setJourneyTags(name, tags);
+            }
+            const journey = journeys.get(name);
+            if (journey) {
+                finish(journey, journey.verdict === 'bad' ? 'bad' : 'good');
+            }
+        },
+
+        excludeJourney(name) {
+            const journey = journeys.get(name);
+            if (journey) {
+                finish(journey, journey.verdict === 'bad' ? 'bad' : 'excluded');
+            }
+        },
+
+        activeJourneyStep() {
+            if (inFlight.size !== 1) {
+                return null;
+            }
+            return inFlight.values().next().value ?? null;
+        },
+
+        async journeyStep(journey, stepName, fn, opts) {
+            const journeyName = resolveJourneyName(journey);
+            const open = journeyName ? journeys.get(journeyName) : undefined;
+            if (!open || !journeyName) {
+                return fn(noopStep);
+            }
+
+            const step: StepRecord = {
+                name: stepName,
+                startedAt: globalThis.performance.now(),
+                durationMs: 0,
+                outcome: 'good',
+                attributes: {},
+                journey: open,
+            };
+            open.steps.push(step);
+
+            const handle = createStepHandle(journeyName, step);
+
+            const stepTimeoutMs = opts?.timeoutMs ?? open.stepTimeoutMs ?? 0;
+            let timeoutTimer: ReturnType<typeof setTimeout> | null = null;
+            if (stepTimeoutMs > 0) {
+                timeoutTimer = setTimeout(() => {
+                    if (open.closed) {
+                        return;
+                    }
+                    step.outcome = 'bad';
+                    step.reason ??= 'step-timeout';
+                    step.attributes.timeout_ms ??= stepTimeoutMs;
+                    step.durationMs = Math.round(globalThis.performance.now() - step.startedAt);
+                    api.failJourneyNow(open, 'step-timeout');
+                }, stepTimeoutMs);
+            }
+
+            enterStep(step);
+            try {
+                return await fn(handle);
+            } catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                step.outcome = 'bad';
+                step.reason ??= 'step-error';
+                step.attributes.error ??= message;
+                api.failJourneyNow(open, 'step-error');
+                throw err;
+            } finally {
+                if (timeoutTimer != null) {
+                    clearTimeout(timeoutTimer);
+                }
+                if (step.durationMs === 0) {
+                    step.durationMs = Math.round(globalThis.performance.now() - step.startedAt);
+                }
+                leaveStep(step);
+            }
+        },
+
+        async journeyMountStep(journey, stepName, fn, opts) {
+            await Promise.resolve();
+            return api.journeyStep(journey, stepName, fn, opts);
+        },
+
+        reportBackendRequest(step, status, durationMs, requestKey) {
+            if (!step) {
+                return;
+            }
+            const journey = step.journey;
+            if (journey.closed) {
+                return;
+            }
+            if (shouldIgnoreRequest(journey, requestKey)) {
+                return;
+            }
+
+            const failed = status === undefined || status >= 500;
+            const slow = durationMs > resolveRequestTimeoutMs(journey, requestKey);
+            if (!failed && !slow) {
+                return;
+            }
+
+            const category = failed ? 'request-error' : 'request-latency';
+
+            step.outcome = 'bad';
+            step.reason ??= category;
+            if (failed && status !== undefined) {
+                step.httpStatus = status;
+            }
+
+            api.failJourneyNow(journey, category);
+        },
+
+        reset(next = {}) {
+            for (const journey of [...journeys.values()]) {
+                clearCountdown(journey);
+                journey.closed = true;
+            }
+            journeys.clear();
+            inFlight.clear();
+            sinks = [...(next.sinks ?? [])];
+            requestTimeouts = {
+                defaultMs: next.requestTimeouts?.defaultMs ?? DEFAULT_REQUEST_TIMEOUTS.defaultMs,
+                endpoints: sortEndpointsByLongestMatch(
+                    next.requestTimeouts?.endpoints ?? DEFAULT_REQUEST_TIMEOUTS.endpoints
+                ),
+            };
+        },
+    };
+
+    return api;
+}
+
+/**
+ * @internal Private — not part of the public package API.
+ * Process-wide engine used by free helpers. App code does not need to touch this.
+ */
+export const defaultRuntime: JourneyRuntime = createJourneyRuntime();
+
+/**
+ * Reset the default engine (open journeys, ambient steps, sinks, request thresholds).
+ * Intended for tests — call in `beforeEach` / `afterEach` instead of manual cleanup.
+ */
+export function resetJourney(options?: JourneyRuntimeOptions): void {
+    defaultRuntime.reset(options);
+}

package/src/core/step-tag.ts

@@ -0,0 +1,24 @@
+import type { JourneyStepRef, StepRecord } from './types';
+
+/**
+ * Non-plain wrapper for {@link StepHandle.tag}.
+ *
+ * jQuery `ajaxSetup` / axios `mergeConfig` deep-merge plain objects. A raw
+ * {@link StepRecord} is circular (`step.journey.steps → step`), so putting it
+ * on ajax/axios options causes "Maximum call stack size exceeded". Class
+ * instances are assigned by reference instead of recursed.
+ */
+export class JourneyStepTag {
+    constructor(readonly step: StepRecord) {}
+}
+
+/** Unwrap `step.tag().journeyStep` or a JourneyStepTag / StepRecord stamp. */
+export function resolveJourneyStep(value: unknown): JourneyStepRef | undefined {
+    if (value instanceof JourneyStepTag) {
+        return value.step;
+    }
+    if (value && typeof value === 'object') {
+        return value as JourneyStepRef;
+    }
+    return undefined;
+}