@beyonk/sapper-httpclient

    10.0.1 • Public • Published

    Beyonk

    Sapper HttpClient

    js-standard-style publish

    Sapper isomorphic fetch library

    Why

    In sapper, there are three different ways of fetching data:

    • client
    • server
    • isomorphic (client + server)
    • retries (on various network errors)

    This library helps you abstract over where you are fetching data, meaning that your code maintains consistency without having to worry about where your data is being fetched.

    The way it does this is by trying to use the first available fetch method, and failing over to alternatives if a method is not available. The methods it tries are, in the following order:

    1. Any fetch library you pass to create() (for example, preload's this.fetch)
    2. window.fetch if the library detects it is running clientside
    3. node-fetch, or whatever you want to pass in, if nothing else is available (pure server-side)

    Generally this means that your usage is the same no matter where you call it, with one exception - using this library in the preload method requires you to pass in Sapper's special this.fetch method, as it is not available outside of the preload method. Examples of which are below.

    Usage

    To use within a Sapper application:

    Install it

    npm i -D @beyonk/sapper-httpclient

    Configure it (both server-side and client-side as there are two bundles)

    // src/client.js && src/server.js
    import Api from '@beyonk/sapper-httpclient'
    
    Api.configure({ baseUrl: 'https://example.com/your/api/base' })

    Use it on the client:

    // src/routes/some-route.html
    import { create } from '@beyonk/sapper-httpclient'
    
    // in a method (client-side)
    const api = create()
    const json = await api.endpoint('some/endpoint').get()
    console.log(json)
    
    // in preload (isomorphic)
    const api = create()
    const json = await api
      .context(this) // Pass in "this" from preload, to sapper's built in "fetch" method, as well as providing this.redirect to handlers
      .endpoint('some/endpoint')
      .get()
    console.log(json)

    Use it on the server:

    // src/routes/some-route.js
    import fetch from 'node-fetch' // or Sapper's built in fetch
    import { create } from '@beyonk/sapper-httpclient'
    
    const api = create()
    const json = await api
      .context({ fetch }) // pass node fetch in here.
      .endpoint('some/endpoint')
      .get()
    console.log(json)

    Handling the response

    import { create } from '@beyonk/sapper-httpclient'
    
    const api = create()
    const json = await api
      .endpoint('some/endpoint')
      .get((json, httpStatus) => {
        console.log('json response is', json)
        console.log('http status code is', httpStatus)
      })

    Methods

    const api = create()
    const client = api
      .endpoint('some/endpoint')
    
    console.log(await client.get()) // Get endpoint
    console.log(await client.payload({ foo: 'bar' }).put()) // Put with body
    console.log(await client.payload({ foo: 'bar' }).post()) // Post with body
    console.log(await client.query({ foo: 'bar' }).get()) // Get with query
    console.log(await client.del()) // Delete
    console.log(await client.headers({ foo: 'bar' }).put()) // Put with headers

    client.query

    The query method accepts an object of params as either a String or Array of Strings. If any property passed into the query is undefined it will be ignored.

    const api = create()
    const client = api
      .endpoint('some/endpoint')
    
    console.log(await client.query({ foo: 'bar' }).get()) // will make a GET request to 'some/endpoint?foo=bar'
    console.log(await client.query({ foo: 'bar', baz: 'qux' }).get()) // will make a GET request to 'some/endpoint?foo=bar&baz=qux
    console.log(await client.query({ foo: ['bar', 'qux' ] }).get()) // will make a GET request to 'some/endpoint?foo=bar&foo=qux
    console.log(await client.query({ foo: undefined, baz: 'qux' }).get()) // will make a GET request to 'some/endpoint?baz=qux

    Using built in response handling

    const api = create()
    const profile = await api
      .endpoint('some/endpoint')
      .get(json => {
        return json.profile
      })
    console.log(profile)

    Catching errors

    Per request

    If no local error handler is specified, the fallback handler default is called. If this isn't specified, the error is logged to the console.

      await client
        .endpoint('some/url')
        .forbidden(e => {
          console.error('Forbidden', e)
        })
        .gone(e => {
          console.error('Gone', e)
        })
        .notFound(e => {
          console.error('Not found', e)
        })
        .accessDenied(e => {
          console.error('Access denied', e)
        })
        .conflict(e => {
          console.error('Conflict', e)
        })
        .paymentRequired(e => {
          console.error('Payment Required', e)
        })
        .preconditionFailed(e => {
          console.error('Precondition failed', e)
        })
        .badData(e => {
          console.error('Bad data', e)
        })
        .default(e => {
          // Any other error caught here
          console.error('Some error', e)
        })
        .get()

    Handler signature

    Handlers have a signature with two items:

    .badData((e, ctx) => {
      console.error('Bad data', e)
      ctx.redirect('/foo/bar')
      // or
      ctx.error('/foo/bar')
    })

    ctx can be whatever you want really - it is whatever you pass in as context(...).

    However, if the context object you pass in has a fetch function, this is used as the fetch for XHR requests, so that in sapper you can just pass the entire this object in preload:

    export async function preload () {
      await Api
        .context(this) // fetch, redirect, error.
        .endpoint('foo/bar')
        ...
    }

    you can also pass in other things to the context:

    export async function preload () {
      await Api
        .context({ ...this, baz: 'qux' })
        .endpoint('foo/bar')
        ...
    }

    At a global level

    Request local error handlers override global error handlers, but if a local error handler are not specified, these will be called instead, if it exists.

    Names are the same as the local handlers:

      import Api from '@beyonk/sapper-httpclient'
      import { goto } from '@sapper/app'
    
      Api.configure({
        baseUrl: 'https://example.com/your/api/base',
        handlers: {
          paymentRequired(e => {
            goto('/checkout')
          })
        }
      })
    
      await client
        .endpoint('some/url')
        .get()

    Retries

    The http client can retry if a network error is encountered. The default is retry: false, and requests won't be retried.

    Configure it as follows:

    import Api from '@beyonk/sapper-httpclient'
    
    Api.configure({
      retry: {
        attempts: 3 // How many times to retry before giving up
        errors: [ 'ECONNRESET' ] // A list of error codes
      }
    })

    errors is an array of any number of the nodejs network error codes

    Parsing error payloads

    As of v7.0.0 the library defaults to parsing error payloads as JSON. This means you can use the data returned in your response.

      /** endpoint returns 401 with:
        {
          username: 'Naughty User'
        }
      **/
    
      await client
        .endpoint('some/url')
        .accessDenied(e => {
          console.error('You are not allowed', e.body.username)
        })

    To turn this behaviour off, pass the option parseErrors with value false:

    import Api from '@beyonk/sapper-httpclient'
    
    Api.configure({
      parseErrors: false
    })

    Running Tests

    npm test

    Credits

    Install

    npm i @beyonk/sapper-httpclient

    DownloadsWeekly Downloads

    104

    Version

    10.0.1

    License

    MIT

    Unpacked Size

    102 kB

    Total Files

    21

    Last publish

    Collaborators

    • avatar
    • avatar