fetchmap

fetchmap

Non-throwing fetch wrapper

Getting started

npm i fetchmap

Description

This is a simple wrapper for a fetch-like function that catches all possible exceptions and returns a 'success or failure' wrapped value. It takes an object that maps response.status to validating transform and standard fetch arguments. Read the docs here.

Example

// ----------------------------- server code -----------------------------
import express from 'express'

express()
  .get('/data', (_, res) => {
    const rnd = Math.random()

    if (rnd < 0.34) {
      res.status(200).json({ some: 'data' })
    } else if (rnd < 0.67) {
      res.status(201).send('This is not JSON!')
    } else {
      res.status(500).send('Server error!')
    }
  })
  .listen(5005)

// ----------------------------- client code -----------------------------
import { createFetchmap } from 'fetchmap'
import nodeFetch, { Response } from 'node-fetch'
import { isRecord } from 'ts-is-record'

// fetchmap compatible result creators
const success = <T>(value: T) => ({ tag: 'success', success: value } as const)
const failure = <T>(error: T) => ({ tag: 'failure', failure: error } as const)

// wrap any fetch-like function
const fetchmap = createFetchmap(nodeFetch)

// data is expected to be JSON, so it has to be validated
const validateData = (body: unknown) =>
  isRecord(body) && 'some' in body && typeof body.some === 'string'
    ? success(body)
    : failure('data validation failed' as const)

// error is just a string, in this example no validation needed
const validateError = (body: string, { status }: Response) => success({ message: body, status })

const dataResult = await fetchmap(
  {
    // for any response with a status inside inclusive range 200..299
    // call 'json' method and validate its result with `validateData` function
    ok: { json: validateData },

    // for any response with a status outside inclusive range 200..299
    // call 'text' method and validate its result with `validateError` function
    notOk: { text: validateError }
  },

  // first argument for a wrapped fetch function
  'https://localhost:5005/data',

  // second argument for a wrapped fetch function
  {
    // request options: method, headers, body etc.
  }
)

expect([
  { tag: 'success', success: { some: 'data' } },
  { tag: 'failure', failure: { serverError: { message: 'Server error!', status: 500 } } },
  {
    tag: 'failure',
    failure: { mapError: new SyntaxError('Unexpected token T in JSON at position 0') }
  }
]).toContainEqual(dataResult)

Usage

See test or playground

ts-railway - compatible result library