@plaudit/webpack-extensions 2.84.0 → 2.85.0

package/build/utils/path-query-and-related-helpers.js

@@ -0,0 +1,277 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAssetFileContents = getAssetFileContents;
+exports.unpackPotentiallyPrefixedFilePath = unpackPotentiallyPrefixedFilePath;
+exports.unpackPathQuery = unpackPathQuery;
+exports.isValidLoadingStrategy = isValidLoadingStrategy;
+exports.newInvalidLoadingStrategyError = newInvalidLoadingStrategyError;
+exports.isValidInFooter = isValidInFooter;
+exports.newInvalidInFooterError = newInvalidInFooterError;
+exports.isValidFetchPriority = isValidFetchPriority;
+exports.newInvalidFetchPriorityError = newInvalidFetchPriorityError;
+exports.isValidPositionForInlineStrategy = isValidPositionForInlineStrategy;
+exports.newInvalidPositionForInlineStrategyError = newInvalidPositionForInlineStrategyError;
+exports.mergeInPathQueryParameters = mergeInPathQueryParameters;
+exports.parseScriptArgsObjectFromPathQueryParameters = parseScriptArgsObjectFromPathQueryParameters;
+const shared_1 = require("../shared");
+const node_path_1 = require("node:path");
+function getAssetFileContents(compilation, name) {
+    const asset = compilation.getAsset(name);
+    if (!asset) {
+        throw new Error(`${name} is unexpectedly missing`);
+    }
+    const assetSource = asset.source.source();
+    return typeof assetSource === 'string' ? assetSource : assetSource?.toString('utf-8');
+}
+function unpackPotentiallyPrefixedFilePath(filePath) {
+    if (filePath.startsWith("file:")) {
+        filePath = filePath.substring(5);
+    }
+    const queryStart = filePath.indexOf("?");
+    if (queryStart === -1) {
+        return [filePath, undefined];
+    }
+    else {
+        return [filePath.substring(0, queryStart), unpackPathQuery(filePath.substring(queryStart + 1))];
+    }
+}
+/**
+ * The following substitutions are performed:
+ * <ul>
+ *     <li>parameters without an assigned value -> a boolean parameter set to true</li>
+ *     <li>true and false -> their boolean equivalents</li>
+ *     <li>numeric values -> their number equivalents</li>
+ * </ul>
+ *
+ * @param pathQuery the part after the "?" in a webpack inclusion path
+ * @return the query as an object with common string -> JS type conversions already performed
+ */
+function unpackPathQuery(pathQuery) {
+    if (!pathQuery) {
+        return undefined;
+    }
+    return new URLSearchParams(pathQuery.replaceAll(/((?:[&?]|^)\w+)(&|$)/g, "$1=true$2")).entries()
+        .map(([key, value]) => {
+        if (value === 'true') {
+            return [key, true];
+        }
+        if (value === 'false') {
+            return [key, false];
+        }
+        if (Number.isFinite(+value)) {
+            return [key, +value];
+        }
+        return [key, value];
+    })
+        .reduce((collector, [key, value]) => {
+        if (collector[key] instanceof Array) {
+            collector[key].push(value);
+        }
+        else if (key in collector) {
+            collector[key] = [collector[key], value];
+        }
+        else {
+            collector[key] = value;
+        }
+        return collector;
+    }, {});
+}
+const namedStrategies = ['defer', 'async', 'eager', 'lazy', 'inline'];
+function isValidLoadingStrategy(strategy) {
+    return strategy === undefined || (typeof strategy === 'string' && namedStrategies.includes(strategy));
+}
+function newInvalidLoadingStrategyError(strategy, file) {
+    return (0, shared_1.newWebpackErrorForFile)(`The strategy was invalid. Received: ${strategy}, Expected: undefined|boolean|'${namedStrategies.join("'|'")}'`, file);
+}
+function isValidInFooter(in_footer) {
+    return typeof in_footer === 'boolean';
+}
+function newInvalidInFooterError(in_footer, file) {
+    return (0, shared_1.newWebpackErrorForFile)(`The in_footer value was invalid. Received: ${in_footer}, Expected: undefined|boolean`, file);
+}
+function isValidFetchPriority(fetchpriority) {
+    return typeof fetchpriority === 'string' && ["auto", "low", "high"].includes(fetchpriority);
+}
+function newInvalidFetchPriorityError(fetchpriority, file) {
+    return (0, shared_1.newWebpackErrorForFile)(`The fetchpriority value was invalid. Received: ${fetchpriority}, Expected: undefined|'auto'|'low'|'high'`, file);
+}
+function isValidPositionForInlineStrategy(position) {
+    return typeof position === 'string' && ["before", "after"].includes(position);
+}
+function newInvalidPositionForInlineStrategyError(position, file) {
+    return (0, shared_1.newWebpackErrorForFile)(`The position value for the inlined asset was invalid. Received: ${position}, Expected: undefined|'before'|'after'`, file);
+}
+function mergeInPathQueryParameters(file, registerScriptArgs, pathQueryParameters) {
+    const baseArgs = unpackRegisterScriptArgsFromPathQueryParameters(typeof registerScriptArgs === 'object' ? registerScriptArgs : { strategy: registerScriptArgs }, file, 'registerScriptArgs');
+    const pathQueryArgs = unpackRegisterScriptArgsFromPathQueryParameters(pathQueryParameters, file, 'path query parameters');
+    if (baseArgs === undefined) {
+        return pathQueryArgs;
+    }
+    if (pathQueryArgs === undefined) {
+        return baseArgs;
+    }
+    for (const key of ['strategy', 'in_footer', 'fetchpriority', 'inline', 'position']) {
+        if (key in baseArgs) {
+            if (key in pathQueryArgs && pathQueryArgs[key] !== baseArgs[key]) {
+                throw (0, shared_1.newWebpackErrorForFile)(`The ${key} values in the registerScriptArgs and the pathQueryParameters for the file conflict`, file);
+            }
+        }
+        else if (key in pathQueryArgs) {
+            baseArgs[key] = pathQueryArgs[key];
+        }
+    }
+    return baseArgs;
+}
+function unpackRegisterScriptArgsFromPathQueryParameters(pathQueryParameters, file, sourceType) {
+    if (pathQueryParameters === undefined) {
+        return undefined;
+    }
+    let hasAnyKeys = false;
+    let baseArgs;
+    const strategy = pathQueryParameters['strategy'];
+    switch (strategy) {
+        case 'eager':
+            hasAnyKeys = true;
+            baseArgs = { strategy: 'eager' };
+            break;
+        case 'lazy':
+            hasAnyKeys = true;
+            baseArgs = { strategy: 'defer', in_footer: true };
+            break;
+        case 'inline':
+            hasAnyKeys = true;
+            baseArgs = { inline: true };
+            break;
+        case true:
+        case false:
+            hasAnyKeys = true;
+            baseArgs = { in_footer: strategy };
+            break;
+        case null:
+        case undefined:
+            baseArgs = {};
+            break;
+        default:
+            throw newInvalidLoadingStrategyError(strategy, file);
+    }
+    if (baseArgs.inline === undefined && pathQueryParameters['inline'] !== undefined) {
+        baseArgs.inline = !!pathQueryParameters['inline'];
+    }
+    const in_footer = pathQueryParameters['in_footer'] ?? pathQueryParameters['in-footer'];
+    if (in_footer !== undefined) {
+        if (!isValidInFooter(in_footer)) {
+            throw newInvalidInFooterError(in_footer, file);
+        }
+        hasAnyKeys = true;
+        baseArgs.in_footer = in_footer;
+    }
+    if (pathQueryParameters['fetchpriority'] !== undefined) {
+        if (!isValidFetchPriority(pathQueryParameters['fetchpriority'])) {
+            throw newInvalidFetchPriorityError(pathQueryParameters['fetchpriority'], file);
+        }
+        if (baseArgs.fetchpriority !== undefined && baseArgs.fetchpriority !== pathQueryParameters['fetchpriority']) {
+            throw (0, shared_1.newWebpackErrorForFile)(`The strategy and fetchpriority values in the ${sourceType} for the file conflict. Got ${strategy} and ${pathQueryParameters['fetchpriority']}`, file);
+        }
+        hasAnyKeys = true;
+        baseArgs.fetchpriority = pathQueryParameters['fetchpriority'];
+    }
+    if (pathQueryParameters['inline'] !== undefined) {
+    }
+    return hasAnyKeys ? baseArgs : undefined;
+}
+/**
+ * This function does a few things:
+ * <ol>
+ *     <li>It extracts strategy, in_footer, and fetchpriority from pathQueryParameters</li>
+ *     <li>If the strategy is, 'inline', it records the contents of the asset for later injection inline and removes the asset from the compilation output</li>
+ * </ol>
+ * @param compilation
+ * @param file
+ * @param pathQueryParameters
+ */
+function parseScriptArgsObjectFromPathQueryParameters(compilation, file, pathQueryParameters) {
+    if (pathQueryParameters === undefined) {
+        return {};
+    }
+    const scriptArgsObject = {};
+    let inlinedAsset = undefined;
+    let hasAnyKeys = false;
+    const strategy = pathQueryParameters['strategy'];
+    switch (strategy) {
+        case 'async':
+        case 'defer':
+            hasAnyKeys = true;
+            scriptArgsObject.strategy = strategy;
+            break;
+        case 'eager':
+            hasAnyKeys = true;
+            scriptArgsObject.in_footer = false;
+            break;
+        case 'lazy':
+            hasAnyKeys = true;
+            scriptArgsObject.strategy = 'defer';
+            scriptArgsObject.in_footer = true;
+            break;
+        case 'inline':
+            inlinedAsset = { contents: getAssetFileContents(compilation, file) };
+            removeFileAndAssetPHP(compilation, file);
+            if ('inline' in pathQueryParameters) {
+                compilation.warnings.push((0, shared_1.newWebpackErrorForFile)("The inline parameter should not be set when setting strategy to 'inline'", file));
+            }
+            break;
+        case true:
+        case false:
+            hasAnyKeys = true;
+            scriptArgsObject.in_footer = strategy;
+            break;
+        case null:
+        case undefined:
+            // This is included because are effectively validating the strategy value with this switch statement, and "not defined" is a valid state
+            break;
+        default:
+            throw newInvalidLoadingStrategyError(strategy, file);
+    }
+    const in_footer = pathQueryParameters['in_footer'] ?? pathQueryParameters['in-footer'];
+    if (in_footer !== undefined) {
+        if (!isValidInFooter(in_footer)) {
+            throw newInvalidInFooterError(in_footer, file);
+        }
+        hasAnyKeys = true;
+        scriptArgsObject.in_footer = in_footer;
+    }
+    if (inlinedAsset === undefined && pathQueryParameters['inline']) {
+        inlinedAsset = { contents: getAssetFileContents(compilation, file) };
+        removeFileAndAssetPHP(compilation, file);
+    }
+    if (inlinedAsset !== undefined) {
+        if (pathQueryParameters['position'] !== undefined) {
+            if (!isValidPositionForInlineStrategy(pathQueryParameters['position'])) {
+                throw newInvalidPositionForInlineStrategyError(pathQueryParameters['position'], file);
+            }
+            inlinedAsset.position = pathQueryParameters['position'];
+        }
+        if (inlinedAsset.position !== 'before' && scriptArgsObject.strategy !== undefined) {
+            compilation.warnings.push((0, shared_1.newWebpackErrorForFile)("Deferred and async scripts that have inlined JS attached in the 'after' position will cause WordPress to convert all of their dependencies to eager scripts at runtime", file));
+        }
+        if (scriptArgsObject.in_footer === undefined) {
+            scriptArgsObject.in_footer = true;
+        }
+    }
+    const fetchpriority = pathQueryParameters['fetchpriority'];
+    if (fetchpriority !== undefined) {
+        if (!isValidFetchPriority(fetchpriority)) {
+            throw newInvalidFetchPriorityError(fetchpriority, file);
+        }
+        if (inlinedAsset !== undefined) {
+            compilation.warnings.push((0, shared_1.newWebpackErrorForFile)("Fetchpriority has no effect on inlined assets", file));
+        }
+        hasAnyKeys = true;
+        scriptArgsObject.fetchpriority = fetchpriority;
+    }
+    return hasAnyKeys ? { scriptArgsObject, inlinedAsset } : { inlinedAsset };
+}
+function removeFileAndAssetPHP(compilation, file) {
+    const pathParts = (0, node_path_1.parse)(file);
+    compilation.deleteAsset((0, node_path_1.join)(pathParts.dir, pathParts.name) + ".asset.php");
+    compilation.deleteAsset(file);
+}

package/build/wordpress-scripts-wrapper.js

@@ -25,6 +25,7 @@ const UnifiedLoaderGenerator_1 = require("./plugins/UnifiedLoaderGenerator");
 const copy_webpack_plugin_1 = __importDefault(require("copy-webpack-plugin"));
 const fork_ts_checker_webpack_plugin_1 = __importDefault(require("fork-ts-checker-webpack-plugin"));
 const webpack_remove_empty_scripts_1 = __importDefault(require("webpack-remove-empty-scripts"));
+const path_query_and_related_helpers_1 = require("./utils/path-query-and-related-helpers");
 function testForDuplicatedEntryPaths(sources) {
     const seenPaths = (0, common_config_helpers_1.groupEntrypointsByAssetFile)(Array.isArray(sources)
         ? sources.map(s => typeof s === 'string' ? s : s[1].destination)
@@ -188,15 +189,16 @@ function buildVerifiedConfig(config) {
             throw new Error("Plain Entrypoints V2 and higher require 'outputDir' to be set");
         }
     }
-    const normalizeSrcAndDestination = ([src, dest]) => {
+    const normalizeSrcAndDestination = ([rawSrc, dest]) => {
+        let [src, pathQueryParameters] = (0, path_query_and_related_helpers_1.unpackPotentiallyPrefixedFilePath)(rawSrc);
         if (srcDir) {
             src = (0, node_path_1.join)(srcDir, src);
         }
         src = (0, node_path_1.isAbsolute)(src) ? (0, node_path_1.relative)(process.cwd(), src) : src;
         if (dest.destination !== undefined && (0, node_path_1.isAbsolute)(dest.destination)) {
-            dest = { ...dest, destination: (0, node_path_1.relative)(process.cwd(), dest.destination) };
+            return [src, { ...dest, destination: (0, node_path_1.relative)(process.cwd(), dest.destination), pathQueryParameters }];
         }
-        return [src, dest];
+        return [src, { ...dest, pathQueryParameters }];
     };
     const rawSources = Array.isArray(config.src)
         ? config.src.map(s => normalizeSrcAndDestination([s, { destination: s }]))
@@ -221,29 +223,22 @@ function buildVerifiedConfig(config) {
     // Destination -> source map
     const allocatedDestinations = {};
     const partiallyVerifiedSources = rawSources.map(rawSource => {
-        const { destination, additionalDependencies = [], assumeGlobalizedPlauditLibraries = cfg.assumeGlobalizedPlauditLibraries, bundleAnalyzer = false, directoryLayout, externalize, withLegacyBlocksIn = false, lazyLoader } = rawSource[1];
+        const { destination, additionalDependencies = [], assumeGlobalizedPlauditLibraries = cfg.assumeGlobalizedPlauditLibraries, bundleAnalyzer = false, directoryLayout, externalize, withLegacyBlocksIn = false, lazyLoader, pathQueryParameters } = rawSource[1];
         const normalizedParts = { additionalDependencies, assumeGlobalizedPlauditLibraries, bundleAnalyzer, directoryLayout, externalize, withLegacyBlocksIn, lazyLoader };
         const locations = typeof rawSource[1].locations === 'string' || typeof rawSource[1].locations === 'function'
             ? { handle: rawSource[1].locations } : rawSource[1].locations ?? {};
-        let normalizedLocations;
-        if ((0, shared_1.isNormalizedUsageLocations)(locations)) {
-            normalizedLocations = locations;
-        }
-        else if (locations.registerScriptArgs === 'lazy') {
-            normalizedLocations = { ...locations, registerScriptArgs: { strategy: 'defer', in_footer: true } };
-        }
-        else {
-            throw new ReferenceError("The only supported string value for registerScript args is 'lazy'");
+        if (typeof locations.registerScriptArgs === 'string' && !['lazy', 'eager', 'inline'].includes(locations.registerScriptArgs)) {
+            throw new ReferenceError("The only supported string values for registerScriptArgs are 'lazy', 'eager', and 'inline'");
         }
         if (destination !== undefined) {
             const effectiveDestination = toEffectiveWebpackDestination(destination);
             allocatedDestinations[effectiveDestination] = rawSource[0]; // We need to pre-populate the allocatedDestinations map with statically-declared destinations
-            return [rawSource[0], { ...normalizedParts, locations: normalizedLocations, destination, effectiveDestination, staticallyDeclaredDestination: true }];
+            return [rawSource[0], { ...normalizedParts, locations, destination, effectiveDestination, staticallyDeclaredDestination: true, pathQueryParameters }];
         }
         else {
             const naiveDestination = deriveNaiveDestinationFromUnverifiedSourceEntry(rawSource, srcPrefixes);
             const effectiveDestination = toEffectiveWebpackDestination(naiveDestination);
-            return [rawSource[0], { ...normalizedParts, locations: normalizedLocations, destination: naiveDestination, effectiveDestination, staticallyDeclaredDestination: false }];
+            return [rawSource[0], { ...normalizedParts, locations, destination: naiveDestination, effectiveDestination, staticallyDeclaredDestination: false, pathQueryParameters }];
         }
     });
     const dynamicEffectiveDestinationsWithExpectedNaiveDuplicates = partiallyVerifiedSources

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@plaudit/webpack-extensions",
-  "version": "2.84.0",
+  "version": "2.85.0",
   "license": "SEE LICENSE IN LICENSE.md",
   "files": [
     "/build",
     "README.md",
     "LICENSE.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "USER-GUIDE.md"
   ],
   "exports": {
     "./wordpress-scripts-wrapper": "./build/wordpress-scripts-wrapper.js",
@@ -23,12 +24,11 @@
     }
   },
   "devDependencies": {
-    "@plaudit/gutenberg-api-extensions": "^2.84.3",
+    "@plaudit/gutenberg-api-extensions": "^2.87.0",
     "@types/browser-sync-webpack-plugin": "^2.2.5",
-    "@types/node": "^25.1.0",
+    "@types/node": "^25.3.4",
     "@types/postcss-functions": "^4.0.4",
     "@types/tapable": "^2.3.0",
-    "@types/webpack": "^5.28.5",
     "@types/webpack-sources": "^3.2.3",
     "postcss-load-config": "^4.0.2",
     "postcss-loader": "^7.3.4",
@@ -36,22 +36,22 @@
     "webpack-bundle-analyzer": "^4.10.2"
   },
   "dependencies": {
-    "@plaudit/php-writer": "^1.3.3",
+    "@plaudit/php-writer": "^1.4.1",
     "@plaudit/postcss-color-function": "^5.0.0",
     "@plaudit/postcss-legacy-shorthand": "^1.0.0",
     "@plaudit/postcss-silent-extend": "^3.0.0",
     "@plaudit/postcss-strip-units": "^3.0.0",
     "@plaudit/postcss-variables": "^1.1.0",
-    "@wordpress/dependency-extraction-webpack-plugin": "^6.39.0",
-    "@wordpress/scripts": "^31.4.0",
-    "autoprefixer": "^10.4.24",
+    "@wordpress/dependency-extraction-webpack-plugin": "^6.41.0",
+    "@wordpress/scripts": "^31.6.0",
+    "autoprefixer": "^10.4.27",
     "browser-sync": "^3.0.4",
     "copy-webpack-plugin": "10.2.4",
     "css-minimizer-webpack-plugin": "^6.0.0",
     "fork-ts-checker-webpack-plugin": "^9.1.0",
     "http-proxy-middleware": "^3.0.5",
     "json2php": "^0.0.12",
-    "postcss": "^8.5.6",
+    "postcss": "^8.5.8",
     "postcss-calc": "^9.0.1",
     "postcss-discard-comments": "^6.0.2",
     "postcss-functions": "^4.0.2",
@@ -63,7 +63,7 @@
     "postcss-reporter": "^7.1.0",
     "postcss-simple-vars": "^7.0.1",
     "postcss-url": "^10.1.3",
-    "webpack": "^5.104.1",
+    "webpack": "^5.105.4",
     "webpack-remove-empty-scripts": "^1.1.1",
     "xml-formatter": "^3.6.7"
   },