@nirelc/microconf 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ilyhalight
+
+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,106 @@
+<div align="center">
+  <h1>microconf</h1>
+  <p>Lightweight and simple type-safety config library over <a href="https://github.com/Nirelc/microtype">microtype</a></p>
+  <img src="./assets/hero.svg" width="100%" alt="microconf banner">
+</div>
+
+---
+
+## Install
+
+NPM
+
+```bash
+npm install @nirelc/microconf
+```
+
+Bun
+
+```bash
+bun install @nirelc/microconf
+```
+
+## Usage
+
+```ts
+import { defineConfig, t, env } from "@nirelc/microconf";
+
+const config = defineConfig({
+  schema: {
+    port: t.number().min(0).max(65535).default(8080),
+  },
+  // optional. With no sources (or sources: []), use schema defaults only
+  sources: [env()],
+});
+```
+
+## Sources
+
+For each field, sources are checked in array order:
+
+- missing value allows the next source to run
+- invalid value cause `ParseConfigError`, other sources and defaults can't replace it
+- if every source is missing the value, the schema is parsed with `undefined` and `.default()` or `.optional()` are applied
+
+Sources return `undefined` from `load(meta)` only for missing values. For existing values, return the schema's `ParseResult`, including validation failures. A successful result containing `data: undefined` is still a resolved value, not a missing one.
+
+Available sources:
+
+### `defaults()`
+
+`defaults()` loads from schema `.default()` values
+
+Defaults are always applied last by `defineConfig`, including with `sources: []`. You don't need to add `defaults()` explicitly
+
+### `env()`
+
+`env()` loads from env variables. We doesn't load `.env` files!
+
+Schema keys are converted to env variable names by:
+
+- add prefix if provided. e.g., with prefix `APP_`, `token` becomes `APP_TOKEN`
+- camelCase -> camel_Case
+- all chars -> UPPERCASE
+- nested keys are converted to flat env variable names by delimiter (default: `__`)
+
+e.g.:
+
+```js
+// index.ts
+const config = defineConfig({
+  schema: {
+    nested: {
+      key: t.string(),
+    },
+  },
+  sources: [env()],
+});
+
+// .env
+NESTED__KEY = hello;
+```
+
+this source can be configured with options:
+
+```ts
+env({
+  prefix: "APP_", // optional, default: undefined
+  delimiter: "__", // optional, default: "__"
+  forceCoerce: true, // optional, default: true
+});
+```
+
+`prefix` - prefix for env variable names. e.g., with prefix `APP_`, `token` becomes `APP_TOKEN`
+`delimiter` - delimiter for nested keys. default: `__`
+`forceCoerce` - boolean to force type coercion. default: `true`. e.g. if set to `false`, `t.boolean()` willn't coerce `"true"` to `true` and will return a parse error instead
+
+## Errors
+
+With `APP_PORT=abc`, `prefix: "APP_"` and a numeric `port` schema:
+
+```text
+Config parsing failed with 1 issue(s):
+- APP_PORT from env: expected number
+```
+
+`ParseConfigError.issues` preserves the validation message and full field `path`, with `source` and the environment `key`. Missing required values are reported against the final `defaults` source.

package/dist/define.d.mts

@@ -0,0 +1,4 @@
+import { Config, InferSchema, Schema } from "./types.mjs";
+//#region src/define.d.ts
+export declare function defineConfig<const S extends Schema>({ schema, sources }: Config<S>): InferSchema<S>;
+//#endregion

package/dist/define.mjs

@@ -0,0 +1,33 @@
+import { isRecord } from "./guards/object.mjs";
+import { DefaultsSource, defaults } from "./sources/defaults.mjs";
+import { setObjValueByPath } from "./utils.mjs";
+import { ParseConfigError, ParseSchemaError, parseSchema } from "./parse.mjs";
+import { formatPath } from "@nirelc/microtype";
+//#region src/define.ts
+function defineConfig({ schema, sources = [] }) {
+	if (!isRecord(schema)) throw new ParseSchemaError([{ message: "Schema must be an object" }]);
+	const metas = parseSchema(schema);
+	if (!metas.success) throw new ParseSchemaError(metas.issues);
+	const unparsedFields = new Map(metas.data.map((meta) => [formatPath(meta.path), meta]));
+	const issues = [];
+	const result = {};
+	for (const source of [...sources.filter((source) => !(source instanceof DefaultsSource)), defaults()]) for (const [key, meta] of unparsedFields.entries()) {
+		const data = source.load(meta);
+		if (data === void 0) continue;
+		unparsedFields.delete(key);
+		if (!data.success) {
+			const sourceIssues = data.issues.length ? data.issues : [{ message: "Invalid value" }];
+			issues.push(...sourceIssues.map((issue) => ({
+				...issue,
+				path: [...meta.path, ...issue.path ?? []],
+				source: source.name
+			})));
+			continue;
+		}
+		setObjValueByPath(result, meta.path, data.data);
+	}
+	if (issues.length) throw new ParseConfigError(issues);
+	return result;
+}
+//#endregion
+export { defineConfig };

package/dist/guards/object.d.mts

@@ -0,0 +1,3 @@
+//#region src/guards/object.d.ts
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+//#endregion

package/dist/guards/object.mjs

@@ -0,0 +1,6 @@
+//#region src/guards/object.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+export { isRecord };

package/dist/index.d.mts

@@ -0,0 +1,7 @@
+import { Config, ConfigIssue, InferSchema, Schema, SchemaMeta, Source } from "./types.mjs";
+import { defineConfig } from "./define.mjs";
+import { env } from "./sources/env.mjs";
+import { defaults } from "./sources/defaults.mjs";
+import { ParseConfigError, ParseError, ParseSchemaError } from "./parse.mjs";
+import * as t from "@nirelc/microtype";
+export { Config, ConfigIssue, InferSchema, ParseConfigError, ParseError, ParseSchemaError, Schema, SchemaMeta, Source, defaults, defineConfig, env, t };

package/dist/index.mjs

@@ -0,0 +1,6 @@
+import { defaults } from "./sources/defaults.mjs";
+import { ParseConfigError, ParseError, ParseSchemaError } from "./parse.mjs";
+import { defineConfig } from "./define.mjs";
+import { env } from "./sources/env.mjs";
+import * as t from "@nirelc/microtype";
+export { ParseConfigError, ParseError, ParseSchemaError, defaults, defineConfig, env, t };

package/dist/parse.d.mts

@@ -0,0 +1,18 @@
+import { ConfigIssue, Schema as Schema$1, SchemaMeta } from "./types.mjs";
+import { Issue, ParseResult } from "@nirelc/microtype";
+//#region src/parse.d.ts
+export declare class ParseError extends Error {
+  readonly issues: Issue[];
+  readonly context: string;
+  constructor(issues: Issue[], context: string);
+}
+export declare class ParseConfigError extends ParseError {
+  override readonly issues: ConfigIssue[];
+  constructor(issues: ConfigIssue[]);
+}
+export declare class ParseSchemaError extends ParseError {
+  override readonly issues: Issue[];
+  constructor(issues: Issue[]);
+}
+export declare function parseSchema(schema: Schema$1, path?: PropertyKey[]): ParseResult<SchemaMeta[]>;
+//#endregion

package/dist/parse.mjs

@@ -0,0 +1,67 @@
+import { isRecord } from "./guards/object.mjs";
+import { BaseSchema, formatIssue, formatPath } from "@nirelc/microtype";
+//#region src/parse.ts
+var ParseError = class extends Error {
+	issues;
+	context;
+	constructor(issues, context) {
+		super(`${context} failed with ${issues.length} issue(s):\n${issues.map((issue) => {
+			if (issue.source === void 0) return `- ${formatIssue(issue)}`;
+			const location = issue.key ?? formatPath(issue.path ?? []);
+			const message = issue.message.replace(/^[A-Z]/, (char) => char.toLowerCase());
+			return `- ${location} from ${issue.source}: ${message}`;
+		}).join("\n")}`);
+		this.issues = issues;
+		this.context = context;
+		this.name = "ParseError";
+	}
+};
+var ParseConfigError = class extends ParseError {
+	issues;
+	constructor(issues) {
+		super(issues, "Config parsing");
+		this.issues = issues;
+		this.name = "ParseConfigError";
+	}
+};
+var ParseSchemaError = class extends ParseError {
+	issues;
+	constructor(issues) {
+		super(issues, "Schema parsing");
+		this.issues = issues;
+		this.name = "ParseSchemaError";
+	}
+};
+function parseSchema(schema, path = []) {
+	if (!isRecord(schema)) return {
+		success: false,
+		issues: [{ message: `Field '${formatPath(path)}' must be a 'TSchema | Schema' object` }]
+	};
+	const meta = [];
+	const issues = [];
+	for (const [key, value] of Object.entries(schema)) {
+		if (value instanceof BaseSchema) {
+			meta.push({
+				key,
+				path: [...path, key],
+				schema: value
+			});
+			continue;
+		}
+		const result = parseSchema(value, [...path, key]);
+		if (!result.success) {
+			issues.push(...result.issues);
+			continue;
+		}
+		meta.push(...result.data);
+	}
+	return issues.length ? {
+		success: false,
+		issues
+	} : {
+		success: true,
+		data: meta
+	};
+}
+//#endregion
+export { ParseConfigError, ParseError, ParseSchemaError, parseSchema };

package/dist/sources/defaults.d.mts

@@ -0,0 +1,9 @@
+import { SchemaMeta, Source } from "../types.mjs";
+import { ParseResult } from "@nirelc/microtype";
+//#region src/sources/defaults.d.ts
+export declare class DefaultsSource implements Source {
+  name: string;
+  load(meta: SchemaMeta): ParseResult<unknown>;
+}
+export declare function defaults(): DefaultsSource;
+//#endregion

package/dist/sources/defaults.mjs

@@ -0,0 +1,12 @@
+//#region src/sources/defaults.ts
+var DefaultsSource = class {
+	name = "defaults";
+	load(meta) {
+		return meta.schema._parse(void 0);
+	}
+};
+function defaults() {
+	return new DefaultsSource();
+}
+//#endregion
+export { DefaultsSource, defaults };

package/dist/sources/env.d.mts

@@ -0,0 +1,24 @@
+import { SchemaMeta, Source } from "../types.mjs";
+import { ParseResult } from "@nirelc/microtype";
+//#region src/sources/env.d.ts
+export type EnvSourceOptions = {
+  prefix?: string;
+  delimiter?: string;
+  /**
+   * force set the coerce option to true for all schemas
+   * useful, because env variables are always strings, and we want to coerce them to the correct type
+   */
+  forceCoerce?: boolean;
+};
+export declare class EnvSource implements Source {
+  prefix: string;
+  delimiter: string;
+  forceCoerce: boolean;
+  name: string;
+  constructor({ prefix, delimiter, forceCoerce }?: EnvSourceOptions);
+  getKeyByPath(path: PropertyKey[]): string;
+  getValueByPath(path: PropertyKey[]): string | undefined;
+  load(meta: SchemaMeta): ParseResult<unknown> | undefined;
+}
+export declare function env(opts?: EnvSourceOptions): EnvSource;
+//#endregion

package/dist/sources/env.mjs

@@ -0,0 +1,47 @@
+import { insertWordSep } from "../utils.mjs";
+import { DefaultSchema, OptionalSchema } from "@nirelc/microtype";
+//#region src/sources/env.ts
+function enableCoercion(schema) {
+	if (schema instanceof DefaultSchema || schema instanceof OptionalSchema) return enableCoercion(schema.inner);
+	if ("coerce" in schema && typeof schema.coerce === "function") return schema.coerce(true);
+	return schema;
+}
+var EnvSource = class {
+	prefix;
+	delimiter;
+	forceCoerce;
+	name = "env";
+	constructor({ prefix = "", delimiter = "__", forceCoerce = true } = {}) {
+		this.prefix = prefix.trim();
+		this.delimiter = delimiter;
+		this.forceCoerce = forceCoerce;
+	}
+	getKeyByPath(path) {
+		return `${this.prefix}${path.map((p) => {
+			if (typeof p === "string") return insertWordSep(p);
+			return p;
+		}).join(this.delimiter)}`.toUpperCase();
+	}
+	getValueByPath(path) {
+		return process.env[this.getKeyByPath(path)];
+	}
+	load(meta) {
+		const value = this.getValueByPath(meta.path);
+		if (value === void 0) return;
+		const result = (this.forceCoerce ? enableCoercion(meta.schema) : meta.schema)._parse(value);
+		if (result.success) return result;
+		const key = this.getKeyByPath(meta.path);
+		return {
+			success: false,
+			issues: result.issues.map((issue) => ({
+				...issue,
+				key
+			}))
+		};
+	}
+};
+function env(opts) {
+	return new EnvSource(opts);
+}
+//#endregion
+export { EnvSource, env };

package/dist/types.d.mts

@@ -0,0 +1,24 @@
+import { Issue, ParseResult, Schema as Schema$1 } from "@nirelc/microtype";
+//#region src/types.d.ts
+export type Schema = {
+  [key: string]: Schema$1 | Schema;
+};
+export type InferSchema<S extends Schema> = { -readonly [K in keyof S]: S[K] extends Schema$1<infer T> ? T : S[K] extends Schema ? InferSchema<S[K]> : never; };
+export type Config<S extends Schema = Schema> = {
+  schema: S;
+  sources?: Source[];
+};
+export type SchemaMeta = {
+  key: string;
+  path: PropertyKey[];
+  schema: Schema$1;
+};
+export type ConfigIssue = Issue & {
+  source?: string;
+  key?: string;
+};
+export interface Source {
+  name: string;
+  load(meta: SchemaMeta): ParseResult<unknown> | undefined;
+}
+//#endregion

package/dist/types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.mts

@@ -0,0 +1,4 @@
+//#region src/utils.d.ts
+export declare const insertWordSep: (word: string) => string;
+export declare function setObjValueByPath(obj: Record<string, unknown>, path: PropertyKey[], value: unknown): undefined;
+//#endregion

package/dist/utils.mjs

@@ -0,0 +1,17 @@
+import { isRecord } from "./guards/object.mjs";
+//#region src/utils.ts
+const insertWordSep = (word) => {
+	return word.replace(/([a-z0-9])([A-Z])/g, "$1_$2");
+};
+function setObjValueByPath(obj, path, value) {
+	if (!path.length) return;
+	const key = path[0];
+	if (path.length === 1) {
+		obj[key] = value;
+		return;
+	}
+	if (!isRecord(obj[key])) obj[key] = {};
+	return setObjValueByPath(obj[key], path.slice(1), value);
+}
+//#endregion
+export { insertWordSep, setObjValueByPath };

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@nirelc/microconf",
+  "description": "Lightweight and simple type-safety config library over microtype",
+  "author": "Toil",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://github.com/nirelc/microconf#readme",
+  "bugs": {
+    "url": "https://github.com/nirelc/microconf/issues"
+  },
+  "keywords": [
+    "config",
+    "env",
+    "configuration",
+    "conf",
+    "micro",
+    "type",
+    "safe",
+    "system",
+    "typings",
+    "fast",
+    "lightweight",
+    "lib"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "publint": "^0.3.24",
+    "tsdown": "^0.23.0",
+    "typescript": "^7.0.2"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./define": {
+      "types": "./dist/define.d.mts",
+      "import": "./dist/define.mjs"
+    },
+    "./types": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/types.mjs"
+    },
+    "./utils": {
+      "types": "./dist/utils.d.mts",
+      "import": "./dist/utils.mjs"
+    },
+    "./sources/*": {
+      "types": "./dist/sources/*.d.mts",
+      "import": "./dist/sources/*.mjs"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "build:bun": "bunx tsdown"
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "./dist"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@nirelc/microtype": "^0.0.2"
+  }
+}