tessl/npm-graphql-yoga

Fully-featured GraphQL Server with focus on easy setup, performance & great developer experience

Overview

Eval results

Files

Schema Integration

Name: tessl/npm-graphql-yoga
Author: tessl

GraphQL schema creation and integration utilities with proper context typing and flexible schema definitions including static schemas, promises, and dynamic schema resolution.

Capabilities

Create Schema

Helper function to create GraphQL schemas with proper Yoga context integration.

/**
 * Creates a GraphQL schema with Yoga context integration
 * @param opts - Schema definition options from @graphql-tools/schema
 * @returns GraphQL schema with Yoga context typing
 */
function createSchema<TContext = {}>(
  opts: IExecutableSchemaDefinition<TContext & YogaInitialContext>
): GraphQLSchemaWithContext<TContext & YogaInitialContext>;

Usage Examples:

import { createSchema } from "graphql-yoga";

// Basic schema creation
const schema = createSchema({
  typeDefs: `
    type Query {
      hello: String
      user(id: ID!): User
    }
    
    type User {
      id: ID!
      name: String!
      email: String!
    }
  `,
  resolvers: {
    Query: {
      hello: () => "Hello World!",
      user: (_, { id }, context) => {
        // context includes YogaInitialContext
        return getUserById(id, context.request);
      }
    }
  }
});

// Schema with custom context typing
interface MyContext {
  user: User;
  db: Database;
}

const schema = createSchema<MyContext>({
  typeDefs: myTypeDefs,
  resolvers: {
    Query: {
      currentUser: (_, __, context) => {
        // context is typed as MyContext & YogaInitialContext
        return context.user;
      }
    }
  }
});

Use Schema Plugin

Plugin to integrate GraphQL schemas into Yoga servers with support for static, promise-based, and dynamic schemas.

/**
 * Plugin to configure GraphQL schema for Yoga server
 * @param schemaDef - Schema definition (static, promise, or function)
 * @returns Plugin for schema integration
 */
function useSchema<
  TServerContext = {},
  TUserContext = {}
>(
  schemaDef?: YogaSchemaDefinition<TServerContext, TUserContext>
): Plugin<YogaInitialContext & TServerContext>;

Usage Examples:

import { createYoga, useSchema, createSchema } from "graphql-yoga";

// Static schema
const yoga = createYoga({
  plugins: [
    useSchema(createSchema({
      typeDefs: `type Query { hello: String }`,
      resolvers: { Query: { hello: () => "Hello!" } }
    }))
  ]
});

// Promise-based schema
const schemaPromise = loadSchemaFromDatabase();
const yoga = createYoga({
  plugins: [useSchema(schemaPromise)]
});

// Dynamic schema function
const yoga = createYoga({
  plugins: [
    useSchema(({ request }) => {
      const tenant = getTenantFromRequest(request);
      return getSchemaForTenant(tenant);
    })
  ]
});

Schema Definition Types

Flexible schema definition types supporting various schema loading patterns.

/**
 * Schema definition supporting static, promise, and dynamic patterns
 */
type YogaSchemaDefinition<TServerContext, TUserContext> =
  | PromiseOrValue<GraphQLSchemaWithContext<TServerContext & YogaInitialContext & TUserContext>>
  | ((
      context: TServerContext & { request: YogaInitialContext['request'] }
    ) => PromiseOrValue<
      GraphQLSchemaWithContext<TServerContext & YogaInitialContext & TUserContext>
    >);

/**
 * GraphQL schema with Yoga context information
 */
interface GraphQLSchemaWithContext<TContext> extends GraphQLSchema {
  _context?: TContext;
}

Usage Examples:

// Static schema
const staticSchema: YogaSchemaDefinition<{}, {}> = createSchema({
  typeDefs: `type Query { version: String }`,
  resolvers: { Query: { version: () => "1.0.0" } }
});

// Promise schema
const promiseSchema: YogaSchemaDefinition<{}, {}> = Promise.resolve(
  createSchema({
    typeDefs: await loadTypeDefs(),
    resolvers: await loadResolvers()
  })
);

// Dynamic schema function
const dynamicSchema: YogaSchemaDefinition<{ tenant: string }, {}> = 
  ({ request, tenant }) => {
    const schema = getSchemaForTenant(tenant);
    return schema;
  };

Schema Context Integration

Integration patterns for combining Yoga's initial context with custom context types.

/**
 * Initial context provided by Yoga to all GraphQL operations
 */
interface YogaInitialContext {
  /** GraphQL operation parameters */
  params: GraphQLParams;
  /** HTTP request object */
  request: Request;
}

/**
 * GraphQL operation parameters
 */
interface GraphQLParams<
  TVariables = Record<string, any>,
  TExtensions = Record<string, any>
> {
  /** GraphQL operation name */
  operationName?: string;
  /** GraphQL query string */
  query?: string;
  /** Query variables */
  variables?: TVariables;
  /** Request extensions */
  extensions?: TExtensions;
}

Usage Examples:

// Accessing Yoga context in resolvers
const schema = createSchema({
  typeDefs: `
    type Query {
      requestInfo: RequestInfo
    }
    
    type RequestInfo {
      method: String!
      url: String!
      userAgent: String
    }
  `,
  resolvers: {
    Query: {
      requestInfo: (_, __, context) => {
        // Access Yoga's initial context
        const { request, params } = context;
        return {
          method: request.method,
          url: request.url,
          userAgent: request.headers.get('user-agent')
        };
      }
    }
  }
});

// Extending context with custom data
interface CustomContext {
  userId: string;
  permissions: string[];
}

const yoga = createYoga({
  schema: createSchema<CustomContext>({
    typeDefs: myTypeDefs,
    resolvers: {
      Query: {
        profile: (_, __, context) => {
          // context includes both YogaInitialContext and CustomContext
          return getUserProfile(context.userId, context.permissions);
        }
      }
    }
  }),
  context: async ({ request }) => {
    const token = request.headers.get('authorization');
    const user = await validateToken(token);
    return {
      userId: user.id,
      permissions: user.permissions
    };
  }
});

Schema Validation and Caching

Options for schema parsing and validation caching to improve performance.

/**
 * Parser and validation cache configuration
 */
interface ParserAndValidationCacheOptions {
  /** Maximum number of cached items */
  max?: number;
  /** Time to live for cache entries in milliseconds */
  ttl?: number;
}

Usage Examples:

// Enable caching with default options
const yoga = createYoga({
  schema: mySchema,
  parserAndValidationCache: true
});

// Custom cache configuration
const yoga = createYoga({
  schema: mySchema,
  parserAndValidationCache: {
    max: 2000,
    ttl: 600000 // 10 minutes
  }
});

// Disable caching
const yoga = createYoga({
  schema: mySchema,
  parserAndValidationCache: false
});