autotel-tanstack 1.1.0

package/src/auto.ts

@@ -0,0 +1,86 @@
+/**
+ * Zero-config auto-instrumentation for TanStack Start
+ *
+ * Import this module to automatically instrument TanStack Start applications
+ * with OpenTelemetry tracing. Configuration is read from environment variables.
+ *
+ * Environment Variables:
+ * - OTEL_SERVICE_NAME: Service name (default: 'tanstack-start')
+ * - OTEL_EXPORTER_OTLP_ENDPOINT: OTLP collector URL
+ * - OTEL_EXPORTER_OTLP_HEADERS: Authentication headers (key=value,key=value)
+ *
+ * @example
+ * ```typescript
+ * // app/start.ts
+ * import 'autotel-tanstack/auto';
+ * import { createStart } from '@tanstack/react-start';
+ *
+ * // Tracing is automatically configured!
+ * export const startInstance = createStart(() => ({}));
+ * ```
+ *
+ * @module
+ */
+
+import { init } from 'autotel';
+
+// Parse service name
+const service = process.env.OTEL_SERVICE_NAME || 'tanstack-start';
+
+// Parse endpoint
+const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+
+// Parse headers
+let headers: Record<string, string> | undefined;
+if (process.env.OTEL_EXPORTER_OTLP_HEADERS) {
+  headers = {};
+  const pairs = process.env.OTEL_EXPORTER_OTLP_HEADERS.split(',');
+  for (const pair of pairs) {
+    const [key, value] = pair.split('=');
+    if (key && value) {
+      headers[key.trim()] = value.trim();
+    }
+  }
+}
+
+// Initialize autotel
+init({
+  service,
+  endpoint,
+  headers,
+});
+
+// Log initialization (only in development)
+if (process.env.NODE_ENV === 'development' || process.env.AUTOTEL_DEBUG) {
+  console.log('[autotel-tanstack] Auto-initialized with:', {
+    service,
+    endpoint: endpoint || '(not configured)',
+    hasHeaders: !!headers,
+  });
+}
+
+// Re-export middleware for convenience
+export { tracingMiddleware, functionTracingMiddleware } from './middleware';
+export { traceServerFn } from './server-functions';
+export { traceLoader, traceBeforeLoad } from './loaders';
+
+/**
+ * Check if auto-instrumentation is active
+ */
+export function isAutoInstrumentationActive(): boolean {
+  return true;
+}
+
+/**
+ * Get the configured service name
+ */
+export function getServiceName(): string {
+  return service;
+}
+
+/**
+ * Get the configured endpoint
+ */
+export function getEndpoint(): string | undefined {
+  return endpoint;
+}

package/src/browser/context.ts

@@ -0,0 +1,88 @@
+/**
+ * Browser stub for context module
+ *
+ * In browser environments, context propagation is not needed.
+ * These functions return empty/default values.
+ */
+
+/**
+ * Type representing values that can be used to initialize Headers
+ */
+export type HeadersInitType =
+  | Headers
+  | Record<string, string>
+  | [string, string][];
+
+/**
+ * Browser stub: Returns root context (no parent)
+ */
+export function extractContextFromRequest(_request: Request): unknown {
+  void _request;
+  // Return an empty context-like object
+  return {};
+}
+
+/**
+ * Browser stub: Returns headers unchanged
+ */
+export function injectContextToHeaders(
+  headers: Headers,
+  ctx?: unknown,
+): Headers {
+  void ctx;
+  return headers;
+}
+
+/**
+ * Browser stub: Create headers with optional initial values
+ */
+export function createTracedHeaders(
+  existingHeaders?: HeadersInitType,
+  ctx?: unknown,
+): Headers {
+  void ctx;
+  return new Headers(existingHeaders);
+}
+
+/**
+ * Browser stub: Run function and return result
+ */
+export function runInContext<T>(parentContext: unknown, fn: () => T): T {
+  void parentContext;
+  return fn();
+}
+
+/**
+ * Browser stub: Returns empty context object
+ */
+export function getActiveContext(): unknown {
+  return {};
+}
+
+/**
+ * Browser stub: Returns empty string
+ */
+export function getTraceParent(): string {
+  return '';
+}
+
+/**
+ * Browser stub: Returns empty string
+ */
+export function getTraceState(): string {
+  return '';
+}
+
+/**
+ * Browser stub: Returns undefined
+ */
+export function getCurrentTraceId(): string | undefined {
+  return undefined;
+}
+
+/**
+ * Browser stub: Returns undefined
+ */
+export function getCurrentSpanId(): string | undefined {
+  return undefined;
+}

package/src/browser/debug-headers.ts

@@ -0,0 +1,19 @@
+/**
+ * Browser stub for debug-headers module
+ *
+ * Debug headers are server-side only.
+ * In browser, this returns pass-through middleware.
+ */
+
+import type { MiddlewareHandler } from './middleware';
+
+/**
+ * Browser stub: Returns pass-through middleware
+ */
+export function debugHeadersMiddleware<
+  TContext = unknown,
+>(): MiddlewareHandler<TContext> {
+  return async function noopMiddleware(opts) {
+    return opts.next();
+  };
+}

package/src/browser/error-reporting.ts

@@ -0,0 +1,63 @@
+/**
+ * Browser stub for error-reporting module
+ *
+ * Error reporting/collection only happens on the server.
+ * In browser, these are no-op functions.
+ */
+
+/**
+ * Error entry structure (stub)
+ */
+export interface ErrorEntry {
+  timestamp: string;
+  message: string;
+  stack?: string;
+  context?: Record<string, unknown>;
+}
+
+/**
+ * Browser stub: No-op
+ */
+export function reportError(
+  error: Error,
+  context?: Record<string, unknown>,
+): void {
+  void error;
+  void context;
+  // No-op in browser
+}
+
+/**
+ * Browser stub: Returns empty array
+ */
+export function getRecentErrors(limit?: number): ErrorEntry[] {
+  void limit;
+  return [];
+}
+
+/**
+ * Browser stub: No-op
+ */
+export function clearErrors(): void {
+  // No-op in browser
+}
+
+/**
+ * Browser stub: Returns JSON Response with empty errors
+ */
+export function createErrorReportingHandler(): () => Response {
+  return () => {
+    return Response.json({ errors: [], count: 0 });
+  };
+}
+
+/**
+ * Browser stub: Returns function unchanged
+ */
+export function withErrorReporting<T extends (...args: unknown[]) => unknown>(
+  fn: T,
+  context?: Record<string, unknown>,
+): T {
+  void context;
+  return fn;
+}

package/src/browser/handlers.ts

@@ -0,0 +1,23 @@
+/**
+ * Browser stub for handlers module
+ *
+ * Handler wrapping only applies on the server side.
+ * In browser, we just return the handler unchanged.
+ */
+
+import type { WrapStartHandlerConfig } from './types';
+
+/**
+ * Handler type
+ */
+export type StartHandler<T = unknown> = (request: Request) => Promise<T>;
+
+/**
+ * Browser stub: Returns the handler unchanged
+ */
+export function wrapStartHandler<T>(
+  config?: WrapStartHandlerConfig,
+): (handler: StartHandler<T>) => StartHandler<T> {
+  void config;
+  return (handler) => handler;
+}

package/src/browser/index.ts

@@ -0,0 +1,65 @@
+/**
+ * Browser entry point for autotel-tanstack
+ *
+ * This module provides no-op stubs for all exports to prevent
+ * @opentelemetry/api and autotel from being bundled in client code.
+ */
+
+// Export types from types.ts (single source of truth)
+export type {
+  Attributes,
+  TanStackInstrumentationConfig,
+  TracingMiddlewareConfig,
+  TraceServerFnConfig,
+  TraceLoaderConfig,
+  WrapStartHandlerConfig,
+} from './types';
+export { DEFAULT_CONFIG, SPAN_ATTRIBUTES } from './types';
+
+// Export functions from each module (excluding their duplicate type exports)
+export { traceLoader, traceBeforeLoad, createTracedRoute } from './loaders';
+export { traceServerFn, createTracedServerFnFactory } from './server-functions';
+export {
+  createTracingMiddleware,
+  tracingMiddleware,
+  functionTracingMiddleware,
+  type MiddlewareHandler,
+} from './middleware';
+export {
+  extractContextFromRequest,
+  injectContextToHeaders,
+  createTracedHeaders,
+  runInContext,
+  getActiveContext,
+  getTraceParent,
+  getTraceState,
+  getCurrentTraceId,
+  getCurrentSpanId,
+  type HeadersInitType,
+} from './context';
+export { wrapStartHandler, type StartHandler } from './handlers';
+export {
+  getMetrics,
+  recordTiming,
+  recordError,
+  resetMetrics,
+  metricsCollector,
+  createMetricsHandler,
+  type MetricsData,
+} from './metrics';
+export {
+  reportError,
+  getRecentErrors,
+  clearErrors,
+  createErrorReportingHandler,
+  withErrorReporting,
+  type ErrorEntry,
+} from './error-reporting';
+export { debugHeadersMiddleware } from './debug-headers';
+export {
+  createTestCollector,
+  assertSpanCreated,
+  assertSpanHasAttribute,
+  type TestSpan,
+  type TestCollector,
+} from './testing';

package/src/browser/loaders.ts

@@ -0,0 +1,62 @@
+/**
+ * Browser stub for loaders module
+ *
+ * In browser environments, these functions are no-ops that just call the
+ * original functions without any tracing overhead.
+ */
+
+import type { TraceLoaderConfig } from './types';
+
+/**
+ * Loader context type (compatible with TanStack router loader context)
+ */
+interface LoaderContext {
+  params?: Record<string, string>;
+  route?: {
+    id?: string;
+  };
+  [key: string]: unknown;
+}
+
+/**
+ * Browser stub: Returns the loader function unchanged
+ */
+export function traceLoader<
+  T extends (context: LoaderContext) => Promise<unknown>,
+>(loaderFn: T, config?: TraceLoaderConfig): T {
+  void config;
+  return loaderFn;
+}
+
+/**
+ * Browser stub: Returns the beforeLoad function unchanged
+ */
+export function traceBeforeLoad<
+  T extends (context: LoaderContext) => Promise<unknown>,
+>(beforeLoadFn: T, config?: TraceLoaderConfig): T {
+  void config;
+  return beforeLoadFn;
+}
+
+/**
+ * Browser stub: Returns object with pass-through wrappers
+ */
+export function createTracedRoute(
+  routeId: string,
+  config?: Omit<TraceLoaderConfig, 'name'>,
+) {
+  void routeId;
+  void config;
+  return {
+    loader<T extends (context: LoaderContext) => Promise<unknown>>(
+      loaderFn: T,
+    ): T {
+      return loaderFn;
+    },
+    beforeLoad<T extends (context: LoaderContext) => Promise<unknown>>(
+      beforeLoadFn: T,
+    ): T {
+      return beforeLoadFn;
+    },
+  };
+}

package/src/browser/metrics.ts

@@ -0,0 +1,86 @@
+/**
+ * Browser stub for metrics module
+ *
+ * Metrics collection only happens on the server.
+ * In browser, these are no-op functions.
+ */
+
+/**
+ * Metrics data structure (stub)
+ */
+export interface MetricsData {
+  requestCount: number;
+  errorCount: number;
+  avgLatency: number;
+  p50Latency: number;
+  p95Latency: number;
+  p99Latency: number;
+  requestsPerSecond: number;
+  endpoints: Record<
+    string,
+    {
+      count: number;
+      errors: number;
+      avgLatency: number;
+    }
+  >;
+}
+
+/**
+ * Browser stub: Returns empty metrics
+ */
+export function getMetrics(): MetricsData {
+  return {
+    requestCount: 0,
+    errorCount: 0,
+    avgLatency: 0,
+    p50Latency: 0,
+    p95Latency: 0,
+    p99Latency: 0,
+    requestsPerSecond: 0,
+    endpoints: {},
+  };
+}
+
+/**
+ * Browser stub: No-op
+ */
+export function recordTiming(name: string, durationMs: number): void {
+  void name;
+  void durationMs;
+  // No-op in browser
+}
+
+/**
+ * Browser stub: No-op
+ */
+export function recordError(name: string): void {
+  void name;
+  // No-op in browser
+}
+
+/**
+ * Browser stub: No-op
+ */
+export function resetMetrics(): void {
+  // No-op in browser
+}
+
+/**
+ * Browser stub: No-op metrics collector
+ */
+export const metricsCollector = {
+  recordTiming: recordTiming,
+  recordError: recordError,
+  getMetrics: getMetrics,
+  reset: resetMetrics,
+};
+
+/**
+ * Browser stub: Returns JSON Response with empty metrics
+ */
+export function createMetricsHandler(): () => Response {
+  return () => {
+    return Response.json(getMetrics());
+  };
+}

package/src/browser/middleware.ts

@@ -0,0 +1,61 @@
+/**
+ * Browser stub for middleware module
+ *
+ * In browser environments, these functions return pass-through middleware
+ * that just calls next() without any tracing overhead.
+ */
+
+import type { TracingMiddlewareConfig } from './types';
+
+/**
+ * Generic middleware handler type
+ */
+export interface MiddlewareHandler<TContext = unknown> {
+  (opts: {
+    next: (ctx?: Partial<TContext>) => Promise<TContext>;
+    context: TContext;
+    request?: Request;
+    pathname?: string;
+    data?: unknown;
+    method?: string;
+    filename?: string;
+    functionId?: string;
+    signal?: AbortSignal;
+  }): Promise<TContext>;
+}
+
+/**
+ * Browser stub: Returns pass-through middleware
+ */
+export function createTracingMiddleware<TContext = unknown>(
+  config?: TracingMiddlewareConfig,
+): MiddlewareHandler<TContext> {
+  void config;
+  return async function noopMiddleware(opts) {
+    return opts.next();
+  };
+}
+
+/**
+ * Browser stub: Returns pass-through middleware
+ */
+export function tracingMiddleware<TContext = unknown>(
+  config?: TracingMiddlewareConfig,
+): MiddlewareHandler<TContext> {
+  void config;
+  return async function noopMiddleware(opts) {
+    return opts.next();
+  };
+}
+
+/**
+ * Browser stub: Returns pass-through middleware
+ */
+export function functionTracingMiddleware<TContext = unknown>(
+  config?: Omit<TracingMiddlewareConfig, 'type'>,
+): MiddlewareHandler<TContext> {
+  void config;
+  return async function noopMiddleware(opts) {
+    return opts.next();
+  };
+}

package/src/browser/server-functions.ts

@@ -0,0 +1,31 @@
+/**
+ * Browser stub for server-functions module
+ *
+ * In browser environments, these functions are no-ops that just return
+ * the original functions without any tracing overhead.
+ */
+
+import type { TraceServerFnConfig } from './types';
+
+/**
+ * Browser stub: Returns the server function unchanged
+ */
+export function traceServerFn<
+  T extends (...args: unknown[]) => Promise<unknown>,
+>(serverFn: T, config?: TraceServerFnConfig): T {
+  void config;
+  return serverFn;
+}
+
+/**
+ * Browser stub: Returns the createServerFn unchanged
+ */
+export function createTracedServerFnFactory<
+  TCreateServerFn extends (...args: unknown[]) => unknown,
+>(
+  createServerFnOriginal: TCreateServerFn,
+  defaultConfig?: Omit<TraceServerFnConfig, 'name'>,
+): TCreateServerFn {
+  void defaultConfig;
+  return createServerFnOriginal;
+}

package/src/browser/testing.ts

@@ -0,0 +1,67 @@
+/**
+ * Browser stub for testing module
+ *
+ * Testing utilities are server-side only.
+ * In browser, these return no-op implementations.
+ */
+
+/**
+ * Test span structure (stub)
+ */
+export interface TestSpan {
+  name: string;
+  attributes: Record<string, unknown>;
+  status: { code: number; message?: string };
+  events: Array<{ name: string; attributes?: Record<string, unknown> }>;
+  duration: number;
+}
+
+/**
+ * Test collector structure (stub)
+ */
+export interface TestCollector {
+  getSpans(): TestSpan[];
+  getSpansByName(name: string): TestSpan[];
+  clear(): void;
+  waitForSpans(count: number, timeout?: number): Promise<TestSpan[]>;
+}
+
+/**
+ * Browser stub: Returns empty collector
+ */
+export function createTestCollector(): TestCollector {
+  return {
+    getSpans: () => [],
+    getSpansByName: () => [],
+    clear: () => {},
+    waitForSpans: async () => [],
+  };
+}
+
+/**
+ * Browser stub: No-op
+ */
+export function assertSpanCreated(
+  collector: TestCollector,
+  name: string,
+): void {
+  void collector;
+  void name;
+  // No-op in browser
+}
+
+/**
+ * Browser stub: No-op
+ */
+export function assertSpanHasAttribute(
+  collector: TestCollector,
+  name: string,
+  key: string,
+  value?: unknown,
+): void {
+  void collector;
+  void name;
+  void key;
+  void value;
+  // No-op in browser
+}