autotel 2.1.0

package/src/trace-helpers.new.test.ts

@@ -0,0 +1,278 @@
+/**
+ * Tests for new trace helper utilities
+ */
+
+import { describe, it, expect } from 'vitest';
+import { createDeterministicTraceId, flattenMetadata } from './trace-helpers';
+
+describe('createDeterministicTraceId', () => {
+  it('should generate consistent trace IDs from the same seed', async () => {
+    const seed = 'request-123';
+    const traceId1 = await createDeterministicTraceId(seed);
+    const traceId2 = await createDeterministicTraceId(seed);
+
+    expect(traceId1).toBe(traceId2);
+  });
+
+  it('should generate different trace IDs from different seeds', async () => {
+    const traceId1 = await createDeterministicTraceId('seed-1');
+    const traceId2 = await createDeterministicTraceId('seed-2');
+
+    expect(traceId1).not.toBe(traceId2);
+  });
+
+  it('should generate valid 32-character hex trace IDs', async () => {
+    const traceId = await createDeterministicTraceId('test-seed');
+
+    expect(traceId).toMatch(/^[0-9a-f]{32}$/);
+    expect(traceId).toHaveLength(32);
+  });
+
+  it('should handle empty string seed', async () => {
+    const traceId = await createDeterministicTraceId('');
+
+    expect(traceId).toMatch(/^[0-9a-f]{32}$/);
+  });
+
+  it('should handle long seed strings', async () => {
+    const longSeed = 'a'.repeat(1000);
+    const traceId = await createDeterministicTraceId(longSeed);
+
+    expect(traceId).toMatch(/^[0-9a-f]{32}$/);
+  });
+
+  it('should handle special characters in seed', async () => {
+    const specialSeed = 'test!@#$%^&*()_+-=[]{}|;:,.<>?';
+    const traceId = await createDeterministicTraceId(specialSeed);
+
+    expect(traceId).toMatch(/^[0-9a-f]{32}$/);
+  });
+
+  it('should handle unicode in seed', async () => {
+    const unicodeSeed = 'test-中文-🚀';
+    const traceId = await createDeterministicTraceId(unicodeSeed);
+
+    expect(traceId).toMatch(/^[0-9a-f]{32}$/);
+  });
+});
+
+describe('flattenMetadata', () => {
+  it('should flatten simple object with default prefix', () => {
+    const metadata = {
+      userId: '123',
+      email: 'user@example.com',
+      plan: 'premium',
+    };
+
+    const flattened = flattenMetadata(metadata);
+
+    expect(flattened).toEqual({
+      'metadata.userId': '123',
+      'metadata.email': 'user@example.com',
+      'metadata.plan': 'premium',
+    });
+  });
+
+  it('should use custom prefix', () => {
+    const metadata = {
+      userId: '123',
+      email: 'user@example.com',
+    };
+
+    const flattened = flattenMetadata(metadata, 'user');
+
+    expect(flattened).toEqual({
+      'user.userId': '123',
+      'user.email': 'user@example.com',
+    });
+  });
+
+  it('should recursively flatten nested objects', () => {
+    const metadata = {
+      count: 42,
+      active: true,
+      config: { timeout: 5000, retries: 3 },
+      tags: ['a', 'b', 'c'],
+    };
+
+    const flattened = flattenMetadata(metadata);
+
+    expect(flattened).toEqual({
+      'metadata.count': '42',
+      'metadata.active': 'true',
+      'metadata.config.timeout': '5000',
+      'metadata.config.retries': '3',
+      'metadata.tags': '["a","b","c"]',
+    });
+  });
+
+  it('should match documentation example - order metadata', () => {
+    const metadata = {
+      user: { id: 'user-123', tier: 'premium' },
+      payment: { method: 'card', processor: 'stripe' },
+      items: 5,
+    };
+
+    const flattened = flattenMetadata(metadata);
+
+    expect(flattened).toEqual({
+      'metadata.user.id': 'user-123',
+      'metadata.user.tier': 'premium',
+      'metadata.payment.method': 'card',
+      'metadata.payment.processor': 'stripe',
+      'metadata.items': '5',
+    });
+  });
+
+  it('should handle deeply nested objects', () => {
+    const metadata = {
+      level1: {
+        level2: {
+          level3: {
+            deepValue: 'found',
+          },
+        },
+      },
+    };
+
+    const flattened = flattenMetadata(metadata);
+
+    expect(flattened).toEqual({
+      'metadata.level1.level2.level3.deepValue': 'found',
+    });
+  });
+
+  it('should skip null values', () => {
+    const metadata = {
+      userId: '123',
+      email: null,
+      plan: 'premium',
+    };
+
+    const flattened = flattenMetadata(metadata);
+
+    expect(flattened).toEqual({
+      'metadata.userId': '123',
+      'metadata.plan': 'premium',
+    });
+  });
+
+  it('should skip undefined values', () => {
+    const metadata = {
+      userId: '123',
+      email: undefined,
+      plan: 'premium',
+    };
+
+    const flattened = flattenMetadata(metadata);
+
+    expect(flattened).toEqual({
+      'metadata.userId': '123',
+      'metadata.plan': 'premium',
+    });
+  });
+
+  it('should handle empty object', () => {
+    const flattened = flattenMetadata({});
+
+    expect(flattened).toEqual({});
+  });
+
+  it('should handle circular references gracefully', () => {
+    const metadata: { userId: string; self?: unknown } = {
+      userId: '123',
+    };
+    metadata.self = metadata;
+
+    const flattened = flattenMetadata(metadata);
+
+    // Processes properties until it encounters the cycle
+    expect(flattened).toEqual({
+      'metadata.userId': '123',
+      'metadata.self.userId': '123',
+      'metadata.self.self': '<circular-reference>',
+    });
+  });
+
+  it('should preserve string values as-is without JSON serialization', () => {
+    const metadata = {
+      name: 'John',
+      description: 'A developer',
+    };
+
+    const flattened = flattenMetadata(metadata);
+
+    // Strings should not have quotes added
+    expect(flattened).toEqual({
+      'metadata.name': 'John',
+      'metadata.description': 'A developer',
+    });
+  });
+
+  it('should handle Date objects', () => {
+    const date = new Date('2024-01-15T12:00:00.000Z');
+    const metadata = {
+      timestamp: date,
+    };
+
+    const flattened = flattenMetadata(metadata);
+
+    expect(flattened['metadata.timestamp']).toBe(JSON.stringify(date));
+  });
+
+  it('should handle nested objects', () => {
+    const metadata = {
+      user: {
+        id: '123',
+        settings: {
+          theme: 'dark',
+          notifications: true,
+        },
+      },
+    };
+
+    const flattened = flattenMetadata(metadata);
+
+    expect(flattened).toEqual({
+      'metadata.user.id': '123',
+      'metadata.user.settings.theme': 'dark',
+      'metadata.user.settings.notifications': 'true',
+    });
+  });
+
+  it('should handle arrays', () => {
+    const metadata = {
+      tags: ['typescript', 'nodejs', 'observability'],
+      numbers: [1, 2, 3],
+    };
+
+    const flattened = flattenMetadata(metadata);
+
+    expect(flattened).toEqual({
+      'metadata.tags': '["typescript","nodejs","observability"]',
+      'metadata.numbers': '[1,2,3]',
+    });
+  });
+
+  it('should handle mixed types', () => {
+    const metadata = {
+      string: 'value',
+      number: 123,
+      boolean: false,
+      nullValue: null,
+      undefinedValue: undefined,
+      object: { nested: 'data' },
+      array: [1, 2, 3],
+    };
+
+    const flattened = flattenMetadata(metadata);
+
+    expect(flattened).toEqual({
+      'metadata.string': 'value',
+      'metadata.number': '123',
+      'metadata.boolean': 'false',
+      'metadata.object.nested': 'data',
+      'metadata.array': '[1,2,3]',
+    });
+  });
+});

package/src/trace-helpers.test.ts

@@ -0,0 +1,242 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  getTracer,
+  getActiveSpan,
+  getActiveContext,
+  runWithSpan,
+  getTraceContext,
+} from './trace-helpers';
+import { init } from './init';
+import { createTraceCollector } from './testing';
+import { span } from './functional';
+import { getConfig } from './config';
+
+describe('Trace Helpers', () => {
+  beforeEach(() => {
+    init({ service: 'test-service' });
+  });
+
+  describe('getTracer()', () => {
+    it('should return a tracer instance', () => {
+      const tracer = getTracer('my-service');
+      expect(tracer).toBeDefined();
+      expect(typeof tracer.startSpan).toBe('function');
+      expect(typeof tracer.startActiveSpan).toBe('function');
+    });
+
+    it('should accept optional version parameter', () => {
+      const tracer = getTracer('my-service', '1.0.0');
+      expect(tracer).toBeDefined();
+    });
+
+    it('should work with the configured mock tracer', () => {
+      const collector = createTraceCollector();
+      // Get the configured mock tracer instead of creating a new one
+      const tracer = getConfig().tracer;
+
+      const testSpan = tracer.startSpan('custom.operation');
+      testSpan.setAttribute('test.key', 'test-value');
+      testSpan.end();
+
+      const spans = collector.getSpans();
+      expect(spans).toHaveLength(1);
+      expect(spans[0]!.name).toBe('custom.operation');
+      expect(spans[0]!.attributes['test.key']).toBe('test-value');
+    });
+  });
+
+  describe('getActiveSpan()', () => {
+    it('should return undefined when no span is active', () => {
+      const activeSpan = getActiveSpan();
+      expect(activeSpan).toBeUndefined();
+    });
+
+    it('should return the active span inside a span context', () => {
+      let capturedSpan;
+
+      span({ name: 'test-span' }, (s) => {
+        capturedSpan = getActiveSpan();
+        expect(capturedSpan).toBe(s);
+      });
+
+      expect(capturedSpan).toBeDefined();
+    });
+
+    it('should allow setting attributes on the active span', () => {
+      const collector = createTraceCollector();
+
+      span({ name: 'test-span' }, () => {
+        const activeSpan = getActiveSpan();
+        if (activeSpan) {
+          activeSpan.setAttribute('custom.attribute', 'value');
+        }
+      });
+
+      const spans = collector.getSpans();
+      expect(spans).toHaveLength(1);
+      expect(spans[0]!.attributes['custom.attribute']).toBe('value');
+    });
+
+    it('should allow calling span methods on the active span', () => {
+      const collector = createTraceCollector();
+
+      span({ name: 'test-span' }, () => {
+        const activeSpan = getActiveSpan();
+        if (activeSpan) {
+          // Test that we can call span methods
+          expect(typeof activeSpan.addEvent).toBe('function');
+          expect(typeof activeSpan.setAttribute).toBe('function');
+          expect(typeof activeSpan.setStatus).toBe('function');
+          expect(activeSpan.isRecording()).toBe(true);
+
+          // Call addEvent to verify it doesn't throw
+          activeSpan.addEvent('custom.event', { eventData: 'test-data' });
+        }
+      });
+
+      const spans = collector.getSpans();
+      expect(spans).toHaveLength(1);
+    });
+  });
+
+  describe('getActiveContext()', () => {
+    it('should return a context', () => {
+      const ctx = getActiveContext();
+      expect(ctx).toBeDefined();
+    });
+
+    it('should return different contexts in different execution paths', () => {
+      const rootContext = getActiveContext();
+      let nestedContext;
+
+      span({ name: 'test-span' }, () => {
+        nestedContext = getActiveContext();
+      });
+
+      // Contexts should be different when inside a span
+      expect(nestedContext).toBeDefined();
+      expect(nestedContext).not.toBe(rootContext);
+    });
+  });
+
+  describe('runWithSpan()', () => {
+    it('should execute function with span as active', () => {
+      createTraceCollector(); // Set up mock tracer
+      const tracer = getConfig().tracer;
+      const testSpan = tracer.startSpan('test-operation');
+
+      let capturedSpan;
+      const result = runWithSpan(testSpan, () => {
+        capturedSpan = getActiveSpan();
+        return 42;
+      });
+
+      expect(result).toBe(42);
+      expect(capturedSpan).toBe(testSpan);
+
+      testSpan.end();
+    });
+
+    it('should execute async function with span as active', async () => {
+      createTraceCollector(); // Set up mock tracer
+      const tracer = getConfig().tracer;
+      const testSpan = tracer.startSpan('async-operation');
+
+      let capturedSpan;
+      const result = await runWithSpan(testSpan, async () => {
+        capturedSpan = getActiveSpan();
+        return 'async-result';
+      });
+
+      expect(result).toBe('async-result');
+      expect(capturedSpan).toBe(testSpan);
+
+      testSpan.end();
+    });
+
+    it('should restore previous context after execution', () => {
+      createTraceCollector(); // Set up mock tracer
+      const tracer = getConfig().tracer;
+      const testSpan = tracer.startSpan('test-operation');
+
+      const contextBefore = getActiveContext();
+
+      runWithSpan(testSpan, () => {
+        // Inside the span context
+        expect(getActiveSpan()).toBe(testSpan);
+      });
+
+      const contextAfter = getActiveContext();
+      expect(contextAfter).toBe(contextBefore);
+
+      testSpan.end();
+    });
+
+    it('should propagate exceptions', () => {
+      createTraceCollector(); // Set up mock tracer
+      const tracer = getConfig().tracer;
+      const testSpan = tracer.startSpan('failing-operation');
+
+      expect(() => {
+        runWithSpan(testSpan, () => {
+          throw new Error('Test error');
+        });
+      }).toThrow('Test error');
+
+      testSpan.end();
+    });
+
+    it('should work with nested spans', () => {
+      const collector = createTraceCollector();
+      // Use the configured mock tracer
+      const tracer = getConfig().tracer;
+
+      const parentSpan = tracer.startSpan('parent');
+
+      runWithSpan(parentSpan, () => {
+        const childSpan = tracer.startSpan('child');
+
+        runWithSpan(childSpan, () => {
+          const activeSpan = getActiveSpan();
+          expect(activeSpan).toBe(childSpan);
+        });
+
+        childSpan.end();
+
+        const activeSpan = getActiveSpan();
+        expect(activeSpan).toBe(parentSpan);
+      });
+
+      parentSpan.end();
+
+      const spans = collector.getSpans();
+      expect(spans).toHaveLength(2);
+
+      const child = spans.find((s) => s.name === 'child');
+      const parent = spans.find((s) => s.name === 'parent');
+
+      expect(child).toBeDefined();
+      expect(parent).toBeDefined();
+    });
+  });
+
+  describe('Integration with getTraceContext()', () => {
+    it('should work together with getTraceContext()', () => {
+      createTraceCollector(); // Set up mock tracer
+      const tracer = getConfig().tracer;
+      const testSpan = tracer.startSpan('test-operation');
+
+      let traceContext;
+      runWithSpan(testSpan, () => {
+        traceContext = getTraceContext();
+      });
+
+      testSpan.end();
+
+      expect(traceContext).toBeDefined();
+      expect(traceContext!.traceId).toBeDefined();
+      expect(traceContext!.spanId).toBeDefined();
+      expect(traceContext!.correlationId).toBeDefined();
+    });
+  });
+});