autotel-adapters 0.3.12 → 0.3.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autotel-adapters",
-  "version": "0.3.12",
+  "version": "0.3.13",
   "description": "Framework adapters and composable DX helpers for autotel",
   "license": "MIT",
   "type": "module",
@@ -56,12 +56,11 @@
   },
   "files": [
     "dist",
-    "src",
     "README.md",
     "skills"
   ],
   "dependencies": {
-    "autotel": "4.1.0"
+    "autotel": "4.2.0"
   },
   "peerDependencies": {
     "hono": ">=4.12.23",

package/src/cloudflare.test.ts

@@ -1,56 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-import { useLogger, withAutotelFetch } from './cloudflare';
-
-describe('cloudflare adapter', () => {
-  it('throws clear error when useLogger is called outside traced context', () => {
-    expect(() =>
-      useLogger({
-        method: 'GET',
-        url: 'https://example.com/health',
-        headers: { 'x-request-id': 'req-1' },
-      }),
-    ).toThrow('[autotel-adapters/cloudflare] No active trace context.');
-  });
-
-  it('provides request-scoped logger inside withAutotelFetch()', async () => {
-    const handler = withAutotelFetch(async (request) => {
-      const log = useLogger(request);
-      log.set({ worker: 'example' });
-      return { ok: true };
-    });
-
-    await expect(
-      handler(
-        { method: 'GET', url: 'https://example.com/orders' },
-        {},
-        {},
-      ),
-    ).resolves.toMatchObject({ ok: true });
-  });
-
-  it('auto-emits one wide event by default', async () => {
-    const onEmit = vi.fn();
-    const handler = withAutotelFetch(
-      async (request) => {
-        useLogger(request).set({ worker: 'example' });
-        return { ok: true };
-      },
-      { requestLoggerOptions: { onEmit } },
-    );
-
-    await handler({ method: 'GET', url: 'https://example.com/orders' }, {}, {});
-    expect(onEmit).toHaveBeenCalledTimes(1);
-  });
-
-  it('does not emit when autoEmit is false', async () => {
-    const onEmit = vi.fn();
-    const handler = withAutotelFetch(async () => ({ ok: true }), {
-      autoEmit: false,
-      requestLoggerOptions: { onEmit },
-    });
-
-    await handler({ method: 'GET', url: 'https://example.com/x' }, {}, {});
-    expect(onEmit).not.toHaveBeenCalled();
-  });
-});
-

package/src/cloudflare.ts

@@ -1,186 +0,0 @@
-import {
-  createDrainPipeline,
-  createStructuredError,
-  getRequestLogger,
-  parseError,
-  trace,
-  type DrainPipelineOptions,
-  type ParsedError,
-  type PipelineDrainFn,
-  type RequestLogger,
-  type RequestLoggerOptions,
-  type StructuredError,
-  type StructuredErrorInput,
-} from 'autotel';
-import { createAdapterToolkit, createUseLogger, getHeader } from './core';
-
-export interface CloudflareRequestLike {
-  method?: string;
-  url?: string;
-  headers?:
-    | { get(name: string): string | null }
-    | Record<string, string | undefined>;
-  cf?: Record<string, unknown>;
-}
-
-export interface CloudflareExecutionContextLike {
-  waitUntil?: (promise: Promise<unknown>) => void;
-  passThroughOnException?: () => void;
-}
-
-export interface CloudflareWithAutotelOptions<TEnv = unknown> {
-  spanName?: string | ((request: CloudflareRequestLike, env: TEnv) => string);
-  requestLoggerOptions?: RequestLoggerOptions;
-  enrich?: (
-    request: CloudflareRequestLike,
-    env: TEnv,
-    ctx: CloudflareExecutionContextLike,
-  ) => Record<string, unknown> | undefined;
-  /** Emit one wide event automatically when the handler settles. Default `true`. */
-  autoEmit?: boolean;
-}
-
-const requestLoggers = new WeakMap<object, RequestLogger>();
-
-function enrichFromRequest(
-  request?: CloudflareRequestLike,
-): Record<string, unknown> | undefined {
-  if (!request) return undefined;
-
-  let route = '/';
-  if (request.url) {
-    try {
-      route = new URL(request.url).pathname;
-    } catch {
-      route = request.url;
-    }
-  }
-
-  const requestId =
-    getHeader(request.headers, 'x-request-id') ??
-    getHeader(request.headers, 'cf-ray');
-
-  return {
-    ...(request.method ? { 'http.request.method': request.method } : {}),
-    ...(request.url ? { 'url.full': request.url } : {}),
-    ...(route ? { 'http.route': route } : {}),
-    ...(requestId ? { 'http.request.id': requestId } : {}),
-    ...(request.cf?.country ? { 'cloudflare.country': request.cf.country } : {}),
-    ...(request.cf?.colo ? { 'cloudflare.colo': request.cf.colo } : {}),
-    ...(request.cf?.city ? { 'cloudflare.city': request.cf.city } : {}),
-  };
-}
-
-const baseUseLogger = createUseLogger<CloudflareRequestLike>({
-  adapterName: 'cloudflare',
-  enrich: enrichFromRequest,
-});
-
-export function useLogger(
-  request?: CloudflareRequestLike,
-  requestLoggerOptions?: RequestLoggerOptions,
-): RequestLogger {
-  if (request) {
-    const existing = requestLoggers.get(request as object);
-    if (existing) return existing;
-  }
-  return baseUseLogger(request, requestLoggerOptions);
-}
-
-export function withAutotelFetch<
-  TEnv,
-  TRequest extends CloudflareRequestLike,
-  TContext extends CloudflareExecutionContextLike,
-  TReturn,
->(
-  handler: (
-    request: TRequest,
-    env: TEnv,
-    ctx: TContext,
-  ) => TReturn | Promise<TReturn>,
-  options?: CloudflareWithAutotelOptions<TEnv>,
-): (
-  request: TRequest,
-  env: TEnv,
-  ctx: TContext,
-) => Promise<TReturn> {
-  return async (
-    request: TRequest,
-    env: TEnv,
-    executionContext: TContext,
-  ): Promise<TReturn> => {
-    const spanName =
-      typeof options?.spanName === 'function'
-        ? options.spanName(request, env)
-        : (options?.spanName ?? `cloudflare.${request.method ?? 'request'}`);
-
-    const wrapped = trace(
-      { name: spanName },
-      (ctx) => async (
-        innerRequest: TRequest,
-        innerEnv: TEnv,
-        innerExecutionContext: TContext,
-      ) => {
-        const log = getRequestLogger(ctx, options?.requestLoggerOptions);
-        const auto = enrichFromRequest(innerRequest);
-        if (auto && Object.keys(auto).length > 0) {
-          log.set(auto);
-        }
-        const custom = options?.enrich?.(
-          innerRequest,
-          innerEnv,
-          innerExecutionContext,
-        );
-        if (custom && Object.keys(custom).length > 0) {
-          log.set(custom);
-        }
-
-        requestLoggers.set(innerRequest as object, log);
-        try {
-          return await handler(innerRequest, innerEnv, innerExecutionContext);
-        } finally {
-          if (options?.autoEmit !== false) {
-            log.emitNow();
-          }
-          requestLoggers.delete(innerRequest as object);
-        }
-      },
-    );
-
-    return await wrapped(request, env, executionContext);
-  };
-}
-
-export function createCloudflareAdapter<TEnv = unknown>(
-  options?: CloudflareWithAutotelOptions<TEnv>,
-) {
-  return {
-    withAutotelFetch: <
-      TRequest extends CloudflareRequestLike,
-      TContext extends CloudflareExecutionContextLike,
-      TReturn,
-    >(
-      handler: (
-        request: TRequest,
-        env: TEnv,
-        ctx: TContext,
-      ) => TReturn | Promise<TReturn>,
-    ) => withAutotelFetch(handler, options),
-    useLogger,
-    parseError: (error: unknown): ParsedError => parseError(error),
-    createStructuredError: (
-      input: StructuredErrorInput,
-    ): StructuredError => createStructuredError(input),
-    createDrainPipeline: <T = unknown>(
-      drainOptions?: DrainPipelineOptions<T>,
-    ): ((batchDrain: (batch: T[]) => void | Promise<void>) => PipelineDrainFn<T>) =>
-      createDrainPipeline(drainOptions),
-  };
-}
-
-export const cloudflareToolkit = createAdapterToolkit<CloudflareRequestLike>({
-  adapterName: 'cloudflare',
-  enrich: enrichFromRequest,
-});
-
-export { parseError, createDrainPipeline, createStructuredError };

package/src/core.test.ts

@@ -1,38 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { createUseLogger, getHeader } from './core';
-
-describe('createUseLogger', () => {
-  it('throws clear adapter-specific error when called without active span', () => {
-    const useLogger = createUseLogger<{ requestId: string }>({
-      adapterName: 'test-framework',
-      enrich: (ctx) => ({ request_id: ctx.requestId }),
-    });
-
-    expect(() => useLogger({ requestId: 'r1' })).toThrow(
-      '[autotel-adapters/test-framework] No active trace context.',
-    );
-  });
-});
-
-describe('getHeader', () => {
-  it('reads from Headers-like object with get()', () => {
-    const headers = { get: (name: string) => (name === 'x-request-id' ? 'req-1' : null) };
-    expect(getHeader(headers, 'x-request-id')).toBe('req-1');
-    expect(getHeader(headers, 'x-missing')).toBeUndefined();
-  });
-
-  it('reads from plain object with exact key match', () => {
-    const headers = { 'X-Request-Id': 'req-2' };
-    expect(getHeader(headers, 'X-Request-Id')).toBe('req-2');
-  });
-
-  it('falls back to lowercase key lookup', () => {
-    const headers = { 'x-request-id': 'req-3' };
-    expect(getHeader(headers, 'X-Request-Id')).toBe('req-3');
-  });
-
-  it('returns undefined for missing headers', () => {
-    expect(getHeader(undefined, 'x-request-id')).toBeUndefined();
-    expect(getHeader({}, 'x-request-id')).toBeUndefined();
-  });
-});

package/src/core.ts

@@ -1,225 +0,0 @@
-import type { AsyncLocalStorage } from 'node:async_hooks';
-import {
-  createDrainPipeline,
-  createStructuredError,
-  getRequestLogger,
-  parseError,
-  trace,
-  type ParsedError,
-  type RequestLogger,
-  type RequestLoggerOptions,
-  type RequestLogSnapshot,
-  type DrainPipelineOptions,
-  type PipelineDrainFn,
-  type StructuredError,
-  type StructuredErrorInput,
-} from 'autotel';
-
-export interface AdapterUseLoggerOptions<TContext> {
-  adapterName: string;
-  enrich?: (context: TContext) => Record<string, unknown> | undefined;
-}
-
-export interface AdapterToolkit<TContext> {
-  useLogger: (
-    context?: TContext,
-    options?: RequestLoggerOptions,
-  ) => RequestLogger;
-  parseError: (error: unknown) => ParsedError;
-  createStructuredError: (input: StructuredErrorInput) => StructuredError;
-  createDrainPipeline: <T = unknown>(
-    options?: DrainPipelineOptions<T>,
-  ) => (drain: (batch: T[]) => void | Promise<void>) => PipelineDrainFn<T>;
-}
-
-export function createUseLogger<TContext = unknown>(
-  options: AdapterUseLoggerOptions<TContext>,
-) {
-  return function useLogger(
-    context?: TContext,
-    requestLoggerOptions?: RequestLoggerOptions,
-  ): RequestLogger {
-    let logger: RequestLogger;
-    try {
-      logger = getRequestLogger(undefined, requestLoggerOptions);
-    } catch {
-      throw new Error(
-        `[autotel-adapters/${options.adapterName}] No active trace context. ` +
-          `Wrap your handler with autotel trace instrumentation before calling useLogger().`,
-      );
-    }
-
-    if (context && options.enrich) {
-      const extra = options.enrich(context);
-      if (extra && Object.keys(extra).length > 0) {
-        logger.set(extra);
-      }
-    }
-
-    return logger;
-  };
-}
-
-export interface RequestRunnerOptions {
-  requestLoggerOptions?: RequestLoggerOptions;
-  /** Emit one wide event automatically when the handler settles. Default `true`. */
-  autoEmit?: boolean;
-  /** Fields merged into the wide event at emit time (e.g. response status). */
-  finalize?: () => Record<string, unknown> | undefined;
-}
-
-/**
- * Build a request runner bound to one framework's logger storage. The returned
- * function opens a span, creates a request logger, runs `handler` inside the
- * storage so `useLogger()` resolves it, records thrown errors, and emits one
- * wide event when the handler settles (unless `autoEmit` is `false`).
- */
-export function createRequestRunner(storage: AsyncLocalStorage<RequestLogger>) {
-  return function runRequest<T>(
-    spanName: string,
-    enrich: (log: RequestLogger) => void,
-    handler: () => T | Promise<T>,
-    options?: RequestRunnerOptions,
-  ): Promise<T> {
-    const wrapped = trace(
-      { name: spanName },
-      (ctx) => async (): Promise<T> => {
-        const log = getRequestLogger(ctx, options?.requestLoggerOptions);
-        enrich(log);
-        try {
-          return await storage.run(log, () => handler());
-        } catch (error) {
-          log.error(error instanceof Error ? error : new Error(String(error)));
-          throw error;
-        } finally {
-          if (options?.autoEmit !== false) {
-            log.emitNow(options?.finalize?.());
-          }
-        }
-      },
-    );
-    return wrapped();
-  };
-}
-
-export function createAdapterToolkit<TContext = unknown>(
-  options: AdapterUseLoggerOptions<TContext>,
-): AdapterToolkit<TContext> {
-  return {
-    useLogger: createUseLogger(options),
-    parseError,
-    createStructuredError,
-    createDrainPipeline,
-  };
-}
-
-/**
- * Description of a single adapter config field. `env` is the ordered list of
- * environment variables to fall back to.
- */
-export interface ConfigField<T> {
-  key: keyof T & string;
-  env?: string[];
-}
-
-function resolveEnv(envKeys?: string[]): string | undefined {
-  if (!envKeys) return undefined;
-  for (const key of envKeys) {
-    const value = process.env[key];
-    if (value) return value;
-  }
-  return undefined;
-}
-
-/**
- * Returns true when at least one env-backed field is not provided via
- * `overrides`, meaning runtime config may still contribute and should be
- * probed to preserve precedence (`overrides > runtime > env`).
- *
- * @example
- * ```ts
- * const FIELDS: ConfigField<MyAdapterConfig>[] = [
- *   { key: 'token', env: ['MY_ADAPTER_TOKEN'] },
- *   { key: 'endpoint', env: ['MY_ADAPTER_URL'] },
- * ]
- *
- * if (shouldProbeRuntime(FIELDS, overrides)) {
- *   runtimeConfig = await loadRuntimeConfig()
- * }
- * ```
- */
-export function shouldProbeRuntime<T>(
-  fields: ConfigField<T>[],
-  overrides?: Partial<T>,
-): boolean {
-  return fields.some(({ key, env }) => {
-    if (!env || env.length === 0) return false;
-    if (overrides?.[key] !== undefined) return false;
-    return true;
-  });
-}
-
-/**
- * Resolve adapter configuration with the standard priority chain:
- *
- * 1. `overrides` passed to the adapter factory
- * 2. `runtimeConfig.autotel.{namespace}.{key}` (if a probe was performed)
- * 3. `runtimeConfig.{namespace}.{key}` (if a probe was performed)
- * 4. `process.env[envKey]` for each env in `field.env`
- *
- * Pass an async `probe` to defer the runtime config lookup so it is only
- * invoked when runtime resolution is needed (i.e. at least one env-backed
- * field is not set by overrides). Adapters that have no probe target may pass
- * `() => Promise.resolve(undefined)`.
- */
-export async function resolveAdapterConfig<T>(
-  namespace: string,
-  fields: ConfigField<T>[],
-  overrides: Partial<T> | undefined,
-  probe: () => Promise<Record<string, any> | undefined>,
-): Promise<Partial<T>> {
-  const runtimeConfig = shouldProbeRuntime(fields, overrides)
-    ? await probe()
-    : undefined;
-  const autotelNs = runtimeConfig?.autotel?.[namespace];
-  const rootNs = runtimeConfig?.[namespace];
-
-  const config: Record<string, unknown> = {};
-  for (const { key, env } of fields) {
-    config[key] =
-      overrides?.[key] ??
-      autotelNs?.[key] ??
-      rootNs?.[key] ??
-      resolveEnv(env);
-  }
-
-  return config as Partial<T>;
-}
-
-export type HeadersLike =
-  | { get(name: string): string | null }
-  | Record<string, string | undefined>;
-
-export function getHeader(
-  headers: HeadersLike | undefined,
-  name: string,
-): string | undefined {
-  if (!headers) return undefined;
-  if ('get' in headers && typeof headers.get === 'function') {
-    return headers.get(name) ?? undefined;
-  }
-  const dictionary = headers as Record<string, string | undefined>;
-  const value = dictionary[name] ?? dictionary[name.toLowerCase()];
-  return typeof value === 'string' ? value : undefined;
-}
-
-export type {
-  RequestLogger,
-  RequestLoggerOptions,
-  RequestLogSnapshot,
-  ParsedError,
-  StructuredError,
-  StructuredErrorInput,
-  DrainPipelineOptions,
-  PipelineDrainFn,
-};

package/src/express.test.ts

@@ -1,85 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-import { useLogger, withAutotel } from './express';
-import type { ExpressRequestLike, ExpressResponseLike } from './express';
-
-const req = (over: Partial<ExpressRequestLike> = {}): ExpressRequestLike => ({
-  method: 'GET',
-  originalUrl: '/api/orders',
-  ...over,
-});
-
-describe('express adapter', () => {
-  it('throws a clear error when useLogger is called outside a traced context', () => {
-    expect(() => useLogger(req())).toThrow(
-      '[autotel-adapters/express] No active trace context.',
-    );
-  });
-
-  it('runs the handler with a request-scoped logger', async () => {
-    const handler = withAutotel((request, res: ExpressResponseLike) => {
-      useLogger(request).set({ feature: 'checkout' });
-      res.statusCode = 201;
-      return 'ok';
-    });
-
-    await expect(handler(req(), { statusCode: 200 })).resolves.toBe('ok');
-  });
-
-  it('auto-emits one wide event with accumulated context and status', async () => {
-    const onEmit = vi.fn();
-    const handler = withAutotel(
-      (request, res: ExpressResponseLike) => {
-        useLogger(request).set({ user: 'u1' });
-        res.statusCode = 200;
-        return 'done';
-      },
-      { requestLoggerOptions: { onEmit } },
-    );
-
-    await handler(req({ method: 'POST' }), { statusCode: 200 });
-
-    expect(onEmit).toHaveBeenCalledTimes(1);
-    const snapshot = onEmit.mock.calls[0]?.[0] as {
-      context: Record<string, unknown>;
-    };
-    expect(snapshot.context.user).toBe('u1');
-    expect(snapshot.context['http.request.method']).toBe('POST');
-    expect(snapshot.context['http.response.status_code']).toBe(200);
-  });
-
-  it('does not emit when autoEmit is false', async () => {
-    const onEmit = vi.fn();
-    const handler = withAutotel(() => 'x', {
-      autoEmit: false,
-      requestLoggerOptions: { onEmit },
-    });
-
-    await handler(req(), { statusCode: 200 });
-    expect(onEmit).not.toHaveBeenCalled();
-  });
-
-  it('records the error, emits, and forwards to next', async () => {
-    const onEmit = vi.fn();
-    const next = vi.fn();
-    const boom = new Error('boom');
-    const handler = withAutotel(
-      () => {
-        throw boom;
-      },
-      { requestLoggerOptions: { onEmit } },
-    );
-
-    await expect(
-      handler(req(), { statusCode: 500 }, next),
-    ).resolves.toBeUndefined();
-    expect(next).toHaveBeenCalledWith(boom);
-    expect(onEmit).toHaveBeenCalledTimes(1);
-  });
-
-  it('rethrows when no next is provided', async () => {
-    const handler = withAutotel(() => {
-      throw new Error('no-next');
-    });
-    await expect(handler(req(), { statusCode: 500 })).rejects.toThrow('no-next');
-  });
-});