README.md

parasprite

Describe your GraphQL schema using chainable interface

See API section for more information.

Requirements

• Node.js >= 8 < 9 || >= 10
• GraphQL.js 0.11.x || 0.12.x || 0.13.x || 14.x (see installation section)

Installation

You can install parasprite from NPM:

npm install --save parasprite graphql

or YARN:

yarn add parasprite graphql

API

Parasprite has classes that help you describe GraphQL schema with chains.

Note: You can invoke these classes without "new" keyword, just like a function

constructor Schema()

Main class that defines GraphQL schema.

Instance methods

query(name[, description]) -> {Type}

• {string} name – Name for root Query type
• {string} [description = undefined] – Description for root Query type

Define Query with given name and description.

mutation(name[, description]) -> {Type}

• {string} name – Name for root Mutation type
• {string} [description = undefined] – Description for root Mutation type

Define Mutation with given name and description.

subscription(name[, description]) -> {Type}

• {string} name – Name for root Subscription type
• {string} [description = undefined] – Description for root Subscription type

Define Subscription with given name and description.

end() -> {GraphQLSchema}

Make GraphQLSchema.

constructor Type

This class helps you describe GraphQLObjectType. there is 3 different syntaxes:

Type(options)

• {object} options
  • {string} name – Name for the type
  • {string} [description = null]
  • {GrphQLInterfaceType | GrphQLInterfaceType[]} [interfaces = null]
  • {GraphQLObjectType} [extends = null]
  • {Function} [isTypeOf = null]

Type(name[, options])

• {string} name
• {object} options
  • {string} [description = null]
  • {GrphQLInterfaceType | GrphQLInterfaceType[]} [interfaces = null]
  • {GraphQLObjectType} [extends = null]
  • {Function} [isTypeOf = null]

Type(name[, description, options])

• {string} name
• {string} [description = null]
• {object} options
  • {GrphQLInterfaceType | GrphQLInterfaceType[]} [interfaces = null]
  • {GraphQLObjectType} [extends = null]
  • {Function} [isTypeOf = null]

Instance methods

field(options) -> {Type}

Define one field on GraphQLObjectType. Returns current instance of Type class.

• {object} options – A field declaration options with the following properties:
  • {string} name
  • {string | [object, boolean]} type – Any valid GraphQL type, or a tuple with the type and required flag
  • {string} [description = undefined]
  • {string} [deprecationReason = undefined]
  • {boolean} [required = false] – If set to true, the field type will be marked as non-null.

resolve(options) -> {Resolve}

Add a new resolve field with the handler.

• {object} options – A field declaration options with the following properties:
  • {string} name
  • {string | [object, boolean]} type – Any valid GraphQL type, or a tuple with the type and required flag
  • {string} [description = undefined]
  • {string} [deprecationReason = undefined]
  • {boolean} [required = false] – If set to true, the field type will be marked as non-null.
  • {Function} handler – a function that will be used as resover for this field

subscribe(options) -> {Resolve}

Add a new subscribe field with the handler.

• {object} options – A field declaration options with the following properties:
  • {string} name
  • {string | [object, boolean]} type – Any valid GraphQL type, or a tuple with the type and required flag
  • {string} [description = undefined]
  • {string} [deprecationReason = undefined]
  • {boolean} [required = false] – If set to true, the field type will be marked as non-null.
  • {Function} handler – a function that will be used as subscriber for this field

end() -> {GraphQLObjectType}

Make a GraphQLObjectType.

constructor Input(name[, description])

• {string} name – Name for object type
• {string} description – Description for object type

Instance methods

field(options) -> {Input}

• {object} options – A field declaration options with the following properties:
  • {string} name
  • {string | [object, boolean]} type – Any valid GraphQL type, or a tuple with the type and required flag
  • {string} [description = undefined]
  • {boolean} [required = false] – If set to true, the field type will be marked as non-null.
  • {any} [defaultValue = undefined] – default value for this field (undefined means there is no default value)

constructor Interface(name[, description], resolveType)

Create a custum GraphQLInterfaceType using Parasprite chainable API

See Type section for more info about available methods.

constructor Union

Create a new GraphQLUnionType.

This constructor have to different APIs:

Union(name[, description], types[, astNode])

• {string} name – Name of the new Unit type.
• {string} description – Type description
• {GraphQLObjectType[]} types – A list of types, that could be resolved by the Union.
• {object} astNode

Union(options)

• {object} options:
  • {string} name – Name of the new Unit type.
  • {string} description – Type description
  • {GraphQLObjectType[]} types – A list of types, that could be resolved by the Union.
  • {object} astNode

Instance methods

match(predicate[, ctx]) -> {Union}

Add a predicate function to the internal queue. These predicate will be used to match returning values with one of given types.

Utils

toListType(value) -> {GraphQLList}

Create GraphQLList from given array or value

toRequired(value) -> {GraphQLNonNull}

Mark given value as non-null.

buildSchema(path[, options]) -> {GraphQLSchema}

Build a GraphQLSchema by reading the definitions from given directory.

• {string} path – An absolute or relative path to the directory with the schema definitions.
• {object} [options = {}] – Advanced parameters for that utility.
  • {object} query – Options for a Query definitions:
    • {string} [name = "Query"] – The name of Query type
    • {string} [dir = "query"] – The subdirectory name from where definitions would be read.
  • {object} mutation – Options for a Mutation definitions:
    • {string} [name = "Mutation"] – The name of Mutation type
    • {string} [dir = "mutation"] – The subdirectory name from where definitions would be read.
  • {object} subscription – Options for a Subscription definitions:
    • {string} [name = "Subscription"] – The name of Subscription type
    • {string} [dir = "subscription"] – The subdirectory name from where definitions would be read.

Usage

1. Basically, all you need is to describe GraphQLSchema is a Schema class and GraphQL internal types:

Take a look at simple example with a resolver that just greets a user:

import {GraphQLString as TString} from "graphql" // You also need graphql package
import Schema from "parasprite"

const greeter = (_, {name}) => `Hello, ${name}!`

const schema = Schema()
  .query("Query")
    .resolve({
      name: "greeter",
      type: TString,
      required: true,
      handler: greeter
    })
      .arg("name", TString, true)
    .end()
  .end()
.end()

This schema is equivalent to the following code in GraphQL schema language:

type Query {
  greeter(name: String!): String!
}

schema {
  query: Query
}

2. More complex example with Type class usage:

import {GraphQLString as TString} from "graphql" // You also need graphql package
import Schema, {Type} from "parasprite"
import Project from "model/Project" // Whatever model you need

const Project = Type("Project")
  .field({
    name: "name",
    type: TString,
    description: "Project name"
  })
  .field({
    name: "tagline",
    type: TString
  })
.end()

const schema = Schema()
  .query("Query")
    .resolve({
      name: "project",
      type: Project,
      description: "Get the project by his name",
      handler: Project.findProjectByName
    })
      .arg({
        name: "name",
        type: TString
      })
    .end()
  .end()
.end()

Equivalent to:

type Project {
  # Project name
  name: String
  tagline: String
}

type Query {
  # Get the project by his name
  project(name: String): Project
}

schema {
  query: Query
}

3. You can also pass a GraphQLObject type to the Schema root fields:

import {GraphQLString as TString} from "graphql"

import Schema from "parasprite/Schema"
import Type from "parasprite/Type"

const greeter = (_, {name}) => `Hello, ${name}!`

const TQuery = Type("Query")
  .resolve({
    name: "greet",
    type: TString,
    required: true,
    handler: greeter
  })
    .arg({
      name: "name",
      type: TString
    })
.end()

const schema = Schema().query(TQuery).end() // That's all!

4. Parasprite allow to extend GraphQLObjectType by using an extends option in Type constructor:

import {GraphQLString as TString, GraphQLInt as TInt} from "graphql"

import Type from "parasprite/Type"

const TUser = Type("User")
  .field({
    name: "login",
    type: TString,
    required: true
  })
  .field({
    name: "age",
    type: TInt,
    required: true
  })
.end()

const TViewer = Type("Viewer", {extends: TUser})
  .field({
    name: "email",
    type: TString,
    required: true,
    description: "Private email address."
  })
.end()

On GraphQL language:

type User {
  login: String!
  age: Int!
}

type Viewer {
  login: String!
  age: Int!

  # Private email address.
  email: String!
}

Roadmap:

• Basic API with queries, mutations and object type;
• Object type;
• Input type;
• Tests;
• Interfaces (documentation in progress);
• Extending for Type;
• Union type;
• Documentation (still in progress);
• Complex working examples (as external repo)

Misc

Wanted to learn more about GraphQL or try another tools? Then visit awesome-graphql list! :)