https://github.com/theGlenn/apollo-prophecy
🔮 GraphQL error management made Easy, generate custom machine-readable errors for Apollo Client/Server from the CLI
https://github.com/theGlenn/apollo-prophecy
apollo apollo-codegen apollographql code-generation error-handling graphql graphql-tools typescript
Last synced: 11 days ago
JSON representation
🔮 GraphQL error management made Easy, generate custom machine-readable errors for Apollo Client/Server from the CLI
- Host: GitHub
- URL: https://github.com/theGlenn/apollo-prophecy
- Owner: theGlenn
- License: mit
- Created: 2018-06-03T22:13:08.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2023-01-06T15:40:12.000Z (over 3 years ago)
- Last Synced: 2025-06-23T10:50:21.040Z (12 months ago)
- Topics: apollo, apollo-codegen, apollographql, code-generation, error-handling, graphql, graphql-tools, typescript
- Language: TypeScript
- Homepage:
- Size: 838 KB
- Stars: 86
- Watchers: 3
- Forks: 3
- Open Issues: 25
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-github-projects - apollo-prophecy - 🔮 GraphQL error management made Easy, generate custom machine-readable errors for Apollo Client/Server from the CLI ⭐85 `TypeScript` (📦 Legacy & Inactive Projects)
README
Apollo Prophecy
👁📟👁
You shall fail... successfully
Command tool to generate errors files for your Appolo Server and Client
## 📟 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](#installation)
* [Usage](#usage)
* [Server Side](#server)
* [Client Side](#client)
* [Contributing](#contributing)
* [TODO](#todo)
* [Test and Miscellaneous](#run-tests)
## Installation
Install with npm:
```sh
npm install -g apollo-prophecy
```
Install with yarn:
```sh
yarn global add apollo-prophecy
```
## Usage
```
Usage: apollo-prophecy [command]
Commands:
apollo-prophecy generate [--out]
apollo-prophecy ask [--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.
```sh
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:
```json
{
"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`
```ts
...
export class AuthenticationRequiredError extends ProphecyError {
constructor(properties?: Record) {
super("AuthenticationRequiredError", "You must be logged in to do this","AUTH_REQUIRED", properties);
}
}
export class UserNotFoundError extends ProphecyError {
constructor(properties?: Record) {
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](###client).
```ts
...
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](#helpers)) for all the errors exposed through the server api documentation.
```sh
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*.
```ts
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.
```ts
import { isThis } from `./_generated/Errors.ts`;
...(error) => {
isThis(error)
.UserNotFoundError(() => ...)
.NotAProphetError(() => ...)
.handle()
}
```
React example:
```tsx
import { isThis } from `./_generated/Errors.ts`;
...(error) => {
return
{
isThis(error)
.UserNotFoundError(() => Could not find a user with tha name)
.NotAProphetError(() => Only Prophets can perfom this kind of actions...)
.handle();
}
}
```
## Contributing
[](https://travis-ci.com/theGlenn/apollo-prophecy)
✊Grab an issue ⏬
🍴fork develop ⏬
👨💻Code ⏬
🛠Test ⏬
📩Pull Request ⏬
💥💥💥
### TODO
* See [#2][i2]: Add support for third-party errors libraries like [apollo-errors](https://github.com/thebigredgeek/apollo-errors) good first issue
* See [#12][i12]: Add `errors.json` file as ask command argument good first issue
* See [#16][i16]: Add language specific code generation [Java/Kotlin][i13]/[Swift][i14]/[Javascript][i15]
* See [#13][i13]: Java/Kotlin good first issue
* See [#14][i14]: Swift good first issue
* See [#15][i15]: Javascript good first issue
[i2]: https://github.com/theGlenn/apollo-prophecy/issues/2
[i12]: https://github.com/theGlenn/apollo-prophecy/issues/12
[i13]: https://github.com/theGlenn/apollo-prophecy/issues/13
[i14]: https://github.com/theGlenn/apollo-prophecy/issues/14
[i15]: https://github.com/theGlenn/apollo-prophecy/issues/15
[i16]: https://github.com/theGlenn/apollo-prophecy/issues/16
### Run tests
```sh
npm test
```
```sh
yarn test
```