@live-codes/lfortran-wasm 0.1.0 → 0.1.1

package/README.md

@@ -39,6 +39,28 @@ each time. Each run links its program as a separate wasm side module, which the
 loads; those live for the lifetime of the loaded compiler, which is why a long-lived page should
 create one and reuse it rather than one per keystroke.
 
+### Classic workers
+
+A page or a module worker imports the package directly. A **classic** worker can use it too, because
+dynamic `import()` is available in classic workers as well — `await import(packageUrl)` works, verified
+with the corpus at 14/14.
+
+If a host can only use `importScripts`, there is a classic IIFE build for that:
+
+```js
+// in a classic (non-module) worker
+importScripts('https://cdn.jsdelivr.net/npm/@live-codes/lfortran-wasm/dist/lfortran-wasm.global.js');
+const compiler = await self.lfortranWasm.createCompiler();   // baseUrl optional; defaults to the CDN
+```
+
+It is 3.4 KB minified, because the loader has no dependencies. Pin the version in production.
+
+`importScripts` cannot load the emscripten glue, and this build exists because of it: the glue is an ES
+module (`EXPORT_ES6=1`), so `importScripts` reports a NetworkError for it. Measured against the same
+CDN in Chromium: another package's classic build loads, ours does not. The loader therefore reaches the
+glue with dynamic `import()`, which works from a classic worker, and only the loader needed a classic
+form.
+
 ## What it costs
 
 | asset | raw | gzip | brotli |
@@ -120,10 +142,12 @@ docker cp lfortran-wasm-run:/src/build-wasm/src/bin/wasm_run.js   docker/lfortra
 docker cp lfortran-wasm-run:/src/build-wasm/src/bin/wasm_run.wasm docker/lfortran-wasm/out/
 docker cp lfortran-wasm-run:/src/build-wasm/src/bin/wasm_run.data docker/lfortran-wasm/out/
 npm run copy-assets                                             # vendors + gzips into assets/
+npm run build:iife                                              # dist/lfortran-wasm.global.js
 ```
 
 `npm run copy-assets` prints a size and a SHA-256 receipt per asset, so a published artifact can be
-matched against a build.
+matched against a build. `build:iife` needs `esbuild`; in this repository it falls back to the copy the
+sibling package has installed.
 
 ## Tests
 
@@ -139,6 +163,28 @@ The same loader and the same corpus are also driven against a real browser by
 `docker/lfortran-wasm/browser-test.html` (14/14) and in Node by `docker/lfortran-wasm/test-run.mjs`,
 which is how the browser path is verified rather than assumed.
 
+## Behaviour worth knowing
+
+Verified, not assumed — each of these was run:
+
+- **Bounds and intrinsic-domain errors are compile-time diagnostics.** `a(5) = 1` on `integer :: a(3)`
+  reports `Array index 5 is out of bounds (1 to 3)` and `sqrt(-1.0)` reports `Argument of 'sqrt' has a
+  negative argument`. They are not runtime traps.
+- **A trap does not poison the compiler.** Stack exhaustion from runaway recursion surfaces as
+  `Maximum call stack size exceeded`, and the next `run()` works normally. The same is true after a
+  program that exits, and after a failed read from an empty stdin.
+- **Integer division by zero prints `0`** rather than trapping or diagnosing. Fortran leaves it
+  undefined, so this is a defensible choice rather than a bug, but it is silent.
+- **Node cannot import the glue from a CDN.** Node's ESM loader accepts only `file:` and `data:` URLs,
+  so `baseUrl` pointing at a CDN works in a browser and a worker, and in Node only the wasm and
+  `.data` come from there — the loader says so explicitly rather than failing obscurely.
+- **The first load is network-bound.** 19.04 MiB compressed; on a slow link that is tens of seconds.
+  It is fetched once per page or worker and cached immutably by the CDN.
+- **Coverage is thin.** 14 corpus programs plus a 22-program spread — modules with contained
+  procedures, derived types, allocatables, array sections, whole-array arithmetic, formatted and file
+  I/O, stdin, libm. LFortran is a young compiler; coarrays, submodules, quad precision and parts of
+  I/O are not verified here, and a live playground will find things this does not.
+
 ## License
 
 MIT for this package. The wasm it ships is LFortran (BSD 3-Clause), LLVM and LLD (Apache-2.0 with

package/dist/lfortran-wasm.global.js

@@ -0,0 +1,6 @@
+/*! @live-codes/lfortran-wasm - MIT. IIFE build, sets self.lfortranWasm.
+ *  importScripts('lfortran-wasm.global.js') then self.lfortranWasm.createCompiler({ baseUrl }).
+ *  Downloads the LFortran + LLVM wasm from assets/ (19 MiB compressed). LFortran is BSD 3-Clause and
+ *  LLVM is Apache-2.0 WITH LLVM-exception - see THIRD-PARTY-NOTICES.md. */
+var lfortranWasm=(()=>{var k=Object.create;var p=Object.defineProperty;var A=Object.getOwnPropertyDescriptor;var P=Object.getOwnPropertyNames;var _=Object.getPrototypeOf,N=Object.prototype.hasOwnProperty;var y=(t=>typeof require<"u"?require:typeof Proxy<"u"?new Proxy(t,{get:(e,r)=>(typeof require<"u"?require:e)[r]}):t)(function(t){if(typeof require<"u")return require.apply(this,arguments);throw Error('Dynamic require of "'+t+'" is not supported')});var v=(t,e)=>{for(var r in e)p(t,r,{get:e[r],enumerable:!0})},F=(t,e,r,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let o of P(e))!N.call(t,o)&&o!==r&&p(t,o,{get:()=>e[o],enumerable:!(n=A(e,o))||n.enumerable});return t};var g=(t,e,r)=>(r=t!=null?k(_(t)):{},F(e||!t||!t.__esModule?p(r,"default",{value:t,enumerable:!0}):r,t)),D=t=>F(p({},"__esModule",{value:!0}),t);var q={};v(q,{createCompiler:()=>C,default:()=>W});var U=typeof process<"u"&&process.versions?.node!=null,a=t=>t.join(`
+`);async function G(t){if(String(t).startsWith("file:")){let{readFile:n}=await import("node:fs/promises"),{gunzipSync:o}=await import("node:zlib");return new Uint8Array(o(await n(t)))}let e=await fetch(t);if(!e.ok)throw new Error(`fetching ${t}: ${e.status} ${e.statusText}`);let r=e.body.pipeThrough(new DecompressionStream("gzip"));return new Uint8Array(await new Response(r).arrayBuffer())}function H(t){let e=new TextEncoder;return r=>{let n=t.FS;if(!n)throw new Error("FS was not exported, so stdin cannot be wired");n.writeFile("/.stdin",e.encode(r));let o=n.open("/.stdin","r");n.streams[0]&&n.close(n.streams[0]),n.streams[0]=o}}async function C(t={}){let{baseUrl:e,glueUrl:r,assetBaseUrl:n,wasmUrl:o,wasmBinary:B,print:x,printErr:L}=t,u=new URL(n??(e?new URL(e,"https://cdn.jsdelivr.net/npm/@live-codes/lfortran-wasm@0.1.1/src/index.js"):new URL("../assets/","https://cdn.jsdelivr.net/npm/@live-codes/lfortran-wasm@0.1.1/src/index.js")),"https://cdn.jsdelivr.net/npm/@live-codes/lfortran-wasm@0.1.1/src/index.js"),l=U&&u.protocol==="file:",b=l?(await import("node:url")).fileURLToPath:null,$=s=>{let d=new URL(s,u);return l?b(d):d.href},i=[],c=[],z=B??await G(new URL(o??"wasm_run.wasm.gz",u)),w=new URL(r??"wasm_run.js",u).href;if(l&&!/^(file|data):/.test(w))throw new Error(`node cannot import the glue from ${w}: its ESM loader supports only file: and data: URLs. Point glueUrl at a local copy, or run this in a browser or a worker.`);let S=await import(w),E=S.default??S.createLFortran;if(typeof E!="function")throw new Error("the glue module did not export a factory");let f=await E({locateFile:$,wasmBinary:z,print:s=>x?x(s):i.push(s),printErr:s=>L?L(s):c.push(s)}),M=f.cwrap("run_fortran","string",["string"]),T=H(f);return{module:f,async run(s,d=""){i.length=0,c.length=0,T(d);let m=performance.now(),j=U?process.exitCode:void 0;try{let h;try{h=M(s)}catch(R){return{stdout:a(i),errors:a(c)||`the program terminated: ${R?.message??R}`,exitCode:null,runMs:performance.now()-m}}return h==="0"?{stdout:a(i),errors:a(c),exitCode:0,runMs:performance.now()-m}:{stdout:a(i),errors:h.replace(/^1,/,"")||a(c),exitCode:null,runMs:performance.now()-m}}finally{U&&(process.exitCode=j)}}}}var W=C;return D(q);})();

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@live-codes/lfortran-wasm",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Run modern Fortran in the browser or in Node, on LFortran's LLVM backend compiled to WebAssembly",
   "type": "module",
   "license": "MIT",
   "exports": {
-    ".": "./src/index.js"
+    ".": "./src/index.js",
+    "./iife": "./dist/lfortran-wasm.global.js"
   },
   "bin": {
     "lfortran-wasm-copy-assets": "./bin/copy-assets.mjs"
@@ -13,6 +14,8 @@
   "files": [
     "src",
     "bin",
+    "scripts",
+    "dist",
     "assets",
     "THIRD-PARTY-NOTICES.md"
   ],
@@ -21,8 +24,12 @@
   },
   "scripts": {
     "copy-assets": "node bin/copy-assets.mjs",
+    "build:iife": "node scripts/build-iife.mjs",
     "test": "node --test \"test/*.test.js\""
   },
+  "devDependencies": {
+    "esbuild": "^0.25.0"
+  },
   "keywords": [
     "fortran",
     "lfortran",

package/scripts/build-iife.mjs

@@ -0,0 +1,64 @@
+// Builds the IIFE bundle: one classic script for workers and pages that cannot use ES modules.
+//
+//   npm run build:iife
+//
+// Why this exists: `importScripts()` evaluates a *classic* script, and an ES module is not one. Measured
+// in Chromium, against the same CDN — importing the clang package's IIFE works, while importing our
+// `assets/wasm_run.js` fails with a NetworkError precisely because it is a module. The glue can stay a
+// module (this bundle reaches it with dynamic import(), which a classic worker supports), but the
+// loader itself has to have a classic form for `importScripts` to be able to load anything.
+//
+// The output is committed, because a classic worker can only point at a URL and a consumer should not
+// need a bundler to get one.
+//
+// `import.meta.url` is defined rather than left to the bundler: esbuild has no meaning for it in an
+// IIFE, and the loader uses it for its default asset base. Pointing it at this package's `src/index.js`
+// on jsDelivr makes the default resolve to `.../assets/` there, which is what a consumer of the global
+// build wants; `baseUrl` still overrides it, which is how the local build is tested.
+import { readFileSync, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const packageJson = JSON.parse(
+	readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8'),
+);
+const sourceUrl = `https://cdn.jsdelivr.net/npm/${packageJson.name}@${packageJson.version}/src/index.js`;
+const outfile = fileURLToPath(new URL('../dist/lfortran-wasm.global.js', import.meta.url));
+
+// esbuild is a devDependency of this package. In this repository the sibling package already has it
+// installed, so fall back to that rather than requiring a network install to build.
+async function loadEsbuild() {
+	try {
+		return await import('esbuild');
+	} catch {
+		// A file: URL, not a path — on Windows a bare `D:\...` is read as a URL scheme.
+		const sibling = new URL('../../fortran-wasm/node_modules/esbuild/lib/main.js', import.meta.url);
+		return import(sibling.href);
+	}
+}
+
+const { build } = await loadEsbuild();
+
+const banner = `/*! ${packageJson.name} - MIT. IIFE build, sets self.lfortranWasm.
+ *  importScripts('lfortran-wasm.global.js') then self.lfortranWasm.createCompiler({ baseUrl }).
+ *  Downloads the LFortran + LLVM wasm from assets/ (19 MiB compressed). LFortran is BSD 3-Clause and
+ *  LLVM is Apache-2.0 WITH LLVM-exception - see THIRD-PARTY-NOTICES.md. */`;
+
+await build({
+	entryPoints: [fileURLToPath(new URL('../src/index.js', import.meta.url))],
+	outfile,
+	bundle: true,
+	format: 'iife',
+	globalName: 'lfortranWasm',
+	minify: true,
+	platform: 'browser',
+	target: 'es2022',
+	// Node-only paths in the loader are behind a runtime check and never taken in a browser, so they are
+	// left as imports rather than bundled.
+	external: ['node:*'],
+	define: { 'import.meta.url': JSON.stringify(sourceUrl) },
+	legalComments: 'external',
+	banner: { js: banner },
+});
+
+console.log(`dist/lfortran-wasm.global.js  ${(statSync(outfile).size / 1024).toFixed(1)} KB (minified)`);
+console.log(`default asset base: ${new URL('../assets/', sourceUrl).href}`);

package/src/index.js

@@ -93,7 +93,17 @@ export async function createCompiler(options = {}) {
 	const stdout = [];
 	const stderr = [];
 	const binary = wasmBinary ?? (await readGzippedBytes(new URL(wasmUrl ?? 'wasm_run.wasm.gz', assetBase)));
-	const glue = await import(new URL(glueUrl ?? 'wasm_run.js', assetBase).href);
+	const glueHref = new URL(glueUrl ?? 'wasm_run.js', assetBase).href;
+	if (inNode && !/^(file|data):/.test(glueHref)) {
+		// Node's ESM loader accepts only file: and data: URLs, so a CDN-hosted glue cannot be imported
+		// there even though the wasm and .data fetch fine over https. Browsers and workers import it
+		// from a CDN without ceremony, which is where this normally runs.
+		throw new Error(
+			`node cannot import the glue from ${glueHref}: its ESM loader supports only file: and data: URLs. ` +
+				'Point glueUrl at a local copy, or run this in a browser or a worker.',
+		);
+	}
+	const glue = await import(glueHref);
 	const factory = glue.default ?? glue.createLFortran;
 	if (typeof factory !== 'function') {
 		throw new Error('the glue module did not export a factory');