@rhombus-std/config.json 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,45 @@
+# @rhombus-std/config.json
+
+JSON file configuration provider for `@rhombus-std/config` —
+`JsonConfigurationSource`/`JsonConfigurationProvider` plus the `addJsonFile`
+sugar bolted onto `ConfigurationBuilder`.
+
+## Install
+
+```sh
+npm install @rhombus-std/config @rhombus-std/config.json
+```
+
+`@rhombus-std/config` is a peer dependency — install it alongside this package.
+
+## Basic usage
+
+```ts
+import "@rhombus-std/config.json"; // unlocks .addJsonFile() on ConfigurationBuilder
+import { ConfigurationBuilder } from "@rhombus-std/config";
+
+const config = new ConfigurationBuilder()
+  .addJsonFile("appsettings.json")
+  .addJsonFile("appsettings.local.json", { optional: true })
+  .build();
+
+config.get("Server:Port");
+```
+
+`optional: true` makes a missing file resolve to an empty provider instead of
+throwing. Malformed JSON in a file that _does_ exist always throws, regardless
+of `optional` — it only covers file absence, not file validity.
+
+## The side-effect import requirement
+
+`addJsonFile` 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 `.addJsonFile()` but never names any other symbol
+from `@rhombus-std/config.json` (no `JsonConfigurationSource`, no
+`JsonConfigurationProvider`), 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.json"; // unlocks .addJsonFile() on ConfigurationBuilder
+```

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import { IConfigurationSource, IConfigurationBuilder, IConfigurationProvider, IndexedSection } from '@rhombus-std/config.core';
+import { ConfigurationProvider } from '@rhombus-std/config';
+
+/** Options accepted by {@link JsonConfigurationSource}'s constructor. */
+interface JsonConfigurationSourceOptions {
+    /**
+     * When `true`, a missing file yields an empty provider instead of
+     * throwing. Malformed JSON in a file that *does* exist always throws,
+     * regardless of this flag -- "optional" only covers file absence, not
+     * file validity.
+     */
+    optional?: boolean;
+}
+/**
+ * A {@link IConfigurationSource} that reads a JSON file from disk (resolved
+ * relative to `process.cwd()`) and flattens it into the case-insensitive
+ * key/value store shared by every {@link ConfigurationProvider}.
+ */
+declare class JsonConfigurationSource implements IConfigurationSource {
+    readonly path: string;
+    readonly optional: boolean;
+    constructor(path: string, opts?: JsonConfigurationSourceOptions);
+    build(_builder: IConfigurationBuilder): IConfigurationProvider;
+}
+
+declare class JsonConfigurationProvider extends ConfigurationProvider {
+    private readonly source;
+    constructor(source: JsonConfigurationSource);
+    load(): void;
+    private flatten;
+}
+
+declare module "@rhombus-std/config/configuration-builder" {
+    interface ConfigurationBuilder<T = IndexedSection> {
+        /** Registers a {@link JsonConfigurationSource} reading `path` (resolved against `process.cwd()`). */
+        addJsonFile(path: string, opts?: JsonConfigurationSourceOptions): this;
+    }
+}
+
+export { JsonConfigurationProvider, JsonConfigurationSource };
+export type { JsonConfigurationSourceOptions };

package/dist/index.js

@@ -0,0 +1,88 @@
+// src/index.ts
+import { ConfigurationBuilder } from "@rhombus-std/config";
+
+// src/json-configuration-provider.ts
+import { ConfigurationProvider } from "@rhombus-std/config";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+function isFileNotFound(err) {
+  return typeof err === "object" && err !== null && err.code === "ENOENT";
+}
+
+class JsonConfigurationProvider extends ConfigurationProvider {
+  source;
+  constructor(source) {
+    super();
+    this.source = source;
+  }
+  load() {
+    this.data.clear();
+    const resolvedPath = resolve(process.cwd(), this.source.path);
+    let raw;
+    try {
+      raw = readFileSync(resolvedPath, "utf-8");
+    } catch (err) {
+      if (isFileNotFound(err)) {
+        if (this.source.optional) {
+          this.onReload();
+          return;
+        }
+        throw new Error(`JsonConfigurationProvider: config file not found: ${resolvedPath}`);
+      }
+      throw err;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      throw new Error(`JsonConfigurationProvider: failed to parse JSON at ${resolvedPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+      throw new Error(`JsonConfigurationProvider: root must be an object or array at ${resolvedPath}`);
+    }
+    this.flatten(parsed, "");
+    this.onReload();
+  }
+  flatten(value, prefix) {
+    if (value === null || value === undefined) {
+      return;
+    }
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => {
+        this.flatten(item, prefix === "" ? String(index) : `${prefix}:${index}`);
+      });
+      return;
+    }
+    if (typeof value === "object") {
+      for (const [key, child] of Object.entries(value)) {
+        this.flatten(child, prefix === "" ? key : `${prefix}:${key}`);
+      }
+      return;
+    }
+    if (prefix !== "") {
+      this.set(prefix, String(value));
+    }
+  }
+}
+
+// src/json-configuration-source.ts
+class JsonConfigurationSource {
+  path;
+  optional;
+  constructor(path, opts) {
+    this.path = path;
+    this.optional = opts?.optional ?? false;
+  }
+  build(_builder) {
+    return new JsonConfigurationProvider(this);
+  }
+}
+
+// src/index.ts
+ConfigurationBuilder.prototype.addJsonFile = function(path, opts) {
+  return this.add(new JsonConfigurationSource(path, opts));
+};
+export {
+  JsonConfigurationSource,
+  JsonConfigurationProvider
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@rhombus-std/config.json",
+  "version": "0.0.0-alpha.0",
+  "description": "JSON file configuration provider for @rhombus-std/config: JsonConfigurationSource/Provider + the addJsonFile augmentation.",
+  "keywords": [
+    "configuration",
+    "config",
+    "json",
+    "ioc",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fnioc/std.git",
+    "directory": "libraries/config.json"
+  },
+  "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"
+  }
+}