Provides fetch, Headers, Request and Response global definitions that can be used in all environments. It makes it easy to have the global TypeScript definitions without having to have all of the core TypeScript browser definitions.

This makes it much simpler to write code that works in both browser and JavaScript engines. At runtime an implementation of the specification will need to be installed in the global scope.

The interfaces provide a confirmed working subset of the specification that works in both JavaScript environments and also browsers. This eliminates using methods or properties that do not work in both situations.

Usage

// Expose the global definitions
import '@ef-carbon/fetch';

// Use the global definitions
const response = await fetch('https://my.url.com');
const res = new Response('data');
const req = new Request('https://my.url.com');
const hdrs = new Headers({ 'a': 'b' });

It is also possible to use export shims to the global variables:

// Import the shims, this forward to the globals
import fetch, { Response, Request, Headers } from '@ef-carbon/fetch';

// Use the global definitions
const response = await fetch('https://my.url.com');
const res = new Response('data');
const req = new Request('https://my.url.com');
const hdrs = new Headers({ 'a': 'b' });

There are interfaces that can be used to provide strongly typed APIs:

import {
  IHeadersMutable,
  IHeadersImmutable,
  IHeadersConstructible,
  IRequestMutable,
  IRequestImmutable,
  IResponseMutable,
  IResponseImmutable,
} from '@ef-carbon/fetch';

function headersImmutable(headers: IHeadersImmutable): void {
  headers.set('a', 'b');  // Compiler error
}

function headersMutable(headers: IHeadersMutable): void {
  headers.set('a', 'b');  // Allowed
}

function headersConstruct(Klass: IHeadersConstructible): IHeadersMutable {
  return new Klass({ 'a': 'b' });
}

const headers = headersConstruct(Headers);
headersImmutable(headers);
headersMutable(headers);

function requestImmutable(request: IRequestImmutable): void {
  request.set('a', 'b');  // Compiler error
}

function requestMutable(request: IRequestMutable): void {
  request.set('a', 'b');  // Allowed
}

function requestConstruct(Klass: IRequestConstructible): IRequestMutable {
  return new Klass({ 'a': 'b' });
}

const request = requestConstruct(Request);
requestImmutable(request);
requestMutable(request);

function responseImmutable(response: IResponseImmutable): void {
  response.set('a', 'b');  // Compiler error
}

function responseMutable(response: IResponseMutable): void {
  response.set('a', 'b');  // Allowed
}

function responseConstruct(Klass: IResponseConstructible): IResponseMutable {
  return new Klass({ 'a': 'b' });
}

const response = responseConstruct(Response);
responseImmutable(response);
responseMutable(response);

Installation of Classes

The global function and classes will need to be available when the code is actually ran. All evergreen browsers now have the implementations but older browsers and non-browser JavaScript engines will need an implementation installed.

Browsers

As most browsers already have the implementation, feature detection should be used to determine if a polyfill should be loaded. As front-end development changes rapidly it is hard to provide a concrete solution. Check the blogosphere for the current best practices.

JavaScript Engines

There is an installation helper script available to JavaScript engines:

import '@ef-carbon/fetch/install';

This installs the appropriate polyfill for the JavaScript environment. By default, the UMD bundle automatically loads the correct polyfill; therefore in Node and React Native, no extra polyfill is needed.