{"id":16213,"library":"set-cookie-parser","title":"Set-Cookie Header Parser","description":"set-cookie-parser is a JavaScript/TypeScript library designed to parse `Set-Cookie` HTTP response headers into structured JavaScript objects. It currently stands at stable version 3.1.0 and is actively maintained, with a healthy release cadence and recent updates. The library is highly versatile, accepting various inputs including single header strings, arrays of header strings, Node.js `http.ServerResponse` objects, and `fetch()` `Response` objects. A key differentiator is its ability to return either an array of cookie objects or a map where cookie names are keys, depending on configuration. Each parsed cookie object provides a comprehensive set of attributes, including `name`, `value`, `path`, `domain`, `expires` (as `Date` objects), `maxAge`, `secure`, `httpOnly`, `sameSite`, and `partitioned`. It ships with built-in TypeScript types, ensuring robust type checking and improved developer experience in modern TypeScript projects.","status":"active","version":"3.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/nfriedly/set-cookie-parser","tags":["javascript","set-cookie","set","cookie","cookies","header","parse","parser","typescript"],"install":[{"cmd":"npm install set-cookie-parser","lang":"bash","label":"npm"},{"cmd":"yarn add set-cookie-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add set-cookie-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary parsing function is a named export. Default import is not provided.","wrong":"import setCookieParser from 'set-cookie-parser';","symbol":"parseSetCookie","correct":"import { parseSetCookie } from 'set-cookie-parser';"},{"note":"When using CommonJS, `parseSetCookie` is a named export requiring destructuring. Direct property access on the `require` result is also possible but less idiomatic for this pattern.","wrong":"const setCookieParser = require('set-cookie-parser');\nconst cookies = setCookieParser.parseSetCookie(res);","symbol":"parseSetCookie","correct":"const { parseSetCookie } = require('set-cookie-parser');"},{"note":"The type definition for a parsed cookie object, useful for TypeScript projects. It aligns with the structure described in the README (name, value, path, etc.).","symbol":"Cookie","correct":"import type { Cookie } from 'set-cookie-parser';"}],"quickstart":{"code":"import * as http from 'node:http';\nimport { parseSetCookie } from 'set-cookie-parser';\n\n// Example: Fetching from a URL and parsing Set-Cookie headers\nhttp.get('http://example.com', function(res) {\n  const cookies = parseSetCookie(res, {\n    decodeValues: true  // default: true\n  });\n\n  console.log('Parsed Cookies from example.com:');\n  if (cookies.length === 0) {\n    console.log('No Set-Cookie headers found.');\n  } else {\n    cookies.forEach(cookie => {\n      console.log(`- Name: ${cookie.name}, Value: ${cookie.value}`);\n      if (cookie.expires) console.log(`  Expires: ${cookie.expires.toISOString()}`);\n      if (cookie.maxAge) console.log(`  Max-Age: ${cookie.maxAge} seconds`);\n      if (cookie.domain) console.log(`  Domain: ${cookie.domain}`);\n      if (cookie.path) console.log(`  Path: ${cookie.path}`);\n      if (cookie.secure) console.log(`  Secure: true`);\n      if (cookie.httpOnly) console.log(`  HttpOnly: true`);\n      if (cookie.sameSite) console.log(`  SameSite: ${cookie.sameSite}`);\n      if (cookie.partitioned) console.log(`  Partitioned: true`);\n      console.log('---');\n    });\n  }\n}).on('error', (e) => {\n  console.error(`Error fetching: ${e.message}`);\n});\n","lang":"typescript","description":"This quickstart demonstrates how to parse `Set-Cookie` headers from an HTTP response object, iterating and logging the properties of each parsed cookie."},"warnings":[{"fix":"Ensure `maxAge` is converted: `res.cookie('name', 'value', { maxAge: cookie.maxAge * 1000 });`","message":"When setting cookies via `express.js`'s `res.cookie()` method using `maxAge` values obtained from `set-cookie-parser`, remember that `express` expects `maxAge` in milliseconds, while `set-cookie-parser` provides it in seconds. Always multiply `maxAge` by 1000 before passing it to `res.cookie()` to avoid unexpectedly short-lived cookies.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Implement client-side validation for `cookie.sameSite` values, e.g., `if (!['Strict', 'Lax', 'None'].includes(cookie.sameSite)) { /* handle invalid value */ }`","message":"The library copies `sameSite` values directly from the `Set-Cookie` header without performing any validation. If the `sameSite` attribute in the header contains an invalid or unexpected string, `set-cookie-parser` will return it verbatim in the parsed cookie object. Consumer applications should implement their own validation if strict adherence to `SameSite` values ('Strict', 'Lax', 'None') is required.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always ensure the input to `parseSetCookie` is an object from which `Set-Cookie` headers can be legitimately read, typically a response object.","message":"The `parseSetCookie` function accepts various inputs including raw strings, arrays of strings, `http.ServerResponse` objects, or `fetch.Response` objects. Passing an `http.IncomingMessage` (request object) instead of a `http.ServerResponse` (response object) might lead to unexpected or empty results, as `Set-Cookie` headers are found on responses, not requests.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"For ES Modules: `import { parseSetCookie } from 'set-cookie-parser';` For CommonJS: `const { parseSetCookie } = require('set-cookie-parser');`","cause":"Attempting to use `parseSetCookie` without correctly importing it as a named export, or using a default import which does not exist.","error":"ReferenceError: parseSetCookie is not defined"},{"fix":"Always check if the `cookies` array (or map) is populated before attempting to access its elements or properties, and ensure the input to `parseSetCookie` is valid and contains `Set-Cookie` headers.","cause":"This typically occurs when trying to access properties like `name` or `value` on a parsed cookie object, but `parseSetCookie` returned an empty array or `undefined` because no `Set-Cookie` headers were present or the input was invalid.","error":"TypeError: Cannot read properties of undefined (reading 'name') (or similar for cookie properties)"},{"fix":"If you are working with `fetch` responses, ensure you pass the actual `Response` object or its `response.headers` object directly to `parseSetCookie`.","cause":"This error usually occurs when you pass a plain object or an incorrect type to `parseSetCookie` when it expects a `fetch.Response` object. The `fetch.Response` object has a `headers` property which is a `Headers` object, and this object has a `get` method.","error":"TypeError: input.headers.get is not a function"}],"ecosystem":"npm"}