Effect GraphQL

A GraphQL framework for Effect-TS that brings full type safety, composability, and functional programming to your GraphQL servers.

Note: This is an experimental prototype exploring the integration between Effect Schema, Effect's service system, and GraphQL.

Features

• Type-Safe End-to-End - Define schemas once with Effect Schema, get TypeScript types and GraphQL types automatically
• Effect-Powered Resolvers - Resolvers are Effect programs with built-in error handling and service injection
• Immutable Builder - Fluent, pipe-able API for composing schemas from reusable parts
• Service Integration - Use Effect's Layer system for dependency injection

Getting Started

The easiest way to get started is with the CLI:

# Create a new project
npx @effect-gql/cli create my-api --server-type node

# Start the dev server
cd my-api
npm run dev

Your GraphQL server will be running at http://localhost:4000/graphql with a GraphiQL playground at http://localhost:4000/graphiql.

Server Types

The CLI supports multiple server runtimes:

| Type | Command | Best For | |------|---------|----------| | Node.js | --server-type node | General Node.js deployments | | Bun | --server-type bun | Bun runtime with native WebSocket support | | Express | --server-type express | Integrating into existing Express apps | | Web | --server-type web | Cloudflare Workers, Deno, edge runtimes |

Manual Installation

npm install @effect-gql/core effect graphql

Quick Start

import { Effect, Layer } from "effect"
import * as S from "effect/Schema"
import { GraphQLSchemaBuilder, execute } from "@effect-gql/core"

// Define your schema with Effect Schema
const UserSchema = S.Struct({
  id: S.String,
  name: S.String,
  email: S.String,
})

// Build your GraphQL schema
const schema = GraphQLSchemaBuilder.empty
  .objectType({ name: "User", schema: UserSchema })
  .query("users", {
    type: S.Array(UserSchema),
    resolve: () => Effect.succeed([
      { id: "1", name: "Alice", email: "[email protected]" },
      { id: "2", name: "Bob", email: "[email protected]" },
    ]),
  })
  .query("user", {
    type: UserSchema,
    args: S.Struct({ id: S.String }),
    resolve: (args) => Effect.succeed({
      id: args.id,
      name: "Alice",
      email: "[email protected]",
    }),
  })
  .buildSchema()

// Execute a query
const result = await Effect.runPromise(
  execute(schema, Layer.empty)(`
    query {
      users { id name email }
    }
  `)
)

Documentation

For full documentation, guides, and API reference, visit the documentation site.

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Development mode with watch
npm run dev

Contributing

Contributions are welcome! Here's how you can help:

1. Report bugs - Open an issue describing the problem and steps to reproduce
2. Suggest features - Open an issue describing your idea
3. Submit PRs - Fork the repo, make your changes, and open a pull request

Please ensure your code:

• Passes all existing tests (npm test)
• Includes tests for new functionality
• Follows the existing code style

License

MIT