Necromancers Playing MTG

    @gechiui/api-fetch
    TypeScript icon, indicating that this package has built-in type declarations

    5.2.7 • Public • Published

    API Fetch

    Utility to make GeChiUI REST API requests. It's a wrapper around window.fetch.

    Installation

    Install the module

    npm install @gechiui/api-fetch --save

    This package assumes that your code will run in an ES2015+ environment. If you're using an environment that has limited or no support for such language features and APIs, you should include the polyfill shipped in @gechiui/babel-preset-default in your code.

    Usage

    import apiFetch from '@gechiui/api-fetch';
    
    // GET
    apiFetch( { path: '/gc/v2/posts' } ).then( ( posts ) => {
    	console.log( posts );
    } );
    
    // POST
    apiFetch( {
    	path: '/gc/v2/posts/1',
    	method: 'POST',
    	data: { title: 'New Post Title' },
    } ).then( ( res ) => {
    	console.log( res );
    } );

    Options

    apiFetch supports and passes through all options of the fetch global.

    Additionally, the following options are available:

    path (string)

    Shorthand to be used in place of url, appended to the REST API root URL for the current site.

    url (string)

    Absolute URL to the endpoint from which to fetch.

    parse (boolean, default true)

    Unlike fetch, the Promise return value of apiFetch will resolve to the parsed JSON result. Disable this behavior by passing parse as false.

    data (object)

    Shorthand to be used in place of body, accepts an object value to be stringified to JSON.

    Aborting a request

    Aborting a request can be achieved through the use of AbortController in the same way as you would when using the native fetch API.

    For legacy browsers that don't support AbortController, you can either:

    • Provide your own polyfill of AbortController if you still want it to be abortable.
    • Ignore it as shown in the example below.

    Example

    const controller =
    	typeof AbortController === 'undefined' ? undefined : new AbortController();
    
    apiFetch( { path: '/gc/v2/posts', signal: controller?.signal } ).catch(
    	( error ) => {
    		// If the browser doesn't support AbortController then the code below will never log.
    		// However, in most cases this should be fine as it can be considered to be a progressive enhancement.
    		if ( error.name === 'AbortError' ) {
    			console.log( 'Request has been aborted' );
    		}
    	}
    );
    
    controller?.abort();

    Middlewares

    the api-fetch package supports middlewares. Middlewares are functions you can use to wrap the apiFetch calls to perform any pre/post process to the API requests.

    Example

    import apiFetch from '@gechiui/api-fetch';
    
    apiFetch.use( ( options, next ) => {
    	const start = Date.now();
    	const result = next( options );
    	result.then( () => {
    		console.log( 'The request took ' + ( Date.now() - start ) + 'ms' );
    	} );
    	return result;
    } );

    Built-in middlewares

    The api-fetch package provides built-in middlewares you can use to provide a nonce and a custom rootURL.

    Nonce middleware

    import apiFetch from '@gechiui/api-fetch';
    
    const nonce = 'nonce value';
    apiFetch.use( apiFetch.createNonceMiddleware( nonce ) );

    The function returned by createNonceMiddleware includes a nonce property corresponding to the actively used nonce. You may also assign to this property if you have a fresh nonce value to use.

    Root URL middleware

    import apiFetch from '@gechiui/api-fetch';
    
    const rootURL = 'http://my-gechiui-site/gc-json/';
    apiFetch.use( apiFetch.createRootURLMiddleware( rootURL ) );

    Custom fetch handler

    The api-fetch package uses window.fetch for making the requests but you can use a custom fetch handler by using the setFetchHandler method. The custom fetch handler will receive the options passed to the apiFetch calls.

    Example

    The example below uses a custom fetch handler for making all the requests with axios.

    import apiFetch from '@gechiui/api-fetch';
    import axios from 'axios';
    
    apiFetch.setFetchHandler( ( options ) => {
    	const { url, path, data, method } = options;
    
    	return axios( {
    		url: url || path,
    		method,
    		data,
    	} );
    } );



    Code is Poetry.

    Install

    npm i @gechiui/api-fetch

    DownloadsWeekly Downloads

    66

    Version

    5.2.7

    License

    GPL-2.0-or-later

    Unpacked Size

    225 kB

    Total Files

    92

    Last publish

    Collaborators

    • gechiui