@btravstack/config

@btravstack/config

Classes

ConfigFieldInvalid

Defined in: packages/config/src/config.ts:78

Why one variable's value is not the value a field wanted — the message ConfigInvalid reports against it.

Extends

TaggedErrorInstance<"ConfigFieldInvalid", { reason: string; }>

Constructors

Constructor

new ConfigFieldInvalid(args): ConfigFieldInvalid;

Defined in: node_modules/.pnpm/unthrown@5.5.0/node_modules/unthrown/dist/index.d.mts:2034

Parameters

Parameter	Type
`args`	`object` & `object`

Returns

ConfigFieldInvalid

Inherited from

TaggedError("ConfigFieldInvalid")<{
  readonly reason: string;
}>.constructor

Properties

Property	Modifier	Type	Overrides	Inherited from	Defined in
`_tag`	`readonly`	`"ConfigFieldInvalid"`	-	`TaggedError("ConfigFieldInvalid")._tag`	node_modules/.pnpm/unthrown@5.5.0/node_modules/unthrown/dist/index.d.mts:2011
`cause?`	`public`	`unknown`	-	`TaggedError("ConfigFieldInvalid").cause`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
`message`	`public`	`string`	`TaggedError("ConfigFieldInvalid").message`	-	packages/config/src/config.ts:81
`name`	`public`	`string`	-	`TaggedError("ConfigFieldInvalid").name`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
`reason`	`readonly`	`string`	-	`TaggedError("ConfigFieldInvalid").reason`	packages/config/src/config.ts:79
`stack?`	`public`	`string`	-	`TaggedError("ConfigFieldInvalid").stack`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076

ConfigInvalid

Defined in: packages/config/src/config.ts:37

A configuration port could not be bound: the environment is wrong, not the code. runMain maps it to sysexits(3)'s EX_CONFIG (78) rather than the generic startup 1, and its message names every offending variable.

Extends

TaggedErrorInstance<"ConfigInvalid", { issues: readonly ConfigIssue[]; port: string; }>

Constructors

Constructor

new ConfigInvalid(args): ConfigInvalid;

Defined in: node_modules/.pnpm/unthrown@5.5.0/node_modules/unthrown/dist/index.d.mts:2034

Parameters

Parameter	Type
`args`	`object` & `object`

Returns

ConfigInvalid

Inherited from

TaggedError("ConfigInvalid")<{
  readonly port: string;
  readonly issues: readonly ConfigIssue[];
}>.constructor

Properties

Property	Modifier	Type	Overrides	Inherited from	Defined in
`_tag`	`readonly`	`"ConfigInvalid"`	-	`TaggedError("ConfigInvalid")._tag`	node_modules/.pnpm/unthrown@5.5.0/node_modules/unthrown/dist/index.d.mts:2011
`cause?`	`public`	`unknown`	-	`TaggedError("ConfigInvalid").cause`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24
`issues`	`readonly`	readonly `ConfigIssue`[]	-	`TaggedError("ConfigInvalid").issues`	packages/config/src/config.ts:39
`message`	`public`	`string`	`TaggedError("ConfigInvalid").message`	-	packages/config/src/config.ts:41
`name`	`public`	`string`	-	`TaggedError("ConfigInvalid").name`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074
`port`	`readonly`	`string`	-	`TaggedError("ConfigInvalid").port`	packages/config/src/config.ts:38
`stack?`	`public`	`string`	-	`TaggedError("ConfigInvalid").stack`	node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076

Env

Defined in: packages/config/src/config.ts:21

The environment, as a service. Twelve-factor configuration is the environment and nothing else, so the kernel provides this port to every graph it boots — process.env by default, StartOptions.env for a test — and a configuration provider is simply a provider that reads it. Nothing else in an application should touch process.env.

Extends

PortInstance<"Env", Readonly<Record<string, string | undefined>>>

Constructors

Constructor

new Env(): Env;

Defined in: packages/di/dist/index.d.mts:15

Returns

Env

Inherited from

Port("Env")<Environment>.constructor

Properties

Property	Modifier	Type	Inherited from	Defined in
`[ID]`	`readonly`	`"Env"`	`Port("Env").[ID]`	packages/di/dist/index.d.mts:11
`[SERVICE]`	`readonly`	`Service`	`Port("Env").[SERVICE]`	packages/di/dist/index.d.mts:12
`portId`	`readonly`	`"Env"`	`Port("Env").portId`	packages/di/dist/index.d.mts:16

Type Aliases

ConfigField

type ConfigField<T> = object;

Defined in: packages/config/src/config.ts:89

One environment variable, read into a value: parse receives the raw string (or undefined when unset) and answers the value or the reason it is not one. Compose them with Config.object.

Type Parameters

Type Parameter
`T`

Properties

Property	Modifier	Type	Defined in
`parse`	`readonly`	(`raw`) => `Result`<`T`, `ConfigFieldInvalid`>	packages/config/src/config.ts:91
`variable`	`readonly`	`string`	packages/config/src/config.ts:90

ConfigIssue

type ConfigIssue = object;

Defined in: packages/config/src/config.ts:27

The one issue shape a configuration schema reports: Standard Schema's Issue, restated structurally so this package depends on nothing.

Properties

Property	Modifier	Type	Defined in
`message`	`readonly`	`string`	packages/config/src/config.ts:28
`path?`	`readonly`	`ReadonlyArray`< \| `PropertyKey` \| { `key`: `PropertyKey`; }>	packages/config/src/config.ts:29

ConfigSchema

type ConfigSchema<Input, Output> = object;

Defined in: packages/config/src/config.ts:60

The slice of Standard Schema (v1) this package speaks — structurally, so a zod, valibot or arktype schema is accepted with no adapter, and so is anything Config.object builds.

Type Parameters

Type Parameter
`Input`
`Output`

Properties

Property	Modifier	Type	Defined in
`~standard`	`readonly`	`object`	packages/config/src/config.ts:61
`~standard.types?`	`readonly`	`object`	packages/config/src/config.ts:73
`~standard.types.input`	`readonly`	`Input`	packages/config/src/config.ts:73
`~standard.types.output`	`readonly`	`Output`	packages/config/src/config.ts:73
`~standard.validate`	`readonly`	(`value`) => \| { `issues?`: `undefined`; `value`: `Output`; } \| { `issues`: readonly `ConfigIssue`[]; } \| `Promise`< \| { `issues?`: `undefined`; `value`: `Output`; } \| { `issues`: readonly `ConfigIssue`[]; }>	packages/config/src/config.ts:64
`~standard.vendor`	`readonly`	`string`	packages/config/src/config.ts:63
`~standard.version`	`readonly`	`1`	packages/config/src/config.ts:62

Environment

type Environment = Readonly<Record<string, string | undefined>>;

Defined in: packages/config/src/config.ts:12

The process environment as it actually arrives: flat, and every value a string or absent.

Variables

Config

const Config: object;

Defined in: packages/config/src/config.ts:142

Configuration, the twelve-factor way: typed values bound from the environment, validated once as the graph is built, and injected like any other service.

Config.object({...}) describes a slice of the environment as a schema (any Standard Schema does as well — a zod object over the raw variables, for instance); Config.provider(Port)(schema) turns it into a di provider that reads Env and answers ConfigInvalid when the environment is wrong. A starter provides its own slice — @btravstack/http binds PORT and HOST onto HttpConfig — and an application binds whatever else it needs onto ports of its own.

Type Declaration

Name	Type	Default value	Description	Defined in
`integer()`	(`variable`, `options`) => `ConfigField`<`number`>	-	A whole number, optionally bounded (both bounds inclusive).	packages/config/src/config.ts:148
`object()`	<`F`>(`fields`) => `ConfigSchema`<`Readonly`<`Record`<`string`, `string` \| `undefined`>>, { readonly [K in string \| number \| symbol]: F[K] extends ConfigField<T> ? T : never }>	-	A record of fields, as a Standard Schema over the environment. Every field is read, so one validation names every offending variable at once — an operator fixes the deployment in one round trip, not one variable per restart. Issues carry the variable name as their `path`.	packages/config/src/config.ts:177
`pinned()`	<`T`>(`value`, `field`) => `ConfigField`<`T`>	-	`field`, unless `value` is given — then a field that answers `value` and reads nothing. What a starter's options do to its own fields: explicit beats environment beats default, per field (`http({ port: 0 })` still reads `HOST`).	packages/config/src/config.ts:168
`port()`	(`variable`, `options`) => `ConfigField`<`number`>	-	A TCP port: a whole number the OS will accept, `0` (an ephemeral bind) included.	packages/config/src/config.ts:159
`provider()`	{ <`P`> (`port`): (`schema`) => `Provider`<`InstanceType`<`P`>, `ConfigInvalid`, `Env`> & `object`; <`Name`> (`name`): <`Output`>(`schema`) => `Provider`<`PortInstance`<`Name`, `Output`>, `ConfigInvalid`, `Env`> & `object`; }	`configProvider`	A provider binding a port from the environment through `schema`. Reads Env — which the kernel provides — so the port is built with the rest of the graph, and a bad environment is a modeled startup `Err` (`ConfigInvalid`, exit code 78 under `runMain`) rather than a crash or, worse, a silently wrong value. Curried like di's own `Provider(port)(…)` and the starters' sugars: the first call names the port, the second says how it is bound. Two forms of the first call. `Config.provider(Port)(schema)` binds a port you declared — the shape for a port that is public API, which a starter or another package names (`HttpConfig`). `Config.provider("RelayConfig")(schema)` mints the port for you — its service is the schema's output — and hands back the provider carrying it: `relayConfig.port` is what a dependent lists in its deps. The shape for a slice that is one application's own, where a class line for the port would name it twice.	packages/config/src/config.ts:235
`string()`	(`variable`, `options`) => `ConfigField`<`string`>	-	A non-empty string.	packages/config/src/config.ts:144

@btravstack/config ​

Classes ​

ConfigFieldInvalid ​

Extends ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Inherited from ​

Properties ​

ConfigInvalid ​

Extends ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Inherited from ​

Properties ​

Env ​

Extends ​

Constructors ​

Constructor ​

Returns ​

Inherited from ​

Properties ​

Type Aliases ​

ConfigField ​

Type Parameters ​

Properties ​

ConfigIssue ​

Properties ​

ConfigSchema ​

Type Parameters ​

Properties ​

Environment ​

Variables ​

Config ​

Type Declaration ​

@btravstack/config

Classes

ConfigFieldInvalid

Extends

Constructors

Constructor

Parameters

Returns

Inherited from

Properties

ConfigInvalid

Extends

Constructors

Constructor

Parameters

Returns

Inherited from

Properties

Env

Extends

Constructors

Constructor

Returns

Inherited from

Properties

Type Aliases

ConfigField

Type Parameters

Properties

ConfigIssue

Properties

ConfigSchema

Type Parameters

Properties

Environment

Variables

Config

Type Declaration