External module "fetcher"

fetcher

• fetcher(input: Init, init?: IInit): Promise<IResponseMutable>

• Provides an extended version of the WHATWG fetch API. It provides two notable additions:

  • It allows a default Check function is invoked on each response
  • It extends the response to provide verification and conversion of JSON

  The checker function can be set globally with {@link checkSet} or locally by providing { check: callback } as part of the initializer object. The checker function is invoked on the response. The default check function throws a FetchError when the response is not ok (i.e. the status is not in the range [200, 299]).

  The response is extended with extend to provide a json call that can accept Verify and Convert callbacks. These provide runtime assurance that a returned JSON payload actually conforms to a compile time interface. This prevents mismatches between compile time TypeScript checks and runtime operation.

  example

  Perform a checked response

  import { fetcher, FetchError } from '@ef-carbon/fetcher';
  
  const response = await fetcher('https://google.com');
  
  try {
    await fetcher('https://this.does.not.exist.com');
  } catch (error) {
    if(error instanceof FetchError) {
      console.error(`${error.status}: ${error.statusText}: ${await error.text()}`);
    }
    throw error;
  }
  

  example

  Perform no check on a request

  import { fetcher, checkNothing } from '@ef-carbon/fetcher';
  
  const response = await fetcher('https://google.com', { check: checkNothing });
  console.log(response.ok);  // true
  
  const response = await fetcher('https://this.does.not.exist.com', { check: checkNothing });
  console.log(response.ok);  // false
  

  example

  Perform verification of JSON payload

  import { Json, isIJsonObject } from '@ef-carbon/fetch';
  import { fetcher, Verify } from '@ef-carbon/fetcher';
  
  interface IData {
    name: string;
  }
  
  function isIData(json: Json): json is IData {
    return isIJsonObject(json) && typeof json.name === 'string';
  }
  
  const verify: Verify<IData> = isIData;
  
  // expected payload `{ "name": "Rick Sanchez" }`
  const response = await fetcher('http://endpoint.com/data.json');
  
  const data = response.json(verify);  // verification
  console.log(data.name);
  

  example

  Perform conversion of JSON payload

  import { Json, isIJsonObject } from '@ef-carbon/fetch';
  import { fetcher, Convert } from '@ef-carbon/fetcher';
  
  interface IData {
    name: string;
  }
  
  function isIData(json: Json): json is IData {
    return isIJsonObject(json) && typeof json.name === 'string';
  }
  
  function getName(json: Json): string {
    if (!isIData(json)) {
      throw TypeError(`Invalid JSON payload: ${JSON.stringify(json)}`);
    }
  
    return json.name;
  }
  
  const convert: Convert<string> = getName;
  
  // expected payload `{ "name": "Rick Sanchez" }`
  const response = await fetcher('http://endpoint.com/data.json');
  
  const name = response.json(convert);  // conversion
  console.log(name);
  

  see

  Check to understand more about checking the response with a callback

  see

  extend function for more information about the extensions provided

  Parameters

  • input: Init

  • Optional init: IInit

  Returns Promise<IResponseMutable>