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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorion-org/runtime-config",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.5",
   "description": "Framework-free runtime-config types and merge helpers.",
   "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"
@@ -34,8 +38,9 @@
   },
   "files": [
     "dist",
-    "examples",
-    "LICENSE"
+    "LICENSE",
+    "src/**/*.ts",
+    "!src/**/*.spec.ts"
   ],
   "keywords": [
     "runtime-config",
@@ -46,6 +51,9 @@
   "engines": {
     "node": "^20.19.0 || >=22.12.0"
   },
+  "dependencies": {
+    "ajv": "^8.17.1"
+  },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts",
     "clean": "rimraf coverage dist tsconfig.tsbuildinfo",

package/src/env.ts

@@ -0,0 +1,91 @@
+import { toSnakeUpperCase } from './key';
+import {
+  projectSectionedRuntimeConfig,
+  type ProjectSectionedRuntimeConfigOptions,
+} from './project';
+import {
+  runtimeConfigVisibilities,
+  type ConfigVisibility,
+  type NamedRuntimeConfigFragment,
+  type RuntimeConfigFragmentMap,
+  type RuntimeEnvVars,
+  type SectionedRuntimeConfig,
+} from './types';
+
+export type ProjectRuntimeConfigEnvVarsOptions = ProjectSectionedRuntimeConfigOptions & {
+  prefix?: string;
+};
+
+export function createRuntimeConfigEnvKey(input: {
+  key: string;
+  prefix?: string;
+  scopeId?: string;
+  visibility?: ConfigVisibility;
+}): string {
+  return toSnakeUpperCase(
+    [input.prefix ?? 'APP', input.visibility, input.scopeId, input.key].filter(Boolean).join('_'),
+  );
+}
+
+export function toRuntimeEnvVars(
+  runtimeConfig: SectionedRuntimeConfig,
+  prefix = 'APP',
+): RuntimeEnvVars {
+  const envVars: RuntimeEnvVars = {};
+
+  for (const visibility of runtimeConfigVisibilities) {
+    for (const [key, value] of Object.entries(runtimeConfig[visibility])) {
+      if (key.startsWith('__')) continue;
+
+      envVars[createRuntimeConfigEnvKey({ prefix, visibility, key })] = value;
+    }
+  }
+
+  return envVars;
+}
+
+export function projectRuntimeConfigEnvVars(
+  fragments: Iterable<NamedRuntimeConfigFragment> | RuntimeConfigFragmentMap,
+  options: ProjectRuntimeConfigEnvVarsOptions = {},
+): RuntimeEnvVars {
+  const { prefix = 'APP', ...projectOptions } = options;
+
+  return toRuntimeEnvVars(
+    projectSectionedRuntimeConfig(fragments, {
+      ...projectOptions,
+      includeContexts: false,
+    }),
+    prefix,
+  );
+}
+
+export function injectRuntimeEnvVars(
+  envVars: RuntimeEnvVars,
+  processEnv: Record<string, unknown>,
+): RuntimeEnvVars {
+  const items: RuntimeEnvVars = {};
+
+  for (const key of Object.keys(envVars)) {
+    items[key] = processEnv[key] ?? envVars[key];
+  }
+
+  return items;
+}
+
+export function runtimeEnvVarsToString(envVars: RuntimeEnvVars): string {
+  return Object.entries(envVars)
+    .map(([key, value]) => `${key}=${String(value)}`)
+    .join('\n');
+}
+
+export function runtimeEnvValueToShellLiteral(value: unknown): string {
+  const json = JSON.stringify(value) ?? 'undefined';
+
+  return `'${json.replace(/'/g, "'\\''")}'`;
+}
+
+export function runtimeEnvVarsToShellAssignments(envVars: RuntimeEnvVars): string {
+  return Object.entries(envVars)
+    .map(([key, value]) => `${key}=${runtimeEnvValueToShellLiteral(value)}`)
+    .join('\n');
+}

package/src/fragment.ts

@@ -0,0 +1,28 @@
+import type {
+  RuntimeConfigContext,
+  RuntimeConfigFragment,
+  RuntimeConfigFragmentInput,
+} from './types';
+
+export type NormalizeRuntimeConfigFragmentOptions = {
+  contextInputKey?: string;
+};
+
+const isObject = (value: unknown): value is Record<string, unknown> => {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+
+export function toRuntimeConfigFragment(
+  config: RuntimeConfigFragmentInput,
+  options: NormalizeRuntimeConfigFragmentOptions = {},
+): RuntimeConfigFragment {
+  const contextInputKey = options.contextInputKey ?? 'contexts';
+  const contexts =
+    contextInputKey === 'contexts' ? config.contexts : (config.contexts ?? config[contextInputKey]);
+
+  return {
+    ...(isObject(config.public) ? { public: config.public } : {}),
+    ...(isObject(config.private) ? { private: config.private } : {}),
+    ...(isObject(contexts) ? { contexts: contexts as Record<string, RuntimeConfigContext> } : {}),
+  };
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './env';
+export * from './fragment';
+export * from './key';
+export * from './project';
+export * from './resolve';
+export * from './scope';
+export * from './types';
+export * from './validation';

package/src/key.ts

@@ -0,0 +1,54 @@
+export type RuntimeConfigKeyStrategy = (scopeId: string, key: string) => string;
+
+export type RuntimeConfigKeyOptions = {
+  keyStrategy?: RuntimeConfigKeyStrategy;
+};
+
+function upperFirst(input: string): string {
+  return input ? input[0]!.toUpperCase() + input.slice(1) : input;
+}
+
+function uncapitalize(input: string): string {
+  return input ? input[0]!.toLowerCase() + input.slice(1) : input;
+}
+
+function camelCase(input: string): string {
+  return input
+    .replace(/['\u2019]/g, '')
+    .split(/[^A-Za-z0-9]+|(?=[A-Z][a-z])/)
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .map((part) => part.toLowerCase())
+    .map((part, index) => (index === 0 ? part : upperFirst(part)))
+    .join('');
+}
+
+export function createRuntimeConfigKey(
+  scopeId: string,
+  key: string,
+  options: RuntimeConfigKeyOptions = {},
+): string {
+  return options.keyStrategy?.(scopeId, key) ?? camelCase(`${scopeId} ${key}`);
+}
+
+export function stripRuntimeConfigScopePrefix(
+  scopeId: string,
+  configKey: string,
+  options: RuntimeConfigKeyOptions = {},
+): string | undefined {
+  const prefix = createRuntimeConfigKey(scopeId, '', options);
+  if (!prefix || !configKey.startsWith(prefix) || configKey.length <= prefix.length) {
+    return undefined;
+  }
+
+  return uncapitalize(configKey.slice(prefix.length));
+}
+
+export function toSnakeUpperCase(input: string): string {
+  return input
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/[^a-zA-Z0-9]+/g, '_')
+    .replace(/_+/g, '_')
+    .replace(/^_|_$/g, '')
+    .toUpperCase();
+}

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'];