@effect-gql/core 0.1.0 → 1.1.0

package/index.d.ts

@@ -0,0 +1,529 @@
+import { F as FieldComplexityMap, G as GraphQLExtension, E as ExtensionsService } from './schema-builder-DKvkzU_M.js';
+export { y as CacheControlConfig, J as CacheControlConfigFromEnv, h as CacheControlScope, C as CacheHint, w as CacheHintMap, x as CachePolicy, z as CachePolicyAnalysisInfo, q as ComplexityAnalysisError, l as ComplexityAnalysisInfo, n as ComplexityCalculator, j as ComplexityConfig, u as ComplexityConfigFromEnv, m as ComplexityExceededInfo, p as ComplexityLimitExceededError, k as ComplexityResult, D as DirectiveApplication, d as DirectiveRegistration, b as EnumRegistration, K as ExecutionArgs, o as FieldComplexity, a as FieldRegistration, f as GraphQLEffectContext, i as GraphQLSchemaBuilder, c as InputTypeRegistration, I as InterfaceRegistration, M as MiddlewareContext, e as MiddlewareRegistration, O as ObjectFieldRegistration, S as SubscriptionFieldRegistration, T as TypeRegistration, g as TypeRegistries, U as UnionRegistration, t as combineCalculators, A as computeCachePolicy, B as computeCachePolicyFromQuery, r as defaultComplexityCalculator, s as depthOnlyCalculator, L as makeExtensionsService, R as runExecuteEndHooks, Q as runExecuteStartHooks, N as runParseHooks, P as runValidateHooks, H as toCacheControlHeader, v as validateComplexity } from './schema-builder-DKvkzU_M.js';
+import { GraphQLOutputType, GraphQLInputType, GraphQLFieldConfigArgumentMap, GraphQLObjectType } from 'graphql';
+export { DirectiveLocation, GraphQLBoolean, GraphQLEnumType, GraphQLFieldConfigMap, GraphQLFloat, GraphQLID, GraphQLInputObjectType, GraphQLInt, GraphQLInterfaceType, GraphQLList, GraphQLNonNull, GraphQLObjectType, GraphQLScalarType, GraphQLSchema, GraphQLString, GraphQLUnionType, Kind, ValueNode, graphql, lexicographicSortSchema, printSchema } from 'graphql';
+export { compose, directive, enumType, execute, extension, field, getSchemaName, inputType, interfaceType, middleware, mutation, objectType, query, subscription, unionType } from './builder/index.js';
+import { Effect, Context, Layer, Ref, HashMap, Option } from 'effect';
+import * as S from 'effect/Schema';
+import * as effect_Cause from 'effect/Cause';
+import * as effect_Types from 'effect/Types';
+import DataLoader from 'dataloader';
+export { CloseEvent, CompleteMessage, ConnectionContext, EffectSSE, EffectWebSocket, ErrorHandler, GraphQLRouterConfig, GraphQLRouterConfigFromEnv, GraphQLRouterConfigInput, GraphQLSSEConfig, GraphQLSSEOptions, GraphQLWSConfig, GraphQLWSOptions, GraphiQLConfig, MakeGraphQLRouterOptions, SSEConnectionContext, SSEError, SSEEvent, SSEEventType, SSESubscriptionRequest, SSESubscriptionResult, SSE_HEADERS, SubscribeMessage, WS_CLOSED, WebSocketError, WsWebSocket, defaultConfig, defaultErrorHandler, formatCompleteEvent, formatErrorEvent, formatNextEvent, formatSSEMessage, graphiqlHtml, makeGraphQLRouter, makeGraphQLSSEHandler, makeGraphQLWSHandler, makeSSESubscriptionStream, normalizeConfig, toEffectWebSocketFromWs, toRouter } from './server/index.js';
+import '@effect/platform';
+
+/**
+ * Convert an Effect Schema to a GraphQL output type
+ */
+declare const toGraphQLType: (schema: S.Schema<any, any, any>) => GraphQLOutputType;
+/**
+ * Convert an Effect Schema to a GraphQL input type
+ */
+declare const toGraphQLInputType: (schema: S.Schema<any, any, any>) => GraphQLInputType;
+/**
+ * Additional field configuration for computed/relational fields
+ */
+interface AdditionalField<Parent, Args, R, E, A> {
+    type: GraphQLOutputType;
+    args?: GraphQLFieldConfigArgumentMap;
+    description?: string;
+    resolve: (parent: Parent, args: Args) => Effect.Effect<A, E, R>;
+}
+/**
+ * Create a GraphQL Object Type from an Effect Schema with a name
+ * Optionally add computed/relational fields with resolvers
+ */
+declare const toGraphQLObjectType: <T>(name: string, schema: S.Schema<any, any, any>, additionalFields?: Record<string, AdditionalField<T, any, any, any, any>>) => GraphQLObjectType;
+/**
+ * Convert an Effect Schema to GraphQL arguments
+ */
+declare const toGraphQLArgs: (schema: S.Schema<any, any, any>) => GraphQLFieldConfigArgumentMap;
+
+declare const GraphQLError_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: "GraphQLError";
+} & Readonly<A>;
+/**
+ * Base class for GraphQL errors in Effect
+ */
+declare class GraphQLError extends GraphQLError_base<{
+    message: string;
+    extensions?: Record<string, unknown>;
+}> {
+}
+declare const ValidationError_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: "ValidationError";
+} & Readonly<A>;
+/**
+ * Validation error for input validation failures
+ */
+declare class ValidationError extends ValidationError_base<{
+    message: string;
+    field?: string;
+}> {
+}
+declare const AuthorizationError_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: "AuthorizationError";
+} & Readonly<A>;
+/**
+ * Authorization error for access control failures
+ */
+declare class AuthorizationError extends AuthorizationError_base<{
+    message: string;
+}> {
+}
+declare const NotFoundError_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: "NotFoundError";
+} & Readonly<A>;
+/**
+ * Not found error for missing resources
+ */
+declare class NotFoundError extends NotFoundError_base<{
+    message: string;
+    resource?: string;
+}> {
+}
+
+/**
+ * GraphQL request context containing request-specific data
+ */
+interface GraphQLRequestContext {
+    readonly request: {
+        readonly headers: Record<string, string>;
+        readonly query: string;
+        readonly variables?: Record<string, unknown>;
+        readonly operationName?: string;
+    };
+}
+declare const GraphQLRequestContext: Context.Tag<GraphQLRequestContext, GraphQLRequestContext>;
+/**
+ * Create a layer from request context
+ */
+declare const makeRequestContextLayer: (context: GraphQLRequestContext) => Layer.Layer<GraphQLRequestContext>;
+
+/**
+ * Ergonomic DataLoader helpers for Effect-based GraphQL
+ *
+ * This module provides a type-safe, declarative way to define DataLoaders
+ * that integrate seamlessly with Effect's service system.
+ *
+ * @example
+ * ```typescript
+ * // Define loaders
+ * const loaders = Loader.define({
+ *   UserById: Loader.single<string, User>({
+ *     batch: (ids) => db.getUsersByIds(ids),
+ *     key: (user) => user.id,
+ *   }),
+ *
+ *   PostsByAuthorId: Loader.grouped<string, Post>({
+ *     batch: (ids) => db.getPostsForAuthors(ids),
+ *     groupBy: (post) => post.authorId,
+ *   }),
+ * })
+ *
+ * // Use in resolvers
+ * resolve: (parent) => loaders.load("UserById", parent.authorId)
+ * ```
+ */
+/**
+ * Configuration for a single-value loader (one key -> one value)
+ */
+interface SingleLoaderDef<K, V, R> {
+    readonly _tag: "single";
+    readonly batch: (keys: readonly K[]) => Effect.Effect<readonly V[], Error, R>;
+    readonly key: (value: V) => K;
+}
+/**
+ * Configuration for a grouped loader (one key -> many values)
+ */
+interface GroupedLoaderDef<K, V, R> {
+    readonly _tag: "grouped";
+    readonly batch: (keys: readonly K[]) => Effect.Effect<readonly V[], Error, R>;
+    readonly groupBy: (value: V) => K;
+}
+type LoaderDef<K, V, R> = SingleLoaderDef<K, V, R> | GroupedLoaderDef<K, V, R>;
+/**
+ * Runtime DataLoader instances
+ */
+type LoaderInstances<Defs extends Record<string, LoaderDef<any, any, any>>> = {
+    [Name in keyof Defs]: Defs[Name] extends SingleLoaderDef<infer K, infer V, any> ? DataLoader<K, V> : Defs[Name] extends GroupedLoaderDef<infer K, infer V, any> ? DataLoader<K, V[]> : never;
+};
+/**
+ * Extract the value type for a loader (accounting for grouped loaders)
+ */
+type LoaderValue<Def> = Def extends SingleLoaderDef<any, infer V, any> ? V : Def extends GroupedLoaderDef<any, infer V, any> ? V[] : never;
+/**
+ * Extract the key type for a loader
+ */
+type LoaderKey<Def> = Def extends LoaderDef<infer K, any, any> ? K : never;
+/**
+ * Extract combined requirements from all loaders
+ */
+type LoaderRequirements<Defs extends Record<string, LoaderDef<any, any, any>>> = {
+    [K in keyof Defs]: Defs[K] extends LoaderDef<any, any, infer R> ? R : never;
+}[keyof Defs];
+/**
+ * Create a single-value loader definition.
+ * One key maps to one value.
+ *
+ * @example
+ * ```typescript
+ * Loader.single<string, User>({
+ *   batch: (ids) => db.getUsersByIds(ids),
+ *   key: (user) => user.id,
+ * })
+ * ```
+ */
+declare function single<K, V, R = never>(config: {
+    batch: (keys: readonly K[]) => Effect.Effect<readonly V[], Error, R>;
+    key: (value: V) => K;
+}): SingleLoaderDef<K, V, R>;
+/**
+ * Create a grouped loader definition.
+ * One key maps to many values.
+ *
+ * @example
+ * ```typescript
+ * Loader.grouped<string, Post>({
+ *   batch: (authorIds) => db.getPostsForAuthors(authorIds),
+ *   groupBy: (post) => post.authorId,
+ * })
+ * ```
+ */
+declare function grouped<K, V, R = never>(config: {
+    batch: (keys: readonly K[]) => Effect.Effect<readonly V[], Error, R>;
+    groupBy: (value: V) => K;
+}): GroupedLoaderDef<K, V, R>;
+/**
+ * A registry of loader definitions with methods to create instances and layers
+ */
+declare class LoaderRegistry<Defs extends Record<string, LoaderDef<any, any, any>>> {
+    readonly definitions: Defs;
+    readonly _tag = "LoaderRegistry";
+    /**
+     * The Effect service tag for this loader registry
+     */
+    readonly Service: Context.Tag<LoaderInstances<Defs>, LoaderInstances<Defs>>;
+    constructor(definitions: Defs);
+    /**
+     * Create a Layer that provides fresh DataLoader instances.
+     * Call this once per request to get request-scoped loaders.
+     */
+    toLayer(): Layer.Layer<LoaderInstances<Defs>, never, LoaderRequirements<Defs>>;
+    /**
+     * Helper to use loaders in a resolver with a callback.
+     */
+    use<A>(fn: (loaders: LoaderInstances<Defs>) => Promise<A>): Effect.Effect<A, Error, LoaderInstances<Defs>>;
+    /**
+     * Load a single value by key.
+     * This is the most common operation in resolvers.
+     *
+     * @internal The internal cast is safe because LoaderInstances<Defs> guarantees
+     * that loaders[name] is a DataLoader with the correct key/value types.
+     */
+    load<Name extends keyof Defs & string>(name: Name, key: LoaderKey<Defs[Name]>): Effect.Effect<LoaderValue<Defs[Name]>, Error, LoaderInstances<Defs>>;
+    /**
+     * Load multiple values by keys.
+     * All keys are batched into a single request.
+     *
+     * @internal The internal cast is safe because LoaderInstances<Defs> guarantees
+     * that loaders[name] is a DataLoader with the correct key/value types.
+     */
+    loadMany<Name extends keyof Defs & string>(name: Name, keys: readonly LoaderKey<Defs[Name]>[]): Effect.Effect<readonly LoaderValue<Defs[Name]>[], Error, LoaderInstances<Defs>>;
+}
+/**
+ * Define a set of loaders.
+ *
+ * @example
+ * ```typescript
+ * const loaders = Loader.define({
+ *   UserById: Loader.single<string, User>({
+ *     batch: (ids) => db.getUsersByIds(ids),
+ *     key: (user) => user.id,
+ *   }),
+ *   PostsByAuthorId: Loader.grouped<string, Post>({
+ *     batch: (ids) => db.getPostsForAuthors(ids),
+ *     groupBy: (post) => post.authorId,
+ *   }),
+ * })
+ *
+ * // In resolvers:
+ * loaders.load("UserById", "123")
+ * loaders.loadMany("UserById", ["1", "2", "3"])
+ * ```
+ */
+declare function define<Defs extends Record<string, LoaderDef<any, any, any>>>(definitions: Defs): LoaderRegistry<Defs>;
+/**
+ * Map an array of items to match requested keys.
+ * Returns items in the same order as keys, with errors for missing items.
+ */
+declare function mapByKey<K, V>(keys: readonly K[], items: readonly V[], keyFn: (item: V) => K): (V | Error)[];
+/**
+ * Group an array of items by a key function.
+ * Returns a Map from key to array of matching items.
+ * Guarantees an entry (possibly empty) for each requested key.
+ */
+declare function groupByKey<K, V>(keys: readonly K[], items: readonly V[], keyFn: (item: V) => K): Map<K, V[]>;
+declare const Loader: {
+    readonly define: typeof define;
+    readonly single: typeof single;
+    readonly grouped: typeof grouped;
+    readonly mapByKey: typeof mapByKey;
+    readonly groupByKey: typeof groupByKey;
+};
+
+/**
+ * A type-safe context system for passing values through the resolver hierarchy.
+ *
+ * Unlike simple property bags, this provides:
+ * - Type-safe slots that know their value type
+ * - Clear errors when required context is missing
+ * - Request-scoped storage that works across nested resolvers
+ *
+ * @example
+ * ```typescript
+ * // Define a context slot
+ * const AuthPrincipal = ResolverContext.make<User>("AuthPrincipal")
+ *
+ * // Provide in a directive
+ * .directive({
+ *   name: "auth",
+ *   apply: () => (effect) => Effect.gen(function*() {
+ *     const user = yield* validateJwt()
+ *     yield* ResolverContext.set(AuthPrincipal, user)
+ *     return yield* effect
+ *   }),
+ * })
+ *
+ * // Access in any nested resolver
+ * .field("User", "posts", {
+ *   resolve: (parent) => Effect.gen(function*() {
+ *     const user = yield* ResolverContext.get(AuthPrincipal)
+ *     // ...
+ *   }),
+ * })
+ * ```
+ */
+/**
+ * Error thrown when trying to access a context value that hasn't been set
+ */
+declare class MissingResolverContextError extends Error {
+    readonly contextName: string;
+    readonly _tag = "MissingResolverContextError";
+    constructor(contextName: string);
+}
+/**
+ * A typed context slot that can hold a value of type A
+ */
+interface ResolverContextSlot<A> {
+    readonly _tag: "ResolverContextSlot";
+    readonly name: string;
+    readonly _A: A;
+}
+/**
+ * Internal storage for resolver context values.
+ * This is a request-scoped service that holds all context values.
+ */
+interface ResolverContextStore {
+    readonly ref: Ref.Ref<HashMap.HashMap<string, unknown>>;
+}
+declare const ResolverContextStore: Context.Tag<ResolverContextStore, ResolverContextStore>;
+/**
+ * Create a Layer that provides the ResolverContextStore.
+ * This should be included in the request layer.
+ */
+declare const makeStoreLayer: () => Effect.Effect<Layer.Layer<ResolverContextStore>>;
+/**
+ * Create a Layer that provides an empty ResolverContextStore.
+ * Convenience function for creating a fresh store layer.
+ */
+declare const storeLayer: Layer.Layer<ResolverContextStore>;
+/**
+ * Create a new resolver context slot.
+ *
+ * The name is used for error messages when the context is accessed but not set.
+ *
+ * @example
+ * ```typescript
+ * const AuthPrincipal = ResolverContext.make<User>("AuthPrincipal")
+ * const TenantId = ResolverContext.make<string>("TenantId")
+ * ```
+ */
+declare const make: <A>(name: string) => ResolverContextSlot<A>;
+/**
+ * Get a value from the resolver context.
+ *
+ * Fails with MissingResolverContextError if the context was not set
+ * by a parent resolver or directive.
+ *
+ * @example
+ * ```typescript
+ * const effect = Effect.gen(function*() {
+ *   const user = yield* ResolverContext.get(AuthPrincipal)
+ *   // user is typed as User
+ * })
+ * ```
+ */
+declare const get: <A>(slot: ResolverContextSlot<A>) => Effect.Effect<A, MissingResolverContextError, ResolverContextStore>;
+/**
+ * Get a value from the resolver context as an Option.
+ *
+ * Returns None if the context was not set, instead of failing.
+ * Useful when context is optional.
+ */
+declare const getOption: <A>(slot: ResolverContextSlot<A>) => Effect.Effect<Option.Option<A>, never, ResolverContextStore>;
+/**
+ * Set a value in the resolver context.
+ *
+ * The value will be available to all subsequent resolver calls in this request.
+ * This mutates the request-scoped store, so nested resolvers will see the value.
+ *
+ * @example
+ * ```typescript
+ * // In a directive
+ * const withAuth = (effect) => Effect.gen(function*() {
+ *   const user = yield* validateJwt()
+ *   yield* ResolverContext.set(AuthPrincipal, user)
+ *   return yield* effect
+ * })
+ * ```
+ */
+declare const set: <A>(slot: ResolverContextSlot<A>, value: A) => Effect.Effect<void, never, ResolverContextStore>;
+/**
+ * Set multiple context values at once.
+ */
+declare const setMany: (values: ReadonlyArray<readonly [ResolverContextSlot<any>, any]>) => Effect.Effect<void, never, ResolverContextStore>;
+/**
+ * Check if a context slot has a value set.
+ */
+declare const has: <A>(slot: ResolverContextSlot<A>) => Effect.Effect<boolean, never, ResolverContextStore>;
+/**
+ * Get a value or return a default if not set.
+ */
+declare const getOrElse: <A>(slot: ResolverContextSlot<A>, orElse: () => A) => Effect.Effect<A, never, ResolverContextStore>;
+/**
+ * Run an effect with a temporary context value.
+ * The value is set before the effect runs and removed after.
+ * Useful for scoped context that shouldn't persist.
+ */
+declare const scoped: <A>(slot: ResolverContextSlot<A>, value: A) => <B, E, R>(effect: Effect.Effect<B, E, R>) => Effect.Effect<B, E, R | ResolverContextStore>;
+/**
+ * Namespace for ResolverContext functions
+ */
+declare const ResolverContext: {
+    readonly make: <A>(name: string) => ResolverContextSlot<A>;
+    readonly get: <A>(slot: ResolverContextSlot<A>) => Effect.Effect<A, MissingResolverContextError, ResolverContextStore>;
+    readonly getOption: <A>(slot: ResolverContextSlot<A>) => Effect.Effect<Option.Option<A>, never, ResolverContextStore>;
+    readonly set: <A>(slot: ResolverContextSlot<A>, value: A) => Effect.Effect<void, never, ResolverContextStore>;
+    readonly setMany: (values: ReadonlyArray<readonly [ResolverContextSlot<any>, any]>) => Effect.Effect<void, never, ResolverContextStore>;
+    readonly has: <A>(slot: ResolverContextSlot<A>) => Effect.Effect<boolean, never, ResolverContextStore>;
+    readonly getOrElse: <A>(slot: ResolverContextSlot<A>, orElse: () => A) => Effect.Effect<A, never, ResolverContextStore>;
+    readonly scoped: <A>(slot: ResolverContextSlot<A>, value: A) => <B, E, R>(effect: Effect.Effect<B, E, R>) => Effect.Effect<B, E, R | ResolverContextStore>;
+    readonly storeLayer: Layer.Layer<ResolverContextStore, never, never>;
+    readonly makeStoreLayer: () => Effect.Effect<Layer.Layer<ResolverContextStore>>;
+    readonly Store: Context.Tag<ResolverContextStore, ResolverContextStore>;
+    readonly MissingResolverContextError: typeof MissingResolverContextError;
+};
+
+/**
+ * Configuration for the analyzer extension
+ */
+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
+ */
+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
+ * //     }
+ * //   }
+ * // }
+ * ```
+ */
+declare const createAnalyzerExtension: (config?: AnalyzerExtensionConfig) => GraphQLExtension<ExtensionsService>;
+
+export { type AdditionalField, type AnalyzerExtensionConfig, type AnalyzerOutput, AuthorizationError, ExtensionsService, FieldComplexityMap, GraphQLError, GraphQLExtension, GraphQLRequestContext, type GroupedLoaderDef, Loader, type LoaderDef, type LoaderInstances, LoaderRegistry, MissingResolverContextError, NotFoundError, ResolverContext, type ResolverContextSlot, ResolverContextStore, type SingleLoaderDef, ValidationError, createAnalyzerExtension, get, getOption, getOrElse, has, make, makeRequestContextLayer, makeStoreLayer, scoped, set, setMany, storeLayer, toGraphQLArgs, toGraphQLInputType, toGraphQLObjectType, toGraphQLType };