Giter VIP home page Giter VIP logo

superagent's Introduction

superagent

build status code coverage code style styled with prettier made with lass license

Small progressive client-side HTTP request library, and Node.js module with the same API, supporting many high-level HTTP client features. Maintained for Forward Email and Lad.

Table of Contents

Install

npm:

npm install superagent

yarn:

yarn add superagent

Usage

Node

const superagent = require('superagent');

// callback
superagent
  .post('/api/pet')
  .send({ name: 'Manny', species: 'cat' }) // sends a JSON post body
  .set('X-API-Key', 'foobar')
  .set('accept', 'json')
  .end((err, res) => {
    // Calling the end function will send the request
  });

// promise with then/catch
superagent.post('/api/pet').then(console.log).catch(console.error);

// promise with async/await
(async () => {
  try {
    const res = await superagent.post('/api/pet');
    console.log(res);
  } catch (err) {
    console.error(err);
  }
})();

Browser

The browser-ready, minified version of superagent is only 50 KB (minified and gzipped).

Browser-ready versions of this module are available via jsdelivr, unpkg, and also in the node_modules/superagent/dist folder in downloads of the superagent package.

Note that we also provide unminified versions with .js instead of .min.js file extensions.

VanillaJS

This is the solution for you if you're just using <script> tags everywhere!

<script src="https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=WeakRef,BigInt"></script>
<script src="https://cdn.jsdelivr.net/npm/superagent"></script>
<!-- if you wish to use unpkg.com instead: -->
<!-- <script src="https://unpkg.com/superagent"></script> -->
<script type="text/javascript">
  (function() {
    // superagent is exposed as `window.superagent`
    // if you wish to use "request" instead please
    // uncomment the following line of code:
    // `window.request = superagent;`
    superagent
      .post('/api/pet')
      .send({ name: 'Manny', species: 'cat' }) // sends a JSON post body
      .set('X-API-Key', 'foobar')
      .set('accept', 'json')
      .end(function (err, res) {
        // Calling the end function will send the request
      });
  })();
</script>

Bundler

If you are using browserify, webpack, rollup, or another bundler, then you can follow the same usage as Node above.

Supported Platforms

  • Node: v14.18.0+

  • Browsers (see .browserslistrc):

    npx browserslist
    and_chr 102
    and_ff 101
    and_qq 10.4
    and_uc 12.12
    android 101
    chrome 103
    chrome 102
    chrome 101
    chrome 100
    edge 103
    edge 102
    edge 101
    firefox 101
    firefox 100
    firefox 91
    ios_saf 15.5
    ios_saf 15.4
    ios_saf 15.2-15.3
    ios_saf 15.0-15.1
    ios_saf 14.5-14.8
    ios_saf 14.0-14.4
    ios_saf 12.2-12.5
    kaios 2.5
    op_mini all
    op_mob 64
    opera 86
    opera 85
    safari 15.5
    safari 15.4
    samsung 17.0
    samsung 16.0

Required Browser Features

We recommend using https://cdnjs.cloudflare.com/polyfill/ (specifically with the bundle mentioned in VanillaJS above):

<script src="https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=WeakRef,BigInt"></script>
  • WeakRef is not supported in Opera 85, iOS Safari 12.2-12.5
  • BigInt is not supported in iOS Safari 12.2-12.5

Plugins

SuperAgent is easily extended via plugins.

const nocache = require('superagent-no-cache');
const superagent = require('superagent');
const prefix = require('superagent-prefix')('/static');

superagent
  .get('/some-url')
  .query({ action: 'edit', city: 'London' }) // query string
  .use(prefix) // Prefixes *only* this request
  .use(nocache) // Prevents caching of *only* this request
  .end((err, res) => {
    // Do something
  });

Existing plugins:

Please prefix your plugin with superagent-* so that it can easily be found by others.

For SuperAgent extensions such as couchdb and oauth visit the wiki.

Upgrading from previous versions

Please see GitHub releases page for the current changelog.

Our breaking changes are mostly in rarely used functionality and from stricter error handling.

  • 6.0 to 6.1
  • 5.x to 6.x:
    • Retry behavior is still opt-in, however we now have a more fine-grained list of status codes and error codes that we retry against (see updated docs)
    • A specific issue with Content-Type matching not being case-insensitive is fixed
    • Set is now required for IE 9, see Required Browser Features for more insight
  • 4.x to 5.x:
    • We've implemented the build setup of Lass to simplify our stack and linting
    • Unminified browserified build size has been reduced from 48KB to 20KB (via tinyify and the latest version of Babel using @babel/preset-env and .browserslistrc)
    • Linting support has been added using caniuse-lite and eslint-plugin-compat
    • We can now target what versions of Node we wish to support more easily using .babelrc
  • 3.x to 4.x:
    • Ensure you're running Node 6 or later. We've dropped support for Node 4.
    • We've started using ES6 and for compatibility with Internet Explorer you may need to use Babel.
    • We suggest migrating from .end() callbacks to .then() or await.
  • 2.x to 3.x:
    • Ensure you're running Node 4 or later. We've dropped support for Node 0.x.
    • Test code that calls .send() multiple times. Invalid calls to .send() will now throw instead of sending garbage.
  • 1.x to 2.x:
    • If you use .parse() in the browser version, rename it to .serialize().
    • If you rely on undefined in query-string values being sent literally as the text "undefined", switch to checking for missing value instead. ?key=undefined is now ?key (without a value).
    • If you use .then() in Internet Explorer, ensure that you have a polyfill that adds a global Promise object.
  • 0.x to 1.x:
    • Instead of 1-argument callback .end(function(res){}) use .then(res => {}).

Contributors

Name
Kornel Lesiński
Peter Lyons
Hunter Loftis
Nick Baugh

License

MIT © TJ Holowaychuk

superagent's People

Contributors

bevacqua avatar defunctzombie avatar focusaurus avatar gjohnson avatar hunterloftis avatar jamielinux avatar jimmywarting avatar johntron avatar kanreisa avatar kof avatar kornelski avatar lamweili avatar lbdremy avatar leipert avatar ltxhhz avatar magicdawn avatar nickl- avatar niftylettuce avatar popeindustries avatar pyoner avatar rauchg avatar scriptype avatar shreyjain1994 avatar slaskis avatar sogaani avatar titanism avatar tj avatar tootallnate avatar yields avatar yunnysunny avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

superagent's Issues

what happened with 0.0.1; using 0.1.1 with node

i was using 0.0.1 with node, it suddenly does not npm install anymore.

i trust your work, so that's what i picked superagent ... however what you recommend, to port my code to work with 0.1.1 or to use another library, if the latter which one you suggest

Is there a non valid char or json in this request ?

Hi,

Trying to send this to neo4j, and it breaks some BadInput rest format (I cant understand from the log). Doing a cURL in their webadmin console get the results correctly, so i it might be something with the library/superagent ? Can i use ? in the url and i guess the properties json is ok as well ?

request
.post('http://localhost:7474/db/data/index/node/users?unique')
.set('Content-Type', 'application/json')
.set('Accept', 'application/json')
.send({"key": "name", "value": "myname", "properties": {"name": "myname", "pass": "dd7f89ad79f"}})
.end(function(res){
if (res.ok) {
console.log('yay got ' + JSON.stringify(res.body));
} else {
console.log('Oh no! error ' + res.text);
}
});

It should be noted that i can send other json requests to the server, more simple key values not nested ones.

Thanks for a great nodejs extension!

plugin system

for now to keep things simple we'll just add everything in to increase adoption however even the internals could/should utilize some form of plugin system, interacting with various events

What about putting host, schema and port inside chain?

agent
.ssl()
.host('localhost')
.port(3000)
.post('/action');

Using this it would be reuse same agent with another action of same host:

var base = agent.ssl(). host('localhost').port(3000);

base.post('/action1');
base.post('/action2'); // reuse same agent with another action of same host

Unable to install with node 0.5.0-pre

Error when trying to run 'npm install superagent' with node 0.5.0-pre installed.

node# npm install superagent
npm ERR! Unsupported
npm ERR! Not compatible with your version of node/npm: [email protected]
npm ERR! Required: {"node":"0.4.x"}
npm ERR! Actual: {"npm":"1.0.6","node":"v0.5.0-pre"}
npm ERR!
npm ERR! System Linux 2.6.38-8-virtual
npm ERR! command "node" "/usr/local/bin/npm" "install" "superagent"
npm ERR!
npm ERR! Additional logging details can be found in:
npm ERR! /root/node/npm-debug.log
npm not ok

Any way for me to fix this or do I just need to wait for the next version of superagent?

Thanks for the great module, by the way!

Shawn

Doc errors

You are missing a } in the doc example:

request
  .get('/search', { query: 'tobi the ferret', function(res){

});

And a ' in:

request.post('/user')
  .set('Content-Type', 'application/json')
  .data('{"name":"tj","pet":"tobi"})
  .end(callback)

add app request support

something like request(app).get('/').... this would make it trivial for testing apps with superagent, and then use SA for Express tests :) when the app is not listening just bind to an ephemeral port and defer. perhaps this should be an extension somewhere else

Redirect broke in 0.1.2

Seems I pushed you into a new release too soon and now the the redirect following is broken :/
It will just do nothing when it finds a redirect page, callback never fires.

.send() doesn't convert array into json

When using

.send({...})

superagent is converting it into json but when using

.send([{...}, {...}])

superagent is not converting it into json. I have to do:

.send(JSON.stringify([{...}, {...}]))

A missing feature?

Problem with passing an Array as data

Superagent cannot handle Array as data parameter. In node.js, it throws this error:

TypeError: Second argument should be a buffer
  at Socket._writeImpl (net.js:159:14)
  at Socket._writeOut (net.js:444:25)
  at Socket.flush (net.js:523:24)
  at Socket._onWritable (net.js:603:12)
  at Socket._onConnect (net.js:591:12)
  at IOWatcher.onWritable [as callback] (net.js:186:12)

In the browser there is a problem with the JSON serialization: if the data parameter is [1,2,3], the data sent is "1,2,3" instead of "[1,2,3]"

EventEmitter not defined

If I use superagent with node the EventEmitter is not defined in lib/superagent.js. Obvious because it's in events.js and index.js only requires lib/superagent.js. Perhaps the index.js should require the superagent.js in the toplevel? Apart from that if i try to require superagent.js at the toplevel nothing gets exported.

Would be nice if you could fix the node part. Looks very promising! Thx for your work.

Basic auth support?

Could basic auth support be added so I could do something like:

request
  .get(...)
  .username()
  .password()
  .end(...);

retry logic

on econnrefused etc, exponential falloff or similar

defaults api

some way to stub out common settings etc that you've chosen for your app, opt-in

Inconsistencies between Node & Browser

Hey TJ, I love Superagent because for the most part it's the same API in the browser as it is Node. Less of a mental context switch. However, the Node version and the Browser version are different.

I'd be happy to try to help clean some of this up with pull-requests. (with tests of course) So, let's start with a simple one first. Encoding of forms. In the browser you use form-data in Node it's form. As seen by:
https://github.com/visionmedia/superagent/blob/master/lib/node/index.js#L76 vs
https://github.com/visionmedia/superagent/blob/master/lib/superagent.js#L145

Since form-data was a more recent change, I assume you like this more?

Thanks,

JP

make: Nothing to be done for `all'.

Running make doesn't do anything. How do I build this darn'd thing? O.o

[JD-i7-iMac:superagent JD]$ make -f Makefile
make: Nothing to be done for `all'.

Just so we're on the same page... this IS a script for making ajax calls in the browser, right? i.e., not just in node?

Synchronous vs Asynchronous

Any way to make the request synchronous as opposed to asynchronous ?

As in I want the request to fully complete, and callback executed before it runs the next command...

request.get 'http://myurl/', (req, res)->
  text = res.text
console.log text

Also off-topic, but is req suppose to return 'null' ? it is for me. (using this on Node.)

Thanks.

res is null

When I run:

request = require "superagent"
request
  .get("http://localhost:81")
  .end((res) ->
    console.log res
  )

I get a "res" that is null

Am I missing something?

UPDATE: Oh, the first one is for error. Time to update the doc :)

multipart api

something like:

request.post('/video')
  .type('mixed/related; boundary=---')
  .part()
    .set('Content-Type', 'application/xml')
    .data(metadata)
  .part()
    .set('Content-Type', 'video/webm')
    .set('Content-Length', stat.size)
    .data(fs.createReadStream(path))
  .end(callback)

auto-assign boundary when mixed/*:

request.post('/video')
  .type('mixed/related')
  .part()
    .set('Content-Type', 'application/xml')
    .data(metadata)
  .part()
    .set('Content-Type', 'video/webm')
    .set('Content-Length', stat.size)
    .data(fs.createReadStream(path))
  .end(callback)

support nesting

socket hang ups using post

I get the following error when I use the post method. Not sure what I am doing wrong:

node.js:134
throw e; // process.nextTick error, or 'error' event on first tick
^
Error: socket hang up
at Socket. (http.js:1271:45)
at Socket.emit (events.js:64:17)
at Array. (net.js:825:12)
at EventEmitter._tickCallback (node.js:126:26)

var sender = agent.post('http://localhost:8080/mockService');
sender.form({
channelID: channelID,
tileText: tileContent
});
sender.end();

Any ideas?

Misbehavior of parameters & form-data

I encountered a couple of an odd behavior when dealing with special parameters and form-data. Here is the source code:

var superagent = require("superagent");
var fs = require('fs');

var req = superagent.get("http://example.com/test?abc=def");
req.request().assignSocket(fs.createWriteStream("./rwparams.txt"));
req.end();


var req = superagent.post("http://example.com/test?abc=def");
req.type('form-data')
req.data({"a":"1","b":2})
req.request().assignSocket(fs.createWriteStream("./rwparams2.txt"));
req.end();

Output of rwparams.txt:

GET /test HTTP/1.1
Host: example.com
Connection: close

The parameter "abc=def" is just gone.

Output of rwparams2.txt:

POST /test HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 5
Connection: close

a=1&b

the variable "b" no longer has a value. At least it could throw an error that it has invalid input.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.