@equinor/fusion-framework-module-msal 4.0.8 → 4.1.0

package/src/versioning/create-version-message.ts

@@ -0,0 +1,63 @@
+import type { SemVer } from 'semver';
+import { VersionMessageType } from './static';
+
+/**
+ * Creates a human-readable version message based on the version message type.
+ *
+ * This function generates descriptive error messages for different version compatibility
+ * scenarios, helping developers understand version-related issues.
+ *
+ * @param type - The type of version message to create
+ * @param requestedVersion - The version that was requested by the user
+ * @param latestVersion - The latest available version in the system
+ * @returns A formatted, human-readable version message string
+ *
+ * @example
+ * ```typescript
+ * const message = createVersionMessage(
+ *   VersionMessageType.MajorIncompatibility,
+ *   '3.0.0',
+ *   '2.1.0'
+ * );
+ * // Returns: "Requested major version 3.0.0 is greater than the latest major version 2.1.0"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const message = createVersionMessage(
+ *   VersionMessageType.MinorMismatch,
+ *   '2.1.0',
+ *   '2.2.0'
+ * );
+ * // Returns: "Minor version mismatch, requested 2.1.0, latest 2.2.0"
+ * ```
+ */
+export const createVersionMessage = (
+  type: VersionMessageType,
+  requestedVersion: string | SemVer,
+  latestVersion: string | SemVer,
+): string => {
+  // Convert versions to strings for consistent formatting
+  const requestedVersionString = String(requestedVersion);
+  const latestVersionString = String(latestVersion);
+  switch (type) {
+    case VersionMessageType.MajorIncompatibility:
+      return `Requested major version ${requestedVersionString} is greater than the latest major version ${latestVersionString}`;
+    case VersionMessageType.InvalidVersion:
+      return `Invalid version ${requestedVersionString}`;
+    case VersionMessageType.InvalidLatestVersion:
+      return `Failed to parse latest version "${latestVersionString}" - this indicates the version.ts file was not generated correctly. Check for import errors in the build process.`;
+    case VersionMessageType.MinorMismatch:
+      return `Minor version mismatch, requested ${requestedVersionString}, latest ${latestVersionString}`;
+    case VersionMessageType.PatchDifference:
+      return `Patch version difference, requested ${requestedVersionString}, latest ${latestVersionString}`;
+    case VersionMessageType.IncompatibleVersion:
+      return `Incompatible version, requested ${requestedVersionString}, latest ${latestVersionString}`;
+    default:
+      return createVersionMessage(
+        VersionMessageType.IncompatibleVersion,
+        requestedVersion,
+        latestVersion,
+      );
+  }
+};

package/src/versioning/index.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Versioning module for MSAL module compatibility checking.
+ *
+ * This module provides comprehensive version resolution and validation functionality
+ * for the MSAL module, ensuring compatibility between different MSAL library versions.
+ *
+ * @example
+ * ```typescript
+ * import { resolveVersion, VersionError } from '@equinor/fusion-framework-module-msal/versioning';
+ *
+ * try {
+ *   const result = resolveVersion('2.1.0');
+ *   console.log('Version is compatible:', result.satisfiesLatest);
+ * } catch (error) {
+ *   if (error instanceof VersionError) {
+ *     console.error('Version error:', error.message);
+ *   }
+ * }
+ * ```
+ */
+
+// Core versioning functionality
+export { resolveVersion } from './resolve-version';
+
+// Error handling
+export { VersionError } from './VersionError';
+
+// Types
+export type { ResolvedVersion } from './types';

package/src/versioning/resolve-version.ts

@@ -0,0 +1,125 @@
+import semver, { type SemVer } from 'semver';
+
+import { MsalModuleVersion } from '../static';
+
+import { VersionError } from './VersionError';
+import type { ResolvedVersion } from './types';
+
+/**
+ * Resolves and validates a version string against the latest available MSAL version.
+ *
+ * This function performs comprehensive version checking including:
+ * - Parsing and validating the requested version
+ * - Checking major version compatibility (throws on incompatibility)
+ * - Warning on minor version mismatches (logs warning but continues)
+ * - Ignoring patch version differences for maximum compatibility
+ *
+ * @param version - The version string or SemVer object to resolve. If not provided, defaults to latest.
+ * @returns A ResolvedVersion object containing parsed versions and compatibility information
+ *
+ * @throws {VersionError} When the requested version is invalid or incompatible
+ *
+ * @example
+ * ```typescript
+ * // Resolve a specific version
+ * const result = resolveVersion('2.1.0');
+ * console.log(result.satisfiesLatest); // true if major version matches
+ *
+ * // Resolve with SemVer object
+ * const result2 = resolveVersion(new SemVer('2.0.0'));
+ *
+ * // Default to latest version
+ * const result3 = resolveVersion();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Error handling
+ * try {
+ *   const result = resolveVersion('3.0.0'); // Assuming latest is 2.x
+ * } catch (error) {
+ *   if (error instanceof VersionError) {
+ *     console.error('Version error:', error.message);
+ *   }
+ * }
+ * ```
+ */
+export function resolveVersion(version?: string | SemVer): ResolvedVersion {
+  // Initialize warnings array to collect any version mismatches
+  const warnings: string[] = [];
+
+  // Parse the requested version, defaulting to latest if not provided
+  const versionString = version || MsalModuleVersion.Latest;
+
+  // Parse versions using coerce for backward compatibility
+  const wantedVersion = semver.coerce(versionString);
+  const latestVersion = semver.coerce(MsalModuleVersion.Latest);
+
+  // Validate that the requested version is a valid semver
+  if (!wantedVersion) {
+    throw VersionError.create(
+      VersionError.Type.InvalidVersion,
+      versionString,
+      MsalModuleVersion.Latest,
+    );
+  }
+
+  // This should never happen! Indicates version.ts was not generated correctly
+  // This is a critical build-time issue that needs immediate attention
+  if (!latestVersion) {
+    throw VersionError.create(
+      VersionError.Type.InvalidLatestVersion,
+      versionString,
+      MsalModuleVersion.Latest,
+    );
+  }
+
+  // Major version incompatibility check - this is a hard error
+  // Users cannot request a major version that doesn't exist yet
+  if (wantedVersion.major > latestVersion.major) {
+    throw VersionError.create(
+      VersionError.Type.MajorIncompatibility,
+      String(wantedVersion),
+      String(latestVersion),
+    );
+  }
+
+  // Minor version mismatch - add warning but don't throw
+  // This helps developers stay aware of version differences without breaking functionality
+  if (wantedVersion.major === latestVersion.major && wantedVersion.minor !== latestVersion.minor) {
+    const minorMismatchWarning = VersionError.create(
+      VersionError.Type.MinorMismatch,
+      String(wantedVersion),
+      String(latestVersion),
+    );
+    warnings.push(minorMismatchWarning.message);
+  }
+
+  // Find the corresponding enum version for the requested major version
+  // This is used for module configuration and feature detection
+  const enumVersion = Object.values(MsalModuleVersion).find(
+    (x) => semver.coerce(x)?.major === wantedVersion.major,
+  );
+
+  // If no matching enum version is found, this indicates a major version
+  // that doesn't have a corresponding enum value defined
+  if (!enumVersion) {
+    throw VersionError.create(
+      VersionError.Type.MajorIncompatibility,
+      String(wantedVersion),
+      String(latestVersion),
+    );
+  }
+
+  // Return comprehensive version resolution result
+  return {
+    wantedVersion,
+    latestVersion,
+    isLatest: wantedVersion.compare(latestVersion) === 0,
+    satisfiesLatest: wantedVersion.major === latestVersion.major,
+    enumVersion,
+    warnings: warnings.length > 0 ? warnings : undefined,
+  } satisfies ResolvedVersion;
+}
+
+export default resolveVersion;

package/src/versioning/static.ts

@@ -0,0 +1,8 @@
+export enum VersionMessageType {
+  MajorIncompatibility = 'major-incompatibility',
+  MinorMismatch = 'minor-mismatch',
+  PatchDifference = 'patch-difference',
+  InvalidVersion = 'invalid-version',
+  InvalidLatestVersion = 'invalid-latest-version',
+  IncompatibleVersion = 'incompatible-version',
+}

package/src/versioning/types.ts

@@ -0,0 +1,60 @@
+import type { SemVer } from 'semver';
+import type { MsalModuleVersion } from '../static';
+
+/**
+ * Result of version resolution containing parsed versions and compatibility information.
+ *
+ * This type represents the outcome of resolving a version string against the latest
+ * available MSAL version, providing detailed compatibility information for consumers.
+ *
+ * @example
+ * ```typescript
+ * const result: ResolvedVersion = {
+ *   wantedVersion: new SemVer('2.1.0'),
+ *   latestVersion: new SemVer('2.2.0'),
+ *   isLatest: false,
+ *   satisfiesLatest: true,
+ *   enumVersion: MsalModuleVersion.V2
+ * };
+ * ```
+ */
+export type ResolvedVersion = {
+  /**
+   * The version that was requested and successfully parsed.
+   * This is the SemVer object representing the user's requested version.
+   */
+  wantedVersion: SemVer;
+
+  /**
+   * The latest available version in the system.
+   * This represents the most recent MSAL version that the module supports.
+   */
+  latestVersion: SemVer;
+
+  /**
+   * Whether the wanted version is exactly the latest version.
+   * True when wantedVersion.compare(latestVersion) === 0
+   */
+  isLatest: boolean;
+
+  /**
+   * Whether the wanted version satisfies the latest major version.
+   * True when major versions match, regardless of minor/patch differences.
+   * This is the primary compatibility check for MSAL versions.
+   */
+  satisfiesLatest: boolean;
+
+  /**
+   * The corresponding enum version for the wanted version.
+   * Maps the major version number to the appropriate MsalModuleVersion enum value.
+   * Used for module configuration and feature detection.
+   */
+  enumVersion: MsalModuleVersion;
+
+  /**
+   * Optional array of warning messages for version mismatches.
+   * Present when there are minor version differences but major versions match.
+   * Consumers can check this field to log warnings or handle version differences.
+   */
+  warnings?: string[];
+};

package/tsconfig.json

@@ -11,5 +11,5 @@
     }
   ],
   "include": ["src/**/*"],
-  "exclude": ["node_modules", "lib"]
+  "exclude": ["node_modules", "lib", "dist", "__tests__"]
 }

package/vitest.config.ts

@@ -0,0 +1,11 @@
+import { defineProject } from 'vitest/config';
+
+import { name, version } from './package.json';
+
+export default defineProject({
+  test: {
+    environment: 'node',
+    include: ['src/__tests__/**/*.test.ts'],
+    name: `${name}@${version}`,
+  },
+});

package/dist/esm/resolve-version.js

@@ -1,27 +0,0 @@
-import semver from 'semver';
-import { MsalModuleVersion } from './static';
-export function resolveVersion(version) {
-    const wantedVersion = semver.coerce(version || MsalModuleVersion.Latest);
-    const latestVersion = semver.coerce(MsalModuleVersion.Latest);
-    // check if version is valid semver version
-    if (!wantedVersion) {
-        throw new Error(`Invalid version ${version} provided`);
-    }
-    if (!latestVersion) {
-        throw new Error('Invalid latest version');
-    }
-    // check if version is greater than latest
-    if (semver.gt(wantedVersion, latestVersion)) {
-        throw new Error(`Requested version ${version} is greater than the latest version ${MsalModuleVersion.Latest}`);
-    }
-    const enumVersion = Object.values(MsalModuleVersion).find((x) => semver.coerce(x)?.major === wantedVersion.major);
-    return {
-        wantedVersion,
-        latestVersion,
-        enumVersion,
-        isLatest: wantedVersion.compare(latestVersion) === 0,
-        satisfiesLatest: wantedVersion.major === latestVersion.major,
-    };
-}
-export default resolveVersion;
-//# sourceMappingURL=resolve-version.js.map

package/dist/esm/resolve-version.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"resolve-version.js","sourceRoot":"","sources":["../../src/resolve-version.ts"],"names":[],"mappings":"AAAA,OAAO,MAAuB,MAAM,QAAQ,CAAC;AAE7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE7C,MAAM,UAAU,cAAc,CAAC,OAAwB;IAOrD,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,IAAI,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACzE,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC9D,2CAA2C;IAC3C,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,mBAAmB,OAAO,WAAW,CAAC,CAAC;IACzD,CAAC;IAED,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAC5C,CAAC;IAED,0CAA0C;IAC1C,IAAI,MAAM,CAAC,EAAE,CAAC,aAAa,EAAE,aAAc,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CACb,qBAAqB,OAAO,uCAAuC,iBAAiB,CAAC,MAAM,EAAE,CAC9F,CAAC;IACJ,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,IAAI,CACvD,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,KAAK,aAAa,CAAC,KAAK,CAClC,CAAC;IAEvB,OAAO;QACL,aAAa;QACb,aAAa;QACb,WAAW;QACX,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,aAAa,CAAC,KAAK,CAAC;QACpD,eAAe,EAAE,aAAa,CAAC,KAAK,KAAK,aAAa,CAAC,KAAK;KAC7D,CAAC;AACJ,CAAC;AAED,eAAe,cAAc,CAAC"}

package/dist/types/resolve-version.d.ts

@@ -1,10 +0,0 @@
-import { type SemVer } from 'semver';
-import { MsalModuleVersion } from './static';
-export declare function resolveVersion(version: string | SemVer): {
-    wantedVersion: SemVer;
-    latestVersion: SemVer;
-    isLatest: boolean;
-    satisfiesLatest: boolean;
-    enumVersion: MsalModuleVersion;
-};
-export default resolveVersion;

package/src/resolve-version.ts

@@ -1,43 +0,0 @@
-import semver, { type SemVer } from 'semver';
-
-import { MsalModuleVersion } from './static';
-
-export function resolveVersion(version: string | SemVer): {
-  wantedVersion: SemVer;
-  latestVersion: SemVer;
-  isLatest: boolean;
-  satisfiesLatest: boolean;
-  enumVersion: MsalModuleVersion;
-} {
-  const wantedVersion = semver.coerce(version || MsalModuleVersion.Latest);
-  const latestVersion = semver.coerce(MsalModuleVersion.Latest);
-  // check if version is valid semver version
-  if (!wantedVersion) {
-    throw new Error(`Invalid version ${version} provided`);
-  }
-
-  if (!latestVersion) {
-    throw new Error('Invalid latest version');
-  }
-
-  // check if version is greater than latest
-  if (semver.gt(wantedVersion, latestVersion!)) {
-    throw new Error(
-      `Requested version ${version} is greater than the latest version ${MsalModuleVersion.Latest}`,
-    );
-  }
-
-  const enumVersion = Object.values(MsalModuleVersion).find(
-    (x) => semver.coerce(x)?.major === wantedVersion.major,
-  ) as MsalModuleVersion;
-
-  return {
-    wantedVersion,
-    latestVersion,
-    enumVersion,
-    isLatest: wantedVersion.compare(latestVersion) === 0,
-    satisfiesLatest: wantedVersion.major === latestVersion.major,
-  };
-}
-
-export default resolveVersion;