@lorion-org/runtime-config-node 1.0.0-beta.0 → 1.0.0-beta.1

package/dist/index.js

@@ -8,7 +8,10 @@ import {
   resolveRuntimeConfigValueFromRuntimeConfig,
   projectRuntimeConfigEnvVars,
   toRuntimeConfigFragment,
-  runtimeEnvVarsToShellAssignments
+  runtimeEnvVarsToShellAssignments,
+  resolveRuntimeConfigValidationMode,
+  shouldRegisterRuntimeConfigValidationSchema,
+  shouldRequireRuntimeConfigAtStartup
 } from "@lorion-org/runtime-config";
 var defaultRuntimeConfigFileName = "runtime.config.json";
 var defaultRuntimeConfigDirName = "runtime-config";
@@ -103,6 +106,35 @@ function getRuntimeConfigPathOptions(source) {
 function getSchemaFileName(options) {
   return options.schemaFileName ?? defaultRuntimeConfigSchemaFileName;
 }
+function formatMissingRuntimeConfigValidationError(skipped) {
+  if (skipped.reason === "missing-schema") {
+    return new Error(
+      [
+        `RuntimeConfig schema file missing for scope "${skipped.scopeId}".`,
+        ...skipped.schemaPath ? [`missing schema file: ${skipped.schemaPath}`] : [],
+        ...skipped.configPath ? [`runtime config file: ${skipped.configPath}`] : []
+      ].join(" ")
+    );
+  }
+  if (skipped.reason === "missing-config") {
+    return new Error(
+      [
+        `RuntimeConfig file missing for scope "${skipped.scopeId}".`,
+        ...skipped.configPath ? [`expected runtime config file: ${skipped.configPath}`] : [],
+        ...skipped.schemaPath ? [`schema file: ${skipped.schemaPath}`] : []
+      ].join(" ")
+    );
+  }
+  const details = [
+    `RuntimeConfig validation target has no schema directory for scope "${skipped.scopeId}".`
+  ];
+  if (skipped.configPath) details.push(`runtime config file: ${skipped.configPath}`);
+  if (skipped.schemaPath) details.push(`schema file: ${skipped.schemaPath}`);
+  return new Error(details.join(" "));
+}
+function shouldReportMissingRuntimeConfig(mode) {
+  return mode !== "optional";
+}
 function stripJsonBom(text) {
   return text.charCodeAt(0) === 65279 ? text.slice(1) : text;
 }
@@ -279,12 +311,19 @@ function formatRuntimeConfigSchemaValidationError(target, validationError) {
   );
 }
 function validateRuntimeConfigSchemaTargets(targets, options = {}) {
+  const invalid = collectRuntimeConfigSchemaTargetValidationErrors(targets, options);
+  if (invalid[0]) {
+    throw invalid[0].error;
+  }
+}
+function collectRuntimeConfigSchemaTargetValidationErrors(targets, options = {}) {
   const ajv = new Ajv({
     strict: false,
     allErrors: false,
     ...options.ajvOptions
   });
   const formatError = options.formatError ?? formatRuntimeConfigSchemaValidationError;
+  const invalid = [];
   for (const target of targets) {
     if (!existsSync(target.schemaPath) || !existsSync(target.configPath)) {
       continue;
@@ -296,13 +335,21 @@ function validateRuntimeConfigSchemaTargets(targets, options = {}) {
     if (!isValid) {
       const validationError = validate.errors?.[0];
       if (validationError) {
-        throw formatError(target, validationError);
+        invalid.push({
+          ...target,
+          error: formatError(target, validationError)
+        });
+        continue;
       }
-      throw new Error(
-        `RuntimeConfig schema validation failed for "${target.scopeId}" (${target.configPath})`
-      );
+      invalid.push({
+        ...target,
+        error: new Error(
+          `RuntimeConfig schema validation failed for "${target.scopeId}" (${target.configPath})`
+        )
+      });
     }
   }
+  return invalid;
 }
 function loadRuntimeConfigTree(varDir, options = {}) {
   const runtimeConfigDir = path.join(varDir, getRuntimeConfigDirName(options));
@@ -421,21 +468,28 @@ function validateRuntimeConfigScopes(varDir, targets, options = {}) {
   const schemaFileName = getSchemaFileName(options);
   const result = {
     fileName: getFileName(options),
+    invalid: [],
     skipped: [],
     validated: [],
     varDir
   };
   for (const target of targets) {
+    if (!shouldRegisterRuntimeConfigValidationSchema(target.policy)) continue;
     const scopeId = target.scopeId.trim();
     if (!scopeId) continue;
+    const mode = resolveRuntimeConfigValidationMode(target.policy);
     const configPath = resolveRuntimeConfigPaths(varDir, scopeId, options).filePath;
     const schemaPath = target.cwd ? path.resolve(target.cwd, schemaFileName) : void 0;
     if (!target.cwd || !schemaPath) {
-      result.skipped.push({ configPath, reason: "missing-scope-dir", scopeId });
+      if (shouldReportMissingRuntimeConfig(mode)) {
+        result.skipped.push({ configPath, reason: "missing-scope-dir", scopeId });
+      }
       continue;
     }
     if (!existsSync(configPath)) {
-      result.skipped.push({ configPath, reason: "missing-config", schemaPath, scopeId });
+      if (shouldReportMissingRuntimeConfig(mode)) {
+        result.skipped.push({ configPath, reason: "missing-config", schemaPath, scopeId });
+      }
       continue;
     }
     if (!existsSync(schemaPath)) {
@@ -444,16 +498,45 @@ function validateRuntimeConfigScopes(varDir, targets, options = {}) {
     }
     result.validated.push({ configPath, schemaPath, scopeId });
   }
-  validateRuntimeConfigSchemaTargets(result.validated, {
+  result.invalid = collectRuntimeConfigSchemaTargetValidationErrors(result.validated, {
     ...options.formatError ? { formatError: options.formatError } : {}
   });
   return result;
 }
+function readRuntimeConfigSchemaRegistry(targets, options = {}) {
+  const schemaFileName = options.schemaFileName ?? defaultRuntimeConfigSchemaFileName;
+  const entries = targets.filter((target) => shouldRegisterRuntimeConfigValidationSchema(target.policy)).flatMap((target) => {
+    const scopeId = target.scopeId.trim();
+    if (!scopeId || !target.cwd) return [];
+    const schemaPath = path.resolve(target.cwd, schemaFileName);
+    if (!existsSync(schemaPath)) return [];
+    return [[scopeId, readRequiredJsonFile(schemaPath)]];
+  });
+  return Object.fromEntries(entries);
+}
+function assertRequiredRuntimeConfigValidationTargets(result, targets) {
+  const requiredScopeIds = new Set(
+    targets.filter((target) => shouldRequireRuntimeConfigAtStartup(target.policy)).map((target) => target.scopeId.trim()).filter(Boolean)
+  );
+  const requiredFailures = [
+    ...result.skipped.filter((entry) => requiredScopeIds.has(entry.scopeId)).map(formatMissingRuntimeConfigValidationError),
+    ...result.invalid.filter((entry) => requiredScopeIds.has(entry.scopeId)).map((entry) => entry.error)
+  ];
+  if (requiredFailures.length) {
+    throw new Error(
+      [
+        "RuntimeConfig startup validation failed.",
+        ...requiredFailures.map((error) => error.message)
+      ].join("\n\n")
+    );
+  }
+}
 function validateRuntimeConfigSourceScopes(source, targets, options = {}) {
   const schemaFileName = getSchemaFileName(options);
   const filesByScope = /* @__PURE__ */ new Map();
   const result = {
     fileName: source.paths[0] ?? "",
+    invalid: [],
     skipped: [],
     validated: [],
     varDir: ""
@@ -462,20 +545,26 @@ function validateRuntimeConfigSourceScopes(source, targets, options = {}) {
     filesByScope.set(file.scopeId, file.configPath);
   }
   for (const target of targets) {
+    if (!shouldRegisterRuntimeConfigValidationSchema(target.policy)) continue;
     const scopeId = target.scopeId.trim();
     if (!scopeId) continue;
+    const mode = resolveRuntimeConfigValidationMode(target.policy);
     const configPath = filesByScope.get(scopeId);
     const schemaPath = target.cwd ? path.resolve(target.cwd, schemaFileName) : void 0;
     if (!target.cwd || !schemaPath) {
-      result.skipped.push({
-        ...configPath ? { configPath } : {},
-        reason: "missing-scope-dir",
-        scopeId
-      });
+      if (shouldReportMissingRuntimeConfig(mode)) {
+        result.skipped.push({
+          ...configPath ? { configPath } : {},
+          reason: "missing-scope-dir",
+          scopeId
+        });
+      }
       continue;
     }
     if (!configPath) {
-      result.skipped.push({ reason: "missing-config", schemaPath, scopeId });
+      if (shouldReportMissingRuntimeConfig(mode)) {
+        result.skipped.push({ reason: "missing-config", schemaPath, scopeId });
+      }
       continue;
     }
     if (!existsSync(schemaPath)) {
@@ -484,13 +573,15 @@ function validateRuntimeConfigSourceScopes(source, targets, options = {}) {
     }
     result.validated.push({ configPath, schemaPath, scopeId });
   }
-  validateRuntimeConfigSchemaTargets(result.validated, {
+  result.invalid = collectRuntimeConfigSchemaTargetValidationErrors(result.validated, {
     ...options.formatError ? { formatError: options.formatError } : {}
   });
   return result;
 }
 export {
+  assertRequiredRuntimeConfigValidationTargets,
   collectRuntimeConfigFragmentFiles,
+  collectRuntimeConfigSchemaTargetValidationErrors,
   ensureParentDir,
   getRuntimeConfigScopeView,
   getRuntimeConfigValue,
@@ -505,6 +596,7 @@ export {
   projectRuntimeConfigTree,
   readJsonFile,
   readRequiredJsonFile,
+  readRuntimeConfigSchemaRegistry,
   readRuntimeConfigScopeJson,
   readTextFile,
   resolveRuntimeConfigFilePath,

package/examples/env-assignments.ts

@@ -3,12 +3,12 @@ import {
   writeRuntimeConfigFragment,
 } from '@lorion-org/runtime-config-node';
 
-writeRuntimeConfigFragment('./var', 'billing', {
+writeRuntimeConfigFragment('./var', 'checkout', {
   public: {
-    apiBase: '/api/billing',
+    successPath: '/orders/confirmed',
   },
   private: {
-    token: 'billing-token',
+    signingSecret: 'checkout_signing_secret_demo',
   },
 });
 
@@ -17,5 +17,5 @@ const assignments = loadRuntimeConfigShellAssignments('./var', {
 });
 
 console.log(assignments);
-// APP_PUBLIC_BILLING_API_BASE='"/api/billing"'
-// APP_PRIVATE_BILLING_TOKEN='"billing-token"'
+// APP_PUBLIC_CHECKOUT_SUCCESS_PATH='"/orders/confirmed"'
+// APP_PRIVATE_CHECKOUT_SIGNING_SECRET='"checkout_signing_secret_demo"'

package/examples/load-runtime-config-tree.ts

@@ -1,9 +1,9 @@
 import { projectSectionedRuntimeConfig } from '@lorion-org/runtime-config';
 import { loadRuntimeConfigTree, writeRuntimeConfigFragment } from '@lorion-org/runtime-config-node';
 
-writeRuntimeConfigFragment('./var', 'billing', {
+writeRuntimeConfigFragment('./var', 'checkout', {
   public: {
-    apiBase: '/api/billing',
+    successPath: '/orders/confirmed',
   },
 });
 
@@ -11,7 +11,7 @@ const fragments = loadRuntimeConfigTree('./var');
 const runtimeConfig = projectSectionedRuntimeConfig(fragments);
 
 console.log(runtimeConfig.public);
-// { billingApiBase: '/api/billing' }
+// { checkoutSuccessPath: '/orders/confirmed' }
 
 console.log(runtimeConfig.private);
 // {}

package/examples/query-runtime-config-tree.ts

@@ -6,17 +6,17 @@ import {
   writeRuntimeConfigFragment,
 } from '@lorion-org/runtime-config-node';
 
-writeRuntimeConfigFragment('./var', 'billing', {
+writeRuntimeConfigFragment('./var', 'checkout', {
   public: {
-    apiBase: '/api/billing',
+    successPath: '/orders/confirmed',
   },
   private: {
-    token: 'billing-token',
+    signingSecret: 'checkout_signing_secret_demo',
   },
   contexts: {
-    tenantA: {
+    'eu-store': {
       public: {
-        apiBase: '/tenant-a/billing',
+        successPath: '/eu-store/orders/confirmed',
       },
     },
   },
@@ -24,30 +24,30 @@ writeRuntimeConfigFragment('./var', 'billing', {
 
 const listResult = listRuntimeConfigFragments('./var');
 console.log(listResult.scopes);
-// [{ scopeId: 'billing', publicKeys: ['apiBase'], privateKeys: ['token'], contextIds: ['tenantA'], ... }]
+// [{ scopeId: 'checkout', publicKeys: ['successPath'], privateKeys: ['signingSecret'], contextIds: ['eu-store'], ... }]
 
 const projectResult = projectRuntimeConfigTree('./var', {
-  contextOutputKey: '__tenants',
+  contextOutputKey: '__stores',
 });
 console.log(projectResult.runtimeConfig.public);
 // {
-//   billingApiBase: '/api/billing',
-//   __tenants: {
-//     tenantA: {
-//       billingApiBase: '/tenant-a/billing',
+//   checkoutSuccessPath: '/orders/confirmed',
+//   __stores: {
+//     'eu-store': {
+//       checkoutSuccessPath: '/eu-store/orders/confirmed',
 //     },
 //   },
 // }
 
-const valueResult = getRuntimeConfigValue('./var', 'billing', 'apiBase', {
-  contextId: 'tenantA',
-  contextOutputKey: '__tenants',
+const valueResult = getRuntimeConfigValue('./var', 'checkout', 'successPath', {
+  contextId: 'eu-store',
+  contextOutputKey: '__stores',
 });
 console.log(valueResult.value);
-// /tenant-a/billing
+// /eu-store/orders/confirmed
 
-const scopeResult = getRuntimeConfigScopeView('./var', 'billing', {
+const scopeResult = getRuntimeConfigScopeView('./var', 'checkout', {
   visibility: 'private',
 });
 console.log(scopeResult.config);
-// { token: 'billing-token' }
+// { signingSecret: 'checkout_signing_secret_demo' }

package/examples/source-and-scope-files.ts

@@ -11,14 +11,14 @@ const source = resolveRuntimeConfigSource({
   envKey: 'APP_VAR_DIR',
 });
 
-writeRuntimeConfigScopeJson(source, 'billing', 'settings.json', {
-  apiBase: '/api/billing',
+writeRuntimeConfigScopeJson(source, 'checkout', 'settings.json', {
+  successPath: '/orders/confirmed',
 });
 
-const settings = readRuntimeConfigScopeJson(source, 'billing', 'settings.json');
+const settings = readRuntimeConfigScopeJson(source, 'checkout', 'settings.json');
 console.log(settings);
-// { apiBase: '/api/billing' }
+// { successPath: '/orders/confirmed' }
 
-const logoPath = resolveRuntimeConfigPublicFilePath(source, 'billing/logo.svg');
+const logoPath = resolveRuntimeConfigPublicFilePath(source, 'checkout/logo.svg');
 console.log(logoPath);
-// /absolute/project/path/var/runtime-config/public/billing/logo.svg
+// /absolute/project/path/var/runtime-config/public/checkout/logo.svg

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorion-org/runtime-config-node",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.1",
   "description": "Node file-system helpers for runtime-config directories and files.",
   "license": "MIT",
   "repository": {
@@ -22,6 +22,10 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "lorion-source": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
       "import": {
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
@@ -35,7 +39,9 @@
   "files": [
     "dist",
     "examples",
-    "LICENSE"
+    "LICENSE",
+    "src/**/*.ts",
+    "!src/**/*.spec.ts"
   ],
   "keywords": [
     "runtime-config",
@@ -48,7 +54,7 @@
   },
   "dependencies": {
     "ajv": "^8.17.1",
-    "@lorion-org/runtime-config": "^1.0.0-beta.0"
+    "@lorion-org/runtime-config": "^1.0.0-beta.1"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts",