{"id":22733470,"url":"https://github.com/strikeentco/yarl","last_synced_at":"2025-04-14T01:54:39.931Z","repository":{"id":57403230,"uuid":"44205303","full_name":"strikeentco/yarl","owner":"strikeentco","description":"Promise based, easy to use, with built-in multipart/form-data and gzip/deflate handling support - yet another request library (yarl).","archived":false,"fork":false,"pushed_at":"2017-07-07T12:04:14.000Z","size":40,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-03T21:01:45.243Z","etag":null,"topics":["form-data","gzip","javascript","nodejs","promise","request","yarl"],"latest_commit_sha":null,"homepage":"","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/strikeentco.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":"2015-10-13T21:15:13.000Z","updated_at":"2019-01-29T10:16:12.000Z","dependencies_parsed_at":"2022-09-18T12:00:41.895Z","dependency_job_id":null,"html_url":"https://github.com/strikeentco/yarl","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/strikeentco%2Fyarl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strikeentco%2Fyarl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strikeentco%2Fyarl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strikeentco%2Fyarl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/strikeentco","download_url":"https://codeload.github.com/strikeentco/yarl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248732483,"owners_count":21152852,"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":["form-data","gzip","javascript","nodejs","promise","request","yarl"],"created_at":"2024-12-10T20:14:43.557Z","updated_at":"2025-04-14T01:54:39.883Z","avatar_url":"https://github.com/strikeentco.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"yarl [![License](https://img.shields.io/npm/l/yarl.svg)](https://github.com/strikeentco/yarl/blob/master/LICENSE) [![npm](https://img.shields.io/npm/v/yarl.svg)](https://www.npmjs.com/package/yarl)\n==========\n[![Build Status](https://travis-ci.org/strikeentco/yarl.svg)](https://travis-ci.org/strikeentco/yarl) [![node](https://img.shields.io/node/v/yarl.svg)](https://www.npmjs.com/package/yarl) [![Test Coverage](https://codeclimate.com/github/strikeentco/yarl/badges/coverage.svg)](https://codeclimate.com/github/strikeentco/yarl/coverage) [![bitHound Score](https://www.bithound.io/github/strikeentco/yarl/badges/score.svg)](https://www.bithound.io/github/strikeentco/yarl)\n\u003e YARL, Carl!\n\n`Promise` based, easy to use, with built-in `multipart/form-data` and `gzip/deflate` handling support - yet another request library (yarl).\n\n## Features\n* `Promise` based (i.e. `async/await` ready)\n* Follows redirects\n* `multipart/form-data` built-in support\n* `json` parse\n* `gzip/deflate` handling\n* `download` method\n* etc.\n\n## Install\n```sh\n$ npm install yarl --save\n```\n\n## Usage\n```js\nconst { get, download } = require('yarl');\n\nget('https://api.github.com/users/strikeentco', { json: true })\n  .then(({body}) =\u003e {\n    body.name; // -\u003e Alexey Bystrov\n    return download(body.avatar_url, `./${body.login}.jpg`);\n  })\n  .then((res) =\u003e {\n    res.body; // -\u003e The data successfully written to file.\n  });\n```\n\n```js\nconst { post } = require('yarl');\nconst { createReadStream } = require('fs');\nconst { get } = require('https');\n\npost('127.0.0.1:3000', {\n  body: {\n    photo: get('https://avatars.githubusercontent.com/u/2401029'),\n    fixture: createReadStream('./test/fixture/fixture.jpg')\n  },\n  multipart: true\n});\n```\n\n# API\n\n### yarl(url, [options])\n\nBy default it's a `GET` request, but you can change it in `options`.\n\nIf `http://` will be missed in `url`, it will be automatically added.\n\n#### Params:\n* **url** (*String|Object*) - The URL to request or a [`http.request` options](https://nodejs.org/api/http.html#http_http_request_options_callback) object.\n* **[options]** (*Object*) - Any of the [`http.request` options](https://nodejs.org/api/http.html#http_http_request_options_callback) options and:\n  * **query**  (*String|Object*) - Correct `urlencoded` string or query `Object`. `Object` will be stringified with [`querystring.stringify`](https://nodejs.org/api/querystring.html#querystring_querystring_stringify_obj_sep_eq_options). This will override the query string in `url`.\n  * **body**  (*String|Object|Array|Buffer*) - Body that will be sent with a `POST`, `PUT`, `PATCH`, `DELETE` request. If `content-length` or `transfer-encoding` is not set in options.headers, `transfer-encoding` will be set as `chunked`.\n  * **multipart** (*Boolean*) - If `true`, body object will be sent as `multipart/form-data`.\n  * **form** (*Boolean*) - If `true`, body object will be sent as `application/x-www-form-urlencoded`.\n  * **json** (*Boolean*) -  If `true`, body object will be sent as `application/json`. Parse response body with `JSON.parse` and set accept header to `application/json`. If used in conjunction with the `form` option, the `body` will the stringified as querystring and the response parsed as JSON.\n  * **forceRedirect** (*Boolean*) - If `true`, will follow redirects for all methods, otherwise for `GET` and `HEAD` only.\n  * **redirectCount** (*Number*) - Number of allowed redirects. By default 10.\n  * **includeHeaders** (*Boolean*) - If `true`, `headers` property will be added to response object, otherwise only `body` will.\n  * **buffer** (*Boolean*) - If `true`, the body is returned as a `Buffer`.\n  * **download** (*String|WritableStream*) - Response body will be written to specified `WritableStream` or new `WritableStream` will be created with specified path.\n  * **gzip** (*Boolean*) - Unzip response body with `gzip`. Useful when server doesn't specify `Content-Encoding` header.\n  * **deflate** (*Boolean*) - Unzip response body with `deflate`. Useful when server doesn't specify `Content-Encoding` header.\n\n### yarl.get(url, [options])\n\nSimmilar to `yarl(url, { method: 'GET' })`.\n\n### yarl.head(url, [options])\n\nSimmilar to `yarl(url, { method: 'HEAD', includeHeaders: true })`.\n\n### yarl.post(url, [options])\n\nSimmilar to `yarl(url, { method: 'POST' })`.\n\n### yarl.put(url, [options])\n\nSimmilar to `yarl(url, { method: 'PUT' })`.\n\n### yarl.patch(url, [options])\n\nSimmilar to `yarl(url, { method: 'PATCH' })`.\n\n### yarl.delete(url, [options])\n\nSimmilar to `yarl(url, { method: 'DELETE' })`.\n\n### yarl.download(url, path)\n\nSimmilar to `yarl(url, { method: 'GET', download: path })`.\n\n## XML\n\nYou can use the [`xml-parser`](https://github.com/segmentio/xml-parser) module to parse XML data:\n\n```js\nconst yarl = require('yarl');\nconst parse = require('xml-parser');\n\nfunction xmlParse(xml) {\n  return Object.assign({}, xml, {\n    body: parse(xml.body)\n  });\n}\n\nyarl('http://api.openweathermap.org/data/2.5/weather?q=London\u0026mode=xml').then(xmlParse).then((r) =\u003e {\n  r.body.root.children[1].attributes.value; // -\u003e temperature\n});\n\n// or\n\nyarl('http://api.openweathermap.org/data/2.5/weather?q=London\u0026mode=xml').then((r) =\u003e {\n  parse(r.body).root.children[1].attributes.value; // -\u003e temperature\n});\n\n```\n\n## Proxies\n\nYou can use the [`tunnel`](https://github.com/koichik/node-tunnel) module with the `agent` option to work with proxies:\n\n```js\nconst yarl = require('yarl');\nconst tunnel = require('tunnel');\n\nyarl('github.com', {\n  agent: tunnel.httpOverHttp({\n    proxy: {\n      host: 'localhost'\n    }\n  })\n});\n```\n\n## Cookies\n\nYou can use the [`cookie`](https://github.com/jshttp/cookie) module to include cookies in a request:\n\n```js\nconst yarl = require('yarl');\nconst cookie = require('cookie');\n\nyarl('github.com', {\n  headers: {\n    cookie: cookie.serialize('foo', 'bar')\n  }\n});\n```\n\n## OAuth\n\nYou can use the [`oauth-1.0a`](https://github.com/ddo/oauth-1.0a) module to create a signed OAuth request:\n\n```js\nconst yarl = require('yarl');\nconst crypto  = require('crypto');\nconst OAuth = require('oauth-1.0a');\n\nconst oauth = OAuth({\n  consumer: {\n    key: process.env.CONSUMER_KEY,\n    secret: process.env.CONSUMER_SECRET\n  },\n  signature_method: 'HMAC-SHA1',\n  hash_function: (baseString, key) =\u003e crypto.createHmac('sha1', key).update(baseString).digest('base64')\n});\n\nconst token = {\n  key: process.env.ACCESS_TOKEN,\n  secret: process.env.ACCESS_TOKEN_SECRET\n};\n\nconst url = 'https://api.twitter.com/1.1/statuses/home_timeline.json';\n\nyarl(url, {\n  headers: oauth.toHeader(oauth.authorize({ url, method: 'GET' }, token)),\n  json: true\n});\n```\n\n## Other examples\n\n```js\nconst yarl = require('yarl');\n\n(async () =\u003e {\n  const { body: photo } = await yarl('https://avatars.githubusercontent.com/u/2401029', { buffer: true });\n  await yarl('127.0.0.1:3000', { body: { photo }, multipart: true })\n})()\n```\n\n```js\nconst { createReadStream } = require('fs');\nconst { get } = require('https');\nconst { post } = require('yarl');\n\nconst options = {\n  body: {\n    photo: {\n      value: [\n        createReadStream('./test/fixture/fixture.jpg'),\n        get('https://avatars.githubusercontent.com/u/2401029')\n      ],\n      options: { filename: 'photo.jpg' }\n    },\n    field: [1, 2, '3', 4, null]\n  },\n  multipart: true,\n  json: true\n};\n\npost('127.0.0.1:3000', options);\n```\n\n## License\n\nThe MIT License (MIT)\u003cbr/\u003e\nCopyright (c) 2015-2017 Alexey Bystrov\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrikeentco%2Fyarl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstrikeentco%2Fyarl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrikeentco%2Fyarl/lists"}