jshttp/cookie for TypeScript HTTP Header Parsing

Cookie Header Conversion for Node.js Servers

jshttp/cookie addresses a narrow server-side problem: converting HTTP cookie headers into ordinary JavaScript objects and converting those objects back into header strings. Its intended users are developers working with HTTP servers in Node.js who need direct control over the `Cookie` and `Set-Cookie` formats. It is not presented as a browser cookie-management API, a cookie jar, or a complete session system.

The package is named `cookie`, is written in TypeScript, and is distributed as an ES module. Version 2.0.1 exposes `dist/index.js` through the package exports and declares Node.js `>=22` as its supported runtime. That requirement matters for service adoption because an older application runtime cannot use this release without a separate compatibility arrangement that the repository does not document.

The project keeps its boundary clear. It parses names and values, recognizes documented `Set-Cookie` attributes, and serializes supported fields. It does not manage incoming requests, store cookies, schedule expiration, enforce domain rules, attach cookies to responses, or decide whether an application should accept a particular cookie. Those jobs remain with the HTTP framework and application code.

Four APIs for Request and Response Cookies

The API has four main functions. `cookie.parseCookie(str, options)` reads a request `Cookie` header and returns an object containing name-value pairs. The optional `decode` function processes cookie values and defaults to `decodeURIComponent`. This is the direction used when a server receives cookies from a client.

The inverse path is `cookie.stringifyCookie(cookieObj, options)`. It turns an object into a `Cookie` header string, while an optional `encode` function defaults to `encodeURIComponent`. The result remains a string suitable for the request-cookie representation documented by the project.

Response cookies use a different object model. `cookie.parseSetCookie(str, options)` reads one `Set-Cookie` header string and separates the cookie name and value from recognized options such as `maxAge`, `expires`, `domain`, `path`, `httpOnly`, `secure`, `partitioned`, `priority`, and `sameSite`. `cookie.stringifySetCookie(setCookieObj, options)` performs the corresponding serialization. The value decoder defaults to `decodeURIComponent`, while the encoder defaults to `encodeURIComponent`.

This separation is important. A request `Cookie` object is a map of names to values, while a `Set-Cookie` object is a structured object containing one cookie and its attributes. Reusing the request shape for response construction would lose attributes such as expiration and security flags.

Installing cookie 2.0.1 in an ESM Project

The README gives npm as the installation route. Add the package to the project with the following command. The `$` prefix shown in the README represents a shell prompt and is not part of the package name.

$ npm install cookie

The package metadata declares `"type": "module"`, so the first application import uses ESM syntax. Import the complete module namespace under the package name:

import * as cookie from "cookie";

A first real use is parsing an incoming request header. The README example passes the header string to `cookie.parseCookie` and returns two decoded values. The encoded `E%3Dmc%5E2` sequence becomes `E=mc^2` under the default decoder.

const cookieObject = cookie.parseCookie("foo=bar; equation=E%3Dmc%5E2");
// { foo: 'bar', equation: 'E=mc^2' }

For response-side work, build a `Set-Cookie` object and pass it to `cookie.stringifySetCookie`. This example produces a basic `foo=bar` header string, without additional attributes.

const setCookieHeader = cookie.stringifySetCookie({
  name: "foo",
  value: "bar",
});
// foo=bar

The repository declares Node.js `>=22`, so installation should be followed by a check that the target server runtime satisfies that engine requirement.

Attribute Mapping and Invalid Set-Cookie Values

The `Set-Cookie` object offers typed fields for common server cookie policy. `maxAge` is a number of seconds, while `expires` expects a `Date`. The README notes that the storage model specification gives `maxAge` precedence when both fields are present, but it also warns that clients may not obey this consistently. It therefore recommends that both values refer to the same date and time when both are emitted.

Without expiration, clients treat the cookie as non-persistent and delete it when the current session ends. `domain` specifies the cookie's `Domain` attribute, while an omitted `path` receives the specification's default path. `httpOnly` prevents client-side JavaScript from seeing the cookie through `document.cookie`, and `secure` causes a browser to return it only over HTTPS.

The library also represents emerging or specification-linked attributes. `partitioned` requires the current domain and top-level domain to match before the client sends the cookie, although the README says the attribute may still change and clients may ignore it until they understand it. `priority` accepts `'low'`, `'medium'`, and `'high'`. `sameSite` accepts `true`, `'lax'`, `'none'`, or `'strict'`, which map the object to the corresponding `SameSite` attribute values.

Invalid attributes are ignored rather than repaired. In the documented example, `max-age=1.5` and `expires=invalid` do not appear in the result, while the recognized name, value, and `domain` remain. The project deliberately does not normalize or modify attributes in the way a browser might. Applications that require browser-equivalent normalization need another layer.

Encoding Boundaries for Cookie Values

Cookie values are limited to a defined character set and must remain simple strings. jshttp/cookie therefore exposes custom encoding hooks at both parsing and serialization boundaries. Parsing accepts `decode`, and serialization accepts `encode`. Their defaults are `decodeURIComponent` and `encodeURIComponent`, respectively.

These callbacks are useful when an application already has a documented encoding convention, but the repository documentation does not establish them as a validation layer. A decoder transforms a cookie value into application data. It does not, by itself, establish whether that data is trusted, correctly signed, or acceptable for a particular route. The package description and API are centered on parsing and serialization, so integrity and authorization must be handled elsewhere.

For a request header, `parseCookie` is the relevant entry point. For `Cookie` serialization, use `stringifyCookie`; for `Set-Cookie` serialization, use `stringifySetCookie`. Supplying an explicit encoder or decoder changes only the value transformation. It does not add new header fields or turn the package into a browser compatibility layer.

Where cookie Stops Short of Session Security

The clearest limitation is that syntax conversion is not session security. The documented object fields can represent `httpOnly`, `secure`, and `sameSite`, but the package does not claim to generate secrets, sign cookie contents, encrypt values, rotate session identifiers, or prevent replay. A signed-cookie library or an application-specific session service is a different approach: it adds integrity metadata and key handling around the cookie, rather than merely converting header syntax. That added model may be unnecessary for a service that only needs to read non-sensitive preference values, but it matters when cookie contents influence authentication.

The library also does not attempt browser-style normalization. Invalid attributes are silently ignored, and recognized attributes are returned without modification. An application that must canonicalize every client header before relying on it should not assume this package provides that behavior. The README gives no rollback guidance, migration notes for custom encoders, or compatibility policy between the `1.1.1` and `2.x` API lines.

A framework-level cookie or session middleware is another alternative when the application already uses one. Its approach is to integrate parsing, response attachment, and possibly signing with request handling. jshttp/cookie instead stays at the header-conversion boundary and leaves those decisions to the caller. The smaller scope can be useful in a custom HTTP stack, while it also means more integration code.

Maintenance, Runtime, and MIT Upgrade Costs

The repository is not archived, and the last push was on 2026-07-08. Version 2.0.1 was released on 2026-06-30, following version 2.0.0 on 2026-06-24 and version 1.1.1 on 2025-11-26. These dates indicate recent repository activity, but they do not remove the need to review API and runtime changes during an upgrade.

The declared Node.js engine is `>=22`, which is the clearest adoption constraint documented by the package metadata. Upgrade cost also depends on application code that imports the package. The current README presents four named functions and a `Set-Cookie` object with several typed properties, but it does not provide a migration guide from earlier major versions. Consumers should therefore inspect their own call sites before changing versions rather than relying on undocumented compatibility.

The package is marked `sideEffects: false`, publishes the `dist/` directory, and declares a size limit of `1.4 KB` for `dist/index.js`. Its license is MIT. That license permits use under its terms, but the repository information does not replace reviewing the actual `LICENSE` file for obligations that apply to a particular distribution. Development tools include TypeScript, Vitest, and `ts-scripts`; the package scripts expose build, test, formatting, benchmark, specification, and size commands.

Editorial conclusion

Adopt jshttp/cookie when a Node.js server needs direct conversion between cookie headers and objects without adopting a larger framework layer. Do not choose it as a substitute for signing, encryption, validation, or browser-compatible attribute normalization. Before adoption, verify that Node.js 22 or later is available and decide whether the library's default decoding behavior matches the accepted cookie values.

Frequently asked questions

Official sources

1. Issues
2. jshttp/cookie on GitHub
3. License: MIT
4. README
5. Releases