jetta
v1.2.0
Published
A powerful, multi-protocol request library and toolkit ✈️
Downloads
119
Maintainers
danielbankheadReadme
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 jettaFeatures
- 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.CookieManagerinstances where cookies are returned - Handy for using with
instanceofand instance.constructorthroughout 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.PublicSuffixto 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:, anddata:protocols - Auto-parse JSON responses, no need for
JSON.parse/try/catchpost-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
enginessupport, bring your own support forhttp:,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
resultsattribute jetta.requestPromise.constantsis the same asjetta.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 testSee 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