@lwrjs/static 0.13.0-alpha.6 → 0.13.0-alpha.8

package/build/es/utils/decision-tree.js

@@ -0,0 +1,267 @@
+/**
+ * A decision tree is used to determine the best static site artifact metadata based on criteria such as specifier, version, isDebug, locale, and additional variants.
+ *
+ * This tree processes all the metadata for a specific type of artifact (bundle, asset, or resource), finding the best match based on the provided input.
+ *
+ * It operates on general decision tree principles, using tree nodes to navigate individual choices and identify the most suitable metadata.
+ *
+ * The tree is populated once by providing a set of possible matching conditions.
+ *
+ * tree.insert('bundle/foo|v/7_0|l/en', {metadata}, isDebug, {en-MX: [en-MX, en-US, en], en: [en], ...})
+ *
+ * The tree currently makes decisions in the following order: specifier, isDebug, version, and then locale.
+ *
+ * To find matching metadata, use the following commands:
+ *
+ * tree.find('bundle/foo|v/7_0|l/en-MX')
+ *
+ * tree.find('bundle/foo', isDebug, 'en-US')
+ */
+import { logger } from '@lwrjs/diagnostics';
+import { LOCALE_SIGIL, VERSION_NOT_PROVIDED, VERSION_SIGIL, normalizeVersionToUri, } from '@lwrjs/shared-utils';
+import { parseSiteId } from '../site-metadata.js';
+// Choice wildcard means I want to match anything
+// Examples are any locale and match the default locale
+const CHOICE_WILDCARD = '*';
+// Choice empty is explicitly an empty choice
+// This is useful for scenarios like an empty version can match any version
+// This cannot be wildcard since we want an explicit version to also not match this choice.
+const CHOICE_EMPTY = '';
+const CHOICE_PROD = 'prod';
+const CHOICE_DEBUG = 'debug';
+// Tree of decisions to lead you to the right artifact
+export default class DecisionTreeImpl {
+    constructor() {
+        this.root = new TreeNode(); // Root node does not hold any decision value
+    }
+    // Insert an artifact into the tree based on a path of decisions
+    insert(siteArtifactId, artifact, debug, localeFallbacks) {
+        //  The decision path is the set of choices needed to get to the right metadata
+        // Currently this is hard coded to [specifier, isDebug, version, locale]
+        const decisionPath = this.createPossibleArtifactChoices({
+            id: siteArtifactId,
+            localeFallbacks,
+            debug,
+        });
+        // The set of choices in the root decision (specifier)
+        const choices = decisionPath[0];
+        // This would only be true if we ever had a decision tree with one choice (for now we expect this to always be false)
+        const isLeaf = decisionPath.length == 1;
+        // Set of valid choices in the root decision (specifier) only expected choice here is the exact specifier
+        for (const [index, key] of choices.entries()) {
+            // We will chose the ranked choice on every node along the decision to keep track of the preferred choice at each node
+            const rank = [index];
+            // If we have note made a node for the root choice (specifier) create one
+            if (!this.root.getChild(key, false)) {
+                this.root.addChild(key, new TreeNode(key, ''));
+            }
+            const nextNode = this.root.getChild(key, false);
+            // Not expected this would only be a leaf if there we no other decisions to be made
+            if (isLeaf) {
+                nextNode.setArtifact(artifact, rank);
+            }
+            else {
+                // If it's not a leaf, prepare for the next iteration
+                // We need to iterate over each choice separately to maintain distinct paths
+                this.deepInsert(1, decisionPath, key, nextNode, artifact, rank);
+            }
+        }
+    }
+    /**
+     * A method to handle deeper insertions, preserving the unique paths.
+     * This will be called for each node in the decision path.
+     */
+    deepInsert(level, decisionPath, currentPath, currentNode, artifact, rank) {
+        // No more choices for you
+        if (level >= decisionPath.length)
+            return;
+        // Get the set of choice for this node
+        const choices = decisionPath[level];
+        // Is this the last node in the decision path?
+        const isLeaf = level === decisionPath.length - 1;
+        for (const [index, key] of choices.entries()) {
+            // If this is a wild card mark it as WILD_CARD_RANK so we force it to be the last choice
+            const nextRank = [...rank, index];
+            if (!currentNode.getChild(key, false)) {
+                currentNode.addChild(key, new TreeNode(key, currentPath));
+            }
+            const nextNode = currentNode.getChild(key, false);
+            if (isLeaf) {
+                nextNode.setArtifact(artifact, nextRank);
+            }
+            else {
+                this.deepInsert(level + 1, decisionPath, `${currentPath}/${key}`, nextNode, artifact, nextRank);
+            }
+        }
+    }
+    // Retrieve an artifact from the tree based on a path of decisions
+    find(siteArtifactId, debug, localeId) {
+        const parsedArtifactId = parseSiteId(siteArtifactId);
+        const decisionPath = this.createArtifactChoices({
+            specifier: parsedArtifactId.specifier,
+            version: parsedArtifactId.variants[VERSION_SIGIL],
+            localeId: localeId ?? parsedArtifactId.variants[LOCALE_SIGIL],
+            debug,
+        });
+        let currentNode = this.root;
+        for (const key of decisionPath) {
+            const lastPath = currentNode.getPath();
+            currentNode = currentNode.getChild(key);
+            if (!currentNode) {
+                logger.debug(`Module ${key} not found at ${lastPath}`);
+                return undefined; // Decision path does not lead to an artifact
+            }
+        }
+        if (!currentNode.artifact) {
+            logger.debug(`Artifact not found at ${currentNode.getPath()}`);
+        }
+        return currentNode.artifact;
+    }
+    /**
+     * Create a decision tree patch to look up the most appropriate bundle
+     *
+     * @param specifier Bundle specifier
+     * @param version known version or will add the choice ''
+     * @param localeId preferred bundle locale or will add '' for default locale
+     * @param debug flag if debug bundle is preferred
+     */
+    createArtifactChoices({ specifier, version, localeId, debug }) {
+        const envChoice = debug ? CHOICE_DEBUG : CHOICE_PROD;
+        // Versions are stored in the bundle id in URL normalized form
+        const versionChoice = getVersionChoice(version);
+        const uriVersion = normalizeVersionToUri(versionChoice);
+        return [specifier, envChoice, uriVersion, localeId || CHOICE_WILDCARD];
+    }
+    createPossibleArtifactChoices({ id, localeFallbacks, debug, }) {
+        const match = parseSiteId(id);
+        const specifier = match.specifier;
+        if (!specifier) {
+            // TODO make diagnostic error
+            throw new Error(`Unable to parse${debug ? ' debug' : ''} static bundle specifier: ${id}`);
+        }
+        // Try to parse a version out of the specifier
+        const versionChoice = getVersionChoice(match.variants[VERSION_SIGIL]);
+        // To make it so that if you ask for a version it will only match an explicit version from the metadata.
+        // I think this will cause a breaking change?
+        // Un comment to all versioned requests to fall back to *
+        // const versions = [...new Set([versionChoice, CHOICE_WILDCARD])];
+        const versions = versionChoice === CHOICE_EMPTY
+            ? [...new Set([CHOICE_EMPTY, CHOICE_WILDCARD])]
+            : [...new Set([versionChoice, CHOICE_EMPTY])];
+        const envChoice = debug ? [CHOICE_DEBUG] : [CHOICE_PROD];
+        const localeChoice = match.variants[LOCALE_SIGIL];
+        const localeId = localeChoice && localeFallbacks ? localeFallbacks[localeChoice] : [CHOICE_WILDCARD];
+        return [[specifier], envChoice, versions, localeId];
+    }
+}
+/**
+ * This represents a single node on the decision path, corresponding to a specific value for a decision criterion (e.g., specifier, isDebug, version, locale).
+ * If it's a leaf node, it points to an artifact's metadata.
+ * It maintains the rank of all choices at this node, allowing a later node with a higher rank to replace the current one as the best option.
+ */
+class TreeNode {
+    constructor(value = '', parentPath = '') {
+        this.children = new Map(); // Maps a decision key to the next TreeNode
+        this.artifact = undefined; // Final artifact at a leaf node
+        this.decisionValue = value;
+        this.parentPath = parentPath;
+    }
+    // Adds a child node based on a decision key
+    addChild(value, node) {
+        this.children.set(value, node);
+    }
+    // Sets the artifact at a leaf node
+    setArtifact(artifact, rank) {
+        if (this.artifact && isLowerOrEqualRank(rank, this.rank)) {
+            logger.debug({
+                label: 'DecisionTree',
+                message: `Ignored Artifact ${this.getPath()} ${this.rank} <= ${rank}`,
+            });
+            return;
+        }
+        logger.debug({
+            label: 'DecisionTree',
+            message: `Added artifact at ${this.getPath()}`,
+        });
+        this.rank = rank;
+        this.artifact = artifact;
+    }
+    // Retrieves a child node based on a decision key
+    getChild(key, allowWildcard = true) {
+        return allowWildcard
+            ? this.children.get(key) || this.children.get(CHOICE_WILDCARD)
+            : this.children.get(key);
+    }
+    getPath() {
+        return this.parentPath ? this.parentPath + '|' + this.decisionValue : this.decisionValue;
+    }
+}
+// If any choice was lower ranked choose this artifact
+function isLowerOrEqualRank(contender, existing) {
+    // If existing path is undefined, we can consider the contender as lower ranked
+    // because there's nothing to compare against.
+    if (!existing) {
+        return true;
+    }
+    // Should not happen placed here to be sure
+    if (existing.length !== contender.length) {
+        throw new Error(`Paths must be of the same length ${existing} not found at ${contender}`);
+    }
+    // Iterate over each decision point to compare choices
+    for (let i = 0; i < existing.length; i++) {
+        // If the contender has made a choice with a higher index at any decision point,
+        // it means the contender is of a lower rank.
+        if (contender[i] > existing[i]) {
+            return true; // Contender is of a lower rank
+        }
+        else if (contender[i] < existing[i]) {
+            // If the contender has a choice with a lower index at any point, it's not of a lower rank.
+            return false;
+        }
+        // If the choices are the same, continue to the next decision point.
+    }
+    // If all choices are the same, the contender is equal rank.
+    return true;
+}
+/**
+ * Returns the version or if empty or undefined it will return a wild card and match
+ * an explicity un-versioned or the first match from the bundle metadata
+ */
+function getVersionChoice(version) {
+    // If the version if empty or explicity version-not-provided
+    // return an empty choice to indicate that this an a value not provided
+    // so that it can match an explicit empty or wild card choice.
+    if (!version || version === VERSION_NOT_PROVIDED) {
+        return CHOICE_EMPTY;
+    }
+    // If there is a version use normalizeVersionToUri to convert it to a how it will be requested
+    return normalizeVersionToUri(version);
+}
+export function createFallbackMap(config) {
+    const map = {};
+    // Helper function to recursively find fallbacks
+    function findFallbacks(localeId, visited = new Set()) {
+        // Prevent cycles by checking if we've already visited this locale
+        if (visited.has(localeId) || localeId === config.defaultLocale) {
+            return [];
+        }
+        visited.add(localeId);
+        const locale = config.locales.find((l) => l.id === localeId);
+        if (!locale || !locale.fallback) {
+            return [localeId];
+        }
+        // Recursively find fallbacks, adding the current localeId to the start
+        return [localeId, ...findFallbacks(locale.fallback, visited)];
+    }
+    config.locales.forEach((locale) => {
+        // default will be wild carded
+        if (locale.id !== config.defaultLocale) {
+            // Initialize the fallbacks array for each locale, including the default as an implied fallback
+            map[locale.id] = [...new Set([...findFallbacks(locale.id)])];
+        }
+    });
+    // Setup a default locale under key '*'
+    map[CHOICE_WILDCARD] = [CHOICE_WILDCARD];
+    return map;
+}
+//# sourceMappingURL=decision-tree.js.map

package/package.json

@@ -4,7 +4,7 @@
     "publishConfig": {
         "access": "public"
     },
-    "version": "0.13.0-alpha.6",
+    "version": "0.13.0-alpha.8",
     "homepage": "https://developer.salesforce.com/docs/platform/lwr/overview",
     "repository": {
         "type": "git",
@@ -16,6 +16,10 @@
     },
     "type": "module",
     "exports": {
+        ".": {
+            "import": "./build/es/index.js",
+            "require": "./build/cjs/index.cjs"
+        },
         "./site-metadata": {
             "import": "./build/es/site-metadata.js",
             "require": "./build/cjs/site-metadata.cjs"
@@ -48,11 +52,11 @@
         "build/**/*.d.ts"
     ],
     "dependencies": {
-        "@lwrjs/diagnostics": "0.13.0-alpha.6",
-        "@lwrjs/shared-utils": "0.13.0-alpha.6"
+        "@lwrjs/diagnostics": "0.13.0-alpha.8",
+        "@lwrjs/shared-utils": "0.13.0-alpha.8"
     },
     "devDependencies": {
-        "@lwrjs/types": "0.13.0-alpha.6",
+        "@lwrjs/types": "0.13.0-alpha.8",
         "@types/express": "^4.17.21",
         "jest": "^26.6.3",
         "jest-express": "^1.12.0",
@@ -65,5 +69,5 @@
     "volta": {
         "extends": "../../../package.json"
     },
-    "gitHead": "88d503249ff6b135416208763fae8a33b5e874de"
+    "gitHead": "91e731eae1457bbbebeb274fa0ea5574705c51a2"
 }

package/build/es/utils/static-utils.d.ts

@@ -1,12 +0,0 @@
-import type { I18NConfig, SiteBundle, SiteBundles } from '@lwrjs/types';
-/**
- * Return the version for a static module bundle.
- *
- * Version defined in the metadata > Requested Version > 'version-not-provided'
- */
-export declare function resolveStaticBundleVersion(metadataVersion?: string, requestedVersion?: string): string;
-/**
- * Get the most best match for a localized bundle
- */
-export declare function getLocalizedBundle(specifier: string, siteBundles: SiteBundles, initialLocaleId: string, i18n: I18NConfig): Promise<SiteBundle | undefined>;
-//# sourceMappingURL=static-utils.d.ts.map

package/build/es/utils/static-utils.js

@@ -1,23 +0,0 @@
-/**
- * Try to add any code that is mrt specific here so that we can isolate details that would have to be refactored to run lambdas
- * on a different platform
- */
-import { VERSION_NOT_PROVIDED, walkLocaleFallbacks } from '@lwrjs/shared-utils';
-/**
- * Return the version for a static module bundle.
- *
- * Version defined in the metadata > Requested Version > 'version-not-provided'
- */
-export function resolveStaticBundleVersion(metadataVersion, requestedVersion) {
-    return metadataVersion || requestedVersion || VERSION_NOT_PROVIDED;
-}
-/**
- * Get the most best match for a localized bundle
- */
-export async function getLocalizedBundle(specifier, siteBundles, initialLocaleId, i18n) {
-    return walkLocaleFallbacks(initialLocaleId, i18n, async (localeId) => {
-        const localizedSpecifier = localeId === i18n.defaultLocale ? specifier : `${specifier}|l/${localeId}`;
-        return siteBundles.bundles[localizedSpecifier];
-    });
-}
-//# sourceMappingURL=static-utils.js.map