{"id":20448529,"url":"https://github.com/datacamp/universal-rx-request","last_synced_at":"2025-04-13T01:27:31.987Z","repository":{"id":57386680,"uuid":"76583261","full_name":"datacamp/universal-rx-request","owner":"datacamp","description":"Library to do HTTP requests with RxJS","archived":false,"fork":false,"pushed_at":"2017-09-27T10:10:18.000Z","size":28,"stargazers_count":11,"open_issues_count":0,"forks_count":0,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-04-02T01:01:30.285Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/datacamp.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":"2016-12-15T18:00:37.000Z","updated_at":"2021-06-19T16:28:27.000Z","dependencies_parsed_at":"2022-09-11T09:11:55.389Z","dependency_job_id":null,"html_url":"https://github.com/datacamp/universal-rx-request","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datacamp%2Funiversal-rx-request","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datacamp%2Funiversal-rx-request/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datacamp%2Funiversal-rx-request/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datacamp%2Funiversal-rx-request/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/datacamp","download_url":"https://codeload.github.com/datacamp/universal-rx-request/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248625493,"owners_count":21135513,"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":[],"created_at":"2024-11-15T10:35:33.411Z","updated_at":"2025-04-13T01:27:31.962Z","avatar_url":"https://github.com/datacamp.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# universal-rx-request \n[![codecov](https://codecov.io/gh/datacamp/universal-rx-request/branch/master/graph/badge.svg)](https://codecov.io/gh/datacamp/universal-rx-request)\n[![npm](https://img.shields.io/npm/l/universal-rx-request.svg)](https://www.npmjs.com/package/universal-rx-request)\n[![npm](https://img.shields.io/npm/dt/universal-rx-request.svg)](https://www.npmjs.com/package/universal-rx-request)\n[![npm](https://img.shields.io/npm/v/universal-rx-request.svg)](https://www.npmjs.com/package/universal-rx-request)\n\nLightweight HTTP requests library based on [superagent](https://github.com/visionmedia/superagent) that returns a [RxJS 5](https://github.com/ReactiveX/rxjs) observable. This library works on browser and server side. \n\n## Install \nThis library has peer dependencies of `rxjs@\u003e=5.0.1` and `superagent@\u003e=3.3.0`.\nTo install via npm for node environment:\n```bash\nnpm install --save superagent rxjs universal-rx-request\n```\n\nTo install on the browser:\n```html\n\u003cscript type=\"text/javascript\" src=\"/lib/index.js\"\u003e\u003c/script\u003e\n```\nThe library exposed a global variable called `rxRequest`. It also works with AMD api.\n\n## Basic Example\n\nThe library exposes a function which directly makes an HTTP request, depending on the configuration given. The request returns an observable.\n```js\nimport rxRequest from 'universal-rx-request';\n\nrxRequest({ method: 'get', url: 'https://api.ipify.org?format=json' })\n  .subscribe(result =\u003e console.log(result.body.ip), console.error);\n// print your current ip\n\nrxRequest({ method: 'get', url: 'https://wrong-api.com/notFound' })\n  .subscribe(result =\u003e console.log, error =\u003e console.error(error.error.errno));\n// print ENOTFOUND\n```\n\n## Works great with redux and redux-observable\n\nImporting rx extensions allows more control of the different steps that the request will go through (fetching =\u003e success|error). \n```js\nimport rxRequest from 'universal-rx-request';\n\nrxRequest.importRxExtensions(); // will add operators for the observables. You only have to do once\n\nrxRequest({ method: 'get', url: 'https://api.ipify.org?format=json' })\n  .mapToAction({ type: 'get_my_ip' })\n  .subscribe(console.log, console.error);\n// print the emitted items as a stream\n//  |--- { type: 'get_my_ip_fetching', requestStatus: 'fetching' } ------ { type: 'get_my_ip_success', requestStatus: 'success',  data: reponse } ----|\n\nrxRequest({ method: 'get', url: 'https://wrong-api.com/notFound' })\n  .mapToAction({ type: 'get_my_ip' })\n  .subscribe(console.log, console.error);\n// print the emitted items as a stream\n//  |--- { type: 'get_my_ip_fetching', requestStatus: 'fetching' } ------ { type: 'get_my_ip_error', requestStatus: 'error',  error: error } ----|\n```\nThanks to this rx extension the state can be handled after each step of the HTTP request.\n\nThe rx extensions provide some other useful operators:\n```js\nimport rxRequest from 'universal-rx-request';\nimport { Observable } from 'rxjs/Observable';\nimport 'rxjs/add/observable/of';\n\nrxRequest.importRxExtensions();\n\nrxRequest({ method: 'get', url: 'https://api.ipify.org?format=json' })\n  .mapToAction({ type: 'get_my_ip' })\n  .mergeMapOnSucceedRequest(result =\u003e Observable.of({ ip: result.data.body.ip }))\n  .subscribe(console.log, console.error);\n// print the emitted items as a stream\n//  |--- { type: 'get_my_ip_fetching', requestStatus: 'fetching' } ------ { ip: 'xxx.xxx.xxx.x' } ----|\n```\n\nAfter mapping the request to an action with `maptoAction`, We recommend the use of the extended operators to deal with succeed or failure responses. These are the extended operators which may be useful:\n- `throwErrorOnFailedRequest()`: Throws an error if the result of the http request is an error. To handle the error, you will have to catch it in the observable flow.\n- `mergeMapOnSucceedRequest((result) =\u003e {...})`: Acts like a classic [mergeMap](http://reactivex.io/rxjs/class/es6/Observable.js~Observable.html#instance-method-mergeMap) in the Rx world except that it will mergeMap only on succeed request (not fetching or error status). The function given as argument has to return an observable.\n- `flatMapOnSucceedRequest((result) =\u003e {...})`: An alias for `mergeMapOnSucceedRequest`.\n- `concatMapOnSucceedRequest((result) =\u003e {...})`: Like `mergeMapOnSucceedRequest` except that it uses the [concatMap](http://reactivex.io/rxjs/class/es6/Observable.js~Observable.html#instance-method-concatMap) operator.\n- `doOnSucceedRequest((result) =\u003e {...})`: Like `mergeMapOnSucceedRequest` except that it uses the [do](http://reactivex.io/rxjs/class/es6/Observable.js~Observable.html#instance-method-do) operator for side effects.\n- `filterOnSucceedRequest()`: Like `mergeMapOnSucceedRequest` except that it uses the [filter](http://reactivex.io/rxjs/class/es6/Observable.js~Observable.html#instance-method-filter) operator.\n\nPlease check out the test folder for a great example of how to use these operators correctly.\n\n## APIs\n\n### rxRequest(settings)\nFunction that makes the HTTP request and returns an observable. Shape of the settings (only url and method fields are required):\n```js\n {\n  url: 'https://...',\n  method: 'get|post|update|...',\n  query: {},\n  data: {},\n  options: {\n    only2xx: true|false,\n    agent: superagent.agent(),\n    json: true|false,\n    headers: {},\n    withCredentials: true|false,\n    responseType: 'blob|...',\n    timeout: {\n      response: 5000,\n      deadline: 60000,\n    },\n    auth: ['tobi', 'learnboost'],\n    redirects: 2,\n    attaches: [ ['file', 'test.png'], ...],\n    fields: [ ['user', 'Bob'], ...],\n  }\n }\n```\nThe function returns an observable which emits an object corresponding to the response of the HTTP request. If an error occurs, the observable emits an error which can be caught in the observable flow. The error emitted is an object containing the `error` and `response` field. For more details about the shapes of the error and response objects, please check the superagent library.\n\n### rxRequest.STATUS\nAn object containg all the different possible states of the HTTP request:\n```js\n{\n  FETCHING: 'fetching',\n  SUCCESS: 'success',\n  ERROR: 'error',\n}\n```\n\n### rxRequest.getStatus(action, status)\nFacility to get the type of the emitted action depending on the action object (`{ type: ... }`) and the status (rxRequest.STATUS).\n\n### rxRequest.importRxExtensions()\nFunction to extend the observable with new operators described above.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatacamp%2Funiversal-rx-request","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatacamp%2Funiversal-rx-request","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatacamp%2Funiversal-rx-request/lists"}