@blixis-io/config 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Voeten
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# `@blixis-io/config`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Zod-validated environment config, built on [`@blixis-io/core`](https://www.npmjs.com/package/@blixis-io/core), HTTP-independent.
+
+```bash
+npm install @blixis-io/config @blixis-io/core @blixis-io/di zod
+```
+
+```ts
+import { defineConfigModule } from "@blixis-io/config";
+import { z } from "zod";
+
+const AppConfigSchema = z.object({
+  PORT: z.coerce.number().default(3000),
+  DATABASE_URL: z.string(),
+});
+
+export const { CONFIG, ConfigModule } = defineConfigModule(AppConfigSchema);
+```
+
+```ts
+@Module({ imports: [ConfigModule.forRoot()] })
+class AppModule {}
+```
+
+`forRoot()` validates `process.env` synchronously, the moment it's called — a missing or malformed variable throws `ConfigValidationError` at boot, before the app ever starts resolving providers, never on first use deep in a request.
+
+Part of [Blixis Framework](https://github.com/blixis-io/framework) — full docs: [Configuration](https://blixis-io.github.io/framework/concepts/config/) · [API reference](https://blixis-io.github.io/framework/reference/blixis-config/).

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import { DynamicModule } from "@blixis-io/core";
+import { InjectionToken } from "@blixis-io/di";
+import { ZodType, z } from "zod";
+//#region src/errors.d.ts
+/** Thrown by `ConfigModule.forRoot()` when the source (env by default) fails schema validation — fails at module-definition time, not first use. */
+export declare class ConfigValidationError extends Error {
+  constructor(zodError: z.ZodError);
+}
+//#endregion
+//#region src/module.d.ts
+/**
+ * Builds a config token + module bound to one Zod schema. Config shape is
+ * inherently app-specific — unlike `@blixis-io/logging`'s `LOGGER`, there's no
+ * single fixed type to export a token for, so each app calls this once with
+ * its own schema and gets back its own distinct, strongly-typed token.
+ */
+export declare function defineConfigModule<Schema extends ZodType>(schema: Schema): {
+  CONFIG: InjectionToken<z.infer<Schema>>;
+  ConfigModule: {
+    new (): {};
+    /**
+     * Validates `source` (default: `process.env`) against the schema
+     * immediately, providing the parsed result under `CONFIG`. Throws
+     * `ConfigValidationError` right away on failure — not deferred to first
+     * injection. `global: true` so every module can inject config without
+     * also having to import `ConfigModule` itself.
+     */
+    forRoot(source?: Record<string, string | undefined>): DynamicModule;
+  };
+};
+//#endregion
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/errors.ts","../src/module.ts"],"mappings":";;;;;qBAGa,8BAA8B;EACzC,YAAY,UAAU,EAAE;;;;;;;;;;wBCOV,mBAAmB,eAAe,SAAS,QAAQ;;;;;;;;;;;IAYxC,QAAA,SAAA,qCAAmD"}

package/dist/index.js

@@ -0,0 +1,62 @@
+import { Module } from "@blixis-io/core";
+import { InjectionToken } from "@blixis-io/di";
+//#region src/errors.ts
+/** Thrown by `ConfigModule.forRoot()` when the source (env by default) fails schema validation — fails at module-definition time, not first use. */
+var ConfigValidationError = class extends Error {
+	constructor(zodError) {
+		const issues = zodError.issues.map((issue) => `  - ${issue.path.join(".")}: ${issue.message}`).join("\n");
+		super(`Invalid configuration:\n${issues}`);
+		this.name = "ConfigValidationError";
+	}
+};
+//#endregion
+//#region \0@oxc-project+runtime@0.151.0/helpers/esm/decorate.js
+function __decorate(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;
+}
+//#endregion
+//#region src/module.ts
+/**
+* Builds a config token + module bound to one Zod schema. Config shape is
+* inherently app-specific — unlike `@blixis-io/logging`'s `LOGGER`, there's no
+* single fixed type to export a token for, so each app calls this once with
+* its own schema and gets back its own distinct, strongly-typed token.
+*/
+function defineConfigModule(schema) {
+	var _ConfigModule;
+	const CONFIG = new InjectionToken("blixis.config");
+	let ConfigModule = _ConfigModule = class ConfigModule {
+		/**
+		* Validates `source` (default: `process.env`) against the schema
+		* immediately, providing the parsed result under `CONFIG`. Throws
+		* `ConfigValidationError` right away on failure — not deferred to first
+		* injection. `global: true` so every module can inject config without
+		* also having to import `ConfigModule` itself.
+		*/
+		static forRoot(source = process.env) {
+			const result = schema.safeParse(source);
+			if (!result.success) throw new ConfigValidationError(result.error);
+			return {
+				module: _ConfigModule,
+				providers: [{
+					provide: CONFIG,
+					useValue: result.data
+				}],
+				exports: [CONFIG],
+				global: true
+			};
+		}
+	};
+	ConfigModule = _ConfigModule = __decorate([Module()], ConfigModule);
+	return {
+		CONFIG,
+		ConfigModule
+	};
+}
+//#endregion
+export { ConfigValidationError, defineConfigModule };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/errors.ts","../src/module.ts"],"sourcesContent":["import type { z } from \"zod\";\n\n/** Thrown by `ConfigModule.forRoot()` when the source (env by default) fails schema validation — fails at module-definition time, not first use. */\nexport class ConfigValidationError extends Error {\n  constructor(zodError: z.ZodError) {\n    const issues = zodError.issues.map((issue) => `  - ${issue.path.join(\".\")}: ${issue.message}`).join(\"\\n\");\n    super(`Invalid configuration:\\n${issues}`);\n    this.name = \"ConfigValidationError\";\n  }\n}\n","import { Module, type DynamicModule } from \"@blixis-io/core\";\nimport { InjectionToken } from \"@blixis-io/di\";\nimport type { z, ZodType } from \"zod\";\nimport { ConfigValidationError } from \"./errors.js\";\n\n/**\n * Builds a config token + module bound to one Zod schema. Config shape is\n * inherently app-specific — unlike `@blixis-io/logging`'s `LOGGER`, there's no\n * single fixed type to export a token for, so each app calls this once with\n * its own schema and gets back its own distinct, strongly-typed token.\n */\nexport function defineConfigModule<Schema extends ZodType>(schema: Schema) {\n  const CONFIG = new InjectionToken<z.infer<Schema>>(\"blixis.config\");\n\n  @Module()\n  class ConfigModule {\n    /**\n     * Validates `source` (default: `process.env`) against the schema\n     * immediately, providing the parsed result under `CONFIG`. Throws\n     * `ConfigValidationError` right away on failure — not deferred to first\n     * injection. `global: true` so every module can inject config without\n     * also having to import `ConfigModule` itself.\n     */\n    static forRoot(source: Record<string, string | undefined> = process.env): DynamicModule {\n      const result = schema.safeParse(source);\n      if (!result.success) {\n        throw new ConfigValidationError(result.error);\n      }\n      return {\n        module: ConfigModule,\n        providers: [{ provide: CONFIG, useValue: result.data }],\n        exports: [CONFIG],\n        global: true,\n      };\n    }\n  }\n\n  return { CONFIG, ConfigModule };\n}\n"],"mappings":";;;;AAGA,IAAa,wBAAb,cAA2C,MAAM;CAC/C,YAAY,UAAsB;EAChC,MAAM,SAAS,SAAS,OAAO,KAAK,UAAU,OAAO,MAAM,KAAK,KAAK,GAAG,EAAE,IAAI,MAAM,SAAS,CAAC,CAAC,KAAK,IAAI;EACxG,MAAM,2BAA2B,QAAQ;EACzC,KAAK,OAAO;CACd;AACF;;;;;;;;;;;;;;;;;ACEA,SAAgB,mBAA2C,QAAgB;;CACzE,MAAM,SAAS,IAAI,eAAgC,eAAe;CAElE,IACM,eAAA,gBADN,MACM,aAAa;;;;;;;;EAQjB,OAAO,QAAQ,SAA6C,QAAQ,KAAoB;GACtF,MAAM,SAAS,OAAO,UAAU,MAAM;GACtC,IAAI,CAAC,OAAO,SACV,MAAM,IAAI,sBAAsB,OAAO,KAAK;GAE9C,OAAO;IACL,QAAA;IACA,WAAW,CAAC;KAAE,SAAS;KAAQ,UAAU,OAAO;IAAK,CAAC;IACtD,SAAS,CAAC,MAAM;IAChB,QAAQ;GACV;EACF;CACF;CArBC,eAAA,gBAAA,WAAA,CAAA,OAAO,CAAA,GAAA,YAAA;CAuBR,OAAO;EAAE;EAAQ;CAAa;AAChC"}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@blixis-io/config",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Zod-validated environment config, built on @blixis-io/core, HTTP-independent.",
+  "license": "MIT",
+  "author": "Michael Voeten <michael@voeten.online>",
+  "homepage": "https://blixis-io.github.io/framework/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blixis-io/framework.git",
+    "directory": "packages/config"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "keywords": [
+    "config",
+    "environment-variables",
+    "zod",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "@blixis-io/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@blixis-io/core": "0.1.0",
+    "@blixis-io/di": "0.1.0",
+    "zod": "^4.6.5"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "build": "rolldown -c"
+  }
 }