@expofp/config 3.11.10

package/dist/lib/visit-resources.js

@@ -0,0 +1,198 @@
+/**
+ * visit-resources — the one schema-guided resource walk, used for both jobs:
+ *
+ * - **Absolutization** (`documentRef`): every ref the config mints carries a
+ *   `process` hook = "validate with my schema, then walk me with a handler
+ *   that rebases relative paths onto the ref's own directory". Resolution
+ *   therefore always settles documents whose asset URLs are absolute.
+ * - **Serialization** (`serializeConfigResources`): the same walk over the
+ *   whole config with a storage handler — and a `$ref` is just another kind
+ *   of asset, one whose handling resolves the document and recurses into it.
+ *
+ * The walk is value-driven and schema-guided: meta tags say what a string
+ * leaf holds (`asset`, `svgAsset`, `cssAsset`), and a
+ * `{ $ref }` object is an external document (its node's `refSchema` meta
+ * points at the document's schema).
+ * Which behaviors fire falls out of which hooks the handler provides — a
+ * handler without `document` leaves refs alone. `value` is mutated in place
+ * and must be an object or array.
+ */
+import { getResolved, isResolved, resolve } from '@expofp/resolve';
+import { deepClone } from '@expofp/utils';
+import { refSchemaOf, toJsonSchema, typeMatches } from './json-schema.js';
+import { collectCssUrls, collectSvgImageHrefs, inlineCssImports, isAbsoluteUrl, refDirectory, rewriteCssUrls, rewriteSvgImageHrefs, toAbsoluteUrl, } from './resource-urls.js';
+import { timeValidation } from './validate-timing.js';
+/**
+ * Gates every schema validation (`parse`) of the large expo documents —
+ * manifest, data.js, drawing/wayfinding payloads. The schemas are loose and
+ * transform-free, so a validating parse is also a faithful copy — which is
+ * exactly what {@link validateOrClone} exploits.
+ *
+ * OFF by default (parsing the large documents costs time); `loadConfig` flips it
+ * per page load via {@link setValidateManifest} from the `validateSchema` opt-in
+ * (`?validateSchema=1` / `efp-validateSchema`). Module-level, tracking the
+ * page-global URL/localStorage flag, so concurrent loads on a page agree.
+ */
+let validateManifest = false;
+/** Set by `loadConfig` from the `validateSchema` flag; gates the parses below. */
+export function setValidateManifest(on) {
+    validateManifest = on;
+}
+/**
+ * An own, mutable copy of a document — validated when the flag is on.
+ *
+ * Every consumer of a resolved document needs its own copy anyway (`resolve`
+ * deep-freezes what it settles, and downstream code mutates in place), and a
+ * Zod parse of these loose, transform-free schemas already IS a fresh copy.
+ * So validation rides the copy that had to be made regardless: parse when
+ * validating, `deepClone` when not — one copy either way, never two.
+ */
+export function validateOrClone(schema, value) {
+    if (validateManifest)
+        return timeValidation(() => schema.parse(value));
+    return deepClone(value);
+}
+/**
+ * Decorate a ref with the one processing rule for referenced documents: take
+ * an own copy — validated against `schema` when the flag is on (see
+ * `validateOrClone`) — then make every schema-tagged resource path absolute
+ * against the ref's own directory — the standard web rule for a live load.
+ * An optional `normalize` hook runs on the copy in between: it folds legacy
+ * shape quirks onto the canonical keys, so the schema-guided walk (and every
+ * consumer) sees the canonical shape (e.g. `normalizeFpSvgLayerAliases`).
+ *
+ * An offline copy instead references its saved documents by *relative*
+ * (page-relative, host-less) paths, and their assets already carry final
+ * serialized paths. Rebasing one of those onto the doc's own relative
+ * directory would double the path (`…/<doc-dir>/<doc-dir>/asset` → 404), so
+ * absolutization is skipped whenever the ref's directory is not itself
+ * absolute — the runtime then resolves the page-relative asset against the
+ * page, wherever the copy is mounted. (A rooted `/…` offline ref stays
+ * absolute, and its already-rooted assets pass through unchanged either way.)
+ *
+ * The rewrite runs on an own copy, so it never touches the fetch-cached raw
+ * document.
+ */
+export function documentRef(ref, schema, normalize) {
+    const process = async (raw, refUrl) => {
+        const document = validateOrClone(schema, raw); // referenced documents are objects
+        normalize?.(document);
+        // A relative ref directory means an offline copy: the document's assets are
+        // already final serialized paths, so rebasing them here would double the path.
+        const base = refDirectory(refUrl);
+        const rebase = isAbsoluteUrl(base);
+        await visitResources(schema, document, {
+            asset: (url) => (rebase ? toAbsoluteUrl(url, base) : url),
+        });
+        return document;
+    };
+    return { ...ref, process };
+}
+/** Rewrite every schema-tagged resource of `value` through `handler`, in place. */
+export async function visitResources(schema, value, handler, options) {
+    await walk(toJsonSchema(schema), value, unassignableRoot, handler, options);
+}
+async function walk(node, value, assign, handler, options) {
+    if (value === null || value === undefined)
+        return;
+    // follow unions down to the branch that fits the value
+    const branches = node?.anyOf ?? node?.oneOf;
+    if (branches) {
+        const branch = branches.find((candidate) => typeMatches(candidate, value));
+        return walk(branch, value, assign, handler, options);
+    }
+    // "$ref is an asset": an external document, when the handler wants them.
+    // Rooted refs are already local — honored verbatim, like every other
+    // rooted resource URL.
+    if (isRefShaped(value)) {
+        if (!handler.document || value.$ref.startsWith('/'))
+            return;
+        const refUrl = value.$ref;
+        try {
+            const documentSchema = node ? refSchemaOf(node) : undefined;
+            // Reuse the warm memo (eagerly-loaded refs settled processed documents);
+            // a cold ref is re-minted with its document schema — the walked value is
+            // a JSON copy, so the original decoration did not survive into it.
+            const resolved = isResolved(value)
+                ? getResolved(value)
+                : await resolve(documentSchema ? documentRef({ $ref: refUrl }, documentSchema) : { $ref: refUrl }, { signal: options?.signal });
+            const copy = { document: deepClone(resolved) };
+            if (documentSchema) {
+                await walk(toJsonSchema(documentSchema), copy.document, (v) => {
+                    copy.document = v;
+                }, handler, options);
+            }
+            assign({ $ref: await handler.document(refUrl, copy.document) });
+        }
+        catch (error) {
+            if (!handler.documentError)
+                throw error;
+            handler.documentError(refUrl, error);
+            assign(undefined); // the field is dropped
+        }
+        return;
+    }
+    if (typeof value === 'string') {
+        if (node?.asset && value) {
+            assign(await handler.asset(value, node.optionalAsset));
+        }
+        else if (node?.svgAsset) {
+            const rewrites = new Map();
+            for (const href of collectSvgImageHrefs(value)) {
+                rewrites.set(href, await handler.asset(href));
+            }
+            assign(rewriteSvgImageHrefs(value, (href) => rewrites.get(href) ?? href));
+        }
+        else if (node?.cssAsset) {
+            // a handler that can fetch stylesheets gets @imports spliced in first,
+            // so the pass below localizes the assets they pull in (fonts etc.)
+            let css = value;
+            let external = new Set();
+            if (handler.stylesheetText) {
+                ({ css, external } = await inlineCssImports(css, handler.stylesheetText.bind(handler)));
+            }
+            const rewrites = new Map();
+            for (const url of collectCssUrls(css)) {
+                if (external.has(url))
+                    continue; // a kept @import's URL stays remote
+                // only scheme-qualified CSS urls are fetchable resources (legacy parity)
+                if (/^[a-z][a-z0-9+.-]*:/i.test(url)) {
+                    rewrites.set(url, await handler.asset(url));
+                }
+            }
+            assign(rewriteCssUrls(css, (url) => rewrites.get(url) ?? url));
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index++) {
+            await walk(node?.items, value[index], (v) => {
+                value[index] = v;
+            }, handler, options);
+        }
+        return;
+    }
+    if (typeof value === 'object') {
+        const container = value;
+        // `z.record(...)` keys are dynamic, so the value schema rides on
+        // `additionalProperties`, not `properties` (e.g. `fpSvgLayerJsRefs`, whose
+        // per-layer `$ref` must resolve + localize like any other). Fall back to it
+        // so record values are walked, not skipped as untyped and left verbatim.
+        const additional = typeof node?.additionalProperties === 'object' ? node.additionalProperties : undefined;
+        for (const key of Object.keys(container)) {
+            await walk(node?.properties?.[key] ?? additional, container[key], (v) => {
+                if (v === undefined)
+                    delete container[key];
+                else
+                    container[key] = v;
+            }, handler, options);
+        }
+    }
+}
+function isRefShaped(value) {
+    return (typeof value === 'object' && value !== null && '$ref' in value && typeof value.$ref === 'string');
+}
+/** The root is an object/array container — leaves rewrite inside it. */
+function unassignableRoot() {
+    throw new Error('visitResources: the top-level value must be an object or array');
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@expofp/config",
+  "version": "3.11.10",
+  "type": "module",
+  "description": "ExpoFP SDK internal: config layer and schemas",
+  "homepage": "https://developer.expofp.com/",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@expofp/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo",
+    "!**/*.map"
+  ],
+  "dependencies": {
+    "debug": "^4.4.3",
+    "tslib": "^2.3.0",
+    "zod": "4.3.5",
+    "@expofp/resolve": "3.11.12",
+    "@expofp/schema": "3.11.12",
+    "@expofp/utils": "3.11.12"
+  }
+}