@rhombus-std/config.env 0.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Butler
+
+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

@@ -0,0 +1,44 @@
+# @rhombus-std/config.env
+
+Environment-variable configuration provider for `@rhombus-std/config` —
+`EnvironmentVariablesConfigurationSource`/`EnvironmentVariablesConfigurationProvider`
+plus the `addEnvironmentVariables` sugar bolted onto `ConfigurationBuilder`.
+
+## Install
+
+```sh
+npm install @rhombus-std/config @rhombus-std/config.env
+```
+
+`@rhombus-std/config` is a peer dependency — install it alongside this package.
+
+## Basic usage
+
+```ts
+import "@rhombus-std/config.env"; // unlocks .addEnvironmentVariables() on ConfigurationBuilder
+import { ConfigurationBuilder } from "@rhombus-std/config";
+
+const config = new ConfigurationBuilder()
+  .addEnvironmentVariables({ prefix: "APP_" })
+  .build();
+
+// APP_SERVER__PORT=8080 in the environment resolves as:
+config.get("Server:Port"); // "8080"
+```
+
+Variable names are normalized (`__` → `:`) before prefix matching, and the
+prefix match itself is case-insensitive — `app_`, `APP_`, and `App_` all match
+a `prefix: "APP_"` source.
+
+## The side-effect import requirement
+
+`addEnvironmentVariables` isn't a method `ConfigurationBuilder` ships with —
+this package bolts it on via TypeScript declaration merging plus a runtime
+prototype patch. If your code calls `.addEnvironmentVariables()` but never
+names any other symbol from `@rhombus-std/config.env`, a bundler or tree-shaker has
+nothing forcing it to load this package's module — you must import it for
+its side effect explicitly:
+
+```ts
+import "@rhombus-std/config.env"; // unlocks .addEnvironmentVariables() on ConfigurationBuilder
+```

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+import { IConfigurationSource, IConfigurationBuilder, IConfigurationProvider, IndexedSection } from '@rhombus-std/config.core';
+import { ConfigurationProvider } from '@rhombus-std/config';
+
+/** Options accepted by {@link EnvironmentVariablesConfigurationSource}. */
+interface EnvironmentVariablesConfigurationSourceOptions {
+    /**
+     * Only variables whose TRANSFORMED name starts with `prefix` (case-insensitive)
+     * are kept; the prefix is stripped from the resulting key.
+     */
+    prefix?: string;
+    /**
+     * Transforms a raw environment variable name before prefix matching.
+     * Defaults to replacing every `__` with `:`, the conventional way to spell
+     * a section-delimited key in an environment variable name.
+     */
+    variableNameTransformation?: (name: string) => string;
+    /**
+     * The environment map to read. Defaults to `process.env`. Injectable so
+     * `load()` is pure with respect to an explicit map -- tests (and any caller
+     * wanting a hermetic source) pass their own instead of mutating the ambient
+     * `process.env`.
+     */
+    env?: Record<string, string | undefined>;
+}
+/** Default {@link EnvironmentVariablesConfigurationSourceOptions.variableNameTransformation}: `__` -> `:`. */
+declare function defaultVariableNameTransformation(name: string): string;
+/**
+ * A configuration source backed by `process.env`, flattened into the
+ * colon-delimited key/value store every provider produces, per an optional
+ * name prefix and a variable-name transformation.
+ */
+declare class EnvironmentVariablesConfigurationSource implements IConfigurationSource {
+    /** Only variables whose transformed name starts with this prefix (case-insensitive) are kept. */
+    prefix?: string;
+    /** Applied to each raw variable name before prefix matching. */
+    variableNameTransformation: (name: string) => string;
+    /** The environment map read at load time (defaults to `process.env`). */
+    env: Record<string, string | undefined>;
+    constructor(options?: EnvironmentVariablesConfigurationSourceOptions);
+    build(_builder: IConfigurationBuilder): IConfigurationProvider;
+}
+
+declare class EnvironmentVariablesConfigurationProvider extends ConfigurationProvider {
+    #private;
+    constructor(source: EnvironmentVariablesConfigurationSource);
+    load(): void;
+}
+
+declare module "@rhombus-std/config/configuration-builder" {
+    interface ConfigurationBuilder<T = IndexedSection> {
+        /**
+         * Registers an {@link EnvironmentVariablesConfigurationSource} seeded from
+         * `process.env`, per an optional `options.prefix` and
+         * `options.variableNameTransformation`.
+         */
+        addEnvironmentVariables(options?: EnvironmentVariablesConfigurationSourceOptions): this;
+    }
+}
+
+export { EnvironmentVariablesConfigurationProvider, EnvironmentVariablesConfigurationSource, defaultVariableNameTransformation };
+export type { EnvironmentVariablesConfigurationSourceOptions };

package/dist/index.js

@@ -0,0 +1,61 @@
+// src/index.ts
+import { ConfigurationBuilder } from "@rhombus-std/config";
+
+// src/environment-variables-configuration-provider.ts
+import { ConfigurationProvider } from "@rhombus-std/config";
+
+class EnvironmentVariablesConfigurationProvider extends ConfigurationProvider {
+  #source;
+  constructor(source) {
+    super();
+    this.#source = source;
+  }
+  load() {
+    this.data.clear();
+    const { prefix, variableNameTransformation, env } = this.#source;
+    for (const [rawName, value] of Object.entries(env)) {
+      if (value === undefined) {
+        continue;
+      }
+      const transformedName = variableNameTransformation(rawName);
+      if (prefix === undefined) {
+        this.set(transformedName, value);
+        continue;
+      }
+      if (!transformedName.toLowerCase().startsWith(prefix.toLowerCase())) {
+        continue;
+      }
+      this.set(transformedName.slice(prefix.length), value);
+    }
+    this.onReload();
+  }
+}
+
+// src/environment-variables-configuration-source.ts
+function defaultVariableNameTransformation(name) {
+  return name.replaceAll("__", ":");
+}
+
+class EnvironmentVariablesConfigurationSource {
+  prefix;
+  variableNameTransformation;
+  env;
+  constructor(options) {
+    this.prefix = options?.prefix;
+    this.variableNameTransformation = options?.variableNameTransformation ?? defaultVariableNameTransformation;
+    this.env = options?.env ?? process.env;
+  }
+  build(_builder) {
+    return new EnvironmentVariablesConfigurationProvider(this);
+  }
+}
+
+// src/index.ts
+ConfigurationBuilder.prototype.addEnvironmentVariables = function(options) {
+  return this.add(new EnvironmentVariablesConfigurationSource(options));
+};
+export {
+  defaultVariableNameTransformation,
+  EnvironmentVariablesConfigurationSource,
+  EnvironmentVariablesConfigurationProvider
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@rhombus-std/config.env",
+  "version": "0.0.0-alpha.0",
+  "description": "process.env configuration provider for @rhombus-std/config: EnvironmentVariablesConfigurationSource/Provider + the addEnvironmentVariables augmentation.",
+  "keywords": [
+    "configuration",
+    "config",
+    "env",
+    "environment-variables",
+    "options",
+    "ioc",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fnioc/std.git",
+    "directory": "libraries/config.env"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": true,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@rhombus-std/config.core": "0.0.0-alpha.0"
+  },
+  "peerDependencies": {
+    "@rhombus-std/config": "^0.0.0-alpha.0"
+  },
+  "devDependencies": {
+    "@rhombus-std/config": "0.0.0-alpha.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "bun x tsc --noEmit -p tsconfig.json && bun build.ts",
+    "lint": "bun x tsc --noEmit -p tsconfig.lint.json"
+  }
+}