diff --git a/.eslintrc.json b/.eslintrc.json index 80d4ed74..50450a60 100644 --- a/.eslintrc.json +++ b/.eslintrc.json @@ -14,6 +14,6 @@ "reportUnusedDisableDirectives": true, "rules": { "@typescript-eslint/explicit-function-return-type": "error", - "max-lines": ["warn", 500] + "max-lines": ["warn", 2000] } } diff --git a/.github/workflows/integration.yaml b/.github/workflows/integration.yaml index d339d48a..7eb3876c 100644 --- a/.github/workflows/integration.yaml +++ b/.github/workflows/integration.yaml @@ -1,28 +1,82 @@ -name: Actions-CI +name: CI on: push: - branches: [master, v5] + branches: [master] pull_request: - branches: [master, v5] + +permissions: + contents: read jobs: - build: + lint: + name: Lint runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: lts/* + cache: npm + - name: Install dependencies + run: npm ci + - name: Run Linter + run: npm run eslint + - name: Run Formatter + run: npm run prettier + test: + name: Test - ${{ matrix.node-version }} + runs-on: ubuntu-latest strategy: + fail-fast: false matrix: node-version: [latest, lts/*, lts/-1] - steps: - - uses: actions/checkout@v2 - - name: Use Node.js ${{ matrix.node-version }} - uses: actions/setup-node@v3 + - name: Checkout + uses: actions/checkout@v4 + - name: Setup Node.js (${{ matrix.node-version }}) + uses: actions/setup-node@v4 with: node-version: ${{ matrix.node-version }} cache: npm - - name: Install dependencies and test - run: npm install - - run: npm test - - run: npm run eslint - - run: npm run prettier + - name: Install dependencies + run: npm ci + - name: Run tests + run: npm test + + api: + name: API & Doc Validation + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: lts/* + cache: npm + - name: Install dependencies + run: npm ci + - name: Build + run: npm run build + - name: Extract API + run: npm run api:extract + - name: Generate docs + run: npm run api:docs + - name: Ensure API and doc changes have been committed + run: | + git add --renormalize . + if (( "$(git diff --ignore-space-at-eol --ignore-cr-at-eol | wc -l)" != 0 )); then + cat << EOF >> $GITHUB_STEP_SUMMARY + ### Detected uncommitted changes + + \`\`\`shell + $(git diff) + \`\`\` + EOF + git diff + exit 1 + fi diff --git a/.gitignore b/.gitignore index a0fc24a8..881cc62e 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,4 @@ coverage .config .bash_history dist/ +tmp/ diff --git a/README.md b/README.md index 0a5b90c4..fd308839 100644 --- a/README.md +++ b/README.md @@ -1,586 +1,144 @@ -# tough-cookie +# Tough Cookie · [![RFC6265][rfc6265-badge]][rfc6265-tracker] [![RFC6265bis][rfc6265bis-badge]][rfc6265bis-tracker] [![npm version][npm-badge]][npm-repo] [![CI on Github Actions: salesforce/tough-cookie][ci-badge]][ci-url] ![PRs Welcome][prs-welcome-badge] -[RFC 6265](https://tools.ietf.org/html/rfc6265) Cookies and CookieJar for Node.js +A Node.js implementation of [RFC6265][rfc6265-tracker] for cookie parsing, storage, and retrieval. -[![npm package](https://nodei.co/npm/tough-cookie.png?downloads=true&downloadRank=true&stars=true)](https://nodei.co/npm/tough-cookie/) +## Getting Started -[![Build Status](https://travis-ci.org/salesforce/tough-cookie.svg?branch=master)](https://travis-ci.org/salesforce/tough-cookie) +Install Tough Cookie using [`npm`][npm-repo]: -## Synopsis - -```javascript -var tough = require('tough-cookie') -var Cookie = tough.Cookie -var cookie = Cookie.parse(header) -cookie.value = 'somethingdifferent' -header = cookie.toString() -var cookiejar = new tough.CookieJar() - -// Asynchronous! -var cookie = await cookiejar.setCookie( - cookie, - 'https://currentdomain.example.com/path', -) -var cookies = await cookiejar.getCookies('https://example.com/otherpath') - -// Or with callbacks! -cookiejar.setCookie( - cookie, - 'https://currentdomain.example.com/path', - function (err, cookie) { - /* ... */ - }, -) -cookiejar.getCookies('http://example.com/otherpath', function (err, cookies) { - /* ... */ -}) -``` - -Why the name? NPM modules `cookie`, `cookies` and `cookiejar` were already taken. - -## Installation - -It's _so_ easy! Install with `npm` or your preferred package manager. - -```sh +```shell npm install tough-cookie ``` -## Node.js Version Support - -We follow the [node.js release schedule](https://github.com/nodejs/Release#release-schedule) and support all versions that are in Active LTS or Maintenance. We will always do a major release when dropping support for older versions of node, and we will do so in consultation with our community. - -## API - -### tough - -The top-level exports from `require('tough-cookie')` can all be used as pure functions and don't need to be bound. - -#### `parseDate(string)` - -Parse a cookie date string into a `Date`. Parses according to [RFC 6265 Section 5.1.1](https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.1), not `Date.parse()`. - -#### `formatDate(date)` - -Format a `Date` into an [RFC 822](https://datatracker.ietf.org/doc/html/rfc822#section-5) string (the RFC 6265 recommended format). - -#### `canonicalDomain(str)` - -Transforms a domain name into a canonical domain name. The canonical domain name is a domain name that has been trimmed, lowercased, stripped of leading dot, and optionally punycode-encoded ([Section 5.1.2 of RFC 6265](https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.2)). For the most part, this function is idempotent (calling the function with the output from a previous call returns the same output). - -#### `domainMatch(str, domStr[, canonicalize=true])` - -Answers "does this real domain match the domain in a cookie?". The `str` is the "current" domain name and the `domStr` is the "cookie" domain name. Matches according to [RFC 6265 Section 5.1.3](https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.3), but it helps to think of it as a "suffix match". - -The `canonicalize` parameter toggles whether the domain parameters get normalized with `canonicalDomain` or not. - -#### `defaultPath(path)` - -Given a current request/response path, gives the path appropriate for storing in a cookie. This is basically the "directory" of a "file" in the path, but is specified by [Section 5.1.4 of the RFC](https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.4). - -The `path` parameter MUST be _only_ the pathname part of a URI (excluding the hostname, query, fragment, and so on). This is the `.pathname` property of node's `uri.parse()` output. +or [`yarn`][yarn-repo]: -#### `pathMatch(reqPath, cookiePath)` - -Answers "does the request-path path-match a given cookie-path?" as per [RFC 6265 Section 5.1.4](https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.4). Returns a boolean. - -This is essentially a prefix-match where `cookiePath` is a prefix of `reqPath`. - -#### `parse(cookieString[, options])` - -Alias for [`Cookie.parse(cookieString[, options])`](#cookieparsecookiestring-options). - -#### `fromJSON(string)` - -Alias for [`Cookie.fromJSON(string)`](#cookiefromjsonstrorobj). - -#### `getPublicSuffix(hostname)` - -Returns the public suffix of this hostname. The public suffix is the shortest domain name upon which a cookie can be set. Returns `null` if the hostname cannot have cookies set for it. - -For example: `www.example.com` and `www.subdomain.example.com` both have public suffix `example.com`. - -For further information, see the [Public Suffix List](http://publicsuffix.org/). This module derives its list from that site. This call is a wrapper around [`psl`](https://www.npmjs.com/package/psl)'s [`get` method](https://www.npmjs.com/package/psl##pslgetdomain). - -#### `cookieCompare(a, b)` - -For use with `.sort()`, sorts a list of cookies into the recommended order given in step 2 of ([RFC 6265 Section 5.4](https://datatracker.ietf.org/doc/html/rfc6265#section-5.4)). The sort algorithm is, in order of precedence: - -- Longest `.path` -- oldest `.creation` (which has a 1-ms precision, same as `Date`) -- lowest `.creationIndex` (to get beyond the 1-ms precision) - -```javascript -var cookies = [ - /* unsorted array of Cookie objects */ -] -cookies = cookies.sort(cookieCompare) +```shell +yarn add tough-cookie ``` -> **Note**: Since the JavaScript `Date` is limited to a 1-ms precision, cookies within the same millisecond are entirely possible. This is especially true when using the `now` option to `.setCookie()`. The `.creationIndex` property is a per-process global counter, assigned during construction with `new Cookie()`, which preserves the spirit of the RFC sorting: older cookies go first. This works great for `MemoryCookieStore` since `Set-Cookie` headers are parsed in order, but is not so great for distributed systems. Sophisticated `Store`s may wish to set this to some other _logical clock_ so that if cookies A and B are created in the same millisecond, but cookie A is created before cookie B, then `A.creationIndex < B.creationIndex`. If you want to alter the global counter, which you probably _shouldn't_ do, it's stored in `Cookie.cookiesCreated`. - -#### `permuteDomain(domain)` - -Generates a list of all possible domains that `domainMatch()` the parameter. Can be handy for implementing cookie stores. - -#### `permutePath(path)` - -Generates a list of all possible paths that `pathMatch()` the parameter. Can be handy for implementing cookie stores. - -### Cookie - -Exported via `tough.Cookie`. - -#### `Cookie.parse(cookieString[, options])` - -Parses a single Cookie or Set-Cookie HTTP header into a `Cookie` object. Returns `undefined` if the string can't be parsed. - -The options parameter is not required and currently has only one property: - -- _loose_ - boolean - if `true` enable parsing of keyless cookies like `=abc` and `=`, which are not RFC-compliant. - -If options is not an object it is ignored, which means it can be used with [`Array#map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map). - -To process the Set-Cookie header(s) on a node HTTP/HTTPS response: - -```javascript -if (Array.isArray(res.headers['set-cookie'])) - cookies = res.headers['set-cookie'].map(Cookie.parse) -else cookies = [Cookie.parse(res.headers['set-cookie'])] -``` - -_Note:_ In version 2.3.3, tough-cookie limited the number of spaces before the `=` to 256 characters. This limitation was removed in version 2.3.4. -For more details, see [issue #92](https://github.com/salesforce/tough-cookie/issues/92). - -#### Properties - -Cookie object properties: - -- _key_ - string - the name or key of the cookie (default `""`) -- _value_ - string - the value of the cookie (default `""`) -- _expires_ - `Date` - if set, the `Expires=` attribute of the cookie (defaults to the string `"Infinity"`). See `setExpires()` -- _maxAge_ - seconds - if set, the `Max-Age=` attribute _in seconds_ of the cookie. Can also be set to strings `"Infinity"` and `"-Infinity"` for non-expiry and immediate-expiry, respectively. See `setMaxAge()` -- _domain_ - string - the `Domain=` attribute of the cookie -- _path_ - string - the `Path=` of the cookie -- _secure_ - boolean - the `Secure` cookie flag -- _httpOnly_ - boolean - the `HttpOnly` cookie flag -- _sameSite_ - string - the `SameSite` cookie attribute (from [RFC 6265bis](#rfc-6265bis)); must be one of `none`, `lax`, or `strict` -- _extensions_ - `Array` - any unrecognized cookie attributes as strings (even if equal-signs inside) -- _creation_ - `Date` - when this cookie was constructed -- _creationIndex_ - number - set at construction, used to provide greater sort precision (see `cookieCompare(a,b)` for a full explanation) - -After a cookie has been passed through `CookieJar.setCookie()` it has the following additional attributes: - -- _hostOnly_ - boolean - is this a host-only cookie (that is, no Domain field was set, but was instead implied). -- _pathIsDefault_ - boolean - if true, there was no Path field on the cookie and `defaultPath()` was used to derive one. -- _creation_ - `Date` - **modified** from construction to when the cookie was added to the jar. -- _lastAccessed_ - `Date` - last time the cookie got accessed. Affects cookie cleaning after it is implemented. Using `cookiejar.getCookies(...)` updates this attribute. - -#### `new Cookie([properties])` - -Receives an options object that can contain any of the above Cookie properties. Uses the default for unspecified properties. - -#### `.toString()` - -Encodes to a Set-Cookie header value. The Expires cookie field is set using `formatDate()`, but is omitted entirely if `.expires` is `Infinity`. - -#### `.cookieString()` - -Encodes to a Cookie header value (specifically, the `.key` and `.value` properties joined with `"="`). - -#### `.setExpires(string)` - -Sets the expiry based on a date-string passed through `parseDate()`. If parseDate returns `null` (that is, can't parse this date string), `.expires` is set to `"Infinity"` (a string). - -#### `.setMaxAge(number)` - -Sets the maxAge in seconds. Coerces `-Infinity` to `"-Infinity"` and `Infinity` to `"Infinity"` so it correctly serializes to JSON. - -#### `.expiryDate([now=Date.now()])` - -`expiryTime()` computes the absolute unix-epoch milliseconds that this cookie expires. `expiryDate()` works similarly, except it returns a `Date` object. Note that in both cases the `now` parameter should be milliseconds. - -Max-Age takes precedence over Expires (as per the RFC). The `.creation` attribute -- or, by default, the `now` parameter -- is used to offset the `.maxAge` attribute. - -If Expires (`.expires`) is set, that's returned. - -Otherwise, `expiryTime()` returns `Infinity` and `expiryDate()` returns a `Date` object for "Tue, 19 Jan 2038 03:14:07 GMT" (latest date that can be expressed by a 32-bit `time_t`; the common limit for most user-agents). - -#### `.TTL([now=Date.now()])` - -Computes the TTL relative to `now` (milliseconds). The same precedence rules as for `expiryTime`/`expiryDate` apply. - -`Infinity` is returned for cookies without an explicit expiry and `0` is returned if the cookie is expired. Otherwise a time-to-live in milliseconds is returned. - -#### `.canonicalizedDomain()` - -#### `.cdomain()` - -Returns the canonicalized `.domain` field. This is lower-cased and punycode ([RFC 3490](https://datatracker.ietf.org/doc/html/rfc3490)) encoded if the domain has any non-ASCII characters. - -#### `.toJSON()` - -For convenience in using `JSON.stringify(cookie)`. Returns a plain-old `Object` that can be JSON-serialized. - -Any `Date` properties (such as `.expires`, `.creation`, and `.lastAccessed`) are exported in ISO format (`.toISOString()`). - -> **NOTE**: Custom `Cookie` properties are discarded. In tough-cookie 1.x, since there was no `.toJSON` method explicitly defined, all enumerable properties were captured. If you want a property to be serialized, add the property name to the `Cookie.serializableProperties` Array. - -#### `Cookie.fromJSON(strOrObj)` - -Does the reverse of `cookie.toJSON()`. If passed a string, will `JSON.parse()` that first. - -Any `Date` properties (such as `.expires`, `.creation`, and `.lastAccessed`) are parsed via [`Date.parse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse), not tough-cookie's `parseDate`, since ISO timestamps are being handled at this layer. - -Returns `null` upon a JSON parsing error. - -#### `.clone()` - -Does a deep clone of this cookie, implemented exactly as `Cookie.fromJSON(cookie.toJSON())`. - -#### `.validate()` - -Status: _IN PROGRESS_. Works for a few things, but is by no means comprehensive. - -Validates cookie attributes for semantic correctness. Useful for "lint" checking any Set-Cookie headers you generate. For now, it returns a boolean, but eventually could return a reason string. Future-proof with this construct: - -```javascript -if (cookie.validate() === true) { - // it's tasty -} else { - // yuck! -} -``` - -### CookieJar - -Exported via `tough.CookieJar`. - -#### `CookieJar([store][, options])` - -Simply use `new CookieJar()`. If a custom store is not passed to the constructor, a [`MemoryCookieStore`](#memorycookiestore) is created and used. - -The `options` object can be omitted and can have the following properties: - -- _rejectPublicSuffixes_ - boolean - default `true` - reject cookies with domains like "com" and "co.uk" -- _looseMode_ - boolean - default `false` - accept malformed cookies like `bar` and `=bar`, which have an implied empty name. -- _prefixSecurity_ - string - default `silent` - set to `'unsafe-disabled'`, `'silent'`, or `'strict'`. See [Cookie Prefixes](#cookie-prefixes) below. -- _allowSpecialUseDomain_ - boolean - default `true` - accepts special-use domain suffixes, such as `local`. Useful for testing purposes. - This is not in the standard, but is used sometimes on the web and is accepted by most browsers. - -#### `.setCookie(cookieOrString, currentUrl[, options][, callback(err, cookie)])` - -Attempt to set the cookie in the cookie jar. The cookie has updated `.creation`, `.lastAccessed` and `.hostOnly` properties. And returns a promise if a callback is not provided. - -The `options` object can be omitted and can have the following properties: - -- _http_ - boolean - default `true` - indicates if this is an HTTP or non-HTTP API. Affects `HttpOnly` cookies. -- _secure_ - boolean - autodetect from URL - indicates if this is a "Secure" API. If the currentUrl starts with `https:` or `wss:` this defaults to `true`, otherwise `false`. -- _now_ - Date - default `new Date()` - what to use for the creation or access time of cookies. -- _ignoreError_ - boolean - default `false` - silently ignore things like parse errors and invalid domains. `Store` errors aren't ignored by this option. -- _sameSiteContext_ - string - default unset - set to `'none'`, `'lax'`, or `'strict'` See [SameSite Cookies](#samesite-cookies) below. +## Usage -As per the RFC, the `.hostOnly` property is set if there was no "Domain=" parameter in the cookie string (or `.domain` was null on the Cookie object). The `.domain` property is set to the fully-qualified hostname of `currentUrl` in this case. Matching this cookie requires an exact hostname match (not a `domainMatch` as per usual). +```typescript +import { Cookie, CookieJar } from 'tough-cookie' -#### `.setCookieSync(cookieOrString, currentUrl[, options])` +// parse a `Cookie` request header +const reqCookies = 'ID=298zf09hf012fh2; csrf=u32t4o3tb3gg43; _gat=1'.split(';').map(Cookie.parse) +// generate a `Cookie` request header +const cookieHeader = reqCookies.map(cookie => cookie.cookieString()).join(';') -Synchronous version of [`setCookie`](#setcookiecookieorstring-currenturl-options-callbackerr-cookie); only works with synchronous stores (that is, the default `MemoryCookieStore`). +// parse a Set-Cookie response header +const resCookie = Cookie.parse('foo=bar; Domain=example.com; Path=/; Expires=Tue, 21 Oct 2025 00:00:00 GMT') +// generate a Set-Cookie response header +const setCookieHeader = cookie.toString() -#### `.getCookies(currentUrl[, options][, callback(err, cookies)])` - -Retrieve the list of cookies that can be sent in a Cookie header for the current URL. Returns a promise if a callback is not provided. - -Returns an array of `Cookie` objects, sorted by default using [`cookieCompare`](#cookiecomparea-b). - -If an error is encountered it's passed as `err` to the callback, otherwise an array of `Cookie` objects is passed. The array is sorted with `cookieCompare()` unless the `{sort:false}` option is given. - -The `options` object can be omitted and can have the following properties: - -- _http_ - boolean - default `true` - indicates if this is an HTTP or non-HTTP API. Affects `HttpOnly` cookies. -- _secure_ - boolean - autodetect from URL - indicates if this is a "Secure" API. If the currentUrl starts with `https:` or `wss:` then this is defaulted to `true`, otherwise `false`. -- _now_ - Date - default `new Date()` - what to use for the creation or access time of cookies -- _expire_ - boolean - default `true` - perform expiry-time checking of cookies and asynchronously remove expired cookies from the store. Using `false` returns expired cookies and does **not** remove them from the store (which is potentially useful for replaying Set-Cookie headers). -- _allPaths_ - boolean - default `false` - if `true`, do not scope cookies by path. The default uses RFC-compliant path scoping. **Note**: may not be supported by the underlying store (the default `MemoryCookieStore` supports it). -- _sameSiteContext_ - string - default unset - Set this to `'none'`, `'lax'`, or `'strict'` to enforce SameSite cookies upon retrieval. See [SameSite Cookies](#samesite-cookies) below. -- _sort_ - boolean - whether to sort the list of cookies. - -The `.lastAccessed` property of the returned cookies will have been updated. - -#### `.getCookiesSync(currentUrl, [{options}])` - -Synchronous version of [`getCookies`](#getcookiescurrenturl-options-callbackerr-cookies); only works with synchronous stores (for example, the default `MemoryCookieStore`). - -#### `.getCookieString(...)` - -Accepts the same options as [`.getCookies()`](#getcookiescurrenturl-options-callbackerr-cookies) but returns a string suitable for a Cookie header rather than an Array. - -#### `.getCookieStringSync(...)` - -Synchronous version of [`getCookieString`](#getcookiestring); only works with synchronous stores (for example, the default `MemoryCookieStore`). - -#### `.getSetCookieStrings(...)` - -Returns an array of strings suitable for **Set-Cookie** headers. Accepts the same options as [`.getCookies()`](#getcookiescurrenturl-options-callbackerr-cookies). Simply maps the cookie array via `.toString()`. - -#### `.getSetCookieStringsSync(...)` - -Synchronous version of [`getSetCookieStrings`](#getsetcookiestrings); only works with synchronous stores (for example, the default `MemoryCookieStore`). - -#### `.serialize([callback(err, serializedObject)])` - -Returns a promise if a callback is not provided. - -Serialize the Jar if the underlying store supports `.getAllCookies`. - -> **NOTE**: Custom `Cookie` properties are discarded. If you want a property to be serialized, add the property name to the `Cookie.serializableProperties` Array. - -See [Serialization Format](#serialization-format). - -#### `.serializeSync()` - -Synchronous version of [`serialize`](#serializecallbackerr-serializedobject); only works with synchronous stores (for example, the default `MemoryCookieStore`). - -#### `.toJSON()` - -Alias of [`.serializeSync()`](#serializesync) for the convenience of `JSON.stringify(cookiejar)`. - -#### `CookieJar.deserialize(serialized[, store][, callback(err, object)])` - -A new Jar is created and the serialized Cookies are added to the underlying store. Each `Cookie` is added via `store.putCookie` in the order in which they appear in the serialization. A promise is returned if a callback is not provided. - -The `store` argument is optional, but should be an instance of `Store`. By default, a new instance of `MemoryCookieStore` is created. - -As a convenience, if `serialized` is a string, it is passed through `JSON.parse` first. - -#### `CookieJar.deserializeSync(serialized[, store])` - -Sync version of [`.deserialize`](#cookiejardeserializeserialized-store-callbackerr-object); only works with synchronous stores (for example, the default `MemoryCookieStore`). - -#### `CookieJar.fromJSON(string)` - -Alias of [`.deserializeSync`](#cookiejardeserializesyncserialized-store) to provide consistency with [`Cookie.fromJSON()`](#cookiefromjsonstrorobj). - -#### `.clone([store][, callback(err, cloned))` - -Produces a deep clone of this jar. Modifications to the original do not affect the clone, and vice versa. Returns a promise if a callback is not provided. - -The `store` argument is optional, but should be an instance of `Store`. By default, a new instance of `MemoryCookieStore` is created. Transferring between store types is supported so long as the source implements `.getAllCookies()` and the destination implements `.putCookie()`. - -#### `.cloneSync([store])` - -Synchronous version of [`.clone`](#clonestore-callbackerr-cloned), returning a new `CookieJar` instance. - -The `store` argument is optional, but must be a _synchronous_ `Store` instance if specified. If not passed, a new instance of `MemoryCookieStore` is used. - -The _source_ and _destination_ must both be synchronous `Store`s. If one or both stores are asynchronous, use `.clone` instead. Recall that `MemoryCookieStore` supports both synchronous and asynchronous API calls. - -#### `.removeAllCookies([callback(err)])` - -Removes all cookies from the jar. Returns a promise if a callback is not provided. - -This is a new backwards-compatible feature of `tough-cookie` version 2.5, so not all Stores will implement it efficiently. For Stores that do not implement `removeAllCookies`, the fallback is to call `removeCookie` after `getAllCookies`. If `getAllCookies` fails or isn't implemented in the Store, that error is returned. If one or more of the `removeCookie` calls fail, only the first error is returned. - -#### `.removeAllCookiesSync()` - -Sync version of [`.removeAllCookies()`](#removeallcookiescallbackerr); only works with synchronous stores (for example, the default `MemoryCookieStore`). - -### Store - -Base class for CookieJar stores. Available as `tough.Store`. - -### Store API - -The storage model for each `CookieJar` instance can be replaced with a custom implementation. The default is `MemoryCookieStore` which can be found in [`lib/memstore.ts`](https://github.com/salesforce/tough-cookie/blob/master/lib/memstore.ts). The API uses continuation-passing-style to allow for asynchronous stores. - -Stores should inherit from the base `Store` class, which is available as a top-level export. - -Stores are asynchronous by default, but if `store.synchronous` is set to `true`, then the `*Sync` methods of the containing `CookieJar` can be used. - -All `domain` parameters are normalized before calling. - -The Cookie store must have all of the following methods. Note that asynchronous implementations **must** support callback parameters. - -#### `store.findCookie(domain, path, key, callback(err, cookie))` - -Retrieve a cookie with the given domain, path, and key (name). The RFC maintains that exactly one of these cookies should exist in a store. If the store is using versioning, this means that the latest or newest such cookie should be returned. - -Callback takes an error and the resulting `Cookie` object. If no cookie is found then `null` MUST be passed instead (that is, not an error). - -#### `store.findCookies(domain, path, allowSpecialUseDomain, callback(err, cookies))` - -Locates cookies matching the given domain and path. This is most often called in the context of [`cookiejar.getCookies()`](#getcookiescurrenturl-options-callbackerr-cookies). - -If no cookies are found, the callback MUST be passed an empty array. - -The resulting list is checked for applicability to the current request according to the RFC (domain-match, path-match, http-only-flag, secure-flag, expiry, and so on), so it's OK to use an optimistic search algorithm when implementing this method. However, the search algorithm used SHOULD try to find cookies that `domainMatch()` the domain and `pathMatch()` the path in order to limit the amount of checking that needs to be done. - -As of version 0.9.12, the `allPaths` option to `cookiejar.getCookies()` above causes the path here to be `null`. If the path is `null`, path-matching MUST NOT be performed (that is, domain-matching only). - -#### `store.putCookie(cookie, callback(err))` - -Adds a new cookie to the store. The implementation SHOULD replace any existing cookie with the same `.domain`, `.path`, and `.key` properties. Depending on the nature of the implementation, it's possible that between the call to `fetchCookie` and `putCookie` that a duplicate `putCookie` can occur. - -The `cookie` object MUST NOT be modified; as the caller has already updated the `.creation` and `.lastAccessed` properties. - -Pass an error if the cookie cannot be stored. - -#### `store.updateCookie(oldCookie, newCookie, callback(err))` - -Update an existing cookie. The implementation MUST update the `.value` for a cookie with the same `domain`, `.path`, and `.key`. The implementation SHOULD check that the old value in the store is equivalent to `oldCookie` - how the conflict is resolved is up to the store. - -The `.lastAccessed` property is always different between the two objects (to the precision possible via JavaScript's clock). Both `.creation` and `.creationIndex` are guaranteed to be the same. Stores MAY ignore or defer the `.lastAccessed` change at the cost of affecting how cookies are selected for automatic deletion (for example, least-recently-used, which is up to the store to implement). - -Stores may wish to optimize changing the `.value` of the cookie in the store versus storing a new cookie. If the implementation doesn't define this method, a stub that calls [`putCookie`](#storeputcookiecookie-callbackerr) is added to the store object. - -The `newCookie` and `oldCookie` objects MUST NOT be modified. - -Pass an error if the newCookie cannot be stored. - -#### `store.removeCookie(domain, path, key, callback(err))` - -Remove a cookie from the store (see notes on [`findCookie`](#storefindcookiedomain-path-key-callbackerr-cookie) about the uniqueness constraint). - -The implementation MUST NOT pass an error if the cookie doesn't exist, and only pass an error due to the failure to remove an existing cookie. - -#### `store.removeCookies(domain, path, callback(err))` - -Removes matching cookies from the store. The `path` parameter is optional and if missing, means all paths in a domain should be removed. - -Pass an error ONLY if removing any existing cookies failed. - -#### `store.removeAllCookies(callback(err))` - -_Optional_. Removes all cookies from the store. - -Pass an error if one or more cookies can't be removed. - -#### `store.getAllCookies(callback(err, cookies))` - -_Optional_. Produces an `Array` of all cookies during [`jar.serialize()`](#serializecallbackerr-serializedobject). The items in the array can be true `Cookie` objects or generic `Object`s with the [Serialization Format](#serialization-format) data structure. - -Cookies SHOULD be returned in creation order to preserve sorting via [`compareCookie()`](#cookiecomparea-b). For reference, `MemoryCookieStore` sorts by `.creationIndex` since it uses true `Cookie` objects internally. If you don't return the cookies in creation order, they'll still be sorted by creation time, but this only has a precision of 1-ms. See `cookieCompare` for more detail. - -Pass an error if retrieval fails. - -**Note**: Not all Stores can implement this due to technical limitations, so it is optional. - -### MemoryCookieStore - -Inherits from `Store`. - -A just-in-memory CookieJar synchronous store implementation, used by default. Despite being a synchronous implementation, it's usable with both the synchronous and asynchronous forms of the `CookieJar` API. Supports serialization, `getAllCookies`, and `removeAllCookies`. - -## Serialization Format - -**NOTE**: If you want to have custom `Cookie` properties serialized, add the property name to `Cookie.serializableProperties`. - -```js - { - // The version of tough-cookie that serialized this jar. - version: 'tough-cookie@1.x.y', - - // add the store type, to make humans happy: - storeType: 'MemoryCookieStore', - - // CookieJar configuration: - rejectPublicSuffixes: true, - // ... future items go here - - // Gets filled from jar.store.getAllCookies(): - cookies: [ - { - key: 'string', - value: 'string', - // ... - /* other Cookie.serializableProperties go here */ - } - ] - } +// store and retrieve cookies +const cookieJar = new CookieJar() // uses the in-memory store by default +await cookieJar.setCookie(resCookie, 'https://example.com/') +const matchingCookies = await cookieJar.getCookies('https://example.com/') ``` -## RFC 6265bis +> [!IMPORTANT] +> For more detailed usage information, refer to the [API docs](./api/docs/tough-cookie.md). -Support for RFC 6265bis revision 02 is being developed. Since this is a bit of an omnibus revision to the RFC 6252, support is broken up into the functional areas. +## RFC6265bis -### Leave Secure Cookies Alone - -Not yet supported. - -This change makes it so that if a cookie is sent from the server to the client with a `Secure` attribute, the channel must also be secure or the cookie is ignored. +Support for [RFC6265bis][rfc6265bis-tracker] is being developed. As these revisions to [RFC6252][rfc6265-tracker] are +still in `Active Internet-Draft` state, the areas of support that follow are subject to change. ### SameSite Cookies -Supported. +This change makes it possible for servers, and supporting clients, to mitigate certain types of CSRF +attacks by disallowing `SameSite` cookies from being sent cross-origin. -This change makes it possible for servers, and supporting clients, to mitigate certain types of CSRF attacks by disallowing `SameSite` cookies from being sent cross-origin. +#### Example -On the Cookie object itself, you can get or set the `.sameSite` attribute, which is serialized into the `SameSite=` cookie attribute. When unset or `undefined`, no `SameSite=` attribute is serialized. The valid values of this attribute are `'none'`, `'lax'`, or `'strict'`. Other values are serialized as-is. +```typescript +import { CookieJar } from 'tough-cookie' -When parsing cookies with a `SameSite` cookie attribute, values other than `'lax'` or `'strict'` are parsed as `'none'`. For example, `SomeCookie=SomeValue; SameSite=garbage` parses so that `cookie.sameSite === 'none'`. +const cookieJar = new CookieJar() // uses the in-memory store by default -In order to support SameSite cookies, you must provide a `sameSiteContext` option to _both_ `setCookie` and `getCookies`. Valid values for this option are just like for the Cookie object, but have particular meanings: +// storing cookies with various SameSite attributes +await cookieJar.setCookie('strict=authorized; SameSite=strict', 'http://example.com/index.html') +await cookieJar.setCookie('lax=okay; SameSite=lax', 'http://example.com/index.html') +await cookieJar.setCookie('normal=whatever', 'http://example.com/index.html') -1. `'strict'` mode - If the request is on the same "site for cookies" (see the RFC draft for more information), pass this option to add a layer of defense against CSRF. -2. `'lax'` mode - If the request is from another site, _but_ is directly because of navigation by the user, such as, `` or ``, pass `sameSiteContext: 'lax'`. -3. `'none'` - Otherwise, pass `sameSiteContext: 'none'` (this indicates a cross-origin request). -4. unset/`undefined` - SameSite **is not** be enforced! This can be a valid use-case for when CSRF isn't in the threat model of the system being built. +// retrieving cookies using a SameSite context +const laxCookies = await cookieJar.getCookies('http://example.com/index.html', { + // the first cookie (strict=authorized) will not be returned if the context is 'lax' + // but the other two cookies will be returned + sameSiteContext: 'lax', +}) +``` -It is highly recommended that you read RFC 6265bis for fine details on SameSite cookies. In particular [Section 8.8](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02##section-8.8) discusses security considerations and defense in depth. +> [!NOTE] +> It is highly recommended that you read [RFC6265bis - Section 8.8][samesite-implementation] for more details on SameSite cookies, security considerations, and defense in depth. ### Cookie Prefixes -Supported. +Cookie prefixes are a way to indicate that a given cookie was set with a set of attributes simply by +inspecting the first few characters of the cookie's name. -Cookie prefixes are a way to indicate that a given cookie was set with a set of attributes simply by inspecting the first few characters of the cookie's name. +Two prefixes are defined: -Cookie prefixes are defined in [Section 4.1.3 of 6265bis](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03##section-4.1.3). +- `"__Secure-"` -Two prefixes are defined: + If a cookie's name begins with a case-sensitive match for the string `__Secure-`, then the cookie was set with a "Secure" attribute. + +- `"__Host-"` -1. `"__Secure-" Prefix`: If a cookie's name begins with a case-sensitive match for the string "\_\_Secure-", then the cookie was set with a "Secure" attribute. -2. `"__Host-" Prefix`: If a cookie's name begins with a case-sensitive match for the string "\_\_Host-", then the cookie was set with a "Secure" attribute, a "Path" attribute with a value of "/", and no "Domain" attribute. + If a cookie's name begins with a case-sensitive match for the string `__Host-`, then the cookie was set with a "Secure" attribute, a "Path" attribute with a value of "/", and no "Domain" attribute. -If `prefixSecurity` is enabled for `CookieJar`, then cookies that match the prefixes defined above but do not obey the attribute restrictions are not added. +If `prefixSecurity` is enabled for `CookieJar`, then cookies that match the prefixes defined above but do +not obey the attribute restrictions are not added. You can define this functionality by passing in the `prefixSecurity` option to `CookieJar`. It can be one of 3 values: -1. `silent`: Enable cookie prefix checking but silently fail to add the cookie if conditions are not met. Default. +1. `silent`: (**default**) Enable cookie prefix checking but silently fail to add the cookie if conditions are not met. 2. `strict`: Enable cookie prefix checking and error out if conditions are not met. 3. `unsafe-disabled`: Disable cookie prefix checking. -Note that if `ignoreError` is passed in as `true` then the error is silent regardless of the `prefixSecurity` option (assuming it's enabled). +> If `ignoreError` is passed in as `true` when setting a cookie then the error is silent regardless of the `prefixSecurity` option (assuming it's enabled). -## Copyright and License +#### Example -BSD-3-Clause: +```typescript +import { CookieJar, MemoryCookieStore } from 'tough-cookie' -```text - Copyright (c) 2015, Salesforce.com, Inc. - All rights reserved. +const cookieJar = new CookieJar(new MemoryCookieStore(), { + prefixSecurity: 'silent' +}) - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are met: +// this cookie will be silently ignored since the url is insecure (http) +await cookieJar.setCookie( + '__Secure-SID=12345; Domain=example.com; Secure;', + 'http://example.com', +) - 1. Redistributions of source code must retain the above copyright notice, - this list of conditions and the following disclaimer. +// this cookie will be stored since the url is secure (https) +await cookieJar.setCookie( + '__Secure-SID=12345; Domain=example.com; Secure;', + 'https://example.com', +) +``` - 2. Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. +> [!NOTE] +> It is highly recommended that you read [RFC6265bis - Section 4.1.3][cookie-prefixes-implementation] for more details on Cookie Prefixes. - 3. Neither the name of Salesforce.com nor the names of its contributors may - be used to endorse or promote products derived from this software without - specific prior written permission. +## Node.js Version Support - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE - LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS - INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. -``` +We follow the [Node.js release schedule](https://github.com/nodejs/Release#release-schedule) and support +all versions that are in Active LTS or Maintenance. We will always do a major release when dropping support +for older versions of node, and we will do so in consultation with our community. + +[npm-badge]: https://img.shields.io/npm/v/tough-cookie.svg?style=flat +[npm-repo]: https://www.npmjs.com/package/tough-cookie +[ci-badge]: https://github.com/salesforce/tough-cookie/actions/workflows/integration.yaml/badge.svg +[ci-url]: https://github.com/salesforce/tough-cookie/actions/workflows/integration.yaml +[rfc6265-badge]: https://img.shields.io/badge/RFC-6265-flat?labelColor=000000&color=666666 +[rfc6265-tracker]: https://datatracker.ietf.org/doc/rfc6265/ +[rfc6265bis-badge]: https://img.shields.io/badge/RFC-6265bis-flat?labelColor=000000&color=666666 +[rfc6265bis-tracker]: https://datatracker.ietf.org/doc/draft-ietf-httpbis-rfc6265bis/ +[samesite-implementation]: https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-02#section-8.8 +[cookie-prefixes-implementation]: https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-02#section-4.1.3 +[prs-welcome-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg +[yarn-repo]: https://yarnpkg.com/package?name=tough-cookie diff --git a/api-extractor.json b/api-extractor.json new file mode 100644 index 00000000..c44f39bb --- /dev/null +++ b/api-extractor.json @@ -0,0 +1,41 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json", + "mainEntryPointFilePath": "/dist/cookie/index.d.ts", + "newlineKind": "lf", + "apiReport": { + "enabled": true, + "reportFolder": "api", + "reportTempFolder": "tmp" + }, + "docModel": { + "enabled": true, + "apiJsonFilePath": "/tmp/.api.json" + }, + "dtsRollup": { + "enabled": false + }, + "tsdocMetadata": { + "enabled": true + }, + "messages": { + "compilerMessageReporting": { + "default": { + "logLevel": "warning" + } + }, + "extractorMessageReporting": { + "default": { + "logLevel": "warning" + }, + "ae-internal-missing-underscore": { + "logLevel": "none", + "addToApiReportFile": false + } + }, + "tsdocMessageReporting": { + "default": { + "logLevel": "warning" + } + } + } +} diff --git a/api/.gitattributes b/api/.gitattributes new file mode 100644 index 00000000..6313b56c --- /dev/null +++ b/api/.gitattributes @@ -0,0 +1 @@ +* text=auto eol=lf diff --git a/api/docs/index.md b/api/docs/index.md new file mode 100644 index 00000000..71821947 --- /dev/null +++ b/api/docs/index.md @@ -0,0 +1,29 @@ + + +[Home](./index.md) + +## API Reference + +## Packages + + + +
+ +Package + + + + +Description + + +
+ +[tough-cookie](./tough-cookie.md) + + + + + +
diff --git a/api/docs/tough-cookie.callback.md b/api/docs/tough-cookie.callback.md new file mode 100644 index 00000000..a2447633 --- /dev/null +++ b/api/docs/tough-cookie.callback.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Callback](./tough-cookie.callback.md) + +## Callback interface + +A callback function that accepts an error or a result. + +**Signature:** + +```typescript +export interface Callback +``` diff --git a/api/docs/tough-cookie.canonicaldomain.md b/api/docs/tough-cookie.canonicaldomain.md new file mode 100644 index 00000000..a4274a19 --- /dev/null +++ b/api/docs/tough-cookie.canonicaldomain.md @@ -0,0 +1,70 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [canonicalDomain](./tough-cookie.canonicaldomain.md) + +## canonicalDomain() function + +Transforms a domain name into a canonical domain name. The canonical domain name is a domain name that has been trimmed, lowercased, stripped of leading dot, and optionally punycode-encoded ([Section 5.1.2 of RFC 6265](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.1.2)). For the most part, this function is idempotent (calling the function with the output from a previous call returns the same output). + +**Signature:** + +```typescript +export declare function canonicalDomain(domainName: Nullable): string | undefined; +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +domainName + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +the domain name to generate the canonical domain from + + +
+**Returns:** + +string \| undefined + +## Remarks + +A canonicalized host name is the string generated by the following algorithm: + +1. Convert the host name to a sequence of individual domain name labels. + +2. Convert each label that is not a Non-Reserved LDH (NR-LDH) label, to an A-label (see Section 2.3.2.1 of \[RFC5890\] for the former and latter), or to a "punycode label" (a label resulting from the "ToASCII" conversion in Section 4 of \[RFC3490\]), as appropriate (see Section 6.3 of this specification). + +3. Concatenate the resulting labels, separated by a %x2E (".") character. + +## Example + + +``` +canonicalDomain('.EXAMPLE.com') === 'example.com' +``` + diff --git a/api/docs/tough-cookie.cookie._constructor_.md b/api/docs/tough-cookie.cookie._constructor_.md new file mode 100644 index 00000000..a2bbe638 --- /dev/null +++ b/api/docs/tough-cookie.cookie._constructor_.md @@ -0,0 +1,49 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [(constructor)](./tough-cookie.cookie._constructor_.md) + +## Cookie.(constructor) + +Create a new Cookie instance. + +**Signature:** + +```typescript +constructor(options?: CreateCookieOptions); +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +options + + + + +[CreateCookieOptions](./tough-cookie.createcookieoptions.md) + + + + +_(Optional)_ The attributes to set on the cookie + + +
diff --git a/api/docs/tough-cookie.cookie.canonicalizeddomain.md b/api/docs/tough-cookie.cookie.canonicalizeddomain.md new file mode 100644 index 00000000..eceaf1f7 --- /dev/null +++ b/api/docs/tough-cookie.cookie.canonicalizeddomain.md @@ -0,0 +1,17 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [canonicalizedDomain](./tough-cookie.cookie.canonicalizeddomain.md) + +## Cookie.canonicalizedDomain() method + +Calls [canonicalDomain()](./tough-cookie.canonicaldomain.md) with the [Cookie.domain](./tough-cookie.cookie.domain.md) property. + +**Signature:** + +```typescript +canonicalizedDomain(): string | undefined; +``` +**Returns:** + +string \| undefined + diff --git a/api/docs/tough-cookie.cookie.cdomain.md b/api/docs/tough-cookie.cookie.cdomain.md new file mode 100644 index 00000000..62628f26 --- /dev/null +++ b/api/docs/tough-cookie.cookie.cdomain.md @@ -0,0 +1,17 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [cdomain](./tough-cookie.cookie.cdomain.md) + +## Cookie.cdomain() method + +Alias for [Cookie.canonicalizedDomain()](./tough-cookie.cookie.canonicalizeddomain.md) + +**Signature:** + +```typescript +cdomain(): string | undefined; +``` +**Returns:** + +string \| undefined + diff --git a/api/docs/tough-cookie.cookie.clone.md b/api/docs/tough-cookie.cookie.clone.md new file mode 100644 index 00000000..c05435cb --- /dev/null +++ b/api/docs/tough-cookie.cookie.clone.md @@ -0,0 +1,17 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [clone](./tough-cookie.cookie.clone.md) + +## Cookie.clone() method + +Does a deep clone of this cookie, implemented exactly as `Cookie.fromJSON(cookie.toJSON())`. + +**Signature:** + +```typescript +clone(): Cookie | undefined; +``` +**Returns:** + +[Cookie](./tough-cookie.cookie.md) \| undefined + diff --git a/api/docs/tough-cookie.cookie.cookiestring.md b/api/docs/tough-cookie.cookie.cookiestring.md new file mode 100644 index 00000000..00314053 --- /dev/null +++ b/api/docs/tough-cookie.cookie.cookiestring.md @@ -0,0 +1,17 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [cookieString](./tough-cookie.cookie.cookiestring.md) + +## Cookie.cookieString() method + +Encodes to a `Cookie` header value (specifically, the [Cookie.key](./tough-cookie.cookie.key.md) and [Cookie.value](./tough-cookie.cookie.value.md) properties joined with "="). + +**Signature:** + +```typescript +cookieString(): string; +``` +**Returns:** + +string + diff --git a/api/docs/tough-cookie.cookie.creation.md b/api/docs/tough-cookie.cookie.creation.md new file mode 100644 index 00000000..7a7bc395 --- /dev/null +++ b/api/docs/tough-cookie.cookie.creation.md @@ -0,0 +1,15 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [creation](./tough-cookie.cookie.creation.md) + +## Cookie.creation property + +Set to the date and time when a Cookie is initially stored or a matching cookie is received that replaces an existing cookie (See [RFC6265 Section 5.3](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.3)). + +Also used to maintain ordering among cookies. Among cookies that have equal-length path fields, cookies with earlier creation-times are listed before cookies with later creation-times (See [RFC6265 Section 5.4](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.4)). + +**Signature:** + +```typescript +creation: Date | 'Infinity' | null; +``` diff --git a/api/docs/tough-cookie.cookie.creationindex.md b/api/docs/tough-cookie.cookie.creationindex.md new file mode 100644 index 00000000..65cb7ef4 --- /dev/null +++ b/api/docs/tough-cookie.cookie.creationindex.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [creationIndex](./tough-cookie.cookie.creationindex.md) + +## Cookie.creationIndex property + +A global counter used to break ordering ties between two cookies that have equal-length path fields and the same creation-time. + +**Signature:** + +```typescript +creationIndex: number; +``` diff --git a/api/docs/tough-cookie.cookie.domain.md b/api/docs/tough-cookie.cookie.domain.md new file mode 100644 index 00000000..f23863d5 --- /dev/null +++ b/api/docs/tough-cookie.cookie.domain.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [domain](./tough-cookie.cookie.domain.md) + +## Cookie.domain property + +The 'Domain' attribute of the cookie represents the domain the cookie belongs to (See [RFC6265 Section 5.2.3](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.3)). + +**Signature:** + +```typescript +domain: string | null; +``` diff --git a/api/docs/tough-cookie.cookie.expires.md b/api/docs/tough-cookie.cookie.expires.md new file mode 100644 index 00000000..fbd0d426 --- /dev/null +++ b/api/docs/tough-cookie.cookie.expires.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [expires](./tough-cookie.cookie.expires.md) + +## Cookie.expires property + +The 'Expires' attribute of the cookie (See [RFC6265 Section 5.2.1](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.1)). + +**Signature:** + +```typescript +expires: Date | 'Infinity' | null; +``` diff --git a/api/docs/tough-cookie.cookie.expirytime.md b/api/docs/tough-cookie.cookie.expirytime.md new file mode 100644 index 00000000..39188c81 --- /dev/null +++ b/api/docs/tough-cookie.cookie.expirytime.md @@ -0,0 +1,57 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [expiryTime](./tough-cookie.cookie.expirytime.md) + +## Cookie.expiryTime() method + +Computes the absolute unix-epoch milliseconds that this cookie expires. + +The "Max-Age" attribute takes precedence over "Expires" (as per the RFC). The [Cookie.lastAccessed](./tough-cookie.cookie.lastaccessed.md) attribute (or the `now` parameter if given) is used to offset the [Cookie.maxAge](./tough-cookie.cookie.maxage.md) attribute. + +If Expires ([Cookie.expires](./tough-cookie.cookie.expires.md)) is set, that's returned. + +**Signature:** + +```typescript +expiryTime(now?: Date): number | undefined; +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +now + + + + +Date + + + + +_(Optional)_ can be used to provide a time offset (instead of [Cookie.lastAccessed](./tough-cookie.cookie.lastaccessed.md)) to use when calculating the "Max-Age" value + + +
+**Returns:** + +number \| undefined + diff --git a/api/docs/tough-cookie.cookie.extensions.md b/api/docs/tough-cookie.cookie.extensions.md new file mode 100644 index 00000000..5a64caf3 --- /dev/null +++ b/api/docs/tough-cookie.cookie.extensions.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [extensions](./tough-cookie.cookie.extensions.md) + +## Cookie.extensions property + +Contains attributes which are not part of the defined spec but match the `extension-av` syntax defined in Section 4.1.1 of RFC6265 (See [RFC6265 Section 4.1.1](https://www.rfc-editor.org/rfc/rfc6265.html#section-4.1.1)). + +**Signature:** + +```typescript +extensions: string[] | null; +``` diff --git a/api/docs/tough-cookie.cookie.fromjson.md b/api/docs/tough-cookie.cookie.fromjson.md new file mode 100644 index 00000000..4f104fed --- /dev/null +++ b/api/docs/tough-cookie.cookie.fromjson.md @@ -0,0 +1,76 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [fromJSON](./tough-cookie.cookie.fromjson.md) + +## Cookie.fromJSON() method + +Does the reverse of [Cookie.toJSON()](./tough-cookie.cookie.tojson.md). + +**Signature:** + +```typescript +static fromJSON(str: unknown): Cookie | undefined; +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +str + + + + +unknown + + + + +An unparsed JSON string or a value that has already been parsed as JSON + + +
+**Returns:** + +[Cookie](./tough-cookie.cookie.md) \| undefined + +## Remarks + +Any Date properties (such as .expires, .creation, and .lastAccessed) are parsed via Date.parse, not tough-cookie's parseDate, since ISO timestamps are being handled at this layer. + +## Example + + +``` +const json = JSON.stringify({ + key: 'alpha', + value: 'beta', + domain: 'example.com', + path: '/foo', + expires: '2038-01-19T03:14:07.000Z', +}) +const cookie = Cookie.fromJSON(json) +cookie.key === 'alpha' +cookie.value === 'beta' +cookie.domain === 'example.com' +cookie.path === '/foo' +cookie.expires === new Date(Date.parse('2038-01-19T03:14:07.000Z')) +``` + diff --git a/api/docs/tough-cookie.cookie.hostonly.md b/api/docs/tough-cookie.cookie.hostonly.md new file mode 100644 index 00000000..74977480 --- /dev/null +++ b/api/docs/tough-cookie.cookie.hostonly.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [hostOnly](./tough-cookie.cookie.hostonly.md) + +## Cookie.hostOnly property + +A boolean flag indicating if a cookie is a host-only cookie (i.e.; when the request's host exactly matches the domain of the cookie) or not (See [RFC6265 Section 5.3](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.3)). + +**Signature:** + +```typescript +hostOnly: boolean | null; +``` diff --git a/api/docs/tough-cookie.cookie.httponly.md b/api/docs/tough-cookie.cookie.httponly.md new file mode 100644 index 00000000..552e0d8d --- /dev/null +++ b/api/docs/tough-cookie.cookie.httponly.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [httpOnly](./tough-cookie.cookie.httponly.md) + +## Cookie.httpOnly property + +The 'HttpOnly' flag of the cookie indicates if the cookie is inaccessible to client scripts or not (See [RFC6265 Section 5.2.6](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.6)). + +**Signature:** + +```typescript +httpOnly: boolean; +``` diff --git a/api/docs/tough-cookie.cookie.ispersistent.md b/api/docs/tough-cookie.cookie.ispersistent.md new file mode 100644 index 00000000..20a5e2f8 --- /dev/null +++ b/api/docs/tough-cookie.cookie.ispersistent.md @@ -0,0 +1,17 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [isPersistent](./tough-cookie.cookie.ispersistent.md) + +## Cookie.isPersistent() method + +Indicates if the cookie has been persisted to a store or not. + +**Signature:** + +```typescript +isPersistent(): boolean; +``` +**Returns:** + +boolean + diff --git a/api/docs/tough-cookie.cookie.key.md b/api/docs/tough-cookie.cookie.key.md new file mode 100644 index 00000000..46d44d6f --- /dev/null +++ b/api/docs/tough-cookie.cookie.key.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [key](./tough-cookie.cookie.key.md) + +## Cookie.key property + +The name or key of the cookie + +**Signature:** + +```typescript +key: string; +``` diff --git a/api/docs/tough-cookie.cookie.lastaccessed.md b/api/docs/tough-cookie.cookie.lastaccessed.md new file mode 100644 index 00000000..4093fc94 --- /dev/null +++ b/api/docs/tough-cookie.cookie.lastaccessed.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [lastAccessed](./tough-cookie.cookie.lastaccessed.md) + +## Cookie.lastAccessed property + +Set to the date and time when a cookie was initially stored ([RFC6265 Section 5.3](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.3)) and updated whenever the cookie is retrieved from the [CookieJar](./tough-cookie.cookiejar.md) ([RFC6265 Section 5.4](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.4)). + +**Signature:** + +```typescript +lastAccessed: Date | 'Infinity' | null; +``` diff --git a/api/docs/tough-cookie.cookie.maxage.md b/api/docs/tough-cookie.cookie.maxage.md new file mode 100644 index 00000000..4932c1cb --- /dev/null +++ b/api/docs/tough-cookie.cookie.maxage.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [maxAge](./tough-cookie.cookie.maxage.md) + +## Cookie.maxAge property + +The 'Max-Age' attribute of the cookie (See [RFC6265 Section 5.2.2](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.2)). + +**Signature:** + +```typescript +maxAge: number | 'Infinity' | '-Infinity' | null; +``` diff --git a/api/docs/tough-cookie.cookie.md b/api/docs/tough-cookie.cookie.md new file mode 100644 index 00000000..fe5547fd --- /dev/null +++ b/api/docs/tough-cookie.cookie.md @@ -0,0 +1,604 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) + +## Cookie class + +An HTTP cookie (web cookie, browser cookie) is a small piece of data that a server sends to a user's web browser. It is defined in [RFC6265](https://www.rfc-editor.org/rfc/rfc6265.html). + +**Signature:** + +```typescript +export declare class Cookie +``` + +## Constructors + + + +
+ +Constructor + + + + +Modifiers + + + + +Description + + +
+ +[(constructor)(options)](./tough-cookie.cookie._constructor_.md) + + + + + + + +Create a new Cookie instance. + + +
+ +## Properties + + + + + + + + + + + + + + + + + + +
+ +Property + + + + +Modifiers + + + + +Type + + + + +Description + + +
+ +[creation](./tough-cookie.cookie.creation.md) + + + + + + + +Date \| 'Infinity' \| null + + + + +Set to the date and time when a Cookie is initially stored or a matching cookie is received that replaces an existing cookie (See [RFC6265 Section 5.3](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.3)). + +Also used to maintain ordering among cookies. Among cookies that have equal-length path fields, cookies with earlier creation-times are listed before cookies with later creation-times (See [RFC6265 Section 5.4](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.4)). + + +
+ +[creationIndex](./tough-cookie.cookie.creationindex.md) + + + + + + + +number + + + + +A global counter used to break ordering ties between two cookies that have equal-length path fields and the same creation-time. + + +
+ +[domain](./tough-cookie.cookie.domain.md) + + + + + + + +string \| null + + + + +The 'Domain' attribute of the cookie represents the domain the cookie belongs to (See [RFC6265 Section 5.2.3](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.3)). + + +
+ +[expires](./tough-cookie.cookie.expires.md) + + + + + + + +Date \| 'Infinity' \| null + + + + +The 'Expires' attribute of the cookie (See [RFC6265 Section 5.2.1](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.1)). + + +
+ +[extensions](./tough-cookie.cookie.extensions.md) + + + + + + + +string\[\] \| null + + + + +Contains attributes which are not part of the defined spec but match the `extension-av` syntax defined in Section 4.1.1 of RFC6265 (See [RFC6265 Section 4.1.1](https://www.rfc-editor.org/rfc/rfc6265.html#section-4.1.1)). + + +
+ +[hostOnly](./tough-cookie.cookie.hostonly.md) + + + + + + + +boolean \| null + + + + +A boolean flag indicating if a cookie is a host-only cookie (i.e.; when the request's host exactly matches the domain of the cookie) or not (See [RFC6265 Section 5.3](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.3)). + + +
+ +[httpOnly](./tough-cookie.cookie.httponly.md) + + + + + + + +boolean + + + + +The 'HttpOnly' flag of the cookie indicates if the cookie is inaccessible to client scripts or not (See [RFC6265 Section 5.2.6](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.6)). + + +
+ +[key](./tough-cookie.cookie.key.md) + + + + + + + +string + + + + +The name or key of the cookie + + +
+ +[lastAccessed](./tough-cookie.cookie.lastaccessed.md) + + + + + + + +Date \| 'Infinity' \| null + + + + +Set to the date and time when a cookie was initially stored ([RFC6265 Section 5.3](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.3)) and updated whenever the cookie is retrieved from the [CookieJar](./tough-cookie.cookiejar.md) ([RFC6265 Section 5.4](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.4)). + + +
+ +[maxAge](./tough-cookie.cookie.maxage.md) + + + + + + + +number \| 'Infinity' \| '-Infinity' \| null + + + + +The 'Max-Age' attribute of the cookie (See [RFC6265 Section 5.2.2](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.2)). + + +
+ +[path](./tough-cookie.cookie.path.md) + + + + + + + +string \| null + + + + +The 'Path' attribute of the cookie represents the path of the cookie (See [RFC6265 Section 5.2.4](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.4)). + + +
+ +[pathIsDefault](./tough-cookie.cookie.pathisdefault.md) + + + + + + + +boolean \| null + + + + +A boolean flag indicating if a cookie had no 'Path' attribute and the default path was used (See [RFC6265 Section 5.2.4](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.4)). + + +
+ +[sameSite](./tough-cookie.cookie.samesite.md) + + + + + + + +string \| undefined + + + + +The 'SameSite' attribute of a cookie as defined in RFC6265bis (See [RFC6265bis (v13) Section 5.2](https://www.ietf.org/archive/id/draft-ietf-httpbis-rfc6265bis-13.html#section-5.2)). + + +
+ +[secure](./tough-cookie.cookie.secure.md) + + + + + + + +boolean + + + + +The 'Secure' flag of the cookie indicates if the scope of the cookie is limited to secure channels (e.g.; HTTPS) or not (See [RFC6265 Section 5.2.5](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.5)). + + +
+ +[serializableProperties](./tough-cookie.cookie.serializableproperties.md) + + + + +`static` + + + + +readonly \["key", "value", "expires", "maxAge", "domain", "path", "secure", "httpOnly", "extensions", "hostOnly", "pathIsDefault", "creation", "lastAccessed", "sameSite"\] + + + + +Cookie properties that will be serialized when using [Cookie.fromJSON()](./tough-cookie.cookie.fromjson.md) and [Cookie.toJSON()](./tough-cookie.cookie.tojson.md). + + +
+ +[value](./tough-cookie.cookie.value.md) + + + + + + + +string + + + + +The value of the cookie + + +
+ +## Methods + + + + + + + + + + + + + + + + +
+ +Method + + + + +Modifiers + + + + +Description + + +
+ +[canonicalizedDomain()](./tough-cookie.cookie.canonicalizeddomain.md) + + + + + + + +Calls [canonicalDomain()](./tough-cookie.canonicaldomain.md) with the [Cookie.domain](./tough-cookie.cookie.domain.md) property. + + +
+ +[cdomain()](./tough-cookie.cookie.cdomain.md) + + + + + + + +Alias for [Cookie.canonicalizedDomain()](./tough-cookie.cookie.canonicalizeddomain.md) + + +
+ +[clone()](./tough-cookie.cookie.clone.md) + + + + + + + +Does a deep clone of this cookie, implemented exactly as `Cookie.fromJSON(cookie.toJSON())`. + + +
+ +[cookieString()](./tough-cookie.cookie.cookiestring.md) + + + + + + + +Encodes to a `Cookie` header value (specifically, the [Cookie.key](./tough-cookie.cookie.key.md) and [Cookie.value](./tough-cookie.cookie.value.md) properties joined with "="). + + +
+ +[expiryTime(now)](./tough-cookie.cookie.expirytime.md) + + + + + + + +Computes the absolute unix-epoch milliseconds that this cookie expires. + +The "Max-Age" attribute takes precedence over "Expires" (as per the RFC). The [Cookie.lastAccessed](./tough-cookie.cookie.lastaccessed.md) attribute (or the `now` parameter if given) is used to offset the [Cookie.maxAge](./tough-cookie.cookie.maxage.md) attribute. + +If Expires ([Cookie.expires](./tough-cookie.cookie.expires.md)) is set, that's returned. + + +
+ +[fromJSON(str)](./tough-cookie.cookie.fromjson.md) + + + + +`static` + + + + +Does the reverse of [Cookie.toJSON()](./tough-cookie.cookie.tojson.md). + + +
+ +[isPersistent()](./tough-cookie.cookie.ispersistent.md) + + + + + + + +Indicates if the cookie has been persisted to a store or not. + + +
+ +[parse(str, options)](./tough-cookie.cookie.parse.md) + + + + +`static` + + + + +Parses a string into a Cookie object. + + +
+ +[setExpires(exp)](./tough-cookie.cookie.setexpires.md) + + + + + + + +Sets the 'Expires' attribute on a cookie. + + +
+ +[setMaxAge(age)](./tough-cookie.cookie.setmaxage.md) + + + + + + + +Sets the 'Max-Age' attribute (in seconds) on a cookie. + + +
+ +[toJSON()](./tough-cookie.cookie.tojson.md) + + + + + + + +For convenience in using `JSON.stringify(cookie)`. Returns a plain-old Object that can be JSON-serialized. + + +
+ +[toString()](./tough-cookie.cookie.tostring.md) + + + + + + + +Encodes to a `Set-Cookie header` value. + + +
+ +[TTL(now)](./tough-cookie.cookie.ttl.md) + + + + + + + +Computes the TTL relative to now (milliseconds). + + +
+ +[validate()](./tough-cookie.cookie.validate.md) + + + + + + + +**_(BETA)_** Validates cookie attributes for semantic correctness. Useful for "lint" checking any `Set-Cookie` headers you generate. For now, it returns a boolean, but eventually could return a reason string. + + +
diff --git a/api/docs/tough-cookie.cookie.parse.md b/api/docs/tough-cookie.cookie.parse.md new file mode 100644 index 00000000..6dbd2b07 --- /dev/null +++ b/api/docs/tough-cookie.cookie.parse.md @@ -0,0 +1,100 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [parse](./tough-cookie.cookie.parse.md) + +## Cookie.parse() method + +Parses a string into a Cookie object. + +**Signature:** + +```typescript +static parse(str: string, options?: ParseCookieOptions): Cookie | undefined; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +str + + + + +string + + + + +The `Set-Cookie` header or a Cookie string to parse. + + +
+ +options + + + + +[ParseCookieOptions](./tough-cookie.parsecookieoptions.md) + + + + +_(Optional)_ Configures `strict` or `loose` mode for cookie parsing + + +
+**Returns:** + +[Cookie](./tough-cookie.cookie.md) \| undefined + +## Remarks + +Note: when parsing a `Cookie` header it must be split by ';' before each Cookie string can be parsed. + +## Example 1 + + +``` +// parse a `Set-Cookie` header +const setCookieHeader = 'a=bcd; Expires=Tue, 18 Oct 2011 07:05:03 GMT' +const cookie = Cookie.parse(setCookieHeader) +cookie.key === 'a' +cookie.value === 'bcd' +cookie.expires === new Date(Date.parse('Tue, 18 Oct 2011 07:05:03 GMT')) +``` + +## Example 2 + + +``` +// parse a `Cookie` header +const cookieHeader = 'name=value; name2=value2; name3=value3' +const cookies = cookieHeader.split(';').map(Cookie.parse) +cookies[0].name === 'name' +cookies[0].value === 'value' +cookies[1].name === 'name2' +cookies[1].value === 'value2' +cookies[2].name === 'name3' +cookies[2].value === 'value3' +``` + diff --git a/api/docs/tough-cookie.cookie.path.md b/api/docs/tough-cookie.cookie.path.md new file mode 100644 index 00000000..a1ce5eb5 --- /dev/null +++ b/api/docs/tough-cookie.cookie.path.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [path](./tough-cookie.cookie.path.md) + +## Cookie.path property + +The 'Path' attribute of the cookie represents the path of the cookie (See [RFC6265 Section 5.2.4](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.4)). + +**Signature:** + +```typescript +path: string | null; +``` diff --git a/api/docs/tough-cookie.cookie.pathisdefault.md b/api/docs/tough-cookie.cookie.pathisdefault.md new file mode 100644 index 00000000..325b6b91 --- /dev/null +++ b/api/docs/tough-cookie.cookie.pathisdefault.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [pathIsDefault](./tough-cookie.cookie.pathisdefault.md) + +## Cookie.pathIsDefault property + +A boolean flag indicating if a cookie had no 'Path' attribute and the default path was used (See [RFC6265 Section 5.2.4](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.4)). + +**Signature:** + +```typescript +pathIsDefault: boolean | null; +``` diff --git a/api/docs/tough-cookie.cookie.samesite.md b/api/docs/tough-cookie.cookie.samesite.md new file mode 100644 index 00000000..7be64cce --- /dev/null +++ b/api/docs/tough-cookie.cookie.samesite.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [sameSite](./tough-cookie.cookie.samesite.md) + +## Cookie.sameSite property + +The 'SameSite' attribute of a cookie as defined in RFC6265bis (See [RFC6265bis (v13) Section 5.2](https://www.ietf.org/archive/id/draft-ietf-httpbis-rfc6265bis-13.html#section-5.2)). + +**Signature:** + +```typescript +sameSite: string | undefined; +``` diff --git a/api/docs/tough-cookie.cookie.secure.md b/api/docs/tough-cookie.cookie.secure.md new file mode 100644 index 00000000..b7607aa5 --- /dev/null +++ b/api/docs/tough-cookie.cookie.secure.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [secure](./tough-cookie.cookie.secure.md) + +## Cookie.secure property + +The 'Secure' flag of the cookie indicates if the scope of the cookie is limited to secure channels (e.g.; HTTPS) or not (See [RFC6265 Section 5.2.5](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.5)). + +**Signature:** + +```typescript +secure: boolean; +``` diff --git a/api/docs/tough-cookie.cookie.serializableproperties.md b/api/docs/tough-cookie.cookie.serializableproperties.md new file mode 100644 index 00000000..74bc648c --- /dev/null +++ b/api/docs/tough-cookie.cookie.serializableproperties.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [serializableProperties](./tough-cookie.cookie.serializableproperties.md) + +## Cookie.serializableProperties property + +Cookie properties that will be serialized when using [Cookie.fromJSON()](./tough-cookie.cookie.fromjson.md) and [Cookie.toJSON()](./tough-cookie.cookie.tojson.md). + +**Signature:** + +```typescript +static serializableProperties: readonly ["key", "value", "expires", "maxAge", "domain", "path", "secure", "httpOnly", "extensions", "hostOnly", "pathIsDefault", "creation", "lastAccessed", "sameSite"]; +``` diff --git a/api/docs/tough-cookie.cookie.setexpires.md b/api/docs/tough-cookie.cookie.setexpires.md new file mode 100644 index 00000000..ca00af7d --- /dev/null +++ b/api/docs/tough-cookie.cookie.setexpires.md @@ -0,0 +1,57 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [setExpires](./tough-cookie.cookie.setexpires.md) + +## Cookie.setExpires() method + +Sets the 'Expires' attribute on a cookie. + +**Signature:** + +```typescript +setExpires(exp: string | Date): void; +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +exp + + + + +string \| Date + + + + +the new value for the 'Expires' attribute of the cookie. + + +
+**Returns:** + +void + +## Remarks + +When given a `string` value it will be parsed with [parseDate()](./tough-cookie.parsedate.md). If the value can't be parsed as a cookie date then the 'Expires' attribute will be set to `"Infinity"`. + diff --git a/api/docs/tough-cookie.cookie.setmaxage.md b/api/docs/tough-cookie.cookie.setmaxage.md new file mode 100644 index 00000000..a7c99ecc --- /dev/null +++ b/api/docs/tough-cookie.cookie.setmaxage.md @@ -0,0 +1,57 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [setMaxAge](./tough-cookie.cookie.setmaxage.md) + +## Cookie.setMaxAge() method + +Sets the 'Max-Age' attribute (in seconds) on a cookie. + +**Signature:** + +```typescript +setMaxAge(age: number): void; +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +age + + + + +number + + + + +the new value for the 'Max-Age' attribute (in seconds). + + +
+**Returns:** + +void + +## Remarks + +Coerces `-Infinity` to `"-Infinity"` and `Infinity` to `"Infinity"` so it can be serialized to JSON. + diff --git a/api/docs/tough-cookie.cookie.tojson.md b/api/docs/tough-cookie.cookie.tojson.md new file mode 100644 index 00000000..42888171 --- /dev/null +++ b/api/docs/tough-cookie.cookie.tojson.md @@ -0,0 +1,23 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [toJSON](./tough-cookie.cookie.tojson.md) + +## Cookie.toJSON() method + +For convenience in using `JSON.stringify(cookie)`. Returns a plain-old Object that can be JSON-serialized. + +**Signature:** + +```typescript +toJSON(): SerializedCookie; +``` +**Returns:** + +[SerializedCookie](./tough-cookie.serializedcookie.md) + +## Remarks + +- Any `Date` properties (such as [Cookie.expires](./tough-cookie.cookie.expires.md), [Cookie.creation](./tough-cookie.cookie.creation.md), and [Cookie.lastAccessed](./tough-cookie.cookie.lastaccessed.md)) are exported in ISO format (`Date.toISOString()`). + +- Custom Cookie properties are discarded. In tough-cookie 1.x, since there was no [Cookie.toJSON()](./tough-cookie.cookie.tojson.md) method explicitly defined, all enumerable properties were captured. If you want a property to be serialized, add the property name to [Cookie.serializableProperties](./tough-cookie.cookie.serializableproperties.md). + diff --git a/api/docs/tough-cookie.cookie.tostring.md b/api/docs/tough-cookie.cookie.tostring.md new file mode 100644 index 00000000..ff1a0181 --- /dev/null +++ b/api/docs/tough-cookie.cookie.tostring.md @@ -0,0 +1,17 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [toString](./tough-cookie.cookie.tostring.md) + +## Cookie.toString() method + +Encodes to a `Set-Cookie header` value. + +**Signature:** + +```typescript +toString(): string; +``` +**Returns:** + +string + diff --git a/api/docs/tough-cookie.cookie.ttl.md b/api/docs/tough-cookie.cookie.ttl.md new file mode 100644 index 00000000..06fd587a --- /dev/null +++ b/api/docs/tough-cookie.cookie.ttl.md @@ -0,0 +1,61 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [TTL](./tough-cookie.cookie.ttl.md) + +## Cookie.TTL() method + +Computes the TTL relative to now (milliseconds). + +**Signature:** + +```typescript +TTL(now?: number): number; +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +now + + + + +number + + + + +_(Optional)_ passing an explicit value is mostly used for testing purposes since this defaults to the `Date.now()` + + +
+**Returns:** + +number + +## Remarks + +- `Infinity` is returned for cookies without an explicit expiry + +- `0` is returned if the cookie is expired. + +- Otherwise a time-to-live in milliseconds is returned. + diff --git a/api/docs/tough-cookie.cookie.validate.md b/api/docs/tough-cookie.cookie.validate.md new file mode 100644 index 00000000..ed9c2ec3 --- /dev/null +++ b/api/docs/tough-cookie.cookie.validate.md @@ -0,0 +1,24 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [validate](./tough-cookie.cookie.validate.md) + +## Cookie.validate() method + +> This API is provided as a beta preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Validates cookie attributes for semantic correctness. Useful for "lint" checking any `Set-Cookie` headers you generate. For now, it returns a boolean, but eventually could return a reason string. + +**Signature:** + +```typescript +validate(): boolean; +``` +**Returns:** + +boolean + +## Remarks + +Works for a few things, but is by no means comprehensive. + diff --git a/api/docs/tough-cookie.cookie.value.md b/api/docs/tough-cookie.cookie.value.md new file mode 100644 index 00000000..60b95892 --- /dev/null +++ b/api/docs/tough-cookie.cookie.value.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Cookie](./tough-cookie.cookie.md) > [value](./tough-cookie.cookie.value.md) + +## Cookie.value property + +The value of the cookie + +**Signature:** + +```typescript +value: string; +``` diff --git a/api/docs/tough-cookie.cookiecompare.md b/api/docs/tough-cookie.cookiecompare.md new file mode 100644 index 00000000..2965cc34 --- /dev/null +++ b/api/docs/tough-cookie.cookiecompare.md @@ -0,0 +1,109 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [cookieCompare](./tough-cookie.cookiecompare.md) + +## cookieCompare() function + +A comparison function that can be used with [Array.sort()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort), which orders a list of cookies into the recommended order given in Step 2 of [RFC6265 - Section 5.4](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.4). + +The sort algorithm is, in order of precedence: + +- Longest [Cookie.path](./tough-cookie.cookie.path.md) + +- Oldest [Cookie.creation](./tough-cookie.cookie.creation.md) (which has a 1-ms precision, same as Date) + +- Lowest [Cookie.creationIndex](./tough-cookie.cookie.creationindex.md) (to get beyond the 1-ms precision) + +**Signature:** + +```typescript +export declare function cookieCompare(a: Cookie, b: Cookie): number; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +a + + + + +[Cookie](./tough-cookie.cookie.md) + + + + +the first Cookie for comparison + + +
+ +b + + + + +[Cookie](./tough-cookie.cookie.md) + + + + +the second Cookie for comparison + + +
+**Returns:** + +number + +## Remarks + +\#\#\# RFC6265 - Section 5.4 - Step 2 + +The user agent SHOULD sort the cookie-list in the following order: + +- Cookies with longer paths are listed before cookies with shorter paths. + +- Among cookies that have equal-length path fields, cookies with earlier creation-times are listed before cookies with later creation-times. + +NOTE: Not all user agents sort the cookie-list in this order, but this order reflects common practice when this document was written, and, historically, there have been servers that (erroneously) depended on this order. + +\#\#\# Custom Store Implementors + +Since the JavaScript Date is limited to a 1-ms precision, cookies within the same millisecond are entirely possible. This is especially true when using the `now` option to `CookieJar.setCookie(...)`. The [Cookie.creationIndex](./tough-cookie.cookie.creationindex.md) property is a per-process global counter, assigned during construction with `new Cookie()`, which preserves the spirit of the RFC sorting: older cookies go first. This works great for [MemoryCookieStore](./tough-cookie.memorycookiestore.md) since `Set-Cookie` headers are parsed in order, but is not so great for distributed systems. + +Sophisticated Stores may wish to set this to some other logical clock so that if cookies `A` and `B` are created in the same millisecond, but cookie `A` is created before cookie `B`, then `A.creationIndex < B.creationIndex`. + +## Example + + +``` +const cookies = [ + new Cookie({ key: 'a', value: '' }), + new Cookie({ key: 'b', value: '' }), + new Cookie({ key: 'c', value: '', path: '/path' }), + new Cookie({ key: 'd', value: '', path: '/path' }), +] +cookies.sort(cookieCompare) +// cookie sort order would be ['c', 'd', 'a', 'b'] +``` + diff --git a/api/docs/tough-cookie.cookiejar._constructor_.md b/api/docs/tough-cookie.cookiejar._constructor_.md new file mode 100644 index 00000000..67e14da5 --- /dev/null +++ b/api/docs/tough-cookie.cookiejar._constructor_.md @@ -0,0 +1,70 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [(constructor)](./tough-cookie.cookiejar._constructor_.md) + +## CookieJar.(constructor) + +Creates a new `CookieJar` instance. + +**Signature:** + +```typescript +constructor(store?: Nullable, options?: CreateCookieJarOptions | boolean); +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +store + + + + +[Nullable](./tough-cookie.nullable.md)<[Store](./tough-cookie.store.md)> + + + + +_(Optional)_ a custom [Store](./tough-cookie.store.md) implementation (defaults to [MemoryCookieStore](./tough-cookie.memorycookiestore.md)) + + +
+ +options + + + + +[CreateCookieJarOptions](./tough-cookie.createcookiejaroptions.md) \| boolean + + + + +_(Optional)_ configures how cookies are processed by the cookie jar + + +
+ +## Remarks + +- If a custom store is not passed to the constructor, an in-memory store ([MemoryCookieStore](./tough-cookie.memorycookiestore.md) will be created and used. - If a boolean value is passed as the `options` parameter, this is equivalent to passing `{ rejectPublicSuffixes: }` + diff --git a/api/docs/tough-cookie.cookiejar.clone.md b/api/docs/tough-cookie.cookiejar.clone.md new file mode 100644 index 00000000..17fcf457 --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.clone.md @@ -0,0 +1,59 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [clone](./tough-cookie.cookiejar.clone.md) + +## CookieJar.clone() method + +Produces a deep clone of this CookieJar. Modifications to the original do not affect the clone, and vice versa. + +**Signature:** + +```typescript +clone(callback: Callback): void; +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +callback + + + + +[Callback](./tough-cookie.callback.md)<[CookieJar](./tough-cookie.cookiejar.md)> + + + + +A function to call when the CookieJar is cloned. + + +
+**Returns:** + +void + +## Remarks + +- When no [Store](./tough-cookie.store.md) is provided, a new [MemoryCookieStore](./tough-cookie.memorycookiestore.md) will be used. + +- Transferring between store types is supported so long as the source implements `.getAllCookies()` and the destination implements `.putCookie()`. + diff --git a/api/docs/tough-cookie.cookiejar.clone_1.md b/api/docs/tough-cookie.cookiejar.clone_1.md new file mode 100644 index 00000000..c68b55dd --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.clone_1.md @@ -0,0 +1,75 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [clone](./tough-cookie.cookiejar.clone_1.md) + +## CookieJar.clone() method + +Produces a deep clone of this CookieJar. Modifications to the original do not affect the clone, and vice versa. + +**Signature:** + +```typescript +clone(newStore: Store, callback: Callback): void; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +newStore + + + + +[Store](./tough-cookie.store.md) + + + + +The target [Store](./tough-cookie.store.md) to clone cookies into. + + +
+ +callback + + + + +[Callback](./tough-cookie.callback.md)<[CookieJar](./tough-cookie.cookiejar.md)> + + + + +A function to call when the CookieJar is cloned. + + +
+**Returns:** + +void + +## Remarks + +- When no [Store](./tough-cookie.store.md) is provided, a new [MemoryCookieStore](./tough-cookie.memorycookiestore.md) will be used. + +- Transferring between store types is supported so long as the source implements `.getAllCookies()` and the destination implements `.putCookie()`. + diff --git a/api/docs/tough-cookie.cookiejar.clone_2.md b/api/docs/tough-cookie.cookiejar.clone_2.md new file mode 100644 index 00000000..2d46d2f8 --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.clone_2.md @@ -0,0 +1,59 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [clone](./tough-cookie.cookiejar.clone_2.md) + +## CookieJar.clone() method + +Produces a deep clone of this CookieJar. Modifications to the original do not affect the clone, and vice versa. + +**Signature:** + +```typescript +clone(newStore?: Store): Promise; +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +newStore + + + + +[Store](./tough-cookie.store.md) + + + + +_(Optional)_ The target [Store](./tough-cookie.store.md) to clone cookies into. + + +
+**Returns:** + +Promise<[CookieJar](./tough-cookie.cookiejar.md)> + +## Remarks + +- When no [Store](./tough-cookie.store.md) is provided, a new [MemoryCookieStore](./tough-cookie.memorycookiestore.md) will be used. + +- Transferring between store types is supported so long as the source implements `.getAllCookies()` and the destination implements `.putCookie()`. + diff --git a/api/docs/tough-cookie.cookiejar.clonesync.md b/api/docs/tough-cookie.cookiejar.clonesync.md new file mode 100644 index 00000000..7ed8c1ca --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.clonesync.md @@ -0,0 +1,61 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [cloneSync](./tough-cookie.cookiejar.clonesync.md) + +## CookieJar.cloneSync() method + +Produces a deep clone of this CookieJar. Modifications to the original do not affect the clone, and vice versa. + +Note: Only works if both the configured Store and destination Store are synchronous. + +**Signature:** + +```typescript +cloneSync(newStore?: Store): CookieJar | undefined; +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +newStore + + + + +[Store](./tough-cookie.store.md) + + + + +_(Optional)_ The target [Store](./tough-cookie.store.md) to clone cookies into. + + +
+**Returns:** + +[CookieJar](./tough-cookie.cookiejar.md) \| undefined + +## Remarks + +- When no [Store](./tough-cookie.store.md) is provided, a new [MemoryCookieStore](./tough-cookie.memorycookiestore.md) will be used. + +- Transferring between store types is supported so long as the source implements `.getAllCookies()` and the destination implements `.putCookie()`. + diff --git a/api/docs/tough-cookie.cookiejar.deserialize.md b/api/docs/tough-cookie.cookiejar.deserialize.md new file mode 100644 index 00000000..d4e397c2 --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.deserialize.md @@ -0,0 +1,75 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [deserialize](./tough-cookie.cookiejar.deserialize.md) + +## CookieJar.deserialize() method + +A new CookieJar is created and the serialized [Cookie](./tough-cookie.cookie.md) values are added to the underlying store. Each [Cookie](./tough-cookie.cookie.md) is added via `store.putCookie(...)` in the order in which they appear in the serialization. + +**Signature:** + +```typescript +static deserialize(strOrObj: string | object, callback: Callback): void; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +strOrObj + + + + +string \| object + + + + +A JSON string or object representing the deserialized cookies. + + +
+ +callback + + + + +[Callback](./tough-cookie.callback.md)<[CookieJar](./tough-cookie.cookiejar.md)> + + + + +A function to call after the [CookieJar](./tough-cookie.cookiejar.md) has been deserialized. + + +
+**Returns:** + +void + +## Remarks + +- When no [Store](./tough-cookie.store.md) is provided, a new [MemoryCookieStore](./tough-cookie.memorycookiestore.md) will be used. + +- As a convenience, if `strOrObj` is a string, it is passed through `JSON.parse` first. + diff --git a/api/docs/tough-cookie.cookiejar.deserialize_1.md b/api/docs/tough-cookie.cookiejar.deserialize_1.md new file mode 100644 index 00000000..7ee0fced --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.deserialize_1.md @@ -0,0 +1,91 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [deserialize](./tough-cookie.cookiejar.deserialize_1.md) + +## CookieJar.deserialize() method + +A new CookieJar is created and the serialized [Cookie](./tough-cookie.cookie.md) values are added to the underlying store. Each [Cookie](./tough-cookie.cookie.md) is added via `store.putCookie(...)` in the order in which they appear in the serialization. + +**Signature:** + +```typescript +static deserialize(strOrObj: string | object, store: Store, callback: Callback): void; +``` + +## Parameters + + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +strOrObj + + + + +string \| object + + + + +A JSON string or object representing the deserialized cookies. + + +
+ +store + + + + +[Store](./tough-cookie.store.md) + + + + +The underlying store to persist the deserialized cookies into. + + +
+ +callback + + + + +[Callback](./tough-cookie.callback.md)<[CookieJar](./tough-cookie.cookiejar.md)> + + + + +A function to call after the [CookieJar](./tough-cookie.cookiejar.md) has been deserialized. + + +
+**Returns:** + +void + +## Remarks + +- When no [Store](./tough-cookie.store.md) is provided, a new [MemoryCookieStore](./tough-cookie.memorycookiestore.md) will be used. + +- As a convenience, if `strOrObj` is a string, it is passed through `JSON.parse` first. + diff --git a/api/docs/tough-cookie.cookiejar.deserialize_2.md b/api/docs/tough-cookie.cookiejar.deserialize_2.md new file mode 100644 index 00000000..8272f43b --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.deserialize_2.md @@ -0,0 +1,75 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [deserialize](./tough-cookie.cookiejar.deserialize_2.md) + +## CookieJar.deserialize() method + +A new CookieJar is created and the serialized [Cookie](./tough-cookie.cookie.md) values are added to the underlying store. Each [Cookie](./tough-cookie.cookie.md) is added via `store.putCookie(...)` in the order in which they appear in the serialization. + +**Signature:** + +```typescript +static deserialize(strOrObj: string | object, store?: Store): Promise; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +strOrObj + + + + +string \| object + + + + +A JSON string or object representing the deserialized cookies. + + +
+ +store + + + + +[Store](./tough-cookie.store.md) + + + + +_(Optional)_ The underlying store to persist the deserialized cookies into. + + +
+**Returns:** + +Promise<[CookieJar](./tough-cookie.cookiejar.md)> + +## Remarks + +- When no [Store](./tough-cookie.store.md) is provided, a new [MemoryCookieStore](./tough-cookie.memorycookiestore.md) will be used. + +- As a convenience, if `strOrObj` is a string, it is passed through `JSON.parse` first. + diff --git a/api/docs/tough-cookie.cookiejar.deserializesync.md b/api/docs/tough-cookie.cookiejar.deserializesync.md new file mode 100644 index 00000000..a7481aaa --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.deserializesync.md @@ -0,0 +1,77 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [deserializeSync](./tough-cookie.cookiejar.deserializesync.md) + +## CookieJar.deserializeSync() method + +A new CookieJar is created and the serialized [Cookie](./tough-cookie.cookie.md) values are added to the underlying store. Each [Cookie](./tough-cookie.cookie.md) is added via `store.putCookie(...)` in the order in which they appear in the serialization. + +Note: Only works if the configured Store is also synchronous. + +**Signature:** + +```typescript +static deserializeSync(strOrObj: string | SerializedCookieJar, store?: Store): CookieJar; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +strOrObj + + + + +string \| [SerializedCookieJar](./tough-cookie.serializedcookiejar.md) + + + + +A JSON string or object representing the deserialized cookies. + + +
+ +store + + + + +[Store](./tough-cookie.store.md) + + + + +_(Optional)_ The underlying store to persist the deserialized cookies into. + + +
+**Returns:** + +[CookieJar](./tough-cookie.cookiejar.md) + +## Remarks + +- When no [Store](./tough-cookie.store.md) is provided, a new [MemoryCookieStore](./tough-cookie.memorycookiestore.md) will be used. + +- As a convenience, if `strOrObj` is a string, it is passed through `JSON.parse` first. + diff --git a/api/docs/tough-cookie.cookiejar.fromjson.md b/api/docs/tough-cookie.cookiejar.fromjson.md new file mode 100644 index 00000000..63171600 --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.fromjson.md @@ -0,0 +1,75 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [fromJSON](./tough-cookie.cookiejar.fromjson.md) + +## CookieJar.fromJSON() method + +Alias of [CookieJar.deserializeSync()](./tough-cookie.cookiejar.deserializesync.md). + +**Signature:** + +```typescript +static fromJSON(jsonString: string | SerializedCookieJar, store?: Store): CookieJar; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +jsonString + + + + +string \| [SerializedCookieJar](./tough-cookie.serializedcookiejar.md) + + + + +A JSON string or object representing the deserialized cookies. + + +
+ +store + + + + +[Store](./tough-cookie.store.md) + + + + +_(Optional)_ The underlying store to persist the deserialized cookies into. + + +
+**Returns:** + +[CookieJar](./tough-cookie.cookiejar.md) + +## Remarks + +- When no [Store](./tough-cookie.store.md) is provided, a new [MemoryCookieStore](./tough-cookie.memorycookiestore.md) will be used. + +- As a convenience, if `strOrObj` is a string, it is passed through `JSON.parse` first. + diff --git a/api/docs/tough-cookie.cookiejar.getcookies.md b/api/docs/tough-cookie.cookiejar.getcookies.md new file mode 100644 index 00000000..512f80a4 --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.getcookies.md @@ -0,0 +1,75 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [getCookies](./tough-cookie.cookiejar.getcookies.md) + +## CookieJar.getCookies() method + +Retrieve the list of cookies that can be sent in a Cookie header for the current URL. + +**Signature:** + +```typescript +getCookies(url: string, callback: Callback): void; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +url + + + + +string + + + + +The domain to store the cookie with. + + +
+ +callback + + + + +[Callback](./tough-cookie.callback.md)<[Cookie](./tough-cookie.cookie.md)\[\]> + + + + +A function to call after a cookie has been successfully retrieved. + + +
+**Returns:** + +void + +## Remarks + +- The array of cookies returned will be sorted according to [cookieCompare()](./tough-cookie.cookiecompare.md). + +- The [Cookie.lastAccessed](./tough-cookie.cookie.lastaccessed.md) property will be updated on all returned cookies. + diff --git a/api/docs/tough-cookie.cookiejar.getcookies_1.md b/api/docs/tough-cookie.cookiejar.getcookies_1.md new file mode 100644 index 00000000..f842189f --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.getcookies_1.md @@ -0,0 +1,91 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [getCookies](./tough-cookie.cookiejar.getcookies_1.md) + +## CookieJar.getCookies() method + +Retrieve the list of cookies that can be sent in a Cookie header for the current URL. + +**Signature:** + +```typescript +getCookies(url: string | URL, options: GetCookiesOptions | undefined, callback: Callback): void; +``` + +## Parameters + + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +url + + + + +string \| URL + + + + +The domain to store the cookie with. + + +
+ +options + + + + +[GetCookiesOptions](./tough-cookie.getcookiesoptions.md) \| undefined + + + + +Configuration settings to use when retrieving the cookies. + + +
+ +callback + + + + +[Callback](./tough-cookie.callback.md)<[Cookie](./tough-cookie.cookie.md)\[\]> + + + + +A function to call after a cookie has been successfully retrieved. + + +
+**Returns:** + +void + +## Remarks + +- The array of cookies returned will be sorted according to [cookieCompare()](./tough-cookie.cookiecompare.md). + +- The [Cookie.lastAccessed](./tough-cookie.cookie.lastaccessed.md) property will be updated on all returned cookies. + diff --git a/api/docs/tough-cookie.cookiejar.getcookies_2.md b/api/docs/tough-cookie.cookiejar.getcookies_2.md new file mode 100644 index 00000000..760ce4d2 --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.getcookies_2.md @@ -0,0 +1,75 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [getCookies](./tough-cookie.cookiejar.getcookies_2.md) + +## CookieJar.getCookies() method + +Retrieve the list of cookies that can be sent in a Cookie header for the current URL. + +**Signature:** + +```typescript +getCookies(url: string | URL, options?: GetCookiesOptions | undefined): Promise; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +url + + + + +string \| URL + + + + +The domain to store the cookie with. + + +
+ +options + + + + +[GetCookiesOptions](./tough-cookie.getcookiesoptions.md) \| undefined + + + + +_(Optional)_ Configuration settings to use when retrieving the cookies. + + +
+**Returns:** + +Promise<[Cookie](./tough-cookie.cookie.md)\[\]> + +## Remarks + +- The array of cookies returned will be sorted according to [cookieCompare()](./tough-cookie.cookiecompare.md). + +- The [Cookie.lastAccessed](./tough-cookie.cookie.lastaccessed.md) property will be updated on all returned cookies. + diff --git a/api/docs/tough-cookie.cookiejar.getcookiessync.md b/api/docs/tough-cookie.cookiejar.getcookiessync.md new file mode 100644 index 00000000..fdb3e2ef --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.getcookiessync.md @@ -0,0 +1,77 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [getCookiesSync](./tough-cookie.cookiejar.getcookiessync.md) + +## CookieJar.getCookiesSync() method + +Synchronously retrieve the list of cookies that can be sent in a Cookie header for the current URL. + +Note: Only works if the configured Store is also synchronous. + +**Signature:** + +```typescript +getCookiesSync(url: string, options?: GetCookiesOptions): Cookie[]; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +url + + + + +string + + + + +The domain to store the cookie with. + + +
+ +options + + + + +[GetCookiesOptions](./tough-cookie.getcookiesoptions.md) + + + + +_(Optional)_ Configuration settings to use when retrieving the cookies. + + +
+**Returns:** + +[Cookie](./tough-cookie.cookie.md)\[\] + +## Remarks + +- The array of cookies returned will be sorted according to [cookieCompare()](./tough-cookie.cookiecompare.md). + +- The [Cookie.lastAccessed](./tough-cookie.cookie.lastaccessed.md) property will be updated on all returned cookies. + diff --git a/api/docs/tough-cookie.cookiejar.getcookiestring.md b/api/docs/tough-cookie.cookiejar.getcookiestring.md new file mode 100644 index 00000000..b2241ab5 --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.getcookiestring.md @@ -0,0 +1,85 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [getCookieString](./tough-cookie.cookiejar.getcookiestring.md) + +## CookieJar.getCookieString() method + +Accepts the same options as `.getCookies()` but returns a string suitable for a `Cookie` header rather than an Array. + +**Signature:** + +```typescript +getCookieString(url: string, options: GetCookiesOptions, callback: Callback): void; +``` + +## Parameters + + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +url + + + + +string + + + + +The domain to store the cookie with. + + +
+ +options + + + + +[GetCookiesOptions](./tough-cookie.getcookiesoptions.md) + + + + +Configuration settings to use when retrieving the cookies. + + +
+ +callback + + + + +[Callback](./tough-cookie.callback.md)<string \| undefined> + + + + +A function to call after the `Cookie` header string has been created. + + +
+**Returns:** + +void + diff --git a/api/docs/tough-cookie.cookiejar.getcookiestring_1.md b/api/docs/tough-cookie.cookiejar.getcookiestring_1.md new file mode 100644 index 00000000..0fd33009 --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.getcookiestring_1.md @@ -0,0 +1,69 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [getCookieString](./tough-cookie.cookiejar.getcookiestring_1.md) + +## CookieJar.getCookieString() method + +Accepts the same options as `.getCookies()` but returns a string suitable for a `Cookie` header rather than an Array. + +**Signature:** + +```typescript +getCookieString(url: string, callback: Callback): void; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +url + + + + +string + + + + +The domain to store the cookie with. + + +
+ +callback + + + + +[Callback](./tough-cookie.callback.md)<string \| undefined> + + + + +A function to call after the `Cookie` header string has been created. + + +
+**Returns:** + +void + diff --git a/api/docs/tough-cookie.cookiejar.getcookiestring_2.md b/api/docs/tough-cookie.cookiejar.getcookiestring_2.md new file mode 100644 index 00000000..936c72c1 --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.getcookiestring_2.md @@ -0,0 +1,69 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [getCookieString](./tough-cookie.cookiejar.getcookiestring_2.md) + +## CookieJar.getCookieString() method + +Accepts the same options as `.getCookies()` but returns a string suitable for a `Cookie` header rather than an Array. + +**Signature:** + +```typescript +getCookieString(url: string, options?: GetCookiesOptions): Promise; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +url + + + + +string + + + + +The domain to store the cookie with. + + +
+ +options + + + + +[GetCookiesOptions](./tough-cookie.getcookiesoptions.md) + + + + +_(Optional)_ Configuration settings to use when retrieving the cookies. + + +
+**Returns:** + +Promise<string> + diff --git a/api/docs/tough-cookie.cookiejar.getcookiestringsync.md b/api/docs/tough-cookie.cookiejar.getcookiestringsync.md new file mode 100644 index 00000000..b79682cb --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.getcookiestringsync.md @@ -0,0 +1,71 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [getCookieStringSync](./tough-cookie.cookiejar.getcookiestringsync.md) + +## CookieJar.getCookieStringSync() method + +Synchronous version of `.getCookieString()`. Accepts the same options as `.getCookies()` but returns a string suitable for a `Cookie` header rather than an Array. + +Note: Only works if the configured Store is also synchronous. + +**Signature:** + +```typescript +getCookieStringSync(url: string, options?: GetCookiesOptions): string; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +url + + + + +string + + + + +The domain to store the cookie with. + + +
+ +options + + + + +[GetCookiesOptions](./tough-cookie.getcookiesoptions.md) + + + + +_(Optional)_ Configuration settings to use when retrieving the cookies. + + +
+**Returns:** + +string + diff --git a/api/docs/tough-cookie.cookiejar.getsetcookiestrings.md b/api/docs/tough-cookie.cookiejar.getsetcookiestrings.md new file mode 100644 index 00000000..843c05c2 --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.getsetcookiestrings.md @@ -0,0 +1,69 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [getSetCookieStrings](./tough-cookie.cookiejar.getsetcookiestrings.md) + +## CookieJar.getSetCookieStrings() method + +Returns an array of strings suitable for `Set-Cookie` headers. Accepts the same options as `.getCookies()`. + +**Signature:** + +```typescript +getSetCookieStrings(url: string, callback: Callback): void; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +url + + + + +string + + + + +The domain to store the cookie with. + + +
+ +callback + + + + +[Callback](./tough-cookie.callback.md)<string\[\] \| undefined> + + + + +A function to call after the `Set-Cookie` header strings have been created. + + +
+**Returns:** + +void + diff --git a/api/docs/tough-cookie.cookiejar.getsetcookiestrings_1.md b/api/docs/tough-cookie.cookiejar.getsetcookiestrings_1.md new file mode 100644 index 00000000..5e7ecab1 --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.getsetcookiestrings_1.md @@ -0,0 +1,85 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [getSetCookieStrings](./tough-cookie.cookiejar.getsetcookiestrings_1.md) + +## CookieJar.getSetCookieStrings() method + +Returns an array of strings suitable for `Set-Cookie` headers. Accepts the same options as `.getCookies()`. + +**Signature:** + +```typescript +getSetCookieStrings(url: string, options: GetCookiesOptions, callback: Callback): void; +``` + +## Parameters + + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +url + + + + +string + + + + +The domain to store the cookie with. + + +
+ +options + + + + +[GetCookiesOptions](./tough-cookie.getcookiesoptions.md) + + + + +Configuration settings to use when retrieving the cookies. + + +
+ +callback + + + + +[Callback](./tough-cookie.callback.md)<string\[\] \| undefined> + + + + +A function to call after the `Set-Cookie` header strings have been created. + + +
+**Returns:** + +void + diff --git a/api/docs/tough-cookie.cookiejar.getsetcookiestrings_2.md b/api/docs/tough-cookie.cookiejar.getsetcookiestrings_2.md new file mode 100644 index 00000000..6fb97b52 --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.getsetcookiestrings_2.md @@ -0,0 +1,69 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [getSetCookieStrings](./tough-cookie.cookiejar.getsetcookiestrings_2.md) + +## CookieJar.getSetCookieStrings() method + +Returns an array of strings suitable for `Set-Cookie` headers. Accepts the same options as `.getCookies()`. + +**Signature:** + +```typescript +getSetCookieStrings(url: string, options?: GetCookiesOptions): Promise; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +url + + + + +string + + + + +The domain to store the cookie with. + + +
+ +options + + + + +[GetCookiesOptions](./tough-cookie.getcookiesoptions.md) + + + + +_(Optional)_ Configuration settings to use when retrieving the cookies. + + +
+**Returns:** + +Promise<string\[\] \| undefined> + diff --git a/api/docs/tough-cookie.cookiejar.getsetcookiestringssync.md b/api/docs/tough-cookie.cookiejar.getsetcookiestringssync.md new file mode 100644 index 00000000..1f0c6d53 --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.getsetcookiestringssync.md @@ -0,0 +1,71 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [getSetCookieStringsSync](./tough-cookie.cookiejar.getsetcookiestringssync.md) + +## CookieJar.getSetCookieStringsSync() method + +Synchronous version of `.getSetCookieStrings()`. Returns an array of strings suitable for `Set-Cookie` headers. Accepts the same options as `.getCookies()`. + +Note: Only works if the configured Store is also synchronous. + +**Signature:** + +```typescript +getSetCookieStringsSync(url: string, options?: GetCookiesOptions): string[]; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +url + + + + +string + + + + +The domain to store the cookie with. + + +
+ +options + + + + +[GetCookiesOptions](./tough-cookie.getcookiesoptions.md) + + + + +_(Optional)_ Configuration settings to use when retrieving the cookies. + + +
+**Returns:** + +string\[\] + diff --git a/api/docs/tough-cookie.cookiejar.md b/api/docs/tough-cookie.cookiejar.md new file mode 100644 index 00000000..57a132d0 --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.md @@ -0,0 +1,610 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) + +## CookieJar class + +A CookieJar is for storage and retrieval of [Cookie](./tough-cookie.cookie.md) objects as defined in [RFC6265 - Section 5.3](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.3). + +It also supports a pluggable persistence layer via [Store](./tough-cookie.store.md). + +**Signature:** + +```typescript +export declare class CookieJar +``` + +## Constructors + + + +
+ +Constructor + + + + +Modifiers + + + + +Description + + +
+ +[(constructor)(store, options)](./tough-cookie.cookiejar._constructor_.md) + + + + + + + +Creates a new `CookieJar` instance. + + +
+ +## Properties + + + + +
+ +Property + + + + +Modifiers + + + + +Type + + + + +Description + + +
+ +[prefixSecurity](./tough-cookie.cookiejar.prefixsecurity.md) + + + + +`readonly` + + + + +string + + + + +The configured [PrefixSecurityEnum](./tough-cookie.prefixsecurityenum.md) value for the [CookieJar](./tough-cookie.cookiejar.md). + + +
+ +[store](./tough-cookie.cookiejar.store.md) + + + + +`readonly` + + + + +[Store](./tough-cookie.store.md) + + + + +The configured [Store](./tough-cookie.store.md) for the [CookieJar](./tough-cookie.cookiejar.md). + + +
+ +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +Method + + + + +Modifiers + + + + +Description + + +
+ +[clone(callback)](./tough-cookie.cookiejar.clone.md) + + + + + + + +Produces a deep clone of this CookieJar. Modifications to the original do not affect the clone, and vice versa. + + +
+ +[clone(newStore, callback)](./tough-cookie.cookiejar.clone_1.md) + + + + + + + +Produces a deep clone of this CookieJar. Modifications to the original do not affect the clone, and vice versa. + + +
+ +[clone(newStore)](./tough-cookie.cookiejar.clone_2.md) + + + + + + + +Produces a deep clone of this CookieJar. Modifications to the original do not affect the clone, and vice versa. + + +
+ +[cloneSync(newStore)](./tough-cookie.cookiejar.clonesync.md) + + + + + + + +Produces a deep clone of this CookieJar. Modifications to the original do not affect the clone, and vice versa. + +Note: Only works if both the configured Store and destination Store are synchronous. + + +
+ +[deserialize(strOrObj, callback)](./tough-cookie.cookiejar.deserialize.md) + + + + +`static` + + + + +A new CookieJar is created and the serialized [Cookie](./tough-cookie.cookie.md) values are added to the underlying store. Each [Cookie](./tough-cookie.cookie.md) is added via `store.putCookie(...)` in the order in which they appear in the serialization. + + +
+ +[deserialize(strOrObj, store, callback)](./tough-cookie.cookiejar.deserialize_1.md) + + + + +`static` + + + + +A new CookieJar is created and the serialized [Cookie](./tough-cookie.cookie.md) values are added to the underlying store. Each [Cookie](./tough-cookie.cookie.md) is added via `store.putCookie(...)` in the order in which they appear in the serialization. + + +
+ +[deserialize(strOrObj, store)](./tough-cookie.cookiejar.deserialize_2.md) + + + + +`static` + + + + +A new CookieJar is created and the serialized [Cookie](./tough-cookie.cookie.md) values are added to the underlying store. Each [Cookie](./tough-cookie.cookie.md) is added via `store.putCookie(...)` in the order in which they appear in the serialization. + + +
+ +[deserializeSync(strOrObj, store)](./tough-cookie.cookiejar.deserializesync.md) + + + + +`static` + + + + +A new CookieJar is created and the serialized [Cookie](./tough-cookie.cookie.md) values are added to the underlying store. Each [Cookie](./tough-cookie.cookie.md) is added via `store.putCookie(...)` in the order in which they appear in the serialization. + +Note: Only works if the configured Store is also synchronous. + + +
+ +[fromJSON(jsonString, store)](./tough-cookie.cookiejar.fromjson.md) + + + + +`static` + + + + +Alias of [CookieJar.deserializeSync()](./tough-cookie.cookiejar.deserializesync.md). + + +
+ +[getCookies(url, callback)](./tough-cookie.cookiejar.getcookies.md) + + + + + + + +Retrieve the list of cookies that can be sent in a Cookie header for the current URL. + + +
+ +[getCookies(url, options, callback)](./tough-cookie.cookiejar.getcookies_1.md) + + + + + + + +Retrieve the list of cookies that can be sent in a Cookie header for the current URL. + + +
+ +[getCookies(url, options)](./tough-cookie.cookiejar.getcookies_2.md) + + + + + + + +Retrieve the list of cookies that can be sent in a Cookie header for the current URL. + + +
+ +[getCookiesSync(url, options)](./tough-cookie.cookiejar.getcookiessync.md) + + + + + + + +Synchronously retrieve the list of cookies that can be sent in a Cookie header for the current URL. + +Note: Only works if the configured Store is also synchronous. + + +
+ +[getCookieString(url, options, callback)](./tough-cookie.cookiejar.getcookiestring.md) + + + + + + + +Accepts the same options as `.getCookies()` but returns a string suitable for a `Cookie` header rather than an Array. + + +
+ +[getCookieString(url, callback)](./tough-cookie.cookiejar.getcookiestring_1.md) + + + + + + + +Accepts the same options as `.getCookies()` but returns a string suitable for a `Cookie` header rather than an Array. + + +
+ +[getCookieString(url, options)](./tough-cookie.cookiejar.getcookiestring_2.md) + + + + + + + +Accepts the same options as `.getCookies()` but returns a string suitable for a `Cookie` header rather than an Array. + + +
+ +[getCookieStringSync(url, options)](./tough-cookie.cookiejar.getcookiestringsync.md) + + + + + + + +Synchronous version of `.getCookieString()`. Accepts the same options as `.getCookies()` but returns a string suitable for a `Cookie` header rather than an Array. + +Note: Only works if the configured Store is also synchronous. + + +
+ +[getSetCookieStrings(url, callback)](./tough-cookie.cookiejar.getsetcookiestrings.md) + + + + + + + +Returns an array of strings suitable for `Set-Cookie` headers. Accepts the same options as `.getCookies()`. + + +
+ +[getSetCookieStrings(url, options, callback)](./tough-cookie.cookiejar.getsetcookiestrings_1.md) + + + + + + + +Returns an array of strings suitable for `Set-Cookie` headers. Accepts the same options as `.getCookies()`. + + +
+ +[getSetCookieStrings(url, options)](./tough-cookie.cookiejar.getsetcookiestrings_2.md) + + + + + + + +Returns an array of strings suitable for `Set-Cookie` headers. Accepts the same options as `.getCookies()`. + + +
+ +[getSetCookieStringsSync(url, options)](./tough-cookie.cookiejar.getsetcookiestringssync.md) + + + + + + + +Synchronous version of `.getSetCookieStrings()`. Returns an array of strings suitable for `Set-Cookie` headers. Accepts the same options as `.getCookies()`. + +Note: Only works if the configured Store is also synchronous. + + +
+ +[removeAllCookies(callback)](./tough-cookie.cookiejar.removeallcookies.md) + + + + + + + +Removes all cookies from the CookieJar. + + +
+ +[removeAllCookies()](./tough-cookie.cookiejar.removeallcookies_1.md) + + + + + + + +Removes all cookies from the CookieJar. + + +
+ +[removeAllCookiesSync()](./tough-cookie.cookiejar.removeallcookiessync.md) + + + + + + + +Removes all cookies from the CookieJar. + +Note: Only works if the configured Store is also synchronous. + + +
+ +[serialize(callback)](./tough-cookie.cookiejar.serialize.md) + + + + + + + +Serialize the CookieJar if the underlying store supports `.getAllCookies`. + + +
+ +[serialize()](./tough-cookie.cookiejar.serialize_1.md) + + + + + + + +Serialize the CookieJar if the underlying store supports `.getAllCookies`. + + +
+ +[serializeSync()](./tough-cookie.cookiejar.serializesync.md) + + + + + + + +Serialize the CookieJar if the underlying store supports `.getAllCookies`. + +Note: Only works if the configured Store is also synchronous. + + +
+ +[setCookie(cookie, url, callback)](./tough-cookie.cookiejar.setcookie.md) + + + + + + + +Attempt to set the [Cookie](./tough-cookie.cookie.md) in the [CookieJar](./tough-cookie.cookiejar.md). + + +
+ +[setCookie(cookie, url, options, callback)](./tough-cookie.cookiejar.setcookie_1.md) + + + + + + + +Attempt to set the [Cookie](./tough-cookie.cookie.md) in the [CookieJar](./tough-cookie.cookiejar.md). + + +
+ +[setCookie(cookie, url, options)](./tough-cookie.cookiejar.setcookie_2.md) + + + + + + + +Attempt to set the [Cookie](./tough-cookie.cookie.md) in the [CookieJar](./tough-cookie.cookiejar.md). + + +
+ +[setCookieSync(cookie, url, options)](./tough-cookie.cookiejar.setcookiesync.md) + + + + + + + +Synchronously attempt to set the [Cookie](./tough-cookie.cookie.md) in the [CookieJar](./tough-cookie.cookiejar.md). + +Note: Only works if the configured [Store](./tough-cookie.store.md) is also synchronous. + + +
+ +[toJSON()](./tough-cookie.cookiejar.tojson.md) + + + + + + + +Alias of [CookieJar.serializeSync()](./tough-cookie.cookiejar.serializesync.md). Allows the cookie to be serialized with `JSON.stringify(cookieJar)`. + + +
diff --git a/api/docs/tough-cookie.cookiejar.prefixsecurity.md b/api/docs/tough-cookie.cookiejar.prefixsecurity.md new file mode 100644 index 00000000..6d0ab52d --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.prefixsecurity.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [prefixSecurity](./tough-cookie.cookiejar.prefixsecurity.md) + +## CookieJar.prefixSecurity property + +The configured [PrefixSecurityEnum](./tough-cookie.prefixsecurityenum.md) value for the [CookieJar](./tough-cookie.cookiejar.md). + +**Signature:** + +```typescript +readonly prefixSecurity: string; +``` diff --git a/api/docs/tough-cookie.cookiejar.removeallcookies.md b/api/docs/tough-cookie.cookiejar.removeallcookies.md new file mode 100644 index 00000000..028c4d23 --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.removeallcookies.md @@ -0,0 +1,61 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [removeAllCookies](./tough-cookie.cookiejar.removeallcookies.md) + +## CookieJar.removeAllCookies() method + +Removes all cookies from the CookieJar. + +**Signature:** + +```typescript +removeAllCookies(callback: ErrorCallback): void; +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +callback + + + + +[ErrorCallback](./tough-cookie.errorcallback.md) + + + + +A function to call when all the cookies have been removed. + + +
+**Returns:** + +void + +## Remarks + +- This is a new backwards-compatible feature of tough-cookie version 2.5, so not all Stores will implement it efficiently. For Stores that do not implement `removeAllCookies`, the fallback is to call `removeCookie` after `getAllCookies`. + +- If `getAllCookies` fails or isn't implemented in the Store, an error is returned. + +- If one or more of the `removeCookie` calls fail, only the first error is returned. + diff --git a/api/docs/tough-cookie.cookiejar.removeallcookies_1.md b/api/docs/tough-cookie.cookiejar.removeallcookies_1.md new file mode 100644 index 00000000..72bc852a --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.removeallcookies_1.md @@ -0,0 +1,25 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [removeAllCookies](./tough-cookie.cookiejar.removeallcookies_1.md) + +## CookieJar.removeAllCookies() method + +Removes all cookies from the CookieJar. + +**Signature:** + +```typescript +removeAllCookies(): Promise; +``` +**Returns:** + +Promise<void> + +## Remarks + +- This is a new backwards-compatible feature of tough-cookie version 2.5, so not all Stores will implement it efficiently. For Stores that do not implement `removeAllCookies`, the fallback is to call `removeCookie` after `getAllCookies`. + +- If `getAllCookies` fails or isn't implemented in the Store, an error is returned. + +- If one or more of the `removeCookie` calls fail, only the first error is returned. + diff --git a/api/docs/tough-cookie.cookiejar.removeallcookiessync.md b/api/docs/tough-cookie.cookiejar.removeallcookiessync.md new file mode 100644 index 00000000..194189c5 --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.removeallcookiessync.md @@ -0,0 +1,27 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [removeAllCookiesSync](./tough-cookie.cookiejar.removeallcookiessync.md) + +## CookieJar.removeAllCookiesSync() method + +Removes all cookies from the CookieJar. + +Note: Only works if the configured Store is also synchronous. + +**Signature:** + +```typescript +removeAllCookiesSync(): void; +``` +**Returns:** + +void + +## Remarks + +- This is a new backwards-compatible feature of tough-cookie version 2.5, so not all Stores will implement it efficiently. For Stores that do not implement `removeAllCookies`, the fallback is to call `removeCookie` after `getAllCookies`. + +- If `getAllCookies` fails or isn't implemented in the Store, an error is returned. + +- If one or more of the `removeCookie` calls fail, only the first error is returned. + diff --git a/api/docs/tough-cookie.cookiejar.serialize.md b/api/docs/tough-cookie.cookiejar.serialize.md new file mode 100644 index 00000000..30767c50 --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.serialize.md @@ -0,0 +1,53 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [serialize](./tough-cookie.cookiejar.serialize.md) + +## CookieJar.serialize() method + +Serialize the CookieJar if the underlying store supports `.getAllCookies`. + +**Signature:** + +```typescript +serialize(callback: Callback): void; +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +callback + + + + +[Callback](./tough-cookie.callback.md)<[SerializedCookieJar](./tough-cookie.serializedcookiejar.md)> + + + + +A function to call after the CookieJar has been serialized + + +
+**Returns:** + +void + diff --git a/api/docs/tough-cookie.cookiejar.serialize_1.md b/api/docs/tough-cookie.cookiejar.serialize_1.md new file mode 100644 index 00000000..391884c4 --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.serialize_1.md @@ -0,0 +1,17 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [serialize](./tough-cookie.cookiejar.serialize_1.md) + +## CookieJar.serialize() method + +Serialize the CookieJar if the underlying store supports `.getAllCookies`. + +**Signature:** + +```typescript +serialize(): Promise; +``` +**Returns:** + +Promise<[SerializedCookieJar](./tough-cookie.serializedcookiejar.md)> + diff --git a/api/docs/tough-cookie.cookiejar.serializesync.md b/api/docs/tough-cookie.cookiejar.serializesync.md new file mode 100644 index 00000000..87eb4bd8 --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.serializesync.md @@ -0,0 +1,19 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [serializeSync](./tough-cookie.cookiejar.serializesync.md) + +## CookieJar.serializeSync() method + +Serialize the CookieJar if the underlying store supports `.getAllCookies`. + +Note: Only works if the configured Store is also synchronous. + +**Signature:** + +```typescript +serializeSync(): SerializedCookieJar | undefined; +``` +**Returns:** + +[SerializedCookieJar](./tough-cookie.serializedcookiejar.md) \| undefined + diff --git a/api/docs/tough-cookie.cookiejar.setcookie.md b/api/docs/tough-cookie.cookiejar.setcookie.md new file mode 100644 index 00000000..b54334f5 --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.setcookie.md @@ -0,0 +1,91 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [setCookie](./tough-cookie.cookiejar.setcookie.md) + +## CookieJar.setCookie() method + +Attempt to set the [Cookie](./tough-cookie.cookie.md) in the [CookieJar](./tough-cookie.cookiejar.md). + +**Signature:** + +```typescript +setCookie(cookie: string | Cookie, url: string | URL, callback: Callback): void; +``` + +## Parameters + + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +cookie + + + + +string \| [Cookie](./tough-cookie.cookie.md) + + + + +The cookie object or cookie string to store. A string value will be parsed into a cookie using [Cookie.parse()](./tough-cookie.cookie.parse.md). + + +
+ +url + + + + +string \| URL + + + + +The domain to store the cookie with. + + +
+ +callback + + + + +[Callback](./tough-cookie.callback.md)<[Cookie](./tough-cookie.cookie.md) \| undefined> + + + + +A function to call after a cookie has been successfully stored. + + +
+**Returns:** + +void + +## Remarks + +- If successfully persisted, the [Cookie](./tough-cookie.cookie.md) will have updated [Cookie.creation](./tough-cookie.cookie.creation.md), [Cookie.lastAccessed](./tough-cookie.cookie.lastaccessed.md) and [Cookie.hostOnly](./tough-cookie.cookie.hostonly.md) properties. + +- As per the RFC, the [Cookie.hostOnly](./tough-cookie.cookie.hostonly.md) flag is set if there was no `Domain={value}` atttribute on the cookie string. The [Cookie.domain](./tough-cookie.cookie.domain.md) property is set to the fully-qualified hostname of `currentUrl` in this case. Matching this cookie requires an exact hostname match (not a [domainMatch()](./tough-cookie.domainmatch.md) as per usual) + diff --git a/api/docs/tough-cookie.cookiejar.setcookie_1.md b/api/docs/tough-cookie.cookiejar.setcookie_1.md new file mode 100644 index 00000000..22df45b0 --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.setcookie_1.md @@ -0,0 +1,107 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [setCookie](./tough-cookie.cookiejar.setcookie_1.md) + +## CookieJar.setCookie() method + +Attempt to set the [Cookie](./tough-cookie.cookie.md) in the [CookieJar](./tough-cookie.cookiejar.md). + +**Signature:** + +```typescript +setCookie(cookie: string | Cookie, url: string | URL, options: SetCookieOptions, callback: Callback): void; +``` + +## Parameters + + + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +cookie + + + + +string \| [Cookie](./tough-cookie.cookie.md) + + + + +The cookie object or cookie string to store. A string value will be parsed into a cookie using [Cookie.parse()](./tough-cookie.cookie.parse.md). + + +
+ +url + + + + +string \| URL + + + + +The domain to store the cookie with. + + +
+ +options + + + + +[SetCookieOptions](./tough-cookie.setcookieoptions.md) + + + + +Configuration settings to use when storing the cookie. + + +
+ +callback + + + + +[Callback](./tough-cookie.callback.md)<[Cookie](./tough-cookie.cookie.md) \| undefined> + + + + +A function to call after a cookie has been successfully stored. + + +
+**Returns:** + +void + +## Remarks + +- If successfully persisted, the [Cookie](./tough-cookie.cookie.md) will have updated [Cookie.creation](./tough-cookie.cookie.creation.md), [Cookie.lastAccessed](./tough-cookie.cookie.lastaccessed.md) and [Cookie.hostOnly](./tough-cookie.cookie.hostonly.md) properties. + +- As per the RFC, the [Cookie.hostOnly](./tough-cookie.cookie.hostonly.md) flag is set if there was no `Domain={value}` atttribute on the cookie string. The [Cookie.domain](./tough-cookie.cookie.domain.md) property is set to the fully-qualified hostname of `currentUrl` in this case. Matching this cookie requires an exact hostname match (not a [domainMatch()](./tough-cookie.domainmatch.md) as per usual) + diff --git a/api/docs/tough-cookie.cookiejar.setcookie_2.md b/api/docs/tough-cookie.cookiejar.setcookie_2.md new file mode 100644 index 00000000..c2424bc1 --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.setcookie_2.md @@ -0,0 +1,91 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [setCookie](./tough-cookie.cookiejar.setcookie_2.md) + +## CookieJar.setCookie() method + +Attempt to set the [Cookie](./tough-cookie.cookie.md) in the [CookieJar](./tough-cookie.cookiejar.md). + +**Signature:** + +```typescript +setCookie(cookie: string | Cookie, url: string | URL, options?: SetCookieOptions): Promise; +``` + +## Parameters + + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +cookie + + + + +string \| [Cookie](./tough-cookie.cookie.md) + + + + +The cookie object or cookie string to store. A string value will be parsed into a cookie using [Cookie.parse()](./tough-cookie.cookie.parse.md). + + +
+ +url + + + + +string \| URL + + + + +The domain to store the cookie with. + + +
+ +options + + + + +[SetCookieOptions](./tough-cookie.setcookieoptions.md) + + + + +_(Optional)_ Configuration settings to use when storing the cookie. + + +
+**Returns:** + +Promise<[Cookie](./tough-cookie.cookie.md) \| undefined> + +## Remarks + +- If successfully persisted, the [Cookie](./tough-cookie.cookie.md) will have updated [Cookie.creation](./tough-cookie.cookie.creation.md), [Cookie.lastAccessed](./tough-cookie.cookie.lastaccessed.md) and [Cookie.hostOnly](./tough-cookie.cookie.hostonly.md) properties. + +- As per the RFC, the [Cookie.hostOnly](./tough-cookie.cookie.hostonly.md) flag is set if there was no `Domain={value}` atttribute on the cookie string. The [Cookie.domain](./tough-cookie.cookie.domain.md) property is set to the fully-qualified hostname of `currentUrl` in this case. Matching this cookie requires an exact hostname match (not a [domainMatch()](./tough-cookie.domainmatch.md) as per usual) + diff --git a/api/docs/tough-cookie.cookiejar.setcookiesync.md b/api/docs/tough-cookie.cookiejar.setcookiesync.md new file mode 100644 index 00000000..1cce537c --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.setcookiesync.md @@ -0,0 +1,93 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [setCookieSync](./tough-cookie.cookiejar.setcookiesync.md) + +## CookieJar.setCookieSync() method + +Synchronously attempt to set the [Cookie](./tough-cookie.cookie.md) in the [CookieJar](./tough-cookie.cookiejar.md). + +Note: Only works if the configured [Store](./tough-cookie.store.md) is also synchronous. + +**Signature:** + +```typescript +setCookieSync(cookie: string | Cookie, url: string, options?: SetCookieOptions): Cookie | undefined; +``` + +## Parameters + + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +cookie + + + + +string \| [Cookie](./tough-cookie.cookie.md) + + + + +The cookie object or cookie string to store. A string value will be parsed into a cookie using [Cookie.parse()](./tough-cookie.cookie.parse.md). + + +
+ +url + + + + +string + + + + +The domain to store the cookie with. + + +
+ +options + + + + +[SetCookieOptions](./tough-cookie.setcookieoptions.md) + + + + +_(Optional)_ Configuration settings to use when storing the cookie. + + +
+**Returns:** + +[Cookie](./tough-cookie.cookie.md) \| undefined + +## Remarks + +- If successfully persisted, the [Cookie](./tough-cookie.cookie.md) will have updated [Cookie.creation](./tough-cookie.cookie.creation.md), [Cookie.lastAccessed](./tough-cookie.cookie.lastaccessed.md) and [Cookie.hostOnly](./tough-cookie.cookie.hostonly.md) properties. + +- As per the RFC, the [Cookie.hostOnly](./tough-cookie.cookie.hostonly.md) flag is set if there was no `Domain={value}` atttribute on the cookie string. The [Cookie.domain](./tough-cookie.cookie.domain.md) property is set to the fully-qualified hostname of `currentUrl` in this case. Matching this cookie requires an exact hostname match (not a [domainMatch()](./tough-cookie.domainmatch.md) as per usual) + diff --git a/api/docs/tough-cookie.cookiejar.store.md b/api/docs/tough-cookie.cookiejar.store.md new file mode 100644 index 00000000..74a5a727 --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.store.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [store](./tough-cookie.cookiejar.store.md) + +## CookieJar.store property + +The configured [Store](./tough-cookie.store.md) for the [CookieJar](./tough-cookie.cookiejar.md). + +**Signature:** + +```typescript +readonly store: Store; +``` diff --git a/api/docs/tough-cookie.cookiejar.tojson.md b/api/docs/tough-cookie.cookiejar.tojson.md new file mode 100644 index 00000000..4319a7c2 --- /dev/null +++ b/api/docs/tough-cookie.cookiejar.tojson.md @@ -0,0 +1,17 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CookieJar](./tough-cookie.cookiejar.md) > [toJSON](./tough-cookie.cookiejar.tojson.md) + +## CookieJar.toJSON() method + +Alias of [CookieJar.serializeSync()](./tough-cookie.cookiejar.serializesync.md). Allows the cookie to be serialized with `JSON.stringify(cookieJar)`. + +**Signature:** + +```typescript +toJSON(): SerializedCookieJar | undefined; +``` +**Returns:** + +[SerializedCookieJar](./tough-cookie.serializedcookiejar.md) \| undefined + diff --git a/api/docs/tough-cookie.createcookiejaroptions.allowspecialusedomain.md b/api/docs/tough-cookie.createcookiejaroptions.allowspecialusedomain.md new file mode 100644 index 00000000..7114c63d --- /dev/null +++ b/api/docs/tough-cookie.createcookiejaroptions.allowspecialusedomain.md @@ -0,0 +1,15 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CreateCookieJarOptions](./tough-cookie.createcookiejaroptions.md) > [allowSpecialUseDomain](./tough-cookie.createcookiejaroptions.allowspecialusedomain.md) + +## CreateCookieJarOptions.allowSpecialUseDomain property + +Accepts [special-use domains](https://datatracker.ietf.org/doc/html/rfc6761) such as `local`. This is not in the standard, but is used sometimes on the web and is accepted by most browsers. It is also useful for testing purposes. + +Defaults to `true` if not specified. + +**Signature:** + +```typescript +allowSpecialUseDomain?: boolean | undefined; +``` diff --git a/api/docs/tough-cookie.createcookiejaroptions.loosemode.md b/api/docs/tough-cookie.createcookiejaroptions.loosemode.md new file mode 100644 index 00000000..86ada989 --- /dev/null +++ b/api/docs/tough-cookie.createcookiejaroptions.loosemode.md @@ -0,0 +1,15 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CreateCookieJarOptions](./tough-cookie.createcookiejaroptions.md) > [looseMode](./tough-cookie.createcookiejaroptions.loosemode.md) + +## CreateCookieJarOptions.looseMode property + +Accept malformed cookies like `bar` and `=bar`, which have an implied empty name but are not RFC-compliant. + +Defaults to `false` if not specified. + +**Signature:** + +```typescript +looseMode?: boolean | undefined; +``` diff --git a/api/docs/tough-cookie.createcookiejaroptions.md b/api/docs/tough-cookie.createcookiejaroptions.md new file mode 100644 index 00000000..8b28a692 --- /dev/null +++ b/api/docs/tough-cookie.createcookiejaroptions.md @@ -0,0 +1,122 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CreateCookieJarOptions](./tough-cookie.createcookiejaroptions.md) + +## CreateCookieJarOptions interface + +Configuration settings to be used with a [CookieJar](./tough-cookie.cookiejar.md). + +**Signature:** + +```typescript +export interface CreateCookieJarOptions +``` + +## Properties + + + + + + +
+ +Property + + + + +Modifiers + + + + +Type + + + + +Description + + +
+ +[allowSpecialUseDomain?](./tough-cookie.createcookiejaroptions.allowspecialusedomain.md) + + + + + + + +boolean \| undefined + + + + +_(Optional)_ Accepts [special-use domains](https://datatracker.ietf.org/doc/html/rfc6761) such as `local`. This is not in the standard, but is used sometimes on the web and is accepted by most browsers. It is also useful for testing purposes. + +Defaults to `true` if not specified. + + +
+ +[looseMode?](./tough-cookie.createcookiejaroptions.loosemode.md) + + + + + + + +boolean \| undefined + + + + +_(Optional)_ Accept malformed cookies like `bar` and `=bar`, which have an implied empty name but are not RFC-compliant. + +Defaults to `false` if not specified. + + +
+ +[prefixSecurity?](./tough-cookie.createcookiejaroptions.prefixsecurity.md) + + + + + + + +'strict' \| 'silent' \| 'unsafe-disabled' \| undefined + + + + +_(Optional)_ Controls how cookie prefixes are handled. See [PrefixSecurityEnum](./tough-cookie.prefixsecurityenum.md). + +Defaults to `silent` if not specified. + + +
+ +[rejectPublicSuffixes?](./tough-cookie.createcookiejaroptions.rejectpublicsuffixes.md) + + + + + + + +boolean \| undefined + + + + +_(Optional)_ Reject cookies that match those defined in the [Public Suffix List](https://publicsuffix.org/) (e.g.; domains like "com" and "co.uk"). + +Defaults to `true` if not specified. + + +
diff --git a/api/docs/tough-cookie.createcookiejaroptions.prefixsecurity.md b/api/docs/tough-cookie.createcookiejaroptions.prefixsecurity.md new file mode 100644 index 00000000..b8c98ca9 --- /dev/null +++ b/api/docs/tough-cookie.createcookiejaroptions.prefixsecurity.md @@ -0,0 +1,15 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CreateCookieJarOptions](./tough-cookie.createcookiejaroptions.md) > [prefixSecurity](./tough-cookie.createcookiejaroptions.prefixsecurity.md) + +## CreateCookieJarOptions.prefixSecurity property + +Controls how cookie prefixes are handled. See [PrefixSecurityEnum](./tough-cookie.prefixsecurityenum.md). + +Defaults to `silent` if not specified. + +**Signature:** + +```typescript +prefixSecurity?: 'strict' | 'silent' | 'unsafe-disabled' | undefined; +``` diff --git a/api/docs/tough-cookie.createcookiejaroptions.rejectpublicsuffixes.md b/api/docs/tough-cookie.createcookiejaroptions.rejectpublicsuffixes.md new file mode 100644 index 00000000..90bd818c --- /dev/null +++ b/api/docs/tough-cookie.createcookiejaroptions.rejectpublicsuffixes.md @@ -0,0 +1,15 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CreateCookieJarOptions](./tough-cookie.createcookiejaroptions.md) > [rejectPublicSuffixes](./tough-cookie.createcookiejaroptions.rejectpublicsuffixes.md) + +## CreateCookieJarOptions.rejectPublicSuffixes property + +Reject cookies that match those defined in the [Public Suffix List](https://publicsuffix.org/) (e.g.; domains like "com" and "co.uk"). + +Defaults to `true` if not specified. + +**Signature:** + +```typescript +rejectPublicSuffixes?: boolean | undefined; +``` diff --git a/api/docs/tough-cookie.createcookieoptions.creation.md b/api/docs/tough-cookie.createcookieoptions.creation.md new file mode 100644 index 00000000..44798f26 --- /dev/null +++ b/api/docs/tough-cookie.createcookieoptions.creation.md @@ -0,0 +1,15 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CreateCookieOptions](./tough-cookie.createcookieoptions.md) > [creation](./tough-cookie.createcookieoptions.creation.md) + +## CreateCookieOptions.creation property + +Set to the date and time when a Cookie is initially stored or a matching cookie is received that replaces an existing cookie (See [RFC6265 Section 5.3](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.3)). + +Also used to maintain ordering among cookies. Among cookies that have equal-length path fields, cookies with earlier creation-times are listed before cookies with later creation-times (See [RFC6265 Section 5.4](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.4)). + +**Signature:** + +```typescript +creation?: Date | 'Infinity' | null; +``` diff --git a/api/docs/tough-cookie.createcookieoptions.domain.md b/api/docs/tough-cookie.createcookieoptions.domain.md new file mode 100644 index 00000000..6d765df3 --- /dev/null +++ b/api/docs/tough-cookie.createcookieoptions.domain.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CreateCookieOptions](./tough-cookie.createcookieoptions.md) > [domain](./tough-cookie.createcookieoptions.domain.md) + +## CreateCookieOptions.domain property + +The 'Domain' attribute of the cookie represents the domain the cookie belongs to (See [RFC6265 Section 5.2.3](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.3)). + +**Signature:** + +```typescript +domain?: string | null; +``` diff --git a/api/docs/tough-cookie.createcookieoptions.expires.md b/api/docs/tough-cookie.createcookieoptions.expires.md new file mode 100644 index 00000000..6bdc424a --- /dev/null +++ b/api/docs/tough-cookie.createcookieoptions.expires.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CreateCookieOptions](./tough-cookie.createcookieoptions.md) > [expires](./tough-cookie.createcookieoptions.expires.md) + +## CreateCookieOptions.expires property + +The 'Expires' attribute of the cookie (See [RFC6265 Section 5.2.1](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.1)). + +**Signature:** + +```typescript +expires?: Date | 'Infinity' | null; +``` diff --git a/api/docs/tough-cookie.createcookieoptions.extensions.md b/api/docs/tough-cookie.createcookieoptions.extensions.md new file mode 100644 index 00000000..8366f3fe --- /dev/null +++ b/api/docs/tough-cookie.createcookieoptions.extensions.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CreateCookieOptions](./tough-cookie.createcookieoptions.md) > [extensions](./tough-cookie.createcookieoptions.extensions.md) + +## CreateCookieOptions.extensions property + +Contains attributes which are not part of the defined spec but match the `extension-av` syntax defined in Section 4.1.1 of RFC6265 (See [RFC6265 Section 4.1.1](https://www.rfc-editor.org/rfc/rfc6265.html#section-4.1.1)). + +**Signature:** + +```typescript +extensions?: string[] | null; +``` diff --git a/api/docs/tough-cookie.createcookieoptions.hostonly.md b/api/docs/tough-cookie.createcookieoptions.hostonly.md new file mode 100644 index 00000000..3e7e04f8 --- /dev/null +++ b/api/docs/tough-cookie.createcookieoptions.hostonly.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CreateCookieOptions](./tough-cookie.createcookieoptions.md) > [hostOnly](./tough-cookie.createcookieoptions.hostonly.md) + +## CreateCookieOptions.hostOnly property + +A boolean flag indicating if a cookie is a host-only cookie (i.e.; when the request's host exactly matches the domain of the cookie) or not (See [RFC6265 Section 5.3](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.3)). + +**Signature:** + +```typescript +hostOnly?: boolean | null; +``` diff --git a/api/docs/tough-cookie.createcookieoptions.httponly.md b/api/docs/tough-cookie.createcookieoptions.httponly.md new file mode 100644 index 00000000..c2a742de --- /dev/null +++ b/api/docs/tough-cookie.createcookieoptions.httponly.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CreateCookieOptions](./tough-cookie.createcookieoptions.md) > [httpOnly](./tough-cookie.createcookieoptions.httponly.md) + +## CreateCookieOptions.httpOnly property + +The 'HttpOnly' flag of the cookie indicates if the cookie is inaccessible to client scripts or not (See [RFC6265 Section 5.2.6](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.6)). + +**Signature:** + +```typescript +httpOnly?: boolean; +``` diff --git a/api/docs/tough-cookie.createcookieoptions.key.md b/api/docs/tough-cookie.createcookieoptions.key.md new file mode 100644 index 00000000..4fac3814 --- /dev/null +++ b/api/docs/tough-cookie.createcookieoptions.key.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CreateCookieOptions](./tough-cookie.createcookieoptions.md) > [key](./tough-cookie.createcookieoptions.key.md) + +## CreateCookieOptions.key property + +The name or key of the cookie + +**Signature:** + +```typescript +key?: string; +``` diff --git a/api/docs/tough-cookie.createcookieoptions.lastaccessed.md b/api/docs/tough-cookie.createcookieoptions.lastaccessed.md new file mode 100644 index 00000000..085df608 --- /dev/null +++ b/api/docs/tough-cookie.createcookieoptions.lastaccessed.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CreateCookieOptions](./tough-cookie.createcookieoptions.md) > [lastAccessed](./tough-cookie.createcookieoptions.lastaccessed.md) + +## CreateCookieOptions.lastAccessed property + +Set to the date and time when a cookie was initially stored ([RFC6265 Section 5.3](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.3)) and updated whenever the cookie is retrieved from the [CookieJar](./tough-cookie.cookiejar.md) ([RFC6265 Section 5.4](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.4)). + +**Signature:** + +```typescript +lastAccessed?: Date | 'Infinity' | null; +``` diff --git a/api/docs/tough-cookie.createcookieoptions.maxage.md b/api/docs/tough-cookie.createcookieoptions.maxage.md new file mode 100644 index 00000000..7b8e2177 --- /dev/null +++ b/api/docs/tough-cookie.createcookieoptions.maxage.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CreateCookieOptions](./tough-cookie.createcookieoptions.md) > [maxAge](./tough-cookie.createcookieoptions.maxage.md) + +## CreateCookieOptions.maxAge property + +The 'Max-Age' attribute of the cookie (See [RFC6265 Section 5.2.2](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.2)). + +**Signature:** + +```typescript +maxAge?: number | 'Infinity' | '-Infinity' | null; +``` diff --git a/api/docs/tough-cookie.createcookieoptions.md b/api/docs/tough-cookie.createcookieoptions.md new file mode 100644 index 00000000..818377f0 --- /dev/null +++ b/api/docs/tough-cookie.createcookieoptions.md @@ -0,0 +1,306 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CreateCookieOptions](./tough-cookie.createcookieoptions.md) + +## CreateCookieOptions interface + +Configurable values that can be set when creating a [Cookie](./tough-cookie.cookie.md). + +**Signature:** + +```typescript +export interface CreateCookieOptions +``` + +## Properties + + + + + + + + + + + + + + + + +
+ +Property + + + + +Modifiers + + + + +Type + + + + +Description + + +
+ +[creation?](./tough-cookie.createcookieoptions.creation.md) + + + + + + + +Date \| 'Infinity' \| null + + + + +_(Optional)_ Set to the date and time when a Cookie is initially stored or a matching cookie is received that replaces an existing cookie (See [RFC6265 Section 5.3](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.3)). + +Also used to maintain ordering among cookies. Among cookies that have equal-length path fields, cookies with earlier creation-times are listed before cookies with later creation-times (See [RFC6265 Section 5.4](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.4)). + + +
+ +[domain?](./tough-cookie.createcookieoptions.domain.md) + + + + + + + +string \| null + + + + +_(Optional)_ The 'Domain' attribute of the cookie represents the domain the cookie belongs to (See [RFC6265 Section 5.2.3](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.3)). + + +
+ +[expires?](./tough-cookie.createcookieoptions.expires.md) + + + + + + + +Date \| 'Infinity' \| null + + + + +_(Optional)_ The 'Expires' attribute of the cookie (See [RFC6265 Section 5.2.1](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.1)). + + +
+ +[extensions?](./tough-cookie.createcookieoptions.extensions.md) + + + + + + + +string\[\] \| null + + + + +_(Optional)_ Contains attributes which are not part of the defined spec but match the `extension-av` syntax defined in Section 4.1.1 of RFC6265 (See [RFC6265 Section 4.1.1](https://www.rfc-editor.org/rfc/rfc6265.html#section-4.1.1)). + + +
+ +[hostOnly?](./tough-cookie.createcookieoptions.hostonly.md) + + + + + + + +boolean \| null + + + + +_(Optional)_ A boolean flag indicating if a cookie is a host-only cookie (i.e.; when the request's host exactly matches the domain of the cookie) or not (See [RFC6265 Section 5.3](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.3)). + + +
+ +[httpOnly?](./tough-cookie.createcookieoptions.httponly.md) + + + + + + + +boolean + + + + +_(Optional)_ The 'HttpOnly' flag of the cookie indicates if the cookie is inaccessible to client scripts or not (See [RFC6265 Section 5.2.6](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.6)). + + +
+ +[key?](./tough-cookie.createcookieoptions.key.md) + + + + + + + +string + + + + +_(Optional)_ The name or key of the cookie + + +
+ +[lastAccessed?](./tough-cookie.createcookieoptions.lastaccessed.md) + + + + + + + +Date \| 'Infinity' \| null + + + + +_(Optional)_ Set to the date and time when a cookie was initially stored ([RFC6265 Section 5.3](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.3)) and updated whenever the cookie is retrieved from the [CookieJar](./tough-cookie.cookiejar.md) ([RFC6265 Section 5.4](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.4)). + + +
+ +[maxAge?](./tough-cookie.createcookieoptions.maxage.md) + + + + + + + +number \| 'Infinity' \| '-Infinity' \| null + + + + +_(Optional)_ The 'Max-Age' attribute of the cookie (See [RFC6265 Section 5.2.2](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.2)). + + +
+ +[path?](./tough-cookie.createcookieoptions.path.md) + + + + + + + +string \| null + + + + +_(Optional)_ The 'Path' attribute of the cookie represents the path of the cookie (See [RFC6265 Section 5.2.4](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.4)). + + +
+ +[pathIsDefault?](./tough-cookie.createcookieoptions.pathisdefault.md) + + + + + + + +boolean \| null + + + + +_(Optional)_ A boolean flag indicating if a cookie had no 'Path' attribute and the default path was used (See [RFC6265 Section 5.2.4](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.4)). + + +
+ +[sameSite?](./tough-cookie.createcookieoptions.samesite.md) + + + + + + + +string \| undefined + + + + +_(Optional)_ The 'SameSite' attribute of a cookie as defined in RFC6265bis (See [RFC6265bis (v13) Section 5.2](https://www.ietf.org/archive/id/draft-ietf-httpbis-rfc6265bis-13.html#section-5.2)). + + +
+ +[secure?](./tough-cookie.createcookieoptions.secure.md) + + + + + + + +boolean + + + + +_(Optional)_ The 'Secure' flag of the cookie indicates if the scope of the cookie is limited to secure channels (e.g.; HTTPS) or not (See [RFC6265 Section 5.2.5](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.5)). + + +
+ +[value?](./tough-cookie.createcookieoptions.value.md) + + + + + + + +string + + + + +_(Optional)_ The value of the cookie + + +
diff --git a/api/docs/tough-cookie.createcookieoptions.path.md b/api/docs/tough-cookie.createcookieoptions.path.md new file mode 100644 index 00000000..64cbd3aa --- /dev/null +++ b/api/docs/tough-cookie.createcookieoptions.path.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CreateCookieOptions](./tough-cookie.createcookieoptions.md) > [path](./tough-cookie.createcookieoptions.path.md) + +## CreateCookieOptions.path property + +The 'Path' attribute of the cookie represents the path of the cookie (See [RFC6265 Section 5.2.4](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.4)). + +**Signature:** + +```typescript +path?: string | null; +``` diff --git a/api/docs/tough-cookie.createcookieoptions.pathisdefault.md b/api/docs/tough-cookie.createcookieoptions.pathisdefault.md new file mode 100644 index 00000000..e1f8632f --- /dev/null +++ b/api/docs/tough-cookie.createcookieoptions.pathisdefault.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CreateCookieOptions](./tough-cookie.createcookieoptions.md) > [pathIsDefault](./tough-cookie.createcookieoptions.pathisdefault.md) + +## CreateCookieOptions.pathIsDefault property + +A boolean flag indicating if a cookie had no 'Path' attribute and the default path was used (See [RFC6265 Section 5.2.4](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.4)). + +**Signature:** + +```typescript +pathIsDefault?: boolean | null; +``` diff --git a/api/docs/tough-cookie.createcookieoptions.samesite.md b/api/docs/tough-cookie.createcookieoptions.samesite.md new file mode 100644 index 00000000..47c48740 --- /dev/null +++ b/api/docs/tough-cookie.createcookieoptions.samesite.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CreateCookieOptions](./tough-cookie.createcookieoptions.md) > [sameSite](./tough-cookie.createcookieoptions.samesite.md) + +## CreateCookieOptions.sameSite property + +The 'SameSite' attribute of a cookie as defined in RFC6265bis (See [RFC6265bis (v13) Section 5.2](https://www.ietf.org/archive/id/draft-ietf-httpbis-rfc6265bis-13.html#section-5.2)). + +**Signature:** + +```typescript +sameSite?: string | undefined; +``` diff --git a/api/docs/tough-cookie.createcookieoptions.secure.md b/api/docs/tough-cookie.createcookieoptions.secure.md new file mode 100644 index 00000000..a6ad7180 --- /dev/null +++ b/api/docs/tough-cookie.createcookieoptions.secure.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CreateCookieOptions](./tough-cookie.createcookieoptions.md) > [secure](./tough-cookie.createcookieoptions.secure.md) + +## CreateCookieOptions.secure property + +The 'Secure' flag of the cookie indicates if the scope of the cookie is limited to secure channels (e.g.; HTTPS) or not (See [RFC6265 Section 5.2.5](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.5)). + +**Signature:** + +```typescript +secure?: boolean; +``` diff --git a/api/docs/tough-cookie.createcookieoptions.value.md b/api/docs/tough-cookie.createcookieoptions.value.md new file mode 100644 index 00000000..70ad3a2d --- /dev/null +++ b/api/docs/tough-cookie.createcookieoptions.value.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [CreateCookieOptions](./tough-cookie.createcookieoptions.md) > [value](./tough-cookie.createcookieoptions.value.md) + +## CreateCookieOptions.value property + +The value of the cookie + +**Signature:** + +```typescript +value?: string; +``` diff --git a/api/docs/tough-cookie.defaultpath.md b/api/docs/tough-cookie.defaultpath.md new file mode 100644 index 00000000..69c721ad --- /dev/null +++ b/api/docs/tough-cookie.defaultpath.md @@ -0,0 +1,77 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [defaultPath](./tough-cookie.defaultpath.md) + +## defaultPath() function + +Given a current request/response path, gives the path appropriate for storing in a cookie. This is basically the "directory" of a "file" in the path, but is specified by [RFC6265 - Section 5.1.4](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.1.4). + +**Signature:** + +```typescript +export declare function defaultPath(path?: Nullable): string; +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +path + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +_(Optional)_ the path portion of the request-uri (excluding the hostname, query, fragment, and so on) + + +
+**Returns:** + +string + +## Remarks + +\#\#\# RFC6265 - Section 5.1.4 + +The user agent MUST use an algorithm equivalent to the following algorithm to compute the default-path of a cookie: + +1. Let uri-path be the path portion of the request-uri if such a portion exists (and empty otherwise). For example, if the request-uri contains just a path (and optional query string), then the uri-path is that path (without the %x3F ("?") character or query string), and if the request-uri contains a full absoluteURI, the uri-path is the path component of that URI. + +2. If the uri-path is empty or if the first character of the uri- path is not a %x2F ("/") character, output %x2F ("/") and skip the remaining steps. + +3. If the uri-path contains no more than one %x2F ("/") character, output %x2F ("/") and skip the remaining step. + +4. Output the characters of the uri-path from the first character up to, but not including, the right-most %x2F ("/"). + +## Example + + +``` +defaultPath('') === '/' +defaultPath('/some-path') === '/' +defaultPath('/some-parent-path/some-path') === '/some-parent-path' +defaultPath('relative-path') === '/' +``` + diff --git a/api/docs/tough-cookie.domainmatch.md b/api/docs/tough-cookie.domainmatch.md new file mode 100644 index 00000000..d5c0d336 --- /dev/null +++ b/api/docs/tough-cookie.domainmatch.md @@ -0,0 +1,110 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [domainMatch](./tough-cookie.domainmatch.md) + +## domainMatch() function + +Answers "does this real domain match the domain in a cookie?". The `domain` is the "current" domain name and the `cookieDomain` is the "cookie" domain name. Matches according to [RFC6265 - Section 5.1.3](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.1.3), but it helps to think of it as a "suffix match". + +**Signature:** + +```typescript +export declare function domainMatch(domain?: Nullable, cookieDomain?: Nullable, canonicalize?: boolean): boolean | undefined; +``` + +## Parameters + + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +domain + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +_(Optional)_ The domain string to test + + +
+ +cookieDomain + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +_(Optional)_ The cookie domain string to match against + + +
+ +canonicalize + + + + +boolean + + + + +_(Optional)_ The canonicalize parameter toggles whether the domain parameters get normalized with canonicalDomain or not + + +
+**Returns:** + +boolean \| undefined + +## Remarks + +\#\#\# 5.1.3. Domain Matching + +A string domain-matches a given domain string if at least one of the following conditions hold: + +- The domain string and the string are identical. (Note that both the domain string and the string will have been canonicalized to lower case at this point.) + +- All of the following conditions hold: + +- The domain string is a suffix of the string. + +- The last character of the string that is not included in the domain string is a %x2E (".") character. + +- The string is a host name (i.e., not an IP address). + +## Example + + +``` +domainMatch('example.com', 'example.com') === true +domainMatch('eXaMpLe.cOm', 'ExAmPlE.CoM') === true +domainMatch('no.ca', 'yes.ca') === false +``` + diff --git a/api/docs/tough-cookie.errorcallback.md b/api/docs/tough-cookie.errorcallback.md new file mode 100644 index 00000000..0ff1a52e --- /dev/null +++ b/api/docs/tough-cookie.errorcallback.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [ErrorCallback](./tough-cookie.errorcallback.md) + +## ErrorCallback interface + +A callback function that only accepts an error. + +**Signature:** + +```typescript +export interface ErrorCallback +``` diff --git a/api/docs/tough-cookie.formatdate.md b/api/docs/tough-cookie.formatdate.md new file mode 100644 index 00000000..459082eb --- /dev/null +++ b/api/docs/tough-cookie.formatdate.md @@ -0,0 +1,60 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [formatDate](./tough-cookie.formatdate.md) + +## formatDate() function + +Format a [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) into the [preferred Internet standard format](https://www.rfc-editor.org/rfc/rfc2616#section-3.3.1) defined in [RFC822](https://www.rfc-editor.org/rfc/rfc822#section-5) and updated in [RFC1123](https://www.rfc-editor.org/rfc/rfc1123#page-55). + +**Signature:** + +```typescript +export declare function formatDate(date: Date): string; +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +date + + + + +Date + + + + +the date value to format + + +
+**Returns:** + +string + +## Example + + +``` +formatDate(new Date(0)) === 'Thu, 01 Jan 1970 00:00:00 GMT` +``` + diff --git a/api/docs/tough-cookie.fromjson.md b/api/docs/tough-cookie.fromjson.md new file mode 100644 index 00000000..43fd7b3b --- /dev/null +++ b/api/docs/tough-cookie.fromjson.md @@ -0,0 +1,57 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [fromJSON](./tough-cookie.fromjson.md) + +## fromJSON() function + +Does the reverse of [Cookie.toJSON()](./tough-cookie.cookie.tojson.md). + +**Signature:** + +```typescript +export declare function fromJSON(str: unknown): Cookie | undefined; +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +str + + + + +unknown + + + + +An unparsed JSON string or a value that has already been parsed as JSON + + +
+**Returns:** + +[Cookie](./tough-cookie.cookie.md) \| undefined + +## Remarks + +Any Date properties (such as .expires, .creation, and .lastAccessed) are parsed via Date.parse, not tough-cookie's parseDate, since ISO timestamps are being handled at this layer. + diff --git a/api/docs/tough-cookie.getcookiesoptions.allpaths.md b/api/docs/tough-cookie.getcookiesoptions.allpaths.md new file mode 100644 index 00000000..fb724fef --- /dev/null +++ b/api/docs/tough-cookie.getcookiesoptions.allpaths.md @@ -0,0 +1,20 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [GetCookiesOptions](./tough-cookie.getcookiesoptions.md) > [allPaths](./tough-cookie.getcookiesoptions.allpaths.md) + +## GetCookiesOptions.allPaths property + +If `true`, do not scope cookies by path. If `false`, then RFC-compliant path scoping will be used. + +**Signature:** + +```typescript +allPaths?: boolean | undefined; +``` + +## Remarks + +- May not be supported by the underlying store (the default [MemoryCookieStore](./tough-cookie.memorycookiestore.md) supports it). + +Defaults to `false` if not provided. + diff --git a/api/docs/tough-cookie.getcookiesoptions.expire.md b/api/docs/tough-cookie.getcookiesoptions.expire.md new file mode 100644 index 00000000..76373aab --- /dev/null +++ b/api/docs/tough-cookie.getcookiesoptions.expire.md @@ -0,0 +1,20 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [GetCookiesOptions](./tough-cookie.getcookiesoptions.md) > [expire](./tough-cookie.getcookiesoptions.expire.md) + +## GetCookiesOptions.expire property + +Perform `expiry-time` checking of cookies and asynchronously remove expired cookies from the store. + +**Signature:** + +```typescript +expire?: boolean | undefined; +``` + +## Remarks + +- Using `false` returns expired cookies and does not remove them from the store which is potentially useful for replaying `Set-Cookie` headers. + +Defaults to `true` if not provided. + diff --git a/api/docs/tough-cookie.getcookiesoptions.http.md b/api/docs/tough-cookie.getcookiesoptions.http.md new file mode 100644 index 00000000..e8c27943 --- /dev/null +++ b/api/docs/tough-cookie.getcookiesoptions.http.md @@ -0,0 +1,15 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [GetCookiesOptions](./tough-cookie.getcookiesoptions.md) > [http](./tough-cookie.getcookiesoptions.http.md) + +## GetCookiesOptions.http property + +Indicates if this is an HTTP or non-HTTP API. Affects HttpOnly cookies. + +Defaults to `true` if not provided. + +**Signature:** + +```typescript +http?: boolean | undefined; +``` diff --git a/api/docs/tough-cookie.getcookiesoptions.md b/api/docs/tough-cookie.getcookiesoptions.md new file mode 100644 index 00000000..ae8d2dbe --- /dev/null +++ b/api/docs/tough-cookie.getcookiesoptions.md @@ -0,0 +1,147 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [GetCookiesOptions](./tough-cookie.getcookiesoptions.md) + +## GetCookiesOptions interface + +Configuration options used when calling `CookieJar.getCookies(...)`. + +**Signature:** + +```typescript +export interface GetCookiesOptions +``` + +## Properties + + + + + + + +
+ +Property + + + + +Modifiers + + + + +Type + + + + +Description + + +
+ +[allPaths?](./tough-cookie.getcookiesoptions.allpaths.md) + + + + + + + +boolean \| undefined + + + + +_(Optional)_ If `true`, do not scope cookies by path. If `false`, then RFC-compliant path scoping will be used. + + +
+ +[expire?](./tough-cookie.getcookiesoptions.expire.md) + + + + + + + +boolean \| undefined + + + + +_(Optional)_ Perform `expiry-time` checking of cookies and asynchronously remove expired cookies from the store. + + +
+ +[http?](./tough-cookie.getcookiesoptions.http.md) + + + + + + + +boolean \| undefined + + + + +_(Optional)_ Indicates if this is an HTTP or non-HTTP API. Affects HttpOnly cookies. + +Defaults to `true` if not provided. + + +
+ +[sameSiteContext?](./tough-cookie.getcookiesoptions.samesitecontext.md) + + + + + + + +'none' \| 'lax' \| 'strict' \| undefined + + + + +_(Optional)_ Set this to 'none', 'lax', or 'strict' to enforce SameSite cookies upon retrieval. + +- `'strict'` - If the request is on the same "site for cookies" (see the RFC draft for more information), pass this option to add a layer of defense against CSRF. + +- `'lax'` - If the request is from another site, but is directly because of navigation by the user, such as, `` or ``, then use `lax`. + +- `'none'` - This indicates a cross-origin request. + +- `undefined` - SameSite is not be enforced! This can be a valid use-case for when CSRF isn't in the threat model of the system being built. + +Defaults to `undefined` if not provided. + + +
+ +[sort?](./tough-cookie.getcookiesoptions.sort.md) + + + + + + + +boolean \| undefined + + + + +_(Optional)_ Flag to indicate if the returned cookies should be sorted or not. + +Defaults to `undefined` if not provided. + + +
diff --git a/api/docs/tough-cookie.getcookiesoptions.samesitecontext.md b/api/docs/tough-cookie.getcookiesoptions.samesitecontext.md new file mode 100644 index 00000000..d28ecf7c --- /dev/null +++ b/api/docs/tough-cookie.getcookiesoptions.samesitecontext.md @@ -0,0 +1,28 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [GetCookiesOptions](./tough-cookie.getcookiesoptions.md) > [sameSiteContext](./tough-cookie.getcookiesoptions.samesitecontext.md) + +## GetCookiesOptions.sameSiteContext property + +Set this to 'none', 'lax', or 'strict' to enforce SameSite cookies upon retrieval. + +- `'strict'` - If the request is on the same "site for cookies" (see the RFC draft for more information), pass this option to add a layer of defense against CSRF. + +- `'lax'` - If the request is from another site, but is directly because of navigation by the user, such as, `` or ``, then use `lax`. + +- `'none'` - This indicates a cross-origin request. + +- `undefined` - SameSite is not be enforced! This can be a valid use-case for when CSRF isn't in the threat model of the system being built. + +Defaults to `undefined` if not provided. + +**Signature:** + +```typescript +sameSiteContext?: 'none' | 'lax' | 'strict' | undefined; +``` + +## Remarks + +- It is highly recommended that you read [RFC6265bis - Section 8.8](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02##section-8.8) which discusses security considerations and defence on SameSite cookies in depth. + diff --git a/api/docs/tough-cookie.getcookiesoptions.sort.md b/api/docs/tough-cookie.getcookiesoptions.sort.md new file mode 100644 index 00000000..a8e956e4 --- /dev/null +++ b/api/docs/tough-cookie.getcookiesoptions.sort.md @@ -0,0 +1,15 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [GetCookiesOptions](./tough-cookie.getcookiesoptions.md) > [sort](./tough-cookie.getcookiesoptions.sort.md) + +## GetCookiesOptions.sort property + +Flag to indicate if the returned cookies should be sorted or not. + +Defaults to `undefined` if not provided. + +**Signature:** + +```typescript +sort?: boolean | undefined; +``` diff --git a/api/docs/tough-cookie.getpublicsuffix.md b/api/docs/tough-cookie.getpublicsuffix.md new file mode 100644 index 00000000..8fc01f05 --- /dev/null +++ b/api/docs/tough-cookie.getpublicsuffix.md @@ -0,0 +1,81 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [getPublicSuffix](./tough-cookie.getpublicsuffix.md) + +## getPublicSuffix() function + +Returns the public suffix of this hostname. The public suffix is the shortest domain name upon which a cookie can be set. + +**Signature:** + +```typescript +export declare function getPublicSuffix(domain: string, options?: GetPublicSuffixOptions): string | undefined; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +domain + + + + +string + + + + +the domain attribute of a cookie + + +
+ +options + + + + +[GetPublicSuffixOptions](./tough-cookie.getpublicsuffixoptions.md) + + + + +_(Optional)_ optional configuration for controlling how the public suffix is determined + + +
+**Returns:** + +string \| undefined + +## Remarks + +A "public suffix" is a domain that is controlled by a public registry, such as "com", "co.uk", and "pvt.k12.wy.us". This step is essential for preventing attacker.com from disrupting the integrity of example.com by setting a cookie with a Domain attribute of "com". Unfortunately, the set of public suffixes (also known as "registry controlled domains") changes over time. If feasible, user agents SHOULD use an up-to-date public suffix list, such as the one maintained by the Mozilla project at http://publicsuffix.org/. (See [RFC6265 - Section 5.3](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.3)) + +## Example + + +``` +getPublicSuffix('www.example.com') === 'example.com' +getPublicSuffix('www.subdomain.example.com') === 'example.com' +``` + diff --git a/api/docs/tough-cookie.getpublicsuffixoptions.allowspecialusedomain.md b/api/docs/tough-cookie.getpublicsuffixoptions.allowspecialusedomain.md new file mode 100644 index 00000000..4a5b25bd --- /dev/null +++ b/api/docs/tough-cookie.getpublicsuffixoptions.allowspecialusedomain.md @@ -0,0 +1,25 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [GetPublicSuffixOptions](./tough-cookie.getpublicsuffixoptions.md) > [allowSpecialUseDomain](./tough-cookie.getpublicsuffixoptions.allowspecialusedomain.md) + +## GetPublicSuffixOptions.allowSpecialUseDomain property + +If set to `true` then the following [Special Use Domains](https://www.rfc-editor.org/rfc/rfc6761.html) will be treated as if they were valid public suffixes ('local', 'example', 'invalid', 'localhost', 'test'). + +**Signature:** + +```typescript +allowSpecialUseDomain?: boolean | undefined; +``` + +## Remarks + +In testing scenarios it's common to configure the cookie store with so that `http://localhost` can be used as a domain: + +```json +{ + allowSpecialUseDomain: true, + rejectPublicSuffixes: false +} +``` + diff --git a/api/docs/tough-cookie.getpublicsuffixoptions.ignoreerror.md b/api/docs/tough-cookie.getpublicsuffixoptions.ignoreerror.md new file mode 100644 index 00000000..4d8e1a89 --- /dev/null +++ b/api/docs/tough-cookie.getpublicsuffixoptions.ignoreerror.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [GetPublicSuffixOptions](./tough-cookie.getpublicsuffixoptions.md) > [ignoreError](./tough-cookie.getpublicsuffixoptions.ignoreerror.md) + +## GetPublicSuffixOptions.ignoreError property + +If set to `true` then any errors that occur while executing [getPublicSuffix()](./tough-cookie.getpublicsuffix.md) will be silently ignored. + +**Signature:** + +```typescript +ignoreError?: boolean | undefined; +``` diff --git a/api/docs/tough-cookie.getpublicsuffixoptions.md b/api/docs/tough-cookie.getpublicsuffixoptions.md new file mode 100644 index 00000000..bc32849d --- /dev/null +++ b/api/docs/tough-cookie.getpublicsuffixoptions.md @@ -0,0 +1,76 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [GetPublicSuffixOptions](./tough-cookie.getpublicsuffixoptions.md) + +## GetPublicSuffixOptions interface + +Options for configuring how [getPublicSuffix()](./tough-cookie.getpublicsuffix.md) behaves. + +**Signature:** + +```typescript +export interface GetPublicSuffixOptions +``` + +## Properties + + + + +
+ +Property + + + + +Modifiers + + + + +Type + + + + +Description + + +
+ +[allowSpecialUseDomain?](./tough-cookie.getpublicsuffixoptions.allowspecialusedomain.md) + + + + + + + +boolean \| undefined + + + + +_(Optional)_ If set to `true` then the following [Special Use Domains](https://www.rfc-editor.org/rfc/rfc6761.html) will be treated as if they were valid public suffixes ('local', 'example', 'invalid', 'localhost', 'test'). + + +
+ +[ignoreError?](./tough-cookie.getpublicsuffixoptions.ignoreerror.md) + + + + + + + +boolean \| undefined + + + + +_(Optional)_ If set to `true` then any errors that occur while executing [getPublicSuffix()](./tough-cookie.getpublicsuffix.md) will be silently ignored. + + +
diff --git a/api/docs/tough-cookie.md b/api/docs/tough-cookie.md new file mode 100644 index 00000000..b35f4dce --- /dev/null +++ b/api/docs/tough-cookie.md @@ -0,0 +1,430 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) + +## tough-cookie package + +## Classes + + + + + + + +
+ +Class + + + + +Description + + +
+ +[Cookie](./tough-cookie.cookie.md) + + + + +An HTTP cookie (web cookie, browser cookie) is a small piece of data that a server sends to a user's web browser. It is defined in [RFC6265](https://www.rfc-editor.org/rfc/rfc6265.html). + + +
+ +[CookieJar](./tough-cookie.cookiejar.md) + + + + +A CookieJar is for storage and retrieval of [Cookie](./tough-cookie.cookie.md) objects as defined in [RFC6265 - Section 5.3](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.3). + +It also supports a pluggable persistence layer via [Store](./tough-cookie.store.md). + + +
+ +[MemoryCookieStore](./tough-cookie.memorycookiestore.md) + + + + +An in-memory [Store](./tough-cookie.store.md) implementation for [CookieJar](./tough-cookie.cookiejar.md). This is the default implementation used by [CookieJar](./tough-cookie.cookiejar.md) and supports both async and sync operations. Also supports serialization, getAllCookies, and removeAllCookies. + + +
+ +[ParameterError](./tough-cookie.parametererror.md) + + + + +Represents a validation error. + + +
+ +[Store](./tough-cookie.store.md) + + + + +Base class for [CookieJar](./tough-cookie.cookiejar.md) stores. + +The storage model for each [CookieJar](./tough-cookie.cookiejar.md) instance can be replaced with a custom implementation. The default is [MemoryCookieStore](./tough-cookie.memorycookiestore.md). + + +
+ +## Functions + + + + + + + + + + + + + + +
+ +Function + + + + +Description + + +
+ +[canonicalDomain(domainName)](./tough-cookie.canonicaldomain.md) + + + + +Transforms a domain name into a canonical domain name. The canonical domain name is a domain name that has been trimmed, lowercased, stripped of leading dot, and optionally punycode-encoded ([Section 5.1.2 of RFC 6265](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.1.2)). For the most part, this function is idempotent (calling the function with the output from a previous call returns the same output). + + +
+ +[cookieCompare(a, b)](./tough-cookie.cookiecompare.md) + + + + +A comparison function that can be used with [Array.sort()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort), which orders a list of cookies into the recommended order given in Step 2 of [RFC6265 - Section 5.4](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.4). + +The sort algorithm is, in order of precedence: + +- Longest [Cookie.path](./tough-cookie.cookie.path.md) + +- Oldest [Cookie.creation](./tough-cookie.cookie.creation.md) (which has a 1-ms precision, same as Date) + +- Lowest [Cookie.creationIndex](./tough-cookie.cookie.creationindex.md) (to get beyond the 1-ms precision) + + +
+ +[defaultPath(path)](./tough-cookie.defaultpath.md) + + + + +Given a current request/response path, gives the path appropriate for storing in a cookie. This is basically the "directory" of a "file" in the path, but is specified by [RFC6265 - Section 5.1.4](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.1.4). + + +
+ +[domainMatch(domain, cookieDomain, canonicalize)](./tough-cookie.domainmatch.md) + + + + +Answers "does this real domain match the domain in a cookie?". The `domain` is the "current" domain name and the `cookieDomain` is the "cookie" domain name. Matches according to [RFC6265 - Section 5.1.3](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.1.3), but it helps to think of it as a "suffix match". + + +
+ +[formatDate(date)](./tough-cookie.formatdate.md) + + + + +Format a [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) into the [preferred Internet standard format](https://www.rfc-editor.org/rfc/rfc2616#section-3.3.1) defined in [RFC822](https://www.rfc-editor.org/rfc/rfc822#section-5) and updated in [RFC1123](https://www.rfc-editor.org/rfc/rfc1123#page-55). + + +
+ +[fromJSON(str)](./tough-cookie.fromjson.md) + + + + +Does the reverse of [Cookie.toJSON()](./tough-cookie.cookie.tojson.md). + + +
+ +[getPublicSuffix(domain, options)](./tough-cookie.getpublicsuffix.md) + + + + +Returns the public suffix of this hostname. The public suffix is the shortest domain name upon which a cookie can be set. + + +
+ +[parse(str, options)](./tough-cookie.parse.md) + + + + +Parses a string into a Cookie object. + + +
+ +[parseDate(cookieDate)](./tough-cookie.parsedate.md) + + + + +Parse a cookie date string into a [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date). Parses according to [RFC6265 - Section 5.1.1](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.1.1), not [Date.parse()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse). + + +
+ +[pathMatch(reqPath, cookiePath)](./tough-cookie.pathmatch.md) + + + + +Answers "does the request-path path-match a given cookie-path?" as per [RFC6265 Section 5.1.4](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.1.4). This is essentially a prefix-match where cookiePath is a prefix of reqPath. + + +
+ +[permuteDomain(domain, allowSpecialUseDomain)](./tough-cookie.permutedomain.md) + + + + +Generates the permutation of all possible values that [domainMatch()](./tough-cookie.domainmatch.md) the given `domain` parameter. The array is in shortest-to-longest order. Useful when building custom [Store](./tough-cookie.store.md) implementations. + + +
+ +[permutePath(path)](./tough-cookie.permutepath.md) + + + + +Generates the permutation of all possible values that [pathMatch()](./tough-cookie.pathmatch.md) the `path` parameter. The array is in longest-to-shortest order. Useful when building custom [Store](./tough-cookie.store.md) implementations. + + +
+ +## Interfaces + + + + + + + + + + + +
+ +Interface + + + + +Description + + +
+ +[Callback](./tough-cookie.callback.md) + + + + +A callback function that accepts an error or a result. + + +
+ +[CreateCookieJarOptions](./tough-cookie.createcookiejaroptions.md) + + + + +Configuration settings to be used with a [CookieJar](./tough-cookie.cookiejar.md). + + +
+ +[CreateCookieOptions](./tough-cookie.createcookieoptions.md) + + + + +Configurable values that can be set when creating a [Cookie](./tough-cookie.cookie.md). + + +
+ +[ErrorCallback](./tough-cookie.errorcallback.md) + + + + +A callback function that only accepts an error. + + +
+ +[GetCookiesOptions](./tough-cookie.getcookiesoptions.md) + + + + +Configuration options used when calling `CookieJar.getCookies(...)`. + + +
+ +[GetPublicSuffixOptions](./tough-cookie.getpublicsuffixoptions.md) + + + + +Options for configuring how [getPublicSuffix()](./tough-cookie.getpublicsuffix.md) behaves. + + +
+ +[ParseCookieOptions](./tough-cookie.parsecookieoptions.md) + + + + +Optional configuration to be used when parsing cookies. + + +
+ +[SerializedCookieJar](./tough-cookie.serializedcookiejar.md) + + + + +A JSON representation of a [CookieJar](./tough-cookie.cookiejar.md). + + +
+ +[SetCookieOptions](./tough-cookie.setcookieoptions.md) + + + + +Configuration options used when calling `CookieJar.setCookie(...)` + + +
+ +## Variables + + + + +
+ +Variable + + + + +Description + + +
+ +[PrefixSecurityEnum](./tough-cookie.prefixsecurityenum.md) + + + + +Cookie prefixes are a way to indicate that a given cookie was set with a set of attributes simply by inspecting the first few characters of the cookie's name. These are defined in [RFC6265bis - Section 4.1.3](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-13#section-4.1.3). + +The following values can be used to configure how a [CookieJar](./tough-cookie.cookiejar.md) enforces attribute restrictions for Cookie prefixes: + +- `silent` - Enable cookie prefix checking but silently ignores the cookie if conditions are not met. This is the default configuration for a [CookieJar](./tough-cookie.cookiejar.md). + +- `strict` - Enables cookie prefix checking and will raise an error if conditions are not met. + +- `unsafe-disabled` - Disables cookie prefix checking. + + +
+ +[version](./tough-cookie.version.md) + + + + +The version of `tough-cookie` + + +
+ +## Type Aliases + + + + +
+ +Type Alias + + + + +Description + + +
+ +[Nullable](./tough-cookie.nullable.md) + + + + +The inverse of NonNullable. + + +
+ +[SerializedCookie](./tough-cookie.serializedcookie.md) + + + + +A JSON object that is created when [Cookie.toJSON()](./tough-cookie.cookie.tojson.md) is called. This object will contain the properties defined in [Cookie.serializableProperties](./tough-cookie.cookie.serializableproperties.md). + + +
diff --git a/api/docs/tough-cookie.memorycookiestore._constructor_.md b/api/docs/tough-cookie.memorycookiestore._constructor_.md new file mode 100644 index 00000000..f01d6dd3 --- /dev/null +++ b/api/docs/tough-cookie.memorycookiestore._constructor_.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [MemoryCookieStore](./tough-cookie.memorycookiestore.md) > [(constructor)](./tough-cookie.memorycookiestore._constructor_.md) + +## MemoryCookieStore.(constructor) + +Create a new [MemoryCookieStore](./tough-cookie.memorycookiestore.md). + +**Signature:** + +```typescript +constructor(); +``` diff --git a/api/docs/tough-cookie.memorycookiestore.findcookie.md b/api/docs/tough-cookie.memorycookiestore.findcookie.md new file mode 100644 index 00000000..e445fcc0 --- /dev/null +++ b/api/docs/tough-cookie.memorycookiestore.findcookie.md @@ -0,0 +1,85 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [MemoryCookieStore](./tough-cookie.memorycookiestore.md) > [findCookie](./tough-cookie.memorycookiestore.findcookie.md) + +## MemoryCookieStore.findCookie() method + +Retrieve a [Cookie](./tough-cookie.cookie.md) with the given `domain`, `path`, and `key` (`name`). The RFC maintains that exactly one of these cookies should exist in a store. If the store is using versioning, this means that the latest or newest such cookie should be returned. + +**Signature:** + +```typescript +findCookie(domain: Nullable, path: Nullable, key: Nullable): Promise; +``` + +## Parameters + + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +domain + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +The cookie domain to match against. + + +
+ +path + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +The cookie path to match against. + + +
+ +key + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +The cookie name to match against. + + +
+**Returns:** + +Promise<[Cookie](./tough-cookie.cookie.md) \| undefined> + diff --git a/api/docs/tough-cookie.memorycookiestore.findcookie_1.md b/api/docs/tough-cookie.memorycookiestore.findcookie_1.md new file mode 100644 index 00000000..754e6348 --- /dev/null +++ b/api/docs/tough-cookie.memorycookiestore.findcookie_1.md @@ -0,0 +1,103 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [MemoryCookieStore](./tough-cookie.memorycookiestore.md) > [findCookie](./tough-cookie.memorycookiestore.findcookie_1.md) + +## MemoryCookieStore.findCookie() method + +Retrieve a [Cookie](./tough-cookie.cookie.md) with the given `domain`, `path`, and `key` (`name`). The RFC maintains that exactly one of these cookies should exist in a store. If the store is using versioning, this means that the latest or newest such cookie should be returned. + +Callback takes an error and the resulting Cookie object. If no cookie is found then null MUST be passed instead (that is, not an error). + +**Signature:** + +```typescript +findCookie(domain: Nullable, path: Nullable, key: Nullable, callback: Callback): void; +``` + +## Parameters + + + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +domain + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +The cookie domain to match against. + + +
+ +path + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +The cookie path to match against. + + +
+ +key + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +The cookie name to match against. + + +
+ +callback + + + + +[Callback](./tough-cookie.callback.md)<[Cookie](./tough-cookie.cookie.md) \| undefined> + + + + +A function to call with either the found cookie or an error. + + +
+**Returns:** + +void + diff --git a/api/docs/tough-cookie.memorycookiestore.findcookies.md b/api/docs/tough-cookie.memorycookiestore.findcookies.md new file mode 100644 index 00000000..cd36edda --- /dev/null +++ b/api/docs/tough-cookie.memorycookiestore.findcookies.md @@ -0,0 +1,93 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [MemoryCookieStore](./tough-cookie.memorycookiestore.md) > [findCookies](./tough-cookie.memorycookiestore.findcookies.md) + +## MemoryCookieStore.findCookies() method + +Locates all [Cookie](./tough-cookie.cookie.md) values matching the given `domain` and `path`. + +The resulting list is checked for applicability to the current request according to the RFC (`domain-match`, `path-match`, `http-only-flag`, `secure-flag`, `expiry`, and so on), so it's OK to use an optimistic search algorithm when implementing this method. However, the search algorithm used SHOULD try to find cookies that [domainMatch()](./tough-cookie.domainmatch.md) the `domain` and [pathMatch()](./tough-cookie.pathmatch.md) the `path` in order to limit the amount of checking that needs to be done. + +**Signature:** + +```typescript +findCookies(domain: string, path: string, allowSpecialUseDomain?: boolean): Promise; +``` + +## Parameters + + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +domain + + + + +string + + + + +The cookie domain to match against. + + +
+ +path + + + + +string + + + + +The cookie path to match against. + + +
+ +allowSpecialUseDomain + + + + +boolean + + + + +_(Optional)_ If `true` then special-use domain suffixes, will be allowed in matches. Defaults to `false`. + + +
+**Returns:** + +Promise<[Cookie](./tough-cookie.cookie.md)\[\]> + +## Remarks + +- As of version `0.9.12`, the `allPaths` option to cookiejar.getCookies() above causes the path here to be `null`. + +- If the `path` is `null`, `path-matching` MUST NOT be performed (that is, `domain-matching` only). + diff --git a/api/docs/tough-cookie.memorycookiestore.findcookies_1.md b/api/docs/tough-cookie.memorycookiestore.findcookies_1.md new file mode 100644 index 00000000..1d961a04 --- /dev/null +++ b/api/docs/tough-cookie.memorycookiestore.findcookies_1.md @@ -0,0 +1,109 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [MemoryCookieStore](./tough-cookie.memorycookiestore.md) > [findCookies](./tough-cookie.memorycookiestore.findcookies_1.md) + +## MemoryCookieStore.findCookies() method + +Locates all [Cookie](./tough-cookie.cookie.md) values matching the given `domain` and `path`. + +The resulting list is checked for applicability to the current request according to the RFC (`domain-match`, `path-match`, `http-only-flag`, `secure-flag`, `expiry`, and so on), so it's OK to use an optimistic search algorithm when implementing this method. However, the search algorithm used SHOULD try to find cookies that [domainMatch()](./tough-cookie.domainmatch.md) the `domain` and [pathMatch()](./tough-cookie.pathmatch.md) the `path` in order to limit the amount of checking that needs to be done. + +**Signature:** + +```typescript +findCookies(domain: string, path: string, allowSpecialUseDomain?: boolean, callback?: Callback): void; +``` + +## Parameters + + + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +domain + + + + +string + + + + +The cookie domain to match against. + + +
+ +path + + + + +string + + + + +The cookie path to match against. + + +
+ +allowSpecialUseDomain + + + + +boolean + + + + +_(Optional)_ If `true` then special-use domain suffixes, will be allowed in matches. Defaults to `false`. + + +
+ +callback + + + + +[Callback](./tough-cookie.callback.md)<[Cookie](./tough-cookie.cookie.md)\[\]> + + + + +_(Optional)_ A function to call with either the found cookies or an error. + + +
+**Returns:** + +void + +## Remarks + +- As of version `0.9.12`, the `allPaths` option to cookiejar.getCookies() above causes the path here to be `null`. + +- If the `path` is `null`, `path-matching` MUST NOT be performed (that is, `domain-matching` only). + diff --git a/api/docs/tough-cookie.memorycookiestore.getallcookies.md b/api/docs/tough-cookie.memorycookiestore.getallcookies.md new file mode 100644 index 00000000..f423d653 --- /dev/null +++ b/api/docs/tough-cookie.memorycookiestore.getallcookies.md @@ -0,0 +1,21 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [MemoryCookieStore](./tough-cookie.memorycookiestore.md) > [getAllCookies](./tough-cookie.memorycookiestore.getallcookies.md) + +## MemoryCookieStore.getAllCookies() method + +Gets all the cookies in the store. + +**Signature:** + +```typescript +getAllCookies(): Promise; +``` +**Returns:** + +Promise<[Cookie](./tough-cookie.cookie.md)\[\]> + +## Remarks + +- Cookies SHOULD be returned in creation order to preserve sorting via [cookieCompare()](./tough-cookie.cookiecompare.md). + diff --git a/api/docs/tough-cookie.memorycookiestore.getallcookies_1.md b/api/docs/tough-cookie.memorycookiestore.getallcookies_1.md new file mode 100644 index 00000000..9ccf131c --- /dev/null +++ b/api/docs/tough-cookie.memorycookiestore.getallcookies_1.md @@ -0,0 +1,57 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [MemoryCookieStore](./tough-cookie.memorycookiestore.md) > [getAllCookies](./tough-cookie.memorycookiestore.getallcookies_1.md) + +## MemoryCookieStore.getAllCookies() method + +Gets all the cookies in the store. + +**Signature:** + +```typescript +getAllCookies(callback: Callback): void; +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +callback + + + + +[Callback](./tough-cookie.callback.md)<[Cookie](./tough-cookie.cookie.md)\[\]> + + + + +A function to call when all the cookies have been retrieved or an error occurs. + + +
+**Returns:** + +void + +## Remarks + +- Cookies SHOULD be returned in creation order to preserve sorting via [cookieCompare()](./tough-cookie.cookiecompare.md). + diff --git a/api/docs/tough-cookie.memorycookiestore.md b/api/docs/tough-cookie.memorycookiestore.md new file mode 100644 index 00000000..98a00ed0 --- /dev/null +++ b/api/docs/tough-cookie.memorycookiestore.md @@ -0,0 +1,342 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [MemoryCookieStore](./tough-cookie.memorycookiestore.md) + +## MemoryCookieStore class + +An in-memory [Store](./tough-cookie.store.md) implementation for [CookieJar](./tough-cookie.cookiejar.md). This is the default implementation used by [CookieJar](./tough-cookie.cookiejar.md) and supports both async and sync operations. Also supports serialization, getAllCookies, and removeAllCookies. + +**Signature:** + +```typescript +export declare class MemoryCookieStore extends Store +``` +**Extends:** [Store](./tough-cookie.store.md) + +## Constructors + + + +
+ +Constructor + + + + +Modifiers + + + + +Description + + +
+ +[(constructor)()](./tough-cookie.memorycookiestore._constructor_.md) + + + + + + + +Create a new [MemoryCookieStore](./tough-cookie.memorycookiestore.md). + + +
+ +## Properties + + + +
+ +Property + + + + +Modifiers + + + + +Type + + + + +Description + + +
+ +[synchronous](./tough-cookie.memorycookiestore.synchronous.md) + + + + + + + +boolean + + + + +This value is `true` since [MemoryCookieStore](./tough-cookie.memorycookiestore.md) implements synchronous functionality. + + +
+ +## Methods + + + + + + + + + + + + + + + + + + +
+ +Method + + + + +Modifiers + + + + +Description + + +
+ +[findCookie(domain, path, key)](./tough-cookie.memorycookiestore.findcookie.md) + + + + + + + +Retrieve a [Cookie](./tough-cookie.cookie.md) with the given `domain`, `path`, and `key` (`name`). The RFC maintains that exactly one of these cookies should exist in a store. If the store is using versioning, this means that the latest or newest such cookie should be returned. + + +
+ +[findCookie(domain, path, key, callback)](./tough-cookie.memorycookiestore.findcookie_1.md) + + + + + + + +Retrieve a [Cookie](./tough-cookie.cookie.md) with the given `domain`, `path`, and `key` (`name`). The RFC maintains that exactly one of these cookies should exist in a store. If the store is using versioning, this means that the latest or newest such cookie should be returned. + +Callback takes an error and the resulting Cookie object. If no cookie is found then null MUST be passed instead (that is, not an error). + + +
+ +[findCookies(domain, path, allowSpecialUseDomain)](./tough-cookie.memorycookiestore.findcookies.md) + + + + + + + +Locates all [Cookie](./tough-cookie.cookie.md) values matching the given `domain` and `path`. + +The resulting list is checked for applicability to the current request according to the RFC (`domain-match`, `path-match`, `http-only-flag`, `secure-flag`, `expiry`, and so on), so it's OK to use an optimistic search algorithm when implementing this method. However, the search algorithm used SHOULD try to find cookies that [domainMatch()](./tough-cookie.domainmatch.md) the `domain` and [pathMatch()](./tough-cookie.pathmatch.md) the `path` in order to limit the amount of checking that needs to be done. + + +
+ +[findCookies(domain, path, allowSpecialUseDomain, callback)](./tough-cookie.memorycookiestore.findcookies_1.md) + + + + + + + +Locates all [Cookie](./tough-cookie.cookie.md) values matching the given `domain` and `path`. + +The resulting list is checked for applicability to the current request according to the RFC (`domain-match`, `path-match`, `http-only-flag`, `secure-flag`, `expiry`, and so on), so it's OK to use an optimistic search algorithm when implementing this method. However, the search algorithm used SHOULD try to find cookies that [domainMatch()](./tough-cookie.domainmatch.md) the `domain` and [pathMatch()](./tough-cookie.pathmatch.md) the `path` in order to limit the amount of checking that needs to be done. + + +
+ +[getAllCookies()](./tough-cookie.memorycookiestore.getallcookies.md) + + + + + + + +Gets all the cookies in the store. + + +
+ +[getAllCookies(callback)](./tough-cookie.memorycookiestore.getallcookies_1.md) + + + + + + + +Gets all the cookies in the store. + + +
+ +[putCookie(cookie)](./tough-cookie.memorycookiestore.putcookie.md) + + + + + + + +Adds a new [Cookie](./tough-cookie.cookie.md) to the store. The implementation SHOULD replace any existing cookie with the same `domain`, `path`, and `key` properties. + + +
+ +[putCookie(cookie, callback)](./tough-cookie.memorycookiestore.putcookie_1.md) + + + + + + + +Adds a new [Cookie](./tough-cookie.cookie.md) to the store. The implementation SHOULD replace any existing cookie with the same `domain`, `path`, and `key` properties. + + +
+ +[removeAllCookies()](./tough-cookie.memorycookiestore.removeallcookies.md) + + + + + + + +Removes all cookies from the store. + + +
+ +[removeAllCookies(callback)](./tough-cookie.memorycookiestore.removeallcookies_1.md) + + + + + + + +Removes all cookies from the store. + + +
+ +[removeCookie(domain, path, key)](./tough-cookie.memorycookiestore.removecookie.md) + + + + + + + +Remove a cookie from the store (see notes on `findCookie` about the uniqueness constraint). + + +
+ +[removeCookie(domain, path, key, callback)](./tough-cookie.memorycookiestore.removecookie_1.md) + + + + + + + +Remove a cookie from the store (see notes on `findCookie` about the uniqueness constraint). + + +
+ +[removeCookies(domain, path)](./tough-cookie.memorycookiestore.removecookies.md) + + + + + + + +Removes matching cookies from the store. The `path` parameter is optional and if missing, means all paths in a domain should be removed. + + +
+ +[removeCookies(domain, path, callback)](./tough-cookie.memorycookiestore.removecookies_1.md) + + + + + + + +Removes matching cookies from the store. The `path` parameter is optional and if missing, means all paths in a domain should be removed. + + +
+ +[updateCookie(oldCookie, newCookie)](./tough-cookie.memorycookiestore.updatecookie.md) + + + + + + + +Update an existing [Cookie](./tough-cookie.cookie.md). The implementation MUST update the `value` for a cookie with the same `domain`, `path`, and `key`. The implementation SHOULD check that the old value in the store is equivalent to oldCookie - how the conflict is resolved is up to the store. + + +
+ +[updateCookie(oldCookie, newCookie, callback)](./tough-cookie.memorycookiestore.updatecookie_1.md) + + + + + + + +Update an existing [Cookie](./tough-cookie.cookie.md). The implementation MUST update the `value` for a cookie with the same `domain`, `path`, and `key`. The implementation SHOULD check that the old value in the store is equivalent to oldCookie - how the conflict is resolved is up to the store. + + +
diff --git a/api/docs/tough-cookie.memorycookiestore.putcookie.md b/api/docs/tough-cookie.memorycookiestore.putcookie.md new file mode 100644 index 00000000..84180478 --- /dev/null +++ b/api/docs/tough-cookie.memorycookiestore.putcookie.md @@ -0,0 +1,59 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [MemoryCookieStore](./tough-cookie.memorycookiestore.md) > [putCookie](./tough-cookie.memorycookiestore.putcookie.md) + +## MemoryCookieStore.putCookie() method + +Adds a new [Cookie](./tough-cookie.cookie.md) to the store. The implementation SHOULD replace any existing cookie with the same `domain`, `path`, and `key` properties. + +**Signature:** + +```typescript +putCookie(cookie: Cookie): Promise; +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +cookie + + + + +[Cookie](./tough-cookie.cookie.md) + + + + +The cookie to store. + + +
+**Returns:** + +Promise<void> + +## Remarks + +- Depending on the nature of the implementation, it's possible that between the call to `fetchCookie` and `putCookie` that a duplicate `putCookie` can occur. + +- The [Cookie](./tough-cookie.cookie.md) object MUST NOT be modified; as the caller has already updated the `creation` and `lastAccessed` properties. + diff --git a/api/docs/tough-cookie.memorycookiestore.putcookie_1.md b/api/docs/tough-cookie.memorycookiestore.putcookie_1.md new file mode 100644 index 00000000..e14b0518 --- /dev/null +++ b/api/docs/tough-cookie.memorycookiestore.putcookie_1.md @@ -0,0 +1,75 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [MemoryCookieStore](./tough-cookie.memorycookiestore.md) > [putCookie](./tough-cookie.memorycookiestore.putcookie_1.md) + +## MemoryCookieStore.putCookie() method + +Adds a new [Cookie](./tough-cookie.cookie.md) to the store. The implementation SHOULD replace any existing cookie with the same `domain`, `path`, and `key` properties. + +**Signature:** + +```typescript +putCookie(cookie: Cookie, callback: ErrorCallback): void; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +cookie + + + + +[Cookie](./tough-cookie.cookie.md) + + + + +The cookie to store. + + +
+ +callback + + + + +[ErrorCallback](./tough-cookie.errorcallback.md) + + + + +A function to call when the cookie has been stored or an error has occurred. + + +
+**Returns:** + +void + +## Remarks + +- Depending on the nature of the implementation, it's possible that between the call to `fetchCookie` and `putCookie` that a duplicate `putCookie` can occur. + +- The [Cookie](./tough-cookie.cookie.md) object MUST NOT be modified; as the caller has already updated the `creation` and `lastAccessed` properties. + diff --git a/api/docs/tough-cookie.memorycookiestore.removeallcookies.md b/api/docs/tough-cookie.memorycookiestore.removeallcookies.md new file mode 100644 index 00000000..aea1862a --- /dev/null +++ b/api/docs/tough-cookie.memorycookiestore.removeallcookies.md @@ -0,0 +1,17 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [MemoryCookieStore](./tough-cookie.memorycookiestore.md) > [removeAllCookies](./tough-cookie.memorycookiestore.removeallcookies.md) + +## MemoryCookieStore.removeAllCookies() method + +Removes all cookies from the store. + +**Signature:** + +```typescript +removeAllCookies(): Promise; +``` +**Returns:** + +Promise<void> + diff --git a/api/docs/tough-cookie.memorycookiestore.removeallcookies_1.md b/api/docs/tough-cookie.memorycookiestore.removeallcookies_1.md new file mode 100644 index 00000000..59aace47 --- /dev/null +++ b/api/docs/tough-cookie.memorycookiestore.removeallcookies_1.md @@ -0,0 +1,53 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [MemoryCookieStore](./tough-cookie.memorycookiestore.md) > [removeAllCookies](./tough-cookie.memorycookiestore.removeallcookies_1.md) + +## MemoryCookieStore.removeAllCookies() method + +Removes all cookies from the store. + +**Signature:** + +```typescript +removeAllCookies(callback: ErrorCallback): void; +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +callback + + + + +[ErrorCallback](./tough-cookie.errorcallback.md) + + + + +A function to call when all the cookies have been removed or an error occurs. + + +
+**Returns:** + +void + diff --git a/api/docs/tough-cookie.memorycookiestore.removecookie.md b/api/docs/tough-cookie.memorycookiestore.removecookie.md new file mode 100644 index 00000000..4389dba1 --- /dev/null +++ b/api/docs/tough-cookie.memorycookiestore.removecookie.md @@ -0,0 +1,85 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [MemoryCookieStore](./tough-cookie.memorycookiestore.md) > [removeCookie](./tough-cookie.memorycookiestore.removecookie.md) + +## MemoryCookieStore.removeCookie() method + +Remove a cookie from the store (see notes on `findCookie` about the uniqueness constraint). + +**Signature:** + +```typescript +removeCookie(domain: string, path: string, key: string): Promise; +``` + +## Parameters + + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +domain + + + + +string + + + + +The cookie domain to match against. + + +
+ +path + + + + +string + + + + +The cookie path to match against. + + +
+ +key + + + + +string + + + + +The cookie name to match against. + + +
+**Returns:** + +Promise<void> + diff --git a/api/docs/tough-cookie.memorycookiestore.removecookie_1.md b/api/docs/tough-cookie.memorycookiestore.removecookie_1.md new file mode 100644 index 00000000..7bf1aa27 --- /dev/null +++ b/api/docs/tough-cookie.memorycookiestore.removecookie_1.md @@ -0,0 +1,101 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [MemoryCookieStore](./tough-cookie.memorycookiestore.md) > [removeCookie](./tough-cookie.memorycookiestore.removecookie_1.md) + +## MemoryCookieStore.removeCookie() method + +Remove a cookie from the store (see notes on `findCookie` about the uniqueness constraint). + +**Signature:** + +```typescript +removeCookie(domain: string, path: string, key: string, callback: ErrorCallback): void; +``` + +## Parameters + + + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +domain + + + + +string + + + + +The cookie domain to match against. + + +
+ +path + + + + +string + + + + +The cookie path to match against. + + +
+ +key + + + + +string + + + + +The cookie name to match against. + + +
+ +callback + + + + +[ErrorCallback](./tough-cookie.errorcallback.md) + + + + +A function to call when the cookie has been removed or an error occurs. + + +
+**Returns:** + +void + diff --git a/api/docs/tough-cookie.memorycookiestore.removecookies.md b/api/docs/tough-cookie.memorycookiestore.removecookies.md new file mode 100644 index 00000000..e99e48fc --- /dev/null +++ b/api/docs/tough-cookie.memorycookiestore.removecookies.md @@ -0,0 +1,69 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [MemoryCookieStore](./tough-cookie.memorycookiestore.md) > [removeCookies](./tough-cookie.memorycookiestore.removecookies.md) + +## MemoryCookieStore.removeCookies() method + +Removes matching cookies from the store. The `path` parameter is optional and if missing, means all paths in a domain should be removed. + +**Signature:** + +```typescript +removeCookies(domain: string, path: string): Promise; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +domain + + + + +string + + + + +The cookie domain to match against. + + +
+ +path + + + + +string + + + + +The cookie path to match against. + + +
+**Returns:** + +Promise<void> + diff --git a/api/docs/tough-cookie.memorycookiestore.removecookies_1.md b/api/docs/tough-cookie.memorycookiestore.removecookies_1.md new file mode 100644 index 00000000..f83e1aab --- /dev/null +++ b/api/docs/tough-cookie.memorycookiestore.removecookies_1.md @@ -0,0 +1,85 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [MemoryCookieStore](./tough-cookie.memorycookiestore.md) > [removeCookies](./tough-cookie.memorycookiestore.removecookies_1.md) + +## MemoryCookieStore.removeCookies() method + +Removes matching cookies from the store. The `path` parameter is optional and if missing, means all paths in a domain should be removed. + +**Signature:** + +```typescript +removeCookies(domain: string, path: string, callback: ErrorCallback): void; +``` + +## Parameters + + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +domain + + + + +string + + + + +The cookie domain to match against. + + +
+ +path + + + + +string + + + + +The cookie path to match against. + + +
+ +callback + + + + +[ErrorCallback](./tough-cookie.errorcallback.md) + + + + +A function to call when the cookies have been removed or an error occurs. + + +
+**Returns:** + +void + diff --git a/api/docs/tough-cookie.memorycookiestore.synchronous.md b/api/docs/tough-cookie.memorycookiestore.synchronous.md new file mode 100644 index 00000000..c33145b7 --- /dev/null +++ b/api/docs/tough-cookie.memorycookiestore.synchronous.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [MemoryCookieStore](./tough-cookie.memorycookiestore.md) > [synchronous](./tough-cookie.memorycookiestore.synchronous.md) + +## MemoryCookieStore.synchronous property + +This value is `true` since [MemoryCookieStore](./tough-cookie.memorycookiestore.md) implements synchronous functionality. + +**Signature:** + +```typescript +synchronous: boolean; +``` diff --git a/api/docs/tough-cookie.memorycookiestore.updatecookie.md b/api/docs/tough-cookie.memorycookiestore.updatecookie.md new file mode 100644 index 00000000..9611e4c2 --- /dev/null +++ b/api/docs/tough-cookie.memorycookiestore.updatecookie.md @@ -0,0 +1,81 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [MemoryCookieStore](./tough-cookie.memorycookiestore.md) > [updateCookie](./tough-cookie.memorycookiestore.updatecookie.md) + +## MemoryCookieStore.updateCookie() method + +Update an existing [Cookie](./tough-cookie.cookie.md). The implementation MUST update the `value` for a cookie with the same `domain`, `path`, and `key`. The implementation SHOULD check that the old value in the store is equivalent to oldCookie - how the conflict is resolved is up to the store. + +**Signature:** + +```typescript +updateCookie(oldCookie: Cookie, newCookie: Cookie): Promise; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +oldCookie + + + + +[Cookie](./tough-cookie.cookie.md) + + + + +the cookie that is already present in the store. + + +
+ +newCookie + + + + +[Cookie](./tough-cookie.cookie.md) + + + + +the cookie to replace the one already present in the store. + + +
+**Returns:** + +Promise<void> + +## Remarks + +- The `lastAccessed` property is always different between the two objects (to the precision possible via JavaScript's clock). + +- Both `creation` and `creationIndex` are guaranteed to be the same. + +- Stores MAY ignore or defer the `lastAccessed` change at the cost of affecting how cookies are selected for automatic deletion. + +- Stores may wish to optimize changing the `value` of the cookie in the store versus storing a new cookie. + +- The `newCookie` and `oldCookie` objects MUST NOT be modified. + diff --git a/api/docs/tough-cookie.memorycookiestore.updatecookie_1.md b/api/docs/tough-cookie.memorycookiestore.updatecookie_1.md new file mode 100644 index 00000000..28ac5553 --- /dev/null +++ b/api/docs/tough-cookie.memorycookiestore.updatecookie_1.md @@ -0,0 +1,97 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [MemoryCookieStore](./tough-cookie.memorycookiestore.md) > [updateCookie](./tough-cookie.memorycookiestore.updatecookie_1.md) + +## MemoryCookieStore.updateCookie() method + +Update an existing [Cookie](./tough-cookie.cookie.md). The implementation MUST update the `value` for a cookie with the same `domain`, `path`, and `key`. The implementation SHOULD check that the old value in the store is equivalent to oldCookie - how the conflict is resolved is up to the store. + +**Signature:** + +```typescript +updateCookie(oldCookie: Cookie, newCookie: Cookie, callback: ErrorCallback): void; +``` + +## Parameters + + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +oldCookie + + + + +[Cookie](./tough-cookie.cookie.md) + + + + +the cookie that is already present in the store. + + +
+ +newCookie + + + + +[Cookie](./tough-cookie.cookie.md) + + + + +the cookie to replace the one already present in the store. + + +
+ +callback + + + + +[ErrorCallback](./tough-cookie.errorcallback.md) + + + + +A function to call when the cookie has been updated or an error has occurred. + + +
+**Returns:** + +void + +## Remarks + +- The `lastAccessed` property is always different between the two objects (to the precision possible via JavaScript's clock). + +- Both `creation` and `creationIndex` are guaranteed to be the same. + +- Stores MAY ignore or defer the `lastAccessed` change at the cost of affecting how cookies are selected for automatic deletion. + +- Stores may wish to optimize changing the `value` of the cookie in the store versus storing a new cookie. + +- The `newCookie` and `oldCookie` objects MUST NOT be modified. + diff --git a/api/docs/tough-cookie.nullable.md b/api/docs/tough-cookie.nullable.md new file mode 100644 index 00000000..2f48ba67 --- /dev/null +++ b/api/docs/tough-cookie.nullable.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Nullable](./tough-cookie.nullable.md) + +## Nullable type + +The inverse of NonNullable. + +**Signature:** + +```typescript +export type Nullable = T | null | undefined; +``` diff --git a/api/docs/tough-cookie.parametererror.md b/api/docs/tough-cookie.parametererror.md new file mode 100644 index 00000000..12f3e01e --- /dev/null +++ b/api/docs/tough-cookie.parametererror.md @@ -0,0 +1,15 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [ParameterError](./tough-cookie.parametererror.md) + +## ParameterError class + +Represents a validation error. + +**Signature:** + +```typescript +export declare class ParameterError extends Error +``` +**Extends:** Error + diff --git a/api/docs/tough-cookie.parse.md b/api/docs/tough-cookie.parse.md new file mode 100644 index 00000000..74f816f0 --- /dev/null +++ b/api/docs/tough-cookie.parse.md @@ -0,0 +1,73 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [parse](./tough-cookie.parse.md) + +## parse() function + +Parses a string into a Cookie object. + +**Signature:** + +```typescript +export declare function parse(str: string, options?: ParseCookieOptions): Cookie | undefined; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +str + + + + +string + + + + +The `Set-Cookie` header or a Cookie string to parse. + + +
+ +options + + + + +[ParseCookieOptions](./tough-cookie.parsecookieoptions.md) + + + + +_(Optional)_ Configures `strict` or `loose` mode for cookie parsing + + +
+**Returns:** + +[Cookie](./tough-cookie.cookie.md) \| undefined + +## Remarks + +Note: when parsing a `Cookie` header it must be split by ';' before each Cookie string can be parsed. + diff --git a/api/docs/tough-cookie.parsecookieoptions.loose.md b/api/docs/tough-cookie.parsecookieoptions.loose.md new file mode 100644 index 00000000..95732951 --- /dev/null +++ b/api/docs/tough-cookie.parsecookieoptions.loose.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [ParseCookieOptions](./tough-cookie.parsecookieoptions.md) > [loose](./tough-cookie.parsecookieoptions.loose.md) + +## ParseCookieOptions.loose property + +If `true` then keyless cookies like `=abc` and `=` which are not RFC-compliant will be parsed. + +**Signature:** + +```typescript +loose?: boolean | undefined; +``` diff --git a/api/docs/tough-cookie.parsecookieoptions.md b/api/docs/tough-cookie.parsecookieoptions.md new file mode 100644 index 00000000..806a38ec --- /dev/null +++ b/api/docs/tough-cookie.parsecookieoptions.md @@ -0,0 +1,57 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [ParseCookieOptions](./tough-cookie.parsecookieoptions.md) + +## ParseCookieOptions interface + +Optional configuration to be used when parsing cookies. + +**Signature:** + +```typescript +export interface ParseCookieOptions +``` + +## Properties + + + +
+ +Property + + + + +Modifiers + + + + +Type + + + + +Description + + +
+ +[loose?](./tough-cookie.parsecookieoptions.loose.md) + + + + + + + +boolean \| undefined + + + + +_(Optional)_ If `true` then keyless cookies like `=abc` and `=` which are not RFC-compliant will be parsed. + + +
diff --git a/api/docs/tough-cookie.parsedate.md b/api/docs/tough-cookie.parsedate.md new file mode 100644 index 00000000..958b547c --- /dev/null +++ b/api/docs/tough-cookie.parsedate.md @@ -0,0 +1,122 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [parseDate](./tough-cookie.parsedate.md) + +## parseDate() function + +Parse a cookie date string into a [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date). Parses according to [RFC6265 - Section 5.1.1](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.1.1), not [Date.parse()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse). + +**Signature:** + +```typescript +export declare function parseDate(cookieDate: Nullable): Date | undefined; +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +cookieDate + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +the cookie date string + + +
+**Returns:** + +Date \| undefined + +## Remarks + +\#\#\# RFC6265 - 5.1.1. Dates + +The user agent MUST use an algorithm equivalent to the following algorithm to parse a cookie-date. Note that the various boolean flags defined as a part of the algorithm (i.e., found-time, found- day-of-month, found-month, found-year) are initially "not set". + +1. Using the grammar below, divide the cookie-date into date-tokens. + +``` + cookie-date = *delimiter date-token-list *delimiter + date-token-list = date-token *( 1*delimiter date-token ) + date-token = 1*non-delimiter + + delimiter = %x09 / %x20-2F / %x3B-40 / %x5B-60 / %x7B-7E + non-delimiter = %x00-08 / %x0A-1F / DIGIT / ":" / ALPHA / %x7F-FF + non-digit = %x00-2F / %x3A-FF + + day-of-month = 1*2DIGIT ( non-digit *OCTET ) + month = ( "jan" / "feb" / "mar" / "apr" / + "may" / "jun" / "jul" / "aug" / + "sep" / "oct" / "nov" / "dec" ) *OCTET + year = 2*4DIGIT ( non-digit *OCTET ) + time = hms-time ( non-digit *OCTET ) + hms-time = time-field ":" time-field ":" time-field + time-field = 1*2DIGIT +``` +2. Process each date-token sequentially in the order the date-tokens appear in the cookie-date: + +1. If the found-time flag is not set and the token matches the time production, set the found-time flag and set the hour- value, minute-value, and second-value to the numbers denoted by the digits in the date-token, respectively. Skip the remaining sub-steps and continue to the next date-token. + +2. If the found-day-of-month flag is not set and the date-token matches the day-of-month production, set the found-day-of- month flag and set the day-of-month-value to the number denoted by the date-token. Skip the remaining sub-steps and continue to the next date-token. + +3. If the found-month flag is not set and the date-token matches the month production, set the found-month flag and set the month-value to the month denoted by the date-token. Skip the remaining sub-steps and continue to the next date-token. + +4. If the found-year flag is not set and the date-token matches the year production, set the found-year flag and set the year-value to the number denoted by the date-token. Skip the remaining sub-steps and continue to the next date-token. + +3. If the year-value is greater than or equal to 70 and less than or equal to 99, increment the year-value by 1900. + +4. If the year-value is greater than or equal to 0 and less than or equal to 69, increment the year-value by 2000. + +1. NOTE: Some existing user agents interpret two-digit years differently. + +5. Abort these steps and fail to parse the cookie-date if: + +- at least one of the found-day-of-month, found-month, found- year, or found-time flags is not set, + +- the day-of-month-value is less than 1 or greater than 31, + +- the year-value is less than 1601, + +- the hour-value is greater than 23, + +- the minute-value is greater than 59, or + +- the second-value is greater than 59. + +(Note that leap seconds cannot be represented in this syntax.) + +6. Let the parsed-cookie-date be the date whose day-of-month, month, year, hour, minute, and second (in UTC) are the day-of-month- value, the month-value, the year-value, the hour-value, the minute-value, and the second-value, respectively. If no such date exists, abort these steps and fail to parse the cookie-date. + +7. Return the parsed-cookie-date as the result of this algorithm. + +## Example + + +``` +parseDate('Wed, 09 Jun 2021 10:18:14 GMT') +``` + diff --git a/api/docs/tough-cookie.pathmatch.md b/api/docs/tough-cookie.pathmatch.md new file mode 100644 index 00000000..406adac4 --- /dev/null +++ b/api/docs/tough-cookie.pathmatch.md @@ -0,0 +1,75 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [pathMatch](./tough-cookie.pathmatch.md) + +## pathMatch() function + +Answers "does the request-path path-match a given cookie-path?" as per [RFC6265 Section 5.1.4](https://www.rfc-editor.org/rfc/rfc6265.html#section-5.1.4). This is essentially a prefix-match where cookiePath is a prefix of reqPath. + +**Signature:** + +```typescript +export declare function pathMatch(reqPath: string, cookiePath: string): boolean; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +reqPath + + + + +string + + + + +the path of the request + + +
+ +cookiePath + + + + +string + + + + +the path of the cookie + + +
+**Returns:** + +boolean + +## Remarks + +A request-path path-matches a given cookie-path if at least one of the following conditions holds: + +- The cookie-path and the request-path are identical. - The cookie-path is a prefix of the request-path, and the last character of the cookie-path is %x2F ("/"). - The cookie-path is a prefix of the request-path, and the first character of the request-path that is not included in the cookie-path is a %x2F ("/") character. + diff --git a/api/docs/tough-cookie.permutedomain.md b/api/docs/tough-cookie.permutedomain.md new file mode 100644 index 00000000..4a1e178e --- /dev/null +++ b/api/docs/tough-cookie.permutedomain.md @@ -0,0 +1,77 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [permuteDomain](./tough-cookie.permutedomain.md) + +## permuteDomain() function + +Generates the permutation of all possible values that [domainMatch()](./tough-cookie.domainmatch.md) the given `domain` parameter. The array is in shortest-to-longest order. Useful when building custom [Store](./tough-cookie.store.md) implementations. + +**Signature:** + +```typescript +export declare function permuteDomain(domain: string, allowSpecialUseDomain?: boolean): string[] | undefined; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +domain + + + + +string + + + + +the domain to generate permutations for + + +
+ +allowSpecialUseDomain + + + + +boolean + + + + +_(Optional)_ flag to control if [Special Use Domains](https://www.rfc-editor.org/rfc/rfc6761.html) such as `localhost` should be allowed + + +
+**Returns:** + +string\[\] \| undefined + +## Example + + +``` +permuteDomain('foo.bar.example.com') +// ['example.com', 'bar.example.com', 'foo.bar.example.com'] +``` + diff --git a/api/docs/tough-cookie.permutepath.md b/api/docs/tough-cookie.permutepath.md new file mode 100644 index 00000000..2dcf558f --- /dev/null +++ b/api/docs/tough-cookie.permutepath.md @@ -0,0 +1,61 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [permutePath](./tough-cookie.permutepath.md) + +## permutePath() function + +Generates the permutation of all possible values that [pathMatch()](./tough-cookie.pathmatch.md) the `path` parameter. The array is in longest-to-shortest order. Useful when building custom [Store](./tough-cookie.store.md) implementations. + +**Signature:** + +```typescript +export declare function permutePath(path: string): string[]; +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +path + + + + +string + + + + +the path to generate permutations for + + +
+**Returns:** + +string\[\] + +## Example + + +``` +permutePath('/foo/bar/') +// ['/foo/bar/', '/foo/bar', '/foo', '/'] +``` + diff --git a/api/docs/tough-cookie.prefixsecurityenum.md b/api/docs/tough-cookie.prefixsecurityenum.md new file mode 100644 index 00000000..399e9071 --- /dev/null +++ b/api/docs/tough-cookie.prefixsecurityenum.md @@ -0,0 +1,25 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [PrefixSecurityEnum](./tough-cookie.prefixsecurityenum.md) + +## PrefixSecurityEnum variable + +Cookie prefixes are a way to indicate that a given cookie was set with a set of attributes simply by inspecting the first few characters of the cookie's name. These are defined in [RFC6265bis - Section 4.1.3](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-13#section-4.1.3). + +The following values can be used to configure how a [CookieJar](./tough-cookie.cookiejar.md) enforces attribute restrictions for Cookie prefixes: + +- `silent` - Enable cookie prefix checking but silently ignores the cookie if conditions are not met. This is the default configuration for a [CookieJar](./tough-cookie.cookiejar.md). + +- `strict` - Enables cookie prefix checking and will raise an error if conditions are not met. + +- `unsafe-disabled` - Disables cookie prefix checking. + +**Signature:** + +```typescript +PrefixSecurityEnum: Readonly<{ + SILENT: "silent"; + STRICT: "strict"; + DISABLED: "unsafe-disabled"; +}> +``` diff --git a/api/docs/tough-cookie.serializedcookie.md b/api/docs/tough-cookie.serializedcookie.md new file mode 100644 index 00000000..1222e234 --- /dev/null +++ b/api/docs/tough-cookie.serializedcookie.md @@ -0,0 +1,17 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [SerializedCookie](./tough-cookie.serializedcookie.md) + +## SerializedCookie type + +A JSON object that is created when [Cookie.toJSON()](./tough-cookie.cookie.tojson.md) is called. This object will contain the properties defined in [Cookie.serializableProperties](./tough-cookie.cookie.serializableproperties.md). + +**Signature:** + +```typescript +export type SerializedCookie = { + key?: string; + value?: string; + [key: string]: unknown; +}; +``` diff --git a/api/docs/tough-cookie.serializedcookiejar.cookies.md b/api/docs/tough-cookie.serializedcookiejar.cookies.md new file mode 100644 index 00000000..350ba100 --- /dev/null +++ b/api/docs/tough-cookie.serializedcookiejar.cookies.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [SerializedCookieJar](./tough-cookie.serializedcookiejar.md) > [cookies](./tough-cookie.serializedcookiejar.cookies.md) + +## SerializedCookieJar.cookies property + +The list of [Cookie](./tough-cookie.cookie.md) values serialized as JSON objects. + +**Signature:** + +```typescript +cookies: SerializedCookie[]; +``` diff --git a/api/docs/tough-cookie.serializedcookiejar.md b/api/docs/tough-cookie.serializedcookiejar.md new file mode 100644 index 00000000..e47ee577 --- /dev/null +++ b/api/docs/tough-cookie.serializedcookiejar.md @@ -0,0 +1,114 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [SerializedCookieJar](./tough-cookie.serializedcookiejar.md) + +## SerializedCookieJar interface + +A JSON representation of a [CookieJar](./tough-cookie.cookiejar.md). + +**Signature:** + +```typescript +export interface SerializedCookieJar +``` + +## Properties + + + + + + +
+ +Property + + + + +Modifiers + + + + +Type + + + + +Description + + +
+ +[cookies](./tough-cookie.serializedcookiejar.cookies.md) + + + + + + + +[SerializedCookie](./tough-cookie.serializedcookie.md)\[\] + + + + +The list of [Cookie](./tough-cookie.cookie.md) values serialized as JSON objects. + + +
+ +[rejectPublicSuffixes](./tough-cookie.serializedcookiejar.rejectpublicsuffixes.md) + + + + + + + +boolean + + + + +The value of [CreateCookieJarOptions.rejectPublicSuffixes](./tough-cookie.createcookiejaroptions.rejectpublicsuffixes.md) configured on the [CookieJar](./tough-cookie.cookiejar.md). + + +
+ +[storeType](./tough-cookie.serializedcookiejar.storetype.md) + + + + + + + +string \| null + + + + +The name of the store used during serialization. + + +
+ +[version](./tough-cookie.serializedcookiejar.version.md) + + + + + + + +string + + + + +The version of `tough-cookie` used during serialization. + + +
diff --git a/api/docs/tough-cookie.serializedcookiejar.rejectpublicsuffixes.md b/api/docs/tough-cookie.serializedcookiejar.rejectpublicsuffixes.md new file mode 100644 index 00000000..69d54244 --- /dev/null +++ b/api/docs/tough-cookie.serializedcookiejar.rejectpublicsuffixes.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [SerializedCookieJar](./tough-cookie.serializedcookiejar.md) > [rejectPublicSuffixes](./tough-cookie.serializedcookiejar.rejectpublicsuffixes.md) + +## SerializedCookieJar.rejectPublicSuffixes property + +The value of [CreateCookieJarOptions.rejectPublicSuffixes](./tough-cookie.createcookiejaroptions.rejectpublicsuffixes.md) configured on the [CookieJar](./tough-cookie.cookiejar.md). + +**Signature:** + +```typescript +rejectPublicSuffixes: boolean; +``` diff --git a/api/docs/tough-cookie.serializedcookiejar.storetype.md b/api/docs/tough-cookie.serializedcookiejar.storetype.md new file mode 100644 index 00000000..22a0fd03 --- /dev/null +++ b/api/docs/tough-cookie.serializedcookiejar.storetype.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [SerializedCookieJar](./tough-cookie.serializedcookiejar.md) > [storeType](./tough-cookie.serializedcookiejar.storetype.md) + +## SerializedCookieJar.storeType property + +The name of the store used during serialization. + +**Signature:** + +```typescript +storeType: string | null; +``` diff --git a/api/docs/tough-cookie.serializedcookiejar.version.md b/api/docs/tough-cookie.serializedcookiejar.version.md new file mode 100644 index 00000000..8a09868b --- /dev/null +++ b/api/docs/tough-cookie.serializedcookiejar.version.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [SerializedCookieJar](./tough-cookie.serializedcookiejar.md) > [version](./tough-cookie.serializedcookiejar.version.md) + +## SerializedCookieJar.version property + +The version of `tough-cookie` used during serialization. + +**Signature:** + +```typescript +version: string; +``` diff --git a/api/docs/tough-cookie.setcookieoptions.http.md b/api/docs/tough-cookie.setcookieoptions.http.md new file mode 100644 index 00000000..7bd236fa --- /dev/null +++ b/api/docs/tough-cookie.setcookieoptions.http.md @@ -0,0 +1,15 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [SetCookieOptions](./tough-cookie.setcookieoptions.md) > [http](./tough-cookie.setcookieoptions.http.md) + +## SetCookieOptions.http property + +Indicates if this is an HTTP or non-HTTP API. Affects HttpOnly cookies. + +Defaults to `true` if not provided. + +**Signature:** + +```typescript +http?: boolean | undefined; +``` diff --git a/api/docs/tough-cookie.setcookieoptions.ignoreerror.md b/api/docs/tough-cookie.setcookieoptions.ignoreerror.md new file mode 100644 index 00000000..34718231 --- /dev/null +++ b/api/docs/tough-cookie.setcookieoptions.ignoreerror.md @@ -0,0 +1,15 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [SetCookieOptions](./tough-cookie.setcookieoptions.md) > [ignoreError](./tough-cookie.setcookieoptions.ignoreerror.md) + +## SetCookieOptions.ignoreError property + +Silently ignore things like parse errors and invalid domains. Store errors aren't ignored by this option. + +Defaults to `false` if not provided. + +**Signature:** + +```typescript +ignoreError?: boolean | undefined; +``` diff --git a/api/docs/tough-cookie.setcookieoptions.loose.md b/api/docs/tough-cookie.setcookieoptions.loose.md new file mode 100644 index 00000000..09e13e0f --- /dev/null +++ b/api/docs/tough-cookie.setcookieoptions.loose.md @@ -0,0 +1,15 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [SetCookieOptions](./tough-cookie.setcookieoptions.md) > [loose](./tough-cookie.setcookieoptions.loose.md) + +## SetCookieOptions.loose property + +Controls if a cookie string should be parsed using `loose` mode or not. See [Cookie.parse()](./tough-cookie.cookie.parse.md) and [ParseCookieOptions](./tough-cookie.parsecookieoptions.md) for more details. + +Defaults to `false` if not provided. + +**Signature:** + +```typescript +loose?: boolean | undefined; +``` diff --git a/api/docs/tough-cookie.setcookieoptions.md b/api/docs/tough-cookie.setcookieoptions.md new file mode 100644 index 00000000..3622f564 --- /dev/null +++ b/api/docs/tough-cookie.setcookieoptions.md @@ -0,0 +1,151 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [SetCookieOptions](./tough-cookie.setcookieoptions.md) + +## SetCookieOptions interface + +Configuration options used when calling `CookieJar.setCookie(...)` + +**Signature:** + +```typescript +export interface SetCookieOptions +``` + +## Properties + + + + + + + +
+ +Property + + + + +Modifiers + + + + +Type + + + + +Description + + +
+ +[http?](./tough-cookie.setcookieoptions.http.md) + + + + + + + +boolean \| undefined + + + + +_(Optional)_ Indicates if this is an HTTP or non-HTTP API. Affects HttpOnly cookies. + +Defaults to `true` if not provided. + + +
+ +[ignoreError?](./tough-cookie.setcookieoptions.ignoreerror.md) + + + + + + + +boolean \| undefined + + + + +_(Optional)_ Silently ignore things like parse errors and invalid domains. Store errors aren't ignored by this option. + +Defaults to `false` if not provided. + + +
+ +[loose?](./tough-cookie.setcookieoptions.loose.md) + + + + + + + +boolean \| undefined + + + + +_(Optional)_ Controls if a cookie string should be parsed using `loose` mode or not. See [Cookie.parse()](./tough-cookie.cookie.parse.md) and [ParseCookieOptions](./tough-cookie.parsecookieoptions.md) for more details. + +Defaults to `false` if not provided. + + +
+ +[now?](./tough-cookie.setcookieoptions.now.md) + + + + + + + +Date \| undefined + + + + +_(Optional)_ Forces the cookie creation and access time of cookies to this value when stored. + +Defaults to `Date.now()` if not provided. + + +
+ +[sameSiteContext?](./tough-cookie.setcookieoptions.samesitecontext.md) + + + + + + + +'strict' \| 'lax' \| 'none' \| undefined + + + + +_(Optional)_ Set this to 'none', 'lax', or 'strict' to enforce SameSite cookies upon storage. + +- `'strict'` - If the request is on the same "site for cookies" (see the RFC draft for more information), pass this option to add a layer of defense against CSRF. + +- `'lax'` - If the request is from another site, but is directly because of navigation by the user, such as, `` or ``, then use `lax`. + +- `'none'` - This indicates a cross-origin request. + +- `undefined` - SameSite is not be enforced! This can be a valid use-case for when CSRF isn't in the threat model of the system being built. + +Defaults to `undefined` if not provided. + + +
diff --git a/api/docs/tough-cookie.setcookieoptions.now.md b/api/docs/tough-cookie.setcookieoptions.now.md new file mode 100644 index 00000000..cb453889 --- /dev/null +++ b/api/docs/tough-cookie.setcookieoptions.now.md @@ -0,0 +1,15 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [SetCookieOptions](./tough-cookie.setcookieoptions.md) > [now](./tough-cookie.setcookieoptions.now.md) + +## SetCookieOptions.now property + +Forces the cookie creation and access time of cookies to this value when stored. + +Defaults to `Date.now()` if not provided. + +**Signature:** + +```typescript +now?: Date | undefined; +``` diff --git a/api/docs/tough-cookie.setcookieoptions.samesitecontext.md b/api/docs/tough-cookie.setcookieoptions.samesitecontext.md new file mode 100644 index 00000000..3a882928 --- /dev/null +++ b/api/docs/tough-cookie.setcookieoptions.samesitecontext.md @@ -0,0 +1,28 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [SetCookieOptions](./tough-cookie.setcookieoptions.md) > [sameSiteContext](./tough-cookie.setcookieoptions.samesitecontext.md) + +## SetCookieOptions.sameSiteContext property + +Set this to 'none', 'lax', or 'strict' to enforce SameSite cookies upon storage. + +- `'strict'` - If the request is on the same "site for cookies" (see the RFC draft for more information), pass this option to add a layer of defense against CSRF. + +- `'lax'` - If the request is from another site, but is directly because of navigation by the user, such as, `` or ``, then use `lax`. + +- `'none'` - This indicates a cross-origin request. + +- `undefined` - SameSite is not be enforced! This can be a valid use-case for when CSRF isn't in the threat model of the system being built. + +Defaults to `undefined` if not provided. + +**Signature:** + +```typescript +sameSiteContext?: 'strict' | 'lax' | 'none' | undefined; +``` + +## Remarks + +- It is highly recommended that you read [RFC6265bis - Section 8.8](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02##section-8.8) which discusses security considerations and defence on SameSite cookies in depth. + diff --git a/api/docs/tough-cookie.store._constructor_.md b/api/docs/tough-cookie.store._constructor_.md new file mode 100644 index 00000000..c7d3604c --- /dev/null +++ b/api/docs/tough-cookie.store._constructor_.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Store](./tough-cookie.store.md) > [(constructor)](./tough-cookie.store._constructor_.md) + +## Store.(constructor) + +Constructs a new instance of the `Store` class + +**Signature:** + +```typescript +constructor(); +``` diff --git a/api/docs/tough-cookie.store.findcookie.md b/api/docs/tough-cookie.store.findcookie.md new file mode 100644 index 00000000..5a8fa725 --- /dev/null +++ b/api/docs/tough-cookie.store.findcookie.md @@ -0,0 +1,87 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Store](./tough-cookie.store.md) > [findCookie](./tough-cookie.store.findcookie.md) + +## Store.findCookie() method + +Retrieve a [Cookie](./tough-cookie.cookie.md) with the given `domain`, `path`, and `key` (`name`). The RFC maintains that exactly one of these cookies should exist in a store. If the store is using versioning, this means that the latest or newest such cookie should be returned. + +Callback takes an error and the resulting Cookie object. If no cookie is found then null MUST be passed instead (that is, not an error). + +**Signature:** + +```typescript +findCookie(domain: Nullable, path: Nullable, key: Nullable): Promise; +``` + +## Parameters + + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +domain + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +The cookie domain to match against. + + +
+ +path + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +The cookie path to match against. + + +
+ +key + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +The cookie name to match against. + + +
+**Returns:** + +Promise<[Cookie](./tough-cookie.cookie.md) \| undefined> + diff --git a/api/docs/tough-cookie.store.findcookie_1.md b/api/docs/tough-cookie.store.findcookie_1.md new file mode 100644 index 00000000..a4fc78c0 --- /dev/null +++ b/api/docs/tough-cookie.store.findcookie_1.md @@ -0,0 +1,103 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Store](./tough-cookie.store.md) > [findCookie](./tough-cookie.store.findcookie_1.md) + +## Store.findCookie() method + +Retrieve a [Cookie](./tough-cookie.cookie.md) with the given `domain`, `path`, and `key` (`name`). The RFC maintains that exactly one of these cookies should exist in a store. If the store is using versioning, this means that the latest or newest such cookie should be returned. + +Callback takes an error and the resulting Cookie object. If no cookie is found then null MUST be passed instead (that is, not an error). + +**Signature:** + +```typescript +findCookie(domain: Nullable, path: Nullable, key: Nullable, callback: Callback): void; +``` + +## Parameters + + + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +domain + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +The cookie domain to match against. + + +
+ +path + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +The cookie path to match against. + + +
+ +key + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +The cookie name to match against. + + +
+ +callback + + + + +[Callback](./tough-cookie.callback.md)<[Cookie](./tough-cookie.cookie.md) \| undefined> + + + + +A function to call with either the found cookie or an error. + + +
+**Returns:** + +void + diff --git a/api/docs/tough-cookie.store.findcookies.md b/api/docs/tough-cookie.store.findcookies.md new file mode 100644 index 00000000..85e19ed7 --- /dev/null +++ b/api/docs/tough-cookie.store.findcookies.md @@ -0,0 +1,93 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Store](./tough-cookie.store.md) > [findCookies](./tough-cookie.store.findcookies.md) + +## Store.findCookies() method + +Locates all [Cookie](./tough-cookie.cookie.md) values matching the given `domain` and `path`. + +The resulting list is checked for applicability to the current request according to the RFC (`domain-match`, `path-match`, `http-only-flag`, `secure-flag`, `expiry`, and so on), so it's OK to use an optimistic search algorithm when implementing this method. However, the search algorithm used SHOULD try to find cookies that [domainMatch()](./tough-cookie.domainmatch.md) the `domain` and [pathMatch()](./tough-cookie.pathmatch.md) the `path` in order to limit the amount of checking that needs to be done. + +**Signature:** + +```typescript +findCookies(domain: Nullable, path: Nullable, allowSpecialUseDomain?: boolean): Promise; +``` + +## Parameters + + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +domain + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +The cookie domain to match against. + + +
+ +path + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +The cookie path to match against. + + +
+ +allowSpecialUseDomain + + + + +boolean + + + + +_(Optional)_ If `true` then special-use domain suffixes, will be allowed in matches. Defaults to `false`. + + +
+**Returns:** + +Promise<[Cookie](./tough-cookie.cookie.md)\[\]> + +## Remarks + +- As of version `0.9.12`, the `allPaths` option to cookiejar.getCookies() above causes the path here to be `null`. + +- If the `path` is `null`, `path-matching` MUST NOT be performed (that is, `domain-matching` only). + diff --git a/api/docs/tough-cookie.store.findcookies_1.md b/api/docs/tough-cookie.store.findcookies_1.md new file mode 100644 index 00000000..03f55489 --- /dev/null +++ b/api/docs/tough-cookie.store.findcookies_1.md @@ -0,0 +1,109 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Store](./tough-cookie.store.md) > [findCookies](./tough-cookie.store.findcookies_1.md) + +## Store.findCookies() method + +Locates all [Cookie](./tough-cookie.cookie.md) values matching the given `domain` and `path`. + +The resulting list is checked for applicability to the current request according to the RFC (`domain-match`, `path-match`, `http-only-flag`, `secure-flag`, `expiry`, and so on), so it's OK to use an optimistic search algorithm when implementing this method. However, the search algorithm used SHOULD try to find cookies that [domainMatch()](./tough-cookie.domainmatch.md) the `domain` and [pathMatch()](./tough-cookie.pathmatch.md) the `path` in order to limit the amount of checking that needs to be done. + +**Signature:** + +```typescript +findCookies(domain: Nullable, path: Nullable, allowSpecialUseDomain?: boolean, callback?: Callback): void; +``` + +## Parameters + + + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +domain + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +The cookie domain to match against. + + +
+ +path + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +The cookie path to match against. + + +
+ +allowSpecialUseDomain + + + + +boolean + + + + +_(Optional)_ If `true` then special-use domain suffixes, will be allowed in matches. Defaults to `false`. + + +
+ +callback + + + + +[Callback](./tough-cookie.callback.md)<[Cookie](./tough-cookie.cookie.md)\[\]> + + + + +_(Optional)_ A function to call with either the found cookies or an error. + + +
+**Returns:** + +void + +## Remarks + +- As of version `0.9.12`, the `allPaths` option to cookiejar.getCookies() above causes the path here to be `null`. + +- If the `path` is `null`, `path-matching` MUST NOT be performed (that is, `domain-matching` only). + diff --git a/api/docs/tough-cookie.store.getallcookies.md b/api/docs/tough-cookie.store.getallcookies.md new file mode 100644 index 00000000..26000f7f --- /dev/null +++ b/api/docs/tough-cookie.store.getallcookies.md @@ -0,0 +1,21 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Store](./tough-cookie.store.md) > [getAllCookies](./tough-cookie.store.getallcookies.md) + +## Store.getAllCookies() method + +Gets all the cookies in the store. + +**Signature:** + +```typescript +getAllCookies(): Promise; +``` +**Returns:** + +Promise<[Cookie](./tough-cookie.cookie.md)\[\]> + +## Remarks + +- Cookies SHOULD be returned in creation order to preserve sorting via [cookieCompare()](./tough-cookie.cookiecompare.md). + diff --git a/api/docs/tough-cookie.store.getallcookies_1.md b/api/docs/tough-cookie.store.getallcookies_1.md new file mode 100644 index 00000000..d347b37e --- /dev/null +++ b/api/docs/tough-cookie.store.getallcookies_1.md @@ -0,0 +1,57 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Store](./tough-cookie.store.md) > [getAllCookies](./tough-cookie.store.getallcookies_1.md) + +## Store.getAllCookies() method + +Gets all the cookies in the store. + +**Signature:** + +```typescript +getAllCookies(callback: Callback): void; +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +callback + + + + +[Callback](./tough-cookie.callback.md)<[Cookie](./tough-cookie.cookie.md)\[\]> + + + + +A function to call when all the cookies have been retrieved or an error occurs. + + +
+**Returns:** + +void + +## Remarks + +- Cookies SHOULD be returned in creation order to preserve sorting via [cookieCompare()](./tough-cookie.cookiecompare.md). + diff --git a/api/docs/tough-cookie.store.md b/api/docs/tough-cookie.store.md new file mode 100644 index 00000000..4f06a0e3 --- /dev/null +++ b/api/docs/tough-cookie.store.md @@ -0,0 +1,351 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Store](./tough-cookie.store.md) + +## Store class + +Base class for [CookieJar](./tough-cookie.cookiejar.md) stores. + +The storage model for each [CookieJar](./tough-cookie.cookiejar.md) instance can be replaced with a custom implementation. The default is [MemoryCookieStore](./tough-cookie.memorycookiestore.md). + +**Signature:** + +```typescript +export declare class Store +``` + +## Remarks + +- Stores should inherit from the base Store class, which is available as a top-level export. + +- Stores are asynchronous by default, but if [Store.synchronous](./tough-cookie.store.synchronous.md) is set to true, then the `*Sync` methods of the containing [CookieJar](./tough-cookie.cookiejar.md) can be used. + +## Constructors + + + +
+ +Constructor + + + + +Modifiers + + + + +Description + + +
+ +[(constructor)()](./tough-cookie.store._constructor_.md) + + + + + + + +Constructs a new instance of the `Store` class + + +
+ +## Properties + + + +
+ +Property + + + + +Modifiers + + + + +Type + + + + +Description + + +
+ +[synchronous](./tough-cookie.store.synchronous.md) + + + + + + + +boolean + + + + +Store implementations that support synchronous methods must return `true`. + + +
+ +## Methods + + + + + + + + + + + + + + + + + + +
+ +Method + + + + +Modifiers + + + + +Description + + +
+ +[findCookie(domain, path, key)](./tough-cookie.store.findcookie.md) + + + + + + + +Retrieve a [Cookie](./tough-cookie.cookie.md) with the given `domain`, `path`, and `key` (`name`). The RFC maintains that exactly one of these cookies should exist in a store. If the store is using versioning, this means that the latest or newest such cookie should be returned. + +Callback takes an error and the resulting Cookie object. If no cookie is found then null MUST be passed instead (that is, not an error). + + +
+ +[findCookie(domain, path, key, callback)](./tough-cookie.store.findcookie_1.md) + + + + + + + +Retrieve a [Cookie](./tough-cookie.cookie.md) with the given `domain`, `path`, and `key` (`name`). The RFC maintains that exactly one of these cookies should exist in a store. If the store is using versioning, this means that the latest or newest such cookie should be returned. + +Callback takes an error and the resulting Cookie object. If no cookie is found then null MUST be passed instead (that is, not an error). + + +
+ +[findCookies(domain, path, allowSpecialUseDomain)](./tough-cookie.store.findcookies.md) + + + + + + + +Locates all [Cookie](./tough-cookie.cookie.md) values matching the given `domain` and `path`. + +The resulting list is checked for applicability to the current request according to the RFC (`domain-match`, `path-match`, `http-only-flag`, `secure-flag`, `expiry`, and so on), so it's OK to use an optimistic search algorithm when implementing this method. However, the search algorithm used SHOULD try to find cookies that [domainMatch()](./tough-cookie.domainmatch.md) the `domain` and [pathMatch()](./tough-cookie.pathmatch.md) the `path` in order to limit the amount of checking that needs to be done. + + +
+ +[findCookies(domain, path, allowSpecialUseDomain, callback)](./tough-cookie.store.findcookies_1.md) + + + + + + + +Locates all [Cookie](./tough-cookie.cookie.md) values matching the given `domain` and `path`. + +The resulting list is checked for applicability to the current request according to the RFC (`domain-match`, `path-match`, `http-only-flag`, `secure-flag`, `expiry`, and so on), so it's OK to use an optimistic search algorithm when implementing this method. However, the search algorithm used SHOULD try to find cookies that [domainMatch()](./tough-cookie.domainmatch.md) the `domain` and [pathMatch()](./tough-cookie.pathmatch.md) the `path` in order to limit the amount of checking that needs to be done. + + +
+ +[getAllCookies()](./tough-cookie.store.getallcookies.md) + + + + + + + +Gets all the cookies in the store. + + +
+ +[getAllCookies(callback)](./tough-cookie.store.getallcookies_1.md) + + + + + + + +Gets all the cookies in the store. + + +
+ +[putCookie(cookie)](./tough-cookie.store.putcookie.md) + + + + + + + +Adds a new [Cookie](./tough-cookie.cookie.md) to the store. The implementation SHOULD replace any existing cookie with the same `domain`, `path`, and `key` properties. + + +
+ +[putCookie(cookie, callback)](./tough-cookie.store.putcookie_1.md) + + + + + + + +Adds a new [Cookie](./tough-cookie.cookie.md) to the store. The implementation SHOULD replace any existing cookie with the same `domain`, `path`, and `key` properties. + + +
+ +[removeAllCookies()](./tough-cookie.store.removeallcookies.md) + + + + + + + +Removes all cookies from the store. + + +
+ +[removeAllCookies(callback)](./tough-cookie.store.removeallcookies_1.md) + + + + + + + +Removes all cookies from the store. + + +
+ +[removeCookie(domain, path, key)](./tough-cookie.store.removecookie.md) + + + + + + + +Remove a cookie from the store (see notes on `findCookie` about the uniqueness constraint). + + +
+ +[removeCookie(domain, path, key, callback)](./tough-cookie.store.removecookie_1.md) + + + + + + + +Remove a cookie from the store (see notes on `findCookie` about the uniqueness constraint). + + +
+ +[removeCookies(domain, path)](./tough-cookie.store.removecookies.md) + + + + + + + +Removes matching cookies from the store. The `path` parameter is optional and if missing, means all paths in a domain should be removed. + + +
+ +[removeCookies(domain, path, callback)](./tough-cookie.store.removecookies_1.md) + + + + + + + +Removes matching cookies from the store. The `path` parameter is optional and if missing, means all paths in a domain should be removed. + + +
+ +[updateCookie(oldCookie, newCookie)](./tough-cookie.store.updatecookie.md) + + + + + + + +Update an existing [Cookie](./tough-cookie.cookie.md). The implementation MUST update the `value` for a cookie with the same `domain`, `path`, and `key`. The implementation SHOULD check that the old value in the store is equivalent to oldCookie - how the conflict is resolved is up to the store. + + +
+ +[updateCookie(oldCookie, newCookie, callback)](./tough-cookie.store.updatecookie_1.md) + + + + + + + +Update an existing [Cookie](./tough-cookie.cookie.md). The implementation MUST update the `value` for a cookie with the same `domain`, `path`, and `key`. The implementation SHOULD check that the old value in the store is equivalent to oldCookie - how the conflict is resolved is up to the store. + + +
diff --git a/api/docs/tough-cookie.store.putcookie.md b/api/docs/tough-cookie.store.putcookie.md new file mode 100644 index 00000000..584222b2 --- /dev/null +++ b/api/docs/tough-cookie.store.putcookie.md @@ -0,0 +1,59 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Store](./tough-cookie.store.md) > [putCookie](./tough-cookie.store.putcookie.md) + +## Store.putCookie() method + +Adds a new [Cookie](./tough-cookie.cookie.md) to the store. The implementation SHOULD replace any existing cookie with the same `domain`, `path`, and `key` properties. + +**Signature:** + +```typescript +putCookie(cookie: Cookie): Promise; +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +cookie + + + + +[Cookie](./tough-cookie.cookie.md) + + + + +The cookie to store. + + +
+**Returns:** + +Promise<void> + +## Remarks + +- Depending on the nature of the implementation, it's possible that between the call to `fetchCookie` and `putCookie` that a duplicate `putCookie` can occur. + +- The [Cookie](./tough-cookie.cookie.md) object MUST NOT be modified; as the caller has already updated the `creation` and `lastAccessed` properties. + diff --git a/api/docs/tough-cookie.store.putcookie_1.md b/api/docs/tough-cookie.store.putcookie_1.md new file mode 100644 index 00000000..d9f91afe --- /dev/null +++ b/api/docs/tough-cookie.store.putcookie_1.md @@ -0,0 +1,75 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Store](./tough-cookie.store.md) > [putCookie](./tough-cookie.store.putcookie_1.md) + +## Store.putCookie() method + +Adds a new [Cookie](./tough-cookie.cookie.md) to the store. The implementation SHOULD replace any existing cookie with the same `domain`, `path`, and `key` properties. + +**Signature:** + +```typescript +putCookie(cookie: Cookie, callback: ErrorCallback): void; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +cookie + + + + +[Cookie](./tough-cookie.cookie.md) + + + + +The cookie to store. + + +
+ +callback + + + + +[ErrorCallback](./tough-cookie.errorcallback.md) + + + + +A function to call when the cookie has been stored or an error has occurred. + + +
+**Returns:** + +void + +## Remarks + +- Depending on the nature of the implementation, it's possible that between the call to `fetchCookie` and `putCookie` that a duplicate `putCookie` can occur. + +- The [Cookie](./tough-cookie.cookie.md) object MUST NOT be modified; as the caller has already updated the `creation` and `lastAccessed` properties. + diff --git a/api/docs/tough-cookie.store.removeallcookies.md b/api/docs/tough-cookie.store.removeallcookies.md new file mode 100644 index 00000000..a7a36696 --- /dev/null +++ b/api/docs/tough-cookie.store.removeallcookies.md @@ -0,0 +1,17 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Store](./tough-cookie.store.md) > [removeAllCookies](./tough-cookie.store.removeallcookies.md) + +## Store.removeAllCookies() method + +Removes all cookies from the store. + +**Signature:** + +```typescript +removeAllCookies(): Promise; +``` +**Returns:** + +Promise<void> + diff --git a/api/docs/tough-cookie.store.removeallcookies_1.md b/api/docs/tough-cookie.store.removeallcookies_1.md new file mode 100644 index 00000000..be473509 --- /dev/null +++ b/api/docs/tough-cookie.store.removeallcookies_1.md @@ -0,0 +1,53 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Store](./tough-cookie.store.md) > [removeAllCookies](./tough-cookie.store.removeallcookies_1.md) + +## Store.removeAllCookies() method + +Removes all cookies from the store. + +**Signature:** + +```typescript +removeAllCookies(callback: ErrorCallback): void; +``` + +## Parameters + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +callback + + + + +[ErrorCallback](./tough-cookie.errorcallback.md) + + + + +A function to call when all the cookies have been removed or an error occurs. + + +
+**Returns:** + +void + diff --git a/api/docs/tough-cookie.store.removecookie.md b/api/docs/tough-cookie.store.removecookie.md new file mode 100644 index 00000000..95b8b539 --- /dev/null +++ b/api/docs/tough-cookie.store.removecookie.md @@ -0,0 +1,85 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Store](./tough-cookie.store.md) > [removeCookie](./tough-cookie.store.removecookie.md) + +## Store.removeCookie() method + +Remove a cookie from the store (see notes on `findCookie` about the uniqueness constraint). + +**Signature:** + +```typescript +removeCookie(domain: Nullable, path: Nullable, key: Nullable): Promise; +``` + +## Parameters + + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +domain + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +The cookie domain to match against. + + +
+ +path + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +The cookie path to match against. + + +
+ +key + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +The cookie name to match against. + + +
+**Returns:** + +Promise<void> + diff --git a/api/docs/tough-cookie.store.removecookie_1.md b/api/docs/tough-cookie.store.removecookie_1.md new file mode 100644 index 00000000..05907e8f --- /dev/null +++ b/api/docs/tough-cookie.store.removecookie_1.md @@ -0,0 +1,101 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Store](./tough-cookie.store.md) > [removeCookie](./tough-cookie.store.removecookie_1.md) + +## Store.removeCookie() method + +Remove a cookie from the store (see notes on `findCookie` about the uniqueness constraint). + +**Signature:** + +```typescript +removeCookie(domain: Nullable, path: Nullable, key: Nullable, callback: ErrorCallback): void; +``` + +## Parameters + + + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +domain + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +The cookie domain to match against. + + +
+ +path + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +The cookie path to match against. + + +
+ +key + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +The cookie name to match against. + + +
+ +callback + + + + +[ErrorCallback](./tough-cookie.errorcallback.md) + + + + +A function to call when the cookie has been removed or an error occurs. + + +
+**Returns:** + +void + diff --git a/api/docs/tough-cookie.store.removecookies.md b/api/docs/tough-cookie.store.removecookies.md new file mode 100644 index 00000000..6be4cb45 --- /dev/null +++ b/api/docs/tough-cookie.store.removecookies.md @@ -0,0 +1,69 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Store](./tough-cookie.store.md) > [removeCookies](./tough-cookie.store.removecookies.md) + +## Store.removeCookies() method + +Removes matching cookies from the store. The `path` parameter is optional and if missing, means all paths in a domain should be removed. + +**Signature:** + +```typescript +removeCookies(domain: string, path: Nullable): Promise; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +domain + + + + +string + + + + +The cookie domain to match against. + + +
+ +path + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +The cookie path to match against. + + +
+**Returns:** + +Promise<void> + diff --git a/api/docs/tough-cookie.store.removecookies_1.md b/api/docs/tough-cookie.store.removecookies_1.md new file mode 100644 index 00000000..ce13026a --- /dev/null +++ b/api/docs/tough-cookie.store.removecookies_1.md @@ -0,0 +1,85 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Store](./tough-cookie.store.md) > [removeCookies](./tough-cookie.store.removecookies_1.md) + +## Store.removeCookies() method + +Removes matching cookies from the store. The `path` parameter is optional and if missing, means all paths in a domain should be removed. + +**Signature:** + +```typescript +removeCookies(domain: string, path: Nullable, callback: ErrorCallback): void; +``` + +## Parameters + + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +domain + + + + +string + + + + +The cookie domain to match against. + + +
+ +path + + + + +[Nullable](./tough-cookie.nullable.md)<string> + + + + +The cookie path to match against. + + +
+ +callback + + + + +[ErrorCallback](./tough-cookie.errorcallback.md) + + + + +A function to call when the cookies have been removed or an error occurs. + + +
+**Returns:** + +void + diff --git a/api/docs/tough-cookie.store.synchronous.md b/api/docs/tough-cookie.store.synchronous.md new file mode 100644 index 00000000..e764004c --- /dev/null +++ b/api/docs/tough-cookie.store.synchronous.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Store](./tough-cookie.store.md) > [synchronous](./tough-cookie.store.synchronous.md) + +## Store.synchronous property + +Store implementations that support synchronous methods must return `true`. + +**Signature:** + +```typescript +synchronous: boolean; +``` diff --git a/api/docs/tough-cookie.store.updatecookie.md b/api/docs/tough-cookie.store.updatecookie.md new file mode 100644 index 00000000..da0f09f1 --- /dev/null +++ b/api/docs/tough-cookie.store.updatecookie.md @@ -0,0 +1,81 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Store](./tough-cookie.store.md) > [updateCookie](./tough-cookie.store.updatecookie.md) + +## Store.updateCookie() method + +Update an existing [Cookie](./tough-cookie.cookie.md). The implementation MUST update the `value` for a cookie with the same `domain`, `path`, and `key`. The implementation SHOULD check that the old value in the store is equivalent to oldCookie - how the conflict is resolved is up to the store. + +**Signature:** + +```typescript +updateCookie(oldCookie: Cookie, newCookie: Cookie): Promise; +``` + +## Parameters + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +oldCookie + + + + +[Cookie](./tough-cookie.cookie.md) + + + + +the cookie that is already present in the store. + + +
+ +newCookie + + + + +[Cookie](./tough-cookie.cookie.md) + + + + +the cookie to replace the one already present in the store. + + +
+**Returns:** + +Promise<void> + +## Remarks + +- The `lastAccessed` property is always different between the two objects (to the precision possible via JavaScript's clock). + +- Both `creation` and `creationIndex` are guaranteed to be the same. + +- Stores MAY ignore or defer the `lastAccessed` change at the cost of affecting how cookies are selected for automatic deletion. + +- Stores may wish to optimize changing the `value` of the cookie in the store versus storing a new cookie. + +- The `newCookie` and `oldCookie` objects MUST NOT be modified. + diff --git a/api/docs/tough-cookie.store.updatecookie_1.md b/api/docs/tough-cookie.store.updatecookie_1.md new file mode 100644 index 00000000..528a7b36 --- /dev/null +++ b/api/docs/tough-cookie.store.updatecookie_1.md @@ -0,0 +1,97 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [Store](./tough-cookie.store.md) > [updateCookie](./tough-cookie.store.updatecookie_1.md) + +## Store.updateCookie() method + +Update an existing [Cookie](./tough-cookie.cookie.md). The implementation MUST update the `value` for a cookie with the same `domain`, `path`, and `key`. The implementation SHOULD check that the old value in the store is equivalent to oldCookie - how the conflict is resolved is up to the store. + +**Signature:** + +```typescript +updateCookie(oldCookie: Cookie, newCookie: Cookie, callback: ErrorCallback): void; +``` + +## Parameters + + + + + +
+ +Parameter + + + + +Type + + + + +Description + + +
+ +oldCookie + + + + +[Cookie](./tough-cookie.cookie.md) + + + + +the cookie that is already present in the store. + + +
+ +newCookie + + + + +[Cookie](./tough-cookie.cookie.md) + + + + +the cookie to replace the one already present in the store. + + +
+ +callback + + + + +[ErrorCallback](./tough-cookie.errorcallback.md) + + + + +A function to call when the cookie has been updated or an error has occurred. + + +
+**Returns:** + +void + +## Remarks + +- The `lastAccessed` property is always different between the two objects (to the precision possible via JavaScript's clock). + +- Both `creation` and `creationIndex` are guaranteed to be the same. + +- Stores MAY ignore or defer the `lastAccessed` change at the cost of affecting how cookies are selected for automatic deletion. + +- Stores may wish to optimize changing the `value` of the cookie in the store versus storing a new cookie. + +- The `newCookie` and `oldCookie` objects MUST NOT be modified. + diff --git a/api/docs/tough-cookie.version.md b/api/docs/tough-cookie.version.md new file mode 100644 index 00000000..bac8d963 --- /dev/null +++ b/api/docs/tough-cookie.version.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [tough-cookie](./tough-cookie.md) > [version](./tough-cookie.version.md) + +## version variable + +The version of `tough-cookie` + +**Signature:** + +```typescript +version = "5.0.0-rc.1" +``` diff --git a/api/tough-cookie.api.md b/api/tough-cookie.api.md new file mode 100644 index 00000000..fccfc150 --- /dev/null +++ b/api/tough-cookie.api.md @@ -0,0 +1,306 @@ +## API Report File for "tough-cookie" + +> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). + +```ts + +/// + +// @public +export interface Callback { + // (undocumented) + (error: Error, result?: never): void; + // (undocumented) + (error: null, result: T): void; +} + +// @public +export function canonicalDomain(domainName: Nullable): string | undefined; + +// @public +export class Cookie { + constructor(options?: CreateCookieOptions); + canonicalizedDomain(): string | undefined; + cdomain(): string | undefined; + clone(): Cookie | undefined; + cookieString(): string; + creation: Date | 'Infinity' | null; + creationIndex: number; + domain: string | null; + expires: Date | 'Infinity' | null; + expiryTime(now?: Date): number | undefined; + extensions: string[] | null; + static fromJSON(str: unknown): Cookie | undefined; + hostOnly: boolean | null; + httpOnly: boolean; + isPersistent(): boolean; + key: string; + lastAccessed: Date | 'Infinity' | null; + maxAge: number | 'Infinity' | '-Infinity' | null; + static parse(str: string, options?: ParseCookieOptions): Cookie | undefined; + path: string | null; + pathIsDefault: boolean | null; + sameSite: string | undefined; + // @internal (undocumented) + static sameSiteCanonical: { + readonly strict: "Strict"; + readonly lax: "Lax"; + }; + // @internal (undocumented) + static sameSiteLevel: { + readonly strict: 3; + readonly lax: 2; + readonly none: 1; + }; + secure: boolean; + static serializableProperties: readonly ["key", "value", "expires", "maxAge", "domain", "path", "secure", "httpOnly", "extensions", "hostOnly", "pathIsDefault", "creation", "lastAccessed", "sameSite"]; + setExpires(exp: string | Date): void; + setMaxAge(age: number): void; + toJSON(): SerializedCookie; + toString(): string; + TTL(now?: number): number; + // @beta + validate(): boolean; + value: string; +} + +// @public +export function cookieCompare(a: Cookie, b: Cookie): number; + +// @public +export class CookieJar { + constructor(store?: Nullable, options?: CreateCookieJarOptions | boolean); + clone(callback: Callback): void; + clone(newStore: Store, callback: Callback): void; + clone(newStore?: Store): Promise; + cloneSync(newStore?: Store): CookieJar | undefined; + // @internal (undocumented) + _cloneSync(newStore?: Store): CookieJar | undefined; + static deserialize(strOrObj: string | object, callback: Callback): void; + static deserialize(strOrObj: string | object, store: Store, callback: Callback): void; + static deserialize(strOrObj: string | object, store?: Store): Promise; + // @internal + static deserialize(strOrObj: string | object, store?: Store | Callback, callback?: Callback): unknown; + static deserializeSync(strOrObj: string | SerializedCookieJar, store?: Store): CookieJar; + static fromJSON(jsonString: string | SerializedCookieJar, store?: Store): CookieJar; + getCookies(url: string, callback: Callback): void; + getCookies(url: string | URL, options: GetCookiesOptions | undefined, callback: Callback): void; + getCookies(url: string | URL, options?: GetCookiesOptions | undefined): Promise; + // @internal + getCookies(url: string | URL, options: GetCookiesOptions | undefined | Callback, callback?: Callback): unknown; + getCookiesSync(url: string, options?: GetCookiesOptions): Cookie[]; + getCookieString(url: string, options: GetCookiesOptions, callback: Callback): void; + getCookieString(url: string, callback: Callback): void; + getCookieString(url: string, options?: GetCookiesOptions): Promise; + // @internal + getCookieString(url: string, options: GetCookiesOptions | Callback, callback?: Callback): unknown; + getCookieStringSync(url: string, options?: GetCookiesOptions): string; + getSetCookieStrings(url: string, callback: Callback): void; + getSetCookieStrings(url: string, options: GetCookiesOptions, callback: Callback): void; + getSetCookieStrings(url: string, options?: GetCookiesOptions): Promise; + // @internal + getSetCookieStrings(url: string, options: GetCookiesOptions, callback?: Callback): unknown; + getSetCookieStringsSync(url: string, options?: GetCookiesOptions): string[]; + // @internal + _importCookies(serialized: unknown, callback: Callback): void; + // @internal (undocumented) + _importCookiesSync(serialized: unknown): void; + readonly prefixSecurity: string; + removeAllCookies(callback: ErrorCallback): void; + removeAllCookies(): Promise; + removeAllCookiesSync(): void; + serialize(callback: Callback): void; + serialize(): Promise; + serializeSync(): SerializedCookieJar | undefined; + setCookie(cookie: string | Cookie, url: string | URL, callback: Callback): void; + setCookie(cookie: string | Cookie, url: string | URL, options: SetCookieOptions, callback: Callback): void; + setCookie(cookie: string | Cookie, url: string | URL, options?: SetCookieOptions): Promise; + // @internal + setCookie(cookie: string | Cookie, url: string | URL, options: SetCookieOptions | Callback, callback?: Callback): unknown; + setCookieSync(cookie: string | Cookie, url: string, options?: SetCookieOptions): Cookie | undefined; + readonly store: Store; + toJSON(): SerializedCookieJar | undefined; +} + +// @public +export interface CreateCookieJarOptions { + allowSpecialUseDomain?: boolean | undefined; + looseMode?: boolean | undefined; + prefixSecurity?: 'strict' | 'silent' | 'unsafe-disabled' | undefined; + rejectPublicSuffixes?: boolean | undefined; +} + +// @public +export interface CreateCookieOptions { + creation?: Date | 'Infinity' | null; + domain?: string | null; + expires?: Date | 'Infinity' | null; + extensions?: string[] | null; + hostOnly?: boolean | null; + httpOnly?: boolean; + key?: string; + lastAccessed?: Date | 'Infinity' | null; + maxAge?: number | 'Infinity' | '-Infinity' | null; + path?: string | null; + pathIsDefault?: boolean | null; + sameSite?: string | undefined; + secure?: boolean; + value?: string; +} + +// @public +export function defaultPath(path?: Nullable): string; + +// @public +export function domainMatch(domain?: Nullable, cookieDomain?: Nullable, canonicalize?: boolean): boolean | undefined; + +// @public +export interface ErrorCallback { + // (undocumented) + (error: Error | null): void; +} + +// @public +export function formatDate(date: Date): string; + +// @public +export function fromJSON(str: unknown): Cookie | undefined; + +// @public +export interface GetCookiesOptions { + allPaths?: boolean | undefined; + expire?: boolean | undefined; + http?: boolean | undefined; + sameSiteContext?: 'none' | 'lax' | 'strict' | undefined; + sort?: boolean | undefined; +} + +// @public +export function getPublicSuffix(domain: string, options?: GetPublicSuffixOptions): string | undefined; + +// @public +export interface GetPublicSuffixOptions { + allowSpecialUseDomain?: boolean | undefined; + ignoreError?: boolean | undefined; +} + +// @public +export class MemoryCookieStore extends Store { + constructor(); + findCookie(domain: Nullable, path: Nullable, key: Nullable): Promise; + findCookie(domain: Nullable, path: Nullable, key: Nullable, callback: Callback): void; + findCookies(domain: string, path: string, allowSpecialUseDomain?: boolean): Promise; + findCookies(domain: string, path: string, allowSpecialUseDomain?: boolean, callback?: Callback): void; + getAllCookies(): Promise; + getAllCookies(callback: Callback): void; + // @internal (undocumented) + idx: MemoryCookieStoreIndex; + putCookie(cookie: Cookie): Promise; + putCookie(cookie: Cookie, callback: ErrorCallback): void; + removeAllCookies(): Promise; + removeAllCookies(callback: ErrorCallback): void; + removeCookie(domain: string, path: string, key: string): Promise; + removeCookie(domain: string, path: string, key: string, callback: ErrorCallback): void; + removeCookies(domain: string, path: string): Promise; + removeCookies(domain: string, path: string, callback: ErrorCallback): void; + synchronous: boolean; + updateCookie(oldCookie: Cookie, newCookie: Cookie): Promise; + updateCookie(oldCookie: Cookie, newCookie: Cookie, callback: ErrorCallback): void; +} + +// @internal +export type MemoryCookieStoreIndex = { + [domain: string]: { + [path: string]: { + [key: string]: Cookie; + }; + }; +}; + +// @public +export type Nullable = T | null | undefined; + +// @public +export class ParameterError extends Error { +} + +// @public +export function parse(str: string, options?: ParseCookieOptions): Cookie | undefined; + +// @public +export interface ParseCookieOptions { + loose?: boolean | undefined; +} + +// @public +export function parseDate(cookieDate: Nullable): Date | undefined; + +// @public +export function pathMatch(reqPath: string, cookiePath: string): boolean; + +// @public +export function permuteDomain(domain: string, allowSpecialUseDomain?: boolean): string[] | undefined; + +// @public +export function permutePath(path: string): string[]; + +// @public +export const PrefixSecurityEnum: Readonly<{ + SILENT: "silent"; + STRICT: "strict"; + DISABLED: "unsafe-disabled"; +}>; + +// @public +export type SerializedCookie = { + key?: string; + value?: string; + [key: string]: unknown; +}; + +// @public +export interface SerializedCookieJar { + [key: string]: unknown; + cookies: SerializedCookie[]; + rejectPublicSuffixes: boolean; + storeType: string | null; + version: string; +} + +// @public +export interface SetCookieOptions { + http?: boolean | undefined; + ignoreError?: boolean | undefined; + loose?: boolean | undefined; + now?: Date | undefined; + sameSiteContext?: 'strict' | 'lax' | 'none' | undefined; +} + +// @public +export class Store { + constructor(); + findCookie(domain: Nullable, path: Nullable, key: Nullable): Promise; + findCookie(domain: Nullable, path: Nullable, key: Nullable, callback: Callback): void; + findCookies(domain: Nullable, path: Nullable, allowSpecialUseDomain?: boolean): Promise; + findCookies(domain: Nullable, path: Nullable, allowSpecialUseDomain?: boolean, callback?: Callback): void; + getAllCookies(): Promise; + getAllCookies(callback: Callback): void; + putCookie(cookie: Cookie): Promise; + putCookie(cookie: Cookie, callback: ErrorCallback): void; + removeAllCookies(): Promise; + removeAllCookies(callback: ErrorCallback): void; + removeCookie(domain: Nullable, path: Nullable, key: Nullable): Promise; + removeCookie(domain: Nullable, path: Nullable, key: Nullable, callback: ErrorCallback): void; + removeCookies(domain: string, path: Nullable): Promise; + removeCookies(domain: string, path: Nullable, callback: ErrorCallback): void; + synchronous: boolean; + updateCookie(oldCookie: Cookie, newCookie: Cookie): Promise; + updateCookie(oldCookie: Cookie, newCookie: Cookie, callback: ErrorCallback): void; +} + +// @public +export const version = "5.0.0-rc.1"; + +// (No @packageDocumentation comment for this package) + +``` diff --git a/lib/__tests__/cookieJar.spec.ts b/lib/__tests__/cookieJar.spec.ts index 208698e9..ca71bb0c 100644 --- a/lib/__tests__/cookieJar.spec.ts +++ b/lib/__tests__/cookieJar.spec.ts @@ -1322,7 +1322,7 @@ describe.each(['local', 'example', 'invalid', 'localhost', 'test'])( throw new Error('This should be an error instance') } expect(e.message).toBe( - `Cookie has domain set to the public suffix "${specialUseDomain}" which is a special use domain. To allow this, configure your CookieJar with {allowSpecialUseDomain:true, rejectPublicSuffixes: false}.`, + `Cookie has domain set to the public suffix "${specialUseDomain}" which is a special use domain. To allow this, configure your CookieJar with {allowSpecialUseDomain: true, rejectPublicSuffixes: false}.`, ) } }) @@ -1373,7 +1373,7 @@ describe.each(['local', 'example', 'invalid', 'localhost', 'test'])( throw new Error('This should be an error instance') } expect(e.message).toBe( - `Cookie has domain set to the public suffix "${specialUseDomain}" which is a special use domain. To allow this, configure your CookieJar with {allowSpecialUseDomain:true, rejectPublicSuffixes: false}.`, + `Cookie has domain set to the public suffix "${specialUseDomain}" which is a special use domain. To allow this, configure your CookieJar with {allowSpecialUseDomain: true, rejectPublicSuffixes: false}.`, ) } }) @@ -1421,7 +1421,7 @@ describe.each(['local', 'example', 'invalid', 'localhost', 'test'])( throw new Error('This should be an error instance') } expect(e.message).toBe( - `Cookie has domain set to the public suffix "${specialUseDomain}" which is a special use domain. To allow this, configure your CookieJar with {allowSpecialUseDomain:true, rejectPublicSuffixes: false}.`, + `Cookie has domain set to the public suffix "${specialUseDomain}" which is a special use domain. To allow this, configure your CookieJar with {allowSpecialUseDomain: true, rejectPublicSuffixes: false}.`, ) } }) @@ -1443,7 +1443,7 @@ describe.each(['local', 'example', 'invalid', 'localhost', 'test'])( throw new Error('This should be an error instance') } expect(e.message).toBe( - `Cookie has domain set to the public suffix "${specialUseDomain}" which is a special use domain. To allow this, configure your CookieJar with {allowSpecialUseDomain:true, rejectPublicSuffixes: false}.`, + `Cookie has domain set to the public suffix "${specialUseDomain}" which is a special use domain. To allow this, configure your CookieJar with {allowSpecialUseDomain: true, rejectPublicSuffixes: false}.`, ) } }) diff --git a/lib/__tests__/data/parser.ts b/lib/__tests__/data/parser.ts index 3c93221a..2da620c8 100644 --- a/lib/__tests__/data/parser.ts +++ b/lib/__tests__/data/parser.ts @@ -1,5 +1,4 @@ // This file just contains test data, so we don't care about the number of lines. -/* eslint-disable max-lines */ export default [ { test: '0001', diff --git a/lib/cookie/canonicalDomain.ts b/lib/cookie/canonicalDomain.ts index c709cbaa..fe9de579 100644 --- a/lib/cookie/canonicalDomain.ts +++ b/lib/cookie/canonicalDomain.ts @@ -2,12 +2,44 @@ import { toASCII } from 'punycode/punycode.js' import { IP_V6_REGEX_OBJECT } from './constants' import type { Nullable } from '../utils' -// S5.1.2 Canonicalized Host Names -export function canonicalDomain(str: Nullable): string | undefined { - if (str == null) { +/** + * Transforms a domain name into a canonical domain name. The canonical domain name is a domain name + * that has been trimmed, lowercased, stripped of leading dot, and optionally punycode-encoded + * ({@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.1.2 | Section 5.1.2 of RFC 6265}). For + * the most part, this function is idempotent (calling the function with the output from a previous call + * returns the same output). + * + * @remarks + * A canonicalized host name is the string generated by the following + * algorithm: + * + * 1. Convert the host name to a sequence of individual domain name + * labels. + * + * 2. Convert each label that is not a Non-Reserved LDH (NR-LDH) label, + * to an A-label (see Section 2.3.2.1 of [RFC5890] for the former + * and latter), or to a "punycode label" (a label resulting from the + * "ToASCII" conversion in Section 4 of [RFC3490]), as appropriate + * (see Section 6.3 of this specification). + * + * 3. Concatenate the resulting labels, separated by a %x2E (".") + * character. + * + * @example + * ``` + * canonicalDomain('.EXAMPLE.com') === 'example.com' + * ``` + * + * @param domainName - the domain name to generate the canonical domain from + * @public + */ +export function canonicalDomain( + domainName: Nullable, +): string | undefined { + if (domainName == null) { return undefined } - let _str = str.trim().replace(/^\./, '') // S4.1.2.3 & S5.2.3: ignore leading . + let _str = domainName.trim().replace(/^\./, '') // S4.1.2.3 & S5.2.3: ignore leading . if (IP_V6_REGEX_OBJECT.test(_str)) { _str = _str.replace('[', '').replace(']', '') diff --git a/lib/cookie/constants.ts b/lib/cookie/constants.ts index 278449b3..ed08ac80 100644 --- a/lib/cookie/constants.ts +++ b/lib/cookie/constants.ts @@ -1,3 +1,16 @@ +/** + * Cookie prefixes are a way to indicate that a given cookie was set with a set of attributes simply by inspecting the + * first few characters of the cookie's name. These are defined in {@link https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-13#section-4.1.3 | RFC6265bis - Section 4.1.3}. + * + * The following values can be used to configure how a {@link CookieJar} enforces attribute restrictions for Cookie prefixes: + * + * - `silent` - Enable cookie prefix checking but silently ignores the cookie if conditions are not met. This is the default configuration for a {@link CookieJar}. + * + * - `strict` - Enables cookie prefix checking and will raise an error if conditions are not met. + * + * - `unsafe-disabled` - Disables cookie prefix checking. + * @public + */ export const PrefixSecurityEnum = Object.freeze({ SILENT: 'silent', STRICT: 'strict', @@ -21,15 +34,38 @@ const IP_V6_REGEX = ` .trim() export const IP_V6_REGEX_OBJECT = new RegExp(`^${IP_V6_REGEX}$`) +/** + * A JSON representation of a {@link CookieJar}. + * @public + */ export interface SerializedCookieJar { + /** + * The version of `tough-cookie` used during serialization. + */ version: string + /** + * The name of the store used during serialization. + */ storeType: string | null + /** + * The value of {@link CreateCookieJarOptions.rejectPublicSuffixes} configured on the {@link CookieJar}. + */ rejectPublicSuffixes: boolean + /** + * Other configuration settings on the {@link CookieJar}. + */ [key: string]: unknown + /** + * The list of {@link Cookie} values serialized as JSON objects. + */ cookies: SerializedCookie[] } -export interface SerializedCookie { +/** + * A JSON object that is created when {@link Cookie.toJSON} is called. This object will contain the properties defined in {@link Cookie.serializableProperties}. + * @public + */ +export type SerializedCookie = { key?: string value?: string [key: string]: unknown diff --git a/lib/cookie/cookie.ts b/lib/cookie/cookie.ts index 782234ff..3852ee79 100644 --- a/lib/cookie/cookie.ts +++ b/lib/cookie/cookie.ts @@ -28,10 +28,6 @@ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. */ - -// This file was too big before we added max-lines, and it's ongoing work to reduce its size. -/* eslint max-lines: [1, 800] */ - import { getPublicSuffix } from '../getPublicSuffix' import * as validators from '../validators' import { inOperator } from '../utils' @@ -111,16 +107,17 @@ function parseCookiePair( return c } -type ParseCookieOptions = { +/** + * Optional configuration to be used when parsing cookies. + * @public + */ +export interface ParseCookieOptions { + /** + * If `true` then keyless cookies like `=abc` and `=` which are not RFC-compliant will be parsed. + */ loose?: boolean | undefined } -/** - * Parses a string into a Cookie object. - * @param str the Set-Cookie header or a Cookie string to parse. Note: when parsing a Cookie header it must be split by ';' before each Cookie string can be parsed. - * @param options configures strict or loose mode for cookie parsing - * @returns `Cookie` object when parsing succeeds, `undefined` when parsing fails. - */ function parse(str: string, options?: ParseCookieOptions): Cookie | undefined { if (validators.isEmptyString(str) || !validators.isString(str)) { return undefined @@ -371,16 +368,40 @@ function fromJSON(str: unknown): Cookie | undefined { return c } -type CreateCookieOptions = Omit< - { - // Assume that all non-method attributes on the class can be configured, except creationIndex. - // eslint-disable-next-line @typescript-eslint/no-explicit-any - [K in keyof Cookie as Cookie[K] extends (...args: any[]) => any - ? never - : K]?: Cookie[K] - }, - 'creationIndex' -> +/** + * Configurable values that can be set when creating a {@link Cookie}. + * @public + */ +export interface CreateCookieOptions { + /** {@inheritDoc Cookie.key} */ + key?: string + /** {@inheritDoc Cookie.value} */ + value?: string + /** {@inheritDoc Cookie.expires} */ + expires?: Date | 'Infinity' | null + /** {@inheritDoc Cookie.maxAge} */ + maxAge?: number | 'Infinity' | '-Infinity' | null + /** {@inheritDoc Cookie.domain} */ + domain?: string | null + /** {@inheritDoc Cookie.path} */ + path?: string | null + /** {@inheritDoc Cookie.secure} */ + secure?: boolean + /** {@inheritDoc Cookie.httpOnly} */ + httpOnly?: boolean + /** {@inheritDoc Cookie.extensions} */ + extensions?: string[] | null + /** {@inheritDoc Cookie.creation} */ + creation?: Date | 'Infinity' | null + /** {@inheritDoc Cookie.hostOnly} */ + hostOnly?: boolean | null + /** {@inheritDoc Cookie.pathIsDefault} */ + pathIsDefault?: boolean | null + /** {@inheritDoc Cookie.lastAccessed} */ + lastAccessed?: Date | 'Infinity' | null + /** {@inheritDoc Cookie.sameSite} */ + sameSite?: string | undefined +} const cookieDefaults = { // the order in which the RFC has them: @@ -401,23 +422,101 @@ const cookieDefaults = { sameSite: undefined, } as const satisfies Required +/** + * An HTTP cookie (web cookie, browser cookie) is a small piece of data that a server sends to a user's web browser. + * It is defined in {@link https://www.rfc-editor.org/rfc/rfc6265.html | RFC6265}. + * @public + */ export class Cookie { + /** + * The name or key of the cookie + */ key: string + /** + * The value of the cookie + */ value: string + /** + * The 'Expires' attribute of the cookie + * (See {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.1 | RFC6265 Section 5.2.1}). + */ expires: Date | 'Infinity' | null + /** + * The 'Max-Age' attribute of the cookie + * (See {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.2 | RFC6265 Section 5.2.2}). + */ maxAge: number | 'Infinity' | '-Infinity' | null + /** + * The 'Domain' attribute of the cookie represents the domain the cookie belongs to + * (See {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.3 | RFC6265 Section 5.2.3}). + */ domain: string | null + /** + * The 'Path' attribute of the cookie represents the path of the cookie + * (See {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.4 | RFC6265 Section 5.2.4}). + */ path: string | null + /** + * The 'Secure' flag of the cookie indicates if the scope of the cookie is + * limited to secure channels (e.g.; HTTPS) or not + * (See {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.5 | RFC6265 Section 5.2.5}). + */ secure: boolean + /** + * The 'HttpOnly' flag of the cookie indicates if the cookie is inaccessible to + * client scripts or not + * (See {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.6 | RFC6265 Section 5.2.6}). + */ httpOnly: boolean + /** + * Contains attributes which are not part of the defined spec but match the `extension-av` syntax + * defined in Section 4.1.1 of RFC6265 + * (See {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-4.1.1 | RFC6265 Section 4.1.1}). + */ extensions: string[] | null + /** + * Set to the date and time when a Cookie is initially stored or a matching cookie is + * received that replaces an existing cookie + * (See {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.3 | RFC6265 Section 5.3}). + * + * Also used to maintain ordering among cookies. Among cookies that have equal-length path fields, + * cookies with earlier creation-times are listed before cookies with later creation-times + * (See {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.4 | RFC6265 Section 5.4}). + */ creation: Date | 'Infinity' | null + /** + * A global counter used to break ordering ties between two cookies that have equal-length path fields + * and the same creation-time. + */ creationIndex: number + /** + * A boolean flag indicating if a cookie is a host-only cookie (i.e.; when the request's host exactly + * matches the domain of the cookie) or not + * (See {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.3 | RFC6265 Section 5.3}). + */ hostOnly: boolean | null + /** + * A boolean flag indicating if a cookie had no 'Path' attribute and the default path + * was used + * (See {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.2.4 | RFC6265 Section 5.2.4}). + */ pathIsDefault: boolean | null + /** + * Set to the date and time when a cookie was initially stored ({@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.3 | RFC6265 Section 5.3}) and updated whenever + * the cookie is retrieved from the {@link CookieJar} ({@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.4 | RFC6265 Section 5.4}). + */ lastAccessed: Date | 'Infinity' | null + /** + * The 'SameSite' attribute of a cookie as defined in RFC6265bis + * (See {@link https://www.ietf.org/archive/id/draft-ietf-httpbis-rfc6265bis-13.html#section-5.2 | RFC6265bis (v13) Section 5.2 }). + */ sameSite: string | undefined + /** + * Create a new Cookie instance. + * @public + * @param options - The attributes to set on the cookie + */ constructor(options: CreateCookieOptions = {}) { this.key = options.key ?? cookieDefaults.key this.value = options.value ?? cookieDefaults.value @@ -461,6 +560,15 @@ export class Cookie { return `Cookie="${this.toString()}; hostOnly=${hostOnly}; aAge=${accessAge}; cAge=${createAge}"` } + /** + * For convenience in using `JSON.stringify(cookie)`. Returns a plain-old Object that can be JSON-serialized. + * + * @remarks + * - Any `Date` properties (such as {@link Cookie.expires}, {@link Cookie.creation}, and {@link Cookie.lastAccessed}) are exported in ISO format (`Date.toISOString()`). + * + * - Custom Cookie properties are discarded. In tough-cookie 1.x, since there was no {@link Cookie.toJSON} method explicitly defined, all enumerable properties were captured. + * If you want a property to be serialized, add the property name to {@link Cookie.serializableProperties}. + */ toJSON(): SerializedCookie { const obj: SerializedCookie = {} @@ -531,10 +639,23 @@ export class Cookie { return obj } + /** + * Does a deep clone of this cookie, implemented exactly as `Cookie.fromJSON(cookie.toJSON())`. + * @public + */ clone(): Cookie | undefined { return fromJSON(this.toJSON()) } + /** + * Validates cookie attributes for semantic correctness. Useful for "lint" checking any `Set-Cookie` headers you generate. + * For now, it returns a boolean, but eventually could return a reason string. + * + * @remarks + * Works for a few things, but is by no means comprehensive. + * + * @beta + */ validate(): boolean { if (this.value == null || !COOKIE_OCTETS.test(this.value)) { return false @@ -571,6 +692,15 @@ export class Cookie { return true } + /** + * Sets the 'Expires' attribute on a cookie. + * + * @remarks + * When given a `string` value it will be parsed with {@link parseDate}. If the value can't be parsed as a cookie date + * then the 'Expires' attribute will be set to `"Infinity"`. + * + * @param exp - the new value for the 'Expires' attribute of the cookie. + */ setExpires(exp: string | Date): void { if (exp instanceof Date) { this.expires = exp @@ -579,6 +709,14 @@ export class Cookie { } } + /** + * Sets the 'Max-Age' attribute (in seconds) on a cookie. + * + * @remarks + * Coerces `-Infinity` to `"-Infinity"` and `Infinity` to `"Infinity"` so it can be serialized to JSON. + * + * @param age - the new value for the 'Max-Age' attribute (in seconds). + */ setMaxAge(age: number): void { if (age === Infinity) { this.maxAge = 'Infinity' @@ -589,6 +727,10 @@ export class Cookie { } } + /** + * Encodes to a `Cookie` header value (specifically, the {@link Cookie.key} and {@link Cookie.value} properties joined with "="). + * @public + */ cookieString(): string { const val = this.value ?? '' if (this.key) { @@ -597,7 +739,10 @@ export class Cookie { return val } - // gives Set-Cookie header format + /** + * Encodes to a `Set-Cookie header` value. + * @public + */ toString(): string { let str = this.cookieString() @@ -648,16 +793,29 @@ export class Cookie { return str } - // TTL() partially replaces the "expiry-time" parts of S5.3 step 3 (setCookie() - // elsewhere) - // S5.3 says to give the "latest representable date" for which we use Infinity - // For "expired" we use 0 + /** + * Computes the TTL relative to now (milliseconds). + * + * @remarks + * - `Infinity` is returned for cookies without an explicit expiry + * + * - `0` is returned if the cookie is expired. + * + * - Otherwise a time-to-live in milliseconds is returned. + * + * @param now - passing an explicit value is mostly used for testing purposes since this defaults to the `Date.now()` + * @public + */ TTL(now: number = Date.now()): number { - /* RFC6265 S4.1.2.2 If a cookie has both the Max-Age and the Expires - * attribute, the Max-Age attribute has precedence and controls the - * expiration date of the cookie. - * (Concurs with S5.3 step 3) - */ + // TTL() partially replaces the "expiry-time" parts of S5.3 step 3 (setCookie() + // elsewhere) + // S5.3 says to give the "latest representable date" for which we use Infinity + // For "expired" we use 0 + // ----- + // RFC6265 S4.1.2.2 If a cookie has both the Max-Age and the Expires + // attribute, the Max-Age attribute has precedence and controls the + // expiration date of the cookie. + // (Concurs with S5.3 step 3) if (this.maxAge != null && typeof this.maxAge === 'number') { return this.maxAge <= 0 ? 0 : this.maxAge * 1000 } @@ -670,9 +828,18 @@ export class Cookie { return (expires?.getTime() ?? now) - (now || Date.now()) } - // expiryTime() replaces the "expiry-time" parts of S5.3 step 3 (setCookie() - // elsewhere) + /** + * Computes the absolute unix-epoch milliseconds that this cookie expires. + * + * The "Max-Age" attribute takes precedence over "Expires" (as per the RFC). The {@link Cookie.lastAccessed} attribute + * (or the `now` parameter if given) is used to offset the {@link Cookie.maxAge} attribute. + * + * If Expires ({@link Cookie.expires}) is set, that's returned. + * + * @param now - can be used to provide a time offset (instead of {@link Cookie.lastAccessed}) to use when calculating the "Max-Age" value + */ expiryTime(now?: Date): number | undefined { + // expiryTime() replaces the "expiry-time" parts of S5.3 step 3 (setCookie() elsewhere) if (this.maxAge != null) { const relativeTo = now || this.lastAccessed || new Date() const maxAge = typeof this.maxAge === 'number' ? this.maxAge : -Infinity @@ -690,37 +857,120 @@ export class Cookie { return this.expires ? this.expires.getTime() : undefined } - // This replaces the "persistent-flag" parts of S5.3 step 3 + /** + * Indicates if the cookie has been persisted to a store or not. + * @public + */ isPersistent(): boolean { + // This replaces the "persistent-flag" parts of S5.3 step 3 return this.maxAge != null || this.expires != 'Infinity' } - // Mostly S5.1.2 and S5.2.3: + /** + * Calls {@link canonicalDomain} with the {@link Cookie.domain} property. + * @public + */ canonicalizedDomain(): string | undefined { + // Mostly S5.1.2 and S5.2.3: return canonicalDomain(this.domain) } + /** + * Alias for {@link Cookie.canonicalizedDomain} + * @public + */ cdomain(): string | undefined { return canonicalDomain(this.domain) } - static parse = parse + /** + * Parses a string into a Cookie object. + * + * @remarks + * Note: when parsing a `Cookie` header it must be split by ';' before each Cookie string can be parsed. + * + * @example + * ``` + * // parse a `Set-Cookie` header + * const setCookieHeader = 'a=bcd; Expires=Tue, 18 Oct 2011 07:05:03 GMT' + * const cookie = Cookie.parse(setCookieHeader) + * cookie.key === 'a' + * cookie.value === 'bcd' + * cookie.expires === new Date(Date.parse('Tue, 18 Oct 2011 07:05:03 GMT')) + * ``` + * + * @example + * ``` + * // parse a `Cookie` header + * const cookieHeader = 'name=value; name2=value2; name3=value3' + * const cookies = cookieHeader.split(';').map(Cookie.parse) + * cookies[0].name === 'name' + * cookies[0].value === 'value' + * cookies[1].name === 'name2' + * cookies[1].value === 'value2' + * cookies[2].name === 'name3' + * cookies[2].value === 'value3' + * ``` + * + * @param str - The `Set-Cookie` header or a Cookie string to parse. + * @param options - Configures `strict` or `loose` mode for cookie parsing + */ + static parse(str: string, options?: ParseCookieOptions): Cookie | undefined { + return parse(str, options) + } - static fromJSON = fromJSON + /** + * Does the reverse of {@link Cookie.toJSON}. + * + * @remarks + * Any Date properties (such as .expires, .creation, and .lastAccessed) are parsed via Date.parse, not tough-cookie's parseDate, since ISO timestamps are being handled at this layer. + * + * @example + * ``` + * const json = JSON.stringify({ + * key: 'alpha', + * value: 'beta', + * domain: 'example.com', + * path: '/foo', + * expires: '2038-01-19T03:14:07.000Z', + * }) + * const cookie = Cookie.fromJSON(json) + * cookie.key === 'alpha' + * cookie.value === 'beta' + * cookie.domain === 'example.com' + * cookie.path === '/foo' + * cookie.expires === new Date(Date.parse('2038-01-19T03:14:07.000Z')) + * ``` + * + * @param str - An unparsed JSON string or a value that has already been parsed as JSON + */ + static fromJSON(str: unknown): Cookie | undefined { + return fromJSON(str) + } - static cookiesCreated = 0 + private static cookiesCreated = 0 + /** + * @internal + */ static sameSiteLevel = { strict: 3, lax: 2, none: 1, } as const + /** + * @internal + */ static sameSiteCanonical = { strict: 'Strict', lax: 'Lax', } as const + /** + * Cookie properties that will be serialized when using {@link Cookie.fromJSON} and {@link Cookie.toJSON}. + * @public + */ static serializableProperties = [ 'key', 'value', diff --git a/lib/cookie/cookieCompare.ts b/lib/cookie/cookieCompare.ts index f5a1a16a..cc0daaf6 100644 --- a/lib/cookie/cookieCompare.ts +++ b/lib/cookie/cookieCompare.ts @@ -1,14 +1,6 @@ import { safeToString } from '../utils' import * as validators from '../validators' import type { Cookie } from './cookie' -/* Section 5.4 part 2: - * "* Cookies with longer paths are listed before cookies with - * shorter paths. - * - * * Among cookies that have equal-length path fields, cookies with - * earlier creation-times are listed before cookies with later - * creation-times." - */ /** * The maximum timestamp a cookie, in milliseconds. The value is (2^31 - 1) seconds since the Unix @@ -16,7 +8,62 @@ import type { Cookie } from './cookie' */ const MAX_TIME = 2147483647000 -/** Compares two cookies for sorting. */ +/** + * A comparison function that can be used with {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort | Array.sort()}, + * which orders a list of cookies into the recommended order given in Step 2 of {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.4 | RFC6265 - Section 5.4}. + * + * The sort algorithm is, in order of precedence: + * + * - Longest {@link Cookie.path} + * + * - Oldest {@link Cookie.creation} (which has a 1-ms precision, same as Date) + * + * - Lowest {@link Cookie.creationIndex} (to get beyond the 1-ms precision) + * + * @remarks + * ### RFC6265 - Section 5.4 - Step 2 + * + * The user agent SHOULD sort the cookie-list in the following order: + * + * - Cookies with longer paths are listed before cookies with shorter paths. + * + * - Among cookies that have equal-length path fields, cookies with + * earlier creation-times are listed before cookies with later + * creation-times. + * + * NOTE: Not all user agents sort the cookie-list in this order, but + * this order reflects common practice when this document was + * written, and, historically, there have been servers that + * (erroneously) depended on this order. + * + * ### Custom Store Implementors + * + * Since the JavaScript Date is limited to a 1-ms precision, cookies within the same millisecond are entirely possible. + * This is especially true when using the `now` option to `CookieJar.setCookie(...)`. The {@link Cookie.creationIndex} + * property is a per-process global counter, assigned during construction with `new Cookie()`, which preserves the spirit + * of the RFC sorting: older cookies go first. This works great for {@link MemoryCookieStore} since `Set-Cookie` headers + * are parsed in order, but is not so great for distributed systems. + * + * Sophisticated Stores may wish to set this to some other + * logical clock so that if cookies `A` and `B` are created in the same millisecond, but cookie `A` is created before + * cookie `B`, then `A.creationIndex < B.creationIndex`. + * + * @example + * ``` + * const cookies = [ + * new Cookie({ key: 'a', value: '' }), + * new Cookie({ key: 'b', value: '' }), + * new Cookie({ key: 'c', value: '', path: '/path' }), + * new Cookie({ key: 'd', value: '', path: '/path' }), + * ] + * cookies.sort(cookieCompare) + * // cookie sort order would be ['c', 'd', 'a', 'b'] + * ``` + * + * @param a - the first Cookie for comparison + * @param b - the second Cookie for comparison + * @public + */ export function cookieCompare(a: Cookie, b: Cookie): number { validators.validate(validators.isObject(a), safeToString(a)) validators.validate(validators.isObject(b), safeToString(b)) diff --git a/lib/cookie/cookieJar.ts b/lib/cookie/cookieJar.ts index ec881ae9..3e47e0ce 100644 --- a/lib/cookie/cookieJar.ts +++ b/lib/cookie/cookieJar.ts @@ -9,10 +9,10 @@ import { pathMatch } from '../pathMatch' import { Cookie } from './cookie' import { Callback, - ErrorCallback, - Nullable, createPromiseCallback, + ErrorCallback, inOperator, + Nullable, safeToString, } from '../utils' import { canonicalDomain } from './canonicalDomain' @@ -26,9 +26,6 @@ import { domainMatch } from './domainMatch' import { cookieCompare } from './cookieCompare' import { version } from '../version' -// This file was too big before we added max-lines, and it's ongoing work to reduce its size. -/* eslint max-lines: [1, 1200] */ - const defaultSetCookieOptions: SetCookieOptions = { loose: false, sameSiteContext: undefined, @@ -36,6 +33,59 @@ const defaultSetCookieOptions: SetCookieOptions = { http: true, } +/** + * Configuration options used when calling `CookieJar.setCookie(...)` + * @public + */ +export interface SetCookieOptions { + /** + * Controls if a cookie string should be parsed using `loose` mode or not. + * See {@link Cookie.parse} and {@link ParseCookieOptions} for more details. + * + * Defaults to `false` if not provided. + */ + loose?: boolean | undefined + /** + * Set this to 'none', 'lax', or 'strict' to enforce SameSite cookies upon storage. + * + * - `'strict'` - If the request is on the same "site for cookies" (see the RFC draft + * for more information), pass this option to add a layer of defense against CSRF. + * + * - `'lax'` - If the request is from another site, but is directly because of navigation + * by the user, such as, `` or ``, then use `lax`. + * + * - `'none'` - This indicates a cross-origin request. + * + * - `undefined` - SameSite is not be enforced! This can be a valid use-case for when + * CSRF isn't in the threat model of the system being built. + * + * Defaults to `undefined` if not provided. + * + * @remarks + * - It is highly recommended that you read {@link https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02##section-8.8 | RFC6265bis - Section 8.8} + * which discusses security considerations and defence on SameSite cookies in depth. + */ + sameSiteContext?: 'strict' | 'lax' | 'none' | undefined + /** + * Silently ignore things like parse errors and invalid domains. Store errors aren't ignored by this option. + * + * Defaults to `false` if not provided. + */ + ignoreError?: boolean | undefined + /** + * Indicates if this is an HTTP or non-HTTP API. Affects HttpOnly cookies. + * + * Defaults to `true` if not provided. + */ + http?: boolean | undefined + /** + * Forces the cookie creation and access time of cookies to this value when stored. + * + * Defaults to `Date.now()` if not provided. + */ + now?: Date | undefined +} + const defaultGetCookieOptions: GetCookiesOptions = { http: true, expire: true, @@ -44,26 +94,96 @@ const defaultGetCookieOptions: GetCookiesOptions = { sort: undefined, } -type SetCookieOptions = { - loose?: boolean | undefined - sameSiteContext?: 'strict' | 'lax' | 'none' | undefined - ignoreError?: boolean | undefined - http?: boolean | undefined - now?: Date | undefined -} - -type GetCookiesOptions = { +/** + * Configuration options used when calling `CookieJar.getCookies(...)`. + * @public + */ +export interface GetCookiesOptions { + /** + * Indicates if this is an HTTP or non-HTTP API. Affects HttpOnly cookies. + * + * Defaults to `true` if not provided. + */ http?: boolean | undefined + /** + * Perform `expiry-time` checking of cookies and asynchronously remove expired + * cookies from the store. + * + * @remarks + * - Using `false` returns expired cookies and does not remove them from the + * store which is potentially useful for replaying `Set-Cookie` headers. + * + * Defaults to `true` if not provided. + */ expire?: boolean | undefined + /** + * If `true`, do not scope cookies by path. If `false`, then RFC-compliant path scoping will be used. + * + * @remarks + * - May not be supported by the underlying store (the default {@link MemoryCookieStore} supports it). + * + * Defaults to `false` if not provided. + */ allPaths?: boolean | undefined + /** + * Set this to 'none', 'lax', or 'strict' to enforce SameSite cookies upon retrieval. + * + * - `'strict'` - If the request is on the same "site for cookies" (see the RFC draft + * for more information), pass this option to add a layer of defense against CSRF. + * + * - `'lax'` - If the request is from another site, but is directly because of navigation + * by the user, such as, `` or ``, then use `lax`. + * + * - `'none'` - This indicates a cross-origin request. + * + * - `undefined` - SameSite is not be enforced! This can be a valid use-case for when + * CSRF isn't in the threat model of the system being built. + * + * Defaults to `undefined` if not provided. + * + * @remarks + * - It is highly recommended that you read {@link https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-02##section-8.8 | RFC6265bis - Section 8.8} + * which discusses security considerations and defence on SameSite cookies in depth. + */ sameSiteContext?: 'none' | 'lax' | 'strict' | undefined + /** + * Flag to indicate if the returned cookies should be sorted or not. + * + * Defaults to `undefined` if not provided. + */ sort?: boolean | undefined } -type CreateCookieJarOptions = { +/** + * Configuration settings to be used with a {@link CookieJar}. + * @public + */ +export interface CreateCookieJarOptions { + /** + * Reject cookies that match those defined in the {@link https://publicsuffix.org/ | Public Suffix List} (e.g.; domains like "com" and "co.uk"). + * + * Defaults to `true` if not specified. + */ rejectPublicSuffixes?: boolean | undefined + /** + * Accept malformed cookies like `bar` and `=bar`, which have an implied empty name but are not RFC-compliant. + * + * Defaults to `false` if not specified. + */ looseMode?: boolean | undefined + /** + * Controls how cookie prefixes are handled. See {@link PrefixSecurityEnum}. + * + * Defaults to `silent` if not specified. + */ prefixSecurity?: 'strict' | 'silent' | 'unsafe-disabled' | undefined + /** + * Accepts {@link https://datatracker.ietf.org/doc/html/rfc6761 | special-use domains } such as `local`. + * This is not in the standard, but is used sometimes on the web and is accepted by most browsers. It is + * also useful for testing purposes. + * + * Defaults to `true` if not specified. + */ allowSpecialUseDomain?: boolean | undefined } @@ -154,13 +274,38 @@ function getNormalizedPrefixSecurity( return PrefixSecurityEnum.SILENT } +/** + * A CookieJar is for storage and retrieval of {@link Cookie} objects as defined in + * {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.3 | RFC6265 - Section 5.3}. + * + * It also supports a pluggable persistence layer via {@link Store}. + * @public + */ export class CookieJar { - readonly store: Store private readonly rejectPublicSuffixes: boolean private readonly enableLooseMode: boolean private readonly allowSpecialUseDomain: boolean + + /** + * The configured {@link Store} for the {@link CookieJar}. + */ + readonly store: Store + + /** + * The configured {@link PrefixSecurityEnum} value for the {@link CookieJar}. + */ readonly prefixSecurity: string + /** + * Creates a new `CookieJar` instance. + * + * @remarks + * - If a custom store is not passed to the constructor, an in-memory store ({@link MemoryCookieStore} will be created and used. + * - If a boolean value is passed as the `options` parameter, this is equivalent to passing `{ rejectPublicSuffixes: }` + * + * @param store - a custom {@link Store} implementation (defaults to {@link MemoryCookieStore}) + * @param options - configures how cookies are processed by the cookie jar + */ constructor( store?: Nullable, options?: CreateCookieJarOptions | boolean, @@ -200,30 +345,89 @@ export class CookieJar { return syncResult } - // TODO: We *could* add overloads based on the value of `options.ignoreError`, such that we only - // return `undefined` when `ignoreError` is true. But would that be excessive overloading? + /** + * Attempt to set the {@link Cookie} in the {@link CookieJar}. + * + * @remarks + * - If successfully persisted, the {@link Cookie} will have updated + * {@link Cookie.creation}, {@link Cookie.lastAccessed} and {@link Cookie.hostOnly} + * properties. + * + * - As per the RFC, the {@link Cookie.hostOnly} flag is set if there was no `Domain={value}` + * atttribute on the cookie string. The {@link Cookie.domain} property is set to the + * fully-qualified hostname of `currentUrl` in this case. Matching this cookie requires an + * exact hostname match (not a {@link domainMatch} as per usual) + * + * @param cookie - The cookie object or cookie string to store. A string value will be parsed into a cookie using {@link Cookie.parse}. + * @param url - The domain to store the cookie with. + * @param callback - A function to call after a cookie has been successfully stored. + * @public + */ setCookie( cookie: string | Cookie, url: string | URL, callback: Callback, ): void + /** + * Attempt to set the {@link Cookie} in the {@link CookieJar}. + * + * @remarks + * - If successfully persisted, the {@link Cookie} will have updated + * {@link Cookie.creation}, {@link Cookie.lastAccessed} and {@link Cookie.hostOnly} + * properties. + * + * - As per the RFC, the {@link Cookie.hostOnly} flag is set if there was no `Domain={value}` + * atttribute on the cookie string. The {@link Cookie.domain} property is set to the + * fully-qualified hostname of `currentUrl` in this case. Matching this cookie requires an + * exact hostname match (not a {@link domainMatch} as per usual) + * + * @param cookie - The cookie object or cookie string to store. A string value will be parsed into a cookie using {@link Cookie.parse}. + * @param url - The domain to store the cookie with. + * @param options - Configuration settings to use when storing the cookie. + * @param callback - A function to call after a cookie has been successfully stored. + * @public + */ setCookie( cookie: string | Cookie, url: string | URL, options: SetCookieOptions, callback: Callback, ): void + /** + * Attempt to set the {@link Cookie} in the {@link CookieJar}. + * + * @remarks + * - If successfully persisted, the {@link Cookie} will have updated + * {@link Cookie.creation}, {@link Cookie.lastAccessed} and {@link Cookie.hostOnly} + * properties. + * + * - As per the RFC, the {@link Cookie.hostOnly} flag is set if there was no `Domain={value}` + * atttribute on the cookie string. The {@link Cookie.domain} property is set to the + * fully-qualified hostname of `currentUrl` in this case. Matching this cookie requires an + * exact hostname match (not a {@link domainMatch} as per usual) + * + * @param cookie - The cookie object or cookie string to store. A string value will be parsed into a cookie using {@link Cookie.parse}. + * @param url - The domain to store the cookie with. + * @param options - Configuration settings to use when storing the cookie. + * @public + */ setCookie( cookie: string | Cookie, url: string | URL, options?: SetCookieOptions, ): Promise + /** + * @internal No doc because this is an overload that supports the implementation + */ setCookie( cookie: string | Cookie, url: string | URL, options: SetCookieOptions | Callback, callback?: Callback, ): unknown + /** + * @internal No doc because this is the overload implementation + */ setCookie( cookie: string | Cookie, url: string | URL, @@ -496,6 +700,27 @@ export class CookieJar { store.findCookie(cookie.domain, cookie.path, cookie.key, withCookie) return promiseCallback.promise } + + /** + * Synchronously attempt to set the {@link Cookie} in the {@link CookieJar}. + * + * Note: Only works if the configured {@link Store} is also synchronous. + * + * @remarks + * - If successfully persisted, the {@link Cookie} will have updated + * {@link Cookie.creation}, {@link Cookie.lastAccessed} and {@link Cookie.hostOnly} + * properties. + * + * - As per the RFC, the {@link Cookie.hostOnly} flag is set if there was no `Domain={value}` + * atttribute on the cookie string. The {@link Cookie.domain} property is set to the + * fully-qualified hostname of `currentUrl` in this case. Matching this cookie requires an + * exact hostname match (not a {@link domainMatch} as per usual) + * + * @param cookie - The cookie object or cookie string to store. A string value will be parsed into a cookie using {@link Cookie.parse}. + * @param url - The domain to store the cookie with. + * @param options - Configuration settings to use when storing the cookie. + * @public + */ setCookieSync( cookie: string | Cookie, url: string, @@ -507,27 +732,70 @@ export class CookieJar { return this.callSync(setCookieFn) } - // RFC6365 S5.4 + /** + * Retrieve the list of cookies that can be sent in a Cookie header for the + * current URL. + * + * @remarks + * - The array of cookies returned will be sorted according to {@link cookieCompare}. + * + * - The {@link Cookie.lastAccessed} property will be updated on all returned cookies. + * + * @param url - The domain to store the cookie with. + * @param callback - A function to call after a cookie has been successfully retrieved. + */ getCookies(url: string, callback: Callback): void + /** + * Retrieve the list of cookies that can be sent in a Cookie header for the + * current URL. + * + * @remarks + * - The array of cookies returned will be sorted according to {@link cookieCompare}. + * + * - The {@link Cookie.lastAccessed} property will be updated on all returned cookies. + * + * @param url - The domain to store the cookie with. + * @param options - Configuration settings to use when retrieving the cookies. + * @param callback - A function to call after a cookie has been successfully retrieved. + */ getCookies( url: string | URL, options: GetCookiesOptions | undefined, callback: Callback, ): void + /** + * Retrieve the list of cookies that can be sent in a Cookie header for the + * current URL. + * + * @remarks + * - The array of cookies returned will be sorted according to {@link cookieCompare}. + * + * - The {@link Cookie.lastAccessed} property will be updated on all returned cookies. + * + * @param url - The domain to store the cookie with. + * @param options - Configuration settings to use when retrieving the cookies. + */ getCookies( url: string | URL, options?: GetCookiesOptions | undefined, ): Promise + /** + * @internal No doc because this is an overload that supports the implementation + */ getCookies( url: string | URL, options: GetCookiesOptions | undefined | Callback, callback?: Callback, ): unknown + /** + * @internal No doc because this is the overload implementation + */ getCookies( url: string | URL, options?: GetCookiesOptions | Callback, callback?: Callback, ): unknown { + // RFC6365 S5.4 if (typeof options === 'function') { callback = options options = defaultGetCookieOptions @@ -666,22 +934,65 @@ export class CookieJar { return promiseCallback.promise } + + /** + * Synchronously retrieve the list of cookies that can be sent in a Cookie header for the + * current URL. + * + * Note: Only works if the configured Store is also synchronous. + * + * @remarks + * - The array of cookies returned will be sorted according to {@link cookieCompare}. + * + * - The {@link Cookie.lastAccessed} property will be updated on all returned cookies. + * + * @param url - The domain to store the cookie with. + * @param options - Configuration settings to use when retrieving the cookies. + */ getCookiesSync(url: string, options?: GetCookiesOptions): Cookie[] { return this.callSync(this.getCookies.bind(this, url, options)) ?? [] } + /** + * Accepts the same options as `.getCookies()` but returns a string suitable for a + * `Cookie` header rather than an Array. + * + * @param url - The domain to store the cookie with. + * @param options - Configuration settings to use when retrieving the cookies. + * @param callback - A function to call after the `Cookie` header string has been created. + */ getCookieString( url: string, options: GetCookiesOptions, callback: Callback, ): void + /** + * Accepts the same options as `.getCookies()` but returns a string suitable for a + * `Cookie` header rather than an Array. + * + * @param url - The domain to store the cookie with. + * @param callback - A function to call after the `Cookie` header string has been created. + */ getCookieString(url: string, callback: Callback): void + /** + * Accepts the same options as `.getCookies()` but returns a string suitable for a + * `Cookie` header rather than an Array. + * + * @param url - The domain to store the cookie with. + * @param options - Configuration settings to use when retrieving the cookies. + */ getCookieString(url: string, options?: GetCookiesOptions): Promise + /** + * @internal No doc because this is an overload that supports the implementation + */ getCookieString( url: string, options: GetCookiesOptions | Callback, callback?: Callback, ): unknown + /** + * @internal No doc because this is the overload implementation + */ getCookieString( url: string, options?: GetCookiesOptions | Callback, @@ -709,6 +1020,16 @@ export class CookieJar { this.getCookies(url, options, next) return promiseCallback.promise } + + /** + * Synchronous version of `.getCookieString()`. Accepts the same options as `.getCookies()` but returns a string suitable for a + * `Cookie` header rather than an Array. + * + * Note: Only works if the configured Store is also synchronous. + * + * @param url - The domain to store the cookie with. + * @param options - Configuration settings to use when retrieving the cookies. + */ getCookieStringSync(url: string, options?: GetCookiesOptions): string { return ( this.callSync( @@ -719,24 +1040,52 @@ export class CookieJar { ) } + /** + * Returns an array of strings suitable for `Set-Cookie` headers. Accepts the same options + * as `.getCookies()`. + * + * @param url - The domain to store the cookie with. + * @param callback - A function to call after the `Set-Cookie` header strings have been created. + */ getSetCookieStrings( url: string, callback: Callback, ): void + /** + * Returns an array of strings suitable for `Set-Cookie` headers. Accepts the same options + * as `.getCookies()`. + * + * @param url - The domain to store the cookie with. + * @param options - Configuration settings to use when retrieving the cookies. + * @param callback - A function to call after the `Set-Cookie` header strings have been created. + */ getSetCookieStrings( url: string, options: GetCookiesOptions, callback: Callback, ): void + /** + * Returns an array of strings suitable for `Set-Cookie` headers. Accepts the same options + * as `.getCookies()`. + * + * @param url - The domain to store the cookie with. + * @param options - Configuration settings to use when retrieving the cookies. + */ getSetCookieStrings( url: string, options?: GetCookiesOptions, ): Promise + /** + * @internal No doc because this is an overload that supports the implementation + */ getSetCookieStrings( url: string, options: GetCookiesOptions, callback?: Callback, ): unknown + /** + * @internal No doc because this is the overload implementation + */ getSetCookieStrings( url: string, options?: GetCookiesOptions | Callback, @@ -766,6 +1115,16 @@ export class CookieJar { this.getCookies(url, options, next) return promiseCallback.promise } + + /** + * Synchronous version of `.getSetCookieStrings()`. Returns an array of strings suitable for `Set-Cookie` headers. + * Accepts the same options as `.getCookies()`. + * + * Note: Only works if the configured Store is also synchronous. + * + * @param url - The domain to store the cookie with. + * @param options - Configuration settings to use when retrieving the cookies. + */ getSetCookieStringsSync( url: string, options: GetCookiesOptions = {}, @@ -775,8 +1134,18 @@ export class CookieJar { ) } + /** + * Serialize the CookieJar if the underlying store supports `.getAllCookies`. + * @param callback - A function to call after the CookieJar has been serialized + */ serialize(callback: Callback): void + /** + * Serialize the CookieJar if the underlying store supports `.getAllCookies`. + */ serialize(): Promise + /** + * @internal No doc because this is the overload implementation + */ serialize(callback?: Callback): unknown { const promiseCallback = createPromiseCallback(callback) const cb = promiseCallback.callback @@ -846,15 +1215,28 @@ export class CookieJar { return promiseCallback.promise } + + /** + * Serialize the CookieJar if the underlying store supports `.getAllCookies`. + * + * Note: Only works if the configured Store is also synchronous. + */ serializeSync(): SerializedCookieJar | undefined { return this.callSync((callback) => this.serialize(callback)) } + /** + * Alias of {@link CookieJar.serializeSync}. Allows the cookie to be serialized + * with `JSON.stringify(cookieJar)`. + */ toJSON(): SerializedCookieJar | undefined { return this.serializeSync() } - // use the class method CookieJar.deserialize instead of calling this directly + /** + * Use the class method CookieJar.deserialize instead of calling this directly + * @internal + */ _importCookies(serialized: unknown, callback: Callback): void { let cookies: unknown[] | undefined = undefined @@ -904,13 +1286,56 @@ export class CookieJar { putNext(null) } + /** + * @internal + */ _importCookiesSync(serialized: unknown): void { this.callSync(this._importCookies.bind(this, serialized)) } + /** + * Produces a deep clone of this CookieJar. Modifications to the original do + * not affect the clone, and vice versa. + * + * @remarks + * - When no {@link Store} is provided, a new {@link MemoryCookieStore} will be used. + * + * - Transferring between store types is supported so long as the source + * implements `.getAllCookies()` and the destination implements `.putCookie()`. + * + * @param callback - A function to call when the CookieJar is cloned. + */ clone(callback: Callback): void + /** + * Produces a deep clone of this CookieJar. Modifications to the original do + * not affect the clone, and vice versa. + * + * @remarks + * - When no {@link Store} is provided, a new {@link MemoryCookieStore} will be used. + * + * - Transferring between store types is supported so long as the source + * implements `.getAllCookies()` and the destination implements `.putCookie()`. + * + * @param newStore - The target {@link Store} to clone cookies into. + * @param callback - A function to call when the CookieJar is cloned. + */ clone(newStore: Store, callback: Callback): void + /** + * Produces a deep clone of this CookieJar. Modifications to the original do + * not affect the clone, and vice versa. + * + * @remarks + * - When no {@link Store} is provided, a new {@link MemoryCookieStore} will be used. + * + * - Transferring between store types is supported so long as the source + * implements `.getAllCookies()` and the destination implements `.putCookie()`. + * + * @param newStore - The target {@link Store} to clone cookies into. + */ clone(newStore?: Store): Promise + /** + * @internal No doc because this is the overload implementation + */ clone( newStore?: Store | Callback, callback?: Callback, @@ -933,6 +1358,9 @@ export class CookieJar { return promiseCallback.promise } + /** + * @internal + */ _cloneSync(newStore?: Store): CookieJar | undefined { const cloneFn = newStore && typeof newStore !== 'function' @@ -941,6 +1369,21 @@ export class CookieJar { return this.callSync((callback) => cloneFn(callback)) } + /** + * Produces a deep clone of this CookieJar. Modifications to the original do + * not affect the clone, and vice versa. + * + * Note: Only works if both the configured Store and destination + * Store are synchronous. + * + * @remarks + * - When no {@link Store} is provided, a new {@link MemoryCookieStore} will be used. + * + * - Transferring between store types is supported so long as the source + * implements `.getAllCookies()` and the destination implements `.putCookie()`. + * + * @param newStore - The target {@link Store} to clone cookies into. + */ cloneSync(newStore?: Store): CookieJar | undefined { if (!newStore) { return this._cloneSync() @@ -953,8 +1396,39 @@ export class CookieJar { return this._cloneSync(newStore) } + /** + * Removes all cookies from the CookieJar. + * + * @remarks + * - This is a new backwards-compatible feature of tough-cookie version 2.5, + * so not all Stores will implement it efficiently. For Stores that do not + * implement `removeAllCookies`, the fallback is to call `removeCookie` after + * `getAllCookies`. + * + * - If `getAllCookies` fails or isn't implemented in the Store, an error is returned. + * + * - If one or more of the `removeCookie` calls fail, only the first error is returned. + * + * @param callback - A function to call when all the cookies have been removed. + */ removeAllCookies(callback: ErrorCallback): void + /** + * Removes all cookies from the CookieJar. + * + * @remarks + * - This is a new backwards-compatible feature of tough-cookie version 2.5, + * so not all Stores will implement it efficiently. For Stores that do not + * implement `removeAllCookies`, the fallback is to call `removeCookie` after + * `getAllCookies`. + * + * - If `getAllCookies` fails or isn't implemented in the Store, an error is returned. + * + * - If one or more of the `removeCookie` calls fail, only the first error is returned. + */ removeAllCookies(): Promise + /** + * @internal No doc because this is the overload implementation + */ removeAllCookies(callback?: ErrorCallback): unknown { const promiseCallback = createPromiseCallback(callback) const cb = promiseCallback.callback @@ -1019,30 +1493,92 @@ export class CookieJar { return promiseCallback.promise } + + /** + * Removes all cookies from the CookieJar. + * + * Note: Only works if the configured Store is also synchronous. + * + * @remarks + * - This is a new backwards-compatible feature of tough-cookie version 2.5, + * so not all Stores will implement it efficiently. For Stores that do not + * implement `removeAllCookies`, the fallback is to call `removeCookie` after + * `getAllCookies`. + * + * - If `getAllCookies` fails or isn't implemented in the Store, an error is returned. + * + * - If one or more of the `removeCookie` calls fail, only the first error is returned. + */ removeAllCookiesSync(): void { return this.callSync((callback) => { return this.removeAllCookies(callback) }) } + /** + * A new CookieJar is created and the serialized {@link Cookie} values are added to + * the underlying store. Each {@link Cookie} is added via `store.putCookie(...)` in + * the order in which they appear in the serialization. + * + * @remarks + * - When no {@link Store} is provided, a new {@link MemoryCookieStore} will be used. + * + * - As a convenience, if `strOrObj` is a string, it is passed through `JSON.parse` first. + * + * @param strOrObj - A JSON string or object representing the deserialized cookies. + * @param callback - A function to call after the {@link CookieJar} has been deserialized. + */ static deserialize( strOrObj: string | object, callback: Callback, ): void + /** + * A new CookieJar is created and the serialized {@link Cookie} values are added to + * the underlying store. Each {@link Cookie} is added via `store.putCookie(...)` in + * the order in which they appear in the serialization. + * + * @remarks + * - When no {@link Store} is provided, a new {@link MemoryCookieStore} will be used. + * + * - As a convenience, if `strOrObj` is a string, it is passed through `JSON.parse` first. + * + * @param strOrObj - A JSON string or object representing the deserialized cookies. + * @param store - The underlying store to persist the deserialized cookies into. + * @param callback - A function to call after the {@link CookieJar} has been deserialized. + */ static deserialize( strOrObj: string | object, store: Store, callback: Callback, ): void + /** + * A new CookieJar is created and the serialized {@link Cookie} values are added to + * the underlying store. Each {@link Cookie} is added via `store.putCookie(...)` in + * the order in which they appear in the serialization. + * + * @remarks + * - When no {@link Store} is provided, a new {@link MemoryCookieStore} will be used. + * + * - As a convenience, if `strOrObj` is a string, it is passed through `JSON.parse` first. + * + * @param strOrObj - A JSON string or object representing the deserialized cookies. + * @param store - The underlying store to persist the deserialized cookies into. + */ static deserialize( strOrObj: string | object, store?: Store, ): Promise + /** + * @internal No doc because this is an overload that supports the implementation + */ static deserialize( strOrObj: string | object, store?: Store | Callback, callback?: Callback, ): unknown + /** + * @internal No doc because this is the overload implementation + */ static deserialize( strOrObj: string | object, store?: Store | Callback, @@ -1104,6 +1640,21 @@ export class CookieJar { return promiseCallback.promise } + /** + * A new CookieJar is created and the serialized {@link Cookie} values are added to + * the underlying store. Each {@link Cookie} is added via `store.putCookie(...)` in + * the order in which they appear in the serialization. + * + * Note: Only works if the configured Store is also synchronous. + * + * @remarks + * - When no {@link Store} is provided, a new {@link MemoryCookieStore} will be used. + * + * - As a convenience, if `strOrObj` is a string, it is passed through `JSON.parse` first. + * + * @param strOrObj - A JSON string or object representing the deserialized cookies. + * @param store - The underlying store to persist the deserialized cookies into. + */ static deserializeSync( strOrObj: string | SerializedCookieJar, store?: Store, @@ -1149,7 +1700,21 @@ export class CookieJar { return jar } - static fromJSON(jsonString: SerializedCookieJar, store?: Store): CookieJar { + /** + * Alias of {@link CookieJar.deserializeSync}. + * + * @remarks + * - When no {@link Store} is provided, a new {@link MemoryCookieStore} will be used. + * + * - As a convenience, if `strOrObj` is a string, it is passed through `JSON.parse` first. + * + * @param jsonString - A JSON string or object representing the deserialized cookies. + * @param store - The underlying store to persist the deserialized cookies into. + */ + static fromJSON( + jsonString: string | SerializedCookieJar, + store?: Store, + ): CookieJar { return CookieJar.deserializeSync(jsonString, store) } } diff --git a/lib/cookie/defaultPath.ts b/lib/cookie/defaultPath.ts index 726ea88e..5021ec63 100644 --- a/lib/cookie/defaultPath.ts +++ b/lib/cookie/defaultPath.ts @@ -1,12 +1,42 @@ -// RFC6265 S5.1.4 Paths and Path-Match - import type { Nullable } from '../utils' -/* - * "The user agent MUST use an algorithm equivalent to the following algorithm - * to compute the default-path of a cookie:" +/** + * Given a current request/response path, gives the path appropriate for storing + * in a cookie. This is basically the "directory" of a "file" in the path, but + * is specified by {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.1.4 | RFC6265 - Section 5.1.4}. + * + * @remarks + * ### RFC6265 - Section 5.1.4 + * + * The user agent MUST use an algorithm equivalent to the following algorithm to compute the default-path of a cookie: + * + * 1. Let uri-path be the path portion of the request-uri if such a + * portion exists (and empty otherwise). For example, if the + * request-uri contains just a path (and optional query string), + * then the uri-path is that path (without the %x3F ("?") character + * or query string), and if the request-uri contains a full + * absoluteURI, the uri-path is the path component of that URI. + * + * 2. If the uri-path is empty or if the first character of the uri- + * path is not a %x2F ("/") character, output %x2F ("/") and skip + * the remaining steps. + * + * 3. If the uri-path contains no more than one %x2F ("/") character, + * output %x2F ("/") and skip the remaining step. + * + * 4. Output the characters of the uri-path from the first character up + * to, but not including, the right-most %x2F ("/"). + * + * @example + * ``` + * defaultPath('') === '/' + * defaultPath('/some-path') === '/' + * defaultPath('/some-parent-path/some-path') === '/some-parent-path' + * defaultPath('relative-path') === '/' + * ``` * - * Assumption: the path (and not query part or absolute uri) is passed in. + * @param path - the path portion of the request-uri (excluding the hostname, query, fragment, and so on) + * @public */ export function defaultPath(path?: Nullable): string { // "2. If the uri-path is empty or if the first character of the uri-path is not diff --git a/lib/cookie/domainMatch.ts b/lib/cookie/domainMatch.ts index caaea90a..dd071eea 100644 --- a/lib/cookie/domainMatch.ts +++ b/lib/cookie/domainMatch.ts @@ -8,13 +8,48 @@ import { canonicalDomain } from './canonicalDomain' const IP_REGEX_LOWERCASE = /(?:^(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)(?:\.(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)){3}$)|(?:^(?:(?:[a-f\d]{1,4}:){7}(?:[a-f\d]{1,4}|:)|(?:[a-f\d]{1,4}:){6}(?:(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)(?:\.(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)){3}|:[a-f\d]{1,4}|:)|(?:[a-f\d]{1,4}:){5}(?::(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)(?:\.(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)){3}|(?::[a-f\d]{1,4}){1,2}|:)|(?:[a-f\d]{1,4}:){4}(?:(?::[a-f\d]{1,4}){0,1}:(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)(?:\.(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)){3}|(?::[a-f\d]{1,4}){1,3}|:)|(?:[a-f\d]{1,4}:){3}(?:(?::[a-f\d]{1,4}){0,2}:(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)(?:\.(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)){3}|(?::[a-f\d]{1,4}){1,4}|:)|(?:[a-f\d]{1,4}:){2}(?:(?::[a-f\d]{1,4}){0,3}:(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)(?:\.(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)){3}|(?::[a-f\d]{1,4}){1,5}|:)|(?:[a-f\d]{1,4}:){1}(?:(?::[a-f\d]{1,4}){0,4}:(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)(?:\.(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)){3}|(?::[a-f\d]{1,4}){1,6}|:)|(?::(?:(?::[a-f\d]{1,4}){0,5}:(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)(?:\.(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)){3}|(?::[a-f\d]{1,4}){1,7}|:)))$)/ -// S5.1.3 Domain Matching +/** + * Answers "does this real domain match the domain in a cookie?". The `domain` is the "current" domain name and the + * `cookieDomain` is the "cookie" domain name. Matches according to {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.1.3 | RFC6265 - Section 5.1.3}, + * but it helps to think of it as a "suffix match". + * + * @remarks + * ### 5.1.3. Domain Matching + * + * A string domain-matches a given domain string if at least one of the + * following conditions hold: + * + * - The domain string and the string are identical. (Note that both + * the domain string and the string will have been canonicalized to + * lower case at this point.) + * + * - All of the following conditions hold: + * + * - The domain string is a suffix of the string. + * + * - The last character of the string that is not included in the + * domain string is a %x2E (".") character. + * + * - The string is a host name (i.e., not an IP address). + * + * @example + * ``` + * domainMatch('example.com', 'example.com') === true + * domainMatch('eXaMpLe.cOm', 'ExAmPlE.CoM') === true + * domainMatch('no.ca', 'yes.ca') === false + * ``` + * + * @param domain - The domain string to test + * @param cookieDomain - The cookie domain string to match against + * @param canonicalize - The canonicalize parameter toggles whether the domain parameters get normalized with canonicalDomain or not + * @public + */ export function domainMatch( - str?: Nullable, - domStr?: Nullable, + domain?: Nullable, + cookieDomain?: Nullable, canonicalize?: boolean, ): boolean | undefined { - if (str == null || domStr == null) { + if (domain == null || cookieDomain == null) { return undefined } @@ -22,11 +57,11 @@ export function domainMatch( let _domStr: Nullable if (canonicalize !== false) { - _str = canonicalDomain(str) - _domStr = canonicalDomain(domStr) + _str = canonicalDomain(domain) + _domStr = canonicalDomain(cookieDomain) } else { - _str = str - _domStr = domStr + _str = domain + _domStr = cookieDomain } if (_str == null || _domStr == null) { @@ -49,7 +84,7 @@ export function domainMatch( /* " o All of the following [three] conditions hold:" */ /* "* The domain string is a suffix of the string" */ - const idx = _str.lastIndexOf(domStr) + const idx = _str.lastIndexOf(cookieDomain) if (idx <= 0) { return false // it's a non-match (-1) or prefix (0) } diff --git a/lib/cookie/formatDate.ts b/lib/cookie/formatDate.ts index faa93f7e..4c5ecfc0 100644 --- a/lib/cookie/formatDate.ts +++ b/lib/cookie/formatDate.ts @@ -1,7 +1,20 @@ import * as validators from '../validators' import { safeToString } from '../utils' -/** Converts a Date to a UTC string representation. */ +/** + * Format a {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date | Date} into + * the {@link https://www.rfc-editor.org/rfc/rfc2616#section-3.3.1 | preferred Internet standard format} + * defined in {@link https://www.rfc-editor.org/rfc/rfc822#section-5 | RFC822} and + * updated in {@link https://www.rfc-editor.org/rfc/rfc1123#page-55 | RFC1123}. + * + * @example + * ``` + * formatDate(new Date(0)) === 'Thu, 01 Jan 1970 00:00:00 GMT` + * ``` + * + * @param date - the date value to format + * @public + */ export function formatDate(date: Date): string { validators.validate(validators.isDate(date), safeToString(date)) return date.toUTCString() diff --git a/lib/cookie/index.ts b/lib/cookie/index.ts index 7b94bdd4..d6245054 100644 --- a/lib/cookie/index.ts +++ b/lib/cookie/index.ts @@ -1,23 +1,48 @@ -export { MemoryCookieStore } from '../memstore' +export { MemoryCookieStore, MemoryCookieStoreIndex } from '../memstore' export { pathMatch } from '../pathMatch' export { permuteDomain } from '../permuteDomain' -export { getPublicSuffix } from '../getPublicSuffix' +export { getPublicSuffix, GetPublicSuffixOptions } from '../getPublicSuffix' export { Store } from '../store' export { ParameterError } from '../validators' export { version } from '../version' - +export { Callback, ErrorCallback, Nullable } from '../utils' export { canonicalDomain } from './canonicalDomain' -export { PrefixSecurityEnum } from './constants' -export { Cookie } from './cookie' +export { + PrefixSecurityEnum, + SerializedCookie, + SerializedCookieJar, +} from './constants' +export { Cookie, CreateCookieOptions, ParseCookieOptions } from './cookie' export { cookieCompare } from './cookieCompare' -export { CookieJar } from './cookieJar' +export { + CookieJar, + CreateCookieJarOptions, + GetCookiesOptions, + SetCookieOptions, +} from './cookieJar' export { defaultPath } from './defaultPath' export { domainMatch } from './domainMatch' export { formatDate } from './formatDate' export { parseDate } from './parseDate' export { permutePath } from './permutePath' -import { Cookie } from './cookie' +import { Cookie, ParseCookieOptions } from './cookie' + +/** + * {@inheritDoc Cookie.parse} + * @public + */ +export function parse( + str: string, + options?: ParseCookieOptions, +): Cookie | undefined { + return Cookie.parse(str, options) +} -export const parse = Cookie.parse -export const fromJSON = Cookie.fromJSON +/** + * {@inheritDoc Cookie.fromJSON} + * @public + */ +export function fromJSON(str: unknown): Cookie | undefined { + return Cookie.fromJSON(str) +} diff --git a/lib/cookie/parseDate.ts b/lib/cookie/parseDate.ts index b9208489..7c090a63 100644 --- a/lib/cookie/parseDate.ts +++ b/lib/cookie/parseDate.ts @@ -123,11 +123,109 @@ function parseMonth(token: string): number | undefined { } } -/* - * RFC6265 S5.1.1 date parser (see RFC for full grammar) +/** + * Parse a cookie date string into a {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date | Date}. Parses according to + * {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.1.1 | RFC6265 - Section 5.1.1}, not + * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse | Date.parse()}. + * + * @remarks + * + * ### RFC6265 - 5.1.1. Dates + * + * The user agent MUST use an algorithm equivalent to the following + * algorithm to parse a cookie-date. Note that the various boolean + * flags defined as a part of the algorithm (i.e., found-time, found- + * day-of-month, found-month, found-year) are initially "not set". + * + * 1. Using the grammar below, divide the cookie-date into date-tokens. + * + * ``` + * cookie-date = *delimiter date-token-list *delimiter + * date-token-list = date-token *( 1*delimiter date-token ) + * date-token = 1*non-delimiter + * + * delimiter = %x09 / %x20-2F / %x3B-40 / %x5B-60 / %x7B-7E + * non-delimiter = %x00-08 / %x0A-1F / DIGIT / ":" / ALPHA / %x7F-FF + * non-digit = %x00-2F / %x3A-FF + * + * day-of-month = 1*2DIGIT ( non-digit *OCTET ) + * month = ( "jan" / "feb" / "mar" / "apr" / + * "may" / "jun" / "jul" / "aug" / + * "sep" / "oct" / "nov" / "dec" ) *OCTET + * year = 2*4DIGIT ( non-digit *OCTET ) + * time = hms-time ( non-digit *OCTET ) + * hms-time = time-field ":" time-field ":" time-field + * time-field = 1*2DIGIT + * ``` + * + * 2. Process each date-token sequentially in the order the date-tokens + * appear in the cookie-date: + * + * 1. If the found-time flag is not set and the token matches the + * time production, set the found-time flag and set the hour- + * value, minute-value, and second-value to the numbers denoted + * by the digits in the date-token, respectively. Skip the + * remaining sub-steps and continue to the next date-token. + * + * 2. If the found-day-of-month flag is not set and the date-token + * matches the day-of-month production, set the found-day-of- + * month flag and set the day-of-month-value to the number + * denoted by the date-token. Skip the remaining sub-steps and + * continue to the next date-token. + * + * 3. If the found-month flag is not set and the date-token matches + * the month production, set the found-month flag and set the + * month-value to the month denoted by the date-token. Skip the + * remaining sub-steps and continue to the next date-token. + * + * 4. If the found-year flag is not set and the date-token matches + * the year production, set the found-year flag and set the + * year-value to the number denoted by the date-token. Skip the + * remaining sub-steps and continue to the next date-token. + * + * 3. If the year-value is greater than or equal to 70 and less than or + * equal to 99, increment the year-value by 1900. + * + * 4. If the year-value is greater than or equal to 0 and less than or + * equal to 69, increment the year-value by 2000. + * + * 1. NOTE: Some existing user agents interpret two-digit years differently. + * + * 5. Abort these steps and fail to parse the cookie-date if: + * + * - at least one of the found-day-of-month, found-month, found- + * year, or found-time flags is not set, + * + * - the day-of-month-value is less than 1 or greater than 31, + * + * - the year-value is less than 1601, + * + * - the hour-value is greater than 23, + * + * - the minute-value is greater than 59, or + * + * - the second-value is greater than 59. + * + * (Note that leap seconds cannot be represented in this syntax.) + * + * 6. Let the parsed-cookie-date be the date whose day-of-month, month, + * year, hour, minute, and second (in UTC) are the day-of-month- + * value, the month-value, the year-value, the hour-value, the + * minute-value, and the second-value, respectively. If no such + * date exists, abort these steps and fail to parse the cookie-date. + * + * 7. Return the parsed-cookie-date as the result of this algorithm. + * + * @example + * ``` + * parseDate('Wed, 09 Jun 2021 10:18:14 GMT') + * ``` + * + * @param cookieDate - the cookie date string + * @public */ -export function parseDate(str: Nullable): Date | undefined { - if (!str) { +export function parseDate(cookieDate: Nullable): Date | undefined { + if (!cookieDate) { return } @@ -135,7 +233,7 @@ export function parseDate(str: Nullable): Date | undefined { * 2. Process each date-token sequentially in the order the date-tokens * appear in the cookie-date */ - const tokens = str.split(DATE_DELIM) + const tokens = cookieDate.split(DATE_DELIM) if (!tokens) { return } diff --git a/lib/cookie/permutePath.ts b/lib/cookie/permutePath.ts index e8ccbf34..4574b9ec 100644 --- a/lib/cookie/permutePath.ts +++ b/lib/cookie/permutePath.ts @@ -1,8 +1,17 @@ import * as validators from '../validators' /** - * Gives the permutation of all possible `pathMatch`es of a given path. The - * array is in longest-to-shortest order. Handy for indexing. + * Generates the permutation of all possible values that {@link pathMatch} the `path` parameter. + * The array is in longest-to-shortest order. Useful when building custom {@link Store} implementations. + * + * @example + * ``` + * permutePath('/foo/bar/') + * // ['/foo/bar/', '/foo/bar', '/foo', '/'] + * ``` + * + * @param path - the path to generate permutations for + * @public */ export function permutePath(path: string): string[] { validators.validate(validators.isString(path)) diff --git a/lib/getPublicSuffix.ts b/lib/getPublicSuffix.ts index 63ca2c88..89e9de02 100644 --- a/lib/getPublicSuffix.ts +++ b/lib/getPublicSuffix.ts @@ -1,34 +1,3 @@ -/*! - * Copyright (c) 2018, Salesforce.com, Inc. - * All rights reserved. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions are met: - * - * 1. Redistributions of source code must retain the above copyright notice, - * this list of conditions and the following disclaimer. - * - * 2. Redistributions in binary form must reproduce the above copyright notice, - * this list of conditions and the following disclaimer in the documentation - * and/or other materials provided with the distribution. - * - * 3. Neither the name of Salesforce.com nor the names of its contributors may - * be used to endorse or promote products derived from this software without - * specific prior written permission. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE - * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS - * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE - * POSSIBILITY OF SUCH DAMAGE. - */ -'use strict' import { getDomain } from 'tldts' // RFC 6761 @@ -36,8 +5,32 @@ const SPECIAL_USE_DOMAINS = ['local', 'example', 'invalid', 'localhost', 'test'] const SPECIAL_TREATMENT_DOMAINS = ['localhost', 'invalid'] -type GetPublicSuffixOptions = { +/** + * Options for configuring how {@link getPublicSuffix} behaves. + * @public + */ +export interface GetPublicSuffixOptions { + /** + * If set to `true` then the following {@link https://www.rfc-editor.org/rfc/rfc6761.html | Special Use Domains} will + * be treated as if they were valid public suffixes ('local', 'example', 'invalid', 'localhost', 'test'). + * + * @remarks + * In testing scenarios it's common to configure the cookie store with so that `http://localhost` can be used as a domain: + * ```json + * { + * allowSpecialUseDomain: true, + * rejectPublicSuffixes: false + * } + * ``` + * + * @defaultValue false + */ allowSpecialUseDomain?: boolean | undefined + /** + * If set to `true` then any errors that occur while executing {@link getPublicSuffix} will be silently ignored. + * + * @defaultValue false + */ ignoreError?: boolean | undefined } @@ -46,6 +39,32 @@ const defaultGetPublicSuffixOptions: GetPublicSuffixOptions = { ignoreError: false, } +/** + * Returns the public suffix of this hostname. The public suffix is the shortest domain + * name upon which a cookie can be set. + * + * @remarks + * A "public suffix" is a domain that is controlled by a + * public registry, such as "com", "co.uk", and "pvt.k12.wy.us". + * This step is essential for preventing attacker.com from + * disrupting the integrity of example.com by setting a cookie + * with a Domain attribute of "com". Unfortunately, the set of + * public suffixes (also known as "registry controlled domains") + * changes over time. If feasible, user agents SHOULD use an + * up-to-date public suffix list, such as the one maintained by + * the Mozilla project at http://publicsuffix.org/. + * (See {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.3 | RFC6265 - Section 5.3}) + * + * @example + * ``` + * getPublicSuffix('www.example.com') === 'example.com' + * getPublicSuffix('www.subdomain.example.com') === 'example.com' + * ``` + * + * @param domain - the domain attribute of a cookie + * @param options - optional configuration for controlling how the public suffix is determined + * @public + */ export function getPublicSuffix( domain: string, options: GetPublicSuffixOptions = {}, @@ -80,7 +99,7 @@ export function getPublicSuffix( SPECIAL_USE_DOMAINS.includes(topLevelDomain) ) { throw new Error( - `Cookie has domain set to the public suffix "${topLevelDomain}" which is a special use domain. To allow this, configure your CookieJar with {allowSpecialUseDomain:true, rejectPublicSuffixes: false}.`, + `Cookie has domain set to the public suffix "${topLevelDomain}" which is a special use domain. To allow this, configure your CookieJar with {allowSpecialUseDomain: true, rejectPublicSuffixes: false}.`, ) } diff --git a/lib/memstore.ts b/lib/memstore.ts index e66a683f..40b95f49 100644 --- a/lib/memstore.ts +++ b/lib/memstore.ts @@ -1,34 +1,3 @@ -/*! - * Copyright (c) 2015, Salesforce.com, Inc. - * All rights reserved. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions are met: - * - * 1. Redistributions of source code must retain the above copyright notice, - * this list of conditions and the following disclaimer. - * - * 2. Redistributions in binary form must reproduce the above copyright notice, - * this list of conditions and the following disclaimer in the documentation - * and/or other materials provided with the distribution. - * - * 3. Neither the name of Salesforce.com nor the names of its contributors may - * be used to endorse or promote products derived from this software without - * specific prior written permission. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE - * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS - * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE - * POSSIBILITY OF SUCH DAMAGE. - */ -'use strict' import type { Cookie } from './cookie/cookie' import { pathMatch } from './pathMatch' import { permuteDomain } from './permuteDomain' @@ -40,6 +9,10 @@ import { Nullable, } from './utils' +/** + * The internal structure used in {@link MemoryCookieStore}. + * @internal + */ export type MemoryCookieStoreIndex = { [domain: string]: { [path: string]: { @@ -48,27 +21,65 @@ export type MemoryCookieStoreIndex = { } } +/** + * An in-memory {@link Store} implementation for {@link CookieJar}. This is the default implementation used by + * {@link CookieJar} and supports both async and sync operations. Also supports serialization, getAllCookies, and removeAllCookies. + * @public + */ export class MemoryCookieStore extends Store { + /** + * This value is `true` since {@link MemoryCookieStore} implements synchronous functionality. + */ override synchronous: boolean + + /** + * @internal + */ idx: MemoryCookieStoreIndex + /** + * Create a new {@link MemoryCookieStore}. + */ constructor() { super() this.synchronous = true this.idx = Object.create(null) as MemoryCookieStoreIndex } + /** + * Retrieve a {@link Cookie} with the given `domain`, `path`, and `key` (`name`). The RFC maintains that exactly + * one of these cookies should exist in a store. If the store is using versioning, this means that the latest or + * newest such cookie should be returned. + * + * @param domain - The cookie domain to match against. + * @param path - The cookie path to match against. + * @param key - The cookie name to match against. + */ override findCookie( domain: Nullable, path: Nullable, key: Nullable, ): Promise + /** + * Retrieve a {@link Cookie} with the given `domain`, `path`, and `key` (`name`). The RFC maintains that exactly + * one of these cookies should exist in a store. If the store is using versioning, this means that the latest or + * newest such cookie should be returned. + * + * Callback takes an error and the resulting Cookie object. If no cookie is found then null MUST be passed instead (that is, not an error). + * @param domain - The cookie domain to match against. + * @param path - The cookie path to match against. + * @param key - The cookie name to match against. + * @param callback - A function to call with either the found cookie or an error. + */ override findCookie( domain: Nullable, path: Nullable, key: Nullable, callback: Callback, ): void + /** + * @internal No doc because this is an overload that supports the implementation + */ override findCookie( domain: Nullable, path: Nullable, @@ -83,17 +94,55 @@ export class MemoryCookieStore extends Store { return promiseCallback.resolve(result) } + /** + * Locates all {@link Cookie} values matching the given `domain` and `path`. + * + * The resulting list is checked for applicability to the current request according to the RFC (`domain-match`, `path-match`, + * `http-only-flag`, `secure-flag`, `expiry`, and so on), so it's OK to use an optimistic search algorithm when implementing + * this method. However, the search algorithm used SHOULD try to find cookies that {@link domainMatch} the `domain` and + * {@link pathMatch} the `path` in order to limit the amount of checking that needs to be done. + * + * @remarks + * - As of version `0.9.12`, the `allPaths` option to cookiejar.getCookies() above causes the path here to be `null`. + * + * - If the `path` is `null`, `path-matching` MUST NOT be performed (that is, `domain-matching` only). + * + * @param domain - The cookie domain to match against. + * @param path - The cookie path to match against. + * @param allowSpecialUseDomain - If `true` then special-use domain suffixes, will be allowed in matches. Defaults to `false`. + */ override findCookies( domain: string, path: string, allowSpecialUseDomain?: boolean, ): Promise + /** + * Locates all {@link Cookie} values matching the given `domain` and `path`. + * + * The resulting list is checked for applicability to the current request according to the RFC (`domain-match`, `path-match`, + * `http-only-flag`, `secure-flag`, `expiry`, and so on), so it's OK to use an optimistic search algorithm when implementing + * this method. However, the search algorithm used SHOULD try to find cookies that {@link domainMatch} the `domain` and + * {@link pathMatch} the `path` in order to limit the amount of checking that needs to be done. + * + * @remarks + * - As of version `0.9.12`, the `allPaths` option to cookiejar.getCookies() above causes the path here to be `null`. + * + * - If the `path` is `null`, `path-matching` MUST NOT be performed (that is, `domain-matching` only). + * + * @param domain - The cookie domain to match against. + * @param path - The cookie path to match against. + * @param allowSpecialUseDomain - If `true` then special-use domain suffixes, will be allowed in matches. Defaults to `false`. + * @param callback - A function to call with either the found cookies or an error. + */ override findCookies( domain: string, path: string, allowSpecialUseDomain?: boolean, callback?: Callback, ): void + /** + * @internal No doc because this is an overload that supports the implementation + */ override findCookies( domain: string, path: string, @@ -161,8 +210,36 @@ export class MemoryCookieStore extends Store { return promiseCallback.resolve(results) } + /** + * Adds a new {@link Cookie} to the store. The implementation SHOULD replace any existing cookie with the same `domain`, + * `path`, and `key` properties. + * + * @remarks + * - Depending on the nature of the implementation, it's possible that between the call to `fetchCookie` and `putCookie` + * that a duplicate `putCookie` can occur. + * + * - The {@link Cookie} object MUST NOT be modified; as the caller has already updated the `creation` and `lastAccessed` properties. + * + * @param cookie - The cookie to store. + */ override putCookie(cookie: Cookie): Promise + /** + * Adds a new {@link Cookie} to the store. The implementation SHOULD replace any existing cookie with the same `domain`, + * `path`, and `key` properties. + * + * @remarks + * - Depending on the nature of the implementation, it's possible that between the call to `fetchCookie` and `putCookie` + * that a duplicate `putCookie` can occur. + * + * - The {@link Cookie} object MUST NOT be modified; as the caller has already updated the `creation` and `lastAccessed` properties. + * + * @param cookie - The cookie to store. + * @param callback - A function to call when the cookie has been stored or an error has occurred. + */ override putCookie(cookie: Cookie, callback: ErrorCallback): void + /** + * @internal No doc because this is an overload that supports the implementation + */ override putCookie(cookie: Cookie, callback?: ErrorCallback): unknown { const promiseCallback = createPromiseCallback(callback) @@ -188,12 +265,54 @@ export class MemoryCookieStore extends Store { return promiseCallback.resolve(undefined) } + /** + * Update an existing {@link Cookie}. The implementation MUST update the `value` for a cookie with the same `domain`, + * `path`, and `key`. The implementation SHOULD check that the old value in the store is equivalent to oldCookie - + * how the conflict is resolved is up to the store. + * + * @remarks + * - The `lastAccessed` property is always different between the two objects (to the precision possible via JavaScript's clock). + * + * - Both `creation` and `creationIndex` are guaranteed to be the same. + * + * - Stores MAY ignore or defer the `lastAccessed` change at the cost of affecting how cookies are selected for automatic deletion. + * + * - Stores may wish to optimize changing the `value` of the cookie in the store versus storing a new cookie. + * + * - The `newCookie` and `oldCookie` objects MUST NOT be modified. + * + * @param oldCookie - the cookie that is already present in the store. + * @param newCookie - the cookie to replace the one already present in the store. + */ override updateCookie(oldCookie: Cookie, newCookie: Cookie): Promise + /** + * Update an existing {@link Cookie}. The implementation MUST update the `value` for a cookie with the same `domain`, + * `path`, and `key`. The implementation SHOULD check that the old value in the store is equivalent to oldCookie - + * how the conflict is resolved is up to the store. + * + * @remarks + * - The `lastAccessed` property is always different between the two objects (to the precision possible via JavaScript's clock). + * + * - Both `creation` and `creationIndex` are guaranteed to be the same. + * + * - Stores MAY ignore or defer the `lastAccessed` change at the cost of affecting how cookies are selected for automatic deletion. + * + * - Stores may wish to optimize changing the `value` of the cookie in the store versus storing a new cookie. + * + * - The `newCookie` and `oldCookie` objects MUST NOT be modified. + * + * @param oldCookie - the cookie that is already present in the store. + * @param newCookie - the cookie to replace the one already present in the store. + * @param callback - A function to call when the cookie has been updated or an error has occurred. + */ override updateCookie( oldCookie: Cookie, newCookie: Cookie, callback: ErrorCallback, ): void + /** + * @internal No doc because this is an overload that supports the implementation + */ override updateCookie( _oldCookie: Cookie, newCookie: Cookie, @@ -207,17 +326,35 @@ export class MemoryCookieStore extends Store { : this.putCookie(newCookie) } + /** + * Remove a cookie from the store (see notes on `findCookie` about the uniqueness constraint). + * + * @param domain - The cookie domain to match against. + * @param path - The cookie path to match against. + * @param key - The cookie name to match against. + */ override removeCookie( domain: string, path: string, key: string, ): Promise + /** + * Remove a cookie from the store (see notes on `findCookie` about the uniqueness constraint). + * + * @param domain - The cookie domain to match against. + * @param path - The cookie path to match against. + * @param key - The cookie name to match against. + * @param callback - A function to call when the cookie has been removed or an error occurs. + */ override removeCookie( domain: string, path: string, key: string, callback: ErrorCallback, ): void + /** + * @internal No doc because this is an overload that supports the implementation + */ override removeCookie( domain: string, path: string, @@ -229,12 +366,30 @@ export class MemoryCookieStore extends Store { return promiseCallback.resolve(undefined) } + /** + * Removes matching cookies from the store. The `path` parameter is optional and if missing, + * means all paths in a domain should be removed. + * + * @param domain - The cookie domain to match against. + * @param path - The cookie path to match against. + */ override removeCookies(domain: string, path: string): Promise + /** + * Removes matching cookies from the store. The `path` parameter is optional and if missing, + * means all paths in a domain should be removed. + * + * @param domain - The cookie domain to match against. + * @param path - The cookie path to match against. + * @param callback - A function to call when the cookies have been removed or an error occurs. + */ override removeCookies( domain: string, path: string, callback: ErrorCallback, ): void + /** + * @internal No doc because this is an overload that supports the implementation + */ override removeCookies( domain: string, path: string, @@ -254,16 +409,44 @@ export class MemoryCookieStore extends Store { return promiseCallback.resolve(undefined) } + /** + * Removes all cookies from the store. + */ override removeAllCookies(): Promise + /** + * Removes all cookies from the store. + * + * @param callback - A function to call when all the cookies have been removed or an error occurs. + */ override removeAllCookies(callback: ErrorCallback): void + /** + * @internal No doc because this is an overload that supports the implementation + */ override removeAllCookies(callback?: ErrorCallback): unknown { const promiseCallback = createPromiseCallback(callback) this.idx = Object.create(null) as MemoryCookieStoreIndex return promiseCallback.resolve(undefined) } + /** + * Gets all the cookies in the store. + * + * @remarks + * - Cookies SHOULD be returned in creation order to preserve sorting via {@link cookieCompare}. + */ override getAllCookies(): Promise + /** + * Gets all the cookies in the store. + * + * @remarks + * - Cookies SHOULD be returned in creation order to preserve sorting via {@link cookieCompare}. + * + * @param callback - A function to call when all the cookies have been retrieved or an error occurs. + */ override getAllCookies(callback: Callback): void + /** + * @internal No doc because this is an overload that supports the implementation + */ override getAllCookies(callback?: Callback): unknown { const promiseCallback = createPromiseCallback(callback) diff --git a/lib/pathMatch.ts b/lib/pathMatch.ts index 36245607..927aa4a1 100644 --- a/lib/pathMatch.ts +++ b/lib/pathMatch.ts @@ -1,37 +1,18 @@ -/*! - * Copyright (c) 2015, Salesforce.com, Inc. - * All rights reserved. +/** + * Answers "does the request-path path-match a given cookie-path?" as per {@link https://www.rfc-editor.org/rfc/rfc6265.html#section-5.1.4 | RFC6265 Section 5.1.4}. + * This is essentially a prefix-match where cookiePath is a prefix of reqPath. * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions are met: + * @remarks + * A request-path path-matches a given cookie-path if at least one of + * the following conditions holds: * - * 1. Redistributions of source code must retain the above copyright notice, - * this list of conditions and the following disclaimer. + * - The cookie-path and the request-path are identical. + * - The cookie-path is a prefix of the request-path, and the last character of the cookie-path is %x2F ("/"). + * - The cookie-path is a prefix of the request-path, and the first character of the request-path that is not included in the cookie-path is a %x2F ("/") character. * - * 2. Redistributions in binary form must reproduce the above copyright notice, - * this list of conditions and the following disclaimer in the documentation - * and/or other materials provided with the distribution. - * - * 3. Neither the name of Salesforce.com nor the names of its contributors may - * be used to endorse or promote products derived from this software without - * specific prior written permission. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE - * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS - * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE - * POSSIBILITY OF SUCH DAMAGE. - */ - -/* - * "A request-path path-matches a given cookie-path if at least one of the - * following conditions holds:" + * @param reqPath - the path of the request + * @param cookiePath - the path of the cookie + * @public */ export function pathMatch(reqPath: string, cookiePath: string): boolean { // "o The cookie-path and the request-path are identical." diff --git a/lib/permuteDomain.ts b/lib/permuteDomain.ts index 26d3780c..8c16c5e2 100644 --- a/lib/permuteDomain.ts +++ b/lib/permuteDomain.ts @@ -1,39 +1,19 @@ -/*! - * Copyright (c) 2015, Salesforce.com, Inc. - * All rights reserved. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions are met: - * - * 1. Redistributions of source code must retain the above copyright notice, - * this list of conditions and the following disclaimer. - * - * 2. Redistributions in binary form must reproduce the above copyright notice, - * this list of conditions and the following disclaimer in the documentation - * and/or other materials provided with the distribution. +import { getPublicSuffix } from './getPublicSuffix' + +/** + * Generates the permutation of all possible values that {@link domainMatch} the given `domain` parameter. The + * array is in shortest-to-longest order. Useful when building custom {@link Store} implementations. * - * 3. Neither the name of Salesforce.com nor the names of its contributors may - * be used to endorse or promote products derived from this software without - * specific prior written permission. + * @example + * ``` + * permuteDomain('foo.bar.example.com') + * // ['example.com', 'bar.example.com', 'foo.bar.example.com'] + * ``` * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE - * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS - * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE - * POSSIBILITY OF SUCH DAMAGE. + * @public + * @param domain - the domain to generate permutations for + * @param allowSpecialUseDomain - flag to control if {@link https://www.rfc-editor.org/rfc/rfc6761.html | Special Use Domains} such as `localhost` should be allowed */ -'use strict' -import { getPublicSuffix } from './getPublicSuffix' - -// Gives the permutation of all possible domainMatch()es of a given domain. The -// array is in shortest-to-longest order. Handy for indexing. - export function permuteDomain( domain: string, allowSpecialUseDomain?: boolean, diff --git a/lib/store.ts b/lib/store.ts index f23eb462..b1c0c830 100644 --- a/lib/store.ts +++ b/lib/store.ts @@ -1,61 +1,69 @@ -/*! - * Copyright (c) 2015, Salesforce.com, Inc. - * All rights reserved. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions are met: - * - * 1. Redistributions of source code must retain the above copyright notice, - * this list of conditions and the following disclaimer. - * - * 2. Redistributions in binary form must reproduce the above copyright notice, - * this list of conditions and the following disclaimer in the documentation - * and/or other materials provided with the distribution. - * - * 3. Neither the name of Salesforce.com nor the names of its contributors may - * be used to endorse or promote products derived from this software without - * specific prior written permission. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE - * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS - * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE - * POSSIBILITY OF SUCH DAMAGE. - */ - // disabling this lint on this whole file because Store should be abstract // but we have implementations in the wild that may not implement all features /* eslint-disable @typescript-eslint/no-unused-vars */ -'use strict' - -import type { Cookie } from './cookie/cookie' +import type { Cookie } from './cookie' import type { Callback, ErrorCallback, Nullable } from './utils' +/** + * Base class for {@link CookieJar} stores. + * + * The storage model for each {@link CookieJar} instance can be replaced with a custom implementation. The default is + * {@link MemoryCookieStore}. + * + * @remarks + * - Stores should inherit from the base Store class, which is available as a top-level export. + * + * - Stores are asynchronous by default, but if {@link Store.synchronous} is set to true, then the `*Sync` methods + * of the containing {@link CookieJar} can be used. + * + * @public + */ export class Store { + /** + * Store implementations that support synchronous methods must return `true`. + */ synchronous: boolean constructor() { this.synchronous = false } + /** + * Retrieve a {@link Cookie} with the given `domain`, `path`, and `key` (`name`). The RFC maintains that exactly + * one of these cookies should exist in a store. If the store is using versioning, this means that the latest or + * newest such cookie should be returned. + * + * Callback takes an error and the resulting Cookie object. If no cookie is found then null MUST be passed instead (that is, not an error). + * @param domain - The cookie domain to match against. + * @param path - The cookie path to match against. + * @param key - The cookie name to match against. + */ findCookie( domain: Nullable, path: Nullable, key: Nullable, ): Promise + /** + * Retrieve a {@link Cookie} with the given `domain`, `path`, and `key` (`name`). The RFC maintains that exactly + * one of these cookies should exist in a store. If the store is using versioning, this means that the latest or + * newest such cookie should be returned. + * + * Callback takes an error and the resulting Cookie object. If no cookie is found then null MUST be passed instead (that is, not an error). + * @param domain - The cookie domain to match against. + * @param path - The cookie path to match against. + * @param key - The cookie name to match against. + * @param callback - A function to call with either the found cookie or an error. + */ findCookie( domain: Nullable, path: Nullable, key: Nullable, callback: Callback, ): void + /** + * @internal No doc because this is an overload that supports the implementation + */ findCookie( _domain: Nullable, _path: Nullable, @@ -65,17 +73,55 @@ export class Store { throw new Error('findCookie is not implemented') } + /** + * Locates all {@link Cookie} values matching the given `domain` and `path`. + * + * The resulting list is checked for applicability to the current request according to the RFC (`domain-match`, `path-match`, + * `http-only-flag`, `secure-flag`, `expiry`, and so on), so it's OK to use an optimistic search algorithm when implementing + * this method. However, the search algorithm used SHOULD try to find cookies that {@link domainMatch} the `domain` and + * {@link pathMatch} the `path` in order to limit the amount of checking that needs to be done. + * + * @remarks + * - As of version `0.9.12`, the `allPaths` option to cookiejar.getCookies() above causes the path here to be `null`. + * + * - If the `path` is `null`, `path-matching` MUST NOT be performed (that is, `domain-matching` only). + * + * @param domain - The cookie domain to match against. + * @param path - The cookie path to match against. + * @param allowSpecialUseDomain - If `true` then special-use domain suffixes, will be allowed in matches. Defaults to `false`. + */ findCookies( domain: Nullable, path: Nullable, allowSpecialUseDomain?: boolean, ): Promise + /** + * Locates all {@link Cookie} values matching the given `domain` and `path`. + * + * The resulting list is checked for applicability to the current request according to the RFC (`domain-match`, `path-match`, + * `http-only-flag`, `secure-flag`, `expiry`, and so on), so it's OK to use an optimistic search algorithm when implementing + * this method. However, the search algorithm used SHOULD try to find cookies that {@link domainMatch} the `domain` and + * {@link pathMatch} the `path` in order to limit the amount of checking that needs to be done. + * + * @remarks + * - As of version `0.9.12`, the `allPaths` option to cookiejar.getCookies() above causes the path here to be `null`. + * + * - If the `path` is `null`, `path-matching` MUST NOT be performed (that is, `domain-matching` only). + * + * @param domain - The cookie domain to match against. + * @param path - The cookie path to match against. + * @param allowSpecialUseDomain - If `true` then special-use domain suffixes, will be allowed in matches. Defaults to `false`. + * @param callback - A function to call with either the found cookies or an error. + */ findCookies( domain: Nullable, path: Nullable, allowSpecialUseDomain?: boolean, callback?: Callback, ): void + /** + * @internal No doc because this is an overload that supports the implementation + */ findCookies( _domain: Nullable, _path: Nullable, @@ -85,18 +131,88 @@ export class Store { throw new Error('findCookies is not implemented') } + /** + * Adds a new {@link Cookie} to the store. The implementation SHOULD replace any existing cookie with the same `domain`, + * `path`, and `key` properties. + * + * @remarks + * - Depending on the nature of the implementation, it's possible that between the call to `fetchCookie` and `putCookie` + * that a duplicate `putCookie` can occur. + * + * - The {@link Cookie} object MUST NOT be modified; as the caller has already updated the `creation` and `lastAccessed` properties. + * + * @param cookie - The cookie to store. + */ putCookie(cookie: Cookie): Promise + /** + * Adds a new {@link Cookie} to the store. The implementation SHOULD replace any existing cookie with the same `domain`, + * `path`, and `key` properties. + * + * @remarks + * - Depending on the nature of the implementation, it's possible that between the call to `fetchCookie` and `putCookie` + * that a duplicate `putCookie` can occur. + * + * - The {@link Cookie} object MUST NOT be modified; as the caller has already updated the `creation` and `lastAccessed` properties. + * + * @param cookie - The cookie to store. + * @param callback - A function to call when the cookie has been stored or an error has occurred. + */ putCookie(cookie: Cookie, callback: ErrorCallback): void + /** + * @internal No doc because this is an overload that supports the implementation + */ putCookie(_cookie: Cookie, _callback?: ErrorCallback): unknown { throw new Error('putCookie is not implemented') } + /** + * Update an existing {@link Cookie}. The implementation MUST update the `value` for a cookie with the same `domain`, + * `path`, and `key`. The implementation SHOULD check that the old value in the store is equivalent to oldCookie - + * how the conflict is resolved is up to the store. + * + * @remarks + * - The `lastAccessed` property is always different between the two objects (to the precision possible via JavaScript's clock). + * + * - Both `creation` and `creationIndex` are guaranteed to be the same. + * + * - Stores MAY ignore or defer the `lastAccessed` change at the cost of affecting how cookies are selected for automatic deletion. + * + * - Stores may wish to optimize changing the `value` of the cookie in the store versus storing a new cookie. + * + * - The `newCookie` and `oldCookie` objects MUST NOT be modified. + * + * @param oldCookie - the cookie that is already present in the store. + * @param newCookie - the cookie to replace the one already present in the store. + */ updateCookie(oldCookie: Cookie, newCookie: Cookie): Promise + /** + * Update an existing {@link Cookie}. The implementation MUST update the `value` for a cookie with the same `domain`, + * `path`, and `key`. The implementation SHOULD check that the old value in the store is equivalent to oldCookie - + * how the conflict is resolved is up to the store. + * + * @remarks + * - The `lastAccessed` property is always different between the two objects (to the precision possible via JavaScript's clock). + * + * - Both `creation` and `creationIndex` are guaranteed to be the same. + * + * - Stores MAY ignore or defer the `lastAccessed` change at the cost of affecting how cookies are selected for automatic deletion. + * + * - Stores may wish to optimize changing the `value` of the cookie in the store versus storing a new cookie. + * + * - The `newCookie` and `oldCookie` objects MUST NOT be modified. + * + * @param oldCookie - the cookie that is already present in the store. + * @param newCookie - the cookie to replace the one already present in the store. + * @param callback - A function to call when the cookie has been updated or an error has occurred. + */ updateCookie( oldCookie: Cookie, newCookie: Cookie, callback: ErrorCallback, ): void + /** + * @internal No doc because this is an overload that supports the implementation + */ updateCookie( _oldCookie: Cookie, _newCookie: Cookie, @@ -107,17 +223,35 @@ export class Store { throw new Error('updateCookie is not implemented') } + /** + * Remove a cookie from the store (see notes on `findCookie` about the uniqueness constraint). + * + * @param domain - The cookie domain to match against. + * @param path - The cookie path to match against. + * @param key - The cookie name to match against. + */ removeCookie( domain: Nullable, path: Nullable, key: Nullable, ): Promise + /** + * Remove a cookie from the store (see notes on `findCookie` about the uniqueness constraint). + * + * @param domain - The cookie domain to match against. + * @param path - The cookie path to match against. + * @param key - The cookie name to match against. + * @param callback - A function to call when the cookie has been removed or an error occurs. + */ removeCookie( domain: Nullable, path: Nullable, key: Nullable, callback: ErrorCallback, ): void + /** + * @internal No doc because this is an overload that supports the implementation + */ removeCookie( _domain: Nullable, _path: Nullable, @@ -127,12 +261,30 @@ export class Store { throw new Error('removeCookie is not implemented') } + /** + * Removes matching cookies from the store. The `path` parameter is optional and if missing, + * means all paths in a domain should be removed. + * + * @param domain - The cookie domain to match against. + * @param path - The cookie path to match against. + */ removeCookies(domain: string, path: Nullable): Promise + /** + * Removes matching cookies from the store. The `path` parameter is optional and if missing, + * means all paths in a domain should be removed. + * + * @param domain - The cookie domain to match against. + * @param path - The cookie path to match against. + * @param callback - A function to call when the cookies have been removed or an error occurs. + */ removeCookies( domain: string, path: Nullable, callback: ErrorCallback, ): void + /** + * @internal No doc because this is an overload that supports the implementation + */ removeCookies( _domain: string, _path: Nullable, @@ -141,14 +293,42 @@ export class Store { throw new Error('removeCookies is not implemented') } + /** + * Removes all cookies from the store. + */ removeAllCookies(): Promise + /** + * Removes all cookies from the store. + * + * @param callback - A function to call when all the cookies have been removed or an error occurs. + */ removeAllCookies(callback: ErrorCallback): void + /** + * @internal No doc because this is an overload that supports the implementation + */ removeAllCookies(_callback?: ErrorCallback): unknown { throw new Error('removeAllCookies is not implemented') } + /** + * Gets all the cookies in the store. + * + * @remarks + * - Cookies SHOULD be returned in creation order to preserve sorting via {@link cookieCompare}. + */ getAllCookies(): Promise + /** + * Gets all the cookies in the store. + * + * @remarks + * - Cookies SHOULD be returned in creation order to preserve sorting via {@link cookieCompare}. + * + * @param callback - A function to call when all the cookies have been retrieved or an error occurs. + */ getAllCookies(callback: Callback): void + /** + * @internal No doc because this is an overload that supports the implementation + */ getAllCookies(_callback?: Callback): unknown { throw new Error( 'getAllCookies is not implemented (therefore jar cannot be serialized)', diff --git a/lib/utils.ts b/lib/utils.ts index c3068b7d..8b330198 100644 --- a/lib/utils.ts +++ b/lib/utils.ts @@ -1,15 +1,24 @@ -/** A callback function that accepts an error or a result. */ +/** + * A callback function that accepts an error or a result. + * @public + */ export interface Callback { (error: Error, result?: never): void (error: null, result: T): void } -/** A callback function that only accepts an error. */ +/** + * A callback function that only accepts an error. + * @public + */ export interface ErrorCallback { (error: Error | null): void } -/** The inverse of NonNullable. */ +/** + * The inverse of NonNullable. + * @public + */ export type Nullable = T | null | undefined /** Wrapped `Object.prototype.toString`, so that you don't need to remember to use `.call()`. */ diff --git a/lib/validators.ts b/lib/validators.ts index 64754973..ee98b9b8 100644 --- a/lib/validators.ts +++ b/lib/validators.ts @@ -83,4 +83,8 @@ export function validate( else throw err } +/** + * Represents a validation error. + * @public + */ export class ParameterError extends Error {} diff --git a/lib/version.ts b/lib/version.ts index c84d50ac..7f37283c 100644 --- a/lib/version.ts +++ b/lib/version.ts @@ -1,2 +1,5 @@ -// Generated by genversion. +/** + * The version of `tough-cookie` + * @public + */ export const version = '5.0.0-rc.1' diff --git a/package-lock.json b/package-lock.json index eeb66e89..7ea8ff20 100644 --- a/package-lock.json +++ b/package-lock.json @@ -14,6 +14,8 @@ "url-parse": "^1.5.10" }, "devDependencies": { + "@microsoft/api-documenter": "^7.23.37", + "@microsoft/api-extractor": "^7.42.3", "@types/jest": "^29.5.10", "@types/node": "^14.18.63", "@types/punycode": "^2.1.4", @@ -1512,6 +1514,143 @@ "@jridgewell/sourcemap-codec": "^1.4.14" } }, + "node_modules/@microsoft/api-documenter": { + "version": "7.24.2", + "resolved": "https://registry.npmjs.org/@microsoft/api-documenter/-/api-documenter-7.24.2.tgz", + "integrity": "sha512-q03DXLBj7nzAzLyLRAVklBynqKgSFI/JBmrhF/mEEIpg8orNo4qKXWO1RSkD2IYrqvZV63b13mcUPYgcFdifQA==", + "dev": true, + "dependencies": { + "@microsoft/api-extractor-model": "7.28.14", + "@microsoft/tsdoc": "0.14.2", + "@rushstack/node-core-library": "4.1.0", + "@rushstack/terminal": "0.10.1", + "@rushstack/ts-command-line": "4.19.2", + "js-yaml": "~3.13.1", + "resolve": "~1.22.1" + }, + "bin": { + "api-documenter": "bin/api-documenter" + } + }, + "node_modules/@microsoft/api-documenter/node_modules/js-yaml": { + "version": "3.13.1", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.13.1.tgz", + "integrity": "sha512-YfbcO7jXDdyj0DGxYVSlSeQNHbD7XPWvrVWeVUujrQEoZzWJIRrCPoyk6kL6IAjAG2IolMK4T0hNUe0HOUs5Jw==", + "dev": true, + "dependencies": { + "argparse": "^1.0.7", + "esprima": "^4.0.0" + }, + "bin": { + "js-yaml": "bin/js-yaml.js" + } + }, + "node_modules/@microsoft/api-extractor": { + "version": "7.43.1", + "resolved": "https://registry.npmjs.org/@microsoft/api-extractor/-/api-extractor-7.43.1.tgz", + "integrity": "sha512-ohg40SsvFFgzHFAtYq5wKJc8ZDyY46bphjtnSvhSSlXpPTG7GHwyyXkn48UZiUCBwr2WC7TRC1Jfwz7nreuiyQ==", + "dev": true, + "dependencies": { + "@microsoft/api-extractor-model": "7.28.14", + "@microsoft/tsdoc": "0.14.2", + "@microsoft/tsdoc-config": "~0.16.1", + "@rushstack/node-core-library": "4.1.0", + "@rushstack/rig-package": "0.5.2", + "@rushstack/terminal": "0.10.1", + "@rushstack/ts-command-line": "4.19.2", + "lodash": "~4.17.15", + "minimatch": "~3.0.3", + "resolve": "~1.22.1", + "semver": "~7.5.4", + "source-map": "~0.6.1", + "typescript": "5.4.2" + }, + "bin": { + "api-extractor": "bin/api-extractor" + } + }, + "node_modules/@microsoft/api-extractor-model": { + "version": "7.28.14", + "resolved": "https://registry.npmjs.org/@microsoft/api-extractor-model/-/api-extractor-model-7.28.14.tgz", + "integrity": "sha512-Bery/c8A8SsKPSvA82cTTuy/+OcxZbLRmKhPkk91/AJOQzxZsShcrmHFAGeiEqSIrv1nPZ3tKq9kfMLdCHmsqg==", + "dev": true, + "dependencies": { + "@microsoft/tsdoc": "0.14.2", + "@microsoft/tsdoc-config": "~0.16.1", + "@rushstack/node-core-library": "4.1.0" + } + }, + "node_modules/@microsoft/api-extractor/node_modules/minimatch": { + "version": "3.0.8", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.0.8.tgz", + "integrity": "sha512-6FsRAQsxQ61mw+qP1ZzbL9Bc78x2p5OqNgNpnoAFLTrX8n5Kxph0CsnhmKKNXTWjXqU5L0pGPR7hYk+XWZr60Q==", + "dev": true, + "dependencies": { + "brace-expansion": "^1.1.7" + }, + "engines": { + "node": "*" + } + }, + "node_modules/@microsoft/api-extractor/node_modules/semver": { + "version": "7.5.4", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.5.4.tgz", + "integrity": "sha512-1bCSESV6Pv+i21Hvpxp3Dx+pSD8lIPt8uVjRrxAUt/nbswYc+tK6Y2btiULjd4+fnq15PX+nqQDC7Oft7WkwcA==", + "dev": true, + "dependencies": { + "lru-cache": "^6.0.0" + }, + "bin": { + "semver": "bin/semver.js" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/@microsoft/api-extractor/node_modules/typescript": { + "version": "5.4.2", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.4.2.tgz", + "integrity": "sha512-+2/g0Fds1ERlP6JsakQQDXjZdZMM+rqpamFZJEKh4kwTIn3iDkgKtby0CeNd5ATNZ4Ry1ax15TMx0W2V+miizQ==", + "dev": true, + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/@microsoft/tsdoc": { + "version": "0.14.2", + "resolved": "https://registry.npmjs.org/@microsoft/tsdoc/-/tsdoc-0.14.2.tgz", + "integrity": "sha512-9b8mPpKrfeGRuhFH5iO1iwCLeIIsV6+H1sRfxbkoGXIyQE2BTsPd9zqSqQJ+pv5sJ/hT5M1zvOFL02MnEezFug==", + "dev": true + }, + "node_modules/@microsoft/tsdoc-config": { + "version": "0.16.2", + "resolved": "https://registry.npmjs.org/@microsoft/tsdoc-config/-/tsdoc-config-0.16.2.tgz", + "integrity": "sha512-OGiIzzoBLgWWR0UdRJX98oYO+XKGf7tiK4Zk6tQ/E4IJqGCe7dvkTvgDZV5cFJUzLGDOjeAXrnZoA6QkVySuxw==", + "dev": true, + "dependencies": { + "@microsoft/tsdoc": "0.14.2", + "ajv": "~6.12.6", + "jju": "~1.4.0", + "resolve": "~1.19.0" + } + }, + "node_modules/@microsoft/tsdoc-config/node_modules/resolve": { + "version": "1.19.0", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.19.0.tgz", + "integrity": "sha512-rArEXAgsBG4UgRGcynxWIWKFvh/XZCcS8UJdHhwy91zwAvCZIbcs+vAbflgBnNjYMs/i/i+/Ux6IZhML1yPvxg==", + "dev": true, + "dependencies": { + "is-core-module": "^2.1.0", + "path-parse": "^1.0.6" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, "node_modules/@nodelib/fs.scandir": { "version": "2.1.5", "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz", @@ -1559,6 +1698,107 @@ "url": "https://opencollective.com/unts" } }, + "node_modules/@rushstack/node-core-library": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/@rushstack/node-core-library/-/node-core-library-4.1.0.tgz", + "integrity": "sha512-qz4JFBZJCf1YN5cAXa1dP6Mki/HrsQxc/oYGAGx29dF2cwF2YMxHoly0FBhMw3IEnxo5fMj0boVfoHVBkpkx/w==", + "dev": true, + "dependencies": { + "fs-extra": "~7.0.1", + "import-lazy": "~4.0.0", + "jju": "~1.4.0", + "resolve": "~1.22.1", + "semver": "~7.5.4", + "z-schema": "~5.0.2" + }, + "peerDependencies": { + "@types/node": "*" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + } + } + }, + "node_modules/@rushstack/node-core-library/node_modules/semver": { + "version": "7.5.4", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.5.4.tgz", + "integrity": "sha512-1bCSESV6Pv+i21Hvpxp3Dx+pSD8lIPt8uVjRrxAUt/nbswYc+tK6Y2btiULjd4+fnq15PX+nqQDC7Oft7WkwcA==", + "dev": true, + "dependencies": { + "lru-cache": "^6.0.0" + }, + "bin": { + "semver": "bin/semver.js" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/@rushstack/rig-package": { + "version": "0.5.2", + "resolved": "https://registry.npmjs.org/@rushstack/rig-package/-/rig-package-0.5.2.tgz", + "integrity": "sha512-mUDecIJeH3yYGZs2a48k+pbhM6JYwWlgjs2Ca5f2n1G2/kgdgP9D/07oglEGf6mRyXEnazhEENeYTSNDRCwdqA==", + "dev": true, + "dependencies": { + "resolve": "~1.22.1", + "strip-json-comments": "~3.1.1" + } + }, + "node_modules/@rushstack/terminal": { + "version": "0.10.1", + "resolved": "https://registry.npmjs.org/@rushstack/terminal/-/terminal-0.10.1.tgz", + "integrity": "sha512-C6Vi/m/84IYJTkfzmXr1+W8Wi3MmBjVF/q3za91Gb3VYjKbpALHVxY6FgH625AnDe5Z0Kh4MHKWA3Z7bqgAezA==", + "dev": true, + "dependencies": { + "@rushstack/node-core-library": "4.1.0", + "supports-color": "~8.1.1" + }, + "peerDependencies": { + "@types/node": "*" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + } + } + }, + "node_modules/@rushstack/terminal/node_modules/has-flag": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", + "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", + "dev": true, + "engines": { + "node": ">=8" + } + }, + "node_modules/@rushstack/terminal/node_modules/supports-color": { + "version": "8.1.1", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-8.1.1.tgz", + "integrity": "sha512-MpUEN2OodtUzxvKQl72cUF7RQ5EiHsGvSsVG0ia9c5RbWGL2CI4C7EpPS8UTBIplnlzZiNuV56w+FuNxy3ty2Q==", + "dev": true, + "dependencies": { + "has-flag": "^4.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/supports-color?sponsor=1" + } + }, + "node_modules/@rushstack/ts-command-line": { + "version": "4.19.2", + "resolved": "https://registry.npmjs.org/@rushstack/ts-command-line/-/ts-command-line-4.19.2.tgz", + "integrity": "sha512-cqmXXmBEBlzo9WtyUrHtF9e6kl0LvBY7aTSVX4jfnBfXWZQWnPq9JTFPlQZ+L/ZwjZ4HrNwQsOVvhe9oOucZkw==", + "dev": true, + "dependencies": { + "@rushstack/terminal": "0.10.1", + "@types/argparse": "1.0.38", + "argparse": "~1.0.9", + "string-argv": "~0.3.1" + } + }, "node_modules/@sinclair/typebox": { "version": "0.27.8", "resolved": "https://registry.npmjs.org/@sinclair/typebox/-/typebox-0.27.8.tgz", @@ -1607,6 +1847,12 @@ "integrity": "sha512-yOlFc+7UtL/89t2ZhjPvvB/DeAr3r+Dq58IgzsFkOAvVC6NMJXmCGjbptdXdR9qsX7pKcTL+s87FtYREi2dEEQ==", "dev": true }, + "node_modules/@types/argparse": { + "version": "1.0.38", + "resolved": "https://registry.npmjs.org/@types/argparse/-/argparse-1.0.38.tgz", + "integrity": "sha512-ebDJ9b0e702Yr7pWgB0jzm+CX4Srzz8RcXtLJDJB+BSccqMa36uyH/zUsSYao5+BD1ytv3k3rPYCq4mAE1hsXA==", + "dev": true + }, "node_modules/@types/babel__core": { "version": "7.20.3", "resolved": "https://registry.npmjs.org/@types/babel__core/-/babel__core-7.20.3.tgz", @@ -3349,6 +3595,20 @@ "integrity": "sha512-5nqDSxl8nn5BSNxyR3n4I6eDmbolI6WT+QqR547RwxQapgjQBmtktdP+HTBb/a/zLsbzERTONyUB5pefh5TtjQ==", "dev": true }, + "node_modules/fs-extra": { + "version": "7.0.1", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-7.0.1.tgz", + "integrity": "sha512-YJDaCJZEnBmcbw13fvdAM9AwNOJwOzrE4pqMqBq5nFiEqXUqHwlK4B+3pUw6JNvfSPtX05xFHtYy/1ni01eGCw==", + "dev": true, + "dependencies": { + "graceful-fs": "^4.1.2", + "jsonfile": "^4.0.0", + "universalify": "^0.1.0" + }, + "engines": { + "node": ">=6 <7 || >=8" + } + }, "node_modules/fs.realpath": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz", @@ -3568,6 +3828,15 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/import-lazy": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/import-lazy/-/import-lazy-4.0.0.tgz", + "integrity": "sha512-rKtvo6a868b5Hu3heneU+L4yEQ4jYKLtjpnPeUdK7h0yzXGmyBTypknlkCvHFBqfX9YlorEiMM6Dnq/5atfHkw==", + "dev": true, + "engines": { + "node": ">=8" + } + }, "node_modules/import-local": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/import-local/-/import-local-3.1.0.tgz", @@ -5478,6 +5747,12 @@ "url": "https://github.com/chalk/supports-color?sponsor=1" } }, + "node_modules/jju": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/jju/-/jju-1.4.0.tgz", + "integrity": "sha512-8wb9Yw966OSxApiCt0K3yNJL8pnNeIv+OEq2YMidz4FKP6nonSRoOXc80iXY4JaN2FC11B9qsNmDsm+ZOfMROA==", + "dev": true + }, "node_modules/js-tokens": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz", @@ -5539,6 +5814,15 @@ "node": ">=6" } }, + "node_modules/jsonfile": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-4.0.0.tgz", + "integrity": "sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==", + "dev": true, + "optionalDependencies": { + "graceful-fs": "^4.1.6" + } + }, "node_modules/kleur": { "version": "3.0.3", "resolved": "https://registry.npmjs.org/kleur/-/kleur-3.0.3.tgz", @@ -5591,6 +5875,24 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/lodash": { + "version": "4.17.21", + "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz", + "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==", + "dev": true + }, + "node_modules/lodash.get": { + "version": "4.4.2", + "resolved": "https://registry.npmjs.org/lodash.get/-/lodash.get-4.4.2.tgz", + "integrity": "sha512-z+Uw/vLuy6gQe8cfaFWD7p0wVv8fJl3mbzXh33RS+0oW2wvUqiRXiQ69gLWSLpgB5/6sU+r6BlQR0MBILadqTQ==", + "dev": true + }, + "node_modules/lodash.isequal": { + "version": "4.5.0", + "resolved": "https://registry.npmjs.org/lodash.isequal/-/lodash.isequal-4.5.0.tgz", + "integrity": "sha512-pDo3lu8Jhfjqls6GkMgpahsF9kCyayhgykjyLMNFTKWrpVdAQtYyB4muAMWozBB4ig/dtWAmsMxLEI8wuz+DYQ==", + "dev": true + }, "node_modules/lodash.memoize": { "version": "4.1.2", "resolved": "https://registry.npmjs.org/lodash.memoize/-/lodash.memoize-4.1.2.tgz", @@ -6342,6 +6644,15 @@ "node": ">=8" } }, + "node_modules/string-argv": { + "version": "0.3.2", + "resolved": "https://registry.npmjs.org/string-argv/-/string-argv-0.3.2.tgz", + "integrity": "sha512-aqD2Q0144Z+/RqG52NeHEkZauTAUWJO8c6yTftGJKO3Tja5tUgIfmIl6kExvhtxSDP7fXB6DvzkfMpCd/F3G+Q==", + "dev": true, + "engines": { + "node": ">=0.6.19" + } + }, "node_modules/string-length": { "version": "4.0.2", "resolved": "https://registry.npmjs.org/string-length/-/string-length-4.0.2.tgz", @@ -6664,6 +6975,15 @@ "node": ">=4.2.0" } }, + "node_modules/universalify": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/universalify/-/universalify-0.1.2.tgz", + "integrity": "sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==", + "dev": true, + "engines": { + "node": ">= 4.0.0" + } + }, "node_modules/update-browserslist-db": { "version": "1.0.10", "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.0.10.tgz", @@ -6734,6 +7054,15 @@ "integrity": "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==", "dev": true }, + "node_modules/validator": { + "version": "13.11.0", + "resolved": "https://registry.npmjs.org/validator/-/validator-13.11.0.tgz", + "integrity": "sha512-Ii+sehpSfZy+At5nPdnyMhx78fEoPDkR2XW/zimHEL3MyGJQOCQ7WeP20jPYRz7ZCpcKLB21NxuXHF3bxjStBQ==", + "dev": true, + "engines": { + "node": ">= 0.10" + } + }, "node_modules/vows": { "version": "0.8.3", "resolved": "https://registry.npmjs.org/vows/-/vows-0.8.3.tgz", @@ -6888,6 +7217,36 @@ "funding": { "url": "https://github.com/sponsors/sindresorhus" } + }, + "node_modules/z-schema": { + "version": "5.0.5", + "resolved": "https://registry.npmjs.org/z-schema/-/z-schema-5.0.5.tgz", + "integrity": "sha512-D7eujBWkLa3p2sIpJA0d1pr7es+a7m0vFAnZLlCEKq/Ij2k0MLi9Br2UPxoxdYystm5K1yeBGzub0FlYUEWj2Q==", + "dev": true, + "dependencies": { + "lodash.get": "^4.4.2", + "lodash.isequal": "^4.5.0", + "validator": "^13.7.0" + }, + "bin": { + "z-schema": "bin/z-schema" + }, + "engines": { + "node": ">=8.0.0" + }, + "optionalDependencies": { + "commander": "^9.4.1" + } + }, + "node_modules/z-schema/node_modules/commander": { + "version": "9.5.0", + "resolved": "https://registry.npmjs.org/commander/-/commander-9.5.0.tgz", + "integrity": "sha512-KRs7WVDKg86PWiuAqhDrAQnTXZKraVcCc6vFdL14qrZ/DcWwuRo7VoiYXalXO7S5GKpqYiVEwCbgFDfxNHKJBQ==", + "dev": true, + "optional": true, + "engines": { + "node": "^12.20.0 || >=14" + } } }, "dependencies": { @@ -8008,6 +8367,121 @@ "@jridgewell/sourcemap-codec": "^1.4.14" } }, + "@microsoft/api-documenter": { + "version": "7.24.2", + "resolved": "https://registry.npmjs.org/@microsoft/api-documenter/-/api-documenter-7.24.2.tgz", + "integrity": "sha512-q03DXLBj7nzAzLyLRAVklBynqKgSFI/JBmrhF/mEEIpg8orNo4qKXWO1RSkD2IYrqvZV63b13mcUPYgcFdifQA==", + "dev": true, + "requires": { + "@microsoft/api-extractor-model": "7.28.14", + "@microsoft/tsdoc": "0.14.2", + "@rushstack/node-core-library": "4.1.0", + "@rushstack/terminal": "0.10.1", + "@rushstack/ts-command-line": "4.19.2", + "js-yaml": "~3.13.1", + "resolve": "~1.22.1" + }, + "dependencies": { + "js-yaml": { + "version": "3.13.1", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.13.1.tgz", + "integrity": "sha512-YfbcO7jXDdyj0DGxYVSlSeQNHbD7XPWvrVWeVUujrQEoZzWJIRrCPoyk6kL6IAjAG2IolMK4T0hNUe0HOUs5Jw==", + "dev": true, + "requires": { + "argparse": "^1.0.7", + "esprima": "^4.0.0" + } + } + } + }, + "@microsoft/api-extractor": { + "version": "7.43.1", + "resolved": "https://registry.npmjs.org/@microsoft/api-extractor/-/api-extractor-7.43.1.tgz", + "integrity": "sha512-ohg40SsvFFgzHFAtYq5wKJc8ZDyY46bphjtnSvhSSlXpPTG7GHwyyXkn48UZiUCBwr2WC7TRC1Jfwz7nreuiyQ==", + "dev": true, + "requires": { + "@microsoft/api-extractor-model": "7.28.14", + "@microsoft/tsdoc": "0.14.2", + "@microsoft/tsdoc-config": "~0.16.1", + "@rushstack/node-core-library": "4.1.0", + "@rushstack/rig-package": "0.5.2", + "@rushstack/terminal": "0.10.1", + "@rushstack/ts-command-line": "4.19.2", + "lodash": "~4.17.15", + "minimatch": "~3.0.3", + "resolve": "~1.22.1", + "semver": "~7.5.4", + "source-map": "~0.6.1", + "typescript": "5.4.2" + }, + "dependencies": { + "minimatch": { + "version": "3.0.8", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.0.8.tgz", + "integrity": "sha512-6FsRAQsxQ61mw+qP1ZzbL9Bc78x2p5OqNgNpnoAFLTrX8n5Kxph0CsnhmKKNXTWjXqU5L0pGPR7hYk+XWZr60Q==", + "dev": true, + "requires": { + "brace-expansion": "^1.1.7" + } + }, + "semver": { + "version": "7.5.4", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.5.4.tgz", + "integrity": "sha512-1bCSESV6Pv+i21Hvpxp3Dx+pSD8lIPt8uVjRrxAUt/nbswYc+tK6Y2btiULjd4+fnq15PX+nqQDC7Oft7WkwcA==", + "dev": true, + "requires": { + "lru-cache": "^6.0.0" + } + }, + "typescript": { + "version": "5.4.2", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.4.2.tgz", + "integrity": "sha512-+2/g0Fds1ERlP6JsakQQDXjZdZMM+rqpamFZJEKh4kwTIn3iDkgKtby0CeNd5ATNZ4Ry1ax15TMx0W2V+miizQ==", + "dev": true + } + } + }, + "@microsoft/api-extractor-model": { + "version": "7.28.14", + "resolved": "https://registry.npmjs.org/@microsoft/api-extractor-model/-/api-extractor-model-7.28.14.tgz", + "integrity": "sha512-Bery/c8A8SsKPSvA82cTTuy/+OcxZbLRmKhPkk91/AJOQzxZsShcrmHFAGeiEqSIrv1nPZ3tKq9kfMLdCHmsqg==", + "dev": true, + "requires": { + "@microsoft/tsdoc": "0.14.2", + "@microsoft/tsdoc-config": "~0.16.1", + "@rushstack/node-core-library": "4.1.0" + } + }, + "@microsoft/tsdoc": { + "version": "0.14.2", + "resolved": "https://registry.npmjs.org/@microsoft/tsdoc/-/tsdoc-0.14.2.tgz", + "integrity": "sha512-9b8mPpKrfeGRuhFH5iO1iwCLeIIsV6+H1sRfxbkoGXIyQE2BTsPd9zqSqQJ+pv5sJ/hT5M1zvOFL02MnEezFug==", + "dev": true + }, + "@microsoft/tsdoc-config": { + "version": "0.16.2", + "resolved": "https://registry.npmjs.org/@microsoft/tsdoc-config/-/tsdoc-config-0.16.2.tgz", + "integrity": "sha512-OGiIzzoBLgWWR0UdRJX98oYO+XKGf7tiK4Zk6tQ/E4IJqGCe7dvkTvgDZV5cFJUzLGDOjeAXrnZoA6QkVySuxw==", + "dev": true, + "requires": { + "@microsoft/tsdoc": "0.14.2", + "ajv": "~6.12.6", + "jju": "~1.4.0", + "resolve": "~1.19.0" + }, + "dependencies": { + "resolve": { + "version": "1.19.0", + "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.19.0.tgz", + "integrity": "sha512-rArEXAgsBG4UgRGcynxWIWKFvh/XZCcS8UJdHhwy91zwAvCZIbcs+vAbflgBnNjYMs/i/i+/Ux6IZhML1yPvxg==", + "dev": true, + "requires": { + "is-core-module": "^2.1.0", + "path-parse": "^1.0.6" + } + } + } + }, "@nodelib/fs.scandir": { "version": "2.1.5", "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz", @@ -8040,6 +8514,80 @@ "integrity": "sha512-Zwq5OCzuwJC2jwqmpEQt7Ds1DTi6BWSwoGkbb1n9pO3hzb35BoJELx7c0T23iDkBGkh2e7tvOtjF3tr3OaQHDQ==", "dev": true }, + "@rushstack/node-core-library": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/@rushstack/node-core-library/-/node-core-library-4.1.0.tgz", + "integrity": "sha512-qz4JFBZJCf1YN5cAXa1dP6Mki/HrsQxc/oYGAGx29dF2cwF2YMxHoly0FBhMw3IEnxo5fMj0boVfoHVBkpkx/w==", + "dev": true, + "requires": { + "fs-extra": "~7.0.1", + "import-lazy": "~4.0.0", + "jju": "~1.4.0", + "resolve": "~1.22.1", + "semver": "~7.5.4", + "z-schema": "~5.0.2" + }, + "dependencies": { + "semver": { + "version": "7.5.4", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.5.4.tgz", + "integrity": "sha512-1bCSESV6Pv+i21Hvpxp3Dx+pSD8lIPt8uVjRrxAUt/nbswYc+tK6Y2btiULjd4+fnq15PX+nqQDC7Oft7WkwcA==", + "dev": true, + "requires": { + "lru-cache": "^6.0.0" + } + } + } + }, + "@rushstack/rig-package": { + "version": "0.5.2", + "resolved": "https://registry.npmjs.org/@rushstack/rig-package/-/rig-package-0.5.2.tgz", + "integrity": "sha512-mUDecIJeH3yYGZs2a48k+pbhM6JYwWlgjs2Ca5f2n1G2/kgdgP9D/07oglEGf6mRyXEnazhEENeYTSNDRCwdqA==", + "dev": true, + "requires": { + "resolve": "~1.22.1", + "strip-json-comments": "~3.1.1" + } + }, + "@rushstack/terminal": { + "version": "0.10.1", + "resolved": "https://registry.npmjs.org/@rushstack/terminal/-/terminal-0.10.1.tgz", + "integrity": "sha512-C6Vi/m/84IYJTkfzmXr1+W8Wi3MmBjVF/q3za91Gb3VYjKbpALHVxY6FgH625AnDe5Z0Kh4MHKWA3Z7bqgAezA==", + "dev": true, + "requires": { + "@rushstack/node-core-library": "4.1.0", + "supports-color": "~8.1.1" + }, + "dependencies": { + "has-flag": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", + "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", + "dev": true + }, + "supports-color": { + "version": "8.1.1", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-8.1.1.tgz", + "integrity": "sha512-MpUEN2OodtUzxvKQl72cUF7RQ5EiHsGvSsVG0ia9c5RbWGL2CI4C7EpPS8UTBIplnlzZiNuV56w+FuNxy3ty2Q==", + "dev": true, + "requires": { + "has-flag": "^4.0.0" + } + } + } + }, + "@rushstack/ts-command-line": { + "version": "4.19.2", + "resolved": "https://registry.npmjs.org/@rushstack/ts-command-line/-/ts-command-line-4.19.2.tgz", + "integrity": "sha512-cqmXXmBEBlzo9WtyUrHtF9e6kl0LvBY7aTSVX4jfnBfXWZQWnPq9JTFPlQZ+L/ZwjZ4HrNwQsOVvhe9oOucZkw==", + "dev": true, + "requires": { + "@rushstack/terminal": "0.10.1", + "@types/argparse": "1.0.38", + "argparse": "~1.0.9", + "string-argv": "~0.3.1" + } + }, "@sinclair/typebox": { "version": "0.27.8", "resolved": "https://registry.npmjs.org/@sinclair/typebox/-/typebox-0.27.8.tgz", @@ -8088,6 +8636,12 @@ "integrity": "sha512-yOlFc+7UtL/89t2ZhjPvvB/DeAr3r+Dq58IgzsFkOAvVC6NMJXmCGjbptdXdR9qsX7pKcTL+s87FtYREi2dEEQ==", "dev": true }, + "@types/argparse": { + "version": "1.0.38", + "resolved": "https://registry.npmjs.org/@types/argparse/-/argparse-1.0.38.tgz", + "integrity": "sha512-ebDJ9b0e702Yr7pWgB0jzm+CX4Srzz8RcXtLJDJB+BSccqMa36uyH/zUsSYao5+BD1ytv3k3rPYCq4mAE1hsXA==", + "dev": true + }, "@types/babel__core": { "version": "7.20.3", "resolved": "https://registry.npmjs.org/@types/babel__core/-/babel__core-7.20.3.tgz", @@ -9366,6 +9920,17 @@ "integrity": "sha512-5nqDSxl8nn5BSNxyR3n4I6eDmbolI6WT+QqR547RwxQapgjQBmtktdP+HTBb/a/zLsbzERTONyUB5pefh5TtjQ==", "dev": true }, + "fs-extra": { + "version": "7.0.1", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-7.0.1.tgz", + "integrity": "sha512-YJDaCJZEnBmcbw13fvdAM9AwNOJwOzrE4pqMqBq5nFiEqXUqHwlK4B+3pUw6JNvfSPtX05xFHtYy/1ni01eGCw==", + "dev": true, + "requires": { + "graceful-fs": "^4.1.2", + "jsonfile": "^4.0.0", + "universalify": "^0.1.0" + } + }, "fs.realpath": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz", @@ -9518,6 +10083,12 @@ "resolve-from": "^4.0.0" } }, + "import-lazy": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/import-lazy/-/import-lazy-4.0.0.tgz", + "integrity": "sha512-rKtvo6a868b5Hu3heneU+L4yEQ4jYKLtjpnPeUdK7h0yzXGmyBTypknlkCvHFBqfX9YlorEiMM6Dnq/5atfHkw==", + "dev": true + }, "import-local": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/import-local/-/import-local-3.1.0.tgz", @@ -10928,6 +11499,12 @@ } } }, + "jju": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/jju/-/jju-1.4.0.tgz", + "integrity": "sha512-8wb9Yw966OSxApiCt0K3yNJL8pnNeIv+OEq2YMidz4FKP6nonSRoOXc80iXY4JaN2FC11B9qsNmDsm+ZOfMROA==", + "dev": true + }, "js-tokens": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz", @@ -10974,6 +11551,15 @@ "integrity": "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==", "dev": true }, + "jsonfile": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-4.0.0.tgz", + "integrity": "sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==", + "dev": true, + "requires": { + "graceful-fs": "^4.1.6" + } + }, "kleur": { "version": "3.0.3", "resolved": "https://registry.npmjs.org/kleur/-/kleur-3.0.3.tgz", @@ -11011,6 +11597,24 @@ "p-locate": "^5.0.0" } }, + "lodash": { + "version": "4.17.21", + "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz", + "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==", + "dev": true + }, + "lodash.get": { + "version": "4.4.2", + "resolved": "https://registry.npmjs.org/lodash.get/-/lodash.get-4.4.2.tgz", + "integrity": "sha512-z+Uw/vLuy6gQe8cfaFWD7p0wVv8fJl3mbzXh33RS+0oW2wvUqiRXiQ69gLWSLpgB5/6sU+r6BlQR0MBILadqTQ==", + "dev": true + }, + "lodash.isequal": { + "version": "4.5.0", + "resolved": "https://registry.npmjs.org/lodash.isequal/-/lodash.isequal-4.5.0.tgz", + "integrity": "sha512-pDo3lu8Jhfjqls6GkMgpahsF9kCyayhgykjyLMNFTKWrpVdAQtYyB4muAMWozBB4ig/dtWAmsMxLEI8wuz+DYQ==", + "dev": true + }, "lodash.memoize": { "version": "4.1.2", "resolved": "https://registry.npmjs.org/lodash.memoize/-/lodash.memoize-4.1.2.tgz", @@ -11553,6 +12157,12 @@ } } }, + "string-argv": { + "version": "0.3.2", + "resolved": "https://registry.npmjs.org/string-argv/-/string-argv-0.3.2.tgz", + "integrity": "sha512-aqD2Q0144Z+/RqG52NeHEkZauTAUWJO8c6yTftGJKO3Tja5tUgIfmIl6kExvhtxSDP7fXB6DvzkfMpCd/F3G+Q==", + "dev": true + }, "string-length": { "version": "4.0.2", "resolved": "https://registry.npmjs.org/string-length/-/string-length-4.0.2.tgz", @@ -11754,6 +12364,12 @@ "integrity": "sha512-1FXk9E2Hm+QzZQ7z+McJiHL4NW1F2EzMu9Nq9i3zAaGqibafqYwCVU6WyWAuyQRRzOlxou8xZSyXLEN8oKj24g==", "dev": true }, + "universalify": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/universalify/-/universalify-0.1.2.tgz", + "integrity": "sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==", + "dev": true + }, "update-browserslist-db": { "version": "1.0.10", "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.0.10.tgz", @@ -11807,6 +12423,12 @@ } } }, + "validator": { + "version": "13.11.0", + "resolved": "https://registry.npmjs.org/validator/-/validator-13.11.0.tgz", + "integrity": "sha512-Ii+sehpSfZy+At5nPdnyMhx78fEoPDkR2XW/zimHEL3MyGJQOCQ7WeP20jPYRz7ZCpcKLB21NxuXHF3bxjStBQ==", + "dev": true + }, "vows": { "version": "0.8.3", "resolved": "https://registry.npmjs.org/vows/-/vows-0.8.3.tgz", @@ -11924,6 +12546,27 @@ "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz", "integrity": "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==", "dev": true + }, + "z-schema": { + "version": "5.0.5", + "resolved": "https://registry.npmjs.org/z-schema/-/z-schema-5.0.5.tgz", + "integrity": "sha512-D7eujBWkLa3p2sIpJA0d1pr7es+a7m0vFAnZLlCEKq/Ij2k0MLi9Br2UPxoxdYystm5K1yeBGzub0FlYUEWj2Q==", + "dev": true, + "requires": { + "commander": "^9.4.1", + "lodash.get": "^4.4.2", + "lodash.isequal": "^4.5.0", + "validator": "^13.7.0" + }, + "dependencies": { + "commander": { + "version": "9.5.0", + "resolved": "https://registry.npmjs.org/commander/-/commander-9.5.0.tgz", + "integrity": "sha512-KRs7WVDKg86PWiuAqhDrAQnTXZKraVcCc6vFdL14qrZ/DcWwuRo7VoiYXalXO7S5GKpqYiVEwCbgFDfxNHKJBQ==", + "dev": true, + "optional": true + } + } } } } diff --git a/package.json b/package.json index c7824e0a..b716dad6 100644 --- a/package.json +++ b/package.json @@ -84,9 +84,12 @@ "!__tests__" ], "scripts": { + "api:dev": "npm run build && npm run api:extract -- --local && npm run api:docs", + "api:docs": "api-documenter markdown --input-folder ./tmp --output-folder ./api/docs", + "api:extract": "api-extractor run --verbose", "build": "npm run clean && tsc", "clean": "rm -rf dist", - "version": "genversion --es6 lib/version.ts && git add lib/version.ts", + "version": "genversion --template version-template.ejs --force lib/version.ts && git add lib/version.ts", "test": "npm run test:ts && npm run test:legacy", "test:ts": "jest", "test:legacy": "npm run build -- --declaration false && ./test/scripts/vows.js test/*_test.js", @@ -100,6 +103,8 @@ "node": ">=16" }, "devDependencies": { + "@microsoft/api-documenter": "^7.23.37", + "@microsoft/api-extractor": "^7.42.3", "@types/jest": "^29.5.10", "@types/node": "^14.18.63", "@types/punycode": "^2.1.4", diff --git a/test/api_test.js b/test/api_test.js index 28920e20..acc589c9 100644 --- a/test/api_test.js +++ b/test/api_test.js @@ -739,7 +739,7 @@ function allowSpecialUseOptionVows() { assert.ok(!cookie); assert.equal( err.message, - `Cookie has domain set to the public suffix "${specialUseDomain}" which is a special use domain. To allow this, configure your CookieJar with {allowSpecialUseDomain:true, rejectPublicSuffixes: false}.` + `Cookie has domain set to the public suffix "${specialUseDomain}" which is a special use domain. To allow this, configure your CookieJar with {allowSpecialUseDomain: true, rejectPublicSuffixes: false}.` ); } }; diff --git a/version-template.ejs b/version-template.ejs new file mode 100644 index 00000000..6ee2436d --- /dev/null +++ b/version-template.ejs @@ -0,0 +1,5 @@ +/** + * The version of `tough-cookie` + * @public + */ +export const version = '<%= pkg.version %>'