@ohos-ports/lwrjs-static 0.24.0-beta.1

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

@@ -0,0 +1,287 @@
+/**
+ * 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|ssr|l/en', {metadata}, isDebug, forSsr, {en-MX: [en-MX, en-US, en], en: [en], ...})
+ *
+ * The tree currently makes decisions in the following order: specifier, isDebug, version, forSsr and then locale.
+ *
+ * To find matching metadata, use the following commands:
+ *
+ * tree.find('bundle/foo|v/7_0|ssr|l/en-MX')
+ *
+ * tree.find('bundle/foo', isDebug, forSsr, 'en-US')
+ */
+import { logger } from '@lwrjs/diagnostics';
+import { LOCALE_SIGIL, SSR_SIGIL, VERSION_NOT_PROVIDED, VERSION_SIGIL, getFeatureFlags, 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 = '';
+// Boolean choice set available it marked true without requiring a value
+const CHOICE_TRUE = 'true';
+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, ssr, 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, ssr, localeId) {
+        const parsedArtifactId = parseSiteId(siteArtifactId);
+        const decisionPath = this.createArtifactChoices({
+            specifier: parsedArtifactId.specifier,
+            version: parsedArtifactId.variants[VERSION_SIGIL],
+            ssr: ssr ?? SSR_SIGIL in parsedArtifactId.variants,
+            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 path 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
+     * @param ssr flag if server bundle is requested
+     */
+    createArtifactChoices({ specifier, version, localeId, debug, ssr }) {
+        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);
+        const ssrChoice = ssr ? CHOICE_TRUE : CHOICE_EMPTY;
+        return this.getOrderedChoices(specifier, envChoice, ssrChoice, uriVersion, localeId);
+    }
+    /**
+     * Get the choices in a consistent order for possible choices or choices for lookup
+     */
+    getOrderedChoices(specifier, envChoice, ssrChoice, uriVersion, localeId) {
+        return [specifier, envChoice, ssrChoice, 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];
+        // If there is an ssr sigil always prefer it during SSR
+        const ssrChoice = match.variants[SSR_SIGIL] || CHOICE_EMPTY;
+        const ssr = getFeatureFlags().SSR_COMPILER_ENABLED
+            ? [ssrChoice]
+            : // For SSR V1 |ssr will prefer true non ssr will prefer empty
+                match.variants[SSR_SIGIL]
+                    ? [CHOICE_TRUE, CHOICE_EMPTY]
+                    : [CHOICE_EMPTY, CHOICE_TRUE];
+        const localeChoice = match.variants[LOCALE_SIGIL];
+        // If there are no fallbacks, or localeChoice is not in fallbacks use the ['*'] wildcard choice
+        const localeId = localeFallbacks?.[localeChoice] ?? [CHOICE_WILDCARD];
+        return this.getOrderedChoices([specifier], envChoice, ssr, 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

@@ -0,0 +1,77 @@
+{
+    "name": "@ohos-ports/lwrjs-static",
+    "license": "MIT",
+    "publishConfig": {
+        "access": "public"
+    },
+    "version": "0.24.0-beta.1",
+    "homepage": "https://github.com/ohos-ports/ohos-ports/tree/main/ports/lwrjs-static/0.24.0",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/ohos-ports/ohos-ports.git",
+        "directory": "ports/lwrjs-static/0.24.0"
+    },
+    "bugs": {
+        "url": "https://github.com/ohos-ports/ohos-ports/issues"
+    },
+    "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"
+        },
+        "./asset-provider": {
+            "import": "./build/es/providers/static-asset-provider.js",
+            "require": "./build/cjs/providers/static-asset-provider.cjs"
+        },
+        "./bundle-provider": {
+            "import": "./build/es/providers/static-bundle-provider.js",
+            "require": "./build/cjs/providers/static-bundle-provider.cjs"
+        },
+        "./module-provider": {
+            "import": "./build/es/providers/static-module-provider.js",
+            "require": "./build/cjs/providers/static-module-provider.cjs"
+        },
+        "./resource-provider": {
+            "import": "./build/es/providers/static-resource-provider.js",
+            "require": "./build/cjs/providers/static-resource-provider.cjs"
+        },
+        "./mrt-static-uri-transformer": {
+            "import": "./build/es/transformers/mrt-static-uri-transformer.js",
+            "require": "./build/cjs/transformers/mrt-static-uri-transformer.cjs"
+        }
+    },
+    "scripts": {
+        "build": "tsc -b",
+        "clean": "rimraf build node_modules",
+        "test": "jest"
+    },
+    "files": [
+        "build/**/*.js",
+        "build/**/*.cjs",
+        "build/**/*.d.ts"
+    ],
+    "dependencies": {
+        "@lwrjs/diagnostics": "0.24.0",
+        "@lwrjs/instrumentation": "0.24.0",
+        "@lwrjs/shared-utils": "0.24.0",
+        "fs-extra": "^11.4.0",
+        "lru-cache": "^10.4.3"
+    },
+    "devDependencies": {
+        "@lwrjs/types": "0.24.0",
+        "@types/express": "^4.17.21",
+        "jest": "29.7.0",
+        "jest-express": "^1.12.0",
+        "memfs": "^4.13.0",
+        "mock-res": "^0.6.0",
+        "ts-jest": "^29.2.6"
+    },
+    "engines": {
+        "node": ">=22.0.0"
+    }
+}