[tough-cookie]: update definitions for version 4 (#43374)

2026-02-06 10:56:53 +00:00 · 2020-03-31 18:19:45 -05:00 · 2020-03-31 18:19:45 -05:00 · 74c6a6ac77
commit 74c6a6ac77
parent 314ba85888
7 changed files with 434 additions and 43 deletions
--- a/types/tough-cookie-file-store/tsconfig.json
+++ b/types/tough-cookie-file-store/tsconfig.json
@ -13,6 +13,9 @@
            "../"
        ],
        "types": [],
+        "paths": {
+            "tough-cookie": ["tough-cookie/v2"]
+        },
        "noEmit": true,
        "forceConsistentCasingInFileNames": true
    },
--- a/types/tough-cookie/index.d.ts
+++ b/types/tough-cookie/index.d.ts
@ -1,4 +1,4 @@
-// Type definitions for tough-cookie 2.3
+// Type definitions for tough-cookie 4.0
 // Project: https://github.com/salesforce/tough-cookie
 // Definitions by: Leonard Thieu <https://github.com/leonard-thieu>
 //                 LiJinyao <https://github.com/LiJinyao>
@ -6,6 +6,14 @@
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
 // TypeScript Version: 2.2

+export const version: string;
+
+export const PrefixSecurityEnum: Readonly<{
+    DISABLED: string;
+    SILENT: string;
+    STRICT: string;
+}>;
+
 /**
 * Parse a cookie date string into a Date.
 * Parses according to RFC6265 Section 5.1.1, not Date.parse().
@ -51,6 +59,11 @@ export function defaultPath(path: string): string;
 */
 export function pathMatch(reqPath: string, cookiePath: string): boolean;

+/**
+ * alias for Cookie.parse(cookieString[, options])
+ */
+export function parse(cookieString: string, options?: Cookie.ParseOptions): Cookie | undefined;
+
 /**
 * alias for Cookie.fromJSON(string)
 */
@ -60,12 +73,10 @@ export function getPublicSuffix(hostname: string): string | null;

 export function cookieCompare(a: Cookie, b: Cookie): number;

-export function permuteDomain(domain: string): string[];
+export function permuteDomain(domain: string, allowSpecialUseDomain?: boolean): string[];

 export function permutePath(path: string): string[];

-// region Cookie
-
 export class Cookie {
    static parse(cookieString: string, options?: Cookie.ParseOptions): Cookie | undefined;

@ -88,24 +99,29 @@ export class Cookie {
    hostOnly: boolean | null;
    pathIsDefault: boolean | null;
    lastAccessed: Date | null;
+    sameSite: string;

    toString(): string;

    cookieString(): string;

-    setExpires(String: string): void;
+    setExpires(exp: Date | string): void;

    setMaxAge(number: number): void;

-    expiryTime(now?: number): number | typeof Infinity;
+    expiryTime(now?: number): number;

    expiryDate(now?: number): Date;

    TTL(now?: Date): number | typeof Infinity;

-    canonicalizedDomain(): string;
+    isPersistent(): boolean;

-    cdomain(): string;
+    canonicalizedDomain(): string | null;
+
+    cdomain(): string | null;
+
+    inspect(): string;

    toJSON(): { [key: string]: any; };

@ -135,6 +151,7 @@ export namespace Cookie {
        hostOnly?: boolean;
        pathIsDefault?: boolean;
        lastAccessed?: Date;
+        sameSite?: string;
    }

    interface Serialized {
@ -142,11 +159,8 @@ export namespace Cookie {
    }
 }

-// endregion
-
-// region CookieJar
-
 export class CookieJar {
+    static deserialize(serialized: CookieJar.Serialized | string, store?: Store): Promise<CookieJar>;
    static deserialize(serialized: CookieJar.Serialized | string, store: Store, cb: (err: Error | null, object: CookieJar) => void): void;
    static deserialize(serialized: CookieJar.Serialized | string, cb: (err: Error | null, object: CookieJar) => void): void;

@ -156,42 +170,55 @@ export class CookieJar {

    constructor(store?: Store, options?: CookieJar.Options);

+    setCookie(cookieOrString: Cookie | string, currentUrl: string, options?: CookieJar.SetCookieOptions): Promise<Cookie>;
    setCookie(cookieOrString: Cookie | string, currentUrl: string, options: CookieJar.SetCookieOptions, cb: (err: Error | null, cookie: Cookie) => void): void;
-    setCookie(cookieOrString: Cookie | string, currentUrl: string, cb: (err: Error, cookie: Cookie) => void): void;
+    setCookie(cookieOrString: Cookie | string, currentUrl: string, cb: (err: Error | null, cookie: Cookie) => void): void;

-    setCookieSync(cookieOrString: Cookie | string, currentUrl: string, options?: CookieJar.SetCookieOptions): void;
+    setCookieSync(cookieOrString: Cookie | string, currentUrl: string, options?: CookieJar.SetCookieOptions): Cookie;

+    getCookies(currentUrl: string, options?: CookieJar.GetCookiesOptions): Promise<Cookie[]>;
    getCookies(currentUrl: string, options: CookieJar.GetCookiesOptions, cb: (err: Error | null, cookies: Cookie[]) => void): void;
    getCookies(currentUrl: string, cb: (err: Error | null, cookies: Cookie[]) => void): void;

    getCookiesSync(currentUrl: string, options?: CookieJar.GetCookiesOptions): Cookie[];

+    getCookieString(currentUrl: string, options?: CookieJar.GetCookiesOptions): Promise<string>;
    getCookieString(currentUrl: string, options: CookieJar.GetCookiesOptions, cb: (err: Error | null, cookies: string) => void): void;
    getCookieString(currentUrl: string, cb: (err: Error | null, cookies: string) => void): void;

    getCookieStringSync(currentUrl: string, options?: CookieJar.GetCookiesOptions): string;

-    getSetCookieStrings(currentUrl: string, options: CookieJar.GetCookiesOptions, cb: (err: Error | null, cookies: string) => void): void;
-    getSetCookieStrings(currentUrl: string, cb: (err: Error | null, cookies: string) => void): void;
+    getSetCookieStrings(currentUrl: string, options?: CookieJar.GetCookiesOptions): Promise<string[]>;
+    getSetCookieStrings(currentUrl: string, options: CookieJar.GetCookiesOptions, cb: (err: Error | null, cookies: string[]) => void): void;
+    getSetCookieStrings(currentUrl: string, cb: (err: Error | null, cookies: string[]) => void): void;

-    getSetCookieStringsSync(currentUrl: string, options?: CookieJar.GetCookiesOptions): string;
+    getSetCookieStringsSync(currentUrl: string, options?: CookieJar.GetCookiesOptions): string[];

+    serialize(): Promise<CookieJar.Serialized>;
    serialize(cb: (err: Error | null, serializedObject: CookieJar.Serialized) => void): void;

    serializeSync(): CookieJar.Serialized;

    toJSON(): CookieJar.Serialized;

+    clone(store?: Store): Promise<CookieJar>;
    clone(store: Store, cb: (err: Error | null, newJar: CookieJar) => void): void;
    clone(cb: (err: Error | null, newJar: CookieJar) => void): void;

-    cloneSync(store: Store): CookieJar;
+    cloneSync(store?: Store): CookieJar;
+
+    removeAllCookies(): Promise<void>;
+    removeAllCookies(cb: (err: Error | null) => void): void;
+
+    removeAllCookiesSync(): void;
 }

 export namespace CookieJar {
    interface Options {
-        rejectPublicSuffixes?: boolean;
+        allowSpecialUseDomain?: boolean;
        looseMode?: boolean;
+        rejectPublicSuffixes?: boolean;
+        prefixSecurity?: string;
    }

    interface SetCookieOptions {
@ -217,14 +244,12 @@ export namespace CookieJar {
    }
 }

-// endregion
-
-// region Store
-
 export abstract class Store {
+    synchronous: boolean;
+
    findCookie(domain: string, path: string, key: string, cb: (err: Error | null, cookie: Cookie | null) => void): void;

-    findCookies(domain: string, path: string, cb: (err: Error | null, cookie: Cookie[]) => void): void;
+    findCookies(domain: string, path: string, allowSpecialUseDomain: boolean, cb: (err: Error | null, cookie: Cookie[]) => void): void;

    putCookie(cookie: Cookie, cb: (err: Error | null) => void): void;

@ -238,5 +263,3 @@ export abstract class Store {
 }

 export class MemoryCookieStore extends Store { }
-
-// endregion
--- a/types/tough-cookie/tough-cookie-tests.ts
+++ b/types/tough-cookie/tough-cookie-tests.ts
@ -1,26 +1,91 @@
-import { Cookie, CookieJar, MemoryCookieStore } from 'tough-cookie';
+import { Cookie, CookieJar, MemoryCookieStore, PrefixSecurityEnum, version } from 'tough-cookie';
+
+version; // $ExpectType string
+PrefixSecurityEnum.DISABLED; // $ExpectType string
+PrefixSecurityEnum.SILENT; // $ExpectType string
+PrefixSecurityEnum.STRICT; // $ExpectType string

 let header = '';
-const cb = () => { };
+const cb = (err: Error | null) => { };
+const cbCookie = (err: Error | null, cookie: Cookie | null) => {};
+const cbCookies = (err: Error | null, cookies: Cookie[]) => {};
+const cbCookieJar = (err: Error | null, jar: CookieJar) => {};
+const cbString = (err: Error | null, value: string) => {};
+const cbStrings = (err: Error | null, value: string[]) => {};

-const cookie = Cookie.parse(header)!;
+const url = 'http://example.com/otherpath';
+const cookie: Cookie = Cookie.parse(header)!;
 cookie.value = 'somethingdifferent';
 header = cookie.toString();

-const cookiejar = new CookieJar();
-cookiejar.setCookie(cookie, 'http://currentdomain.example.com/path', cb);
-// ...
-cookiejar.getCookies('http://example.com/otherpath', (err, cookies) => {
-    // res.headers['cookie'] = cookies.join('; ');
-});
+const jar = new CookieJar();
+jar.setCookie(cookie, 'http://currentdomain.example.com/path'); // $ExpectType Promise<Cookie>
+jar.setCookie(cookie, 'http://currentdomain.example.com/path', cbCookie); // $ExpectType void
+jar.setCookie(cookie, 'http://currentdomain.example.com/path', {}, cbCookie); // $ExpectType void

-// All option are optional.
-cookiejar.getCookies('http://example.com/otherpath', {}, () => {});
+jar.setCookieSync(cookie, 'http://currentdomain.example.com/path'); // $ExpectType Cookie

-cookiejar.getCookies('http://example.com/otherpath', {
-    now: new Date(),
-    allPaths: true,
-}, () => {});
+jar.getCookies(url); // $ExpectType Promise<Cookie[]>
+jar.getCookies(url, {}); // $ExpectType Promise<Cookie[]>
+jar.getCookies(url, cbCookies); // $ExpectType void
+jar.getCookies(url, { now: new Date(), allPaths: true }, cbCookies); // $ExpectType void

-CookieJar.deserializeSync("test cookie with store", new MemoryCookieStore());
-CookieJar.deserializeSync("test cookie");
+jar.getCookiesSync(url); // $ExpectType Cookie[]
+jar.getCookiesSync(url, {}); // $ExpectType Cookie[]
+
+jar.getCookieString(url); // $ExpectType Promise<string>
+jar.getCookieString(url, cbString); // $ExpectType void
+jar.getCookieString(url, {}, cbString); // $ExpectType void
+
+jar.getCookieStringSync(url); // $ExpectType string
+jar.getCookieStringSync(url, {}); // $ExpectType string
+
+jar.getSetCookieStrings(url); // $ExpectType Promise<string[]>
+jar.getSetCookieStrings(url, cbStrings); // $ExpectType void
+jar.getSetCookieStrings(url, {}, cbStrings); // $ExpectType void
+
+jar.getSetCookieStringsSync(url); // $ExpectType string[]
+jar.getSetCookieStringsSync(url, {}); // $ExpectType string[]
+
+jar.serialize(); // $ExpectType Promise<Serialized>
+jar.serialize((err: Error | null, serializedObject: CookieJar.Serialized): void => {}); // $ExpectType void
+
+jar.serializeSync(); // $ExpectType Serialized
+
+jar.toJSON(); // $ExpectType Serialized
+
+jar.clone(); // $ExpectType Promise<CookieJar>
+jar.clone(new MemoryCookieStore()); // $ExpectType Promise<CookieJar>
+jar.clone(cbCookieJar); // $ExpectType void
+jar.clone(new MemoryCookieStore(), cbCookieJar); // $ExpectType void
+
+jar.cloneSync(); // $ExpectType CookieJar
+jar.cloneSync(new MemoryCookieStore()); // $ExpectType CookieJar
+
+jar.removeAllCookies(); // $ExpectType Promise<void>
+jar.removeAllCookies(cb); // $ExpectType void
+
+jar.removeAllCookiesSync(); // $ExpectType void
+
+CookieJar.deserialize("", cbCookieJar); // $ExpectType void
+CookieJar.deserialize("", new MemoryCookieStore(), cbCookieJar); // $ExpectType void
+CookieJar.deserialize(""); // $ExpectType Promise<CookieJar>
+CookieJar.deserialize("", new MemoryCookieStore()); // $ExpectType Promise<CookieJar>
+
+CookieJar.deserializeSync("test cookie with store", new MemoryCookieStore()); // $ExpectType CookieJar
+CookieJar.deserializeSync("test cookie"); // $ExpectType CookieJar
+
+const store = new MemoryCookieStore();
+store.findCookie('example.com', '/', 'foo', cbCookie); // $ExpectType void
+
+store.findCookies('example.com', '/', false, cbCookies); // $ExpectType void
+
+store.putCookie(cookie, cb); // $ExpectType void
+
+store.updateCookie(cookie, cookie, cb); // $ExpectType void
+
+store.removeCookie('example.com', '/', 'foo', cb); // $ExpectType void
+
+store.removeCookies('example.com', '/', cb); // $ExpectType void
+
+store.getAllCookies(cbCookies); // $ExpectType void
--- a/types/tough-cookie/v2/index.d.ts
+++ b/types/tough-cookie/v2/index.d.ts
@ -0,0 +1,242 @@
+// Type definitions for tough-cookie 2.3
+// Project: https://github.com/salesforce/tough-cookie
+// Definitions by: Leonard Thieu <https://github.com/leonard-thieu>
+//                 LiJinyao <https://github.com/LiJinyao>
+//                 Michael Wei <https://github.com/no2chem>
+// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
+// TypeScript Version: 2.2
+
+/**
+ * Parse a cookie date string into a Date.
+ * Parses according to RFC6265 Section 5.1.1, not Date.parse().
+ */
+export function parseDate(string: string): Date;
+
+/**
+ * Format a Date into a RFC1123 string (the RFC6265-recommended format).
+ */
+export function formatDate(date: Date): string;
+
+/**
+ * Transforms a domain-name into a canonical domain-name.
+ * The canonical domain-name is a trimmed, lowercased, stripped-of-leading-dot
+ * and optionally punycode-encoded domain-name (Section 5.1.2 of RFC6265).
+ * For the most part, this function is idempotent (can be run again on its output without ill effects).
+ */
+export function canonicalDomain(str: string): string;
+
+/**
+ * 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 RFC6265 Section 5.1.3, but it helps to think of it as a "suffix match".
+ *
+ * The canonicalize parameter will run the other two parameters through canonicalDomain or not.
+ */
+export function domainMatch(str: string, domStr: string, canonicalize?: boolean): boolean;
+
+/**
+ * Given a current request/response path, gives the Path apropriate 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.
+ *
+ * The path parameter MUST be only the pathname part of a URI (i.e. excludes the hostname, query, fragment, etc.).
+ * This is the .pathname property of node's uri.parse() output.
+ */
+export function defaultPath(path: string): string;
+
+/**
+ * Answers "does the request-path path-match a given cookie-path?" as per RFC6265 Section 5.1.4.
+ * Returns a boolean.
+ *
+ * This is essentially a prefix-match where cookiePath is a prefix of reqPath.
+ */
+export function pathMatch(reqPath: string, cookiePath: string): boolean;
+
+/**
+ * alias for Cookie.fromJSON(string)
+ */
+export function fromJSON(string: string): Cookie;
+
+export function getPublicSuffix(hostname: string): string | null;
+
+export function cookieCompare(a: Cookie, b: Cookie): number;
+
+export function permuteDomain(domain: string): string[];
+
+export function permutePath(path: string): string[];
+
+// region Cookie
+
+export class Cookie {
+    static parse(cookieString: string, options?: Cookie.ParseOptions): Cookie | undefined;
+
+    static fromJSON(strOrObj: string | object): Cookie | null;
+
+    constructor(properties?: Cookie.Properties);
+
+    key: string;
+    value: string;
+    expires: Date | 'Infinity';
+    maxAge: number | 'Infinity' | '-Infinity';
+    domain: string | null;
+    path: string | null;
+    secure: boolean;
+    httpOnly: boolean;
+    extensions: string[] | null;
+    creation: Date | null;
+    creationIndex: number;
+
+    hostOnly: boolean | null;
+    pathIsDefault: boolean | null;
+    lastAccessed: Date | null;
+
+    toString(): string;
+
+    cookieString(): string;
+
+    setExpires(String: string): void;
+
+    setMaxAge(number: number): void;
+
+    expiryTime(now?: number): number | typeof Infinity;
+
+    expiryDate(now?: number): Date;
+
+    TTL(now?: Date): number | typeof Infinity;
+
+    canonicalizedDomain(): string;
+
+    cdomain(): string;
+
+    toJSON(): { [key: string]: any; };
+
+    clone(): Cookie;
+
+    validate(): boolean | string;
+}
+
+export namespace Cookie {
+    interface ParseOptions {
+        loose?: boolean;
+    }
+
+    interface Properties {
+        key?: string;
+        value?: string;
+        expires?: Date;
+        maxAge?: number | 'Infinity' | '-Infinity';
+        domain?: string;
+        path?: string;
+        secure?: boolean;
+        httpOnly?: boolean;
+        extensions?: string[];
+        creation?: Date;
+        creationIndex?: number;
+
+        hostOnly?: boolean;
+        pathIsDefault?: boolean;
+        lastAccessed?: Date;
+    }
+
+    interface Serialized {
+        [key: string]: any;
+    }
+}
+
+// endregion
+
+// region CookieJar
+
+export class CookieJar {
+    static deserialize(serialized: CookieJar.Serialized | string, store: Store, cb: (err: Error | null, object: CookieJar) => void): void;
+    static deserialize(serialized: CookieJar.Serialized | string, cb: (err: Error | null, object: CookieJar) => void): void;
+
+    static deserializeSync(serialized: CookieJar.Serialized | string, store?: Store): CookieJar;
+
+    static fromJSON(string: string): CookieJar;
+
+    constructor(store?: Store, options?: CookieJar.Options);
+
+    setCookie(cookieOrString: Cookie | string, currentUrl: string, options: CookieJar.SetCookieOptions, cb: (err: Error | null, cookie: Cookie) => void): void;
+    setCookie(cookieOrString: Cookie | string, currentUrl: string, cb: (err: Error, cookie: Cookie) => void): void;
+
+    setCookieSync(cookieOrString: Cookie | string, currentUrl: string, options?: CookieJar.SetCookieOptions): void;
+
+    getCookies(currentUrl: string, options: CookieJar.GetCookiesOptions, cb: (err: Error | null, cookies: Cookie[]) => void): void;
+    getCookies(currentUrl: string, cb: (err: Error | null, cookies: Cookie[]) => void): void;
+
+    getCookiesSync(currentUrl: string, options?: CookieJar.GetCookiesOptions): Cookie[];
+
+    getCookieString(currentUrl: string, options: CookieJar.GetCookiesOptions, cb: (err: Error | null, cookies: string) => void): void;
+    getCookieString(currentUrl: string, cb: (err: Error | null, cookies: string) => void): void;
+
+    getCookieStringSync(currentUrl: string, options?: CookieJar.GetCookiesOptions): string;
+
+    getSetCookieStrings(currentUrl: string, options: CookieJar.GetCookiesOptions, cb: (err: Error | null, cookies: string) => void): void;
+    getSetCookieStrings(currentUrl: string, cb: (err: Error | null, cookies: string) => void): void;
+
+    getSetCookieStringsSync(currentUrl: string, options?: CookieJar.GetCookiesOptions): string;
+
+    serialize(cb: (err: Error | null, serializedObject: CookieJar.Serialized) => void): void;
+
+    serializeSync(): CookieJar.Serialized;
+
+    toJSON(): CookieJar.Serialized;
+
+    clone(store: Store, cb: (err: Error | null, newJar: CookieJar) => void): void;
+    clone(cb: (err: Error | null, newJar: CookieJar) => void): void;
+
+    cloneSync(store: Store): CookieJar;
+}
+
+export namespace CookieJar {
+    interface Options {
+        rejectPublicSuffixes?: boolean;
+        looseMode?: boolean;
+    }
+
+    interface SetCookieOptions {
+        http?: boolean;
+        secure?: boolean;
+        now?: Date;
+        ignoreError?: boolean;
+    }
+
+    interface GetCookiesOptions {
+        http?: boolean;
+        secure?: boolean;
+        now?: Date;
+        expire?: boolean;
+        allPaths?: boolean;
+    }
+
+    interface Serialized {
+        version: string;
+        storeType: string;
+        rejectPublicSuffixes: boolean;
+        cookies: Cookie.Serialized[];
+    }
+}
+
+// endregion
+
+// region Store
+
+export abstract class Store {
+    findCookie(domain: string, path: string, key: string, cb: (err: Error | null, cookie: Cookie | null) => void): void;
+
+    findCookies(domain: string, path: string, cb: (err: Error | null, cookie: Cookie[]) => void): void;
+
+    putCookie(cookie: Cookie, cb: (err: Error | null) => void): void;
+
+    updateCookie(oldCookie: Cookie, newCookie: Cookie, cb: (err: Error | null) => void): void;
+
+    removeCookie(domain: string, path: string, key: string, cb: (err: Error | null) => void): void;
+
+    removeCookies(domain: string, path: string, cb: (err: Error | null) => void): void;
+
+    getAllCookies(cb: (err: Error | null, cookie: Cookie[]) => void): void;
+}
+
+export class MemoryCookieStore extends Store { }
+
+// endregion
--- a/types/tough-cookie/v2/tough-cookie-tests.ts
+++ b/types/tough-cookie/v2/tough-cookie-tests.ts
@ -0,0 +1,26 @@
+import { Cookie, CookieJar, MemoryCookieStore } from 'tough-cookie';
+
+let header = '';
+const cb = () => { };
+
+const cookie = Cookie.parse(header)!;
+cookie.value = 'somethingdifferent';
+header = cookie.toString();
+
+const cookiejar = new CookieJar();
+cookiejar.setCookie(cookie, 'http://currentdomain.example.com/path', cb);
+// ...
+cookiejar.getCookies('http://example.com/otherpath', (err, cookies) => {
+    // res.headers['cookie'] = cookies.join('; ');
+});
+
+// All option are optional.
+cookiejar.getCookies('http://example.com/otherpath', {}, () => {});
+
+cookiejar.getCookies('http://example.com/otherpath', {
+    now: new Date(),
+    allPaths: true,
+}, () => {});
+
+CookieJar.deserializeSync("test cookie with store", new MemoryCookieStore());
+CookieJar.deserializeSync("test cookie");
--- a/types/tough-cookie/v2/tsconfig.json
+++ b/types/tough-cookie/v2/tsconfig.json
@ -0,0 +1,26 @@
+{
+    "compilerOptions": {
+        "module": "commonjs",
+        "lib": [
+            "es6"
+        ],
+        "noImplicitAny": true,
+        "noImplicitThis": true,
+        "strictNullChecks": true,
+        "strictFunctionTypes": true,
+        "baseUrl": "../../",
+        "typeRoots": [
+            "../../"
+        ],
+        "types": [],
+        "paths": {
+            "tough-cookie": ["tough-cookie/v2"]
+        },
+        "noEmit": true,
+        "forceConsistentCasingInFileNames": true
+    },
+    "files": [
+        "index.d.ts",
+        "tough-cookie-tests.ts"
+    ]
+}
--- a/types/tough-cookie/v2/tslint.json
+++ b/types/tough-cookie/v2/tslint.json
@ -0,0 +1,6 @@
+{
+    "extends": "dtslint/dt.json",
+    "rules": {
+        "no-empty-interface": false
+    }
+}