@effect-gql/federation 0.1.0

package/src/directives.ts

@@ -0,0 +1,170 @@
+import type { FederationDirective, KeyDirective } from "./types"
+
+// ============================================================================
+// Type-Level Directive Factories
+// ============================================================================
+
+/**
+ * Create a @key directive for entity identification
+ *
+ * @example
+ * ```typescript
+ * entity({
+ *   name: "User",
+ *   schema: UserSchema,
+ *   keys: [key({ fields: "id" })],
+ *   resolveReference: (ref) => UserService.findById(ref.id),
+ * })
+ * ```
+ */
+export const key = (config: KeyDirective): FederationDirective => ({
+  _tag: "key",
+  fields: config.fields,
+  resolvable: config.resolvable,
+})
+
+/**
+ * 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()],
+ * })
+ * ```
+ */
+export const shareable = (): FederationDirective => ({
+  _tag: "shareable",
+})
+
+/**
+ * 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()],
+ * })
+ * ```
+ */
+export const inaccessible = (): FederationDirective => ({
+  _tag: "inaccessible",
+})
+
+/**
+ * Create an @interfaceObject directive
+ * Indicates this object represents an interface from another subgraph
+ *
+ * @example
+ * ```typescript
+ * objectType({
+ *   name: "Media",
+ *   schema: MediaSchema,
+ *   directives: [interfaceObject()],
+ * })
+ * ```
+ */
+export const interfaceObject = (): FederationDirective => ({
+  _tag: "interfaceObject",
+})
+
+/**
+ * Create a @tag directive for metadata annotation
+ *
+ * @example
+ * ```typescript
+ * entity({
+ *   name: "Product",
+ *   schema: ProductSchema,
+ *   keys: [key({ fields: "id" })],
+ *   directives: [tag("public"), tag("catalog")],
+ * })
+ * ```
+ */
+export const tag = (name: string): FederationDirective => ({
+  _tag: "tag",
+  name,
+})
+
+// ============================================================================
+// Field-Level Directive Factories
+// ============================================================================
+
+/**
+ * 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,
+ * })
+ * ```
+ */
+export const external = (): FederationDirective => ({
+  _tag: "external",
+})
+
+/**
+ * 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),
+ * })
+ * ```
+ */
+export const requires = (config: { fields: string }): FederationDirective => ({
+  _tag: "requires",
+  fields: config.fields,
+})
+
+/**
+ * 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),
+ * })
+ * ```
+ */
+export const provides = (config: { fields: string }): FederationDirective => ({
+  _tag: "provides",
+  fields: config.fields,
+})
+
+/**
+ * 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),
+ * })
+ * ```
+ */
+export const override = (config: { from: string; label?: string }): FederationDirective => ({
+  _tag: "override",
+  from: config.from,
+  label: config.label,
+})

package/src/entities.ts

@@ -0,0 +1,90 @@
+import { Effect, Runtime } from "effect"
+import { GraphQLObjectType, GraphQLUnionType, GraphQLString } from "@effect-gql/core"
+import type { EntityRegistration, EntityRepresentation } from "./types"
+
+/**
+ * Create the _Entity union type from registered entities
+ */
+export function createEntityUnion(
+  entities: Map<string, EntityRegistration<any, any>>,
+  typeRegistry: Map<string, GraphQLObjectType>
+): GraphQLUnionType {
+  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: any) => value.__typename,
+  })
+}
+
+/**
+ * Create the _entities resolver
+ *
+ * This resolver receives an array of representations (objects with __typename and key fields)
+ * and returns the corresponding entities by calling each entity's resolveReference function.
+ *
+ * Uses Effect.all with unbounded concurrency to resolve all entities in parallel.
+ */
+export function createEntitiesResolver<R>(entities: Map<string, EntityRegistration<any, R>>) {
+  return async (
+    _parent: any,
+    args: { representations: readonly EntityRepresentation[] },
+    context: { runtime: Runtime.Runtime<R> }
+  ): Promise<(any | null)[]> => {
+    const effects = args.representations.map((representation) => {
+      const entityName = representation.__typename
+      const entity = entities.get(entityName)
+
+      if (!entity) {
+        return Effect.fail(new Error(`Unknown entity type: ${entityName}`))
+      }
+
+      return entity.resolveReference(representation as any).pipe(
+        Effect.map((result) => {
+          // Add __typename to the result for union type resolution
+          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" }))
+  }
+}
+
+/**
+ * Create the _Service type for SDL introspection
+ */
+export function createServiceType(): GraphQLObjectType {
+  return new GraphQLObjectType({
+    name: "_Service",
+    description: "Provides SDL for the subgraph schema",
+    fields: {
+      sdl: {
+        type: GraphQLString,
+        description: "The SDL representing the subgraph schema",
+      },
+    },
+  })
+}
+
+/**
+ * Create the _service resolver
+ */
+export function createServiceResolver(sdl: string) {
+  return () => ({ sdl })
+}