GRAPHQL-SCHEMAX

Creates GraphQL string schema from plain JSON objects. Managing GraphQL schemas via plain JSON objects offers the following advantages:

• Composition: Reuse the same base object in inputs or types.
• Separation of concerns: Isolate your domain in modules and merge them later.
• Inspection: Easily traverse the schema tree.
• Leaner: Define GraphQL types, enums and inputs on-the-fly (anonymous types) instead of having to define them explicitly.

This package works with both ES6 modules and CommonJS.

npm i graphql-schemax

import { Schemax } from 'graphql-schemax'
// const { Schemax } = require('graphql-schemax') // CommonJS

const schema = new Schemax(
	'type Query', {
		users: { where: { id:'ID', first_name:'String', last_name:'String', email:'String' }, sort: { by:['first_name', 'last_name'], dir:['asc', 'desc'] }, limit: 'Int', ':': [{
			id:'ID',
			first_name:'String',
			last_name:'String',
			email:'String'
		}] }
	},
	'type Mutation', {
		createUser: { user: { first_name:'String', last_name:'String', email:'String'}, ':':{
			id:'ID',
			first_name:'String',
			last_name:'String',
			email:'String'
		} }
	}
)

console.log(schema.toString())

This code outputs the following string:

type Query {
	users(where: Input_0826775903, sort: Input_0419529037, limit: Int): [Type_0826775903]
}

type Mutation {
	createUser(user: Input_01074650554): Type_0826775903
}

input Input_0826775903 {
	id: ID
	first_name: String
	last_name: String
	email: String
}

enum Enum_0110021644 {
	first_name
	last_name
}

enum Enum_1894885946 {
	asc
	desc
}

input Input_0419529037 {
	by: Enum_0110021644
	dir: Enum_1894885946
}

type Type_0826775903 {
	id: ID
	first_name: String
	last_name: String
	email: String
}

input Input_01074650554 {
	first_name: String
	last_name: String
	email: String
}

schema {
	query: Query
	mutation: Mutation
}

Table of contents

• Getting started
  • Quick overview
  • Using the same object as a type or input
  • Careful - Enums vs Arrays
  • Required anonymous types
    • Required anonymous Type and Input
    • Required anonymous Enum
    • Required non-empty anonymous array
  • Naming anonymous types
    • Naming anonymous Type and Input
    • Naming anonymous Enum
  • Directives
    • Basic directive
    • Multiple identical directives
• APIs
  • constructor
    • Inline schema definitions signature
    • Array schema definitions signature
    • Single object signature
  • toString
  • add
  • addIgnoreRules
  • addTypeResolutions
    • Renaming a type
    • Merging types
      • Keeping the longest type
      • Keeping the shortest type
      • Custom merge
• Dev
  • About this project
  • Building this project for both CommonJS and ES6 modules
  • Unit test
• FAQ
  • How to merge schemas?
  • What happens when the same type definitions exist in multiple schemas?
• License

Getting started

Quick overview

import { Schemax } from 'graphql-schemax'
// const { Schemax } = require('graphql-schemax') // CommonJS

const schema = new Schemax(
	'type Query', {
		users: { where: { id:'ID', first_name:'String', last_name:'String', email:'String' }, sort: { by:['first_name', 'last_name'], dir:['asc', 'desc'] }, limit: 'Int', ':': [{
			id:'ID',
			first_name:'String',
			last_name:'String',
			email:'String'
		}] }
	},
	'type Mutation', {
		createUser: { user: { first_name:'String', last_name:'String', email:'String'}, ':':{
			id:'ID',
			first_name:'String',
			last_name:'String',
			email:'String'
		} }
	}
)

console.log(schema.toString())

This code outputs the following string:

type Query {
	users(where: Input_0826775903, sort: Input_0419529037, limit: Int): [Type_0826775903]
}

type Mutation {
	createUser(user: Input_01074650554): Type_0826775903
}

input Input_0826775903 {
	id: ID
	first_name: String
	last_name: String
	email: String
}

enum Enum_0110021644 {
	first_name
	last_name
}

enum Enum_1894885946 {
	asc
	desc
}

input Input_0419529037 {
	by: Enum_0110021644
	dir: Enum_1894885946
}

type Type_0826775903 {
	id: ID
	first_name: String
	last_name: String
	email: String
}

input Input_01074650554 {
	first_name: String
	last_name: String
	email: String
}

schema {
	query: Query
	mutation: Mutation
}

Notice that:

• The GraphQL input are automatically generated. They are referred as anonymous inputs. The naming convention is Input_<hash> where <hash> is the hash of the input definition. The same mechanism is used for anonymous type and enum. This strategy allows to avoid unecessary type duplication. This can be seen with the output of the users and createUser methods. The same object results in a single schema definition called Type_0826775903.
• GraphQL enum (e.g., by:['first_name', 'last_name']) uses an array instead of an object.
• Arguments such as those defined on the users and createUser methods are represented by an object that uses this convention:
  • { argument01: 'TypeDefinition', argument02: 'TypeDefinition', ':': 'TypeDefinition' }
  • The last property must always be ':', which represents the output. This property is required.
  • first_name:'String' is actually a shortcut for first_name: { ':': 'String' }.

If you wish to be explicit about each type, the example above can be re-written as follow:

const schema = new Schemax(
	'type User', {
		id:'ID',
		first_name:'String',
		last_name:'String',
		email:'String'
	},
	'input WhereUser', {
		id:'ID', 
		first_name:'String', 
		last_name:'String', 
		email:'String'
	},
	'input SortUser', {
		by: 'SortByEnum', 
		dir: 'DirEnum'
	},
	'input InsertUser', {
		first_name:'String', 
		last_name:'String', 
		email:'String'
	},
	'enum SortByEnum', [
		'first_name', 
		'last_name'
	],
	'enum DirEnum', [
		'asc', 
		'desc'
	],
	'type Query', {
		users: { where: 'WhereUser', sort: 'SortUser', limit: 'Int', ':': '[User]' }
	},
	'type Mutation', {
		createUser: { user: 'InsertUser', ':': 'User' }
	}
)
console.log(schema.toString())

Which outputs:

type User {
	id: ID
	first_name: String
	last_name: String
	email: String
}

input WhereUser {
	id: ID
	first_name: String
	last_name: String
	email: String
}

input SortUser {
	by: SortByEnum
	dir: DirEnum
}

input InsertUser {
	first_name: String
	last_name: String
	email: String
}

enum SortByEnum {
	first_name
	last_name
}

enum DirEnum {
	asc
	desc
}

type Query {
	users(where: WhereUser, sort: SortUser, limit: Int): [User]
}

type Mutation {
	createUser(user: InsertUser): User
}

schema {
	query: Query
	mutation: Mutation
}

Notice that enum definitions use arrays instead of objects.

Using the same object as a type or input

The sample below shows how to use the coord object as a GraphQL type (used in the Tower type) and a GraphQL input (used in the towers field).

const coord = {
	lat:'Float', 
	long:'Float' 
}

const schema = new Schemax(
	'type Tower', {
		id:'ID!',
		name: 'String!',
		coord: { ':': coord }
	},
	'type Query @aws_cognito_user_pools', {
		towers: { 
			where: { id:'ID', coord:coord }, 
			':': '[Tower]'
		}
	}
)

Careful - Enums vs Arrays

Defining GraphQL enums is done via string arrays:

const schema = new Schemax(
	'type Tower', {
		id:'ID!',
		name: 'String!',
		type: ['tall', 'short']
	}
)

Defining GraphQL array types is done via object arrays:

const schema = new Schemax(
	'type Tower', {
		id:'ID!',
		name: 'String!',
		type: ['tall', 'short'],
		devices: { ':': [{ id:'ID', name: 'String'}] }
	}
)

Common mistake: Creating an enum instead of an array type

Let's assume there is an explicit Device type, and that a Tower typ needs to define a devices field as an array of Device. The following is incorrect:

const schema = new Schemax(
	'type Device', {
		id: 'ID',
		name: 'String'
	},
	'type Tower', {
		id:'ID!',
		name: 'String!',
		devices: ['Device']
	}
)

In this example, the Tower.devices field is a GraphQL enum with one possible value called Device.

The correct definition is:

const schema = new Schemax(
	'type Device', {
		id: 'ID',
		name: 'String'
	},
	'type Tower', {
		id:'ID!',
		name: 'String!',
		devices: '[Device]'
	}
)

or, alternatively:

const schema = new Schemax(
	'type Device', {
		id: 'ID',
		name: 'String'
	},
	'type Tower', {
		id:'ID!',
		name: 'String!',
		devices: { ':': [{ id:'ID', name:'String' }] }
	}
)

Required anonymous types

Required anonymous Type and Input

Use the __required property or its alias ! as follow:

const schema = new Schemax(
	'type Query', {
		users: { where: { id:'ID', first_name:'String', __required:true }, ':': [{
			id:'ID',
			first_name:'String',
			last_name:'String',
			email:'String'
		}] }
	}
)

console.log(schema.toString())

With the alias: users: { where: { id:'ID', first_name:'String', '!':true }, ':': [{

Which outputs:

type Query {
	users(where: Input_01605579239!): [Type_0826775903]
}

input Input_01605579239 {
	id: ID
	first_name: String
}

type Type_0826775903 {
	id: ID
	first_name: String
	last_name: String
	email: String
}

schema {
	query: Query
}

Required anonymous Enum

To make an anonymous enum required, use the reserved __required string, or its alias !:

const schema = [
	'type Query', {
		products:{ type:['car','home','furniture','__required'], ':':{ name:'String' } }
	}
]

console.log(new Schemax(schema).toString())

With the alias: ['car','home','furniture','!']

Which outputs:

type Query {
	products(type: Enum_11845869194!): Type_12078318863
}

enum Enum_11845869194 {
	car
	furniture
	home
}

type Type_12078318863 {
	name: String
}

schema {
	query: Query
}

Required non-empty anonymous array

Use the __noempty keyword or its alias !0 to create enums similar to [RoleEnum!].

const schema = [
	'type Mutation', {
		invite: { users:[{ 
			id:'ID', 
			email:'String', 
			roles:[['admin','writer','reader','__required','__noempty','__name:RoleEnum']],
			__noempty:true, 
			__name:'UserInviteInput' 
		}], ':':{ message:'String', __name:'Message' } }
	}
]

console.log(new Schemax(schema).toString())

With the alias: roles:[['admin','writer','reader','__required','!0','__name:RoleEnum']]

Which outputs:

type Mutation {
	invite(users: [UserInviteInput!]): Message
}

enum RoleEnum {
	admin
	reader
	writer
}

input UserInviteInput {
	id: ID
	email: String
	roles: [RoleEnum!]!
}

type Message {
	message: String
}

schema {
	mutation: Mutation
}

Naming anonymous types

Naming anonymous Type and Input

Use the __name property or its alias # as follow:

const schema = new Schemax(
	'type Query', {
		users: { where: { id:'ID', first_name:'String', __required:true, __name: 'WhereUserInput' }, ':': [{
			id:'ID',
			first_name:'String',
			last_name:'String',
			email:'String',
			__name: 'User'
		}] }
	}
)

console.log(schema.toString())

With the alias: users: { where: { id:'ID', first_name:'String', __required:true, '#': 'WhereUserInput' }, ':': [{

Which outputs:

type Query {
	users(where: WhereUserInput!): [User]
}

input WhereUserInput {
	id: ID
	first_name: String
}

type User {
	id: ID
	first_name: String
	last_name: String
	email: String
}

schema {
	query: Query
}

Naming anonymous Enum

To use a custom enum, use the reserved __name:YOUR_NAME string or its alias version #YOUR_NAME:

const schema = [
	'type Query', {
		products:{ type:['car','home','furniture','__name:ProductTypeEnum'], ':':{ name:'String' } }
	}
]

console.log(new Schemax(schema).toString())

With the alias: ['car','home','furniture','#ProductTypeEnum'] NOTICE: With the # alias, the : is dropped.

type Query {
	products(type: ProductTypeEnum): Type_12078318863
}

enum ProductTypeEnum {
	car
	furniture
	home
}

type Type_12078318863 {
	name: String
}

schema {
	query: Query
}

Directives

Basic directive

const schema = new Schemax(
	`directive @deprecated(
		reason: String = "No longer supported"
	) on FIELD_DEFINITION | ENUM_VALUE`, null,
	'type Query @aws_cognito_user_pools', {
		users: { where: { id:'ID', first_name:'String', __required:true, __name: 'WhereUserInput' }, ':': [{
			id:'ID @aws_auth',
			first_name:'String',
			last_name:'String',
			'@aws_api_key @aws_cognito_user_pools(cognito_groups: ["Bloggers", "Readers"])': null,
			email:'String',
			__name: 'User'
		}] }
	}
)

schema.addIgnoreRules(['Unknown directive'])

console.log(schema.toString())

NOTES:

• schema.addIgnoreRules(['Unknown directive']) is necessary to prevent the Unknown directive error to break the compilation. To know more about this topic, please refer to the addIgnoreRules section.
• Adding the same email directive on the first_name would fail as a JSON object cannot define multiple identical keys. To overcome this limitation please refer to the Multiple identical directives section.

Which outputs:

directive @deprecated(
	reason: String = "No longer supported"
) on FIELD_DEFINITION | ENUM_VALUE

type Query @aws_cognito_user_pools {
	users(where: WhereUserInput!): [User]
}

input WhereUserInput {
	id: ID
	first_name: String
}

type User {
	id: ID @aws_auth
	first_name: String
	last_name: String
	@aws_api_key @aws_cognito_user_pools(cognito_groups: ["Bloggers", "Readers"])
	email: String
}

schema {
	query: Query
}

Notice how the directive must be followed by null.

Multiple identical directives

In the example above, only one field (email) is using the @aws_api_key @aws_cognito_user_pools(cognito_groups: ["Bloggers", "Readers"]) directive. Adding that directive on the first_name would fail as a JSON object cannot define multiple identical keys. To overcome this limitation, prefix the directive with its field:

const schema = new Schemax(
	`directive @deprecated(
		reason: String = "No longer supported"
	) on FIELD_DEFINITION | ENUM_VALUE`, null,
	'type Query @aws_cognito_user_pools', {
		users: { where: { id:'ID', first_name:'String', __required:true, __name: 'WhereUserInput' }, ':': [{
			id:'ID @aws_auth',
			'first_name:@aws_api_key @aws_cognito_user_pools(cognito_groups: ["Bloggers", "Readers"])': null,
			first_name:'String',
			last_name:'String',
			'email:@aws_api_key @aws_cognito_user_pools(cognito_groups: ["Bloggers", "Readers"])': null,
			email:'String',
			__name: 'User'
		}] }
	}
)

schema.addIgnoreRules(['Unknown directive'])

console.log(schema.toString())

APIs

constructor

The Schemax class supports multiple signatures:

1. Undefined amount of arguments with support for
   • Inline schema definitions signature
   • Array schema definitions signature
2. Single object to configure various options and the schema definition at the same time.

Inline schema definitions signature

import { Schemax } from 'graphql-schemax'

const schema = new Schemax(
	'type Project', {
		id: 'ID',
		name: 'String'
	},
	'type User', {
		id: 'ID',
		first_name: 'String',
		last_name: 'String'
	},
	'type Query', {
		projects: '[Project]',
		users: '[User]'
	}
)

console.log(schema.toString())

Which can also be written as follow:

import { Schemax } from 'graphql-schemax'

const inlineSchema = [
'type Project', {
	id: 'ID',
	name: 'String'
},
'type User', {
	id: 'ID',
	first_name: 'String',
	last_name: 'String'
},
'type Query', {
	projects: '[Project]',
	users: '[User]'
}]

const schema = new Schemax(...inlineSchema)

console.log(schema.toString())

Array schema definitions signature

import { Schemax } from 'graphql-schemax'

const inlineSchema = [
'type Project', {
	id: 'ID',
	name: 'String'
},
'type User', {
	id: 'ID',
	first_name: 'String',
	last_name: 'String'
},
'type Query', {
	projects: '[Project]',
	users: '[User]'
}]

const schema = new Schemax(inlineSchema)

console.log(schema.toString())

or

import { Schemax } from 'graphql-schemax'

const inlineSchema01 = [
'type Project', {
	id: 'ID',
	name: 'String'
},
'type Query', {
	projects: '[Project]'
}]

const inlineSchema02 = [
'type User', {
	id: 'ID',
	first_name: 'String',
	last_name: 'String'
},
'type Query', {
	users: '[User]'
}]

const schema = new Schemax(inlineSchema01, inlineSchema02)

console.log(schema.toString())

NOTICE: The type Query is defined twice. When Schemax detects multiple identical definitions, it merges them. This means that in this example, the output is equal to:

type Query {
	projects: [Project]
	users: [User]
}

Finally, the constructor also support mixing those two styles:

const schema = new Schemax(inlineSchema01, 
'type User', {
	id: 'ID',
	first_name: 'String',
	last_name: 'String'
},
'type Query', {
	users: '[User]'
})

toString

Compiles the Schemax instance to a GraphQL string.

import { Schemax } from 'graphql-schemax'

const schema = new Schemax(
	'type Project', {
		id: 'ID',
		name: 'String'
	},
	'type User', {
		id: 'ID',
		first_name: 'String',
		last_name: 'String'
	},
	'type Query', {
		projects: '[Project]',
		users: '[User]'
	}
)

console.log(schema.toString())

Which outputs:

type Project {
	id: ID
	name: String
}

type User {
	id: ID
	first_name: String
	last_name: String
}

type Query {
	projects: [Project]
	users: [User]
}

schema {
	query: Query
}

Single object signature

import { Schemax } from 'graphql-schemax'

const schema = new Schemax({
	ignoreRules:['Unknown directive'],
	typeResolutions: [{
		def: 'type User', 
		to: 'type User @some_undefined_directive'
	}],
	defs:[
		'type Project', {
			id: 'ID',
			name: 'String'
		},
		'type User', {
			id: 'ID',
			first_name: 'String',
			last_name: 'String'
		},
		'type Query', {
			projects: '[Project]',
			users: '[User]'
		}
	]
})

console.log(schema.toString())

Which outputs:

type Project {
	id: ID
	name: String
}

type Query {
	projects: [Project]
	users: [User]
}

type User @some_undefined_directive {
	id: ID
	first_name: String
	last_name: String
}

schema {
	query: Query
}

NOTES: To learn more about the ignoreRules and typeResolutions, please refer to the following sections:

• addIgnoreRules
• addTypeResolutions

add

Mutates the Schemax instance by adding more schema definitions. It supports the same signature as the constructor.

import { Schemax } from 'graphql-schemax'

const inlineSchema01 = [
'type Project', {
	id: 'ID',
	name: 'String'
},
'type Query', {
	projects: '[Project]'
}]

const inlineSchema02 = [
'type User', {
	id: 'ID',
	first_name: 'String',
	last_name: 'String'
},
'type Query', {
	users: '[User]'
}]

const schema = new Schemax()

console.log('SAMPLE 01')
console.log(schema.toString())

schema.add(inlineSchema01)

console.log('SAMPLE 02')
console.log(schema.toString())

schema.add(inlineSchema02, 
'type Address', {
	id: 'ID',
	line01: 'String'
})

console.log('SAMPLE 03')
console.log(schema.toString())

Which outputs:

// SAMPLE 01

// SAMPLE 02
type Project {
	id: ID
	name: String
}

type Query {
	projects: [Project]
}

schema {
	query: Query
}
// SAMPLE 03
type Project {
	id: ID
	name: String
}

type Query {
	projects: [Project]
	users: [User]
}

type User {
	id: ID
	first_name: String
	last_name: String
}

type Address {
	id: ID
	line01: String
}

schema {
	query: Query
}

addIgnoreRules

graphql-schemax validates the generated string schema to prevent GraphQL errors. Depending on your use case, you might need to ignore those errors (e.g., undefined directives throw an Unknown directive GraphQL error if directives are used but not defined. This happens with global directives such as @aws_api_key or @aws_cognito_user_pools in AWS AppSync). GraphQL errors can be ignore based on their message using the addIgnoreRules API as follow:

import { Schemax } from 'graphql-schemax'

const schema = new Schemax(
	'type Project', {
		id: 'ID',
		name: 'String'
	},
	'type User @aws_api_key', {
		id: 'ID',
		first_name: 'String',
		last_name: 'String'
	},
	'type Query', {
		projects: '[Project]',
		users: '[User]'
	})

schema.addIgnoreRules(['Unknown directive'])

console.log(schema.toString())

Where schema.addIgnoreRules(['Unknown directive']) can be read as follow: Ignore GraphQL errors whose message starts with 'Unknown directive'.

This example supports 2 variations:

• schema.addIgnoreRules([/^Unknown directive/]): Use regular expression for more advanced string matching.
• schema.addIgnoreRules([(errMsg => /^Unknown directive/.test(errMsg))]): Use customfunction for even more advanced string matching.

The values of this API can also be defined in the Single object signature version of the Schemax constructor.

addTypeResolutions

Helps renaming or merging types by explicitly controlling how type names are resolved.

Renaming a type

import { Schemax } from 'graphql-schemax'

const inlineSchema01 = [
'type Project', {
	id: 'ID',
	name: 'String'
},
'type Query', {
	projects: '[Project]'
}]

const inlineSchema02 = [
'type User', {
	id: 'ID',
	first_name: 'String',
	last_name: 'String'
},
'type Query', {
	users: '[User]'
}]

const schema = new Schemax(...inlineSchema01, ...inlineSchema02)
schema.addTypeResolutions([{
	def: 'type User', to: 'type User @aws_api_key'
}])
// Necessary to prevent the @aws_api_key directive to break the compilation.
schema.addIgnoreRules(['Unknown directive'])

console.log(schema.toString())

NOTES: schema.addIgnoreRules(['Unknown directive']) is necessary to prevent the Unknown directive error to break the compilation. To know more about this topic, please refer to the addIgnoreRules section.

The values of this API can also be defined in the Single object signature version of the Schemax constructor.

Merging types

Keeping the longest type

import { Schemax } from 'graphql-schemax'

const inlineSchema01 = [
'type Project', {
	id: 'ID',
	name: 'String'
},
'type Query', {
	projects: '[Project]'
}]

const inlineSchema02 = [
'type User', {
	id: 'ID',
	first_name: 'String',
	last_name: 'String'
},
'type Query @aws_api_key', {
	users: '[User]'
}]

const schema = new Schemax(...inlineSchema01, ...inlineSchema02)
schema.addTypeResolutions([{
	def: /^type Query(\s|$)/, keepLongest:true
}])
// Necessary to prevent the @aws_api_key directive to break the compilation.
schema.addIgnoreRules(['Unknown directive'])

console.log(schema.toString())

NOTES: schema.addIgnoreRules(['Unknown directive']) is necessary to prevent the Unknown directive error to break the compilation. To know more about this topic, please refer to the addIgnoreRules section.

Which returns:

type Project {
	id: ID
	name: String
}

type User {
	id: ID
	first_name: String
	last_name: String
}

type Query @aws_api_key {
	projects: [Project]
	users: [User]
}

schema {
	query: Query
}

Keeping the shortest type

import { Schemax } from 'graphql-schemax'

const inlineSchema01 = [
'type Project', {
	id: 'ID',
	name: 'String'
},
'type Query', {
	projects: '[Project]'
}]

const inlineSchema02 = [
'type User', {
	id: 'ID',
	first_name: 'String',
	last_name: 'String'
},
'type Query @aws_api_key', {
	users: '[User]'
}]

const schema = new Schemax(...inlineSchema01, ...inlineSchema02)
schema.addTypeResolutions([{
	def: /^type Query(\s|$)/, keepShortest:true
}])
// Necessary to prevent the @aws_api_key directive to break the compilation.
schema.addIgnoreRules(['Unknown directive'])

console.log(schema.toString())

NOTES: schema.addIgnoreRules(['Unknown directive']) is necessary to prevent the Unknown directive error to break the compilation. To know more about this topic, please refer to the addIgnoreRules section.

Which returns:

type Project {
	id: ID
	name: String
}

type User {
	id: ID
	first_name: String
	last_name: String
}

type Query {
	projects: [Project]
	users: [User]
}

schema {
	query: Query
}

Custom merge

import { Schemax } from 'graphql-schemax'

const inlineSchema01 = [
'type Project', {
	id: 'ID',
	name: 'String'
},
'type Query @aws_cognito_user_pools', {
	projects: '[Project]'
}]

const inlineSchema02 = [
'type User', {
	id: 'ID',
	first_name: 'String',
	last_name: 'String'
},
'type Query @aws_api_key', {
	users: '[User]'
}]

const schema = new Schemax(...inlineSchema01, ...inlineSchema02)
schema.addTypeResolutions([{
	def: /^type Query(\s|$)/, 
	reduce:(oldType, newType, context) => { // fired for each type that matches the regex /^type Query(\s|$)/
		const attributes = newType.replace('type Query', '').split(' ').filter(x => x)
		if (!context.attributes)
			context.attributes = new Set(attributes)
		else
			attributes.forEach(a => context.attributes.add(a))

		const attrs = Array.from(context.attributes)
		return attrs.length ? `type Query ${attrs.join(' ')}` : 'type Query'
	}
}])
// Necessary to prevent the @aws_api_key directive to break the compilation.
schema.addIgnoreRules(['Unknown directive'])

console.log(schema.toString())

NOTES: schema.addIgnoreRules(['Unknown directive']) is necessary to prevent the Unknown directive error to break the compilation. To know more about this topic, please refer to the addIgnoreRules section.

Which returns:

type Project {
	id: ID
	name: String
}

type User {
	id: ID
	first_name: String
	last_name: String
}

type Query @aws_cognito_user_pools @aws_api_key {
	projects: [Project]
	users: [User]
}

schema {
	query: Query
}

Dev

About this project

This project is built using ES6 modules located under the src folder. All the entry point definitions are located in the package.json under the exports property.

rollup is used to compile the ES6 modules to CommonJS.

Building this project for both CommonJS and ES6 modules

npm run build

This command compiles the ES6 modules located under the src folder to .cjs file sent to the dist folder.

This command is aitomatically executed before exah deployment to make sure the latest build is always depployed.

Unit test

npm test

FAQ

How to merge schemas?

Both the constructor and add APIs support multiple schema definitions. Those schema definitions are merged when the toString API is executed.

What happens when the same type definitions exist in multiple schemas?

They are merged into a single type definition. This is how the type Query, type Mutation and type Subscription can be defined in multiple microservice schemas and merged into a single GraphQL schema. For example:

import { Schemax } from 'graphql-schemax'

const inlineSchema01 = [
'type Project', {
	id: 'ID',
	name: 'String'
},
'type Query', {
	projects: '[Project]'
}]

const inlineSchema02 = [
'type User', {
	id: 'ID',
	first_name: 'String',
	last_name: 'String'
},
'type Project', {
	sku: 'String'
},
'type Query', {
	users: '[User]'
}]

const schema = new Schemax(inlineSchema01, inlineSchema02)

console.log(schema.toString())

Outputs:

type Project {
	id: ID
	name: String
	sku: String
}

type Query {
	projects: [Project]
	users: [User]
}

type User {
	id: ID
	first_name: String
	last_name: String
}

schema {
	query: Query
}

Notice that both type Project and type Query are defined twice. They are both merged in the final GraphQL schema.

WARNING: If the type definitions are not exactly identical, the type are considered different and won't be merged. This means that identical types with different directive won't be merged automatically. To deal with this advanced scenario, use the addTypeResolutions API.

License

BSD 3-Clause License

Copyright (c) 2019-2021, Cloudless Consulting Pty Ltd All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.