@expofp/utils 0.0.0-experimental.2d6c681

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export * from './lib/build-zip-archive.js';
+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

@@ -0,0 +1,16 @@
+export * from './lib/build-zip-archive.js';
+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/build-zip-archive.d.ts

@@ -0,0 +1,5 @@
+export declare function buildZipArchive(files: AsyncIterable<{
+    path: string;
+    data: Uint8Array;
+}>): Promise<Blob>;
+//# sourceMappingURL=build-zip-archive.d.ts.map

package/dist/lib/build-zip-archive.js

@@ -0,0 +1,40 @@
+import debug from 'debug';
+import JSZip from 'jszip';
+const log = debug('efp:utils:buildZipArchive');
+const CONCURRENCY = 10;
+async function processConcurrently(iterator, concurrency, processor) {
+    const activePromises = new Set();
+    for await (const item of iterator) {
+        const promise = Promise.resolve(processor(item)).then(() => {
+            activePromises.delete(promise);
+        });
+        activePromises.add(promise);
+        if (activePromises.size >= concurrency) {
+            await Promise.race(activePromises);
+        }
+    }
+    await Promise.all(activePromises);
+}
+export async function buildZipArchive(files) {
+    const zip = new JSZip();
+    // const bundle = await makeOfflineBundle(manifest);
+    let hasFiles = false;
+    await processConcurrently(files, CONCURRENCY, (file) => {
+        log('Adding file to zip:', file.path, 'size:', file.data.byteLength);
+        zip.file(file.path, file.data);
+        hasFiles = true;
+    });
+    // for (const extraFile of extraFiles ?? []) {
+    //   log('Adding extra file to zip:', extraFile.path, 'size:', extraFile.data.byteLength);
+    //   zip.file(extraFile.path, extraFile.data);
+    //   hasFiles = true;
+    // }
+    if (!hasFiles) {
+        throw new Error('No files were added to the ZIP archive');
+    }
+    // Generate archive
+    const blob = await zip.generateAsync({ type: 'blob' });
+    // console.info('Manifest for HTML:', offlineData.manifest);
+    log('Generated offline ZIP bundle, size:', blob.size);
+    return blob;
+}

package/dist/lib/clone.d.ts

@@ -0,0 +1,3 @@
+export declare function deepClone<T>(obj: T): T;
+export declare function shallowClone<T>(obj: T): T;
+//# sourceMappingURL=clone.d.ts.map

package/dist/lib/clone.js

@@ -0,0 +1,14 @@
+export function deepClone(obj) {
+    if ('structuredClone' in globalThis) {
+        return globalThis.structuredClone(obj);
+    }
+    return JSON.parse(JSON.stringify(obj));
+}
+export function shallowClone(obj) {
+    if (obj === null || typeof obj !== 'object')
+        return obj;
+    if (Array.isArray(obj)) {
+        return obj.slice();
+    }
+    return { ...obj };
+}

package/dist/lib/deep-freeze.d.ts

@@ -0,0 +1,2 @@
+export declare function deepFreeze<T>(obj: T): T;
+//# sourceMappingURL=deep-freeze.d.ts.map

package/dist/lib/deep-freeze.js

@@ -0,0 +1,11 @@
+export function deepFreeze(obj) {
+    if (obj === null || typeof obj !== 'object')
+        return obj;
+    Object.getOwnPropertyNames(obj).forEach((prop) => {
+        const value = obj[prop];
+        if (value && typeof value === 'object') {
+            deepFreeze(value);
+        }
+    });
+    return Object.freeze(obj);
+}

package/dist/lib/fetch-with-retry.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Fetches a resource from the network, with retry support in Node.js environments.
+ * In browser environments, it uses the native `fetch` API.
+ * In Node.js environments, it uses the `fetch-retry` library to add retry capabilities.
+ * Node.js are more prone to transient network errors, so retries can help improve reliability.
+ */
+export declare const fetchWithRetry: (...args: Parameters<typeof window.fetch>) => ReturnType<typeof window.fetch>;
+//# sourceMappingURL=fetch-with-retry.d.ts.map

package/dist/lib/fetch-with-retry.js

@@ -0,0 +1,21 @@
+/// <reference lib="dom" />
+let fn;
+/**
+ * Fetches a resource from the network, with retry support in Node.js environments.
+ * In browser environments, it uses the native `fetch` API.
+ * In Node.js environments, it uses the `fetch-retry` library to add retry capabilities.
+ * Node.js are more prone to transient network errors, so retries can help improve reliability.
+ */
+export const fetchWithRetry = async function fetch(...args) {
+    if (!fn) {
+        if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+            fn = window.fetch.bind(window);
+        }
+        else {
+            const fr = await import('fetch-retry');
+            const wrappedFetch = fr.default(globalThis.fetch);
+            fn = wrappedFetch;
+        }
+    }
+    return fn(...args);
+};

package/dist/lib/import-fs-promises.d.ts

@@ -0,0 +1,2 @@
+export declare function importFsPromises(): Promise<typeof import("node:fs/promises")>;
+//# sourceMappingURL=import-fs-promises.d.ts.map

package/dist/lib/import-fs-promises.js

@@ -0,0 +1,4 @@
+import { importNodeModule } from './import-node-module.js';
+export async function importFsPromises() {
+    return importNodeModule('node:fs/promises');
+}

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.d.ts

@@ -0,0 +1,11 @@
+export interface ImportJsonOptions {
+    forceFetch?: boolean;
+    fetchCache?: Map<string, Promise<unknown>>;
+    /**
+     * Callback invoked when a URL is fetched or imported or read from the file system.
+     */
+    importCallback?: (url: string) => void;
+    signal?: AbortSignal | null;
+}
+export declare function importJson<T = unknown>(url: string, options?: ImportJsonOptions): Promise<T>;
+//# sourceMappingURL=import-json.d.ts.map

package/dist/lib/import-json.js

@@ -0,0 +1,91 @@
+import debug from 'debug';
+import { deepFreeze } from './deep-freeze.js';
+import { fetchWithRetry } from './fetch-with-retry.js';
+import { importFsPromises } from './import-fs-promises.js';
+const log = debug('efp:utils:importJson');
+const jsonFrozen = new WeakSet();
+// undefined = untried, function = works, null = known broken (Safari 14, CSP, etc.)
+let importJsonNative;
+// ET: this is a workaround for Vite that analyzes dynamic imports and removes 'with' option
+// to be removed when Vite supports it properly
+// Cons: can have CSP issues in some environments.
+// Lazy + try/caught: Safari 14's parser rejects the two-argument import() form at
+// new Function() construction time, before any feature-detect call site can run.
+function getImportJsonNative() {
+    if (importJsonNative === undefined) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-implied-eval
+            importJsonNative = new Function('url', 'return import(url, { with: { type: "json" } });');
+        }
+        catch {
+            log('Dynamic import not available');
+            importJsonNative = null;
+        }
+    }
+    return importJsonNative ?? undefined;
+}
+export async function importJson(url, options) {
+    const forceFetch = options?.forceFetch ?? false;
+    const fetchCache = options?.fetchCache ?? new Map();
+    const signal = options?.signal ?? null;
+    let result;
+    const native = !forceFetch ? getImportJsonNative() : undefined;
+    if (native) {
+        try {
+            log('Dynamic import', url);
+            const module = await native(url);
+            result = module.default;
+        }
+        catch {
+            log('Dynamic import not available');
+            importJsonNative = null;
+        }
+    }
+    if (result === undefined) {
+        if (url.startsWith('file:') && !forceFetch) {
+            log('Read from file system', url);
+            result = await readJsonFromFs(new URL(url));
+        }
+        else {
+            log('Fetch', url);
+            result = await loadJson(url, fetchCache, signal);
+        }
+    }
+    options?.importCallback?.(url);
+    // Guard against accidental mutations of the imported JSON
+    if (typeof result === 'object' && result !== null && !jsonFrozen.has(result)) {
+        deepFreeze(result);
+        jsonFrozen.add(result);
+    }
+    return result;
+}
+async function loadJson(url, fetchCache, signal) {
+    const key = '__loadJson__' + url;
+    if (fetchCache.has(key)) {
+        return fetchCache.get(key);
+    }
+    const dataPromise = (async () => {
+        const response = await fetchWithRetry(url, { signal });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch JSON from ${url}`);
+        }
+        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) {
+    if (url.protocol !== 'file:') {
+        throw new Error(`readJsonFromFs only supports file: URLs, got ${url.href}`);
+    }
+    const fs = await importFsPromises();
+    const data = await fs.readFile(url, { encoding: 'utf-8' });
+    return JSON.parse(data);
+}

package/dist/lib/import-node-module.d.ts

@@ -0,0 +1,2 @@
+export declare function importNodeModule<T>(moduleName: string): Promise<T>;
+//# sourceMappingURL=import-node-module.d.ts.map

package/dist/lib/import-node-module.js

@@ -0,0 +1,16 @@
+export async function importNodeModule(moduleName) {
+    if (typeof process === 'undefined' || !process.versions?.node) {
+        throw new Error('importNodeModule can only be used in Node.js environments');
+    }
+    try {
+        // prevents every bundler (Vite, Rollup, webpack alike) from analyzing the specifier
+        // eslint-disable-next-line @typescript-eslint/no-implied-eval, @typescript-eslint/no-unsafe-call
+        return (await new Function('moduleName', 'return import(moduleName)')(moduleName));
+    }
+    catch {
+        // A `new Function` scope has no dynamic-import callback under module
+        // runners like vitest's — fall back to a literal import, hidden from
+        // bundlers by the magic comments instead.
+        return (await import(/* @vite-ignore */ /* webpackIgnore: true */ moduleName));
+    }
+}

package/dist/lib/import-runtime-json.d.ts

@@ -0,0 +1,2 @@
+export declare function importRuntimeJson<T = unknown>(fileName: string): Promise<T>;
+//# sourceMappingURL=import-runtime-json.d.ts.map

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

@@ -0,0 +1,10 @@
+import debug from 'debug';
+import { importJson } from './import-json.js';
+const log = debug('efp:utils:importRuntimeJson');
+export async function importRuntimeJson(fileName) {
+    // ignore because vite may rewrite '.' to data:...
+    const baseUrl = new URL(/* @vite-ignore */ '.', import.meta.url).href;
+    const url = new URL(fileName, baseUrl);
+    log('Loading runtime JSON from', url.href);
+    return await importJson(url.href);
+}

package/dist/lib/load-script.d.ts

@@ -0,0 +1,3 @@
+/** @deprecated we should never load/eval scripts */
+export declare function loadScript(scriptUrl: string, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=load-script.d.ts.map

package/dist/lib/load-script.js

@@ -0,0 +1,108 @@
+/// <reference lib="dom" />
+import debug from 'debug';
+import { fetchWithRetry } from './fetch-with-retry.js';
+const log = debug('efp:utils:loadScript');
+function isBrowser() {
+    return typeof window !== 'undefined' && typeof document !== 'undefined';
+}
+function isAbortError(err) {
+    return err instanceof Error && err.name === 'AbortError';
+}
+/** @deprecated we should never load/eval scripts */
+export async function loadScript(scriptUrl, signal) {
+    log('Loading', scriptUrl);
+    if (isBrowser()) {
+        await loadInBrowser(scriptUrl, signal);
+    }
+    else {
+        await loadInNode(scriptUrl, signal);
+    }
+}
+/* -------------------- Browser implementation -------------------- */
+function loadInBrowser(scriptUrl, signal) {
+    return new Promise((resolve, reject) => {
+        const script = document.createElement('script');
+        script.src = scriptUrl;
+        script.async = true;
+        const cleanup = () => {
+            script.onload = null;
+            script.onerror = null;
+            script.remove();
+        };
+        const onAbort = () => {
+            cleanup();
+            reject(new Error('Script load aborted'));
+        };
+        if (signal?.aborted) {
+            cleanup();
+            reject(new Error('Script load aborted'));
+            return;
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+        script.onload = () => {
+            signal?.removeEventListener('abort', onAbort);
+            cleanup();
+            resolve();
+        };
+        script.onerror = () => {
+            signal?.removeEventListener('abort', onAbort);
+            cleanup();
+            reject(new Error(`Failed to load script: ${scriptUrl}`));
+        };
+        document.head.appendChild(script);
+    });
+}
+/* -------------------- Node implementation -------------------- */
+async function loadInNode(scriptUrl, signal) {
+    if (signal?.aborted) {
+        throw new Error('Script load aborted');
+    }
+    let res;
+    try {
+        res = await fetchWithRetry(scriptUrl, { signal });
+    }
+    catch (err) {
+        // Node / WHATWG fetch uses AbortError on abort
+        if (isAbortError(err)) {
+            throw new Error('Script load aborted', { cause: err });
+        }
+        throw err;
+    }
+    if (!res.ok) {
+        throw new Error(`Failed to load script in Node (HTTP ${res.status}): ${scriptUrl}`);
+    }
+    // If it was aborted between headers and body:
+    if (signal?.aborted) {
+        throw new Error('Script load aborted');
+    }
+    let code;
+    try {
+        code = await res.text();
+    }
+    catch (err) {
+        if (isAbortError(err)) {
+            throw new Error('Script load aborted', { cause: err });
+        }
+        throw err;
+    }
+    if (signal?.aborted) {
+        throw new Error('Script load aborted');
+    }
+    const g = globalThis;
+    const prevWindow = g.window;
+    g.window = g;
+    try {
+        // Indirect eval -> global scope in Node
+        // Assumes the loaded script attaches itself to globalThis/window/global.
+        (0, eval)(code);
+    }
+    finally {
+        // Restore previous window (if any)
+        if (prevWindow === undefined) {
+            delete g.window;
+        }
+        else {
+            g.window = prevWindow;
+        }
+    }
+}

package/dist/lib/make-local-path.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Makes a local file path from a URL, preserving extension and automatically adding hash for files.
+ *
+ * @param url Full URL object (e.g., new URL('http://demo.expofp.com/data/path/to/file.ext?version=12345'))
+ * @param filenameSuffix Optional suffix to add before file extension (e.g., '_small', '_medium', '_large'). Not allowed for directories.
+ *
+ * @returns
+ * For files: http-demo-expofp-com/data/path/to/fullhashoffullurl/filename_small.ext (hash is automatically added based on full URL including query params)
+ * For directories: http-demo-expofp-com/data/path/to/dir/ (no hash added, trailing slash preserved)
+ *
+ * @remarks
+ * - All path segments (protocol, domain, directories) are slugified to avoid special characters
+ * - Filename is slugified and truncated to max 50 characters (excluding extension)
+ * - Hash is automatically added for files (based on full URL including query params)
+ * - Hash is never added for directories (paths ending with /)
+ * - Query parameters affect the hash for files, making different versions have unique local paths
+ *
+ * @example
+ * ```ts
+ * // File with query params
+ * const url1 = new URL('http://demo.expofp.com/image.jpg?v=1');
+ * await makeLocalPath(url1); // http-demo-expofp-com/ABC123XYZ/image.jpg
+ *
+ * const url2 = new URL('http://demo.expofp.com/image.jpg?v=2');
+ * await makeLocalPath(url2); // http-demo-expofp-com/DEF456UVW/image.jpg (different hash)
+ *
+ * // File with suffix
+ * const url3 = new URL('http://demo.expofp.com/image.jpg');
+ * await makeLocalPath(url3, '_small'); // http-demo-expofp-com/GHI789RST/image_small.jpg
+ *
+ * // Directory
+ * const url4 = new URL('http://demo.expofp.com/data/');
+ * await makeLocalPath(url4); // http-demo-expofp-com/data/
+ * ```
+ */
+export declare function makeLocalPath(url: URL, filenameSuffix?: string): Promise<string>;
+//# sourceMappingURL=make-local-path.d.ts.map

package/dist/lib/make-local-path.js

@@ -0,0 +1,100 @@
+import debug from 'debug';
+import { safeSlugify } from './safe-slugify.js';
+import { shortHash } from './short-hash.js';
+const log = debug('efp:utils:makeLocalPath');
+/**
+ * Makes a local file path from a URL, preserving extension and automatically adding hash for files.
+ *
+ * @param url Full URL object (e.g., new URL('http://demo.expofp.com/data/path/to/file.ext?version=12345'))
+ * @param filenameSuffix Optional suffix to add before file extension (e.g., '_small', '_medium', '_large'). Not allowed for directories.
+ *
+ * @returns
+ * For files: http-demo-expofp-com/data/path/to/fullhashoffullurl/filename_small.ext (hash is automatically added based on full URL including query params)
+ * For directories: http-demo-expofp-com/data/path/to/dir/ (no hash added, trailing slash preserved)
+ *
+ * @remarks
+ * - All path segments (protocol, domain, directories) are slugified to avoid special characters
+ * - Filename is slugified and truncated to max 50 characters (excluding extension)
+ * - Hash is automatically added for files (based on full URL including query params)
+ * - Hash is never added for directories (paths ending with /)
+ * - Query parameters affect the hash for files, making different versions have unique local paths
+ *
+ * @example
+ * ```ts
+ * // File with query params
+ * const url1 = new URL('http://demo.expofp.com/image.jpg?v=1');
+ * await makeLocalPath(url1); // http-demo-expofp-com/ABC123XYZ/image.jpg
+ *
+ * const url2 = new URL('http://demo.expofp.com/image.jpg?v=2');
+ * await makeLocalPath(url2); // http-demo-expofp-com/DEF456UVW/image.jpg (different hash)
+ *
+ * // File with suffix
+ * const url3 = new URL('http://demo.expofp.com/image.jpg');
+ * await makeLocalPath(url3, '_small'); // http-demo-expofp-com/GHI789RST/image_small.jpg
+ *
+ * // Directory
+ * const url4 = new URL('http://demo.expofp.com/data/');
+ * await makeLocalPath(url4); // http-demo-expofp-com/data/
+ * ```
+ */
+export async function makeLocalPath(url, filenameSuffix) {
+    // // Normalize baseUrl to end with /
+    // const normalizedBase = baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
+    // // Combine to get full URL
+    // const fullUrl = new URL(relativeUrl || '', normalizedBase).href;
+    // Parse the URL
+    // const url = new URL(fullUrl);
+    // Check if this is a directory (ends with / or is empty/root)
+    const isDirectory = url.pathname.endsWith('/') || url.pathname === '';
+    const addHash = !isDirectory;
+    // Validate parameters for directories
+    if (isDirectory && filenameSuffix) {
+        throw new Error('filenameSuffix is not allowed for directory paths');
+    }
+    // Create hash if requested (using full URL)
+    const hash = addHash ? await shortHash(url.href) : null;
+    // Slugify protocol and domain (e.g., "http-demo-expofp-com")
+    const protocol = safeSlugify(url.protocol.replace(':', ''));
+    const domain = safeSlugify(url.hostname);
+    const port = url.port ? `-${url.port}` : '';
+    const protocolDomain = `${protocol}-${domain}${port}`;
+    // Parse the path
+    const pathParts = url.pathname.split('/').filter(Boolean);
+    if (isDirectory) {
+        // For directories, all parts are directory parts
+        const slugifiedDirs = pathParts.map((part) => safeSlugify(part));
+        // Build the full local path with trailing /
+        const pathSegments = hash
+            ? [protocolDomain, ...slugifiedDirs, hash]
+            : [protocolDomain, ...slugifiedDirs];
+        return pathSegments.join('/') + '/';
+    }
+    // For files: Extract filename (last part) and directory parts
+    const filename = pathParts.pop() ?? '';
+    const directoryParts = pathParts;
+    // Slugify directory parts
+    const slugifiedDirs = directoryParts.map((part) => safeSlugify(part));
+    // Extract extension and base filename
+    const lastDotIndex = filename.lastIndexOf('.');
+    const extension = lastDotIndex !== -1 ? filename.slice(lastDotIndex) : '';
+    const baseFilename = lastDotIndex !== -1 ? filename.slice(0, lastDotIndex) : filename;
+    // Slugify the base filename
+    let slugifiedFilename = safeSlugify(baseFilename);
+    // Ensure filename is max 50 characters (not including extension)
+    const maxFilenameLength = 50;
+    if (slugifiedFilename.length > maxFilenameLength) {
+        log(`Filename truncated from ${slugifiedFilename.length} to ${maxFilenameLength} characters: ${slugifiedFilename}`);
+        slugifiedFilename = slugifiedFilename.slice(0, maxFilenameLength);
+    }
+    // Add suffix if provided (before extension)
+    if (filenameSuffix) {
+        slugifiedFilename = `${slugifiedFilename}${filenameSuffix}`;
+    }
+    // Combine filename with extension
+    const finalFilename = `${slugifiedFilename}${extension}`;
+    // Build the full local path
+    const pathSegments = hash
+        ? [protocolDomain, ...slugifiedDirs, hash, finalFilename]
+        : [protocolDomain, ...slugifiedDirs, finalFilename];
+    return pathSegments.join('/');
+}

package/dist/lib/read-file-from-url.d.ts

@@ -0,0 +1,11 @@
+type ReadFileFromUrlResult = {
+    ok: true;
+    data: Uint8Array;
+} | {
+    ok: false;
+};
+export declare function readFileFromUrl(url: URL, options?: {
+    signal?: AbortSignal;
+}): Promise<ReadFileFromUrlResult>;
+export {};
+//# sourceMappingURL=read-file-from-url.d.ts.map

package/dist/lib/read-file-from-url.js

@@ -0,0 +1,17 @@
+import { fetchWithRetry } from './fetch-with-retry.js';
+import { importFsPromises } from './import-fs-promises.js';
+export async function readFileFromUrl(url, options) {
+    if (url.protocol === 'file:') {
+        const { readFile } = await importFsPromises();
+        const data = await readFile(url, { signal: options?.signal });
+        return { ok: true, data };
+    }
+    else {
+        const response = await fetchWithRetry(url, { signal: options?.signal });
+        if (!response.ok) {
+            return { ok: false };
+        }
+        const arrayBuffer = await response.arrayBuffer();
+        return { ok: true, data: new Uint8Array(arrayBuffer) };
+    }
+}

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/dist/lib/safe-slugify.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Generates a filesystem-safe slug from input string, ensuring uniqueness.
+ * @param input
+ * @returns
+ */
+export declare function safeSlugify(input: string): string;
+//# sourceMappingURL=safe-slugify.d.ts.map

package/dist/lib/safe-slugify.js

@@ -0,0 +1,80 @@
+// Module-level caches
+const inputToSlug = new Map();
+const slugToInput = new Map();
+const WINDOWS_RESERVED = new Set([
+    'con',
+    'prn',
+    'aux',
+    'nul',
+    'com1',
+    'com2',
+    'com3',
+    'com4',
+    'com5',
+    'com6',
+    'com7',
+    'com8',
+    'com9',
+    'lpt1',
+    'lpt2',
+    'lpt3',
+    'lpt4',
+    'lpt5',
+    'lpt6',
+    'lpt7',
+    'lpt8',
+    'lpt9',
+]);
+function makeBaseSlug(input) {
+    let slug = input
+        .normalize('NFKD')
+        // All non letters/numbers → "-"
+        .replace(/[^\p{Letter}\p{Number}]+/gu, '-')
+        // Collapse multiple "-"
+        .replace(/-+/g, '-')
+        // Trim "-" from start/end
+        .replace(/^-|-$/g, '')
+        .toLowerCase();
+    // Strip forbidden Windows characters just in case
+    slug = slug.replace(/[<>:"/\\|?*]/g, '');
+    // Windows forbids trailing space/period
+    slug = slug.replace(/[. ]+$/g, '');
+    // Fallback if everything was stripped
+    if (!slug)
+        slug = 'file';
+    // Avoid bare reserved device names
+    if (WINDOWS_RESERVED.has(slug)) {
+        slug += '-file';
+    }
+    return slug;
+}
+/**
+ * Generates a filesystem-safe slug from input string, ensuring uniqueness.
+ * @param input
+ * @returns
+ */
+export function safeSlugify(input) {
+    // If we've seen this exact input before, return the same slug
+    const existing = inputToSlug.get(input);
+    if (existing)
+        return existing;
+    const base = makeBaseSlug(input);
+    let candidate = base;
+    let counter = 2;
+    while (true) {
+        const existingInput = slugToInput.get(candidate);
+        if (!existingInput) {
+            // Free slug → claim it for this input
+            slugToInput.set(candidate, input);
+            inputToSlug.set(input, candidate);
+            return candidate;
+        }
+        if (existingInput === input) {
+            // Same input somehow (super defensive)
+            inputToSlug.set(input, candidate);
+            return candidate;
+        }
+        // Collision: same slug already used by different input → add suffix
+        candidate = `${base}-${counter++}`;
+    }
+}

package/dist/lib/short-hash.d.ts

@@ -0,0 +1,2 @@
+export declare function shortHash(input: string, bytes?: number): Promise<string>;
+//# sourceMappingURL=short-hash.d.ts.map

package/dist/lib/short-hash.js

@@ -0,0 +1,24 @@
+export async function shortHash(input, bytes = 16) {
+    const data = new TextEncoder().encode(input);
+    const digest = await crypto.subtle.digest('SHA-256', data);
+    const full = new Uint8Array(digest);
+    return toBase62(full.subarray(0, bytes));
+}
+const BASE62_CHARS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+function toBase62(bytes) {
+    // TODO: check if this ArrayBuffer guard is still needed — parameter is typed Uint8Array
+    const u8 = bytes instanceof ArrayBuffer ? new Uint8Array(bytes) : bytes;
+    // Convert bytes -> BigInt (no Buffer required)
+    let num = 0n;
+    // eslint-disable-next-line compat/compat
+    for (const b of u8)
+        num = (num << 8n) + BigInt(b);
+    if (num === 0n)
+        return '0';
+    let result = '';
+    while (num > 0n) {
+        result = BASE62_CHARS[Number(num % 62n)] + result;
+        num /= 62n;
+    }
+    return result;
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@expofp/utils",
+  "version": "0.0.0-experimental.2d6c681",
+  "type": "module",
+  "description": "ExpoFP SDK internal: shared utilities",
+  "homepage": "https://developer.expofp.com/",
+  "license": "MIT",
+  "sideEffects": false,
+  "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",
+    "fetch-retry": "^6.0.0",
+    "jszip": "^3.10.1",
+    "tslib": "^2.3.0"
+  }
+}