Configuration API

Generated public TypeScript reference for @relkit/config.

Common APIs

• defineEnv

For configuration and examples, read Environment contracts, local docker, define.

For a complete workflow, follow 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.

config-observability.ts

ConfigOperation

Signature

declare const ConfigOperation: ConfigOperation;

Source

ConfigTelemetry (class)

Injectable telemetry for environment operations.

Example

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

Signature

declare class ConfigTelemetry

Source

ConfigTelemetryLive

Live spans and bounded operation metrics.

Example

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

Signature

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

Source

ConfigTelemetryService

Signature

declare const ConfigTelemetryService: ConfigTelemetryService;

Source

observeConfig

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

Example

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

Signature

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

Source

runConfigSync

Run a synchronous compatibility adapter while retaining its original failure.

Throws

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

Example

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

Signature

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

Source

config-observability.types.ts

ConfigOperation (type alias)

Stable, bounded names for environment configuration operations.

Signature

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

ConfigTelemetryService (interface)

Substitutable observer used by the config Effect operations.

Signature

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

config-validation-error.ts

ConfigValidationError (class)

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

Example

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

Signature

declare class ConfigValidationError

Source

env-builder-metadata.ts

metadata

Build initial immutable metadata inside the observed builder creation.

Example

metadata("string", false);

Signature

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

Source

updateMetadata

Copy metadata inside an observed fluent builder operation.

Example

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

Signature

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

Source

env-builder.ts

createEnvBuilder

Create a field builder synchronously for existing callers.

Example

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

Signature

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

Source

createEnvBuilderEffect

Create a frozen field builder through the Effect path.

Example

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

Signature

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

Source

parseEnvBuilderEffect

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

Example

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

Signature

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

Source

env-builder.types.ts

Synchronous parser type retained for public field compatibility.

Example

const parse: Parse<number> = Number;

DefaultFactory (type alias)

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

Example

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

Signature

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

Source

Parse (type alias)

Synchronous parser type retained for public field compatibility.

Example

const parse: Parse<number> = Number;

Signature

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

Source

env-factory.ts

bindingOrBuilderEffect

Build an environment field or a named binding reference.

Example

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

Signature

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

env

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

Example

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

Signature

declare const env: EnvBuilderFactory;

Source

literalBuilderEffect

Build a literal field while rejecting non-finite choices.

Example

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

Signature

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

Source

parseJsonEffect

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

Example

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

Signature

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

Source

parseUrlEffect

Parse a URL with a tagged failure for malformed input.

Example

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

Signature

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

Source

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

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

Signature

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

env-json.ts

JsonValue

Signature

declare const JsonValue: JsonValue;

Source

toJsonValue

Convert an example synchronously for existing callers.

Throws

TypeError for unsupported values or accessors.

Example

toJsonValue({ count: 2 });

Signature

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

Source

toJsonValueEffect

Convert declaration examples to immutable, JSON-safe values.

Example

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

Signature

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

Source

env-json.types.ts

Deeply JSON-safe value suitable for declaration metadata.

Example

const example: JsonValue = { enabled: true };

JsonValue (type alias)

Deeply JSON-safe value suitable for declaration metadata.

Example

const example: JsonValue = { enabled: true };

Signature

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

Source

env-parsers.ts

parseBoolean

Parse an exact Boolean synchronously.

Throws

TypeError for any other token.

Example

parseBoolean("false");

Signature

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

Source

parseBooleanEffect

Parse an exact Boolean environment token.

Example

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

Signature

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

Source

parseLiteral

Match a literal synchronously.

Throws

TypeError when there is no match.

Example

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

Signature

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

Source

parseLiteralEffect

Match a raw value against declared literal choices.

Example

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

Signature

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

Source

parseNumber

Parse a finite number synchronously.

Throws

TypeError when the value is not finite.

Example

parseNumber("42");

Signature

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

Source

parseNumberEffect

Parse a finite number from an environment string.

Example

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

Signature

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

Source

parsePort

Parse a TCP port synchronously.

Throws

TypeError for an invalid port.

Example

parsePort("3000");

Signature

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

Source

parsePortEffect

Parse a TCP port from an environment string.

Example

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

Signature

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

Source

env-ref.ts

createEnvRef

Create a field reference synchronously for a declaration.

Example

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

Signature

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

Source

createEnvRefEffect

Create an immutable typed field reference.

Example

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

Signature

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

Source

isEnvRef

Check a reference synchronously for existing callers.

Example

isEnvRef(definition.MODE);

Signature

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

Source

isEnvRefEffect

Check whether a value is a typed environment reference.

Example

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

Signature

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

Source

env-resolution-error.ts

EnvResolutionError (class)

Tagged failure containing ordered field issues.

Example

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

Signature

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

Source

name (property)

Signature

readonly name: "EnvResolutionError"

Source

env.ts

defineEnv

Build a declaration synchronously for existing callers.

Throws

TypeError for a reserved name or invalid builder.

Example

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

Signature

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

Source

Since v0.1.0

BindingValueRef

Signature

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

Source

EnvBuilder

Signature

declare const EnvBuilder: EnvBuilder<T>;

Source

EnvBuilderBase

Signature

declare const EnvBuilderBase: EnvBuilderBase;

Source

EnvBuilderFactory

Signature

declare const EnvBuilderFactory: EnvBuilderFactory;

Source

EnvDefinition

Signature

declare const EnvDefinition: EnvDefinition<S>;

Source

EnvMetadata

Signature

declare const EnvMetadata: EnvMetadata;

Source

EnvMetadataMap

Signature

declare const EnvMetadataMap: EnvMetadataMap<S>;

Source

EnvRef

Signature

declare const EnvRef: EnvRef<Name, Value>;

Source

EnvShape

Signature

declare const EnvShape: EnvShape;

Source

EnvValueType

Signature

declare const EnvValueType: EnvValueType;

Source

InferEnvValue

Signature

declare const InferEnvValue: InferEnvValue<B>;

Source

InferEnvValues

Signature

declare const InferEnvValues: InferEnvValues<S>;

Source

JsonValue

Signature

declare const JsonValue: JsonValue;

Source

LiteralValue

Signature

declare const LiteralValue: LiteralValue;

Source

defineEnvEffect

Build an immutable declaration without reading runtime values.

Example

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

Signature

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

Source

env

Signature

declare const env: EnvBuilderFactory;

Source

isEnvRef

Signature

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

Source

env.types.ts

BindingValueRef

Signature

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

Source

EnvBuilder (interface)

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

Example

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

Signature

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

EnvBuilderBase (interface)

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

Example

const field: EnvBuilderBase = env.string();

Signature

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

EnvBuilderFactory

Signature

declare const EnvBuilderFactory: EnvBuilderFactory;

Source

EnvDefinition (type alias)

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

Example

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

Signature

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

EnvMetadata (interface)

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

Example

const metadata = env.secret().metadata;

Signature

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

EnvMetadataMap (type alias)

Infer a metadata map from a declaration shape.

Example

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

Signature

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

Source

EnvRef (interface)

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

Example

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

Signature

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

EnvShape (type alias)

Map field names to builders without reading runtime values.

Example

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

Signature

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

Source

EnvValueType (type alias)

Stable field type emitted in metadata.

Example

const type: EnvValueType = "secret-string";

Signature

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

Source

InferEnvValue (type alias)

Extract a field builder’s resolved value type.

Example

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

Signature

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

Source

InferEnvValues (type alias)

Infer the immutable runtime value object from a declaration shape.

Example

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

Signature

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

Source

LiteralValue (type alias)

Scalar literals accepted by env.literal.

Example

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

Signature

type LiteralValue = string | number | boolean;

Source

index.ts

BindingValueRef

Signature

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

Source

ConfigOperation

Signature

declare const ConfigOperation: ConfigOperation;

Source

ConfigTelemetry

Signature

declare const ConfigTelemetry: typeof ConfigTelemetry;

Source

ConfigTelemetryLive

Signature

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

Source

ConfigTelemetryService

Signature

declare const ConfigTelemetryService: ConfigTelemetryService;

Source

ConfigValidationError

Signature

declare const ConfigValidationError: typeof ConfigValidationError;

Source

EnvBuilder

Signature

declare const EnvBuilder: EnvBuilder<T>;

Source

EnvBuilderBase

Signature

declare const EnvBuilderBase: EnvBuilderBase;

Source

EnvBuilderFactory

Signature

declare const EnvBuilderFactory: EnvBuilderFactory;

Source

EnvDefinition

Signature

declare const EnvDefinition: EnvDefinition<S>;

Source

EnvIssue

Signature

declare const EnvIssue: EnvIssue;

Source

EnvMetadata

Signature

declare const EnvMetadata: EnvMetadata;

Source

EnvMetadataMap

Signature

declare const EnvMetadataMap: EnvMetadataMap<S>;

Source

EnvProjection

Signature

declare const EnvProjection: EnvProjection;

Source

EnvRef

Signature

declare const EnvRef: EnvRef<Name, Value>;

Source

EnvResolutionError

Signature

declare const EnvResolutionError: typeof EnvResolutionError;

Source

EnvShape

Signature

declare const EnvShape: EnvShape;

Source

EnvSource

Signature

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

Source

EnvValueType

Signature

declare const EnvValueType: EnvValueType;

Source

InferEnvValue

Signature

declare const InferEnvValue: InferEnvValue<B>;

Source

InferEnvValues

Signature

declare const InferEnvValues: InferEnvValues<S>;

Source

JsonValue

Signature

declare const JsonValue: JsonValue;

Source

LiteralValue

Signature

declare const LiteralValue: LiteralValue;

Source

ResolveEnvOptions

Signature

declare const ResolveEnvOptions: ResolveEnvOptions;

Source

ResolvedEnv

Signature

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

Source

createEnvRefEffect

Signature

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

Source

defineEnv

Signature

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

Source

defineEnvEffect

Signature

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

Source

env

Signature

declare const env: EnvBuilderFactory;

Source

isBindingValueRef

Signature

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

Source

isEnvRef

Signature

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

Source

isEnvRefEffect

Signature

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

Source

parseEnvBuilderEffect

Signature

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

Source

projectEnv

Signature

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

Source

projectEnvEffect

Signature

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

Source

resolveEnv

Signature

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

Source

resolveEnvEffect

Signature

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

Source

config.ts

resolveEnvWithEffect

Promise compatibility adapter for the internal ConfigProvider bridge.

Example

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

Signature

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

Source

resolveEnvWithEffectEffect

Resolve through an explicit Effect ConfigProvider.

Example

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

Signature

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

Source

resolve-helpers.ts

definitionIssue

Check the declaration shape before reading field callbacks.

Example

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

Signature

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

Source

optionsIssue

Check an explicit environment name and source map.

Example

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

Signature

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

Source

resolveField

Resolve one field while appending issues in declaration order.

Example

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

Signature

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

Source

resolve.ts

EnvIssue

Signature

declare const EnvIssue: EnvIssue;

Source

EnvProjection

Signature

declare const EnvProjection: EnvProjection;

Source

EnvResolutionError

Signature

declare const EnvResolutionError: typeof EnvResolutionError;

Source

EnvSource

Signature

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

Source

ResolveEnvOptions

Signature

declare const ResolveEnvOptions: ResolveEnvOptions;

Source

ResolvedEnv

Signature

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

Source

projectEnv

Project metadata synchronously for existing callers.

Throws

TypeError for a malformed definition.

Example

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

Signature

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

Source

projectEnvEffect

Project sorted, JSON-safe metadata without source values.

Example

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

Signature

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

Source

resolveEnv

Resolve a declaration synchronously for existing callers.

Throws

TypeError for invalid inputs; EnvResolutionError for field issues.

Example

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

Signature

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

Source

resolveEnvEffect

Resolve all declared values with ordered, typed failures.

Example

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

Signature

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

Source

resolve.types.ts

EnvIssue (interface)

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

Example

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

Signature

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

Source

EnvProjection (interface)

Public, value-free metadata for one field.

Example

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

Signature

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

Source

EnvSource (type alias)

Explicit source values; resolution never reads the process environment.

Example

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

Signature

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

Source

ResolveEnvOptions (interface)

Inputs for resolving an environment declaration.

Example

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

Signature

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

Source

ResolvedEnv (type alias)

Immutable values inferred from a declaration shape.

Example

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

Signature

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

Source