README
Apollo Prophecy
You shall fail... successfully
๐ 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
First, install apollo-prophecy
globaly
npm install -g 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
command generate
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
command ask
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
.
function errorHere()
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
}
}
function isThis()
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
๐ด fork develop โคต
๐จโ๐ป Code โคต
๐ Test โคต
๐ฉ Pull Request โคต
๐ฅ๐ฅ๐ฅ
TODO
- See #2: Add support for third party libraries errors like apollo-errors
Running tests locally:
npm test
yarn test