@andreas-timm/config 0.1.0

package/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2026, Andreas Timm
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,53 @@
+# @andreas-timm/config
+
+Bun-first utilities for loading layered TOML config files and validating the merged result with Zod.
+
+## Features
+
+- Load `global.toml`, `local.toml`, or custom TOML file lists in order.
+- Resolve config files relative to a project root, from absolute paths, or from `~`.
+- Deep-merge files with later files overriding earlier values.
+- Inject `root_dir` before schema validation.
+- Report Zod validation issues with the resolved source file paths.
+
+## Install
+
+```sh
+bun add @andreas-timm/config zod
+```
+
+## Usage
+
+```ts
+// src/config.ts
+import { join } from "node:path";
+import { z } from "zod";
+import { load } from "@andreas-timm/config";
+
+export const ConfigSchema = z
+    .object({
+        root_dir: z.string(),
+    })
+    .strict();
+
+export type Config = z.infer<typeof ConfigSchema>;
+
+const rootDir = join(import.meta.dir, "..");
+const configFiles = ["global.toml", "local.toml"];
+
+let cached: Promise<Config> | undefined;
+
+export function loadConfig(): Promise<Config> {
+    cached ??= load(ConfigSchema, rootDir, configFiles);
+    return cached;
+}
+
+export function resetConfig(): void {
+    cached = undefined;
+}
+```
+
+`loadConfig()` caches the promise in module scope, so files are read and parsed only on the first call and concurrent callers share the in-flight load. Call `resetConfig()` to force a reload in tests or after editing a TOML file.
+
+For the full setup pattern and usage guidance, see [`skills/bun-config/SKILL.md`](https://github.com/andreas-timm/config-ts/blob/main/skills/bun-config/SKILL.md).
+

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { z } from "zod";
+export declare function load<Config>(configSchema: z.ZodType<Config>, rootDir: string, configFiles?: string[]): Promise<Config>;

package/dist/index.js

@@ -0,0 +1,62 @@
+// @bun
+// src/index.ts
+import { homedir } from "os";
+import { join } from "path";
+import merge from "lodash.merge";
+import { concatMap, from, lastValueFrom } from "rxjs";
+import { reduce } from "rxjs/operators";
+import { z } from "zod";
+function resolveConfigFilePath(rootDir, fileName) {
+  if (fileName.startsWith("/")) {
+    return fileName;
+  }
+  if (fileName.startsWith("~")) {
+    const home = homedir();
+    if (fileName === "~") {
+      return home;
+    }
+    if (fileName.startsWith("~/") || fileName.startsWith("~\\")) {
+      return join(home, fileName.slice(2));
+    }
+    return join(home, fileName.slice(1));
+  }
+  return join(rootDir, fileName);
+}
+async function load(configSchema, rootDir, configFiles = ["global.toml", "local.toml"]) {
+  const config$ = from(configFiles).pipe(concatMap(async (fileName) => {
+    const file = Bun.file(resolveConfigFilePath(rootDir, fileName));
+    if (await file.exists()) {
+      const text = await file.text();
+      return Bun.TOML.parse(text);
+    }
+    return {};
+  }), reduce((acc, cur) => merge(acc, cur), {}));
+  const merged = await lastValueFrom(config$);
+  try {
+    return configSchema.parse({ root_dir: rootDir, ...merged });
+  } catch (err) {
+    if (err instanceof z.ZodError) {
+      const files = configFiles.map((f) => resolveConfigFilePath(rootDir, f)).join(", ");
+      const details = err.issues.map((i) => {
+        const path = i.path?.length ? i.path.join(".") : "<root>";
+        const expected = "expected" in i && i.expected !== undefined ? `
+  expected: ${i.expected}` : "";
+        const received = "received" in i && i.received !== undefined ? `
+  received: ${i.received}` : "";
+        return `- path: ${path}
+  code: ${i.code}
+  message: ${i.message}${expected}${received}`;
+      }).join(`
+`);
+      const helpful = `From: ${files}
+` + `Computed root_dir: ${rootDir}
+` + `Schema validation issues:
+${details}`;
+      throw new Error(helpful, { cause: err });
+    }
+    throw err;
+  }
+}
+export {
+  load
+};

package/package.json

@@ -0,0 +1,73 @@
+{
+    "name": "@andreas-timm/config",
+    "version": "0.1.0",
+    "description": "Bun-first TOML config loading with Zod validation",
+    "license": "BSD-2-Clause",
+    "author": {
+        "name": "Andreas Timm",
+        "email": "info@andreas-timm.dev"
+    },
+    "homepage": "https://github.com/andreas-timm/config-ts#readme",
+    "bugs": {
+        "url": "https://github.com/andreas-timm/config-ts/issues"
+    },
+    "keywords": [
+        "bun",
+        "config",
+        "toml",
+        "typescript",
+        "zod"
+    ],
+    "type": "module",
+    "files": [
+        "dist",
+        "src",
+        "skills",
+        "LICENSE",
+        "README.md"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "default": "./dist/index.js"
+        }
+    },
+    "types": "./dist/index.d.ts",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/andreas-timm/config-ts.git"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "build": "rm -rf dist && bun build src/index.ts --target bun --format esm --packages external --outfile dist/index.js && tsc -p tsconfig.build.json",
+        "lint": "set -x; status=0; biome lint || status=$?; biome check || status=$?; eslint scripts src test || status=$?; tsc --noEmit -p tsconfig.json || status=$?; exit $status",
+        "pack": "bun pm pack --ignore-scripts --destination packs",
+        "prepack": "bun run build",
+        "prepublishOnly": "bun lint && bun test && bun audit --audit-level=moderate",
+        "postpack": "bun scripts/postpack.ts",
+        "release:publish": "bun scripts/publish.ts"
+    },
+    "dependencies": {
+        "lodash.merge": "^4.6.2",
+        "rxjs": "^7.8.2"
+    },
+    "peerDependencies": {
+        "zod": "^4.0.0"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "^2.4.13",
+        "@eslint/js": "^10.0.1",
+        "@types/bun": "^1.3.13",
+        "@types/lodash.merge": "^4.6.9",
+        "@types/node": "^25.6.0",
+        "@typescript-eslint/eslint-plugin": "^8.59.0",
+        "@typescript-eslint/parser": "^8.59.0",
+        "globals": "^17.5.0",
+        "prettier-plugin-organize-imports": "^4.3.0",
+        "typescript": "^5.9.3",
+        "zod": "^4.3.6"
+    }
+}

package/skills/bun-config/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: bun-config
+description: Load layered TOML config files in Bun projects with `@andreas-timm/config`, validated by a Zod schema. Use whenever a Bun project needs typed configuration loading from `global.toml` and `local.toml` or a similar ordered file list with merge and schema validation.
+---
+# Bun Config With `@andreas-timm/config`
+
+Use this skill when a Bun project needs typed, layered configuration loaded from TOML files and validated with Zod.
+
+## Install
+
+```sh
+bun add @andreas-timm/config zod
+```
+
+## tsconfig.json
+
+```jsonc
+{
+    "compilerOptions": {
+        "types": ["bun"],
+        "paths": {
+            "@config": ["./src/config.ts"]
+        }
+    }
+}
+```
+
+- `types: ["bun"]` is required for `Bun.file` and `Bun.TOML`.
+- The `@config` alias keeps imports stable across the project.
+
+## Config Module
+
+Create `src/config.ts` that defines the schema and exports `loadConfig`:
+
+```ts
+// src/config.ts
+import { join } from "node:path";
+import { z } from "zod";
+import { load } from "@andreas-timm/config";
+
+export const ConfigSchema = z
+    .object({
+        root_dir: z.string(),
+    })
+    .strict();
+
+export type Config = z.infer<typeof ConfigSchema>;
+
+const rootDir = join(import.meta.dir, "..");
+const configFiles = ["global.toml", "local.toml"];
+
+let cached: Promise<Config> | undefined;
+
+export function loadConfig(): Promise<Config> {
+    cached ??= load(ConfigSchema, rootDir, configFiles);
+    return cached;
+}
+
+export function resetConfig(): void {
+    cached = undefined;
+}
+```
+
+## Usage
+
+```ts
+import { loadConfig } from "@config";
+
+const config = await loadConfig();
+```
+
+## Behavior
+
+- Files are read in order and deep-merged with `lodash.merge`; later files override earlier ones.
+- Missing files are skipped silently.
+- `root_dir` is injected automatically before schema parsing.
+- Validation errors include the resolved file paths and per-issue details.
+- `loadConfig()` caches the promise in module scope, so files are read and parsed only on the first call and concurrent callers share the in-flight load. Call `resetConfig()` to force a reload in tests or after editing a TOML file.

package/src/index.ts

@@ -0,0 +1,76 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import merge from "lodash.merge";
+import { concatMap, from, lastValueFrom } from "rxjs";
+import { reduce } from "rxjs/operators";
+import { z } from "zod";
+
+type ConfigData = Record<string, unknown>;
+
+function resolveConfigFilePath(rootDir: string, fileName: string): string {
+    if (fileName.startsWith("/")) {
+        return fileName;
+    }
+    if (fileName.startsWith("~")) {
+        const home = homedir();
+        if (fileName === "~") {
+            return home;
+        }
+        if (fileName.startsWith("~/") || fileName.startsWith("~\\")) {
+            return join(home, fileName.slice(2));
+        }
+        return join(home, fileName.slice(1));
+    }
+    return join(rootDir, fileName);
+}
+
+export async function load<Config>(
+    configSchema: z.ZodType<Config>,
+    rootDir: string,
+    configFiles: string[] = ["global.toml", "local.toml"],
+): Promise<Config> {
+    const config$ = from(configFiles).pipe(
+        concatMap(async (fileName) => {
+            const file = Bun.file(resolveConfigFilePath(rootDir, fileName));
+            if (await file.exists()) {
+                const text = await file.text();
+                return Bun.TOML.parse(text) as ConfigData;
+            }
+            return {};
+        }),
+        reduce((acc, cur) => merge(acc, cur), {} as ConfigData),
+    );
+
+    const merged = await lastValueFrom(config$);
+
+    try {
+        return configSchema.parse({ root_dir: rootDir, ...merged });
+    } catch (err) {
+        if (err instanceof z.ZodError) {
+            const files = configFiles
+                .map((f) => resolveConfigFilePath(rootDir, f))
+                .join(", ");
+            const details = err.issues
+                .map((i) => {
+                    const path = i.path?.length ? i.path.join(".") : "<root>";
+                    const expected =
+                        "expected" in i && i.expected !== undefined
+                            ? `\n  expected: ${i.expected}`
+                            : "";
+                    const received =
+                        "received" in i && i.received !== undefined
+                            ? `\n  received: ${i.received}`
+                            : "";
+                    return `- path: ${path}\n  code: ${i.code}\n  message: ${i.message}${expected}${received}`;
+                })
+                .join("\n");
+            // prettier-ignore
+            const helpful =
+                `From: ${files}\n` +
+                `Computed root_dir: ${rootDir}\n` +
+                `Schema validation issues:\n${details}`;
+            throw new Error(helpful, { cause: err });
+        }
+        throw err;
+    }
+}