@expofp/utils 3.11.12 → 3.12.0

package/dist/index.d.ts

@@ -3,12 +3,15 @@ export * from './lib/clone.js';
 export * from './lib/deep-freeze.js';
 export * from './lib/fetch-with-retry.js';
 export * from './lib/import-fs-promises.js';
+export * from './lib/import-js-as-json.js';
 export * from './lib/import-json.js';
 export * from './lib/import-node-module.js';
 export * from './lib/import-runtime-json.js';
 export * from './lib/load-script.js';
 export * from './lib/make-local-path.js';
 export * from './lib/read-file-from-url.js';
+export * from './lib/safe-decode.js';
+export * from './lib/safe-local-storage.js';
 export * from './lib/safe-slugify.js';
 export * from './lib/short-hash.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -3,11 +3,14 @@ export * from './lib/clone.js';
 export * from './lib/deep-freeze.js';
 export * from './lib/fetch-with-retry.js';
 export * from './lib/import-fs-promises.js';
+export * from './lib/import-js-as-json.js';
 export * from './lib/import-json.js';
 export * from './lib/import-node-module.js';
 export * from './lib/import-runtime-json.js';
 export * from './lib/load-script.js';
 export * from './lib/make-local-path.js';
 export * from './lib/read-file-from-url.js';
+export * from './lib/safe-decode.js';
+export * from './lib/safe-local-storage.js';
 export * from './lib/safe-slugify.js';
 export * from './lib/short-hash.js';

package/dist/lib/import-js-as-json.d.ts

@@ -0,0 +1,52 @@
+export interface EvalJsToJsonOptions {
+    /**
+     * If set, return only these top-level names (missing ones are skipped) instead
+     * of every assigned global. Useful when a script assigns noise you don't want.
+     */
+    pick?: readonly string[];
+    /**
+     * Extra globals seeded into the sandbox before running — e.g. a `console` or a
+     * stub `document` the script expects. Seeded keys are inputs and are omitted
+     * from the result (unless the script overwrites one and you `pick` it).
+     */
+    globals?: Record<string, unknown>;
+}
+export interface ImportJsAsJsonOptions extends EvalJsToJsonOptions {
+    signal?: AbortSignal | null;
+}
+/**
+ * Evaluate a standalone (non-module) JavaScript snippet and return everything it
+ * assigned to the global scope as a plain object. **Works in both the browser and
+ * Node.js** — no `eval`-free CSP required beyond `unsafe-eval` (see caveats).
+ *
+ * The snippet runs inside `with (sandbox) { … }`, where `sandbox` is a Proxy that
+ * traps every free identifier. So, with no need to know the names in advance:
+ * - top-level `var` declarations (`var __data = {…}`) land in the sandbox
+ * - bare and browser-style assignments (`__x = …`, `window['__paths'] = …`,
+ *   `self.x = …`), including dynamically-named ones (`window['__p' + i] = …`)
+ * - built-ins the script reads (`JSON`, `Math`, `document`, `fetch`, …) fall
+ *   through to the real global object
+ *
+ * Not captured: top-level `let`/`const` and `function` *declarations* — they bind
+ * to the wrapper's own scope, not the sandbox. Values are whatever the script
+ * assigned, so the result is JSON-shaped only if the script assigned JSON-shaped
+ * values.
+ *
+ * Caveats — this is a data extractor, not a sandbox:
+ * - Requires `Proxy` and dynamic code eval; a strict CSP without `unsafe-eval`
+ *   (or an ancient pre-`Proxy` WebView) will make it throw.
+ * - The script gets full access to the host's real globals and runs synchronously
+ *   with no timeout or isolation. **Only evaluate code you trust** — validating the
+ *   source's origin/trust is the caller's job.
+ */
+export declare function evalJsToJson<T = Record<string, unknown>>(code: string, options?: EvalJsToJsonOptions): T;
+/**
+ * Load a standalone JavaScript file and return its global assignments as a plain
+ * object. Fetches `http(s):` URLs (browser or Node) and reads `file:` URLs (Node
+ * only). Thin loader around {@link evalJsToJson} — see it for capture rules and
+ * the trust caveat.
+ *
+ * @param url Absolute `http:`/`https:` URL (any environment) or `file:` URL (Node).
+ */
+export declare function importJsAsJson<T = Record<string, unknown>>(url: string, options?: ImportJsAsJsonOptions): Promise<T>;
+//# sourceMappingURL=import-js-as-json.d.ts.map

package/dist/lib/import-js-as-json.js

@@ -0,0 +1,124 @@
+/// <reference lib="dom" />
+import debug from 'debug';
+import { fetchWithRetry } from './fetch-with-retry.js';
+const log = debug('efp:utils:importJsAsJson');
+/**
+ * Import a Node.js builtin without the browser bundler trying to resolve it: the
+ * specifier is a runtime variable marked `@vite-ignore`, so Vite/Rollup leave it
+ * as a plain dynamic import. Only reached for `file:` URLs, which are Node-only.
+ */
+async function importNodeBuiltin(specifier) {
+    return (await import(/* @vite-ignore */ specifier));
+}
+/** The real global object, looked up defensively (older WebViews lack `globalThis`). */
+const globalRef = typeof globalThis !== 'undefined'
+    ? globalThis
+    : typeof self !== 'undefined'
+        ? self
+        : typeof window !== 'undefined'
+            ? window
+            : {};
+/**
+ * Identifiers pointed back at the sandbox so browser-style scripts (`window.x = …`,
+ * `self.y = …`) run unmodified. Treated as inputs — never part of the result.
+ */
+const SELF_REFERENCE_GLOBALS = ['window', 'self', 'globalThis'];
+/**
+ * Evaluate a standalone (non-module) JavaScript snippet and return everything it
+ * assigned to the global scope as a plain object. **Works in both the browser and
+ * Node.js** — no `eval`-free CSP required beyond `unsafe-eval` (see caveats).
+ *
+ * The snippet runs inside `with (sandbox) { … }`, where `sandbox` is a Proxy that
+ * traps every free identifier. So, with no need to know the names in advance:
+ * - top-level `var` declarations (`var __data = {…}`) land in the sandbox
+ * - bare and browser-style assignments (`__x = …`, `window['__paths'] = …`,
+ *   `self.x = …`), including dynamically-named ones (`window['__p' + i] = …`)
+ * - built-ins the script reads (`JSON`, `Math`, `document`, `fetch`, …) fall
+ *   through to the real global object
+ *
+ * Not captured: top-level `let`/`const` and `function` *declarations* — they bind
+ * to the wrapper's own scope, not the sandbox. Values are whatever the script
+ * assigned, so the result is JSON-shaped only if the script assigned JSON-shaped
+ * values.
+ *
+ * Caveats — this is a data extractor, not a sandbox:
+ * - Requires `Proxy` and dynamic code eval; a strict CSP without `unsafe-eval`
+ *   (or an ancient pre-`Proxy` WebView) will make it throw.
+ * - The script gets full access to the host's real globals and runs synchronously
+ *   with no timeout or isolation. **Only evaluate code you trust** — validating the
+ *   source's origin/trust is the caller's job.
+ */
+export function evalJsToJson(code, options) {
+    if (typeof Proxy === 'undefined') {
+        throw new Error('evalJsToJson requires Proxy, which is unavailable in this environment');
+    }
+    const seeded = options?.globals ?? {};
+    const sandbox = { ...seeded };
+    const handler = {
+        // Trap every identifier lookup inside the `with` block into the sandbox…
+        has: () => true,
+        get: (target, key) => {
+            // …except `Symbol.unscopables`, which `with` consults to decide bindings.
+            if (key === Symbol.unscopables)
+                return undefined;
+            // Point window/self/globalThis at the sandbox so `window.x = …` lands here.
+            if (typeof key === 'string' && SELF_REFERENCE_GLOBALS.includes(key))
+                return scope;
+            // Script-assigned globals win; otherwise fall through to the real globals
+            // (JSON, Math, document, …) so the snippet can actually run.
+            if (key in target)
+                return target[key];
+            return globalRef[key];
+        },
+        set: (target, key, value) => {
+            target[key] = value;
+            return true;
+        },
+    };
+    const scope = new Proxy(sandbox, handler);
+    // A Function-constructed body is always sloppy-mode (even inside this strict ESM
+    // module), so `with` is legal here. The trailing newline stops a `//` line comment
+    // at the end of `code` from swallowing the closing brace.
+    // eslint-disable-next-line @typescript-eslint/no-implied-eval -- evaluating the legacy `.js` payload is the whole purpose of this module
+    const run = new Function('__scope__', `with(__scope__){${code}\n}`);
+    run(scope);
+    const excluded = new Set([...SELF_REFERENCE_GLOBALS, ...Object.keys(seeded)]);
+    return collectGlobals(sandbox, excluded, options?.pick);
+}
+/**
+ * Load a standalone JavaScript file and return its global assignments as a plain
+ * object. Fetches `http(s):` URLs (browser or Node) and reads `file:` URLs (Node
+ * only). Thin loader around {@link evalJsToJson} — see it for capture rules and
+ * the trust caveat.
+ *
+ * @param url Absolute `http:`/`https:` URL (any environment) or `file:` URL (Node).
+ */
+export async function importJsAsJson(url, options) {
+    log('Loading JS from', url);
+    const code = await loadJsSource(url, options?.signal ?? null);
+    return evalJsToJson(code, options);
+}
+async function loadJsSource(url, signal) {
+    const parsed = new URL(url);
+    if (parsed.protocol === 'file:') {
+        log('Read from file system', url);
+        const { readFile } = await importNodeBuiltin('node:fs/promises');
+        return readFile(parsed, { encoding: 'utf-8', signal: signal ?? undefined });
+    }
+    log('Fetch', url);
+    const response = await fetchWithRetry(url, { signal });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch JS from ${url} (HTTP ${response.status})`);
+    }
+    return response.text();
+}
+function collectGlobals(sandbox, excluded, pick) {
+    const result = {};
+    const keys = pick ?? Object.keys(sandbox).filter((key) => !excluded.has(key));
+    for (const key of keys) {
+        if (Object.prototype.hasOwnProperty.call(sandbox, key)) {
+            result[key] = sandbox[key];
+        }
+    }
+    return result;
+}

package/dist/lib/import-json.js

@@ -72,6 +72,13 @@ async function loadJson(url, fetchCache, signal) {
         return (await response.json());
     })();
     fetchCache.set(key, dataPromise);
+    // A rejection must not poison the URL for the cache's life (one transient
+    // fetch drop would replay as a permanent failure) — evict it so the next
+    // importJson retries.
+    dataPromise.catch(() => {
+        if (fetchCache.get(key) === dataPromise)
+            fetchCache.delete(key);
+    });
     return dataPromise;
 }
 async function readJsonFromFs(url) {

package/dist/lib/safe-decode.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `decodeURIComponent`, or the input unchanged where decoding throws. Query
+ * strings arrive from outside the SDK (shared links, embedding pages), so a
+ * malformed percent-escape like `?100%booth` is normal input — code on the
+ * boot/dispatch path must degrade to the raw string, never die on `URIError`.
+ */
+export declare function safeDecode(value: string): string;
+//# sourceMappingURL=safe-decode.d.ts.map

package/dist/lib/safe-decode.js

@@ -0,0 +1,14 @@
+/**
+ * `decodeURIComponent`, or the input unchanged where decoding throws. Query
+ * strings arrive from outside the SDK (shared links, embedding pages), so a
+ * malformed percent-escape like `?100%booth` is normal input — code on the
+ * boot/dispatch path must degrade to the raw string, never die on `URIError`.
+ */
+export function safeDecode(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}

package/dist/lib/safe-local-storage.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `window.localStorage`, or `null` where touching it throws. A cross-origin
+ * iframe with third-party cookies blocked throws a `SecurityError` on the
+ * property access itself (Chrome/Firefox), so bare `localStorage` reads are
+ * unsafe anywhere on the boot path — feature-detect through this instead.
+ * Node (no `window`) also lands on `null`. Reads on the returned store work in
+ * more environments than writes (quota-0 private modes throw on `setItem`
+ * only), so callers that write still need their own probe or try/catch.
+ */
+export declare function safeLocalStorage(): Storage | null;
+//# sourceMappingURL=safe-local-storage.d.ts.map

package/dist/lib/safe-local-storage.js

@@ -0,0 +1,18 @@
+/// <reference lib="dom" />
+/**
+ * `window.localStorage`, or `null` where touching it throws. A cross-origin
+ * iframe with third-party cookies blocked throws a `SecurityError` on the
+ * property access itself (Chrome/Firefox), so bare `localStorage` reads are
+ * unsafe anywhere on the boot path — feature-detect through this instead.
+ * Node (no `window`) also lands on `null`. Reads on the returned store work in
+ * more environments than writes (quota-0 private modes throw on `setItem`
+ * only), so callers that write still need their own probe or try/catch.
+ */
+export function safeLocalStorage() {
+    try {
+        return window.localStorage;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expofp/utils",
-  "version": "3.11.12",
+  "version": "3.12.0",
   "type": "module",
   "description": "ExpoFP SDK internal: shared utilities",
   "homepage": "https://developer.expofp.com/",

package/README.md

@@ -1,11 +0,0 @@
-# @expofp/utils
-
-Generic, domain-free utilities for the ExpoFP SDK. Bundled with the packages that depend on it — no
-separate install.
-
-**Scope rule:** strictly common-use helpers only — no domain logic. Nothing here may know about floor
-plans, booths, exhibitors, or events, or import from a domain package. The test: _could it ship in a
-general-purpose npm utility library unchanged?_ If not, it belongs next to the domain that owns it.
-
-- Build: `nx build utils`
-- Test: `nx test utils`