{"id":47985,"library":"gretchen","title":"gretchen","description":"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()`.","status":"active","version":"1.5.1","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/truework/gretchen","tags":["javascript","fetch","fetching","http","https","request","requests","get","url","typescript"],"install":[{"cmd":"npm install gretchen","lang":"bash","label":"npm"},{"cmd":"yarn add gretchen","lang":"bash","label":"yarn"},{"cmd":"pnpm add gretchen","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"gretchen is ESM only; require() will cause a runtime error in Node.js.","wrong":"const gretch = require('gretchen')","symbol":"gretch","correct":"import { gretch } from 'gretchen'"},{"note":"createInstance is a named export. It creates a custom gretch instance with base URL and default options.","wrong":"","symbol":"createInstance","correct":"import { createInstance } from 'gretchen'"},{"note":"GretchenDefaults is a TypeScript type, not a value. Import it using 'import type' to avoid runtime errors.","wrong":"import { GretchenDefaults } from 'gretchen'","symbol":"GretchenDefaults","correct":"import type { GretchenDefaults } from 'gretchen'"}],"quickstart":{"code":"import { gretch } from 'gretchen';\n\nasync function getUser(id: string) {\n  const { data, error, response } = await gretch(`/api/user/${id}`).json();\n  if (error) {\n    console.error('Request failed', error);\n    return;\n  }\n  console.log('User:', data);\n}\n\ngetUser('123');","lang":"typescript","description":"Shows basic usage with type safety: fetch a user, handle errors without try/catch, and parse JSON response."},"warnings":[{"fix":"Use import syntax, or set { \"type\": \"module\" } in package.json if using Node.js.","message":"gretchen is ESM only. CommonJS require() will fail.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Always check the error property; do not rely on try/catch for HTTP errors.","message":"gretchen 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.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Prefer .text() or .blob() over .flush() for non-JSON responses.","message":"The 'flush()' method may be deprecated in future versions. Use '.text()' or '.blob()' if you don't need JSON parsing.","severity":"deprecated","affected_versions":">=1.5.0"},{"fix":"Use AbortController directly if you need to cancel the request.","message":"Timeout option does not cancel the underlying fetch request, only rejects the promise. The request may complete server-side.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Override delay option if you need custom retry intervals.","message":"Retry delay defaults to exponential backoff with a base of 1000ms. The Retry-After header is respected but only if present with a numeric value.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Update code to destructure { data, error, response } instead of { body }.","message":"In v0.x, the response shape returned { body, status, headers }. In v1.x it returns { data, error, response }.","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.5.1':31 '2xx':45 '3kb':72 'api':78 'axio':36 'browser':59 'client':7 'configur':17 'conveni':84 'current':27 'definit':56 'error':13,51 'expos':47 'fetch':10,81,91,92 'first':5 'fluent':77 'flush':89 'get':97 'got':38 'gretchen':1 'handl':14 'header':26 'http':6,93 'https':94 'ie11':65 'infrequ':33 'javascript':90 'json':87 'like':86 'method':85 'minim':62 'minzip':73 'modern':58 'never':40 'node.js':67 'non':44 'non-2xx':43 'polyfil':63 'provid':75 'releas':34 'request':95,96 'requir':61 'respons':16,46 'retri':18,24 'retry-aft':23 'safe':12 'ship':53 'similar':79 'small':70 'stabl':28 'success':49 'support':21 'target':57 'throw':41 'timeout':19 'type':15,52 'typescript':4,55,99 'typescript-first':3 'unlik':35 'url':98 'version':29 'wrap':9","created_at":"2026-06-07T16:54:20.655581+00:00","updated_at":"2026-06-07T16:54:20.655581+00:00","problems":[{"fix":"Change to: import { gretch } from 'gretchen'","cause":"Using default import instead of named import: import gretch from 'gretchen'","error":"TypeError: gretch is not a function"},{"fix":"Add \"type\": \"module\" to package.json, or use .mjs extension.","cause":"Running code in a CommonJS environment without ESM support.","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Ensure gretchen is installed and that you are using 'import { gretch } from 'gretchen' with correct casing.","cause":"TypeScript unable to resolve the import due to missing types or incorrect module resolution.","error":"TS2304: Cannot find name 'gretch'"},{"fix":"Install and import 'node-fetch' or use a global polyfill like 'cross-fetch'.","cause":"Using gretchen in Node.js environment without a fetch polyfill.","error":"Error: fetch is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/truework/gretchen#readme","github":"ssh://git@github.com/truework/gretchen","docs":null,"changelog":null,"pypi":null,"npm":"gretchen","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}