feat: improve type accuracy for getConfig() and others

Author: bradenmacdonald

package-lock.json

@@ -42,6 +42,7 @@
     "@testing-library/jest-dom": "6.6.3",
     "@testing-library/react": "16.2.0",
     "@testing-library/user-event": "14.6.1",
+    "@types/node": "^25.6.0",
     "axios-mock-adapter": "^1.22.0",
     "jest-environment-jsdom": "29.7.0",
     "jest-localstorage-mock": "^2.4.26",

package.json

@@ -302,7 +302,7 @@ export async function hydrateAuthenticatedUser() {
  * @name UserData
  * @interface
  * @memberof module:Auth
- * @property {string} userId
+ * @property {number} userId
  * @property {string} username
  * @property {Array} roles
  * @property {boolean} administrator

src/auth/interface.js

@@ -128,7 +128,7 @@ import { APP_CONFIG_INITIALIZED, CONFIG_CHANGED } from './constants';
 import { publish, subscribe } from './pubSub';
 import { ensureDefinedConfig } from './utils';
 
-function extractRegex(envVar) {
+function extractRegex(envVar: unknown) {
   // Convert the environment variable string to a regex, while guarding
   // against a non-string and an empty/whitespace-only string.
   if (typeof envVar === 'string' && envVar.trim() !== '') {
@@ -141,9 +141,10 @@ function extractRegex(envVar) {
  * Safely parses a JSON string coming from the environment variables.
  * If the JSON is invalid, the function returns an empty object and logs an error to the console.
  *
- * @param {string} paragonUrlsJson - The JSON string representing Paragon theme URLs.
- * @returns {Object|undefined} - Returns a parsed object if the JSON is valid; otherwise, returns
- * an empty object if invalid or undefined if no input is provided.
+ * @param paragonUrlsJson - The JSON string representing Paragon theme URLs.
+ * @returns Returns a parsed object if the JSON is valid; otherwise, returns
+ * an empty object if invalid or undefined if no input is provided. In case of a
+ * different type of error, return the error object itself.
  *
  * @example
  * const jsonString = '{
@@ -154,7 +155,7 @@ function extractRegex(envVar) {
  * const parsedUrls = parseParagonThemeUrls(jsonString);
  * console.log(parsedUrls); // Outputs the parsed JSON object
  */
-function parseParagonThemeUrls(paragonUrlsJson) {
+function parseParagonThemeUrls(paragonUrlsJson: string): Record<string, any> | undefined | Error {
   if (!paragonUrlsJson) {
     return undefined;
   }
@@ -167,45 +168,105 @@ function parseParagonThemeUrls(paragonUrlsJson) {
       return {};
     }
     // In case of a different type of error, return the error object itself
-    return err;
+    return err as Error;
   }
 }
 
-const ENVIRONMENT = process.env.NODE_ENV;
-let config = {
-  ACCESS_TOKEN_COOKIE_NAME: process.env.ACCESS_TOKEN_COOKIE_NAME,
-  ACCOUNT_PROFILE_URL: process.env.ACCOUNT_PROFILE_URL,
-  ACCOUNT_SETTINGS_URL: process.env.ACCOUNT_SETTINGS_URL,
-  BASE_URL: process.env.BASE_URL,
+/**
+ * An object describing the current application configuration.
+ *
+ * In its most basic form, the initialization process loads this document via `process.env`
+ * variables.  There are other ways to add configuration variables to the ConfigDocument as
+ * documented above (JavaScript File Configuration, Runtime Configuration, and the Initialization
+ * Config Handler).
+ *
+ * ```
+ * {
+ *   BASE_URL: process.env.BASE_URL,
+ *   // ... other vars
+ * }
+ * ```
+ *
+ * When using Webpack (i.e., normal usage), the build process is responsible for supplying these
+ * variables via command-line environment variables.  That means they must be supplied at build
+ * time.
+ *
+ * @memberof module:Config
+ */
+export interface ConfigDocument {
+  ACCESS_TOKEN_COOKIE_NAME: string;
+  ACCOUNT_PROFILE_URL: string;
+  ACCOUNT_SETTINGS_URL: string;
+  /** The URL of the current application. */
+  BASE_URL: string;
+  PUBLIC_PATH: string;
+  CREDENTIALS_BASE_URL?: string;
+  CSRF_TOKEN_API_PATH: string;
+  DISCOVERY_API_BASE_URL?: string;
+  PUBLISHER_BASE_URL?: string;
+  ECOMMERCE_BASE_URL?: string;
+  ENVIRONMENT: 'development' | 'production' | 'test';
+  IGNORED_ERROR_REGEX?: RegExp;
+  LANGUAGE_PREFERENCE_COOKIE_NAME: string;
+  LEARNING_BASE_URL: string;
+  LMS_BASE_URL: string;
+  LOGIN_URL: string;
+  LOGOUT_URL: string;
+  STUDIO_BASE_URL: string;
+  MARKETING_SITE_BASE_URL: string;
+  ORDER_HISTORY_URL?: string;
+  REFRESH_ACCESS_TOKEN_ENDPOINT: string;
+  SECURE_COOKIES: boolean; // <-- the only non-string value
+  SEGMENT_KEY?: string;
+  SITE_NAME: string;
+  USER_INFO_COOKIE_NAME: string;
+  LOGO_URL: string;
+  LOGO_TRADEMARK_URL: string;
+  LOGO_WHITE_URL: string;
+  FAVICON_URL: string;
+  MFE_CONFIG_API_URL: string;
+  APP_ID: string;
+  SUPPORT_URL: string;
+  PARAGON_THEME_URLS: Record<string, any> | Error | undefined;
+  externalLinkUrlOverrides?: null | Record<string, string>;
+  [otherKey: string]: any;
+}
+
+const ENVIRONMENT = process.env.NODE_ENV as 'development' | 'production' | 'test';
+let config: ConfigDocument = {
+  ACCESS_TOKEN_COOKIE_NAME: process.env.ACCESS_TOKEN_COOKIE_NAME!,
+  ACCOUNT_PROFILE_URL: process.env.ACCOUNT_PROFILE_URL!,
+  ACCOUNT_SETTINGS_URL: process.env.ACCOUNT_SETTINGS_URL!,
+  BASE_URL: process.env.BASE_URL!,
   PUBLIC_PATH: process.env.PUBLIC_PATH || '/',
   CREDENTIALS_BASE_URL: process.env.CREDENTIALS_BASE_URL,
-  CSRF_TOKEN_API_PATH: process.env.CSRF_TOKEN_API_PATH,
+  CSRF_TOKEN_API_PATH: process.env.CSRF_TOKEN_API_PATH!,
   DISCOVERY_API_BASE_URL: process.env.DISCOVERY_API_BASE_URL,
   PUBLISHER_BASE_URL: process.env.PUBLISHER_BASE_URL,
   ECOMMERCE_BASE_URL: process.env.ECOMMERCE_BASE_URL,
   ENVIRONMENT,
   IGNORED_ERROR_REGEX: extractRegex(process.env.IGNORED_ERROR_REGEX),
-  LANGUAGE_PREFERENCE_COOKIE_NAME: process.env.LANGUAGE_PREFERENCE_COOKIE_NAME,
-  LEARNING_BASE_URL: process.env.LEARNING_BASE_URL,
-  LMS_BASE_URL: process.env.LMS_BASE_URL,
-  LOGIN_URL: process.env.LOGIN_URL,
-  LOGOUT_URL: process.env.LOGOUT_URL,
-  STUDIO_BASE_URL: process.env.STUDIO_BASE_URL,
-  MARKETING_SITE_BASE_URL: process.env.MARKETING_SITE_BASE_URL,
+  LANGUAGE_PREFERENCE_COOKIE_NAME: process.env.LANGUAGE_PREFERENCE_COOKIE_NAME!,
+  LEARNING_BASE_URL: process.env.LEARNING_BASE_URL!,
+  LMS_BASE_URL: process.env.LMS_BASE_URL!,
+  LOGIN_URL: process.env.LOGIN_URL!,
+  LOGOUT_URL: process.env.LOGOUT_URL!,
+  STUDIO_BASE_URL: process.env.STUDIO_BASE_URL!,
+  MARKETING_SITE_BASE_URL: process.env.MARKETING_SITE_BASE_URL!,
   ORDER_HISTORY_URL: process.env.ORDER_HISTORY_URL,
-  REFRESH_ACCESS_TOKEN_ENDPOINT: process.env.REFRESH_ACCESS_TOKEN_ENDPOINT,
+  REFRESH_ACCESS_TOKEN_ENDPOINT: process.env.REFRESH_ACCESS_TOKEN_ENDPOINT!,
   SECURE_COOKIES: ENVIRONMENT !== 'development',
   SEGMENT_KEY: process.env.SEGMENT_KEY,
-  SITE_NAME: process.env.SITE_NAME,
-  USER_INFO_COOKIE_NAME: process.env.USER_INFO_COOKIE_NAME,
-  LOGO_URL: process.env.LOGO_URL,
-  LOGO_TRADEMARK_URL: process.env.LOGO_TRADEMARK_URL,
-  LOGO_WHITE_URL: process.env.LOGO_WHITE_URL,
-  FAVICON_URL: process.env.FAVICON_URL,
-  MFE_CONFIG_API_URL: process.env.MFE_CONFIG_API_URL,
-  APP_ID: process.env.APP_ID,
-  SUPPORT_URL: process.env.SUPPORT_URL,
-  PARAGON_THEME_URLS: parseParagonThemeUrls(process.env.PARAGON_THEME_URLS),
+  SITE_NAME: process.env.SITE_NAME!,
+  USER_INFO_COOKIE_NAME: process.env.USER_INFO_COOKIE_NAME!,
+  LOGO_URL: process.env.LOGO_URL!,
+  LOGO_TRADEMARK_URL: process.env.LOGO_TRADEMARK_URL!,
+  LOGO_WHITE_URL: process.env.LOGO_WHITE_URL!,
+  FAVICON_URL: process.env.FAVICON_URL!,
+  MFE_CONFIG_API_URL: process.env.MFE_CONFIG_API_URL!,
+  APP_ID: process.env.APP_ID!,
+  SUPPORT_URL: process.env.SUPPORT_URL!,
+  PARAGON_THEME_URLS: parseParagonThemeUrls(process.env.PARAGON_THEME_URLS!),
 };
 
 /**
@@ -221,10 +282,8 @@ let config = {
  *   LMS_BASE_URL,
  * } = getConfig();
  * ```
- *
- * @returns {ConfigDocument}
  */
-export function getConfig() {
+export function getConfig(): ConfigDocument {
   return config;
 }
 
@@ -243,10 +302,8 @@ export function getConfig() {
  *   LMS_BASE_URL, // This is overriding the ENTIRE document - this is not merged in!
  * });
  * ```
- *
- * @param {ConfigDocument} newConfig
  */
-export function setConfig(newConfig) {
+export function setConfig(newConfig: ConfigDocument) {
   ensureDefinedConfig(config, 'config');
   config = newConfig;
   publish(CONFIG_CHANGED);
@@ -264,9 +321,8 @@ export function setConfig(newConfig) {
  *
  * If any of the key values are `undefined`, an error will be logged to 'warn'.
  *
- * @param {Object} newConfig
  */
-export function mergeConfig(newConfig) {
+export function mergeConfig(newConfig: Partial<ConfigDocument>) {
   ensureDefinedConfig(newConfig, 'ProcessEnvConfigService');
   config = Object.assign(config, newConfig);
   publish(CONFIG_CHANGED);
@@ -292,11 +348,8 @@ export function mergeConfig(newConfig) {
  * of the specified properties.  This means that this function is compatible with custom `config`
  * phase handlers responsible for loading additional configuration data in the initialization
  * sequence.
- *
- * @param {Array} keys
- * @param {string} [requester='unspecified application code']
  */
-export function ensureConfig(keys, requester = 'unspecified application code') {
+export function ensureConfig(keys: string[], requester = 'unspecified application code') {
   subscribe(APP_CONFIG_INITIALIZED, () => {
     keys.forEach((key) => {
       if (config[key] === undefined) {
@@ -313,8 +366,8 @@ export function ensureConfig(keys, requester = 'unspecified application code') {
  * the provided URL.
  *
  *
- * @param {string} url - The default URL.
- * @returns {string} - The external link URL. Defaults to the input URL if not found in the
+ * @param url - The default URL.
+ * @returns - The external link URL. Defaults to the input URL if not found in the
  * `externalLinkUrlOverrides` object. If the input URL is invalid, '#' is returned.
  *
  * @example
@@ -325,7 +378,7 @@ export function ensureConfig(keys, requester = 'unspecified application code') {
  *   target="_blank"
  * >
  */
-export function getExternalLinkUrl(url) {
+export function getExternalLinkUrl(url: string): string {
   // Guard against non-strings or whitespace-only strings
   if (typeof url !== 'string' || !url.trim()) {
     return '#';
@@ -334,58 +387,3 @@ export function getExternalLinkUrl(url) {
   const overriddenLinkUrls = getConfig().externalLinkUrlOverrides || {};
   return overriddenLinkUrls[url] || url;
 }
-
-/**
- * An object describing the current application configuration.
- *
- * In its most basic form, the initialization process loads this document via `process.env`
- * variables.  There are other ways to add configuration variables to the ConfigDocument as
- * documented above (JavaScript File Configuration, Runtime Configuration, and the Initialization
- * Config Handler).
- *
- * ```
- * {
- *   BASE_URL: process.env.BASE_URL,
- *   // ... other vars
- * }
- * ```
- *
- * When using Webpack (i.e., normal usage), the build process is responsible for supplying these
- * variables via command-line environment variables.  That means they must be supplied at build
- * time.
- *
- * @name ConfigDocument
- * @memberof module:Config
- * @property {string} ACCESS_TOKEN_COOKIE_NAME
- * @property {string} ACCOUNT_PROFILE_URL
- * @property {string} ACCOUNT_SETTINGS_URL
- * @property {string} BASE_URL The URL of the current application.
- * @property {string} CREDENTIALS_BASE_URL
- * @property {string} CSRF_TOKEN_API_PATH
- * @property {string} DISCOVERY_API_BASE_URL
- * @property {string} PUBLISHER_BASE_URL
- * @property {string} ECOMMERCE_BASE_URL
- * @property {string} ENVIRONMENT This is one of: development, production, or test.
- * @property {string} IGNORED_ERROR_REGEX
- * @property {string} LANGUAGE_PREFERENCE_COOKIE_NAME
- * @property {string} LEARNING_BASE_URL
- * @property {string} LMS_BASE_URL
- * @property {string} LOGIN_URL
- * @property {string} LOGOUT_URL
- * @property {string} STUDIO_BASE_URL
- * @property {string} MARKETING_SITE_BASE_URL
- * @property {string} ORDER_HISTORY_URL
- * @property {string} REFRESH_ACCESS_TOKEN_ENDPOINT
- * @property {boolean} SECURE_COOKIES
- * @property {string} SEGMENT_KEY
- * @property {string} SITE_NAME
- * @property {string} USER_INFO_COOKIE_NAME
- * @property {string} LOGO_URL
- * @property {string} LOGO_TRADEMARK_URL
- * @property {string} LOGO_WHITE_URL
- * @property {string} FAVICON_URL
- * @property {string} MFE_CONFIG_API_URL
- * @property {string} APP_ID
- * @property {string} SUPPORT_URL
- * @property {string} PARAGON_THEME_URLS
- */

src/config.js src/config.tssrc/config.js renamed to src/config.ts

@@ -147,7 +147,7 @@ export function findSupportedLocale(locale) {
  * Gracefully fall back to a more general primary language subtag or to English (en)
  * if we don't support that language.
  *
- * @param {string} locale If a locale is provided, returns the closest supported locale. Optional.
+ * @param {string} [locale] If a locale is provided, returns the closest supported locale. Optional.
  * @throws An error if i18n has not yet been configured.
  * @returns {string}
  * @memberof module:Internationalization