@next-box/appsettings 0.0.0-stage → 0.0.4

package/package.json

@@ -1,6 +1,88 @@
 {
   "name": "@next-box/appsettings",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "A configuration management library for TypeScript applications, inspired by .NET’s appsettings.json.",
+  "version": "0.0.4",
+  "author": "miami-man",
+  "license": "MIT",
+  "homepage": "https://github.com/badbatch/next-box",
+  "repository": {
+    "directory": "packages/appsettings",
+    "type": "git",
+    "url": "https://github.com/badbatch/next-box.git"
+  },
+  "bugs": "https://github.com/badbatch/next-box/issues",
+  "type": "module",
+  "bin": {
+    "appsettings": "./bin/appsettings.mjs"
+  },
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.mjs",
+  "types": "./dist/types/cjs/index.d.cts",
+  "imports": {
+    "#*": "./src/*"
+  },
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": {
+        "import": "./dist/types/esm/index.d.ts",
+        "require": "./dist/types/cjs/index.d.cts"
+      },
+      "import": "./dist/esm/index.mjs",
+      "require": "./dist/cjs/index.cjs"
+    },
+    "./cli": {
+      "source": "./src/cli/index.ts",
+      "types": {
+        "import": "./dist/types/esm/cli.d.ts",
+        "require": "./dist/types/cjs/cli.d.cts"
+      },
+      "import": "./dist/esm/cli.mjs",
+      "require": "./dist/cjs/cli.cjs"
+    },
+    "./server": {
+      "source": "./src/server.ts",
+      "types": {
+        "import": "./dist/types/esm/server.d.ts",
+        "require": "./dist/types/cjs/server.d.cts"
+      },
+      "import": "./dist/esm/server.mjs",
+      "require": "./dist/cjs/server.cjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "remeda": "^2.58.0",
+    "yargs": "^18.2.0",
+    "zcb": "^0.3.10",
+    "zod": "^4.6.7"
+  },
+  "peerDependencies": {
+    "react": ">=19"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.4.1",
+    "@testing-library/react": "^16.3.3",
+    "@types/node": "^26.6.6",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@types/yargs": "^17.0.35",
+    "cts-types": "^0.0.17",
+    "del-cli": "^8.0.1",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "type-fest": "^5.10.0"
+  },
+  "scripts": {
+    "build": "pnpm run clean:dist && pnpm run compile",
+    "clean:deps": "del-cli ./node_modules",
+    "clean:dist": "del-cli ./dist",
+    "compile": "pnpm run /^compile:.*/",
+    "compile:cjs": "MODULE_SYSTEM=cjs rollup -c ./rollup.config.mjs",
+    "compile:esm": "rollup -c ./rollup.config.mjs",
+    "compile:types": "tsc --project ./tsconfig.build.json && cts-types build dist/types/esm dist/types/cjs",
+    "type-check": "tsc --project ./tsconfig.json --noEmit --composite false --declaration false --declarationMap false --emitDeclarationOnly false"
+  }
 }

package/rollup.config.mjs

@@ -0,0 +1,17 @@
+import config from '../../rollup.config.mjs';
+
+const { input, ...rest } = config;
+
+// rollup requires config to be default export
+// eslint-disable-next-line import-x/no-default-export
+export default [
+  config,
+  {
+    ...rest,
+    input: input.replace('index', 'cli'),
+  },
+  {
+    ...rest,
+    input: input.replace('index', 'server'),
+  },
+];

package/src/__testUtils__/AppSettingsSchema.d.ts

@@ -0,0 +1,9 @@
+declare module '../index.ts' {
+  interface AppSettingsSchema {
+    Api: { Missing?: string; Timeout: number };
+    Features: { DarkMode: boolean };
+    Missing: { Value: string };
+  }
+}
+
+export {};

package/src/__testUtils__/components/ErrorBoundary.tsx

@@ -0,0 +1,25 @@
+import { Component, type ReactNode } from 'react';
+
+export type ErrorBoundaryProps = {
+  children: ReactNode;
+};
+
+type ErrorBoundaryState = {
+  error: Error | undefined;
+};
+
+export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  public static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { error };
+  }
+
+  public override state: ErrorBoundaryState = { error: undefined };
+
+  public override render(): ReactNode {
+    if (this.state.error) {
+      return <div>{this.state.error.message}</div>;
+    }
+
+    return this.props.children;
+  }
+}

package/src/cli/command.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from '@jest/globals';
+import yargs, { type Argv } from 'yargs';
+import * as generateTypesCommand from './command.ts';
+
+describe('generate-types command', () => {
+  it('When help is requested, then it displays the command usage and options', async () => {
+    // @ts-expect-error not important in test
+    const argv = generateTypesCommand.builder(yargs([])) as Argv;
+
+    // Arrange
+    const parser = argv
+      .scriptName('appsettings')
+      .usage(`$0 ${generateTypesCommand.command}`, generateTypesCommand.describe)
+      .help();
+
+    // Act
+    const help = await parser.getHelp();
+
+    // Assert
+    expect(help).toMatchInlineSnapshot(`
+      "appsettings generate-types <schema> <output>
+
+      Generate a declaration that types appsettings hooks from your schema.
+
+      Positionals:
+        schema  TypeScript module that exports the inferred settings type.    [string]
+        output  Declaration file to generate.
+                                      [string] [default: "appsettings.generated.d.ts"]
+
+      Options:
+        --version  Show version number                                       [boolean]
+        --type     Exported type name.         [string] [default: "AppSettingsConfig"]
+        --help     Show help                                                 [boolean]"
+    `);
+  });
+});

package/src/cli/command.ts

@@ -0,0 +1,33 @@
+import { type CommandBuilder } from 'yargs';
+import { type GenerateTypesArguments } from '#cli/handler.ts';
+
+export const builder: CommandBuilder<object, GenerateTypesArguments> = yargs =>
+  yargs
+    .positional('schema', {
+      demandOption: true,
+      describe: 'TypeScript module that exports the inferred settings type.',
+      type: 'string',
+    })
+    .positional('output', {
+      default: 'appsettings.generated.d.ts',
+      describe: 'Declaration file to generate.',
+      type: 'string',
+    })
+    .option('type', {
+      default: 'AppSettingsConfig',
+      describe: 'Exported type name.',
+      type: 'string',
+    })
+    .check(({ type }) => {
+      if (!/^[A-Za-z_$][\w$]*$/u.test(type)) {
+        throw new Error('--type must be a TypeScript identifier.');
+      }
+
+      return true;
+    });
+
+export const command = 'generate-types <schema> <output>';
+
+export const describe = 'Generate a declaration that types appsettings hooks from your schema.';
+
+export { handler } from './handler.ts';

package/src/cli/handler.test.ts

@@ -0,0 +1,61 @@
+import { afterEach, describe, expect, it } from '@jest/globals';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { handler } from './handler.ts';
+
+describe('generate-types handler', () => {
+  let directory: string | undefined;
+  let originalWorkingDirectory: string | undefined;
+
+  afterEach(async () => {
+    if (originalWorkingDirectory) {
+      process.chdir(originalWorkingDirectory);
+      originalWorkingDirectory = undefined;
+    }
+
+    if (directory) {
+      await rm(directory, { force: true, recursive: true });
+      directory = undefined;
+    }
+  });
+
+  it('When called with schema and output paths, then it writes a relative type augmentation declaration', async () => {
+    // Arrange
+    directory = await mkdtemp(join(tmpdir(), 'appsettings-cli-'));
+    originalWorkingDirectory = process.cwd();
+    process.chdir(directory);
+
+    const args = {
+      output: 'src/types/appsettings.generated.d.ts',
+      schema: 'src/appSettings.schema.ts',
+      type: 'AppSettingsConfig',
+    };
+
+    // Act
+    await handler(args);
+    const contents = await readFile(args.output, 'utf8');
+
+    // Assert
+    expect(contents).toContain("import type { AppSettingsConfig } from '../appSettings.schema';");
+    expect(contents).toContain("declare module '@next-box/appsettings'");
+    expect(contents).toContain('interface AppSettingsSchema extends AppSettingsConfig {}');
+  });
+
+  it('When called again without changing its arguments, then it keeps the generated file contents unchanged', async () => {
+    // Arrange
+    directory = await mkdtemp(join(tmpdir(), 'appsettings-cli-'));
+    originalWorkingDirectory = process.cwd();
+    process.chdir(directory);
+    const args = { output: 'generated.d.ts', schema: 'schema.ts', type: 'Settings' };
+    await handler(args);
+    const firstContents = await readFile(args.output, 'utf8');
+
+    // Act
+    await handler(args);
+    const secondContents = await readFile(args.output, 'utf8');
+
+    // Assert
+    expect(secondContents).toBe(firstContents);
+  });
+});

package/src/cli/handler.ts

@@ -0,0 +1,58 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, relative, resolve, sep } from 'node:path';
+
+const createModuleSpecifier = (path: string): string => {
+  let specifier = path
+    .split(sep)
+    .join('/')
+    .replace(/\.(?:[cm]?tsx?)$/u, '');
+
+  if (!specifier.startsWith('.')) {
+    specifier = `./${specifier}`;
+  }
+
+  return specifier;
+};
+
+const isMissingFile = (error: unknown): boolean =>
+  !!error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT';
+
+export interface GenerateTypesArguments {
+  output: string;
+  schema: string;
+  type: string;
+}
+
+export const handler = async ({ output, schema, type }: GenerateTypesArguments): Promise<void> => {
+  const schemaPath = resolve(process.cwd(), schema);
+  const outputPath = resolve(process.cwd(), output);
+  const schemaImportPath = createModuleSpecifier(relative(dirname(outputPath), schemaPath));
+
+  const contents = [
+    `import type { ${type} } from '${schemaImportPath}';`,
+    '',
+    "declare module '@next-box/appsettings' {",
+    `  interface AppSettingsSchema extends ${type} {}`,
+    '}',
+    '',
+    'export {};',
+    '',
+  ].join('\n');
+
+  let existingContents: string | undefined;
+
+  try {
+    existingContents = await readFile(outputPath, 'utf8');
+  } catch (error) {
+    if (!isMissingFile(error)) {
+      throw error;
+    }
+  }
+
+  if (existingContents !== contents) {
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, contents, 'utf8');
+  }
+
+  process.stdout.write(`Generated ${relative(process.cwd(), outputPath)}\n`);
+};

package/src/cli.test.ts

@@ -0,0 +1,45 @@
+import { afterEach, describe, expect, it } from '@jest/globals';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { runAppsettingsCli } from './cli.ts';
+
+describe('runAppsettingsCli', () => {
+  let directory: string | undefined;
+  let originalWorkingDirectory: string | undefined;
+  let originalArguments: string[] | undefined;
+
+  afterEach(async () => {
+    if (originalArguments) {
+      process.argv = originalArguments;
+      originalArguments = undefined;
+    }
+
+    if (originalWorkingDirectory) {
+      process.chdir(originalWorkingDirectory);
+      originalWorkingDirectory = undefined;
+    }
+
+    if (directory) {
+      await rm(directory, { force: true, recursive: true });
+      directory = undefined;
+    }
+  });
+
+  it('When invoked with generate-types arguments, then it runs the command and writes the declaration', async () => {
+    // Arrange
+    directory = await mkdtemp(join(tmpdir(), 'appsettings-cli-'));
+    originalWorkingDirectory = process.cwd();
+    originalArguments = process.argv;
+    process.chdir(directory);
+    process.argv = ['node', 'appsettings', 'generate-types', 'schema.ts', 'generated.d.ts', '--type', 'Settings'];
+
+    // Act
+    await runAppsettingsCli();
+    const contents = await readFile('generated.d.ts', 'utf8');
+
+    // Assert
+    expect(contents).toContain("import type { Settings } from './schema';");
+    expect(contents).toContain('interface AppSettingsSchema extends Settings {}');
+  });
+});

package/src/cli.ts

@@ -0,0 +1,13 @@
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import * as generateTypesCommand from './cli/command.ts';
+
+export const runAppsettingsCli = async (): Promise<void> => {
+  await yargs(hideBin(process.argv))
+    .scriptName('appsettings')
+    .command(generateTypesCommand)
+    .demandCommand(1, 'Choose a command to run.')
+    .strict()
+    .help()
+    .parseAsync();
+};

package/src/components/AppSettingsProvider.test.tsx

@@ -0,0 +1,25 @@
+/** @jest-environment @repodog/jest-config/FailOnJsdomConsoleEnvironment.mjs */
+
+import { describe, expect, it } from '@jest/globals';
+import { render, screen } from '@testing-library/react';
+import { useAppSetting } from '../hooks/useAppSetting.ts';
+import { AppSettingsProvider } from './AppSettingsProvider.tsx';
+
+const SettingsOutput = () => <span>{String(useAppSetting('Api.Timeout'))}</span>;
+
+describe('AppSettingsProvider', () => {
+  it('When settings are provided, then child components can read the supplied snapshot', () => {
+    // Arrange
+    const settings = { Api: { Timeout: 5000 } };
+
+    // Act
+    render(
+      <AppSettingsProvider settings={settings}>
+        <SettingsOutput />
+      </AppSettingsProvider>,
+    );
+
+    // Assert
+    expect(screen.getByText('5000')).toBeTruthy();
+  });
+});

package/src/components/AppSettingsProvider.tsx

@@ -0,0 +1,18 @@
+'use client';
+
+import { type ReactElement, type ReactNode, useMemo } from 'react';
+import { AppSettingsImplementation } from '#config/AppSettingsImplementation.ts';
+import { AppSettingsContext } from '../hooks/useAppSettingsContext.ts';
+
+export interface AppSettingsProviderProps<T extends object = object> {
+  children: ReactNode;
+  settings: Readonly<T>;
+}
+
+export const AppSettingsProvider = <T extends object>({
+  children,
+  settings,
+}: AppSettingsProviderProps<T>): ReactElement => {
+  const appSettings = useMemo(() => new AppSettingsImplementation(settings), [settings]);
+  return <AppSettingsContext value={appSettings}>{children}</AppSettingsContext>;
+};

package/src/components/Setting.test.tsx

@@ -0,0 +1,59 @@
+/** @jest-environment @repodog/jest-config/FailOnJsdomConsoleEnvironment.mjs */
+
+import { describe, expect, it } from '@jest/globals';
+import { render, screen } from '@testing-library/react';
+import { AppSettingsProvider } from './AppSettingsProvider.tsx';
+import { Setting } from './Setting.tsx';
+
+describe('Setting', () => {
+  it('When the current value matches one of the expected values, then it renders the children', () => {
+    // Arrange
+    const settings = { Features: { DarkMode: true } };
+
+    // Act
+    render(
+      <AppSettingsProvider settings={settings}>
+        <Setting path="Features.DarkMode" value={[false, true]}>
+          Enabled
+        </Setting>
+      </AppSettingsProvider>,
+    );
+
+    // Assert
+    expect(screen.getByText('Enabled')).toBeTruthy();
+  });
+
+  it('When the value does not match, then it renders the fallback', () => {
+    // Arrange
+    const settings = { Features: { DarkMode: false } };
+
+    // Act
+    render(
+      <AppSettingsProvider settings={settings}>
+        <Setting fallback="Disabled" path="Features.DarkMode" value={true}>
+          Enabled
+        </Setting>
+      </AppSettingsProvider>,
+    );
+
+    // Assert
+    expect(screen.getByText('Disabled')).toBeTruthy();
+  });
+
+  it('When negate is enabled, then it renders children for a non-matching value', () => {
+    // Arrange
+    const settings = { Features: { DarkMode: false } };
+
+    // Act
+    render(
+      <AppSettingsProvider settings={settings}>
+        <Setting negate path="Features.DarkMode" value={true}>
+          Not enabled
+        </Setting>
+      </AppSettingsProvider>,
+    );
+
+    // Assert
+    expect(screen.getByText('Not enabled')).toBeTruthy();
+  });
+});

package/src/components/Setting.tsx

@@ -0,0 +1,43 @@
+'use client';
+
+import { type ReactNode } from 'react';
+import { type Get } from 'type-fest';
+import { useAppSettingsContext } from '#hooks/useAppSettingsContext.ts';
+import { type AppSettingsSchema } from '../index.ts';
+import { type SettingPath } from '../types/Config.types.ts';
+
+export interface SettingProps<T extends object, P extends SettingPath<T>> {
+  children: ReactNode;
+  fallback?: ReactNode;
+  negate?: boolean;
+  path: P;
+  value: Get<T, P> | undefined | readonly (Get<T, P> | undefined)[];
+}
+
+type SettingRuntimeProps = {
+  children: ReactNode;
+  fallback?: ReactNode;
+  negate?: boolean;
+  path: string;
+  value: unknown;
+};
+
+export function Setting<P extends SettingPath<AppSettingsSchema>>(props: {
+  children: ReactNode;
+  fallback?: ReactNode;
+  negate?: boolean;
+  path: P;
+  value: Get<AppSettingsSchema, P> | undefined | readonly (Get<AppSettingsSchema, P> | undefined)[];
+}): ReactNode;
+
+export function Setting<T extends object, P extends SettingPath<T>>(props: SettingProps<T, P>): ReactNode;
+
+// Required to support above overloads
+// eslint-disable-next-line prefer-arrow/prefer-arrow-functions
+export function Setting({ children, fallback, negate = false, path, value }: SettingRuntimeProps): ReactNode {
+  const settings = useAppSettingsContext();
+  const current = settings.read(path);
+  const expected = Array.isArray(value) ? value : [value];
+  const isMatches = expected.includes(current);
+  return (negate ? !isMatches : isMatches) ? children : fallback;
+}

package/src/config/AppSettingsImplementation.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from '@jest/globals';
+import { AppSettingsImplementation } from './AppSettingsImplementation.ts';
+
+describe('AppSettingsImplementation', () => {
+  it('When reading configured paths, then it returns leaves, sections, and the complete snapshot', () => {
+    // Arrange
+    const settings = new AppSettingsImplementation({
+      Api: { Retry: undefined, Timeout: 5000 },
+      Features: { DarkMode: true },
+    });
+
+    // Act
+    const leaf = settings.get('Api.Timeout');
+    const section = settings.getSection('Api');
+    const all = settings.getAll();
+
+    // Assert
+    expect(leaf).toBe(5000);
+    expect(section).toEqual({ Timeout: 5000 });
+    expect(all).toEqual({ Api: { Timeout: 5000 }, Features: { DarkMode: true } });
+  });
+
+  it('When a required setting exists or is missing, then it returns the value or throws with its path', () => {
+    // Arrange
+    const settings = new AppSettingsImplementation({ Api: { Retry: undefined, Timeout: 5000 } });
+
+    // Act
+    const value = settings.getOrThrow('Api.Timeout');
+
+    const getMissingValue = () => {
+      settings.getOrThrow('Api.Retry');
+    };
+
+    // Assert
+    expect(value).toBe(5000);
+    expect(getMissingValue).toThrow('Required app setting "Api.Retry" is missing.');
+  });
+
+  it('When checking paths, then it reports present values and sections but not missing values', () => {
+    // Arrange
+    const settings = new AppSettingsImplementation({ Api: { Retry: undefined, Timeout: 5000 } });
+
+    // Act
+    const hasLeaf = settings.has('Api.Timeout');
+    const hasSection = settings.has('Api');
+    const hasMissing = settings.has('Api.Retry');
+
+    // Assert
+    expect(hasLeaf).toBe(true);
+    expect(hasSection).toBe(true);
+    expect(hasMissing).toBe(false);
+  });
+
+  it('When a plain object section is scoped, then it returns a reader relative to that section', () => {
+    // Arrange
+    const settings = new AppSettingsImplementation({ Api: { Timeout: 5000 } });
+
+    // Act
+    const scoped = settings.scope('Api');
+
+    // Assert
+    expect(scoped.get('Timeout')).toBe(5000);
+    expect(scoped.getOrThrow('Timeout')).toBe(5000);
+  });
+});

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