Improve attribute documentation

CHANGELOG.md

@@ -6,6 +6,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.0] - 2024-04-19
+### Added
+- Support for experimental `partitioned` cookies.
+
+### Fixed
+- Cookies now expire on the maximum date when `expires` is set to a number larger than the maximum date.
+
+### Changed
+- Improved attribute documentation.
+
 ## [1.4.0] - 2022-08-21
 ### Changed
 - Distributed as a native ES module instead of CommonJS.
@@ -43,7 +53,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [1.0.0] - 2017-02-05
 - Initial release
 
-[Unreleased]: https://github.com/theodorejb/es-cookie/compare/v1.4.0...HEAD
+[Unreleased]: https://github.com/theodorejb/es-cookie/compare/v1.5.0...HEAD
+[1.5.0]: https://github.com/theodorejb/es-cookie/compare/v1.4.0...v1.5.0
 [1.4.0]: https://github.com/theodorejb/es-cookie/compare/v1.3.2...v1.4.0
 [1.3.2]: https://github.com/theodorejb/es-cookie/compare/v1.3.1...v1.3.2
 [1.3.1]: https://github.com/theodorejb/es-cookie/compare/v1.3.0...v1.3.1

package.json

@@ -1,6 +1,6 @@
 {
   "name": "es-cookie",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "A JavaScript module for handling cookies",
   "files": [
     "src/*.js",

src/CookieAttributes.ts

@@ -1,13 +1,18 @@
-export type CookieAttributes = BaseCookieAttributes & SameSiteCookieAttributes & MaybePartitionedCookie;
+export type CookieAttributes = BaseCookie & MaybeSecureCookie & MaybeSameSiteCookie & MaybePartitionedCookie;
 
-interface BaseCookieAttributes {
+interface BaseCookie {
     /**
-     * A number will be interpreted as days from time of creation
+     * Indicates the maximum lifetime of the cookie. A number will be interpreted as days from time of creation.
+     * If unspecified, the cookie becomes a session cookie. A session finishes when the client shuts down,
+     * after which the session cookie is removed. 
      */
     expires?: Date | number;
 
     /**
-     * Hosts to which the cookie will be sent
+     * The host to which the cookie will be sent. Only the current domain can be set as the value,
+     * or a domain of a higher order, unless it is a public suffix. Setting the domain will make the
+     * cookie available to it, as well as to all its subdomains.
+     * If omitted, this attribute defaults to the host of the current document URL, not including subdomains.
      */
     domain?: string;
 
@@ -16,35 +21,63 @@ interface BaseCookieAttributes {
      * path matches (or is a subdirectory of) the cookie's path attribute.
      */
     path?: string;
+}
+
+type MaybeSecureCookie = InsecureCookie | SecureCookie;
 
+interface InsecureCookie {
     /**
-     * If enabled, the cookie will only be included in an HTTP request
-     * if it is transmitted over a secure channel (typically HTTP over TLS).
+     * If enabled, the cookie will only be sent to the server when a request is made with the https:
+     * scheme (except on localhost), and therefore, is more resistant to man-in-the-middle attacks.
      */
-    secure?: boolean;
+    secure?: false;
+}
+
+interface SecureCookie {
+    /**
+     * Indicates that the cookie is sent to the server only when a request is made with the https:
+     * scheme (except on localhost), and therefore, is more resistant to man-in-the-middle attacks.
+     */
+    secure: true;
 }
 
-type SameSiteCookieAttributes = LaxStrictSameSiteCookieAttributes | NoneSameSiteCookieAttributes;
+type MaybeSameSiteCookie = LaxOrStrictSameSiteCookie | NoneSameSiteCookie;
 
-interface LaxStrictSameSiteCookieAttributes {
+interface LaxOrStrictSameSiteCookie {
     /**
-     * Only send the cookie if the request originates from the same website the
-     * cookie is from. This provides some protection against cross-site request
-     * forgery attacks (CSRF).
+     * Controls whether or not a cookie is sent with cross-site requests,
+     * providing some protection against cross-site request forgery attacks (CSRF). 
      *
-     * The strict mode witholds the cookie from any kind of cross-site usage
-     * (including inbound links from external sites). The lax mode witholds
-     * the cookie on cross-domain subrequests (e.g. images or frames), but
-     * sends it whenever a user navigates safely from an external site (e.g.
-     * by following a link).
+     * `strict`: the browser only sends the cookie with requests originating
+     * from the same site (and same scheme) that set the cookie.
+     * 
+     * `lax`: the cookie is not sent on cross-site requests, (e.g. to load images or frames), but
+     * is sent when navigating to the origin site from an external site (e.g. when following a link).
+     * This is the default behavior if the SameSite attribute is not specified.
+     *
+     * `none`: the browser sends the cookie with both cross-site and same-site requests.
+     * The `secure` attribute must also be set when using this value.
      */
     sameSite?: 'strict' | 'lax';
 }
 
 /** Cookies with `SameSite=None` must also specify 'Secure' */
-interface NoneSameSiteCookieAttributes {
+interface NoneSameSiteCookie extends SecureCookie {
+    /**
+     * Controls whether or not a cookie is sent with cross-site requests,
+     * providing some protection against cross-site request forgery attacks (CSRF). 
+     *
+     * `strict`: the browser only sends the cookie with requests originating
+     * from the same site (and same scheme) that set the cookie.
+     * 
+     * `lax`: the cookie is not sent on cross-site requests, (e.g. to load images or frames), but
+     * is sent when navigating to the origin site from an external site (e.g. when following a link).
+     * This is the default behavior if the SameSite attribute is not specified.
+     *
+     * `none`: the browser sends the cookie with both cross-site and same-site requests.
+     * The `secure` attribute must also be set when using this value.
+     */
     sameSite: 'none';
-    secure: true;
 }
 
 type MaybePartitionedCookie = UnpartitionedCookieAttributes | PartitionedCookieAttributes;
@@ -57,10 +90,9 @@ interface UnpartitionedCookieAttributes {
 }
 
 /** Cookies with `Partitioned` must also specify 'Secure' */
-interface PartitionedCookieAttributes {
+interface PartitionedCookieAttributes extends SecureCookie {
     /**
      * Indicates that the cookie should be stored using partitioned storage.
      */
     partitioned: true;
-    secure: true;
 }