Federation Types

/**
 * _Any scalar for entity representations
 * Used in _entities field for federation entity resolution
 */
const AnyType: GraphQLScalarType;

// GraphQL usage: _Any
// Purpose: Represents entity representations in _entities queries

/**
 * link__Import scalar for federation imports
 * Used in @link directive import argument
 */
const LinkImportType: GraphQLScalarType;

// GraphQL usage: link__Import
// Purpose: Specifies imported items in @link directive

# _Any used in federation infrastructure
type Query {
  _entities(representations: [_Any!]!): [_Entity]!
}

# link__Import used in schema linking
extend schema @link(
  url: "https://specs.apollo.dev/federation/v2.0",
  import: [link__Import]
)

/**
 * _Service type for subgraph introspection
 * Provides SDL representation of service capabilities
 */
const ServiceType: GraphQLObjectType;

// GraphQL definition:
// type _Service {
//   sdl: String
// }

// Automatically added to Query type by buildSubgraphSchema
const schema = buildSubgraphSchema(typeDefs);
// Results in:
// type Query {
//   _service: _Service!
//   # ... other fields
// }

/**
 * _Entity union of all federated entities
 * Dynamically includes all types with @key directive
 */
const EntityType: GraphQLUnionType;

// GraphQL usage: _Entity
// Dynamically becomes: union _Entity = User | Product | Order

# Automatically generated based on @key types
type User @key(fields: "id") {
  id: ID!
  name: String!
}

type Product @key(fields: "id") {
  id: ID!
  title: String!
}

# Results in:
# union _Entity = User | Product

/**
 * Configuration for _entities federation field
 * Handles entity resolution from representations
 */
const entitiesField: GraphQLFieldConfig<any, any>;

// GraphQL signature:
// _entities(representations: [_Any!]!): [_Entity]!

/**
 * Configuration for _service federation field
 * Provides SDL introspection for gateway
 */
const serviceField: GraphQLFieldConfig<any, any>;

// GraphQL signature:
// _service: _Service!

import { entitiesField, serviceField } from "@apollo/subgraph";

// These are automatically added by buildSubgraphSchema
const queryType = new GraphQLObjectType({
  name: 'Query',
  fields: {
    // Your fields
    hello: { type: GraphQLString, resolve: () => "Hello!" },
    
    // Federation fields (added automatically)
    _entities: entitiesField,
    _service: serviceField
  }
});

/**
 * Resolves federated entities from representations
 * @param params - Entity resolution parameters
 * @returns Array of resolved entity objects
 */
function entitiesResolver(params: {
  representations: any;
  context: any;
  info: GraphQLResolveInfo;
}): any[];

import { entitiesResolver } from "@apollo/subgraph";

// Typically used internally by buildSubgraphSchema
// Manual usage for custom entity resolution:
const resolvedEntities = entitiesResolver({
  representations: [
    { __typename: 'User', id: '1' },
    { __typename: 'Product', id: '123' }
  ],
  context: requestContext,
  info: graphqlResolveInfo
});

const resolvers = {
  User: {
    // Called when User entity needs resolution
    __resolveReference: async (representation, context, info) => {
      // representation: { __typename: 'User', id: '123' }
      const user = await context.dataSources.users.findById(representation.id);
      return user;
    }
  },
  
  // Interface entity resolution
  Node: {
    __resolveReference: async (representation, context, info) => {
      // Handle interface entity resolution
      const entity = await resolveNodeById(representation.id);
      return entity;
    },
    __resolveType: (obj) => {
      // Return concrete type name
      return obj.__typename;
    }
  }
};

/**
 * Array of all federation-specific GraphQL types
 */
const federationTypes: GraphQLNamedType[];

/**
 * Checks if a type is federation-specific
 * @param type - GraphQL type to check  
 * @returns True if type is federation infrastructure
 */
function isFederationType(type: GraphQLType): boolean;

import { federationTypes, isFederationType } from "@apollo/subgraph";

// Access all federation types
federationTypes.forEach(type => {
  console.log(`Federation type: ${type.name}`);
});
// Output: _Service, _Any, _Entity, link__Import

// Check if type is federation-specific
const userType = schema.getType('User');
const entityType = schema.getType('_Entity');

console.log(isFederationType(userType));   // false
console.log(isFederationType(entityType)); // true

/**
 * Utility type for nullable values
 */
type Maybe<T> = null | undefined | T;

import { Maybe } from "@apollo/subgraph";

// Function that might return a user or null
function findUser(id: string): Maybe<User> {
  return users.find(u => u.id === id) || null;
}

// Interface entity definition
interface Node @key(fields: "id") {
  id: ID!
}

type User implements Node @key(fields: "id") {
  id: ID!
  name: String!
}

// Resolver implementation
const resolvers = {
  Node: {
    __resolveReference: async (representation, context, info) => {
      // Interface-level resolution
      return await resolveNodeById(representation.id);
    },
    __resolveType: (obj, context, info) => {
      // Determine concrete type at runtime
      return obj.__typename || 'User';
    }
  },
  User: {
    __resolveReference: async (representation, context, info) => {
      // Type-specific resolution if needed
      return await context.dataSources.users.findById(representation.id);
    }
  }
};

import { maybeCacheControlFromInfo } from '@apollo/cache-control-types';

// Cache control is automatically handled in entitiesResolver
// Custom cache control in entity resolvers:
const resolvers = {
  Product: {
    __resolveReference: (representation, context, info) => {
      // Cache control applied automatically based on type directives
      return fetchProduct(representation.id);
    }
  }
};

const resolvers = {
  User: {
    __resolveReference: async (representation, context, info) => {
      try {
        const user = await context.dataSources.users.findById(representation.id);
        if (!user) {
          throw new Error(`User with id ${representation.id} not found`);
        }
        return user;
      } catch (error) {
        // Log error and re-throw for proper federation error handling
        console.error('Entity resolution failed:', error);
        throw error;
      }
    }
  }
};

/**
 * Reference resolver function type
 */
type GraphQLReferenceResolver<TContext> = (
  reference: object,
  context: TContext,
  info: GraphQLResolveInfo,
) => any;

/**
 * Extensions for GraphQL object types
 */
interface ApolloGraphQLObjectTypeExtensions<TSource = any, TContext = any> 
  extends GraphQLObjectTypeExtensions {
  apollo?: {
    subgraph?: {
      resolveReference?: GraphQLReferenceResolver<TContext>;
    };
  };
}

/**
 * Extensions for GraphQL interface types  
 */
interface ApolloGraphQLInterfaceTypeExtensions<TSource = any, TContext = any>
  extends GraphQLInterfaceTypeExtensions {
  apollo?: {
    subgraph?: {
      resolveReference?: GraphQLReferenceResolver<TContext>;
    };
  };
}