{"id":16055057,"url":"https://github.com/kouks/awi","last_synced_at":"2025-03-17T16:32:05.364Z","repository":{"id":34240228,"uuid":"172791988","full_name":"kouks/awi","owner":"kouks","description":"Versatile, modern and lightweight http client based on promises.","archived":false,"fork":false,"pushed_at":"2023-01-07T03:24:23.000Z","size":1043,"stargazers_count":8,"open_issues_count":17,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-16T02:27:48.319Z","etag":null,"topics":["ajax","client","http","node","promise","xhr"],"latest_commit_sha":null,"homepage":"","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/kouks.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-02-26T21:17:18.000Z","updated_at":"2024-09-11T08:55:42.000Z","dependencies_parsed_at":"2023-01-15T05:31:48.187Z","dependency_job_id":null,"html_url":"https://github.com/kouks/awi","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kouks%2Fawi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kouks%2Fawi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kouks%2Fawi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kouks%2Fawi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kouks","download_url":"https://codeload.github.com/kouks/awi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221696992,"owners_count":16865520,"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":["ajax","client","http","node","promise","xhr"],"created_at":"2024-10-09T02:05:37.034Z","updated_at":"2024-10-27T15:18:15.971Z","avatar_url":"https://github.com/kouks.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Awi\n\n[![npm](https://badge.fury.io/js/awi.svg)](https://www.npmjs.com/package/awi)\n[![Travis CI](https://travis-ci.org/kouks/awi.svg?branch=master)](https://travis-ci.org/kouks/awi)\n[![coverage](https://codecov.io/gh/kouks/awi/branch/master/graph/badge.svg)](https://codecov.io/gh/kouks/awi)\n\n\nVersatile, modern and lightweight http client based on promises.\n\n## Installation\n\n```bash\nnpm i -S awi\n```\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/awi/dist/awi.js\"\u003e\u003c/script\u003e\n```\n\n## Requirements\n\n| Node   | Chrome | Edge | Firefox | Opera | Safari |\n| :----: | :----: | :--: | :-----: | :---: | :----: |\n| 6.13.0 | 52     | 17   | 29      | 19    | 10     |\n\n## Usage\n\n### Basics\n\nThe most basic of requests can be executed seamlessly with Awi. Simply create\na new instance and call the `get` sugar method with the desired URL. This call\nreturns an instance of Awi's `Response` interface that has the response body,\nstatus and headers easily accessible.\n\n```typescript\nimport { Awi, Response } from 'awi'\n\nconst response: Response = await new Awi()\n  .get('http://server.api/todos')\n\nconsole.assert(typeof response.body === 'object')\nconsole.assert(typeof response.headers === 'object')\nconsole.assert(response.status === 200)\n```\n\nAwi is at its best when used in TypeScript as you can type-hint all responses\nand get type checks and nice auto-completion from your IDE.\n\n```typescript\nimport { Awi, Response } from 'awi'\n\ninterface TodoResponse extends Response {\n  body: { title: string, completed: boolean }\n}\n\nconst response: Response = await new Awi()\n  .get\u003cTodoResponse\u003e('http://server.api/todos/1')\n\nconsole.assert(typeof response.body.title === 'string')\nconsole.assert(typeof response.body.completed === 'boolean')\n```\n\nAwi provides syntax sugar for all basic request methods. `POST`, `PUT` and\n`PATCH` helpers optionally take the body of the request as their second\nargument.\n\n```typescript\nimport { Awi, Response } from 'awi'\n\nconst response: Response = await new Awi()\n  .post('http://server.api/todos', { title: 'Start using Awi.', completed: true })\n\nconsole.assert(response.status === 201)\n```\n\nUpon receiving a 400+ response status, Awi automatically rejects the promise so\nthat you don't have to do arbitrary checks for the response status via `if`\nstatements.\n\n```typescript\nimport { Awi } from 'awi'\n\nawait new Awi()\n  .post('http://server.api/todos', { completed: false })\n  .catch(response =\u003e console.assert(response.status === 422))\n```\n\nAwi also provides a `body` helper to avoid repeating the infamous\n`.then(res =\u003e res.body)` promise callback. This helper accepts a generic type\nto type-hint the response body.\n\n\u003e Note that this helper sends a `GET` request by default. If you desire to use\n\u003e a different request method, the method needs to be specified using\n\u003e an [interceptor](#interceptors).\n\n\u003e Also note that if the promise is rejected, the whole response object is\n\u003e returned.\n\n```typescript\nimport { Awi } from 'awi'\n\ninterface Todo {\n  title: string\n  completed: boolean\n}\n\nconst todo: Todo = await new Awi()\n  .body\u003cTodo\u003e('http://server.api/todos/1')\n\nconsole.assert(typeof todo.title === 'string')\nconsole.assert(typeof todo.completed === 'boolean')\n```\n\nThanks to [@bausano](https://github.com/bausano) and his awesome\n[data structures package](https://github.com/bausano/ts-data-structures), Awi\nhas an `optional` helper that returns the body of the response as an\n`Optional\u003cT\u003e` rather than rejecting the promise.\n\n\u003e Note that this helper sends a `GET` request by default. If you desire to use\n\u003e a different request method, the method needs to be specified using\n\u003e an [interceptor](#interceptors).\n\n\u003e Also note that if the request fails due to network issues or misconfiguration,\n\u003e the promise is still rejected.\n\n```typescript\nimport { Awi, Optional } from 'awi'\n\ninterface Todo {\n  title: string\n  completed: boolean\n}\n\nconst todo: Optional\u003cTodo\u003e = await new Awi()\n  .optional\u003cTodo\u003e('http://server.api/todos/1')\n\nconsole.assert(todo instanceof Optional)\n```\n\n### Interceptors\n\nRequest interceptors are what makes Awi stand out. Inspired by\n[Koa](https://koajs.com/), Awi provides a `use` method that accepts an\nasynchronous callback that modifies the request object.\n\n```typescript\nimport { Awi, Response } from 'awi'\n\nconst response: Response = await new Awi()\n  .use(async req =\u003e req.base = 'http://server.api')\n  .use(async req =\u003e req.path = 'todos')\n  .get()\n\nconsole.assert(response.status === 200))\n```\n\n\u003e All properties that can be modified on the request object are available in\n\u003e Awi's [API reference](https://github.com/kouks/awi/wiki/Request).\n\nEvery request in Awi is uniquely defined by the array of interceptors assigned\nto the request. All Awi's helper methods are nothing more but a sugar for\nassigning interceptors. All requests can be sent without using the helpers via\nthe `send` method.\n\n```typescript\nimport { Awi, Method, Response } from 'awi'\n\nconst response: Response = await new Awi()\n  .use(async req =\u003e req.base = 'http://server.api')\n  .use(async req =\u003e req.path = 'todos')\n  .use(async req =\u003e req.method = Method.GET)\n  .send()\n\nconsole.assert(response.status === 200))\n```\n\n\u003e Although this approach is rather lenghty and using helpers is much cleaner, it\n\u003e provides a straightforward way to extend Awi and/or create request templates.\n\nAs you can see, the interceptor concept provides a way to create request\ntemplates for your application in a very nice and reusable way. This can be\nespecially useful when making authorized requests.\n\n```typescript\nimport { Awi, Response } from 'awi'\n\n// Define the template to be reused.\nconst auth = () =\u003e new Awi()\n  .use(async req =\u003e req.base = 'http://server.api')\n  .use(async req =\u003e req.headers['authorization'] = `Bearer ${localStorage.token}`)\n\n// Use the template and provide further parameters.\nconst response: Response = await auth()\n  .get('user')\n\nconsole.assert(response.status === 200))\n```\n\n### API Reference\n\nAll of Awi's functionality is summed up on the\n[wiki page](https://github.com/kouks/awi/wiki/API-Reference).\n\n## Why Awi?\n\n**It's lightweight**\n\nThe minified file size is 12kB and we do not intend to make it bigger!\n\n**It's designed for developers, by developers**\n\nMaking http requests is something every developer needs to do on daily basis,\nespecially when it comes to TypeScript or JavaScript. Awi has a neat code base,\nis strictly typed and we purposefully leave documentation blocks in the built\nfiles - this way, you can read up on what each method does by simply\nctrl-clicking on it!\n\n**It's flexible**\n\nYou can either choose to go the easy way and using Awi's built-in helpers to\nexecute your HTTP request as a one-liner, or you can define and extract reusable\ntemplates for your requests from scratch!\n\nAwi is also open-source, so should you be missing any features that would make\nyour life easier, feel free to contribute.\n\n## Credits\n\nThe interceptor pattern is heavily inspired by [Koa](https://koajs.com/), which\nis also used to create a mock server for our e2e tests.\n\nImplemetation of executors for both web and node are inspired by no other than\n[axios](https://github.com/axios/axios).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkouks%2Fawi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkouks%2Fawi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkouks%2Fawi/lists"}