@tsed/config 8.9.0-beta.1

package/src/hooks/afterResolveConfiguration.ts

@@ -0,0 +1,77 @@
+import "@tsed/ajv";
+
+import {configuration, constant, injectable, logger} from "@tsed/di";
+import {$on} from "@tsed/hooks";
+
+import {CONFIG_SOURCES} from "../constants/constants.js";
+import type {ConfigurationExtends} from "../interfaces/ConfigSource.js";
+import {getConfigSources} from "../utils/getConfigSources.js";
+import {validate} from "../utils/validate.js";
+
+export async function afterResolveConfiguration() {
+  const sources = getConfigSources(constant<ConfigurationExtends>("extends", []));
+
+  for (const source of sources.values()) {
+    const {instance, options, watch, refreshOn, name, validationSchema} = source;
+
+    const refresh = async () => {
+      let data = await instance.getAll();
+
+      if (validationSchema) {
+        data = await validate(name!, data, validationSchema);
+      }
+
+      source.data = data;
+      configuration().set(data);
+    };
+
+    await refresh();
+
+    // manage watcher
+    if (watch && instance?.watch) {
+      const closer = await instance.watch(refresh);
+
+      $on("$onDestroy", closer);
+    }
+
+    // manager refresh on request
+    if (refreshOn === "request") {
+      $on("$onRequest", () => {
+        return refresh();
+      });
+    }
+
+    // manager refresh on response
+    if (refreshOn === "response") {
+      $on("$onResponse", () => {
+        refresh().catch((error) => {
+          logger().error({
+            event: "CONFIG_SOURCE_REFRESH_ERROR",
+            hook: "$onResponse",
+            error_name: error.name,
+            error_message: error.message,
+            error_stack: error.stack
+          });
+        });
+      });
+    }
+  }
+
+  configuration().set(
+    "configs",
+    Object.fromEntries(
+      [...sources.entries()].map(([key, source]) => {
+        return [key, source.data];
+      })
+    )
+  );
+
+  const configs = Object.fromEntries(
+    [...sources.entries()].map(([key, source]) => {
+      return [key, source.instance];
+    })
+  );
+  injectable(CONFIG_SOURCES).value(configs);
+}
+
+$on("$afterResolveConfiguration", afterResolveConfiguration);

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @file Automatically generated by @tsed/barrels.
+ */
+export * from "./constants/constants.js";
+export * from "./hooks/afterResolveConfiguration.js";
+export * from "./interfaces/ConfigSource.js";
+export * from "./interfaces/index.js";
+export * from "./providers/dotenv/DotEnvsConfigSource.js";
+export * from "./providers/dotenv/index.js";
+export * from "./providers/envs/EnvsConfigSource.js";
+export * from "./providers/envs/index.js";
+export * from "./providers/json/index.js";
+export * from "./providers/json/JsonConfigSource.js";
+export * from "./providers/yaml/index.js";
+export * from "./providers/yaml/YamlConfigSource.js";
+export * from "./utils/getConfigSources.js";
+export * from "./utils/jsonParse.js";
+export * from "./utils/validate.js";
+export * from "./utils/withOptions.js";

package/src/interfaces/ConfigSource.ts

@@ -0,0 +1,65 @@
+import type {Type} from "@tsed/core";
+import {JsonSchema} from "@tsed/schema";
+
+export interface ConfigSourceOptions<Opts = any> {
+  /**
+   * The name of the configuration provider.
+   */
+  name?: string;
+
+  /**
+   * The priority of the configuration provider. Higher priority providers will override values from lower priority providers.
+   * @default 0
+   */
+  priority?: number;
+
+  /**
+   * Whether to enable the configuration provider.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * The ConfigSource to use for loading configuration values.
+   * @param args
+   */
+  use: Type<ConfigSource<Opts>>;
+  /**
+   * Options for the configuration provider.
+   */
+  options: Opts;
+  /**
+   * The schema to validate the configuration values against.
+   */
+  validationSchema?: JsonSchema;
+  /**
+   * Enable FileSystem Watch mode. ConfigSource must implement the `watch()` method.
+   */
+  watch?: boolean;
+  /**
+   * Refresh strategy. Ts.ED can refresh ConfigSource during the "$onRequest" or "$onResponse" hook.
+   *
+   * Note: refresh data during `$onRequest` can degrade performance depending on the ConfigSource type.
+   * We recommend to refresh data during the $onResponse hook (action are asynchronous).
+   */
+  refreshOn?: "request" | "response";
+}
+
+export type InitialConfigSourceOptions = Omit<ConfigSourceOptions, "options" | "use">;
+export type ConfigSourceWatchCloseCB = () => Promise<void> | void;
+export type ConfigSourceOnChangeCB = () => void;
+
+/**
+ * Interface for a configuration source that can provide configuration values.
+ */
+export interface ConfigSource<Opts = any> {
+  options: Opts;
+
+  /**
+   * Load configuration from the source.
+   */
+  getAll(): Promise<Record<string, unknown>> | Record<string, unknown>;
+
+  watch?(onChange?: ConfigSourceOnChangeCB): Promise<ConfigSourceWatchCloseCB> | ConfigSourceWatchCloseCB;
+}
+
+export type ConfigurationExtends = (Type<ConfigSource> | ConfigSourceOptions)[];

package/src/interfaces/index.ts

@@ -0,0 +1,12 @@
+import type {ConfigurationExtends} from "./ConfigSource.js";
+
+/**
+ * Extend the global TsED namespace to include configuration for this package.
+ */
+declare global {
+  namespace TsED {
+    interface Configuration {
+      extends?: ConfigurationExtends;
+    }
+  }
+}

package/src/providers/dotenv/DotEnvsConfigSource.ts

@@ -0,0 +1,40 @@
+import {watch} from "node:fs";
+import {join} from "node:path";
+
+import dotenvExpand from "dotenv-expand";
+import dotenv, {type DotenvFlowConfigOptions} from "dotenv-flow";
+import {globby} from "globby";
+
+import type {ConfigSourceOnChangeCB} from "../../interfaces/ConfigSource.js";
+import {EnvsConfigSource, type EnvsConfigSourceOptions} from "../envs/EnvsConfigSource.js";
+
+export type DotEnvsConfigSourceOptions = EnvsConfigSourceOptions & DotenvFlowConfigOptions;
+
+export class DotEnvsConfigSource extends EnvsConfigSource<DotEnvsConfigSourceOptions> {
+  getAll(): Record<string, unknown> {
+    dotenvExpand.expand(dotenv.config(this.options));
+
+    return super.getAll();
+  }
+
+  async watch(onChange?: ConfigSourceOnChangeCB) {
+    const files = await globby(join(this.options.path!, ".env"), {
+      dot: true,
+      absolute: true
+    });
+
+    const watchers = files.map((file) => {
+      const watcher = watch(file, onChange);
+
+      return () => {
+        watcher.close();
+      };
+    });
+
+    return () => {
+      watchers.map((close) => {
+        return close();
+      });
+    };
+  }
+}

package/src/providers/dotenv/index.ts

@@ -0,0 +1,3 @@
+import "../../hooks/afterResolveConfiguration.js";
+
+export * from "./DotEnvsConfigSource.js";

package/src/providers/envs/EnvsConfigSource.spec.ts

@@ -0,0 +1,51 @@
+import {EnvsConfigSource} from "./EnvsConfigSource.js";
+
+describe("EnvsConfigSource", () => {
+  describe("getAll()", () => {
+    it("should return all environment variables", () => {
+      process.env.TEST_VAR = "test";
+      process.env.TEST_VAR_2 = "test2";
+
+      const source = new EnvsConfigSource();
+      source.options = {};
+
+      const result = source.getAll();
+
+      expect(result.TEST_VAR).toEqual("test");
+      expect(result.TEST_VAR_2).toEqual("test2");
+    });
+
+    it("should parse JSON values if parseJson is true", () => {
+      process.env.TEST_JSON = '{"key":"value"}';
+
+      const source = new EnvsConfigSource();
+      source.options = {parseJson: true};
+
+      const result = source.getAll();
+
+      expect(result.TEST_JSON).toEqual({key: "value"});
+    });
+
+    it("should not parse JSON values if parseJson is false", () => {
+      process.env.TEST_JSON = '{"key":"value"}';
+
+      const source = new EnvsConfigSource();
+      source.options = {parseJson: false};
+
+      const result = source.getAll();
+
+      expect(result.TEST_JSON).toEqual('{"key":"value"}');
+    });
+    it("should handle invalid JSON gracefully", () => {
+      process.env.INVALID_JSON = "{invalid json}";
+
+      const source = new EnvsConfigSource();
+      source.options = {parseJson: true};
+
+      const result = source.getAll();
+
+      // Check that it falls back to the string value when parsing fails
+      expect(result.INVALID_JSON).toEqual("{invalid json}");
+    });
+  });
+});

package/src/providers/envs/EnvsConfigSource.ts

@@ -0,0 +1,23 @@
+import type {ConfigSource} from "../../interfaces/ConfigSource.js";
+import {jsonParse} from "../../utils/jsonParse.js";
+
+export interface EnvsConfigSourceOptions {
+  parseJson?: boolean;
+}
+
+export class EnvsConfigSource<Config extends EnvsConfigSourceOptions = EnvsConfigSourceOptions> implements ConfigSource<Config> {
+  options: Config;
+
+  getAll(): Record<string, unknown> {
+    const {parseJson = true} = this.options;
+
+    return Object.entries(process.env).reduce((obj, [key, value]) => {
+      const formattedValue = parseJson ? jsonParse(value!) : value;
+
+      return {
+        ...obj,
+        [key]: formattedValue
+      };
+    }, {});
+  }
+}

package/src/providers/envs/index.ts

@@ -0,0 +1,3 @@
+import "../../hooks/afterResolveConfiguration.js";
+
+export * from "./EnvsConfigSource.js";

package/src/providers/json/JsonConfigSource.spec.ts

@@ -0,0 +1,60 @@
+import {existsSync, readFileSync, watch} from "node:fs";
+
+import {JsonConfigSource} from "./JsonConfigSource.js";
+
+vi.mock("node:fs");
+describe("JsonConfigSource", () => {
+  describe("getAll()", () => {
+    it("should read JSON file and return parsed object", () => {
+      const source = new JsonConfigSource();
+      source.options = {
+        path: "./test.json"
+      };
+
+      vi.mocked(existsSync).mockReturnValue(true);
+      vi.mocked(readFileSync).mockReturnValue(JSON.stringify({key: "value"}));
+
+      const result = source.getAll();
+
+      expect(result).toEqual({key: "value"});
+    });
+    it("should return empty object if file does not exist", () => {
+      const source = new JsonConfigSource();
+      source.options = {
+        path: "./test.json"
+      };
+
+      vi.mocked(existsSync).mockReturnValue(false);
+
+      const result = source.getAll();
+
+      expect(result).toEqual({});
+    });
+  });
+
+  describe("watch()", () => {
+    it("should call watch with the correct path", () => {
+      const source = new JsonConfigSource();
+      source.options = {
+        path: "./test.json"
+      };
+
+      const mockOnChange = vi.fn();
+
+      const mockWatcher = {
+        close: vi.fn()
+      };
+
+      vi.mocked(watch).mockReturnValue(mockWatcher as any);
+
+      const result = source.watch(mockOnChange);
+
+      expect(watch).toHaveBeenCalledWith("./test.json", mockOnChange);
+      expect(result).toBeInstanceOf(Function);
+
+      result();
+
+      expect(mockWatcher.close).toHaveBeenCalled();
+    });
+  });
+});

package/src/providers/json/JsonConfigSource.ts

@@ -0,0 +1,45 @@
+import {existsSync, readFileSync, watch} from "node:fs";
+
+import {logger} from "@tsed/di";
+
+import type {ConfigSource} from "../../interfaces/ConfigSource.js";
+
+export interface JsonConfigSourceOptions {
+  /**
+   * The path to the JSON file.
+   */
+  path: string;
+
+  /**
+   * The encoding to use when reading the file.
+   * @default "utf8"
+   */
+  encoding?: BufferEncoding;
+}
+
+export class JsonConfigSource implements ConfigSource<JsonConfigSourceOptions> {
+  options: JsonConfigSourceOptions;
+
+  getAll(): Record<string, unknown> {
+    const {path, encoding = "utf8"} = this.options;
+    // Check if the file exists
+    if (!existsSync(path)) {
+      logger().warn(`Configuration file not found: ${path}`);
+      return {};
+    }
+
+    // Read the file
+    const fileContent = readFileSync(path, encoding);
+
+    return JSON.parse(fileContent);
+  }
+
+  watch(onChange: () => void) {
+    const {path} = this.options;
+    const watcher = watch(path, onChange);
+
+    return () => {
+      watcher.close();
+    };
+  }
+}

package/src/providers/json/index.ts

@@ -0,0 +1,3 @@
+import "../../hooks/afterResolveConfiguration.js";
+
+export * from "./JsonConfigSource.js";

package/src/providers/yaml/YamlConfigSource.spec.ts

@@ -0,0 +1,64 @@
+import {existsSync, readFileSync, watch} from "node:fs";
+
+import JsYaml from "js-yaml";
+
+import {YamlConfigSource} from "./YamlConfigSource.js";
+
+vi.mock("node:fs");
+vi.mock("js-yaml");
+
+describe("YamlConfigSource", () => {
+  describe("getAll()", () => {
+    it("should read JSON file and return parsed object", async () => {
+      const source = new YamlConfigSource();
+      source.options = {
+        path: "./test.yaml"
+      };
+
+      vi.mocked(existsSync).mockReturnValue(true);
+      vi.mocked(JsYaml.load).mockReturnValue({key: "value"});
+
+      const result = await source.getAll();
+
+      expect(result).toEqual({key: "value"});
+    });
+    it("should return empty object if file does not exist", async () => {
+      const source = new YamlConfigSource();
+      source.options = {
+        path: "./test.yaml"
+      };
+
+      vi.mocked(existsSync).mockReturnValue(false);
+
+      const result = await source.getAll();
+
+      expect(result).toEqual({});
+    });
+  });
+
+  describe("watch()", () => {
+    it("should call watch with the correct path", () => {
+      const source = new YamlConfigSource();
+      source.options = {
+        path: "./test.yaml"
+      };
+
+      const mockOnChange = vi.fn();
+
+      const mockWatcher = {
+        close: vi.fn()
+      };
+
+      vi.mocked(watch).mockReturnValue(mockWatcher as any);
+
+      const result = source.watch(mockOnChange);
+
+      expect(watch).toHaveBeenCalledWith("./test.yaml", mockOnChange);
+      expect(result).toBeInstanceOf(Function);
+
+      result();
+
+      expect(mockWatcher.close).toHaveBeenCalled();
+    });
+  });
+});

package/src/providers/yaml/YamlConfigSource.ts

@@ -0,0 +1,39 @@
+import {existsSync, watch} from "node:fs";
+
+import {logger} from "@tsed/di";
+import JsYaml, {type LoadOptions} from "js-yaml";
+
+import type {ConfigSource} from "../../interfaces/ConfigSource.js";
+
+export interface YamlConfigSourceOptions extends LoadOptions {
+  /**
+   * The path to the JSON file.
+   */
+  path: string;
+}
+
+export class YamlConfigSource implements ConfigSource<YamlConfigSourceOptions> {
+  options: YamlConfigSourceOptions;
+
+  async getAll() {
+    const {path, ...opts} = this.options;
+
+    // Check if the file exists
+    if (!existsSync(path)) {
+      logger().warn(`Configuration file not found: ${path}`);
+      return {};
+    }
+
+    // Read the file
+    return (await JsYaml.load(path, opts)) as Record<string, unknown>;
+  }
+
+  watch(onChange: () => void) {
+    const {path} = this.options;
+    const watcher = watch(path, onChange);
+
+    return () => {
+      watcher.close();
+    };
+  }
+}

package/src/providers/yaml/index.ts

@@ -0,0 +1,3 @@
+import "../../hooks/afterResolveConfiguration.js";
+
+export * from "./YamlConfigSource.js";

package/src/utils/getConfigSources.ts

@@ -0,0 +1,52 @@
+import {nameOf, type Type} from "@tsed/core";
+import {inject, injectable, ProviderScope} from "@tsed/di";
+import {camelCase} from "change-case";
+
+import type {ConfigSource, ConfigSourceOptions} from "../interfaces/ConfigSource.js";
+
+export function getConfigSources(configSources: (Type<ConfigSource<any>> | ConfigSourceOptions)[]) {
+  return configSources
+    .map((configSource, index) => {
+      if (!("use" in configSource)) {
+        return {
+          name: camelCase(nameOf(configSource).replace("ConfigSource", "")),
+          use: configSource,
+          options: {},
+          priority: index,
+          enabled: true
+        } satisfies ConfigSourceOptions;
+      }
+
+      return {
+        enabled: true,
+        ...configSource,
+        priority: configSource.priority || 0,
+        name: configSource.name || camelCase(nameOf(configSource.use).replace("ConfigSource", ""))
+      } satisfies ConfigSourceOptions;
+    })
+    .sort((a, b) => a.priority! - b.priority!)
+    .filter(({enabled}) => enabled)
+    .reduce((map, options, index) => {
+      let {use, name, options: useOpts} = options;
+
+      injectable(use).scope(ProviderScope.INSTANCE);
+
+      const instance = inject(use, {
+        useOpts
+      });
+
+      instance.options = useOpts;
+
+      if (map.has(name)) {
+        name = `${name}_${index}`;
+      }
+
+      map.set(name, {
+        ...options,
+        instance,
+        data: {}
+      });
+
+      return map;
+    }, new Map<string, ConfigSourceOptions & {instance: ConfigSource<any>; data: Record<string, any>}>());
+}

package/src/utils/jsonParse.ts

@@ -0,0 +1,7 @@
+export function jsonParse(value: string): any {
+  try {
+    return JSON.parse(value);
+  } catch (e) {
+    return value;
+  }
+}

package/src/utils/validate.ts

@@ -0,0 +1,18 @@
+import {AjvService} from "@tsed/ajv";
+import {inject} from "@tsed/di";
+import {JsonSchema} from "@tsed/schema";
+
+export async function validate(configName: string, config: Record<string, unknown>, validationSchema: JsonSchema) {
+  const ajv = inject(AjvService);
+
+  try {
+    return await ajv.validate(config, {
+      returnsCoercedValues: true,
+      schema: validationSchema.toJSON()
+    });
+  } catch (er) {
+    er.message = er.message.replace("Value.", `extends[${configName}].`);
+
+    throw er;
+  }
+}

package/src/utils/withOptions.ts

@@ -0,0 +1,19 @@
+import type {Type} from "@tsed/core";
+
+import type {ConfigSource, InitialConfigSourceOptions} from "../interfaces/ConfigSource.js";
+
+export function withOptions<Opts>(
+  use: Type<ConfigSource<Opts>>,
+  {name, priority, validationSchema, enabled, refreshOn, watch, ...opts}: InitialConfigSourceOptions & Opts
+) {
+  return {
+    name,
+    priority,
+    validationSchema,
+    use,
+    watch,
+    refreshOn,
+    enabled: enabled !== false,
+    options: opts
+  };
+}

package/tsconfig.esm.json

@@ -0,0 +1,26 @@
+{
+  "extends": "@tsed/typescript/tsconfig.node.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "rootDir": "src",
+    "outDir": "./lib/esm",
+    "declarationDir": "./lib/types",
+    "declaration": true,
+    "composite": true,
+    "noEmit": false
+  },
+  "include": ["src/**/*.ts", "src/**/*.json"],
+  "exclude": [
+    "node_modules",
+    "test",
+    "lib",
+    "benchmark",
+    "coverage",
+    "spec",
+    "**/*.benchmark.ts",
+    "**/*.spec.ts",
+    "keys",
+    "**/__mock__/**",
+    "webpack.config.js"
+  ]
+}

package/vitest.config.mts

@@ -0,0 +1,21 @@
+// @ts-ignore
+import {presets} from "@tsed/vitest/presets";
+import {defineConfig} from "vitest/config";
+
+export default defineConfig(
+  {
+    ...presets,
+    test: {
+      ...presets.test,
+      coverage: {
+        ...presets.test.coverage,
+        thresholds: {
+          statements: 0,
+          branches: 0,
+          functions: 0,
+          lines: 0
+        }
+      }
+    }
+  }
+);