cfw-graphql-bootstrap 1.0.9 → 1.0.10

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 import { BaseContext as BaseContext$1, ApolloServerOptions, ApolloServerPlugin } from '@apollo/server';
 import { ExecutionContext } from '@cloudflare/workers-types';
 import { CloudflareContextFunctionArgument } from '@as-integrations/cloudflare-workers';
-import { GraphQLSchema, GraphQLError, DocumentNode } from 'graphql';
+import { GraphQLSchema, GraphQLError, DocumentNode, GraphQLFormattedError } from 'graphql';
 import { Hono, MiddlewareHandler } from 'hono';
 import { ApolloServerErrorCode } from '@apollo/server/errors';
+import { Logger } from 'pino';
 import DataLoader, { BatchLoadFn, Options } from 'dataloader';
 import { KeyValueCache, KeyValueCacheSetOptions } from '@apollo/utils.keyvaluecache';
 export { gql } from 'graphql-tag';
@@ -320,18 +321,119 @@ declare class EnvironmentLoader {
 }
 declare const envLoader: EnvironmentLoader;
 
-interface JaegerContext {
-    rootSpan?: {
-        getBaggageItem: (key: string) => string | undefined;
+/**
+ * Cloudflare Workers Tracing Wrapper
+ *
+ * Cloudflare Workers now provides automatic tracing with zero configuration.
+ * This wrapper provides additional context and manual span creation when needed.
+ *
+ * Key features:
+ * - Automatic instrumentation of all I/O operations (KV, R2, D1, etc.)
+ * - OpenTelemetry-compliant spans
+ * - Zero-config setup when enabled in wrangler.toml
+ */
+interface TraceContext {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    baggage?: Record<string, string>;
+}
+/**
+ * Extract W3C Trace Context from headers
+ * Format: traceparent: 00-{traceId}-{spanId}-{flags}
+ */
+declare function extractTraceContext(headers: Headers): TraceContext | null;
+/**
+ * Generate W3C Trace Context header
+ */
+declare function generateTraceHeader(context: TraceContext): string;
+/**
+ * Generate trace ID (32 hex chars / 128 bits)
+ */
+declare function generateTraceId(): string;
+/**
+ * Generate span ID (16 hex chars / 64 bits)
+ */
+declare function generateSpanId(): string;
+/**
+ * Custom span for manual instrumentation
+ * This is useful when you want to track specific operations
+ * that aren't automatically instrumented
+ */
+declare class WorkerSpan {
+    readonly name: string;
+    readonly spanId: string;
+    readonly traceId: string;
+    readonly parentSpanId?: string;
+    private startTime;
+    private endTime?;
+    private attributes;
+    private events;
+    constructor(name: string, spanId: string, traceId: string, parentSpanId?: string);
+    setAttribute(key: string, value: any): this;
+    setAttributes(attributes: Record<string, any>): this;
+    addEvent(name: string, attributes?: Record<string, any>): this;
+    end(): void;
+    toJSON(): {
+        name: string;
+        spanId: string;
+        traceId: string;
+        parentSpanId: string;
+        startTime: number;
+        endTime: number;
+        duration: number;
+        attributes: Record<string, any>;
+        events: {
+            name: string;
+            timestamp: number;
+            attributes?: Record<string, any>;
+        }[];
     };
 }
-interface BaseContext extends JaegerContext, BaseContext$1 {
+/**
+ * Tracer for Cloudflare Workers
+ * Provides manual span creation for custom instrumentation
+ */
+declare class WorkerTracer {
+    private readonly traceContext;
+    private readonly executionContext?;
+    private spans;
+    constructor(traceContext: TraceContext, executionContext?: ExecutionContext);
+    createSpan(name: string, parentSpanId?: string): WorkerSpan;
+    /**
+     * Run a function within a span
+     */
+    trace<T>(name: string, fn: (span: WorkerSpan) => Promise<T>): Promise<T>;
+    /**
+     * Export spans (for custom logging or external systems)
+     */
+    exportSpans(): Array<ReturnType<WorkerSpan['toJSON']>>;
+    /**
+     * Log spans to console (useful for development)
+     */
+    logSpans(): void;
+    /**
+     * Send spans to external observability platform via fetch
+     * This can be used with waitUntil to avoid blocking the response
+     */
+    sendToObservabilityPlatform(endpoint: string, headers?: Record<string, string>): Promise<void>;
+}
+/**
+ * Create a tracer instance for the current request
+ */
+declare function createTracer(headers: Headers, executionContext?: ExecutionContext): WorkerTracer;
+
+interface BaseContext extends BaseContext$1 {
     user?: ContextUser;
     logger: typeof logger;
     executionCtx: ExecutionContext;
     cache?: KVCache;
     db?: D1Database;
     env: EnvConfig;
+    traceContext?: TraceContext;
+    tracer?: WorkerTracer;
+    traceId?: string;
+    spanId?: string;
     /** @deprecated should not be used directly */
     authorization: string;
     clientId: string;
@@ -411,6 +513,18 @@ interface ValidationOptions {
 }
 declare function createValidationMiddleware(options?: ValidationOptions): MiddlewareHandler;
 
+/**
+ * Cloudflare Workers Native Tracing Middleware
+ *
+ * This middleware integrates with Cloudflare's automatic tracing feature.
+ * When enabled in wrangler.toml, CF automatically traces all I/O operations.
+ *
+ * This middleware:
+ * 1. Extracts or creates W3C Trace Context (traceparent header)
+ * 2. Propagates trace context through the request
+ * 3. Provides manual tracing capabilities for custom spans
+ * 4. Logs trace information for correlation
+ */
 declare function createTracingMiddleware(): MiddlewareHandler;
 
 interface HealthCheckOptions {
@@ -424,6 +538,12 @@ declare function configureHealthChecks(app: Hono<{
     };
 }>, options?: HealthCheckOptions): void;
 
+/**
+ * Apollo Server plugin for GraphQL operation tracing
+ * Integrates with Cloudflare Workers native tracing
+ */
+declare function createTracingPlugin<TContext extends BaseContext>(): ApolloServerPlugin<TContext>;
+
 declare enum ErrorCode {
     UNAUTHENTICATED = "UNAUTHENTICATED",
     FORBIDDEN = "FORBIDDEN",
@@ -445,6 +565,22 @@ type SchemaModule = ReturnType<typeof createSchemaModule>;
 
 declare const getNonUserInputErrors: (errors: readonly GraphQLError[]) => GraphQLError[];
 
+/**
+ * Sanitizes Prisma errors before sending to client
+ * Removes implementation details like "prisma.speaker.create()"
+ */
+declare function sanitizePrismaError(error: any, logger?: Logger): GraphQLError;
+/**
+ * Wraps async resolver functions to catch and sanitize Prisma errors
+ */
+declare function withPrismaErrorHandling<T extends (...args: any[]) => Promise<any>>(fn: T, logger?: Logger): T;
+
+/**
+ * Format error function that sanitizes Prisma errors
+ * This is used in Apollo Server configuration
+ */
+declare function formatError(formattedError: GraphQLFormattedError, error: unknown): GraphQLFormattedError;
+
 type DataSources = Record<string, any>;
 type DataSourcesFn = <TContext extends BaseContext = BaseContext>(cache: KVCache, contextValue: TContext) => DataSources;
 type ComputedContext<TDatasource, TContext extends BaseContext> = TContext & {
@@ -574,8 +710,22 @@ declare global {
  *   }
  *
  *   async getUser(id: string) {
+ *     // Just use Prisma normally - errors are sanitized by Apollo plugin
  *     return this.client.user.findUnique({ where: { id } });
  *   }
+ *
+ *   async createUser(data: CreateUserInput) {
+ *     // Prisma errors like "Unique constraint" are automatically sanitized
+ *     return this.client.user.create({ data });
+ *   }
+ *
+ *   async updateUser(id: string, data: UpdateUserInput) {
+ *     // Clean, simple code - error handling is in the GraphQL layer
+ *     return this.client.user.update({
+ *       where: { id },
+ *       data
+ *     });
+ *   }
  * }
  *
  * // Multiple instances share the same client efficiently:
@@ -626,4 +776,4 @@ declare abstract class PrismaD1Datasource<TContext extends BaseContext = BaseCon
     }): Promise<number>;
 }
 
-export { AbstractDatasource, ApolloDataSources, ApolloKVAdapter, AppError, type BaseContext, type BaseDatasource, type BaseServerOptions, BatchingDataSource, type CacheOptions, CachedDataLoader, type ComputedContext, type ContextExtendFunction, type ContextUser, type EnvConfig, ErrorCode, InMemoryCache, KVCache, type PrismaClientLike, type PrismaD1, PrismaD1Datasource, type RestClientOptions, RestDatasource, type Runner, type SchemaModule, ServerBuilder, type ServerConfig, type ServerOptions, cached, configureHealthChecks, createApolloCache, createApolloLoggingPlugin, createBatchingDataSource, createCache, createContextFunction, createGraphQLServer, createRateLimitMiddleware, createSchemaModule, createTracingMiddleware, createValidationMiddleware, ensureBatchOrder, ensureBatchOrderNullable, envLoader, getNonUserInputErrors, logger };
+export { AbstractDatasource, ApolloDataSources, ApolloKVAdapter, AppError, type BaseContext, type BaseDatasource, type BaseServerOptions, BatchingDataSource, type CacheOptions, CachedDataLoader, type ComputedContext, type ContextExtendFunction, type ContextUser, type EnvConfig, ErrorCode, InMemoryCache, KVCache, type PrismaClientLike, type PrismaD1, PrismaD1Datasource, type RestClientOptions, RestDatasource, type Runner, type SchemaModule, ServerBuilder, type ServerConfig, type ServerOptions, type TraceContext, WorkerSpan, WorkerTracer, cached, configureHealthChecks, createApolloCache, createApolloLoggingPlugin, createBatchingDataSource, createCache, createContextFunction, createGraphQLServer, createRateLimitMiddleware, createSchemaModule, createTracer, createTracingMiddleware, createTracingPlugin, createValidationMiddleware, ensureBatchOrder, ensureBatchOrderNullable, envLoader, extractTraceContext, formatError, generateSpanId, generateTraceHeader, generateTraceId, getNonUserInputErrors, logger, sanitizePrismaError, withPrismaErrorHandling };