cookie-es 1.0.0 → 1.2.0

package/LICENSE

@@ -1,24 +1,28 @@
-(The MIT License)
+MIT License
 
+Cookie-es copyright (c) Pooya Parsa <pooya@pi0.io>
+
+Cookie parsing based on https://github.com/jshttp/cookie
 Copyright (c) 2012-2014 Roman Shtylman <shtylman@gmail.com>
 Copyright (c) 2015 Douglas Christopher Wilson <doug@somethingdoug.com>
 
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-'Software'), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
+Set-Cookie parsing based on https://github.com/nfriedly/set-cookie-parser
+Copyright (c) 2015 Nathan Friedly <nathan@nfriedly.com> (http://nfriedly.com/)
 
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,32 +1,82 @@
 
-# cookie-es
+# 🍪 cookie-es
 
-[![bundle size](https://flat.badgen.net/bundlephobia/minzip/cookie-es)](https://bundlephobia.com/package/cookie-es)
+<!-- automd:badges bundlejs -->
 
-ESM build of [cookie](https://www.npmjs.com/package/cookie) with bundled types.
+[![npm version](https://img.shields.io/npm/v/cookie-es)](https://npmjs.com/package/cookie-es)
+[![npm downloads](https://img.shields.io/npm/dm/cookie-es)](https://npmjs.com/package/cookie-es)
+[![bundle size](https://img.shields.io/bundlejs/size/cookie-es)](https://bundlejs.com/?q=cookie-es)
+
+<!-- /automd -->
+
+🍪 [`Cookie`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cookie) and [`Set-Cookie`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie) parser and serializer based on [cookie](https://github.com/jshttp/cookiee) and [set-cookie-parser](https://github.com/nfriedly/set-cookie-parser) with dual ESM/CJS exports and bundled types. 🎁
 
 ## Usage
 
 Install:
 
+<!-- automd:pm-install -->
+
 ```sh
+# ✨ Auto-detect
+npx nypm install cookie-es
+
 # npm
-npm i cookie-es
+npm install cookie-es
 
 # yarn
 yarn add cookie-es
+
+# pnpm
+pnpm install cookie-es
+
+# bun
+bun install cookie-es
 ```
 
+<!-- /automd-->
+
 Import:
 
+
+<!-- automd:jsimport cdn cjs src=./src/index.ts -->
+
+**ESM** (Node.js, Bun)
+
 ```js
-// ESM
-import { parse, serialize } from 'cookie-es'
+import {
+  parse,
+  serialize,
+  parseSetCookie,
+  splitSetCookieString,
+} from "cookie-es";
+```
+
+**CommonJS** (Legacy Node.js)
 
-// CommonJS
-const { parse, serialize } = require('cookie-es')
+```js
+const {
+  parse,
+  serialize,
+  parseSetCookie,
+  splitSetCookieString,
+} = require("cookie-es");
 ```
 
+**CDN** (Deno, Bun and Browsers)
+
+```js
+import {
+  parse,
+  serialize,
+  parseSetCookie,
+  splitSetCookieString,
+} from "https://esm.sh/cookie-es";
+```
+
+<!-- /automd -->
+
+
 ## License
 
 [MIT](./LICENSE)

package/dist/index.cjs

@@ -1,6 +1,5 @@
 'use strict';
 
-const fieldContentRegExp = /^[\u0009\u0020-\u007E\u0080-\u00FF]+$/;
 function parse(str, options) {
   if (typeof str !== "string") {
     throw new TypeError("argument str must be a string");
@@ -33,9 +32,21 @@ function parse(str, options) {
   }
   return obj;
 }
+function decode(str) {
+  return str.includes("%") ? decodeURIComponent(str) : str;
+}
+function tryDecode(str, decode2) {
+  try {
+    return decode2(str);
+  } catch {
+    return str;
+  }
+}
+
+const fieldContentRegExp = /^[\u0009\u0020-\u007E\u0080-\u00FF]+$/;
 function serialize(name, value, options) {
   const opt = options || {};
-  const enc = opt.encode || encode;
+  const enc = opt.encode || encodeURIComponent;
   if (typeof enc !== "function") {
     throw new TypeError("option encode is invalid");
   }
@@ -81,56 +92,172 @@ function serialize(name, value, options) {
   if (opt.priority) {
     const priority = typeof opt.priority === "string" ? opt.priority.toLowerCase() : opt.priority;
     switch (priority) {
-      case "low":
+      case "low": {
         str += "; Priority=Low";
         break;
-      case "medium":
+      }
+      case "medium": {
         str += "; Priority=Medium";
         break;
-      case "high":
+      }
+      case "high": {
         str += "; Priority=High";
         break;
-      default:
+      }
+      default: {
         throw new TypeError("option priority is invalid");
+      }
     }
   }
   if (opt.sameSite) {
     const sameSite = typeof opt.sameSite === "string" ? opt.sameSite.toLowerCase() : opt.sameSite;
     switch (sameSite) {
-      case true:
+      case true: {
         str += "; SameSite=Strict";
         break;
-      case "lax":
+      }
+      case "lax": {
         str += "; SameSite=Lax";
         break;
-      case "strict":
+      }
+      case "strict": {
         str += "; SameSite=Strict";
         break;
-      case "none":
+      }
+      case "none": {
         str += "; SameSite=None";
         break;
-      default:
+      }
+      default: {
         throw new TypeError("option sameSite is invalid");
+      }
     }
   }
+  if (opt.partitioned) {
+    str += "; Partitioned";
+  }
   return str;
 }
 function isDate(val) {
   return Object.prototype.toString.call(val) === "[object Date]" || val instanceof Date;
 }
-function tryDecode(str, decode2) {
+
+function parseSetCookie(setCookieValue, options) {
+  const parts = (setCookieValue || "").split(";").filter((str) => typeof str === "string" && !!str.trim());
+  const nameValuePairStr = parts.shift() || "";
+  const parsed = _parseNameValuePair(nameValuePairStr);
+  const name = parsed.name;
+  let value = parsed.value;
   try {
-    return decode2(str);
+    value = options?.decode === false ? value : (options?.decode || decodeURIComponent)(value);
   } catch {
-    return str;
   }
+  const cookie = {
+    name,
+    value
+  };
+  for (const part of parts) {
+    const sides = part.split("=");
+    const partKey = (sides.shift() || "").trimStart().toLowerCase();
+    const partValue = sides.join("=");
+    switch (partKey) {
+      case "expires": {
+        cookie.expires = new Date(partValue);
+        break;
+      }
+      case "max-age": {
+        cookie.maxAge = Number.parseInt(partValue, 10);
+        break;
+      }
+      case "secure": {
+        cookie.secure = true;
+        break;
+      }
+      case "httponly": {
+        cookie.httpOnly = true;
+        break;
+      }
+      case "samesite": {
+        cookie.sameSite = partValue;
+        break;
+      }
+      default: {
+        cookie[partKey] = partValue;
+      }
+    }
+  }
+  return cookie;
 }
-function decode(str) {
-  return str.includes("%") ? decodeURIComponent(str) : str;
+function _parseNameValuePair(nameValuePairStr) {
+  let name = "";
+  let value = "";
+  const nameValueArr = nameValuePairStr.split("=");
+  if (nameValueArr.length > 1) {
+    name = nameValueArr.shift();
+    value = nameValueArr.join("=");
+  } else {
+    value = nameValuePairStr;
+  }
+  return { name, value };
 }
-function encode(val) {
-  return encodeURIComponent(val);
+
+function splitSetCookieString(cookiesString) {
+  if (Array.isArray(cookiesString)) {
+    return cookiesString.flatMap((c) => splitSetCookieString(c));
+  }
+  if (typeof cookiesString !== "string") {
+    return [];
+  }
+  const cookiesStrings = [];
+  let pos = 0;
+  let start;
+  let ch;
+  let lastComma;
+  let nextStart;
+  let cookiesSeparatorFound;
+  const skipWhitespace = () => {
+    while (pos < cookiesString.length && /\s/.test(cookiesString.charAt(pos))) {
+      pos += 1;
+    }
+    return pos < cookiesString.length;
+  };
+  const notSpecialChar = () => {
+    ch = cookiesString.charAt(pos);
+    return ch !== "=" && ch !== ";" && ch !== ",";
+  };
+  while (pos < cookiesString.length) {
+    start = pos;
+    cookiesSeparatorFound = false;
+    while (skipWhitespace()) {
+      ch = cookiesString.charAt(pos);
+      if (ch === ",") {
+        lastComma = pos;
+        pos += 1;
+        skipWhitespace();
+        nextStart = pos;
+        while (pos < cookiesString.length && notSpecialChar()) {
+          pos += 1;
+        }
+        if (pos < cookiesString.length && cookiesString.charAt(pos) === "=") {
+          cookiesSeparatorFound = true;
+          pos = nextStart;
+          cookiesStrings.push(cookiesString.slice(start, lastComma));
+          start = pos;
+        } else {
+          pos = lastComma + 1;
+        }
+      } else {
+        pos += 1;
+      }
+    }
+    if (!cookiesSeparatorFound || pos >= cookiesString.length) {
+      cookiesStrings.push(cookiesString.slice(start, cookiesString.length));
+    }
+  }
+  return cookiesStrings;
 }
 
 exports.parse = parse;
+exports.parseSetCookie = parseSetCookie;
 exports.serialize = serialize;
+exports.splitSetCookieString = splitSetCookieString;

package/dist/index.d.cts

@@ -0,0 +1,222 @@
+/**
+ * Basic HTTP cookie parser and serializer for HTTP servers.
+ */
+/**
+ * Additional serialization options
+ */
+interface CookieSerializeOptions {
+    /**
+     * Specifies the value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.3|Domain Set-Cookie attribute}. By default, no
+     * domain is set, and most clients will consider the cookie to apply to only
+     * the current domain.
+     */
+    domain?: string | undefined;
+    /**
+     * Specifies a function that will be used to encode a cookie's value. Since
+     * value of a cookie has a limited character set (and must be a simple
+     * string), this function can be used to encode a value into a string suited
+     * for a cookie's value.
+     *
+     * The default function is the global `encodeURIComponent`, which will
+     * encode a JavaScript string into UTF-8 byte sequences and then URL-encode
+     * any that fall outside of the cookie range.
+     */
+    encode?(value: string): string;
+    /**
+     * Specifies the `Date` object to be the value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.1|`Expires` `Set-Cookie` attribute}. By default,
+     * no expiration is set, and most clients will consider this a "non-persistent cookie" and will delete
+     * it on a condition like exiting a web browser application.
+     *
+     * *Note* the {@link https://tools.ietf.org/html/rfc6265#section-5.3|cookie storage model specification}
+     * states that if both `expires` and `maxAge` are set, then `maxAge` takes precedence, but it is
+     * possible not all clients by obey this, so if both are set, they should
+     * point to the same date and time.
+     */
+    expires?: Date | undefined;
+    /**
+     * Specifies the boolean value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.6|`HttpOnly` `Set-Cookie` attribute}.
+     * When truthy, the `HttpOnly` attribute is set, otherwise it is not. By
+     * default, the `HttpOnly` attribute is not set.
+     *
+     * *Note* be careful when setting this to true, as compliant clients will
+     * not allow client-side JavaScript to see the cookie in `document.cookie`.
+     */
+    httpOnly?: boolean | undefined;
+    /**
+     * Specifies the number (in seconds) to be the value for the `Max-Age`
+     * `Set-Cookie` attribute. The given number will be converted to an integer
+     * by rounding down. By default, no maximum age is set.
+     *
+     * *Note* the {@link https://tools.ietf.org/html/rfc6265#section-5.3|cookie storage model specification}
+     * states that if both `expires` and `maxAge` are set, then `maxAge` takes precedence, but it is
+     * possible not all clients by obey this, so if both are set, they should
+     * point to the same date and time.
+     */
+    maxAge?: number | undefined;
+    /**
+     * Specifies the value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.4|`Path` `Set-Cookie` attribute}.
+     * By default, the path is considered the "default path".
+     */
+    path?: string | undefined;
+    /**
+     * Specifies the `string` to be the value for the [`Priority` `Set-Cookie` attribute][rfc-west-cookie-priority-00-4.1].
+     *
+     * - `'low'` will set the `Priority` attribute to `Low`.
+     * - `'medium'` will set the `Priority` attribute to `Medium`, the default priority when not set.
+     * - `'high'` will set the `Priority` attribute to `High`.
+     *
+     * More information about the different priority levels can be found in
+     * [the specification][rfc-west-cookie-priority-00-4.1].
+     *
+     * **note** This is an attribute that has not yet been fully standardized, and may change in the future.
+     * This also means many clients may ignore this attribute until they understand it.
+     */
+    priority?: "low" | "medium" | "high" | undefined;
+    /**
+     * Specifies the boolean or string to be the value for the {@link https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7|`SameSite` `Set-Cookie` attribute}.
+     *
+     * - `true` will set the `SameSite` attribute to `Strict` for strict same
+     * site enforcement.
+     * - `false` will not set the `SameSite` attribute.
+     * - `'lax'` will set the `SameSite` attribute to Lax for lax same site
+     * enforcement.
+     * - `'strict'` will set the `SameSite` attribute to Strict for strict same
+     * site enforcement.
+     *  - `'none'` will set the SameSite attribute to None for an explicit
+     *  cross-site cookie.
+     *
+     * More information about the different enforcement levels can be found in {@link https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7|the specification}.
+     *
+     * *note* This is an attribute that has not yet been fully standardized, and may change in the future. This also means many clients may ignore this attribute until they understand it.
+     */
+    sameSite?: true | false | "lax" | "strict" | "none" | undefined;
+    /**
+     * Specifies the boolean value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.5|`Secure` `Set-Cookie` attribute}. When truthy, the
+     * `Secure` attribute is set, otherwise it is not. By default, the `Secure` attribute is not set.
+     *
+     * *Note* be careful when setting this to `true`, as compliant clients will
+     * not send the cookie back to the server in the future if the browser does
+     * not have an HTTPS connection.
+     */
+    secure?: boolean | undefined;
+    /**
+     * Specifies the `boolean` value for the [`Partitioned` `Set-Cookie`](https://datatracker.ietf.org/doc/html/draft-cutler-httpbis-partitioned-cookies#section-2.1)
+     * attribute. When truthy, the `Partitioned` attribute is set, otherwise it is not. By default, the
+     * `Partitioned` attribute is not set.
+     *
+     * **note** This is an attribute that has not yet been fully standardized, and may change in the future.
+     * This also means many clients may ignore this attribute until they understand it.
+     *
+     * More information can be found in the [proposal](https://github.com/privacycg/CHIPS).
+     */
+    partitioned?: boolean;
+}
+/**
+ * Additional parsing options
+ */
+interface CookieParseOptions {
+    /**
+     * Specifies a function that will be used to decode a cookie's value. Since
+     * the value of a cookie has a limited character set (and must be a simple
+     * string), this function can be used to decode a previously-encoded cookie
+     * value into a JavaScript string or other object.
+     *
+     * The default function is the global `decodeURIComponent`, which will decode
+     * any URL-encoded sequences into their byte representations.
+     *
+     * *Note* if an error is thrown from this function, the original, non-decoded
+     * cookie value will be returned as the cookie's value.
+     */
+    decode?(value: string): string;
+    /**
+     * Custom function to filter parsing specific keys.
+     */
+    filter?(key: string): boolean;
+}
+
+/**
+ * Parse an HTTP Cookie header string and returning an object of all cookie
+ * name-value pairs.
+ *
+ * @param str the string representing a `Cookie` header value
+ * @param [options] object containing parsing options
+ */
+declare function parse(str: string, options?: CookieParseOptions): Record<string, string>;
+
+/**
+ * Serialize a cookie name-value pair into a `Set-Cookie` header string.
+ *
+ * @param name the name for the cookie
+ * @param value value to set the cookie to
+ * @param [options] object containing serialization options
+ * @throws {TypeError} when `maxAge` options is invalid
+ */
+declare function serialize(name: string, value: string, options?: CookieSerializeOptions): string;
+
+interface SetCookieParseOptions {
+    /**
+     * Custom decode function to use on cookie values.
+     *
+     * By default, `decodeURIComponent` is used.
+     *
+     * **Note:** If decoding fails, the original (undecoded) value will be used
+     */
+    decode?: false | ((value: string) => string);
+}
+interface SetCookie {
+    /**
+     * Cookie name
+     */
+    name: string;
+    /**
+     * Cookie value
+     */
+    value: string;
+    /**
+     * Cookie path
+     */
+    path?: string | undefined;
+    /**
+     * Absolute expiration date for the cookie
+     */
+    expires?: Date | undefined;
+    /**
+     * Relative max age of the cookie in seconds from when the client receives it (integer or undefined)
+     *
+     * Note: when using with express's res.cookie() method, multiply maxAge by 1000 to convert to milliseconds
+     */
+    maxAge?: number | undefined;
+    /**
+     * Domain for the cookie,
+     * May begin with "." to indicate the named domain or any subdomain of it
+     */
+    domain?: string | undefined;
+    /**
+     * Indicates that this cookie should only be sent over HTTPs
+     */
+    secure?: boolean | undefined;
+    /**
+     * Indicates that this cookie should not be accessible to client-side JavaScript
+     */
+    httpOnly?: boolean | undefined;
+    /**
+     * Indicates a cookie ought not to be sent along with cross-site requests
+     */
+    sameSite?: string | undefined;
+    [key: string]: unknown;
+}
+
+/**
+ * Parse a [Set-Cookie](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie) header string into an object.
+ */
+declare function parseSetCookie(setCookieValue: string, options?: SetCookieParseOptions): SetCookie;
+
+/**
+ * Set-Cookie header field-values are sometimes comma joined in one string. This splits them without choking on commas
+ * that are within a single set-cookie field-value, such as in the Expires portion.
+ *
+ * See https://tools.ietf.org/html/rfc2616#section-4.2
+ */
+declare function splitSetCookieString(cookiesString: string | string[]): string[];
+
+export { type CookieParseOptions, type CookieSerializeOptions, type SetCookie, type SetCookieParseOptions, parse, parseSetCookie, serialize, splitSetCookieString };

package/dist/index.d.mts

@@ -0,0 +1,222 @@
+/**
+ * Basic HTTP cookie parser and serializer for HTTP servers.
+ */
+/**
+ * Additional serialization options
+ */
+interface CookieSerializeOptions {
+    /**
+     * Specifies the value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.3|Domain Set-Cookie attribute}. By default, no
+     * domain is set, and most clients will consider the cookie to apply to only
+     * the current domain.
+     */
+    domain?: string | undefined;
+    /**
+     * Specifies a function that will be used to encode a cookie's value. Since
+     * value of a cookie has a limited character set (and must be a simple
+     * string), this function can be used to encode a value into a string suited
+     * for a cookie's value.
+     *
+     * The default function is the global `encodeURIComponent`, which will
+     * encode a JavaScript string into UTF-8 byte sequences and then URL-encode
+     * any that fall outside of the cookie range.
+     */
+    encode?(value: string): string;
+    /**
+     * Specifies the `Date` object to be the value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.1|`Expires` `Set-Cookie` attribute}. By default,
+     * no expiration is set, and most clients will consider this a "non-persistent cookie" and will delete
+     * it on a condition like exiting a web browser application.
+     *
+     * *Note* the {@link https://tools.ietf.org/html/rfc6265#section-5.3|cookie storage model specification}
+     * states that if both `expires` and `maxAge` are set, then `maxAge` takes precedence, but it is
+     * possible not all clients by obey this, so if both are set, they should
+     * point to the same date and time.
+     */
+    expires?: Date | undefined;
+    /**
+     * Specifies the boolean value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.6|`HttpOnly` `Set-Cookie` attribute}.
+     * When truthy, the `HttpOnly` attribute is set, otherwise it is not. By
+     * default, the `HttpOnly` attribute is not set.
+     *
+     * *Note* be careful when setting this to true, as compliant clients will
+     * not allow client-side JavaScript to see the cookie in `document.cookie`.
+     */
+    httpOnly?: boolean | undefined;
+    /**
+     * Specifies the number (in seconds) to be the value for the `Max-Age`
+     * `Set-Cookie` attribute. The given number will be converted to an integer
+     * by rounding down. By default, no maximum age is set.
+     *
+     * *Note* the {@link https://tools.ietf.org/html/rfc6265#section-5.3|cookie storage model specification}
+     * states that if both `expires` and `maxAge` are set, then `maxAge` takes precedence, but it is
+     * possible not all clients by obey this, so if both are set, they should
+     * point to the same date and time.
+     */
+    maxAge?: number | undefined;
+    /**
+     * Specifies the value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.4|`Path` `Set-Cookie` attribute}.
+     * By default, the path is considered the "default path".
+     */
+    path?: string | undefined;
+    /**
+     * Specifies the `string` to be the value for the [`Priority` `Set-Cookie` attribute][rfc-west-cookie-priority-00-4.1].
+     *
+     * - `'low'` will set the `Priority` attribute to `Low`.
+     * - `'medium'` will set the `Priority` attribute to `Medium`, the default priority when not set.
+     * - `'high'` will set the `Priority` attribute to `High`.
+     *
+     * More information about the different priority levels can be found in
+     * [the specification][rfc-west-cookie-priority-00-4.1].
+     *
+     * **note** This is an attribute that has not yet been fully standardized, and may change in the future.
+     * This also means many clients may ignore this attribute until they understand it.
+     */
+    priority?: "low" | "medium" | "high" | undefined;
+    /**
+     * Specifies the boolean or string to be the value for the {@link https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7|`SameSite` `Set-Cookie` attribute}.
+     *
+     * - `true` will set the `SameSite` attribute to `Strict` for strict same
+     * site enforcement.
+     * - `false` will not set the `SameSite` attribute.
+     * - `'lax'` will set the `SameSite` attribute to Lax for lax same site
+     * enforcement.
+     * - `'strict'` will set the `SameSite` attribute to Strict for strict same
+     * site enforcement.
+     *  - `'none'` will set the SameSite attribute to None for an explicit
+     *  cross-site cookie.
+     *
+     * More information about the different enforcement levels can be found in {@link https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7|the specification}.
+     *
+     * *note* This is an attribute that has not yet been fully standardized, and may change in the future. This also means many clients may ignore this attribute until they understand it.
+     */
+    sameSite?: true | false | "lax" | "strict" | "none" | undefined;
+    /**
+     * Specifies the boolean value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.5|`Secure` `Set-Cookie` attribute}. When truthy, the
+     * `Secure` attribute is set, otherwise it is not. By default, the `Secure` attribute is not set.
+     *
+     * *Note* be careful when setting this to `true`, as compliant clients will
+     * not send the cookie back to the server in the future if the browser does
+     * not have an HTTPS connection.
+     */
+    secure?: boolean | undefined;
+    /**
+     * Specifies the `boolean` value for the [`Partitioned` `Set-Cookie`](https://datatracker.ietf.org/doc/html/draft-cutler-httpbis-partitioned-cookies#section-2.1)
+     * attribute. When truthy, the `Partitioned` attribute is set, otherwise it is not. By default, the
+     * `Partitioned` attribute is not set.
+     *
+     * **note** This is an attribute that has not yet been fully standardized, and may change in the future.
+     * This also means many clients may ignore this attribute until they understand it.
+     *
+     * More information can be found in the [proposal](https://github.com/privacycg/CHIPS).
+     */
+    partitioned?: boolean;
+}
+/**
+ * Additional parsing options
+ */
+interface CookieParseOptions {
+    /**
+     * Specifies a function that will be used to decode a cookie's value. Since
+     * the value of a cookie has a limited character set (and must be a simple
+     * string), this function can be used to decode a previously-encoded cookie
+     * value into a JavaScript string or other object.
+     *
+     * The default function is the global `decodeURIComponent`, which will decode
+     * any URL-encoded sequences into their byte representations.
+     *
+     * *Note* if an error is thrown from this function, the original, non-decoded
+     * cookie value will be returned as the cookie's value.
+     */
+    decode?(value: string): string;
+    /**
+     * Custom function to filter parsing specific keys.
+     */
+    filter?(key: string): boolean;
+}
+
+/**
+ * Parse an HTTP Cookie header string and returning an object of all cookie
+ * name-value pairs.
+ *
+ * @param str the string representing a `Cookie` header value
+ * @param [options] object containing parsing options
+ */
+declare function parse(str: string, options?: CookieParseOptions): Record<string, string>;
+
+/**
+ * Serialize a cookie name-value pair into a `Set-Cookie` header string.
+ *
+ * @param name the name for the cookie
+ * @param value value to set the cookie to
+ * @param [options] object containing serialization options
+ * @throws {TypeError} when `maxAge` options is invalid
+ */
+declare function serialize(name: string, value: string, options?: CookieSerializeOptions): string;
+
+interface SetCookieParseOptions {
+    /**
+     * Custom decode function to use on cookie values.
+     *
+     * By default, `decodeURIComponent` is used.
+     *
+     * **Note:** If decoding fails, the original (undecoded) value will be used
+     */
+    decode?: false | ((value: string) => string);
+}
+interface SetCookie {
+    /**
+     * Cookie name
+     */
+    name: string;
+    /**
+     * Cookie value
+     */
+    value: string;
+    /**
+     * Cookie path
+     */
+    path?: string | undefined;
+    /**
+     * Absolute expiration date for the cookie
+     */
+    expires?: Date | undefined;
+    /**
+     * Relative max age of the cookie in seconds from when the client receives it (integer or undefined)
+     *
+     * Note: when using with express's res.cookie() method, multiply maxAge by 1000 to convert to milliseconds
+     */
+    maxAge?: number | undefined;
+    /**
+     * Domain for the cookie,
+     * May begin with "." to indicate the named domain or any subdomain of it
+     */
+    domain?: string | undefined;
+    /**
+     * Indicates that this cookie should only be sent over HTTPs
+     */
+    secure?: boolean | undefined;
+    /**
+     * Indicates that this cookie should not be accessible to client-side JavaScript
+     */
+    httpOnly?: boolean | undefined;
+    /**
+     * Indicates a cookie ought not to be sent along with cross-site requests
+     */
+    sameSite?: string | undefined;
+    [key: string]: unknown;
+}
+
+/**
+ * Parse a [Set-Cookie](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie) header string into an object.
+ */
+declare function parseSetCookie(setCookieValue: string, options?: SetCookieParseOptions): SetCookie;
+
+/**
+ * Set-Cookie header field-values are sometimes comma joined in one string. This splits them without choking on commas
+ * that are within a single set-cookie field-value, such as in the Expires portion.
+ *
+ * See https://tools.ietf.org/html/rfc2616#section-4.2
+ */
+declare function splitSetCookieString(cookiesString: string | string[]): string[];
+
+export { type CookieParseOptions, type CookieSerializeOptions, type SetCookie, type SetCookieParseOptions, parse, parseSetCookie, serialize, splitSetCookieString };

package/dist/index.d.ts

@@ -99,6 +99,17 @@ interface CookieSerializeOptions {
      * not have an HTTPS connection.
      */
     secure?: boolean | undefined;
+    /**
+     * Specifies the `boolean` value for the [`Partitioned` `Set-Cookie`](https://datatracker.ietf.org/doc/html/draft-cutler-httpbis-partitioned-cookies#section-2.1)
+     * attribute. When truthy, the `Partitioned` attribute is set, otherwise it is not. By default, the
+     * `Partitioned` attribute is not set.
+     *
+     * **note** This is an attribute that has not yet been fully standardized, and may change in the future.
+     * This also means many clients may ignore this attribute until they understand it.
+     *
+     * More information can be found in the [proposal](https://github.com/privacycg/CHIPS).
+     */
+    partitioned?: boolean;
 }
 /**
  * Additional parsing options
@@ -117,6 +128,10 @@ interface CookieParseOptions {
      * cookie value will be returned as the cookie's value.
      */
     decode?(value: string): string;
+    /**
+     * Custom function to filter parsing specific keys.
+     */
+    filter?(key: string): boolean;
 }
 
 /**
@@ -127,6 +142,7 @@ interface CookieParseOptions {
  * @param [options] object containing parsing options
  */
 declare function parse(str: string, options?: CookieParseOptions): Record<string, string>;
+
 /**
  * Serialize a cookie name-value pair into a `Set-Cookie` header string.
  *
@@ -137,4 +153,70 @@ declare function parse(str: string, options?: CookieParseOptions): Record<string
  */
 declare function serialize(name: string, value: string, options?: CookieSerializeOptions): string;
 
-export { CookieParseOptions, CookieSerializeOptions, parse, serialize };
+interface SetCookieParseOptions {
+    /**
+     * Custom decode function to use on cookie values.
+     *
+     * By default, `decodeURIComponent` is used.
+     *
+     * **Note:** If decoding fails, the original (undecoded) value will be used
+     */
+    decode?: false | ((value: string) => string);
+}
+interface SetCookie {
+    /**
+     * Cookie name
+     */
+    name: string;
+    /**
+     * Cookie value
+     */
+    value: string;
+    /**
+     * Cookie path
+     */
+    path?: string | undefined;
+    /**
+     * Absolute expiration date for the cookie
+     */
+    expires?: Date | undefined;
+    /**
+     * Relative max age of the cookie in seconds from when the client receives it (integer or undefined)
+     *
+     * Note: when using with express's res.cookie() method, multiply maxAge by 1000 to convert to milliseconds
+     */
+    maxAge?: number | undefined;
+    /**
+     * Domain for the cookie,
+     * May begin with "." to indicate the named domain or any subdomain of it
+     */
+    domain?: string | undefined;
+    /**
+     * Indicates that this cookie should only be sent over HTTPs
+     */
+    secure?: boolean | undefined;
+    /**
+     * Indicates that this cookie should not be accessible to client-side JavaScript
+     */
+    httpOnly?: boolean | undefined;
+    /**
+     * Indicates a cookie ought not to be sent along with cross-site requests
+     */
+    sameSite?: string | undefined;
+    [key: string]: unknown;
+}
+
+/**
+ * Parse a [Set-Cookie](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie) header string into an object.
+ */
+declare function parseSetCookie(setCookieValue: string, options?: SetCookieParseOptions): SetCookie;
+
+/**
+ * Set-Cookie header field-values are sometimes comma joined in one string. This splits them without choking on commas
+ * that are within a single set-cookie field-value, such as in the Expires portion.
+ *
+ * See https://tools.ietf.org/html/rfc2616#section-4.2
+ */
+declare function splitSetCookieString(cookiesString: string | string[]): string[];
+
+export { type CookieParseOptions, type CookieSerializeOptions, type SetCookie, type SetCookieParseOptions, parse, parseSetCookie, serialize, splitSetCookieString };

package/dist/index.mjs

@@ -1,4 +1,3 @@
-const fieldContentRegExp = /^[\u0009\u0020-\u007E\u0080-\u00FF]+$/;
 function parse(str, options) {
   if (typeof str !== "string") {
     throw new TypeError("argument str must be a string");
@@ -31,9 +30,21 @@ function parse(str, options) {
   }
   return obj;
 }
+function decode(str) {
+  return str.includes("%") ? decodeURIComponent(str) : str;
+}
+function tryDecode(str, decode2) {
+  try {
+    return decode2(str);
+  } catch {
+    return str;
+  }
+}
+
+const fieldContentRegExp = /^[\u0009\u0020-\u007E\u0080-\u00FF]+$/;
 function serialize(name, value, options) {
   const opt = options || {};
-  const enc = opt.encode || encode;
+  const enc = opt.encode || encodeURIComponent;
   if (typeof enc !== "function") {
     throw new TypeError("option encode is invalid");
   }
@@ -79,55 +90,169 @@ function serialize(name, value, options) {
   if (opt.priority) {
     const priority = typeof opt.priority === "string" ? opt.priority.toLowerCase() : opt.priority;
     switch (priority) {
-      case "low":
+      case "low": {
         str += "; Priority=Low";
         break;
-      case "medium":
+      }
+      case "medium": {
         str += "; Priority=Medium";
         break;
-      case "high":
+      }
+      case "high": {
         str += "; Priority=High";
         break;
-      default:
+      }
+      default: {
         throw new TypeError("option priority is invalid");
+      }
     }
   }
   if (opt.sameSite) {
     const sameSite = typeof opt.sameSite === "string" ? opt.sameSite.toLowerCase() : opt.sameSite;
     switch (sameSite) {
-      case true:
+      case true: {
         str += "; SameSite=Strict";
         break;
-      case "lax":
+      }
+      case "lax": {
         str += "; SameSite=Lax";
         break;
-      case "strict":
+      }
+      case "strict": {
         str += "; SameSite=Strict";
         break;
-      case "none":
+      }
+      case "none": {
         str += "; SameSite=None";
         break;
-      default:
+      }
+      default: {
         throw new TypeError("option sameSite is invalid");
+      }
     }
   }
+  if (opt.partitioned) {
+    str += "; Partitioned";
+  }
   return str;
 }
 function isDate(val) {
   return Object.prototype.toString.call(val) === "[object Date]" || val instanceof Date;
 }
-function tryDecode(str, decode2) {
+
+function parseSetCookie(setCookieValue, options) {
+  const parts = (setCookieValue || "").split(";").filter((str) => typeof str === "string" && !!str.trim());
+  const nameValuePairStr = parts.shift() || "";
+  const parsed = _parseNameValuePair(nameValuePairStr);
+  const name = parsed.name;
+  let value = parsed.value;
   try {
-    return decode2(str);
+    value = options?.decode === false ? value : (options?.decode || decodeURIComponent)(value);
   } catch {
-    return str;
   }
+  const cookie = {
+    name,
+    value
+  };
+  for (const part of parts) {
+    const sides = part.split("=");
+    const partKey = (sides.shift() || "").trimStart().toLowerCase();
+    const partValue = sides.join("=");
+    switch (partKey) {
+      case "expires": {
+        cookie.expires = new Date(partValue);
+        break;
+      }
+      case "max-age": {
+        cookie.maxAge = Number.parseInt(partValue, 10);
+        break;
+      }
+      case "secure": {
+        cookie.secure = true;
+        break;
+      }
+      case "httponly": {
+        cookie.httpOnly = true;
+        break;
+      }
+      case "samesite": {
+        cookie.sameSite = partValue;
+        break;
+      }
+      default: {
+        cookie[partKey] = partValue;
+      }
+    }
+  }
+  return cookie;
 }
-function decode(str) {
-  return str.includes("%") ? decodeURIComponent(str) : str;
+function _parseNameValuePair(nameValuePairStr) {
+  let name = "";
+  let value = "";
+  const nameValueArr = nameValuePairStr.split("=");
+  if (nameValueArr.length > 1) {
+    name = nameValueArr.shift();
+    value = nameValueArr.join("=");
+  } else {
+    value = nameValuePairStr;
+  }
+  return { name, value };
 }
-function encode(val) {
-  return encodeURIComponent(val);
+
+function splitSetCookieString(cookiesString) {
+  if (Array.isArray(cookiesString)) {
+    return cookiesString.flatMap((c) => splitSetCookieString(c));
+  }
+  if (typeof cookiesString !== "string") {
+    return [];
+  }
+  const cookiesStrings = [];
+  let pos = 0;
+  let start;
+  let ch;
+  let lastComma;
+  let nextStart;
+  let cookiesSeparatorFound;
+  const skipWhitespace = () => {
+    while (pos < cookiesString.length && /\s/.test(cookiesString.charAt(pos))) {
+      pos += 1;
+    }
+    return pos < cookiesString.length;
+  };
+  const notSpecialChar = () => {
+    ch = cookiesString.charAt(pos);
+    return ch !== "=" && ch !== ";" && ch !== ",";
+  };
+  while (pos < cookiesString.length) {
+    start = pos;
+    cookiesSeparatorFound = false;
+    while (skipWhitespace()) {
+      ch = cookiesString.charAt(pos);
+      if (ch === ",") {
+        lastComma = pos;
+        pos += 1;
+        skipWhitespace();
+        nextStart = pos;
+        while (pos < cookiesString.length && notSpecialChar()) {
+          pos += 1;
+        }
+        if (pos < cookiesString.length && cookiesString.charAt(pos) === "=") {
+          cookiesSeparatorFound = true;
+          pos = nextStart;
+          cookiesStrings.push(cookiesString.slice(start, lastComma));
+          start = pos;
+        } else {
+          pos = lastComma + 1;
+        }
+      } else {
+        pos += 1;
+      }
+    }
+    if (!cookiesSeparatorFound || pos >= cookiesString.length) {
+      cookiesStrings.push(cookiesString.slice(start, cookiesString.length));
+    }
+  }
+  return cookiesStrings;
 }
 
-export { parse, serialize };
+export { parse, parseSetCookie, serialize, splitSetCookieString };

package/package.json

@@ -1,40 +1,46 @@
 {
   "name": "cookie-es",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "repository": "unjs/cookie-es",
   "license": "MIT",
   "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "require": "./dist/index.cjs",
-      "import": "./dist/index.mjs"
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     }
   },
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
-  "types": "./dist/index.d.ts",
+  "types": "./dist/index.d.cts",
   "files": [
     "dist"
   ],
   "scripts": {
     "build": "unbuild",
-    "dev": "vitest",
-    "lint": "eslint --cache --ext .ts,.js,.mjs,.cjs . && prettier -c src test",
-    "lint:fix": "eslint --cache --ext .ts,.js,.mjs,.cjs . --fix && prettier -c src test -w",
+    "dev": "vitest --coverage",
+    "lint": "eslint --cache . && prettier -c src test",
+    "lint:fix": "automd && eslint --cache . --fix && prettier -c src test -w",
     "release": "pnpm test && pnpm build && changelogen --release --push && npm publish",
     "test": "pnpm lint && vitest run --coverage"
   },
   "devDependencies": {
-    "@vitest/coverage-c8": "^0.31.0",
-    "changelogen": "^0.5.3",
-    "eslint": "^8.39.0",
-    "eslint-config-unjs": "^0.1.0",
-    "prettier": "^2.8.8",
-    "typescript": "^5.0.4",
-    "unbuild": "^1.2.1",
-    "vitest": "^0.31.0"
+    "@vitest/coverage-v8": "^2.0.3",
+    "automd": "^0.3.8",
+    "changelogen": "^0.5.5",
+    "eslint": "^9.7.0",
+    "eslint-config-unjs": "^0.3.2",
+    "prettier": "^3.3.3",
+    "typescript": "^5.5.3",
+    "unbuild": "^2.0.0",
+    "vitest": "^2.0.3"
   },
-  "packageManager": "pnpm@8.4.0"
-}
+  "packageManager": "pnpm@9.5.0"
+}