@effect-gql/core 0.1.0 → 1.0.0

package/schema-builder-Cvdq7Kz_.d.ts

@@ -0,0 +1,963 @@
+import * as effect from 'effect';
+import { Effect, Config, Stream, Runtime, Context, Pipeable } from 'effect';
+import * as S from 'effect/Schema';
+import * as graphql from 'graphql';
+import { DocumentNode, OperationDefinitionNode, GraphQLSchema, DirectiveLocation, GraphQLResolveInfo, GraphQLError, ExecutionResult } from 'graphql';
+import * as effect_Cause from 'effect/Cause';
+import * as effect_Types from 'effect/Types';
+
+declare const ComplexityLimitExceededError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "ComplexityLimitExceededError";
+} & Readonly<A>;
+/**
+ * Error thrown when query complexity exceeds configured limits
+ */
+declare class ComplexityLimitExceededError extends ComplexityLimitExceededError_base<{
+    readonly message: string;
+    readonly limit: number;
+    readonly actual: number;
+    readonly limitType: "depth" | "complexity" | "aliases" | "fields";
+}> {
+}
+declare const ComplexityAnalysisError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "ComplexityAnalysisError";
+} & Readonly<A>;
+/**
+ * Error thrown when complexity analysis fails
+ */
+declare class ComplexityAnalysisError extends ComplexityAnalysisError_base<{
+    readonly message: string;
+    readonly cause?: unknown;
+}> {
+}
+/**
+ * Result of complexity analysis for a GraphQL operation
+ */
+interface ComplexityResult {
+    /** Maximum depth of the query */
+    readonly depth: number;
+    /** Total complexity score */
+    readonly complexity: number;
+    /** Number of field selections (including nested) */
+    readonly fieldCount: number;
+    /** Number of aliased fields */
+    readonly aliasCount: number;
+}
+/**
+ * Information provided to complexity calculators
+ */
+interface ComplexityAnalysisInfo {
+    /** Parsed GraphQL document */
+    readonly document: DocumentNode;
+    /** The operation being executed */
+    readonly operation: OperationDefinitionNode;
+    /** Variables provided with the query */
+    readonly variables?: Record<string, unknown>;
+    /** The GraphQL schema */
+    readonly schema: GraphQLSchema;
+    /** Field complexity definitions from the builder */
+    readonly fieldComplexities: FieldComplexityMap;
+}
+/**
+ * Information provided when complexity limit is exceeded
+ */
+interface ComplexityExceededInfo {
+    /** The computed complexity result */
+    readonly result: ComplexityResult;
+    /** Which limit was exceeded */
+    readonly exceededLimit: "depth" | "complexity" | "aliases" | "fields";
+    /** The limit value */
+    readonly limit: number;
+    /** The actual value */
+    readonly actual: number;
+    /** The query that exceeded limits */
+    readonly query: string;
+    /** Operation name if provided */
+    readonly operationName?: string;
+}
+/**
+ * Complexity value for a field - can be static or dynamic based on arguments
+ */
+type FieldComplexity = number | ((args: Record<string, unknown>) => number);
+/**
+ * Map of type.field -> complexity
+ */
+type FieldComplexityMap = Map<string, FieldComplexity>;
+/**
+ * Custom complexity calculator function.
+ * Must be self-contained (no service requirements).
+ */
+type ComplexityCalculator = (info: ComplexityAnalysisInfo) => Effect.Effect<ComplexityResult, ComplexityAnalysisError, never>;
+/**
+ * Configuration for query complexity limiting
+ */
+interface ComplexityConfig {
+    /**
+     * Maximum allowed query depth.
+     * Depth is the deepest nesting level in the query.
+     * @example
+     * // Depth 3:
+     * // { user { posts { comments { text } } } }
+     */
+    readonly maxDepth?: number;
+    /**
+     * Maximum allowed total complexity score.
+     * Complexity is calculated by summing field costs.
+     */
+    readonly maxComplexity?: number;
+    /**
+     * Maximum number of field aliases allowed.
+     * Prevents response explosion attacks via aliases.
+     */
+    readonly maxAliases?: number;
+    /**
+     * Maximum total number of fields in the query.
+     * Includes all nested field selections.
+     */
+    readonly maxFields?: number;
+    /**
+     * Default complexity cost for fields without explicit costs.
+     * @default 1
+     */
+    readonly defaultFieldComplexity?: number;
+    /**
+     * Custom complexity calculator.
+     * If provided, this is used instead of the default calculator.
+     * Can be used to implement custom cost algorithms.
+     */
+    readonly calculator?: ComplexityCalculator;
+    /**
+     * Hook called when a limit is exceeded.
+     * Useful for logging, metrics, or custom handling.
+     * This is called BEFORE the error is thrown.
+     * Must be self-contained (no service requirements).
+     */
+    readonly onExceeded?: (info: ComplexityExceededInfo) => Effect.Effect<void, never, never>;
+}
+/**
+ * Default complexity calculator that walks the AST and computes:
+ * - depth: Maximum nesting level
+ * - complexity: Sum of field costs
+ * - fieldCount: Total number of field selections
+ * - aliasCount: Number of aliased fields
+ */
+declare const defaultComplexityCalculator: (defaultCost?: number) => ComplexityCalculator;
+/**
+ * Validate query complexity against configured limits.
+ * Returns the complexity result if within limits, or fails with ComplexityLimitExceededError.
+ */
+declare const validateComplexity: (query: string, operationName: string | undefined, variables: Record<string, unknown> | undefined, schema: GraphQLSchema, fieldComplexities: FieldComplexityMap, config: ComplexityConfig) => Effect.Effect<ComplexityResult, ComplexityLimitExceededError | ComplexityAnalysisError, never>;
+/**
+ * Effect Config for loading complexity configuration from environment variables.
+ *
+ * Environment variables:
+ * - GRAPHQL_MAX_DEPTH: Maximum query depth
+ * - GRAPHQL_MAX_COMPLEXITY: Maximum complexity score
+ * - GRAPHQL_MAX_ALIASES: Maximum number of aliases
+ * - GRAPHQL_MAX_FIELDS: Maximum number of fields
+ * - GRAPHQL_DEFAULT_FIELD_COMPLEXITY: Default field complexity (default: 1)
+ */
+declare const ComplexityConfigFromEnv: Config.Config<ComplexityConfig>;
+/**
+ * A simple depth-only calculator that only tracks query depth.
+ * Use this when you only care about depth limiting and want fast validation.
+ */
+declare const depthOnlyCalculator: ComplexityCalculator;
+/**
+ * Combine multiple calculators - returns the maximum values from all calculators.
+ */
+declare const combineCalculators: (...calculators: ComplexityCalculator[]) => ComplexityCalculator;
+
+/**
+ * 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
+ */
+type CacheControlScope = "PUBLIC" | "PRIVATE";
+/**
+ * Cache control hint for a type or field.
+ * Used to compute the overall cache policy for a GraphQL response.
+ */
+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
+ */
+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
+ */
+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
+ */
+interface InterfaceRegistration {
+    name: string;
+    schema: S.Schema<any, any, any>;
+    resolveType: (value: any) => string;
+    directives?: readonly DirectiveApplication[];
+}
+/**
+ * Configuration for an enum type
+ */
+interface EnumRegistration {
+    name: string;
+    values: readonly string[];
+    description?: string;
+    directives?: readonly DirectiveApplication[];
+}
+/**
+ * Configuration for a union type
+ */
+interface UnionRegistration {
+    name: string;
+    types: readonly string[];
+    resolveType: (value: any) => string;
+    directives?: readonly DirectiveApplication[];
+}
+/**
+ * Configuration for an input type
+ */
+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
+ */
+interface DirectiveApplication {
+    readonly name: string;
+    readonly args?: Record<string, unknown>;
+}
+/**
+ * Configuration for a directive definition
+ */
+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
+ */
+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
+ *   })
+ * })
+ * ```
+ */
+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
+ */
+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
+ */
+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
+ */
+interface GraphQLEffectContext<R> {
+    runtime: Runtime.Runtime<R>;
+}
+/**
+ * Type registries used during schema building
+ */
+interface TypeRegistries {
+    types: Map<string, graphql.GraphQLObjectType>;
+    interfaces: Map<string, graphql.GraphQLInterfaceType>;
+    enums: Map<string, graphql.GraphQLEnumType>;
+    unions: Map<string, graphql.GraphQLUnionType>;
+    inputs: Map<string, graphql.GraphQLInputObjectType>;
+    directives: Map<string, graphql.GraphQLDirective>;
+}
+
+/**
+ * Execution arguments passed to onExecuteStart hook
+ */
+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() })
+ *   }),
+ * })
+ * ```
+ */
+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()
+ * })
+ * ```
+ */
+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
+ */
+declare const ExtensionsService: Context.Tag<ExtensionsService, ExtensionsService>;
+/**
+ * Create a new ExtensionsService backed by a Ref
+ */
+declare const makeExtensionsService: () => Effect.Effect<ExtensionsService, never, never>;
+/**
+ * Run all onParse hooks for registered extensions
+ */
+declare const runParseHooks: <R>(extensions: readonly GraphQLExtension<R>[], source: string, document: DocumentNode) => Effect.Effect<void, never, R>;
+/**
+ * Run all onValidate hooks for registered extensions
+ */
+declare const runValidateHooks: <R>(extensions: readonly GraphQLExtension<R>[], document: DocumentNode, errors: readonly GraphQLError[]) => Effect.Effect<void, never, R>;
+/**
+ * Run all onExecuteStart hooks for registered extensions
+ */
+declare const runExecuteStartHooks: <R>(extensions: readonly GraphQLExtension<R>[], args: ExecutionArgs) => Effect.Effect<void, never, R>;
+/**
+ * Run all onExecuteEnd hooks for registered extensions
+ */
+declare const runExecuteEndHooks: <R>(extensions: readonly GraphQLExtension<R>[], result: ExecutionResult) => Effect.Effect<void, never, R>;
+
+/**
+ * Map of type.field -> cache hint, or type -> cache hint for type-level hints
+ */
+type CacheHintMap = Map<string, CacheHint>;
+/**
+ * Computed cache policy for a GraphQL response
+ */
+interface CachePolicy {
+    /**
+     * Maximum age in seconds the response can be cached.
+     * This is the minimum maxAge of all resolved fields.
+     * If 0, the response should not be cached.
+     */
+    readonly maxAge: number;
+    /**
+     * Cache scope - PUBLIC means CDN-cacheable, PRIVATE means browser-only.
+     * If any field is PRIVATE, the entire response is PRIVATE.
+     */
+    readonly scope: CacheControlScope;
+}
+/**
+ * Configuration for cache control
+ */
+interface CacheControlConfig {
+    /**
+     * Enable cache control header calculation.
+     * @default true
+     */
+    readonly enabled?: boolean;
+    /**
+     * Default maxAge for root fields (Query, Mutation).
+     * @default 0 (no caching)
+     */
+    readonly defaultMaxAge?: number;
+    /**
+     * Default scope for fields without explicit scope.
+     * @default "PUBLIC"
+     */
+    readonly defaultScope?: CacheControlScope;
+    /**
+     * Whether to set HTTP Cache-Control headers on responses.
+     * @default true
+     */
+    readonly calculateHttpHeaders?: boolean;
+}
+/**
+ * Information provided to cache policy calculation
+ */
+interface CachePolicyAnalysisInfo {
+    /** Parsed GraphQL document */
+    readonly document: DocumentNode;
+    /** The operation being executed */
+    readonly operation: OperationDefinitionNode;
+    /** The GraphQL schema */
+    readonly schema: GraphQLSchema;
+    /** Cache hints from the builder (type.field -> hint or type -> hint) */
+    readonly cacheHints: CacheHintMap;
+    /** Configuration options */
+    readonly config: CacheControlConfig;
+}
+/**
+ * Compute the cache policy for a GraphQL response based on the fields resolved.
+ *
+ * The policy is computed by walking the selection set and aggregating hints:
+ * - maxAge: Use the minimum maxAge of all resolved fields
+ * - scope: If any field is PRIVATE, the entire response is PRIVATE
+ *
+ * Default behaviors (matching Apollo):
+ * - Root fields default to maxAge: 0 (unless configured otherwise)
+ * - Object-returning fields default to maxAge: 0
+ * - Scalar fields inherit their parent's maxAge
+ * - Fields with inheritMaxAge: true inherit from parent
+ */
+declare const computeCachePolicy: (info: CachePolicyAnalysisInfo) => Effect.Effect<CachePolicy, never, never>;
+/**
+ * Compute cache policy from a query string
+ */
+declare const computeCachePolicyFromQuery: (query: string, operationName: string | undefined, schema: GraphQLSchema, cacheHints: CacheHintMap, config?: CacheControlConfig) => Effect.Effect<CachePolicy, Error, never>;
+/**
+ * Convert a cache policy to an HTTP Cache-Control header value
+ */
+declare const toCacheControlHeader: (policy: CachePolicy) => string;
+/**
+ * Effect Config for loading cache control configuration from environment variables.
+ *
+ * Environment variables:
+ * - GRAPHQL_CACHE_CONTROL_ENABLED: Enable cache control (default: true)
+ * - GRAPHQL_CACHE_CONTROL_DEFAULT_MAX_AGE: Default maxAge for root fields (default: 0)
+ * - GRAPHQL_CACHE_CONTROL_DEFAULT_SCOPE: Default scope (PUBLIC or PRIVATE, default: PUBLIC)
+ * - GRAPHQL_CACHE_CONTROL_HTTP_HEADERS: Set HTTP headers (default: true)
+ */
+declare const CacheControlConfigFromEnv: Config.Config<CacheControlConfig>;
+
+/**
+ * GraphQL Schema Builder with type-safe service requirements (Layer-per-Request Pattern)
+ *
+ * The type parameter R accumulates all service requirements from resolvers.
+ * Unlike the runtime-in-context approach, this pattern builds the schema without
+ * executing any Effects. At request time, you provide a Layer with all required services.
+ */
+declare class GraphQLSchemaBuilder<R = never> implements Pipeable.Pipeable {
+    private readonly state;
+    private constructor();
+    /**
+     * Pipeable interface implementation - enables fluent .pipe() syntax
+     */
+    pipe<A>(this: A): A;
+    pipe<A, B>(this: A, ab: (a: A) => B): B;
+    pipe<A, B, C>(this: A, ab: (a: A) => B, bc: (b: B) => C): C;
+    pipe<A, B, C, D>(this: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D): D;
+    pipe<A, B, C, D, E>(this: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E): E;
+    pipe<A, B, C, D, E, F>(this: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F): F;
+    pipe<A, B, C, D, E, F, G>(this: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G): G;
+    pipe<A, B, C, D, E, F, G, H>(this: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H): H;
+    pipe<A, B, C, D, E, F, G, H, I>(this: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I): I;
+    /**
+     * Create an empty schema builder
+     */
+    static readonly empty: GraphQLSchemaBuilder<never>;
+    /**
+     * Create a new builder with updated state
+     */
+    private with;
+    /**
+     * Add a query field
+     */
+    query<A, E, R2, Args = void>(name: string, config: {
+        type: S.Schema<A, any, any>;
+        args?: S.Schema<Args, any, any>;
+        description?: string;
+        directives?: readonly DirectiveApplication[];
+        /**
+         * Complexity cost of this field for query complexity limiting.
+         * Can be a static number or a function that receives the resolved arguments.
+         */
+        complexity?: FieldComplexity;
+        /**
+         * Cache control hint for this field.
+         * Used to compute HTTP Cache-Control headers for the response.
+         */
+        cacheControl?: CacheHint;
+        resolve: (args: Args) => Effect.Effect<A, E, R2>;
+    }): GraphQLSchemaBuilder<R | R2>;
+    /**
+     * Add a mutation field
+     */
+    mutation<A, E, R2, Args = void>(name: string, config: {
+        type: S.Schema<A, any, any>;
+        args?: S.Schema<Args, any, any>;
+        description?: string;
+        directives?: readonly DirectiveApplication[];
+        /**
+         * Complexity cost of this field for query complexity limiting.
+         * Can be a static number or a function that receives the resolved arguments.
+         */
+        complexity?: FieldComplexity;
+        resolve: (args: Args) => Effect.Effect<A, E, R2>;
+    }): GraphQLSchemaBuilder<R | R2>;
+    /**
+     * Add a subscription field
+     *
+     * Subscriptions return a Stream that yields values over time.
+     * The subscribe function returns an Effect that produces a Stream.
+     *
+     * @example
+     * ```typescript
+     * builder.subscription("userCreated", {
+     *   type: User,
+     *   subscribe: Effect.gen(function*() {
+     *     const pubsub = yield* PubSubService
+     *     return pubsub.subscribe("USER_CREATED")
+     *   }),
+     * })
+     * ```
+     */
+    subscription<A, E, R2, Args = void>(name: string, config: {
+        type: S.Schema<A, any, any>;
+        args?: S.Schema<Args, any, any>;
+        description?: string;
+        directives?: readonly DirectiveApplication[];
+        /**
+         * Complexity cost of this subscription for query complexity limiting.
+         * Can be a static number or a function that receives the resolved arguments.
+         */
+        complexity?: FieldComplexity;
+        /**
+         * Cache control hint for this subscription.
+         * Note: Subscriptions are typically not cached, but this can be used for initial response hints.
+         */
+        cacheControl?: CacheHint;
+        subscribe: (args: Args) => Effect.Effect<effect.Stream.Stream<A, E, R2>, E, R2>;
+        resolve?: (value: A, args: Args) => Effect.Effect<A, E, R2>;
+    }): GraphQLSchemaBuilder<R | R2>;
+    /**
+     * Register an object type from a schema
+     */
+    objectType<A, R2 = never>(config: {
+        name?: string;
+        schema: S.Schema<A, 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.
+         */
+        cacheControl?: CacheHint;
+        fields?: Record<string, {
+            type: S.Schema<any, any, any>;
+            args?: S.Schema<any, any, any>;
+            description?: string;
+            directives?: readonly DirectiveApplication[];
+            /**
+             * Complexity cost of this field for query complexity limiting.
+             */
+            complexity?: FieldComplexity;
+            /**
+             * Cache control hint for this field.
+             */
+            cacheControl?: CacheHint;
+            resolve: (parent: A, args: any) => Effect.Effect<any, any, any>;
+        }>;
+    }): GraphQLSchemaBuilder<R | R2>;
+    /**
+     * Register an interface type from a schema
+     */
+    interfaceType(config: {
+        name?: string;
+        schema: S.Schema<any, any, any>;
+        resolveType?: (value: any) => string;
+        directives?: readonly DirectiveApplication[];
+    }): GraphQLSchemaBuilder<R>;
+    /**
+     * Register an enum type
+     */
+    enumType(config: {
+        name: string;
+        values: readonly string[];
+        description?: string;
+        directives?: readonly DirectiveApplication[];
+    }): GraphQLSchemaBuilder<R>;
+    /**
+     * Register a union type
+     */
+    unionType(config: {
+        name: string;
+        types: readonly string[];
+        resolveType?: (value: any) => string;
+        directives?: readonly DirectiveApplication[];
+    }): GraphQLSchemaBuilder<R>;
+    /**
+     * Register an input type
+     */
+    inputType(config: {
+        name?: string;
+        schema: S.Schema<any, any, any>;
+        description?: string;
+        directives?: readonly DirectiveApplication[];
+    }): GraphQLSchemaBuilder<R>;
+    /**
+     * Register a directive
+     */
+    directive<Args = void, R2 = never>(config: {
+        name: string;
+        description?: string;
+        locations: readonly DirectiveLocation[];
+        args?: S.Schema<Args, any, any>;
+        apply?: (args: Args) => <A, E, R3>(effect: Effect.Effect<A, E, R3>) => Effect.Effect<A, E, R2 | R3>;
+    }): GraphQLSchemaBuilder<R | R2>;
+    /**
+     * Register a middleware
+     *
+     * Middleware wraps all resolvers (or those matching a pattern) and executes
+     * in an "onion" model - first registered middleware is the outermost layer.
+     *
+     * @param config.name - Middleware name (for debugging/logging)
+     * @param config.description - Optional description
+     * @param config.match - Optional predicate to filter which fields this applies to
+     * @param config.apply - Function that transforms the resolver Effect
+     *
+     * @example
+     * ```typescript
+     * builder.middleware({
+     *   name: "logging",
+     *   apply: (effect, ctx) => Effect.gen(function*() {
+     *     yield* Effect.logInfo(`Resolving ${ctx.info.fieldName}`)
+     *     const start = Date.now()
+     *     const result = yield* effect
+     *     yield* Effect.logInfo(`Resolved in ${Date.now() - start}ms`)
+     *     return result
+     *   })
+     * })
+     * ```
+     */
+    middleware<R2 = never>(config: {
+        name: string;
+        description?: string;
+        match?: (info: GraphQLResolveInfo) => boolean;
+        apply: <A, E, R3>(effect: Effect.Effect<A, E, R3>, context: MiddlewareContext) => Effect.Effect<A, E, R2 | R3>;
+    }): GraphQLSchemaBuilder<R | R2>;
+    /**
+     * Register an extension
+     *
+     * Extensions provide lifecycle hooks that run at each phase of request processing
+     * (parse, validate, execute) and can contribute data to the response's extensions field.
+     *
+     * @param config.name - Extension name (for debugging/logging)
+     * @param config.description - Optional description
+     * @param config.onParse - Called after query parsing
+     * @param config.onValidate - Called after validation
+     * @param config.onExecuteStart - Called before execution begins
+     * @param config.onExecuteEnd - Called after execution completes
+     *
+     * @example
+     * ```typescript
+     * builder.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() })
+     *   }),
+     * })
+     * ```
+     */
+    extension<R2 = never>(config: {
+        name: string;
+        description?: string;
+        onParse?: (source: string, document: DocumentNode) => Effect.Effect<void, never, R2>;
+        onValidate?: (document: DocumentNode, errors: readonly GraphQLError[]) => Effect.Effect<void, never, R2>;
+        onExecuteStart?: (args: ExecutionArgs) => Effect.Effect<void, never, R2>;
+        onExecuteEnd?: (result: ExecutionResult) => Effect.Effect<void, never, R2>;
+    }): GraphQLSchemaBuilder<R | R2>;
+    /**
+     * Get the registered extensions for use by the execution layer
+     */
+    getExtensions(): readonly GraphQLExtension<any>[];
+    /**
+     * Add a computed/relational field to an object type
+     */
+    field<Parent, A, E, R2, Args = void>(typeName: string, fieldName: string, config: {
+        type: S.Schema<A, any, any>;
+        args?: S.Schema<Args, any, any>;
+        description?: string;
+        directives?: readonly DirectiveApplication[];
+        /**
+         * Complexity cost of this field for query complexity limiting.
+         * Can be a static number or a function that receives the resolved arguments.
+         */
+        complexity?: FieldComplexity;
+        /**
+         * Cache control hint for this field.
+         * Used to compute HTTP Cache-Control headers for the response.
+         */
+        cacheControl?: CacheHint;
+        resolve: (parent: Parent, args: Args) => Effect.Effect<A, E, R2>;
+    }): GraphQLSchemaBuilder<R | R2>;
+    /**
+     * Get the field complexity map for use in complexity validation.
+     * Maps "TypeName.fieldName" to the complexity value or function.
+     */
+    getFieldComplexities(): FieldComplexityMap;
+    /**
+     * Get the cache hint map for use in cache control calculation.
+     * Maps "TypeName.fieldName" to the cache hint for field-level hints,
+     * or "TypeName" to the cache hint for type-level hints.
+     */
+    getCacheHints(): CacheHintMap;
+    /**
+     * Build the GraphQL schema (no services required)
+     */
+    buildSchema(): GraphQLSchema;
+    private buildDirectiveRegistry;
+    private buildEnumRegistry;
+    private buildInputRegistry;
+    private buildInterfaceRegistry;
+    private buildTypeAndUnionRegistries;
+    private createFieldBuilderContext;
+    private buildQueryFields;
+    private buildMutationFields;
+    private buildSubscriptionFields;
+    private assembleSchema;
+}
+
+export { computeCachePolicy as A, computeCachePolicyFromQuery as B, type CacheHint as C, type DirectiveApplication as D, ExtensionsService as E, type FieldComplexityMap as F, type GraphQLExtension as G, toCacheControlHeader as H, type InterfaceRegistration as I, CacheControlConfigFromEnv as J, type ExecutionArgs as K, makeExtensionsService as L, type MiddlewareContext as M, runParseHooks as N, type ObjectFieldRegistration as O, runValidateHooks as P, runExecuteStartHooks as Q, runExecuteEndHooks as R, type SubscriptionFieldRegistration as S, type TypeRegistration as T, type UnionRegistration as U, type FieldRegistration as a, type EnumRegistration as b, type InputTypeRegistration as c, type DirectiveRegistration as d, type MiddlewareRegistration as e, type GraphQLEffectContext as f, type TypeRegistries as g, type CacheControlScope as h, GraphQLSchemaBuilder as i, type ComplexityConfig as j, type ComplexityResult as k, type ComplexityAnalysisInfo as l, type ComplexityExceededInfo as m, type ComplexityCalculator as n, type FieldComplexity as o, ComplexityLimitExceededError as p, ComplexityAnalysisError as q, defaultComplexityCalculator as r, depthOnlyCalculator as s, combineCalculators as t, ComplexityConfigFromEnv as u, validateComplexity as v, type CacheHintMap as w, type CachePolicy as x, type CacheControlConfig as y, type CachePolicyAnalysisInfo as z };