@kleb/config (0.5.0)
Installation
@kleb:registry=npm install @kleb/config@0.5.0"@kleb/config": "0.5.0"About this package
@kleb/config
Typed configuration loading for TypeScript projects.
Use the server builder when the library should own creation, loading, updates, reloads, and saves:
import { field, kConfig } from "@kleb/config/server";
const appConfig = kConfig("server.json")
.fields({
port: field.number().int().min(1).max(65535).default(3000).env("PORT"),
mode: field.enum(["dev", "prod"] as const).default("dev"),
})
.section(
"http",
kConfig("http.json").fields({
host: field.string().default("127.0.0.1"),
enabled: field.boolean().default(true),
}),
);
const config = appConfig.load({ env: process.env, logger });
config.value.port;
config.update((draft) => {
draft.http.host = "0.0.0.0";
});
config.save();
config.reload();
JSON files are strict: a number field must be a JSON number. Environment and CLI
values are parsed only for fields that declare .env() or .cli(). Unknown
file keys are warnings, and saves write the declared config shape.
.env()/.cli() overrides only apply to fields declared directly on a
builder via .field()/.fields() — at the top level or inside a .section().
They are never applied to fields nested inside a composite validator such as
field.object(...), field.array(...), field.record(...), field.tuple(...),
or field.union(...); those inner fields are always sourced from the JSON file
(or an in-memory update/set), regardless of any .env()/.cli() calls on the
inner field definitions.
Boolean fields parsed from an env or CLI source accept a small set of
case-insensitive tokens in addition to true/false: 1/0, yes/no, and
on/off. Any other string throws a ConfigError. Boolean values loaded from
a JSON file must still be a JSON true/false.
Validate caller-provided configuration with any Standard Schema-compatible schema:
import { loadConfig } from "@kleb/config";
const config = loadConfig(schema, {
PORT: "3000",
LOG_LEVEL: "info",
});
Use the server entrypoint to read process.env:
import { loadEnvConfig } from "@kleb/config/server";
const config = loadEnvConfig(schema, {
prefix: "APP_",
});
Prefix filtering strips the prefix by default before validation:
const config = loadEnvConfig(schema, {
prefix: "APP_",
keys: ["PORT", "LOG_LEVEL"],
});
Validation errors keep schema-provided messages on ConfigError.issues, but the thrown
ConfigError.message only reports paths and issue counts. This keeps application logs from
leaking raw configuration values if a schema includes them in its issue text.
Config sources reject unsafe object keys such as __proto__, constructor, and
prototype when loading, merging, parsing CLI/JSON sources, or saving builder-managed
configuration.