@jsenv/core 29.6.1 → 29.7.0

package/{readme.md → README.md}

@@ -7,26 +7,9 @@ It has naturally evolved to cover the core needs of a JavaScript project: develo
 - :sparkles: Dev, tests and build in a single tool
 - :ok_hand: Seamless integration with standard HTML, CSS and JS
 
-# Demo
-
-The following command can be used to create a jsenv project on a machine.
-
-```console
-npm create jsenv@latest
-```
-
-This command prompts to choose a demo from a list.
-Each demo contains preconfigured scripts:
-
-- `npm run dev`: starts a dev server with autoreload.
-- `npm run test`: execute test files on browsers(s) and/or Node.js.
-- `npm run build`: generate files optimized for production.
-
-> **Info**
-> Executing "npm install" in web demos can take time.
-> It is because in these demos tests are runned in headless browsers that needs to be installed first.
+# Documentation
 
-See also [packages/create-jsenv](./packages/create-jsenv).
+https://github.com/jsenv/jsenv-core/wiki
 
 # Installation
 
@@ -36,15 +19,6 @@ npm install --save-dev @jsenv/core
 
 _@jsenv/core_ is tested on Mac, Windows, Linux with Node.js 18.5.0. Other operating systems and Node.js versions are not tested.
 
-# Documentation
-
-| Link                                               | Description                                    |
-| -------------------------------------------------- | ---------------------------------------------- |
-| [Browser support](./docs/browser_support.md)       | Documentation around browser support           |
-| [Assets and workers](./docs/assets_and_workers.md) | How to reference files within a file           |
-| [Import resolution](./docs/import_resolution.md)   | Import resolution inside js modules            |
-| [NPM package](./docs/npm_package.md)               | How to use a NPM package (especially commonjs) |
-
 # Name
 
 The name "jsenv" stands for JavaScript environments. This is because the original purpose of jsenv was to bring closer two JavaScript runtimes: web browsers and Node.js.

package/dist/main.js

@@ -337,9 +337,12 @@ const pathnameToExtension$1 = pathname => {
 };
 
 const asUrlWithoutSearch = url => {
-  const urlObject = new URL(url);
-  urlObject.search = "";
-  return urlObject.href;
+  if (url.includes("?")) {
+    const urlObject = new URL(url);
+    urlObject.search = "";
+    return urlObject.href;
+  }
+  return url;
 };
 
 // normalize url search params:
@@ -19273,7 +19276,7 @@ const jsenvPluginUrlResolution = ({
 const jsenvPluginUrlVersion = () => {
   return {
     name: "jsenv:url_version",
-    appliesDuring: "*",
+    appliesDuring: "dev",
     redirectUrl: reference => {
       // "v" search param goal is to enable long-term cache
       // for server response headers
@@ -21708,27 +21711,30 @@ const jsenvPluginMinification = minification => {
     context,
     options: minification.json
   }) : null;
+  const cssOptimizer = minification.css ? (urlInfo, context) => minifyCss({
+    cssUrlInfo: urlInfo,
+    context,
+    options: minification.css
+  }) : null;
+  const jsClassicOptimizer = minification.js_classic ? (urlInfo, context) => minifyJs({
+    jsUrlInfo: urlInfo,
+    context,
+    options: minification.js_classic
+  }) : null;
+  const jsModuleOptimizer = minification.js_module ? (urlInfo, context) => minifyJs({
+    jsUrlInfo: urlInfo,
+    context,
+    options: minification.js_module
+  }) : null;
   return {
     name: "jsenv:minification",
     appliesDuring: "build",
     optimizeUrlContent: {
       html: htmlOptimizer,
       svg: htmlOptimizer,
-      css: minification.css ? (urlInfo, context) => minifyCss({
-        cssUrlInfo: urlInfo,
-        context,
-        options: minification.css
-      }) : null,
-      js_classic: minification.js_classic ? (urlInfo, context) => minifyJs({
-        jsUrlInfo: urlInfo,
-        context,
-        options: minification.js_classic
-      }) : null,
-      js_module: minification.js_module ? (urlInfo, context) => minifyJs({
-        jsUrlInfo: urlInfo,
-        context,
-        options: minification.js_module
-      }) : null,
+      css: cssOptimizer,
+      js_classic: jsClassicOptimizer,
+      js_module: jsModuleOptimizer,
       json: jsonOptimizer,
       importmap: jsonOptimizer,
       webmanifest: jsonOptimizer
@@ -22460,7 +22466,7 @@ const jsenvPluginExplorer = ({
 
 const jsenvPluginRibbon = ({
   rootDirectoryUrl,
-  htmlInclude = "**/*.html"
+  htmlInclude = "/**/*.html"
 }) => {
   const ribbonClientFileUrl = new URL("./js/ribbon.js", import.meta.url);
   const associations = URL_META.resolveAssociations({
@@ -24801,6 +24807,14 @@ const inferParentFromRequest = (request, rootDirectoryUrl) => {
   });
 };
 
+/**
+ * Start a server for source files:
+ * - cook source files according to jsenv plugins
+ * - inject code to autoreload the browser when a file is modified
+ * @param {Object} devServerParameters
+ * @param {string|url} devServerParameters.rootDirectoryUrl Root directory of the project
+ * @return {Object} A dev server object
+ */
 const startDevServer = async ({
   signal = new AbortController().signal,
   handleSIGINT = true,
@@ -28394,7 +28408,83 @@ const createBuildFilesService = ({
 };
 const SECONDS_IN_30_DAYS = 60 * 60 * 24 * 30;
 
-const replacePlaceholders = (content, replacements) => {
+const injectGlobals = (urlInfo, globals) => {
+  if (urlInfo.type === "html") {
+    return globalInjectorOnHtml(urlInfo, globals);
+  }
+  if (urlInfo.type === "js_classic" || urlInfo.type === "js_module") {
+    return globalsInjectorOnJs(urlInfo, globals);
+  }
+  throw new Error(`cannot inject globals into "${urlInfo.type}"`);
+};
+const globalInjectorOnHtml = async (urlInfo, globals) => {
+  // ideally we would inject an importmap but browser support is too low
+  // (even worse for worker/service worker)
+  // so for now we inject code into entry points
+  const htmlAst = parseHtmlString(urlInfo.content, {
+    storeOriginalPositions: false
+  });
+  const clientCode = generateClientCodeForGlobals({
+    globals,
+    isWebWorker: false
+  });
+  injectScriptNodeAsEarlyAsPossible(htmlAst, createHtmlNode({
+    tagName: "script",
+    textContent: clientCode
+  }), "jsenv:inject_globals");
+  return stringifyHtmlAst(htmlAst);
+};
+const globalsInjectorOnJs = async (urlInfo, globals) => {
+  const clientCode = generateClientCodeForGlobals({
+    globals,
+    isWebWorker: urlInfo.subtype === "worker" || urlInfo.subtype === "service_worker" || urlInfo.subtype === "shared_worker"
+  });
+  const magicSource = createMagicSource(urlInfo.content);
+  magicSource.prepend(clientCode);
+  return magicSource.toContentAndSourcemap();
+};
+const generateClientCodeForGlobals = ({
+  isWebWorker = false,
+  globals
+}) => {
+  const globalName = isWebWorker ? "self" : "window";
+  return `Object.assign(${globalName}, ${JSON.stringify(globals, null, "  ")});`;
+};
+
+const jsenvPluginInjectGlobals = rawAssociations => {
+  let resolvedAssociations;
+  return {
+    name: "jsenv:inject_globals",
+    appliesDuring: "*",
+    init: context => {
+      resolvedAssociations = URL_META.resolveAssociations({
+        injector: rawAssociations
+      }, context.rootDirectoryUrl);
+    },
+    transformUrlContent: async (urlInfo, context) => {
+      const {
+        injector
+      } = URL_META.applyAssociations({
+        url: asUrlWithoutSearch(urlInfo.url),
+        associations: resolvedAssociations
+      });
+      if (!injector) {
+        return null;
+      }
+      if (typeof injector !== "function") {
+        throw new TypeError("injector must be a function");
+      }
+      const globals = await injector(urlInfo, context);
+      if (!globals || Object.keys(globals).length === 0) {
+        return null;
+      }
+      return injectGlobals(urlInfo, globals);
+    }
+  };
+};
+
+const replacePlaceholders = (urlInfo, replacements) => {
+  const content = urlInfo.content;
   const magicSource = createMagicSource(content);
   Object.keys(replacements).forEach(key => {
     let index = content.indexOf(key);
@@ -28404,7 +28494,7 @@ const replacePlaceholders = (content, replacements) => {
       magicSource.replace({
         start,
         end,
-        replacement: replacements[key]
+        replacement: urlInfo.type === "js_classic" || urlInfo.type === "js_module" ? JSON.stringify(replacements[key], null, "  ") : replacements[key]
       });
       index = content.indexOf(key, end);
     }
@@ -28412,6 +28502,38 @@ const replacePlaceholders = (content, replacements) => {
   return magicSource.toContentAndSourcemap();
 };
 
+const jsenvPluginPlaceholders = rawAssociations => {
+  let resolvedAssociations;
+  return {
+    name: "jsenv:placeholders",
+    appliesDuring: "*",
+    init: context => {
+      resolvedAssociations = URL_META.resolveAssociations({
+        replacer: rawAssociations
+      }, context.rootDirectoryUrl);
+    },
+    transformUrlContent: async (urlInfo, context) => {
+      const {
+        replacer
+      } = URL_META.applyAssociations({
+        url: asUrlWithoutSearch(urlInfo.url),
+        associations: resolvedAssociations
+      });
+      if (!replacer) {
+        return null;
+      }
+      if (typeof replacer !== "function") {
+        throw new TypeError("replacer must be a function");
+      }
+      const replacements = await replacer(urlInfo, context);
+      if (!replacements || Object.keys(replacements).length === 0) {
+        return null;
+      }
+      return replacePlaceholders(urlInfo, replacements);
+    }
+  };
+};
+
 const execute = async ({
   signal = new AbortController().signal,
   handleSIGINT = true,
@@ -28497,70 +28619,4 @@ const execute = async ({
   }
 };
 
-const injectGlobals = (urlInfo, globals) => {
-  if (urlInfo.type === "html") {
-    return globalInjectorOnHtml(urlInfo, globals);
-  }
-  if (urlInfo.type === "js_classic" || urlInfo.type === "js_module") {
-    return globalsInjectorOnJs(urlInfo, globals);
-  }
-  throw new Error(`cannot inject globals into "${urlInfo.type}"`);
-};
-const globalInjectorOnHtml = async (urlInfo, globals) => {
-  // ideally we would inject an importmap but browser support is too low
-  // (even worse for worker/service worker)
-  // so for now we inject code into entry points
-  const htmlAst = parseHtmlString(urlInfo.content, {
-    storeOriginalPositions: false
-  });
-  const clientCode = generateClientCodeForGlobals({
-    globals,
-    isWebWorker: false
-  });
-  injectScriptNodeAsEarlyAsPossible(htmlAst, createHtmlNode({
-    tagName: "script",
-    textContent: clientCode
-  }), "jsenv:inject_globals");
-  return stringifyHtmlAst(htmlAst);
-};
-const globalsInjectorOnJs = async (urlInfo, globals) => {
-  const clientCode = generateClientCodeForGlobals({
-    globals,
-    isWebWorker: urlInfo.subtype === "worker" || urlInfo.subtype === "service_worker" || urlInfo.subtype === "shared_worker"
-  });
-  const magicSource = createMagicSource(urlInfo.content);
-  magicSource.prepend(clientCode);
-  return magicSource.toContentAndSourcemap();
-};
-const generateClientCodeForGlobals = ({
-  isWebWorker = false,
-  globals
-}) => {
-  const globalName = isWebWorker ? "self" : "window";
-  return `Object.assign(${globalName}, ${JSON.stringify(globals, null, "  ")});`;
-};
-
-const jsenvPluginInjectGlobals = urlAssociations => {
-  return {
-    name: "jsenv:inject_globals",
-    appliesDuring: "*",
-    transformUrlContent: async (urlInfo, context) => {
-      const url = Object.keys(urlAssociations).find(url => {
-        return url === urlInfo.url;
-      });
-      if (!url) {
-        return null;
-      }
-      let globals = urlAssociations[url];
-      if (typeof globals === "function") {
-        globals = await globals(urlInfo, context);
-      }
-      if (Object.keys(globals).length === 0) {
-        return null;
-      }
-      return injectGlobals(urlInfo, globals);
-    }
-  };
-};
-
-export { build, chromium, chromiumIsolatedTab, execute, executeTestPlan, firefox, firefoxIsolatedTab, jsenvPluginInjectGlobals, nodeChildProcess, nodeWorkerThread, pingServer, replacePlaceholders, startBuildServer, startDevServer, webkit, webkitIsolatedTab };
+export { build, chromium, chromiumIsolatedTab, execute, executeTestPlan, firefox, firefoxIsolatedTab, jsenvPluginInjectGlobals, jsenvPluginPlaceholders, nodeChildProcess, nodeWorkerThread, pingServer, startBuildServer, startDevServer, webkit, webkitIsolatedTab };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/core",
-  "version": "29.6.1",
+  "version": "29.7.0",
   "description": "Tool to develop, test and build js projects",
   "license": "MIT",
   "author": {
@@ -69,16 +69,16 @@
     "@jsenv/abort": "4.2.4",
     "@jsenv/ast": "1.4.4",
     "@jsenv/babel-plugins": "1.0.9",
-    "@jsenv/filesystem": "4.1.5",
+    "@jsenv/filesystem": "4.1.6",
     "@jsenv/importmap": "1.2.1",
     "@jsenv/integrity": "0.0.1",
     "@jsenv/log": "3.3.1",
     "@jsenv/node-esm-resolution": "0.2.0",
     "@jsenv/server": "14.1.9",
-    "@jsenv/sourcemap": "1.0.6",
+    "@jsenv/sourcemap": "1.0.7",
     "@jsenv/uneval": "1.6.0",
     "@jsenv/url-meta": "7.0.0",
-    "@jsenv/urls": "1.2.7",
+    "@jsenv/urls": "1.2.8",
     "@jsenv/utils": "2.0.1",
     "acorn-import-assertions": "1.8.0",
     "construct-style-sheets-polyfill": "3.1.0",

package/src/dev/start_dev_server.js

@@ -19,6 +19,14 @@ import { defaultRuntimeCompat } from "@jsenv/core/src/build/build.js"
 import { createReloadableWorker } from "@jsenv/core/src/helpers/worker_reload.js"
 import { createFileService } from "./file_service.js"
 
+/**
+ * Start a server for source files:
+ * - cook source files according to jsenv plugins
+ * - inject code to autoreload the browser when a file is modified
+ * @param {Object} devServerParameters
+ * @param {string|url} devServerParameters.rootDirectoryUrl Root directory of the project
+ * @return {Object} A dev server object
+ */
 export const startDevServer = async ({
   signal = new AbortController().signal,
   handleSIGINT = true,

package/src/main.js

@@ -23,8 +23,8 @@ export { startBuildServer } from "./build/start_build_server.js"
 
 // helpers
 export { pingServer } from "./ping_server.js"
-export { replacePlaceholders } from "./helpers/replace_placeholders.js"
 
 // advanced
-export { execute } from "./execute/execute.js"
 export { jsenvPluginInjectGlobals } from "./plugins/inject_globals/jsenv_plugin_inject_globals.js"
+export { jsenvPluginPlaceholders } from "./plugins/placeholders/jsenv_plugin_placeholders.js"
+export { execute } from "./execute/execute.js"

package/src/plugins/inject_globals/jsenv_plugin_inject_globals.js

@@ -1,21 +1,33 @@
+import { URL_META } from "@jsenv/url-meta"
+import { asUrlWithoutSearch } from "@jsenv/urls"
+
 import { injectGlobals } from "./inject_globals.js"
 
-export const jsenvPluginInjectGlobals = (urlAssociations) => {
+export const jsenvPluginInjectGlobals = (rawAssociations) => {
+  let resolvedAssociations
+
   return {
     name: "jsenv:inject_globals",
     appliesDuring: "*",
+    init: (context) => {
+      resolvedAssociations = URL_META.resolveAssociations(
+        { injector: rawAssociations },
+        context.rootDirectoryUrl,
+      )
+    },
     transformUrlContent: async (urlInfo, context) => {
-      const url = Object.keys(urlAssociations).find((url) => {
-        return url === urlInfo.url
+      const { injector } = URL_META.applyAssociations({
+        url: asUrlWithoutSearch(urlInfo.url),
+        associations: resolvedAssociations,
       })
-      if (!url) {
+      if (!injector) {
         return null
       }
-      let globals = urlAssociations[url]
-      if (typeof globals === "function") {
-        globals = await globals(urlInfo, context)
+      if (typeof injector !== "function") {
+        throw new TypeError("injector must be a function")
       }
-      if (Object.keys(globals).length === 0) {
+      const globals = await injector(urlInfo, context)
+      if (!globals || Object.keys(globals).length === 0) {
         return null
       }
       return injectGlobals(urlInfo, globals)

package/src/plugins/minification/jsenv_plugin_minification.js

@@ -37,6 +37,30 @@ export const jsenvPluginMinification = (minification) => {
           options: minification.json,
         })
     : null
+  const cssOptimizer = minification.css
+    ? (urlInfo, context) =>
+        minifyCss({
+          cssUrlInfo: urlInfo,
+          context,
+          options: minification.css,
+        })
+    : null
+  const jsClassicOptimizer = minification.js_classic
+    ? (urlInfo, context) =>
+        minifyJs({
+          jsUrlInfo: urlInfo,
+          context,
+          options: minification.js_classic,
+        })
+    : null
+  const jsModuleOptimizer = minification.js_module
+    ? (urlInfo, context) =>
+        minifyJs({
+          jsUrlInfo: urlInfo,
+          context,
+          options: minification.js_module,
+        })
+    : null
 
   return {
     name: "jsenv:minification",
@@ -44,30 +68,9 @@ export const jsenvPluginMinification = (minification) => {
     optimizeUrlContent: {
       html: htmlOptimizer,
       svg: htmlOptimizer,
-      css: minification.css
-        ? (urlInfo, context) =>
-            minifyCss({
-              cssUrlInfo: urlInfo,
-              context,
-              options: minification.css,
-            })
-        : null,
-      js_classic: minification.js_classic
-        ? (urlInfo, context) =>
-            minifyJs({
-              jsUrlInfo: urlInfo,
-              context,
-              options: minification.js_classic,
-            })
-        : null,
-      js_module: minification.js_module
-        ? (urlInfo, context) =>
-            minifyJs({
-              jsUrlInfo: urlInfo,
-              context,
-              options: minification.js_module,
-            })
-        : null,
+      css: cssOptimizer,
+      js_classic: jsClassicOptimizer,
+      js_module: jsModuleOptimizer,
       json: jsonOptimizer,
       importmap: jsonOptimizer,
       webmanifest: jsonOptimizer,

package/src/plugins/placeholders/jsenv_plugin_placeholders.js

@@ -0,0 +1,36 @@
+import { URL_META } from "@jsenv/url-meta"
+import { asUrlWithoutSearch } from "@jsenv/urls"
+
+import { replacePlaceholders } from "./replace_placeholders.js"
+
+export const jsenvPluginPlaceholders = (rawAssociations) => {
+  let resolvedAssociations
+
+  return {
+    name: "jsenv:placeholders",
+    appliesDuring: "*",
+    init: (context) => {
+      resolvedAssociations = URL_META.resolveAssociations(
+        { replacer: rawAssociations },
+        context.rootDirectoryUrl,
+      )
+    },
+    transformUrlContent: async (urlInfo, context) => {
+      const { replacer } = URL_META.applyAssociations({
+        url: asUrlWithoutSearch(urlInfo.url),
+        associations: resolvedAssociations,
+      })
+      if (!replacer) {
+        return null
+      }
+      if (typeof replacer !== "function") {
+        throw new TypeError("replacer must be a function")
+      }
+      const replacements = await replacer(urlInfo, context)
+      if (!replacements || Object.keys(replacements).length === 0) {
+        return null
+      }
+      return replacePlaceholders(urlInfo, replacements)
+    },
+  }
+}

package/src/{helpers → plugins/placeholders}/replace_placeholders.js

@@ -1,13 +1,21 @@
 import { createMagicSource } from "@jsenv/sourcemap"
 
-export const replacePlaceholders = (content, replacements) => {
+export const replacePlaceholders = (urlInfo, replacements) => {
+  const content = urlInfo.content
   const magicSource = createMagicSource(content)
   Object.keys(replacements).forEach((key) => {
     let index = content.indexOf(key)
     while (index !== -1) {
       const start = index
       const end = index + key.length
-      magicSource.replace({ start, end, replacement: replacements[key] })
+      magicSource.replace({
+        start,
+        end,
+        replacement:
+          urlInfo.type === "js_classic" || urlInfo.type === "js_module"
+            ? JSON.stringify(replacements[key], null, "  ")
+            : replacements[key],
+      })
       index = content.indexOf(key, end)
     }
   })

package/src/plugins/ribbon/jsenv_plugin_ribbon.js

@@ -9,7 +9,7 @@ import { asUrlWithoutSearch } from "@jsenv/urls"
 
 export const jsenvPluginRibbon = ({
   rootDirectoryUrl,
-  htmlInclude = "**/*.html",
+  htmlInclude = "/**/*.html",
 }) => {
   const ribbonClientFileUrl = new URL("./client/ribbon.js", import.meta.url)
   const associations = URL_META.resolveAssociations(

package/src/plugins/url_version/jsenv_plugin_url_version.js

@@ -1,7 +1,7 @@
 export const jsenvPluginUrlVersion = () => {
   return {
     name: "jsenv:url_version",
-    appliesDuring: "*",
+    appliesDuring: "dev",
     redirectUrl: (reference) => {
       // "v" search param goal is to enable long-term cache
       // for server response headers