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

package/src/validation.ts

@@ -0,0 +1,126 @@
+import Ajv, { type ErrorObject, type ValidateFunction } from 'ajv';
+import type { RuntimeConfigContext } from './types';
+
+export type RuntimeConfigValidationMode = 'none' | 'optional' | 'startup' | 'onUse';
+
+export type RuntimeConfigValidationPolicy = {
+  validation?: RuntimeConfigValidationMode;
+};
+
+export type RuntimeConfigValidationSchemaRegistry = Record<string, object>;
+
+export type RuntimeConfigValidationErrorTarget = {
+  scopeId: string;
+};
+
+export type RuntimeConfigValidationErrorFormatter = (
+  target: RuntimeConfigValidationErrorTarget,
+  validationError: ErrorObject,
+) => Error;
+
+export type RuntimeConfigValidationPolicyInput =
+  | RuntimeConfigValidationMode
+  | RuntimeConfigValidationPolicy
+  | undefined;
+
+export const defaultRuntimeConfigValidationMode: RuntimeConfigValidationMode = 'optional';
+
+export function resolveRuntimeConfigValidationMode(
+  input: RuntimeConfigValidationPolicyInput,
+): RuntimeConfigValidationMode {
+  return typeof input === 'string'
+    ? input
+    : (input?.validation ?? defaultRuntimeConfigValidationMode);
+}
+
+export function shouldRegisterRuntimeConfigValidationSchema(
+  input: RuntimeConfigValidationPolicyInput,
+): boolean {
+  return resolveRuntimeConfigValidationMode(input) !== 'none';
+}
+
+export function shouldValidateRuntimeConfigAtStartup(
+  input: RuntimeConfigValidationPolicyInput,
+): boolean {
+  const mode = resolveRuntimeConfigValidationMode(input);
+
+  return mode !== 'none' && mode !== 'onUse';
+}
+
+export function shouldRequireRuntimeConfigAtStartup(
+  input: RuntimeConfigValidationPolicyInput,
+): boolean {
+  return resolveRuntimeConfigValidationMode(input) === 'startup';
+}
+
+function formatDefaultRuntimeConfigValidationError(
+  target: RuntimeConfigValidationErrorTarget,
+  validationError: ErrorObject,
+): Error {
+  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'),
+  );
+}
+
+export class RuntimeConfigValidatorRegistry {
+  readonly #cache = new Map<string, ValidateFunction>();
+  readonly #formatError: RuntimeConfigValidationErrorFormatter;
+  readonly #schemas: RuntimeConfigValidationSchemaRegistry;
+
+  constructor(
+    schemas: RuntimeConfigValidationSchemaRegistry,
+    options: {
+      formatError?: RuntimeConfigValidationErrorFormatter;
+    } = {},
+  ) {
+    this.#formatError = options.formatError ?? formatDefaultRuntimeConfigValidationError;
+    this.#schemas = schemas;
+  }
+
+  get(scopeId: string): ValidateFunction {
+    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: string, fragment: RuntimeConfigContext): void {
+    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);
+  }
+}
+
+export function createRuntimeConfigValidatorRegistry(
+  schemas: RuntimeConfigValidationSchemaRegistry,
+  options: {
+    formatError?: RuntimeConfigValidationErrorFormatter;
+  } = {},
+): RuntimeConfigValidatorRegistry {
+  return new RuntimeConfigValidatorRegistry(schemas, options);
+}

package/examples/context-input-key.ts

@@ -1,46 +0,0 @@
-import {
-  projectSectionedRuntimeConfig,
-  resolveRuntimeConfigValue,
-} from '@lorion-org/runtime-config';
-
-const runtimeConfig = projectSectionedRuntimeConfig(
-  [
-    {
-      scopeId: 'billing',
-      config: {
-        public: {
-          apiBase: '/api/billing',
-        },
-        tenants: {
-          tenantA: {
-            public: {
-              apiBase: '/tenant-a/billing',
-            },
-          },
-        },
-      },
-    },
-  ],
-  {
-    contextInputKey: 'tenants',
-    contextOutputKey: '__tenants',
-  },
-);
-
-console.log(runtimeConfig.public);
-// {
-//   billingApiBase: '/api/billing',
-//   __tenants: {
-//     tenantA: {
-//       billingApiBase: '/tenant-a/billing'
-//     }
-//   }
-// }
-
-console.log(
-  resolveRuntimeConfigValue(runtimeConfig.public, 'billing', 'apiBase', {
-    contextId: 'tenantA',
-    contextOutputKey: '__tenants',
-  }),
-);
-// '/tenant-a/billing'

package/examples/env-vars.ts

@@ -1,25 +0,0 @@
-import {
-  runtimeEnvVarsToShellAssignments,
-  runtimeEnvVarsToString,
-  toRuntimeEnvVars,
-} from '@lorion-org/runtime-config';
-
-const envVars = toRuntimeEnvVars(
-  {
-    public: {
-      billingApiBase: '/api/billing',
-    },
-    private: {
-      billingApiSecret: 'secret',
-    },
-  },
-  'APP',
-);
-
-console.log(runtimeEnvVarsToString(envVars));
-// APP_PUBLIC_BILLING_API_BASE=/api/billing
-// APP_PRIVATE_BILLING_API_SECRET=secret
-
-console.log(runtimeEnvVarsToShellAssignments(envVars));
-// APP_PUBLIC_BILLING_API_BASE='"/api/billing"'
-// APP_PRIVATE_BILLING_API_SECRET='"secret"'

package/examples/namespaced-runtime-config.ts

@@ -1,50 +0,0 @@
-import {
-  projectRuntimeConfigNamespace,
-  projectRuntimeConfigNamespaces,
-} from '@lorion-org/runtime-config';
-
-const billingRuntimeConfig = projectRuntimeConfigNamespace('billing', {
-  public: {
-    apiBase: '/api/billing',
-  },
-  private: {
-    token: 'billing-token',
-  },
-});
-
-console.log(billingRuntimeConfig.public.billing);
-// { apiBase: '/api/billing' }
-
-console.log(billingRuntimeConfig.billing);
-// { token: 'billing-token' }
-
-const combinedRuntimeConfig = projectRuntimeConfigNamespaces([
-  {
-    scopeId: 'billing',
-    config: {
-      public: {
-        apiBase: '/api/billing',
-      },
-      private: {
-        token: 'billing-token',
-      },
-    },
-  },
-  {
-    scopeId: 'mail',
-    config: {
-      public: {
-        apiBase: '/api/mail',
-      },
-    },
-  },
-]);
-
-console.log(combinedRuntimeConfig.public.billing);
-// { apiBase: '/api/billing' }
-
-console.log(combinedRuntimeConfig.public.mail);
-// { apiBase: '/api/mail' }
-
-console.log(combinedRuntimeConfig.billing);
-// { token: 'billing-token' }

package/examples/scope-view.ts

@@ -1,32 +0,0 @@
-import {
-  getPrivateRuntimeConfigScope,
-  getPublicRuntimeConfigScope,
-  projectRuntimeConfigFragment,
-  toRuntimeEnvVars,
-} from '@lorion-org/runtime-config';
-
-const runtimeConfig = projectRuntimeConfigFragment('auth', {
-  public: {
-    url: 'https://auth.example.test',
-    realm: 'main',
-  },
-  private: {
-    clientSecret: 'secret',
-  },
-});
-
-console.log(runtimeConfig.public.authUrl);
-// 'https://auth.example.test'
-
-console.log(toRuntimeEnvVars(runtimeConfig, 'APP'));
-// {
-//   APP_PUBLIC_AUTH_URL: 'https://auth.example.test',
-//   APP_PUBLIC_AUTH_REALM: 'main',
-//   APP_PRIVATE_AUTH_CLIENT_SECRET: 'secret'
-// }
-
-console.log(getPublicRuntimeConfigScope(runtimeConfig, 'auth'));
-// { url: 'https://auth.example.test', realm: 'main' }
-
-console.log(getPrivateRuntimeConfigScope(runtimeConfig, 'auth'));
-// { clientSecret: 'secret' }

package/examples/sectioned-runtime-config.ts

@@ -1,52 +0,0 @@
-import {
-  getPublicRuntimeConfigScope,
-  projectSectionedRuntimeConfig,
-  resolveRuntimeConfigValue,
-  type RuntimeConfigFragmentMap,
-} from '@lorion-org/runtime-config';
-
-const fragments: RuntimeConfigFragmentMap = new Map([
-  [
-    'billing',
-    {
-      public: {
-        apiBase: '/api/billing',
-      },
-      private: {
-        apiSecret: 'secret',
-      },
-      contexts: {
-        tenantA: {
-          public: {
-            apiBase: '/tenant-a/billing',
-          },
-        },
-      },
-    },
-  ],
-  [
-    'mail',
-    {
-      public: {
-        apiBase: '/api/mail',
-      },
-    },
-  ],
-]);
-
-const runtimeConfig = projectSectionedRuntimeConfig(fragments);
-const tenantApiBase = resolveRuntimeConfigValue(runtimeConfig.public, 'billing', 'apiBase', {
-  contextId: 'tenantA',
-});
-
-console.log(runtimeConfig.public.billingApiBase);
-// '/api/billing'
-
-console.log(runtimeConfig.private.billingApiSecret);
-// 'secret'
-
-console.log(tenantApiBase);
-// '/tenant-a/billing'
-
-console.log(getPublicRuntimeConfigScope(runtimeConfig, 'billing'));
-// { apiBase: '/api/billing' }