Negatory. Postpone Mission.

    TypeScript icon, indicating that this package has built-in type declarations

    0.1.2 • Public • Published

    gretchen npm

    Making fetch happen in Typescript.

    ⚠️ This is beta software, and it might not be ready for production use just yet. However, if you'd like to try it out or contribute, we'd love that and we'd love to hear your thoughts.


    • safe: will not throw on non-200 responses
    • precise: allows for typing of both success & error responses
    • resilient: configurable retries & timeout
    • smart: respects Retry-After header
    • small: won't break your bundle


    npm i @truework/gretchen --save

    Browser Support

    gretchen targets all modern browsers. For IE11 support, you'll need to polyfill fetch, Promise, and Object.assign. For Node.js, you'll need fetch and AbortController.


    Basic usage looks a lot like window.fetch:

    import { gretch } from "@truework/gretchen";
    const request = gretch("/api/user/12");

    The request will be made immediately, but to await the response and consume any response data, use any of the standard fetch body interface methods:

    const response = await request.json();

    gretchen responses are somewhat special. In Typescript terms, they employ a discriminated union to allow you to type and consume both the success and error responses returned by your API.

    In a successful response, the object will look something like this:

      url: string,
      status: number,
      data: object, // Response body
      error: undefined,

    And for an error response it will look something like this:

      url: string,
      status: number,
      data: undefined,
      error: object, // Response body, or an Error


    gretchen defaults to GET requests, and sets credentials to same-origin.

    To make different types of requests, or edit headers and other request config, pass a config object:

    const response = await gretch("/api/user/12", {
      credentials: "include",
      headers: {
        "Tracking-ID": "abcde12345"

    Configuring requests bodies should look familiar as well:

    const response = await gretch("/api/user/12", {
      method: "PATCH",
      body: JSON.stringify({
        email: ``

    For convenience, there’s also a json shorthand. We’ll take care of stringifying the body:

    const response = await gretch("/api/user/12", {
      method: "PATCH",
      json: {
        name: "Megan Rapinoe",
        occupation: "President of the United States"


    gretchen will automatically attempt to retry some types of requests if they return certain error codes. Below are the configurable options and their defaults:

    • attempts - a number of retries to attempt before failing. Defaults to 2.
    • codes - an array of number status codes that indicate a retry-able request. Defaults to [ 408, 413, 429 ].
    • methods - an array of strings indicating which request methods should be retry-able. Defaults to [ "GET" ].
    • delay - a number in milliseconds used to exponentially back-off the delay time between requests. Defaults to 6. Example: first delay is 6ms, second 36ms, third 216ms, and so on.

    These options can be set using the configuration object:

    const response = await gretch("/api/user/12", {
      retry: {
        attempts: 3


    By default, gretchen will time out requests after 10 seconds and retry them, unless otherwise configured. To configure timeout, pass a value in milliseconds:

    const response = await gretch("/api/user/12", {
      timeout: 20000


    gretchen uses the concept of "hooks" to tap into the request lifecycle. Hooks are good for code that needs to run on every request, like adding tracking headers and logging errors.


    The before hook runs just prior to the request being made. You can even modify the request directly, like to add headers. The before hook is passed the Request object, and the full options object.

    const response = await gretch("/api/user/12", {
      hooks: {
        before(request, options) {
          request.headers.set("Tracking-ID", "abcde");


    The after hook has the opportunity to read the gretchen response. It cannot modify it. This is mostly useful for logging.

    const response = await gretch("/api/user/12", {
      hooks: {
        after({ url, status, data, error }) {
          sentry.captureMessage(`${url} returned ${status}`);


    gretchen also exports a create method that allows you to configure default options. This is useful if you want to attach something like logging to every request made with the returned instance.

    import { create } from "@truework/gretchen";
    const gretch = create({
      headers: {
        "X-Powered-By": "@truework/gretchen"
      hooks: {
        after({ error }) {
          if (error) sentry.captureException(error);
    await gretch("/api/user/12").json();

    Usage with Typescript

    gretchen is written in Typescript and employs a discriminated union to allow you to type and consume both the success and error responses returned by your API.

    To do so, pass your data types directly to the gretch call:

    type Success = {
      name: string;
      occupation: string;
    type Error = {
      code: number;
      errors: string[];
    const response = await gretch<Success, Error>("/api/user/12").json();

    Then, you can safely use the responses:

    if (response.error) {
      const {
        code, // number
        errors // array of strings
      } = response.error; // typeof Error
    } else if ( {
      const {
        name, // string
        occupation // string
      } =; // typeof Success


    There are a lot of options out there for requesting data. Most modern fetch implementations, however, rely on throwing errors. For type-safety, we wanted something that would allow us to type the response, no matter what. We also wanted to bake in a few opinions of our own, although the API is flexible enough for most other applications.


    This library was inspired by ky and fetch-retry.


    MIT License © Truework

    cheap movie reference


    npm i @truework/gretchen

    DownloadsWeekly Downloads






    Unpacked Size

    115 kB

    Total Files


    Last publish


    • js-truework
    • manan_joshi
    • angelachang
    • truework-team