Use modern JS features, ship TS defs (#175)

Author: blakeembrey

.eslintignore

@@ -1,253 +1,26 @@
 name: ci
 
 on:
-- pull_request
-- push
+  - pull_request
+  - push
 
 jobs:
   test:
-    runs-on: ubuntu-20.04
+    name: Node.js ${{ matrix.node-version }}
+    runs-on: ubuntu-latest
     strategy:
       matrix:
-        name:
-        - Node.js 0.6
-        - Node.js 0.8
-        - Node.js 0.10
-        - Node.js 0.12
-        - io.js 1.x
-        - io.js 2.x
-        - io.js 3.x
-        - Node.js 4.x
-        - Node.js 5.x
-        - Node.js 6.x
-        - Node.js 7.x
-        - Node.js 8.x
-        - Node.js 9.x
-        - Node.js 10.x
-        - Node.js 11.x
-        - Node.js 12.x
-        - Node.js 13.x
-        - Node.js 14.x
-        - Node.js 15.x
-        - Node.js 16.x
-        - Node.js 17.x
-        - Node.js 18.x
-        - Node.js 19.x
-        - Node.js 20.x
-        - Node.js 21.x
-
-        include:
-        - name: Node.js 0.6
-          node-version: "0.6"
-          npm-i: mocha@1.21.5
-          npm-rm: beautify-benchmark benchmark nyc top-sites
-
-        - name: Node.js 0.8
-          node-version: "0.8"
-          npm-i: mocha@2.5.3
-          npm-rm: beautify-benchmark benchmark nyc top-sites
-
-        - name: Node.js 0.10
-          node-version: "0.10"
-          npm-i: mocha@3.5.3 nyc@10.3.2
-          npm-rm: beautify-benchmark benchmark top-sites
-
-        - name: Node.js 0.12
-          node-version: "0.12"
-          npm-i: mocha@3.5.3 nyc@10.3.2
-          npm-rm: beautify-benchmark benchmark top-sites
-
-        - name: io.js 1.x
-          node-version: "1.8"
-          npm-i: mocha@3.5.3 nyc@10.3.2
-          npm-rm: beautify-benchmark benchmark top-sites
-
-        - name: io.js 2.x
-          node-version: "2.5"
-          npm-i: mocha@3.5.3 nyc@10.3.2
-          npm-rm: beautify-benchmark benchmark top-sites
-
-        - name: io.js 3.x
-          node-version: "3.3"
-          npm-i: mocha@3.5.3 nyc@10.3.2
-          npm-rm: beautify-benchmark benchmark top-sites
-
-        - name: Node.js 4.x
-          node-version: "4.9"
-          npm-i: mocha@5.2.0 nyc@11.9.0
-          npm-rm: beautify-benchmark benchmark top-sites
-
-        - name: Node.js 5.x
-          node-version: "5.12"
-          npm-i: mocha@5.2.0 nyc@11.9.0
-          npm-rm: beautify-benchmark benchmark top-sites
-
-        - name: Node.js 6.x
-          node-version: "6.17"
-          npm-i: mocha@6.2.2 nyc@14.1.1
-          npm-rm: beautify-benchmark benchmark top-sites
-
-        - name: Node.js 7.x
-          node-version: "7.10"
-          npm-i: mocha@6.2.2 nyc@14.1.1
-          npm-rm: beautify-benchmark benchmark top-sites
-
-        - name: Node.js 8.x
-          node-version: "8.17"
-          npm-i: mocha@7.1.2 nyc@14.1.1
-          npm-rm: beautify-benchmark benchmark top-sites
-
-        - name: Node.js 9.x
-          node-version: "9.11"
-          npm-i: mocha@7.1.2 nyc@14.1.1
-          npm-rm: beautify-benchmark benchmark top-sites
-
-        - name: Node.js 10.x
-          node-version: "10.24"
-          npm-i: mocha@8.4.0
-          npm-rm: beautify-benchmark benchmark top-sites
-
-        - name: Node.js 11.x
-          node-version: "11.15"
-          npm-i: mocha@8.4.0
-          npm-rm: beautify-benchmark benchmark top-sites
-
-        - name: Node.js 12.x
-          node-version: "12.22"
-          npm-i: mocha@9.2.2
-          npm-rm: beautify-benchmark benchmark top-sites
-
-        - name: Node.js 13.x
-          node-version: "13.14"
-          npm-i: mocha@9.2.2
-          npm-rm: beautify-benchmark benchmark top-sites
-
-        - name: Node.js 14.x
-          node-version: "14.21"
-          npm-rm: beautify-benchmark benchmark top-sites
-
-        - name: Node.js 15.x
-          node-version: "15.14"
-          npm-rm: beautify-benchmark benchmark top-sites
-
-        - name: Node.js 16.x
-          node-version: "16.20"
-          npm-rm: beautify-benchmark benchmark top-sites
-
-        - name: Node.js 17.x
-          node-version: "17.9"
-          npm-rm: beautify-benchmark benchmark top-sites
-
-        - name: Node.js 18.x
-          node-version: "18.18"
-          npm-rm: beautify-benchmark benchmark top-sites
-
-        - name: Node.js 19.x
-          node-version: "19.9"
-          npm-rm: beautify-benchmark benchmark top-sites
-
-        - name: Node.js 20.x
-          node-version: "20.9"
-          npm-rm: beautify-benchmark benchmark top-sites
-
-        - name: Node.js 21.x
-          node-version: "21.1"
-
-    steps:
-    - uses: actions/checkout@v3
-
-    - name: Install Node.js ${{ matrix.node-version }}
-      shell: bash -eo pipefail -l {0}
-      run: |
-        if [[ "${{ matrix.node-version }}" == 0.6* ]]; then
-          sudo sh -c 'echo "deb http://us.archive.ubuntu.com/ubuntu/ bionic universe" >> /etc/apt/sources.list'
-          sudo sh -c 'echo "deb http://security.ubuntu.com/ubuntu bionic-security main" >> /etc/apt/sources.list'
-          sudo apt-get update
-          sudo apt-get install g++-4.8 gcc-4.8 libssl1.0-dev python2 python-is-python2
-          export CC=/usr/bin/gcc-4.8
-          export CXX=/usr/bin/g++-4.8
-        fi
-        nvm install --default ${{ matrix.node-version }}
-        if [[ "${{ matrix.node-version }}" == 0.* && "$(cut -d. -f2 <<< "${{ matrix.node-version }}")" -lt 10 ]]; then
-          nvm install --alias=npm 0.10
-          nvm use ${{ matrix.node-version }}
-          if [[ "$(npm -v)" == 1.1.* ]]; then
-            nvm exec npm npm install -g npm@1.1
-            ln -fs "$(which npm)" "$(dirname "$(nvm which npm)")/npm"
-          else
-            sed -i '1s;^.*$;'"$(printf '#!%q' "$(nvm which npm)")"';' "$(readlink -f "$(which npm)")"
-          fi
-          npm config set strict-ssl false
-        fi
-        dirname "$(nvm which ${{ matrix.node-version }})" >> "$GITHUB_PATH"
-
-    - name: Configure npm
-      run: |
-        if [[ "$(npm config get package-lock)" == "true" ]]; then
-          npm config set package-lock false
-        else
-          npm config set shrinkwrap false
-        fi
-
-    - name: Remove npm module(s) ${{ matrix.npm-rm }}
-      run: npm rm --silent --save-dev ${{ matrix.npm-rm }}
-      if: matrix.npm-rm != ''
-
-    - name: Install npm module(s) ${{ matrix.npm-i }}
-      run: npm install --save-dev ${{ matrix.npm-i }}
-      if: matrix.npm-i != ''
-
-    - name: Setup Node.js version-specific dependencies
-      shell: bash
-      run: |
-        # eslint for linting
-        # - remove on Node.js < 12
-        if [[ "$(cut -d. -f1 <<< "${{ matrix.node-version }}")" -lt 12 ]]; then
-          node -pe 'Object.keys(require("./package").devDependencies).join("\n")' | \
-            grep -E '^eslint(-|$)' | \
-            sort -r | \
-            xargs -n1 npm rm --silent --save-dev
-        fi
-
-    - name: Install Node.js dependencies
-      run: npm install
-
-    - name: List environment
-      id: list_env
-      shell: bash
-      run: |
-        echo "node@$(node -v)"
-        echo "npm@$(npm -v)"
-        npm -s ls ||:
-        (npm -s ls --depth=0 ||:) | awk -F'[ @]' 'NR>1 && $2 { print $2 "=" $3 }' >> "$GITHUB_OUTPUT"
-
-    - name: Run tests
-      shell: bash
-      run: |
-        if npm -ps ls nyc | grep -q nyc; then
-          npm run test-ci
-        else
-          npm test
-        fi
-
-    - name: Lint code
-      if: steps.list_env.outputs.eslint != ''
-      run: npm run lint
-
-    - name: Collect code coverage
-      uses: coverallsapp/github-action@master
-      if: steps.list_env.outputs.nyc != ''
-      with:
-        github-token: ${{ secrets.GITHUB_TOKEN }}
-        flag-name: run-${{ matrix.test_number }}
-        parallel: true
-
-  coverage:
-    needs: test
-    runs-on: ubuntu-latest
+        node-version:
+          - "18"
+          - "20"
+          - "22"
     steps:
-    - name: Upload code coverage
-      uses: coverallsapp/github-action@master
-      with:
-        github-token: ${{ secrets.github_token }}
-        parallel-finished: true
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm ci
+      - run: npm test
+      - uses: codecov/codecov-action@v4
+        with:
+          name: Node.js ${{ matrix.node-version }}

.eslintrc.yml

@@ -2,4 +2,5 @@
 coverage/
 node_modules/
 npm-debug.log
-package-lock.json
+dist/
+*.tsbuildinfo

.github/workflows/ci.yml

@@ -1,44 +1,42 @@
 {
   "name": "cookie",
-  "description": "HTTP server cookie parsing and serialization",
   "version": "0.7.2",
-  "author": "Roman Shtylman <shtylman@gmail.com>",
-  "contributors": [
-    "Douglas Christopher Wilson <doug@somethingdoug.com>"
-  ],
-  "license": "MIT",
+  "description": "HTTP server cookie parsing and serialization",
   "keywords": [
     "cookie",
     "cookies"
   ],
   "repository": "jshttp/cookie",
-  "devDependencies": {
-    "beautify-benchmark": "0.2.4",
-    "benchmark": "2.1.4",
-    "eslint": "8.53.0",
-    "eslint-plugin-markdown": "3.0.1",
-    "mocha": "10.2.0",
-    "nyc": "15.1.0",
-    "safe-buffer": "5.2.1",
-    "top-sites": "1.1.194"
-  },
+  "license": "MIT",
+  "author": "Roman Shtylman <shtylman@gmail.com>",
+  "contributors": [
+    "Douglas Christopher Wilson <doug@somethingdoug.com>"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "files": [
-    "HISTORY.md",
-    "LICENSE",
-    "README.md",
-    "SECURITY.md",
-    "index.js"
+    "dist/"
   ],
-  "main": "index.js",
+  "scripts": {
+    "bench": "vitest bench",
+    "build": "ts-scripts build",
+    "format": "ts-scripts format",
+    "prepare": "ts-scripts install",
+    "prepublishOnly": "npm run build",
+    "specs": "ts-scripts specs",
+    "test": "ts-scripts test"
+  },
+  "devDependencies": {
+    "@borderless/ts-scripts": "^0.15.0",
+    "@vitest/coverage-v8": "^2.1.2",
+    "top-sites": "1.1.194",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.2"
+  },
   "engines": {
-    "node": ">= 0.6"
+    "node": ">=18"
   },
-  "scripts": {
-    "bench": "node benchmark/index.js",
-    "lint": "eslint .",
-    "test": "mocha --reporter spec --bail --check-leaks test/",
-    "test-ci": "nyc --reporter=lcov --reporter=text npm test",
-    "test-cov": "nyc --reporter=html --reporter=text npm test",
-    "update-bench": "node scripts/update-benchmark.js"
+  "ts-scripts": {
+    "project": "tsconfig.build.json"
   }
 }

.gitignore

@@ -1,69 +1,90 @@
-'use strict'
+"use strict";
 
-var fs = require('fs')
-var http = require('http')
-var https = require('https')
-var path = require('path')
-var topSites = require('top-sites')
-var url = require('url')
+var fs = require("fs");
+var http = require("http");
+var https = require("https");
+var path = require("path");
+var topSites = require("top-sites");
+var url = require("url");
 
-var BENCH_COOKIES_FILE = path.join(__dirname, '..', 'benchmark', 'parse-top.json')
+var BENCH_COOKIES_FILE = path.join(__dirname, "parse-top.json");
 
 getAllCookies(topSites.slice(0, 20), function (err, cookies) {
-  if (err) throw err
-  var str = '{\n' +
-    Object.keys(cookies).sort().map(function (key) {
-      return '  ' + JSON.stringify(key) + ': ' + JSON.stringify(cookies[key])
-    }).join(',\n') +
-    '\n}\n'
-  fs.writeFileSync(BENCH_COOKIES_FILE, str)
-})
+  if (err) throw err;
+  var str =
+    "{\n" +
+    Object.keys(cookies)
+      .sort()
+      .map(function (key) {
+        return "  " + JSON.stringify(key) + ": " + JSON.stringify(cookies[key]);
+      })
+      .join(",\n") +
+    "\n}\n";
+  fs.writeFileSync(BENCH_COOKIES_FILE, str);
+});
 
-function get (href, callback) {
-  var protocol = url.parse(href, false, true).protocol
-  var proto = protocol === 'https:' ? https : http
+function get(href, callback) {
+  var protocol = url.parse(href, false, true).protocol;
+  var proto = protocol === "https:" ? https : http;
 
-  proto.get(href)
-    .on('error', callback)
-    .on('response', function (res) {
-      if (res.headers.location && res.statusCode >= 300 && res.statusCode < 400) {
-        get(url.resolve(href, res.headers.location), callback)
+  proto
+    .get(href)
+    .on("error", callback)
+    .on("response", function (res) {
+      if (
+        res.headers.location &&
+        res.statusCode >= 300 &&
+        res.statusCode < 400
+      ) {
+        get(url.resolve(href, res.headers.location), callback);
       } else {
-        callback(null, res)
+        callback(null, res);
       }
-    })
+    });
 }
 
-function getAllCookies (sites, callback) {
-  var all = Object.create(null)
-  var wait = sites.length
+function getAllCookies(sites, callback) {
+  var all = Object.create(null);
+  var wait = sites.length;
 
   sites.forEach(function (site) {
     getCookies(site, function (err, cookies) {
       if (!err && cookies.length) {
-        all[site.rootDomain] = cookies.map(obfuscate).join('; ')
+        all[site.rootDomain] = cookies.map(obfuscate).join("; ");
       }
       if (!--wait) {
-        callback(null, all)
+        callback(null, all);
       }
-    })
-  })
+    });
+  });
 }
 
-function getCookies (site, callback) {
-  var href = url.format({ hostname: site.rootDomain, protocol: 'http' })
+function getCookies(site, callback) {
+  var href = url.format({ hostname: site.rootDomain, protocol: "http" });
   get(href, function (err, res) {
-    if (err) return callback(err)
-    var cookies = (res.headers['set-cookie'] || []).map(function (c) { return c.split(';')[0] })
-    callback(null, cookies)
-  })
+    if (err) return callback(err);
+    var cookies = (res.headers["set-cookie"] || []).map(function (c) {
+      return c.split(";")[0];
+    });
+    callback(null, cookies);
+  });
 }
 
-function obfuscate (str) {
+function obfuscate(str) {
   return str
-    .replace(/%[0-9a-f]{2}/gi, function () { return '%__' })
-    .replace(/[a-z]/g, function () { return 'l' })
-    .replace(/[A-Z]/g, function () { return 'U' })
-    .replace(/[0-9]/g, function () { return '0' })
-    .replace(/%__/g, function () { return '%22' })
+    .replace(/%[0-9a-f]{2}/gi, function () {
+      return "%__";
+    })
+    .replace(/[a-z]/g, function () {
+      return "l";
+    })
+    .replace(/[A-Z]/g, function () {
+      return "U";
+    })
+    .replace(/[0-9]/g, function () {
+      return "0";
+    })
+    .replace(/%__/g, function () {
+      return "%22";
+    });
 }

README.md

@@ -0,0 +1,389 @@
+/**
+ * RegExp to match cookie-name in RFC 6265 sec 4.1.1
+ * This refers out to the obsoleted definition of token in RFC 2616 sec 2.2
+ * which has been replaced by the token definition in RFC 7230 appendix B.
+ *
+ * cookie-name       = token
+ * token             = 1*tchar
+ * tchar             = "!" / "#" / "$" / "%" / "&" / "'" /
+ *                     "*" / "+" / "-" / "." / "^" / "_" /
+ *                     "`" / "|" / "~" / DIGIT / ALPHA
+ */
+const cookieNameRegExp = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+
+/**
+ * RegExp to match cookie-value in RFC 6265 sec 4.1.1
+ *
+ * cookie-value      = *cookie-octet / ( DQUOTE *cookie-octet DQUOTE )
+ * cookie-octet      = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E
+ *                     ; US-ASCII characters excluding CTLs,
+ *                     ; whitespace DQUOTE, comma, semicolon,
+ *                     ; and backslash
+ */
+const cookieValueRegExp =
+  /^("?)[\u0021\u0023-\u002B\u002D-\u003A\u003C-\u005B\u005D-\u007E]*\1$/;
+
+/**
+ * RegExp to match domain-value in RFC 6265 sec 4.1.1
+ *
+ * domain-value      = <subdomain>
+ *                     ; defined in [RFC1034], Section 3.5, as
+ *                     ; enhanced by [RFC1123], Section 2.1
+ * <subdomain>       = <label> | <subdomain> "." <label>
+ * <label>           = <let-dig> [ [ <ldh-str> ] <let-dig> ]
+ *                     Labels must be 63 characters or less.
+ *                     'let-dig' not 'letter' in the first char, per RFC1123
+ * <ldh-str>         = <let-dig-hyp> | <let-dig-hyp> <ldh-str>
+ * <let-dig-hyp>     = <let-dig> | "-"
+ * <let-dig>         = <letter> | <digit>
+ * <letter>          = any one of the 52 alphabetic characters A through Z in
+ *                     upper case and a through z in lower case
+ * <digit>           = any one of the ten digits 0 through 9
+ *
+ * Keep support for leading dot: https://github.com/jshttp/cookie/issues/173
+ *
+ * > (Note that a leading %x2E ("."), if present, is ignored even though that
+ * character is not permitted, but a trailing %x2E ("."), if present, will
+ * cause the user agent to ignore the attribute.)
+ */
+const domainValueRegExp =
+  /^([.]?[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)([.][a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/i;
+
+/**
+ * RegExp to match path-value in RFC 6265 sec 4.1.1
+ *
+ * path-value        = <any CHAR except CTLs or ";">
+ * CHAR              = %x01-7F
+ *                     ; defined in RFC 5234 appendix B.1
+ */
+const pathValueRegExp = /^[\u0020-\u003A\u003D-\u007E]*$/;
+
+const __toString = Object.prototype.toString;
+const __hasOwnProperty = Object.prototype.hasOwnProperty;
+
+const NullObject = /* @__PURE__ */ (() => {
+  const C = function () {};
+  C.prototype = Object.create(null);
+  return C;
+})() as unknown as { new (): any };
+
+/**
+ * Parse options.
+ */
+export interface ParseOptions {
+  /**
+   * 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.
+   *
+   * Note: if an error is thrown from this function, the original, non-decoded
+   * cookie value will be returned as the cookie's value.
+   *
+   * @default decodeURIComponent
+   */
+  decode?: (str: string) => string;
+}
+
+/**
+ * Parse a cookie header.
+ *
+ * Parse the given cookie header string into an object
+ * The object has the various cookies as keys(names) => values
+ */
+export function parse(
+  str: string,
+  options?: ParseOptions,
+): Record<string, string> {
+  const obj: Record<string, string> = new NullObject();
+  const len = str.length;
+  // RFC 6265 sec 4.1.1, RFC 2616 2.2 defines a cookie name consists of one char minimum, plus '='.
+  if (len < 2) return obj;
+
+  const dec = options?.decode || decode;
+  let index = 0;
+
+  do {
+    const eqIdx = str.indexOf("=", index);
+    if (eqIdx === -1) break; // No more cookie pairs.
+
+    const colonIdx = str.indexOf(";", index);
+    const endIdx = colonIdx === -1 ? len : colonIdx;
+
+    if (eqIdx > endIdx) {
+      // backtrack on prior semicolon
+      index = str.lastIndexOf(";", eqIdx - 1) + 1;
+      continue;
+    }
+
+    const keyStartIdx = startIndex(str, index, eqIdx);
+    const keyEndIdx = endIndex(str, eqIdx, keyStartIdx);
+    const key = str.slice(keyStartIdx, keyEndIdx);
+
+    // only assign once
+    if (!__hasOwnProperty.call(obj, key)) {
+      let valStartIdx = startIndex(str, eqIdx + 1, endIdx);
+      let valEndIdx = endIndex(str, endIdx, valStartIdx);
+
+      if (
+        str.charCodeAt(valStartIdx) === 0x22 /* " */ &&
+        str.charCodeAt(valEndIdx - 1) === 0x22 /* " */
+      ) {
+        valStartIdx++;
+        valEndIdx--;
+      }
+
+      const val = str.slice(valStartIdx, valEndIdx);
+      obj[key] = tryDecode(val, dec);
+    }
+
+    index = endIdx + 1;
+  } while (index < len);
+
+  return obj;
+}
+
+function startIndex(str: string, index: number, max: number) {
+  do {
+    const code = str.charCodeAt(index);
+    if (code !== 0x20 /*   */ && code !== 0x09 /* \t */) return index;
+  } while (++index < max);
+  return max;
+}
+
+function endIndex(str: string, index: number, min: number) {
+  while (index > min) {
+    const code = str.charCodeAt(--index);
+    if (code !== 0x20 /*   */ && code !== 0x09 /* \t */) return index + 1;
+  }
+  return min;
+}
+
+/**
+ * Serialize options.
+ */
+export interface SerializeOptions {
+  /**
+   * 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.
+   *
+   * @default encodeURIComponent
+   */
+  encode?: (str: string) => string;
+  /**
+   * Specifies the `number` (in seconds) to be the value for the [`Max-Age` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.2).
+   * The given number will be converted to an integer by rounding down. By default, no maximum age is set.
+   *
+   * The [cookie storage model specification](https://tools.ietf.org/html/rfc6265#section-5.3) 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;
+  /**
+   * Specifies the `Date` object to be the value for the [`Expires` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.1).
+   * 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.
+   *
+   * The [cookie storage model specification](https://tools.ietf.org/html/rfc6265#section-5.3) 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;
+  /**
+   * Specifies the value for the [`Domain` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.3).
+   * By default, no domain is set, and most clients will consider the cookie to apply to only the current domain.
+   */
+  domain?: string;
+  /**
+   * Specifies the value for the [`Path` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.4). By default, the path
+   * is considered the ["default path"](https://tools.ietf.org/html/rfc6265#section-5.1.4).
+   */
+  path?: string;
+  /**
+   * Specifies the `boolean` value for the [`HttpOnly` `Set-Cookie` attribute][rfc-6265-5.2.6]. When truthy,
+   * the `HttpOnly` attribute is set, otherwise it is not. By default, the `HttpOnly` attribute is not set.
+   *
+   * 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;
+  /**
+   * Specifies the `boolean` value for the [`Secure` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.5). When truthy,
+   * the `Secure` attribute is set, otherwise it is not. By default, the `Secure` attribute is not set.
+   *
+   * 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;
+  /**
+   * Specifies the `boolean` value for the [`Partitioned` `Set-Cookie`](https://tools.ietf.org/html/draft-cutler-httpbis-partitioned-cookies/)
+   * attribute. When truthy, the `Partitioned` attribute is set, otherwise it is not. By default, the
+   * `Partitioned` attribute is not set.
+   *
+   * 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;
+  /**
+   * Specifies the value for the [`Priority` `Set-Cookie` attribute](https://tools.ietf.org/html/draft-west-cookie-priority-00#section-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](https://tools.ietf.org/html/draft-west-cookie-priority-00#section-4.1).
+   */
+  priority?: "low" | "medium" | "high";
+  /**
+   * Specifies the value for the [`SameSite` `Set-Cookie` attribute](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-09#section-5.4.7).
+   *
+   * - `true` will set the `SameSite` attribute to `Strict` for strict same site enforcement.
+   * - `'lax'` will set the `SameSite` attribute to `Lax` for lax same site enforcement.
+   * - `'none'` will set the `SameSite` attribute to `None` for an explicit cross-site cookie.
+   * - `'strict'` will set the `SameSite` attribute to `Strict` for strict same site enforcement.
+   *
+   * More information about the different enforcement levels can be found in
+   * [the specification](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-09#section-5.4.7).
+   */
+  sameSite?: boolean | "lax" | "strict" | "none";
+}
+
+/**
+ * Serialize data into a cookie header.
+ *
+ * Serialize a name value pair into a cookie string suitable for
+ * http headers. An optional options object specifies cookie parameters.
+ *
+ * serialize('foo', 'bar', { httpOnly: true })
+ *   => "foo=bar; httpOnly"
+ */
+export function serialize(
+  name: string,
+  val: string,
+  options?: SerializeOptions,
+): string {
+  const enc = options?.encode || encodeURIComponent;
+
+  if (!cookieNameRegExp.test(name)) {
+    throw new TypeError(`argument name is invalid: ${name}`);
+  }
+
+  const value = enc(val);
+
+  if (!cookieValueRegExp.test(value)) {
+    throw new TypeError(`argument val is invalid: ${val}`);
+  }
+
+  let str = name + "=" + value;
+  if (!options) return str;
+
+  if (options.maxAge !== undefined) {
+    if (!Number.isInteger(options.maxAge)) {
+      throw new TypeError(`option maxAge is invalid: ${options.maxAge}`);
+    }
+
+    str += "; Max-Age=" + options.maxAge;
+  }
+
+  if (options.domain) {
+    if (!domainValueRegExp.test(options.domain)) {
+      throw new TypeError(`option domain is invalid: ${options.domain}`);
+    }
+
+    str += "; Domain=" + options.domain;
+  }
+
+  if (options.path) {
+    if (!pathValueRegExp.test(options.path)) {
+      throw new TypeError(`option path is invalid: ${options.path}`);
+    }
+
+    str += "; Path=" + options.path;
+  }
+
+  if (options.expires) {
+    if (
+      !isDate(options.expires) ||
+      !Number.isFinite(options.expires.valueOf())
+    ) {
+      throw new TypeError(`option expires is invalid: ${options.expires}`);
+    }
+
+    str += "; Expires=" + options.expires.toUTCString();
+  }
+
+  if (options.httpOnly) {
+    str += "; HttpOnly";
+  }
+
+  if (options.secure) {
+    str += "; Secure";
+  }
+
+  if (options.partitioned) {
+    str += "; Partitioned";
+  }
+
+  if (options.priority) {
+    switch (options.priority) {
+      case "low":
+        str += "; Priority=Low";
+        break;
+      case "medium":
+        str += "; Priority=Medium";
+        break;
+      case "high":
+        str += "; Priority=High";
+        break;
+      default:
+        throw new TypeError(`option priority is invalid: ${options.priority}`);
+    }
+  }
+
+  if (options.sameSite) {
+    switch (options.sameSite) {
+      case true:
+      case "strict":
+        str += "; SameSite=Strict";
+        break;
+      case "lax":
+        str += "; SameSite=Lax";
+        break;
+      case "none":
+        str += "; SameSite=None";
+        break;
+      default:
+        throw new TypeError(`option sameSite is invalid: ${options.sameSite}`);
+    }
+  }
+
+  return str;
+}
+
+/**
+ * URL-decode string value. Optimized to skip native call when no %.
+ */
+function decode(str: string): string {
+  return str.indexOf("%") !== -1 ? decodeURIComponent(str) : str;
+}
+
+/**
+ * Determine if value is a Date.
+ */
+function isDate(val: any): val is Date {
+  return __toString.call(val) === "[object Date]";
+}
+
+/**
+ * Try decoding a string using a decoding function.
+ */
+function tryDecode(str: string, decode: (str: string) => string): string {
+  try {
+    return decode(str);
+  } catch (e) {
+    return str;
+  }
+}

benchmark/index.js

@@ -0,0 +1,47 @@
+import { describe, bench } from "vitest";
+import * as cookie from "./index.js";
+import top from "../scripts/parse-top.json";
+
+describe("parse", () => {
+  bench("simple", () => {
+    cookie.parse("foo=bar");
+  });
+
+  bench("decode", () => {
+    cookie.parse("foo=hello%20there!");
+  });
+
+  bench("unquote", () => {
+    cookie.parse('foo="foo bar"');
+  });
+
+  bench("duplicates", () => {
+    cookie.parse(genCookies(2) + "; " + genCookies(2));
+  });
+
+  bench("10 cookies", () => {
+    cookie.parse(genCookies(10));
+  });
+
+  bench("100 cookies", () => {
+    cookie.parse(genCookies(100));
+  });
+});
+
+describe("parse top-sites", () => {
+  Object.entries(top).forEach(function ([domain, value]) {
+    bench("parse " + domain, () => {
+      cookie.parse(value);
+    });
+  });
+});
+
+function genCookies(num: number) {
+  let str = "";
+
+  for (let i = 0; i < num; i++) {
+    str += "; foo" + i + "=bar";
+  }
+
+  return str.slice(2);
+}

benchmark/parse-top.js

@@ -0,0 +1,96 @@
+import { describe, it, expect } from "vitest";
+import * as cookie from "./index.js";
+
+describe("cookie.parse(str)", function () {
+  it("should parse cookie string to object", function () {
+    expect(cookie.parse("foo=bar")).toEqual({ foo: "bar" });
+    expect(cookie.parse("foo=123")).toEqual({ foo: "123" });
+  });
+
+  it("should ignore OWS", function () {
+    expect(cookie.parse("FOO    = bar;   baz  =   raz")).toEqual({
+      FOO: "bar",
+      baz: "raz",
+    });
+  });
+
+  it("should parse cookie with empty value", function () {
+    expect(cookie.parse("foo=; bar=")).toEqual({ foo: "", bar: "" });
+  });
+
+  it("should parse cookie with minimum length", function () {
+    expect(cookie.parse("f=")).toEqual({ f: "" });
+    expect(cookie.parse("f=;b=")).toEqual({ f: "", b: "" });
+  });
+
+  it("should URL-decode values", function () {
+    expect(cookie.parse('foo="bar=123456789&name=Magic+Mouse"')).toEqual({
+      foo: "bar=123456789&name=Magic+Mouse",
+    });
+
+    expect(cookie.parse("email=%20%22%2c%3b%2f")).toEqual({ email: ' ",;/' });
+  });
+
+  it("should parse quoted values", function () {
+    expect(cookie.parse('foo="bar"')).toEqual({ foo: "bar" });
+    expect(cookie.parse('foo=" a b c "')).toEqual({ foo: " a b c " });
+  });
+
+  it("should trim whitespace around key and value", function () {
+    expect(cookie.parse('  foo  =  "bar"  ')).toEqual({ foo: "bar" });
+    expect(cookie.parse("  foo  =  bar  ;  fizz  =  buzz  ")).toEqual({
+      foo: "bar",
+      fizz: "buzz",
+    });
+    expect(cookie.parse(' foo = " a b c " ')).toEqual({ foo: " a b c " });
+    expect(cookie.parse(" = bar ")).toEqual({ "": "bar" });
+    expect(cookie.parse(" foo = ")).toEqual({ foo: "" });
+    expect(cookie.parse("   =   ")).toEqual({ "": "" });
+    expect(cookie.parse("\tfoo\t=\tbar\t")).toEqual({ foo: "bar" });
+  });
+
+  it("should return original value on escape error", function () {
+    expect(cookie.parse("foo=%1;bar=bar")).toEqual({ foo: "%1", bar: "bar" });
+  });
+
+  it("should ignore cookies without value", function () {
+    expect(cookie.parse("foo=bar;fizz  ;  buzz")).toEqual({ foo: "bar" });
+    expect(cookie.parse("  fizz; foo=  bar")).toEqual({ foo: "bar" });
+  });
+
+  it("should ignore duplicate cookies", function () {
+    expect(cookie.parse("foo=%1;bar=bar;foo=boo")).toEqual({
+      foo: "%1",
+      bar: "bar",
+    });
+    expect(cookie.parse("foo=false;bar=bar;foo=true")).toEqual({
+      foo: "false",
+      bar: "bar",
+    });
+    expect(cookie.parse("foo=;bar=bar;foo=boo")).toEqual({
+      foo: "",
+      bar: "bar",
+    });
+  });
+
+  it("should parse native properties", function () {
+    expect(cookie.parse("toString=foo;valueOf=bar")).toEqual({
+      toString: "foo",
+      valueOf: "bar",
+    });
+  });
+});
+
+describe("cookie.parse(str, options)", function () {
+  describe('with "decode" option', function () {
+    it("should specify alternative value decoder", function () {
+      expect(
+        cookie.parse('foo="YmFy"', {
+          decode: function (v) {
+            return Buffer.from(v, "base64").toString();
+          },
+        }),
+      ).toEqual({ foo: "bar" });
+    });
+  });
+});

benchmark/parse.js

@@ -0,0 +1,338 @@
+import { describe, it, expect } from "vitest";
+import * as cookie from "./index.js";
+
+describe("cookie.serialize(name, value)", function () {
+  it("should serialize name and value", function () {
+    expect(cookie.serialize("foo", "bar")).toEqual("foo=bar");
+  });
+
+  it("should URL-encode value", function () {
+    expect(cookie.serialize("foo", "bar +baz")).toEqual("foo=bar%20%2Bbaz");
+  });
+
+  it("should serialize empty value", function () {
+    expect(cookie.serialize("foo", "")).toEqual("foo=");
+  });
+
+  it("should serialize valid name", function () {
+    var validNames = [
+      "foo",
+      "foo!bar",
+      "foo#bar",
+      "foo$bar",
+      "foo'bar",
+      "foo*bar",
+      "foo+bar",
+      "foo-bar",
+      "foo.bar",
+      "foo^bar",
+      "foo_bar",
+      "foo`bar",
+      "foo|bar",
+      "foo~bar",
+      "foo7bar",
+    ];
+
+    validNames.forEach(function (name) {
+      expect(cookie.serialize(name, "baz")).toEqual(name + "=baz");
+    });
+  });
+
+  it("should throw for invalid name", function () {
+    var invalidNames = [
+      "foo\n",
+      "foo\u280a",
+      "foo/foo",
+      "foo,foo",
+      "foo;foo",
+      "foo@foo",
+      "foo[foo]",
+      "foo?foo",
+      "foo:foo",
+      "foo{foo}",
+      "foo foo",
+      "foo\tfoo",
+      'foo"foo',
+      "foo<script>foo",
+    ];
+
+    invalidNames.forEach(function (name) {
+      expect(cookie.serialize.bind(cookie, name, "bar")).toThrow(
+        /argument name is invalid/,
+      );
+    });
+  });
+});
+
+describe("cookie.serialize(name, value, options)", function () {
+  describe('with "domain" option', function () {
+    it("should serialize valid domain", function () {
+      var validDomains = [
+        "example.com",
+        "sub.example.com",
+        ".example.com",
+        "localhost",
+        ".localhost",
+        "my-site.org",
+        "localhost",
+      ];
+
+      validDomains.forEach(function (domain) {
+        expect(cookie.serialize("foo", "bar", { domain: domain })).toEqual(
+          "foo=bar; Domain=" + domain,
+        );
+      });
+    });
+
+    it("should throw for invalid domain", function () {
+      var invalidDomains = [
+        "example.com\n",
+        "sub.example.com\u0000",
+        "my site.org",
+        "domain..com",
+        "example.com; Path=/",
+        "example.com /* inject a comment */",
+      ];
+
+      invalidDomains.forEach(function (domain) {
+        expect(
+          cookie.serialize.bind(cookie, "foo", "bar", { domain: domain }),
+        ).toThrow(/option domain is invalid/);
+      });
+    });
+  });
+
+  describe('with "encode" option', function () {
+    it("should specify alternative value encoder", function () {
+      expect(
+        cookie.serialize("foo", "bar", {
+          encode: function (v) {
+            return Buffer.from(v, "utf8").toString("base64");
+          },
+        }),
+      ).toEqual("foo=YmFy");
+    });
+
+    it("should throw when returned value is invalid", function () {
+      expect(
+        cookie.serialize.bind(cookie, "foo", "+ \n", {
+          encode: function (v) {
+            return v;
+          },
+        }),
+      ).toThrow(/argument val is invalid/);
+      expect(
+        cookie.serialize.bind(cookie, "foo", "foo bar", {
+          encode: function (v) {
+            return v;
+          },
+        }),
+      ).toThrow(/argument val is invalid/);
+    });
+  });
+
+  describe('with "expires" option', function () {
+    it("should throw on invalid date", function () {
+      expect(
+        cookie.serialize.bind(cookie, "foo", "bar", { expires: new Date(NaN) }),
+      ).toThrow(/option expires is invalid/);
+    });
+
+    it("should set expires to given date", function () {
+      expect(
+        cookie.serialize("foo", "bar", {
+          expires: new Date(Date.UTC(2000, 11, 24, 10, 30, 59, 900)),
+        }),
+      ).toEqual("foo=bar; Expires=Sun, 24 Dec 2000 10:30:59 GMT");
+    });
+  });
+
+  describe('with "httpOnly" option', function () {
+    it("should include httpOnly flag when true", function () {
+      expect(cookie.serialize("foo", "bar", { httpOnly: true })).toEqual(
+        "foo=bar; HttpOnly",
+      );
+    });
+
+    it("should not include httpOnly flag when false", function () {
+      expect(cookie.serialize("foo", "bar", { httpOnly: false })).toEqual(
+        "foo=bar",
+      );
+    });
+  });
+
+  describe('with "maxAge" option', function () {
+    it("should throw when not a number", function () {
+      expect(function () {
+        cookie.serialize("foo", "bar", { maxAge: "buzz" as any });
+      }).toThrow(/option maxAge is invalid/);
+    });
+
+    it("should throw when Infinity", function () {
+      expect(function () {
+        cookie.serialize("foo", "bar", { maxAge: Infinity });
+      }).toThrow(/option maxAge is invalid/);
+    });
+
+    it("should throw when max-age is not an integer", function () {
+      expect(function () {
+        cookie.serialize("foo", "bar", { maxAge: 3.14 });
+      }).toThrow(/option maxAge is invalid/);
+    });
+
+    it("should set max-age to value", function () {
+      expect(cookie.serialize("foo", "bar", { maxAge: 1000 })).toEqual(
+        "foo=bar; Max-Age=1000",
+      );
+      expect(cookie.serialize("foo", "bar", { maxAge: 0 })).toEqual(
+        "foo=bar; Max-Age=0",
+      );
+    });
+
+    it("should not set when undefined", function () {
+      expect(cookie.serialize("foo", "bar", { maxAge: undefined })).toEqual(
+        "foo=bar",
+      );
+    });
+  });
+
+  describe('with "partitioned" option', function () {
+    it("should include partitioned flag when true", function () {
+      expect(cookie.serialize("foo", "bar", { partitioned: true })).toEqual(
+        "foo=bar; Partitioned",
+      );
+    });
+
+    it("should not include partitioned flag when false", function () {
+      expect(cookie.serialize("foo", "bar", { partitioned: false })).toEqual(
+        "foo=bar",
+      );
+    });
+
+    it("should not include partitioned flag when not defined", function () {
+      expect(cookie.serialize("foo", "bar", {})).toEqual("foo=bar");
+    });
+  });
+
+  describe('with "path" option', function () {
+    it("should serialize path", function () {
+      var validPaths = [
+        "/",
+        "/login",
+        "/foo.bar/baz",
+        "/foo-bar",
+        "/foo=bar?baz",
+        '/foo"bar"',
+        "/../foo/bar",
+        "../foo/",
+        "./",
+      ];
+
+      validPaths.forEach(function (path) {
+        expect(cookie.serialize("foo", "bar", { path: path })).toEqual(
+          "foo=bar; Path=" + path,
+        );
+      });
+    });
+
+    it("should throw for invalid value", function () {
+      var invalidPaths = [
+        "/\n",
+        "/foo\u0000",
+        "/path/with\rnewline",
+        "/; Path=/sensitive-data",
+        '/login"><script>alert(1)</script>',
+      ];
+
+      invalidPaths.forEach(function (path) {
+        expect(
+          cookie.serialize.bind(cookie, "foo", "bar", { path: path }),
+        ).toThrow(/option path is invalid/);
+      });
+    });
+  });
+
+  describe('with "priority" option', function () {
+    it("should throw on invalid priority", function () {
+      expect(function () {
+        cookie.serialize("foo", "bar", { priority: "foo" as any });
+      }).toThrow(/option priority is invalid/);
+    });
+
+    it("should throw on non-string", function () {
+      expect(function () {
+        cookie.serialize("foo", "bar", { priority: 42 as any });
+      }).toThrow(/option priority is invalid/);
+    });
+
+    it("should set priority low", function () {
+      expect(cookie.serialize("foo", "bar", { priority: "low" })).toEqual(
+        "foo=bar; Priority=Low",
+      );
+    });
+
+    it("should set priority medium", function () {
+      expect(cookie.serialize("foo", "bar", { priority: "medium" })).toEqual(
+        "foo=bar; Priority=Medium",
+      );
+    });
+
+    it("should set priority high", function () {
+      expect(cookie.serialize("foo", "bar", { priority: "high" })).toEqual(
+        "foo=bar; Priority=High",
+      );
+    });
+  });
+
+  describe('with "sameSite" option', function () {
+    it("should throw on invalid sameSite", function () {
+      expect(() => {
+        cookie.serialize("foo", "bar", { sameSite: "foo" as any });
+      }).toThrow(/option sameSite is invalid/);
+    });
+
+    it("should set sameSite strict", function () {
+      expect(cookie.serialize("foo", "bar", { sameSite: "strict" })).toEqual(
+        "foo=bar; SameSite=Strict",
+      );
+    });
+
+    it("should set sameSite lax", function () {
+      expect(cookie.serialize("foo", "bar", { sameSite: "lax" })).toEqual(
+        "foo=bar; SameSite=Lax",
+      );
+    });
+
+    it("should set sameSite none", function () {
+      expect(cookie.serialize("foo", "bar", { sameSite: "none" })).toEqual(
+        "foo=bar; SameSite=None",
+      );
+    });
+
+    it("should set sameSite strict when true", function () {
+      expect(cookie.serialize("foo", "bar", { sameSite: true })).toEqual(
+        "foo=bar; SameSite=Strict",
+      );
+    });
+
+    it("should not set sameSite when false", function () {
+      expect(cookie.serialize("foo", "bar", { sameSite: false })).toEqual(
+        "foo=bar",
+      );
+    });
+  });
+
+  describe('with "secure" option', function () {
+    it("should include secure flag when true", function () {
+      expect(cookie.serialize("foo", "bar", { secure: true })).toEqual(
+        "foo=bar; Secure",
+      );
+    });
+
+    it("should not include secure flag when false", function () {
+      expect(cookie.serialize("foo", "bar", { secure: false })).toEqual(
+        "foo=bar",
+      );
+    });
+  });
+});

index.js

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": ["src/**/*.spec.ts", "src/**/*.bench.ts"]
+}

package-lock.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@borderless/ts-scripts/configs/tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"]
+}