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

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the 'Software'), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the 'Software'), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -45,7 +45,7 @@ The intended adapter shape is:
 - application-specific names, file names, and defaults stay in the consuming adapter
 
 Adapters may accept existing fragment field names and map them to generic
-contexts with `contextInputKey`. For example, a project can read `tenants`
+contexts with `contextInputKey`. For example, a project can read `stores`
 from its files while this package still works with the generic `contexts`
 model internally.
 
@@ -59,13 +59,13 @@ Fragments are written in local scope vocabulary. The scope id is not repeated in
 the keys.
 
 ```ts
-const authFragment = {
+const checkoutFragment = {
   public: {
-    url: 'https://auth.example.test',
-    realm: 'main',
+    currency: 'EUR',
+    successPath: '/orders/confirmed',
   },
   private: {
-    clientSecret: 'secret',
+    signingSecret: 'checkout_signing_secret_demo',
   },
 };
 ```
@@ -78,15 +78,15 @@ Some runtimes need one shared `public` and `private` object. The scope id become
 a transport prefix so many fragments can coexist without key collisions.
 
 ```ts
-const runtimeConfig = projectSectionedRuntimeConfig(new Map([['auth', authFragment]]));
+const runtimeConfig = projectSectionedRuntimeConfig(new Map([['checkout', checkoutFragment]]));
 
 // For a single fragment, use:
-projectRuntimeConfigFragment('auth', authFragment);
+projectRuntimeConfigFragment('checkout', checkoutFragment);
 
-runtimeConfig.public.authUrl;
-// => 'https://auth.example.test'
-runtimeConfig.private.authClientSecret;
-// => 'secret'
+runtimeConfig.public.checkoutCurrency;
+// => 'EUR'
+runtimeConfig.private.checkoutSigningSecret;
+// => 'checkout_signing_secret_demo'
 ```
 
 ### 3. Environment variable shape
@@ -96,19 +96,19 @@ Environment variables keep the same transport prefix and add visibility.
 ```ts
 toRuntimeEnvVars(runtimeConfig, 'APP');
 // => {
-//   APP_PUBLIC_AUTH_URL: 'https://auth.example.test',
-//   APP_PUBLIC_AUTH_REALM: 'main',
-//   APP_PRIVATE_AUTH_CLIENT_SECRET: 'secret'
+//   APP_PUBLIC_CHECKOUT_CURRENCY: 'EUR',
+//   APP_PUBLIC_CHECKOUT_SUCCESS_PATH: '/orders/confirmed',
+//   APP_PRIVATE_CHECKOUT_SIGNING_SECRET: 'checkout_signing_secret_demo'
 // }
 ```
 
 Usage code can read the flat runtime shape back through local keys:
 
 ```ts
-const auth = getPublicRuntimeConfigScope(runtimeConfig, 'auth');
+const checkout = getPublicRuntimeConfigScope(runtimeConfig, 'checkout');
 
-auth.url;
-// => 'https://auth.example.test'
+checkout.successPath;
+// => '/orders/confirmed'
 ```
 
 ## Basic example
@@ -122,18 +122,18 @@ import {
 
 const fragments = new Map([
   [
-    'billing',
+    'checkout',
     {
       public: {
-        apiBase: '/api/billing',
+        successPath: '/orders/confirmed',
       },
       private: {
-        apiSecret: 'secret',
+        signingSecret: 'checkout_signing_secret_demo',
       },
       contexts: {
-        tenantA: {
+        'eu-store': {
           public: {
-            apiBase: '/tenant-a/billing',
+            successPath: '/eu-store/orders/confirmed',
           },
         },
       },
@@ -143,16 +143,16 @@ const fragments = new Map([
 
 const runtimeConfig = projectSectionedRuntimeConfig(fragments);
 
-runtimeConfig.public.billingApiBase;
-// => '/api/billing'
+runtimeConfig.public.checkoutSuccessPath;
+// => '/orders/confirmed'
 
-resolveRuntimeConfigValue(runtimeConfig.public, 'billing', 'apiBase', {
-  contextId: 'tenantA',
+resolveRuntimeConfigValue(runtimeConfig.public, 'checkout', 'successPath', {
+  contextId: 'eu-store',
 });
-// => '/tenant-a/billing'
+// => '/eu-store/orders/confirmed'
 
-getPublicRuntimeConfigScope(runtimeConfig, 'billing');
-// => { apiBase: '/api/billing' }
+getPublicRuntimeConfigScope(runtimeConfig, 'checkout');
+// => { successPath: '/orders/confirmed' }
 ```
 
 ## Example: custom context input key
@@ -163,15 +163,15 @@ import { projectSectionedRuntimeConfig } from '@lorion-org/runtime-config';
 projectSectionedRuntimeConfig(
   [
     {
-      scopeId: 'billing',
+      scopeId: 'checkout',
       config: {
         public: {
-          apiBase: '/api/billing',
+          successPath: '/orders/confirmed',
         },
-        tenants: {
-          tenantA: {
+        stores: {
+          'eu-store': {
             public: {
-              apiBase: '/tenant-a/billing',
+              successPath: '/eu-store/orders/confirmed',
             },
           },
         },
@@ -179,16 +179,16 @@ projectSectionedRuntimeConfig(
     },
   ],
   {
-    contextInputKey: 'tenants',
-    contextOutputKey: '__tenants',
+    contextInputKey: 'stores',
+    contextOutputKey: '__stores',
   },
 );
 // => {
 //   public: {
-//     billingApiBase: '/api/billing',
-//     __tenants: {
-//       tenantA: {
-//         billingApiBase: '/tenant-a/billing'
+//     checkoutSuccessPath: '/orders/confirmed',
+//     __stores: {
+//       'eu-store': {
+//         checkoutSuccessPath: '/eu-store/orders/confirmed'
 //       }
 //     }
 //   },
@@ -209,38 +209,33 @@ import {
   projectRuntimeConfigNamespaces,
 } from '@lorion-org/runtime-config';
 
-const runtimeConfig = projectRuntimeConfigNamespace('mail', {
+const runtimeConfig = projectRuntimeConfigNamespace('checkout', {
   public: {
-    apiBase: '/api/mail',
+    successPath: '/orders/confirmed',
   },
   private: {
-    token: 'mail-token',
+    signingSecret: 'checkout_signing_secret_demo',
   },
 });
 
-runtimeConfig.public.mail;
-// => { apiBase: '/api/mail' }
-runtimeConfig.mail;
-// => { token: 'mail-token' }
+runtimeConfig.public.checkout;
+// => { successPath: '/orders/confirmed' }
+runtimeConfig.checkout;
+// => { signingSecret: 'checkout_signing_secret_demo' }
 
 const combinedRuntimeConfig = projectRuntimeConfigNamespaces([
   {
-    scopeId: 'mail',
+    scopeId: 'payments',
     config: {
       public: {
-        apiBase: '/api/mail',
-      },
-      private: {
-        token: 'mail-token',
+        configuredProvider: 'payment-provider-stripe',
       },
     },
   },
 ]);
 
-combinedRuntimeConfig.public.mail;
-// => { apiBase: '/api/mail' }
-combinedRuntimeConfig.mail;
-// => { token: 'mail-token' }
+combinedRuntimeConfig.public.payments;
+// => { configuredProvider: 'payment-provider-stripe' }
 ```
 
 ## Example: environment variables
@@ -258,30 +253,30 @@ import {
 const envVars = toRuntimeEnvVars(
   {
     public: {
-      billingApiBase: '/api/billing',
+      checkoutSuccessPath: '/orders/confirmed',
     },
     private: {
-      billingApiSecret: 'secret',
+      checkoutSigningSecret: 'checkout_signing_secret_demo',
     },
   },
   'APP',
 );
 
 runtimeEnvVarsToString(envVars);
-// => APP_PUBLIC_BILLING_API_BASE=/api/billing
-// => APP_PRIVATE_BILLING_API_SECRET=secret
+// => APP_PUBLIC_CHECKOUT_SUCCESS_PATH=/orders/confirmed
+// => APP_PRIVATE_CHECKOUT_SIGNING_SECRET=checkout_signing_secret_demo
 
 runtimeEnvVarsToShellAssignments(envVars);
-// => APP_PUBLIC_BILLING_API_BASE='"/api/billing"'
-// => APP_PRIVATE_BILLING_API_SECRET='"secret"'
+// => APP_PUBLIC_CHECKOUT_SUCCESS_PATH='"/orders/confirmed"'
+// => APP_PRIVATE_CHECKOUT_SIGNING_SECRET='"checkout_signing_secret_demo"'
 
 projectRuntimeConfigEnvVars(
   new Map([
     [
-      'billing',
+      'payments',
       {
         public: {
-          apiBase: '/api/billing',
+          configuredProvider: 'payment-provider-stripe',
         },
       },
     ],
@@ -291,7 +286,7 @@ projectRuntimeConfigEnvVars(
   },
 );
 // => {
-//   APP_PUBLIC_BILLING_API_BASE: '/api/billing'
+//   APP_PUBLIC_PAYMENTS_CONFIGURED_PROVIDER: 'payment-provider-stripe'
 // }
 ```
 

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,13 +17,24 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  RuntimeConfigValidatorRegistry: () => RuntimeConfigValidatorRegistry,
   createRuntimeConfigEnvKey: () => createRuntimeConfigEnvKey,
   createRuntimeConfigKey: () => createRuntimeConfigKey,
+  createRuntimeConfigValidatorRegistry: () => createRuntimeConfigValidatorRegistry,
+  defaultRuntimeConfigValidationMode: () => defaultRuntimeConfigValidationMode,
   getPrivateRuntimeConfigScope: () => getPrivateRuntimeConfigScope,
   getPublicRuntimeConfigScope: () => getPublicRuntimeConfigScope,
   getRuntimeConfigFragment: () => getRuntimeConfigFragment,
@@ -33,12 +46,16 @@ __export(index_exports, {
   projectRuntimeConfigNamespace: () => projectRuntimeConfigNamespace,
   projectRuntimeConfigNamespaces: () => projectRuntimeConfigNamespaces,
   projectSectionedRuntimeConfig: () => projectSectionedRuntimeConfig,
+  resolveRuntimeConfigValidationMode: () => resolveRuntimeConfigValidationMode,
   resolveRuntimeConfigValue: () => resolveRuntimeConfigValue,
   resolveRuntimeConfigValueFromRuntimeConfig: () => resolveRuntimeConfigValueFromRuntimeConfig,
   runtimeConfigVisibilities: () => runtimeConfigVisibilities,
   runtimeEnvValueToShellLiteral: () => runtimeEnvValueToShellLiteral,
   runtimeEnvVarsToShellAssignments: () => runtimeEnvVarsToShellAssignments,
   runtimeEnvVarsToString: () => runtimeEnvVarsToString,
+  shouldRegisterRuntimeConfigValidationSchema: () => shouldRegisterRuntimeConfigValidationSchema,
+  shouldRequireRuntimeConfigAtStartup: () => shouldRequireRuntimeConfigAtStartup,
+  shouldValidateRuntimeConfigAtStartup: () => shouldValidateRuntimeConfigAtStartup,
   stripRuntimeConfigScopePrefix: () => stripRuntimeConfigScopePrefix,
   toRuntimeConfigFragment: () => toRuntimeConfigFragment,
   toRuntimeEnvVars: () => toRuntimeEnvVars,
@@ -340,10 +357,74 @@ function getRuntimeConfigFragment(runtimeConfig, scopeId, options = {}) {
     private: getPrivateRuntimeConfigScope(runtimeConfig, scopeId, privateOptions)
   };
 }
+
+// src/validation.ts
+var import_ajv = __toESM(require("ajv"), 1);
+var defaultRuntimeConfigValidationMode = "optional";
+function resolveRuntimeConfigValidationMode(input) {
+  return typeof input === "string" ? input : input?.validation ?? defaultRuntimeConfigValidationMode;
+}
+function shouldRegisterRuntimeConfigValidationSchema(input) {
+  return resolveRuntimeConfigValidationMode(input) !== "none";
+}
+function shouldValidateRuntimeConfigAtStartup(input) {
+  const mode = resolveRuntimeConfigValidationMode(input);
+  return mode !== "none" && mode !== "onUse";
+}
+function shouldRequireRuntimeConfigAtStartup(input) {
+  return resolveRuntimeConfigValidationMode(input) === "startup";
+}
+function formatDefaultRuntimeConfigValidationError(target, validationError) {
+  const jsonPath = validationError.instancePath || "/";
+  const schemaError = `${validationError.keyword}${validationError.message ? `: ${validationError.message}` : ""}`;
+  return new Error(
+    [
+      "RuntimeConfig schema validation failed.",
+      `Scope: ${target.scopeId}`,
+      `JSON path: ${jsonPath}`,
+      `Schema error: ${schemaError}`
+    ].join("\n")
+  );
+}
+var RuntimeConfigValidatorRegistry = class {
+  #cache = /* @__PURE__ */ new Map();
+  #formatError;
+  #schemas;
+  constructor(schemas, options = {}) {
+    this.#formatError = options.formatError ?? formatDefaultRuntimeConfigValidationError;
+    this.#schemas = schemas;
+  }
+  get(scopeId) {
+    const schema = this.#schemas[scopeId];
+    if (!schema) {
+      throw new Error(`RuntimeConfig validation schema not registered for scope "${scopeId}".`);
+    }
+    const cached = this.#cache.get(scopeId);
+    if (cached) return cached;
+    const validate = new import_ajv.default({ strict: false, allErrors: false }).compile(schema);
+    this.#cache.set(scopeId, validate);
+    return validate;
+  }
+  assert(scopeId, fragment) {
+    const validate = this.get(scopeId);
+    if (validate(fragment)) return;
+    const validationError = validate.errors?.[0];
+    if (!validationError) {
+      throw new Error(`RuntimeConfig schema validation failed for scope "${scopeId}".`);
+    }
+    throw this.#formatError({ scopeId }, validationError);
+  }
+};
+function createRuntimeConfigValidatorRegistry(schemas, options = {}) {
+  return new RuntimeConfigValidatorRegistry(schemas, options);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  RuntimeConfigValidatorRegistry,
   createRuntimeConfigEnvKey,
   createRuntimeConfigKey,
+  createRuntimeConfigValidatorRegistry,
+  defaultRuntimeConfigValidationMode,
   getPrivateRuntimeConfigScope,
   getPublicRuntimeConfigScope,
   getRuntimeConfigFragment,
@@ -355,12 +436,16 @@ function getRuntimeConfigFragment(runtimeConfig, scopeId, options = {}) {
   projectRuntimeConfigNamespace,
   projectRuntimeConfigNamespaces,
   projectSectionedRuntimeConfig,
+  resolveRuntimeConfigValidationMode,
   resolveRuntimeConfigValue,
   resolveRuntimeConfigValueFromRuntimeConfig,
   runtimeConfigVisibilities,
   runtimeEnvValueToShellLiteral,
   runtimeEnvVarsToShellAssignments,
   runtimeEnvVarsToString,
+  shouldRegisterRuntimeConfigValidationSchema,
+  shouldRequireRuntimeConfigAtStartup,
+  shouldValidateRuntimeConfigAtStartup,
   stripRuntimeConfigScopePrefix,
   toRuntimeConfigFragment,
   toRuntimeEnvVars,

package/dist/index.d.cts

@@ -1,3 +1,5 @@
+import { ErrorObject, ValidateFunction } from 'ajv';
+
 type RuntimeConfigKeyStrategy = (scopeId: string, key: string) => string;
 type RuntimeConfigKeyOptions = {
     keyStrategy?: RuntimeConfigKeyStrategy;
@@ -98,4 +100,31 @@ declare function getPublicRuntimeConfigScope<T extends RuntimeConfigSection = Ru
 declare function getPrivateRuntimeConfigScope<T extends RuntimeConfigSection = RuntimeConfigSection>(runtimeConfig: Partial<Record<ConfigVisibility, RuntimeConfigSection | undefined>>, scopeId: string, options?: Omit<GetRuntimeConfigScopeOptions, 'visibility'>): T;
 declare function getRuntimeConfigFragment(runtimeConfig: Partial<Record<ConfigVisibility, RuntimeConfigSection | undefined>>, scopeId: string, options?: GetRuntimeConfigFragmentOptions): RuntimeConfigContext;
 
-export { type ConfigVisibility, type GetRuntimeConfigFragmentOptions, type GetRuntimeConfigScopeOptions, type NamedRuntimeConfigFragment, type NormalizeRuntimeConfigFragmentOptions, type ProjectRuntimeConfigEnvVarsOptions, type ProjectRuntimeConfigFragmentOptions, type ProjectRuntimeConfigNamespaceOptions, type ProjectRuntimeConfigNamespacesOptions, type ProjectSectionedRuntimeConfigOptions, type ResolveRuntimeConfigValueFromRuntimeConfigOptions, type ResolveRuntimeConfigValueOptions, type RuntimeConfigContext, type RuntimeConfigFragment, type RuntimeConfigFragmentInput, type RuntimeConfigFragmentMap, type RuntimeConfigKeyOptions, type RuntimeConfigKeyStrategy, type RuntimeConfigNamespaceProjection, type RuntimeConfigSection, type RuntimeEnvVars, type SectionedRuntimeConfig, createRuntimeConfigEnvKey, createRuntimeConfigKey, getPrivateRuntimeConfigScope, getPublicRuntimeConfigScope, getRuntimeConfigFragment, getRuntimeConfigScope, injectRuntimeEnvVars, normalizeRuntimeConfigFragments, projectRuntimeConfigEnvVars, projectRuntimeConfigFragment, projectRuntimeConfigNamespace, projectRuntimeConfigNamespaces, projectSectionedRuntimeConfig, resolveRuntimeConfigValue, resolveRuntimeConfigValueFromRuntimeConfig, runtimeConfigVisibilities, runtimeEnvValueToShellLiteral, runtimeEnvVarsToShellAssignments, runtimeEnvVarsToString, stripRuntimeConfigScopePrefix, toRuntimeConfigFragment, toRuntimeEnvVars, toSnakeUpperCase };
+type RuntimeConfigValidationMode = 'none' | 'optional' | 'startup' | 'onUse';
+type RuntimeConfigValidationPolicy = {
+    validation?: RuntimeConfigValidationMode;
+};
+type RuntimeConfigValidationSchemaRegistry = Record<string, object>;
+type RuntimeConfigValidationErrorTarget = {
+    scopeId: string;
+};
+type RuntimeConfigValidationErrorFormatter = (target: RuntimeConfigValidationErrorTarget, validationError: ErrorObject) => Error;
+type RuntimeConfigValidationPolicyInput = RuntimeConfigValidationMode | RuntimeConfigValidationPolicy | undefined;
+declare const defaultRuntimeConfigValidationMode: RuntimeConfigValidationMode;
+declare function resolveRuntimeConfigValidationMode(input: RuntimeConfigValidationPolicyInput): RuntimeConfigValidationMode;
+declare function shouldRegisterRuntimeConfigValidationSchema(input: RuntimeConfigValidationPolicyInput): boolean;
+declare function shouldValidateRuntimeConfigAtStartup(input: RuntimeConfigValidationPolicyInput): boolean;
+declare function shouldRequireRuntimeConfigAtStartup(input: RuntimeConfigValidationPolicyInput): boolean;
+declare class RuntimeConfigValidatorRegistry {
+    #private;
+    constructor(schemas: RuntimeConfigValidationSchemaRegistry, options?: {
+        formatError?: RuntimeConfigValidationErrorFormatter;
+    });
+    get(scopeId: string): ValidateFunction;
+    assert(scopeId: string, fragment: RuntimeConfigContext): void;
+}
+declare function createRuntimeConfigValidatorRegistry(schemas: RuntimeConfigValidationSchemaRegistry, options?: {
+    formatError?: RuntimeConfigValidationErrorFormatter;
+}): RuntimeConfigValidatorRegistry;
+
+export { type ConfigVisibility, type GetRuntimeConfigFragmentOptions, type GetRuntimeConfigScopeOptions, type NamedRuntimeConfigFragment, type NormalizeRuntimeConfigFragmentOptions, type ProjectRuntimeConfigEnvVarsOptions, type ProjectRuntimeConfigFragmentOptions, type ProjectRuntimeConfigNamespaceOptions, type ProjectRuntimeConfigNamespacesOptions, type ProjectSectionedRuntimeConfigOptions, type ResolveRuntimeConfigValueFromRuntimeConfigOptions, type ResolveRuntimeConfigValueOptions, type RuntimeConfigContext, type RuntimeConfigFragment, type RuntimeConfigFragmentInput, type RuntimeConfigFragmentMap, type RuntimeConfigKeyOptions, type RuntimeConfigKeyStrategy, type RuntimeConfigNamespaceProjection, type RuntimeConfigSection, type RuntimeConfigValidationErrorFormatter, type RuntimeConfigValidationErrorTarget, type RuntimeConfigValidationMode, type RuntimeConfigValidationPolicy, type RuntimeConfigValidationPolicyInput, type RuntimeConfigValidationSchemaRegistry, RuntimeConfigValidatorRegistry, type RuntimeEnvVars, type SectionedRuntimeConfig, createRuntimeConfigEnvKey, createRuntimeConfigKey, createRuntimeConfigValidatorRegistry, defaultRuntimeConfigValidationMode, getPrivateRuntimeConfigScope, getPublicRuntimeConfigScope, getRuntimeConfigFragment, getRuntimeConfigScope, injectRuntimeEnvVars, normalizeRuntimeConfigFragments, projectRuntimeConfigEnvVars, projectRuntimeConfigFragment, projectRuntimeConfigNamespace, projectRuntimeConfigNamespaces, projectSectionedRuntimeConfig, resolveRuntimeConfigValidationMode, resolveRuntimeConfigValue, resolveRuntimeConfigValueFromRuntimeConfig, runtimeConfigVisibilities, runtimeEnvValueToShellLiteral, runtimeEnvVarsToShellAssignments, runtimeEnvVarsToString, shouldRegisterRuntimeConfigValidationSchema, shouldRequireRuntimeConfigAtStartup, shouldValidateRuntimeConfigAtStartup, stripRuntimeConfigScopePrefix, toRuntimeConfigFragment, toRuntimeEnvVars, toSnakeUpperCase };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { ErrorObject, ValidateFunction } from 'ajv';
+
 type RuntimeConfigKeyStrategy = (scopeId: string, key: string) => string;
 type RuntimeConfigKeyOptions = {
     keyStrategy?: RuntimeConfigKeyStrategy;
@@ -98,4 +100,31 @@ declare function getPublicRuntimeConfigScope<T extends RuntimeConfigSection = Ru
 declare function getPrivateRuntimeConfigScope<T extends RuntimeConfigSection = RuntimeConfigSection>(runtimeConfig: Partial<Record<ConfigVisibility, RuntimeConfigSection | undefined>>, scopeId: string, options?: Omit<GetRuntimeConfigScopeOptions, 'visibility'>): T;
 declare function getRuntimeConfigFragment(runtimeConfig: Partial<Record<ConfigVisibility, RuntimeConfigSection | undefined>>, scopeId: string, options?: GetRuntimeConfigFragmentOptions): RuntimeConfigContext;
 
-export { type ConfigVisibility, type GetRuntimeConfigFragmentOptions, type GetRuntimeConfigScopeOptions, type NamedRuntimeConfigFragment, type NormalizeRuntimeConfigFragmentOptions, type ProjectRuntimeConfigEnvVarsOptions, type ProjectRuntimeConfigFragmentOptions, type ProjectRuntimeConfigNamespaceOptions, type ProjectRuntimeConfigNamespacesOptions, type ProjectSectionedRuntimeConfigOptions, type ResolveRuntimeConfigValueFromRuntimeConfigOptions, type ResolveRuntimeConfigValueOptions, type RuntimeConfigContext, type RuntimeConfigFragment, type RuntimeConfigFragmentInput, type RuntimeConfigFragmentMap, type RuntimeConfigKeyOptions, type RuntimeConfigKeyStrategy, type RuntimeConfigNamespaceProjection, type RuntimeConfigSection, type RuntimeEnvVars, type SectionedRuntimeConfig, createRuntimeConfigEnvKey, createRuntimeConfigKey, getPrivateRuntimeConfigScope, getPublicRuntimeConfigScope, getRuntimeConfigFragment, getRuntimeConfigScope, injectRuntimeEnvVars, normalizeRuntimeConfigFragments, projectRuntimeConfigEnvVars, projectRuntimeConfigFragment, projectRuntimeConfigNamespace, projectRuntimeConfigNamespaces, projectSectionedRuntimeConfig, resolveRuntimeConfigValue, resolveRuntimeConfigValueFromRuntimeConfig, runtimeConfigVisibilities, runtimeEnvValueToShellLiteral, runtimeEnvVarsToShellAssignments, runtimeEnvVarsToString, stripRuntimeConfigScopePrefix, toRuntimeConfigFragment, toRuntimeEnvVars, toSnakeUpperCase };
+type RuntimeConfigValidationMode = 'none' | 'optional' | 'startup' | 'onUse';
+type RuntimeConfigValidationPolicy = {
+    validation?: RuntimeConfigValidationMode;
+};
+type RuntimeConfigValidationSchemaRegistry = Record<string, object>;
+type RuntimeConfigValidationErrorTarget = {
+    scopeId: string;
+};
+type RuntimeConfigValidationErrorFormatter = (target: RuntimeConfigValidationErrorTarget, validationError: ErrorObject) => Error;
+type RuntimeConfigValidationPolicyInput = RuntimeConfigValidationMode | RuntimeConfigValidationPolicy | undefined;
+declare const defaultRuntimeConfigValidationMode: RuntimeConfigValidationMode;
+declare function resolveRuntimeConfigValidationMode(input: RuntimeConfigValidationPolicyInput): RuntimeConfigValidationMode;
+declare function shouldRegisterRuntimeConfigValidationSchema(input: RuntimeConfigValidationPolicyInput): boolean;
+declare function shouldValidateRuntimeConfigAtStartup(input: RuntimeConfigValidationPolicyInput): boolean;
+declare function shouldRequireRuntimeConfigAtStartup(input: RuntimeConfigValidationPolicyInput): boolean;
+declare class RuntimeConfigValidatorRegistry {
+    #private;
+    constructor(schemas: RuntimeConfigValidationSchemaRegistry, options?: {
+        formatError?: RuntimeConfigValidationErrorFormatter;
+    });
+    get(scopeId: string): ValidateFunction;
+    assert(scopeId: string, fragment: RuntimeConfigContext): void;
+}
+declare function createRuntimeConfigValidatorRegistry(schemas: RuntimeConfigValidationSchemaRegistry, options?: {
+    formatError?: RuntimeConfigValidationErrorFormatter;
+}): RuntimeConfigValidatorRegistry;
+
+export { type ConfigVisibility, type GetRuntimeConfigFragmentOptions, type GetRuntimeConfigScopeOptions, type NamedRuntimeConfigFragment, type NormalizeRuntimeConfigFragmentOptions, type ProjectRuntimeConfigEnvVarsOptions, type ProjectRuntimeConfigFragmentOptions, type ProjectRuntimeConfigNamespaceOptions, type ProjectRuntimeConfigNamespacesOptions, type ProjectSectionedRuntimeConfigOptions, type ResolveRuntimeConfigValueFromRuntimeConfigOptions, type ResolveRuntimeConfigValueOptions, type RuntimeConfigContext, type RuntimeConfigFragment, type RuntimeConfigFragmentInput, type RuntimeConfigFragmentMap, type RuntimeConfigKeyOptions, type RuntimeConfigKeyStrategy, type RuntimeConfigNamespaceProjection, type RuntimeConfigSection, type RuntimeConfigValidationErrorFormatter, type RuntimeConfigValidationErrorTarget, type RuntimeConfigValidationMode, type RuntimeConfigValidationPolicy, type RuntimeConfigValidationPolicyInput, type RuntimeConfigValidationSchemaRegistry, RuntimeConfigValidatorRegistry, type RuntimeEnvVars, type SectionedRuntimeConfig, createRuntimeConfigEnvKey, createRuntimeConfigKey, createRuntimeConfigValidatorRegistry, defaultRuntimeConfigValidationMode, getPrivateRuntimeConfigScope, getPublicRuntimeConfigScope, getRuntimeConfigFragment, getRuntimeConfigScope, injectRuntimeEnvVars, normalizeRuntimeConfigFragments, projectRuntimeConfigEnvVars, projectRuntimeConfigFragment, projectRuntimeConfigNamespace, projectRuntimeConfigNamespaces, projectSectionedRuntimeConfig, resolveRuntimeConfigValidationMode, resolveRuntimeConfigValue, resolveRuntimeConfigValueFromRuntimeConfig, runtimeConfigVisibilities, runtimeEnvValueToShellLiteral, runtimeEnvVarsToShellAssignments, runtimeEnvVarsToString, shouldRegisterRuntimeConfigValidationSchema, shouldRequireRuntimeConfigAtStartup, shouldValidateRuntimeConfigAtStartup, stripRuntimeConfigScopePrefix, toRuntimeConfigFragment, toRuntimeEnvVars, toSnakeUpperCase };

package/dist/index.js

@@ -292,9 +292,73 @@ function getRuntimeConfigFragment(runtimeConfig, scopeId, options = {}) {
     private: getPrivateRuntimeConfigScope(runtimeConfig, scopeId, privateOptions)
   };
 }
+
+// src/validation.ts
+import Ajv from "ajv";
+var defaultRuntimeConfigValidationMode = "optional";
+function resolveRuntimeConfigValidationMode(input) {
+  return typeof input === "string" ? input : input?.validation ?? defaultRuntimeConfigValidationMode;
+}
+function shouldRegisterRuntimeConfigValidationSchema(input) {
+  return resolveRuntimeConfigValidationMode(input) !== "none";
+}
+function shouldValidateRuntimeConfigAtStartup(input) {
+  const mode = resolveRuntimeConfigValidationMode(input);
+  return mode !== "none" && mode !== "onUse";
+}
+function shouldRequireRuntimeConfigAtStartup(input) {
+  return resolveRuntimeConfigValidationMode(input) === "startup";
+}
+function formatDefaultRuntimeConfigValidationError(target, validationError) {
+  const jsonPath = validationError.instancePath || "/";
+  const schemaError = `${validationError.keyword}${validationError.message ? `: ${validationError.message}` : ""}`;
+  return new Error(
+    [
+      "RuntimeConfig schema validation failed.",
+      `Scope: ${target.scopeId}`,
+      `JSON path: ${jsonPath}`,
+      `Schema error: ${schemaError}`
+    ].join("\n")
+  );
+}
+var RuntimeConfigValidatorRegistry = class {
+  #cache = /* @__PURE__ */ new Map();
+  #formatError;
+  #schemas;
+  constructor(schemas, options = {}) {
+    this.#formatError = options.formatError ?? formatDefaultRuntimeConfigValidationError;
+    this.#schemas = schemas;
+  }
+  get(scopeId) {
+    const schema = this.#schemas[scopeId];
+    if (!schema) {
+      throw new Error(`RuntimeConfig validation schema not registered for scope "${scopeId}".`);
+    }
+    const cached = this.#cache.get(scopeId);
+    if (cached) return cached;
+    const validate = new Ajv({ strict: false, allErrors: false }).compile(schema);
+    this.#cache.set(scopeId, validate);
+    return validate;
+  }
+  assert(scopeId, fragment) {
+    const validate = this.get(scopeId);
+    if (validate(fragment)) return;
+    const validationError = validate.errors?.[0];
+    if (!validationError) {
+      throw new Error(`RuntimeConfig schema validation failed for scope "${scopeId}".`);
+    }
+    throw this.#formatError({ scopeId }, validationError);
+  }
+};
+function createRuntimeConfigValidatorRegistry(schemas, options = {}) {
+  return new RuntimeConfigValidatorRegistry(schemas, options);
+}
 export {
+  RuntimeConfigValidatorRegistry,
   createRuntimeConfigEnvKey,
   createRuntimeConfigKey,
+  createRuntimeConfigValidatorRegistry,
+  defaultRuntimeConfigValidationMode,
   getPrivateRuntimeConfigScope,
   getPublicRuntimeConfigScope,
   getRuntimeConfigFragment,
@@ -306,12 +370,16 @@ export {
   projectRuntimeConfigNamespace,
   projectRuntimeConfigNamespaces,
   projectSectionedRuntimeConfig,
+  resolveRuntimeConfigValidationMode,
   resolveRuntimeConfigValue,
   resolveRuntimeConfigValueFromRuntimeConfig,
   runtimeConfigVisibilities,
   runtimeEnvValueToShellLiteral,
   runtimeEnvVarsToShellAssignments,
   runtimeEnvVarsToString,
+  shouldRegisterRuntimeConfigValidationSchema,
+  shouldRequireRuntimeConfigAtStartup,
+  shouldValidateRuntimeConfigAtStartup,
   stripRuntimeConfigScopePrefix,
   toRuntimeConfigFragment,
   toRuntimeEnvVars,