{"id":28385755,"url":"https://github.com/beyonk-group/http","last_synced_at":"2025-06-26T00:05:30.707Z","repository":{"id":46036732,"uuid":"165380454","full_name":"beyonk-group/http","owner":"beyonk-group","description":"An isomorphic http client for Svelte applications","archived":false,"fork":false,"pushed_at":"2025-06-18T12:10:34.000Z","size":411,"stargazers_count":45,"open_issues_count":2,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-18T12:29:37.531Z","etag":null,"topics":["fetch","httpclient","node-fetch","sapper","svelte","svelte-kit","sveltekit","xhr"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/beyonk-group.png","metadata":{"files":{"readme":"README.MD","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-01-12T11:33:15.000Z","updated_at":"2024-08-17T14:47:17.000Z","dependencies_parsed_at":"2025-06-18T12:23:17.354Z","dependency_job_id":"09bcb10e-d3fa-4794-806a-f51bd3c005d3","html_url":"https://github.com/beyonk-group/http","commit_stats":null,"previous_names":["beyonk-group/sapper-httpclient","beyonk-adventures/sapper-httpclient"],"tags_count":50,"template":false,"template_full_name":null,"purl":"pkg:github/beyonk-group/http","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beyonk-group%2Fhttp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beyonk-group%2Fhttp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beyonk-group%2Fhttp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beyonk-group%2Fhttp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beyonk-group","download_url":"https://codeload.github.com/beyonk-group/http/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beyonk-group%2Fhttp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261973727,"owners_count":23238586,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["fetch","httpclient","node-fetch","sapper","svelte","svelte-kit","sveltekit","xhr"],"created_at":"2025-05-30T11:43:42.424Z","updated_at":"2025-06-26T00:05:30.697Z","avatar_url":"https://github.com/beyonk-group.png","language":"JavaScript","readme":"\u003ca href=\"https://beyonk.com\"\u003e\n  \u003cimg src=\"https://user-images.githubusercontent.com/218949/144224348-1b3a20d5-d68e-4a7a-b6ac-6946f19f4a86.png\" width=\"198\" /\u003e\n\u003c/a\u003e\n\n## Http\n\n[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](http://standardjs.com) ![publish](https://github.com/beyonk-adventures/http/workflows/publish/badge.svg?branch=master)\n\nIsomorphic fetch library.\n\u003cbr /\u003e\nFormerly known as `@beyonk/sapper-httpclient`\n\n## Why\n\nIn hybrid applications, there are three different ways of fetching data:\n\n* client\n* server\n* isomorphic (client + server)\n* retries (on various network errors)\n\nThis library helps you abstract over where you are fetching data, meaning that your code maintains consistency without having to worry about where your data is being fetched.\n\nThe way it does this is by trying to use the first available fetch method, and failing over to alternatives if a  method is not available. The methods it tries are, in the following order:\n\n1. Any fetch library you pass to `create()` (for example, `load`'s `fetch`)\n1. window.fetch if the library detects it is running clientside\n1. `node-fetch`, or whatever you want to pass in, if nothing else is available (pure server-side)\n\nGenerally this means that your usage is the same no matter where you call it, with one exception - using this library in the `load` method requires you to pass in SvelteKit's special `fetch` method, as it is not available outside of the load method. Examples of which are below.\n\n## Usage\n\n### To use within an application:\n\n### Install it\n\n```bash\nnpm i -D @beyonk/http\n```\n\n### Configure it (both server-side and client-side as there are two bundles)\n\n```js\n// src/client.js \u0026\u0026 src/server.js\nimport Api from '@beyonk/http'\n\nApi.configure({ baseUrl: 'https://example.com/your/api/base' })\n```\n\n### Use it on the client:\n\n```js\n// src/routes/some-route.html\nimport { create } from '@beyonk/http'\n\n// in a method (client-side)\nconst api = create()\nconst json = await api.endpoint('some/endpoint').get()\nconsole.log(json)\n\n// in load (isomorphic)\nconst api = create()\nconst json = await api\n  .context({ fetch }) // Pass in the \"fetch\" parameter from load\n  .endpoint('some/endpoint')\n  .get()\nconsole.log(json)\n```\n\n### Use it on the server:\n\n```js\n// src/routes/+page.server.js\nimport fetch from 'node-fetch' // or SvelteKit's built in fetch\nimport { create } from '@beyonk/http'\n\nconst api = create()\nconst json = await api\n  .context({ fetch }) // pass node fetch in here.\n  .endpoint('some/endpoint')\n  .get()\nconsole.log(json)\n```\n\n### Handling the response\n\n```js\nimport { create } from '@beyonk/http'\n\nconst api = create()\nconst json = await api\n  .endpoint('some/endpoint')\n  .get((json, httpStatus) =\u003e {\n    console.log('json response is', json)\n    console.log('http status code is', httpStatus)\n  })\n```\n\n## Methods\n\n```js\nconst api = create()\nconst client = api\n  .endpoint('some/endpoint')\n\nconsole.log(await client.get()) // Get endpoint\nconsole.log(await client.payload({ foo: 'bar' }).put()) // Put with body\nconsole.log(await client.payload({ foo: 'bar' }).post()) // Post with body\nconsole.log(await client.query({ foo: 'bar' }).get()) // Get with query\nconsole.log(await client.del()) // Delete\nconsole.log(await client.headers({ foo: 'bar' }).put()) // Put with headers\n```\n\n#### client.query\n\nThe `query` method accepts an object of params as either a String or Array of Strings.\nIf any property passed into the query is `undefined` it will be ignored. \n\n```js\nconst api = create()\nconst client = api\n  .endpoint('some/endpoint')\n\nconsole.log(await client.query({ foo: 'bar' }).get()) // will make a GET request to 'some/endpoint?foo=bar'\nconsole.log(await client.query({ foo: 'bar', baz: 'qux' }).get()) // will make a GET request to 'some/endpoint?foo=bar\u0026baz=qux\nconsole.log(await client.query({ foo: ['bar', 'qux' ] }).get()) // will make a GET request to 'some/endpoint?foo=bar\u0026foo=qux\nconsole.log(await client.query({ foo: undefined, baz: 'qux' }).get()) // will make a GET request to 'some/endpoint?baz=qux\n\n```\n\n## Using built in response handling\n\n```js\nconst api = create()\nconst profile = await api\n  .endpoint('some/endpoint')\n  .get(json =\u003e {\n    return json.profile\n  })\nconsole.log(profile)\n```\n\n## Catching errors\n\n### Per request\n\nIf no local error handler is specified, the fallback handler `default` is called. If this isn't specified, the error is logged to the console.\n\n```js\n  await client\n    .endpoint('some/url')\n    .forbidden(e =\u003e {\n      console.error('Forbidden', e)\n    })\n    .gone(e =\u003e {\n      console.error('Gone', e)\n    })\n    .notFound(e =\u003e {\n      console.error('Not found', e)\n    })\n    .accessDenied(e =\u003e {\n      console.error('Access denied', e)\n    })\n    .conflict(e =\u003e {\n      console.error('Conflict', e)\n    })\n    .paymentRequired(e =\u003e {\n      console.error('Payment Required', e)\n    })\n    .preconditionFailed(e =\u003e {\n      console.error('Precondition failed', e)\n    })\n    .badData(e =\u003e {\n      console.error('Bad data', e)\n    })\n    .default(e =\u003e {\n      // Any other error caught here\n      console.error('Some error', e)\n    })\n    .get()\n```\n\n#### Handler signature\n\nHandlers have a signature with two items:\n\n```js\n.badData((e, ctx) =\u003e {\n  console.error('Bad data', e)\n  throw redirect('/foo/bar')\n})\n```\n\nctx can be whatever you want really - it is whatever you pass in as `context(...)`.\n\nHowever, if the `context` object you pass in has a `fetch` function, this is used as the `fetch` for XHR requests.\n\n```js\nexport async function preload () {\n  await Api\n    .context({ fetch })\n    .endpoint('foo/bar')\n    ...\n}\n```\n\nyou can also pass in other things to the context:\n\n```js\nexport async function preload () {\n  await Api\n    .context({ ...this, baz: 'qux' })\n    .endpoint('foo/bar')\n    ...\n}\n```\n\n### At a global level\n\nRequest local error handlers override global error handlers, but if a local error handler are not specified, these will be called instead, if it exists.\n\nNames are the same as the local handlers:\n\n```js\n  import Api from '@beyonk/http'\n  import { redirect } from '@sveltejs/kit'\n\n  Api.configure({\n    baseUrl: 'https://example.com/your/api/base',\n    handlers: {\n      paymentRequired(e =\u003e {\n        throw redirect(307, '/checkout')\n      })\n    }\n  })\n\n  await client\n    .endpoint('some/url')\n    .get()\n```\n\n## Retries\n\nThe http client can retry if a network error is encountered. The default is `retry: false`, and requests won't be retried.\n\nConfigure it as follows:\n\n```js\nimport Api from '@beyonk/http'\n\nApi.configure({\n  retry: {\n    attempts: 3 // How many times to retry before giving up\n    errors: [ 'ECONNRESET' ] // A list of error codes\n  }\n})\n```\n\nerrors is an array of any number of the [nodejs network error codes](https://nodejs.org/api/errors.html#errors_common_system_errors)\n\n\n## Parsing error payloads\n\nAs of v7.0.0 the library defaults to parsing error payloads as JSON. This means you can use the data returned in your response.\n\n```js\n  /** endpoint returns 401 with:\n    {\n      username: 'Naughty User'\n    }\n  **/\n\n  await client\n    .endpoint('some/url')\n    .accessDenied(e =\u003e {\n      console.error('You are not allowed', e.body.username)\n    })\n```\n\nTo turn this behaviour off, pass the option `parseErrors` with value false:\n\n```js\nimport Api from '@beyonk/http'\n\nApi.configure({\n  parseErrors: false\n})\n```\n\n## Running Tests\n\n```sh\nnpm test\n```\n\n## Credits\n\n* Original code by [Antony Jones](https://github.com/antony)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeyonk-group%2Fhttp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeyonk-group%2Fhttp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeyonk-group%2Fhttp/lists"}