---
title: Configuration API
description: Generated public TypeScript reference for @relkit/config.
search:
  exclude: true
sidebar:
  icon: braces
---

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [defineEnv](/docs/api/config#defineenv)

For configuration and examples, read [Environment contracts](/docs/learn/concepts/environment), [local docker](/docs/modules/database/local-docker), [define](/docs/modules/database/define).

For a complete workflow, follow [upload product images](/guides/storage/upload-product-images).

## Public imports

- `@relkit/config` — 37 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                         | Kind  | Import from      | Example                                                                                                          |
| --------------------------------------------------------------------------- | ----- | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| [BindingValueRef](/docs/api/provider#bindingvalueref-type-alias)            | Type  | `@relkit/config` | [Module example](/docs/learn/concepts/environment)                                                               |
| [ConfigOperation](/docs/api/config#configoperation-type-alias)              | Type  | `@relkit/config` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/config/tests/effect-telemetry.test.ts#L14) |
| [ConfigTelemetry](/docs/api/config#configtelemetry-class)                   | Value | `@relkit/config` | [API example](/docs/api/config#configtelemetry-class)                                                            |
| [ConfigTelemetryLive](/docs/api/config#configtelemetrylive)                 | Value | `@relkit/config` | [API example](/docs/api/config#configtelemetrylive)                                                              |
| [ConfigTelemetryService](/docs/api/config#configtelemetryservice-interface) | Type  | `@relkit/config` | [Module example](/docs/learn/concepts/environment)                                                               |
| [ConfigValidationError](/docs/api/config#configvalidationerror-class)       | Value | `@relkit/config` | [API example](/docs/api/config#configvalidationerror-class)                                                      |
| [createEnvRefEffect](/docs/api/config#createenvrefeffect)                   | Value | `@relkit/config` | [API example](/docs/api/config#createenvrefeffect)                                                               |
| [defineEnv](/docs/api/config#defineenv)                                     | Value | `@relkit/config` | [API example](/docs/api/config#defineenv)                                                                        |
| [defineEnvEffect](/docs/api/config#defineenveffect)                         | Value | `@relkit/config` | [API example](/docs/api/config#defineenveffect)                                                                  |
| [env](/docs/api/config#env)                                                 | Value | `@relkit/config` | [API example](/docs/api/config#env)                                                                              |
| [EnvBuilder](/docs/api/config#envbuilder-interface)                         | Type  | `@relkit/config` | [API example](/docs/api/config#envbuilder-interface)                                                             |
| [EnvBuilderBase](/docs/api/config#envbuilderbase-interface)                 | Type  | `@relkit/config` | [API example](/docs/api/config#envbuilderbase-interface)                                                         |
| [EnvBuilderFactory](/docs/api/config#envbuilderfactory-interface)           | Type  | `@relkit/config` | [API example](/docs/api/config#envbuilderfactory-interface)                                                      |
| [EnvDefinition](/docs/api/config#envdefinition-type-alias)                  | Type  | `@relkit/config` | [API example](/docs/api/config#envdefinition-type-alias)                                                         |
| [EnvIssue](/docs/api/config#envissue-interface)                             | Type  | `@relkit/config` | [API example](/docs/api/config#envissue-interface)                                                               |
| [EnvMetadata](/docs/api/config#envmetadata-interface)                       | Type  | `@relkit/config` | [API example](/docs/api/config#envmetadata-interface)                                                            |
| [EnvMetadataMap](/docs/api/config#envmetadatamap-type-alias)                | Type  | `@relkit/config` | [API example](/docs/api/config#envmetadatamap-type-alias)                                                        |
| [EnvProjection](/docs/api/config#envprojection-interface)                   | Type  | `@relkit/config` | [API example](/docs/api/config#envprojection-interface)                                                          |
| [EnvRef](/docs/api/config#envref-interface)                                 | Type  | `@relkit/config` | [API example](/docs/api/config#envref-interface)                                                                 |
| [EnvResolutionError](/docs/api/config#envresolutionerror-class)             | Value | `@relkit/config` | [API example](/docs/api/config#envresolutionerror-class)                                                         |
| [EnvShape](/docs/api/config#envshape-type-alias)                            | Type  | `@relkit/config` | [API example](/docs/api/config#envshape-type-alias)                                                              |
| [EnvSource](/docs/api/config#envsource-type-alias)                          | Type  | `@relkit/config` | [API example](/docs/api/config#envsource-type-alias)                                                             |
| [EnvValueType](/docs/api/config#envvaluetype-type-alias)                    | Type  | `@relkit/config` | [API example](/docs/api/config#envvaluetype-type-alias)                                                          |
| [InferEnvValue](/docs/api/config#inferenvvalue-type-alias)                  | Type  | `@relkit/config` | [API example](/docs/api/config#inferenvvalue-type-alias)                                                         |
| [InferEnvValues](/docs/api/config#inferenvvalues-type-alias)                | Type  | `@relkit/config` | [API example](/docs/api/config#inferenvvalues-type-alias)                                                        |
| [isBindingValueRef](/docs/api/provider#isbindingvalueref)                   | Value | `@relkit/config` | [API example](/docs/api/provider#isbindingvalueref)                                                              |
| [isEnvRef](/docs/api/config#isenvref)                                       | Value | `@relkit/config` | [API example](/docs/api/config#isenvref)                                                                         |
| [isEnvRefEffect](/docs/api/config#isenvrefeffect)                           | Value | `@relkit/config` | [API example](/docs/api/config#isenvrefeffect)                                                                   |
| [JsonValue](/docs/api/config#jsonvalue-type-alias)                          | Type  | `@relkit/config` | [API example](/docs/api/config#jsonvalue-type-alias)                                                             |
| [LiteralValue](/docs/api/config#literalvalue-type-alias)                    | Type  | `@relkit/config` | [API example](/docs/api/config#literalvalue-type-alias)                                                          |
| [parseEnvBuilderEffect](/docs/api/config#parseenvbuildereffect)             | Value | `@relkit/config` | [API example](/docs/api/config#parseenvbuildereffect)                                                            |
| [projectEnv](/docs/api/config#projectenv-1)                                 | Value | `@relkit/config` | [API example](/docs/api/config#projectenv-1)                                                                     |
| [projectEnvEffect](/docs/api/config#projectenveffect-1)                     | Value | `@relkit/config` | [API example](/docs/api/config#projectenveffect-1)                                                               |
| [ResolvedEnv](/docs/api/config#resolvedenv-type-alias)                      | Type  | `@relkit/config` | [API example](/docs/api/config#resolvedenv-type-alias)                                                           |
| [resolveEnv](/docs/api/config#resolveenv-1)                                 | Value | `@relkit/config` | [API example](/docs/api/config#resolveenv-1)                                                                     |
| [resolveEnvEffect](/docs/api/config#resolveenveffect-1)                     | Value | `@relkit/config` | [API example](/docs/api/config#resolveenveffect-1)                                                               |
| [ResolveEnvOptions](/docs/api/config#resolveenvoptions-interface)           | Type  | `@relkit/config` | [API example](/docs/api/config#resolveenvoptions-interface)                                                      |

## `config-observability.ts`

### ConfigOperation

**Signature**

```ts
declare const ConfigOperation: ConfigOperation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/config-observability.ts#L4)

### ConfigTelemetry (class)

Injectable telemetry for environment operations.

**Example**

```ts
Effect.provide(resolveEnvEffect(definition, options), ConfigTelemetryLive);
```

**Signature**

```ts
declare class ConfigTelemetry
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/config-observability.ts#L9)

### ConfigTelemetryLive

Live spans and bounded operation metrics.

**Example**

```ts
Effect.runSync(Effect.provide(projectEnvEffect(definition), ConfigTelemetryLive));
```

**Signature**

```ts
declare const ConfigTelemetryLive: Layer.Layer<ConfigTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/config-observability.ts#L16)

### ConfigTelemetryService

**Signature**

```ts
declare const ConfigTelemetryService: ConfigTelemetryService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/config-observability.ts#L4)

### observeConfig

Observe an Effect operation with a stable span and operation metrics.

**Example**

```ts
observeConfig("project", Effect.succeed([]));
```

**Signature**

```ts
declare const observeConfig: <A, E, R>(
  operation: ConfigOperation,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/config-observability.ts#L30)

### runConfigSync

Run a synchronous compatibility adapter while retaining its original failure.

**Throws**

The domain error, original defect, or mapped compatibility TypeError.

**Example**

```ts
runConfigSync(Effect.succeed("ready"));
```

**Signature**

```ts
declare const runConfigSync: <A, E>(effect: Effect.Effect<A, E>) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/config-observability.ts#L69)

## `config-observability.types.ts`

### ConfigOperation (type alias)

Stable, bounded names for environment configuration operations.

**Signature**

```ts
type ConfigOperation =
  | "define"
  | "resolve"
  | "resolve-provider"
  | "project"
  | "is-ref"
  | "create-ref"
  | "json-value"
  | "parse-number"
  | "parse-port"
  | "parse-boolean"
  | "parse-literal"
  | "builder-create"
  | "builder-get-default"
  | "builder-parse"
  | "builder-literal"
  | "builder-or-binding"
  | "parse-url"
  | "parse-json"
  | "builder-default"
  | "builder-optional"
  | "builder-required-in"
  | "builder-description"
  | "builder-example";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/config-observability.types.ts#L4)

### ConfigTelemetryService (interface)

Substitutable observer used by the config Effect operations.

**Signature**

```ts
export interface ConfigTelemetryService {
  /** Observe one operation without changing its success or error.
   * @param operation - Stable bounded operation name.
   * @param effect - Effect to instrument.
   * @returns The original Effect success and error channels.
   * @example observe("resolve", Effect.succeed({ MODE: "test" }));
   */
  readonly observe: <A, E, R>(
    operation: ConfigOperation,
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E, R>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/config-observability.types.ts#L30)

## `config-validation-error.ts`

### ConfigValidationError (class)

Expected invalid config declaration or value with a stable failure tag.

**Example**

```ts
new ConfigValidationError({ message: "Expected a finite number" });
```

**Signature**

```ts
declare class ConfigValidationError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/config-validation-error.ts#L6)

## `env-builder-metadata.ts`

### metadata

Build initial immutable metadata inside the observed builder creation.

**Example**

```ts
metadata("string", false);
```

**Signature**

```ts
declare const metadata: (
  type: EnvValueType,
  sensitive: boolean,
  values?: readonly LiteralValue[],
) => EnvMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-builder-metadata.ts#L10)

### updateMetadata

Copy metadata inside an observed fluent builder operation.

**Example**

```ts
updateMetadata(env.string().metadata, { optional: true });
```

**Signature**

```ts
declare const updateMetadata: (value: EnvMetadata, changes: Record<string, unknown>) => EnvMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-builder-metadata.ts#L31)

## `env-builder.ts`

### createEnvBuilder

Create a field builder synchronously for existing callers.

**Example**

```ts
createEnvBuilder("string", (value) => value);
```

**Signature**

```ts
declare const createEnvBuilder: <T>(
  type: EnvValueType,
  parse: Parse<T>,
  sensitive?: boolean,
  values?: readonly LiteralValue[],
) => EnvBuilder<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-builder.ts#L190)

### createEnvBuilderEffect

Create a frozen field builder through the Effect path.

**Example**

```ts
Effect.runSync(createEnvBuilderEffect("string", (value) => value));
```

**Signature**

```ts
declare const createEnvBuilderEffect: <T>(
  type: EnvValueType,
  parse: Parse<T>,
  sensitive?: boolean,
  values?: readonly LiteralValue[],
) => Effect.Effect<EnvBuilder<T>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-builder.ts#L170)

### parseEnvBuilderEffect

Parse a builder's raw input through an observable, typed Effect.

**Example**

```ts
Effect.runSync(parseEnvBuilderEffect(Number, "2"));
```

**Signature**

```ts
declare const parseEnvBuilderEffect: <T>(
  parse: Parse<T>,
  value: string,
) => Effect.Effect<Exclude<T, undefined>, ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-builder.ts#L131)

## `env-builder.types.ts`

Synchronous parser type retained for public field compatibility.

**Example**

```ts
const parse: Parse<number> = Number;
```

### DefaultFactory (type alias)

Lazy default factory type invoked only when source input is absent.

**Example**

```ts
const fallback: DefaultFactory<string> = () => "test";
```

**Signature**

```ts
type DefaultFactory<T> = () => Exclude<T, undefined>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-builder.types.ts#L9)

### Parse (type alias)

Synchronous parser type retained for public field compatibility.

**Example**

```ts
const parse: Parse<number> = Number;
```

**Signature**

```ts
type Parse<T> = (value: string) => Exclude<T, undefined>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-builder.types.ts#L4)

## `env-factory.ts`

### bindingOrBuilderEffect

Build an environment field or a named binding reference.

**Example**

```ts
Effect.runSync(bindingOrBuilderEffect(undefined, "string", (value) => value));
```

**Signature**

```ts
declare const bindingOrBuilderEffect: <Value>(
  name: string | undefined,
  type: BindingValueType,
  parse: (value: string) => Exclude<Value, undefined>,
  sensitive?: boolean,
) => Effect.Effect<EnvBuilder<Value> | BindingValueRef<string, Value>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-factory.ts#L80)

### env

Factory of value-free fields and named binding-local references.

**Example**

```ts
const declaration = defineEnv({ MODE: env.string() });
```

**Signature**

```ts
declare const env: EnvBuilderFactory;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-factory.ts#L14)

### literalBuilderEffect

Build a literal field while rejecting non-finite choices.

**Example**

```ts
Effect.runSync(literalBuilderEffect("test", "prod"));
```

**Signature**

```ts
declare const literalBuilderEffect: <
  const Values extends readonly [LiteralValue, ...LiteralValue[]],
>(
  ...values: Values
) => Effect.Effect<EnvBuilder<Values[number]>, ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-factory.ts#L50)

### parseJsonEffect

Parse JSON and normalize it to immutable metadata-safe values.

**Example**

```ts
Effect.runSync(parseJsonEffect('{"count":2}'));
```

**Signature**

```ts
declare const parseJsonEffect: (
  value: string,
) => Effect.Effect<JsonValue, ConfigValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-factory.ts#L125)

### parseUrlEffect

Parse a URL with a tagged failure for malformed input.

**Example**

```ts
Effect.runSync(parseUrlEffect("https://example.test"));
```

**Signature**

```ts
declare const parseUrlEffect: (value: string) => Effect.Effect<URL, ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-factory.ts#L100)

## `env-factory.types.ts`

### EnvBuilderFactory (interface)

Public overloads for field builders and named binding references.
Calling without a name declares a field; passing a name creates a binding reference.

**Example**

```ts
const mode = env.string();
const cache = env.secret("CACHE_URL");
```

**Signature**

```ts
export interface EnvBuilderFactory {
  /** Declare a string field.
   * @returns A string builder.
   * @example env.string();
   */
  string(): EnvBuilder<string>;
  /** Reference a named string binding.
   * @param name - Binding environment name.
   * @returns A value-free string binding reference.
   * @example env.string("MODE");
   */
  string<const Name extends string>(name: Name): BindingValueRef<Name, string, "string">;
  /** Declare a finite number field.
   * @returns A number builder.
   * @example env.number();
   */
  number(): EnvBuilder<number>;
  /** Reference a named number binding.
   * @param name - Binding environment name.
   * @returns A number binding reference.
   * @example env.number("RETRIES");
   */
  number<const Name extends string>(name: Name): BindingValueRef<Name, number, "number">;
  /** Declare an exact Boolean field.
   * @returns A Boolean builder.
   * @example env.boolean();
   */
  boolean(): EnvBuilder<boolean>;
  /** Reference a named Boolean binding.
   * @param name - Binding environment name.
   * @returns A Boolean binding reference.
   * @example env.boolean("ENABLED");
   */
  boolean<const Name extends string>(name: Name): BindingValueRef<Name, boolean, "boolean">;
  /** Declare a TCP port field.
   * @returns A port builder.
   * @example env.port();
   */
  port(): EnvBuilder<number>;
  /** Reference a named port binding.
   * @param name - Binding environment name.
   * @returns A port binding reference.
   * @example env.port("SERVICE_PORT");
   */
  port<const Name extends string>(name: Name): BindingValueRef<Name, number, "port">;
  /** Declare finite literal choices.
   * @param values - Nonempty list of allowed choices.
   * @returns A literal builder.
   * @throws TypeError when a numeric choice is not finite.
   * @example env.literal("test", "production");
   */
  literal<const Values extends readonly [LiteralValue, ...LiteralValue[]]>(
    ...values: Values
  ): EnvBuilder<Values[number]>;
  /** Declare a URL field.
   * @returns A URL builder.
   * @example env.url();
   */
  url(): EnvBuilder<URL>;
  /** Reference a named URL binding.
   * @param name - Binding environment name.
   * @returns A URL binding reference.
   * @example env.url("ORIGIN");
   */
  url<const Name extends string>(name: Name): BindingValueRef<Name, URL, "url">;
  /** Declare a JSON field.
   * @returns A JSON builder.
   * @example env.json();
   */
  json(): EnvBuilder<JsonValue>;
  /** Reference a named JSON binding.
   * @param name - Binding environment name.
   * @returns A JSON binding reference.
   * @example env.json("SETTINGS");
   */
  json<const Name extends string>(name: Name): BindingValueRef<Name, JsonValue, "json">;
  /** Declare a sensitive string field.
   * @returns A secret string builder.
   * @example env.secret();
   */
  secret(): EnvBuilder<string>;
  /** Reference a named secret binding.
   * @param name - Binding environment name.
   * @returns A secret binding reference.
   * @example env.secret("API_TOKEN");
   */
  secret<const Name extends string>(name: Name): BindingValueRef<Name, string, "secret-string">;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-factory.types.ts#L9)

## `env-json.ts`

### JsonValue

**Signature**

```ts
declare const JsonValue: JsonValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-json.ts#L6)

### toJsonValue

Convert an example synchronously for existing callers.

**Throws**

TypeError for unsupported values or accessors.

**Example**

```ts
toJsonValue({ count: 2 });
```

**Signature**

```ts
declare const toJsonValue: (value: unknown) => JsonValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-json.ts#L23)

### toJsonValueEffect

Convert declaration examples to immutable, JSON-safe values.

**Example**

```ts
Effect.runSync(toJsonValueEffect({ count: 2 }));
```

**Signature**

```ts
declare const toJsonValueEffect: (
  value: unknown,
) => Effect.Effect<JsonValue, ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-json.ts#L13)

## `env-json.types.ts`

Deeply JSON-safe value suitable for declaration metadata.

**Example**

```ts
const example: JsonValue = { enabled: true };
```

### JsonValue (type alias)

Deeply JSON-safe value suitable for declaration metadata.

**Example**

```ts
const example: JsonValue = { enabled: true };
```

**Signature**

```ts
type JsonValue =
  string | number | boolean | null | readonly JsonValue[] | { readonly [key: string]: JsonValue };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-json.types.ts#L4)

## `env-parsers.ts`

### parseBoolean

Parse an exact Boolean synchronously.

**Throws**

TypeError for any other token.

**Example**

```ts
parseBoolean("false");
```

**Signature**

```ts
declare const parseBoolean: (value: string) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-parsers.ts#L88)

### parseBooleanEffect

Parse an exact Boolean environment token.

**Example**

```ts
Effect.runSync(parseBooleanEffect("true"));
```

**Signature**

```ts
declare const parseBooleanEffect: (value: string) => Effect.Effect<boolean, ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-parsers.ts#L71)

### parseLiteral

Match a literal synchronously.

**Throws**

TypeError when there is no match.

**Example**

```ts
parseLiteral("test", ["test", "prod"]);
```

**Signature**

```ts
declare const parseLiteral: <T extends LiteralValue>(value: string, values: readonly T[]) => T;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-parsers.ts#L123)

### parseLiteralEffect

Match a raw value against declared literal choices.

**Example**

```ts
Effect.runSync(parseLiteralEffect("test", ["test", "prod"]));
```

**Signature**

```ts
declare const parseLiteralEffect: <T extends LiteralValue>(
  value: string,
  values: readonly T[],
) => Effect.Effect<T, ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-parsers.ts#L98)

### parseNumber

Parse a finite number synchronously.

**Throws**

TypeError when the value is not finite.

**Example**

```ts
parseNumber("42");
```

**Signature**

```ts
declare const parseNumber: (value: string) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-parsers.ts#L32)

### parseNumberEffect

Parse a finite number from an environment string.

**Example**

```ts
Effect.runSync(parseNumberEffect("42"));
```

**Signature**

```ts
declare const parseNumberEffect: (value: string) => Effect.Effect<number, ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-parsers.ts#L11)

### parsePort

Parse a TCP port synchronously.

**Throws**

TypeError for an invalid port.

**Example**

```ts
parsePort("3000");
```

**Signature**

```ts
declare const parsePort: (value: string) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-parsers.ts#L62)

### parsePortEffect

Parse a TCP port from an environment string.

**Example**

```ts
Effect.runSync(parsePortEffect("3000"));
```

**Signature**

```ts
declare const parsePortEffect: (value: string) => Effect.Effect<number, ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-parsers.ts#L41)

## `env-ref.ts`

### createEnvRef

Create a field reference synchronously for a declaration.

**Example**

```ts
createEnvRef("MODE", env.string());
```

**Signature**

```ts
declare const createEnvRef: <Name extends string, Value>(
  name: Name,
  field: EnvBuilderBase,
) => EnvRef<Name, Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-ref.ts#L65)

### createEnvRefEffect

Create an immutable typed field reference.

**Example**

```ts
Effect.runSync(createEnvRefEffect("MODE", env.string()));
```

**Signature**

```ts
declare const createEnvRefEffect: <Name extends string, Value>(
  name: Name,
  field: EnvBuilderBase,
) => Effect.Effect<EnvRef<Name, Value>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-ref.ts#L40)

### isEnvRef

Check a reference synchronously for existing callers.

**Example**

```ts
isEnvRef(definition.MODE);
```

**Signature**

```ts
declare const isEnvRef: (value: unknown) => value is EnvRef;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-ref.ts#L30)

### isEnvRefEffect

Check whether a value is a typed environment reference.

**Example**

```ts
Effect.runSync(isEnvRefEffect(definition.MODE));
```

**Signature**

```ts
declare const isEnvRefEffect: (value: unknown) => Effect.Effect<boolean>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-ref.ts#L10)

## `env-resolution-error.ts`

### EnvResolutionError (class)

Tagged failure containing ordered field issues.

**Example**

```ts
new EnvResolutionError([
  { name: "TOKEN", code: "missing", message: "Required value is missing", sensitive: true },
]);
```

**Signature**

```ts
declare class EnvResolutionError {
  constructor(issues: readonly EnvIssue[]);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-resolution-error.ts#L7)

### name (property)

**Signature**

```ts
readonly name: "EnvResolutionError"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-resolution-error.ts#L11)

## `env.ts`

### defineEnv

Build a declaration synchronously for existing callers.

**Throws**

TypeError for a reserved name or invalid builder.

**Example**

```ts
import { defineEnv, env } from "@relkit/config";
const environment = defineEnv({ MODE: env.string().default("development") });
```

**Signature**

```ts
declare const defineEnv: <const S extends EnvShape>(
  shape: S & { readonly PORT?: never; readonly RELKIT_ENV?: never },
) => EnvDefinition<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L105)

Since v0.1.0

### BindingValueRef

**Signature**

```ts
declare const BindingValueRef: BindingValueRef<Name, Value, Type>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L14)

### EnvBuilder

**Signature**

```ts
declare const EnvBuilder: EnvBuilder<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L11)

### EnvBuilderBase

**Signature**

```ts
declare const EnvBuilderBase: EnvBuilderBase;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L12)

### EnvBuilderFactory

**Signature**

```ts
declare const EnvBuilderFactory: EnvBuilderFactory;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L13)

### EnvDefinition

**Signature**

```ts
declare const EnvDefinition: EnvDefinition<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L15)

### EnvMetadata

**Signature**

```ts
declare const EnvMetadata: EnvMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L16)

### EnvMetadataMap

**Signature**

```ts
declare const EnvMetadataMap: EnvMetadataMap<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L17)

### EnvRef

**Signature**

```ts
declare const EnvRef: EnvRef<Name, Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L20)

### EnvShape

**Signature**

```ts
declare const EnvShape: EnvShape;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L18)

### EnvValueType

**Signature**

```ts
declare const EnvValueType: EnvValueType;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L19)

### InferEnvValue

**Signature**

```ts
declare const InferEnvValue: InferEnvValue<B>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L21)

### InferEnvValues

**Signature**

```ts
declare const InferEnvValues: InferEnvValues<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L22)

### JsonValue

**Signature**

```ts
declare const JsonValue: JsonValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L9)

### LiteralValue

**Signature**

```ts
declare const LiteralValue: LiteralValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L23)

### defineEnvEffect

Build an immutable declaration without reading runtime values.

**Example**

```ts
Effect.runSync(defineEnvEffect({ MODE: env.string() }));
```

**Signature**

```ts
declare const defineEnvEffect: <const S extends EnvShape>(
  shape: S & { readonly PORT?: never; readonly RELKIT_ENV?: never },
) => Effect.Effect<EnvDefinition<S>, ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L31)

### env

**Signature**

```ts
declare const env: EnvBuilderFactory;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L7)

### isEnvRef

**Signature**

```ts
declare const isEnvRef: (value: unknown) => value is EnvRef;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L8)

## `env.types.ts`

### BindingValueRef

**Signature**

```ts
declare const BindingValueRef: BindingValueRef<Name, Value, Type>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L3)

### EnvBuilder (interface)

Value-free field declaration with immutable fluent metadata methods.
Every method returns a new frozen builder; the original remains unchanged.

**Example**

```ts
const mode = env.string().default("test").description("Runtime mode");
```

**Signature**

```ts
export interface EnvBuilder<T> extends EnvBuilderBase {
  readonly parse: (value: string) => Exclude<T, undefined>;
  readonly getDefault: () => Exclude<T, undefined> | undefined;
  /** Attach a lazy or literal default.
   * @param value - Default literal or factory, invoked during resolution.
   * @returns A new builder whose value is required when present.
   * @example env.string().default("test");
   */
  default(
    value: Exclude<T, undefined> | (() => Exclude<T, undefined>),
  ): EnvBuilder<Exclude<T, undefined>>;
  /** Allow absence outside explicitly required environments.
   * @returns A new builder whose value may be undefined.
   * @example env.string().optional();
   */
  optional(): EnvBuilder<T | undefined>;
  /** Require the field in named environments.
   * @param environments - Environment names, with duplicates removed.
   * @returns A new builder with merged requirement metadata.
   * @throws TypeError when a name is empty.
   * @example env.string().requiredIn("production");
   */
  requiredIn(...environments: readonly string[]): EnvBuilder<T>;
  /** Add human-readable field guidance.
   * @param text - Description shown in metadata.
   * @returns A new builder with a description.
   * @example env.string().description("Public origin");
   */
  description(text: string): EnvBuilder<T>;
  /** Add a JSON-safe example, redacting sensitive fields.
   * @param value - Example value.
   * @returns A new builder with example metadata.
   * @throws TypeError when a public example is not JSON-safe.
   * @example env.url().example(new URL("https://example.test"));
   */
  example(value: T): EnvBuilder<T>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L71)

### EnvBuilderBase (interface)

Minimum builder contract used during resolution.
`parse` and `getDefault` remain synchronous compatibility callbacks.

**Example**

```ts
const field: EnvBuilderBase = env.string();
```

**Signature**

```ts
export interface EnvBuilderBase {
  readonly kind: "env-builder";
  readonly metadata: EnvMetadata;
  /** Parse a raw string through the field's Effect-backed compatibility adapter.
   * @param value - Raw environment value.
   * @returns Parsed field value.
   * @throws TypeError for invalid built-in values; custom parsers may throw.
   * @example env.number().parse("2");
   */
  readonly parse: (value: string) => unknown;
  /** Produce a lazy default only when resolution needs it.
   * @returns Default value or undefined.
   * @throws A user default factory's original error.
   * @example env.string().default("test").getDefault();
   */
  readonly getDefault: () => unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L49)

### EnvBuilderFactory

**Signature**

```ts
declare const EnvBuilderFactory: EnvBuilderFactory;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L4)

### EnvDefinition (type alias)

Immutable, value-free declaration returned by `defineEnv`.
Field references are non-enumerable; shape and metadata are frozen.

**Example**

```ts
const declaration: EnvDefinition<{ MODE: EnvBuilder<string> }> = defineEnv({ MODE: env.string() });
```

**Signature**

```ts
type EnvDefinition<S extends EnvShape> = {
  readonly kind: "env-definition";
  readonly shape: S;
  readonly metadata: EnvMetadataMap<S>;
} & {
  readonly [K in keyof S]: EnvRef<K & string, InferEnvValue<S[K]>>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L134)

### EnvMetadata (interface)

JSON-safe metadata emitted by an environment declaration.
Defaults are represented by `hasDefault` and never exposed here.

**Example**

```ts
const metadata = env.secret().metadata;
```

**Signature**

```ts
export interface EnvMetadata {
  readonly type: EnvValueType;
  readonly requiredIn: readonly string[];
  readonly hasDefault: boolean;
  readonly optional: boolean;
  readonly sensitive: boolean;
  readonly values?: readonly LiteralValue[];
  readonly description?: string;
  readonly example?: JsonValue;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L21)

### EnvMetadataMap (type alias)

Infer a metadata map from a declaration shape.

**Example**

```ts
type Metadata = EnvMetadataMap<{ MODE: EnvBuilder<string> }>;
```

**Signature**

```ts
type EnvMetadataMap<S extends EnvShape> = {
  readonly [K in keyof S]: EnvMetadata;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L126)

### EnvRef (interface)

Typed, value-free reference to one declared variable.
`__value` is phantom typing; the declaration never reads source values.

**Example**

```ts
const reference = defineEnv({ MODE: env.string() }).MODE;
```

**Signature**

```ts
export interface EnvRef<Name extends string = string, Value = unknown> {
  readonly kind: "env-ref";
  readonly name: Name;
  readonly type: EnvValueType;
  readonly sensitive: boolean;
  readonly metadata: EnvMetadata;
  readonly __value?: Value;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L36)

### EnvShape (type alias)

Map field names to builders without reading runtime values.

**Example**

```ts
const shape: EnvShape = { MODE: env.string() };
```

**Signature**

```ts
type EnvShape = { readonly [name: string]: EnvBuilderBase };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L112)

### EnvValueType (type alias)

Stable field type emitted in metadata.

**Example**

```ts
const type: EnvValueType = "secret-string";
```

**Signature**

```ts
type EnvValueType =
  "string" | "number" | "boolean" | "port" | "literal" | "url" | "json" | "secret-string";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L14)

### InferEnvValue (type alias)

Extract a field builder's resolved value type.

**Example**

```ts
type Mode = InferEnvValue<ReturnType<typeof env.string>>;
```

**Signature**

```ts
type InferEnvValue<B> = B extends EnvBuilder<infer T> ? T : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L116)

### InferEnvValues (type alias)

Infer the immutable runtime value object from a declaration shape.

**Example**

```ts
type Values = InferEnvValues<{ MODE: EnvBuilder<string> }>;
```

**Signature**

```ts
type InferEnvValues<S extends EnvShape> = {
  readonly [K in keyof S]: InferEnvValue<S[K]>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L120)

### LiteralValue (type alias)

Scalar literals accepted by `env.literal`.

**Example**

```ts
env.literal("test", "production");
```

**Signature**

```ts
type LiteralValue = string | number | boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L9)

## `index.ts`

### BindingValueRef

**Signature**

```ts
declare const BindingValueRef: BindingValueRef<Name, Value, Type>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L9)

### ConfigOperation

**Signature**

```ts
declare const ConfigOperation: ConfigOperation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L4)

### ConfigTelemetry

**Signature**

```ts
declare const ConfigTelemetry: typeof ConfigTelemetry;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L3)

### ConfigTelemetryLive

**Signature**

```ts
declare const ConfigTelemetryLive: Layer<ConfigTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L3)

### ConfigTelemetryService

**Signature**

```ts
declare const ConfigTelemetryService: ConfigTelemetryService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L4)

### ConfigValidationError

**Signature**

```ts
declare const ConfigValidationError: typeof ConfigValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L5)

### EnvBuilder

**Signature**

```ts
declare const EnvBuilder: EnvBuilder<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L10)

### EnvBuilderBase

**Signature**

```ts
declare const EnvBuilderBase: EnvBuilderBase;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L11)

### EnvBuilderFactory

**Signature**

```ts
declare const EnvBuilderFactory: EnvBuilderFactory;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L12)

### EnvDefinition

**Signature**

```ts
declare const EnvDefinition: EnvDefinition<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L13)

### EnvIssue

**Signature**

```ts
declare const EnvIssue: EnvIssue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L32)

### EnvMetadata

**Signature**

```ts
declare const EnvMetadata: EnvMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L14)

### EnvMetadataMap

**Signature**

```ts
declare const EnvMetadataMap: EnvMetadataMap<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L15)

### EnvProjection

**Signature**

```ts
declare const EnvProjection: EnvProjection;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L33)

### EnvRef

**Signature**

```ts
declare const EnvRef: EnvRef<Name, Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L18)

### EnvResolutionError

**Signature**

```ts
declare const EnvResolutionError: typeof EnvResolutionError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L25)

### EnvShape

**Signature**

```ts
declare const EnvShape: EnvShape;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L16)

### EnvSource

**Signature**

```ts
declare const EnvSource: Readonly<Record<string, string | undefined>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L34)

### EnvValueType

**Signature**

```ts
declare const EnvValueType: EnvValueType;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L17)

### InferEnvValue

**Signature**

```ts
declare const InferEnvValue: InferEnvValue<B>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L19)

### InferEnvValues

**Signature**

```ts
declare const InferEnvValues: InferEnvValues<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L20)

### JsonValue

**Signature**

```ts
declare const JsonValue: JsonValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L21)

### LiteralValue

**Signature**

```ts
declare const LiteralValue: LiteralValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L22)

### ResolveEnvOptions

**Signature**

```ts
declare const ResolveEnvOptions: ResolveEnvOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L35)

### ResolvedEnv

**Signature**

```ts
declare const ResolvedEnv: Readonly<InferEnvValues<S>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L36)

### createEnvRefEffect

**Signature**

```ts
declare const createEnvRefEffect: <Name extends string, Value>(
  name: Name,
  field: EnvBuilderBase,
) => Effect<EnvRef<Name, Value>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L2)

### defineEnv

**Signature**

```ts
declare const defineEnv: <const S extends EnvShape>(
  shape: S & { readonly PORT?: never; readonly RELKIT_ENV?: never },
) => EnvDefinition<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L1)

### defineEnvEffect

**Signature**

```ts
declare const defineEnvEffect: <const S extends EnvShape>(
  shape: S & { readonly PORT?: never; readonly RELKIT_ENV?: never },
) => Effect<EnvDefinition<S>, ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L1)

### env

**Signature**

```ts
declare const env: EnvBuilderFactory;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L1)

### isBindingValueRef

**Signature**

```ts
declare const isBindingValueRef: (value: unknown) => value is BindingValueRef;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L7)

### isEnvRef

**Signature**

```ts
declare const isEnvRef: (value: unknown) => value is EnvRef;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L1)

### isEnvRefEffect

**Signature**

```ts
declare const isEnvRefEffect: (value: unknown) => Effect<boolean>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L2)

### parseEnvBuilderEffect

**Signature**

```ts
declare const parseEnvBuilderEffect: <T>(
  parse: Parse<T>,
  value: string,
) => Effect<Exclude<T, undefined>, ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L6)

### projectEnv

**Signature**

```ts
declare const projectEnv: <S extends EnvShape>(
  definition: EnvDefinition<S>,
) => readonly EnvProjection[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L26)

### projectEnvEffect

**Signature**

```ts
declare const projectEnvEffect: <S extends EnvShape>(
  definition: EnvDefinition<S>,
) => Effect<readonly EnvProjection[], ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L27)

### resolveEnv

**Signature**

```ts
declare const resolveEnv: <S extends EnvShape>(
  definition: EnvDefinition<S>,
  options: ResolveEnvOptions,
) => ResolvedEnv<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L28)

### resolveEnvEffect

**Signature**

```ts
declare const resolveEnvEffect: <S extends EnvShape>(
  definition: EnvDefinition<S>,
  options: ResolveEnvOptions,
) => Effect<ResolvedEnv<S>, ConfigValidationError | EnvResolutionError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L29)

## `config.ts`

### resolveEnvWithEffect

Promise compatibility adapter for the internal ConfigProvider bridge.

**Example**

```ts
await resolveEnvWithEffect(definition, { MODE: "test" }, "test");
```

**Signature**

```ts
declare const resolveEnvWithEffect: <S extends EnvShape>(
  definition: EnvDefinition<S>,
  source: EnvSource,
  environment: string,
) => Promise<ResolvedEnv<S>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/internal/config.ts#L39)

### resolveEnvWithEffectEffect

Resolve through an explicit Effect ConfigProvider.

**Example**

```ts
Effect.runPromise(resolveEnvWithEffectEffect(definition, { MODE: "test" }, "test"));
```

**Signature**

```ts
declare const resolveEnvWithEffectEffect: <S extends EnvShape>(
  definition: EnvDefinition<S>,
  source: EnvSource,
  environment: string,
) => Effect.Effect<ResolvedEnv<S>, Config.ConfigError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/internal/config.ts#L18)

## `resolve-helpers.ts`

### definitionIssue

Check the declaration shape before reading field callbacks.

**Example**

```ts
definitionIssue(defineEnv({ MODE: env.string() }));
```

**Signature**

```ts
declare const definitionIssue: (value: unknown) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve-helpers.ts#L9)

### optionsIssue

Check an explicit environment name and source map.

**Example**

```ts
optionsIssue({ environment: "test", source: {} });
```

**Signature**

```ts
declare const optionsIssue: (options: ResolveEnvOptions) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve-helpers.ts#L31)

### resolveField

Resolve one field while appending issues in declaration order.

**Example**

```ts
resolveField("MODE", env.string(), { MODE: "test" }, "test", values, issues);
```

**Signature**

```ts
declare const resolveField: (
  name: string,
  builder: EnvBuilderBase,
  source: EnvSource,
  environment: string,
  values: Record<string, unknown>,
  issues: EnvIssue[],
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve-helpers.ts#L54)

## `resolve.ts`

### EnvIssue

**Signature**

```ts
declare const EnvIssue: EnvIssue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.ts#L11)

### EnvProjection

**Signature**

```ts
declare const EnvProjection: EnvProjection;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.ts#L12)

### EnvResolutionError

**Signature**

```ts
declare const EnvResolutionError: typeof EnvResolutionError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.ts#L9)

### EnvSource

**Signature**

```ts
declare const EnvSource: Readonly<Record<string, string | undefined>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.ts#L13)

### ResolveEnvOptions

**Signature**

```ts
declare const ResolveEnvOptions: ResolveEnvOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.ts#L14)

### ResolvedEnv

**Signature**

```ts
declare const ResolvedEnv: Readonly<InferEnvValues<S>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.ts#L15)

### projectEnv

Project metadata synchronously for existing callers.

**Throws**

TypeError for a malformed definition.

**Example**

```ts
projectEnv(defineEnv({ MODE: env.string() }));
```

**Signature**

```ts
declare const projectEnv: <S extends EnvShape>(
  definition: EnvDefinition<S>,
) => readonly EnvProjection[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.ts#L97)

### projectEnvEffect

Project sorted, JSON-safe metadata without source values.

**Example**

```ts
Effect.runSync(projectEnvEffect(defineEnv({ MODE: env.string() })));
```

**Signature**

```ts
declare const projectEnvEffect: <S extends EnvShape>(
  definition: EnvDefinition<S>,
) => Effect.Effect<readonly EnvProjection[], ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.ts#L74)

### resolveEnv

Resolve a declaration synchronously for existing callers.

**Throws**

TypeError for invalid inputs; EnvResolutionError for field issues.

**Example**

```ts
resolveEnv(defineEnv({ MODE: env.string() }), { environment: "test", source: { MODE: "ready" } });
```

**Signature**

```ts
declare const resolveEnv: <S extends EnvShape>(
  definition: EnvDefinition<S>,
  options: ResolveEnvOptions,
) => ResolvedEnv<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.ts#L62)

### resolveEnvEffect

Resolve all declared values with ordered, typed failures.

**Example**

```ts
Effect.runSync(
  resolveEnvEffect(defineEnv({ MODE: env.string() }), {
    environment: "test",
    source: { MODE: "ready" },
  }),
);
```

**Signature**

```ts
declare const resolveEnvEffect: <S extends EnvShape>(
  definition: EnvDefinition<S>,
  options: ResolveEnvOptions,
) => Effect.Effect<ResolvedEnv<S>, ConfigValidationError | EnvResolutionError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.ts#L24)

## `resolve.types.ts`

### EnvIssue (interface)

One invalid or missing declared field.
Sensitive messages are redacted before an issue is exposed.

**Example**

```ts
const issue: EnvIssue = {
  name: "MODE",
  code: "missing",
  message: "Required value is missing",
  sensitive: false,
};
```

**Signature**

```ts
export interface EnvIssue {
  readonly name: string;
  readonly code: "missing" | "invalid";
  readonly message: string;
  readonly sensitive: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.types.ts#L20)

### EnvProjection (interface)

Public, value-free metadata for one field.

**Example**

```ts
const fields: readonly EnvProjection[] = projectEnv(definition);
```

**Signature**

```ts
export interface EnvProjection extends EnvMetadata {
  readonly name: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.types.ts#L35)

### EnvSource (type alias)

Explicit source values; resolution never reads the process environment.

**Example**

```ts
const source: EnvSource = { MODE: "test" };
```

**Signature**

```ts
type EnvSource = Readonly<Record<string, string | undefined>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.types.ts#L6)

### ResolveEnvOptions (interface)

Inputs for resolving an environment declaration.

**Example**

```ts
const options: ResolveEnvOptions = { environment: "test", source: {} };
```

**Signature**

```ts
export interface ResolveEnvOptions {
  readonly environment: string;
  readonly source: EnvSource;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.types.ts#L11)

### ResolvedEnv (type alias)

Immutable values inferred from a declaration shape.

**Example**

```ts
type Values = ResolvedEnv<{ MODE: EnvBuilder<string> }>;
```

**Signature**

```ts
type ResolvedEnv<S extends EnvShape> = Readonly<InferEnvValues<S>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.types.ts#L30)