@jsenv/core 38.2.3 → 38.2.5

package/README.md

@@ -1,9 +1,96 @@
 # @jsenv/core [![npm package](https://img.shields.io/npm/v/@jsenv/core.svg?logo=npm&label=package)](https://www.npmjs.com/package/@jsenv/core)
 
-Jsenv is a tool to develop test and build projects using JavaScript.  
-Jsenv is simple, easy to understand and well documented.
+Jsenv is a tool to develop test and build projects using JavaScript. Jsenv is simple, easy to understand and well [documented](<https://github.com/jsenv/core/wiki/A)-directory-structure>).
 
-[Documentation](<https://github.com/jsenv/core/wiki/A)-Introduction>)
+Jsenv cares a lot about the developper experience, especially when it comes to tests.
+
+The pillars of jsenv are:
+
+1. A dev server serving source files with autoreload
+2. A build generating an optimized version of source files into a directory
+3. A build server serving build files
+4. A test runner executing test files in web browser(s)
+
+# The best parts
+
+## Reduce cognitive load inside test files
+
+When coding, we spend most of our time working on source files. At some point we switch from source files to test files. Suddenly things are different:
+
+- code does not execute as it would in source files
+- some tools are used differently in test files, some cannot be used at all
+- you are forced to code in a certain way that is completely different from the one in source files
+
+This huge gap between source files and test files creates a context switching costing a lot of cognitive energy.  
+Jsenv makes a special effort to [provide a solution](<https://github.com/jsenv/core/wiki/D)-Test>) where switching from source files to test files is easy.
+
+It also means tools used on source files can be reused on test files: ESlint, VSCode debugger, etc. No need to maintain separate tools and/or configurations.
+
+## Other good parts
+
+- A [large browser support during dev](<https://github.com/jsenv/core/wiki/B)-Dev#21-browser-support>). Because some people might be happy to use an other browser than the latest chrome during dev. Moreover it is useful to reproduce bug specific to certain browsers.
+- A [large browser support after build](<https://github.com/jsenv/core/wiki/C)-Build#211-maximal-browser-support>). Because some product still needs to support old versions of Firefox, Chrome and Safari.
+- A [single set of files during build](<https://github.com/jsenv/core/wiki/C)-Build#212-same-build-for-all-browsers>). Because a single one is simpler to properly support in every aspects.
+- Versioning during build is robust and <a href="https://bundlers.tooling.report/hashing/avoid-cascade/" target="_blank">avoids cascading hash changes</a><sup>↗</sup>
+- Ability to [execute tests in multiple browsers](<https://github.com/jsenv/core/wiki/D)-Test#32-executing-on-more-browsers>): Chrome, Safari, Firefox
+- An advanced support of top level await, allowing to use it everywhere
+- An advanced support of web workers including worker type module
+- Unlock js module features on a regular `<script>` when needed. If you need the behaviour of `<script>` which is to block other `<script>` tag in the page, you'll be happy to still have the power of js modules, like imports, at your disposal.
+
+# Demos
+
+A demo is a project pre-configured with jsenv.
+
+The following command can be used to install and try a demo:
+
+```console
+npm create jsenv@latest
+```
+
+It will prompt to choose one of the available demo:
+
+```console
+? Select a demo: › - Use arrow-keys. Return to submit.
+❯   web
+    web-react
+    web-preact
+    node-package
+```
+
+Selecting "web" will copy [create-jsenv/demo-web](https://github.com/jsenv/core/tree/bc7fb0aa2c8ced1db4d7583a2ea1858be464c23b/packages/related/create-jsenv/demo-web)<sup>↗</sup> files into a directory:
+
+```console
+✔ Select a demo: › web
+✔ copy demo files into "[...]jsenv-demo-web/" (done in 0.1 second)
+----- commands to run -----
+cd jsenv-demo-web
+npm install
+npm start
+---------------------------
+```
+
+After running the suggested commands the demo is ready.
+
+> **Info**
+> "npm install" can take time because tests are runned in headless browsers that needs to be installed first.
+
+The demo contains preconfigured scripts:
+
+- `npm run dev`: starts a server for source files; Documented in [B) Dev](<https://github.com/jsenv/core/wiki/B)-Dev>).
+- `npm run build`: generate files optimized for production; Documented in [C) Build](<https://github.com/jsenv/core/wiki/C)-Build>).
+- `npm run build:serve`: start a server for build files; Documented in [C) Build#how-to-serve-build-files](<https://github.com/jsenv/core/wiki/C)-Build#3-how-to-serve-build-files>).
+- `npm run test`: execute test files on browsers(s); Documented in [D) Test](<https://github.com/jsenv/core/wiki/D)-Test>).
+
+<!--
+The following commands can be used to skip the prompt
+
+| Command                                     |
+| ------------------------------------------- |
+| `npm create jsenv@latest -- --web`          |
+| `npm create jsenv@latest -- --web-preact`   |
+| `npm create jsenv@latest -- --web-react`    |
+| `npm create jsenv@latest -- --node-package` |
+-->
 
 <!-- # Installation
 
@@ -11,5 +98,5 @@ Jsenv is simple, easy to understand and well documented.
 npm install --save-dev @jsenv/core
 ```
 
-_@jsenv/core_ is tested on Mac, Windows, Linux with Node.js 18.
+_@jsenv/core_ is tested on Mac, Windows, Linux with Node.js 20.
 Other operating systems and Node.js versions are not tested. -->

package/dist/jsenv_core.js

@@ -2509,7 +2509,9 @@ const createWatcher = (sourcePath, options) => {
           if (e.code === "ENOENT") {
             return;
           }
-          console.error(`error while fixing windows eperm: ${e.stack}`);
+          console.error(
+            `error while trying to get rid of windows EPERM: ${e.stack}`,
+          );
           throw error;
         }
       } else {
@@ -2543,7 +2545,8 @@ callback: ${callback}`);
   return { registerCleanupCallback, cleanup };
 };
 
-const fsWatchSupportsRecursive = true;
+const isLinux = process.platform === "linux";
+const fsWatchSupportsRecursive = !isLinux;
 
 const registerDirectoryLifecycle = (
   source,
@@ -2626,8 +2629,8 @@ const registerDirectoryLifecycle = (
     try {
       const relativeUrl = urlToRelativeUrl(url, source);
       const previousInfo = infoMap.get(relativeUrl);
-      const stats = statSync(new URL(url));
-      const type = statsToType(stats);
+      const stat = statSync(new URL(url));
+      const type = statsToType(stat);
       const patternValue = previousInfo
         ? previousInfo.patternValue
         : getWatchPatternValue({ url, type });
@@ -2636,13 +2639,15 @@ const registerDirectoryLifecycle = (
         url,
         relativeUrl,
         type,
-        atimeMs: stats.atimeMs,
-        mtimeMs: stats.mtimeMs,
+        stat,
         patternValue,
       };
     } catch (e) {
       if (e.code === "ENOENT") {
-        return null;
+        return {
+          type: null,
+          stat: null,
+        };
       }
       throw e;
     }
@@ -2715,7 +2720,7 @@ const registerDirectoryLifecycle = (
   const handleChange = (relativeUrl) => {
     const entryUrl = new URL(relativeUrl, sourceUrl).href;
     const entryInfo = readEntryInfo(entryUrl);
-    if (!entryInfo) {
+    if (entryInfo.type === null) {
       const previousEntryInfo = infoMap.get(relativeUrl);
       if (!previousEntryInfo) {
         // on MacOS it's possible to receive a "rename" event for
@@ -2775,17 +2780,36 @@ const registerDirectoryLifecycle = (
       readdirSync(new URL(directoryUrl)).forEach((entryName) => {
         const childEntryUrl = new URL(entryName, directoryUrl).href;
         const childEntryInfo = readEntryInfo(childEntryUrl);
-        if (childEntryInfo && childEntryInfo.patternValue) {
+        if (childEntryInfo.type !== null && childEntryInfo.patternValue) {
           handleEntryFound(childEntryInfo, { notify });
         }
       });
+      // we must watch manually every directory we find
+      if (!fsWatchSupportsRecursive) {
+        const watcher = createWatcher(urlToFileSystemPath(entryInfo.url), {
+          persistent: keepProcessAlive,
+        });
+        tracker.registerCleanupCallback(() => {
+          watcher.close();
+        });
+        watcher.on("change", (eventType, filename) => {
+          handleDirectoryEvent({
+            directoryRelativeUrl: entryInfo.relativeUrl,
+            filename: filename
+              ? // replace back slashes with slashes
+                filename.replace(/\\/g, "/")
+              : "",
+            eventType,
+          });
+        });
+      }
     }
     if (added && entryInfo.patternValue && notify) {
       added({
         relativeUrl: entryInfo.relativeUrl,
         type: entryInfo.type,
         patternValue: entryInfo.patternValue,
-        mtime: entryInfo.mtimeMs,
+        mtime: entryInfo.stat.mtimeMs,
       });
     }
   };
@@ -2796,19 +2820,19 @@ const registerDirectoryLifecycle = (
         relativeUrl: entryInfo.relativeUrl,
         type: entryInfo.type,
         patternValue: entryInfo.patternValue,
-        mtime: entryInfo.mtimeMs,
+        mtime: entryInfo.stat.mtimeMs,
       });
     }
   };
   const handleEntryUpdated = (entryInfo) => {
     infoMap.set(entryInfo.relativeUrl, entryInfo);
-    if (updated && entryInfo.patternValue) {
+    if (updated && entryInfo.patternValue && shouldCallUpdated(entryInfo)) {
       updated({
         relativeUrl: entryInfo.relativeUrl,
         type: entryInfo.type,
         patternValue: entryInfo.patternValue,
-        mtime: entryInfo.mtimeMs,
-        previousMtime: entryInfo.previousInfo.mtimeMs,
+        mtime: entryInfo.stat.mtimeMs,
+        previousMtime: entryInfo.previousInfo.stat.mtimeMs,
       });
     }
   };
@@ -2816,7 +2840,7 @@ const registerDirectoryLifecycle = (
   readdirSync(new URL(sourceUrl)).forEach((entry) => {
     const entryUrl = new URL(entry, sourceUrl).href;
     const entryInfo = readEntryInfo(entryUrl);
-    if (entryInfo && entryInfo.patternValue) {
+    if (entryInfo.type !== null && entryInfo.patternValue) {
       handleEntryFound(entryInfo, {
         notify: notifyExistent,
       });
@@ -2850,6 +2874,20 @@ ${relativeUrls.join("\n")}`,
   return tracker.cleanup;
 };
 
+const shouldCallUpdated = (entryInfo) => {
+  const { stat, previousInfo } = entryInfo;
+  if (!stat.atimeMs) {
+    return true;
+  }
+  if (stat.atimeMs < stat.mtimeMs) {
+    return true;
+  }
+  if (isLinux && stat.mtimeMs <= previousInfo.stat.mtimeMs) {
+    return false;
+  }
+  return true;
+};
+
 const undefinedOrFunction = (value) => {
   return typeof value === "undefined" || typeof value === "function";
 };
@@ -13214,6 +13252,7 @@ const createUrlInfoTransformer = ({
     generatedUrlObject.searchParams.delete("as_json_module");
     generatedUrlObject.searchParams.delete("as_text_module");
     generatedUrlObject.searchParams.delete("dynamic_import");
+    generatedUrlObject.searchParams.delete("cjs_as_js_module");
     const urlForSourcemap = generatedUrlObject.href;
     urlInfo.sourcemapGeneratedUrl = generateSourcemapFileUrl(urlForSourcemap);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/core",
-  "version": "38.2.3",
+  "version": "38.2.5",
   "description": "Tool to develop, test and build js projects",
   "license": "MIT",
   "author": {
@@ -62,7 +62,7 @@
     "@financial-times/polyfill-useragent-normaliser": "1.10.2",
     "@jsenv/abort": "4.2.4",
     "@jsenv/ast": "5.1.4",
-    "@jsenv/filesystem": "4.3.0",
+    "@jsenv/filesystem": "4.3.2",
     "@jsenv/importmap": "1.2.1",
     "@jsenv/integrity": "0.0.1",
     "@jsenv/log": "3.4.0",

package/src/kitchen/url_graph/url_info_transformations.js

@@ -149,6 +149,7 @@ export const createUrlInfoTransformer = ({
     generatedUrlObject.searchParams.delete("as_json_module");
     generatedUrlObject.searchParams.delete("as_text_module");
     generatedUrlObject.searchParams.delete("dynamic_import");
+    generatedUrlObject.searchParams.delete("cjs_as_js_module");
     const urlForSourcemap = generatedUrlObject.href;
     urlInfo.sourcemapGeneratedUrl = generateSourcemapFileUrl(urlForSourcemap);