# Cookies API proposal

**URL:** <https://es.discourse.group/t/cookies-api-proposal/1848>\
**Category:** 💡 Ideas\
**Tags:** proposal\
**Created:** [November 15, 2023, 4:53pm UTC](https://es.discourse.group/t/cookies-api-proposal/1848 "2023-11-15T16:53:56Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![kettanaito](https://yyz2.discourse-cdn.com/free1/user_avatar/es.discourse.group/kettanaito/32/1623_2.png) [@kettanaito](https://es.discourse.group/u/kettanaito)\
**Post date:** [November 15, 2023, 4:53pm UTC](https://es.discourse.group/t/cookies-api-proposal/1848/1 "2023-11-15T16:53:56Z")

</div>

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](https://www.npmjs.com/package/cookie), [two](https://www.npmjs.com/package/set-cookie-parser), [three](https://www.npmjs.com/package/cookie-parser)) 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

```ts
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:

```js
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.

```js
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!

---

<div class="post-metadata">

**Author:** ![aclaymore](https://yyz2.discourse-cdn.com/free1/user_avatar/es.discourse.group/aclaymore/32/501_2.png) [@aclaymore](https://es.discourse.group/u/aclaymore)\
**Post date:** [November 15, 2023, 7:50pm UTC](https://es.discourse.group/t/cookies-api-proposal/1848/2 "2023-11-15T19:50:36Z")

</div>

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

Similar to how `setTimeout` and `fetch` is not part of [ECMAScript® 2024 Language&nbsp;Specification](https://tc39.es/ecma262/multipage/)

---

<div class="post-metadata">

**Author:** ![kettanaito](https://yyz2.discourse-cdn.com/free1/user_avatar/es.discourse.group/kettanaito/32/1623_2.png) [@kettanaito](https://es.discourse.group/u/kettanaito)\
**Post date:** [November 16, 2023, 9:05am UTC](https://es.discourse.group/t/cookies-api-proposal/1848/3 "2023-11-16T09:05:52Z")

</div>

Thanks! I moved this proposal to the [WHATWG Fetch repository](https://github.com/whatwg/html/issues/9935).