Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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: 17 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 (over 6 years ago)
Default Branch: master
Last Pushed: 2023-01-06T15:40:12.000Z (almost 2 years ago)
Last Synced: 2024-09-29T09:19:25.438Z (about 2 months ago)
Topics: apollo, apollo-codegen, apollographql, code-generation, error-handling, graphql, graphql-tools, typescript
Language: TypeScript
Homepage:
Size: 838 KB
Stars: 86
Watchers: 4
Forks: 3
Open Issues: 25
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE

Awesome Lists containing this project

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 

[![Build status](https://travis-ci.com/theGlenn/apollo-prophecy.svg?branch=master&style=flat-square)](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

```