@openmrs/esm-routes 5.3.3-pre.1268

package/.turbo/turbo-build.log

@@ -0,0 +1,11 @@
+@openmrs/esm-routes:build: cache hit, replaying output 707c5d2b5ef0dfc3
+@openmrs/esm-routes:build: Browserslist: caniuse-lite is outdated. Please run:
+@openmrs/esm-routes:build:   npx update-browserslist-db@latest
+@openmrs/esm-routes:build:   Why you should do it regularly: https://github.com/browserslist/update-db#readme
+@openmrs/esm-routes:build: asset openmrs-esm-utils.js 3.06 KiB [emitted] [minimized] (name: main) 1 related asset
+@openmrs/esm-routes:build: runtime modules 670 bytes 3 modules
+@openmrs/esm-routes:build: orphan modules 6.77 KiB [orphan] 2 modules
+@openmrs/esm-routes:build: built modules 6.87 KiB [built]
+@openmrs/esm-routes:build:   ./src/index.ts + 2 modules 6.82 KiB [built] [code generated]
+@openmrs/esm-routes:build:   external "@openmrs/esm-utils" 42 bytes [built] [code generated]
+@openmrs/esm-routes:build: webpack 5.88.0 compiled successfully in 7491 ms

package/README.md

@@ -0,0 +1,3 @@
+# openmrs-esm-routes
+
+openmrs-esm-routes provides helper functions for working with the O3 routes.json files.

package/dist/openmrs-esm-utils.js

@@ -0,0 +1,2 @@
+System.register(["@openmrs/esm-utils"],(function(e,r){var t={};return{setters:[function(e){t.canAccessStorage=e.canAccessStorage}],execute:function(){e((()=>{"use strict";var e={618:e=>{e.exports=t}},r={};function o(t){var n=r[t];if(void 0!==n)return n.exports;var a=r[t]={exports:{}};return e[t](a,a.exports,o),a.exports}o.d=(e,r)=>{for(var t in r)o.o(r,t)&&!o.o(e,t)&&Object.defineProperty(e,t,{enumerable:!0,get:r[t]})},o.o=(e,r)=>Object.prototype.hasOwnProperty.call(e,r),o.r=e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})};var n={};return(()=>{o.r(n),o.d(n,{addRoutesOverride:()=>a,isOpenmrsAppRoutes:()=>u,isOpenmrsRoutes:()=>l,localStorageRoutesPrefix:()=>e,removeRoutesOverride:()=>i,resetAllRoutesOverrides:()=>s});var e="openmrs-routes:";function r(e,r){(null==r||r>e.length)&&(r=e.length);for(var t=0,o=new Array(r);t<r;t++)o[t]=e[t];return o}var t=(0,o(618).canAccessStorage)();function a(e,r){if(t){if("string"==typeof r){if(r.startsWith("http"))return c(e,r);try{var o=JSON.parse(r);if(u(o))return c(e,o);console.error("The supplied routes for ".concat(e," is not a valid OpenmrsAppRoutes object"),r)}catch(e){}}else{if(n=r,null!=(a=URL)&&"undefined"!=typeof Symbol&&a[Symbol.hasInstance]?a[Symbol.hasInstance](n):n instanceof a)return c(e,r.toString());if(u(r))return c(e,r)}var n,a;console.error("Override for ".concat(e," is not in a valid format. Expected either a Javascript Object, a JSON string of a Javascript object, or a URL"),r)}}function i(r){if(t){var o=e+r;localStorage.removeItem(o)}}function s(){if(t)for(var r=window.localStorage,o=0;o<r.length;o++){var n=r.key(o);(null==n?void 0:n.startsWith(e))&&r.removeItem(n)}}function c(r,t){var o=e+r;localStorage.setItem(o,JSON.stringify(t))}function u(e){if(e&&"object"==typeof e){var r=Object.prototype.hasOwnProperty,t=e;return!!(!r.call(e,"pages")||Boolean(t.pages)&&Array.isArray(t.pages))&&!!(!r.call(e,"extensions")||Boolean(t.extensions)&&Array.isArray(t.extensions))}return!1}function l(e){if(e&&"object"==typeof e){var t=e;return Object.entries(t).every((function(e){var t,o,n=(o=2,function(e){if(Array.isArray(e))return e}(t=e)||function(e,r){var t=null==e?null:"undefined"!=typeof Symbol&&e[Symbol.iterator]||e["@@iterator"];if(null!=t){var o,n,a=[],i=!0,s=!1;try{for(t=t.call(e);!(i=(o=t.next()).done)&&(a.push(o.value),!r||a.length!==r);i=!0);}catch(e){s=!0,n=e}finally{try{i||null==t.return||t.return()}finally{if(s)throw n}}return a}}(t,o)||function(e,t){if(e){if("string"==typeof e)return r(e,t);var o=Object.prototype.toString.call(e).slice(8,-1);return"Object"===o&&e.constructor&&(o=e.constructor.name),"Map"===o||"Set"===o?Array.from(o):"Arguments"===o||/^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(o)?r(e,t):void 0}}(t,o)||function(){throw new TypeError("Invalid attempt to destructure non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.")}()),a=n[0],i=n[1];return"string"==typeof a&&u(i)}))}return!1}})(),n})())}}}));
+//# sourceMappingURL=openmrs-esm-utils.js.map

package/dist/openmrs-esm-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openmrs-esm-utils.js","mappings":"0LAAAA,EAAOC,QAAUC,C,GCCbC,EAA2B,CAAC,EAGhC,SAASC,EAAoBC,GAE5B,IAAIC,EAAeH,EAAyBE,GAC5C,QAAqBE,IAAjBD,EACH,OAAOA,EAAaL,QAGrB,IAAID,EAASG,EAAyBE,GAAY,CAGjDJ,QAAS,CAAC,GAOX,OAHAO,EAAoBH,GAAUL,EAAQA,EAAOC,QAASG,GAG/CJ,EAAOC,OACf,CCrBAG,EAAoBK,EAAI,CAACR,EAASS,KACjC,IAAI,IAAIC,KAAOD,EACXN,EAAoBQ,EAAEF,EAAYC,KAASP,EAAoBQ,EAAEX,EAASU,IAC5EE,OAAOC,eAAeb,EAASU,EAAK,CAAEI,YAAY,EAAMC,IAAKN,EAAWC,IAE1E,ECNDP,EAAoBQ,EAAI,CAACK,EAAKC,IAAUL,OAAOM,UAAUC,eAAeC,KAAKJ,EAAKC,GCClFd,EAAoBkB,EAAKrB,IACH,oBAAXsB,QAA0BA,OAAOC,aAC1CX,OAAOC,eAAeb,EAASsB,OAAOC,YAAa,CAAEC,MAAO,WAE7DZ,OAAOC,eAAeb,EAAS,aAAc,CAAEwB,OAAO,GAAO,E,oMCLvD,IAAMC,EAA2B,kBCAD,iB,yFAKvC,IAAMC,GAAYC,E,OAAAA,oBAYX,SAASC,EAAkBC,EAAoBC,GACpD,GAAKJ,EAAL,CAIA,GAAsB,iBAAXI,EAAqB,CAC9B,GAAIA,EAAOC,WAAW,QACpB,OAAOC,EAAyBH,EAAYC,GAE5C,IACE,IAAMG,EAAcC,KAAKC,MAAML,GAC/B,GAAIM,EAAmBH,GACrB,OAAOD,EAAyBH,EAAYI,GAE5CI,QAAQC,MAAM,2BAAsC,OAAXT,EAAW,2CAA0CC,EAElG,CAAE,SAAO,CAEb,KAAO,I,EAAIA,E,SAAkBS,M,0FAC3B,OAAOP,EAAyBH,EAAYC,EAAOU,YAC9C,GAAIJ,EAAmBN,GAC5B,OAAOE,EAAyBH,EAAYC,EAC9C,C,QAEAO,QAAQC,MACN,gBAA2B,OAAXT,EAAW,kHAC3BC,EAvBF,CAyBF,CASO,SAASW,EAAqBZ,GACnC,GAAKH,EAAL,CAIA,IAAMhB,EAAMe,EAA2BI,EACvCa,aAAaC,WAAWjC,EAHxB,CAIF,CAQO,SAASkC,IACd,GAAKlB,EAKL,IADA,IAAMgB,EAAeG,OAAOH,aACnBI,EAAI,EAAGA,EAAIJ,EAAaK,OAAQD,IAAK,CAC5C,IAAMpC,EAAMgC,EAAahC,IAAIoC,IACzBpC,aAAAA,EAAAA,EAAKqB,WAAWN,KAClBiB,EAAaC,WAAWjC,EAE5B,CACF,CAEA,SAASsB,EAAyBH,EAAoBC,GACpD,IAAMpB,EAAMe,EAA2BI,EACvCa,aAAaM,QAAQtC,EAAKwB,KAAKe,UAAUnB,GAC3C,CAUO,SAASM,EAAmBN,GACjC,GAAIA,GAA4B,iBAAXA,EAAqB,CACxC,IAAMX,EAAiBP,OAAOM,UAAUC,eAGlCc,EAAcH,EAEpB,UAAIX,EAAeC,KAAKU,EAAQ,UACzBoB,QAAQjB,EAAYkB,QAAWC,MAAMC,QAAQpB,EAAYkB,aAK5DhC,EAAeC,KAAKU,EAAQ,eACzBoB,QAAQjB,EAAYqB,aAAgBF,MAAMC,QAAQpB,EAAYqB,YAQvE,CAEA,OAAO,CACT,CAUO,SAASC,EAAgBzB,GAC9B,GAAIA,GAA4B,iBAAXA,EAAqB,CACxC,IAAMG,EAAcH,EAEpB,OAAOlB,OAAO4C,QAAQvB,GAAawB,OAAM,Y,g1BAAE/C,EAAAA,EAAAA,GAAKc,EAAAA,EAAAA,G,MAA0B,iBAARd,GAAoB0B,EAAmBZ,E,GAC3G,CAEA,OAAO,CACT,C","sources":["webpack://@openmrs/esm-routes/external system \"@openmrs/esm-utils\"","webpack://@openmrs/esm-routes/webpack/bootstrap","webpack://@openmrs/esm-routes/webpack/runtime/define property getters","webpack://@openmrs/esm-routes/webpack/runtime/hasOwnProperty shorthand","webpack://@openmrs/esm-routes/webpack/runtime/make namespace object","webpack://@openmrs/esm-routes/./src/constants.ts","webpack://@openmrs/esm-routes/./src/routes.ts"],"sourcesContent":["module.exports = __WEBPACK_EXTERNAL_MODULE__618__;","// The module cache\nvar __webpack_module_cache__ = {};\n\n// The require function\nfunction __webpack_require__(moduleId) {\n\t// Check if module is in cache\n\tvar cachedModule = __webpack_module_cache__[moduleId];\n\tif (cachedModule !== undefined) {\n\t\treturn cachedModule.exports;\n\t}\n\t// Create a new module (and put it into the cache)\n\tvar module = __webpack_module_cache__[moduleId] = {\n\t\t// no module.id needed\n\t\t// no module.loaded needed\n\t\texports: {}\n\t};\n\n\t// Execute the module function\n\t__webpack_modules__[moduleId](module, module.exports, __webpack_require__);\n\n\t// Return the exports of the module\n\treturn module.exports;\n}\n\n","// define getter functions for harmony exports\n__webpack_require__.d = (exports, definition) => {\n\tfor(var key in definition) {\n\t\tif(__webpack_require__.o(definition, key) && !__webpack_require__.o(exports, key)) {\n\t\t\tObject.defineProperty(exports, key, { enumerable: true, get: definition[key] });\n\t\t}\n\t}\n};","__webpack_require__.o = (obj, prop) => (Object.prototype.hasOwnProperty.call(obj, prop))","// define __esModule on exports\n__webpack_require__.r = (exports) => {\n\tif(typeof Symbol !== 'undefined' && Symbol.toStringTag) {\n\t\tObject.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });\n\t}\n\tObject.defineProperty(exports, '__esModule', { value: true });\n};","export const localStorageRoutesPrefix = 'openmrs-routes:';\n","/** @module @category Routes Utilities */\nimport type { OpenmrsAppRoutes, OpenmrsRoutes } from '@openmrs/esm-globals';\nimport { canAccessStorage } from '@openmrs/esm-utils';\nimport { localStorageRoutesPrefix } from './constants';\n\nconst isEnabled = canAccessStorage();\n\n/**\n * Used to add a route override to local storage. These are read as the routes registry\n * is assembled, so the app must be reloaded for new overrides to take effect.\n *\n * @internal\n * @param moduleName The name of the module the routes are for\n * @param routes Either an {@link OpenmrsAppRoutes} object, a string that represents a JSON\n *  version of an {@link OpenmrsAppRoutes} object or a string or URL that resolves to a\n *  JSON document that represents an {@link OpenmrsAppRoutes} object\n */\nexport function addRoutesOverride(moduleName: string, routes: OpenmrsAppRoutes | string | URL) {\n  if (!isEnabled) {\n    return;\n  }\n\n  if (typeof routes === 'string') {\n    if (routes.startsWith('http')) {\n      return addRouteOverrideInternal(moduleName, routes);\n    } else {\n      try {\n        const maybeRoutes = JSON.parse(routes);\n        if (isOpenmrsAppRoutes(maybeRoutes)) {\n          return addRouteOverrideInternal(moduleName, maybeRoutes);\n        } else {\n          console.error(`The supplied routes for ${moduleName} is not a valid OpenmrsAppRoutes object`, routes);\n        }\n      } catch {}\n    }\n  } else if (routes instanceof URL) {\n    return addRouteOverrideInternal(moduleName, routes.toString());\n  } else if (isOpenmrsAppRoutes(routes)) {\n    return addRouteOverrideInternal(moduleName, routes);\n  }\n\n  console.error(\n    `Override for ${moduleName} is not in a valid format. Expected either a Javascript Object, a JSON string of a Javascript object, or a URL`,\n    routes,\n  );\n}\n\n/**\n * Used to remove an existing routes override from local storage. These are read as the routes registry\n * is assembled, so the app must be reloaded for removed override to be removed.\n *\n * @internal\n * @param moduleName The module to remove the overrides for\n */\nexport function removeRoutesOverride(moduleName: string) {\n  if (!isEnabled) {\n    return;\n  }\n\n  const key = localStorageRoutesPrefix + moduleName;\n  localStorage.removeItem(key);\n}\n\n/**\n * Used to remove all existing routes overrides from local storage. These are read as the routes registry\n * is assembled, so the app must be reloaded for the removed overrides to appear to be removed.\n *\n * @internal\n */\nexport function resetAllRoutesOverrides() {\n  if (!isEnabled) {\n    return;\n  }\n\n  const localStorage = window.localStorage;\n  for (let i = 0; i < localStorage.length; i++) {\n    const key = localStorage.key(i);\n    if (key?.startsWith(localStorageRoutesPrefix)) {\n      localStorage.removeItem(key);\n    }\n  }\n}\n\nfunction addRouteOverrideInternal(moduleName: string, routes: OpenmrsAppRoutes | string) {\n  const key = localStorageRoutesPrefix + moduleName;\n  localStorage.setItem(key, JSON.stringify(routes));\n}\n\n/**\n * Simple type-predicate to ensure that the value can be treated as an OpenmrsAppRoutes\n * object.\n *\n * @internal\n * @param routes the object to check to see if it is an OpenmrsAppRoutes object\n * @returns true if the routes value is an OpenmrsAppRoutes\n */\nexport function isOpenmrsAppRoutes(routes: OpenmrsAppRoutes | unknown): routes is OpenmrsAppRoutes {\n  if (routes && typeof routes === 'object') {\n    const hasOwnProperty = Object.prototype.hasOwnProperty;\n    // we cast maybeRoutes as OpenmrsAppRoutes mainly so we can refer to the properties it should\n    // have without repeated casts\n    const maybeRoutes = routes as OpenmrsAppRoutes;\n\n    if (hasOwnProperty.call(routes, 'pages')) {\n      if (!Boolean(maybeRoutes.pages) || !Array.isArray(maybeRoutes.pages)) {\n        return false;\n      }\n    }\n\n    if (hasOwnProperty.call(routes, 'extensions')) {\n      if (!Boolean(maybeRoutes.extensions) || !Array.isArray(maybeRoutes.extensions)) {\n        return false;\n      }\n    }\n\n    // Notice that we're essentially testing for things that cannot be treated as an OpenmrsAppRoutes\n    // object. This is because a completely empty object is a valid OpenmrsAppRoutes object.\n    return true;\n  }\n\n  return false;\n}\n\n/**\n * Simple type-predicate to ensure that the value can be treated as an OpenmrsRoutes\n * object.\n *\n * @internal\n * @param routes the object to check to see if it is an OpenmrsRoutes object\n * @returns true if the routes value is an OpenmrsRoutes\n */\nexport function isOpenmrsRoutes(routes: OpenmrsRoutes | unknown): routes is OpenmrsRoutes {\n  if (routes && typeof routes === 'object') {\n    const maybeRoutes = routes as OpenmrsRoutes;\n\n    return Object.entries(maybeRoutes).every(([key, value]) => typeof key === 'string' && isOpenmrsAppRoutes(value));\n  }\n\n  return false;\n}\n"],"names":["module","exports","__WEBPACK_EXTERNAL_MODULE__618__","__webpack_module_cache__","__webpack_require__","moduleId","cachedModule","undefined","__webpack_modules__","d","definition","key","o","Object","defineProperty","enumerable","get","obj","prop","prototype","hasOwnProperty","call","r","Symbol","toStringTag","value","localStorageRoutesPrefix","isEnabled","canAccessStorage","addRoutesOverride","moduleName","routes","startsWith","addRouteOverrideInternal","maybeRoutes","JSON","parse","isOpenmrsAppRoutes","console","error","URL","toString","removeRoutesOverride","localStorage","removeItem","resetAllRoutesOverrides","window","i","length","setItem","stringify","Boolean","pages","Array","isArray","extensions","isOpenmrsRoutes","entries","every"],"sourceRoot":""}

package/jest.config.js

@@ -0,0 +1,9 @@
+module.exports = {
+  transform: {
+    "^.+\\.(m?j|t)sx?$": ["@swc/jest"],
+  },
+  testEnvironment: "jsdom",
+  testEnvironmentOptions: {
+    url: "http://localhost/",
+  },
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@openmrs/esm-routes",
+  "version": "5.3.3-pre.1268",
+  "license": "MPL-2.0",
+  "description": "Utilities for working with the routes registry",
+  "browser": "dist/openmrs-esm-routes.js",
+  "main": "src/index.ts",
+  "source": true,
+  "sideEffects": false,
+  "scripts": {
+    "test": "cross-env TZ=UTC jest --config jest.config.js --verbose false --passWithNoTests --color",
+    "test:watch": "cross-env TZ=UTC jest --watch --config jest.config.js --color",
+    "build": "webpack --mode=production",
+    "build:development": "webpack --mode development",
+    "analyze": "webpack --mode=production --env analyze=true",
+    "typescript": "tsc",
+    "lint": "eslint src --ext ts,tsx"
+  },
+  "keywords": [
+    "openmrs",
+    "microfrontends"
+  ],
+  "directories": {
+    "lib": "dist",
+    "src": "src"
+  },
+  "browserslist": [
+    "extends browserslist-config-openmrs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openmrs/openmrs-esm-core.git"
+  },
+  "bugs": {
+    "url": "https://github.com/openmrs/openmrs-esm-core/issues"
+  },
+  "homepage": "https://github.com/openmrs/openmrs-esm-core#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@openmrs/esm-globals": "5.x",
+    "@openmrs/esm-utils": "5.x"
+  },
+  "devDependencies": {
+    "@openmrs/esm-globals": "5.3.3-pre.1268",
+    "@openmrs/esm-utils": "5.3.3-pre.1268",
+    "jest-fetch-mock": "^3.0.3"
+  },
+  "stableVersion": "5.2.0"
+}

package/src/constants.ts

@@ -0,0 +1 @@
+export const localStorageRoutesPrefix = 'openmrs-routes:';

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './constants';
+export * from './routes';

package/src/routes.test.ts

@@ -0,0 +1,137 @@
+import fetchMock, { enableFetchMocks } from 'jest-fetch-mock';
+enableFetchMocks();
+
+import { addRoutesOverride, isOpenmrsAppRoutes } from './routes';
+
+describe('Openmrs Routes Utilities', () => {
+  describe('addRoutesOverride', () => {
+    beforeEach(() => localStorage.clear());
+
+    it('should add routes when provided as an object', () => {
+      addRoutesOverride('@openmrs/my-module', {
+        backendDependencies: {
+          fhir2: '^2.0.0',
+          'webservices.rest': '^1.4.0',
+        },
+        version: '1.2.0-pre.12345+build.8',
+        pages: [
+          {
+            component: 'root',
+            route: 'myPage',
+          },
+        ],
+        extensions: [
+          {
+            name: 'custom extension',
+            component: 'customExtension',
+          },
+        ],
+      });
+
+      expect(localStorage.getItem('openmrs-routes:@openmrs/my-module')).toBe(
+        '{"backendDependencies":{"fhir2":"^2.0.0","webservices.rest":"^1.4.0"},"version":"1.2.0-pre.12345+build.8","pages":[{"component":"root","route":"myPage"}],"extensions":[{"name":"custom extension","component":"customExtension"}]}',
+      );
+    });
+
+    it('should add routes when provided as a JSON string', () => {
+      addRoutesOverride(
+        '@openmrs/my-module',
+        JSON.stringify({
+          backendDependencies: {
+            fhir2: '^2.0.0',
+            'webservices.rest': '^1.4.0',
+          },
+          version: '1.2.0-pre.12345+build.8',
+          pages: [
+            {
+              component: 'root',
+              route: 'myPage',
+            },
+          ],
+          extensions: [
+            {
+              name: 'custom extension',
+              component: 'customExtension',
+            },
+          ],
+        }),
+      );
+
+      expect(localStorage.getItem('openmrs-routes:@openmrs/my-module')).toBe(
+        '{"backendDependencies":{"fhir2":"^2.0.0","webservices.rest":"^1.4.0"},"version":"1.2.0-pre.12345+build.8","pages":[{"component":"root","route":"myPage"}],"extensions":[{"name":"custom extension","component":"customExtension"}]}',
+      );
+    });
+
+    it('should add routes when loaded via a string HTTP endpoint', () => {
+      addRoutesOverride('@openmrs/my-module', 'http://localhost/my-route-override.json');
+
+      expect(localStorage.getItem('openmrs-routes:@openmrs/my-module')).toBe(
+        '"http://localhost/my-route-override.json"',
+      );
+    });
+
+    it('should add routes when loaded via a URL HTTP endpoint', () => {
+      addRoutesOverride('@openmrs/my-module', new URL('http://localhost/my-route-override.json'));
+
+      expect(localStorage.getItem('openmrs-routes:@openmrs/my-module')).toBe(
+        '"http://localhost/my-route-override.json"',
+      );
+    });
+  });
+
+  describe('isOpenmrsAppRoutes', () => {
+    it('should return true for a valid routes object', () => {
+      expect(
+        isOpenmrsAppRoutes({
+          backendDependencies: {
+            fhir2: '^2.0.0',
+            'webservices.rest': '^1.4.0',
+          },
+          version: '1.2.0-pre.12345+build.8',
+          pages: [
+            {
+              component: 'root',
+              route: 'myPage',
+            },
+          ],
+          extensions: [
+            {
+              name: 'custom extension',
+              component: 'customExtension',
+            },
+          ],
+        }),
+      ).toBe(true);
+    });
+
+    it('should accept an object with only pages', () => {
+      expect(
+        isOpenmrsAppRoutes({
+          pages: [
+            {
+              component: 'root',
+              route: 'myPage',
+            },
+          ],
+        }),
+      ).toBe(true);
+    });
+
+    it('should accept an object with only extensions', () => {
+      expect(
+        isOpenmrsAppRoutes({
+          extensions: [
+            {
+              name: 'custom extension',
+              component: 'customExtension',
+            },
+          ],
+        }),
+      ).toBe(true);
+    });
+
+    it('should report an empty object as valid', () => {
+      expect(isOpenmrsAppRoutes({})).toBe(true);
+    });
+  });
+});

package/src/routes.ts

@@ -0,0 +1,140 @@
+/** @module @category Routes Utilities */
+import type { OpenmrsAppRoutes, OpenmrsRoutes } from '@openmrs/esm-globals';
+import { canAccessStorage } from '@openmrs/esm-utils';
+import { localStorageRoutesPrefix } from './constants';
+
+const isEnabled = canAccessStorage();
+
+/**
+ * Used to add a route override to local storage. These are read as the routes registry
+ * is assembled, so the app must be reloaded for new overrides to take effect.
+ *
+ * @internal
+ * @param moduleName The name of the module the routes are for
+ * @param routes Either an {@link OpenmrsAppRoutes} object, a string that represents a JSON
+ *  version of an {@link OpenmrsAppRoutes} object or a string or URL that resolves to a
+ *  JSON document that represents an {@link OpenmrsAppRoutes} object
+ */
+export function addRoutesOverride(moduleName: string, routes: OpenmrsAppRoutes | string | URL) {
+  if (!isEnabled) {
+    return;
+  }
+
+  if (typeof routes === 'string') {
+    if (routes.startsWith('http')) {
+      return addRouteOverrideInternal(moduleName, routes);
+    } else {
+      try {
+        const maybeRoutes = JSON.parse(routes);
+        if (isOpenmrsAppRoutes(maybeRoutes)) {
+          return addRouteOverrideInternal(moduleName, maybeRoutes);
+        } else {
+          console.error(`The supplied routes for ${moduleName} is not a valid OpenmrsAppRoutes object`, routes);
+        }
+      } catch {}
+    }
+  } else if (routes instanceof URL) {
+    return addRouteOverrideInternal(moduleName, routes.toString());
+  } else if (isOpenmrsAppRoutes(routes)) {
+    return addRouteOverrideInternal(moduleName, routes);
+  }
+
+  console.error(
+    `Override for ${moduleName} is not in a valid format. Expected either a Javascript Object, a JSON string of a Javascript object, or a URL`,
+    routes,
+  );
+}
+
+/**
+ * Used to remove an existing routes override from local storage. These are read as the routes registry
+ * is assembled, so the app must be reloaded for removed override to be removed.
+ *
+ * @internal
+ * @param moduleName The module to remove the overrides for
+ */
+export function removeRoutesOverride(moduleName: string) {
+  if (!isEnabled) {
+    return;
+  }
+
+  const key = localStorageRoutesPrefix + moduleName;
+  localStorage.removeItem(key);
+}
+
+/**
+ * Used to remove all existing routes overrides from local storage. These are read as the routes registry
+ * is assembled, so the app must be reloaded for the removed overrides to appear to be removed.
+ *
+ * @internal
+ */
+export function resetAllRoutesOverrides() {
+  if (!isEnabled) {
+    return;
+  }
+
+  const localStorage = window.localStorage;
+  for (let i = 0; i < localStorage.length; i++) {
+    const key = localStorage.key(i);
+    if (key?.startsWith(localStorageRoutesPrefix)) {
+      localStorage.removeItem(key);
+    }
+  }
+}
+
+function addRouteOverrideInternal(moduleName: string, routes: OpenmrsAppRoutes | string) {
+  const key = localStorageRoutesPrefix + moduleName;
+  localStorage.setItem(key, JSON.stringify(routes));
+}
+
+/**
+ * Simple type-predicate to ensure that the value can be treated as an OpenmrsAppRoutes
+ * object.
+ *
+ * @internal
+ * @param routes the object to check to see if it is an OpenmrsAppRoutes object
+ * @returns true if the routes value is an OpenmrsAppRoutes
+ */
+export function isOpenmrsAppRoutes(routes: OpenmrsAppRoutes | unknown): routes is OpenmrsAppRoutes {
+  if (routes && typeof routes === 'object') {
+    const hasOwnProperty = Object.prototype.hasOwnProperty;
+    // we cast maybeRoutes as OpenmrsAppRoutes mainly so we can refer to the properties it should
+    // have without repeated casts
+    const maybeRoutes = routes as OpenmrsAppRoutes;
+
+    if (hasOwnProperty.call(routes, 'pages')) {
+      if (!Boolean(maybeRoutes.pages) || !Array.isArray(maybeRoutes.pages)) {
+        return false;
+      }
+    }
+
+    if (hasOwnProperty.call(routes, 'extensions')) {
+      if (!Boolean(maybeRoutes.extensions) || !Array.isArray(maybeRoutes.extensions)) {
+        return false;
+      }
+    }
+
+    // Notice that we're essentially testing for things that cannot be treated as an OpenmrsAppRoutes
+    // object. This is because a completely empty object is a valid OpenmrsAppRoutes object.
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Simple type-predicate to ensure that the value can be treated as an OpenmrsRoutes
+ * object.
+ *
+ * @internal
+ * @param routes the object to check to see if it is an OpenmrsRoutes object
+ * @returns true if the routes value is an OpenmrsRoutes
+ */
+export function isOpenmrsRoutes(routes: OpenmrsRoutes | unknown): routes is OpenmrsRoutes {
+  if (routes && typeof routes === 'object') {
+    const maybeRoutes = routes as OpenmrsRoutes;
+
+    return Object.entries(maybeRoutes).every(([key, value]) => typeof key === 'string' && isOpenmrsAppRoutes(value));
+  }
+
+  return false;
+}

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "esModuleInterop": true,
+    "module": "esnext",
+    "target": "es2015",
+    "allowSyntheticDefaultImports": true,
+    "jsx": "react",
+    "strictNullChecks": true,
+    "moduleResolution": "node",
+    "declaration": true,
+    "declarationDir": "dist",
+    "emitDeclarationOnly": true,
+    "lib": [
+      "dom",
+      "es5",
+      "scripthost",
+      "es2015",
+      "es2015.promise",
+      "es2016.array.include",
+      "es2018",
+      "esnext"
+    ]
+  },
+  "include": ["src/**/*"]
+}

package/webpack.config.js

@@ -0,0 +1,42 @@
+const ForkTsCheckerWebpackPlugin = require("fork-ts-checker-webpack-plugin");
+const { resolve } = require("path");
+const { CleanWebpackPlugin } = require("clean-webpack-plugin");
+const { BundleAnalyzerPlugin } = require("webpack-bundle-analyzer");
+
+const { peerDependencies } = require("./package.json");
+
+module.exports = (env) => ({
+  entry: [resolve(__dirname, "src/index.ts")],
+  output: {
+    filename: "openmrs-esm-utils.js",
+    path: resolve(__dirname, "dist"),
+    library: { type: "system" },
+  },
+  devtool: "source-map",
+  module: {
+    rules: [
+      {
+        test: /\.m?(js|ts|tsx)$/,
+        exclude: /node_modules/,
+        use: "swc-loader",
+      },
+    ],
+  },
+  externals: Object.keys(peerDependencies || {}),
+  resolve: {
+    extensions: [".ts", ".js", ".tsx", ".jsx"],
+  },
+  plugins: [
+    new CleanWebpackPlugin(),
+    new ForkTsCheckerWebpackPlugin(),
+    new BundleAnalyzerPlugin({
+      analyzerMode: env && env.analyze ? "static" : "disabled",
+    }),
+  ],
+  devServer: {
+    disableHostCheck: true,
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+    },
+  },
+});