Request for comments / direction: Add types into repo and type checking without converting to typescript

.editorconfig

@@ -6,6 +6,6 @@ charset = utf-8
 insert_final_newline = true
 trim_trailing_whitespace = true
 
-[{*.js,*.json,*.yml}]
+[{*.js,*.ts,*.json,*.yml}]
 indent_size = 2
 indent_style = space

index.js

@@ -22,9 +22,9 @@ var parseUrl = require('parseurl');
 var signature = require('cookie-signature')
 var uid = require('uid-safe').sync
 
-var Cookie = require('./session/cookie')
+const { Cookie } = require('./session/cookie')
 var MemoryStore = require('./session/memory')
-var Session = require('./session/session')
+const { Session } = require('./session/session')
 var Store = require('./session/store')
 
 // environment

package.json

@@ -19,14 +19,24 @@
     "uid-safe": "~2.1.5"
   },
   "devDependencies": {
+    "@types/cookie": "^0.6.0",
+    "@types/cookie-signature": "^1.0.7",
+    "@types/debug": "^4.1.12",
+    "@types/depd": "^1.1.37",
+    "@types/express": "^5.0.0",
+    "@types/node": "^18.19.80",
+    "@types/on-headers": "~1.0.2",
+    "@types/parseurl": "~1.3.3",
+    "@types/uid-safe": "~2.1.5",
     "after": "0.8.2",
     "cookie-parser": "1.4.6",
     "eslint": "8.56.0",
     "eslint-plugin-markdown": "3.0.1",
     "express": "4.17.3",
     "mocha": "10.2.0",
     "nyc": "15.1.0",
-    "supertest": "6.3.4"
+    "supertest": "6.3.4",
+    "typescript": "5.8.2"
   },
   "files": [
     "session/",
@@ -38,6 +48,7 @@
   },
   "scripts": {
     "lint": "eslint . && node ./scripts/lint-readme.js",
+    "check-types": "tsc --project ./tsconfig.json",
     "test": "./test/support/gencert.sh && mocha --require test/support/env --check-leaks --no-exit --reporter spec test/",
     "test-ci": "nyc --reporter=lcov --reporter=text npm test",
     "test-cov": "nyc npm test",

session/cookie.js

@@ -11,73 +11,95 @@
  * Module dependencies.
  */
 
-var cookie = require('cookie')
-var deprecate = require('depd')('express-session')
+const cookie = require('cookie')
+const deprecate = require('depd')('express-session')
 
 /**
- * Initialize a new `Cookie` with the given `options`.
- *
- * @param {IncomingMessage} req
- * @param {Object} options
- * @api private
+ * @import { CookieOptions } from "./cookie.types"
  */
 
-var Cookie = module.exports = function Cookie(options) {
-  this.path = '/';
-  this.maxAge = null;
-  this.httpOnly = true;
+/**
+ * @implements {CookieOptions}
+ */
+class Cookie {
+  /** @private @type {Date | undefined} */
+  _expires;
+  /** @type {number | undefined} - Returns the original `maxAge` (time-to-live), in milliseconds, of the session cookie. */
+  originalMaxAge;
+  /** @type {CookieOptions['signed']} */
+  signed;
+  /** @type {CookieOptions['httpOnly']} */
+  httpOnly;
+  /** @type {CookieOptions['path']} */
+  path;
+  /** @type {CookieOptions['domain']} */
+  domain;
+  /** @type {CookieOptions['secure']} */
+  secure;
+  /** @type {CookieOptions['sameSite']} */
+  sameSite;
 
-  if (options) {
-    if (typeof options !== 'object') {
-      throw new TypeError('argument options must be a object')
-    }
+  /**
+   * Initialize a new `Cookie` with the given `options`.
+   *
+   * @param {CookieOptions} options
+   */
+  constructor(options) {
+    this.path = '/';
+    this.maxAge = undefined;
+    this.httpOnly = true;
+
+    if (options) {
+      if (typeof options !== 'object') {
+        throw new TypeError('argument options must be a object')
+      }
 
-    for (var key in options) {
-      if (key !== 'data') {
-        this[key] = options[key]
+      /** @type {{[x: string]: any}} */
+      const thisAsObject = this
+      /** @type {{[x: string]: any}} */
+      const optionsAsObject = options
+      for (var key in optionsAsObject) {
+        if (key !== 'data') {
+          thisAsObject[key] = optionsAsObject[key]
+        }
       }
     }
-  }
 
-  if (this.originalMaxAge === undefined || this.originalMaxAge === null) {
-    this.originalMaxAge = this.maxAge
+    if (this.originalMaxAge === undefined || this.originalMaxAge === null) {
+      this.originalMaxAge = this.maxAge
+    }
   }
-};
-
-/*!
- * Prototype.
- */
-
-Cookie.prototype = {
 
   /**
    * Set expires `date`.
    *
-   * @param {Date} date
-   * @api public
+   * @param {Date | undefined} date
+   * @public
    */
 
   set expires(date) {
+    /* @type {Date | undefined} */
     this._expires = date;
+    /* @type {number | undefined} */
     this.originalMaxAge = this.maxAge;
-  },
+  }
 
   /**
    * Get expires `date`.
    *
-   * @return {Date}
-   * @api public
+   * @return {Date | undefined}
+   * @public
    */
 
   get expires() {
     return this._expires;
-  },
+  }
 
   /**
    * Set expires via max-age in `ms`.
    *
-   * @param {Number} ms
-   * @api public
+   * @param {Number | Date | undefined} ms
+   * @public
    */
 
   set maxAge(ms) {
@@ -92,26 +114,27 @@ Cookie.prototype = {
     this.expires = typeof ms === 'number'
       ? new Date(Date.now() + ms)
       : ms;
-  },
+  }
 
   /**
    * Get expires max-age in `ms`.
    *
-   * @return {Number}
-   * @api public
+   * @return {number | undefined}
+   * @public
    */
 
   get maxAge() {
     return this.expires instanceof Date
       ? this.expires.valueOf() - Date.now()
       : this.expires;
-  },
+  }
 
   /**
    * Return cookie data object.
    *
+   * @this {Cookie & CookieOptions}
    * @return {Object}
-   * @api private
+   * @public
    */
 
   get data() {
@@ -126,27 +149,33 @@ Cookie.prototype = {
       , path: this.path
       , sameSite: this.sameSite
     }
-  },
+  }
 
   /**
    * Return a serialized cookie string.
    *
-   * @return {String}
-   * @api public
+   * @param {string} name
+   * @param {string} val
+   * @return {string}
+   * @public
    */
 
-  serialize: function(name, val){
+  serialize(name, val) {
     return cookie.serialize(name, val, this.data);
-  },
+  }
 
   /**
    * Return JSON representation of this cookie.
    *
    * @return {Object}
-   * @api private
+   * @private
    */
 
-  toJSON: function(){
+  toJSON() {
     return this.data;
   }
-};
+}
+
+module.exports = {
+  Cookie,
+}

session/cookie.types.ts

@@ -0,0 +1,106 @@
+export interface CookieOptions {
+  /**
+   * Specifies the number (in milliseconds) to use when calculating the `Expires Set-Cookie` attribute.
+   * This is done by taking the current server time and adding `maxAge` milliseconds to the value to calculate an `Expires` datetime. By default, no maximum age is set.
+   *
+   * If both `expires` and `maxAge` are set in the options, then the last one defined in the object is what is used.
+   * `maxAge` should be preferred over `expires`.
+   *
+   * @see expires
+   */
+  maxAge?: number | undefined;
+
+  /**
+   * 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.
+   *
+   * **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.
+   */
+  partitioned?: boolean | undefined;
+
+  /**
+   * Specifies the `string` to be 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).
+   *
+   * **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;
+
+  signed?: boolean | undefined;
+
+  /**
+   * Specifies the `Date` object to be the value for the `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.
+   *
+   * If both `expires` and `maxAge` are set in the options, then the last one defined in the object is what is used.
+   *
+   * @deprecated The `expires` option should not be set directly; instead only use the `maxAge` option
+   * @see maxAge
+   */
+  expires?: Date | null | undefined;
+
+  /**
+   * Specifies the boolean value for the `HttpOnly Set-Cookie` attribute. When truthy, the `HttpOnly` attribute is set, otherwise it is not.
+   * By default, the `HttpOnly` attribute is 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 | undefined;
+
+  /**
+   * Specifies the value for the `Path Set-Cookie` attribute.
+   * By default, this is set to '/', which is the root path of the domain.
+   */
+  path?: string | undefined;
+
+  /**
+   * Specifies the value for the `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 the boolean value for the `Secure Set-Cookie` attribute. 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.
+   *
+   * Please note that `secure: true` is a **recommended option**.
+   * However, it requires an https-enabled website, i.e., HTTPS is necessary for secure cookies.
+   * If `secure` is set, and you access your site over HTTP, **the cookie will not be set**.
+   *
+   * The cookie.secure option can also be set to the special value `auto` to have this setting automatically match the determined security of the connection.
+   * Be careful when using this setting if the site is available both as HTTP and HTTPS, as once the cookie is set on HTTPS, it will no longer be visible over HTTP.
+   * This is useful when the Express "trust proxy" setting is properly setup to simplify development vs production configuration.
+   *
+   * If you have your node.js behind a proxy and are using `secure: true`, you need to set "trust proxy" in express. Please see the [README](https://github.com/expressjs/session) for details.
+   *
+   * Please see the [README](https://github.com/expressjs/session) for an example of using secure cookies in production, but allowing for testing in development based on NODE_ENV.
+   */
+  secure?: boolean | "auto" | undefined;
+
+  encode?: ((val: string) => string) | undefined;
+
+  /**
+   * Specifies the boolean or string to be the value for the `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.
+   * - `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.
+   *
+   * **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?: boolean | "lax" | "strict" | "none" | undefined;
+}