@effect-gql/federation 0.1.0 → 1.0.0

package/README.md

@@ -0,0 +1,100 @@
+# 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
+
+## Installation
+
+```bash
+npm install @effect-gql/core effect graphql
+```
+
+## Quick Start
+
+```typescript
+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: "alice@example.com" },
+      { id: "2", name: "Bob", email: "bob@example.com" },
+    ]),
+  })
+  .query("user", {
+    type: UserSchema,
+    args: S.Struct({ id: S.String }),
+    resolve: (args) => Effect.succeed({
+      id: args.id,
+      name: "Alice",
+      email: "alice@example.com",
+    }),
+  })
+  .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](https://nrf110.github.io/effect-gql/).
+
+## Development
+
+```bash
+# 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

package/index.cjs

@@ -0,0 +1,618 @@
+'use strict';
+
+var effect = require('effect');
+var S = require('effect/Schema');
+var core = require('@effect-gql/core');
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var S__namespace = /*#__PURE__*/_interopNamespace(S);
+
+// src/federated-builder.ts
+function parseLiteralToValue(ast) {
+  switch (ast.kind) {
+    case core.Kind.STRING:
+    case core.Kind.BOOLEAN:
+      return ast.value;
+    case core.Kind.INT:
+      return parseInt(ast.value, 10);
+    case core.Kind.FLOAT:
+      return parseFloat(ast.value);
+    case core.Kind.NULL:
+      return null;
+    case core.Kind.LIST:
+      return ast.values.map(parseLiteralToValue);
+    case core.Kind.OBJECT: {
+      const obj = {};
+      for (const field2 of ast.fields) {
+        obj[field2.name.value] = parseLiteralToValue(field2.value);
+      }
+      return obj;
+    }
+    default:
+      return void 0;
+  }
+}
+var AnyScalar = new core.GraphQLScalarType({
+  name: "_Any",
+  description: "The _Any scalar is used to pass representations of entities from external services.",
+  serialize: (value) => value,
+  parseValue: (value) => value,
+  parseLiteral: parseLiteralToValue
+});
+var FieldSetScalar = new core.GraphQLScalarType({
+  name: "_FieldSet",
+  description: "A string representing a selection of fields.",
+  serialize: (value) => value,
+  parseValue: (value) => value,
+  parseLiteral: (ast) => {
+    if (ast.kind === core.Kind.STRING) {
+      return ast.value;
+    }
+    return void 0;
+  }
+});
+function createEntityUnion(entities, typeRegistry) {
+  const types = Array.from(entities.keys()).map((name) => typeRegistry.get(name)).filter(Boolean);
+  if (types.length === 0) {
+    throw new Error("At least one entity must be registered to create _Entity union");
+  }
+  return new core.GraphQLUnionType({
+    name: "_Entity",
+    description: "Union of all types that have @key directives",
+    types: () => types,
+    resolveType: (value) => value.__typename
+  });
+}
+function createEntitiesResolver(entities) {
+  return async (_parent, args, context) => {
+    const effects = args.representations.map((representation) => {
+      const entityName = representation.__typename;
+      const entity2 = entities.get(entityName);
+      if (!entity2) {
+        return effect.Effect.fail(new Error(`Unknown entity type: ${entityName}`));
+      }
+      return entity2.resolveReference(representation).pipe(
+        effect.Effect.map((result) => {
+          if (result !== null && typeof result === "object") {
+            return { ...result, __typename: entityName };
+          }
+          return result;
+        }),
+        // Catch individual entity resolution errors and return null
+        effect.Effect.catchAll(
+          (error) => effect.Effect.logError(`Failed to resolve entity ${entityName}`, error).pipe(effect.Effect.as(null))
+        )
+      );
+    });
+    return effect.Runtime.runPromise(context.runtime)(effect.Effect.all(effects, { concurrency: "unbounded" }));
+  };
+}
+function createServiceType() {
+  return new core.GraphQLObjectType({
+    name: "_Service",
+    description: "Provides SDL for the subgraph schema",
+    fields: {
+      sdl: {
+        type: core.GraphQLString,
+        description: "The SDL representing the subgraph schema"
+      }
+    }
+  });
+}
+function createServiceResolver(sdl) {
+  return () => ({ sdl });
+}
+
+// src/types.ts
+function toDirectiveApplication(directive) {
+  switch (directive._tag) {
+    case "key":
+      return {
+        name: "key",
+        args: {
+          fields: directive.fields,
+          ...directive.resolvable !== void 0 ? { resolvable: directive.resolvable } : {}
+        }
+      };
+    case "external":
+      return { name: "external" };
+    case "requires":
+      return { name: "requires", args: { fields: directive.fields } };
+    case "provides":
+      return { name: "provides", args: { fields: directive.fields } };
+    case "shareable":
+      return { name: "shareable" };
+    case "inaccessible":
+      return { name: "inaccessible" };
+    case "override":
+      return {
+        name: "override",
+        args: {
+          from: directive.from,
+          ...directive.label !== void 0 ? { label: directive.label } : {}
+        }
+      };
+    case "interfaceObject":
+      return { name: "interfaceObject" };
+    case "tag":
+      return { name: "tag", args: { name: directive.name } };
+  }
+}
+
+// src/federated-builder.ts
+var FederatedSchemaBuilder = class _FederatedSchemaBuilder {
+  constructor(state) {
+    this.state = state;
+  }
+  pipe() {
+    return effect.Pipeable.pipeArguments(this, arguments);
+  }
+  /**
+   * Create an empty federated schema builder
+   */
+  static empty = new _FederatedSchemaBuilder({
+    coreBuilder: core.GraphQLSchemaBuilder.empty,
+    entities: /* @__PURE__ */ new Map(),
+    version: "2.3"
+  });
+  /**
+   * Create a builder with custom configuration
+   */
+  static create(config = {}) {
+    return new _FederatedSchemaBuilder({
+      coreBuilder: core.GraphQLSchemaBuilder.empty,
+      entities: /* @__PURE__ */ new Map(),
+      version: config.version ?? "2.3"
+    });
+  }
+  /**
+   * Create a new builder with updated state
+   */
+  with(updates) {
+    return new _FederatedSchemaBuilder({
+      ...this.state,
+      ...updates
+    });
+  }
+  /**
+   * Get the underlying core builder for advanced usage
+   */
+  get coreBuilder() {
+    return this.state.coreBuilder;
+  }
+  // ============================================================================
+  // Entity Registration
+  // ============================================================================
+  /**
+   * Register an entity type with @key directive(s) and reference resolver.
+   *
+   * Entities are the core building block of Apollo Federation. They represent
+   * types that can be resolved across subgraph boundaries using their key fields.
+   *
+   * @example
+   * ```typescript
+   * builder.entity({
+   *   name: "User",
+   *   schema: UserSchema,
+   *   keys: [key({ fields: "id" })],
+   *   resolveReference: (ref) => UserService.findById(ref.id),
+   * })
+   * ```
+   */
+  entity(config) {
+    const { name, schema, keys, directives } = config;
+    const typeDirectives = [
+      // Add @key directives
+      ...keys.map(
+        (k) => ({
+          name: "key",
+          args: {
+            fields: k.fields,
+            ...k.resolvable !== void 0 ? { resolvable: k.resolvable } : {}
+          }
+        })
+      ),
+      // Add additional directives
+      ...directives?.map(toDirectiveApplication) ?? []
+    ];
+    const newCoreBuilder = this.state.coreBuilder.objectType({
+      name,
+      schema,
+      directives: typeDirectives
+    });
+    const newEntities = new Map(this.state.entities);
+    newEntities.set(name, config);
+    return this.with({
+      coreBuilder: newCoreBuilder,
+      entities: newEntities
+    });
+  }
+  // ============================================================================
+  // Delegate to Core Builder
+  // ============================================================================
+  /**
+   * Add a query field
+   */
+  query(name, config) {
+    return this.with({
+      coreBuilder: this.state.coreBuilder.query(name, config)
+    });
+  }
+  /**
+   * Add a mutation field
+   */
+  mutation(name, config) {
+    return this.with({
+      coreBuilder: this.state.coreBuilder.mutation(name, config)
+    });
+  }
+  /**
+   * Add a subscription field
+   */
+  subscription(name, config) {
+    return this.with({
+      coreBuilder: this.state.coreBuilder.subscription(name, config)
+    });
+  }
+  /**
+   * Register an object type (non-entity)
+   */
+  objectType(config) {
+    return this.with({
+      coreBuilder: this.state.coreBuilder.objectType(config)
+    });
+  }
+  /**
+   * Register an interface type
+   */
+  interfaceType(config) {
+    return this.with({
+      coreBuilder: this.state.coreBuilder.interfaceType(config)
+    });
+  }
+  /**
+   * Register an enum type
+   */
+  enumType(config) {
+    return this.with({
+      coreBuilder: this.state.coreBuilder.enumType(config)
+    });
+  }
+  /**
+   * Register a union type
+   */
+  unionType(config) {
+    return this.with({
+      coreBuilder: this.state.coreBuilder.unionType(config)
+    });
+  }
+  /**
+   * Register an input type
+   */
+  inputType(config) {
+    return this.with({
+      coreBuilder: this.state.coreBuilder.inputType(config)
+    });
+  }
+  /**
+   * Add a computed/relational field to an object type
+   */
+  field(typeName, fieldName, config) {
+    return this.with({
+      coreBuilder: this.state.coreBuilder.field(
+        typeName,
+        fieldName,
+        config
+      )
+    });
+  }
+  // ============================================================================
+  // Schema Building
+  // ============================================================================
+  /**
+   * Build the federated GraphQL schema with _entities and _service queries.
+   *
+   * Returns both the executable schema and the Federation-compliant SDL.
+   */
+  buildFederatedSchema() {
+    let builderForSchema = this.state.coreBuilder;
+    const needsPlaceholder = !this.hasQueryFields();
+    if (needsPlaceholder) {
+      builderForSchema = builderForSchema.query("_placeholder", {
+        type: S__namespace.String,
+        resolve: () => effect.Effect.succeed("placeholder")
+      });
+    }
+    const baseSchema = builderForSchema.buildSchema();
+    const typeRegistry = /* @__PURE__ */ new Map();
+    const typeMap = baseSchema.getTypeMap();
+    for (const [name, type] of Object.entries(typeMap)) {
+      const isObjectType = type.constructor.name === "GraphQLObjectType";
+      if (isObjectType && !name.startsWith("__")) {
+        typeRegistry.set(name, type);
+      }
+    }
+    const entityUnion = this.state.entities.size > 0 ? createEntityUnion(this.state.entities, typeRegistry) : null;
+    const serviceType = createServiceType();
+    const federationQueryFields = {};
+    if (entityUnion) {
+      federationQueryFields._entities = {
+        type: new core.GraphQLNonNull(new core.GraphQLList(entityUnion)),
+        args: {
+          representations: {
+            type: new core.GraphQLNonNull(new core.GraphQLList(new core.GraphQLNonNull(AnyScalar)))
+          }
+        },
+        resolve: createEntitiesResolver(this.state.entities)
+      };
+    }
+    const sdl = this.generateFederatedSDL(baseSchema, needsPlaceholder);
+    federationQueryFields._service = {
+      type: new core.GraphQLNonNull(serviceType),
+      resolve: createServiceResolver(sdl)
+    };
+    const baseQueryType = baseSchema.getQueryType();
+    const baseQueryFields = baseQueryType?.getFields() ?? {};
+    const queryType = new core.GraphQLObjectType({
+      name: "Query",
+      fields: () => {
+        const fields = {};
+        for (const [name, field2] of Object.entries(baseQueryFields)) {
+          if (name === "_placeholder") continue;
+          fields[name] = {
+            type: field2.type,
+            args: field2.args.reduce(
+              (acc, arg) => {
+                acc[arg.name] = {
+                  type: arg.type,
+                  description: arg.description,
+                  defaultValue: arg.defaultValue
+                };
+                return acc;
+              },
+              {}
+            ),
+            description: field2.description,
+            resolve: field2.resolve,
+            extensions: field2.extensions
+          };
+        }
+        Object.assign(fields, federationQueryFields);
+        return fields;
+      }
+    });
+    const types = [AnyScalar, FieldSetScalar, serviceType];
+    if (entityUnion) {
+      types.push(entityUnion);
+    }
+    for (const [name, type] of Object.entries(typeMap)) {
+      if (!name.startsWith("__") && name !== "Query") {
+        types.push(type);
+      }
+    }
+    const schema = new core.GraphQLSchema({
+      query: queryType,
+      mutation: baseSchema.getMutationType() ?? void 0,
+      subscription: baseSchema.getSubscriptionType() ?? void 0,
+      types
+    });
+    return { schema, sdl };
+  }
+  /**
+   * Check if the core builder has any query fields registered
+   */
+  hasQueryFields() {
+    try {
+      const schema = this.state.coreBuilder.buildSchema();
+      const queryType = schema.getQueryType();
+      return queryType !== null && queryType !== void 0;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Build a standard (non-federated) schema.
+   * Useful for testing or running without a gateway.
+   */
+  buildSchema() {
+    return this.state.coreBuilder.buildSchema();
+  }
+  // ============================================================================
+  // SDL Generation
+  // ============================================================================
+  /**
+   * Generate Federation-compliant SDL with directive annotations.
+   */
+  generateFederatedSDL(schema, excludePlaceholder = false) {
+    const lines = [
+      `extend schema @link(url: "https://specs.apollo.dev/federation/v${this.state.version}", import: ["@key", "@shareable", "@external", "@requires", "@provides", "@override", "@inaccessible", "@interfaceObject", "@tag"])`,
+      ""
+    ];
+    let baseSDL = core.printSchema(schema);
+    if (excludePlaceholder) {
+      baseSDL = baseSDL.replace(/\s*_placeholder:\s*String\n?/g, "");
+    }
+    const annotatedSDL = this.annotateSDLWithDirectives(baseSDL, schema);
+    lines.push(annotatedSDL);
+    return lines.join("\n");
+  }
+  /**
+   * Annotate SDL types with their federation directives from extensions.
+   */
+  annotateSDLWithDirectives(sdl, schema) {
+    const typeMap = schema.getTypeMap();
+    let result = sdl;
+    for (const [typeName, type] of Object.entries(typeMap)) {
+      if (typeName.startsWith("__")) continue;
+      const directives = type.extensions?.directives;
+      if (!directives || directives.length === 0) continue;
+      const directiveStr = directives.map(formatDirective).join(" ");
+      const typePattern = new RegExp(
+        `(type\\s+${typeName}(?:\\s+implements\\s+[^{]+)?)(\\s*\\{)`,
+        "g"
+      );
+      result = result.replace(typePattern, `$1 ${directiveStr}$2`);
+      const interfacePattern = new RegExp(`(interface\\s+${typeName})(\\s*\\{)`, "g");
+      result = result.replace(interfacePattern, `$1 ${directiveStr}$2`);
+      const enumPattern = new RegExp(`(enum\\s+${typeName})(\\s*\\{)`, "g");
+      result = result.replace(enumPattern, `$1 ${directiveStr}$2`);
+      const unionPattern = new RegExp(`(union\\s+${typeName})(\\s*=)`, "g");
+      result = result.replace(unionPattern, `$1 ${directiveStr}$2`);
+      const inputPattern = new RegExp(`(input\\s+${typeName})(\\s*\\{)`, "g");
+      result = result.replace(inputPattern, `$1 ${directiveStr}$2`);
+    }
+    for (const [typeName, type] of Object.entries(typeMap)) {
+      if (typeName.startsWith("__")) continue;
+      if (!(type instanceof core.GraphQLObjectType)) continue;
+      const fields = type.getFields();
+      for (const [fieldName, field2] of Object.entries(fields)) {
+        const fieldDirectives = field2.extensions?.directives;
+        if (!fieldDirectives || fieldDirectives.length === 0) continue;
+        const directiveStr = fieldDirectives.map(formatDirective).join(" ");
+        const typeBlockPattern = new RegExp(
+          `(type\\s+${typeName}[^{]*\\{[\\s\\S]*?)(${fieldName}(?:\\([^)]*\\))?:\\s*[^\\n]+?)([\\n}])`,
+          "g"
+        );
+        result = result.replace(typeBlockPattern, `$1$2 ${directiveStr}$3`);
+      }
+    }
+    return result;
+  }
+};
+function formatDirective(directive) {
+  if (!directive.args || Object.keys(directive.args).length === 0) {
+    return `@${directive.name}`;
+  }
+  const args = Object.entries(directive.args).map(([key2, value]) => {
+    if (typeof value === "string") {
+      return `${key2}: "${value}"`;
+    }
+    return `${key2}: ${JSON.stringify(value)}`;
+  }).join(", ");
+  return `@${directive.name}(${args})`;
+}
+
+// src/directives.ts
+var key = (config) => ({
+  _tag: "key",
+  fields: config.fields,
+  resolvable: config.resolvable
+});
+var shareable = () => ({
+  _tag: "shareable"
+});
+var inaccessible = () => ({
+  _tag: "inaccessible"
+});
+var interfaceObject = () => ({
+  _tag: "interfaceObject"
+});
+var tag = (name) => ({
+  _tag: "tag",
+  name
+});
+var external = () => ({
+  _tag: "external"
+});
+var requires = (config) => ({
+  _tag: "requires",
+  fields: config.fields
+});
+var provides = (config) => ({
+  _tag: "provides",
+  fields: config.fields
+});
+var override = (config) => ({
+  _tag: "override",
+  from: config.from,
+  label: config.label
+});
+var entity = (config) => (builder) => builder.entity(config);
+var query = (name, config) => (builder) => builder.query(name, config);
+var mutation = (name, config) => (builder) => builder.mutation(name, config);
+var subscription = (name, config) => (builder) => builder.subscription(name, config);
+var objectType = (config) => (builder) => builder.objectType(config);
+var interfaceType = (config) => (builder) => builder.interfaceType(config);
+var enumType = (config) => (builder) => builder.enumType(config);
+var unionType = (config) => (builder) => builder.unionType(config);
+var inputType = (config) => (builder) => builder.inputType(config);
+var field = (typeName, fieldName, config) => (builder) => builder.field(typeName, fieldName, config);
+var externalField = (config) => ({
+  type: config.type,
+  description: config.description,
+  directives: [{ name: "external" }],
+  resolve: (parent) => effect.Effect.succeed(parent)
+});
+var requiresField = (config) => ({
+  type: config.type,
+  description: config.description,
+  directives: [{ name: "requires", args: { fields: config.fields } }],
+  resolve: config.resolve
+});
+var providesField = (config) => ({
+  type: config.type,
+  description: config.description,
+  directives: [{ name: "provides", args: { fields: config.fields } }],
+  resolve: config.resolve
+});
+var overrideField = (config) => ({
+  type: config.type,
+  description: config.description,
+  directives: [
+    {
+      name: "override",
+      args: {
+        from: config.from,
+        ...config.label !== void 0 ? { label: config.label } : {}
+      }
+    }
+  ],
+  resolve: config.resolve
+});
+
+exports.AnyScalar = AnyScalar;
+exports.FederatedSchemaBuilder = FederatedSchemaBuilder;
+exports.FieldSetScalar = FieldSetScalar;
+exports.entity = entity;
+exports.enumType = enumType;
+exports.external = external;
+exports.externalField = externalField;
+exports.field = field;
+exports.inaccessible = inaccessible;
+exports.inputType = inputType;
+exports.interfaceObject = interfaceObject;
+exports.interfaceType = interfaceType;
+exports.key = key;
+exports.mutation = mutation;
+exports.objectType = objectType;
+exports.override = override;
+exports.overrideField = overrideField;
+exports.provides = provides;
+exports.providesField = providesField;
+exports.query = query;
+exports.requires = requires;
+exports.requiresField = requiresField;
+exports.shareable = shareable;
+exports.subscription = subscription;
+exports.tag = tag;
+exports.toDirectiveApplication = toDirectiveApplication;
+exports.unionType = unionType;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map