Replace FS_createPreloadedFile with async version (#24917)

sbc100 · web-flow · commit 319a76c53794 · 2025-08-13T12:37:27.000-07:00
The new `FS_preloadFile` API replaces the `FS_createPreloadedFile` API. Keeping the old version around for compatibility. Followup to #24914
diff --git a/src/jsifier.mjs b/src/jsifier.mjs
@@ -102,8 +102,8 @@ function stringifyWithFunctions(obj) {
   for (const [key, value] of Object.entries(obj)) {
     var str = stringifyWithFunctions(value);
     // Handle JS method syntax where the function property starts with its own
-    // name. e.g.  foo(a) {},
-    if (typeof value === 'function' && str.startsWith(key)) {
+    // name. e.g.  `foo(a) {}` (or `async foo(a) {}`)
+    if (typeof value === 'function' && (str.startsWith(key) || str.startsWith('async ' + key))) {
       rtn += str + ',\n';
     } else {
       rtn += escapeJSONKey(key) + ':' + str + ',\n';
diff --git a/src/lib/libfs.js b/src/lib/libfs.js
@@ -39,6 +39,7 @@ var LibraryFS = {
     return `
 #if !MINIMAL_RUNTIME
 FS.createPreloadedFile = FS_createPreloadedFile;
+FS.preloadFile = FS_preloadFile;
 #endif
 FS.staticInit();`;
   },
diff --git a/src/lib/libfs_shared.js b/src/lib/libfs_shared.js
@@ -32,6 +32,12 @@ addToLibrary({
     return byteArray;
   },
 
+  // Legacy version of FS_preloadFile that uses callback rather than async
+  $FS_createPreloadedFile__deps: ['$FS_preloadFile'],
+  $FS_createPreloadedFile: (parent, name, url, canRead, canWrite, onload, onerror, dontCreateFile, canOwn, preFinish) => {
+    FS_preloadFile(parent, name, url, canRead, canWrite, dontCreateFile, canOwn, preFinish).then(onload).catch(onerror);
+  },
+
   // Preloads a file asynchronously. You can call this before run, for example in
   // preRun. run will be delayed until this file arrives and is set up.
   // If you call it after run(), you may want to pause the main loop until it
@@ -44,39 +50,33 @@ addToLibrary({
   // You can also call this with a typed array instead of a url. It will then
   // do preloading for the Image/Audio part, as if the typed array were the
   // result of an XHR that you did manually.
-  $FS_createPreloadedFile__deps: [
+  $FS_preloadFile__deps: [
     '$asyncLoad',
     '$PATH_FS',
     '$FS_createDataFile',
     '$getUniqueRunDependency',
     '$FS_handledByPreloadPlugin',
   ],
-  $FS_createPreloadedFile: (parent, name, url, canRead, canWrite, onload, onerror, dontCreateFile, canOwn, preFinish) => {
+  $FS_preloadFile: async (parent, name, url, canRead, canWrite, dontCreateFile, canOwn, preFinish) => {
     // TODO we should allow people to just pass in a complete filename instead
     // of parent and name being that we just join them anyways
     var fullname = name ? PATH_FS.resolve(PATH.join2(parent, name)) : parent;
     var dep = getUniqueRunDependency(`cp ${fullname}`); // might have several active requests for the same fullname
-    function processData(byteArray) {
-      FS_handledByPreloadPlugin(byteArray, fullname)
-        .then((byteArray) => {
-          preFinish?.();
-          if (!dontCreateFile) {
-            FS_createDataFile(parent, name, byteArray, canRead, canWrite, canOwn);
-          }
-          onload?.();
-          removeRunDependency(dep);
-        })
-        .catch(() =>  {
-          onerror?.();
-          removeRunDependency(dep);
-        });
-    }
-
     addRunDependency(dep);
-    if (typeof url == 'string') {
-      asyncLoad(url).then(processData, onerror);
-    } else {
-      processData(url);
+
+    try {
+      var byteArray = url;
+      if (typeof url == 'string') {
+        byteArray = await asyncLoad(url);
+      }
+
+      byteArray = await FS_handledByPreloadPlugin(byteArray, fullname);
+      preFinish?.();
+      if (!dontCreateFile) {
+        FS_createDataFile(parent, name, byteArray, canRead, canWrite, canOwn);
+      }
+    } finally {
+      removeRunDependency(dep);
     }
   },
 #endif
diff --git a/src/lib/libwasmfs.js b/src/lib/libwasmfs.js
@@ -33,6 +33,7 @@ addToLibrary({
     '$readI53FromU64',
     '$FS_createDataFile',
     '$FS_createPreloadedFile',
+    '$FS_preloadFile',
     '$FS_getMode',
     // For FS.readFile
     '$UTF8ArrayToString',
@@ -117,6 +118,10 @@ addToLibrary({
       return FS_createPreloadedFile(parent, name, url, canRead, canWrite, onload, onerror, dontCreateFile, canOwn, preFinish);
     },
 
+    async preloadFile(parent, name, url, canRead, canWrite, dontCreateFile, canOwn, preFinish) {
+      return FS_preloadFile(parent, name, url, canRead, canWrite, dontCreateFile, canOwn, preFinish);
+    },
+
 #if hasExportedSymbol('_wasmfs_read_file') // Support the JS function exactly
                                            // when the __wasmfs_* function is
                                            // present to be called (otherwise,
diff --git a/src/lib/libwget.js b/src/lib/libwget.js
@@ -20,7 +20,7 @@ var LibraryWget = {
     '$PATH_FS', '$callUserCallback', '$Browser',
     '$withStackSave', '$stringToUTF8OnStack',
     '$FS_mkdirTree',
-    '$FS_createPreloadedFile',
+    '$FS_preloadFile',
     '$FS_unlink',
   ],
   emscripten_async_wget__proxy: 'sync',
@@ -37,12 +37,10 @@ var LibraryWget = {
       }
     }
     var destinationDirectory = PATH.dirname(_file);
-    FS_createPreloadedFile(
+    FS_preloadFile(
       destinationDirectory,
       PATH.basename(_file),
       _url, true, true,
-      () => doCallback(onload),
-      () => doCallback(onerror),
       false, // dontCreateFile
       false, // canOwn
       () => { // preFinish
@@ -53,7 +51,7 @@ var LibraryWget = {
         // if the destination directory does not yet exist, create it
         FS_mkdirTree(destinationDirectory);
       }
-    );
+    ).then(() => doCallback(onload)).catch(() => doCallback(onerror));
   },
 
   emscripten_async_wget_data__deps: ['$asyncLoad', 'malloc', 'free', '$callUserCallback'],
diff --git a/src/runtime_debug.js b/src/runtime_debug.js
@@ -67,6 +67,7 @@ function isExportedByForceFilesystem(name) {
   return name === 'FS_createPath' ||
          name === 'FS_createDataFile' ||
          name === 'FS_createPreloadedFile' ||
+         name === 'FS_preloadFile' ||
          name === 'FS_unlink' ||
          name === 'addRunDependency' ||
 #if !WASMFS
diff --git a/test/code_size/test_codesize_hello_O0.json b/test/code_size/test_codesize_hello_O0.json
@@ -1,10 +1,10 @@
 {
-  "a.out.js": 22462,
-  "a.out.js.gz": 8335,
+  "a.out.js": 22503,
+  "a.out.js.gz": 8341,
   "a.out.nodebug.wasm": 15143,
   "a.out.nodebug.wasm.gz": 7452,
-  "total": 37605,
-  "total_gz": 15787,
+  "total": 37646,
+  "total_gz": 15793,
   "sent": [
     "fd_write"
   ],
diff --git a/test/code_size/test_codesize_hello_dylink_all.json b/test/code_size/test_codesize_hello_dylink_all.json
@@ -1,7 +1,7 @@
 {
-  "a.out.js": 246862,
+  "a.out.js": 246888,
   "a.out.nodebug.wasm": 597826,
-  "total": 844688,
+  "total": 844714,
   "sent": [
     "IMG_Init",
     "IMG_Load",
diff --git a/test/code_size/test_codesize_minimal_O0.json b/test/code_size/test_codesize_minimal_O0.json
@@ -1,10 +1,10 @@
 {
-  "a.out.js": 17723,
-  "a.out.js.gz": 6621,
+  "a.out.js": 17764,
+  "a.out.js.gz": 6628,
   "a.out.nodebug.wasm": 1136,
   "a.out.nodebug.wasm.gz": 659,
-  "total": 18859,
-  "total_gz": 7280,
+  "total": 18900,
+  "total_gz": 7287,
   "sent": [],
   "imports": [],
   "exports": [
diff --git a/test/code_size/test_unoptimized_code_size.json b/test/code_size/test_unoptimized_code_size.json
@@ -1,16 +1,16 @@
 {
-  "hello_world.js": 53923,
-  "hello_world.js.gz": 17123,
+  "hello_world.js": 53981,
+  "hello_world.js.gz": 17132,
   "hello_world.wasm": 15143,
   "hello_world.wasm.gz": 7452,
   "no_asserts.js": 26714,
   "no_asserts.js.gz": 8952,
   "no_asserts.wasm": 12227,
   "no_asserts.wasm.gz": 6008,
-  "strict.js": 51973,
-  "strict.js.gz": 16455,
+  "strict.js": 52031,
+  "strict.js.gz": 16465,
   "strict.wasm": 15143,
   "strict.wasm.gz": 7438,
-  "total": 175123,
-  "total_gz": 63428
+  "total": 175239,
+  "total_gz": 63447
 }
diff --git a/test/other/codesize/test_codesize_minimal_O0.expected.js b/test/other/codesize/test_codesize_minimal_O0.expected.js
@@ -341,6 +341,7 @@ function isExportedByForceFilesystem(name) {
   return name === 'FS_createPath' ||
          name === 'FS_createDataFile' ||
          name === 'FS_createPreloadedFile' ||
+         name === 'FS_preloadFile' ||
          name === 'FS_unlink' ||
          name === 'addRunDependency' ||
          // The old FS has some functionality that WasmFS lacks.
@@ -1014,6 +1015,7 @@ Module['FS_createPreloadedFile'] = FS.createPreloadedFile;
   'getSocketFromFD',
   'getSocketAddress',
   'FS_createPreloadedFile',
+  'FS_preloadFile',
   'FS_modeStringToFlags',
   'FS_getMode',
   'FS_stdin_getChar',
diff --git a/test/other/embind_tsgen_ignore_1.d.ts b/test/other/embind_tsgen_ignore_1.d.ts
@@ -2,7 +2,7 @@
 declare namespace RuntimeExports {
     function FS_createPath(...args: any[]): any;
     function FS_createDataFile(...args: any[]): any;
-    function FS_createPreloadedFile(parent: any, name: any, url: any, canRead: any, canWrite: any, onload: any, onerror: any, dontCreateFile: any, canOwn: any, preFinish: any): void;
+    function FS_preloadFile(parent: any, name: any, url: any, canRead: any, canWrite: any, dontCreateFile: any, canOwn: any, preFinish: any): Promise<void>;
     function FS_unlink(...args: any[]): any;
     function FS_createLazyFile(...args: any[]): any;
     function FS_createDevice(...args: any[]): any;
diff --git a/tools/file_packager.py b/tools/file_packager.py
@@ -677,11 +677,14 @@ def generate_js(data_target, data_files, metadata):
           % (start / (1024 * 1024)))
 
     create_preloaded = '''
-          Module['FS_createPreloadedFile'](this.name, null, byteArray, true, true,
-            () => Module['removeRunDependency'](`fp ${that.name}`),
-            () => err(`Preloading file ${that.name} failed`),
-            false, true); // canOwn this data in the filesystem, it is a slide into the heap that will never change\n'''
-    create_data = '''// canOwn this data in the filesystem, it is a slide into the heap that will never change
+          try {
+            // canOwn this data in the filesystem, it is a slice into the heap that will never change
+            await Module['FS_preloadFile'](this.name, null, byteArray, true, true, false, true);
+            Module['removeRunDependency'](`fp ${that.name}`);
+          } catch (e) {
+            err(`Preloading file ${that.name} failed`);
+          }\n'''
+    create_data = '''// canOwn this data in the filesystem, it is a slice into the heap that will never change
           Module['FS_createDataFile'](this.name, null, byteArray, true, true, true);
           Module['removeRunDependency'](`fp ${that.name}`);'''
 
@@ -707,7 +710,7 @@ def generate_js(data_target, data_files, metadata):
           var byteArray = this.byteArray.subarray(this.start, this.end);
           this.finish(byteArray);
         },
-        finish: function(byteArray) {
+        finish: async function(byteArray) {
           var that = this;
           %s
           this.requests[this.name] = null;
diff --git a/tools/link.py b/tools/link.py
@@ -1484,7 +1484,7 @@ def limit_incoming_module_api():
     settings.EXPORTED_RUNTIME_METHODS += [
       'FS_createPath',
       'FS_createDataFile',
-      'FS_createPreloadedFile',
+      'FS_preloadFile',
       'FS_unlink',
     ]
     if not settings.WASMFS:
