@ereo/trace 0.1.28

package/dist/types.d.ts

@@ -0,0 +1,120 @@
+/**
+ * @ereo/trace - Core type definitions
+ *
+ * All interfaces and types for the tracing system.
+ */
+/** 16-byte hex trace identifier */
+export type TraceId = string;
+/** 8-byte hex span identifier */
+export type SpanId = string;
+/** The framework layer a span belongs to */
+export type SpanLayer = 'request' | 'routing' | 'data' | 'forms' | 'signals' | 'rpc' | 'database' | 'auth' | 'islands' | 'build' | 'errors' | 'custom';
+/** Final status of a span */
+export type SpanStatus = 'ok' | 'error' | 'timeout';
+/** A timestamped event within a span */
+export interface SpanEvent {
+    name: string;
+    time: number;
+    attributes?: Record<string, string | number | boolean>;
+}
+/** Completed span data (immutable after end()) */
+export interface SpanData {
+    id: SpanId;
+    traceId: TraceId;
+    parentId: SpanId | null;
+    name: string;
+    layer: SpanLayer;
+    status: SpanStatus;
+    startTime: number;
+    endTime: number;
+    duration: number;
+    attributes: Record<string, string | number | boolean>;
+    events: SpanEvent[];
+    children: SpanId[];
+}
+/** Origin of a trace (server or client) */
+export type TraceOrigin = 'server' | 'client';
+/** Metadata about a trace */
+export interface TraceMetadata {
+    origin: TraceOrigin;
+    method?: string;
+    pathname?: string;
+    statusCode?: number;
+    routePattern?: string;
+}
+/** A complete trace with all its spans */
+export interface TraceData {
+    id: TraceId;
+    rootSpanId: SpanId;
+    startTime: number;
+    endTime: number;
+    duration: number;
+    spans: Map<SpanId, SpanData>;
+    metadata: TraceMetadata;
+}
+/** Active span handle for recording data */
+export interface Span {
+    /** The span's unique ID */
+    readonly id: SpanId;
+    /** The trace this span belongs to */
+    readonly traceId: TraceId;
+    /** Set an attribute on the span */
+    setAttribute(key: string, value: string | number | boolean): void;
+    /** Record a timestamped event */
+    event(name: string, attributes?: Record<string, string | number | boolean>): void;
+    /** End the span (records end time) */
+    end(): void;
+    /** Record an error and set status to 'error' */
+    error(err: unknown): void;
+    /** Create a child span */
+    child(name: string, layer: SpanLayer): Span;
+}
+/** Tracer interface for creating and managing traces */
+export interface Tracer {
+    /** Start a new trace with a root span */
+    startTrace(name: string, layer: SpanLayer, metadata?: Partial<TraceMetadata>): Span;
+    /** Start a new span as a child of the current active span */
+    startSpan(name: string, layer: SpanLayer): Span;
+    /** Get the currently active span, if any */
+    activeSpan(): Span | null;
+    /** Execute a function within a span, automatically ending it on completion */
+    withSpan<T>(name: string, layer: SpanLayer, fn: (span: Span) => T | Promise<T>): T | Promise<T>;
+    /** Get all stored traces */
+    getTraces(): TraceData[];
+    /** Get a single trace by ID */
+    getTrace(id: TraceId): TraceData | undefined;
+    /** Subscribe to trace events */
+    subscribe(cb: (event: TraceStreamEvent) => void): () => void;
+    /** Merge client-side spans into an existing completed trace */
+    mergeClientSpans(traceId: TraceId, spans: SpanData[]): void;
+}
+/** Events emitted by the tracer for live streaming */
+export type TraceStreamEvent = {
+    type: 'trace:start';
+    trace: TraceData;
+} | {
+    type: 'trace:end';
+    trace: TraceData;
+} | {
+    type: 'span:start';
+    span: SpanData;
+} | {
+    type: 'span:end';
+    span: SpanData;
+} | {
+    type: 'span:event';
+    spanId: SpanId;
+    event: SpanEvent;
+};
+/** Configuration for the tracer */
+export interface TracerConfig {
+    /** Maximum number of completed traces to store (default: 200) */
+    maxTraces?: number;
+    /** Maximum spans per trace before capping (default: 500) */
+    maxSpansPerTrace?: number;
+    /** Layers to instrument (default: all) */
+    layers?: SpanLayer[];
+    /** Minimum duration (ms) to record (default: 0) */
+    minDuration?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/viewer.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @ereo/trace - Standalone Trace Viewer
+ *
+ * Self-contained HTML page at `/__ereo/traces`.
+ * Vanilla JS timeline renderer (no React dependency).
+ * Can be exported for sharing/bug reports.
+ */
+import type { Tracer, TraceData } from './types';
+/** Generate the standalone trace viewer HTML */
+export declare function generateViewerHTML(traces: TraceData[]): string;
+/**
+ * Create an HTTP handler that serves the standalone trace viewer.
+ */
+export declare function createViewerHandler(tracer: Tracer): (request: Request) => Response;
+/**
+ * Export traces as a self-contained HTML file string.
+ * For CLI: `ereo trace export > traces.html`
+ */
+export declare function exportTracesHTML(tracer: Tracer): string;
+//# sourceMappingURL=viewer.d.ts.map

package/dist/viewer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewer.d.ts","sourceRoot":"","sources":["../src/viewer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAY,MAAM,SAAS,CAAC;AAG3D,gDAAgD;AAChD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,CA2M9D;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,QAAQ,CAQlF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEvD"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@ereo/trace",
+  "version": "0.1.28",
+  "license": "MIT",
+  "author": "Ereo Team",
+  "homepage": "https://ereo.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ereojs/ereo.git",
+    "directory": "packages/trace"
+  },
+  "bugs": {
+    "url": "https://github.com/ereojs/ereo/issues"
+  },
+  "description": "Full-stack developer observability and tracing for EreoJS framework",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./noop": {
+      "types": "./dist/noop.d.ts",
+      "import": "./dist/noop.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts ./src/noop.ts ./src/client.ts --outdir ./dist --target bun --external @ereo/core && bun run build:types",
+    "build:types": "tsc --emitDeclarationOnly --outDir dist",
+    "dev": "bun build ./src/index.ts ./src/noop.ts ./src/client.ts --outdir ./dist --target bun --watch",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@ereo/core": "^0.1.28"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.1.0",
+    "typescript": "^5.4.0"
+  }
+}