modern-pdf-lib 0.25.0 → 0.28.0

package/dist/{loader-C7B5dVCI.mjs → loader-B1Ix7ozU.mjs}

@@ -1,6 +1,236 @@
-import { os as __exportAll } from "./index-DCSbmXWh.d.mts";
-
+import { Vu as __exportAll } from "./index-C1lZe66f.d.mts";
+//#region src/wasm/inlineWasm.ts
+/**
+* @module wasm/inlineWasm
+*
+* Provides runtime access to inline (base64-encoded) WASM module bytes
+* with **lazy decoding** and **GC-friendly caching**.
+*
+* This module is the runtime companion to the build-time code generation
+* script `scripts/generate-inline-wasm.ts`. It imports the generated
+* constants from `inlineWasm.generated.ts` and exposes functions that
+* decode a module's base64 string into a `Uint8Array` on demand.
+*
+* Design:
+* - The heavy lifting (reading WASM files, base64 encoding) happens at
+*   **build time** via the code generation script.
+* - At **runtime**, base64 decoding is deferred until the module is
+*   actually requested — no upfront cost.
+* - Decoded bytes are held via `WeakRef` so the GC can reclaim them
+*   when memory pressure is high. A strong cache is also available
+*   for performance-critical paths.
+* - {@link preloadInlineWasm} allows proactive decoding before first use.
+* - {@link getInlineWasmSize} returns the encoded size without triggering
+*   any base64 decode.
+*
+* @packageDocumentation
+*/
+/**
+* The set of all WASM module names supported by the library.
+*
+* These correspond to the crate directories under `src/wasm/`.
+*/
+const WASM_MODULE_NAMES = [
+	"libdeflate",
+	"png",
+	"ttf",
+	"shaping",
+	"jbig2",
+	"jpeg"
+];
+/**
+* Strong cache of decoded WASM bytes, keyed by module name.
+*
+* Entries are populated on first access and kept alive as long as
+* callers hold references. {@link clearInlineWasmCache} clears this.
+*/
+const strongCache = /* @__PURE__ */ new Map();
+/**
+* Weak cache of decoded WASM bytes.
+*
+* When the strong cache is cleared (e.g., to reduce memory), the
+* weak cache may still hold a reference if the GC hasn't collected
+* the bytes. This avoids redundant re-decoding when bytes are still
+* reachable elsewhere.
+*/
+const weakCache = /* @__PURE__ */ new Map();
+/**
+* Retrieve the decoded WASM bytes for a given module name.
+*
+* On first call for a module, the base64 string from the generated file
+* is decoded into a `Uint8Array`. Subsequent calls return the cached
+* result. If the strong cache has been cleared but a `WeakRef` still
+* holds the bytes, they are recovered without re-decoding.
+*
+* @param name  The WASM module name (e.g., `'libdeflate'`, `'png'`).
+* @returns     The decoded WASM binary as a `Uint8Array`.
+* @throws      If the module name is unknown or the generated file does
+*              not contain data for the requested module.
+*
+* @example
+* ```ts
+* const wasmBytes = getInlineWasmBytes('libdeflate');
+* const module = await WebAssembly.compile(wasmBytes);
+* ```
+*/
+function getInlineWasmBytes(name) {
+	if (!isValidModuleName(name)) throw new Error(`Unknown WASM module: "${name}". Valid modules: ${WASM_MODULE_NAMES.join(", ")}`);
+	const strong = strongCache.get(name);
+	if (strong) return strong;
+	const weakRef = weakCache.get(name);
+	if (weakRef) {
+		const weakBytes = weakRef.deref();
+		if (weakBytes) {
+			strongCache.set(name, weakBytes);
+			return weakBytes;
+		}
+		weakCache.delete(name);
+	}
+	const base64Data = getBase64Data(name);
+	const bytes = Uint8Array.fromBase64(base64Data);
+	strongCache.set(name, bytes);
+	weakCache.set(name, new WeakRef(bytes));
+	return bytes;
+}
+/**
+* Check whether a given module name is a valid WASM module name.
+*
+* @param name  The name to check.
+* @returns     `true` if the name is one of the known WASM modules.
+*/
+function isValidModuleName(name) {
+	return WASM_MODULE_NAMES.includes(name);
+}
+/**
+* Check whether inline WASM data is available for a given module.
+*
+* Returns `true` if the generated file contains base64 data for the
+* requested module. Returns `false` if the generated file does not
+* exist or does not include the module.
+*
+* @param name  The WASM module name.
+* @returns     `true` if inline bytes can be retrieved for this module.
+*/
+function hasInlineWasmData(name) {
+	if (!isValidModuleName(name)) return false;
+	try {
+		return name in requireGenerated().INLINE_WASM_MODULES;
+	} catch {
+		return false;
+	}
+}
+/**
+* Get the encoded (base64) size of a WASM module **without** decoding it.
+*
+* This is useful for diagnostics, size budgeting, and bundle analysis.
+* The returned value is the number of characters in the base64 string;
+* the actual binary size is approximately `encodedSize * 3 / 4`.
+*
+* @param name  The WASM module name.
+* @returns     The base64 string length (in characters), or `0` if the
+*              module is not available.
+*
+* @example
+* ```ts
+* const encoded = getInlineWasmSize('libdeflate');
+* const binaryApprox = Math.floor(encoded * 3 / 4);
+* console.log(`libdeflate: ~${binaryApprox} bytes binary`);
+* ```
+*/
+function getInlineWasmSize(name) {
+	if (!isValidModuleName(name)) return 0;
+	try {
+		const data = requireGenerated().INLINE_WASM_MODULES[name];
+		return data ? data.length : 0;
+	} catch {
+		return 0;
+	}
+}
+/**
+* Proactively decode and cache WASM bytes for the specified modules.
+*
+* Call this during application initialization to avoid decoding latency
+* on the first actual use. If no names are provided, all available
+* modules are preloaded.
+*
+* @param names  Optional list of module names to preload. Defaults to
+*               all modules present in the generated data.
+* @returns      The names of modules that were successfully preloaded.
+*
+* @example
+* ```ts
+* // Preload specific modules
+* preloadInlineWasm('libdeflate', 'png');
+*
+* // Preload everything available
+* preloadInlineWasm();
+* ```
+*/
+function preloadInlineWasm(...names) {
+	const targets = names.length > 0 ? names : [...WASM_MODULE_NAMES];
+	const loaded = [];
+	for (const name of targets) {
+		if (!isValidModuleName(name)) continue;
+		if (strongCache.has(name)) {
+			loaded.push(name);
+			continue;
+		}
+		try {
+			getInlineWasmBytes(name);
+			loaded.push(name);
+		} catch {}
+	}
+	return loaded;
+}
+/**
+* Lazily load and cache the generated module.
+*
+* Uses a dynamic import expression to avoid hard compile-time dependency
+* on the generated file (which may not exist during development).
+*/
+function requireGenerated() {
+	try {
+		throw new Error("Inline WASM data not loaded. Call loadInlineWasmModule() first, or run `npm run generate:wasm-inline`.");
+	} catch (err) {
+		throw err;
+	}
+}
+/**
+* Extract the base64 string for a given module name from the generated data.
+*
+* @throws If the generated data is not loaded or does not contain the module.
+*/
+function getBase64Data(name) {
+	try {
+		const moduleData = requireGenerated().INLINE_WASM_MODULES[name];
+		if (!moduleData) throw new Error(`WASM module "${name}" is not available in the generated inline data. Run \`npm run generate:wasm-inline\` to regenerate.`);
+		return moduleData;
+	} catch (err) {
+		if (err instanceof Error && err.message.includes("is not available")) throw err;
+		throw new Error(`Failed to load inline WASM data for module "${name}". The generated file may not exist. Run \`npm run generate:wasm-inline\` to generate it. Original error: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+//#endregion
 //#region src/wasm/loader.ts
+/**
+* @module wasm/loader
+*
+* Universal WASM module loader for the modern-pdf library.
+*
+* Provides a single entry point for loading `.wasm` binaries across
+* all supported JavaScript runtimes:
+*
+* - **Browser**: Uses `fetch()` to load from a URL.
+* - **Node.js**: Uses `fs/promises` via dynamic import to read from disk.
+* - **Deno**: Uses `Deno.readFile()` or `fetch()` for local/remote files.
+* - **Bun**: Uses `Bun.file()` for local files or `fetch()` for URLs.
+* - **Cloudflare Workers / Edge**: Must provide WASM bytes directly
+*   (no filesystem access), or use bundled imports.
+*
+* Loaded modules are cached by name to avoid redundant fetches.
+*
+* @packageDocumentation
+*/
 var loader_exports = /* @__PURE__ */ __exportAll({
 	clearWasmCache: () => clearWasmCache,
 	configureWasmLoader: () => configureWasmLoader,
@@ -39,13 +269,13 @@ let globalConfig = {};
 * ```
 */
 function detectRuntime() {
-	if (typeof globalThis !== "undefined" && "caches" in globalThis && typeof globalThis["HTMLElement"] === "undefined" && typeof globalThis["process"] === "undefined") {
+	if ("caches" in globalThis && !("HTMLElement" in globalThis) && !("process" in globalThis)) {
 		if (typeof globalThis["navigator"] === "object") {
 			if ((globalThis.navigator?.userAgent ?? "").includes("Cloudflare-Workers")) return "workerd";
 		}
 	}
-	if (typeof globalThis["Deno"] === "object") return "deno";
-	if (typeof globalThis["Bun"] === "object") return "bun";
+	if ("Deno" in globalThis) return "deno";
+	if ("Bun" in globalThis) return "bun";
 	if (typeof globalThis["process"] === "object" && typeof globalThis["process"]?.["versions"] === "object" && typeof (globalThis["process"]?.["versions"])?.["node"] === "string") return "node";
 	if (typeof globalThis["ServiceWorkerGlobalScope"] === "function" && typeof self !== "undefined" && self instanceof globalThis["ServiceWorkerGlobalScope"]) return "service-worker";
 	if (typeof globalThis.document === "object" || typeof globalThis.window === "object") return "browser";
@@ -99,7 +329,10 @@ async function loadViaFetch(url) {
 */
 async function loadViaNodeFs(filePath) {
 	try {
-		const { readFile } = await import("node:fs/promises");
+		const { readFile } = await import(
+			/* @vite-ignore */
+			"node:fs/promises"
+);
 		const buffer = await readFile(filePath);
 		return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
 	} catch (err) {
@@ -129,14 +362,22 @@ function resolveModulePath(name, config, runtime) {
 		case "service-worker": return `/wasm/${filename}`;
 		case "node":
 		case "bun": try {
-			return new URL(`../wasm/${name}/pkg/${filename}`, import.meta.url).pathname;
+			return new URL(`./wasm/${name}/${filename}`, import.meta.url).pathname;
 		} catch {
-			return `./wasm/${name}/pkg/${filename}`;
+			try {
+				return new URL(`../wasm/${name}/pkg/${filename}`, import.meta.url).pathname;
+			} catch {
+				return `./wasm/${name}/pkg/${filename}`;
+			}
 		}
 		case "deno": try {
-			return new URL(`../wasm/${name}/pkg/${filename}`, import.meta.url).href;
+			return new URL(`./wasm/${name}/${filename}`, import.meta.url).href;
 		} catch {
-			return `./wasm/${name}/pkg/${filename}`;
+			try {
+				return new URL(`../wasm/${name}/pkg/${filename}`, import.meta.url).href;
+			} catch {
+				return `./wasm/${name}/pkg/${filename}`;
+			}
 		}
 		case "workerd": throw new Error(`Cannot auto-resolve WASM path in Workers/Edge runtime. Provide WASM bytes via configureWasmLoader({ moduleBytes: { ${name}: bytes } }) or use modulePaths configuration.`);
 		default: return `./wasm/${name}/pkg/${filename}`;
@@ -174,6 +415,11 @@ async function loadWasmModule(name) {
 		moduleCache.set(name, bytes);
 		return bytes;
 	}
+	if (hasInlineWasmData(name)) try {
+		const bytes = getInlineWasmBytes(name);
+		moduleCache.set(name, bytes);
+		return bytes;
+	} catch {}
 	const runtime = detectRuntime();
 	const modulePath = resolveModulePath(name, globalConfig, runtime);
 	let bytes;
@@ -322,7 +568,7 @@ function resetWasmLoader() {
 	moduleCache.clear();
 	globalConfig = {};
 }
-
 //#endregion
-export { isWasmDisabled as a, loadWasmModuleStreaming as c, resetWasmLoader as d, instantiateWasmModuleStreaming as i, loader_exports as l, configureWasmLoader as n, isWasmModuleCached as o, detectRuntime as r, loadWasmModule as s, clearWasmCache as t, provideWasmBytes as u };
-//# sourceMappingURL=loader-C7B5dVCI.mjs.map
+export { isWasmDisabled as a, loadWasmModuleStreaming as c, resetWasmLoader as d, getInlineWasmBytes as f, preloadInlineWasm as g, isValidModuleName as h, instantiateWasmModuleStreaming as i, loader_exports as l, hasInlineWasmData as m, configureWasmLoader as n, isWasmModuleCached as o, getInlineWasmSize as p, detectRuntime as r, loadWasmModule as s, clearWasmCache as t, provideWasmBytes as u };
+
+//# sourceMappingURL=loader-B1Ix7ozU.mjs.map