chrome-trace-event 1.0.4: Tracer

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify Tracer in pkg:npm/chrome-trace-event@1.0.4
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/chrome-trace-event@1.0.4
Demonstrate these symbols/APIs:
  - Tracer

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:8961076245803a61d270af7876e8eb0a1b87aeadfcfd04805f7a5cb23e2e3aeb","contract":["Tracer stream in objectMode emits begin, end, completeEvent, and instantEvent Trace Event objects with ts, pid, tid, and ph properties","Tracer child instance inherits parent tracer push stream target and fields","Tracer in noStream mode buffers events until flush is invoked and outputs valid Trace Event JSON array","Tracer constructor validates option types and throws Error on non-object options or non-boolean objectMode"],"goal":"verify Tracer in pkg:npm/chrome-trace-event@1.0.4","kind":"HOW","packages":["pkg:npm/chrome-trace-event@1.0.4"],"schemaVersion":1,"symbols":["Tracer"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/chrome-trace-event@1.0.4"],"schemaVersion":1,"subject":"pkg:npm/chrome-trace-event@1.0.4","symbols":["Tracer"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-chrome-trace-event-tracer",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-chrome-trace-event-tracer",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "chrome-trace-event": "1.0.4"
      }
    },
    "node_modules/chrome-trace-event": {
      "version": "1.0.4",
      "resolved": "https://registry.npmjs.org/chrome-trace-event/-/chrome-trace-event-1.0.4.tgz",
      "integrity": "sha512-rNjApaLzuwaOTjCiT8lSDdGN1APCiqkChLMJxJPWLunPAt5fy8xgU9/jNOchV84wfIxrA0lRQB7oCT8jrn/wrQ==",
      "license": "MIT",
      "engines": {
        "node": ">=6.0"
      }
    }
  }
}

{
  "name": "sample-chrome-trace-event-tracer",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "chrome-trace-event": "1.0.4"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify Tracer in pkg:npm/chrome-trace-event@1.0.4",
  "kind": "HOW",
  "packages": [
    "pkg:npm/chrome-trace-event@1.0.4"
  ],
  "symbols": [
    "Tracer"
  ]
}

import chromeTraceEvent from "chrome-trace-event";
const { Tracer } = chromeTraceEvent;

/**
 * Creates a new Tracer stream in objectMode for receiving event objects directly.
 * @param {object} [opts]
 * @returns {Tracer}
 */
export function createObjectTracer(opts = {}) {
  return new Tracer({
    objectMode: true,
    ...opts
  });
}

/**
 * Creates a new Tracer stream in noStream mode that buffers events until flush().
 * @param {object} [opts]
 * @returns {Tracer}
 */
export function createBufferedTracer(opts = {}) {
  return new Tracer({
    noStream: true,
    ...opts
  });
}

/**
 * Creates a child tracer from an existing tracer.
 * @param {Tracer} parentTracer
 * @param {object} [fields]
 * @returns {Tracer}
 */
export function createChildTracer(parentTracer, fields = {}) {
  return parentTracer.child(fields);
}

/**
 * Records a complete trace cycle with begin and end events.
 * @param {Tracer} tracer
 * @param {string} name
 * @param {string[]} [categories]
 * @param {object} [args]
 */
export function recordTraceSpan(tracer, name, categories = ["default"], args = {}) {
  tracer.begin({ name, cat: categories, args });
  tracer.end({ name, cat: categories, args });
}

/**
 * Records an instant marker event.
 * @param {Tracer} tracer
 * @param {string} name
 * @param {object} [args]
 */
export function recordInstantMarker(tracer, name, args = {}) {
  tracer.instantEvent({ name, args });
}

/**
 * Records a complete event with explicit duration.
 * @param {Tracer} tracer
 * @param {string} name
 * @param {number} dur
 * @param {object} [args]
 */
export function recordCompleteSpan(tracer, name, dur, args = {}) {
  tracer.completeEvent({ name, dur, args });
}

import assert from "node:assert/strict";
import chromeTraceEvent from "chrome-trace-event";
const { Tracer } = chromeTraceEvent;
import {
  createObjectTracer,
  createBufferedTracer,
  createChildTracer,
  recordTraceSpan,
  recordInstantMarker,
  recordCompleteSpan
} from "../src/index.mjs";

// Test 1: Tracer in objectMode streams begin, end, completeEvent, and instantEvent Trace Event objects with ts, pid, tid, and ph properties
{
  const tracer = createObjectTracer();
  const events = [];
  tracer.on("data", (event) => events.push(event));

  recordTraceSpan(tracer, "renderTask", ["ui"], { frame: 1 });
  recordInstantMarker(tracer, "layoutCheck", { reflow: false });
  recordCompleteSpan(tracer, "paint", 1500, { layer: "canvas" });

  tracer.push(null);
  await new Promise((resolve) => tracer.on("end", resolve));

  assert.equal(events.length, 4);

  // begin event
  assert.equal(events[0].ph, "B");
  assert.equal(events[0].name, "renderTask");
  assert.equal(events[0].cat, "ui");
  assert.equal(events[0].args.frame, 1);
  assert.equal(typeof events[0].ts, "number");
  assert.equal(typeof events[0].pid, "number");
  assert.equal(typeof events[0].tid, "number");

  // end event
  assert.equal(events[1].ph, "E");
  assert.equal(events[1].name, "renderTask");
  assert.equal(events[1].cat, "ui");
  assert.equal(events[1].args.frame, 1);

  // instant event
  assert.equal(events[2].ph, "I");
  assert.equal(events[2].name, "layoutCheck");
  assert.equal(events[2].args.reflow, false);

  // complete event
  assert.equal(events[3].ph, "X");
  assert.equal(events[3].name, "paint");
  assert.equal(events[3].dur, 1500);
  assert.equal(events[3].args.layer, "canvas");
}

// Test 2: Tracer child creates child tracer inheriting parent push stream and fields
{
  const rootTracer = createObjectTracer({ fields: { cat: ["root"] } });
  const events = [];
  rootTracer.on("data", (event) => events.push(event));

  const childTracer = createChildTracer(rootTracer, { module: "network" });
  childTracer.begin({ name: "fetchRequest", cat: ["http"] });
  childTracer.instantEvent({ name: "headersReceived", status: 200 });
  childTracer.end({ name: "fetchRequest", cat: ["http"] });

  rootTracer.push(null);
  await new Promise((resolve) => rootTracer.on("end", resolve));

  assert.equal(events.length, 3);
  assert.equal(events[0].ph, "B");
  assert.equal(events[0].name, "fetchRequest");
  assert.equal(events[0].cat, "http");
  assert.equal(events[1].ph, "I");
  assert.equal(events[1].name, "headersReceived");
  assert.equal(events[1].status, 200);
  assert.equal(events[2].ph, "E");
  assert.equal(events[2].name, "fetchRequest");
}

// Test 3: Tracer with noStream: true buffers events and formats standard Trace Event JSON array upon flush()
{
  const bufferedTracer = createBufferedTracer();
  const chunks = [];
  bufferedTracer.on("data", (chunk) => chunks.push(chunk));

  bufferedTracer.begin({ name: "batchJob", cat: ["batch"] });
  bufferedTracer.instantEvent({ name: "step1" });
  bufferedTracer.end({ name: "batchJob", cat: ["batch"] });

  // No chunks pushed before flush
  assert.equal(chunks.length, 0);

  bufferedTracer.flush();
  bufferedTracer.push(null);
  await new Promise((resolve) => bufferedTracer.on("end", resolve));

  const jsonOutput = chunks.join("");
  assert.ok(jsonOutput.startsWith("["));
  assert.ok(jsonOutput.endsWith("]"));

  const parsedEvents = JSON.parse(jsonOutput);
  assert.equal(parsedEvents.length, 3);
  assert.equal(parsedEvents[0].ph, "B");
  assert.equal(parsedEvents[0].name, "batchJob");
  assert.equal(parsedEvents[1].ph, "I");
  assert.equal(parsedEvents[1].name, "step1");
  assert.equal(parsedEvents[2].ph, "E");
  assert.equal(parsedEvents[2].name, "batchJob");
}

// Test 4: Tracer constructor validates option types and throws on invalid options
{
  assert.throws(() => new Tracer("invalid-option-string"), {
    message: "Invalid options passed (must be an object)"
  });

  assert.throws(() => new Tracer({ parent: "not-an-object" }), {
    message: "Invalid option (parent) passed (must be an object)"
  });

  assert.throws(() => new Tracer({ fields: 12345 }), {
    message: "Invalid option (fields) passed (must be an object)"
  });

  assert.throws(() => new Tracer({ objectMode: "not-a-boolean" }), {
    message: "Invalid option (objectsMode) passed (must be a boolean)"
  });
}

console.log("All pkg:npm/chrome-trace-event@1.0.4 contract assertions passed.");