{"id":10669,"library":"cookie","title":"HTTP Cookie Parser and Serializer","description":"The `cookie` package provides fundamental utilities for parsing and serializing HTTP `Cookie` and `Set-Cookie` headers, commonly used in Node.js HTTP servers. It is currently at stable version 1.1.1, with relatively frequent patch and minor releases addressing fixes and new HTTP cookie attributes like `partitioned` and `priority`. Key differentiators include its focus on adherence to RFC6265, minimal API surface, and robust handling of common cookie patterns. It is maintained by the `jshttp` organization, known for foundational Express.js ecosystem middleware, ensuring reliability and specification compliance.","status":"active","version":"1.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/jshttp/cookie","tags":["javascript","cookie","cookies","typescript"],"install":[{"cmd":"npm install cookie","lang":"bash","label":"npm"},{"cmd":"yarn add cookie","lang":"bash","label":"yarn"},{"cmd":"pnpm add cookie","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM named imports are required since v1.0.0. CommonJS users should also use named imports for `parseCookie` directly or import the entire module as a namespace.","wrong":"const { parseCookie } = require('cookie');","symbol":"parseCookie","correct":"import { parseCookie } from 'cookie';"},{"note":"The `serialize` method was renamed to `stringifySetCookie` in v1.1.0, though `serialize` remains for backward compatibility. Always use the new named export for clarity.","wrong":"import cookie from 'cookie';\nconst header = cookie.serialize(...); // Deprecated name","symbol":"stringifySetCookie","correct":"import { stringifySetCookie } from 'cookie';"},{"note":"Introduced in v1.1.0 for parsing `Set-Cookie` headers into objects, distinct from `parseCookie` for `Cookie` headers.","symbol":"parseSetCookie","correct":"import { parseSetCookie } from 'cookie';"},{"note":"Since v1.0.0, the package uses an `__esModule` marker, meaning default imports are no longer valid. You must use a namespace import (`import * as cookie`) or named imports for specific functions.","wrong":"import cookie from 'cookie'; // Default import no longer works","symbol":"* as cookie","correct":"import * as cookie from 'cookie';"}],"quickstart":{"code":"import { parseCookie, stringifySetCookie, parseSetCookie } from 'cookie';\n\n// Example 1: Parsing a 'Cookie' header from an incoming request\nconst cookieHeader = 'foo=bar; equation=E%3Dmc%5E2; Path=/; Secure';\nconst parsedCookies = parseCookie(cookieHeader);\nconsole.log('Parsed Cookies:', parsedCookies);\n// Expected: { foo: 'bar', equation: 'E=mc^2' }\n\n// Example 2: Stringifying a 'Set-Cookie' header for an outgoing response\nconst setCookieObject = {\n  name: 'sessionid',\n  value: 'abc123def456',\n  maxAge: 3600, // 1 hour\n  httpOnly: true,\n  secure: true,\n  path: '/',\n  sameSite: 'Lax'\n};\nconst setCookieString = stringifySetCookie(setCookieObject);\nconsole.log('Set-Cookie String:', setCookieString);\n// Expected: sessionid=abc123def456; Max-Age=3600; Path=/; HttpOnly; Secure; SameSite=Lax\n\n// Example 3: Parsing a 'Set-Cookie' header (e.g., from a client-side response)\nconst rawSetCookie = 'mytoken=somevalue; Max-Age=7200; Path=/api; Expires=Wed, 21 Oct 2026 07:28:00 GMT; HttpOnly';\nconst parsedSetCookie = parseSetCookie(rawSetCookie);\nconsole.log('Parsed Set-Cookie Object:', parsedSetCookie);\n// Expected: { name: 'mytoken', value: 'somevalue', maxAge: 7200, path: '/api', expires: <Date object>, httpOnly: true }","lang":"typescript","description":"Demonstrates parsing HTTP `Cookie` headers and both parsing and stringifying `Set-Cookie` headers with common options."},"warnings":[{"fix":"Update your import statements to use `import { parse, serialize }` or `import * as cookie from 'cookie';`. Ensure Node.js v18 or newer is used. Review options like `strict` and `priority` for lowercase values.","message":"Version 1.0.0 introduced significant breaking changes, including minimum Node.js v18, mandatory named or namespace ESM imports, and a null prototype object for `parse` return values. The `strict` and `priority` options now require lowercase strings.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Migrate to the new method names: `parse` -> `parseCookie` and `serialize` -> `stringifySetCookie`. Use `stringifyCookie` for generic cookie object to header string conversion (e.g., `a=b;c=d`) and `parseSetCookie` for parsing full `Set-Cookie` header strings into an object.","message":"The `parse` and `serialize` methods were renamed to `parseCookie` and `stringifySetCookie` respectively in v1.1.0 to improve clarity and introduce `parseSetCookie` and `stringifyCookie`. While old names are aliased for backward compatibility, relying on them is discouraged.","severity":"breaking","affected_versions":">=1.1.0"},{"fix":"If both `maxAge` and `expires` are provided, calculate `expires` based on `maxAge` to maintain consistency across clients, e.g., `expires: new Date(Date.now() + maxAge * 1000)`.","message":"When using `maxAge` and `expires` options together in `stringifySetCookie`, RFC6265 states `maxAge` takes precedence. However, some clients might not obey this. It's best practice to ensure both point to the same date and time if used.","severity":"gotcha","affected_versions":">=0.5.0"},{"fix":"Ensure that any `maxAge` values passed to `stringifySetCookie` are whole numbers. If you have fractional values, round them or convert them to integers before passing.","message":"The `maxAge` option in `stringifySetCookie` now strictly requires an integer value, using `Number.isInteger` for validation. Non-integer values will cause issues.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Be aware that custom or malformed attributes in a `Set-Cookie` header will simply be dropped from the parsed object. Do not rely on `parseSetCookie` to preserve or interpret non-standard attributes.","message":"The `cookie.parseSetCookie` method strictly follows the specification and will ignore invalid or unrecognized attributes in a `Set-Cookie` string, rather than attempting to normalize or guess their intent.","severity":"gotcha","affected_versions":">=1.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change your import statement to `import * as cookie from 'cookie';` or `import { parseCookie, stringifySetCookie } from 'cookie';`.","cause":"Attempting to use `import cookie from 'cookie'` and then calling `cookie.parse()` or `cookie.serialize()` after v1.0.0, which removed the default export.","error":"TypeError: cookie is not a function"},{"fix":"Use ESM `import` statements: `import { parseCookie, stringifySetCookie } from 'cookie';`.","cause":"Using CommonJS `require()` syntax in an ESM module context (e.g., in a Node.js project with `\"type\": \"module\"` in `package.json` or in a browser environment via bundler without proper CJS translation).","error":"ReferenceError: require is not defined"},{"fix":"Ensure the `maxAge` value is a whole number (e.g., `Math.floor(value)` or `parseInt(value, 10)`).","cause":"Providing a non-integer value for the `maxAge` option when calling `stringifySetCookie` (or the deprecated `serialize`).","error":"TypeError: options.maxAge must be an integer"},{"fix":"Ensure cookie names and values adhere to valid character sets (e.g., for values, `encodeURIComponent` by default handles most cases). Looser validation was added in v1.0.2, but extreme cases may still fail.","cause":"Attempting to parse or serialize cookie strings with characters that violate RFC6265 specifications, though the package is generally lenient.","error":"Error: Invalid character in cookie name/value"}],"ecosystem":"npm"}