live-traces 0.1.0

package/dist/src/types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * live-traces — Wire Format Types
+ *
+ * Plain TypeScript types with zero dependencies.
+ * Any backend (Go, Python, Rust, Node) can emit these as JSON
+ * and the React frontend will render them.
+ *
+ * Import from "live-traces/types" — no Effect required.
+ */
+export interface TraceScope {
+    readonly type: "team" | "org" | "user";
+    readonly id: string;
+}
+export interface TraceStart {
+    readonly _tag: "TraceStart";
+    readonly traceId: string;
+    readonly label: string;
+    readonly scope: TraceScope;
+    readonly timestamp: number;
+}
+export interface SpanStart {
+    readonly _tag: "SpanStart";
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly parentSpanId?: string | undefined;
+    readonly name: string;
+    readonly attributes: Record<string, unknown>;
+    readonly timestamp: number;
+}
+export interface SpanEnd {
+    readonly _tag: "SpanEnd";
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly status: "ok" | "error";
+    readonly durationMs: number;
+    readonly timestamp: number;
+}
+export interface SpanEvent {
+    readonly _tag: "SpanEvent";
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly name: string;
+    readonly level?: "Debug" | "Info" | "Warning" | "Error" | undefined;
+    readonly attributes?: Record<string, unknown> | undefined;
+    readonly timestamp: number;
+}
+export interface TraceEnd {
+    readonly _tag: "TraceEnd";
+    readonly traceId: string;
+    readonly status: "completed" | "failed";
+    readonly durationMs: number;
+    readonly error?: string | undefined;
+    readonly timestamp: number;
+}
+export type TraceEvent = TraceStart | SpanStart | SpanEnd | SpanEvent | TraceEnd;
+export declare const traceStart: (traceId: string, label: string, scope: TraceScope) => TraceStart;
+export declare const spanStart: (traceId: string, spanId: string, name: string, attributes?: Record<string, unknown>, parentSpanId?: string) => SpanStart;
+export declare const spanEnd: (traceId: string, spanId: string, status: "ok" | "error", durationMs: number) => SpanEnd;
+export declare const spanEvent: (traceId: string, spanId: string, name: string, level?: "Debug" | "Info" | "Warning" | "Error", attributes?: Record<string, unknown>) => SpanEvent;
+export declare const traceEnd: (traceId: string, status: "completed" | "failed", durationMs: number, error?: string) => TraceEnd;
+/** Mark a span as a user-visible step in the trace UI */
+export declare const UI_STEP: "ui.step";
+/** Mark a span as internal (excluded from live trace capture) */
+export declare const TRACE_INTERNAL: "trace.internal";
+/** Root marker — set automatically by LiveTrace.withTrace() */
+export declare const LIVE_TRACE: "live-trace";
+export declare const LIVE_TRACE_ID: "live-trace.id";
+export declare const LIVE_TRACE_LABEL: "live-trace.label";
+export declare const LIVE_TRACE_SCOPE_TYPE: "live-trace.scope.type";
+export declare const LIVE_TRACE_SCOPE_ID: "live-trace.scope.id";
+/** Optional provider key for source/integration filtering (e.g. "notion", "google-drive") */
+export declare const LIVE_TRACE_PROVIDER: "live-trace.provider";
+//# sourceMappingURL=types.d.ts.map

package/dist/src/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/src/types.js

@@ -0,0 +1,69 @@
+/**
+ * live-traces — Wire Format Types
+ *
+ * Plain TypeScript types with zero dependencies.
+ * Any backend (Go, Python, Rust, Node) can emit these as JSON
+ * and the React frontend will render them.
+ *
+ * Import from "live-traces/types" — no Effect required.
+ */
+// ============================================================================
+// Factory helpers — plain functions, no Effect import
+// ============================================================================
+export const traceStart = (traceId, label, scope) => ({
+    _tag: "TraceStart",
+    traceId,
+    label,
+    scope,
+    timestamp: Date.now(),
+});
+export const spanStart = (traceId, spanId, name, attributes = {}, parentSpanId) => ({
+    _tag: "SpanStart",
+    traceId,
+    spanId,
+    parentSpanId,
+    name,
+    attributes,
+    timestamp: Date.now(),
+});
+export const spanEnd = (traceId, spanId, status, durationMs) => ({
+    _tag: "SpanEnd",
+    traceId,
+    spanId,
+    status,
+    durationMs,
+    timestamp: Date.now(),
+});
+export const spanEvent = (traceId, spanId, name, level, attributes) => ({
+    _tag: "SpanEvent",
+    traceId,
+    spanId,
+    name,
+    level,
+    attributes,
+    timestamp: Date.now(),
+});
+export const traceEnd = (traceId, status, durationMs, error) => ({
+    _tag: "TraceEnd",
+    traceId,
+    status,
+    durationMs,
+    error,
+    timestamp: Date.now(),
+});
+// ============================================================================
+// Attribute constants — use with Effect.withSpan
+// ============================================================================
+/** Mark a span as a user-visible step in the trace UI */
+export const UI_STEP = "ui.step";
+/** Mark a span as internal (excluded from live trace capture) */
+export const TRACE_INTERNAL = "trace.internal";
+/** Root marker — set automatically by LiveTrace.withTrace() */
+export const LIVE_TRACE = "live-trace";
+export const LIVE_TRACE_ID = "live-trace.id";
+export const LIVE_TRACE_LABEL = "live-trace.label";
+export const LIVE_TRACE_SCOPE_TYPE = "live-trace.scope.type";
+export const LIVE_TRACE_SCOPE_ID = "live-trace.scope.id";
+/** Optional provider key for source/integration filtering (e.g. "notion", "google-drive") */
+export const LIVE_TRACE_PROVIDER = "live-trace.provider";
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA+DH,+EAA+E;AAC/E,sDAAsD;AACtD,+EAA+E;AAE/E,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,OAAe,EAAE,KAAa,EAAE,KAAiB,EAAc,EAAE,CAAC,CAAC;IAC1F,IAAI,EAAE,YAAY;IAClB,OAAO;IACP,KAAK;IACL,KAAK;IACL,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;CACxB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,SAAS,GAAG,CACrB,OAAe,EACf,MAAc,EACd,IAAY,EACZ,aAAsC,EAAE,EACxC,YAAqB,EACZ,EAAE,CAAC,CAAC;IACb,IAAI,EAAE,WAAW;IACjB,OAAO;IACP,MAAM;IACN,YAAY;IACZ,IAAI;IACJ,UAAU;IACV,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;CACxB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,OAAe,EAAE,MAAc,EAAE,MAAsB,EAAE,UAAkB,EAAW,EAAE,CAAC,CAAC;IAC9G,IAAI,EAAE,SAAS;IACf,OAAO;IACP,MAAM;IACN,MAAM;IACN,UAAU;IACV,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;CACxB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,SAAS,GAAG,CACrB,OAAe,EACf,MAAc,EACd,IAAY,EACZ,KAA8C,EAC9C,UAAoC,EAC3B,EAAE,CAAC,CAAC;IACb,IAAI,EAAE,WAAW;IACjB,OAAO;IACP,MAAM;IACN,IAAI;IACJ,KAAK;IACL,UAAU;IACV,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;CACxB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,OAAe,EAAE,MAA8B,EAAE,UAAkB,EAAE,KAAc,EAAY,EAAE,CAAC,CAAC;IACxH,IAAI,EAAE,UAAU;IAChB,OAAO;IACP,MAAM;IACN,UAAU;IACV,KAAK;IACL,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;CACxB,CAAC,CAAC;AAEH,+EAA+E;AAC/E,iDAAiD;AACjD,+EAA+E;AAE/E,yDAAyD;AACzD,MAAM,CAAC,MAAM,OAAO,GAAG,SAAkB,CAAC;AAE1C,iEAAiE;AACjE,MAAM,CAAC,MAAM,cAAc,GAAG,gBAAyB,CAAC;AAExD,+DAA+D;AAC/D,MAAM,CAAC,MAAM,UAAU,GAAG,YAAqB,CAAC;AAChD,MAAM,CAAC,MAAM,aAAa,GAAG,eAAwB,CAAC;AACtD,MAAM,CAAC,MAAM,gBAAgB,GAAG,kBAA2B,CAAC;AAC5D,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAgC,CAAC;AACtE,MAAM,CAAC,MAAM,mBAAmB,GAAG,qBAA8B,CAAC;AAClE,6FAA6F;AAC7F,MAAM,CAAC,MAAM,mBAAmB,GAAG,qBAA8B,CAAC"}

package/index.ts

@@ -0,0 +1,58 @@
+/**
+ * live-traces
+ *
+ * Real-time Effect span streaming to frontend UIs.
+ *
+ * Sub-exports:
+ * - "live-traces"        — Effect Tracer decorator (this file)
+ * - "live-traces/types"  — Plain TS types, zero deps
+ * - "live-traces/react"  — React store + hooks, no Effect dep
+ */
+
+// Core tracer
+export { LiveTraceLayer } from "./src/Tracer.js";
+
+// User-facing API
+export { withTrace, step, LiveSpanRef, type LiveTraceConfig } from "./src/LiveTrace.js";
+
+// Logger (bridges Effect.log → SpanEvent inside traced scopes)
+export { liveTraceLogger } from "./src/Logger.js";
+
+// Sink + transport
+export {
+    TraceSink,
+    TraceSinkLive,
+    TraceTransportTag,
+    ConsoleTransportLayer,
+    type TraceTransport,
+    type TraceSinkHandle,
+    type TraceSinkConfig,
+} from "./src/Sink.js";
+
+// WrappedSpan (for advanced use / testing)
+export { WrappedSpan, isWrappedSpan, LiveTraceSymbol } from "./src/WrappedSpan.js";
+
+// Effect Schemas
+export {
+    TraceEventSchema,
+    TraceStartSchema,
+    SpanStartSchema,
+    SpanEndSchema,
+    SpanEventSchema,
+    TraceEndSchema,
+    TraceScopeSchema,
+} from "./src/Schema.js";
+
+// Re-export types for convenience
+export type { TraceEvent, TraceStart, SpanStart, SpanEnd, SpanEvent, TraceEnd, TraceScope } from "./src/types.js";
+
+export {
+    UI_STEP,
+    TRACE_INTERNAL,
+    LIVE_TRACE,
+    LIVE_TRACE_ID,
+    LIVE_TRACE_LABEL,
+    LIVE_TRACE_SCOPE_TYPE,
+    LIVE_TRACE_SCOPE_ID,
+    LIVE_TRACE_PROVIDER,
+} from "./src/types.js";

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "live-traces",
+  "version": "0.1.0",
+  "description": "Real-time Effect span streaming to frontend UIs. Stream traces from any backend to React with zero overhead.",
+  "keywords": [
+    "effect",
+    "tracing",
+    "telemetry",
+    "opentelemetry",
+    "spans",
+    "observability",
+    "react",
+    "live",
+    "streaming",
+    "sse",
+    "websocket"
+  ],
+  "license": "Apache-2.0",
+  "author": "Necmettin Karakaya <necmettin.karakaya@gmail.com>",
+  "homepage": "https://live-traces.necmttn.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/necmttn/live-traces.git",
+    "directory": "packages/live-traces"
+  },
+  "bugs": {
+    "url": "https://github.com/necmttn/live-traces/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "react",
+    "index.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/src/types.d.ts",
+      "import": "./dist/src/types.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    },
+    "./transports/sse": {
+      "types": "./dist/src/transports/sse.d.ts",
+      "import": "./dist/src/transports/sse.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist .tsbuildinfo",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "echo 'no lint configured'",
+    "prepublishOnly": "bun run clean && bun run build"
+  },
+  "peerDependencies": {
+    "effect": ">=3.10.0",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "effect": "^3.18.0",
+    "react": "^19.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/react/hooks.ts

@@ -0,0 +1,73 @@
+/**
+ * React hooks for consuming trace data.
+ *
+ * Uses useSyncExternalStore for tear-free reads from the TraceStore.
+ * All hooks return STABLE references — derived data is computed in
+ * useMemo to prevent infinite render loops.
+ *
+ * No Effect dependency — works with any React 18+ app.
+ */
+import { useMemo, useSyncExternalStore } from "react";
+
+import type { SpanNode, TraceState } from "./store.js";
+
+import { getTraceStore } from "./store.js";
+
+/** Stable empty array to avoid creating new references */
+const EMPTY_STEPS: SpanNode[] = [];
+
+/**
+ * Get the stable Map snapshot from the store.
+ * This is the foundation for all hooks — the Map reference only changes
+ * when the store is actually updated via dispatch().
+ */
+function useSnapshot() {
+    const store = getTraceStore();
+    return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+}
+
+/**
+ * Subscribe to all active traces.
+ * Returns traces sorted by startedAt descending.
+ */
+export function useActiveTraces(): TraceState[] {
+    const snapshot = useSnapshot();
+    return useMemo(() => Array.from(snapshot.values()).toSorted((a, b) => b.startedAt - a.startedAt), [snapshot]);
+}
+
+/**
+ * Subscribe to a single trace by ID.
+ * Returns undefined if the trace doesn't exist (yet).
+ */
+export function useTrace(traceId: string): TraceState | undefined {
+    const snapshot = useSnapshot();
+    return useMemo(() => snapshot.get(traceId), [snapshot, traceId]);
+}
+
+/**
+ * Get the step spans (ui.step=true) for a trace, in chronological order.
+ * These are the user-visible processing stages.
+ */
+export function useTraceSteps(traceId: string): SpanNode[] {
+    const snapshot = useSnapshot();
+    return useMemo(() => {
+        const trace = snapshot.get(traceId);
+        if (!trace) return EMPTY_STEPS;
+        const steps = Array.from(trace.spans.values()).filter((s) => s.isStep);
+        if (steps.length === 0) return EMPTY_STEPS;
+        return steps.toSorted((a, b) => a.startedAt - b.startedAt);
+    }, [snapshot, traceId]);
+}
+
+/**
+ * Get the root span tree for a trace.
+ * Returns the root SpanNode with nested children.
+ */
+export function useSpanTree(traceId: string): SpanNode | undefined {
+    const snapshot = useSnapshot();
+    return useMemo(() => {
+        const trace = snapshot.get(traceId);
+        if (!trace || !trace.rootSpanId) return undefined;
+        return trace.spans.get(trace.rootSpanId);
+    }, [snapshot, traceId]);
+}

package/react/index.ts

@@ -0,0 +1,30 @@
+/**
+ * live-traces/react
+ *
+ * React store and hooks for consuming trace events.
+ * Zero Effect dependency — works with any React 18+ app.
+ *
+ * Usage:
+ * ```tsx
+ * import { useActiveTraces, useTrace, useTraceSteps } from "live-traces/react"
+ *
+ * function ActivityPanel() {
+ *   const traces = useActiveTraces()
+ *   return traces.map(t => <TraceCard key={t.traceId} trace={t} />)
+ * }
+ *
+ * function TraceCard({ trace }: { trace: TraceState }) {
+ *   const steps = useTraceSteps(trace.traceId)
+ *   return steps.map(s => <StepRow key={s.spanId} step={s} />)
+ * }
+ * ```
+ */
+
+// Store
+export { TraceStore, getTraceStore } from "./store.js";
+export type { TraceState, SpanNode, SpanEventEntry, TraceStatus } from "./store.js";
+
+// Hooks
+export { useActiveTraces, useTrace, useTraceSteps, useSpanTree } from "./hooks.js";
+
+export { LIVE_TRACE_PROVIDER, LIVE_TRACE_SCOPE_TYPE, LIVE_TRACE_SCOPE_ID } from "../src/types.js";