@next-box/appsettings 0.0.0-stage → 0.0.2

package/src/types/AppSettings.types.ts

@@ -0,0 +1,30 @@
+import { type Get } from 'type-fest';
+import { type ZodType } from 'zod';
+import { type SettingPath, type SettingSectionPath } from './Config.types.ts';
+import { type SettingsSource } from './Source.types.ts';
+
+export interface AppSettings<T extends object> {
+  get<P extends SettingPath<T>>(path: P): Get<T, P> | undefined;
+  getAll(): Readonly<T>;
+  getOrThrow<P extends SettingPath<T>>(path: P): Get<T, P>;
+  getSection<P extends SettingSectionPath<T>>(path: P): Get<T, P> | undefined;
+  has(path: SettingPath<T> | SettingSectionPath<T>): boolean;
+  scope<P extends SettingSectionPath<T>>(path: P): ScopedSettings<Extract<Get<T, P>, object>>;
+}
+
+// Internal dynamic lookup used by React bindings.
+export interface InternalAppSettings<T extends object> extends AppSettings<T> {
+  read(path: string): unknown;
+}
+
+export interface ScopedSettings<T extends object = Record<string, unknown>> {
+  get<P extends SettingPath<T>>(path: P): Get<T, P> | undefined;
+  getAll(): Readonly<T>;
+  getOrThrow<P extends SettingPath<T>>(path: P): Get<T, P>;
+}
+
+export interface CreateAppSettingsOptions<T extends object> {
+  defaults: Partial<T>;
+  schema: ZodType<T>;
+  sources?: readonly SettingsSource[];
+}

package/src/types/Config.types.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from '@jest/globals';
+import { type SettingPath, type SettingSectionPath, type SettingValue } from './Config.types.ts';
+
+type ExampleSettings = {
+  Api: { BaseUrl: string; Retry: { Count: number }; Timeout: number };
+  Features: { DarkMode: boolean };
+  Tags: readonly string[];
+};
+
+describe('configuration path types', () => {
+  it('When paths are declared, then leaf and section paths accept the appropriate settings paths', () => {
+    // Arrange
+    const leafPaths: SettingPath<ExampleSettings>[] = [
+      'Api.BaseUrl',
+      'Api.Retry.Count',
+      'Api.Timeout',
+      'Features.DarkMode',
+      'Tags',
+    ];
+
+    const sectionPaths: SettingSectionPath<ExampleSettings>[] = ['Api', 'Api.Retry', 'Features'];
+    const timeout: SettingValue<ExampleSettings, 'Api.Timeout'> = 5000;
+    const retryCount: SettingValue<ExampleSettings['Api']['Retry'], 'Count'> = 3;
+
+    // Act
+    const paths = { leafPaths, retryCount, sectionPaths, timeout };
+
+    // Assert
+    expect(paths).toEqual({
+      leafPaths: ['Api.BaseUrl', 'Api.Retry.Count', 'Api.Timeout', 'Features.DarkMode', 'Tags'],
+      retryCount: 3,
+      sectionPaths: ['Api', 'Api.Retry', 'Features'],
+      timeout: 5000,
+    });
+  });
+});

package/src/types/Config.types.ts

@@ -0,0 +1,27 @@
+import { type Get } from 'type-fest';
+
+type Primitive = string | number | boolean | bigint | symbol | null | undefined;
+
+type PreviousDepth = [never, 0, 1, 2, 3, 4, 5];
+
+export type SettingPath<T extends object, Depth extends number = 5> = Depth extends 0
+  ? never
+  : {
+      [K in Extract<keyof T, string>]: T[K] extends Primitive | readonly Primitive[]
+        ? K
+        : T[K] extends object
+          ? `${K}.${SettingPath<T[K], PreviousDepth[Depth]>}`
+          : K;
+    }[Extract<keyof T, string>];
+
+export type SettingSectionPath<T extends object, Depth extends number = 5> = Depth extends 0
+  ? never
+  : {
+      [K in Extract<keyof T, string>]: T[K] extends Primitive | readonly Primitive[]
+        ? never
+        : T[K] extends object
+          ? K | `${K}.${SettingSectionPath<T[K], PreviousDepth[Depth]>}`
+          : never;
+    }[Extract<keyof T, string>];
+
+export type SettingValue<T extends object, P extends SettingPath<T>> = Get<T, P>;

package/src/types/Source.types.ts

@@ -0,0 +1,4 @@
+export interface SettingsSource {
+  load(): Promise<Record<string, unknown>>;
+  readonly name: string;
+}

package/tsconfig.build.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist/types/esm",
+    "rootDir": "src"
+  },
+  "exclude": [
+    "**/*.test.*",
+  ]
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": ["@repodog/ts-config/index.json", "@repodog/ts-config/build.json"],
+  "compilerOptions": {
+    "types": ["node"]
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "references": []
+}