Migrate TypeScript to JSDoc

.node-version

@@ -0,0 +1 @@
+20.5.1

package.json

@@ -38,7 +38,6 @@
     "@open-wc/testing": "^3.1.7",
     "@playwright/test": "^1.28.0",
     "@rollup/plugin-node-resolve": "13.1.3",
-    "@rollup/plugin-typescript": "^11.0.0",
     "@types/multer": "^1.4.5",
     "@typescript-eslint/eslint-plugin": "^5.50.0",
     "@typescript-eslint/parser": "^5.50.0",
@@ -57,21 +56,22 @@
     "rollup": "^2.35.1",
     "ts-node": "^10.9.1",
     "tslib": "^2.5.0",
-    "typescript": "^4.9.5"
+    "typescript": "^5.2.2"
   },
   "scripts": {
     "clean": "rm -fr dist",
     "clean:win": "rmdir /s /q dist",
-    "build": "tsc --noEmit false --declaration true --emitDeclarationOnly true --outDir dist/types && rollup -c",
-    "build:win": "tsc --noEmit false --declaration true --emitDeclarationOnly true --outDir dist/types & rollup -c",
+    "prebuild": "yarn clean",
+    "build": "tsc src/**/*.js --allowJs --declaration true --emitDeclarationOnly true --outDir dist/types && rollup -c",
+    "build:win": "tsc src/**/*.js --allowJs --declaration true --emitDeclarationOnly true --outDir dist/types & rollup -c",
     "watch": "rollup -wc",
     "start": "ts-node -O '{\"module\":\"commonjs\"}' src/tests/server.ts",
     "test": "yarn test:unit && yarn test:browser",
     "test:browser": "playwright test",
     "test:unit": "NODE_OPTIONS=--inspect web-test-runner",
     "test:unit:win": "SET NODE_OPTIONS=--inspect & web-test-runner",
     "release": "yarn build && npm publish",
-    "lint": "eslint . --ext .ts"
+    "lint": "eslint . --ext .js"
   },
   "engines": {
     "node": ">= 14"

playwright.config.d.ts

@@ -0,0 +1,3 @@
+import { type PlaywrightTestConfig } from "@playwright/test";
+declare const config: PlaywrightTestConfig;
+export default config;

playwright.config.js

@@ -0,0 +1,28 @@
+import { devices } from "@playwright/test"
+
+const config = {
+  projects: [
+    {
+      name: "chrome",
+      use: { ...devices["Desktop Chrome"] },
+    },
+    {
+      name: "firefox",
+      use: { ...devices["Desktop Firefox"] },
+    },
+  ],
+  retries: 2,
+  testDir: "./src/tests/",
+  testMatch: /(functional|integration)\/.*_tests\.ts/,
+  webServer: {
+    command: "yarn start",
+    url: "http://localhost:9000/src/tests/fixtures/test.js",
+    timeout: 120 * 1000,
+    reuseExistingServer: !process.env.CI,
+  },
+  use: {
+    baseURL: "http://localhost:9000/",
+  },
+}
+
+export default config

rollup.config.js

@@ -1,32 +1,28 @@
 import resolve from "@rollup/plugin-node-resolve"
-import typescript from "@rollup/plugin-typescript"
 
 import { version } from "./package.json"
 const year = new Date().getFullYear()
 const banner = `/*!\nTurbo ${version}\nCopyright © ${year} 37signals LLC\n */`
 
 export default [
   {
-    input: "src/index.ts",
+    input: "src/index.js",
     output: [
       {
         name: "Turbo",
         file: "dist/turbo.es2017-umd.js",
         format: "umd",
-        banner
+        banner,
       },
       {
         file: "dist/turbo.es2017-esm.js",
         format: "es",
-        banner
-      }
-    ],
-    plugins: [
-      resolve(),
-      typescript()
+        banner,
+      },
     ],
+    plugins: [resolve()],
     watch: {
-      include: "src/**"
-    }
-  }
+      include: "src/**",
+    },
+  },
 ]

src/core/bardo.ts → src/core/bardo.js

@@ -1,30 +1,28 @@
-import { PermanentElementMap } from "./snapshot"
-
-export interface BardoDelegate {
-  enteringBardo(currentPermanentElement: Element, newPermanentElement: Element): void
-  leavingBardo(currentPermanentElement: Element): void
-}
-
 export class Bardo {
-  readonly permanentElementMap: PermanentElementMap
-  readonly delegate: BardoDelegate
+  /** @readonly */
+  permanentElementMap = undefined
+  /** @readonly */
+  delegate = undefined
 
-  static async preservingPermanentElements(
-    delegate: BardoDelegate,
-    permanentElementMap: PermanentElementMap,
-    callback: () => void
-  ) {
+  /** @static
+   * @param {BardoDelegate} delegate
+   * @param {PermanentElementMap} permanentElementMap
+   * @param {() => void} callback
+   * @returns {Promise<void>}
+   */
+  static async preservingPermanentElements(delegate, permanentElementMap, callback) {
     const bardo = new this(delegate, permanentElementMap)
     bardo.enter()
     await callback()
     bardo.leave()
   }
 
-  constructor(delegate: BardoDelegate, permanentElementMap: PermanentElementMap) {
+  constructor(delegate, permanentElementMap) {
     this.delegate = delegate
     this.permanentElementMap = permanentElementMap
   }
 
+  /** @returns {void} */
   enter() {
     for (const id in this.permanentElementMap) {
       const [currentPermanentElement, newPermanentElement] = this.permanentElementMap[id]
@@ -33,6 +31,7 @@ export class Bardo {
     }
   }
 
+  /** @returns {void} */
   leave() {
     for (const id in this.permanentElementMap) {
       const [currentPermanentElement] = this.permanentElementMap[id]
@@ -42,33 +41,50 @@ export class Bardo {
     }
   }
 
-  replaceNewPermanentElementWithPlaceholder(permanentElement: Element) {
+  /** @param {Element} permanentElement
+   * @returns {void}
+   */
+  replaceNewPermanentElementWithPlaceholder(permanentElement) {
     const placeholder = createPlaceholderForPermanentElement(permanentElement)
     permanentElement.replaceWith(placeholder)
   }
 
-  replaceCurrentPermanentElementWithClone(permanentElement: Element) {
+  /** @param {Element} permanentElement
+   * @returns {void}
+   */
+  replaceCurrentPermanentElementWithClone(permanentElement) {
     const clone = permanentElement.cloneNode(true)
     permanentElement.replaceWith(clone)
   }
 
-  replacePlaceholderWithPermanentElement(permanentElement: Element) {
+  /** @param {Element} permanentElement
+   * @returns {void}
+   */
+  replacePlaceholderWithPermanentElement(permanentElement) {
     const placeholder = this.getPlaceholderById(permanentElement.id)
     placeholder?.replaceWith(permanentElement)
   }
 
-  getPlaceholderById(id: string) {
+  /** @param {string} id
+   * @returns {HTMLMetaElement}
+   */
+  getPlaceholderById(id) {
     return this.placeholders.find((element) => element.content == id)
   }
 
-  get placeholders(): HTMLMetaElement[] {
-    return [...document.querySelectorAll<HTMLMetaElement>("meta[name=turbo-permanent-placeholder][content]")]
+  get placeholders() {
+    return [...document.querySelectorAll("meta[name=turbo-permanent-placeholder][content]")]
   }
 }
 
-function createPlaceholderForPermanentElement(permanentElement: Element) {
+/** @param {Element} permanentElement
+ * @returns {HTMLMetaElement}
+ */
+function createPlaceholderForPermanentElement(permanentElement) {
   const element = document.createElement("meta")
   element.setAttribute("name", "turbo-permanent-placeholder")
   element.setAttribute("content", permanentElement.id)
   return element
 }
+
+/** @typedef {Object} BardoDelegate */

src/core/cache.ts → src/core/cache.js

@@ -1,30 +1,38 @@
-import { Session } from "./session"
 import { setMetaContent } from "../util"
 
 export class Cache {
-  readonly session: Session
+  /** @readonly */
+  session = undefined
 
-  constructor(session: Session) {
+  constructor(session) {
     this.session = session
   }
 
+  /** @returns {void} */
   clear() {
     this.session.clearCache()
   }
 
+  /** @returns {void} */
   resetCacheControl() {
     this.setCacheControl("")
   }
 
+  /** @returns {void} */
   exemptPageFromCache() {
     this.setCacheControl("no-cache")
   }
 
+  /** @returns {void} */
   exemptPageFromPreview() {
     this.setCacheControl("no-preview")
   }
 
-  private setCacheControl(value: string) {
+  /** @private
+   * @param {string} value
+   * @returns {void}
+   */
+  setCacheControl(value) {
     setMetaContent("turbo-cache-control", value)
   }
 }

src/core/drive/error_renderer.ts → src/core/drive/error_renderer.js

@@ -1,25 +1,33 @@
-import { PageSnapshot } from "./page_snapshot"
 import { Renderer } from "../renderer"
 import { activateScriptElement } from "../../util"
 
-export class ErrorRenderer extends Renderer<HTMLBodyElement, PageSnapshot> {
-  static renderElement(currentElement: HTMLBodyElement, newElement: HTMLBodyElement) {
+/** @extends Renderer<HTMLBodyElement, PageSnapshot> */
+export class ErrorRenderer extends Renderer {
+  /** @static
+   * @param {HTMLBodyElement} currentElement
+   * @param {HTMLBodyElement} newElement
+   * @returns {void}
+   */
+  static renderElement(currentElement, newElement) {
     const { documentElement, body } = document
 
     documentElement.replaceChild(newElement, body)
   }
 
+  /** @returns {Promise<void>} */
   async render() {
     this.replaceHeadAndBody()
     this.activateScriptElements()
   }
 
+  /** @returns {void} */
   replaceHeadAndBody() {
     const { documentElement, head } = document
     documentElement.replaceChild(this.newHead, head)
     this.renderElement(this.currentElement, this.newElement)
   }
 
+  /** @returns {void} */
   activateScriptElements() {
     for (const replaceableElement of this.scriptElements) {
       const parentNode = replaceableElement.parentNode