Skip to content

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

License

Notifications You must be signed in to change notification settings

danielbankhead/jetta

Repository files navigation

Jetta

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

Jetta by Altus Aero npm version npm total downloads npm license AppVeyor Travis CI Travis CI GitHub - Issues Open GitHub - Pull Requests Open GitHub - Contributors Node Security Platform Standard - JavaScript Style Guide

Jetta logo

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')

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()

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()

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

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'))

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')

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()

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})
})

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:'

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

Future

  • easy range option support

  • Support more languages for error messages

    • See lib/jetta-error.js
  • See more in FUTURE.md