@effect-gql/core 0.1.0

package/src/analyzer-extension.ts

@@ -0,0 +1,254 @@
+import { Effect } from "effect"
+import { Kind, type OperationDefinitionNode } from "graphql"
+import type { GraphQLExtension, ExecutionArgs } from "./extensions"
+import { ExtensionsService } from "./extensions"
+import {
+  defaultComplexityCalculator,
+  type ComplexityResult,
+  type FieldComplexityMap,
+} from "./server/complexity"
+
+/**
+ * Configuration for the analyzer extension
+ */
+export interface AnalyzerExtensionConfig {
+  /**
+   * Include the total complexity score in the response.
+   * @default true
+   */
+  readonly includeComplexity?: boolean
+
+  /**
+   * Include the maximum query depth in the response.
+   * @default true
+   */
+  readonly includeDepth?: boolean
+
+  /**
+   * Include the total field count in the response.
+   * @default false
+   */
+  readonly includeFieldCount?: boolean
+
+  /**
+   * Include the alias count in the response.
+   * @default false
+   */
+  readonly includeAliasCount?: boolean
+
+  /**
+   * The key to use in the response extensions object.
+   * @default "analyzer"
+   */
+  readonly key?: string
+
+  /**
+   * Thresholds for logging warnings when exceeded.
+   * When a metric exceeds its threshold, a warning is logged.
+   */
+  readonly thresholds?: {
+    readonly depth?: number
+    readonly complexity?: number
+    readonly fieldCount?: number
+    readonly aliasCount?: number
+  }
+
+  /**
+   * Default complexity cost for fields without explicit costs.
+   * @default 1
+   */
+  readonly defaultFieldComplexity?: number
+
+  /**
+   * Optional field complexity overrides.
+   * If not provided, uses the field complexities from the schema builder
+   * (passed via ExecutionArgs).
+   */
+  readonly fieldComplexities?: FieldComplexityMap
+}
+
+/**
+ * Output format for analyzer extension
+ */
+export interface AnalyzerOutput {
+  complexity?: number
+  depth?: number
+  fieldCount?: number
+  aliasCount?: number
+}
+
+/**
+ * Create an analyzer extension that reports query complexity metrics
+ * in the response extensions field.
+ *
+ * Similar to async-graphql's Analyzer extension, this allows you to
+ * monitor the complexity of incoming queries without blocking execution.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - reports complexity and depth
+ * const analyzer = createAnalyzerExtension()
+ *
+ * // With all metrics and warnings
+ * const analyzer = createAnalyzerExtension({
+ *   includeFieldCount: true,
+ *   includeAliasCount: true,
+ *   thresholds: {
+ *     depth: 10,
+ *     complexity: 100,
+ *   },
+ * })
+ *
+ * // Add to schema builder
+ * const builder = GraphQLSchemaBuilder.empty.pipe(
+ *   extension(analyzer),
+ *   // ...queries, mutations, etc.
+ * )
+ *
+ * // Response will include:
+ * // {
+ * //   "data": { ... },
+ * //   "extensions": {
+ * //     "analyzer": {
+ * //       "complexity": 42,
+ * //       "depth": 3
+ * //     }
+ * //   }
+ * // }
+ * ```
+ */
+export const createAnalyzerExtension = (
+  config: AnalyzerExtensionConfig = {}
+): GraphQLExtension<ExtensionsService> => {
+  const {
+    includeComplexity = true,
+    includeDepth = true,
+    includeFieldCount = false,
+    includeAliasCount = false,
+    key = "analyzer",
+    thresholds,
+    defaultFieldComplexity = 1,
+    fieldComplexities: configFieldComplexities,
+  } = config
+
+  return {
+    name: "analyzer",
+    description: "Reports query complexity metrics in response extensions",
+
+    onExecuteStart: (args: ExecutionArgs) =>
+      Effect.gen(function* () {
+        const ext = yield* ExtensionsService
+
+        // Find the operation
+        const operation = findOperation(args)
+        if (!operation) {
+          return
+        }
+
+        // Use config field complexities if provided, otherwise use from args
+        const fieldComplexities = configFieldComplexities ?? args.fieldComplexities
+
+        // Calculate complexity
+        const calculator = defaultComplexityCalculator(defaultFieldComplexity)
+        const result = yield* calculator({
+          document: args.document,
+          operation,
+          variables: args.variableValues,
+          schema: args.schema,
+          fieldComplexities,
+        }).pipe(
+          Effect.catchAll((error) =>
+            Effect.logWarning("Analyzer extension: complexity calculation failed", error).pipe(
+              Effect.as(null)
+            )
+          )
+        )
+
+        if (!result) {
+          return
+        }
+
+        // Check thresholds and log warnings
+        yield* checkThresholds(result, thresholds)
+
+        // Build output
+        const output: AnalyzerOutput = {}
+        if (includeComplexity) {
+          output.complexity = result.complexity
+        }
+        if (includeDepth) {
+          output.depth = result.depth
+        }
+        if (includeFieldCount) {
+          output.fieldCount = result.fieldCount
+        }
+        if (includeAliasCount) {
+          output.aliasCount = result.aliasCount
+        }
+
+        // Add to extensions
+        yield* ext.set(key, output)
+      }),
+  }
+}
+
+/**
+ * Find the operation to analyze from the document
+ */
+function findOperation(args: ExecutionArgs): OperationDefinitionNode | null {
+  const operations = args.document.definitions.filter(
+    (d): d is OperationDefinitionNode => d.kind === Kind.OPERATION_DEFINITION
+  )
+
+  if (operations.length === 0) {
+    return null
+  }
+
+  if (args.operationName) {
+    return operations.find((o) => o.name?.value === args.operationName) ?? null
+  }
+
+  return operations[0]
+}
+
+/**
+ * Check thresholds and log warnings for exceeded values
+ */
+function checkThresholds(
+  result: ComplexityResult,
+  thresholds?: AnalyzerExtensionConfig["thresholds"]
+): Effect.Effect<void> {
+  if (!thresholds) {
+    return Effect.void
+  }
+
+  const warnings: string[] = []
+
+  if (thresholds.depth !== undefined && result.depth > thresholds.depth) {
+    warnings.push(`Query depth ${result.depth} exceeds threshold ${thresholds.depth}`)
+  }
+  if (thresholds.complexity !== undefined && result.complexity > thresholds.complexity) {
+    warnings.push(
+      `Query complexity ${result.complexity} exceeds threshold ${thresholds.complexity}`
+    )
+  }
+  if (thresholds.fieldCount !== undefined && result.fieldCount > thresholds.fieldCount) {
+    warnings.push(
+      `Query field count ${result.fieldCount} exceeds threshold ${thresholds.fieldCount}`
+    )
+  }
+  if (thresholds.aliasCount !== undefined && result.aliasCount > thresholds.aliasCount) {
+    warnings.push(
+      `Query alias count ${result.aliasCount} exceeds threshold ${thresholds.aliasCount}`
+    )
+  }
+
+  if (warnings.length > 0) {
+    return Effect.logWarning("Analyzer extension: thresholds exceeded", {
+      warnings,
+      result,
+    })
+  }
+
+  return Effect.void
+}

package/src/builder/execute.ts

@@ -0,0 +1,153 @@
+import { Effect, Layer } from "effect"
+import {
+  GraphQLSchema,
+  GraphQLError,
+  parse,
+  validate,
+  execute as graphqlExecute,
+  type ExecutionResult,
+  type DocumentNode,
+} from "graphql"
+import type { GraphQLEffectContext } from "./types"
+import {
+  type GraphQLExtension,
+  ExtensionsService,
+  makeExtensionsService,
+  runParseHooks,
+  runValidateHooks,
+  runExecuteStartHooks,
+  runExecuteEndHooks,
+} from "../extensions"
+import type { FieldComplexityMap } from "../server/complexity"
+
+/**
+ * Execute a GraphQL query with a service layer
+ *
+ * This is the layer-per-request execution model. Build the schema once,
+ * then execute each request with its own layer (including request-scoped services).
+ *
+ * The execution follows these phases:
+ * 1. Parse - Convert source string to DocumentNode
+ * 2. Validate - Check document against schema
+ * 3. Execute - Run resolvers and return result
+ *
+ * Extensions can hook into each phase via onParse, onValidate, onExecuteStart, onExecuteEnd.
+ * Extension data is automatically merged into the response's extensions field.
+ */
+export const execute =
+  <R>(
+    schema: GraphQLSchema,
+    layer: Layer.Layer<R>,
+    extensions: readonly GraphQLExtension<any>[] = [],
+    fieldComplexities: FieldComplexityMap = new Map()
+  ) =>
+  (
+    source: string,
+    variableValues?: Record<string, unknown>,
+    operationName?: string
+  ): Effect.Effect<ExecutionResult, Error> =>
+    Effect.gen(function* () {
+      // Create the ExtensionsService for this request
+      const extensionsService = yield* makeExtensionsService()
+
+      // Create runtime from the provided layer
+      const runtime = yield* Effect.runtime<R>()
+
+      // Phase 1: Parse
+      let document: DocumentNode
+      try {
+        document = parse(source)
+      } catch (parseError) {
+        // Parse errors are returned as GraphQL errors, not thrown
+        const extensionData = yield* extensionsService.get()
+        return {
+          errors: [
+            parseError instanceof GraphQLError ? parseError : new GraphQLError(String(parseError)),
+          ],
+          extensions: Object.keys(extensionData).length > 0 ? extensionData : undefined,
+        } as ExecutionResult
+      }
+
+      // Run onParse hooks
+      yield* runParseHooks(extensions, source, document).pipe(
+        Effect.provideService(ExtensionsService, extensionsService)
+      )
+
+      // Phase 2: Validate
+      const validationErrors = validate(schema, document)
+
+      // Run onValidate hooks
+      yield* runValidateHooks(extensions, document, validationErrors).pipe(
+        Effect.provideService(ExtensionsService, extensionsService)
+      )
+
+      // If validation failed, return errors without executing
+      if (validationErrors.length > 0) {
+        const extensionData = yield* extensionsService.get()
+        return {
+          errors: validationErrors,
+          extensions: Object.keys(extensionData).length > 0 ? extensionData : undefined,
+        } as ExecutionResult
+      }
+
+      // Phase 3: Execute
+      const executionArgs = {
+        source,
+        document,
+        variableValues,
+        operationName,
+        schema,
+        fieldComplexities,
+      }
+
+      // Run onExecuteStart hooks
+      yield* runExecuteStartHooks(extensions, executionArgs).pipe(
+        Effect.provideService(ExtensionsService, extensionsService)
+      )
+
+      // Execute the GraphQL query
+      const executeResult = yield* Effect.try({
+        try: () =>
+          graphqlExecute({
+            schema,
+            document,
+            variableValues,
+            operationName,
+            contextValue: { runtime } satisfies GraphQLEffectContext<R>,
+          }),
+        catch: (error) => new Error(String(error)),
+      })
+
+      // Await result if it's a promise (for subscriptions, it might be)
+      const resolvedResult: Awaited<typeof executeResult> =
+        executeResult && typeof executeResult === "object" && "then" in executeResult
+          ? yield* Effect.promise(() => executeResult)
+          : executeResult
+
+      // Run onExecuteEnd hooks
+      yield* runExecuteEndHooks(extensions, resolvedResult).pipe(
+        Effect.provideService(ExtensionsService, extensionsService)
+      )
+
+      // Merge extension data into result
+      const extensionData = yield* extensionsService.get()
+      if (Object.keys(extensionData).length > 0) {
+        return {
+          ...resolvedResult,
+          extensions: {
+            ...resolvedResult.extensions,
+            ...extensionData,
+          },
+        }
+      }
+
+      return resolvedResult
+    }).pipe(Effect.provide(layer)) as Effect.Effect<ExecutionResult, Error>
+
+/**
+ * Execute a GraphQL query with a service layer (simple version without extensions)
+ *
+ * @deprecated Use execute() instead, which now supports extensions as an optional parameter
+ */
+export const executeSimple = <R>(schema: GraphQLSchema, layer: Layer.Layer<R>) =>
+  execute(schema, layer, [])