Skip to content

cookie-lib.md

Latest commit

 

History

History
160 lines (146 loc) · 7.51 KB

cookie-lib.md

File metadata and controls

160 lines (146 loc) · 7.51 KB

jetta.cookieLib OBJECT

  • A utility for parsing, stringifying, and validating cookies.
  • Example:
const cookie = jetta.cookieLib.parseSetCookie('id=example; Domain=example.com; Secure; SameSite')

  • Options for jetta.cookieLib.parse* and jetta.cookieLib.stringify* can be found at cookie-options.md

  • All options are optional (defaults can be found in jetta.defaults.cookie)

  • All methods may throw an instance of JettaError if something is invalid.

  • new jetta.cookieLib.ParsedCookieHeader()

    • Represents a parsed Cookie header

    • Handy for using with instanceof and instance.constructor throughout your codebase

    • instance OBJECT

      • name (alias Name) STRING

      • value (alias Value) STRING

      • Aliases are getters and setters

  • new jetta.cookieLib.ParsedSetCookieHeader()

    • Represents a parsed Set-Cookie header

    • Handy for using with instanceof and instance.constructor throughout your codebase

    • instance OBJECT

      • name (alias Name) STRING

      • value (alias Value) STRING

      • Expires (alias expires) DATE | null

      • Max-Age (alias max-age, maxAge) NUMBER | null

        • In seconds, not milliseconds (for uniformity with the spec)

      • Domain (alias domain) STRING | null

      • Path (alias path) STRING | null

      • Secure (alias secure) BOOLEAN | null

      • HttpOnly (alias 'http-only', 'Http-Only', httpOnly, httponly) BOOLEAN | null

      • SameSite (alias sameSite, samesite) STRING<'None','Strict','Lax'> | null

      • Aliases are getters and setters

      • Any other cookie attributes/information will be passed as-is

        • true if no value, string otherwise

  • jetta.cookieLib.parseCookie(cookieString STRING[, options OBJECT])

    • Parses the value from a Cookie header into an array of objects

    • Each object is an instance of jetta.cookieLib.ParsedCookieHeader with name and value

    • Example:

      jetta.cookieLib.parseCookie('user=bob; color=blue')
// returns:
// [ ParsedCookieHeader { name: 'user', value: 'bob' },
// ParsedCookieHeader { name: 'color', value: 'blue' } ]

    • return ARRAY<instanceof jetta.cookieLib.ParsedCookieHeader>

  • jetta.cookieLib.parseCookieKV(cookieString STRING[, options OBJECT])

    • Parses the value from a Cookie header into a key-value object, where key is the cookie's name

    • Example:

      jetta.cookieLib.parseCookieKV('user=bob; color=blue')
// returns: { user: 'bob', color: 'blue' }

    • return OBJECT

  • jetta.cookieLib.parseSetCookie(cookieString STRING[, options OBJECT])

    • Parses the value from a Set-Cookie header - into an object with various cookie attributes

    • Example:

      jetta.cookieLib.parseSetCookie('id=1502909778285-2-4892-bob-1a; expires=Thu, 01 Jul 2021 04:00:00 GMT; path=/; domain=.example.com; HttpOnly; Secure')
// returns:
// ParsedSetCookieHeader {
// name: 'id',
// value: '1502909778285-2-4892-bob-1a',
// Expires: 2021-07-01T04:00:00.000Z,
// 'Max-Age': null,
// Domain: 'example.com',
// Path: '/',
// Secure: true,
// HttpOnly: true,
// SameSite: null }

    • return instanceof jetta.cookieLib.ParsedSetCookieHeader

  • jetta.cookieLib.stringifyCookie(cookieList ARRAY[, options OBJECT])

    • Stringifies an array of objects into a value for a cookie header

    • The objects in the array passed to the function may be:

      • instanceof jetta.cookieLib.ParsedCookieHeader
      • instanceof jetta.cookieLib.ParsedSetCookieHeader
      • Any OBJECT with name and value attributes

    • Removes any unnecessary wrapping double-quotes around the value

    • Example:

      jetta.cookieLib.stringifyCookie([{name: 'cat', value: 'Internet'}, {name: 'js', value: '"JavaScript"'}])
// returns: 'cat=Internet; js=JavaScript'

    • return STRING

  • jetta.cookieLib.stringifyCookieKV(cookieKeyValues OBJECT[, options OBJECT])

    • Stringifies an object of key-value attributes into a value for a cookie header (where key = cookie's name)

    • Removes any unnecessary wrapping double-quotes around the value

    • Example:

      jetta.cookieLib.stringifyCookieKV({cat: 'Internet', js: '"JavaScript"'})
// returns: 'cat=Internet; js=JavaScript'

    • return STRING

  • jetta.cookieLib.stringifySetCookie(cookie OBJECT[, options OBJECT])

    • Stringifies a cookie-like object into a string to be used with a Set-Cookie header

    • Removes any unnecessary wrapping double-quotes around the value

    • Can pass an instanceof jetta.cookieLib.ParsedSetCookieHeader or Object

    • If passing an Object:

      • keys can match the aliases from jetta.cookieLib.ParsedSetCookieHeader
      • Expires can be a Date, Number (milliseconds since UNIX epoch, e.g. Date.now()), or Date string
      • Max-Age is a Number in seconds
      • SameSite can be a string or boolean

    • Example:

      jetta.cookieLib.stringifySetCookie({name: 'example', value: 'cookie', Expires: new Date(1498591378533)})
// returns: 'example=cookie; Expires=Tue, 27 Jun 2017 19:22:58 GMT'

    • return STRING

  • jetta.cookieLib.safeHTTPMethods OBJECT

    • An an object of HTTP methods that are considered to be 'safe'
    • Example: 
      jetta.cookieLib.safeHTTPMethods.GET === true
jetta.cookieLib.safeHTTPMethods.POST === undefined
jetta.cookieLib.safeHTTPMethods.UNKNOWN_METHOD === undefined

  • jetta.cookieLib.validCookieNameRegex REGEXP

    • A regular expression generated from RFC 6265 Section 4.1.1 for valid cookie names
    • Example: 
      jetta.cookieLib.validCookieNameRegex.test('example') === true
jetta.cookieLib.validCookieNameRegex.test('') === false
jetta.cookieLib.validCookieNameRegex.test('ø') === false

  • jetta.cookieLib.validCookieValueRegex REGEXP

    • A regular expression generated from RFC 6265 Section 4.1.1 for valid cookie values
    • Example: 
      jetta.cookieLib.validCookieValueRegex.test('example') === true
jetta.cookieLib.validCookieValueRegex.test('') === true
jetta.cookieLib.validCookieValueRegex.test('a b') === false
jetta.cookieLib.validCookieValueRegex.test('π') === false

  • jetta.cookieLib.validPathValueRegex REGEXP

    • A regular expression generated from RFC 6265 Section 4.1.1 for valid cookie paths
    • Example: 
      jetta.cookieLib.validPathValueRegex.test('example') === true
jetta.cookieLib.validPathValueRegex.test('some/path/example') === true
jetta.cookieLib.validPathValueRegex.test('') === true
jetta.cookieLib.validPathValueRegex.test('a b') === true
jetta.cookieLib.validPathValueRegex.test(';') === false
jetta.cookieLib.validPathValueRegex.test('π') === false

  • jetta.cookieLib.trailingSemicolonRegex REGEXP

    • A regular expression for trailing semicolons

    • For 100% cross-platform compatibility there is no built-in encoder/decoder for cookie names & values (most US-ASCII characters are accepted). You can easily use decodeURIComponent and encodeURIComponent where necessary and can test via jetta.cookieLib.validCookieNameRegex, jetta.cookieLib.validCookieValueRegex, and jetta.cookieLib.validPathValueRegex (the jetta.cookieLib.parse* and jetta.cookieLib.stringify* functions use these internally).