Part of #581.
Motivation
RFC 6265bis-22 §5.2 defines exactly three valid SameSite values: Strict, Lax, and None. Currently Cookie.sameSite is typed as string | undefined, meaning any arbitrary string compiles. The codebase already has internal matching logic in checkSameSiteContext that maps these values.
Current usage
class Cookie {
sameSite: string | undefined // accepts any string
}
interface SetCookieOptions {
sameSiteContext?: 'strict' | 'lax' | 'none' | undefined // already uses literal union here
}
Note: SetCookieOptions.sameSiteContext already uses the correct literal union — only Cookie.sameSite is overly permissive.
Type design
This is a string literal union, not a branded/nominal type, since the valid values are a small, fixed set:
export type SameSiteLevel = 'strict' | 'lax' | 'none';
API strategy
Public API change (narrowing — justified)
| Property |
Current type |
New type |
Breaking? |
Cookie.sameSite |
string | undefined |
SameSiteLevel | undefined |
Technically yes — but any consumer passing a value other than the three valid strings was already incorrect per the RFC |
CreateCookieOptions.sameSite |
string | undefined |
SameSiteLevel | undefined |
Same rationale |
Rationale for public change
- The three values are exhaustively defined by the RFC
SetCookieOptions.sameSiteContext already uses this exact union — the types are inconsistent today
- This is a type correction rather than a behavioral change — no runtime behavior changes
- Consumers passing valid values are unaffected; consumers passing invalid values get a compile error pointing them to a real bug
Internal changes
checkSameSiteContext() can accept and return SameSiteLevel directly instead of parsing from string
- Cookie parsing logic maps raw header values to
SameSiteLevel | undefined at parse time
Part of #581.
Motivation
RFC 6265bis-22 §5.2 defines exactly three valid SameSite values:
Strict,Lax, andNone. CurrentlyCookie.sameSiteis typed asstring | undefined, meaning any arbitrary string compiles. The codebase already has internal matching logic incheckSameSiteContextthat maps these values.Current usage
Note:
SetCookieOptions.sameSiteContextalready uses the correct literal union — onlyCookie.sameSiteis overly permissive.Type design
This is a string literal union, not a branded/nominal type, since the valid values are a small, fixed set:
API strategy
Public API change (narrowing — justified)
Cookie.sameSitestring | undefinedSameSiteLevel | undefinedCreateCookieOptions.sameSitestring | undefinedSameSiteLevel | undefinedRationale for public change
SetCookieOptions.sameSiteContextalready uses this exact union — the types are inconsistent todayInternal changes
checkSameSiteContext()can accept and returnSameSiteLeveldirectly instead of parsing fromstringSameSiteLevel | undefinedat parse time