@genesislcap/foundation-utils 15.46.5 → 15.46.6-alpha-6d1bd2f25.0

package/dist/custom-elements.json

@@ -754,6 +754,14 @@
             "package": "./is-dev"
           }
         },
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "./runtime-config"
+          }
+        },
         {
           "kind": "js",
           "name": "*",
@@ -786,6 +794,69 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/env/runtime-config.ts",
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "DEFAULT_RUNTIME_CONFIG_URL",
+          "type": {
+            "text": "string"
+          },
+          "default": "'/env.json'",
+          "description": "The default URL fetchRuntimeConfig reads from.",
+          "privacy": "public"
+        },
+        {
+          "kind": "function",
+          "name": "fetchRuntimeConfig",
+          "return": {
+            "type": {
+              "text": ""
+            }
+          },
+          "parameters": [
+            {
+              "name": "url",
+              "default": "DEFAULT_RUNTIME_CONFIG_URL",
+              "type": {
+                "text": "string"
+              },
+              "description": "The config URL. Defaults to {@link DEFAULT_RUNTIME_CONFIG_URL}.\n * "
+            },
+            {
+              "name": "fallback",
+              "default": "{}",
+              "type": {
+                "text": "Partial<T>"
+              },
+              "description": "Values to use when the config can't be read, and defaults for keys it omits."
+            }
+          ],
+          "description": "Fetches per-deployment JSON config, such as an error-monitoring DSN or environment name, that\ncan't be baked in at build time because the same image is promoted across environments.",
+          "privacy": "public"
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "DEFAULT_RUNTIME_CONFIG_URL",
+          "declaration": {
+            "name": "DEFAULT_RUNTIME_CONFIG_URL",
+            "module": "src/env/runtime-config.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "fetchRuntimeConfig",
+          "declaration": {
+            "name": "fetchRuntimeConfig",
+            "module": "src/env/runtime-config.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/env/variables.ts",

package/dist/dts/env/index.d.ts

@@ -1,3 +1,4 @@
 export * from './is-dev';
+export * from './runtime-config';
 export * from './variables';
 //# sourceMappingURL=index.d.ts.map

package/dist/dts/env/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/env/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/env/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC"}

package/dist/dts/env/runtime-config.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The default URL {@link fetchRuntimeConfig} reads from.
+ * @public
+ */
+export declare const DEFAULT_RUNTIME_CONFIG_URL = "/env.json";
+/**
+ * Fetches per-deployment JSON config, such as an error-monitoring DSN or environment name, that
+ * can't be baked in at build time because the same image is promoted across environments.
+ *
+ * @remarks
+ * Never rejects. Resolves to `fallback` when the request fails (network error, non-2xx status
+ * such as a 404) or the body isn't a JSON object. The last case covers an SPA fallback that serves
+ * `index.html` with a 200 for unknown paths. On success, the fetched values are shallow-merged over
+ * `fallback`. The request bypasses the HTTP cache so a redeployed config is picked up on reload.
+ *
+ * @example
+ * ```ts
+ * type EnvConfig = { sentryDsn: string; environment: string };
+ * const { sentryDsn, environment = 'local' } = await fetchRuntimeConfig<EnvConfig>();
+ * if (sentryDsn) Sentry.init({ dsn: sentryDsn, environment });
+ * ```
+ *
+ * @param url - The config URL. Defaults to {@link DEFAULT_RUNTIME_CONFIG_URL}.
+ * @param fallback - Values to use when the config can't be read, and defaults for keys it omits.
+ * @returns The fetched config merged over `fallback`, or `fallback` alone.
+ * @public
+ */
+export declare function fetchRuntimeConfig<T extends object>(url?: string, fallback?: Partial<T>): Promise<Partial<T>>;
+//# sourceMappingURL=runtime-config.d.ts.map

package/dist/dts/env/runtime-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-config.d.ts","sourceRoot":"","sources":["../../../src/env/runtime-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,0BAA0B,cAAc,CAAC;AAKtD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,SAAS,MAAM,EACvD,GAAG,GAAE,MAAmC,EACxC,QAAQ,GAAE,OAAO,CAAC,CAAC,CAAM,GACxB,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAerB"}

package/dist/esm/env/index.js

@@ -1,2 +1,3 @@
 export * from './is-dev';
+export * from './runtime-config';
 export * from './variables';

package/dist/esm/env/runtime-config.js

@@ -0,0 +1,48 @@
+import { __awaiter } from "tslib";
+/**
+ * The default URL {@link fetchRuntimeConfig} reads from.
+ * @public
+ */
+export const DEFAULT_RUNTIME_CONFIG_URL = '/env.json';
+const isPlainObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Fetches per-deployment JSON config, such as an error-monitoring DSN or environment name, that
+ * can't be baked in at build time because the same image is promoted across environments.
+ *
+ * @remarks
+ * Never rejects. Resolves to `fallback` when the request fails (network error, non-2xx status
+ * such as a 404) or the body isn't a JSON object. The last case covers an SPA fallback that serves
+ * `index.html` with a 200 for unknown paths. On success, the fetched values are shallow-merged over
+ * `fallback`. The request bypasses the HTTP cache so a redeployed config is picked up on reload.
+ *
+ * @example
+ * ```ts
+ * type EnvConfig = { sentryDsn: string; environment: string };
+ * const { sentryDsn, environment = 'local' } = await fetchRuntimeConfig<EnvConfig>();
+ * if (sentryDsn) Sentry.init({ dsn: sentryDsn, environment });
+ * ```
+ *
+ * @param url - The config URL. Defaults to {@link DEFAULT_RUNTIME_CONFIG_URL}.
+ * @param fallback - Values to use when the config can't be read, and defaults for keys it omits.
+ * @returns The fetched config merged over `fallback`, or `fallback` alone.
+ * @public
+ */
+export function fetchRuntimeConfig() {
+    return __awaiter(this, arguments, void 0, function* (url = DEFAULT_RUNTIME_CONFIG_URL, fallback = {}) {
+        try {
+            const response = yield fetch(url, {
+                cache: 'no-store',
+                headers: { Accept: 'application/json' },
+            });
+            if (!response.ok) {
+                return fallback;
+            }
+            // Parse the text rather than trusting Content-Type: an SPA fallback may answer with HTML.
+            const config = JSON.parse(yield response.text());
+            return isPlainObject(config) ? Object.assign(Object.assign({}, fallback), config) : fallback;
+        }
+        catch (_a) {
+            return fallback;
+        }
+    });
+}

package/dist/foundation-utils.api.json

@@ -2079,6 +2079,33 @@
             "endIndex": 2
           }
         },
+        {
+          "kind": "Variable",
+          "canonicalReference": "@genesislcap/foundation-utils!DEFAULT_RUNTIME_CONFIG_URL:var",
+          "docComment": "/**\n * The default URL {@link fetchRuntimeConfig} reads from.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "DEFAULT_RUNTIME_CONFIG_URL = "
+            },
+            {
+              "kind": "Content",
+              "text": "\"/env.json\""
+            }
+          ],
+          "fileUrlPath": "src/env/runtime-config.ts",
+          "initializerTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          },
+          "isReadonly": true,
+          "releaseTag": "Public",
+          "name": "DEFAULT_RUNTIME_CONFIG_URL",
+          "variableTypeTokenRange": {
+            "startIndex": 0,
+            "endIndex": 0
+          }
+        },
         {
           "kind": "Variable",
           "canonicalReference": "@genesislcap/foundation-utils!DEFAULT_USER:var",
@@ -5086,6 +5113,107 @@
             "endIndex": 2
           }
         },
+        {
+          "kind": "Function",
+          "canonicalReference": "@genesislcap/foundation-utils!fetchRuntimeConfig:function(1)",
+          "docComment": "/**\n * Fetches per-deployment JSON config, such as an error-monitoring DSN or environment name, that can't be baked in at build time because the same image is promoted across environments.\n *\n * @remarks\n *\n * Never rejects. Resolves to `fallback` when the request fails (network error, non-2xx status such as a 404) or the body isn't a JSON object. The last case covers an SPA fallback that serves `index.html` with a 200 for unknown paths. On success, the fetched values are shallow-merged over `fallback`. The request bypasses the HTTP cache so a redeployed config is picked up on reload.\n *\n * @param url - The config URL. Defaults to {@link DEFAULT_RUNTIME_CONFIG_URL}.\n *\n * @param fallback - Values to use when the config can't be read, and defaults for keys it omits.\n *\n * @returns The fetched config merged over `fallback`, or `fallback` alone.\n *\n * @example\n * ```ts\n * type EnvConfig = { sentryDsn: string; environment: string };\n * const { sentryDsn, environment = 'local' } = await fetchRuntimeConfig<EnvConfig>();\n * if (sentryDsn) Sentry.init({ dsn: sentryDsn, environment });\n * ```\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function fetchRuntimeConfig<T extends "
+            },
+            {
+              "kind": "Content",
+              "text": "object"
+            },
+            {
+              "kind": "Content",
+              "text": ">(url?: "
+            },
+            {
+              "kind": "Content",
+              "text": "string"
+            },
+            {
+              "kind": "Content",
+              "text": ", fallback?: "
+            },
+            {
+              "kind": "Reference",
+              "text": "Partial",
+              "canonicalReference": "!Partial:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<T>"
+            },
+            {
+              "kind": "Content",
+              "text": "): "
+            },
+            {
+              "kind": "Reference",
+              "text": "Promise",
+              "canonicalReference": "!Promise:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "<"
+            },
+            {
+              "kind": "Reference",
+              "text": "Partial",
+              "canonicalReference": "!Partial:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<T>>"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/env/runtime-config.ts",
+          "returnTypeTokenRange": {
+            "startIndex": 8,
+            "endIndex": 12
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "url",
+              "parameterTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 4
+              },
+              "isOptional": true
+            },
+            {
+              "parameterName": "fallback",
+              "parameterTypeTokenRange": {
+                "startIndex": 5,
+                "endIndex": 7
+              },
+              "isOptional": true
+            }
+          ],
+          "typeParameters": [
+            {
+              "typeParameterName": "T",
+              "constraintTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "defaultTypeTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              }
+            }
+          ],
+          "name": "fetchRuntimeConfig"
+        },
         {
           "kind": "Enum",
           "canonicalReference": "@genesislcap/foundation-utils!FontStyle:enum",

package/dist/foundation-utils.d.ts

@@ -285,6 +285,12 @@ export declare let DEFAULT_ORGANISATION: string;
  */
 export declare let DEFAULT_PASSWORD: string;
 
+/**
+ * The default URL {@link fetchRuntimeConfig} reads from.
+ * @public
+ */
+export declare const DEFAULT_RUNTIME_CONFIG_URL = "/env.json";
+
 /**
  * The default Username value, used in auth/login flow [`genesislcap-foundation-auth`](https://link-to-docs).
  * @remarks Optional.
@@ -569,6 +575,30 @@ declare type EventListener_2<T = any> = (data: T) => void;
  */
 export declare type EventName = 'input' | 'change' | 'default';
 
+/**
+ * Fetches per-deployment JSON config, such as an error-monitoring DSN or environment name, that
+ * can't be baked in at build time because the same image is promoted across environments.
+ *
+ * @remarks
+ * Never rejects. Resolves to `fallback` when the request fails (network error, non-2xx status
+ * such as a 404) or the body isn't a JSON object. The last case covers an SPA fallback that serves
+ * `index.html` with a 200 for unknown paths. On success, the fetched values are shallow-merged over
+ * `fallback`. The request bypasses the HTTP cache so a redeployed config is picked up on reload.
+ *
+ * @example
+ * ```ts
+ * type EnvConfig = { sentryDsn: string; environment: string };
+ * const { sentryDsn, environment = 'local' } = await fetchRuntimeConfig<EnvConfig>();
+ * if (sentryDsn) Sentry.init({ dsn: sentryDsn, environment });
+ * ```
+ *
+ * @param url - The config URL. Defaults to {@link DEFAULT_RUNTIME_CONFIG_URL}.
+ * @param fallback - Values to use when the config can't be read, and defaults for keys it omits.
+ * @returns The fetched config merged over `fallback`, or `fallback` alone.
+ * @public
+ */
+export declare function fetchRuntimeConfig<T extends object>(url?: string, fallback?: Partial<T>): Promise<Partial<T>>;
+
 /**
  * An enum of possible font styles.
  * @public

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/foundation-utils",
   "description": "Genesis Foundation Utils",
-  "version": "15.46.5",
+  "version": "15.46.6-alpha-6d1bd2f25.0",
   "sideEffects": false,
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
@@ -29,17 +29,17 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "15.46.5",
-    "@genesislcap/genx": "15.46.5",
-    "@genesislcap/ts-builder": "15.46.5",
-    "@genesislcap/uvu-playwright-builder": "15.46.5",
-    "@genesislcap/vite-builder": "15.46.5",
-    "@genesislcap/webpack-builder": "15.46.5",
+    "@genesislcap/foundation-testing": "15.46.6-alpha-6d1bd2f25.0",
+    "@genesislcap/genx": "15.46.6-alpha-6d1bd2f25.0",
+    "@genesislcap/ts-builder": "15.46.6-alpha-6d1bd2f25.0",
+    "@genesislcap/uvu-playwright-builder": "15.46.6-alpha-6d1bd2f25.0",
+    "@genesislcap/vite-builder": "15.46.6-alpha-6d1bd2f25.0",
+    "@genesislcap/webpack-builder": "15.46.6-alpha-6d1bd2f25.0",
     "@types/json-schema": "^7.0.11"
   },
   "dependencies": {
-    "@genesislcap/expression-builder": "15.46.5",
-    "@genesislcap/foundation-logger": "15.46.5",
+    "@genesislcap/expression-builder": "15.46.6-alpha-6d1bd2f25.0",
+    "@genesislcap/foundation-logger": "15.46.6-alpha-6d1bd2f25.0",
     "@microsoft/fast-components": "2.30.6",
     "@microsoft/fast-element": "1.14.0",
     "@microsoft/fast-foundation": "2.50.0",