@effect-gql/core 0.1.0

package/src/builder/field-builders.ts

@@ -0,0 +1,322 @@
+import { Effect, Runtime, Stream, Queue, Fiber, Option } from "effect"
+import { GraphQLFieldConfig, GraphQLResolveInfo } from "graphql"
+import type {
+  FieldRegistration,
+  SubscriptionFieldRegistration,
+  ObjectFieldRegistration,
+  DirectiveRegistration,
+  MiddlewareRegistration,
+  MiddlewareContext,
+  GraphQLEffectContext,
+} from "./types"
+import {
+  toGraphQLTypeWithRegistry,
+  toGraphQLArgsWithRegistry,
+  type TypeConversionContext,
+  type InputTypeLookupCache,
+} from "./type-registry"
+
+/**
+ * Context needed for building fields
+ */
+export interface FieldBuilderContext extends TypeConversionContext {
+  directiveRegistrations: Map<string, DirectiveRegistration>
+  middlewares: readonly MiddlewareRegistration[]
+  inputTypeLookupCache?: InputTypeLookupCache
+}
+
+/**
+ * Apply directives to an Effect by wrapping it with directive transformers
+ */
+function applyDirectives<A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+  directives: readonly { name: string; args?: Record<string, unknown> }[] | undefined,
+  directiveRegistrations: Map<string, DirectiveRegistration>
+): Effect.Effect<A, E, any> {
+  if (!directives) return effect
+
+  let wrapped = effect
+  for (const directiveApp of directives) {
+    const directiveReg = directiveRegistrations.get(directiveApp.name)
+    if (directiveReg?.apply) {
+      wrapped = directiveReg.apply(directiveApp.args ?? {})(wrapped)
+    }
+  }
+  return wrapped
+}
+
+/**
+ * Apply middleware to an Effect by wrapping it with middleware transformers.
+ *
+ * Middleware executes in "onion" order - first registered middleware is the
+ * outermost layer, meaning it runs first before and last after the resolver.
+ *
+ * Each middleware can optionally specify a `match` predicate to filter which
+ * fields it applies to.
+ */
+function applyMiddleware<A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+  context: MiddlewareContext,
+  middlewares: readonly MiddlewareRegistration[]
+): Effect.Effect<A, E, any> {
+  if (middlewares.length === 0) return effect
+
+  let wrapped = effect
+
+  // Apply in reverse order so first registered is outermost
+  // (executes first before, last after)
+  for (let i = middlewares.length - 1; i >= 0; i--) {
+    const middleware = middlewares[i]
+
+    // Check if middleware should apply to this field
+    if (middleware.match && !middleware.match(context.info)) {
+      continue
+    }
+
+    wrapped = middleware.apply(wrapped, context)
+  }
+
+  return wrapped
+}
+
+/**
+ * Build a GraphQL field config from a field registration (for queries/mutations)
+ */
+export function buildField(
+  config: FieldRegistration,
+  ctx: FieldBuilderContext
+): GraphQLFieldConfig<any, any> {
+  const fieldConfig: GraphQLFieldConfig<any, any> = {
+    type: toGraphQLTypeWithRegistry(config.type, ctx),
+    resolve: async (
+      _parent,
+      args,
+      context: GraphQLEffectContext<any>,
+      info: GraphQLResolveInfo
+    ) => {
+      // Apply directives first (per-field, explicit)
+      let effect = applyDirectives(
+        config.resolve(args),
+        config.directives,
+        ctx.directiveRegistrations
+      )
+
+      // Apply middleware (global/pattern-matched)
+      const middlewareContext: MiddlewareContext = { parent: _parent, args, info }
+      effect = applyMiddleware(effect, middlewareContext, ctx.middlewares)
+
+      return await Runtime.runPromise(context.runtime)(effect)
+    },
+  }
+
+  if (config.args) {
+    fieldConfig.args = toGraphQLArgsWithRegistry(
+      config.args,
+      ctx.enumRegistry,
+      ctx.inputRegistry,
+      ctx.inputs,
+      ctx.enums,
+      ctx.inputTypeLookupCache
+    )
+  }
+  if (config.description) {
+    fieldConfig.description = config.description
+  }
+
+  return fieldConfig
+}
+
+/**
+ * Build a GraphQL field config for an object field (has parent param)
+ */
+export function buildObjectField(
+  config: ObjectFieldRegistration,
+  ctx: FieldBuilderContext
+): GraphQLFieldConfig<any, any> {
+  const fieldConfig: GraphQLFieldConfig<any, any> = {
+    type: toGraphQLTypeWithRegistry(config.type, ctx),
+    resolve: async (parent, args, context: GraphQLEffectContext<any>, info: GraphQLResolveInfo) => {
+      // Apply directives first (per-field, explicit)
+      let effect = applyDirectives(
+        config.resolve(parent, args),
+        config.directives,
+        ctx.directiveRegistrations
+      )
+
+      // Apply middleware (global/pattern-matched)
+      const middlewareContext: MiddlewareContext = { parent, args, info }
+      effect = applyMiddleware(effect, middlewareContext, ctx.middlewares)
+
+      return await Runtime.runPromise(context.runtime)(effect)
+    },
+  }
+
+  if (config.args) {
+    fieldConfig.args = toGraphQLArgsWithRegistry(
+      config.args,
+      ctx.enumRegistry,
+      ctx.inputRegistry,
+      ctx.inputs,
+      ctx.enums,
+      ctx.inputTypeLookupCache
+    )
+  }
+  if (config.description) {
+    fieldConfig.description = config.description
+  }
+
+  return fieldConfig
+}
+
+/**
+ * Build a GraphQL subscription field config.
+ *
+ * Subscriptions in GraphQL have a special structure:
+ * - `subscribe` returns an AsyncIterator that yields the "root value" for each event
+ * - `resolve` transforms each yielded value into the final result
+ *
+ * We convert Effect's Stream to an AsyncIterator using a Queue-based approach.
+ */
+export function buildSubscriptionField(
+  config: SubscriptionFieldRegistration,
+  ctx: FieldBuilderContext
+): GraphQLFieldConfig<any, any> {
+  const fieldConfig: GraphQLFieldConfig<any, any> = {
+    type: toGraphQLTypeWithRegistry(config.type, ctx),
+
+    // The subscribe function returns an AsyncIterator
+    subscribe: async (
+      _parent,
+      args,
+      context: GraphQLEffectContext<any>,
+      info: GraphQLResolveInfo
+    ) => {
+      // Get the Stream from the subscribe Effect
+      let subscribeEffect = config.subscribe(args)
+
+      // Apply directives to the subscribe effect
+      subscribeEffect = applyDirectives(
+        subscribeEffect,
+        config.directives,
+        ctx.directiveRegistrations
+      ) as any
+
+      // Apply middleware to the subscribe effect
+      const middlewareContext: MiddlewareContext = { parent: _parent, args, info }
+      subscribeEffect = applyMiddleware(subscribeEffect, middlewareContext, ctx.middlewares) as any
+
+      const stream = await Runtime.runPromise(context.runtime)(subscribeEffect)
+
+      // Convert Stream to AsyncIterator using queue-based approach
+      return streamToAsyncIterator(stream, context.runtime)
+    },
+
+    // The resolve function transforms each yielded value
+    // If no custom resolve is provided, return the payload directly
+    resolve: config.resolve
+      ? async (value, args, context: GraphQLEffectContext<any>, info: GraphQLResolveInfo) => {
+          let effect = config.resolve!(value, args)
+
+          // Apply middleware to the resolve effect
+          const middlewareContext: MiddlewareContext = { parent: value, args, info }
+          effect = applyMiddleware(effect, middlewareContext, ctx.middlewares)
+
+          return await Runtime.runPromise(context.runtime)(effect)
+        }
+      : (value) => value,
+  }
+
+  if (config.args) {
+    fieldConfig.args = toGraphQLArgsWithRegistry(
+      config.args,
+      ctx.enumRegistry,
+      ctx.inputRegistry,
+      ctx.inputs,
+      ctx.enums,
+      ctx.inputTypeLookupCache
+    )
+  }
+  if (config.description) {
+    fieldConfig.description = config.description
+  }
+
+  return fieldConfig
+}
+
+/**
+ * Convert an Effect Stream to an AsyncIterator using a Queue-based approach.
+ *
+ * This is needed because Stream.toAsyncIterable() requires R = never,
+ * but our streams may have service requirements that need to be provided
+ * by the runtime context.
+ */
+function streamToAsyncIterator<A, E, R>(
+  stream: Stream.Stream<A, E, R>,
+  runtime: Runtime.Runtime<R>
+): AsyncIterator<A> {
+  // Create the queue synchronously via runSync since unbounded queue creation is synchronous
+  let queue: Queue.Queue<Option.Option<A>>
+  let fiber: Fiber.RuntimeFiber<void, E>
+  let initialized = false
+  let done = false
+
+  const initialize = async () => {
+    if (initialized) return
+    initialized = true
+
+    queue = await Runtime.runPromise(runtime)(Queue.unbounded<Option.Option<A>>())
+
+    // Fork a fiber to run the stream and push values to the queue
+    fiber = Runtime.runFork(runtime)(
+      Effect.ensuring(
+        Stream.runForEach(stream, (value) => Queue.offer(queue, Option.some(value))),
+        // Signal completion by pushing None
+        Queue.offer(queue, Option.none())
+      )
+    )
+  }
+
+  return {
+    [Symbol.asyncIterator]() {
+      return this
+    },
+
+    async next(): Promise<IteratorResult<A>> {
+      await initialize()
+
+      if (done) {
+        return { done: true, value: undefined }
+      }
+
+      try {
+        const optionValue = await Runtime.runPromise(runtime)(Queue.take(queue))
+
+        if (Option.isNone(optionValue)) {
+          done = true
+          return { done: true, value: undefined }
+        }
+
+        return { done: false, value: optionValue.value }
+      } catch (error) {
+        done = true
+        throw error
+      }
+    },
+
+    async return(): Promise<IteratorResult<A>> {
+      // Cleanup - interrupt the fiber and shutdown the queue
+      done = true
+      if (initialized) {
+        try {
+          await Runtime.runPromise(runtime)(
+            Fiber.interrupt(fiber as unknown as Fiber.Fiber<any, any>)
+          )
+          await Runtime.runPromise(runtime)(Queue.shutdown(queue))
+        } catch {
+          // Ignore cleanup errors
+        }
+      }
+      return { done: true, value: undefined }
+    },
+  } as AsyncIterator<A>
+}

package/src/builder/index.ts

@@ -0,0 +1,48 @@
+// Re-export types
+export type {
+  FieldRegistration,
+  TypeRegistration,
+  InterfaceRegistration,
+  EnumRegistration,
+  UnionRegistration,
+  InputTypeRegistration,
+  DirectiveApplication,
+  DirectiveRegistration,
+  MiddlewareContext,
+  MiddlewareRegistration,
+  SubscriptionFieldRegistration,
+  ObjectFieldRegistration,
+  GraphQLEffectContext,
+  TypeRegistries,
+  CacheHint,
+  CacheControlScope,
+} from "./types"
+
+// Re-export DirectiveLocation for convenience
+export { DirectiveLocation } from "graphql"
+
+// Re-export schema builder
+export { GraphQLSchemaBuilder } from "./schema-builder"
+
+// Re-export pipe-able API
+export {
+  objectType,
+  interfaceType,
+  enumType,
+  unionType,
+  inputType,
+  directive,
+  middleware,
+  extension,
+  query,
+  mutation,
+  subscription,
+  field,
+  compose,
+} from "./pipe-api"
+
+// Re-export execute helper
+export { execute } from "./execute"
+
+// Re-export utilities that may be useful externally
+export { getSchemaName } from "./type-registry"

package/src/builder/pipe-api.ts

@@ -0,0 +1,312 @@
+import { Effect, Stream } from "effect"
+import * as S from "effect/Schema"
+import {
+  DirectiveLocation,
+  GraphQLResolveInfo,
+  DocumentNode,
+  ExecutionResult,
+  GraphQLError,
+} from "graphql"
+import type { DirectiveApplication, MiddlewareContext, CacheHint } from "./types"
+import type { ExecutionArgs } from "../extensions"
+import { GraphQLSchemaBuilder } from "./schema-builder"
+import type { FieldComplexity } from "../server/complexity"
+
+/**
+ * Add an object type to the schema builder (pipe-able)
+ * Name is optional if schema is TaggedStruct, TaggedClass, or Schema.Class
+ */
+export const 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?: FieldComplexity
+        cacheControl?: CacheHint
+        resolve: (parent: A, args: any) => Effect.Effect<any, any, any>
+      }
+    >
+  }) =>
+  <R>(builder: GraphQLSchemaBuilder<R>): GraphQLSchemaBuilder<R | R2> =>
+    builder.objectType(config)
+
+/**
+ * Add an interface type to the schema builder (pipe-able)
+ * Name is optional if schema is TaggedStruct, TaggedClass, or Schema.Class
+ */
+export const interfaceType =
+  (config: {
+    name?: string
+    schema: S.Schema<any, any, any>
+    resolveType?: (value: any) => string
+    directives?: readonly DirectiveApplication[]
+  }) =>
+  <R>(builder: GraphQLSchemaBuilder<R>): GraphQLSchemaBuilder<R> =>
+    builder.interfaceType(config)
+
+/**
+ * Add an enum type to the schema builder (pipe-able)
+ */
+export const enumType =
+  (config: {
+    name: string
+    values: readonly string[]
+    description?: string
+    directives?: readonly DirectiveApplication[]
+  }) =>
+  <R>(builder: GraphQLSchemaBuilder<R>): GraphQLSchemaBuilder<R> =>
+    builder.enumType(config)
+
+/**
+ * Add a union type to the schema builder (pipe-able)
+ */
+export const unionType =
+  (config: {
+    name: string
+    types: readonly string[]
+    resolveType?: (value: any) => string
+    directives?: readonly DirectiveApplication[]
+  }) =>
+  <R>(builder: GraphQLSchemaBuilder<R>): GraphQLSchemaBuilder<R> =>
+    builder.unionType(config)
+
+/**
+ * Add an input type to the schema builder (pipe-able)
+ * Name is optional if schema is TaggedStruct, TaggedClass, or Schema.Class
+ */
+export const inputType =
+  (config: {
+    name?: string
+    schema: S.Schema<any, any, any>
+    description?: string
+    directives?: readonly DirectiveApplication[]
+  }) =>
+  <R>(builder: GraphQLSchemaBuilder<R>): GraphQLSchemaBuilder<R> =>
+    builder.inputType(config)
+
+/**
+ * Register a directive (pipe-able)
+ *
+ * @param config - Directive configuration
+ * @param config.name - The directive name (without @)
+ * @param config.description - Optional description
+ * @param config.locations - Array of DirectiveLocation values where this directive can be applied
+ * @param config.args - Optional Effect Schema for directive arguments
+ * @param config.apply - Optional function to transform resolver Effects (for executable directives)
+ */
+export const 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>
+  }) =>
+  <R>(builder: GraphQLSchemaBuilder<R>): GraphQLSchemaBuilder<R | R2> =>
+    builder.directive(config)
+
+/**
+ * Register a middleware (pipe-able)
+ *
+ * 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
+ * GraphQLSchemaBuilder.empty.pipe(
+ *   middleware({
+ *     name: "logging",
+ *     apply: (effect, ctx) => Effect.gen(function*() {
+ *       yield* Effect.logInfo(`Resolving ${ctx.info.fieldName}`)
+ *       return yield* effect
+ *     })
+ *   }),
+ *   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 const 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>
+  }) =>
+  <R>(builder: GraphQLSchemaBuilder<R>): GraphQLSchemaBuilder<R | R2> =>
+    builder.middleware(config)
+
+/**
+ * Register an extension (pipe-able)
+ *
+ * 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
+ * GraphQLSchemaBuilder.empty.pipe(
+ *   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 const 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>
+  }) =>
+  <R>(builder: GraphQLSchemaBuilder<R>): GraphQLSchemaBuilder<R | R2> =>
+    builder.extension(config)
+
+/**
+ * Add a query field to the schema builder (pipe-able)
+ */
+export const 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?: FieldComplexity
+      cacheControl?: CacheHint
+      resolve: (args: Args) => Effect.Effect<A, E, R2>
+    }
+  ) =>
+  <R>(builder: GraphQLSchemaBuilder<R>): GraphQLSchemaBuilder<R | R2> =>
+    builder.query(name, config)
+
+/**
+ * Add a mutation field to the schema builder (pipe-able)
+ */
+export const 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?: FieldComplexity
+      resolve: (args: Args) => Effect.Effect<A, E, R2>
+    }
+  ) =>
+  <R>(builder: GraphQLSchemaBuilder<R>): GraphQLSchemaBuilder<R | R2> =>
+    builder.mutation(name, config)
+
+/**
+ * Add a subscription field to the schema builder (pipe-able)
+ *
+ * Subscriptions return a Stream that yields values over time.
+ *
+ * @example
+ * ```typescript
+ * GraphQLSchemaBuilder.empty.pipe(
+ *   subscription("userCreated", {
+ *     type: User,
+ *     subscribe: Effect.gen(function*() {
+ *       const pubsub = yield* PubSubService
+ *       return pubsub.subscribe("USER_CREATED")
+ *     }),
+ *   })
+ * )
+ * ```
+ */
+export const 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?: FieldComplexity
+      cacheControl?: CacheHint
+      subscribe: (args: Args) => Effect.Effect<Stream.Stream<A, E, R2>, E, R2>
+      resolve?: (value: A, args: Args) => Effect.Effect<A, E, R2>
+    }
+  ) =>
+  <R>(builder: GraphQLSchemaBuilder<R>): GraphQLSchemaBuilder<R | R2> =>
+    builder.subscription(name, config)
+
+/**
+ * Add a field to an existing object type (pipe-able)
+ */
+export const 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?: FieldComplexity
+      cacheControl?: CacheHint
+      resolve: (parent: Parent, args: Args) => Effect.Effect<A, E, R2>
+    }
+  ) =>
+  <R>(builder: GraphQLSchemaBuilder<R>): GraphQLSchemaBuilder<R | R2> =>
+    builder.field(typeName, fieldName, config)
+
+/**
+ * Compose multiple schema operations (helper for arrays)
+ */
+export const compose =
+  <R>(...operations: Array<(builder: GraphQLSchemaBuilder<any>) => GraphQLSchemaBuilder<any>>) =>
+  (builder: GraphQLSchemaBuilder<R>): GraphQLSchemaBuilder<any> =>
+    operations.reduce((b, op) => op(b), builder)