standardize helpers on returning undefined

lib/__tests__/domainMatch.spec.ts

@@ -13,10 +13,10 @@ describe('domainMatch', () => {
     ['example.com', 'example.com.', false], // RFC6265 S4.1.2.3
 
     // nulls and undefineds
-    [null, 'example.com', null],
-    ['example.com', null, null],
-    [null, null, null],
-    [undefined, undefined, null],
+    [null, 'example.com', undefined],
+    ['example.com', null, undefined],
+    [null, null, undefined],
+    [undefined, undefined, undefined],
 
     // suffix matching:
     ['www.example.com', 'example.com', true], // substr AND suffix

lib/cookie/canonicalDomain.ts

@@ -3,9 +3,9 @@ import { IP_V6_REGEX_OBJECT } from './constants'
 import type { Nullable } from '../utils'
 
 // S5.1.2 Canonicalized Host Names
-export function canonicalDomain(str: Nullable<string>): string | null {
+export function canonicalDomain(str: Nullable<string>): string | undefined {
   if (str == null) {
-    return null
+    return undefined
   }
   let _str = str.trim().replace(/^\./, '') // S4.1.2.3 & S5.2.3: ignore leading .
 

lib/cookie/cookie.ts

@@ -280,6 +280,10 @@ function parse(str: string, options?: ParseCookieOptions): Cookie | undefined {
   return c
 }
 
+// TBD: `null` is valid JSON, but `undefined` is not. Options:
+// 1. Change this to return `undefined` - weird because it's not JSON
+// 2. Keep this as `null` - weird because it's a violation of our new convention
+// 3. Change *everything* to return `null` - a lot of work, maybe other edge cases that we can't change?
 function fromJSON(str: unknown): Cookie | null {
   if (!str || validators.isEmptyString(str)) {
     return null
@@ -532,6 +536,7 @@ export class Cookie {
     return obj
   }
 
+  // TBD: This is a wrapper for `fromJSON`, return type depends on decision there
   clone(): Cookie | null {
     return fromJSON(this.toJSON())
   }
@@ -697,15 +702,12 @@ export class Cookie {
   }
 
   // Mostly S5.1.2 and S5.2.3:
-  canonicalizedDomain(): string | null {
-    if (this.domain == null) {
-      return null
-    }
+  canonicalizedDomain(): string | undefined {
     return canonicalDomain(this.domain)
   }
 
-  cdomain(): string | null {
-    return this.canonicalizedDomain()
+  cdomain(): string | undefined {
+    return canonicalDomain(this.domain)
   }
 
   static parse = parse

lib/cookie/cookieJar.ts

@@ -85,13 +85,13 @@ function getCookieContext(url: unknown): URL | urlParse<string> {
 }
 
 type SameSiteLevel = keyof (typeof Cookie)['sameSiteLevel']
-function checkSameSiteContext(value: string): SameSiteLevel | null {
+function checkSameSiteContext(value: string): SameSiteLevel | undefined {
   validators.validate(validators.isNonEmptyString(value), value)
   const context = String(value).toLowerCase()
   if (context === 'none' || context === 'lax' || context === 'strict') {
     return context
   } else {
-    return null
+    return undefined
   }
 }
 
@@ -268,7 +268,7 @@ export class CookieJar {
       return promiseCallback.resolve(undefined)
     }
 
-    const host = canonicalDomain(context.hostname)
+    const host = canonicalDomain(context.hostname) ?? null
     const loose = options?.loose || this.enableLooseMode
 
     let sameSiteContext = null

lib/cookie/domainMatch.ts

@@ -13,9 +13,9 @@ export function domainMatch(
   str?: Nullable<string>,
   domStr?: Nullable<string>,
   canonicalize?: boolean,
-): boolean | null {
+): boolean | undefined {
   if (str == null || domStr == null) {
-    return null
+    return undefined
   }
 
   let _str: Nullable<string>
@@ -30,7 +30,7 @@ export function domainMatch(
   }
 
   if (_str == null || _domStr == null) {
-    return null
+    return undefined
   }
 
   /*

lib/getPublicSuffix.ts

@@ -49,7 +49,7 @@ const defaultGetPublicSuffixOptions: GetPublicSuffixOptions = {
 export function getPublicSuffix(
   domain: string,
   options: GetPublicSuffixOptions = {},
-): string | null {
+): string | undefined {
   options = { ...defaultGetPublicSuffixOptions, ...options }
   const domainParts = domain.split('.')
   const topLevelDomain = domainParts[domainParts.length - 1]
@@ -84,8 +84,9 @@ export function getPublicSuffix(
     )
   }
 
-  return getDomain(domain, {
+  const publicSuffix = getDomain(domain, {
     allowIcannDomains: true,
     allowPrivateDomains: true,
   })
+  if (publicSuffix) return publicSuffix
 }

lib/permuteDomain.ts

@@ -37,13 +37,13 @@ import { getPublicSuffix } from './getPublicSuffix'
 export function permuteDomain(
   domain: string,
   allowSpecialUseDomain?: boolean,
-): string[] | null {
+): string[] | undefined {
   const pubSuf = getPublicSuffix(domain, {
     allowSpecialUseDomain: allowSpecialUseDomain,
   })
 
   if (!pubSuf) {
-    return null
+    return undefined
   }
   if (pubSuf == domain) {
     return [domain]