@effect-gql/federation 0.1.0 → 1.0.0

package/index.d.ts

@@ -0,0 +1,577 @@
+import * as effect from 'effect';
+import { Effect, Pipeable } from 'effect';
+import * as S from 'effect/Schema';
+import * as _effect_gql_core from '@effect-gql/core';
+import { GraphQLSchemaBuilder, DirectiveApplication, GraphQLSchema, GraphQLScalarType } from '@effect-gql/core';
+import * as graphql from 'graphql';
+
+/**
+ * Configuration for a @key directive
+ */
+interface KeyDirective {
+    /** FieldSet selection string (e.g., "id" or "sku package") */
+    readonly fields: string;
+    /** Whether this key can be used to resolve the entity. Default: true */
+    readonly resolvable?: boolean;
+}
+/**
+ * All Federation 2.x directive types
+ */
+type FederationDirective = {
+    readonly _tag: "key";
+    readonly fields: string;
+    readonly resolvable?: boolean;
+} | {
+    readonly _tag: "external";
+} | {
+    readonly _tag: "requires";
+    readonly fields: string;
+} | {
+    readonly _tag: "provides";
+    readonly fields: string;
+} | {
+    readonly _tag: "shareable";
+} | {
+    readonly _tag: "inaccessible";
+} | {
+    readonly _tag: "override";
+    readonly from: string;
+    readonly label?: string;
+} | {
+    readonly _tag: "interfaceObject";
+} | {
+    readonly _tag: "tag";
+    readonly name: string;
+};
+/**
+ * Entity representation sent to _entities query
+ * Contains __typename plus the key fields
+ */
+interface EntityRepresentation {
+    readonly __typename: string;
+    readonly [key: string]: unknown;
+}
+/**
+ * Configuration for registering an entity type
+ */
+interface EntityRegistration<A, R = never> {
+    /** Type name */
+    readonly name: string;
+    /** Effect Schema for the entity type */
+    readonly schema: S.Schema<A, any, any>;
+    /** Key directive configurations (at least one required) */
+    readonly keys: readonly KeyDirective[];
+    /** Additional directives to apply to the type */
+    readonly directives?: readonly FederationDirective[];
+    /**
+     * Reference resolver - given key fields, return the full entity.
+     * The representation contains __typename plus all fields from any matching @key.
+     */
+    readonly resolveReference: (representation: Partial<A> & {
+        __typename: string;
+    }) => Effect.Effect<A | null, any, R>;
+}
+/**
+ * Configuration for the FederatedSchemaBuilder
+ */
+interface FederatedSchemaConfig {
+    /** Federation specification version (default: "2.3") */
+    readonly version?: string;
+}
+/**
+ * Result of building a federated schema
+ */
+interface FederatedSchemaResult {
+    /** The GraphQL schema with Federation queries */
+    readonly schema: graphql.GraphQLSchema;
+    /** The Federation-compliant SDL with directive annotations */
+    readonly sdl: string;
+}
+/**
+ * Convert a FederationDirective to a DirectiveApplication
+ */
+declare function toDirectiveApplication(directive: FederationDirective): _effect_gql_core.DirectiveApplication;
+
+/**
+ * Federation-aware schema builder that extends the core GraphQLSchemaBuilder
+ * with Apollo Federation 2.x support.
+ *
+ * @example
+ * ```typescript
+ * const schema = FederatedSchemaBuilder.empty
+ *   .pipe(
+ *     entity({
+ *       name: "User",
+ *       schema: UserSchema,
+ *       keys: [key({ fields: "id" })],
+ *       resolveReference: (ref) => UserService.findById(ref.id),
+ *     }),
+ *     query("me", {
+ *       type: UserSchema,
+ *       resolve: () => UserService.getCurrentUser(),
+ *     }),
+ *   )
+ *   .buildFederatedSchema()
+ * ```
+ */
+declare class FederatedSchemaBuilder<R = never> implements Pipeable.Pipeable {
+    private readonly state;
+    private constructor();
+    /**
+     * Pipeable interface implementation
+     */
+    pipe<A>(this: A): A;
+    pipe<A, B>(this: A, ab: (a: A) => B): B;
+    pipe<A, B, C>(this: A, ab: (a: A) => B, bc: (b: B) => C): C;
+    pipe<A, B, C, D>(this: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D): D;
+    pipe<A, B, C, D, E>(this: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E): E;
+    pipe<A, B, C, D, E, F>(this: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F): F;
+    /**
+     * Create an empty federated schema builder
+     */
+    static empty: FederatedSchemaBuilder<never>;
+    /**
+     * Create a builder with custom configuration
+     */
+    static create(config?: FederatedSchemaConfig): FederatedSchemaBuilder<never>;
+    /**
+     * Create a new builder with updated state
+     */
+    private with;
+    /**
+     * Get the underlying core builder for advanced usage
+     */
+    get coreBuilder(): GraphQLSchemaBuilder<R>;
+    /**
+     * 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<A, R2>(config: EntityRegistration<A, R2>): FederatedSchemaBuilder<R | R2>;
+    /**
+     * Add a query field
+     */
+    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[];
+        resolve: (args: Args) => Effect.Effect<A, E, R2>;
+    }): FederatedSchemaBuilder<R | R2>;
+    /**
+     * Add a mutation field
+     */
+    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[];
+        resolve: (args: Args) => Effect.Effect<A, E, R2>;
+    }): FederatedSchemaBuilder<R | R2>;
+    /**
+     * Add a subscription field
+     */
+    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[];
+        subscribe: (args: Args) => Effect.Effect<effect.Stream.Stream<A, E, R2>, E, R2>;
+        resolve?: (value: A, args: Args) => Effect.Effect<A, E, R2>;
+    }): FederatedSchemaBuilder<R | R2>;
+    /**
+     * Register an object type (non-entity)
+     */
+    objectType<A, R2 = never>(config: {
+        name?: string;
+        schema: S.Schema<A, any, any>;
+        implements?: readonly string[];
+        directives?: readonly DirectiveApplication[];
+    }): FederatedSchemaBuilder<R | R2>;
+    /**
+     * Register an interface type
+     */
+    interfaceType(config: {
+        name?: string;
+        schema: S.Schema<any, any, any>;
+        resolveType?: (value: any) => string;
+        directives?: readonly DirectiveApplication[];
+    }): FederatedSchemaBuilder<R>;
+    /**
+     * Register an enum type
+     */
+    enumType(config: {
+        name: string;
+        values: readonly string[];
+        description?: string;
+        directives?: readonly DirectiveApplication[];
+    }): FederatedSchemaBuilder<R>;
+    /**
+     * Register a union type
+     */
+    unionType(config: {
+        name: string;
+        types: readonly string[];
+        resolveType?: (value: any) => string;
+        directives?: readonly DirectiveApplication[];
+    }): FederatedSchemaBuilder<R>;
+    /**
+     * Register an input type
+     */
+    inputType(config: {
+        name?: string;
+        schema: S.Schema<any, any, any>;
+        description?: string;
+        directives?: readonly DirectiveApplication[];
+    }): FederatedSchemaBuilder<R>;
+    /**
+     * Add a computed/relational field to an object type
+     */
+    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[];
+        resolve: (parent: Parent, args: Args) => Effect.Effect<A, E, R2>;
+    }): FederatedSchemaBuilder<R | R2>;
+    /**
+     * Build the federated GraphQL schema with _entities and _service queries.
+     *
+     * Returns both the executable schema and the Federation-compliant SDL.
+     */
+    buildFederatedSchema(): FederatedSchemaResult;
+    /**
+     * Check if the core builder has any query fields registered
+     */
+    private hasQueryFields;
+    /**
+     * Build a standard (non-federated) schema.
+     * Useful for testing or running without a gateway.
+     */
+    buildSchema(): GraphQLSchema;
+    /**
+     * Generate Federation-compliant SDL with directive annotations.
+     */
+    private generateFederatedSDL;
+    /**
+     * Annotate SDL types with their federation directives from extensions.
+     */
+    private annotateSDLWithDirectives;
+}
+
+/**
+ * Create a @key directive for entity identification
+ *
+ * @example
+ * ```typescript
+ * entity({
+ *   name: "User",
+ *   schema: UserSchema,
+ *   keys: [key({ fields: "id" })],
+ *   resolveReference: (ref) => UserService.findById(ref.id),
+ * })
+ * ```
+ */
+declare const key: (config: KeyDirective) => FederationDirective;
+/**
+ * Create a @shareable directive
+ * Marks a type or field as resolvable by multiple subgraphs
+ *
+ * @example
+ * ```typescript
+ * entity({
+ *   name: "Product",
+ *   schema: ProductSchema,
+ *   keys: [key({ fields: "id" })],
+ *   directives: [shareable()],
+ * })
+ * ```
+ */
+declare const shareable: () => FederationDirective;
+/**
+ * Create an @inaccessible directive
+ * Omits the type/field from the public API while keeping it available for federation
+ *
+ * @example
+ * ```typescript
+ * objectType({
+ *   name: "InternalMetadata",
+ *   schema: MetadataSchema,
+ *   directives: [inaccessible()],
+ * })
+ * ```
+ */
+declare const inaccessible: () => FederationDirective;
+/**
+ * Create an @interfaceObject directive
+ * Indicates this object represents an interface from another subgraph
+ *
+ * @example
+ * ```typescript
+ * objectType({
+ *   name: "Media",
+ *   schema: MediaSchema,
+ *   directives: [interfaceObject()],
+ * })
+ * ```
+ */
+declare const interfaceObject: () => FederationDirective;
+/**
+ * Create a @tag directive for metadata annotation
+ *
+ * @example
+ * ```typescript
+ * entity({
+ *   name: "Product",
+ *   schema: ProductSchema,
+ *   keys: [key({ fields: "id" })],
+ *   directives: [tag("public"), tag("catalog")],
+ * })
+ * ```
+ */
+declare const tag: (name: string) => FederationDirective;
+/**
+ * Create an @external directive
+ * Marks a field as defined in another subgraph
+ *
+ * @example
+ * ```typescript
+ * field("User", "externalId", {
+ *   type: S.String,
+ *   directives: [external()],
+ *   resolve: (parent) => parent.externalId,
+ * })
+ * ```
+ */
+declare const external: () => FederationDirective;
+/**
+ * Create a @requires directive
+ * Specifies fields that must be fetched from other subgraphs before this field can be resolved
+ *
+ * @example
+ * ```typescript
+ * field("Product", "shippingEstimate", {
+ *   type: S.Int,
+ *   directives: [requires({ fields: "weight dimensions { height width }" })],
+ *   resolve: (product) => calculateShipping(product.weight, product.dimensions),
+ * })
+ * ```
+ */
+declare const requires: (config: {
+    fields: string;
+}) => FederationDirective;
+/**
+ * Create a @provides directive
+ * Router optimization hint - indicates this field provides additional fields on the returned type
+ *
+ * @example
+ * ```typescript
+ * field("Review", "author", {
+ *   type: UserSchema,
+ *   directives: [provides({ fields: "name email" })],
+ *   resolve: (review) => UserService.findById(review.authorId),
+ * })
+ * ```
+ */
+declare const provides: (config: {
+    fields: string;
+}) => FederationDirective;
+/**
+ * Create an @override directive
+ * Transfers resolution responsibility from another subgraph
+ *
+ * @example
+ * ```typescript
+ * field("Product", "price", {
+ *   type: S.Number,
+ *   directives: [override({ from: "legacy-pricing" })],
+ *   resolve: (product) => PricingService.getPrice(product.id),
+ * })
+ * ```
+ */
+declare const override: (config: {
+    from: string;
+    label?: string;
+}) => FederationDirective;
+
+/**
+ * Register an entity type with @key directive(s) and reference resolver.
+ *
+ * @example
+ * ```typescript
+ * FederatedSchemaBuilder.empty.pipe(
+ *   entity({
+ *     name: "User",
+ *     schema: UserSchema,
+ *     keys: [key({ fields: "id" })],
+ *     resolveReference: (ref) => UserService.findById(ref.id),
+ *   }),
+ * )
+ * ```
+ */
+declare const entity: <A, R>(config: EntityRegistration<A, R>) => <R2>(builder: FederatedSchemaBuilder<R2>) => FederatedSchemaBuilder<R | R2>;
+/**
+ * Add a query field
+ */
+declare const query: <A, E, R, Args = void>(name: string, config: {
+    type: S.Schema<A, any, any>;
+    args?: S.Schema<Args, any, any>;
+    description?: string;
+    directives?: readonly DirectiveApplication[];
+    resolve: (args: Args) => Effect.Effect<A, E, R>;
+}) => <R2>(builder: FederatedSchemaBuilder<R2>) => FederatedSchemaBuilder<R | R2>;
+/**
+ * Add a mutation field
+ */
+declare const mutation: <A, E, R, Args = void>(name: string, config: {
+    type: S.Schema<A, any, any>;
+    args?: S.Schema<Args, any, any>;
+    description?: string;
+    directives?: readonly DirectiveApplication[];
+    resolve: (args: Args) => Effect.Effect<A, E, R>;
+}) => <R2>(builder: FederatedSchemaBuilder<R2>) => FederatedSchemaBuilder<R | R2>;
+/**
+ * Add a subscription field
+ */
+declare const subscription: <A, E, R, Args = void>(name: string, config: {
+    type: S.Schema<A, any, any>;
+    args?: S.Schema<Args, any, any>;
+    description?: string;
+    directives?: readonly DirectiveApplication[];
+    subscribe: (args: Args) => Effect.Effect<effect.Stream.Stream<A, E, R>, E, R>;
+    resolve?: (value: A, args: Args) => Effect.Effect<A, E, R>;
+}) => <R2>(builder: FederatedSchemaBuilder<R2>) => FederatedSchemaBuilder<R | R2>;
+/**
+ * Register an object type (non-entity)
+ */
+declare const objectType: <A>(config: {
+    name?: string;
+    schema: S.Schema<A, any, any>;
+    implements?: readonly string[];
+    directives?: readonly DirectiveApplication[];
+}) => <R>(builder: FederatedSchemaBuilder<R>) => FederatedSchemaBuilder<R>;
+/**
+ * Register an interface type
+ */
+declare const interfaceType: (config: {
+    name?: string;
+    schema: S.Schema<any, any, any>;
+    resolveType?: (value: any) => string;
+    directives?: readonly DirectiveApplication[];
+}) => <R>(builder: FederatedSchemaBuilder<R>) => FederatedSchemaBuilder<R>;
+/**
+ * Register an enum type
+ */
+declare const enumType: (config: {
+    name: string;
+    values: readonly string[];
+    description?: string;
+    directives?: readonly DirectiveApplication[];
+}) => <R>(builder: FederatedSchemaBuilder<R>) => FederatedSchemaBuilder<R>;
+/**
+ * Register a union type
+ */
+declare const unionType: (config: {
+    name: string;
+    types: readonly string[];
+    resolveType?: (value: any) => string;
+    directives?: readonly DirectiveApplication[];
+}) => <R>(builder: FederatedSchemaBuilder<R>) => FederatedSchemaBuilder<R>;
+/**
+ * Register an input type
+ */
+declare const inputType: (config: {
+    name?: string;
+    schema: S.Schema<any, any, any>;
+    description?: string;
+    directives?: readonly DirectiveApplication[];
+}) => <R>(builder: FederatedSchemaBuilder<R>) => FederatedSchemaBuilder<R>;
+/**
+ * Add a computed/relational field to an object type
+ */
+declare const field: <Parent, A, E, R, Args = void>(typeName: string, fieldName: string, config: {
+    type: S.Schema<A, any, any>;
+    args?: S.Schema<Args, any, any>;
+    description?: string;
+    directives?: readonly DirectiveApplication[];
+    resolve: (parent: Parent, args: Args) => Effect.Effect<A, E, R>;
+}) => <R2>(builder: FederatedSchemaBuilder<R2>) => FederatedSchemaBuilder<R | R2>;
+/**
+ * Create a field configuration with @external directive
+ */
+declare const externalField: <A>(config: {
+    type: S.Schema<A, any, any>;
+    description?: string;
+}) => {
+    type: S.Schema<A, any, any>;
+    description?: string;
+    directives: readonly DirectiveApplication[];
+    resolve: (parent: any) => Effect.Effect<A, never, never>;
+};
+/**
+ * Create a field configuration with @requires directive
+ */
+declare const requiresField: <A, E, R, Parent = any>(config: {
+    type: S.Schema<A, any, any>;
+    fields: string;
+    description?: string;
+    resolve: (parent: Parent) => Effect.Effect<A, E, R>;
+}) => {
+    type: S.Schema<A, any, any>;
+    description?: string;
+    directives: readonly DirectiveApplication[];
+    resolve: (parent: Parent) => Effect.Effect<A, E, R>;
+};
+/**
+ * Create a field configuration with @provides directive
+ */
+declare const providesField: <A, E, R, Parent = any>(config: {
+    type: S.Schema<A, any, any>;
+    fields: string;
+    description?: string;
+    resolve: (parent: Parent) => Effect.Effect<A, E, R>;
+}) => {
+    type: S.Schema<A, any, any>;
+    description?: string;
+    directives: readonly DirectiveApplication[];
+    resolve: (parent: Parent) => Effect.Effect<A, E, R>;
+};
+/**
+ * Create a field configuration with @override directive
+ */
+declare const overrideField: <A, E, R, Parent = any>(config: {
+    type: S.Schema<A, any, any>;
+    from: string;
+    label?: string;
+    description?: string;
+    resolve: (parent: Parent) => Effect.Effect<A, E, R>;
+}) => {
+    type: S.Schema<A, any, any>;
+    description?: string;
+    directives: readonly DirectiveApplication[];
+    resolve: (parent: Parent) => Effect.Effect<A, E, R>;
+};
+
+/**
+ * The _Any scalar is used for entity representations in the _entities query.
+ * It accepts any JSON value representing an entity with __typename and key fields.
+ */
+declare const AnyScalar: GraphQLScalarType<unknown, unknown>;
+/**
+ * The _FieldSet scalar represents a selection of fields.
+ * It's used in directive arguments like @key(fields: "id") and @requires(fields: "weight").
+ */
+declare const FieldSetScalar: GraphQLScalarType<unknown, unknown>;
+
+export { AnyScalar, type EntityRegistration, type EntityRepresentation, FederatedSchemaBuilder, type FederatedSchemaConfig, type FederatedSchemaResult, type FederationDirective, FieldSetScalar, type KeyDirective, entity, enumType, external, externalField, field, inaccessible, inputType, interfaceObject, interfaceType, key, mutation, objectType, override, overrideField, provides, providesField, query, requires, requiresField, shareable, subscription, tag, toDirectiveApplication, unionType };