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

package/src/project.ts

@@ -0,0 +1,208 @@
+import { createRuntimeConfigKey, type RuntimeConfigKeyOptions } from './key';
+import { toRuntimeConfigFragment, type NormalizeRuntimeConfigFragmentOptions } from './fragment';
+import {
+  runtimeConfigVisibilities,
+  type NamedRuntimeConfigFragment,
+  type RuntimeConfigContext,
+  type RuntimeConfigFragment,
+  type RuntimeConfigFragmentMap,
+  type RuntimeConfigNamespaceProjection,
+  type RuntimeConfigSection,
+  type SectionedRuntimeConfig,
+  type ConfigVisibility,
+} from './types';
+
+export type ProjectSectionedRuntimeConfigOptions = RuntimeConfigKeyOptions &
+  NormalizeRuntimeConfigFragmentOptions & {
+    contextOutputKey?: string;
+    includeContexts?: boolean;
+    scopeIds?: string[];
+  };
+
+export type ProjectRuntimeConfigFragmentOptions = Omit<
+  ProjectSectionedRuntimeConfigOptions,
+  'scopeIds'
+>;
+
+export type ProjectRuntimeConfigNamespacesOptions = {
+  contextInputKey?: string;
+  contextId?: string;
+  namespaceStrategy?: 'nested' | 'flat';
+  scopeIds?: string[];
+};
+
+export type ProjectRuntimeConfigNamespaceOptions = Omit<
+  ProjectRuntimeConfigNamespacesOptions,
+  'scopeIds'
+>;
+
+export function normalizeRuntimeConfigFragments(
+  fragments: Iterable<NamedRuntimeConfigFragment> | RuntimeConfigFragmentMap,
+  options: NormalizeRuntimeConfigFragmentOptions = {},
+): NamedRuntimeConfigFragment[] {
+  const entries =
+    fragments instanceof Map
+      ? Array.from(fragments.entries()).map(([scopeId, config]) => ({ scopeId, config }))
+      : Array.from(fragments);
+
+  return entries
+    .map((fragment) => ({
+      scopeId: fragment.scopeId.trim(),
+      config: toRuntimeConfigFragment(fragment.config, options),
+    }))
+    .filter((fragment) => fragment.scopeId.length > 0)
+    .sort((left, right) => left.scopeId.localeCompare(right.scopeId));
+}
+
+function filterFragments(input: {
+  fragments: Iterable<NamedRuntimeConfigFragment> | RuntimeConfigFragmentMap;
+  contextInputKey?: string;
+  scopeIds?: string[];
+}): NamedRuntimeConfigFragment[] {
+  const scopeIdSet = input.scopeIds
+    ? new Set(input.scopeIds.map((id) => id.trim()).filter(Boolean))
+    : undefined;
+
+  return normalizeRuntimeConfigFragments(input.fragments, {
+    ...(input.contextInputKey ? { contextInputKey: input.contextInputKey } : {}),
+  }).filter((fragment) => !scopeIdSet || scopeIdSet.has(fragment.scopeId));
+}
+
+function getSection(
+  config: RuntimeConfigContext | undefined,
+  visibility: ConfigVisibility,
+): RuntimeConfigSection | undefined {
+  return config?.[visibility];
+}
+
+function assignDefined(target: RuntimeConfigSection, key: string, value: unknown): void {
+  if (value !== undefined) {
+    target[key] = value;
+  }
+}
+
+export function projectSectionedRuntimeConfig(
+  fragments: Iterable<NamedRuntimeConfigFragment> | RuntimeConfigFragmentMap,
+  options: ProjectSectionedRuntimeConfigOptions = {},
+): SectionedRuntimeConfig {
+  const result: SectionedRuntimeConfig = {
+    public: {},
+    private: {},
+  };
+  const contextOutputKey = options.contextOutputKey ?? '__contexts';
+
+  const filteredFragments = filterFragments({
+    fragments,
+    ...(options.contextInputKey ? { contextInputKey: options.contextInputKey } : {}),
+    ...(options.scopeIds ? { scopeIds: options.scopeIds } : {}),
+  });
+
+  for (const fragment of filteredFragments) {
+    for (const visibility of runtimeConfigVisibilities) {
+      const section = getSection(fragment.config, visibility);
+      if (!section) continue;
+
+      for (const [key, value] of Object.entries(section)) {
+        assignDefined(
+          result[visibility],
+          createRuntimeConfigKey(fragment.scopeId, key, options),
+          value,
+        );
+      }
+    }
+
+    if (options.includeContexts === false) continue;
+
+    for (const [contextId, context] of Object.entries(fragment.config.contexts ?? {})) {
+      for (const visibility of runtimeConfigVisibilities) {
+        const section = getSection(context, visibility);
+        if (!section) continue;
+
+        const contexts =
+          (result[visibility][contextOutputKey] as
+            | Record<string, RuntimeConfigSection>
+            | undefined) ?? {};
+        const contextValues = contexts[contextId] ?? {};
+
+        for (const [key, value] of Object.entries(section)) {
+          assignDefined(
+            contextValues,
+            createRuntimeConfigKey(fragment.scopeId, key, options),
+            value,
+          );
+        }
+
+        contexts[contextId] = contextValues;
+        result[visibility][contextOutputKey] = contexts;
+      }
+    }
+  }
+
+  return result;
+}
+
+export function projectRuntimeConfigFragment(
+  scopeId: string,
+  config: RuntimeConfigFragment,
+  options: ProjectRuntimeConfigFragmentOptions = {},
+): SectionedRuntimeConfig {
+  return projectSectionedRuntimeConfig(new Map([[scopeId, config]]), options);
+}
+
+export function projectRuntimeConfigNamespace(
+  scopeId: string,
+  config: RuntimeConfigFragment,
+  options: ProjectRuntimeConfigNamespaceOptions = {},
+): RuntimeConfigNamespaceProjection {
+  return projectRuntimeConfigNamespaces([{ scopeId, config }], options);
+}
+
+export function projectRuntimeConfigNamespaces(
+  fragments: Iterable<NamedRuntimeConfigFragment> | RuntimeConfigFragmentMap,
+  options: ProjectRuntimeConfigNamespacesOptions = {},
+): RuntimeConfigNamespaceProjection {
+  const result: RuntimeConfigNamespaceProjection = {
+    public: {},
+  };
+  const namespaceStrategy = options.namespaceStrategy ?? 'nested';
+
+  const filteredFragments = filterFragments({
+    fragments,
+    ...(options.contextInputKey ? { contextInputKey: options.contextInputKey } : {}),
+    ...(options.scopeIds ? { scopeIds: options.scopeIds } : {}),
+  });
+
+  for (const fragment of filteredFragments) {
+    const context = options.contextId ? fragment.config.contexts?.[options.contextId] : undefined;
+    const publicSection = {
+      ...(fragment.config.public ?? {}),
+      ...(context?.public ?? {}),
+    };
+    const privateSection = {
+      ...(fragment.config.private ?? {}),
+      ...(context?.private ?? {}),
+    };
+
+    if (namespaceStrategy === 'flat') {
+      Object.assign(result.public, publicSection);
+      Object.assign(result, privateSection);
+      continue;
+    }
+
+    if (Object.keys(publicSection).length) {
+      result.public[fragment.scopeId] = {
+        ...(result.public[fragment.scopeId] ?? {}),
+        ...publicSection,
+      };
+    }
+
+    if (Object.keys(privateSection).length) {
+      result[fragment.scopeId] = {
+        ...(result[fragment.scopeId] ?? {}),
+        ...privateSection,
+      };
+    }
+  }
+
+  return result;
+}

package/src/resolve.ts

@@ -0,0 +1,51 @@
+import { createRuntimeConfigKey, type RuntimeConfigKeyOptions } from './key';
+import type { ConfigVisibility, RuntimeConfigSection } from './types';
+
+export type ResolveRuntimeConfigValueOptions<T = unknown> = RuntimeConfigKeyOptions & {
+  contextId?: string;
+  contextOutputKey?: string;
+  defaultValue?: T;
+};
+
+export type ResolveRuntimeConfigValueFromRuntimeConfigOptions<T = unknown> =
+  ResolveRuntimeConfigValueOptions<T> & {
+    visibility?: ConfigVisibility;
+  };
+
+export function resolveRuntimeConfigValue<T = unknown>(
+  scopeConfig: RuntimeConfigSection | undefined,
+  scopeId: string,
+  key: string,
+  options: ResolveRuntimeConfigValueOptions<T> = {},
+): T | undefined {
+  const configKey = createRuntimeConfigKey(scopeId, key, options);
+  const contextOutputKey = options.contextOutputKey ?? '__contexts';
+
+  if (options.contextId) {
+    const contexts = scopeConfig?.[contextOutputKey] as
+      | Record<string, RuntimeConfigSection>
+      | undefined;
+    const contextValue = contexts?.[options.contextId]?.[configKey] as T | undefined;
+    if (contextValue !== undefined) {
+      return contextValue;
+    }
+  }
+
+  const globalValue = scopeConfig?.[configKey] as T | undefined;
+  if (globalValue !== undefined) {
+    return globalValue;
+  }
+
+  return options.defaultValue;
+}
+
+export function resolveRuntimeConfigValueFromRuntimeConfig<T = unknown>(
+  runtimeConfig: Partial<Record<ConfigVisibility, RuntimeConfigSection | undefined>>,
+  scopeId: string,
+  key: string,
+  options: ResolveRuntimeConfigValueFromRuntimeConfigOptions<T> = {},
+): T | undefined {
+  const { visibility = 'public', ...resolveOptions } = options;
+
+  return resolveRuntimeConfigValue(runtimeConfig[visibility], scopeId, key, resolveOptions);
+}

package/src/scope.ts

@@ -0,0 +1,129 @@
+import { stripRuntimeConfigScopePrefix, type RuntimeConfigKeyOptions } from './key';
+import { resolveRuntimeConfigValue } from './resolve';
+import type { ConfigVisibility, RuntimeConfigContext, RuntimeConfigSection } from './types';
+
+export type GetRuntimeConfigScopeOptions = RuntimeConfigKeyOptions & {
+  contextId?: string;
+  contextOutputKey?: string;
+  keys?: string[];
+  visibility?: ConfigVisibility;
+};
+
+export type GetRuntimeConfigFragmentOptions = RuntimeConfigKeyOptions & {
+  contextId?: string;
+  contextOutputKey?: string;
+  keys?: Partial<Record<ConfigVisibility, string[]>>;
+};
+
+function assignDefined(target: RuntimeConfigSection, key: string, value: unknown): void {
+  if (value !== undefined) {
+    target[key] = value;
+  }
+}
+
+function collectRuntimeConfigScopeValues(input: {
+  scopeConfig: RuntimeConfigSection | undefined;
+  scopeId: string;
+  options: RuntimeConfigKeyOptions;
+}): RuntimeConfigSection {
+  const values: RuntimeConfigSection = {};
+
+  for (const [configKey, value] of Object.entries(input.scopeConfig ?? {})) {
+    if (configKey.startsWith('__')) continue;
+
+    const key = stripRuntimeConfigScopePrefix(input.scopeId, configKey, input.options);
+    if (key) assignDefined(values, key, value);
+  }
+
+  return values;
+}
+
+export function getRuntimeConfigScope<T extends RuntimeConfigSection = RuntimeConfigSection>(
+  runtimeConfig: Partial<Record<ConfigVisibility, RuntimeConfigSection | undefined>>,
+  scopeId: string,
+  options: GetRuntimeConfigScopeOptions = {},
+): T {
+  const {
+    contextId,
+    contextOutputKey = '__contexts',
+    keys,
+    visibility = 'public',
+    ...keyOptions
+  } = options;
+  const scopeConfig = runtimeConfig[visibility];
+
+  if (keys) {
+    return Object.fromEntries(
+      keys
+        .map((key) => {
+          const value = resolveRuntimeConfigValue(scopeConfig, scopeId, key, {
+            ...keyOptions,
+            ...(contextId ? { contextId } : {}),
+            contextOutputKey,
+          });
+
+          return [key, value] as const;
+        })
+        .filter(([, value]) => value !== undefined),
+    ) as T;
+  }
+
+  const values = collectRuntimeConfigScopeValues({
+    scopeConfig,
+    scopeId,
+    options: keyOptions,
+  });
+
+  if (!contextId) return values as T;
+
+  const contexts = scopeConfig?.[contextOutputKey] as
+    | Record<string, RuntimeConfigSection>
+    | undefined;
+  const contextValues = collectRuntimeConfigScopeValues({
+    scopeConfig: contexts?.[contextId],
+    scopeId,
+    options: keyOptions,
+  });
+
+  return {
+    ...values,
+    ...contextValues,
+  } as T;
+}
+
+export function getPublicRuntimeConfigScope<T extends RuntimeConfigSection = RuntimeConfigSection>(
+  runtimeConfig: Partial<Record<ConfigVisibility, RuntimeConfigSection | undefined>>,
+  scopeId: string,
+  options: Omit<GetRuntimeConfigScopeOptions, 'visibility'> = {},
+): T {
+  return getRuntimeConfigScope<T>(runtimeConfig, scopeId, {
+    ...options,
+    visibility: 'public',
+  });
+}
+
+export function getPrivateRuntimeConfigScope<T extends RuntimeConfigSection = RuntimeConfigSection>(
+  runtimeConfig: Partial<Record<ConfigVisibility, RuntimeConfigSection | undefined>>,
+  scopeId: string,
+  options: Omit<GetRuntimeConfigScopeOptions, 'visibility'> = {},
+): T {
+  return getRuntimeConfigScope<T>(runtimeConfig, scopeId, {
+    ...options,
+    visibility: 'private',
+  });
+}
+
+export function getRuntimeConfigFragment(
+  runtimeConfig: Partial<Record<ConfigVisibility, RuntimeConfigSection | undefined>>,
+  scopeId: string,
+  options: GetRuntimeConfigFragmentOptions = {},
+): RuntimeConfigContext {
+  const { keys, ...scopeOptions } = options;
+  const publicOptions = keys?.public ? { ...scopeOptions, keys: keys.public } : scopeOptions;
+  const privateOptions = keys?.private ? { ...scopeOptions, keys: keys.private } : scopeOptions;
+
+  return {
+    public: getPublicRuntimeConfigScope(runtimeConfig, scopeId, publicOptions),
+    private: getPrivateRuntimeConfigScope(runtimeConfig, scopeId, privateOptions),
+  };
+}

package/src/types.ts

@@ -0,0 +1,34 @@
+export type ConfigVisibility = 'public' | 'private';
+
+export type RuntimeConfigSection = Record<string, unknown>;
+
+export type RuntimeConfigContext = {
+  public?: RuntimeConfigSection;
+  private?: RuntimeConfigSection;
+};
+
+export type RuntimeConfigFragment = RuntimeConfigContext & {
+  contexts?: Record<string, RuntimeConfigContext>;
+};
+
+export type RuntimeConfigFragmentInput = RuntimeConfigFragment & Record<string, unknown>;
+
+export type NamedRuntimeConfigFragment = {
+  scopeId: string;
+  config: RuntimeConfigFragmentInput;
+};
+
+export type RuntimeConfigFragmentMap = Map<string, RuntimeConfigFragment>;
+
+export type SectionedRuntimeConfig = {
+  public: RuntimeConfigSection;
+  private: RuntimeConfigSection;
+};
+
+export type RuntimeConfigNamespaceProjection = RuntimeConfigSection & {
+  public: RuntimeConfigSection;
+};
+
+export type RuntimeEnvVars = Record<string, unknown>;
+
+export const runtimeConfigVisibilities: ConfigVisibility[] = ['public', 'private'];

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);
+}