{"id":15983159,"url":"https://github.com/perry-mitchell/cowl","last_synced_at":"2025-10-23T23:31:55.983Z","repository":{"id":55853486,"uuid":"169707409","full_name":"perry-mitchell/cowl","owner":"perry-mitchell","description":"Request cowl for making requests from NodeJS/Browser/React-Native","archived":false,"fork":false,"pushed_at":"2022-01-30T10:36:33.000Z","size":1201,"stargazers_count":3,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-09T16:18:09.602Z","etag":null,"topics":["request","wrapper","xhr","xmlhttprequest","xmlhttprequest-wrapper"],"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/perry-mitchell.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2019-02-08T08:52:56.000Z","updated_at":"2022-01-29T20:22:38.000Z","dependencies_parsed_at":"2022-08-15T07:51:00.351Z","dependency_job_id":null,"html_url":"https://github.com/perry-mitchell/cowl","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/perry-mitchell/cowl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perry-mitchell%2Fcowl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perry-mitchell%2Fcowl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perry-mitchell%2Fcowl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perry-mitchell%2Fcowl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/perry-mitchell","download_url":"https://codeload.github.com/perry-mitchell/cowl/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perry-mitchell%2Fcowl/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259813010,"owners_count":22915199,"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":["request","wrapper","xhr","xmlhttprequest","xmlhttprequest-wrapper"],"created_at":"2024-10-08T01:40:54.880Z","updated_at":"2025-10-23T23:31:55.929Z","avatar_url":"https://github.com/perry-mitchell.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cowl\n\u003e Request cowl for making requests from NodeJS/Browser/React-Native\n\n[![npm version](https://badge.fury.io/js/cowl.svg)](https://www.npmjs.com/package/cowl) [![Build Status](https://travis-ci.org/perry-mitchell/cowl.svg?branch=master)](https://travis-ci.org/perry-mitchell/cowl)\n\n## About\n\nCowl is a wrapper for HTTP/S requests for use in NodeJS and the browser. React-Native is a work-in-progress. It's designed to be useable from 1 script, support bundling (via Webpack) and support sending and receiving data. It provides a simple API that uses a configuration object to make requests.\n\nCowl can return `ArrayBuffer`s in the browser by specifying `arraybuffer` as the `responseType`. Specifying a `responseType` of `buffer` in the browser will still result in an `ArrayBuffer` being returned. Cowl can return both `ArrayBuffer`s and `Buffer`s when running on NodeJS.\n\n## Usage\n\nInstall it by running `npm install cowl`.\n\nGET requests can be made by using the configuration object or by simply passing a URL:\n\n```javascript\nconst { request } = require(\"cowl\");\n\nrequest(\"https://server.com/api\").then(/* ... */);\n\nrequest({\n    url: \"https://server.com/api\"\n}).then(/* ... */);\n\nrequest({\n    url: \"https://server.com/api\",\n    method: \"GET\",\n    headers: {\n        \"Authorization\": \"Bearer ...\"\n    }\n}).then(/* ... */);\n```\n\nCowl will automatically assume that JSON is being sent if the body is an `Object` and no `Content-Type` header is overridden. Cowl will read the response headers to automatically discern the type if `responseType` is set to \"auto\".\n\nCowl will return a `Buffer` instance for `application/octet-stream` binary responses, even if in a browser (`ArrayBuffer`s are converted to `Buffer` instances).\n\nYou can set `responseType` to be any of the following:\n\n * `auto` - Automatically detect the response type (default) (ideal for text/JSON)\n * `text` - Treat the response as text\n * `json` - Treat the response as JSON\n * `arraybuffer` - Treat the response as an Array Buffer. Supported on NodeJS and in the browser.\n * `buffer` - Treat the response as a Buffer. Supported on NodeJS only. Specifying `buffer` in the browser will automatically default to requesting as `arraybuffer`.\n\n **NB:** The response type is provided to the XHR mechanism, and the output is largely dependent on the server's response. The type you specify as `responseType` should match what you _expect_ to receive, not what you wish to.\n\n```javascript\nconst { request } = require(\"cowl\");\n\nrequest({\n    url: \"https://server.com/res/item\",\n    method: \"GET\",\n    responseType: \"buffer\"\n}).then(resp =\u003e {\n    // resp.data will be a Buffer under NodeJS, and an ArrayBuffer in the browser\n});\n\nrequest({\n    url: \"https://server.com/res/item\",\n    method: \"GET\",\n    responseType: \"arraybuffer\"\n}).then(resp =\u003e {\n    // resp.data will be an ArrayBuffer\n});\n```\n\nRequest objects form the following structure:\n\n| Property    | Required | Type         | Description                           |\n|-------------|----------|--------------|---------------------------------------|\n| `url`       | Yes      | `String`     | The request URL                       |\n| `method`    | No       | `String`     | The HTTP request method (default: GET) |\n| `headers`   | No       | `Object`     | Headers for the request               |\n| `query`     | No       | `String` / `Object` | Query object/string            |\n| `responseType` | No    | `String`     | The response type (default: auto)     |\n| `body`      | No       | `Object` / `String` / `Buffer` / `ArrayBuffer` | Data to upload |\n\nResponse objects have the following structure:\n\n| Property      | Type      | Description                           |\n|---------------|-----------|---------------------------------------|\n| `url`         | String    | The resulting URL that the request was made against |\n| `method`      | String    | The request method used               |\n| `headers`     | Object    | The response headers received         |\n| `data`        | Object|Buffer|String | The response body          |\n| `status`      | Number    | The status code                       |\n| `statusText`  | String    | The status code text                  |\n\n### Response headers\n\nHeaders sent by the server are parsed and all keys converted to lower-case for easier handling.\n\n### Request failures\n\nIf a request fails or returns a status code outside the allowed range (200-399), an error is thrown. This particular error will contain some properties to help deal with the failure, accessible by using the [`Layerr`](https://github.com/perry-mitchell/layerr) Node library. The properties are as follows:\n\n| Property          | Type      | Description                               |\n|-------------------|-----------|-------------------------------------------|\n| `status`          | `Number`  | The status code                           |\n| `statusText`      | `String`  | The status text                           |\n| `code`            | `Number`  | Usually `ERR_REQUEST_FAILED`              |\n| `responseHeaders` | `Object`  | Response headers                          |\n| `responseBody`    | `String` / * | Response body data (unprocessed)       |\n\n_Note that not all the properties will be available for all errors._\n\n_Early versions of this project set these properties directly to the `Error` instance itself, but this method is **deprecated**. Use `Layerr` or `VError` to fetch the info (via `Layerr.info(err)` or `VError.info(err)`) instead._\n\nYou can specify a new validation method for status codes by providing a `validateStatus` method in the request options.\n\n## Packaging\n\nIf you're using webpack to bundle this library, make sure to check out the [example in this repo](webpack.config.js). Specifically, make sure to stub `fs` and `net`:\n\n```javascript\n{\n    node: {\n        fs: \"empty\",\n        net: \"empty\"\n    }\n}\n```\n\n## Compatibility\n\nCowl works on NodeJS version 10 and above. Compiling it via Babel or Webpack may allow it to function on earlier versions, but this is not officially supported.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperry-mitchell%2Fcowl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fperry-mitchell%2Fcowl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperry-mitchell%2Fcowl/lists"}