autotel 4.1.0 → 4.2.0

package/src/decorators.ts

@@ -1,188 +0,0 @@
-/**
- * TypeScript 5+ Decorators for autotel
- *
- * Provides @Trace decorator for class-based code.
- *
- * **Requires TypeScript 5.0+**
- *
- * @example Method decorator
- * ```typescript
- * import { Trace } from 'autotel/decorators'
- *
- * class OrderService {
- *   @Trace('order.create', { withMetrics: true })
- *   async createOrder(data: OrderData) {
- *     return await db.orders.create(data)
- *   }
- *
- *   @Trace() // Uses method name as span name
- *   async processPayment(orderId: string) {
- *     return await stripe.charge(orderId)
- *   }
- * }
- * ```
- */
-
-import type { TracingOptions, TraceContext } from './functional';
-import { getConfig } from './config';
-import { SpanStatusCode } from '@opentelemetry/api';
-import { createTraceContext } from './trace-context';
-
-/**
- * Options for @Trace method decorator
- */
-export interface TraceDecoratorOptions extends Omit<TracingOptions, 'name'> {
-  /**
-   * Custom span name. If not provided, uses the method name.
-   */
-  name?: string;
-}
-
-/**
- * @Trace - Method decorator for fine-grained tracing
- *
- * Wraps a class method with automatic tracing. Supports both patterns:
- * - Simple: method doesn't use ctx
- * - Advanced: method accesses ctx via this.ctx
- *
- * @example Simple usage (no ctx)
- * ```typescript
- * class OrderService {
- *   @Trace()
- *   async createOrder(data: OrderData) {
- *     return await db.orders.create(data)
- *   }
- * }
- * ```
- *
- * @example With custom name and options
- * ```typescript
- * class PaymentService {
- *   @Trace('payment.charge', { withMetrics: true })
- *   async chargeCard(amount: number) {
- *     return await stripe.charges.create({ amount })
- *   }
- * }
- * ```
- *
- * @example Accessing ctx
- * ```typescript
- * interface WithTraceContext {
- *   ctx?: TraceContext
- * }
- *
- * class UserService {
- *   @Trace()
- *   async createUser(data: UserData) {
- *     // Access ctx via this.ctx (available during execution)
- *     const ctx = (this as unknown as WithTraceContext).ctx
- *     if (ctx) {
- *       ctx.setAttribute('user.id', data.id)
- *     }
- *     return await db.users.create(data)
- *   }
- * }
- * ```
- */
-export function Trace(
-  options?: TraceDecoratorOptions,
-): <T extends (...args: unknown[]) => Promise<unknown>>(
-  originalMethod: T,
-  context: ClassMethodDecoratorContext,
-) => T;
-export function Trace(
-  name?: string,
-  options?: TraceDecoratorOptions,
-): <T extends (...args: unknown[]) => Promise<unknown>>(
-  originalMethod: T,
-  context: ClassMethodDecoratorContext,
-) => T;
-export function Trace(
-  nameOrOptions?: string | TraceDecoratorOptions,
-  maybeOptions?: TraceDecoratorOptions,
-): <T extends (...args: unknown[]) => Promise<unknown>>(
-  originalMethod: T,
-  context: ClassMethodDecoratorContext,
-) => T {
-  // Parse arguments
-  const name =
-    typeof nameOrOptions === 'string' ? nameOrOptions : nameOrOptions?.name;
-  // Options are used in the returned decorator function, not here
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  const _options: TraceDecoratorOptions =
-    typeof nameOrOptions === 'string'
-      ? maybeOptions || {}
-      : nameOrOptions || {};
-
-  // TypeScript 5+ decorator signature
-  return function <T extends (...args: unknown[]) => Promise<unknown>>(
-    originalMethod: T,
-    context: ClassMethodDecoratorContext,
-  ): T {
-    const methodName = String(context.name);
-
-    // Skip if not an async function
-    // Check multiple ways to detect async functions (for different transpilation environments)
-    // TypeScript decorators run at class definition time, so we need robust detection
-    const methodStr = originalMethod?.toString() || '';
-    const isAsync =
-      originalMethod &&
-      (originalMethod.constructor?.name === 'AsyncFunction' ||
-        methodStr.trim().startsWith('async ') ||
-        (methodStr.includes('[native code]') && methodStr.includes('async')) ||
-        // Fallback: if function has async in its string representation
-        /async\s+/.test(methodStr));
-
-    if (!isAsync) {
-      // Not an async function, return as-is
-      return originalMethod;
-    }
-
-    const spanName = name || methodName;
-
-    return async function <This>(
-      this: This,
-      ...args: unknown[]
-    ): Promise<unknown> {
-      const config = getConfig();
-      const tracer = config.tracer;
-
-      return tracer.startActiveSpan(spanName, async (span) => {
-        try {
-          // Make ctx available via this.ctx for methods that need it
-          const ctx: TraceContext = createTraceContext(span);
-
-          const originalCtx = (this as { ctx?: TraceContext }).ctx;
-          try {
-            (this as { ctx?: TraceContext }).ctx = ctx;
-            const result = await originalMethod.apply(this, args as []);
-            span.setStatus({ code: SpanStatusCode.OK });
-            return result;
-          } finally {
-            // Restore original ctx
-            if (originalCtx === undefined) {
-              delete (this as { ctx?: TraceContext }).ctx;
-            } else {
-              (this as { ctx?: TraceContext }).ctx = originalCtx;
-            }
-          }
-        } catch (error) {
-          span.setStatus({
-            code: SpanStatusCode.ERROR,
-            message: error instanceof Error ? error.message : 'Unknown error',
-          });
-          span.recordException(
-            error instanceof Error ? error : new Error(String(error)),
-          );
-          throw error;
-        } finally {
-          span.end();
-        }
-      });
-    } as T;
-  };
-}
-
-// Re-export types for convenience
-
-export { type TraceContext, type TracingOptions } from './functional';

package/src/define-event.test.ts

@@ -1,41 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { defineEvent } from './define-event';
-
-describe('defineEvent', () => {
-  it('validates payload and exposes schema metadata when provided', () => {
-    const event = defineEvent(
-      'order.placed',
-      {
-        safeParse(input: unknown) {
-          if (
-            typeof input === 'object' &&
-            input !== null &&
-            'orderId' in input &&
-            typeof (input as Record<string, unknown>).orderId === 'string'
-          ) {
-            return {
-              success: true as const,
-              data: input as { orderId: string },
-            };
-          }
-          return { success: false as const, error: new Error('invalid') };
-        },
-      },
-      {
-        toJsonSchema: () => ({
-          type: 'object',
-          properties: { orderId: { type: 'string' } },
-          required: ['orderId'],
-        }),
-      },
-    );
-
-    expect(event.name).toBe('order.placed');
-    expect(event.schemaMetadata?.source).toBe('zod');
-    expect(event.schemaMetadata?.hash).toMatch(/^[a-f0-9]{64}$/);
-    expect(() => event.track({ orderId: 'o-1' })).not.toThrow();
-    expect(() => event.track({} as { orderId: string })).toThrow(
-      /Schema validation failed/,
-    );
-  });
-});

package/src/define-event.ts

@@ -1,58 +0,0 @@
-import { track } from './track';
-import { hashJson } from './stable-hash';
-import type { EventSchemaMetadata } from './event-subscriber';
-
-type SafeParseResult<T> =
-  | { success: true; data: T }
-  | { success: false; error: unknown };
-
-export interface SchemaLike<T> {
-  safeParse(input: unknown): SafeParseResult<T>;
-}
-
-export interface DefineEventOptions<S> {
-  toJsonSchema?: (schema: S) => unknown;
-}
-
-export interface DefinedEvent<Name extends string, Payload> {
-  readonly name: Name;
-  readonly schemaMetadata?: EventSchemaMetadata;
-  track(payload: Payload): void;
-}
-
-export function defineEvent<
-  Name extends string,
-  Payload,
-  S extends SchemaLike<Payload>,
->(
-  name: Name,
-  schema: S,
-  options: DefineEventOptions<S> = {},
-): DefinedEvent<Name, Payload> {
-  const jsonSchema = options.toJsonSchema?.(schema);
-  const schemaMetadata = jsonSchema
-    ? {
-        source: 'zod' as const,
-        jsonSchema,
-        hash: hashJson(jsonSchema),
-      }
-    : undefined;
-
-  return {
-    name,
-    schemaMetadata,
-    track(payload: Payload) {
-      const parsed = schema.safeParse(payload);
-      if (!parsed.success) {
-        throw new Error(
-          `Invalid payload for event "${name}". Schema validation failed.`,
-        );
-      }
-      track(
-        name,
-        parsed.data,
-        schemaMetadata ? { schema: schemaMetadata } : undefined,
-      );
-    },
-  };
-}

package/src/devtools.ts

@@ -1,60 +0,0 @@
-export interface AutotelDevtoolsConfig {
-  enabled?: boolean;
-  endpoint?: string;
-  embedded?: boolean;
-  host?: string;
-  port?: number;
-  verbose?: boolean;
-}
-
-export interface ResolvedAutotelDevtoolsConfig {
-  enabled: boolean;
-  endpoint?: string;
-  embedded: boolean;
-  host: string;
-  port: number;
-  verbose: boolean;
-}
-
-const defaultHost = '127.0.0.1';
-const defaultPort = 4318;
-
-export function resolveDevtoolsConfig(
-  config: boolean | AutotelDevtoolsConfig | undefined,
-): ResolvedAutotelDevtoolsConfig {
-  if (!config) {
-    return {
-      enabled: false,
-      endpoint: undefined,
-      embedded: false,
-      host: defaultHost,
-      port: defaultPort,
-      verbose: false,
-    };
-  }
-
-  if (config === true) {
-    return {
-      enabled: true,
-      endpoint: `http://${defaultHost}:${defaultPort}`,
-      embedded: false,
-      host: defaultHost,
-      port: defaultPort,
-      verbose: false,
-    };
-  }
-
-  const enabled = config.enabled ?? true;
-  const host = config.host ?? defaultHost;
-  const port = config.port ?? defaultPort;
-  const endpoint = config.endpoint ?? `http://${host}:${port}`;
-
-  return {
-    enabled,
-    endpoint: enabled ? endpoint : undefined,
-    embedded: enabled && (config.embedded ?? false),
-    host,
-    port,
-    verbose: config.verbose ?? false,
-  };
-}

package/src/drain-pipeline.test.ts

@@ -1,68 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-import { createDrainPipeline } from './drain-pipeline';
-
-describe('createDrainPipeline', () => {
-  it('batches by size and sends to drain', async () => {
-    const batchDrain = vi.fn(async () => {});
-    const pipeline = createDrainPipeline<number>({
-      batch: { size: 2, intervalMs: 1000 },
-    });
-    const drain = pipeline(batchDrain);
-
-    drain(1);
-    drain(2);
-    await new Promise((resolve) => setImmediate(resolve));
-
-    expect(batchDrain).toHaveBeenCalledTimes(1);
-    expect(batchDrain).toHaveBeenCalledWith([1, 2]);
-    expect(drain.pending).toBe(0);
-  });
-
-  it('retries failed batches and eventually succeeds', async () => {
-    let attempts = 0;
-    const batchDrain = vi.fn(async () => {
-      attempts++;
-      if (attempts < 2) throw new Error('temporary');
-    });
-
-    const pipeline = createDrainPipeline<number>({
-      batch: { size: 1, intervalMs: 1000 },
-      retry: {
-        maxAttempts: 3,
-        initialDelayMs: 1,
-        maxDelayMs: 2,
-        backoff: 'fixed',
-        jitter: false,
-      },
-    });
-    const drain = pipeline(batchDrain);
-
-    drain(42);
-    await drain.flush();
-
-    expect(batchDrain).toHaveBeenCalledTimes(2);
-    expect(drain.pending).toBe(0);
-  });
-
-  it('drops overflowed events based on policy', async () => {
-    const dropped: number[] = [];
-    const batchDrain = vi.fn(async () => {});
-    const pipeline = createDrainPipeline<number>({
-      batch: { size: 10, intervalMs: 1000 },
-      maxBufferSize: 2,
-      dropPolicy: 'oldest',
-      onDropped: (events) => dropped.push(...events),
-    });
-    const drain = pipeline(batchDrain);
-
-    drain(1);
-    drain(2);
-    drain(3); // drops 1
-
-    expect(dropped).toEqual([1]);
-    expect(drain.pending).toBe(2);
-
-    await drain.flush();
-    expect(batchDrain).toHaveBeenCalledWith([2, 3]);
-  });
-});

package/src/drain-pipeline.ts

@@ -1,199 +0,0 @@
-export interface DrainPipelineOptions<T = unknown> {
-  batch?: {
-    /** Maximum events per batch. @default 50 */
-    size?: number;
-    /** Max time an event can stay buffered before flush. @default 5000 */
-    intervalMs?: number;
-  };
-  retry?: {
-    /** Total attempts including first try. @default 3 */
-    maxAttempts?: number;
-    /** Delay strategy between attempts. @default 'exponential' */
-    backoff?: 'exponential' | 'linear' | 'fixed';
-    /** Base delay for first retry. @default 1000 */
-    initialDelayMs?: number;
-    /** Max delay cap. @default 30000 */
-    maxDelayMs?: number;
-    /** Add random jitter to delays. @default true */
-    jitter?: boolean;
-  };
-  /** Max buffered events before dropping. @default 1000 */
-  maxBufferSize?: number;
-  /** Overflow policy. @default 'oldest' */
-  dropPolicy?: 'oldest' | 'newest';
-  /** Called when events are dropped from overflow or exhausted retries. */
-  onDropped?: (events: T[], error?: Error) => void;
-}
-
-export interface PipelineDrainFn<T> {
-  (ctx: T): void;
-  /** Flush all buffered events. */
-  flush: () => Promise<void>;
-  /** Flush and stop scheduling future timer work. */
-  shutdown: () => Promise<void>;
-  readonly pending: number;
-}
-
-function wait(ms: number): Promise<void> {
-  return new Promise((resolve) => {
-    const timer = setTimeout(resolve, ms);
-    timer.unref?.();
-  });
-}
-
-export function createDrainPipeline<T = unknown>(
-  options?: DrainPipelineOptions<T>,
-): (drain: (batch: T[]) => void | Promise<void>) => PipelineDrainFn<T> {
-  const batchSize = options?.batch?.size ?? 50;
-  const intervalMs = options?.batch?.intervalMs ?? 5000;
-  const maxBufferSize = options?.maxBufferSize ?? 1000;
-  const maxAttempts = options?.retry?.maxAttempts ?? 3;
-  const backoff = options?.retry?.backoff ?? 'exponential';
-  const initialDelayMs = options?.retry?.initialDelayMs ?? 1000;
-  const maxDelayMs = options?.retry?.maxDelayMs ?? 30_000;
-  const jitter = options?.retry?.jitter ?? true;
-  const dropPolicy = options?.dropPolicy ?? 'oldest';
-  const onDropped = options?.onDropped;
-
-  if (!Number.isFinite(batchSize) || batchSize <= 0) {
-    throw new Error(
-      `[autotel/drain-pipeline] batch.size must be a positive finite number, got: ${batchSize}`,
-    );
-  }
-  if (!Number.isFinite(intervalMs) || intervalMs <= 0) {
-    throw new Error(
-      `[autotel/drain-pipeline] batch.intervalMs must be a positive finite number, got: ${intervalMs}`,
-    );
-  }
-  if (!Number.isFinite(maxBufferSize) || maxBufferSize <= 0) {
-    throw new Error(
-      `[autotel/drain-pipeline] maxBufferSize must be a positive finite number, got: ${maxBufferSize}`,
-    );
-  }
-  if (!Number.isFinite(maxAttempts) || maxAttempts <= 0) {
-    throw new Error(
-      `[autotel/drain-pipeline] retry.maxAttempts must be a positive finite number, got: ${maxAttempts}`,
-    );
-  }
-
-  return (drain: (batch: T[]) => void | Promise<void>): PipelineDrainFn<T> => {
-    const buffer: T[] = [];
-    let timer: ReturnType<typeof setTimeout> | null = null;
-    let activeFlush: Promise<void> | null = null;
-    let isShutdown = false;
-
-    const clearTimer = () => {
-      if (timer) {
-        clearTimeout(timer);
-        timer = null;
-      }
-    };
-
-    const computeDelay = (attempt: number): number => {
-      const base =
-        backoff === 'fixed'
-          ? initialDelayMs
-          : backoff === 'linear'
-            ? initialDelayMs * attempt
-            : initialDelayMs * 2 ** (attempt - 1);
-
-      const bounded = Math.min(base, maxDelayMs);
-      if (!jitter || bounded <= 0) return bounded;
-      const factor = 0.5 + Math.random(); // [0.5, 1.5)
-      return Math.max(0, Math.round(bounded * factor));
-    };
-
-    const sendWithRetry = async (batch: T[]): Promise<void> => {
-      let lastError: Error | undefined;
-      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-        try {
-          await drain(batch);
-          return;
-        } catch (error) {
-          lastError = error instanceof Error ? error : new Error(String(error));
-          if (attempt < maxAttempts) {
-            await wait(computeDelay(attempt));
-          }
-        }
-      }
-      onDropped?.(batch, lastError);
-    };
-
-    const drainBuffer = async (): Promise<void> => {
-      while (buffer.length > 0) {
-        const batch = buffer.splice(0, batchSize);
-        await sendWithRetry(batch);
-      }
-    };
-
-    const scheduleFlush = () => {
-      if (isShutdown || timer || activeFlush) return;
-      timer = setTimeout(() => {
-        timer = null;
-        startFlush();
-      }, intervalMs);
-      timer.unref?.();
-    };
-
-    const startFlush = () => {
-      if (activeFlush || isShutdown) return;
-      activeFlush = drainBuffer().finally(() => {
-        activeFlush = null;
-        if (isShutdown) return;
-        if (buffer.length >= batchSize) {
-          startFlush();
-        } else if (buffer.length > 0) {
-          scheduleFlush();
-        }
-      });
-    };
-
-    const push = (ctx: T) => {
-      if (isShutdown) return;
-
-      if (buffer.length >= maxBufferSize) {
-        if (dropPolicy === 'newest') {
-          onDropped?.([ctx]);
-          return;
-        }
-        const dropped = buffer.splice(0, 1);
-        onDropped?.(dropped);
-      }
-
-      buffer.push(ctx);
-      if (buffer.length >= batchSize) {
-        clearTimer();
-        startFlush();
-      } else {
-        scheduleFlush();
-      }
-    };
-
-    const flush = async (): Promise<void> => {
-      clearTimer();
-      if (activeFlush) await activeFlush;
-
-      const snapshot = buffer.length;
-      if (snapshot <= 0) return;
-      const toFlush = buffer.splice(0, snapshot);
-      while (toFlush.length > 0) {
-        const batch = toFlush.splice(0, batchSize);
-        await sendWithRetry(batch);
-      }
-    };
-
-    const shutdown = async (): Promise<void> => {
-      isShutdown = true;
-      await flush();
-    };
-
-    const fn = push as PipelineDrainFn<T>;
-    fn.flush = flush;
-    fn.shutdown = shutdown;
-    Object.defineProperty(fn, 'pending', {
-      enumerable: true,
-      get: () => buffer.length,
-    });
-    return fn;
-  };
-}