Switch to memory64 for the Wasm build to enable greater memory usage. (#99)

Now we forcibly return a double instead of size_ts for all methods, to avoid
the confusion of dealing with a mix of Numbers/BigInts in Javascript.

Node >= 24 MUST be used with memory64. Updated actions to use the latest
builder image with an appropriately modern Node.

Author: LTLA

.github/workflows/publish-npm.yaml

@@ -7,10 +7,25 @@ on:
 name: Build and publish to NPM 
 
 jobs:
+  prepare-version:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout repo
+      uses: actions/checkout@v4
+
+    - id: find-version
+      run: |
+        version=$(cat .image-version)
+        echo "version=${version}" >> $GITHUB_OUTPUT
+
+    outputs:
+      version: ${{ steps.find-version.outputs.version }}
+
   build:
     runs-on: ubuntu-latest
+    needs: [prepare-version]
     if: ${{ github.event.workflow_run.conclusion == 'success' }}
-    container: ghcr.io/kanaverse/emcmake-docker/builder:master
+    container: ghcr.io/kanaverse/emcmake-docker/builder:${{ needs.prepare-version.outputs.version }}
 
     steps:
     - name: Checkout repo
@@ -19,7 +34,7 @@ jobs:
     - name: Set up Node
       uses: actions/setup-node@v4
       with:
-        node-version: 18
+        node-version: 24
         registry-url: 'https://registry.npmjs.org'
 
     # We only run the remaining (remote-touching) steps if the version has actually changed.
@@ -38,7 +53,7 @@ jobs:
       uses: actions/cache@v4
       with:
         path: extern/installed
-        key: deps-${{ hashFiles('extern/**/build.sh') }}-${{ env.IMAGE_VERSION }}
+        key: deps-${{ hashFiles('extern/**/build.sh') }}-${{ needs.prepare-version.outputs.version }}
 
     - name: Cache Modules
       if: env.UPDATE_SCRANJS == 1
@@ -64,7 +79,7 @@ jobs:
       uses: actions/cache@v4
       with:
         path: tests/rds/*.rds
-        key: rds-${{ hashFiles('tests/rds/generate.R') }}
+        key: rds-${{ hashFiles('tests/rds/generate.R') }}-${{ needs.prepare-version.outputs.version }}
 
     - name: Double-checking tests
       if: env.UPDATE_SCRANJS == 1

.github/workflows/run-tests.yaml

@@ -6,16 +6,20 @@ on:
 
 name: Test JS bindings
 
-env:
-  IMAGE_VERSION: master
-
 jobs:
   prepare-version:
     runs-on: ubuntu-latest
     steps:
-    - run: echo "null"
+    - name: Checkout repo
+      uses: actions/checkout@v4
+
+    - id: find-version
+      run: |
+        version=$(cat .image-version)
+        echo "version=${version}" >> $GITHUB_OUTPUT
+
     outputs:
-      version: ${{ env.IMAGE_VERSION }}
+      version: ${{ steps.find-version.outputs.version }}
 
   # Building the RDS files for the various RDS-reading utilities.
   create_rds:
@@ -53,7 +57,7 @@ jobs:
       uses: actions/cache@v4
       with:
         path: extern/installed
-        key: deps-${{ hashFiles('extern/**/build.sh') }}-${{ env.IMAGE_VERSION }}
+        key: deps-${{ hashFiles('extern/**/build.sh') }}-${{ needs.prepare-version.outputs.version }}
 
     - name: Build HDF5
       if: steps.installed.outputs.cache-hit != 'true'
@@ -79,7 +83,7 @@ jobs:
     - name: Set up Node
       uses: actions/setup-node@v4
       with:
-        node-version: 18
+        node-version: 24
 
     - name: Cache Modules
       uses: actions/cache@v4
@@ -94,7 +98,7 @@ jobs:
       uses: actions/cache@v4
       with:
         path: extern/installed
-        key: deps-${{ hashFiles('extern/**/build.sh') }}-${{ env.IMAGE_VERSION }}
+        key: deps-${{ hashFiles('extern/**/build.sh') }}-${{ needs.prepare-version.outputs.version }}
 
     - name: Cache RDS files
       uses: actions/cache@v4
@@ -107,7 +111,7 @@ jobs:
       uses: actions/cache@v4
       with:
         path: js/wasm
-        key: wasm-${{ hashFiles('build.sh', 'extern/**/build.sh', 'CMakeLists.txt', 'extern/CMakeLists.txt', 'src/*') }}-${{ env.IMAGE_VERSION }}
+        key: wasm-${{ hashFiles('build.sh', 'extern/**/build.sh', 'CMakeLists.txt', 'extern/CMakeLists.txt', 'src/*') }}-${{ needs.prepare-version.outputs.version }}
 
     - name: Update node build 
       if: steps.wasm-build.outputs.cache-hit != 'true'

.image-version

@@ -0,0 +1 @@
+2025-11-25

.npmrc

@@ -0,0 +1 @@
+engine-strict=true

CMakeLists.txt

@@ -71,6 +71,7 @@ target_compile_options(
     scran_wasm PUBLIC 
     -O3
     -pthread
+    -sMEMORY64
 )
 
 target_link_libraries(
@@ -121,7 +122,8 @@ target_link_options(scran_wasm PRIVATE
     -O3
     --bind 
     -sALLOW_MEMORY_GROWTH=1 
-    -sMAXIMUM_MEMORY=4GB 
+    -sMEMORY64
+    -sMAXIMUM_MEMORY=16GB # current maximum, otherwise Emscripten complains.
     -sSTACK_SIZE=2MB
     -sUSE_ZLIB=1 
     -sMODULARIZE=1 
@@ -137,14 +139,15 @@ set_target_properties(scran_wasm PROPERTIES OUTPUT_NAME scran)
 
 set(COMPILE_NODE OFF CACHE BOOL "Compile for Node.js")
 if (COMPILE_NODE)
+    # Exporting HEAP8 for compatibility with old wasmarrays.js.
     target_link_options(scran_wasm PRIVATE
         -sENVIRONMENT=node 
         -sNODERAWFS=1
-        -sEXPORTED_RUNTIME_METHODS=wasmMemory,PThread
+        -sEXPORTED_RUNTIME_METHODS=wasmMemory,HEAP8,PThread
     )
 else ()
     target_link_options(scran_wasm PRIVATE 
         -sENVIRONMENT=web,worker 
-        -sEXPORTED_RUNTIME_METHODS=wasmMemory,PThread,FS
+        -sEXPORTED_RUNTIME_METHODS=wasmMemory,HEAP8,PThread,FS
     )
 endif()

build.sh

@@ -45,12 +45,16 @@ if [ ! -e $builddir ]
 then
     mkdir $builddir
     echo "{}" > $builddir/package.json # avoid assuming ES6 syntax for igraph config scripts.
+
+    # Setting the C flags below, even though we don't have any C;
+    # this ensures that emcmake knows to operate in 64-bit mode for find_package().
     emcmake cmake \
         -S . \
         -B $builddir \
         -DCOMPILE_NODE=${node_flag} \
         -DCMAKE_BUILD_TYPE=Release \
         -DCMAKE_PREFIX_PATH=extern/installed \
+        -DCMAKE_C_FLAGS="-sMEMORY64" \
         -DTATAMI_HDF5_FIND_HDF5=OFF
 fi
 

extern/CMakeLists.txt

@@ -95,7 +95,7 @@ FetchContent_Declare(
 FetchContent_Declare(
   scran_qc
   GIT_REPOSITORY https://github.com/libscran/scran_qc
-  GIT_TAG master
+  GIT_TAG v0.1.1
 )
 
 FetchContent_Declare(

extern/hdf5/build.sh

@@ -30,7 +30,7 @@ BUILD_DIR=build-${HDF5_VERSION}
 if [ ! -e ${BUILD_DIR} ]
 then
     mkdir -p ../installed
-    coreflags="-pthread" # propagating compile flags from the root scran.js CMakeLists.txt.
+    coreflags="-pthread -sMEMORY64" # propagating compile flags from the root scran.js CMakeLists.txt.
     echo "{}" > package.json # avoid assuming ES6 module syntax from the root scran.js package.json.
     emcmake cmake \
         -S ${SOURCE_DIR} \

extern/igraph/build.sh

@@ -23,7 +23,7 @@ BUILD_DIR=build-${IGRAPH_VERSION}
 if [ ! -e ${BUILD_DIR} ]
 then
     mkdir -p ../installed
-    coreflags="-pthread" # propagating compile flags from the root scran.js CMakeLists.txt.
+    coreflags="-pthread -sMEMORY64" # propagating compile flags from the root scran.js CMakeLists.txt.
     echo "{}" > package.json # avoid assuming ES6 module syntax from the root scran.js package.json.
     emcmake cmake \
         -S ${SOURCE_DIR} \

js/wasm.js

@@ -8,9 +8,7 @@ const cache = {};
  * @param {object} [options={}] - Optional parameters.
  * @param {number} [options.numberOfThreads=4] - Number of threads to use for calculations.
  * This will spin up the requested number of Web Workers during module initialization.
- * @param {boolean} [options.localFile=false] - Whether or not to look for the Wasm and worker scripts locally.
- * This should only be `true` when using old versions of Node.js where file URLs are not supported, 
- * and is ignored completely outside of Node.js contexts.
+ * @param {boolean} [options.localFile=false] - Deprecated and ignored.
  *
  * @return {boolean}
  * The Wasm bindings are initialized and `true` is returned.
@@ -25,10 +23,6 @@ export async function initialize({ numberOfThreads = 4, localFile = false } = {}
         scran_custom_nthreads: numberOfThreads
     };
 
-    if (localFile) {                                                                /** NODE ONLY **/  
-        options.locateFile = (x) => import.meta.url.substring(7) + "/../wasm/" + x; /** NODE ONLY **/
-    }                                                                               /** NODE ONLY **/
-
     cache.module = await loadScran(options);
     cache.space = register(cache.module);