@effect-gql/core 0.1.0

package/src/builder/types.ts

@@ -0,0 +1,305 @@
+import { Effect, Runtime, Stream } from "effect"
+import * as S from "effect/Schema"
+import { DirectiveLocation, GraphQLResolveInfo } from "graphql"
+import type { FieldComplexity } from "../server/complexity"
+
+/**
+ * Cache control scope determines whether a cached response can be shared.
+ * - PUBLIC: Response can be cached by CDNs and shared across users
+ * - PRIVATE: Response is user-specific and should only be cached in browsers
+ */
+export type CacheControlScope = "PUBLIC" | "PRIVATE"
+
+/**
+ * Cache control hint for a type or field.
+ * Used to compute the overall cache policy for a GraphQL response.
+ */
+export interface CacheHint {
+  /**
+   * Maximum age in seconds that this field's value can be cached.
+   * The response's maxAge will be the minimum of all field maxAges.
+   */
+  readonly maxAge?: number
+
+  /**
+   * Whether the cached value is user-specific (PRIVATE) or shared (PUBLIC).
+   * If any field is PRIVATE, the entire response is PRIVATE.
+   */
+  readonly scope?: CacheControlScope
+
+  /**
+   * When true, this field inherits its maxAge from the parent field
+   * instead of using the default (which is 0 for root fields).
+   * Cannot be used together with maxAge.
+   */
+  readonly inheritMaxAge?: boolean
+}
+
+/**
+ * Configuration for a query or mutation field
+ */
+export interface FieldRegistration<Args = any, A = any, E = any, R = any> {
+  type: S.Schema<A, any, any>
+  args?: S.Schema<Args, any, any>
+  description?: string
+  directives?: readonly DirectiveApplication[]
+  /**
+   * Complexity cost of this field.
+   * Can be a static number or a function that receives the resolved arguments.
+   * Used for query complexity limiting.
+   *
+   * @example
+   * // Static cost
+   * complexity: 5
+   *
+   * // Dynamic cost based on pagination
+   * complexity: (args) => args.limit * 2
+   */
+  complexity?: FieldComplexity
+  /**
+   * Cache control hint for this field.
+   * Used to compute HTTP Cache-Control headers for the response.
+   *
+   * @example
+   * // Cache for 1 hour
+   * cacheControl: { maxAge: 3600 }
+   *
+   * // User-specific data, don't cache in CDN
+   * cacheControl: { maxAge: 60, scope: "PRIVATE" }
+   */
+  cacheControl?: CacheHint
+  resolve: (args: Args) => Effect.Effect<A, E, R>
+}
+
+/**
+ * Configuration for an object type
+ */
+export interface TypeRegistration {
+  name: string
+  schema: S.Schema<any, any, any>
+  implements?: readonly string[]
+  directives?: readonly DirectiveApplication[]
+  /**
+   * Default cache control hint for all fields returning this type.
+   * Can be overridden by field-level cacheControl.
+   *
+   * @example
+   * // All User fields cacheable for 1 hour by default
+   * cacheControl: { maxAge: 3600 }
+   */
+  cacheControl?: CacheHint
+}
+
+/**
+ * Configuration for an interface type
+ */
+export interface InterfaceRegistration {
+  name: string
+  schema: S.Schema<any, any, any>
+  resolveType: (value: any) => string
+  directives?: readonly DirectiveApplication[]
+}
+
+/**
+ * Configuration for an enum type
+ */
+export interface EnumRegistration {
+  name: string
+  values: readonly string[]
+  description?: string
+  directives?: readonly DirectiveApplication[]
+}
+
+/**
+ * Configuration for a union type
+ */
+export interface UnionRegistration {
+  name: string
+  types: readonly string[]
+  resolveType: (value: any) => string
+  directives?: readonly DirectiveApplication[]
+}
+
+/**
+ * Configuration for an input type
+ */
+export interface InputTypeRegistration {
+  name: string
+  schema: S.Schema<any, any, any>
+  description?: string
+  directives?: readonly DirectiveApplication[]
+}
+
+/**
+ * A reference to a directive applied to a type, field, or argument
+ */
+export interface DirectiveApplication {
+  readonly name: string
+  readonly args?: Record<string, unknown>
+}
+
+/**
+ * Configuration for a directive definition
+ */
+export interface DirectiveRegistration<Args = any, R = never> {
+  name: string
+  description?: string
+  locations: readonly DirectiveLocation[]
+  args?: S.Schema<Args, any, any>
+  /**
+   * For executable directives - transforms the resolver Effect.
+   * Called with directive args, returns an Effect transformer.
+   */
+  apply?: (args: Args) => <A, E, R2>(effect: Effect.Effect<A, E, R2>) => Effect.Effect<A, E, R | R2>
+}
+
+/**
+ * Context passed to middleware apply functions
+ * Contains the resolver's parent value, arguments, and GraphQL resolve info
+ */
+export interface MiddlewareContext<Parent = any, Args = any> {
+  readonly parent: Parent
+  readonly args: Args
+  readonly info: GraphQLResolveInfo
+}
+
+/**
+ * Configuration for middleware registration
+ *
+ * Middleware wraps all resolvers (or those matching a pattern) and executes
+ * in an "onion" model - first registered middleware is the outermost layer.
+ *
+ * Unlike directives which are applied per-field explicitly, middleware is
+ * applied globally or via pattern matching.
+ *
+ * @example
+ * ```typescript
+ * // Logging middleware - applies to all fields
+ * middleware({
+ *   name: "logging",
+ *   apply: (effect, ctx) => Effect.gen(function*() {
+ *     yield* Effect.logInfo(`Resolving ${ctx.info.fieldName}`)
+ *     return yield* effect
+ *   })
+ * })
+ *
+ * // Admin-only middleware - pattern matched
+ * middleware({
+ *   name: "adminOnly",
+ *   match: (info) => info.fieldName.startsWith("admin"),
+ *   apply: (effect) => Effect.gen(function*() {
+ *     const auth = yield* AuthService
+ *     yield* auth.requireAdmin()
+ *     return yield* effect
+ *   })
+ * })
+ * ```
+ */
+export interface MiddlewareRegistration<R = never> {
+  readonly name: string
+  readonly description?: string
+
+  /**
+   * Optional predicate to filter which fields this middleware applies to.
+   * If undefined, middleware applies to all fields.
+   * Receives the GraphQL resolve info for the field being resolved.
+   */
+  readonly match?: (info: GraphQLResolveInfo) => boolean
+
+  /**
+   * Transform the resolver Effect.
+   * Receives the resolver effect and full context (parent, args, info).
+   * Returns the transformed effect.
+   *
+   * Middleware executes in "onion" order - first registered is outermost.
+   */
+  readonly apply: <A, E, R2>(
+    effect: Effect.Effect<A, E, R2>,
+    context: MiddlewareContext
+  ) => Effect.Effect<A, E, R | R2>
+}
+
+/**
+ * Configuration for a subscription field
+ * Returns a Stream that yields values over time
+ */
+export interface SubscriptionFieldRegistration<Args = any, A = any, E = any, R = any> {
+  type: S.Schema<A, any, any>
+  args?: S.Schema<Args, any, any>
+  description?: string
+  directives?: readonly DirectiveApplication[]
+  /**
+   * Complexity cost of this subscription.
+   * Can be a static number or a function that receives the resolved arguments.
+   * Used for query complexity limiting.
+   */
+  complexity?: FieldComplexity
+  /**
+   * Cache control hint for this subscription.
+   * Note: Subscriptions are real-time and typically not cached,
+   * but this can be used for initial data hints.
+   */
+  cacheControl?: CacheHint
+  /**
+   * Subscribe function returns an Effect that produces a Stream.
+   * The Stream yields values that are passed to the resolve function.
+   */
+  subscribe: (args: Args) => Effect.Effect<Stream.Stream<A, E, R>, E, R>
+  /**
+   * Optional resolve function to transform each yielded value.
+   * If not provided, yields values directly.
+   */
+  resolve?: (value: A, args: Args) => Effect.Effect<A, E, R>
+}
+
+/**
+ * Configuration for a field on an object type
+ */
+export interface ObjectFieldRegistration<Parent = any, Args = any, A = any, E = any, R = any> {
+  type: S.Schema<A, any, any>
+  args?: S.Schema<Args, any, any>
+  description?: string
+  directives?: readonly DirectiveApplication[]
+  /**
+   * Complexity cost of this field.
+   * Can be a static number or a function that receives the resolved arguments.
+   * Used for query complexity limiting.
+   *
+   * @example
+   * // Relation field with pagination
+   * complexity: (args) => (args.limit ?? 10) * 2
+   */
+  complexity?: FieldComplexity
+  /**
+   * Cache control hint for this field.
+   * Used to compute HTTP Cache-Control headers for the response.
+   *
+   * @example
+   * // Expensive computation, cache for 5 minutes
+   * cacheControl: { maxAge: 300 }
+   *
+   * // Inherit cache policy from parent type
+   * cacheControl: { inheritMaxAge: true }
+   */
+  cacheControl?: CacheHint
+  resolve: (parent: Parent, args: Args) => Effect.Effect<A, E, R>
+}
+
+/**
+ * GraphQL context that contains the Effect runtime
+ */
+export interface GraphQLEffectContext<R> {
+  runtime: Runtime.Runtime<R>
+}
+
+/**
+ * Type registries used during schema building
+ */
+export interface TypeRegistries {
+  types: Map<string, import("graphql").GraphQLObjectType>
+  interfaces: Map<string, import("graphql").GraphQLInterfaceType>
+  enums: Map<string, import("graphql").GraphQLEnumType>
+  unions: Map<string, import("graphql").GraphQLUnionType>
+  inputs: Map<string, import("graphql").GraphQLInputObjectType>
+  directives: Map<string, import("graphql").GraphQLDirective>
+}

package/src/context.ts

@@ -0,0 +1,23 @@
+import { Context, Layer } from "effect"
+
+/**
+ * GraphQL request context containing request-specific data
+ */
+export interface GraphQLRequestContext {
+  readonly request: {
+    readonly headers: Record<string, string>
+    readonly query: string
+    readonly variables?: Record<string, unknown>
+    readonly operationName?: string
+  }
+}
+
+export const GraphQLRequestContext =
+  Context.GenericTag<GraphQLRequestContext>("GraphQLRequestContext")
+
+/**
+ * Create a layer from request context
+ */
+export const makeRequestContextLayer = (
+  context: GraphQLRequestContext
+): Layer.Layer<GraphQLRequestContext> => Layer.succeed(GraphQLRequestContext, context)

package/src/error.ts

@@ -0,0 +1,32 @@
+import { Data } from "effect"
+
+/**
+ * Base class for GraphQL errors in Effect
+ */
+export class GraphQLError extends Data.TaggedError("GraphQLError")<{
+  message: string
+  extensions?: Record<string, unknown>
+}> {}
+
+/**
+ * Validation error for input validation failures
+ */
+export class ValidationError extends Data.TaggedError("ValidationError")<{
+  message: string
+  field?: string
+}> {}
+
+/**
+ * Authorization error for access control failures
+ */
+export class AuthorizationError extends Data.TaggedError("AuthorizationError")<{
+  message: string
+}> {}
+
+/**
+ * Not found error for missing resources
+ */
+export class NotFoundError extends Data.TaggedError("NotFoundError")<{
+  message: string
+  resource?: string
+}> {}

package/src/extensions.ts

@@ -0,0 +1,240 @@
+import { Context, Effect, Ref } from "effect"
+import type { DocumentNode, ExecutionResult, GraphQLError, GraphQLSchema } from "graphql"
+import type { FieldComplexityMap } from "./server/complexity"
+
+/**
+ * Execution arguments passed to onExecuteStart hook
+ */
+export interface ExecutionArgs {
+  readonly source: string
+  readonly document: DocumentNode
+  readonly variableValues?: Record<string, unknown>
+  readonly operationName?: string
+  /** The GraphQL schema being executed against */
+  readonly schema: GraphQLSchema
+  /** Field complexity definitions from the schema builder */
+  readonly fieldComplexities: FieldComplexityMap
+}
+
+/**
+ * Configuration for a GraphQL extension
+ *
+ * Extensions provide lifecycle hooks that run at each phase of request processing,
+ * and can contribute data to the response's `extensions` field.
+ *
+ * @example
+ * ```typescript
+ * // Tracing extension
+ * extension({
+ *   name: "tracing",
+ *   onExecuteStart: () => Effect.gen(function*() {
+ *     const ext = yield* ExtensionsService
+ *     yield* ext.set("tracing", { startTime: Date.now() })
+ *   }),
+ *   onExecuteEnd: () => Effect.gen(function*() {
+ *     const ext = yield* ExtensionsService
+ *     yield* ext.merge("tracing", { endTime: Date.now() })
+ *   }),
+ * })
+ * ```
+ */
+export interface GraphQLExtension<R = never> {
+  readonly name: string
+  readonly description?: string
+
+  /**
+   * Called after the query source is parsed into a DocumentNode.
+   * Useful for query analysis, caching parsed documents, etc.
+   */
+  readonly onParse?: (source: string, document: DocumentNode) => Effect.Effect<void, never, R>
+
+  /**
+   * Called after validation completes.
+   * Receives the document and any validation errors.
+   * Useful for complexity analysis, query whitelisting, etc.
+   */
+  readonly onValidate?: (
+    document: DocumentNode,
+    errors: readonly GraphQLError[]
+  ) => Effect.Effect<void, never, R>
+
+  /**
+   * Called before execution begins.
+   * Receives the full execution arguments.
+   * Useful for setting up tracing, logging, etc.
+   */
+  readonly onExecuteStart?: (args: ExecutionArgs) => Effect.Effect<void, never, R>
+
+  /**
+   * Called after execution completes.
+   * Receives the execution result (including data and errors).
+   * Useful for recording metrics, finalizing traces, etc.
+   */
+  readonly onExecuteEnd?: (result: ExecutionResult) => Effect.Effect<void, never, R>
+}
+
+/**
+ * Service for accumulating extension data during request processing.
+ *
+ * This service is automatically provided for each request and allows
+ * extensions, middleware, and resolvers to contribute to the response
+ * extensions field.
+ *
+ * @example
+ * ```typescript
+ * Effect.gen(function*() {
+ *   const ext = yield* ExtensionsService
+ *
+ *   // Set a value (overwrites existing)
+ *   yield* ext.set("complexity", { score: 42 })
+ *
+ *   // Merge into existing value
+ *   yield* ext.merge("tracing", { endTime: Date.now() })
+ *
+ *   // Get all accumulated extensions
+ *   const all = yield* ext.get()
+ * })
+ * ```
+ */
+export interface ExtensionsService {
+  /**
+   * Set a key-value pair in the extensions.
+   * Overwrites any existing value for this key.
+   */
+  readonly set: (key: string, value: unknown) => Effect.Effect<void>
+
+  /**
+   * Deep merge an object into an existing key's value.
+   * If the key doesn't exist, sets the value.
+   * If the existing value is not an object, overwrites it.
+   */
+  readonly merge: (key: string, value: Record<string, unknown>) => Effect.Effect<void>
+
+  /**
+   * Get all accumulated extensions as a record.
+   */
+  readonly get: () => Effect.Effect<Record<string, unknown>>
+}
+
+/**
+ * Tag for the ExtensionsService
+ */
+export const ExtensionsService = Context.GenericTag<ExtensionsService>(
+  "@effect-gql/ExtensionsService"
+)
+
+/**
+ * Deep merge two objects
+ */
+function deepMerge(
+  target: Record<string, unknown>,
+  source: Record<string, unknown>
+): Record<string, unknown> {
+  const result = { ...target }
+  for (const key of Object.keys(source)) {
+    const sourceValue = source[key]
+    const targetValue = result[key]
+
+    if (
+      typeof sourceValue === "object" &&
+      sourceValue !== null &&
+      !Array.isArray(sourceValue) &&
+      typeof targetValue === "object" &&
+      targetValue !== null &&
+      !Array.isArray(targetValue)
+    ) {
+      result[key] = deepMerge(
+        targetValue as Record<string, unknown>,
+        sourceValue as Record<string, unknown>
+      )
+    } else {
+      result[key] = sourceValue
+    }
+  }
+  return result
+}
+
+/**
+ * Create a new ExtensionsService backed by a Ref
+ */
+export const makeExtensionsService = (): Effect.Effect<ExtensionsService, never, never> =>
+  Effect.gen(function* () {
+    const ref = yield* Ref.make<Record<string, unknown>>({})
+
+    return ExtensionsService.of({
+      set: (key, value) => Ref.update(ref, (current) => ({ ...current, [key]: value })),
+
+      merge: (key, value) =>
+        Ref.update(ref, (current) => {
+          const existing = current[key]
+          if (typeof existing === "object" && existing !== null && !Array.isArray(existing)) {
+            return {
+              ...current,
+              [key]: deepMerge(existing as Record<string, unknown>, value),
+            }
+          }
+          return { ...current, [key]: value }
+        }),
+
+      get: () => Ref.get(ref),
+    })
+  })
+
+/**
+ * Generic helper to run extension hooks with error handling.
+ * Filters extensions that have the specified hook, runs them,
+ * and logs warnings if any hook fails.
+ */
+const runExtensionHooks = <R, K extends keyof GraphQLExtension<R>>(
+  extensions: readonly GraphQLExtension<R>[],
+  hookName: K,
+  getHookEffect: (ext: GraphQLExtension<R>) => Effect.Effect<void, never, R>
+): Effect.Effect<void, never, R> =>
+  Effect.forEach(
+    extensions.filter((ext) => ext[hookName] !== undefined),
+    (ext) =>
+      getHookEffect(ext).pipe(
+        Effect.catchAllCause((cause) =>
+          Effect.logWarning(`Extension "${ext.name}" ${String(hookName)} hook failed`, cause)
+        )
+      ),
+    { discard: true }
+  ) as Effect.Effect<void, never, R>
+
+/**
+ * Run all onParse hooks for registered extensions
+ */
+export const runParseHooks = <R>(
+  extensions: readonly GraphQLExtension<R>[],
+  source: string,
+  document: DocumentNode
+): Effect.Effect<void, never, R> =>
+  runExtensionHooks(extensions, "onParse", (ext) => ext.onParse!(source, document))
+
+/**
+ * Run all onValidate hooks for registered extensions
+ */
+export const runValidateHooks = <R>(
+  extensions: readonly GraphQLExtension<R>[],
+  document: DocumentNode,
+  errors: readonly GraphQLError[]
+): Effect.Effect<void, never, R> =>
+  runExtensionHooks(extensions, "onValidate", (ext) => ext.onValidate!(document, errors))
+
+/**
+ * Run all onExecuteStart hooks for registered extensions
+ */
+export const runExecuteStartHooks = <R>(
+  extensions: readonly GraphQLExtension<R>[],
+  args: ExecutionArgs
+): Effect.Effect<void, never, R> =>
+  runExtensionHooks(extensions, "onExecuteStart", (ext) => ext.onExecuteStart!(args))
+
+/**
+ * Run all onExecuteEnd hooks for registered extensions
+ */
+export const runExecuteEndHooks = <R>(
+  extensions: readonly GraphQLExtension<R>[],
+  result: ExecutionResult
+): Effect.Effect<void, never, R> =>
+  runExtensionHooks(extensions, "onExecuteEnd", (ext) => ext.onExecuteEnd!(result))

package/src/index.ts

@@ -0,0 +1,32 @@
+export * from "./builder"
+export * from "./schema-mapping"
+export * from "./error"
+export * from "./context"
+export * from "./loader"
+export * from "./resolver-context"
+export * from "./server"
+export * from "./extensions"
+export * from "./analyzer-extension"
+
+// Re-export commonly used graphql types to ensure single instance
+export {
+  GraphQLSchema,
+  GraphQLObjectType,
+  GraphQLScalarType,
+  GraphQLInterfaceType,
+  GraphQLUnionType,
+  GraphQLEnumType,
+  GraphQLInputObjectType,
+  GraphQLList,
+  GraphQLNonNull,
+  GraphQLString,
+  GraphQLInt,
+  GraphQLFloat,
+  GraphQLBoolean,
+  GraphQLID,
+  printSchema,
+  lexicographicSortSchema,
+  graphql,
+  Kind,
+} from "graphql"
+export type { ValueNode, GraphQLFieldConfigMap } from "graphql"