autotel 2.2.0 → 2.4.0

package/dist/trace-helpers.cjs

@@ -1,54 +1,54 @@
 'use strict';
 
-var chunkTRI4V5BF_cjs = require('./chunk-TRI4V5BF.cjs');
-require('./chunk-NHCNRQD3.cjs');
+var chunk2EHB2KXS_cjs = require('./chunk-2EHB2KXS.cjs');
+require('./chunk-IW37CN6L.cjs');
 require('./chunk-G7VZBCD6.cjs');
 
 
 
 Object.defineProperty(exports, "createDeterministicTraceId", {
   enumerable: true,
-  get: function () { return chunkTRI4V5BF_cjs.createDeterministicTraceId; }
+  get: function () { return chunk2EHB2KXS_cjs.createDeterministicTraceId; }
 });
 Object.defineProperty(exports, "enrichWithTraceContext", {
   enumerable: true,
-  get: function () { return chunkTRI4V5BF_cjs.enrichWithTraceContext; }
+  get: function () { return chunk2EHB2KXS_cjs.enrichWithTraceContext; }
 });
 Object.defineProperty(exports, "finalizeSpan", {
   enumerable: true,
-  get: function () { return chunkTRI4V5BF_cjs.finalizeSpan; }
+  get: function () { return chunk2EHB2KXS_cjs.finalizeSpan; }
 });
 Object.defineProperty(exports, "flattenMetadata", {
   enumerable: true,
-  get: function () { return chunkTRI4V5BF_cjs.flattenMetadata; }
+  get: function () { return chunk2EHB2KXS_cjs.flattenMetadata; }
 });
 Object.defineProperty(exports, "getActiveContext", {
   enumerable: true,
-  get: function () { return chunkTRI4V5BF_cjs.getActiveContext; }
+  get: function () { return chunk2EHB2KXS_cjs.getActiveContext; }
 });
 Object.defineProperty(exports, "getActiveSpan", {
   enumerable: true,
-  get: function () { return chunkTRI4V5BF_cjs.getActiveSpan; }
+  get: function () { return chunk2EHB2KXS_cjs.getActiveSpan; }
 });
 Object.defineProperty(exports, "getTraceContext", {
   enumerable: true,
-  get: function () { return chunkTRI4V5BF_cjs.getTraceContext; }
+  get: function () { return chunk2EHB2KXS_cjs.getTraceContext; }
 });
 Object.defineProperty(exports, "getTracer", {
   enumerable: true,
-  get: function () { return chunkTRI4V5BF_cjs.getTracer; }
+  get: function () { return chunk2EHB2KXS_cjs.getTracer; }
 });
 Object.defineProperty(exports, "isTracing", {
   enumerable: true,
-  get: function () { return chunkTRI4V5BF_cjs.isTracing; }
+  get: function () { return chunk2EHB2KXS_cjs.isTracing; }
 });
 Object.defineProperty(exports, "runWithSpan", {
   enumerable: true,
-  get: function () { return chunkTRI4V5BF_cjs.runWithSpan; }
+  get: function () { return chunk2EHB2KXS_cjs.runWithSpan; }
 });
 Object.defineProperty(exports, "setSpanName", {
   enumerable: true,
-  get: function () { return chunkTRI4V5BF_cjs.setSpanName; }
+  get: function () { return chunk2EHB2KXS_cjs.setSpanName; }
 });
 //# sourceMappingURL=trace-helpers.cjs.map
 //# sourceMappingURL=trace-helpers.cjs.map

package/dist/trace-helpers.js

@@ -1,5 +1,5 @@
-export { createDeterministicTraceId, enrichWithTraceContext, finalizeSpan, flattenMetadata, getActiveContext, getActiveSpan, getTraceContext, getTracer, isTracing, runWithSpan, setSpanName } from './chunk-M4ANN7RL.js';
-import './chunk-HCCXC7XG.js';
+export { createDeterministicTraceId, enrichWithTraceContext, finalizeSpan, flattenMetadata, getActiveContext, getActiveSpan, getTraceContext, getTracer, isTracing, runWithSpan, setSpanName } from './chunk-AXCCOSA3.js';
+import './chunk-YHW3MAS7.js';
 import './chunk-Z6ZWNWWR.js';
 //# sourceMappingURL=trace-helpers.js.map
 //# sourceMappingURL=trace-helpers.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autotel",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Write Once, Observe Anywhere",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -160,10 +160,10 @@
   "license": "MIT",
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "import-in-the-middle": "^1.11.0",
-    "yaml": "^2.6.0",
+    "import-in-the-middle": "^2.0.0",
+    "yaml": "^2.8.1",
     "@opentelemetry/api-logs": "^0.208.0",
-    "@opentelemetry/auto-instrumentations-node": "^0.67.1",
+    "@opentelemetry/auto-instrumentations-node": "^0.67.2",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.208.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.208.0",
     "@opentelemetry/instrumentation-pino": "^0.55.0",
@@ -184,7 +184,7 @@
     "@opentelemetry/resource-detector-gcp": "^0.43.0",
     "@opentelemetry/sdk-logs": "^0.208.0",
     "@opentelemetry/sdk-trace-node": "^2.2.0",
-    "@traceloop/node-server-sdk": "^0.21.1",
+    "@traceloop/node-server-sdk": "^0.22.0",
     "pino": "^10.1.0",
     "pino-pretty": "^13.1.2"
   },
@@ -231,7 +231,7 @@
     "@edge-runtime/vm": "^5.0.0",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/context-async-hooks": "^2.2.0",
-    "@opentelemetry/auto-instrumentations-node": "^0.67.1",
+    "@opentelemetry/auto-instrumentations-node": "^0.67.2",
     "@opentelemetry/exporter-logs-otlp-grpc": "^0.208.0",
     "@opentelemetry/exporter-logs-otlp-http": "^0.208.0",
     "@opentelemetry/exporter-metrics-otlp-grpc": "^0.208.0",

package/src/functional.strict-types.typecheck.ts

@@ -0,0 +1,53 @@
+/**
+ * Strict type inference test for the bug:
+ * trace() with name parameter returns unknown type
+ */
+
+import { trace } from './functional';
+
+// This test file should be checked with: npx tsc --noEmit
+
+// Helper type to detect unknown - this will be 'true' if T is unknown, 'false' otherwise
+type IsUnknown<T> = unknown extends T
+  ? T extends unknown
+    ? true
+    : false
+  : false;
+
+// Test 1: With explicit TraceContext type - this should always work
+const withExplicitType = trace('test-span', () => async () => {
+  return { foo: 'bar' };
+});
+
+// Type assertion - this line should compile without error if type is inferred correctly
+const _test1: () => Promise<{ foo: string }> = withExplicitType;
+
+// Test 2: Without explicit TraceContext type - this is the bug scenario
+const withoutExplicitType = trace('test-span', () => async () => {
+  return { foo: 'bar' };
+});
+
+// Get the inner type of the Promise returned by the function
+type InnerReturnType = Awaited<ReturnType<typeof withoutExplicitType>>;
+
+// This will be 'true' if the bug exists (type is unknown)
+type IsBugPresent = IsUnknown<InnerReturnType>;
+
+// Type assertion - if the bug exists, this will fail because IsBugPresent is 'true'
+// If the bug is fixed, IsBugPresent is 'false' and this compiles
+const _bugCheck: IsBugPresent extends false ? 'fixed' : never = 'fixed';
+
+// Type assertion - if the bug exists, this line will fail compilation
+// because the return type would be () => Promise<unknown>
+const _test2: () => Promise<{ foo: string }> = withoutExplicitType;
+
+// Test 3: Alternative - check if we can access .foo on the result
+async function testAccess() {
+  const result = await withoutExplicitType();
+  // If the type is unknown, TypeScript will error on .foo access
+  // If the type is { foo: string }, this compiles fine
+  return result.foo;
+}
+
+// Prevent unused variable warnings
+export { _test1, _test2, testAccess, _bugCheck };

package/src/functional.test.ts

@@ -1126,4 +1126,159 @@ describe('Functional API', () => {
       expect(collector.getSpans()).toHaveLength(1);
     });
   });
+
+  describe('Array attribute support', () => {
+    it('should support string array attributes', async () => {
+      const collector = createTraceCollector();
+
+      await trace(async (ctx: TraceContext) => {
+        ctx.setAttribute('tags', ['qa', 'test', 'automated']);
+        return 'done';
+      });
+
+      const spans = collector.getSpans();
+      expect(spans).toHaveLength(1);
+      expect(spans[0]!.attributes['tags']).toEqual(['qa', 'test', 'automated']);
+    });
+
+    it('should support number array attributes', async () => {
+      const collector = createTraceCollector();
+
+      await trace(async (ctx: TraceContext) => {
+        ctx.setAttribute('scores', [95, 87, 92]);
+        return 'done';
+      });
+
+      const spans = collector.getSpans();
+      expect(spans).toHaveLength(1);
+      expect(spans[0]!.attributes['scores']).toEqual([95, 87, 92]);
+    });
+
+    it('should support boolean array attributes', async () => {
+      const collector = createTraceCollector();
+
+      await trace(async (ctx: TraceContext) => {
+        ctx.setAttribute('flags', [true, false, true]);
+        return 'done';
+      });
+
+      const spans = collector.getSpans();
+      expect(spans).toHaveLength(1);
+      expect(spans[0]!.attributes['flags']).toEqual([true, false, true]);
+    });
+
+    it('should support mixed attributes including arrays via setAttributes', async () => {
+      const collector = createTraceCollector();
+
+      await trace(async (ctx: TraceContext) => {
+        ctx.setAttributes({
+          'user.id': 'user_123',
+          environment: 'development',
+          version: '1.0.0',
+          tags: ['qa', 'test'],
+          scores: [1, 2, 3],
+        });
+        return 'done';
+      });
+
+      const spans = collector.getSpans();
+      expect(spans).toHaveLength(1);
+      expect(spans[0]!.attributes['user.id']).toBe('user_123');
+      expect(spans[0]!.attributes['environment']).toBe('development');
+      expect(spans[0]!.attributes['tags']).toEqual(['qa', 'test']);
+      expect(spans[0]!.attributes['scores']).toEqual([1, 2, 3]);
+    });
+  });
+
+  describe('Full OTel Span API', () => {
+    it('should support addEvent for span events', async () => {
+      const collector = createTraceCollector();
+
+      // Verify the method can be called without error
+      const result = await trace(async (ctx: TraceContext) => {
+        ctx.addEvent('order.started', { 'order.id': '123' });
+        ctx.addEvent('items.fetched', { 'item.count': 5 });
+        return 'done';
+      });
+
+      expect(result).toBe('done');
+      expect(collector.getSpans()).toHaveLength(1);
+    });
+
+    it('should support updateName for dynamic span naming', async () => {
+      const collector = createTraceCollector();
+
+      await trace('initial.name', async (ctx: TraceContext) => {
+        ctx.updateName('updated.name');
+        return 'done';
+      });
+
+      const spans = collector.getSpans();
+      expect(spans).toHaveLength(1);
+      expect(spans[0]!.name).toBe('updated.name');
+    });
+
+    it('should support isRecording', async () => {
+      const collector = createTraceCollector();
+      let wasRecording = false;
+
+      await trace(async (ctx: TraceContext) => {
+        wasRecording = ctx.isRecording();
+        return 'done';
+      });
+
+      expect(wasRecording).toBe(true);
+      expect(collector.getSpans()).toHaveLength(1);
+    });
+
+    it('should support addLink for span links', async () => {
+      const collector = createTraceCollector();
+
+      // Create a mock span context to link to
+      const linkContext = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: 'b7ad6b7169203331',
+        traceFlags: 1,
+      };
+
+      // Verify the method can be called without error
+      const result = await trace(async (ctx: TraceContext) => {
+        ctx.addLink({ context: linkContext });
+        return 'done';
+      });
+
+      expect(result).toBe('done');
+      expect(collector.getSpans()).toHaveLength(1);
+    });
+
+    it('should support addLinks for multiple span links', async () => {
+      const collector = createTraceCollector();
+
+      const links = [
+        {
+          context: {
+            traceId: '0af7651916cd43dd8448eb211c80319c',
+            spanId: 'b7ad6b7169203331',
+            traceFlags: 1,
+          },
+        },
+        {
+          context: {
+            traceId: '0af7651916cd43dd8448eb211c80319d',
+            spanId: 'b7ad6b7169203332',
+            traceFlags: 1,
+          },
+        },
+      ];
+
+      // Verify the method can be called without error
+      const result = await trace(async (ctx: TraceContext) => {
+        ctx.addLinks(links);
+        return 'done';
+      });
+
+      expect(result).toBe('done');
+      expect(collector.getSpans()).toHaveLength(1);
+    });
+  });
 });

package/src/functional.ts

@@ -406,6 +406,11 @@ function createDummyCtx<
     setAttributes: () => {},
     setStatus: () => {},
     recordException: () => {},
+    addEvent: () => {},
+    addLink: () => {},
+    addLinks: () => {},
+    updateName: () => {},
+    isRecording: () => false,
     getBaggage: () => {},
     setBaggage: () => '',
     deleteBaggage: () => {},
@@ -1636,11 +1641,11 @@ export function trace<TReturn = unknown>(
   name: string,
   fn: ExcludeFactoryReturn<(ctx: TraceContext) => TReturn>,
 ): TReturn;
-// Overload 2b: Name + factory sync function with no args - non-generic for type inference
-export function trace(
+// Overload 2b: Name + factory sync function with no args
+export function trace<TReturn = unknown>(
   name: string,
-  fnFactory: (ctx: TraceContext) => () => unknown,
-): () => unknown;
+  fnFactory: (ctx: TraceContext) => () => TReturn,
+): () => TReturn;
 // Overload 2c: Name + factory sync function - non-generic for type inference
 export function trace<TArgs extends unknown[], TReturn>(
   name: string,
@@ -1670,11 +1675,11 @@ export function trace<TReturn = unknown>(
   options: TracingOptions<[], TReturn>,
   fn: (ctx: TraceContext) => TReturn,
 ): TReturn;
-// Overload 3b: Options + factory sync function with no args - non-generic for type inference
-export function trace(
-  options: TracingOptions,
-  fnFactory: (ctx: TraceContext) => () => unknown,
-): () => unknown;
+// Overload 3b: Options + factory sync function with no args
+export function trace<TReturn = unknown>(
+  options: TracingOptions<[], TReturn>,
+  fnFactory: (ctx: TraceContext) => () => TReturn,
+): () => TReturn;
 // Overload 3c: Options + factory sync function - non-generic for type inference
 export function trace<TArgs extends unknown[], TReturn>(
   options: TracingOptions<TArgs, TReturn>,
@@ -1740,11 +1745,11 @@ export function trace<TReturn = unknown>(
   name: string,
   fn: ExcludeFactoryReturn<(ctx: TraceContext) => Promise<TReturn>>,
 ): Promise<TReturn>;
-// Overload 5b: Name + factory async function with no args - non-generic for type inference
-export function trace(
+// Overload 5b: Name + factory async function with no args
+export function trace<TReturn = unknown>(
   name: string,
-  fnFactory: (ctx: TraceContext) => () => Promise<unknown>,
-): () => Promise<unknown>;
+  fnFactory: (ctx: TraceContext) => () => Promise<TReturn>,
+): () => Promise<TReturn>;
 // Overload 5c: Name + factory async function - non-generic for type inference
 export function trace<TArgs extends unknown[], TReturn>(
   name: string,
@@ -1776,11 +1781,11 @@ export function trace<TReturn = unknown>(
   options: TracingOptions<[], TReturn>,
   fn: (ctx: TraceContext) => Promise<TReturn>,
 ): Promise<TReturn>;
-// Overload 6b: Options + factory async function with no args - non-generic for type inference
-export function trace(
-  options: TracingOptions,
-  fnFactory: (ctx: TraceContext) => () => Promise<unknown>,
-): () => Promise<unknown>;
+// Overload 6b: Options + factory async function with no args
+export function trace<TReturn = unknown>(
+  options: TracingOptions<[], TReturn>,
+  fnFactory: (ctx: TraceContext) => () => Promise<TReturn>,
+): () => Promise<TReturn>;
 // Overload 6c: Options + factory async function - non-generic for type inference
 export function trace<TArgs extends unknown[], TReturn>(
   options: TracingOptions<TArgs, TReturn>,

package/src/functional.types.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Type inference tests for trace() function
+ *
+ * These tests verify that TypeScript correctly infers return types
+ * for various trace() call signatures.
+ *
+ * Run with: pnpm run type-check
+ */
+
+import { describe, it, expect } from 'vitest';
+import { trace } from './functional';
+import type { TraceContext } from './trace-helpers';
+
+describe('trace() type inference', () => {
+  // Helper to ensure we're getting the expected type
+  // If the type is `unknown`, accessing .foo will cause a type error
+  // This is a compile-time check
+
+  it('trace(fn) - single argument factory should infer return type', async () => {
+    // This SHOULD work - returns Promise<{ foo: string }>
+    const fn1 = trace((_ctx: TraceContext) => async () => {
+      return { foo: 'bar' };
+    });
+
+    const result1 = await fn1();
+    // If type is correct, this compiles. If unknown, this errors.
+    expect(result1.foo).toBe('bar');
+  });
+
+  it('trace(fn) - without explicit ctx type should infer return type', async () => {
+    // Test from bug report: ctx without explicit type annotation
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const fn1 = trace((ctx) => async () => {
+      return { foo: 'bar' };
+    });
+
+    const result1 = await fn1();
+    // If type is correct, this compiles. If unknown, this errors.
+    expect(result1.foo).toBe('bar');
+  });
+
+  it('trace(name, fn) - two argument factory should infer return type', async () => {
+    // BUG: This SHOULD return Promise<{ foo: string }> but might return unknown
+    const fn2 = trace('my-span-name', (_ctx: TraceContext) => async () => {
+      return { foo: 'bar' };
+    });
+
+    const result2 = await fn2();
+    // If the bug exists, TypeScript will error here because result2 is `unknown`
+    // and we can't access .foo on unknown
+    expect(result2.foo).toBe('bar');
+  });
+
+  it('trace(name, fn) - without explicit ctx type should infer return type', async () => {
+    // Exact reproduction from bug report
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const fn2 = trace('my-span-name', (ctx) => async () => {
+      return { foo: 'bar' };
+    });
+
+    const result2 = await fn2();
+    // If the type is properly inferred as { foo: string }, accessing .foo should work.
+    // If the bug exists and type is `unknown`, TypeScript will error here.
+    // Adding @ts-expect-error would make the type check pass ONLY if there's an error.
+    expect(result2.foo).toBe('bar');
+  });
+
+  it('BUG VERIFICATION: trace(name, fn) returns unknown type', async () => {
+    // This test uses @ts-expect-error to VERIFY the bug exists
+    // If @ts-expect-error is "unused", that means the bug is FIXED
+    // If @ts-expect-error is needed, the bug EXISTS
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const fn2 = trace('my-span-name', (ctx) => async () => {
+      return { foo: 'bar' };
+    });
+
+    const result2 = await fn2();
+
+    // If result2 is inferred as `unknown`, we'd need @ts-expect-error
+    // If result2 is inferred as `{ foo: string }`, this line works without error
+    // BUG FIXED: No @ts-expect-error needed anymore!
+    const _fooValue: string = result2.foo;
+    expect(_fooValue).toBe('bar');
+  });
+
+  it('trace(fn) with args should infer return type', async () => {
+    const fn3 = trace(
+      (_ctx: TraceContext) => async (name: string, age: number) => {
+        return { name, age };
+      },
+    );
+
+    const result3 = await fn3('Alice', 30);
+    expect(result3.name).toBe('Alice');
+    expect(result3.age).toBe(30);
+  });
+
+  it('trace(name, fn) with args should infer return type', async () => {
+    // BUG: This should also infer correctly
+    const fn4 = trace(
+      'user.create',
+      (_ctx: TraceContext) => async (name: string, age: number) => {
+        return { name, age };
+      },
+    );
+
+    const result4 = await fn4('Bob', 25);
+    // If type is correct, this compiles. If unknown, this errors.
+    expect(result4.name).toBe('Bob');
+    expect(result4.age).toBe(25);
+  });
+
+  it('trace(name, fn) sync factory should infer return type', () => {
+    const fn5 = trace('sync.operation', (_ctx: TraceContext) => () => {
+      return 42;
+    });
+
+    const result5 = fn5();
+    // Type should be number, not unknown
+    const numResult: number = result5;
+    expect(numResult).toBe(42);
+  });
+
+  it('trace(name, fn) plain function should infer return type', async () => {
+    // Plain function (no ctx) with name
+    const fn6 = trace('plain.function', async (a: number, b: number) => {
+      return a + b;
+    });
+
+    const result6 = await fn6(2, 3);
+    // Type should be number, not unknown
+    const numResult: number = result6;
+    expect(numResult).toBe(5);
+  });
+});

package/src/trace-context.ts

@@ -7,6 +7,8 @@ import type {
   SpanStatusCode,
   BaggageEntry,
   Context,
+  Link,
+  TimeInput,
 } from '@opentelemetry/api';
 import { context, propagation } from '@opentelemetry/api';
 import { AsyncLocalStorage } from 'node:async_hooks';
@@ -76,14 +78,44 @@ export interface TraceContextBase {
   correlationId: string;
 }
 
+/**
+ * Attribute value types following OpenTelemetry specification.
+ * Supports primitive values and arrays of homogeneous primitives.
+ */
+export type AttributeValue =
+  | string
+  | number
+  | boolean
+  | string[]
+  | number[]
+  | boolean[];
+
 /**
  * Span methods available on trace context
  */
 export interface SpanMethods {
-  setAttribute(key: string, value: string | number | boolean): void;
-  setAttributes(attrs: Record<string, string | number | boolean>): void;
+  /** Set a single attribute on the span */
+  setAttribute(key: string, value: AttributeValue): void;
+  /** Set multiple attributes on the span */
+  setAttributes(attrs: Record<string, AttributeValue>): void;
+  /** Set the status of the span */
   setStatus(status: { code: SpanStatusCode; message?: string }): void;
-  recordException(exception: Error): void;
+  /** Record an exception on the span */
+  recordException(exception: Error, time?: TimeInput): void;
+  /** Add an event to the span (for logging milestones/checkpoints) */
+  addEvent(
+    name: string,
+    attributesOrStartTime?: Record<string, AttributeValue> | TimeInput,
+    startTime?: TimeInput,
+  ): void;
+  /** Add a link to another span */
+  addLink(link: Link): void;
+  /** Add multiple links to other spans */
+  addLinks(links: Link[]): void;
+  /** Update the span name dynamically */
+  updateName(name: string): void;
+  /** Check if the span is recording */
+  isRecording(): boolean;
 }
 
 /**
@@ -355,6 +387,11 @@ export function createTraceContext<
     setAttributes: span.setAttributes.bind(span),
     setStatus: span.setStatus.bind(span),
     recordException: span.recordException.bind(span),
+    addEvent: span.addEvent.bind(span),
+    addLink: span.addLink.bind(span),
+    addLinks: span.addLinks.bind(span),
+    updateName: span.updateName.bind(span),
+    isRecording: span.isRecording.bind(span),
     ...baggageHelpers,
   };
 }