Jetta
A powerful, multi-protocol request library and toolkit ✈️
const jetta = jetta
// Other useful tools: { results = await jetta} const cookieManager = const publicSuffix = jettaisValid // falsejettaisLocalhost // truejettaparsedURLhref // '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 = const imageURL = 'https://altusaero.net/opensource/jetta/logo/1.2/jetta.svg'const options = toFile: 'jetta.svg' jetta
Usage
OBJECT
jetta.defaults - The global default options
- Options passed to jetta functions and constructors will overwrite these defaults for that particular call or instance
OBJECT
jetta.cookieLib - A utility for parsing, stringifying, and validating cookies.
- Example:
const cookie = jettacookieLib
- Complete documentation can be found in docs/cookie-lib.md.
CLASS
jetta.CookieManagerCookie - 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 =
- Complete documentation can be found in docs/cookie-manager.md.
CLASS
extends EventEmitter
jetta.CookieManager - 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 =
- Complete documentation can be found in docs/cookie-manager.md.
OBJECT
jetta.domainLib - A utility for comparing and analyzing domains
- Example:
jettadomainLib // truejettadomainLib // truejettadomainLib // truejettadomainLib // false
- Complete documentation can be found in docs/domain-lib.md.
FUNCTION
jetta.makeNestedDirectory - 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
- Complete documentation can be found in docs/make-nested-directory.md.
CLASS
extends Error
jetta.JettaError - 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 = 'jetta-cookie-invalid-name' 'en'
- Complete documentation can be found in docs/jetta-error.md.
CLASS
extends EventEmitter
jetta.PublicSuffix - 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 =
- Complete documentation can be found in docs/public-suffix.md.
FUNCTION
jetta.request - 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
- Complete documentation can be found in docs/request.md.
FUNCTION
jetta.requestPromise - A promise version of
jetta.request
- Uses the same options and parameters as
jetta.request
, with the exception of a callback - Example:
jetta
- 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.
FUNCTION
jetta.urlParser - A utility for parsing and validating URLs
- Provides options for strict and lax validation
- Example:
const urlResults = jetta urlResultsisLocalhost // falseurlResultsisValid // trueurlResultsparsedURLprotocol // '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