JavaScript: provide type definitions for TypeScript

.github/workflows/cd.yml

@@ -269,11 +269,13 @@ jobs:
           local-path: ./build/src/bindings/javascript/build/src/wasm
           remote-path: /home/www/opencor.ws/libopencor/downloads/wasm
           sync: full
-      - name: Publish libOpenCOR
+      - name: Publish libOpenCOR and its types
         # To publish using OIDC implies automatic provenance generation, so no need to specify --provenance (see
         # https://docs.npmjs.com/trusted-publishers). Provenance requires "repository.url" in package.json to match the
         # repository from which we are publishing. In our case, it means that we can only publish to npm from the
         # "opencor/libopencor" repository. (Provenance can be disabled, but we prefer to be open.)
         run: |
           cd build/src/bindings/javascript/build/src
           npm publish --access public --no-git-checks
+          cd types
+          npm publish --access public --no-git-checks

VERSION.txt

@@ -1 +1 @@
-1.20260713.0
+1.20260716.0

cmake/common.cmake

@@ -363,12 +363,14 @@ function(configure_target TARGET)
     # Mark as advanced the CMake variables set by our various packages.
 
     mark_as_advanced(CURL_DIR
+                     CURL_USE_CMAKECONFIG
+                     CURL_USE_PKGCONFIG
                      Clang_DIR
                      LLVM_DIR
-                     Libssh2_DIR
                      SUNDIALS_DIR
                      combine-static_DIR
                      libCellML_DIR
+                     libssh2_DIR
                      numl-static_DIR
                      sbml-static_DIR
                      sedml-static_DIR)

cmake/environmentchecks.cmake

@@ -127,10 +127,14 @@ if(Python_EXECUTABLE)
 
     mark_as_advanced(NB_CREATE_INSTALL_RULES
                      NB_TEST
-                     NB_TEST_SANITZE
+                     NB_TEST_CUDA
+                     NB_TEST_FREE_THREADED
+                     NB_TEST_SANITIZERS_ASAN
+                     NB_TEST_SANITIZERS_TSAN
+                     NB_TEST_SANITIZERS_UBSAN
                      NB_TEST_SHARED_BUILD
                      NB_TEST_STABLE_ABI
-                     nanobind_DIR)
+                     NB_USE_SUBMODULE_DEPS)
 endif()
 
 # Look for various programs.

src/CMakeLists.txt

@@ -328,11 +328,14 @@ if(EMSCRIPTEN)
     #          -sINITIAL_TABLE=65536 to have enough space for our WebAssembly table, -sINLINING_LIMIT to increase the
     #          inlining limit, -sMODULARIZE=1 to generate a module factory function, -sSHARED_MEMORY=1 to enable shared
     #          memory support, -sSTACK_SIZE=8MB to reserve a reasonable amount of memory for the stack at startup (which
-    #          is needed for "big" models), and --bind to generate the necessary Embind bindings.
+    #          is needed for "big" models), --bind to generate the necessary Embind bindings, and --emit-tsd to generate
+    #          a TypeScript type definitions file.
     # Note #3: for linking, we used to have -sALLOW_MEMORY_GROWTH=1, -sINITIAL_MEMORY=256MB, and -sMAXIMUM_MEMORY=2GB,
     #          but we now support threading and to allow memory growth might non-WASM code to run slowly. So, now, we
     #          use -sINITIAL_MEMORY=2GB and don't allow memory growth.
 
+    set(DTS_FILE ${CMAKE_PROJECT_NAME}.d.ts)
+
     target_compile_options(${CMAKE_PROJECT_NAME} PRIVATE
                            -O3
                            -matomics
@@ -355,41 +358,66 @@ if(EMSCRIPTEN)
                         -sMODULARIZE=1
                         -sSHARED_MEMORY=1
                         -sSTACK_SIZE=8MB
-                        --bind)
+                        --bind
+                        --emit-tsd ${DTS_FILE})
 
     # Package our JavaScript bindings, if possible.
 
+    find_program(NODE_EXE NAMES node)
     find_program(NPM_EXE NAMES ${PREFERRED_NPM_NAMES} npm)
 
-    if(NPM_EXE)
+    if(NODE_EXE AND NPM_EXE)
+        # Post-process the generated .d.ts to match our EM_ASM runtime patches.
+
+        add_custom_command(TARGET ${CMAKE_PROJECT_NAME} POST_BUILD
+                           COMMAND ${NODE_EXE} ${CMAKE_SOURCE_DIR}/src/bindings/javascript/postprocess.dts.mjs ${DTS_FILE})
+
+        # Package our JavaScript bindings into a .tgz file that can be published to npm.
+
         set(TGZ_FILENAME ${REAL_CMAKE_PROJECT_NAME}-${PROJECT_VERSION}.tgz)
         set(TGZ_FILE ${CMAKE_BINARY_DIR}/../../../../${TGZ_FILENAME})
 
         add_custom_command(TARGET ${CMAKE_PROJECT_NAME} POST_BUILD
                            COMMAND ${CMAKE_COMMAND} -E make_directory dist
+                           COMMAND ${CMAKE_COMMAND} -E copy ${DTS_FILE} dist
                            COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_PROJECT_NAME}.js dist
                            COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_PROJECT_NAME}.wasm dist
-                           COMMAND ${CMAKE_COMMAND} -E copy package.json dist
                            COMMAND ${NPM_EXE} pack
                            COMMAND ${CMAKE_COMMAND} -E copy opencor-${TGZ_FILENAME} ${TGZ_FILE})
+
+        # Also package our .d.ts file as a standalone TypeScript type definitions package.
+
+        set(TYPES_TGZ_FILENAME ${REAL_CMAKE_PROJECT_NAME}-types-${PROJECT_VERSION}.tgz)
+        set(TYPES_TGZ_FILE ${CMAKE_BINARY_DIR}/../../../../${TYPES_TGZ_FILENAME})
+
+        add_custom_command(TARGET ${CMAKE_PROJECT_NAME} POST_BUILD
+                           COMMAND ${CMAKE_COMMAND} -E make_directory types/dist
+                           COMMAND ${CMAKE_COMMAND} -E copy package.types.json types/package.json
+                           COMMAND ${CMAKE_COMMAND} -E copy README.md types
+                           COMMAND ${CMAKE_COMMAND} -E copy LICENSE.txt types
+                           COMMAND ${CMAKE_COMMAND} -E copy ${DTS_FILE} types/dist
+                           COMMAND ${CMAKE_COMMAND} -E chdir types ${NPM_EXE} pack
+                           COMMAND ${CMAKE_COMMAND} -E copy types/opencor-${TYPES_TGZ_FILENAME} ${TYPES_TGZ_FILE})
     else()
-        message(WARNING "npm could not be found, so libOpenCOR's JavaScript bindings could not be packaged.")
+        message(FATAL_ERROR "The node and/or npm tools could not be found, so libOpenCOR's JavaScript bindings could not be finalised and packaged.")
     endif()
 
     # Copy our generated files over so that they can be deployed.
 
     foreach(DEPLOY_DIR ${CMAKE_PROJECT_VERSION} latest)
         add_custom_command(TARGET ${CMAKE_PROJECT_NAME} POST_BUILD
                            COMMAND ${CMAKE_COMMAND} -E make_directory wasm/${DEPLOY_DIR}
-                           COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_PROJECT_NAME}.js wasm/${DEPLOY_DIR}/${CMAKE_PROJECT_NAME}.js
-                           COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_PROJECT_NAME}.wasm wasm/${DEPLOY_DIR}/${CMAKE_PROJECT_NAME}.wasm)
+                           COMMAND ${CMAKE_COMMAND} -E copy ${DTS_FILE} wasm/${DEPLOY_DIR}
+                           COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_PROJECT_NAME}.js wasm/${DEPLOY_DIR}
+                           COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_PROJECT_NAME}.wasm wasm/${DEPLOY_DIR})
     endforeach()
 
     # Copy our generated files over so that they can be used by our test Web page.
 
     add_custom_command(TARGET ${CMAKE_PROJECT_NAME} POST_BUILD
-                       COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_PROJECT_NAME}.js ${JAVASCRIPT_BINDINGS_DIR}/${CMAKE_PROJECT_NAME}.js
-                       COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_PROJECT_NAME}.wasm ${JAVASCRIPT_BINDINGS_DIR}/${CMAKE_PROJECT_NAME}.wasm)
+                       COMMAND ${CMAKE_COMMAND} -E copy ${DTS_FILE} ${JAVASCRIPT_BINDINGS_DIR}/${DTS_FILE}
+                       COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_PROJECT_NAME}.js ${JAVASCRIPT_BINDINGS_DIR}
+                       COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_PROJECT_NAME}.wasm ${JAVASCRIPT_BINDINGS_DIR})
 
     # Let people know how to run our test Web page.
 

src/bindings/javascript/CMakeLists.txt

@@ -55,6 +55,8 @@ if(EMSCRIPTEN OR LIBOPENCOR_JAVASCRIPT_BINDINGS)
         configure_file(${CMAKE_CURRENT_SOURCE_DIR}/package.in.json ${CMAKE_CURRENT_BINARY_DIR}/../../package.json @ONLY)
         configure_file(${CMAKE_SOURCE_DIR}/README.md ${CMAKE_CURRENT_BINARY_DIR}/../../README.md)
         configure_file(${CMAKE_SOURCE_DIR}/LICENSE.txt ${CMAKE_CURRENT_BINARY_DIR}/../../LICENSE.txt)
+
+        configure_file(${CMAKE_CURRENT_SOURCE_DIR}/package.types.in.json ${CMAKE_CURRENT_BINARY_DIR}/../../package.types.json @ONLY)
     else()
         # Build our JavaScript bindings.
 

src/bindings/javascript/file.cpp

@@ -83,9 +83,11 @@ void fileApi()
 
     // clang-format off
     EM_ASM({
-        Module["File"]["Type"] = Module["File.Type"];
+        if (Module["File"]) {
+            Module["File"]["Type"] = Module["File.Type"];
 
-        delete Module["File.Type"];
+            delete Module["File.Type"];
+        }
     }); // clang-format on
 
     // FileManager API.

src/bindings/javascript/logger.cpp

@@ -48,12 +48,14 @@ void loggerApi()
 
     // clang-format off
     EM_ASM({
-        Module["Issue"]["Type"] = Module["Issue.Type"];
+        if (Module["Issue"]) {
+            Module["Issue"]["Type"] = Module["Issue.Type"];
 
-        delete Module["Issue.Type"];
+            delete Module["Issue.Type"];
 
-        Module["Issue"].prototype.toString = function() {
-            return this.description;
-        };
+            Module["Issue"].prototype.toString = function() {
+                return this.description;
+            };
+        }
     }); // clang-format on
 }

src/bindings/javascript/main.cpp

@@ -60,7 +60,13 @@ EMSCRIPTEN_BINDINGS(libOpenCOR)
         let vectorNames = 'Doubles|FilePtrs|IssuePtrs|SedAbstractTaskPtrs|SedChangePtrs|SedDataDescriptionPtrs|SedDataGeneratorPtrs|SedInstanceTaskPtrs|SedModelPtrs|SedOutputPtrs|SedSimulationPtrs|SedStylePtrs|Strings'.split('|');
 
         vectorNames.forEach((name) => {
-            let prototype = Module[name].prototype;
+            let vectorClass = Module[name];
+
+            if (!vectorClass) {
+                return;
+            }
+
+            let prototype = vectorClass.prototype;
 
             Object.defineProperty(prototype, 'length', {
                 get: function() {

src/bindings/javascript/package.in.json

@@ -6,22 +6,27 @@
   "bugs": {
     "url": "https://github.com/opencor/libopencor/issues"
   },
-  "description": "libOpenCOR is is a library that can be used to organise, edit, simulate, and analyse CellML files.",
+  "description": "libOpenCOR is a library that can be used to organise, edit, simulate, and analyse CellML files.",
   "exports": {
-    ".": "./dist/libopencor.js",
-    "./libopencor.wasm": "./dist/libopencor.wasm"
+    ".": {
+      "types": "./dist/libopencor.d.ts",
+      "import": "./dist/libopencor.js"
+    }
   },
-  "files": ["dist/libopencor.js", "dist/libopencor.wasm", "README.md", "LICENSE.txt"],
+  "files": ["dist/libopencor.d.ts", "dist/libopencor.js", "dist/libopencor.wasm", "README.md", "LICENSE.txt"],
   "homepage": "https://opencor.ws/libopencor/",
   "keywords": ["cellml", "combine", "omex", "opencor", "sed-ml"],
   "license": "Apache-2.0",
+  "main": "dist/libopencor.js",
   "module": "dist/libopencor.js",
   "name": "@opencor/libopencor",
   "productName": "libOpenCOR",
+  "sideEffects": false,
   "repository": {
     "type": "git",
     "url": "git+https://github.com/opencor/libopencor.git"
   },
   "type": "module",
+  "types": "dist/libopencor.d.ts",
   "version": "@PROJECT_VERSION@"
 }

src/bindings/javascript/package.types.in.json

@@ -0,0 +1,25 @@
+{
+  "author": {
+    "name": "Alan Garny",
+    "email": "a.garny@auckland.ac.nz"
+  },
+  "bugs": {
+    "url": "https://github.com/opencor/libopencor/issues"
+  },
+  "description": "libOpenCOR TypeScript type definitions.",
+  "files": ["dist/libopencor.d.ts", "README.md", "LICENSE.txt"],
+  "homepage": "https://opencor.ws/libopencor/",
+  "keywords": ["cellml", "combine", "omex", "opencor", "sed-ml", "types"],
+  "license": "Apache-2.0",
+  "main": "dist/libopencor.d.ts",
+  "name": "@opencor/libopencor-types",
+  "productName": "libOpenCOR types",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/opencor/libopencor.git"
+  },
+  "type": "module",
+  "types": "dist/libopencor.d.ts",
+  "version": "@PROJECT_VERSION@"
+}