Hi. I'd like to propose a new Cookies API for JavaScript.
Intended usage
The Cookies API is designed to create and manipulate with a cookie string. The cookie string itself is rather inefficient to work with, which spawned a number of third-party packages (one, two, three) to fill in that demand (dozens of millions downloads in total).
Note that the proposed API is designed to manipulate with cookie strings. That kind of manipulation is synchronous by design (unlike a similar API of CookieStorage, which is also meant to solve different problems).
API
class Cookies {
public name: string
public value: string
public domain: string
public maxAge: number
public expires: Date
public secure: boolean
public httpOnly: boolean
// Parse a cookie string into Cookie instances.
static from(input: string): Cookie | Cookie[] {}
// Create a new cookie instance.
constructor(name: string, value: string, options?: CookieOptions) {}
public isExpired(): boolean
// Serialize this Cookie instance to a valid cookie string.
public toString(): string
}
Usage example:
let cookie = new Cookie('secret', 'value', { expires: new Date('2024-01-01') })
document.cookie = cookie.toString()
The Cookie API can also be used to work with cookie in server and server-like environments.
http.post('/login', ({ request }) => {
const sessionCookie = new Cookie('session', 'secret', options)
return new Response(null, {
status: 301,
headers: {
'Set-Cookie': sessionCookie.toString(),
Location: '/dashboard',
}
})
})
A lot of JavaScript frameworks can benefit from a standard Cookie API, especially as the platform develops into mixed client/server applications. Creating and handling request/response cookies becomes something most developers would have to do.
Pending questions
This proposal is primarily single instance-based. We may also consider something like CookieStore for parsing and serializing cookie strings with multiple values (which is often the case for document.cookie and request.headers.get('Cookie')).
We can also approach this from that multi-value perspective and design Cookie to accumulate multiple cookie values. Either approach is fine by me, discussions are appreciated!