From 20f629cc511306b5bb9314f12b347b404b62575f Mon Sep 17 00:00:00 2001 From: Colin Casey Date: Mon, 22 Apr 2024 12:08:41 -0300 Subject: [PATCH] Replace derived `CreateCookieOptions` with explicit type --- api/docs/tough-cookie.cookie._constructor_.md | 2 +- api/docs/tough-cookie.cookie.parse.md | 2 +- api/docs/tough-cookie.cookie.tojson.md | 2 +- api/docs/tough-cookie.createcookieoptions.md | 306 ++++++++++++++++++ api/docs/tough-cookie.md | 48 +++ .../tough-cookie.parsecookieoptions.loose.md | 13 + api/docs/tough-cookie.parsecookieoptions.md | 57 ++++ api/docs/tough-cookie.serializedcookie.md | 17 + api/docs/tough-cookie.serializedcookiejar.md | 2 +- api/tough-cookie.api.md | 33 +- lib/cookie/cookie.ts | 42 ++- lib/cookie/index.ts | 8 +- 12 files changed, 512 insertions(+), 20 deletions(-) create mode 100644 api/docs/tough-cookie.createcookieoptions.md create mode 100644 api/docs/tough-cookie.parsecookieoptions.loose.md create mode 100644 api/docs/tough-cookie.parsecookieoptions.md create mode 100644 api/docs/tough-cookie.serializedcookie.md diff --git a/api/docs/tough-cookie.cookie._constructor_.md b/api/docs/tough-cookie.cookie._constructor_.md index 80022b88..a2bbe638 100644 --- a/api/docs/tough-cookie.cookie._constructor_.md +++ b/api/docs/tough-cookie.cookie._constructor_.md @@ -37,7 +37,7 @@ options -CreateCookieOptions +[CreateCookieOptions](./tough-cookie.createcookieoptions.md) diff --git a/api/docs/tough-cookie.cookie.parse.md b/api/docs/tough-cookie.cookie.parse.md index 0ffb1e3d..6dbd2b07 100644 --- a/api/docs/tough-cookie.cookie.parse.md +++ b/api/docs/tough-cookie.cookie.parse.md @@ -53,7 +53,7 @@ options -ParseCookieOptions +[ParseCookieOptions](./tough-cookie.parsecookieoptions.md) diff --git a/api/docs/tough-cookie.cookie.tojson.md b/api/docs/tough-cookie.cookie.tojson.md index 840aa6d4..42888171 100644 --- a/api/docs/tough-cookie.cookie.tojson.md +++ b/api/docs/tough-cookie.cookie.tojson.md @@ -13,7 +13,7 @@ toJSON(): SerializedCookie; ``` **Returns:** -SerializedCookie +[SerializedCookie](./tough-cookie.serializedcookie.md) ## Remarks 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.md b/api/docs/tough-cookie.md index ffd2ab47..6668152f 100644 --- a/api/docs/tough-cookie.md +++ b/api/docs/tough-cookie.md @@ -245,6 +245,17 @@ A callback function that accepts an error or a result. 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). + + @@ -278,6 +289,17 @@ Configuration options used when calling `CookieJar.getCookies(...)`. Options for configuring how [getPublicSuffix()](./tough-cookie.getpublicsuffix.md) behaves. + + + +[ParseCookieOptions](./tough-cookie.parsecookieoptions.md) + + + + +Optional configuration to be used when parsing cookies. + + @@ -363,5 +385,31 @@ The following values can be used to configure how a [CookieJar](./tough-cookie.c The version of `tough-cookie` + + + +## Type Aliases + + +
+ +Type Alias + + + + +Description + + +
+ +[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.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.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.md b/api/docs/tough-cookie.serializedcookiejar.md index e99d52ed..e47ee577 100644 --- a/api/docs/tough-cookie.serializedcookiejar.md +++ b/api/docs/tough-cookie.serializedcookiejar.md @@ -45,7 +45,7 @@ Description -SerializedCookie\[\] +[SerializedCookie](./tough-cookie.serializedcookie.md)\[\] diff --git a/api/tough-cookie.api.md b/api/tough-cookie.api.md index da19bc77..b0e38a47 100644 --- a/api/tough-cookie.api.md +++ b/api/tough-cookie.api.md @@ -21,7 +21,6 @@ export function canonicalDomain(domainName: Nullable): string | undefine // @public export class Cookie { - // Warning: (ae-forgotten-export) The symbol "CreateCookieOptions" needs to be exported by the entry point index.d.ts constructor(options?: CreateCookieOptions); canonicalizedDomain(): string | undefined; cdomain(): string | undefined; @@ -40,7 +39,6 @@ export class Cookie { key: string; lastAccessed: Date | 'Infinity' | null; maxAge: number | 'Infinity' | '-Infinity' | null; - // Warning: (ae-forgotten-export) The symbol "ParseCookieOptions" needs to be exported by the entry point index.d.ts static parse(str: string, options?: ParseCookieOptions): Cookie | undefined; path: string | null; pathIsDefault: boolean | null; @@ -60,7 +58,6 @@ export class Cookie { 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; - // Warning: (ae-forgotten-export) The symbol "SerializedCookie" needs to be exported by the entry point index.d.ts toJSON(): SerializedCookie; toString(): string; TTL(now?: number): number; @@ -135,6 +132,24 @@ export interface CreateCookieJarOptions { 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; @@ -204,6 +219,11 @@ export class ParameterError extends Error { // @public (undocumented) export const parse: typeof Cookie.parse; +// @public +export interface ParseCookieOptions { + loose?: boolean | undefined; +} + // @public export function parseDate(cookieDate: Nullable): Date | undefined; @@ -223,6 +243,13 @@ export const PrefixSecurityEnum: Readonly<{ DISABLED: "unsafe-disabled"; }>; +// @public +export type SerializedCookie = { + key?: string; + value?: string; + [key: string]: unknown; +}; + // @public export interface SerializedCookieJar { [key: string]: unknown; diff --git a/lib/cookie/cookie.ts b/lib/cookie/cookie.ts index 2747502d..1568e50c 100644 --- a/lib/cookie/cookie.ts +++ b/lib/cookie/cookie.ts @@ -373,19 +373,39 @@ function fromJSON(str: unknown): Cookie | undefined { } /** - * Type alias for all the cookie properties defined by {@link Cookie} (except for {@link Cookie.creationIndex}). + * Configurable values that can be set when creating a {@link Cookie}. * @public */ -export 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' -> +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: diff --git a/lib/cookie/index.ts b/lib/cookie/index.ts index e14c7999..6e90808b 100644 --- a/lib/cookie/index.ts +++ b/lib/cookie/index.ts @@ -7,8 +7,12 @@ export { ParameterError } from '../validators' export { version } from '../version' export { Callback, ErrorCallback } from '../utils' export { canonicalDomain } from './canonicalDomain' -export { PrefixSecurityEnum, SerializedCookieJar } from './constants' -export { Cookie } from './cookie' +export { + PrefixSecurityEnum, + SerializedCookie, + SerializedCookieJar, +} from './constants' +export { Cookie, CreateCookieOptions, ParseCookieOptions } from './cookie' export { cookieCompare } from './cookieCompare' export { CookieJar,