Improve error messages for mismatching peer dependencies (#220)

- Include dev versions that still satisfy semver - Address #191 --------- Co-authored-by: Nick Tessier <[email protected]>
iTwin · Oct 24, 2024 · 00224c3 · 00224c3
1 parent 93c960e
commit 00224c3
Show file tree

Hide file tree

Showing 3 changed files with 37 additions and 1 deletion.
diff --git a/change/@itwin-imodel-transformer-cd213d9d-704d-4184-b1a5-0e9890ae3af6.json b/change/@itwin-imodel-transformer-cd213d9d-704d-4184-b1a5-0e9890ae3af6.json
@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "improve error messages for mismatching peer dependencies",
+  "packageName": "@itwin/imodel-transformer",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}
diff --git a/packages/transformer/README.md b/packages/transformer/README.md
@@ -31,3 +31,20 @@ require("https").get("https://registry.npmjs.org/@itwin/imodel-transformer", r=>
 }))
 EOF
 ```
+
+## Environment Variables
+
+### TRANSFORMER_NO_STRICT_DEP_CHECK
+
+Set this variable to `1` to disable strict dependency checks in `packages/transformer/src/transformer.ts`. The strict dependency check validates that the version of @itwinjs/core-backend provided falls in the range defined by the peerDependencies of the transformer package.
+
+### SUGGEST_TRANSFORMER_VERSIONS
+
+Set this variable to `1` to enable `packages/transformer/src/transformer.ts` to suggest compatible versions if dependencies are not in the specified peer dependency range of this package.
+
+```dotenv
+# Disable strict dependency checks in transformer.ts
+TRANSFORMER_NO_STRICT_DEP_CHECK=1
+
+# Enable version suggestions in transformer.ts
+SUGGEST_TRANSFORMER_VERSIONS=1
diff --git a/packages/transformer/src/imodel-transformer.ts b/packages/transformer/src/imodel-transformer.ts
@@ -24,9 +24,21 @@ const ourITwinCoreBackendDepRange = peerDependencies["@itwin/core-backend"];
 const noStrictDepCheckEnvVar = "TRANSFORMER_NO_STRICT_DEP_CHECK";
 const suggestEnvVarName = "SUGGEST_TRANSFORMER_VERSIONS";
 
+// warn if using a prerelease or dev version
+if (semver.prerelease(iTwinCoreBackendVersion)) {
+  // eslint-disable-next-line no-console
+  console.warn(
+    `Warning: dev version detected (${iTwinCoreBackendVersion}). ` +
+      "This version is most likely fine, but it may introduce new behavior that could cause " +
+      "unexpected issues or changes in the transformer's functionality. Please proceed with caution."
+  );
+}
+
 if (
   process.env[noStrictDepCheckEnvVar] !== "1" &&
-  !semver.satisfies(iTwinCoreBackendVersion, ourITwinCoreBackendDepRange)
+  !semver.satisfies(iTwinCoreBackendVersion, ourITwinCoreBackendDepRange, {
+    includePrerelease: true,
+  })
 ) {
   const errHeader =
     `${ourName}@${ourVersion} only supports @itwin/core-backend@${ourITwinCoreBackendDepRange}, ` +