🐝 wasp-graphql 🐝
Queries a GraphQL endpoint with syntax similar to a fetch
request. Accepts a url
and a settings object, and returns a Promise
that can resolve the request.
Promise
and fetch
must either be in scope, or passed in as a third argument part.
No additional dependencies are installed.
Fully compatible with RESTful APIs.
Useful Links
redux-wasp
: Promise-based GraphQL library for Reduxredux-wasp-apollo
: Promise-based GraphQL library for keeping query state in sync between Redux & Apollo
Table of Contents
- Quick Usage
- Compatibility
- Usage Guide
- Library API
Quick Usage
MDN Documentation: Using Fetch
wasp-graphql
strives to match the Fetch API as closely as possible.
/* Installation */npm install --save wasp-graphql
/* Imports */;
/** * Syntax: query(url, init, customEnv) * * @param * @param * @param * @returns */ const myUrl = '/api/my-custom-resource'const myHeaders = 'Content-Type': 'application/json' // #1 argument: The url for the intended resource // #2 argument: Object properties for configuring the request // An even shorter shortcut for when no custom request properties are required // #3 argument (rare)// Only necessary if fetch or Promise is not in scope.// Use this argument to pass in custom versions.
/* Usage example */; const url = '/api/my-custom-resource';const init = headers: 'Content-Type': 'application/json' query: '{foo { bar }}'; const myResults = ;
See How It Works for additional usage examples.
Compatibility
- Tested against Node.js v6+ (including latest version)
- Requires
fetch
to be either saved to the global scope or passed in as a configuration parameter
Fetch as Global/Fetch API
TODO
Ways to install fetch
:
Fetch as Parameter
See Configuration Parameters
TODO
Usage Guide
Installation
Install via npm:
// npmnpm install --save wasp-graphql // yarnyarn add wasp-graphql
How to Import
// ES5var Wasp = ;var query = Waspquery; // ES6;const query = Waspquery; // ES6 + Object Destructuring;
How It Works
Making a request
wasp-graphql
**Making a
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...
;;
Or as a property called fields
for the second argument...
; ;// Any `fetch` init property can be included as well;
Or as part of a fully customized body
property (ADVANCED).
; // 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 credentials: 'include';;
Then, you can unpack the results of query with .json()
:
; ;
Variables
GraphQL variables can be passed on as a separate property named variables
.
; ;
A longer example:
; const url = '/api/starwars';const fields = ` query HeroNameAndFriends($episode: Episode) { hero(episode: $episode) { name friends { name } } }`;const variables = episode: 'JEDI'; ; // A custom body property can be used as well;
Examples of good SYNTAX
// fields as a second argument // good // extended fields as a second argument // good // with a fields as a property and the default settings // good // with a fields as a property and custom fetch optionsconst config = fields: 'query FooBarBaz {foo bar baz}' cache: 'no-cache' mode: "same-origin" // 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 credentials: 'include' mode: 'same-origin' // 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 credentials: 'include' mode: 'same-origin' // 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; // bad // No second argument; // bad // An invalid second argument; // bad // Empty strings; // bad // Misconfigured init object (missing a body property); // bad // Misconfigured body property (did not use JSON.stringify()); // bad // if the first argument isn't an endpoint, nothing is fetched; // 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; // bad
Library API
Quick Reference
;
query(url: string, init: string | Object)
/** * Provides a thin, GQL-compliant wrapper over the Fetch API. * * SYNTAX: query(url, init) * @param * @param * @param * @param * // For additional valid arguments, see the Fetch API: * // https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch * * Default init properties * @param * @param * * @returns */ ;
mutation(url: string, init: string | Object)
Alias for query
.
Changelog
View it here
Contributing
Contributors
Thanks goes to these wonderful people:
Contributors
Thanks goes to these wonderful people:
Denny Temple | Reynolds A Colon | marceca | kamo31 |
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.