@next-box/appsettings 0.0.0-stage → 0.0.2

package/src/hooks/useAppSettingsContext.test.tsx

@@ -0,0 +1,45 @@
+/** @jest-environment @repodog/jest-config/FailOnJsdomConsoleEnvironment.mjs */
+
+import { describe, expect, it } from '@jest/globals';
+import { render, renderHook, screen } from '@testing-library/react';
+import { type ReactNode } from 'react';
+import { ErrorBoundary } from '../__testUtils__/components/ErrorBoundary.tsx';
+import { AppSettingsProvider } from '../components/AppSettingsProvider.tsx';
+import { useAppSettingsContext } from './useAppSettingsContext.ts';
+
+describe('useAppSettingsContext', () => {
+  it('When used within a provider, then it returns the settings context instance', () => {
+    // Arrange
+    const settings = { Api: { Timeout: 5000 } };
+
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <AppSettingsProvider settings={settings}>{children}</AppSettingsProvider>
+    );
+
+    // Act
+    const { result } = renderHook(() => useAppSettingsContext(), { wrapper });
+
+    // Assert
+    expect(result.current.get('Api.Timeout')).toBe(5000);
+  });
+
+  it('When used outside a provider, then it throws a descriptive error', () => {
+    // Arrange
+    const ContextReader = () => {
+      useAppSettingsContext();
+      // Required for React typing
+      // eslint-disable-next-line unicorn/no-null
+      return null;
+    };
+
+    // Act
+    render(
+      <ErrorBoundary>
+        <ContextReader />
+      </ErrorBoundary>,
+    );
+
+    // Assert
+    expect(screen.getByText('useAppSettingsContext must be used within an <AppSettingsProvider>.')).toBeTruthy();
+  });
+});

package/src/hooks/useAppSettingsContext.ts

@@ -0,0 +1,17 @@
+import { createContext, use } from 'react';
+import { type InternalAppSettings } from '#types/AppSettings.types.ts';
+import { type AppSettingsSchema } from '../index.ts';
+
+export const AppSettingsContext = createContext<unknown>(undefined);
+
+export const useAppSettingsContext = <T extends object = AppSettingsSchema>(): InternalAppSettings<T> => {
+  const settings = use(AppSettingsContext);
+
+  if (!settings || typeof settings !== 'object') {
+    throw new Error('useAppSettingsContext must be used within an <AppSettingsProvider>.');
+  }
+
+  // Context is untyped because each provider supplies a different schema.
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  return settings as InternalAppSettings<T>;
+};

package/src/index.ts

@@ -0,0 +1,11 @@
+export { AppSettingsProvider } from '#components/AppSettingsProvider.tsx';
+export { Setting } from '#components/Setting.tsx';
+export { useAppSetting } from '#hooks/useAppSetting.ts';
+export { useAppSettings } from '#hooks/useAppSettings.ts';
+export type { AppSettings, ScopedSettings } from '#types/AppSettings.types.ts';
+export type { SettingPath, SettingSectionPath, SettingValue } from '#types/Config.types.ts';
+
+// Consumers can augment this interface through the package's public entry point.
+export interface AppSettingsSchema {
+  readonly __appSettingsSchema?: never;
+}

package/src/server.ts

@@ -0,0 +1,7 @@
+export { createAppSettings } from '#config/createAppSettings.ts';
+export { AppSettingsSource, type AppSettingsSourceOptions } from '#sources/AppSettingsSource.ts';
+export { EnvironmentSource, type EnvironmentSourceOptions } from '#sources/EnvironmentSource.ts';
+export { RemoteSource, type RemoteSourceOptions } from '#sources/RemoteSource.ts';
+export { MemorySource, type MemorySourceOptions } from '#sources/MemorySource.ts';
+export { type CreateAppSettingsOptions } from '#types/AppSettings.types.ts';
+export type { SettingsSource } from '#types/Source.types.ts';

package/src/sources/AppSettingsSource.test.ts

@@ -0,0 +1,61 @@
+/** @jest-environment node */
+
+import { afterEach, describe, expect, it } from '@jest/globals';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { AppSettingsSource } from './AppSettingsSource.ts';
+
+describe('AppSettingsSource', () => {
+  let directory: string | undefined;
+
+  afterEach(async () => {
+    if (!directory) {
+      return;
+    }
+
+    await rm(directory, { force: true, recursive: true });
+    directory = undefined;
+  });
+
+  it('When base and environment files exist, then the environment file overrides the base recursively', async () => {
+    // Arrange
+    directory = await mkdtemp(join(tmpdir(), 'appsettings-source-'));
+    await writeFile(join(directory, 'appsettings.json'), JSON.stringify({ Api: { Retry: 3, Timeout: 1000 } }));
+    await writeFile(join(directory, 'appsettings.test.json'), JSON.stringify({ Api: { Timeout: 5000 } }));
+    const source = new AppSettingsSource({ directory, environment: 'test' });
+
+    // Act
+    const result = await source.load();
+
+    // Assert
+    expect(result).toEqual({ Api: { Retry: 3, Timeout: 5000 } });
+    expect(source.name).toBe('appsettings:test');
+  });
+
+  it('When the environment file is absent, then it returns the base file', async () => {
+    // Arrange
+    directory = await mkdtemp(join(tmpdir(), 'appsettings-source-'));
+    await writeFile(join(directory, 'appsettings.json'), JSON.stringify({ App: { Name: 'Example' } }));
+    const source = new AppSettingsSource({ directory, environment: 'test', name: 'custom' });
+
+    // Act
+    const result = await source.load();
+
+    // Assert
+    expect(result).toEqual({ App: { Name: 'Example' } });
+    expect(source.name).toBe('custom');
+  });
+
+  it('When the base file is absent, then loading rejects', async () => {
+    // Arrange
+    directory = await mkdtemp(join(tmpdir(), 'appsettings-source-'));
+    const source = new AppSettingsSource({ directory, environment: 'test' });
+
+    // Act
+    const result = source.load();
+
+    // Assert
+    await expect(result).rejects.toMatchObject({ code: 'ENOENT' });
+  });
+});

package/src/sources/AppSettingsSource.ts

@@ -0,0 +1,30 @@
+import { resolve } from 'node:path';
+import { ConfigMerger } from '#config/ConfigMerger.ts';
+import { loadJson } from '#sources/helpers/loadJson.ts';
+import { type SettingsSource } from '../types/Source.types.ts';
+
+export interface AppSettingsSourceOptions {
+  directory?: string;
+  environment?: string;
+  name?: string;
+}
+
+export class AppSettingsSource implements SettingsSource {
+  private directory: string;
+  private environment: string;
+  public name: string;
+
+  public constructor(options: AppSettingsSourceOptions) {
+    this.directory = options.directory ?? process.cwd();
+    this.environment = options.environment ?? process.env.NODE_ENV ?? 'development';
+    this.name = options.name ?? `appsettings:${this.environment}`;
+  }
+
+  async load(): Promise<Record<string, unknown>> {
+    const basePath = resolve(this.directory, 'appsettings.json');
+    const environmentPath = resolve(this.directory, `appsettings.${this.environment}.json`);
+    const base = await loadJson(basePath, false);
+    const override = (await loadJson(environmentPath, true)) ?? {};
+    return new ConfigMerger().merge(base, override);
+  }
+}

package/src/sources/EnvironmentSource.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from '@jest/globals';
+import { EnvironmentSource } from './EnvironmentSource.ts';
+
+describe('EnvironmentSource', () => {
+  it('When matching variables are loaded, then it maps nested keys and parses booleans and numbers', async () => {
+    // Arrange
+    const source = new EnvironmentSource({
+      envs: {
+        APP_API__BASE_URL: 'https://api.example.com',
+        APP_API__TIMEOUT: '5000',
+        APP_FEATURES__DARK_MODE: 'true',
+        APP_FEATURES__NEW_DASHBOARD: 'false',
+        APP_UNSET: undefined,
+        OTHER_API__TIMEOUT: '1000',
+      },
+    });
+
+    // Act
+    const result = await source.load();
+
+    // Assert
+    expect(result).toEqual({
+      Api: { BaseUrl: 'https://api.example.com', Timeout: 5000 },
+      Features: { DarkMode: true, NewDashboard: false },
+    });
+
+    expect(source.name).toBe('environment:APP_');
+  });
+
+  it('When a custom prefix and name are provided, then it uses them and preserves non-numeric values', async () => {
+    // Arrange
+    const source = new EnvironmentSource({
+      envs: { SERVICE_MODE: 'Development', SERVICE_PORT: 'not-a-number' },
+      name: 'service-env',
+      prefix: 'SERVICE_',
+    });
+
+    // Act
+    const result = await source.load();
+
+    // Assert
+    expect(result).toEqual({ Mode: 'Development', Port: 'not-a-number' });
+    expect(source.name).toBe('service-env');
+  });
+});

package/src/sources/EnvironmentSource.ts

@@ -0,0 +1,87 @@
+import { capitalize, isPlainObject } from 'remeda';
+import { type SettingsSource } from '../types/Source.types.ts';
+
+export interface EnvironmentSourceOptions {
+  envs: Record<string, string | undefined>;
+  name?: string;
+  prefix?: string;
+}
+
+export class EnvironmentSource implements SettingsSource {
+  private readonly envs: Record<string, string | undefined>;
+  private readonly prefix: string;
+
+  private normalizeSegment = (value: string): string =>
+    value
+      .toLowerCase()
+      .split('_')
+      .filter(Boolean)
+      .map(part => capitalize(part))
+      .join('');
+
+  public readonly name: string;
+
+  public constructor(options: EnvironmentSourceOptions) {
+    this.envs = options.envs;
+    this.prefix = options.prefix ?? 'APP_';
+    this.name = options.name ?? `environment:${this.prefix}`;
+  }
+
+  private parseEnvironmentValue(value: string): unknown {
+    if (value === 'true') {
+      return true;
+    }
+
+    if (value === 'false') {
+      return false;
+    }
+
+    if (value.trim() !== '' && Number.isFinite(Number(value))) {
+      return Number(value);
+    }
+
+    return value;
+  }
+
+  load(): Promise<Record<string, unknown>> {
+    const result: Record<string, unknown> = {};
+
+    for (const [key, value] of Object.entries(this.envs)) {
+      if (value === undefined || !key.startsWith(this.prefix)) {
+        continue;
+      }
+
+      const path = key
+        .slice(this.prefix.length)
+        .split('__')
+        .filter(Boolean)
+        .map(part => this.normalizeSegment(part));
+
+      const leaf = path.pop();
+
+      if (!leaf) {
+        continue;
+      }
+
+      let current = result;
+
+      for (const part of path) {
+        const next = current[part];
+
+        if (!isPlainObject(next)) {
+          current[part] = {};
+        }
+
+        const currentPart = current[part];
+
+        if (isPlainObject(currentPart)) {
+          current = currentPart;
+        }
+      }
+
+      current[leaf] = this.parseEnvironmentValue(value);
+    }
+
+    return Promise.resolve(result);
+  }
+}

package/src/sources/MemorySource.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from '@jest/globals';
+import { MemorySource } from './MemorySource.ts';
+
+describe('MemorySource', () => {
+  it('When loaded, then it returns a copy of the supplied values', async () => {
+    // Arrange
+    const values = { Api: { Timeout: 5000 } };
+    const source = new MemorySource({ values });
+
+    // Act
+    const result = await source.load();
+    result.Additional = true;
+
+    // Assert
+    expect(result).not.toBe(values);
+    expect(result.Api).not.toBe(values.Api);
+    expect(values.Api.Timeout).toBe(5000);
+    expect(source.name).toBe('memory');
+  });
+
+  it('When a custom name is provided, then it exposes that name', () => {
+    // Arrange
+    const source = new MemorySource({ name: 'runtime-overrides', values: {} });
+
+    // Act
+    const name = source.name;
+
+    // Assert
+    expect(name).toBe('runtime-overrides');
+  });
+});

package/src/sources/MemorySource.ts

@@ -0,0 +1,21 @@
+import { clone } from 'remeda';
+import { type SettingsSource } from '../types/Source.types.ts';
+
+export interface MemorySourceOptions {
+  name?: string;
+  values: Record<string, unknown>;
+}
+
+export class MemorySource implements SettingsSource {
+  private readonly values: Record<string, unknown>;
+  public readonly name: string;
+
+  public constructor(options: MemorySourceOptions) {
+    this.name = options.name ?? 'memory';
+    this.values = options.values;
+  }
+
+  load(): Promise<Record<string, unknown>> {
+    return Promise.resolve(clone(this.values));
+  }
+}

package/src/sources/RemoteSource.test.ts

@@ -0,0 +1,80 @@
+/** @jest-environment node */
+
+import { describe, expect, it } from '@jest/globals';
+import { RemoteSource } from './RemoteSource.ts';
+
+describe('RemoteSource', () => {
+  it('When the response is successful, then it returns its JSON object', async () => {
+    // Arrange
+    const response = new Response(undefined, { status: 200 });
+    response.json = () => Promise.resolve({ Api: { Timeout: 5000 } });
+    const fetch = () => Promise.resolve(response);
+    const source = new RemoteSource({ fetch, url: 'https://config.example.com/settings.json' });
+
+    // Act
+    const result = await source.load();
+
+    // Assert
+    expect(result).toEqual({ Api: { Timeout: 5000 } });
+    expect(source.name).toBe('remote:https://config.example.com/settings.json');
+  });
+
+  it('When a response path is provided, then it returns the selected nested object', async () => {
+    // Arrange
+    const response = new Response();
+    response.json = () => Promise.resolve({ data: { settings: { Api: { Timeout: 5000 } } } });
+    const fetch = () => Promise.resolve(response);
+    const source = new RemoteSource({ fetch, responsePath: 'data.settings', url: 'https://config.example.com' });
+
+    // Act
+    const result = await source.load();
+
+    // Assert
+    expect(result).toEqual({ Api: { Timeout: 5000 } });
+  });
+
+  it('When the response is not successful, then it throws an error containing the response status', async () => {
+    // Arrange
+    const fetch = () => Promise.resolve(new Response('Unavailable', { status: 503, statusText: 'Unavailable' }));
+    const source = new RemoteSource({ fetch, url: 'https://config.example.com' });
+
+    // Act
+    const result = source.load();
+
+    // Assert
+    await expect(result).rejects.toThrow('503 Unavailable');
+  });
+
+  it('When the JSON root or selected response path is not an object, then it rejects', async () => {
+    // Arrange
+    const fetchArray = (): Promise<Response> => Promise.resolve(new Response('[]'));
+    const fetchMissingPath = (): Promise<Response> => Promise.resolve(new Response('{"data": {"settings": []}}'));
+    const rootSource = new RemoteSource({ fetch: fetchArray, url: 'https://config.example.com' });
+
+    const nestedSource = new RemoteSource({
+      fetch: fetchMissingPath,
+      responsePath: 'data.settings',
+      url: 'https://config.example.com',
+    });
+
+    // Act
+    const root = rootSource.load();
+    const nested = nestedSource.load();
+
+    // Assert
+    await expect(root).rejects.toThrow('must contain an object at the root');
+    await expect(nested).rejects.toThrow('must contain an object at the root');
+  });
+
+  it('When a response path is used on a primitive JSON value, then it rejects before selecting the path', async () => {
+    // Arrange
+    const fetch = () => Promise.resolve(new Response('42'));
+    const source = new RemoteSource({ fetch, responsePath: 'data', url: 'https://config.example.com' });
+
+    // Act
+    const result = source.load();
+
+    // Assert
+    await expect(result).rejects.toThrow('must be an object type if response path is provided');
+  });
+});

package/src/sources/RemoteSource.ts

@@ -0,0 +1,50 @@
+import { isObjectType, isPlainObject, prop, stringToPath } from 'remeda';
+import { type SettingsSource } from '#types/Source.types.ts';
+
+export interface RemoteSourceOptions {
+  fetch: typeof globalThis.fetch;
+  name?: string;
+  responsePath?: string;
+  url: string;
+}
+
+export class RemoteSource implements SettingsSource {
+  private fetch: typeof globalThis.fetch;
+  private responsePath?: string;
+  private url: string;
+  public name: string;
+
+  public constructor(options: RemoteSourceOptions) {
+    this.fetch = options.fetch;
+    this.url = options.url;
+    this.name = options.name ?? `remote:${this.url}`;
+    this.responsePath = options.responsePath;
+  }
+
+  async load(): Promise<Record<string, unknown>> {
+    if (typeof this.fetch !== 'function') {
+      throw new TypeError('RemoteSource requires fetch, which is unavailable in this runtime.');
+    }
+
+    const response = await this.fetch(this.url);
+
+    if (!response.ok) {
+      throw new Error(`Failed to load settings from "${this.url}": ${String(response.status)} ${response.statusText}`);
+    }
+
+    let value: unknown = await response.json();
+
+    if (this.responsePath && !isObjectType(value)) {
+      throw new Error(`Fetched value must be an object type if response path is provided, but was ${typeof value}.`);
+    }
+
+    // @ts-expect-error Unable to statically type string literal
+    value = this.responsePath ? prop(value, ...stringToPath(this.responsePath)) : value;
+
+    if (!isPlainObject(value)) {
+      throw new Error(`JSON settings from "${this.url}" must contain an object at the root.`);
+    }
+
+    return value;
+  }
+}

package/src/sources/helpers/loadJson.test.ts

@@ -0,0 +1,74 @@
+/** @jest-environment node */
+
+import { afterEach, describe, expect, it } from '@jest/globals';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { loadJson } from './loadJson.ts';
+
+describe('loadJson', () => {
+  let directory: string | undefined;
+
+  afterEach(async () => {
+    if (!directory) {
+      return;
+    }
+
+    await rm(directory, { force: true, recursive: true });
+    directory = undefined;
+  });
+
+  it('When the file contains a JSON object, then it returns the parsed object', async () => {
+    // Arrange
+    directory = await mkdtemp(join(tmpdir(), 'appsettings-json-'));
+    const path = join(directory, 'settings.json');
+    await writeFile(path, JSON.stringify({ Api: { Timeout: 5000 } }));
+
+    // Act
+    const result = await loadJson(path, false);
+
+    // Assert
+    expect(result).toEqual({ Api: { Timeout: 5000 } });
+  });
+
+  it('When an optional file does not exist, then it returns undefined', async () => {
+    // Arrange
+    directory = await mkdtemp(join(tmpdir(), 'appsettings-json-'));
+    const path = join(directory, 'missing.json');
+
+    // Act
+    const result = await loadJson(path, true);
+
+    // Assert
+    expect(result).toBeUndefined();
+  });
+
+  it('When a required file does not exist, then it propagates the filesystem error', async () => {
+    // Arrange
+    directory = await mkdtemp(join(tmpdir(), 'appsettings-json-'));
+    const path = join(directory, 'missing.json');
+
+    // Act
+    const result = loadJson(path, false);
+
+    // Assert
+    await expect(result).rejects.toMatchObject({ code: 'ENOENT' });
+  });
+
+  it('When the file contains malformed JSON or a non-object root, then it rejects', async () => {
+    // Arrange
+    directory = await mkdtemp(join(tmpdir(), 'appsettings-json-'));
+    const malformedPath = join(directory, 'malformed.json');
+    const arrayPath = join(directory, 'array.json');
+    await writeFile(malformedPath, '{');
+    await writeFile(arrayPath, '[]');
+
+    // Act
+    const malformed = loadJson(malformedPath, false);
+    const array = loadJson(arrayPath, false);
+
+    // Assert
+    await expect(malformed).rejects.toBeInstanceOf(SyntaxError);
+    await expect(array).rejects.toThrow('must contain an object at the root');
+  });
+});

package/src/sources/helpers/loadJson.ts

@@ -0,0 +1,29 @@
+import { readFile } from 'node:fs/promises';
+import { isPlainObject } from 'remeda';
+
+export function loadJson(path: string, isOptional: false): Promise<Record<string, unknown>>;
+export function loadJson(path: string, isOptional: true): Promise<Record<string, unknown> | undefined>;
+
+// Required for overloads
+// eslint-disable-next-line prefer-arrow/prefer-arrow-functions
+export async function loadJson(path: string, isOptional: boolean): Promise<Record<string, unknown> | undefined> {
+  let contents: string;
+
+  try {
+    contents = await readFile(path, 'utf8');
+  } catch (error) {
+    if (isOptional && typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT') {
+      return undefined;
+    }
+
+    throw error;
+  }
+
+  const value: unknown = JSON.parse(contents);
+
+  if (!isPlainObject(value)) {
+    throw new Error(`JSON settings from "${path}" must contain an object at the root.`);
+  }
+
+  return value;
+}

package/src/types/AppSettings.types.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from '@jest/globals';
+import { z } from 'zod';
+import { AppSettingsImplementation } from '../config/AppSettingsImplementation.ts';
+import { createAppSettings } from '../config/createAppSettings.ts';
+import { type AppSettings, type CreateAppSettingsOptions, type ScopedSettings } from './AppSettings.types.ts';
+import { type SettingsSource } from './Source.types.ts';
+
+type ExampleSettings = { Api: { Retry?: number; Timeout: number } };
+
+const assertType = <Expected>(_value: Expected): void => undefined;
+
+describe('AppSettings types', () => {
+  it('When configuration is loaded, then settings and scoped readers expose correctly typed values', async () => {
+    // Arrange
+    const source: SettingsSource = {
+      load: () => Promise.resolve({ Api: { Timeout: 5000 } }),
+      name: 'example',
+    };
+
+    const options: CreateAppSettingsOptions<ExampleSettings> = {
+      defaults: { Api: { Timeout: 1000 } },
+      schema: z.object({ Api: z.object({ Retry: z.number().optional(), Timeout: z.number() }) }),
+      sources: [source],
+    };
+
+    // Act
+    const config = await createAppSettings(options);
+    const settings: AppSettings<ExampleSettings> = new AppSettingsImplementation(config);
+    const scoped: ScopedSettings<{ Retry?: number; Timeout: number }> = settings.scope('Api');
+    const timeout = settings.get('Api.Timeout');
+    const retry = settings.get('Api.Retry');
+    const requiredTimeout = settings.getOrThrow('Api.Timeout');
+    const all = settings.getAll();
+    const section = settings.getSection('Api');
+    const hasTimeout = settings.has('Api.Timeout');
+    const scopedTimeout = scoped.get('Timeout');
+    const scopedRequiredTimeout = scoped.getOrThrow('Timeout');
+    const scopedAll = scoped.getAll();
+
+    assertType<number | undefined>(timeout);
+    assertType<number | undefined>(retry);
+    assertType<number>(requiredTimeout);
+    assertType<Readonly<ExampleSettings>>(all);
+    assertType<ExampleSettings['Api'] | undefined>(section);
+    assertType<boolean>(hasTimeout);
+    assertType<number | undefined>(scopedTimeout);
+    assertType<number>(scopedRequiredTimeout);
+    assertType<Readonly<ExampleSettings['Api']>>(scopedAll);
+
+    // Assert
+    expect(timeout).toBe(5000);
+    expect(retry).toBeUndefined();
+    expect(requiredTimeout).toBe(5000);
+    expect(all).toEqual({ Api: { Timeout: 5000 } });
+    expect(section).toEqual({ Timeout: 5000 });
+    expect(hasTimeout).toBe(true);
+    expect(scopedTimeout).toBe(5000);
+    expect(scopedRequiredTimeout).toBe(5000);
+    expect(scopedAll).toEqual({ Timeout: 5000 });
+  });
+});