@next-box/appsettings 0.0.0-stage → 0.0.2

package/src/config/AppSettingsImplementation.ts

@@ -0,0 +1,61 @@
+import { isPlainObject } from 'remeda';
+import { type Get } from 'type-fest';
+import { ScopedSettingsImplementation } from '#config/ScopedSettingsImplementation.ts';
+import { type InternalAppSettings, type ScopedSettings } from '#types/AppSettings.types.ts';
+import { type SettingPath, type SettingSectionPath } from '#types/Config.types.ts';
+import { ConfigReader } from './ConfigReader.ts';
+import { ConfigStore } from './ConfigStore.ts';
+
+export class AppSettingsImplementation<T extends object> implements InternalAppSettings<T> {
+  private readonly store: ConfigStore<T>;
+
+  constructor(settings: T) {
+    this.store = new ConfigStore(settings);
+  }
+
+  get<P extends SettingPath<T>>(path: P): Get<T, P> | undefined;
+  get(path: string): unknown {
+    return this.read(path);
+  }
+
+  read(path: string): unknown {
+    return new ConfigReader(this.store.getSnapshot()).read(path);
+  }
+
+  getAll(): Readonly<T> {
+    return this.store.getSnapshot();
+  }
+
+  getOrThrow<P extends SettingPath<T>>(path: P): Get<T, P>;
+  getOrThrow(path: string): unknown {
+    const value = new ConfigReader(this.store.getSnapshot()).read(path);
+
+    if (value === undefined) {
+      throw new Error(`Required app setting "${path}" is missing.`);
+    }
+
+    return value;
+  }
+
+  getSection<P extends SettingSectionPath<T>>(path: P): Get<T, P> | undefined;
+  getSection(path: string): unknown {
+    return new ConfigReader(this.store.getSnapshot()).read(path);
+  }
+
+  has(path: SettingPath<T> | SettingSectionPath<T>): boolean;
+  has(path: string): boolean {
+    return new ConfigReader(this.store.getSnapshot()).has(path);
+  }
+
+  scope<P extends SettingSectionPath<T>>(path: P): ScopedSettings<Extract<Get<T, P>, object>>;
+  scope(path: string): ScopedSettings<object> {
+    const reader = new ConfigReader(this.store.getSnapshot());
+    const section = reader.read(path);
+
+    if (!isPlainObject(section)) {
+      throw new Error(`App setting section "${path}" is missing.`);
+    }
+
+    return new ScopedSettingsImplementation(section, path);
+  }
+}

package/src/config/ConfigMerger.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from '@jest/globals';
+import { ConfigMerger } from './ConfigMerger.ts';
+
+describe('ConfigMerger', () => {
+  it('When configuration layers contain nested objects, then later values override recursively', () => {
+    // Arrange
+    const defaults = { Api: { BaseUrl: 'https://default.example.com', Timeout: 1000 }, Enabled: true };
+    const overrides = { Api: { Timeout: 5000 } };
+    const merger = new ConfigMerger();
+
+    // Act
+    const result = merger.merge(defaults, overrides);
+
+    // Assert
+    expect(result).toEqual({ Api: { BaseUrl: 'https://default.example.com', Timeout: 5000 }, Enabled: true });
+  });
+
+  it('When later layers contain arrays, then they replace earlier arrays without mutating inputs', () => {
+    // Arrange
+    const defaults = { Api: { Timeout: 1000 }, Values: [1, 2] };
+    const overrides = { Values: [3] };
+    const merger = new ConfigMerger();
+
+    // Act
+    const result = merger.merge(defaults, overrides);
+
+    // Assert
+    expect(result).toEqual({ Api: { Timeout: 1000 }, Values: [3] });
+    expect(defaults).toEqual({ Api: { Timeout: 1000 }, Values: [1, 2] });
+    expect(overrides).toEqual({ Values: [3] });
+  });
+
+  it('When there are no override layers, then it returns the first layer', () => {
+    // Arrange
+    const defaults = { Enabled: true };
+    const merger = new ConfigMerger();
+
+    // Act
+    const result = merger.merge(defaults);
+
+    // Assert
+    expect(result).toBe(defaults);
+  });
+});

package/src/config/ConfigMerger.ts

@@ -0,0 +1,9 @@
+import { mergeDeep } from 'remeda';
+
+export class ConfigMerger {
+  merge<T extends object>(first: T, ...configs: readonly T[]): T {
+    // TypeScript cannot guarantee that merging arbitrary objects produces T
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    return configs.reduce((merged, config) => mergeDeep(merged, config) as T, first);
+  }
+}

package/src/config/ConfigReader.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from '@jest/globals';
+import { ConfigReader } from './ConfigReader.ts';
+
+describe('ConfigReader', () => {
+  it('When a dotted path points to a leaf, then it returns that value', () => {
+    // Arrange
+    const reader = new ConfigReader({ Api: { Timeout: 5000 } });
+
+    // Act
+    const result = reader.read('Api.Timeout');
+
+    // Assert
+    expect(result).toBe(5000);
+  });
+
+  it('When a path is missing or traverses a primitive, then it returns undefined and reports no match', () => {
+    // Arrange
+    const reader = new ConfigReader({ Api: { Timeout: 5000 }, Name: 'App' });
+
+    // Act
+    const missing = reader.read('Api.Retry.Count');
+    const throughPrimitive = reader.read('Name.Length');
+
+    // Assert
+    expect(missing).toBeUndefined();
+    expect(throughPrimitive).toBeUndefined();
+    expect(reader.has('Api.Missing')).toBe(false);
+  });
+
+  it('When a path points to a defined value or section, then it reads and reports it', () => {
+    // Arrange
+    const reader = new ConfigReader({ Api: { Timeout: 5000 }, Empty: undefined });
+
+    // Act
+    const section = reader.getSection('Api');
+    const leaf = reader.get('Api.Timeout');
+
+    // Assert
+    expect(section).toEqual({ Timeout: 5000 });
+    expect(leaf).toBe(5000);
+    expect(reader.has('Api')).toBe(true);
+    expect(reader.has('Empty')).toBe(false);
+  });
+
+  it('When a section is scoped, then the returned reader reads paths relative to that section', () => {
+    // Arrange
+    const reader = new ConfigReader({ Api: { Timeout: 5000 } });
+    const scopedReader = reader.scope('Api');
+
+    // Act
+    const result = scopedReader.read('Timeout');
+
+    // Assert
+    expect(result).toBe(5000);
+  });
+});

package/src/config/ConfigReader.ts

@@ -0,0 +1,45 @@
+import { isPlainObject } from 'remeda';
+import { type Get } from 'type-fest';
+import { type Path, type Scope, type ConfigReader as ZcbConfigReader, createConfigReader } from 'zcb';
+
+export class ConfigReader<T extends object> {
+  private reader: ZcbConfigReader<T>;
+  private readonly config: T;
+
+  constructor(config: T) {
+    this.config = config;
+    this.reader = createConfigReader(config);
+  }
+
+  private getAt(path: string): unknown {
+    return path.split('.').reduce<unknown>((current, key) => {
+      if (!isPlainObject(current)) {
+        return;
+      }
+
+      return current[key];
+    }, this.config);
+  }
+
+  public get<P extends Path<T>>(path: P): Get<T, P> {
+    return this.reader.read(path);
+  }
+
+  public getSection<P extends Scope<T>>(path: P): Get<T, P> {
+    // Required as underlying getAt needs to be kept permissive
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    return this.getAt(path) as Get<T, P>;
+  }
+
+  public has(path: string): boolean {
+    return this.getAt(path) !== undefined;
+  }
+
+  public read(path: string): unknown {
+    return this.getAt(path);
+  }
+
+  public scope<P extends Scope<T>>(path: P): ZcbConfigReader<Get<T, P>> {
+    return this.reader.scope(path);
+  }
+}

package/src/config/ConfigStore.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from '@jest/globals';
+import { ConfigStore } from './ConfigStore.ts';
+
+describe('ConfigStore', () => {
+  it('When initialized, then it keeps a stable frozen snapshot detached from the input', () => {
+    // Arrange
+    const initial = { Api: { Timeout: 5000 } };
+    const store = new ConfigStore(initial);
+
+    // Act
+    const snapshot = store.getSnapshot();
+    initial.Api.Timeout = 100;
+
+    // Assert
+    expect(snapshot).toEqual({ Api: { Timeout: 5000 } });
+    expect(store.getSnapshot()).toBe(snapshot);
+    expect(Object.isFrozen(snapshot)).toBe(true);
+    expect(Object.isFrozen(snapshot.Api)).toBe(true);
+  });
+
+  it('When initialized with arrays, then the snapshot array and its entries are frozen', () => {
+    // Arrange
+    const store = new ConfigStore({ Servers: [{ Host: 'api.example.com' }] });
+
+    // Act
+    const snapshot = store.getSnapshot();
+
+    // Assert
+    expect(Object.isFrozen(snapshot.Servers)).toBe(true);
+    expect(Object.isFrozen(snapshot.Servers[0])).toBe(true);
+  });
+});

package/src/config/ConfigStore.ts

@@ -0,0 +1,12 @@
+import { clone } from 'remeda';
+import { freezeDeep } from '#config/helpers/freezeDeep.ts';
+
+export class ConfigStore<T extends object> {
+  private snapshot: Readonly<T>;
+
+  public getSnapshot = (): Readonly<T> => this.snapshot;
+
+  constructor(initial: T) {
+    this.snapshot = freezeDeep(clone(initial));
+  }
+}

package/src/config/ConfigValidator.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from '@jest/globals';
+import { z } from 'zod';
+import { ConfigValidator } from './ConfigValidator.ts';
+
+describe('ConfigValidator', () => {
+  it('When a value matches the schema, then it returns the parsed value', () => {
+    // Arrange
+    const schema = z.object({ Api: z.object({ Timeout: z.number() }) });
+    const validator = new ConfigValidator(schema);
+    const value = { Api: { Timeout: 5000 } };
+
+    // Act
+    const result = validator.validate(value);
+
+    // Assert
+    expect(result).toEqual(value);
+  });
+
+  it('When a value does not match the schema, then it throws the schema validation error', () => {
+    // Arrange
+    const schema = z.object({ Api: z.object({ Timeout: z.number() }) });
+    const validator = new ConfigValidator(schema);
+
+    // Act
+    const validateInvalidValue = () => validator.validate({ Api: { Timeout: 'slow' } });
+
+    // Assert
+    expect(validateInvalidValue).toThrow();
+  });
+});

package/src/config/ConfigValidator.ts

@@ -0,0 +1,13 @@
+import { type ZodType, type output } from 'zod';
+
+export class ConfigValidator<T extends ZodType> {
+  private readonly schema: T;
+
+  constructor(schema: T) {
+    this.schema = schema;
+  }
+
+  validate(value: unknown): output<T> {
+    return this.schema.parse(value);
+  }
+}

package/src/config/ScopedSettingsImplementation.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from '@jest/globals';
+import { ScopedSettingsImplementation } from './ScopedSettingsImplementation.ts';
+
+describe('ScopedSettingsImplementation', () => {
+  it('When a path exists within the scope, then it returns the value and scoped data', () => {
+    // Arrange
+    const section = { Api: { Timeout: 5000 }, Name: 'App', Retry: undefined };
+    const settings = new ScopedSettingsImplementation(section, 'Platform.Api');
+
+    // Act
+    const value = settings.get('Api.Timeout');
+    const all = settings.getAll();
+
+    // Assert
+    expect(value).toBe(5000);
+    expect(all).toBe(section);
+  });
+
+  it('When a required scoped value is missing, then it throws with the full path', () => {
+    // Arrange
+    const settings = new ScopedSettingsImplementation({ Retry: undefined }, 'Platform.Api');
+
+    // Act
+    const getMissingValue = () => {
+      settings.getOrThrow('Retry');
+    };
+
+    // Assert
+    expect(getMissingValue).toThrow('Required app setting "Platform.Api.Retry" is missing.');
+  });
+});

package/src/config/ScopedSettingsImplementation.ts

@@ -0,0 +1,36 @@
+import { type Get } from 'type-fest';
+import { ConfigReader } from '#config/ConfigReader.ts';
+import { type ScopedSettings } from '#types/AppSettings.types.ts';
+import { type SettingPath } from '#types/Config.types.ts';
+
+export class ScopedSettingsImplementation<T extends object> implements ScopedSettings<T> {
+  private readonly reader: ConfigReader<T>;
+  private readonly section: T;
+  private readonly parentPath: string;
+
+  constructor(section: T, parentPath: string) {
+    this.section = section;
+    this.parentPath = parentPath;
+    this.reader = new ConfigReader(section);
+  }
+
+  get<P extends SettingPath<T>>(path: P): Get<T, P> | undefined;
+  get(path: string): unknown {
+    return this.reader.read(path);
+  }
+
+  getAll(): Readonly<T> {
+    return this.section;
+  }
+
+  getOrThrow<P extends SettingPath<T>>(path: P): Get<T, P>;
+  getOrThrow(path: string): unknown {
+    const value = this.reader.read(path);
+
+    if (value === undefined) {
+      throw new Error(`Required app setting "${this.parentPath}.${path}" is missing.`);
+    }
+
+    return value;
+  }
+}

package/src/config/createAppSettings.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it, jest } from '@jest/globals';
+import { z } from 'zod';
+import { type SettingsSource } from '#types/Source.types.ts';
+import { createAppSettings } from './createAppSettings.ts';
+
+describe('createAppSettings', () => {
+  it('When sources are provided, then it loads them in order, merges them, and validates the result', async () => {
+    // Arrange
+    const schema = z.object({ Api: z.object({ BaseUrl: z.string(), Timeout: z.number() }) });
+    const defaults = { Api: { BaseUrl: 'https://default.example.com', Timeout: 1000 } };
+    const firstLoad = jest.fn(() => Promise.resolve({ Api: { Timeout: 3000 } }));
+    const secondLoad = jest.fn(() => Promise.resolve({ Api: { BaseUrl: 'https://api.example.com' } }));
+    const firstSource: SettingsSource = { load: firstLoad, name: 'first' };
+    const secondSource: SettingsSource = { load: secondLoad, name: 'second' };
+
+    // Act
+    const result = await createAppSettings({ defaults, schema, sources: [firstSource, secondSource] });
+
+    // Assert
+    expect(firstLoad).toHaveBeenCalledTimes(1);
+    expect(secondLoad).toHaveBeenCalledTimes(1);
+    expect(result).toEqual({ Api: { BaseUrl: 'https://api.example.com', Timeout: 3000 } });
+  });
+
+  it('When no sources are provided, then it validates the defaults', async () => {
+    // Arrange
+    const defaults = { Api: { Timeout: 1000 } };
+    const schema = z.object({ Api: z.object({ Timeout: z.number() }) });
+
+    // Act
+    const result = await createAppSettings({ defaults, schema });
+
+    // Assert
+    expect(result).toEqual(defaults);
+  });
+
+  it('When a source rejects, then it rejects without continuing to later sources', async () => {
+    // Arrange
+    const error = new Error('Source failed');
+
+    const firstLoad = jest.fn(() => {
+      throw error;
+    });
+
+    // @ts-expect-error Fine for test
+    const secondLoad: jest.Mock<() => never> = jest.fn(() => ({}));
+
+    const sources: SettingsSource[] = [
+      { load: firstLoad, name: 'first' },
+      { load: secondLoad, name: 'second' },
+    ];
+
+    const options = { defaults: {}, schema: z.object({}), sources };
+
+    // Act
+    const result = createAppSettings(options);
+
+    // Assert
+    await expect(result).rejects.toBe(error);
+    expect(secondLoad).not.toHaveBeenCalled();
+  });
+
+  it('When the merged settings fail validation, then it rejects with a schema error', async () => {
+    // Arrange
+    const defaults = { Api: { Timeout: 1000 } };
+
+    const invalidSource: SettingsSource = {
+      load: () => Promise.resolve({ Api: { Timeout: 'slow' } }),
+      name: 'invalid',
+    };
+
+    const options = {
+      defaults,
+      schema: z.object({ Api: z.object({ Timeout: z.number() }) }),
+      sources: [invalidSource],
+    };
+
+    // Act
+    const result = createAppSettings(options);
+
+    // Assert
+    await expect(result).rejects.toThrow();
+  });
+});

package/src/config/createAppSettings.ts

@@ -0,0 +1,18 @@
+import { type CreateAppSettingsOptions } from '#types/AppSettings.types.ts';
+import { ConfigMerger } from './ConfigMerger.ts';
+import { ConfigValidator } from './ConfigValidator.ts';
+
+export const createAppSettings = async <T extends object>({
+  defaults,
+  schema,
+  sources = [],
+}: CreateAppSettingsOptions<T>): Promise<Readonly<T>> => {
+  const loadedSources: Record<string, unknown>[] = [];
+
+  for (const source of sources) {
+    loadedSources.push(await source.load());
+  }
+
+  const merged = new ConfigMerger().merge(defaults, ...loadedSources);
+  return new ConfigValidator(schema).validate(merged);
+};

package/src/config/helpers/freezeDeep.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from '@jest/globals';
+import { freezeDeep } from './freezeDeep.ts';
+
+describe('freezeDeep', () => {
+  it('When given nested plain objects, then it freezes each object and returns the original value', () => {
+    // Arrange
+    const value = { Api: { Retry: { Count: 3 } } };
+
+    // Act
+    const result = freezeDeep(value);
+
+    // Assert
+    expect(result).toBe(value);
+    expect(Object.isFrozen(value)).toBe(true);
+    expect(Object.isFrozen(value.Api)).toBe(true);
+    expect(Object.isFrozen(value.Api.Retry)).toBe(true);
+  });
+
+  it('When given arrays containing objects, then it freezes the array and its nested objects', () => {
+    // Arrange
+    const value = { Servers: [{ Host: 'api.example.com' }] };
+
+    // Act
+    freezeDeep(value);
+
+    // Assert
+    expect(Object.isFrozen(value.Servers)).toBe(true);
+    expect(Object.isFrozen(value.Servers[0])).toBe(true);
+  });
+
+  it('When given a primitive, then it returns the value unchanged', () => {
+    // Arrange
+    const value = 'setting';
+
+    // Act
+    const result = freezeDeep(value);
+
+    // Assert
+    expect(result).toBe(value);
+  });
+});

package/src/config/helpers/freezeDeep.ts

@@ -0,0 +1,15 @@
+import { isPlainObject } from 'remeda';
+
+export const freezeDeep = <T>(value: T): T => {
+  if ((isPlainObject(value) || Array.isArray(value)) && !Object.isFrozen(value)) {
+    const values: unknown[] = Object.values(value);
+
+    for (const entry of values) {
+      freezeDeep(entry);
+    }
+
+    Object.freeze(value);
+  }
+
+  return value;
+};

package/src/hooks/useAppSetting.test.tsx

@@ -0,0 +1,37 @@
+/** @jest-environment @repodog/jest-config/FailOnJsdomConsoleEnvironment.mjs */
+
+import { describe, expect, it } from '@jest/globals';
+import { renderHook } from '@testing-library/react';
+import { type ReactNode } from 'react';
+import { AppSettingsProvider } from '../components/AppSettingsProvider.tsx';
+import { useAppSetting } from './useAppSetting.ts';
+
+const settings = { Api: { Missing: undefined, Timeout: 5000 } };
+
+const createWrapper = ({ children }: { children: ReactNode }) => (
+  <AppSettingsProvider settings={settings}>{children}</AppSettingsProvider>
+);
+
+describe('useAppSetting', () => {
+  it('When used within a provider, then it returns the value at the requested leaf path', () => {
+    // Arrange
+    const path = 'Api.Timeout';
+
+    // Act
+    const { result } = renderHook(() => useAppSetting(path), { wrapper: createWrapper });
+
+    // Assert
+    expect(result.current).toBe(5000);
+  });
+
+  it('When the requested path is missing, then it returns undefined', () => {
+    // Arrange
+    const path = 'Api.Missing';
+
+    // Act
+    const { result } = renderHook(() => useAppSetting(path), { wrapper: createWrapper });
+
+    // Assert
+    expect(result.current).toBeUndefined();
+  });
+});

package/src/hooks/useAppSetting.ts

@@ -0,0 +1,14 @@
+import { type Get } from 'type-fest';
+import { type AppSettingsSchema } from '../index.ts';
+import { type SettingPath } from '../types/Config.types.ts';
+import { useAppSettingsContext } from './useAppSettingsContext.ts';
+
+export function useAppSetting<P extends SettingPath<AppSettingsSchema>>(path: P): Get<AppSettingsSchema, P> | undefined;
+export function useAppSetting<T extends object, P extends SettingPath<T>>(path: P): Get<T, P> | undefined;
+
+// Required for overloads
+// eslint-disable-next-line prefer-arrow/prefer-arrow-functions
+export function useAppSetting(path: string): unknown {
+  const settings = useAppSettingsContext();
+  return settings.read(path);
+}

package/src/hooks/useAppSettings.test.tsx

@@ -0,0 +1,37 @@
+/** @jest-environment @repodog/jest-config/FailOnJsdomConsoleEnvironment.mjs */
+
+import { describe, expect, it } from '@jest/globals';
+import { renderHook } from '@testing-library/react';
+import { type ReactNode } from 'react';
+import { AppSettingsProvider } from '../components/AppSettingsProvider.tsx';
+import { useAppSettings } from './useAppSettings.ts';
+
+const settings = { Api: { Timeout: 5000 } };
+
+const createWrapper = ({ children }: { children: ReactNode }) => (
+  <AppSettingsProvider settings={settings}>{children}</AppSettingsProvider>
+);
+
+describe('useAppSettings', () => {
+  it('When used within a provider, then it returns the requested object section', () => {
+    // Arrange
+    const path = 'Api';
+
+    // Act
+    const { result } = renderHook(() => useAppSettings(path), { wrapper: createWrapper });
+
+    // Assert
+    expect(result.current).toEqual({ Timeout: 5000 });
+  });
+
+  it('When the requested section is missing, then it returns undefined', () => {
+    // Arrange
+    const path = 'Missing';
+
+    // Act
+    const { result } = renderHook(() => useAppSettings(path), { wrapper: createWrapper });
+
+    // Assert
+    expect(result.current).toBeUndefined();
+  });
+});

package/src/hooks/useAppSettings.ts

@@ -0,0 +1,17 @@
+import { type Get } from 'type-fest';
+import { type SettingSectionPath } from '#types/Config.types.ts';
+import { type AppSettingsSchema } from '../index.ts';
+import { useAppSettingsContext } from './useAppSettingsContext.ts';
+
+export function useAppSettings<P extends SettingSectionPath<AppSettingsSchema>>(
+  path: P,
+): Get<AppSettingsSchema, P> | undefined;
+
+export function useAppSettings<T extends object, P extends SettingSectionPath<T>>(path: P): Get<T, P> | undefined;
+
+// Required for overloads
+// eslint-disable-next-line prefer-arrow/prefer-arrow-functions
+export function useAppSettings(path: string): unknown {
+  const settings = useAppSettingsContext();
+  return settings.read(path);
+}