@revealui/core 0.0.1-pre.4 → 0.2.1

package/dist/observability/tracing.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Distributed Tracing System
+ *
+ * Implements distributed tracing for tracking requests across services
+ */
+export interface Span {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+    tags: Record<string, string | number | boolean>;
+    logs: Array<{
+        timestamp: number;
+        message: string;
+        fields?: Record<string, unknown>;
+    }>;
+    status: 'ok' | 'error';
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+}
+export interface Trace {
+    traceId: string;
+    spans: Span[];
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+    rootSpan?: Span;
+}
+export declare class TracingSystem {
+    private activeSpans;
+    private completedTraces;
+    private maxTraces;
+    /**
+     * Start a new trace
+     */
+    startTrace(name: string, tags?: Record<string, string | number | boolean>): Span;
+    /**
+     * Start a child span
+     */
+    startSpan(name: string, parentSpan: Span, tags?: Record<string, string | number | boolean>): Span;
+    /**
+     * End a span
+     */
+    endSpan(span: Span, error?: Error): void;
+    /**
+     * Add tag to span
+     */
+    setTag(span: Span, key: string, value: string | number | boolean): void;
+    /**
+     * Log event in span
+     */
+    log(span: Span, message: string, fields?: Record<string, unknown>): void;
+    /**
+     * Add span to trace
+     */
+    private addToTrace;
+    /**
+     * Get trace by ID
+     */
+    getTrace(traceId: string): Trace | undefined;
+    /**
+     * Get all traces
+     */
+    getAllTraces(): Trace[];
+    /**
+     * Clear all traces
+     */
+    clearTraces(): void;
+    /**
+     * Generate unique ID
+     */
+    private generateId;
+    /**
+     * Export traces in Jaeger format
+     */
+    exportJaeger(): unknown[];
+}
+/**
+ * Default tracing system
+ */
+export declare const tracing: TracingSystem;
+/**
+ * Trace a function
+ */
+export declare function trace<T>(name: string, fn: (span: Span) => Promise<T>, parentSpan?: Span): Promise<T>;
+/**
+ * Trace synchronous function
+ */
+export declare function traceSync<T>(name: string, fn: (span: Span) => T, parentSpan?: Span): T;
+/**
+ * Extract trace context from headers
+ */
+export declare function extractTraceContext(headers: Headers | Record<string, string>): {
+    traceId?: string;
+    spanId?: string;
+};
+/**
+ * Inject trace context into headers
+ */
+export declare function injectTraceContext(span: Span, headers: Headers | Record<string, string>): void;
+/**
+ * Create tracing middleware
+ */
+export declare function createTracingMiddleware<TRequest = unknown, TResponse = unknown>(): (request: TRequest & {
+    headers?: Record<string, string>;
+    url: string;
+    method: string;
+}, next: () => Promise<TResponse & {
+    status?: number;
+    headers?: Record<string, string>;
+}>) => Promise<TResponse & {
+    status?: number;
+    headers?: Record<string, string>;
+}>;
+/**
+ * Trace database query
+ */
+export declare function traceDBQuery<T>(query: string, fn: () => Promise<T>, parentSpan?: Span): Promise<T>;
+/**
+ * Trace API call
+ */
+export declare function traceAPICall<T>(method: string, url: string, fn: () => Promise<T>, parentSpan?: Span): Promise<T>;
+/**
+ * Trace cache operation
+ */
+export declare function traceCacheOperation<T>(operation: string, key: string, fn: () => Promise<T>, parentSpan?: Span): Promise<T>;
+/**
+ * Get span context for propagation
+ */
+export declare function getSpanContext(span: Span): {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+};
+/**
+ * Create span from context
+ */
+export declare function createSpanFromContext(name: string, context: {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+}, tags?: Record<string, string | number | boolean>): Span;
+//# sourceMappingURL=tracing.d.ts.map

package/dist/observability/tracing.d.ts.map

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

package/dist/observability/tracing.js

@@ -0,0 +1,381 @@
+/**
+ * Distributed Tracing System
+ *
+ * Implements distributed tracing for tracking requests across services
+ */
+export class TracingSystem {
+    activeSpans = new Map();
+    completedTraces = new Map();
+    maxTraces = 1000;
+    /**
+     * Start a new trace
+     */
+    startTrace(name, tags) {
+        const traceId = this.generateId();
+        const spanId = this.generateId();
+        const span = {
+            traceId,
+            spanId,
+            name,
+            startTime: Date.now(),
+            tags: tags || {},
+            logs: [],
+            status: 'ok',
+        };
+        this.activeSpans.set(spanId, span);
+        return span;
+    }
+    /**
+     * Start a child span
+     */
+    startSpan(name, parentSpan, tags) {
+        const spanId = this.generateId();
+        const span = {
+            traceId: parentSpan.traceId,
+            spanId,
+            parentSpanId: parentSpan.spanId,
+            name,
+            startTime: Date.now(),
+            tags: tags || {},
+            logs: [],
+            status: 'ok',
+        };
+        this.activeSpans.set(spanId, span);
+        return span;
+    }
+    /**
+     * End a span
+     */
+    endSpan(span, error) {
+        span.endTime = Date.now();
+        span.duration = span.endTime - span.startTime;
+        if (error) {
+            span.status = 'error';
+            span.error = {
+                name: error.name,
+                message: error.message,
+                stack: error.stack,
+            };
+        }
+        this.activeSpans.delete(span.spanId);
+        // Add to completed traces
+        this.addToTrace(span);
+    }
+    /**
+     * Add tag to span
+     */
+    setTag(span, key, value) {
+        span.tags[key] = value;
+    }
+    /**
+     * Log event in span
+     */
+    log(span, message, fields) {
+        span.logs.push({
+            timestamp: Date.now(),
+            message,
+            fields,
+        });
+    }
+    /**
+     * Add span to trace
+     */
+    addToTrace(span) {
+        let trace = this.completedTraces.get(span.traceId);
+        if (!trace) {
+            trace = {
+                traceId: span.traceId,
+                spans: [],
+                startTime: span.startTime,
+            };
+            this.completedTraces.set(span.traceId, trace);
+            // Cleanup old traces
+            if (this.completedTraces.size > this.maxTraces) {
+                const oldestTraceId = this.completedTraces.keys().next().value;
+                if (oldestTraceId !== undefined) {
+                    this.completedTraces.delete(oldestTraceId);
+                }
+            }
+        }
+        trace.spans.push(span);
+        // Update trace times
+        if (span.endTime && (!trace.endTime || span.endTime > trace.endTime)) {
+            trace.endTime = span.endTime;
+        }
+        if (span.startTime < trace.startTime) {
+            trace.startTime = span.startTime;
+        }
+        if (trace.endTime) {
+            trace.duration = trace.endTime - trace.startTime;
+        }
+        // Find root span
+        if (!span.parentSpanId) {
+            trace.rootSpan = span;
+        }
+    }
+    /**
+     * Get trace by ID
+     */
+    getTrace(traceId) {
+        return this.completedTraces.get(traceId);
+    }
+    /**
+     * Get all traces
+     */
+    getAllTraces() {
+        return Array.from(this.completedTraces.values());
+    }
+    /**
+     * Clear all traces
+     */
+    clearTraces() {
+        this.completedTraces.clear();
+    }
+    /**
+     * Generate unique ID
+     */
+    generateId() {
+        return crypto.randomUUID().replace(/-/g, '').substring(0, 16);
+    }
+    /**
+     * Export traces in Jaeger format
+     */
+    exportJaeger() {
+        return this.getAllTraces().map((trace) => ({
+            traceID: trace.traceId,
+            spans: trace.spans.map((span) => ({
+                traceID: span.traceId,
+                spanID: span.spanId,
+                parentSpanID: span.parentSpanId,
+                operationName: span.name,
+                startTime: span.startTime * 1000, // microseconds
+                duration: span.duration ? span.duration * 1000 : 0,
+                tags: Object.entries(span.tags).map(([key, value]) => ({
+                    key,
+                    type: typeof value,
+                    value,
+                })),
+                logs: span.logs.map((log) => ({
+                    timestamp: log.timestamp * 1000,
+                    fields: [
+                        {
+                            key: 'message',
+                            type: 'string',
+                            value: log.message,
+                        },
+                        ...(log.fields
+                            ? Object.entries(log.fields).map(([key, value]) => ({
+                                key,
+                                type: typeof value,
+                                value,
+                            }))
+                            : []),
+                    ],
+                })),
+            })),
+        }));
+    }
+}
+/**
+ * Default tracing system
+ */
+export const tracing = new TracingSystem();
+/**
+ * Trace a function
+ */
+export async function trace(name, fn, parentSpan) {
+    const span = parentSpan ? tracing.startSpan(name, parentSpan) : tracing.startTrace(name);
+    try {
+        const result = await fn(span);
+        tracing.endSpan(span);
+        return result;
+    }
+    catch (error) {
+        tracing.endSpan(span, error instanceof Error ? error : new Error(String(error)));
+        throw error;
+    }
+}
+/**
+ * Trace synchronous function
+ */
+export function traceSync(name, fn, parentSpan) {
+    const span = parentSpan ? tracing.startSpan(name, parentSpan) : tracing.startTrace(name);
+    try {
+        const result = fn(span);
+        tracing.endSpan(span);
+        return result;
+    }
+    catch (error) {
+        tracing.endSpan(span, error instanceof Error ? error : new Error(String(error)));
+        throw error;
+    }
+}
+/**
+ * Extract trace context from headers
+ */
+export function extractTraceContext(headers) {
+    // Handle both Headers and Record<string, string>
+    const getHeader = (key) => {
+        if ('get' in headers && typeof headers.get === 'function') {
+            return headers.get(key);
+        }
+        return headers[key];
+    };
+    // Support multiple formats
+    const traceParent = getHeader('traceparent'); // W3C Trace Context
+    const b3TraceId = getHeader('x-b3-traceid'); // B3 format
+    const b3SpanId = getHeader('x-b3-spanid');
+    if (traceParent) {
+        // Parse W3C traceparent: version-traceid-spanid-flags
+        const parts = traceParent.split('-');
+        if (parts.length >= 3) {
+            return {
+                traceId: parts[1],
+                spanId: parts[2],
+            };
+        }
+    }
+    if (b3TraceId) {
+        return {
+            traceId: b3TraceId,
+            spanId: b3SpanId || undefined,
+        };
+    }
+    return {};
+}
+/**
+ * Inject trace context into headers
+ */
+export function injectTraceContext(span, headers) {
+    // Handle both Headers and Record<string, string>
+    const setHeader = (key, value) => {
+        if ('set' in headers && typeof headers.set === 'function') {
+            headers.set(key, value);
+        }
+        else {
+            ;
+            headers[key] = value;
+        }
+    };
+    // W3C Trace Context format
+    const traceparent = `00-${span.traceId}-${span.spanId}-01`;
+    setHeader('traceparent', traceparent);
+    // B3 format (for compatibility)
+    setHeader('x-b3-traceid', span.traceId);
+    setHeader('x-b3-spanid', span.spanId);
+    if (span.parentSpanId) {
+        setHeader('x-b3-parentspanid', span.parentSpanId);
+    }
+}
+/**
+ * Create tracing middleware
+ */
+export function createTracingMiddleware() {
+    return async (request, next) => {
+        const traceContext = extractTraceContext(request.headers ?? {});
+        const url = new URL(request.url);
+        let span;
+        if (traceContext.traceId) {
+            // Continue existing trace
+            const parentSpan = {
+                traceId: traceContext.traceId,
+                spanId: traceContext.spanId || '',
+                name: 'parent',
+                startTime: Date.now(),
+                tags: {},
+                logs: [],
+                status: 'ok',
+            };
+            span = tracing.startSpan(`${request.method} ${url.pathname}`, parentSpan, {
+                'http.method': request.method,
+                'http.url': request.url,
+                'http.path': url.pathname,
+            });
+        }
+        else {
+            // Start new trace
+            span = tracing.startTrace(`${request.method} ${url.pathname}`, {
+                'http.method': request.method,
+                'http.url': request.url,
+                'http.path': url.pathname,
+            });
+        }
+        try {
+            const response = await next();
+            const statusCode = response.status ?? 200;
+            tracing.setTag(span, 'http.status_code', statusCode);
+            if (statusCode >= 400) {
+                span.status = 'error';
+            }
+            tracing.endSpan(span);
+            // Inject trace context into response
+            if (response.headers) {
+                injectTraceContext(span, response.headers);
+            }
+            return response;
+        }
+        catch (error) {
+            tracing.setTag(span, 'http.status_code', 500);
+            tracing.endSpan(span, error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    };
+}
+/**
+ * Trace database query
+ */
+export async function traceDBQuery(query, fn, parentSpan) {
+    return trace('database.query', async (span) => {
+        tracing.setTag(span, 'db.statement', query);
+        tracing.setTag(span, 'db.type', 'sql');
+        const result = await fn();
+        return result;
+    }, parentSpan);
+}
+/**
+ * Trace API call
+ */
+export async function traceAPICall(method, url, fn, parentSpan) {
+    return trace('api.call', async (span) => {
+        tracing.setTag(span, 'http.method', method);
+        tracing.setTag(span, 'http.url', url);
+        const result = await fn();
+        return result;
+    }, parentSpan);
+}
+/**
+ * Trace cache operation
+ */
+export async function traceCacheOperation(operation, key, fn, parentSpan) {
+    return trace('cache.operation', async (span) => {
+        tracing.setTag(span, 'cache.operation', operation);
+        tracing.setTag(span, 'cache.key', key);
+        const result = await fn();
+        return result;
+    }, parentSpan);
+}
+/**
+ * Get span context for propagation
+ */
+export function getSpanContext(span) {
+    return {
+        traceId: span.traceId,
+        spanId: span.spanId,
+        parentSpanId: span.parentSpanId,
+    };
+}
+/**
+ * Create span from context
+ */
+export function createSpanFromContext(name, context, tags) {
+    const parentSpan = {
+        traceId: context.traceId,
+        spanId: context.parentSpanId || context.spanId,
+        name: 'parent',
+        startTime: Date.now(),
+        tags: {},
+        logs: [],
+        status: 'ok',
+    };
+    return tracing.startSpan(name, parentSpan, tags);
+}