@abinnovision/nestjs-configx 1.1.1 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [2.0.0](https://github.com/abinnovision/nestjs-commons/compare/nestjs-configx-v1.1.1...nestjs-configx-v2.0.0) (2025-12-13)
+
+
+### ⚠ BREAKING CHANGES
+
+* simplify configx public api ([#50](https://github.com/abinnovision/nestjs-commons/issues/50))
+
+### Features
+
+* simplify configx public api ([#50](https://github.com/abinnovision/nestjs-commons/issues/50)) ([285e283](https://github.com/abinnovision/nestjs-commons/commit/285e2834ca03fde56375fc4596e4a5c01b171abc))
+
+
+### Bug Fixes
+
+* add documentation and testing for new public api ([#51](https://github.com/abinnovision/nestjs-commons/issues/51)) ([c22099d](https://github.com/abinnovision/nestjs-commons/commit/c22099d4fce7a20feac6d72476305c5e2ef8ec01))
+* support methods in configx implementation class ([#45](https://github.com/abinnovision/nestjs-commons/issues/45)) ([d8f8ead](https://github.com/abinnovision/nestjs-commons/commit/d8f8ead93bbdc648277940b79fc331842dd4e377))
+
 ## [1.1.1](https://github.com/abinnovision/nestjs-commons/compare/nestjs-configx-v1.1.0...nestjs-configx-v1.1.1) (2025-03-29)
 
 

package/README.md

@@ -1,39 +1,30 @@
 # @abinnovision/nestjs-configx
 
-Simple configuration management for NestJS.
-Supports [Standard Schema](https://standardschema.dev/).
+Type-safe configuration for NestJS using [Standard Schema](https://standardschema.dev/).
 
-## Installation
+## Goals
 
-```bash
-yarn add @abinnovision/nestjs-configx
-```
+- Type-safe configuration from `process.env`
+- Schema-agnostic via Standard Schema (Zod, ArkType, etc.)
+- Minimal NestJS integration (just a provider, no module)
+- Fail-fast validation at startup
 
-## Schema Libraries
-
-This library implements the [Standard Schema](https://standardschema.dev/)
-specification. This means that you can use any schema library that implements
-the specification.
+## Non-goals
 
-A full list of **libraries that implement the specification can be found
-[here](https://standardschema.dev/#what-schema-libraries-implement-the-spec)**.
+- Multiple config sources (at least not yet)
+- Async schema validation
+- Runtime config reloading
+- Secret management / encryption
 
-This library is tested with the following libraries:
+## Installation
 
-- [Zod](https://github.com/colinhacks/zod)
-- [ArkType](https://github.com/arktypeio/arktype)
+```bash
+yarn add @abinnovision/nestjs-configx
+```
 
 ## Usage
 
-### Define the configuration
-
-First, you need to define the configuration. This is done by creating a class
-that extends the return value of the `configx` function.
-
-The function takes a single argument, which is an object schema that maps the
-environment variables.
-
-#### Using Zod
+### 1. Define your config
 
 ```typescript
 import { configx } from "@abinnovision/nestjs-configx";
@@ -41,62 +32,59 @@ import { z } from "zod";
 
 export class AppConfigx extends configx(
   z.object({
-    PORT: z.string().default("3000").transform(Number).pipe(z.number()),
+    PORT: z.string().default("3000").transform(Number),
     HOST: z.string().default("0.0.0.0"),
   }),
 ) {}
 ```
 
-#### Using ArkType
-
-```typescript
-import { configx } from "@abinnovision/nestjs-configx";
-import { type } from "arktype";
-
-export class AppConfigx extends configx(
-  type({
-    PORT: "string.numeric.parse = '3000'",
-    HOST: "string = '127.0.0.1'",
-  }),
-) {}
-```
-
-### Register the configuration
-
-Next, you need to register the configuration in your NestJS module. This is
-done by calling the `register` method of the `ConfigxModule`.
-
-The method takes multiple Configx classes as arguments, which will be used to
-resolve the configuration.
+### 2. Register as provider
 
 ```typescript
-import { ConfigxModule } from "@abinnovision/nestjs-configx";
 import { Module } from "@nestjs/common";
-
 import { AppConfigx } from "./app.configx";
 
 @Module({
-  imports: [ConfigxModule.register(AppConfigx)],
+  providers: [AppConfigx],
+  exports: [AppConfigx],
 })
 export class AppModule {}
 ```
 
-### Use the configuration
-
-Finally, you can use the configuration in your NestJS components.
+### 3. Inject and use
 
 ```typescript
-import { Injectable } from "@nestjs/common";
-
-import { AppConfigx } from "./app.configx";
-
 @Injectable()
 export class AppService {
-  constructor(private readonly appConfig: AppConfigx) {}
+  constructor(private readonly config: AppConfigx) {}
 
-  getConfig() {
-    // Get the configuration value.
-    return this.appConfig.PORT;
+  getPort() {
+    return this.config.PORT; // number - fully typed
   }
 }
 ```
+
+## Schema Libraries
+
+Any [Standard Schema](https://standardschema.dev/#what-schema-libraries-implement-the-spec) compatible library works. Tested with:
+
+- [Zod](https://github.com/colinhacks/zod)
+- [ArkType](https://github.com/arktypeio/arktype)
+
+### ArkType Example
+
+```typescript
+import { configx } from "@abinnovision/nestjs-configx";
+import { type } from "arktype";
+
+export class AppConfigx extends configx(
+  type({
+    PORT: "string.numeric.parse = '3000'",
+    HOST: "string = '0.0.0.0'",
+  }),
+) {}
+```
+
+## Error Handling
+
+Invalid configuration throws `InvalidConfigError` at instantiation with details about which fields failed validation.

package/dist/create.d.ts

@@ -0,0 +1,7 @@
+import type { ConfigxSchema, ConfigxType } from "./types";
+/**
+ * Creates a new Configx class based on the provided schema.
+ *
+ * @param schema The schema of the Configx class (Zod, ArkType, or any StandardSchema).
+ */
+export declare function configx<T extends ConfigxSchema>(schema: T): ConfigxType<T>;

package/dist/create.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configx = configx;
+const resolver_1 = require("./resolver");
+/**
+ * Creates a new Configx class based on the provided schema.
+ *
+ * @param schema The schema of the Configx class (Zod, ArkType, or any StandardSchema).
+ */
+function configx(schema) {
+    // eslint-disable-next-line @typescript-eslint/no-extraneous-class
+    class ConfigxUsage {
+        static schema = schema;
+        constructor() {
+            // Resolve the configuration.
+            const config = (0, resolver_1.resolveConfig)({
+                schema,
+                resolveEnv: () => process.env,
+            });
+            // Assign the resolved configuration to the instance.
+            // This is currently the most efficient way to do this without relying on proxies.
+            Object.assign(this, config);
+        }
+    }
+    return ConfigxUsage;
+}

package/dist/errors.d.ts

@@ -0,0 +1,14 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+/**
+ * Base class for all Configx errors.
+ */
+export declare class ConfigxError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when the configuration is invalid.
+ */
+export declare class InvalidConfigError extends ConfigxError {
+    constructor(message: string);
+    static fromSchemaIssues(issues: readonly StandardSchemaV1.Issue[]): InvalidConfigError;
+}

package/dist/errors.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidConfigError = exports.ConfigxError = void 0;
+/**
+ * Formats an issue for the ConfigxError.
+ *
+ * @param issue The issue to format.
+ * @returns The formatted issue.
+ */
+const formatIssue = (issue) => {
+    let result = "";
+    if ((issue.path?.length ?? 0) > 0) {
+        // Format the path segments.
+        const path = (issue.path ?? [])
+            .map((segment) => {
+            // If the segment is an object with a key property, use that.
+            if (typeof segment === "object" && "key" in segment) {
+                return segment.key.toString();
+            }
+            return segment.toString();
+        })
+            .join(".");
+        // Add the path to the result.
+        result += `'${path}': `;
+    }
+    else {
+        // If there is no path, the issue is a root issue.
+        result += "@: ";
+    }
+    // Add the message.
+    result += issue.message;
+    return result;
+};
+/**
+ * Base class for all Configx errors.
+ */
+class ConfigxError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigxError";
+    }
+}
+exports.ConfigxError = ConfigxError;
+/**
+ * Error thrown when the configuration is invalid.
+ */
+class InvalidConfigError extends ConfigxError {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidConfigError";
+    }
+    static fromSchemaIssues(issues) {
+        const messageBody = issues.map(formatIssue).join("; ");
+        return new InvalidConfigError(messageBody);
+    }
+}
+exports.InvalidConfigError = InvalidConfigError;

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export * from "./configx.module";
-export * from "./configx.helpers";
-export * from "./configx.errors";
+export * from "./errors";
+export * from "./create";
+export * from "./types";

package/dist/index.js

@@ -14,6 +14,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./configx.module"), exports);
-__exportStar(require("./configx.helpers"), exports);
-__exportStar(require("./configx.errors"), exports);
+__exportStar(require("./errors"), exports);
+__exportStar(require("./create"), exports);
+__exportStar(require("./types"), exports);

package/dist/resolver.d.ts

@@ -0,0 +1,24 @@
+import type { ConfigxSchema } from "./types";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+interface ResolveConfigArgs<T extends ConfigxSchema> {
+    /**
+     * Schema of the Configx class.
+     */
+    schema: T;
+    /**
+     * Resolves the environment variables object.
+     */
+    resolveEnv: () => Record<string, string | undefined>;
+}
+/**
+ * Resolves and validates configuration from environment variables using the provided schema.
+ *
+ * @param args The resolution arguments.
+ * @param args.schema A Standard Schema V1 compatible schema (Zod, ArkType, etc.).
+ * @param args.resolveEnv Function that returns the environment variables object.
+ * @returns The validated and transformed configuration object.
+ * @throws {ConfigxError} If the schema uses asynchronous validation.
+ * @throws {InvalidConfigError} If the environment variables fail schema validation.
+ */
+export declare const resolveConfig: <T extends ConfigxSchema>(args: ResolveConfigArgs<T>) => StandardSchemaV1.InferOutput<T>;
+export {};

package/dist/resolver.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveConfig = void 0;
+const errors_1 = require("./errors");
+/**
+ * Resolves and validates configuration from environment variables using the provided schema.
+ *
+ * @param args The resolution arguments.
+ * @param args.schema A Standard Schema V1 compatible schema (Zod, ArkType, etc.).
+ * @param args.resolveEnv Function that returns the environment variables object.
+ * @returns The validated and transformed configuration object.
+ * @throws {ConfigxError} If the schema uses asynchronous validation.
+ * @throws {InvalidConfigError} If the environment variables fail schema validation.
+ */
+const resolveConfig = (args) => {
+    // The object which will later be parsed by the schema.
+    const parsableObject = args.resolveEnv();
+    const result = args.schema["~standard"].validate(parsableObject);
+    if (result instanceof Promise) {
+        throw new errors_1.ConfigxError("Asynchronous schemas are not supported");
+    }
+    if (result.issues === undefined) {
+        return result.value;
+    }
+    else {
+        throw errors_1.InvalidConfigError.fromSchemaIssues(result.issues);
+    }
+};
+exports.resolveConfig = resolveConfig;

package/dist/{configx.types.d.ts → types.d.ts}

@@ -5,19 +5,14 @@ import type { StandardSchemaV1 } from "@standard-schema/spec";
 export type ConfigxSchema = StandardSchemaV1<Record<string, string | undefined>, Record<string, any>>;
 /**
  * Describes a Configx class.
- * The instance of the class is used to access the configuration.
  */
-export interface Configx<T extends ConfigxSchema = any> {
+export interface ConfigxType<T extends ConfigxSchema = any> {
     /**
-     * The Zod schema of the Configx class.
+     * Standard Schema V1 schema of the Configx class.
      */
     schema: T;
     /**
      * Instantiates a new Configx instance.
      */
-    new (): ConfigxValue<T>;
+    new (): StandardSchemaV1.InferOutput<T>;
 }
-/**
- * Describes the value of the Configx class.
- */
-export type ConfigxValue<T extends ConfigxSchema> = StandardSchemaV1.InferOutput<T>;

package/package.json

@@ -1,65 +1,65 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@abinnovision/nestjs-configx",
-  "packageManager": "yarn@4.5.1",
-  "version": "1.1.1",
-  "license": "Apache-2.0",
+  "version": "2.0.0",
+  "keywords": [
+    "nestjs",
+    "config",
+    "configuration",
+    "standard-schema"
+  ],
   "repository": {
     "url": "https://github.com/abinnovision/nestjs-commons"
   },
+  "license": "Apache-2.0",
   "author": {
     "name": "AB INNOVISION GmbH",
     "email": "info@abinnovision.com",
     "url": "https://abinnovision.com/"
   },
-  "keywords": [
-    "nestjs",
-    "config",
-    "configuration",
-    "configuration",
-    "standard-schema"
-  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "files": [
     "dist"
   ],
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "lint-staged": {
-    "src/**/*.{ts,js}": [
-      "eslint --fix",
-      "prettier --write"
-    ],
-    "*.{js,ts,json,json5,yaml,yml,md}": [
-      "prettier --write"
-    ]
-  },
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
-    "format:check": "prettier --check '{{src,test}/**/*,*}.{js,jsx,ts,tsx,json,json5,yml,yaml,md}'",
-    "format:fix": "prettier --write '{{src,test}/**/*,*}.{js,jsx,ts,tsx,json,json5,yml,yaml,md}'",
-    "lint:check": "eslint '{{src,test}/**/*,*}.{js,jsx,ts,tsx}'",
-    "lint:fix": "eslint '{{src,test}/**/*,*}.{js,jsx,ts,tsx}' --fix",
+    "format:check": "prettier --check 'src/**/*.ts' '*.{json{,5},md,y{,a}ml}'",
+    "format:fix": "prettier --write 'src/**/*.ts' '*.{json{,5},md,y{,a}ml}'",
+    "lint:check": "eslint 'src/**/*.ts'",
+    "lint:fix": "eslint 'src/**/*.ts' --fix",
     "test-unit": "vitest --run --coverage --config vitest.config.mts",
     "test-unit:watch": "vitest --config vitest.config.mts"
   },
+  "lint-staged": {
+    "src/**/*.ts": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json{,5},md,y{,a}ml}": "prettier --write"
+  },
   "prettier": "@abinnovision/prettier-config",
+  "dependencies": {
+    "@standard-schema/spec": "^1.0.0"
+  },
   "devDependencies": {
-    "@abinnovision/eslint-config-base": "^2.2.0",
-    "@abinnovision/eslint-config-typescript": "^2.2.1",
-    "@abinnovision/prettier-config": "^2.1.3",
+    "@abinnovision/eslint-config-base": "^3.0.2",
+    "@abinnovision/prettier-config": "^2.1.5",
     "@swc/core": "^1.11.5",
     "arktype": "^2.1.9",
-    "eslint": "^9.21.0",
-    "globals": "^15.15.0",
-    "prettier": "^3.5.0",
+    "eslint": "^9.39.1",
+    "globals": "^16.5.0",
+    "prettier": "^3.7.4",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.1",
     "typescript": "^5.8.2",
-    "vitest": "^3.0.5",
+    "vitest": "^4.0.15",
     "zod": "^3.24.1"
   },
-  "dependencies": {
-    "@nestjs/common": "^11.0.8",
-    "@standard-schema/spec": "^1.0.0"
+  "packageManager": "yarn@4.5.1",
+  "publishConfig": {
+    "ghpr": true,
+    "npm": true,
+    "npmAccess": "public"
   }
 }

package/dist/configx.errors.d.ts

@@ -1,8 +0,0 @@
-import type { StandardSchemaV1 } from "@standard-schema/spec";
-/**
- * Generic error class for Configx.
- */
-export declare class ConfigxError extends Error {
-    static fromSchemaIssues(issues: readonly StandardSchemaV1.Issue[]): ConfigxError;
-    constructor(message: string);
-}

package/dist/configx.errors.js

@@ -1,38 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ConfigxError = void 0;
-/**
- * Formats an issue for the ConfigxError.
- *
- * @param issue The issue to format.
- * @returns The formatted issue.
- */
-const formatIssue = (issue) => {
-    let result = "";
-    if ((issue.path?.length ?? 0) > 0) {
-        // If there is a path, the issue is a nested issue.
-        result += issue.path?.join(".") + ": ";
-    }
-    else {
-        // If there is no path, the issue is a root issue.
-        result += "@: ";
-    }
-    // Add the message.
-    result += issue.message;
-    return result;
-};
-/**
- * Generic error class for Configx.
- */
-class ConfigxError extends Error {
-    static fromSchemaIssues(issues) {
-        const messageHeader = "Invalid config:\n";
-        const messageBody = issues.map((it) => `- ${formatIssue(it)}`).join("\n");
-        return new ConfigxError(`${messageHeader}${messageBody}`);
-    }
-    constructor(message) {
-        super(message);
-        this.name = "ConfigxError";
-    }
-}
-exports.ConfigxError = ConfigxError;

package/dist/configx.helpers.d.ts

@@ -1,7 +0,0 @@
-import type { Configx, ConfigxSchema } from "./configx.types";
-/**
- * Creates a new Configx class.
- *
- * @param schema The Zod schema of the Configx class.
- */
-export declare function configx<T extends ConfigxSchema>(schema: T): Configx<T>;

package/dist/configx.helpers.js

@@ -1,14 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.configx = configx;
-/**
- * Creates a new Configx class.
- *
- * @param schema The Zod schema of the Configx class.
- */
-function configx(schema) {
-    class Augmented {
-        static schema = schema;
-    }
-    return Augmented;
-}

package/dist/configx.module.d.ts

@@ -1,18 +0,0 @@
-import { DynamicModule, OnModuleInit } from "@nestjs/common";
-import { Configx } from "./configx.types";
-export declare class ConfigxModule implements OnModuleInit {
-    /**
-     * Registers the ConfigxModule in the root module.
-     *
-     * @param configs
-     */
-    static register(...configs: Configx[]): DynamicModule;
-    /**
-     * Resolves the config providers for the given options.
-     *
-     * @private
-     * @param configs
-     */
-    private static resolveConfigProviders;
-    onModuleInit(): void;
-}

package/dist/configx.module.js

@@ -1,53 +0,0 @@
-"use strict";
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
-var ConfigxModule_1;
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ConfigxModule = void 0;
-const common_1 = require("@nestjs/common");
-const configx_resolver_1 = require("./configx.resolver");
-let ConfigxModule = ConfigxModule_1 = class ConfigxModule {
-    /**
-     * Registers the ConfigxModule in the root module.
-     *
-     * @param configs
-     */
-    static register(...configs) {
-        const configProviders = this.resolveConfigProviders(configs);
-        return {
-            module: ConfigxModule_1,
-            providers: configProviders,
-            exports: configProviders,
-        };
-    }
-    /**
-     * Resolves the config providers for the given options.
-     *
-     * @private
-     * @param configs
-     */
-    static resolveConfigProviders(configs) {
-        // If there are no configs, return an empty array.
-        if (configs.length === 0) {
-            return [];
-        }
-        return configs.map((config) => {
-            return {
-                provide: config,
-                useFactory: () => (0, configx_resolver_1.resolveConfig)({
-                    config,
-                    resolveEnv: () => process.env,
-                }),
-            };
-        });
-    }
-    onModuleInit() { }
-};
-exports.ConfigxModule = ConfigxModule;
-exports.ConfigxModule = ConfigxModule = ConfigxModule_1 = __decorate([
-    (0, common_1.Module)({})
-], ConfigxModule);

package/dist/configx.resolver.d.ts

@@ -1,16 +0,0 @@
-import type { Configx, ConfigxSchema } from "./configx.types";
-import type { StandardSchemaV1 } from "@standard-schema/spec";
-interface ResolveConfigArgs<T extends ConfigxSchema> {
-    config: Configx<T>;
-    /**
-     * Resolves the environment variables object.
-     */
-    resolveEnv: () => Record<string, string | undefined>;
-}
-/**
- * Resolves the configuration with the given ConfigxConfig.
- *
- * @param args The arguments for the function.
- */
-export declare const resolveConfig: <T extends ConfigxSchema>(args: ResolveConfigArgs<T>) => Promise<StandardSchemaV1.InferOutput<T>>;
-export {};

package/dist/configx.resolver.js

@@ -1,21 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveConfig = void 0;
-const configx_errors_1 = require("./configx.errors");
-/**
- * Resolves the configuration with the given ConfigxConfig.
- *
- * @param args The arguments for the function.
- */
-const resolveConfig = async (args) => {
-    // The object which will later be parsed by the Zod schema.
-    const parsableObject = args.resolveEnv();
-    const result = await args.config.schema["~standard"].validate(parsableObject);
-    if (result.issues === undefined) {
-        return result.value;
-    }
-    else {
-        throw configx_errors_1.ConfigxError.fromSchemaIssues(result.issues);
-    }
-};
-exports.resolveConfig = resolveConfig;