wasp-graphql

0.3.6 • Public • Published

wasp-graphql

npm Build Status npm bundle size (minified) code style: prettier

contributions welcome All Contributors GitHub

Execute a GraphQL query exactly like you would a fetch request. No dependencies included.

Takes a url and an init object as input. Returns a Promise containing the results of the request.

// fetch
fetch('/graphql', { body: JSON.stringify({ query: '{ foo { bar baz } }' }) })
 
// query
import { query } from 'wasp-graphql'
query('/graphql', { fields: '{ foo { bar baz } }' })
 
// Logging the results
fetch(url, init)
  .then(res => res.json())
  .then(json => console.log(json))
query(url, init)
  .then(res => res.json())
  .then(json => console.log(json))

For additional features unique to Redux, check out redux-wasp and redux-wasp-apollo.

For a live, full-stack application showcasing this library in action, visit The Buzz.

Installation

Install via npm:

npm install --save wasp-graphql

Install via yarn:

yarn add wasp-graphql

Requires fetch to be in scope.

Use

// ES6 (with Destructuring)
import { query } from 'wasp-graphql'
 
// ES6
import Wasp from 'wasp-graphql'
const query = Wasp.query
 
// ES5
var Wasp = require('wasp-graphql')
var query = Wasp.query

How It Works

How to query a GraphQL server.

Write a string to request data ("fields") from a GraphQL endpoint.

Given an example string:

var myFields = `{
  hero {
    name
    friends {
      name
    }
  }
}`

Pass the query string alone as the second argument...

import { query } from 'wasp-graphql'
query('/my/url/endpoint', myFields)

Or as a property called fields for the second argument...

import { query } from 'wasp-graphql'
 
query('/my/url/endpoint', { fields: myFields })
// Any `fetch` init property can be included as well
query('/my/url/endpoint', { fields: myFields, mode: 'no-cors' })

Or as part of a fully customized body property (ADVANCED).

import { query } from 'wasp-graphql'
 
// Remember that `body` must be a JSON parsable string. Also, many GQL
//    servers will expect fields to be sent under a `body.query` property.
const init = {
  body: JSON.stringify({
    query: myFields
  }),
  credentials: 'include'
}
query('/my/url/endpoint', init)

Then, you can unpack the results of query with .json():

import { query } from 'wasp-graphql'
 
query('/my/url/endpoint', init)
  .then(response => {
    console.log(response.json()) // my data
  })
  .catch(error => {
    console.log(error) // my error
  })

As a thin wrapper over the Fetch API, anything that applies to fetch will also apply to query as well.

Variables

About dynamic arguments

GraphQL variables can be passed on as a separate property named variables.

import { query } from 'wasp-graphql'
 
query(url, { fields: myFields, variables: myVariables })

A longer example:

import { query } from 'wasp-graphql'
 
const url = '/api/starwars'
const fields = `
  query HeroNameAndFriends($episode: Episode) {
    hero(episode: $episode) {
      name
      friends {
        name
      }
    }
  }
`
const variables = {
  episode: 'JEDI'
}
 
query(url, { fields, variables })
  .then(res => res.json())
  .then(json => {
    console.log(json)
  })
 
// A custom body property can be used as well
query(url, { body: JSON.stringify({ fields, variables }) }).then(/* ... */)

Examples of good SYNTAX

import { query } from 'wasp-graphql'
 
// fields as a second argument
query('/foo/bar', '{foo { bar baz }}')  // good
 
// extended fields as a second argument
query('/myendpoint', 'query myQuery { field1 field2 { subfield1 } }')  // good
 
// with a fields as a property and the default settings
query('/myurl', { fields: '{foo { bar }}' })  // good
 
// with a fields as a property and custom fetch options
const config = {
  fields: 'query FooBarBaz {foo bar baz}',
  cache: 'no-cache',
  mode: "same-origin"
}
query('/myurl', config)  // good
 
// Remember that `body` must be a JSON parsable string. Also, many GQL
//    servers will expect fields to be sent under a `body.query` property.
//    GQL variables can be sent under `body.variables`.
const init = {
  body: JSON.stringify({
    query: myFields,
    variables: '{ "name": "Batman" }'
  }),
  credentials: 'include',
  mode: 'same-origin'
}
query('/my/url/endpoint', init)  // good
 
// With a fully custom init object.  Body must be a JSON parsable string
//    with a query property.
const init = {
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  }
  body: JSON.stringify({
    query: myFields,
    variables: '{ "name": "Batman" }'
  }),
  credentials: 'include',
  mode: 'same-origin'
}
query('/my/url/endpoint', init)  // good

Important note: If you add your own headers to the init object, the default headers will be overwritten. If this causes an issue, including these with your custom headers should resolve it:

{
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

Examples of broken SYNTAX

// No arguments
query() // bad
 
// No second argument
query('/foo/bar') // bad
 
// An invalid second argument
query('/foo/bar', []) // bad
 
// Empty strings
query('', '') // bad
 
// Misconfigured init object (missing a body property)
query('/foo', { cache: 'no-cache' }) // bad
 
// Misconfigured body property (did not use JSON.stringify())
query('/foo', { body: { query: '{foo bar}' } }) // bad
 
// if the first argument isn't an endpoint, nothing is fetched
query('I AM NOT A URL', '{ foo bar baz }') // bad
 
// if the second argument is a string, but not a valid query string,
//      then the server won't be able to do anything with it
query('/foo', 'I AM NOT A STRING OF GRAPHQL FIELDS') // bad

API

Quick Reference

import { query, mutation } from 'wasp-graphql'

query(url: string, init: string | Object)

/**
 * Provides a thin, GQL-compliant wrapper over the Fetch API.
 *
 * SYNTAX: query(url, init)
 
 * @param {string} url - The url for the intended resource
 * @param {(string|Object)} init - Can be a string of fields or a configuration object
 * @param {string} [init.fields] - GQL fields: Will be added to the body of the request
 * @param {Object} [init.variables] - GQL variables: Will be added to the body of the request
 * // For additional valid arguments, see the Fetch API:
 * // https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch
 *
 * Default init properties
 * @param {string} [init.method='POST'] 
 * @param {Object} [init.headers={ 'Content-Type': 'application/json', 'Accept': 'application/json' }] 
 *
 * @returns {Promise} 
 */
 
import { query } from 'wasp-graphql'

mutation(url: string, init: string | Object)

Alias for query.


Changelog

View it here

Contributing

Read more

Contributors

Thanks goes to these wonderful people:


Denny Temple


Reynolds A Colon


kamo31


marceca

This project follows the all-contributors specification. Contributions of any kind welcome!

Code of Conduct

Read our Code of Conduct here.

License

Free and Open Source under the MIT License.

Dependents (1)

Package Sidebar

Install

npm i wasp-graphql

Weekly Downloads

6

Version

0.3.6

License

MIT

Unpacked Size

13.7 kB

Total Files

5

Last publish

Collaborators

  • dentemple
  • marceca
  • rcolon100