@expofp/utils 3.0.0-alpha.3

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export * from './lib/buildZipArchive.js';
+export * from './lib/clone.js';
+export * from './lib/deepFreeze.js';
+export * from './lib/importFsPromises.js';
+export * from './lib/importJsonModule.js';
+export * from './lib/importNodeModule.js';
+export * from './lib/importRuntimeJsonModule.js';
+export * from './lib/loadScript.js';
+export * from './lib/makeLocalPath.js';
+export * from './lib/niceFetch.js';
+export * from './lib/readFileFromUrl.js';
+export * from './lib/sha256Base62Truncated.js';
+export * from './lib/slugifyFilesystemUnique.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,13 @@
+export * from './lib/buildZipArchive.js';
+export * from './lib/clone.js';
+export * from './lib/deepFreeze.js';
+export * from './lib/importFsPromises.js';
+export * from './lib/importJsonModule.js';
+export * from './lib/importNodeModule.js';
+export * from './lib/importRuntimeJsonModule.js';
+export * from './lib/loadScript.js';
+export * from './lib/makeLocalPath.js';
+export * from './lib/niceFetch.js';
+export * from './lib/readFileFromUrl.js';
+export * from './lib/sha256Base62Truncated.js';
+export * from './lib/slugifyFilesystemUnique.js';

package/dist/lib/buildZipArchive.d.ts

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

package/dist/lib/buildZipArchive.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/deepFreeze.d.ts

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

package/dist/lib/deepFreeze.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/importFsPromises.d.ts

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

package/dist/lib/importFsPromises.js

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

package/dist/lib/importJsonModule.d.ts

@@ -0,0 +1,11 @@
+export interface ImportJsonModuleOptions {
+    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 importJsonModule<T = unknown>(url: string, options?: ImportJsonModuleOptions): Promise<T>;
+//# sourceMappingURL=importJsonModule.d.ts.map

package/dist/lib/importJsonModule.js

@@ -0,0 +1,78 @@
+import debug from 'debug';
+import { deepFreeze } from './deepFreeze.js';
+import { importFsPromises } from './importFsPromises.js';
+import { niceFetch } from './niceFetch.js';
+const log = debug('efp:utils:importJsonModule');
+let importJsonNotAvailable;
+const jsonFrozen = new WeakSet();
+// 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
+const importJsonNative = new Function('url', 'return import(url, { with: { type: "json" } });');
+export async function importJsonModule(url, options) {
+    const opts = {
+        forceFetch: options?.forceFetch || false,
+        fetchCache: options?.fetchCache || new Map(),
+        importCallback: options?.importCallback,
+        signal: options?.signal || null,
+    };
+    // console.warn('importJson:', resolveContext.forceFetch);
+    if (importJsonNotAvailable === undefined && !opts.forceFetch) {
+        try {
+            await importJsonNative(url);
+            importJsonNotAvailable = false;
+        }
+        catch {
+            log('Dynamic import not available');
+            importJsonNotAvailable = true;
+        }
+    }
+    let result = undefined;
+    if (!importJsonNotAvailable && !opts.forceFetch) {
+        log('Dynamic import', url);
+        const module = await importJsonNative(url);
+        result = module.default;
+    }
+    else if (url.startsWith('file:') && !opts.forceFetch) {
+        log('Read from file system', url);
+        result = await readJsonFromFs(new URL(url));
+    }
+    else {
+        log('Fetch', url);
+        result = await loadJson(url, opts.fetchCache, opts.signal || null);
+    }
+    // log('Callback for imported JSON URL:', url, !!opts.importCallback);
+    opts.importCallback?.(url);
+    // Freeze the imported JSON to make it immutable
+    // This is rather a guard against accidental mutations
+    if (typeof result === 'object' && result !== null && !jsonFrozen.has(result)) {
+        deepFreeze(result);
+        jsonFrozen.add(result);
+    }
+    return result;
+}
+// const fetchCache = new Map<string, Promise<any>>();
+async function loadJson(url, fetchCache, signal) {
+    const key = '__loadJson__' + url;
+    if (fetchCache.has(key)) {
+        return fetchCache.get(key);
+    }
+    const dataPromise = (async function loadJsonInner() {
+        // in browser just use fetch, for node - fetch-retry
+        const response = await niceFetch(url, { signal });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch JSON from ${url}`);
+        }
+        return await response.json();
+    })();
+    fetchCache.set(key, dataPromise);
+    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/importNodeModule.d.ts

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

package/dist/lib/importNodeModule.js

@@ -0,0 +1,7 @@
+export async function importNodeModule(moduleName) {
+    if (typeof process === 'undefined' || !process.versions?.node) {
+        throw new Error('importNodeModule can only be used in Node.js environments');
+    }
+    // prevents Vite/Rollup from analyzing the import specifier
+    return new Function(`return import('${moduleName}')`)();
+}

package/dist/lib/importRuntimeJsonFile.d.ts

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

package/dist/lib/importRuntimeJsonFile.js

@@ -0,0 +1,10 @@
+import debug from 'debug';
+import { importJsonModule } from './importJsonModule.js';
+const log = debug('efp:utils:importRuntimeJsonModule');
+export async function importRuntimeJsonModule(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 importJsonModule(url.href);
+}

package/dist/lib/importRuntimeJsonModule.d.ts

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

package/dist/lib/importRuntimeJsonModule.js

@@ -0,0 +1,10 @@
+import debug from 'debug';
+import { importJsonModule } from './importJsonModule.js';
+const log = debug('efp:utils:importRuntimeJsonModule');
+export async function importRuntimeJsonModule(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 importJsonModule(url.href);
+}

package/dist/lib/loadScript.d.ts

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

package/dist/lib/loadScript.js

@@ -0,0 +1,108 @@
+/// <reference lib="dom" />
+import debug from 'debug';
+import { niceFetch } from './niceFetch.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 niceFetch(scriptUrl, { signal });
+    }
+    catch (err) {
+        // Node / WHATWG fetch uses AbortError on abort
+        if (isAbortError(err)) {
+            throw new Error('Script load aborted');
+        }
+        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');
+        }
+        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/makeLocalPath.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=makeLocalPath.d.ts.map

package/dist/lib/makeLocalPath.js

@@ -0,0 +1,100 @@
+import debug from 'debug';
+import { sha256Base62Truncated } from './sha256Base62Truncated.js';
+import { slugifyFilesystemUnique } from './slugifyFilesystemUnique.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 sha256Base62Truncated(url.href) : null;
+    // Slugify protocol and domain (e.g., "http-demo-expofp-com")
+    const protocol = slugifyFilesystemUnique(url.protocol.replace(':', ''));
+    const domain = slugifyFilesystemUnique(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) => slugifyFilesystemUnique(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) => slugifyFilesystemUnique(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 = slugifyFilesystemUnique(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/niceFetch.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 niceFetch: (...args: Parameters<typeof window.fetch>) => ReturnType<typeof window.fetch>;
+//# sourceMappingURL=niceFetch.d.ts.map

package/dist/lib/niceFetch.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 niceFetch = 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 fetchWithRetry = fr.default(globalThis.fetch);
+            fn = fetchWithRetry;
+        }
+    }
+    return fn(...args);
+};

package/dist/lib/readFileFromUrl.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=readFileFromUrl.d.ts.map

package/dist/lib/readFileFromUrl.js

@@ -0,0 +1,17 @@
+import { importFsPromises } from './importFsPromises.js';
+import { niceFetch } from './niceFetch.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 niceFetch(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/sha256Base62Truncated.d.ts

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

package/dist/lib/sha256Base62Truncated.js

@@ -0,0 +1,23 @@
+export async function sha256Base62Truncated(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;
+    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/dist/lib/slugifyFilesystemUnique.d.ts

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

package/dist/lib/slugifyFilesystemUnique.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 slugifyFilesystemUnique(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/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@expofp/utils",
+  "version": "3.0.0-alpha.3",
+  "type": "module",
+  "description": "ExpoFP SDK internal: shared utilities",
+  "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",
+    "fetch-retry": "^6.0.0",
+    "jszip": "^3.10.1",
+    "tslib": "^2.3.0"
+  }
+}