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/'
$ npm install jetta
- 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
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}`)
}
})
- The global default options
- Options passed to jetta functions and constructors will overwrite these defaults for that particular call or instance
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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/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 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.
- 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 asjetta.request.constants
- Complete documentation can be found in docs/request.md.
- 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.
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
- 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%
It is extremely easy to run tests for jetta. From source simply:
$ npm install
$ npm test
See test/README.md for more details.
- Forms support inspired by simple-get
-
easy range option support
-
Support more languages for error messages
- See lib/jetta-error.js
-
See more in FUTURE.md