{"id":30219147,"url":"https://github.com/mastert/jsonapi-metal-client","last_synced_at":"2026-04-18T04:01:53.245Z","repository":{"id":42993055,"uuid":"458798009","full_name":"masterT/jsonapi-metal-client","owner":"masterT","description":"Bare metal TypeScript and JavaScript client for web API implementing JSON:API v1.0","archived":false,"fork":false,"pushed_at":"2022-03-24T11:17:43.000Z","size":265,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-29T10:56:25.962Z","etag":null,"topics":["client","javascript","jsonapi","typescript"],"latest_commit_sha":null,"homepage":"https://mastert.github.io/jsonapi-metal-client/typescript/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/masterT.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-02-13T12:08:04.000Z","updated_at":"2024-01-08T19:26:13.000Z","dependencies_parsed_at":"2022-09-10T10:00:47.415Z","dependency_job_id":null,"html_url":"https://github.com/masterT/jsonapi-metal-client","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/masterT/jsonapi-metal-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masterT%2Fjsonapi-metal-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masterT%2Fjsonapi-metal-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masterT%2Fjsonapi-metal-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masterT%2Fjsonapi-metal-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/masterT","download_url":"https://codeload.github.com/masterT/jsonapi-metal-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masterT%2Fjsonapi-metal-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31955919,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","javascript","jsonapi","typescript"],"created_at":"2025-08-14T07:48:00.344Z","updated_at":"2026-04-18T04:01:53.233Z","avatar_url":"https://github.com/masterT.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JSON:API metal client\n\n[![Build](https://github.com/masterT/jsonapi-metal-client/actions/workflows/Build.yml/badge.svg)](https://github.com/masterT/jsonapi-metal-client/actions/workflows/Build.yml)\n[![npm version](https://badge.fury.io/js/jsonapi-metal-client.svg)](https://badge.fury.io/js/jsonapi-metal-client)\n\nBare metal TypeScript and JavaScript client for web API implementing [JSON:API v1.0](https://jsonapi.org/).\n\n- Zero dependency\n- Type-safe\n- Isomorphic\n\nDocumentations\n- [Typescript documentation](https://masterT.github.io/jsonapi-metal-client/typescript/)\n\n---\n\n## Table of Contents\n\n* [Requirements](#requirements)\n* [Installation](#installation)\n* [Usage](#usage)\n* [Documentation](#documentation)\n  + [HTTP adapter](#http-adapter)\n    - [Using `fetch`](#using-fetch)\n    - [Using `axios`](#using-axios)\n  + [Client](#client)\n    - [Configure custom HTTP headers](#configure-custom-http-headers)\n    - [Result](#result)\n    - [Specification](#specification)\n* [Development](#development)\n* [License](#license)\n\n## Requirements\n\n- ES6 (ECMAScript 2015)\n\n## Installation\n\nUsing _npm_:\n\n```shell\nnpm install -s jsonapi-metal-client\n```\n\nUsing _yarn_:\n\n```shell\nyarn add jsonapi-metal-client\n```\n\nWith ES6 modules:\n\n```js\nimport { HttpAdapters, JsonApi } from 'jsonapi-metal-client';\n```\n\nWith CommonJS modules:\n\n```js\nconst { HttpAdapters, JsonApi } = require('jsonapi-metal-client');\n```\n\n## Usage\n\n```js\nconst httpAdapter = new HttpAdapters.FetchHttpAdapter(window.fetch.bind(window));\nconst client = new JsonApi.Client(httpAdapter);\n\n// Fetch a resource collection.\nclient.fetch('https://example.com/articles');\nclient.fetchResource('https://example.com/articles');\nclient.fetchResourceCollection('https://example.com/articles');\n\n// Fetch an individual resource.\nclient.fetch('https://example.com/articles/1');\nclient.fetchResource('https://example.com/articles/1');\nclient.fetchResourceIndividual('https://example.com/articles/1');\n\n// Fetch relationship data representing a to-one relationship.\nclient.fetch('https://example.com/articles/1/relationships/author');\nclient.fetchRelationship('https://example.com/articles/1/relationships/author');\nclient.fetchRelationshipToOne('https://example.com/articles/1/relationships/author');\n\n// Fetch relationship data representing a to-many relationship.\nclient.fetch('https://example.com/articles/1/relationships/comments');\nclient.fetchRelationship('https://example.com/articles/1/relationships/comments');\nclient.fetchRelationshipToMany('https://example.com/articles/1/relationships/comments');\n\n// Create a resource.\nclient.createResource(\n  'https://example.com/comments',\n  {\n    data: {\n      type: 'photos',\n      attributes: {\n        title: 'Ember Hamster',\n        src: 'http://example.com/images/productivity.png'\n      },\n      relationships: {\n        photographer: {\n          data: { type: 'people', id: '9' }\n        }\n      }\n    }\n  }\n);\n\n// Update a resource.\nclient.updateResource(\n  'https://example.com/articles/1',\n  {\n    data: {\n      type: 'articles',\n      id: '1',\n      attributes: {\n        title: 'To TDD or Not'\n      }\n    }\n  }\n);\n\n// Delete a resource.\nclient.deleteResource('https://example.com/photos/1');\n\n// Update a to-one relationship.\nclient.updateRelationshipToOne(\n  'https://example.com/articles/1/relationships/author',\n  {\n    data: { type: 'people', id: '12' }\n  }\n);\n\n// Add a member to a to-many relationship.\nclient.createRelationshipToMany(\n  'https://example.com/articles/1/relationships/comments',\n  {\n    data: [\n      { type: 'comments', id: '123' }\n    ]\n  }\n);\n\n// Replace all members of a to-many relationship.\nclient.updateRelationshipToMany(\n  'https://example.com/articles/1/relationships/tags',\n  {\n    data: []\n  }\n);\n\n// Remove members from a to-many relationship.\nclient.deleteRelationshipToMany(\n  'https://example.com/articles/1/relationships/comments',\n  {\n    data: [\n      { type: 'comments', id: '12' },\n      { type: 'comments', id: '13' }\n    ]\n  }\n);\n```\n\n## Documentation\n\n- [Typescript documentation](https://masterT.github.io/jsonapi-metal-client/typescript/)\n\n### HTTP adapter\n\n#### Using `axios`\n\nHTTP Adapter using the [axios](://github.com/axios/axios).\n\n```js\nimport axios from 'axios'\n\nconst httpAdapter = new HttpAdapters.AxiosHttpAdapter(\n  axios\n);\n```\n\nUsing custom instance:\n\n```js\nimport axios from 'axios'\n\nconst instance = axios.create({ /* ... */ });\n\nconst httpAdapter = new HttpAdapters.AxiosHttpAdapter(\n  instance\n);\n```\n\n#### Using `fetch`\n\nHTTP Adapter using the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).\n\n```js\nconst httpAdapter = new HttpAdapters.FetchHttpAdapter(\n  window.fetch.bind(window)\n);\n```\n\nFor Node.js you can install [cross-fetch](https://www.npmjs.com/package/cross-fetch), or other implementations.\n\n```js\nconst fetch = require('cross-fetch');\n\nconst httpAdapter = new HttpAdapters.FetchHttpAdapter(\n  fetch\n);\n```\n\n##### Set `defaultInit`\n\nSet a default request `init` options that will be merged with all the request options made by the adapter:\n\n```js\nconst defaultInit = { mode: 'cors' };\nconst httpAdapter = new HttpAdapters.FetchHttpAdapter(fetch, defaultInit);\n\nclient.defaultInit.credentials = 'include';\n\nconsole.log(client.defaultInit);\n// { mode: 'cors', credentials: 'include' }\n```\n\n### Client\n\nSet the HTTP adapter.\n\n```js\nconst client = new JsonApi.Client(httpAdapter);\n```\n\n#### Configure custom HTTP headers\n\nSet default HTTP headers to apply to each HTTP requests.\n\n```ts\nconst username = 'username';\nconst password = 'password';\nconst defaultHttpHeaders = { 'Authorization': 'Basic ' + btoa(username + ':' + password) };\n\nconst client = new JsonApi.Client(httpAdapter, defaultHttpHeaders);\n\nclient.defaultHttpHeaders['x-foo'] = 'bar';\n\nconsole.log(client.defaultHttpHeaders);\n// { Authorization: 'Basic dXNlcm5hbWU6cGFzc3dvcmQ=', 'x-foo': 'bar' }\n```\n\n#### Result\n\nThe client returns a Promise that resolves with a `Result` for JSON:API operations with contains the properties:\n\n| Name        | Type      | Description |\n|-------------|-----------|-------------|\n| `isSuccess` | *boolean* | whether the operation is successful. |\n| `document`  | *object*  | JSON:API document. |\n| `request`   | *object*  | HTTP request representation. |\n| `response`  | *object*  | HTTP response representation. |\n\n```js\nconst result = await client.fetch('http://examples.com/articles/1');\nconsole.log(result)\n// {\n//   isSuccess: true,\n//   document: {\n//     links: {\n//       self: \"http://example.com/articles/1\"\n//     },\n//     data: {\n//       type: \"articles\",\n//       id: \"1\",\n//       attributes: {\n//         title: \"JSON:API paints my bikeshed!\"\n//       },\n//       relationships: {\n//         author: {\n//           links: {\n//             related: \"http://example.com/articles/1/author\"\n//           }\n//         }\n//       }\n//     }\n//   },\n//   request: {\n//     url: 'http://examples.com/articles/1',\n//     headers: {\n//       Accept: 'application/vnd.api+json'\n//     },\n//     method: 'GET',\n//     body: null\n//   },\n//   response: {\n//     status: 200,\n//     body: '{\"type\":\"articles\",\"id\":\"1\",\"attributes\":{\"title\":\"JSON:API paints my bikeshed!\"},\"relationships\":{\"author\":{\"links\":{\"related\":\"http://example.com/articles/1/author\"}}}}',\n//     headers: {\n//       'content-type': 'application/vnd.api+json; charset=utf-8',\n//       etag: 'W/\"47a7cbaefdec0639404a5946676f6e95\"'\n//     }\n//   }\n// }\n```\n\n#### Specification\n\nThere are some [type guards (type predicats)](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates) that can be used to inspect the kind of JSON:API document.\n\n```js\nimport { JsonApi } from 'jsonapi-metal-client';\n\nconst {\n  isFetchResponse\n  isFetchResourceResponse\n  isFetchResourceIndividualResponse\n  isErrorDocument\n} = JsonApi.Specification.TypeGuards\n\nconst result = await client.fetch('http://examples.com/articles/1');\nif (result.isSuccess) {\n  isFetchResponse(result.document)\n  isFetchResourceResponse(result.document)\n  isFetchResourceIndividualResponse(result.document)\n  // true\n} else {\n  if (result.document) {\n    isErrorDocument(result.document)\n    // true\n  }\n}\n```\n\n## Development\n\nRequirements:\n- Yarn\n\n### Type Guards\n\nGenerate [type guards (type predicats)](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates).\n\n```shell\nyarn type-guards\n```\n\n### Documentation\n\nGenerate documentation using [TypeDoc](https://typedoc.org/):\n\n```shell\nyarn documentation\n```\n\n### Lint\n\nExecuting lint check using [ESLint](https://eslint.org/):\n\n```shell\nyarn lint\n```\n\nExecuting lint fix using [ESLint](https://eslint.org/):\n\n```shell\nyarn format\n```\n\n### Test\n\nExecuting [Jest](https://jestjs.io/) test suite:\n\n```shell\nyarn test\n```\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastert%2Fjsonapi-metal-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmastert%2Fjsonapi-metal-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastert%2Fjsonapi-metal-client/lists"}