autotel-adapters 0.1.0

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "autotel-adapters",
+  "version": "0.1.0",
+  "description": "Framework adapters and composable DX helpers for autotel",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js",
+      "require": "./dist/core.cjs"
+    },
+    "./hono": {
+      "types": "./dist/hono.d.ts",
+      "import": "./dist/hono.js",
+      "require": "./dist/hono.cjs"
+    },
+    "./tanstack": {
+      "types": "./dist/tanstack.d.ts",
+      "import": "./dist/tanstack.js",
+      "require": "./dist/tanstack.cjs"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "import": "./dist/next.js",
+      "require": "./dist/next.cjs"
+    },
+    "./nitro": {
+      "types": "./dist/nitro.d.ts",
+      "import": "./dist/nitro.js",
+      "require": "./dist/nitro.cjs"
+    },
+    "./cloudflare": {
+      "types": "./dist/cloudflare.d.ts",
+      "import": "./dist/cloudflare.js",
+      "require": "./dist/cloudflare.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "clean": "rimraf dist"
+  },
+  "dependencies": {
+    "autotel": "workspace:*"
+  },
+  "peerDependencies": {
+    "hono": ">=4.12.3",
+    "@tanstack/react-start": "^1.166.1",
+    "@tanstack/solid-start": "^1.166.1",
+    "next": ">=16.1.6",
+    "h3": "^1.15.5",
+    "nitropack": "^2.13.1"
+  },
+  "peerDependenciesMeta": {
+    "hono": {
+      "optional": true
+    },
+    "@tanstack/react-start": {
+      "optional": true
+    },
+    "@tanstack/solid-start": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    },
+    "h3": {
+      "optional": true
+    },
+    "nitropack": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "hono": "^4.12.3",
+    "rimraf": "^6.1.3",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jagreehal/autotel",
+    "directory": "packages/autotel-adapters"
+  }
+}

package/src/cloudflare.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } 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 });
+  });
+});
+

package/src/cloudflare.ts

@@ -0,0 +1,181 @@
+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;
+}
+
+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 {
+          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

@@ -0,0 +1,38 @@
+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

@@ -0,0 +1,98 @@
+import {
+  createDrainPipeline,
+  createStructuredError,
+  getRequestLogger,
+  parseError,
+  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 function createAdapterToolkit<TContext = unknown>(
+  options: AdapterUseLoggerOptions<TContext>,
+): AdapterToolkit<TContext> {
+  return {
+    useLogger: createUseLogger(options),
+    parseError,
+    createStructuredError,
+    createDrainPipeline,
+  };
+}
+
+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/hono.ts

@@ -0,0 +1,20 @@
+import type { Context } from 'hono';
+import { createUseLogger, createAdapterToolkit } from './core';
+
+export const useLogger = createUseLogger<Context>({
+  adapterName: 'hono',
+  enrich: (c) => ({
+    'http.request.method': c.req.method,
+    'url.full': c.req.url,
+    'http.route': c.req.path,
+  }),
+});
+
+export const honoToolkit = createAdapterToolkit<Context>({
+  adapterName: 'hono',
+  enrich: (c) => ({
+    'http.request.method': c.req.method,
+    'url.full': c.req.url,
+    'http.route': c.req.path,
+  }),
+});

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './core';
+export { createNextAdapter, withAutotel } from './next';
+export { createNitroAdapter, withAutotelEventHandler } from './nitro';
+export { createCloudflareAdapter, withAutotelFetch } from './cloudflare';
+export { honoToolkit } from './hono';
+export { tanstackToolkit } from './tanstack';

package/src/next.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { useLogger, withAutotel } from './next';
+
+describe('next adapter', () => {
+  it('throws clear error when useLogger is called outside traced context', () => {
+    expect(() => useLogger({ method: 'GET', url: '/api/orders' })).toThrow(
+      '[autotel-adapters/next] No active trace context.',
+    );
+  });
+
+  it('provides request-scoped logger inside withAutotel()', async () => {
+    const handler = withAutotel(async (request: { url: string }) => {
+      const log = useLogger(request);
+      log.set({ feature: 'checkout' });
+      return 'ok';
+    });
+
+    await expect(handler({ url: 'https://example.com/orders' })).resolves.toBe(
+      'ok',
+    );
+  });
+});

package/src/next.ts

@@ -0,0 +1,127 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import {
+  createDrainPipeline,
+  getRequestLogger,
+  parseError,
+  trace,
+  createStructuredError,
+  type RequestLogger,
+  type RequestLoggerOptions,
+  type ParsedError,
+  type DrainPipelineOptions,
+  type PipelineDrainFn,
+  type StructuredError,
+  type StructuredErrorInput,
+} from 'autotel';
+import { createAdapterToolkit, createUseLogger, getHeader } from './core';
+
+export interface NextRequestLike {
+  method?: string;
+  url?: string;
+  headers?:
+    | { get(name: string): string | null }
+    | Record<string, string | undefined>;
+}
+
+export interface NextWithAutotelOptions {
+  spanName?: string | ((request?: NextRequestLike) => string);
+  requestLoggerOptions?: RequestLoggerOptions;
+  enrich?: (request?: NextRequestLike) => Record<string, unknown> | undefined;
+}
+
+const nextLoggerStorage = new AsyncLocalStorage<RequestLogger>();
+
+function enrichFromRequest(
+  request?: NextRequestLike,
+): 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');
+
+  return {
+    ...(request.method ? { 'http.request.method': request.method } : {}),
+    ...(request.url ? { 'url.full': request.url } : {}),
+    ...(route ? { 'http.route': route } : {}),
+    ...(requestId ? { 'http.request.header.x-request-id': requestId } : {}),
+  };
+}
+
+const baseUseLogger = createUseLogger<NextRequestLike>({
+  adapterName: 'next',
+  enrich: enrichFromRequest,
+});
+
+export function useLogger(
+  request?: NextRequestLike,
+  requestLoggerOptions?: RequestLoggerOptions,
+): RequestLogger {
+  const logger = nextLoggerStorage.getStore();
+  if (logger) return logger;
+  return baseUseLogger(request, requestLoggerOptions);
+}
+
+export function withAutotel<TArgs extends unknown[], TReturn>(
+  handler: (...args: TArgs) => TReturn | Promise<TReturn>,
+  options?: NextWithAutotelOptions,
+): (...args: TArgs) => Promise<TReturn> {
+  return async (...args: TArgs): Promise<TReturn> => {
+    const request = args[0] as NextRequestLike | undefined;
+    const spanName =
+      typeof options?.spanName === 'function'
+        ? options.spanName(request)
+        : (options?.spanName ?? 'next.request');
+
+    const wrapped = trace(
+      { name: spanName },
+      (ctx) => async (...innerArgs: TArgs) => {
+        const innerRequest = innerArgs[0] as NextRequestLike | undefined;
+        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);
+        if (custom && Object.keys(custom).length > 0) {
+          log.set(custom);
+        }
+        return await nextLoggerStorage.run(log, async () => handler(...innerArgs));
+      },
+    );
+    return await wrapped(...args);
+  };
+}
+
+export function createNextAdapter(options?: NextWithAutotelOptions) {
+  return {
+    withAutotel: <TArgs extends unknown[], TReturn>(
+      handler: (...args: TArgs) => TReturn | Promise<TReturn>,
+    ) => withAutotel(handler, options),
+    useLogger: (
+      request?: NextRequestLike,
+      requestLoggerOptions?: RequestLoggerOptions,
+    ): RequestLogger => useLogger(request, requestLoggerOptions),
+    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 nextToolkit = createAdapterToolkit<NextRequestLike>({
+  adapterName: 'next',
+  enrich: enrichFromRequest,
+});
+
+export { parseError, createDrainPipeline, createStructuredError };

package/src/nitro.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import { useLogger, withAutotelEventHandler } from './nitro';
+
+describe('nitro adapter', () => {
+  it('throws clear error when useLogger is called outside traced context', () => {
+    expect(() =>
+      useLogger({ method: 'GET', path: '/api/orders', context: {} }),
+    ).toThrow('[autotel-adapters/nitro] No active trace context.');
+  });
+
+  it('provides request-scoped logger inside withAutotelEventHandler()', async () => {
+    const handler = withAutotelEventHandler(
+      async (event: { path: string; context: Record<string, unknown> }) => {
+        const log = useLogger(event, 'api-service');
+        log.set({ route: event.path });
+        return { ok: true };
+      },
+    );
+
+    await expect(
+      handler({ path: '/orders', context: {} }),
+    ).resolves.toMatchObject({ ok: true });
+  });
+});