ybogomolov / fetcher-ts

Type-safe wrapper around Fetch API

Hey there! 👋

I'm Yuriy Bogomolov, a seasoned software architect with a passion for functional programming, type systems, and category theory. You might recognize me from my work on #MonadicMondays, my lectures and workshops on YouTube, or my contributions to the fp-ts ecosystem. And if you're looking for some additional resources, I also write articles on my personal blog that cover everything from the basics of functional programming to advanced techniques and best practices.

Are you an individual developer or part of a small team looking to level up your functional programming skills in TypeScript? Look no further, because I'm here to help. As a mentor, I offer personalized guidance and support as you navigate the complex world of functional programming. Whether you're just starting out or looking to take your skills to the next level, I'll work with you to develop a customized learning plan that fits your unique needs and goals.

So why wait? Let's start your journey towards mastering functional programming in TypeScript today. You can reach me via email at [email protected], or shoot me a message on Telegram - I'm always happy to chat!

fetcher-ts's Issues

Feedback

Based on the following (self imposed) requirements:

• the library shouldn't be tied to io-ts
• the library shouldn't be tied to cross-fetch
• decoding shouldn't be optional (not recommended but you can always resort to a dummy decoder like E.right)
• a handler for unexpected errors shouldn't be optional

I would propose an API like this:

import * as E from 'fp-ts/lib/Either'
import { ReaderEither } from 'fp-ts/lib/ReaderEither'
import { TaskEither } from 'fp-ts/lib/TaskEither'

type _Fetch = typeof fetch

export interface Fetch extends _Fetch {}

export interface Decoder<E, A> extends ReaderEither<unknown, E, A> {}

type Status = 200 | 400 | 500 // etc...

export type FetcherError =
  | { readonly type: 'JsonDeserializationError'; readonly details: unknown }
  | { readonly type: 'HandlerNotSetError'; readonly status: number }

export interface Fetcher<S extends Status, E, A> {
  readonly input: RequestInfo
  readonly handlers: Record<S, Decoder<E, A>>
  readonly onUnexpectedError: (error: FetcherError) => E.Either<E, A>
  readonly init?: RequestInit
}

export function make<S extends Status, E, A>(
  input: RequestInfo,
  handlers: Record<S, Decoder<E, A>>,
  onUnexpectedError: (error: FetcherError) => E.Either<E, A>,
  init?: RequestInit
): Fetcher<S, E, A> {
  return { input, onUnexpectedError, handlers, init }
}

export function toTaskEither(fetch: Fetch): <S extends Status, E, A>(fetcher: Fetcher<S, E, A>) => TaskEither<E, A> {
  // sketch implementation
  return <S extends Status, E, A>(fetcher: Fetcher<S, E, A>) => async () => {
    const isStatus = (status: number): status is S => fetcher.handlers.hasOwnProperty(status)
    const response = await fetch(fetcher.input, fetcher.init)
    const status = response.status
    if (isStatus(status)) {
      try {
        const contentType = response.headers.get('content-type')
        const body: unknown =
          contentType?.includes('application/json') !== undefined ? await response.json() : await response.text()
        const handler = fetcher.handlers[status]
        return handler(body)
      } catch (details) {
        return fetcher.onUnexpectedError({ type: 'JsonDeserializationError', details })
      }
    } else {
      return fetcher.onUnexpectedError({ type: 'HandlerNotSetError', status })
    }
  }
}

Example

import * as t from 'io-ts'
import { failure } from 'io-ts/lib/PathReporter'
import { flow } from 'fp-ts/lib/function'
import { fetch } from 'cross-fetch'

const taskify = toTaskEither(fetch)

type MyError = { readonly type: 'unexpectedError' } | { readonly type: 'decodeError'; readonly message: string }

const unexpectedError: MyError = { type: 'unexpectedError' }

const decodeError = (errors: t.Errors): MyError => ({
  type: 'decodeError',
  message: failure(errors).join('\n')
})

const getFetcher = (url: string): Fetcher<200 | 400, MyError, string> =>
  make(
    url,
    {
      200: flow(
        t.type({ title: t.string }).decode,
        E.bimap(decodeError, user => user.title)
      ),
      400: flow(t.string.decode, E.mapLeft(decodeError))
    },
    () => E.left(unexpectedError)
  )

// te: TaskEither<Err, string>
const te = taskify(getFetcher('https://jsonplaceholder.typicode.com/posts/1'))

te().then(console.log)
/*
{ _tag: 'Right',
  right:
   'sunt aut facere repellat provident occaecati excepturi optio reprehenderit' }
*/

taskify(getFetcher('https://jsonplaceholder.typicode.com/posts'))().then(console.log)
/*
{ _tag: 'Left',
  left:
   { type: 'decodeError',
     message:
      'Invalid value undefined supplied to : { title: string }/title: string' } }
*/

Map breaks, because extractor is not pushed into handlers when calling map?

While using the sample from README.

Could not deserialize response JSON, details: TypeError: extractor is not a function

Unwanted call for handler in case of failing io-ts codec

https://github.com/YBogomolov/fetcher-ts/blob/develop/src/fetcher.ts#L167

Handler is called for error case which seems incorrect as for me

1. handler usually expecting to get completely valid object, while it might be null or something invalid
2. usually it will break the code and original io-ts will be lost with catched 'Handler side error, details' error

Why does the return type has a optional decode Error?

I've been scratching my head not able to figure out the reason for the run()'s return type's signature. Is it possible to have a decode error while also having an output?

I was expecting a return type of run() to be Either<io.Error, To>, where To itself can be an Either.

What was the reason to have a tuple with an optional decode error?

Response headers are lost

Currently response is treated either as JSON or as text. No header information is extracted during processing. This may be required for codes like 202/204, as they usually carry no useful payload in the body of response.