gretchen

library1.5.1jsnpmunverified

A TypeScript-first HTTP client that wraps fetch with safe error handling, typed responses, configurable retries, timeouts, and support for Retry-After headers. Current stable version is 1.5.1, with infrequent releases. Unlike axios or got, it never throws on non-2xx responses, exposing both success and error types. Ships with TypeScript definitions, targets modern browsers, and requires minimal polyfills for IE11 or Node.js. It's small (under 3KB minzip) and provides a fluent API similar to fetch but with convenience methods like `.json()` and `.flush()`.

devops

npm install gretchen

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRETCHEN

gretchen

devopsjavascriptv1.5.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

gretch

✓ import { gretch } from 'gretchen'

✗ const gretch = require('gretchen')

gretchen is ESM only; require() will cause a runtime error in Node.js.

createInstance

✓ import { createInstance } from 'gretchen'

createInstance is a named export. It creates a custom gretch instance with base URL and default options.

GretchenDefaults

✓ import type { GretchenDefaults } from 'gretchen'

✗ import { GretchenDefaults } from 'gretchen'

GretchenDefaults is a TypeScript type, not a value. Import it using 'import type' to avoid runtime errors.

Shows basic usage with type safety: fetch a user, handle errors without try/catch, and parse JSON response.

import { gretch } from 'gretchen'; async function getUser(id: string) { const { data, error, response } = await gretch(`/api/user/${id}`).json(); if (error) { console.error('Request failed', error); return; } console.log('User:', data); } getUser('123');

Debug

Known issues

breakinggretchen is ESM only. CommonJS require() will fail.

fix

Use import syntax, or set { "type": "module" } in package.json if using Node.js.

affects: >=1.0.0

gotchagretchen does not throw on non-2xx responses. The error object in the response is only populated for network failures or non-2xx status codes when retries are exhausted.

fix

Always check the error property; do not rely on try/catch for HTTP errors.

affects: >=0.0.0

deprecatedThe 'flush()' method may be deprecated in future versions. Use '.text()' or '.blob()' if you don't need JSON parsing.

fix

Prefer .text() or .blob() over .flush() for non-JSON responses.

affects: >=1.5.0

gotchaTimeout option does not cancel the underlying fetch request, only rejects the promise. The request may complete server-side.

fix

Use AbortController directly if you need to cancel the request.

affects: >=0.0.0

gotchaRetry delay defaults to exponential backoff with a base of 1000ms. The Retry-After header is respected but only if present with a numeric value.

fix

Override delay option if you need custom retry intervals.

affects: >=0.0.0

breakingIn v0.x, the response shape returned { body, status, headers }. In v1.x it returns { data, error, response }.

fix

Update code to destructure { data, error, response } instead of { body }.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: gretch is not a function

Using default import instead of named import: import gretch from 'gretchen'

fix

Change to: import { gretch } from 'gretchen'

SyntaxError: Cannot use import statement outside a module

Running code in a CommonJS environment without ESM support.

fix

Add "type": "module" to package.json, or use .mjs extension.

TS2304: Cannot find name 'gretch'

TypeScript unable to resolve the import due to missing types or incorrect module resolution.

fix

Ensure gretchen is installed and that you are using 'import { gretch } from 'gretchen' with correct casing.

Error: fetch is not defined

Using gretchen in Node.js environment without a fetch polyfill.

fix

Install and import 'node-fetch' or use a global polyfill like 'cross-fetch'.

Upgrade

Version history

1.5.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

Amazon

Resources

githubssh://git@github.com/truework/gretchen ↗

packagegretchen ↗

homepagehttps://github.com/truework/gretchen#readme ↗