clarify docs and add changelog

CHANGELOG.md

@@ -0,0 +1,125 @@
+
+
+## [2.7.0] - 2024-08-01
+* Added support for `partitioned` attribute
+
+Docs:
+* Added changelog
+
+## [2.6.0] - 2023-05-18
+* Add support for getSetCookie() method on fetch response headers objects.
+
+### [2.5.1] - 2024-07-25
+* Change name-value-pair parsing to follow 6265bis
+  * When there's no `=` in the "name=value" part, now the name is '' and the value is the entire string. Previously it was the other way around.
+
+
+## [2.5.0] - 2022-06-04
+* Add `"sideEffects": false` to `package.json` to help bundlers like Webpack and Rollup
+
+## [2.4.8] - 2021-02-26
+* Revert to ES5
+
+## [2.4.7] - 2021-01-16
+* Handle cases where `decodeURIComponent()` throws when decoding a value by logging an error and returning the original value
+* Switch to ES6
+
+## [2.4.6] - 2020-05-30
+* Return an empty object rather than an empty array for falsy input when `options.map` is enabled
+
+## [2.4.5] - 2020-04-04
+* Document new silent option
+* No functional changes
+
+## [2.4.4] - 2020-04-04
+*  Log a warning if the library appears to have been used incorrectly on a request rather than on a response.
+   * New `silent` option to suppress this behavior
+
+## [2.4.3] - 2020-01-29
+* Fix `parseString` export, add default options
+
+## [2.4.2] - 2020-01-29
+* Documentation improvements
+* No functional changes
+
+## [2.4.1] - 2019-12-13
+* Documentation improvements
+* No functional changes
+
+## [2.4.0] - 2019-08-15
+* Documented `parse`, `parseString`, & `splitCookiesString` methods
+* Attempted but failed to export `parseString` method
+* No functional changes
+
+## [2.3.8] - 2019-07-15
+* Drop testing on node < 8 due to ESLint
+* No functional changes
+
+## [2.3.7] - 2019-07-15 (unpublished)
+* Development dependency bump
+* No functional changes
+
+## [2.3.6] - 2019-07-15 (unpublished)
+* Support arbitrary capitalization of `Set-Cookie` header name for non-node.js environments
+
+## [2.3.5] - 2019-01-29
+* Clarify documentation of `map` option
+* No functional changes
+
+## [2.3.4] - 2019-01-28 (unpublished)
+* Fixed automated publishing to npm
+* No functional changes
+
+## [2.3.3] - 2019-01-28 (unpublished)
+* No functional changes
+
+## [2.3.2] - 2019-01-28 (unpublished)
+* No functional changes
+
+## [2.3.1] - 2019-01-28 (unpublished)
+* No functional changes
+
+## [2.3.0] - 2018-11-12 (unpublished)
+
+* New `map` option to return an Object with cookies keyed by name rather than an array of cookies
+
+## [2.2.1] - 2018-07-10
+* Revert to ES5
+
+## [2.2.0] - 2018-07-08
+* Add `splitCookiesString` to separate multiple comma-separated Set-Cookie headers
+* Changed code from ES5 to ES6
+
+## [2.1.2] - 2018-05-26
+
+Docs
+* Fixed a broken link
+
+## [2.1.1] - 2018-02-26
+
+* Updated automated release script
+
+## [2.1.0] - 2018-02-26
+
+Added
+
+* Support for `SameSite` attribute
+
+##  [2.0.0] - 2016-12-13
+* Added decodeValues option (calls `decodeURIComponent()` on each cookie value), enabled by default.
+* Added `splitCookiesString` method.
+
+## [1.0.2] - 2016-02-08
+
+Docs:
+
+* Update badges and keywords
+
+## [1.0.1] - 2015-07-01
+
+Docs:
+* Added output example
+
+## [1.0.0] - 2015-07-01
+
+Initial release

README.md

@@ -22,15 +22,16 @@ Returns either an array of cookie objects or a map of name => cookie object with
 
 * `name` - cookie name (string)
 * `value` - cookie value (string)
-* `path` - cookie path (string or undefined)
-* `domain` - domain for the cookie (string or undefined, may begin with "." to indicate the named domain or any subdomain of it)
+* `path` - URL path to limit the scope to (string or undefined)
+* `domain` - domain to expand the scope to (string or undefined, may begin with "." to indicate the named domain or any subdomain of it)
 * `expires` - absolute expiration date for the cookie (Date object or undefined)
-* `maxAge` - relative max age of the cookie in seconds from when the client receives it (integer or undefined)
+* `maxAge` - relative expiration time of the cookie in seconds from when the client receives it (integer or undefined)
   * Note: when using with [express's res.cookie() method](http://expressjs.com/en/4x/api.html#res.cookie), multiply `maxAge` by 1000 to convert to milliseconds.
-* `secure` - indicates that this cookie should only be sent over HTTPs (true or undefined)
-* `httpOnly` - indicates that this cookie should *not* be accessible to client-side JavaScript (true or undefined)
-* `sameSite` - indicates a cookie ought not to be sent along with cross-site requests (string or undefined)
-* `partitioned` - indicates that this cookie could be created in an iframe from a 3rd party domain (true or undefined)
+* `secure` - indicates cookie should only be sent over HTTPs (true or undefined)
+* `httpOnly` - indicates cookie should *not* be accessible to client-side JavaScript (true or undefined)
+* `sameSite` - indicates if cookie should be included in cross-site requests ([more info](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value)) (string or undefined)
+  * Note: valid values are `"Strict"`, `"Lax"`, and `"None"`, but set-cookie-parser coppies the value verbatim and does *not* perform any validation.
+* `partitioned` - indicates cookie should be scoped to the combination of 3rd party domain + top page domain ([more info](https://developer.mozilla.org/en-US/docs/Web/Privacy/Privacy_sandbox/Partitioned_cookies)) (true or undefined)
 
 (The output format is loosely based on the input format of https://www.npmjs.com/package/cookie)
 
@@ -181,11 +182,6 @@ It's uncommon, but the HTTP spec does allow for multiple of the same header to h
 This method splits apart a combined header without choking on commas that appear within a cookie's value (or expiration date).
 Returns an array of strings that may be passed to `parse()`.
 
-## V2 Changes
-
-* Added decodeValues option (calls `decodeURIComponent()` on each cookie value), enabled by default.
-* Added `splitCookiesString` method.
-
 ## References
 
 * [RFC 6265: HTTP State Management Mechanism](https://tools.ietf.org/html/rfc6265)