ketting

library9.1.0jsnpmunverified

Opinionated HATEOAS / REST client for JavaScript and TypeScript, currently at version 9.1.0. Released under the MIT license, with active development. Supports multiple hypermedia formats including HAL, JSON:API, Siren, Collection+JSON, and HTML links. Designed for both browser and Node.js environments, built on top of the Fetch API. Provides middleware support for authentication (e.g., OAuth2) and integrates with React via companion library react-ketting. Requires Node.js >=20.

devops

npm install ketting

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · KETTING

ketting

devopsjavascriptv9.1.0

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.

Ketting

✓ import { Ketting } from 'ketting'

✗ const Ketting = require('ketting');

ESM-only since v9; CommonJS require will fail for the main entry.

Resource

✓ import { Resource } from 'ketting'

TypeScript type import for a resource object returned by follow/get methods.

createResource

✓ import { createResource } from 'ketting'

✗ import createResource from 'ketting';

createResource is a named export, not default. Use named import syntax.

Initialize Ketting, follow a link, read state, modify data, and save via PUT.

import { Ketting } from 'ketting'; const ketting = new Ketting('https://api.example.org/'); async function main() { const author = await ketting.follow('author'); const authorState = await author.get(); console.log(authorState.data); authorState.data.firstName = 'Evert'; await author.put(authorState); } main().catch(console.error);

Debug

Known issues

breakingKetting v9 drops CommonJS support and requires Node >=20. Ensure your environment is up to date.

fix

Use ESM imports (import { Ketting } from 'ketting') and upgrade Node to >=20.

affects: >=9.0.0

breakingKetting v8 removed the `fetch` option from constructor in favor of custom fetch via middleware.

fix

Use fetch-mw-oauth2 or implement a custom fetch middleware if you need custom fetch behavior.

affects: >=8.0.0

gotchaThe `follow` method returns a Resource object, not the actual data. You must call `.get()` on it.

fix

Use `const resource = await ketting.follow('link'); const state = await resource.get();`

affects: >=7.0.0

gotchaWhen using PUT, you must pass a state object that is the same as what was returned by `.get()` (or a clone). Do not construct a new object from scratch.

fix

Always base your PUT state on the result of `.get()` to preserve metadata.

affects: >=7.0.0

Errors

Common errors & fixes

Ketting is not a constructor

Using CommonJS require on an ESM-only package.

fix

Switch to ESM imports: `import { Ketting } from 'ketting'`

fetch is not defined

Ketting requires the global `fetch` API which is available natively in Node 18+ and modern browsers.

fix

If using Node <18, install and import `node-fetch` and set it as global: `globalThis.fetch = require('node-fetch');`

TypeError: Cannot read properties of undefined (reading 'data')

Calling `.data` on a state object that is undefined, typically because `.get()` was not awaited or the resource does not exist.

fix

Ensure you await `resource.get()` and check for HTTP errors (e.g., 404). Wrap in try/catch.

Upgrade

Version history

9.1.0latest on npm

Audit

Dependencies

fetch-mw-oauth2optionalOAuth2 middleware for authentication flows

Agent activity

9 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/badgateway/ketting ↗

packageketting ↗

homepagehttps://github.com/badgateway/ketting#readme ↗