@effect-gql/federation 0.1.0 → 1.0.0

package/index.js

@@ -0,0 +1,570 @@
+import { Pipeable, Effect, Runtime } from 'effect';
+import * as S from 'effect/Schema';
+import { GraphQLScalarType, Kind, GraphQLSchemaBuilder, GraphQLNonNull, GraphQLList, GraphQLObjectType, GraphQLSchema, printSchema, GraphQLUnionType, GraphQLString } from '@effect-gql/core';
+
+// src/federated-builder.ts
+function parseLiteralToValue(ast) {
+  switch (ast.kind) {
+    case Kind.STRING:
+    case Kind.BOOLEAN:
+      return ast.value;
+    case Kind.INT:
+      return parseInt(ast.value, 10);
+    case Kind.FLOAT:
+      return parseFloat(ast.value);
+    case Kind.NULL:
+      return null;
+    case Kind.LIST:
+      return ast.values.map(parseLiteralToValue);
+    case 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 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 GraphQLScalarType({
+  name: "_FieldSet",
+  description: "A string representing a selection of fields.",
+  serialize: (value) => value,
+  parseValue: (value) => value,
+  parseLiteral: (ast) => {
+    if (ast.kind === 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 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.fail(new Error(`Unknown entity type: ${entityName}`));
+      }
+      return entity2.resolveReference(representation).pipe(
+        Effect.map((result) => {
+          if (result !== null && typeof result === "object") {
+            return { ...result, __typename: entityName };
+          }
+          return result;
+        }),
+        // Catch individual entity resolution errors and return null
+        Effect.catchAll(
+          (error) => Effect.logError(`Failed to resolve entity ${entityName}`, error).pipe(Effect.as(null))
+        )
+      );
+    });
+    return Runtime.runPromise(context.runtime)(Effect.all(effects, { concurrency: "unbounded" }));
+  };
+}
+function createServiceType() {
+  return new GraphQLObjectType({
+    name: "_Service",
+    description: "Provides SDL for the subgraph schema",
+    fields: {
+      sdl: {
+        type: 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 Pipeable.pipeArguments(this, arguments);
+  }
+  /**
+   * Create an empty federated schema builder
+   */
+  static empty = new _FederatedSchemaBuilder({
+    coreBuilder: GraphQLSchemaBuilder.empty,
+    entities: /* @__PURE__ */ new Map(),
+    version: "2.3"
+  });
+  /**
+   * Create a builder with custom configuration
+   */
+  static create(config = {}) {
+    return new _FederatedSchemaBuilder({
+      coreBuilder: 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.String,
+        resolve: () => 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 GraphQLNonNull(new GraphQLList(entityUnion)),
+        args: {
+          representations: {
+            type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(AnyScalar)))
+          }
+        },
+        resolve: createEntitiesResolver(this.state.entities)
+      };
+    }
+    const sdl = this.generateFederatedSDL(baseSchema, needsPlaceholder);
+    federationQueryFields._service = {
+      type: new GraphQLNonNull(serviceType),
+      resolve: createServiceResolver(sdl)
+    };
+    const baseQueryType = baseSchema.getQueryType();
+    const baseQueryFields = baseQueryType?.getFields() ?? {};
+    const queryType = new 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 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 = 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 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.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
+});
+
+export { AnyScalar, FederatedSchemaBuilder, FieldSetScalar, entity, enumType, external, externalField, field, inaccessible, inputType, interfaceObject, interfaceType, key, mutation, objectType, override, overrideField, provides, providesField, query, requires, requiresField, shareable, subscription, tag, toDirectiveApplication, unionType };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map