@jsenv/core 30.3.8 → 30.4.0

package/src/dev/file_service.js

@@ -35,6 +35,7 @@ export const createFileService = ({
   clientMainFileUrl,
   cooldownBetweenFileEvents,
   explorer,
+  cacheControl,
   ribbon,
   sourcemaps,
   sourcemapsSourcesProtocol,
@@ -145,6 +146,7 @@ export const createFileService = ({
           clientFileChangeCallbackList,
           clientFilesPruneCallbackList,
           explorer,
+          cacheControl,
           ribbon,
         }),
       ],
@@ -173,18 +175,25 @@ export const createFileService = ({
           // when file is modified
           return false
         }
-        if (!watch) {
+        if (!watch && urlInfo.contentEtag) {
+          // file is not watched, check the filesystem
           let fileContentAsBuffer
           try {
             fileContentAsBuffer = readFileSync(new URL(urlInfo.url))
           } catch (e) {
             if (e.code === "ENOENT") {
+              // we should consider calling urlGraph.deleteUrlInfo(urlInfo)
+              urlInfo.originalContentEtag = undefined
+              urlInfo.contentEtag = undefined
               return false
             }
             return false
           }
           const fileContentEtag = bufferToEtag(fileContentAsBuffer)
           if (fileContentEtag !== urlInfo.originalContentEtag) {
+            // we should consider calling urlGraph.considerModified(urlInfo)
+            urlInfo.originalContentEtag = undefined
+            urlInfo.contentEtag = undefined
             return false
           }
         }

package/src/dev/readme.md

@@ -0,0 +1,13 @@
+# dev/
+
+Code implementing jsenv dev server can be found here.
+
+# Description
+
+Jsenv dev server is a file server injecting code into HTML to autoreload when a file is saved.
+
+It uses a plugin pattern allowing to control dev server behaviour
+
+- Plugins can be used to transform file content before serving them; And many more things
+- Some plugins are internal to jsenv and can be configured through parameters
+- Some plugins are published in their own packages and can be passed via startDevServer "plugins" parameter

package/src/dev/start_dev_server.js

@@ -72,6 +72,7 @@ export const startDevServer = async ({
   fileSystemMagicRedirection,
   transpilation,
   explorer = true, // see jsenv_plugin_explorer.js
+  cacheControl = true,
   ribbon = true,
   // toolbar = false,
 
@@ -209,6 +210,7 @@ export const startDevServer = async ({
           clientMainFileUrl,
           cooldownBetweenFileEvents,
           explorer,
+          cacheControl,
           ribbon,
           sourcemaps,
           sourcemapsSourcesProtocol,

package/src/execute/execute.js

@@ -1,3 +1,15 @@
+/*
+ * Export a function capable to execute a file on a runtime (browser or node) and return how it goes.
+ *
+ * - can be useful to execute a file in a browser/node.js programmatically
+ * - not documented
+ * - the most importants parts:
+ *   - fileRelativeUrl: the file to execute inside rootDirectoryUrl
+ *   - runtime: an object with a "run" method.
+ *   The run method will start a browser/node process and execute file in it
+ * - Most of the logic lives in "./run.js" used by executeTestPlan to run tests
+ */
+
 import { Abort, raceProcessTeardownEvents } from "@jsenv/abort"
 import { assertAndNormalizeDirectoryUrl } from "@jsenv/filesystem"
 import { createLogger } from "@jsenv/log"
@@ -51,13 +63,13 @@ export const execute = async ({
   if (runtime.type === "browser") {
     if (!devServerOrigin) {
       throw new TypeError(
-        `devServerOrigin is required when running tests on browser(s)`,
+        `devServerOrigin is required to execute file on a browser`,
       )
     }
     const devServerStarted = await pingServer(devServerOrigin)
     if (!devServerStarted) {
       throw new Error(
-        `dev server not started at ${devServerOrigin}. It is required to run tests`,
+        `no server listening at ${devServerOrigin}. It is required to execute file`,
       )
     }
   }

package/src/execute/run.js

@@ -1,3 +1,15 @@
+/*
+ * Export a function capable to run a file on a runtime.
+ *
+ * - Used internally by "executeTestPlan" part of the documented API
+ * - Used internally by "execute" an advanced API not documented
+ * - logs generated during file execution can be collected
+ * - logs generated during file execution can be mirrored (re-logged to the console)
+ * - File is given allocatedMs to complete
+ * - Errors are collected
+ * - File execution result is returned, it contains status/errors/namespace/consoleCalls
+ */
+
 import { createId } from "@paralleldrive/cuid2"
 import { Abort, raceCallbacks } from "@jsenv/abort"
 import { ensureParentDirectories } from "@jsenv/filesystem"

package/src/execute/runtimes/browsers/chromium.js

@@ -2,7 +2,9 @@ import { createRuntimeFromPlaywright } from "./from_playwright.js"
 
 export const chromium = createRuntimeFromPlaywright({
   browserName: "chromium",
-  browserVersion: "110.0.5481.38", // to update, check https://github.com/microsoft/playwright/releases
+  // browserVersion will be set by "browser._initializer.version"
+  // see also https://github.com/microsoft/playwright/releases
+  browserVersion: "unset",
   coveragePlaywrightAPIAvailable: true,
 })
 export const chromiumIsolatedTab = chromium.isolatedTab

package/src/execute/runtimes/browsers/firefox.js

@@ -2,6 +2,8 @@ import { createRuntimeFromPlaywright } from "./from_playwright.js"
 
 export const firefox = createRuntimeFromPlaywright({
   browserName: "firefox",
-  browserVersion: "108.0.2", // to update, check https://github.com/microsoft/playwright/releases
+  // browserVersion will be set by "browser._initializer.version"
+  // see also https://github.com/microsoft/playwright/releases
+  browserVersion: "unset",
 })
 export const firefoxIsolatedTab = firefox.isolatedTab

package/src/execute/runtimes/browsers/from_playwright.js

@@ -46,8 +46,8 @@ export const createRuntimeFromPlaywright = ({
     keepRunning,
     onConsole,
 
-    executablePath,
     headful = keepRunning,
+    playwrightLaunchOptions = {},
     ignoreHTTPSErrors = true,
   }) => {
     const cleanupCallbackList = createCallbackListNotifiedOnce()
@@ -62,11 +62,14 @@ export const createRuntimeFromPlaywright = ({
           signal,
           browserName,
           stopOnExit: true,
-          playwrightOptions: {
+          playwrightLaunchOptions: {
+            ...playwrightLaunchOptions,
             headless: !headful,
-            executablePath,
           },
         })
+        if (browser._initializer.version) {
+          runtime.version = browser._initializer.version
+        }
         const browserContext = await browser.newContext({ ignoreHTTPSErrors })
         return { browser, browserContext }
       })()
@@ -409,7 +412,7 @@ const launchBrowserUsingPlaywright = async ({
   signal,
   browserName,
   stopOnExit,
-  playwrightOptions,
+  playwrightLaunchOptions,
 }) => {
   const launchBrowserOperation = Abort.startOperation()
   launchBrowserOperation.addAbortSignal(signal)
@@ -431,7 +434,7 @@ const launchBrowserUsingPlaywright = async ({
   const browserClass = playwright[browserName]
   try {
     const browser = await browserClass.launch({
-      ...playwrightOptions,
+      ...playwrightLaunchOptions,
       // let's handle them to close properly browser + remove listener
       // instead of relying on playwright to do so
       handleSIGINT: false,

package/src/execute/runtimes/browsers/webkit.js

@@ -2,7 +2,9 @@ import { createRuntimeFromPlaywright } from "./from_playwright.js"
 
 export const webkit = createRuntimeFromPlaywright({
   browserName: "webkit",
-  browserVersion: "16.4", // to update, check https://github.com/microsoft/playwright/releases
+  // browserVersion will be set by "browser._initializer.version"
+  // see also https://github.com/microsoft/playwright/releases
+  browserVersion: "unset",
   ignoreErrorHook: (error) => {
     // we catch error during execution but safari throw unhandled rejection
     // in a non-deterministic way.

package/src/execute/runtimes/readme.md

@@ -0,0 +1,13 @@
+# runtimes/
+
+Code implementing runtimes can be found here.
+
+# Description
+
+A runtime is an object with a "run" method.
+The run method is roughly doing the following:
+
+1. spawn a runtime (browser,Node.js)
+2. set various listeners to monitor file execution
+3. execute the file
+4. return info about file execution (logs and errors for instance)

package/src/kitchen/kitchen.js

@@ -356,7 +356,7 @@ ${ANSI.color(normalizedReturnValue, ANSI.YELLOW)}
         type,
         subtype,
         originalUrl,
-        originalContent,
+        originalContent = content,
         sourcemap,
         filename,
 
@@ -381,8 +381,13 @@ ${ANSI.color(normalizedReturnValue, ANSI.YELLOW)}
       urlInfo.subtype = subtype || reference.expectedSubtype || ""
       // during build urls info are reused and load returns originalUrl/originalContent
       urlInfo.originalUrl = originalUrl || urlInfo.originalUrl
-      urlInfo.originalContent =
-        originalContent === undefined ? content : originalContent
+      if (originalContent !== urlInfo.originalContent) {
+        urlInfo.originalContentEtag = undefined // set by "initTransformations"
+      }
+      if (content !== urlInfo.content) {
+        urlInfo.contentEtag = undefined // set by "applyFinalTransformations"
+      }
+      urlInfo.originalContent = originalContent
       urlInfo.content = content
       urlInfo.sourcemap = sourcemap
       if (data) {

package/src/kitchen/readme.md

@@ -0,0 +1,8 @@
+# kitchen/
+
+Code implementing jsenv kitchen can be found here.
+
+# Description
+
+Jsenv kitchen is an abstraction representing the place where files content is transformed to obtain something.
+Jsenv dev server and build go through the kitchen to transform file content.

package/src/kitchen/url_graph.js

@@ -37,12 +37,30 @@ export const createUrlGraph = () => {
     if (!parentUrlInfo) {
       return null
     }
-    const firstReferenceOnThatUrl = parentUrlInfo.references.find(
-      (reference) => {
+    const seen = []
+    const search = (urlInfo) => {
+      const firstReferenceFound = urlInfo.references.find((reference) => {
         return urlSpecifierEncoding.decode(reference) === specifier
-      },
-    )
-    return firstReferenceOnThatUrl
+      })
+      if (firstReferenceFound) {
+        return firstReferenceFound
+      }
+      for (const dependencyUrl of parentUrlInfo.dependencies) {
+        if (seen.includes(dependencyUrl)) {
+          continue
+        }
+        seen.push(dependencyUrl)
+        const dependencyUrlInfo = getUrlInfo(dependencyUrl)
+        if (dependencyUrlInfo.isInline) {
+          const firstRef = search(dependencyUrlInfo)
+          if (firstRef) {
+            return firstRef
+          }
+        }
+      }
+      return null
+    }
+    return search(parentUrlInfo)
   }
   const findDependent = (urlInfo, visitor) => {
     const seen = [urlInfo.url]

package/src/plugins/cache_control/jsenv_plugin_cache_control.js

@@ -1,15 +1,19 @@
-export const jsenvPluginCacheControl = () => {
+export const jsenvPluginCacheControl = ({
+  versionedUrls = true,
+  maxAge = SECONDS_IN_30_DAYS,
+}) => {
   return {
     name: "jsenv:cache_control",
     appliesDuring: "dev",
     augmentResponse: ({ reference }) => {
       if (
+        versionedUrls &&
         reference.searchParams.has("v") &&
         !reference.searchParams.has("hmr")
       ) {
         return {
           headers: {
-            "cache-control": `private,max-age=${SECONDS_IN_30_DAYS},immutable`,
+            "cache-control": `private,max-age=${maxAge},immutable`,
           },
         }
       }

package/src/plugins/plugins.js

@@ -38,11 +38,15 @@ export const getCorePlugins = ({
   clientFileChangeCallbackList,
   clientFilesPruneCallbackList,
   explorer,
+  cacheControl,
   ribbon = true,
 } = {}) => {
   if (explorer === true) {
     explorer = {}
   }
+  if (cacheControl === true) {
+    cacheControl = {}
+  }
   if (supervisor === true) {
     supervisor = {}
   }
@@ -59,6 +63,7 @@ export const getCorePlugins = ({
   } else {
     clientMainFileUrl = String(clientMainFileUrl)
   }
+
   if (ribbon === true) {
     ribbon = {}
   }
@@ -97,7 +102,7 @@ export const getCorePlugins = ({
           }),
         ]
       : []),
-    jsenvPluginCacheControl(),
+    ...(cacheControl ? [jsenvPluginCacheControl(cacheControl)] : []),
     ...(explorer
       ? [jsenvPluginExplorer({ ...explorer, clientMainFileUrl })]
       : []),

package/src/plugins/readme.md

@@ -0,0 +1,18 @@
+# plugins/
+
+Code implementing jsenv internal plugins can be found here.
+
+# Description
+
+These plugins can be configured using parameters of "startDevServer" and "build" functions.
+
+A few examples of plugins that can be found here:
+
+- inject code to autoreload during dev
+- apply node module resolution on js imports
+
+They are here and not inside a separate NPM package because:
+
+1. they are considered useful enough to be available by default
+2. putting them into a separate package would force people to enable a bunch of plugins
+   to obtain what they want instead of having sensible defaults

package/src/plugins/server_events/client/server_events_client.js

@@ -1,5 +1,3 @@
-/* globals self */
-
 import { createWebSocketConnection } from "./web_socket_connection.js"
 
 const websocketScheme = self.location.protocol === "https:" ? "wss" : "ws"

package/src/plugins/transpilation/as_js_classic/client/s.js

@@ -12,7 +12,6 @@
 
 ;(function () {
   /* eslint-env browser */
-  /* globals self */
 
   const loadRegistry = Object.create(null)
   const registerRegistry = Object.create(null)

package/src/test/execute_plan.js

@@ -326,6 +326,7 @@ export const executePlan = async (
 
         const afterExecutionInfo = {
           ...beforeExecutionInfo,
+          runtimeVersion: runtime.version,
           endMs: Date.now(),
           executionResult,
         }

package/src/test/readme.md

@@ -0,0 +1,3 @@
+# test/
+
+Code implementing "executeTestPlan" can be found here