ladjs/superagent ladjs/superagent

  • Stars
    star
    16,475
  • Rank 1,711 (Top 0.04 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created over 13 years ago
  • Updated about 1 year ago
Twitter logo Share LinkedIn logo Share Facebook logo Share
ladjs/superagent
github

ladjs

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Ajax for Node.js and browsers (JS HTTP client). Maintained for @forwardemail, @ladjs, @spamscanner, @breejs, @cabinjs, and @lassjs.

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://polyfill.io/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: v6.x+

  • 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://polyfill.io (specifically with the bundle mentioned in VanillaJS above):

<script src="https://polyfill.io/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

More Repositories

1

supertest

πŸ•· Super-agent driven library for testing node.js HTTP servers using a fluent API. Maintained for @forwardemail, @ladjs, @spamscanner, @breejs, @cabinjs, and @lassjs.
JavaScript
13,355
star
2

lad

Node.js framework made by a former @expressjs TC and @koajs team member. Built for @forwardemail, @spamscanner, @breejs, @cabinjs, and @lassjs.
JavaScript
2,250
star
3

react-native-loading-spinner-overlay

πŸ’ˆ React Native loading spinner overlay
JavaScript
1,583
star
4

frisbee

πŸ• Modern fetch-based alternative to axios/superagent/request. Great for React Native.
JavaScript
1,123
star
5

express-cdn

☁️ Node module for delivering optimized, minified, mangled, gzipped assets with Express and Amazon's CDN (S3/CloudFront)
JavaScript
662
star
6

react-native-phone-verification

The best React Native example for phone verification (an alternative to Twitter Digits).
JavaScript
374
star
7

frappe

πŸ†“ Remotely shake your Android devices (including emulators) using a menubar applet and the hotkey ⌘+SHIFT+R
JavaScript
215
star
8

dotenv-parse-variables

Parse dotenv files for Boolean, Array, and Number variable types, built for Lad
JavaScript
122
star
9

i18n-locales

List of locales for i18n
JavaScript
72
star
10

graceful

Gracefully exit HTTP servers (Express/Koa/Fastify/etc), databases (Mongo/Mongoose), Redis clients, Bree job schedulers, and custom handlers.
JavaScript
66
star
11

koa-better-error-handler

A better error-handler for Lad and Koa. Makes `ctx.throw` awesome (best used with koa-404-handler)
JavaScript
52
star
12

chalkline

πŸ’„ Draw a big chalkline in your terminal! Great for debugging and reading your log output locally!
JavaScript
35
star
13

cache-pug-templates

Cache Pug templates for Lad/Koa/Express/Connect with Redis
JavaScript
26
star
14

mongoose-slug-plugin

Slugs for Mongoose with history and i18n support (uses speakingurl by default, but you can use any slug library such as limax, slugify, mollusc, or slugme)
JavaScript
22
star
15

express-cachebuster

Provides cross-browser version-control/cache-busting as a dynamic view helper in express.
JavaScript
22
star
16

gulp-jade-usemin

Gulp plugin for running usemin on Jade files
JavaScript
21
star
17

max-listeners-exceeded-warning

Debug and detect "MaxListenersExceededWarning: Possible EventEmitter memory leak detected warnings"
JavaScript
19
star
18

country-language

Query any country's spoken languages or countries where a language is spoken.
JavaScript
12
star
19

mandarin

Automatic i18n phrase translation using Google Translate
JavaScript
12
star
20

i18n

i18n wrapper and Koa middleware for Lad
JavaScript
10
star
21

naivebayes

A ladjs naivebayes package forked from `https://github.com/surmon-china/naivebayes`
JavaScript
10
star
22

web

Web server for Lad
JavaScript
9
star
23

koa-better-flash

Flash message middleware for Koa and Passport
JavaScript
9
star
24

env

Environment configuration loader for Lad
JavaScript
8
star
25

mongoose-common-plugin

Common plugin for Mongoose with standard schema fields and localization support
JavaScript
8
star
26

check-chai

βœ… Adds chai helper function `chai.check` for asynchronous testing with multiple expect or assert statements
JavaScript
8
star
27

koa-404-handler

404 handler for Lad and Koa (best used with koa-better-error-handler)
JavaScript
7
star
28

mongoose-validation-error-transform

Automatically transform Mongoose validation error message(s) to a humanized and readable format
JavaScript
7
star
29

express-cdn-cloudfront

Add-on module for express-cdn to provide Amazon CloudFront integration with Amazon S3.
7
star
30

passport

Passport for Lad
JavaScript
6
star
31

lad.sh

Demo for Lad - The Best Node.js Framework
JavaScript
6
star
32

remark-preset-github

GitHub markdown and prose style
JavaScript
6
star
33

dayjs-with-plugins

Day.js with all plugins and locales added out of the box, no need to use dayjs.extend!
JavaScript
6
star
34

is-string-and-not-blank

3x as fast as is-whitespace and whitespace-regex thanks to is-string-blank. This package is a simple function that accepts an argument and returns true if it is a string AND it is not blank.
JavaScript
5
star
35

redis

Redis for Lad
JavaScript
5
star
36

koa-meta

SEO <title> and <meta name="description"> middleware for Koa and Lad
JavaScript
5
star
37

koa-cache-responses

Caching middleware for Koa using koa-cash and route pattern-based matching with path-to-regexp. Made for Lad.
JavaScript
5
star
38

express-cdn-cloudfiles

Add-on module for express-cdn to provide Rackspace CloudFiles integration with built-in Akamai CDN delivery.
5
star
39

lookerupper

✨ :octocat: Copy to your clipboard a package's name and use `CmdOrCtrl+Shift+L` to lookup its documentation on GitHub
JavaScript
5
star
40

express-redirect-loop

Prevent redirect loops with sessions since HTTP referrer header is unreliable
JavaScript
4
star
41

get-paths

Helper function to get an absolute path for a template engine view
JavaScript
4
star
42

spdy-or-http2

Node.js ponyfill for HTTP/2 support (uses native http2 module or falls back to spdy)
JavaScript
4
star
43

proxy

Proxy for Lad
JavaScript
4
star
44

api

API server for Lad
JavaScript
4
star
45

koa-views-render

Simple render(page, locals) middleware for Koa and Lad (uses koa-views)
JavaScript
4
star
46

koa-better-timeout

Response timeout middleware for Koa and Lad (uses Boom by default)
JavaScript
4
star
47

express-jade

Express middleware to compile client-side Jade templates as template functions in the `window.jade` namespace.
JavaScript
4
star
48

koa-redis-ratelimit

*DOES NOT WORK DUE TO `ratelimiter`, PLEASE USE https://github.com/scttcper/koa-simple-ratelimit INSTEAD* Rate limiting middleware backed by Redis for Koa v2+, built for 🐊 CrocodileJS
JavaScript
3
star
49

mongoose

Mongoose helper for Lad
JavaScript
3
star
50

koa-redirect-loop

Prevent redirect loops with sessions since HTTP referrer header is unreliable and ensures sessions are saved upon redirect
JavaScript
3
star
51

store-ip-address

Stores a user's IP address in the background for Lad
JavaScript
3
star
52

message-headers

Automatically updated list of RFC HTTP permanent and provisional headers from IANA (https://www.iana.org/assignments/message-headers/message-headers.xhtml)
JavaScript
3
star
53

mongoose-omit-common-fields

Array of common fields to emit for Mongoose toObject/toJSON (helpful for security)
JavaScript
3
star
54

mongoose-model-agenda

Mongoose model for Agenda
JavaScript
3
star
55

express-cdn-cloudflare

Add-on module for express-cdn to provide CloudFlare CDN integration with Amazon S3.
3
star
56

koa-better-static

Static file serving middleware for Koa. Forked from an inactive project and maintained for Lad.
JavaScript
3
star
57

koa-manifest-rev

Dynamically load assets into your views from your `rev-manifest.json` manifest revision file.
JavaScript
3
star
58

stop-agenda

Gracefully stop Agenda and cancel recurring jobs
JavaScript
2
star
59

assets

Assets for Lad
JavaScript
2
star
60

policies

Policies helper for Lad
JavaScript
2
star
61

shared-config

Shared configuration for Lad's API and Web servers
JavaScript
2
star
62

manifest-rev

Dynamically load assets into your views, emails, etc. from your `rev-manifest.json` manifest revision file.
JavaScript
2
star
63

gulp-envify

Gulp plugin for envify without browserify (maintained fork of https://github.com/tomashanacek/gulp-envify)
JavaScript
2
star
64

preserve-qs

Preserve querystrings during redirect and creating new URLs for Node.js and browser environments (supports Lad, Koa, Express, and Connect)
JavaScript
2
star
65

juice-resources-promise

Simple helper function to convert juice.juiceResources into a Promise
JavaScript
2
star
66

gulp-haschanged-deps-async

Deep dependency recursive modified time comparison to ensure your files only re-compile when needed
JavaScript
2
star
67

pick-original

Transform an Object that was transformed to return only the original properties recursively picked if they are not undefined.
JavaScript
1
star
68

koa-cors-gate

JavaScript
1
star
69

store-sessions

Store/manage user sessions in the background for Lad
JavaScript
1
star
70

mongoose-error-messages

Better error messages for Mongoose, built for Lad
JavaScript
1
star
71

lad-template

sao template for lad
JavaScript
1
star
72

state-helper

State helper for Lad
JavaScript
1
star
73

agenda

Agenda for Lad
JavaScript
1
star
74

bull

Bull for Lad
JavaScript
1
star
75

browserslist-config

Browserslist config for Lad
JavaScript
1
star