Apollo Prophecy

📟 Features

• Generate Server-side throwable errors in your resolvers like throw new NotAProphetError()
• Expose machine readable graphql errors through your api documentation
• Generate Client-side Apollo errors consumable like errorHere(error).isNotAProphetError ?

📋 Table of Contents

• Installation
• Usage
  • Server Side
  • Client Side
• Contributing
  • TODO
  • Test and Miscellaneous

Installation

Install with npm:

npm install -g apollo-prophecy

Install with yarn:

yarn global add apollo-prophecy

Usage

Usage: apollo-prophecy [command]

Commands:
  apollo-prophecy generate <json file> [--out]
  apollo-prophecy ask <graphql endpoint> [--type] [--out]

Options:
  -h, --help     Show help                                             [boolean]
  -v, --version  Display version number                                [boolean]

Server

⚠️ This Project is Only compatible with Apollo-Server v2

generate command

Creates Error.ts from a JSON input file. Using --out param you can change the name and location.

apollo-prophecy generate errors.json

Input file entries should at least contains the keys message and code.

For example given the following errors.json as input:

{
  "AuthenticationRequiredError": {
    "message": "You must be logged in to do this",
    "code": "AUTH_REQUIRED"
  },
  "UserNotFoundError": {
    "message": "No user found",
    "code": "USER_NOT_FOUND"
  },
}

Apollo Prophecy will generate the following Errors.ts

...
export class AuthenticationRequiredError extends ProphecyError {
  constructor(properties?: Record<string, any>) {
    super("AuthenticationRequiredError", "You must be logged in to do this","AUTH_REQUIRED", properties);
  }
}
  
export class UserNotFoundError extends ProphecyError {
  constructor(properties?: Record<string, any>) {
    super("UserNotFoundError", "No user found", "USER_NOT_FOUND", properties);
  }
}
...

Now you can use it the following way throw new UserNotFoundError() in your resolvers.

apollo-prophecy also exposes a definitions object and a graphql type definition named PropheticError so that you can expose all your errors descriptions through a resolver, see Client.

...
export const definitions = [{
    "name": "AuthenticationRequiredError"
    "message": "You must be logged in to do this",
    "extensions": {
      "code": "AUTH_REQUIRED"
    }
  }, {
    "name": "UserNotFoundError"
    "message": "No user found",
    "extensions": {
      "code": "USER_NOT_FOUND"
    }
  }
}];

export const errorType = `
  type PropheticErrorExtensions {
    code: String
  }

  type PropheticError {
    message: String?
    extensions: PropheticErrorExtensions
  }
`;
...

Client

ask command

Queries the errors field on the specified graphql endpoint and creates an Errors.ts file containing helpers with check methods (see Helpers) for all the errors exposed through the server api documentation.

apollo-prophecy ask http://localhost:3000/graphql

Helpers

In order to easily handle erros with Apollo-Client, the generated Errors.ts exposes two helpers methods errorHere and isThis, both methods takes one paramater of type ApolloError or GraphQLError.

errorHere() function

errorHere returns an object that has a property named after each errors. You can perform a simple boolean check on the error argument by calling the approiate key.

import { errorHere } from `./_generated/Errors.ts`;

...(error) => {
  if(errorHere(error).isUserNotFoundError){
    // Do something
  } else if(errorHere(error).isNotAProphetError){
    // Do something else
  }
}

isThis() function

isThis returns an object that has a handler method for each errors. It perfoms a simple check on the error argument, if the it succeed the corresponding handler is called otherwise nothing happens.

Note: Handlers can return a values.

import { isThis } from `./_generated/Errors.ts`;

...(error) => {
  isThis(error)
  .UserNotFoundError(() => ...)
  .NotAProphetError(() => ...)
  .handle()
}

React example:

import { isThis } from `./_generated/Errors.ts`;

...(error) => {
  return <p style={{color: '#FF495C'}}>
    {
      isThis(error)
      .UserNotFoundError(() => <span>Could not find a user with tha name</span>)
      .NotAProphetError(() => <span>Only Prophets can perfom this kind of actions...</span>)
      .handle();
    }
  </p>
}

Contributing

TODO

• See #2: Add support for third-party errors libraries like apollo-errors good first issue
• See #12: Add errors.json file as ask command argument good first issue
• See #16: Add language specific code generation Java/Kotlin/Swift/Javascript
  • See #13: Java/Kotlin good first issue
  • See #14: Swift good first issue
  • See #15: Javascript good first issue

Run tests

npm test

yarn test