grantila/core-types-graphql

core-types ⬌ GraphQL conversion

core-types-graphql

This package provides conversion functions between core-types and GraphQL.

You probably don't want to use this package directly, but rather typeconv which uses this package to convert between TypeScript, JSON Schema and GraphQL.

Other conversion packages:

• core-types-ts
• core-types-json-schema

Versions

Since 3.0, this package is pure ESM and requires Node 14.13.1 or later.

Contents

• core-types-graphql
• Versions
• Contents
• Usage
  • core-types to GraphQL
  • GraphQL to core-types
• Utilities

Usage

There are two conversion functions, convertCoreTypesToGraphql and convertGraphqlToCoreTypes, both returning a wrapped value, of the type ConversionResult.

core-types to GraphQL

Conversion can be done to GraphQL code using convertCoreTypesToGraphql, but also to GraphQL AST using convertCoreTypesToGraphqlAst. The arguments to these are the same.

import { convertCoreTypesToGraphql } from 'core-types-graphql'

let doc; // This core-types document comes from somewhere

const { data: graphQL } = convertCoreTypesToGraphql( doc );

You can provide options as a second argument fn the type:

interface CoreTypesToGraphqlOptions
{
	warn?: WarnFunction;
	filename?: string;
	sourceFilename?: string;
	userPackage?: string;
	userPackageUrl?: string;
	nullTypeName?: string | null;
	nameGenerator?: NameGeneratorFunction;
	unsupported?: 'ignore' | 'warn' | 'error';
	includeComment?: boolean;
}

These options are all optional.

• warn: A function callback to be used for warnings, defaults to console.warn.
• filename The filename to be written to.
  This is a hint, no file will be written by the conversion function.
• sourceFilename: The name of the source file from which the core-types comes.
• userPackage: The name of the package using this package.
• userPackageUrl: The url to the package using this package.
• nullTypeName: Optional custom type used for null.
• nameGenerator: A function for generating names.
  GraphQL doesn't support inline objects or union types,
  so these must be constructed as separate types.
• unsupported: What to do when detecting an unsupported type
  • ignore: Ignore (skip) type
  • warn: Ignore type, but warn (default)
  • error: Throw an error
• includeComment: Includes a header comment about the auto-generated file.
  Defaults to true.

The warn function is of type WarnFunction from core-types, meaning it takes a message as string, and an optional second argument of type CoreTypesErrorMeta, also from core-types.

The nameGenerator function is of type NameGeneratorFunction defined as:

( baseName: string, nameHint: string, test: NameGeneratorTestFunction ) => string;

where NameGeneratorTestFunction is a test function to check if the generated name is available, on the form:

( name: string ) => boolean;

If this is specified (instead of letting a default name generator be used), an implementation is supposed to generate a name, potentially based on the baseName and a nameHint (e.g. an interface name and a property name within that interface), and test this generated name against test, altering it if necessary until test returns true, and then return that string.

GraphQL to core-types

import { convertGraphqlToCoreTypes } from 'core-types-graphql'

let graphQL; // This GraphQL string comes from somewhere

const { data: doc } = convertGraphqlToCoreTypes( graphQL );

An optional second argument can be provided on the form

interface GraphqlToCoreTypesOptions
{
	warn?: WarnFunction;
	unsupported?: 'ignore' | 'warn' | 'error';
}

• warn: The same warn function as in CoreTypesToGraphqlOptions
• unsupported: What to do when detecting an unsupported type
  • ignore: Ignore (skip) type (default)
  • warn: Ignore type, but warn
  • error: Throw an error

Utilities

This package exports two utility functions; getBreakingChanges and getDangerousChanges which both take two GraphQL source code texts (as strings) semantically meaning an "old" and a "new" version of a schema. The functions return a list of breaking/dangerous changes on the type BreakingChange/DangerousChange from the graphql package.