# Envapt

## Call Signature

```ts
function Envapt(key, options?): EnvaptFieldDecorator<string | undefined>;
```

A custom converter function with a fallback (both required), or a fallback only.

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `key` | `EnvKeyInput` | Environment variable name(s) to load |
| `options?` | \{ `converter?`: `undefined`; `fallback`: `undefined`; \} | Configuration options |
| `options.converter?` | `undefined` | - |
| `options.fallback` | `undefined` | - |

### Returns

[`EnvaptFieldDecorator`](../type-aliases/EnvaptFieldDecorator.mdx)\<`string` \| `undefined`\>

### Example

```ts
class Config extends Envapter {
  \@Envapt('ADMIN_EMAILS', { fallback: new Set<string>(), converter: (raw) => new Set(raw.split(',')) })
  static readonly adminEmails: Set<string>;

  \@Envapt('LOG_FILE', { fallback: '/var/log/app.log' })
  static readonly logFile: string;
}
```

## Call Signature

```ts
function Envapt<TFallback>(key, options): EnvaptFieldDecorator<TFallback>;
```

A custom converter function with a fallback (both required), or a fallback only.

### Type Parameters

| Type Parameter |
| ------ |
|  `TFallback` |

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `key` | `EnvKeyInput` | Environment variable name(s) to load |
| `options` | \{ `converter`: [`ConverterFunction`](../../envapt/type-aliases/ConverterFunction.mdx)\<`TFallback` \| `null` \| `undefined`\>; `fallback`: `TFallback`; \} | Configuration options |
| `options.converter` | [`ConverterFunction`](../../envapt/type-aliases/ConverterFunction.mdx)\<`TFallback` \| `null` \| `undefined`\> | - |
| `options.fallback` | `TFallback` | - |

### Returns

[`EnvaptFieldDecorator`](../type-aliases/EnvaptFieldDecorator.mdx)\<`TFallback`\>

### Example

```ts
class Config extends Envapter {
  \@Envapt('ADMIN_EMAILS', { fallback: new Set<string>(), converter: (raw) => new Set(raw.split(',')) })
  static readonly adminEmails: Set<string>;

  \@Envapt('LOG_FILE', { fallback: '/var/log/app.log' })
  static readonly logFile: string;
}
```

## Call Signature

```ts
function Envapt<TFallback>(key, options): EnvaptFieldDecorator<FallbackOnlyReturn<TFallback>>;
```

A custom converter function with a fallback (both required), or a fallback only.

### Type Parameters

| Type Parameter |
| ------ |
|  `TFallback` *extends* `FallbackOnlyValue` \| `undefined` |

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `key` | `EnvKeyInput` | Environment variable name(s) to load |
| `options` | \{ `converter?`: `undefined`; `fallback`: `TFallback`; \} | Configuration options |
| `options.converter?` | `undefined` | - |
| `options.fallback` | `TFallback` | - |

### Returns

[`EnvaptFieldDecorator`](../type-aliases/EnvaptFieldDecorator.mdx)\<`FallbackOnlyReturn`\<`TFallback`\>\>

### Example

```ts
class Config extends Envapter {
  \@Envapt('ADMIN_EMAILS', { fallback: new Set<string>(), converter: (raw) => new Set(raw.split(',')) })
  static readonly adminEmails: Set<string>;

  \@Envapt('LOG_FILE', { fallback: '/var/log/app.log' })
  static readonly logFile: string;
}
```

## Call Signature

```ts
function Envapt<TReturnType>(key, options): EnvaptFieldDecorator<NonNullable<TReturnType> | undefined>;
```

A custom converter function without a fallback. Omit `required` to get `undefined` for a missing
value, or pass `required: true` to throw `MissingEnvValue` on missing or empty values.

### Type Parameters

| Type Parameter |
| ------ |
|  `TReturnType` |

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `key` | `EnvKeyInput` | Environment variable name(s) to load |
| `options` | \{ `converter`: [`ConverterFunction`](../../envapt/type-aliases/ConverterFunction.mdx)\<`TReturnType`\>; `required?`: `false`; \} | Configuration options |
| `options.converter` | [`ConverterFunction`](../../envapt/type-aliases/ConverterFunction.mdx)\<`TReturnType`\> | - |
| `options.required?` | `false` | - |

### Returns

[`EnvaptFieldDecorator`](../type-aliases/EnvaptFieldDecorator.mdx)\<`NonNullable`\<`TReturnType`\> \| `undefined`\>

### Example

```ts
class Config extends Envapter {
  \@Envapt('MAINTENANCE_UNTIL', { converter: (raw) => new Date(raw) })
  static readonly maintenanceUntil: Date | undefined;

  \@Envapt('JWT_SECRET', { converter: (raw) => Buffer.from(raw, 'base64'), required: true })
  static readonly jwtSecret: Buffer;
}
```

## Call Signature

```ts
function Envapt<TReturnType>(key, options): EnvaptFieldDecorator<NonNullable<TReturnType>>;
```

A custom converter function with a fallback (both required), or a fallback only.

### Type Parameters

| Type Parameter |
| ------ |
|  `TReturnType` |

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `key` | `EnvKeyInput` | Environment variable name(s) to load |
| `options` | \{ `converter`: [`ConverterFunction`](../../envapt/type-aliases/ConverterFunction.mdx)\<`TReturnType`\>; `required`: `true`; \} | Configuration options |
| `options.converter` | [`ConverterFunction`](../../envapt/type-aliases/ConverterFunction.mdx)\<`TReturnType`\> | - |
| `options.required` | `true` | - |

### Returns

[`EnvaptFieldDecorator`](../type-aliases/EnvaptFieldDecorator.mdx)\<`NonNullable`\<`TReturnType`\>\>

### Example

```ts
class Config extends Envapter {
  \@Envapt('ADMIN_EMAILS', { fallback: new Set<string>(), converter: (raw) => new Set(raw.split(',')) })
  static readonly adminEmails: Set<string>;

  \@Envapt('LOG_FILE', { fallback: '/var/log/app.log' })
  static readonly logFile: string;
}
```

## Call Signature

```ts
function Envapt<TConverter>(key, options): EnvaptFieldDecorator<InferConverterReturnType<TConverter>>;
```

A built-in or array converter with a fallback, or `required: true`. The converter sets the
fallback type, for example a number or time-string for `Converters.Time` and a `URL` instance
for `Converters.Url`.

### Type Parameters

| Type Parameter |
| ------ |
|  `TConverter` *extends* `ConverterToken` \| `ArrayOf`\<`ArrayElement`\> |

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `key` | `EnvKeyInput` | Environment variable name(s) to load |
| `options` | \| \{ `converter`: `TConverter`; `fallback`: `InferConverterFallbackType`\<`TConverter`\>; `required?`: `false`; \} \| \{ `converter`: `TConverter`; `required`: `true`; \} | Configuration options |

### Returns

[`EnvaptFieldDecorator`](../type-aliases/EnvaptFieldDecorator.mdx)\<`InferConverterReturnType`\<`TConverter`\>\>

### Example

```ts
import { Converters } from 'envapt';

class Config extends Envapter {
  \@Envapt('APP_PORT', { converter: Converters.Port, fallback: 3000 })
  static readonly port: number;

  \@Envapt('APP_URL', { converter: Converters.Url, fallback: new URL('http://localhost:3000') })
  static readonly url: URL;

  // reads CANARY_URL when present, otherwise APP_URL
  \@Envapt(['CANARY_URL', 'APP_URL'], { converter: Converters.Url })
  static readonly canaryUrl: URL | undefined;

  // Time takes a number (milliseconds) or a time-string fallback (`<number><unit>`)
  \@Envapt('REQUEST_TIMEOUT', { converter: Converters.Time, fallback: '10s' })
  static readonly requestTimeout: number;

  \@Envapt('ALLOWED_ORIGINS', {
    converter: Converters.array({ of: Converters.String }),
    fallback: ['https://example.com']
  })
  static readonly allowedOrigins: string[];

  \@Envapt('DATABASE_URL', { converter: Converters.Url, required: true })
  static readonly databaseUrl: URL;
}
```

## Call Signature

```ts
function Envapt<TConverter>(key, options): EnvaptFieldDecorator<InferConverterReturnType<TConverter> | undefined>;
```

A custom converter function with a fallback (both required), or a fallback only.

### Type Parameters

| Type Parameter |
| ------ |
|  `TConverter` *extends* `ConverterToken` \| `ArrayOf`\<`ArrayElement`\> |

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `key` | `EnvKeyInput` | Environment variable name(s) to load |
| `options` | \{ `converter`: `TConverter`; `fallback?`: `undefined`; `required?`: `false`; \} | Configuration options |
| `options.converter` | `TConverter` | - |
| `options.fallback?` | `undefined` | - |
| `options.required?` | `false` | - |

### Returns

[`EnvaptFieldDecorator`](../type-aliases/EnvaptFieldDecorator.mdx)\<`InferConverterReturnType`\<`TConverter`\> \| `undefined`\>

### Example

```ts
class Config extends Envapter {
  \@Envapt('ADMIN_EMAILS', { fallback: new Set<string>(), converter: (raw) => new Set(raw.split(',')) })
  static readonly adminEmails: Set<string>;

  \@Envapt('LOG_FILE', { fallback: '/var/log/app.log' })
  static readonly logFile: string;
}
```

## Call Signature

```ts
function Envapt(key, options): EnvaptFieldDecorator<string>;
```

Required, no converter (raw string). Throws `MissingEnvValue` on first access when the env
value is missing or empty. Pairing `required: true` with `fallback` matches no overload at
compile time. A call that bypasses the types throws `InvalidUserDefinedConfig` at runtime.

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `key` | `EnvKeyInput` | Environment variable name(s) to load |
| `options` | \{ `required`: `true`; \} | `{ required: true }` |
| `options.required` | `true` | - |

### Returns

[`EnvaptFieldDecorator`](../type-aliases/EnvaptFieldDecorator.mdx)\<`string`\>

### Example

```ts
class Config extends Envapter {
  \@Envapt('API_KEY', { required: true })
  static readonly apiKey: string;
}
```

## Call Signature

```ts
function Envapt<Schema>(key, options): EnvaptFieldDecorator<InferSchemaOutput<Schema> | undefined>;
```

A Standard Schema v1 schema (zod, valibot, arktype, or hand-written). Synchronous schemas only.
A `validate` that returns a Promise throws `InvalidUserDefinedConfig` at runtime. Pairing
`schema` with `converter` matches no overload at compile time. A call that bypasses the types
throws `InvalidUserDefinedConfig` at runtime.

### Type Parameters

| Type Parameter |
| ------ |
|  `Schema` *extends* [`StandardSchemaV1`](../../envapt/interfaces/StandardSchemaV1.mdx)\<`unknown`, `unknown`\> |

### Parameters

| Parameter | Type |
| ------ | ------ |
| `key` | `EnvKeyInput` |
| `options` | \{ `fallback?`: `undefined`; `required?`: `false`; `schema`: `SchemaConstraint`\<`Schema`\>; \} |
| `options.fallback?` | `undefined` |
| `options.required?` | `false` |
| `options.schema` | `SchemaConstraint`\<`Schema`\> |

### Returns

[`EnvaptFieldDecorator`](../type-aliases/EnvaptFieldDecorator.mdx)\<`InferSchemaOutput`\<`Schema`\> \| `undefined`\>

## Call Signature

```ts
function Envapt<Schema>(key, options): EnvaptFieldDecorator<InferSchemaOutput<Schema>>;
```

A custom converter function with a fallback (both required), or a fallback only.

### Type Parameters

| Type Parameter |
| ------ |
|  `Schema` *extends* [`StandardSchemaV1`](../../envapt/interfaces/StandardSchemaV1.mdx)\<`unknown`, `unknown`\> |

### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `key` | `EnvKeyInput` | Environment variable name(s) to load |
| `options` | \| \{ `fallback`: `InferSchemaOutput`\<`Schema`\>; `required?`: `false`; `schema`: `SchemaConstraint`\<`Schema`\>; \} \| \{ `required`: `true`; `schema`: `SchemaConstraint`\<`Schema`\>; \} | Configuration options |

### Returns

[`EnvaptFieldDecorator`](../type-aliases/EnvaptFieldDecorator.mdx)\<`InferSchemaOutput`\<`Schema`\>\>

### Example

```ts
class Config extends Envapter {
  \@Envapt('ADMIN_EMAILS', { fallback: new Set<string>(), converter: (raw) => new Set(raw.split(',')) })
  static readonly adminEmails: Set<string>;

  \@Envapt('LOG_FILE', { fallback: '/var/log/app.log' })
  static readonly logFile: string;
}
```