Cookies API proposal

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!

1 Like

This sounds like something more for a venue like https://whatwg.org/ rather than the core language.

Similar to how setTimeout and fetch is not part of ECMAScript® 2024 Language Specification

1 Like

Thanks! I moved this proposal to the WHATWG Fetch repository.