Jetta

A powerful, multi-protocol request library and toolkit ✈️

const jetta = require('jetta')
 
jetta.request('altusaero.com', (error, results) => {
  if (error !== null) {
    throw error // contains extended details along with multi-language support
  } else {
    console.dir(results, {colors: true}) // response time, headers, normalized options used, and more
    console.log(results.data.toString()) // <!DOCTYPE html><html lang="en"><head><meta charset="utf-8">...
  }
})

// Other useful tools:
async function myRequest (url = 'altusaero.com', options = {}) {
  results = await jetta.requestPromise(url, options)
}
 
const cookieManager = new jetta.CookieManager()
const publicSuffix = new jetta.PublicSuffix()
 
jetta.urlParser('foo-bar').isValid // false
jetta.urlParser('127.0.0.12').isLocalhost // true
jetta.urlParser('example.com', {addMissingProtocol: true}).parsedURL.href // 'https://example.com/'

Installation

$ npm install jetta

Features

Easy to use, feature-rich, with secure defaults
Requests - fast with useful built-in features:
- Callback and promise support
- Auto-parse JSON responses
- Saves bandwidth by supporting requests that have multiple levels of compression (Content-Encoding)
- Built-in checksum generator
- Custom engine support
- Convenient request body handlers for forms, JSON, and streams
- Makes minimal assumptions - returns the data so that you may decide what to do with it
- Provides guarantees so that you may always have consistent data
Cookie manager - add, delete, and update cookies with or without making a request
- Generate Cookie and Set-Cookie headers with context (domain, subdomains, path, security, HttpOnly, etc.)
- Built-in public suffix manager - no worries on 'super cookies' being sent any parent domains
- Easy JSON import and export
- Automatically deletes expired cookies
Public suffix manager - easy, automated public suffix list manager
- Automatically updates from sources you specify (useful open source defaults are available)
- Easily check against the database
URL parser - parse and validate URLs
- IDN support
Well-tested with 100% code coverage
0 dependencies
- Easy to review the source code for ideas and security purposes

Quick Start

const jetta = require('jetta')
 
const imageURL = 'https://altusaero.net/opensource/jetta/logo/1.2/jetta.svg'
const options = {toFile: 'jetta.svg'}
 
jetta.request(imageURL, options, (error, results) => {
  if (error !== null) {
    console.error(`${error.code} [${error.lang}]: ${error.message}`)
  } else {
    console.log(`wrote: ${options.toFile}`)
  }
})

Usage

jetta.defaults `OBJECT`

The global default options
Options passed to jetta functions and constructors will overwrite these defaults for that particular call or instance

jetta.cookieLib `OBJECT`

A utility for parsing, stringifying, and validating cookies.
Example:

const cookie = jetta.cookieLib.parseSetCookie('id=example; Domain=example.com; Secure; SameSite')

Complete documentation can be found in docs/cookie-lib.md.

jetta.CookieManagerCookie `CLASS`

A simple object representing a cookie prepared for storage
Created internally by jetta.CookieManager instances where cookies are returned
Handy for using with instanceof and instance.constructor throughout your codebase
Example:

const cookieForStorage = new jetta.CookieManagerCookie()

Complete documentation can be found in docs/cookie-manager.md.

jetta.CookieManager `CLASS` extends `EventEmitter`

Add, delete, and update cookies
Generate Cookie and Set-Cookie headers with context (domain, subdomains, path, security, HttpOnly, etc.)
Automatically deletes expired cookies
Built-in jetta.PublicSuffix to make sure you're not saving & sending supercookies
Example:

const cm = new jetta.CookieManager()

Complete documentation can be found in docs/cookie-manager.md.

jetta.domainLib `OBJECT`

A utility for comparing and analyzing domains
Example:

jetta.domainLib.domainInOtherDomain('example.com', 'com') // true
jetta.domainLib.domainInOtherDomain('example.com', 'example.com') // true
jetta.domainLib.domainInOtherDomain('super.sub.example.com', 'example.com') // true
jetta.domainLib.domainInOtherDomain('not-example.com', 'example.com') // false

Complete documentation can be found in docs/domain-lib.md.

jetta.makeNestedDirectory `FUNCTION`

A simple utility for creating nested directories, creating them where they do not exist
Used internally by other jetta features and tests, but exposed for your convenience
Example:

jetta.makeNestedDirectory(path.join('example', 'new', 'nested', 'directory'))

Complete documentation can be found in docs/make-nested-directory.md.

jetta.JettaError `CLASS` extends `Error`

The global error class used to denote errors generated by jetta
Instances contain unique error codes, making them easy to track in the codebase
Designed with multi-language support, which helps non-English speakers trace errors
Example:

const error = new jetta.JettaError('jetta-cookie-invalid-name', 'en')

Complete documentation can be found in docs/jetta-error.md.

jetta.PublicSuffix `CLASS` extends `EventEmitter`

A public suffix list useful for looking up TLDs and eTLDs
Automatically updates from provided sources (uses open source sources by default)
Example:

const ps = new jetta.PublicSuffix()

Complete documentation can be found in docs/public-suffix.md.

jetta.request `FUNCTION`

Create local and remote-bound requests
Built-in support for http:, https:, file:, and data: protocols
Auto-parse JSON responses, no need for JSON.parse/try/catch post-callback
Saves bandwidth by supporting requests that have multiple levels of compression (Accept-Encoding)
Built-in checksum generator, generate checksums on the data as the request is being received
Custom engines support, bring your own support for http:, https:, file:, data:, and other protocols that jetta does not yet support
Convenient request body handlers for forms, JSON, and streams
Makes minimal assumptions - returns the data so that you may decide what to do with it
Example:

jetta.request('altusaero.com', (error, results) => {
  // for convenience purposes, 'results.error' is the same as the 'error' param
  console.dir(results, {colors: true})
})

Complete documentation can be found in docs/request.md.

jetta.requestPromise `FUNCTION`

A promise version of jetta.request
Uses the same options and parameters as jetta.request, with the exception of a callback
Example:

jetta.requestPromise('altusaero.com').then((results) => {
  console.dir(results, {colors: true})
}).catch(console.error)

As Promises cannot return multiple parameters, any errors generated will have a results attribute
jetta.requestPromise.constants is the same as jetta.request.constants
Complete documentation can be found in docs/request.md.

jetta.urlParser `FUNCTION`

A utility for parsing and validating URLs
Provides options for strict and lax validation
Example:

const urlResults = jetta.urlParser('example.com/about/', {addMissingProtocol: true})
 
urlResults.isLocalhost // false
urlResults.isValid // true
urlResults.parsedURL.protocol // 'https:'

Complete documentation can be found in docs/url-parser.md.

Motivation

We wanted a simple, flexible, and easy-to-use request library that didn't compromise on performance and features.

Built-in URL validator - we wanted to validate URLs before making requests
Return useful statistics, such as time, response headers, options used, and checksum
Detailed error messages - Describe exactly where and how things went wrong - not just an Error object
Minimize dependencies - less licensing and code to review (for security and legal purposes) & insanely fast installs

Goals

Keep it simple
Keep it flexible
Keep it fast - its name is jetta, as in jet stream
Keep it secure
Keep it lightweight (minimal dependencies)
Keep it well-documented
Keep tests and code coverage at 100%

Testing

It is extremely easy to run tests for jetta. From source simply:

$ npm install
$ npm test

See test/README.md for more details.

Credits

Forms support inspired by simple-get

Future

easy range option support
Support more languages for error messages
- See lib/jetta-error.js
See more in FUTURE.md

npm

jetta

Jetta

A powerful, multi-protocol request library and toolkit ✈️

Installation

Features

Quick Start

Usage

jetta.defaults `OBJECT`

jetta.cookieLib `OBJECT`

jetta.CookieManagerCookie `CLASS`

jetta.CookieManager `CLASS` extends `EventEmitter`

jetta.domainLib `OBJECT`

jetta.makeNestedDirectory `FUNCTION`

jetta.JettaError `CLASS` extends `Error`

jetta.PublicSuffix `CLASS` extends `EventEmitter`

jetta.request `FUNCTION`

jetta.requestPromise `FUNCTION`

jetta.urlParser `FUNCTION`

Motivation

Goals

Testing

Credits

Future

Keywords

Install

Weekly Downloads

Version

License

Homepage

Repository

Last publish

Collaborators

jetta

Jetta

A powerful, multi-protocol request library and toolkit ✈️

Installation

Features

Quick Start

Usage

jetta.defaults OBJECT

jetta.cookieLib OBJECT

jetta.CookieManagerCookie CLASS

jetta.CookieManager CLASS extends EventEmitter

jetta.domainLib OBJECT

jetta.makeNestedDirectory FUNCTION

jetta.JettaError CLASS extends Error

jetta.PublicSuffix CLASS extends EventEmitter

jetta.request FUNCTION

jetta.requestPromise FUNCTION

jetta.urlParser FUNCTION

Motivation

Goals

Testing

Credits

Future

Keywords

Install

DownloadsWeekly Downloads

Version

License

Homepage

Repository

Last publish

Collaborators

jetta.defaults `OBJECT`

jetta.cookieLib `OBJECT`

jetta.CookieManagerCookie `CLASS`

jetta.CookieManager `CLASS` extends `EventEmitter`

jetta.domainLib `OBJECT`

jetta.makeNestedDirectory `FUNCTION`

jetta.JettaError `CLASS` extends `Error`

jetta.PublicSuffix `CLASS` extends `EventEmitter`

jetta.request `FUNCTION`

jetta.requestPromise `FUNCTION`

jetta.urlParser `FUNCTION`

Weekly Downloads