@jsenv/core 38.0.6 → 38.1.1

package/README.md

@@ -1,32 +1,19 @@
 # @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 was created to provide a tool that can be used both for the web and Node.js.
-It has naturally evolved to cover the core needs of a JavaScript project: developement, testing and building for production.
+Jsenv is a tool to develop test and build projects using JavaScript. This tool makes a special effort to let you free to code as you want. Jsenv is simple, easy to understand and well documented.
 
-- :ok_hand: Seamless integration with standard HTML, CSS and JS.
-- :sparkles: Same developer experience on source files and test files.
-- :exploding_head: Can execute tests on Chrome, Firefox, Safari and Node.js.
+[Documentation for users](<https://github.com/jsenv/core/wiki/A)-Introduction>) · [Changelog](./CHANGELOG.md)
 
-[Documentation](<https://github.com/jsenv/core/wiki/A)-Getting-started>) · [Changelog](./CHANGELOG.md)
+See also
 
-# Installation
+- [Documentation for contributors](./docs/contributors/README.md)
+- [Documentation for maintainers](./docs/maintainers/README.md)
+
+<!-- # Installation
 
 ```console
 npm install --save-dev @jsenv/core
 ```
 
 _@jsenv/core_ is tested on Mac, Windows, Linux with Node.js 18.
-Other operating systems and Node.js versions are not tested.
-
-# Name
-
-The name "jsenv" stands for JavaScript environments.<br />
-"jsenv" without capital letter because "JSEnv" would be too painful to type.
-
-# Logo
-
-The logo is composed by the name at the center and two circles orbiting around it.
-One of the circle is web browsers, the other is Node.js.
-It represents the two JavaScript runtimes supported by jsenv.
-
-![jsenv logo with legend](./docs/jsenv_logo_legend.png)
+Other operating systems and Node.js versions are not tested. -->

package/dist/jsenv_core.js

@@ -14797,6 +14797,214 @@ const createRepartitionMessage = ({ html, css, js, json, other, total }) => {
 - `)}`;
 };
 
+const placeholderSymbol = Symbol.for("jsenv_placeholder");
+const PLACEHOLDER = {
+  optional: (value) => {
+    return { [placeholderSymbol]: "optional", value };
+  },
+};
+
+const replacePlaceholders = (content, replacements, urlInfo) => {
+  const magicSource = createMagicSource(content);
+  for (const key of Object.keys(replacements)) {
+    let index = content.indexOf(key);
+    const replacement = replacements[key];
+    let isOptional;
+    let value;
+    if (replacement && replacement[placeholderSymbol]) {
+      const valueBehindSymbol = replacement[placeholderSymbol];
+      isOptional = valueBehindSymbol === "optional";
+      value = replacement.value;
+    } else {
+      value = replacement;
+    }
+    if (index === -1) {
+      if (!isOptional) {
+        urlInfo.context.logger.warn(
+          `placeholder "${key}" not found in ${urlInfo.url}.
+--- suggestion a ---
+Add "${key}" in that file.
+--- suggestion b ---
+Fix eventual typo in "${key}"?
+--- suggestion c ---
+Mark injection as optional using PLACEHOLDER.optional()
+
+import { PLACEHOLDER } from "@jsenv/core"
+
+return {
+  "${key}": PLACEHOLDER.optional(${JSON.stringify(value)})
+}`,
+        );
+      }
+      continue;
+    }
+
+    while (index !== -1) {
+      const start = index;
+      const end = index + key.length;
+      magicSource.replace({
+        start,
+        end,
+        replacement:
+          urlInfo.type === "js_classic" ||
+          urlInfo.type === "js_module" ||
+          urlInfo.type === "html"
+            ? JSON.stringify(value, null, "  ")
+            : value,
+      });
+      index = content.indexOf(key, end);
+    }
+  }
+  return magicSource.toContentAndSourcemap();
+};
+
+const injectGlobals = (content, globals, urlInfo) => {
+  if (urlInfo.type === "html") {
+    return globalInjectorOnHtml(content, globals);
+  }
+  if (urlInfo.type === "js_classic" || urlInfo.type === "js_module") {
+    return globalsInjectorOnJs(content, globals, urlInfo);
+  }
+  throw new Error(`cannot inject globals into "${urlInfo.type}"`);
+};
+
+const globalInjectorOnHtml = (content, 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(content, {
+    storeOriginalPositions: false,
+  });
+  const clientCode = generateClientCodeForGlobals(globals, {
+    isWebWorker: false,
+  });
+  injectHtmlNodeAsEarlyAsPossible(
+    htmlAst,
+    createHtmlNode({
+      tagName: "script",
+      textContent: clientCode,
+    }),
+    "jsenv:inject_globals",
+  );
+  return stringifyHtmlAst(htmlAst);
+};
+
+const globalsInjectorOnJs = (content, globals, urlInfo) => {
+  const clientCode = generateClientCodeForGlobals(globals, {
+    isWebWorker:
+      urlInfo.subtype === "worker" ||
+      urlInfo.subtype === "service_worker" ||
+      urlInfo.subtype === "shared_worker",
+  });
+  const magicSource = createMagicSource(content);
+  magicSource.prepend(clientCode);
+  return magicSource.toContentAndSourcemap();
+};
+
+const generateClientCodeForGlobals = (globals, { isWebWorker = false }) => {
+  const globalName = isWebWorker ? "self" : "window";
+  return `Object.assign(${globalName}, ${JSON.stringify(
+    globals,
+    null,
+    "  ",
+  )});`;
+};
+
+const jsenvPluginInjections = (rawAssociations) => {
+  let resolvedAssociations;
+
+  return {
+    name: "jsenv:injections",
+    appliesDuring: "*",
+    init: (context) => {
+      resolvedAssociations = URL_META.resolveAssociations(
+        { injectionsGetter: rawAssociations },
+        context.rootDirectoryUrl,
+      );
+    },
+    transformUrlContent: async (urlInfo) => {
+      const { injectionsGetter } = URL_META.applyAssociations({
+        url: asUrlWithoutSearch(urlInfo.url),
+        associations: resolvedAssociations,
+      });
+      if (!injectionsGetter) {
+        return null;
+      }
+      if (typeof injectionsGetter !== "function") {
+        throw new TypeError("injectionsGetter must be a function");
+      }
+      const injections = await injectionsGetter(urlInfo);
+      if (!injections) {
+        return null;
+      }
+      const keys = Object.keys(injections);
+      if (keys.length === 0) {
+        return null;
+      }
+      let someGlobal = false;
+      let someReplacement = false;
+      const globals = {};
+      const replacements = {};
+      for (const key of keys) {
+        const { type, name, value } = createInjection(injections[key], key);
+        if (type === "global") {
+          globals[name] = value;
+          someGlobal = true;
+        } else {
+          replacements[name] = value;
+          someReplacement = true;
+        }
+      }
+
+      if (!someGlobal && !someReplacement) {
+        return null;
+      }
+
+      let content = urlInfo.content;
+      let sourcemap;
+      if (someGlobal) {
+        const globalInjectionResult = injectGlobals(content, globals, urlInfo);
+        content = globalInjectionResult.content;
+        sourcemap = globalInjectionResult.sourcemap;
+      }
+      if (someReplacement) {
+        const replacementResult = replacePlaceholders(
+          content,
+          replacements,
+          urlInfo,
+        );
+        content = replacementResult.content;
+        sourcemap = sourcemap
+          ? composeTwoSourcemaps(sourcemap, replacementResult.sourcemap)
+          : replacementResult.sourcemap;
+      }
+      return {
+        content,
+        sourcemap,
+      };
+    },
+  };
+};
+
+const wellKnowGlobalNames = ["window", "global", "globalThis", "self"];
+const createInjection = (value, key) => {
+  for (const wellKnowGlobalName of wellKnowGlobalNames) {
+    const prefix = `${wellKnowGlobalName}.`;
+    if (key.startsWith(prefix)) {
+      return {
+        type: "global",
+        name: key.slice(prefix.length),
+        value,
+      };
+    }
+  }
+  return {
+    type: "replacement",
+    name: key,
+    value,
+  };
+};
+
 const jsenvPluginReferenceExpectedTypes = () => {
   const redirectJsReference = (reference) => {
     const urlObject = new URL(reference.url);
@@ -18675,30 +18883,6 @@ const babelPluginMetadataImportMetaScenarios = () => {
   };
 };
 
-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:
-          urlInfo.type === "js_classic" ||
-          urlInfo.type === "js_module" ||
-          urlInfo.type === "html"
-            ? JSON.stringify(replacements[key], null, "  ")
-            : replacements[key],
-      });
-      index = content.indexOf(key, end);
-    }
-  });
-  return magicSource.toContentAndSourcemap();
-};
-
 /*
  * Source code can contain the following
  * - __dev__
@@ -18709,10 +18893,14 @@ const replacePlaceholders = (urlInfo, replacements) => {
 
 const jsenvPluginGlobalScenarios = () => {
   const transformIfNeeded = (urlInfo) => {
-    return replacePlaceholders(urlInfo, {
-      __DEV__: urlInfo.context.dev,
-      __BUILD__: urlInfo.context.build,
-    });
+    return replacePlaceholders(
+      urlInfo.content,
+      {
+        __DEV__: PLACEHOLDER.optional(urlInfo.context.dev),
+        __BUILD__: PLACEHOLDER.optional(urlInfo.context.build),
+      },
+      urlInfo,
+    );
   };
 
   return {
@@ -19600,6 +19788,7 @@ const getCorePlugins = ({
   magicDirectoryIndex,
   directoryReferenceAllowed,
   supervisor,
+  injections,
   transpilation = true,
   inlining = true,
 
@@ -19620,6 +19809,7 @@ const getCorePlugins = ({
 
   return [
     jsenvPluginReferenceAnalysis(referenceAnalysis),
+    ...(injections ? [jsenvPluginInjections(injections)] : []),
     jsenvPluginTranspilation(transpilation),
     jsenvPluginImportmap(),
     ...(inlining ? [jsenvPluginInlining()] : []),
@@ -20736,7 +20926,7 @@ const createBuildSpecifierManager = ({
             const urlInfo = finalKitchen.graph.getUrlInfo(finalUrl);
             if (!urlInfo) {
               logger.warn(
-                `remove resource hint because cannot find "${href}" in the graph`,
+                `${UNICODE.WARNING} remove resource hint because cannot find "${href}" in the graph`,
               );
               mutations.push(() => {
                 removeHtmlNode(node);
@@ -20747,7 +20937,7 @@ const createBuildSpecifierManager = ({
               const rawUrlInfo = rawKitchen.graph.getUrlInfo(rawUrl);
               if (rawUrlInfo && rawUrlInfo.data.bundled) {
                 logger.warn(
-                  `remove resource hint on "${href}" because it was bundled`,
+                  `${UNICODE.WARNING} remove resource hint on "${href}" because it was bundled`,
                 );
                 mutations.push(() => {
                   removeHtmlNode(node);
@@ -20755,7 +20945,7 @@ const createBuildSpecifierManager = ({
                 return;
               }
               logger.warn(
-                `remove resource hint on "${href}" because it is not used anymore`,
+                `${UNICODE.WARNING} remove resource hint on "${href}" because it is not used anymore`,
               );
               mutations.push(() => {
                 removeHtmlNode(node);
@@ -21228,6 +21418,7 @@ const build = async ({
   magicDirectoryIndex,
   directoryReferenceAllowed,
   scenarioPlaceholders,
+  injections,
   transpilation = {},
   bundling = true,
   minification = !runtimeCompat.node,
@@ -21412,6 +21603,7 @@ build ${entryPointKeys.length} entry points`);
           magicExtensions,
           magicDirectoryIndex,
           directoryReferenceAllowed,
+          injections,
           transpilation: {
             babelHelpersAsImport: !explicitJsModuleConversion,
             ...transpilation,
@@ -21965,6 +22157,7 @@ const createFileService = ({
   magicExtensions,
   magicDirectoryIndex,
   supervisor,
+  injections,
   transpilation,
   clientAutoreload,
   cacheControl,
@@ -22046,6 +22239,7 @@ const createFileService = ({
           magicExtensions,
           magicDirectoryIndex,
           supervisor,
+          injections,
           transpilation,
 
           clientAutoreload,
@@ -22382,6 +22576,7 @@ const startDevServer = async ({
   supervisor = true,
   magicExtensions,
   magicDirectoryIndex,
+  injections,
   transpilation,
   cacheControl = true,
   ribbon = true,
@@ -22524,6 +22719,7 @@ const startDevServer = async ({
           magicExtensions,
           magicDirectoryIndex,
           supervisor,
+          injections,
           transpilation,
           clientAutoreload,
           cacheControl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/core",
-  "version": "38.0.6",
+  "version": "38.1.1",
   "description": "Tool to develop, test and build js projects",
   "license": "MIT",
   "author": {
@@ -71,6 +71,7 @@
     "@jsenv/runtime-compat": "1.2.0",
     "@jsenv/server": "15.1.0",
     "@jsenv/sourcemap": "1.2.1",
+    "@jsenv/plugin-injections": "1.0.0",
     "@jsenv/plugin-bundling": "2.5.1",
     "@jsenv/plugin-minification": "1.5.0",
     "@jsenv/plugin-transpilation": "1.3.2",
@@ -90,14 +91,12 @@
     "@jsenv/https-local": "3.0.7",
     "@jsenv/package-workspace": "0.5.2",
     "@jsenv/performance-impact": "4.1.1",
-    "@jsenv/plugin-globals": "./packages/related/plugin-globals/",
-    "@jsenv/plugin-placeholders": "./packages/related/plugin-placeholders/",
     "@jsenv/plugin-as-js-classic": "./packages/related/plugin-as-js-classic/",
     "@jsenv/test": "./packages/related/test/",
-    "eslint": "8.45.0",
+    "eslint": "8.46.0",
     "eslint-plugin-html": "7.1.0",
     "eslint-plugin-import": "2.28.0",
-    "eslint-plugin-react": "7.33.0",
+    "eslint-plugin-react": "7.33.1",
     "open": "9.1.0",
     "playwright": "1.36.2",
     "prettier": "3.0.0"

package/src/build/build.js

@@ -107,6 +107,7 @@ export const build = async ({
   magicDirectoryIndex,
   directoryReferenceAllowed,
   scenarioPlaceholders,
+  injections,
   transpilation = {},
   bundling = true,
   minification = !runtimeCompat.node,
@@ -291,6 +292,7 @@ build ${entryPointKeys.length} entry points`);
           magicExtensions,
           magicDirectoryIndex,
           directoryReferenceAllowed,
+          injections,
           transpilation: {
             babelHelpersAsImport: !explicitJsModuleConversion,
             ...transpilation,

package/src/build/build_specifier_manager.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { createDetailedMessage } from "@jsenv/log";
+import { createDetailedMessage, UNICODE } from "@jsenv/log";
 import { comparePathnames } from "@jsenv/filesystem";
 import { createMagicSource, generateSourcemapFileUrl } from "@jsenv/sourcemap";
 import {
@@ -790,7 +790,7 @@ export const createBuildSpecifierManager = ({
             const urlInfo = finalKitchen.graph.getUrlInfo(finalUrl);
             if (!urlInfo) {
               logger.warn(
-                `remove resource hint because cannot find "${href}" in the graph`,
+                `${UNICODE.WARNING} remove resource hint because cannot find "${href}" in the graph`,
               );
               mutations.push(() => {
                 removeHtmlNode(node);
@@ -801,7 +801,7 @@ export const createBuildSpecifierManager = ({
               const rawUrlInfo = rawKitchen.graph.getUrlInfo(rawUrl);
               if (rawUrlInfo && rawUrlInfo.data.bundled) {
                 logger.warn(
-                  `remove resource hint on "${href}" because it was bundled`,
+                  `${UNICODE.WARNING} remove resource hint on "${href}" because it was bundled`,
                 );
                 mutations.push(() => {
                   removeHtmlNode(node);
@@ -809,7 +809,7 @@ export const createBuildSpecifierManager = ({
                 return;
               }
               logger.warn(
-                `remove resource hint on "${href}" because it is not used anymore`,
+                `${UNICODE.WARNING} remove resource hint on "${href}" because it is not used anymore`,
               );
               mutations.push(() => {
                 removeHtmlNode(node);

package/src/dev/file_service.js

@@ -31,6 +31,7 @@ export const createFileService = ({
   magicExtensions,
   magicDirectoryIndex,
   supervisor,
+  injections,
   transpilation,
   clientAutoreload,
   cacheControl,
@@ -112,6 +113,7 @@ export const createFileService = ({
           magicExtensions,
           magicDirectoryIndex,
           supervisor,
+          injections,
           transpilation,
 
           clientAutoreload,

package/src/dev/start_dev_server.js

@@ -55,6 +55,7 @@ export const startDevServer = async ({
   supervisor = true,
   magicExtensions,
   magicDirectoryIndex,
+  injections,
   transpilation,
   cacheControl = true,
   ribbon = true,
@@ -197,6 +198,7 @@ export const startDevServer = async ({
           magicExtensions,
           magicDirectoryIndex,
           supervisor,
+          injections,
           transpilation,
           clientAutoreload,
           cacheControl,

package/src/plugins/global_scenarios/jsenv_plugin_global_scenarios.js

@@ -5,14 +5,18 @@
  * A global will be injected with true/false when needed
  */
 
-import { replacePlaceholders } from "@jsenv/plugin-placeholders";
+import { replacePlaceholders, PLACEHOLDER } from "@jsenv/plugin-injections";
 
 export const jsenvPluginGlobalScenarios = () => {
   const transformIfNeeded = (urlInfo) => {
-    return replacePlaceholders(urlInfo, {
-      __DEV__: urlInfo.context.dev,
-      __BUILD__: urlInfo.context.build,
-    });
+    return replacePlaceholders(
+      urlInfo.content,
+      {
+        __DEV__: PLACEHOLDER.optional(urlInfo.context.dev),
+        __BUILD__: PLACEHOLDER.optional(urlInfo.context.build),
+      },
+      urlInfo,
+    );
   };
 
   return {

package/src/plugins/plugins.js

@@ -1,4 +1,5 @@
 import { jsenvPluginSupervisor } from "@jsenv/plugin-supervisor";
+import { jsenvPluginInjections } from "@jsenv/plugin-injections";
 import { jsenvPluginTranspilation } from "@jsenv/plugin-transpilation";
 
 import { jsenvPluginReferenceAnalysis } from "./reference_analysis/jsenv_plugin_reference_analysis.js";
@@ -31,6 +32,7 @@ export const getCorePlugins = ({
   magicDirectoryIndex,
   directoryReferenceAllowed,
   supervisor,
+  injections,
   transpilation = true,
   inlining = true,
 
@@ -51,6 +53,7 @@ export const getCorePlugins = ({
 
   return [
     jsenvPluginReferenceAnalysis(referenceAnalysis),
+    ...(injections ? [jsenvPluginInjections(injections)] : []),
     jsenvPluginTranspilation(transpilation),
     jsenvPluginImportmap(),
     ...(inlining ? [jsenvPluginInlining()] : []),