cookie-es 1.0.0 → 1.1.0

package/README.md

@@ -1,7 +1,13 @@
 
 # cookie-es
 
-[![bundle size](https://flat.badgen.net/bundlephobia/minzip/cookie-es)](https://bundlephobia.com/package/cookie-es)
+<!-- automd:badges bundlejs -->
+
+[![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 -->
 
 ESM build of [cookie](https://www.npmjs.com/package/cookie) with bundled types.
 
@@ -9,24 +15,53 @@ ESM build of [cookie](https://www.npmjs.com/package/cookie) with bundled types.
 
 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 } from "cookie-es";
+```
+
+**CommonJS** (Legacy Node.js)
 
-// CommonJS
-const { parse, serialize } = require('cookie-es')
+```js
+const { parse, serialize } = require("cookie-es");
 ```
 
+**CDN** (Deno, Bun and Browsers)
+
+```js
+import { parse, serialize } from "https://esm.sh/cookie-es";
+```
+
+<!-- /automd -->
+
+
 ## License
 
 [MIT](./LICENSE)

package/dist/index.cjs

@@ -81,38 +81,50 @@ 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) {

package/dist/index.d.cts

@@ -0,0 +1,151 @@
+/**
+ * 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`](rfc-cutler-httpbis-partitioned-cookies)
+     * 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 about 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;
+}
+
+/**
+ * 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;
+
+export { type CookieParseOptions, type CookieSerializeOptions, parse, serialize };

package/dist/index.d.mts

@@ -0,0 +1,151 @@
+/**
+ * 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`](rfc-cutler-httpbis-partitioned-cookies)
+     * 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 about 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;
+}
+
+/**
+ * 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;
+
+export { type CookieParseOptions, type CookieSerializeOptions, parse, serialize };

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`](rfc-cutler-httpbis-partitioned-cookies)
+     * 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 about can be found in [the proposal](https://github.com/privacycg/CHIPS)
+     */
+    partitioned?: boolean;
 }
 /**
  * Additional parsing options
@@ -137,4 +148,4 @@ declare function parse(str: string, options?: CookieParseOptions): Record<string
  */
 declare function serialize(name: string, value: string, options?: CookieSerializeOptions): string;
 
-export { CookieParseOptions, CookieSerializeOptions, parse, serialize };
+export { type CookieParseOptions, type CookieSerializeOptions, parse, serialize };

package/dist/index.mjs

@@ -79,38 +79,50 @@ 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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cookie-es",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "repository": "unjs/cookie-es",
   "license": "MIT",
   "sideEffects": false,
@@ -22,19 +22,20 @@
     "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",
+    "lint:fix": "automd && eslint --cache --ext .ts,.js,.mjs,.cjs . --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": "^1.4.0",
+    "automd": "^0.3.7",
+    "changelogen": "^0.5.5",
+    "eslint": "^8.57.0",
+    "eslint-config-unjs": "^0.2.1",
+    "prettier": "^3.2.5",
+    "typescript": "^5.4.3",
+    "unbuild": "^2.0.0",
+    "vitest": "^1.4.0"
   },
-  "packageManager": "pnpm@8.4.0"
+  "packageManager": "pnpm@8.15.5"
 }