envapt 6.0.2 → 7.0.0-next.0

package/dist/node/decorators/{Envapt.d.mts → legacy/Envapt.d.mts}

@@ -1,15 +1,15 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { ArrayOf } from "../converters/Converters.mjs";
-import { BuiltInConverter, ConverterFunction, InferConverterFallbackType, InferPrimitiveReturnType, PrimitiveConstructor } from "../types/Conversion.mjs";
-import { InferSchemaOutput, StandardSchemaV1 } from "../StandardSchema.mjs";
-import { SchemaConstraint } from "../types/Schema.mjs";
-import { EnvKeyInput } from "../types/Env.mjs";
+import { ArrayOf } from "../../converters/Converters.mjs";
+import { BuiltInConverter, ConverterFunction, InferConverterFallbackType, InferConverterReturnType, InferPrimitiveReturnType, PrimitiveConstructor } from "../../types/Conversion.mjs";
+import { InferSchemaOutput, StandardSchemaV1 } from "../../infra/StandardSchema.mjs";
+import { SchemaConstraint } from "../../types/Schema.mjs";
+import { EnvKeyInput } from "../../types/Env.mjs";
+import { EnvaptFieldDecorator } from "../../types/Decorator.mjs";
 
-//#region src/decorators/Envapt.d.ts
+//#region src/decorators/legacy/Envapt.d.ts
 /**
- * Usage 1: Either a custom converter function + fallback (both required), OR a fallback
- * only (no converter).
+ * A custom converter function with a fallback (both required), or a fallback only.
  *
  * @param key - Environment variable name(s) to load
  * @param options - Configuration options
@@ -17,7 +17,6 @@ import { EnvKeyInput } from "../types/Env.mjs";
  * @example
  * ```ts
  * class Config extends Envapter {
- *   // Custom converter that validates a non-empty API key
  *   \@Envapt('API_KEY', {
  *     fallback: 'default-key',
  *     converter(raw, _fallback) {
@@ -27,30 +26,32 @@ import { EnvKeyInput } from "../types/Env.mjs";
  *   })
  *   static readonly apiKey: string;
  *
- *   // Fallback-only (no converter): string fallback
  *   \@Envapt('LOG_FILE', { fallback: '/var/log/app.log' })
  *   static readonly logFile: string;
  *
- *   // Fallback-only: arbitrary object fallback
  *   \@Envapt('RETRY_POLICY', { fallback: { retries: 3, backoff: 'exponential' } })
  *   static readonly retryPolicy: unknown;
  * }
  * ```
  */
+declare function Envapt(key: EnvKeyInput, options: {
+  fallback: undefined;
+  converter?: undefined;
+}): EnvaptFieldDecorator<string | undefined>;
 declare function Envapt<TFallback>(key: EnvKeyInput, options: {
   converter: (raw: string | undefined, fallback: TFallback) => TFallback;
   fallback: TFallback;
 } | {
   fallback: TFallback;
   converter?: undefined;
-}): PropertyDecorator;
+}): EnvaptFieldDecorator<TFallback>;
 /**
- * Usage 2: Custom converter function without fallback. Either omit `required` (returns the
- * converter's output, possibly `undefined`) or pass `required: true` to throw `MissingEnvValue`
- * on missing/empty values.
+ * A custom converter function without a fallback. Omit `required` to return the converter's
+ * output (possibly `undefined`), or pass `required: true` to throw `MissingEnvValue` on
+ * missing or empty values.
  *
  * @param key - Environment variable name(s) to load
- * @param options - Configuration options with custom converter only, with optional `required: true`
+ * @param options - Configuration options
  * @public
  * @example
  * ```ts
@@ -74,15 +75,11 @@ declare function Envapt<TReturnType>(key: EnvKeyInput, options: {
 } | {
   converter: ConverterFunction<TReturnType>;
   required: true;
-}): PropertyDecorator;
+}): EnvaptFieldDecorator<TReturnType>;
 /**
- * Usage 3: Built-in or array converter with optional fallback OR `required: true`.
- *
- * `InferConverterFallbackType` handles asymmetric cases: scalar `Converters.Time` accepts
- * `TimeFallback`, and `ArrayOf<'time'>` accepts `TimeFallback[]`. Every other converter
- * reduces to `InferConverterReturnType`. The two object-shape branches are mutually
- * exclusive: either provide a `fallback`, or pass `required: true` to throw
- * `MissingEnvValue` on missing/empty values.
+ * A built-in or array converter with a fallback, or `required: true`. The fallback type tracks
+ * the converter, so `Converters.Time` takes a number or time-string and `Converters.Url` takes
+ * a `URL` instance.
  *
  * @param key - Environment variable name(s) to load
  * @param options - Configuration options
@@ -92,23 +89,21 @@ declare function Envapt<TReturnType>(key: EnvKeyInput, options: {
  * import { Converters } from 'envapt';
  *
  * class Config extends Envapter {
- *   // Use built-in Number converter with a numeric fallback
  *   \@Envapt('APP_PORT', { converter: Converters.Number, fallback: 3000 })
  *   static readonly port: number;
  *
- *   // Url converter: the fallback is a URL instance, not a string
+ *   // the Url fallback is a URL instance, not a string
  *   \@Envapt('APP_URL', { converter: Converters.Url, fallback: new URL('http://localhost:3000') })
  *   static readonly url: URL;
  *
- *   // Prefer CANARY_URL when present, otherwise fall back to APP_URL
+ *   // prefers CANARY_URL when present, otherwise APP_URL
  *   \@Envapt(['CANARY_URL', 'APP_URL'], { converter: Converters.Url })
  *   static readonly canaryUrl: URL | null;
  *
- *   // `Converters.Time` accepts either a number (milliseconds) or a time-string fallback (`<number><unit>`).
+ *   // Time takes a number (milliseconds) or a time-string fallback (`<number><unit>`)
  *   \@Envapt('REQUEST_TIMEOUT', { converter: Converters.Time, fallback: '10s' })
  *   static readonly requestTimeout: number;
  *
- *   // Array converter: comma-separated list of origins -> string[]
  *   \@Envapt('ALLOWED_ORIGINS', {
  *     converter: Converters.array({ of: Converters.String }),
  *     fallback: ['https://example.com']
@@ -122,21 +117,29 @@ declare function Envapt<TReturnType>(key: EnvKeyInput, options: {
  */
 declare function Envapt<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, options: {
   converter: TConverter;
-  fallback?: InferConverterFallbackType<TConverter> | undefined;
+  fallback: InferConverterFallbackType<TConverter>;
   required?: false;
 } | {
   converter: TConverter;
   required: true;
-}): PropertyDecorator;
+}): EnvaptFieldDecorator<InferConverterReturnType<TConverter>>;
+declare function Envapt<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, options: {
+  converter: TConverter;
+  fallback: undefined;
+  required?: false;
+}): EnvaptFieldDecorator<InferConverterReturnType<TConverter> | undefined>;
+declare function Envapt<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, options: {
+  converter: TConverter;
+  required?: false;
+}): EnvaptFieldDecorator<InferConverterReturnType<TConverter> | null>;
 /**
- * Usage 4: Primitive constructor with optional fallback
+ * A primitive constructor (`Number`, `Boolean`) with an optional fallback.
  *
  * @param key - Environment variable name(s) to load
- * @param options - Configuration options with primitive constructor
+ * @param options - Configuration options
  * @public
  * @example
  * ```ts
- * // Use primitive constructors to coerce values
  * class Config extends Envapter {
  *   \@Envapt('MAX_CONNECTIONS', { converter: Number, fallback: 100 })
  *   static readonly maxConnections: number;
@@ -148,17 +151,26 @@ declare function Envapt<TConverter extends BuiltInConverter | ArrayOf>(key: EnvK
  */
 declare function Envapt<TConstructor extends PrimitiveConstructor>(key: EnvKeyInput, options: {
   converter: TConstructor;
-  fallback?: InferPrimitiveReturnType<TConstructor>;
+  fallback: InferPrimitiveReturnType<TConstructor>;
   required?: false;
 } | {
   converter: TConstructor;
   required: true;
-}): PropertyDecorator;
+}): EnvaptFieldDecorator<InferPrimitiveReturnType<TConstructor>>;
+declare function Envapt<TConstructor extends PrimitiveConstructor>(key: EnvKeyInput, options: {
+  converter: TConstructor;
+  fallback: undefined;
+  required?: false;
+}): EnvaptFieldDecorator<InferPrimitiveReturnType<TConstructor> | undefined>;
+declare function Envapt<TConstructor extends PrimitiveConstructor>(key: EnvKeyInput, options: {
+  converter: TConstructor;
+  required?: false;
+}): EnvaptFieldDecorator<InferPrimitiveReturnType<TConstructor> | null>;
 /**
- * Usage 5: Required, no converter (raw string). Throws `MissingEnvValue` on first access if
- * the env value is missing or empty (post-trim). Independent of global `Envapter.strict`.
- * Combining `required: true` with `fallback` fails to match any overload at compile time;
- * the runtime Validator catches dynamic objects that bypass the types.
+ * Required, no converter (raw string). Throws `MissingEnvValue` on first access when the env
+ * value is missing or empty after trimming, independent of the global `Envapter.strict` flag.
+ * Pairing `required: true` with `fallback` matches no overload at compile time, and the runtime
+ * Validator rejects dynamic objects that bypass the types.
  *
  * @param key - Environment variable name(s) to load
  * @param options - `{ required: true }`
@@ -173,7 +185,7 @@ declare function Envapt<TConstructor extends PrimitiveConstructor>(key: EnvKeyIn
  */
 declare function Envapt(key: EnvKeyInput, options: {
   required: true;
-}): PropertyDecorator;
+}): EnvaptFieldDecorator<string>;
 /**
  * No-fallback form. The property resolves from env or `null`.
  *
@@ -181,20 +193,18 @@ declare function Envapt(key: EnvKeyInput, options: {
  * @public
  * @example
  * ```ts
- * // Classic API: no fallback — property will resolve from env or be null
  * class Config extends Envapter {
  *   \@Envapt('SIMPLE_VALUE')
  *   static readonly simple?: string | null;
  * }
  * ```
  */
-declare function Envapt<_TReturnType = string | null>(key: EnvKeyInput): PropertyDecorator;
+declare function Envapt(key: EnvKeyInput): EnvaptFieldDecorator<string | null>;
 /**
- * Usage 6: Standard Schema v1 adapter (zod, valibot, arktype, hand-rolled). Synchronous
- * schemas only; a Promise-returning `validate` triggers a runtime
- * `InvalidUserDefinedConfig` throw. Combining `schema` with `converter` fails to match any
- * overload at compile time; the runtime Validator catches dynamic objects that bypass the
- * types.
+ * A Standard Schema v1 adapter (zod, valibot, arktype, hand-rolled). Synchronous schemas only,
+ * so a Promise-returning `validate` throws `InvalidUserDefinedConfig` at runtime. Pairing
+ * `schema` with `converter` matches no overload at compile time, and the runtime Validator
+ * rejects dynamic objects that bypass the types.
  * @public
  */
 declare function Envapt<Schema extends StandardSchemaV1>(key: EnvKeyInput, options: {
@@ -204,7 +214,7 @@ declare function Envapt<Schema extends StandardSchemaV1>(key: EnvKeyInput, optio
 } | {
   schema: SchemaConstraint<Schema>;
   required: true;
-}): PropertyDecorator;
+}): EnvaptFieldDecorator<InferSchemaOutput<Schema>>;
 //#endregion
 export { Envapt };
 //# sourceMappingURL=Envapt.d.mts.map

package/dist/node/decorators/legacy/Envapt.mjs

@@ -0,0 +1,2 @@
+import"node:path";import"node:url";import.meta.url;import{parseEnvaptOptions as e}from"../parseEnvaptOptions.mjs";import{createPropertyDecorator as t}from"./createPropertyDecorator.mjs";function n(n,r){return t(n,e(r))}export{n as Envapt};
+//# sourceMappingURL=Envapt.mjs.map

package/dist/node/decorators/legacy/Envapt.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Envapt.mjs","names":[],"sources":["../../../../src/decorators/legacy/Envapt.ts"],"sourcesContent":["import { createPropertyDecorator } from './createPropertyDecorator';\nimport { parseEnvaptOptions } from '../parseEnvaptOptions';\n\nimport type { ArrayOf } from '../../converters';\nimport type { InferSchemaOutput, StandardSchemaV1 } from '../../infra/StandardSchema';\nimport type {\n    BuiltInConverter,\n    ConverterFunction,\n    EnvaptFieldDecorator,\n    EnvKeyInput,\n    InferConverterFallbackType,\n    InferConverterReturnType,\n    InferPrimitiveReturnType,\n    PrimitiveConstructor,\n    SchemaConstraint\n} from '../../types';\n\n/**\n * A custom converter function with a fallback (both required), or a fallback only.\n *\n * @param key - Environment variable name(s) to load\n * @param options - Configuration options\n * @public\n * @example\n * ```ts\n * class Config extends Envapter {\n *   \\@Envapt('API_KEY', {\n *     fallback: 'default-key',\n *     converter(raw, _fallback) {\n *       if (!raw || raw.trim() === '') throw new Error('API_KEY required');\n *       return raw.trim();\n *     }\n *   })\n *   static readonly apiKey: string;\n *\n *   \\@Envapt('LOG_FILE', { fallback: '/var/log/app.log' })\n *   static readonly logFile: string;\n *\n *   \\@Envapt('RETRY_POLICY', { fallback: { retries: 3, backoff: 'exponential' } })\n *   static readonly retryPolicy: unknown;\n * }\n * ```\n */\nexport function Envapt(\n    key: EnvKeyInput,\n    options: { fallback: undefined; converter?: undefined }\n): EnvaptFieldDecorator<string | undefined>;\nexport function Envapt<TFallback>(\n    key: EnvKeyInput,\n    options:\n        | { converter: (raw: string | undefined, fallback: TFallback) => TFallback; fallback: TFallback }\n        | { fallback: TFallback; converter?: undefined }\n): EnvaptFieldDecorator<TFallback>;\n\n/**\n * A custom converter function without a fallback. Omit `required` to return the converter's\n * output (possibly `undefined`), or pass `required: true` to throw `MissingEnvValue` on\n * missing or empty values.\n *\n * @param key - Environment variable name(s) to load\n * @param options - Configuration options\n * @public\n * @example\n * ```ts\n * class Config extends Envapter {\n *   \\@Envapt('FEATURE_FLAGS', { converter(raw) {\n *     return raw ? raw.split('|').map(s => s.trim()) : [];\n *   } })\n *   static readonly featureFlags: string[];\n *\n *   \\@Envapt('JWT_SECRET', {\n *     converter: (raw) => Buffer.from(raw ?? '', 'base64'),\n *     required: true\n *   })\n *   static readonly jwtSecret: Buffer;\n * }\n * ```\n */\nexport function Envapt<TReturnType>(\n    key: EnvKeyInput,\n    options:\n        | { converter: ConverterFunction<TReturnType>; required?: false }\n        | { converter: ConverterFunction<TReturnType>; required: true }\n): EnvaptFieldDecorator<TReturnType>;\n\n/**\n * A built-in or array converter with a fallback, or `required: true`. The fallback type tracks\n * the converter, so `Converters.Time` takes a number or time-string and `Converters.Url` takes\n * a `URL` instance.\n *\n * @param key - Environment variable name(s) to load\n * @param options - Configuration options\n * @public\n * @example\n * ```ts\n * import { Converters } from 'envapt';\n *\n * class Config extends Envapter {\n *   \\@Envapt('APP_PORT', { converter: Converters.Number, fallback: 3000 })\n *   static readonly port: number;\n *\n *   // the Url fallback is a URL instance, not a string\n *   \\@Envapt('APP_URL', { converter: Converters.Url, fallback: new URL('http://localhost:3000') })\n *   static readonly url: URL;\n *\n *   // prefers CANARY_URL when present, otherwise APP_URL\n *   \\@Envapt(['CANARY_URL', 'APP_URL'], { converter: Converters.Url })\n *   static readonly canaryUrl: URL | null;\n *\n *   // Time takes a number (milliseconds) or a time-string fallback (`<number><unit>`)\n *   \\@Envapt('REQUEST_TIMEOUT', { converter: Converters.Time, fallback: '10s' })\n *   static readonly requestTimeout: number;\n *\n *   \\@Envapt('ALLOWED_ORIGINS', {\n *     converter: Converters.array({ of: Converters.String }),\n *     fallback: ['https://example.com']\n *   })\n *   static readonly allowedOrigins: string[];\n *\n *   \\@Envapt('DATABASE_URL', { converter: Converters.Url, required: true })\n *   static readonly databaseUrl: URL;\n * }\n * ```\n */\nexport function Envapt<TConverter extends BuiltInConverter | ArrayOf>(\n    key: EnvKeyInput,\n    options:\n        | { converter: TConverter; fallback: InferConverterFallbackType<TConverter>; required?: false }\n        | { converter: TConverter; required: true }\n): EnvaptFieldDecorator<InferConverterReturnType<TConverter>>;\nexport function Envapt<TConverter extends BuiltInConverter | ArrayOf>(\n    key: EnvKeyInput,\n    options: { converter: TConverter; fallback: undefined; required?: false }\n): EnvaptFieldDecorator<InferConverterReturnType<TConverter> | undefined>;\nexport function Envapt<TConverter extends BuiltInConverter | ArrayOf>(\n    key: EnvKeyInput,\n    options: { converter: TConverter; required?: false }\n): EnvaptFieldDecorator<InferConverterReturnType<TConverter> | null>;\n\n/**\n * A primitive constructor (`Number`, `Boolean`) with an optional fallback.\n *\n * @param key - Environment variable name(s) to load\n * @param options - Configuration options\n * @public\n * @example\n * ```ts\n * class Config extends Envapter {\n *   \\@Envapt('MAX_CONNECTIONS', { converter: Number, fallback: 100 })\n *   static readonly maxConnections: number;\n *\n *   \\@Envapt('FEATURE_ENABLED', { converter: Boolean, fallback: false })\n *   static readonly featureEnabled: boolean;\n * }\n * ```\n */\nexport function Envapt<TConstructor extends PrimitiveConstructor>(\n    key: EnvKeyInput,\n    options:\n        | { converter: TConstructor; fallback: InferPrimitiveReturnType<TConstructor>; required?: false }\n        | { converter: TConstructor; required: true }\n): EnvaptFieldDecorator<InferPrimitiveReturnType<TConstructor>>;\nexport function Envapt<TConstructor extends PrimitiveConstructor>(\n    key: EnvKeyInput,\n    options: { converter: TConstructor; fallback: undefined; required?: false }\n): EnvaptFieldDecorator<InferPrimitiveReturnType<TConstructor> | undefined>;\nexport function Envapt<TConstructor extends PrimitiveConstructor>(\n    key: EnvKeyInput,\n    options: { converter: TConstructor; required?: false }\n): EnvaptFieldDecorator<InferPrimitiveReturnType<TConstructor> | null>;\n\n/**\n * Required, no converter (raw string). Throws `MissingEnvValue` on first access when the env\n * value is missing or empty after trimming, independent of the global `Envapter.strict` flag.\n * Pairing `required: true` with `fallback` matches no overload at compile time, and the runtime\n * Validator rejects dynamic objects that bypass the types.\n *\n * @param key - Environment variable name(s) to load\n * @param options - `{ required: true }`\n * @public\n * @example\n * ```ts\n * class Config extends Envapter {\n *   \\@Envapt('API_KEY', { required: true })\n *   static readonly apiKey: string;\n * }\n * ```\n */\nexport function Envapt(key: EnvKeyInput, options: { required: true }): EnvaptFieldDecorator<string>;\n\n/**\n * No-fallback form. The property resolves from env or `null`.\n *\n * @param key - Environment variable name(s) to load\n * @public\n * @example\n * ```ts\n * class Config extends Envapter {\n *   \\@Envapt('SIMPLE_VALUE')\n *   static readonly simple?: string | null;\n * }\n * ```\n */\nexport function Envapt(key: EnvKeyInput): EnvaptFieldDecorator<string | null>;\n\n/**\n * A Standard Schema v1 adapter (zod, valibot, arktype, hand-rolled). Synchronous schemas only,\n * so a Promise-returning `validate` throws `InvalidUserDefinedConfig` at runtime. Pairing\n * `schema` with `converter` matches no overload at compile time, and the runtime Validator\n * rejects dynamic objects that bypass the types.\n * @public\n */\nexport function Envapt<Schema extends StandardSchemaV1>(\n    key: EnvKeyInput,\n    options:\n        | { schema: SchemaConstraint<Schema>; fallback?: InferSchemaOutput<Schema>; required?: false }\n        | { schema: SchemaConstraint<Schema>; required: true }\n): EnvaptFieldDecorator<InferSchemaOutput<Schema>>;\n\n/**\n * Instance or static property decorator that loads and converts an environment variable.\n */\nexport function Envapt<TFallback = unknown>(key: EnvKeyInput, options?: unknown): EnvaptFieldDecorator<unknown> {\n    return createPropertyDecorator(key, parseEnvaptOptions<TFallback>(options)) as EnvaptFieldDecorator<unknown>;\n}\n"],"mappings":"0LA8NA,SAAgB,EAA4B,EAAkB,EAAkD,CAC5G,OAAO,EAAwB,EAAK,EAA8B,CAAO,CAAC,CAC9E"}

package/dist/node/decorators/legacy/SugarDecorators.cjs

@@ -0,0 +1,2 @@
+import"node:path";import"node:url";import.meta.url;const e=require("../../converters/Converters.cjs"),t=require("./createPropertyDecorator.cjs");function n(e,n,r){return t.createPropertyDecorator(n,{converter:e,fallback:r,hasFallback:r!==void 0,required:!1,schema:void 0})}function r(t,r){return n(e.Converters.Boolean,t,r)}function i(t,r){return n(e.Converters.Number,t,r)}function a(t,r){return n(e.Converters.String,t,r)}function o(t,r){return n(e.Converters.Time,t,r)}function s(t,r){return n(e.Converters.Url,t,r)}exports.EnvBool=r,exports.EnvNum=i,exports.EnvStr=a,exports.EnvTime=o,exports.EnvUrl=s;
+//# sourceMappingURL=SugarDecorators.cjs.map

package/dist/node/decorators/legacy/SugarDecorators.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"SugarDecorators.cjs","names":["createPropertyDecorator","Converters"],"sources":["../../../../src/decorators/legacy/SugarDecorators.ts"],"sourcesContent":["import { createPropertyDecorator } from './createPropertyDecorator';\nimport { Converters } from '../../converters';\n\nimport type { ConverterToken } from '../../converters';\nimport type { EnvaptFieldDecorator, EnvKeyInput, TimeFallback } from '../../types';\n\nfunction sugar<TFallback>(\n    converter: ConverterToken,\n    key: EnvKeyInput,\n    fallback: TFallback | undefined\n): EnvaptFieldDecorator<TFallback> {\n    // the runtime installer is a plain (target, key) decorator, so the cast only adds a\n    // compile-time field-type constraint with no runtime counterpart\n    return createPropertyDecorator<TFallback>(key, {\n        converter,\n        fallback,\n        hasFallback: fallback !== undefined,\n        required: false,\n        schema: undefined\n    }) as EnvaptFieldDecorator<TFallback>;\n}\n\n/**\n * Shorthand for `@Envapt(key, { converter: Converters.Boolean, fallback })`.\n * @public\n */\nexport function EnvBool(key: EnvKeyInput, fallback: boolean): EnvaptFieldDecorator<boolean>;\nexport function EnvBool(key: EnvKeyInput): EnvaptFieldDecorator<boolean | null>;\nexport function EnvBool(key: EnvKeyInput, fallback?: boolean): EnvaptFieldDecorator<boolean | null> {\n    return sugar(Converters.Boolean, key, fallback);\n}\n\n/**\n * Shorthand for `@Envapt(key, { converter: Converters.Number, fallback })`.\n * @public\n */\nexport function EnvNum(key: EnvKeyInput, fallback: number): EnvaptFieldDecorator<number>;\nexport function EnvNum(key: EnvKeyInput): EnvaptFieldDecorator<number | null>;\nexport function EnvNum(key: EnvKeyInput, fallback?: number): EnvaptFieldDecorator<number | null> {\n    return sugar(Converters.Number, key, fallback);\n}\n\n/**\n * Shorthand for `@Envapt(key, { converter: Converters.String, fallback })`.\n * @public\n */\nexport function EnvStr(key: EnvKeyInput, fallback: string): EnvaptFieldDecorator<string>;\nexport function EnvStr(key: EnvKeyInput): EnvaptFieldDecorator<string | null>;\nexport function EnvStr(key: EnvKeyInput, fallback?: string): EnvaptFieldDecorator<string | null> {\n    return sugar(Converters.String, key, fallback);\n}\n\n/**\n * Shorthand for `@Envapt(key, { converter: Converters.Time, fallback })`. The fallback is a\n * millisecond number or a time string (`'15m'`), and the resolved value is always milliseconds.\n * @public\n */\nexport function EnvTime(key: EnvKeyInput, fallback: TimeFallback): EnvaptFieldDecorator<number>;\nexport function EnvTime(key: EnvKeyInput): EnvaptFieldDecorator<number | null>;\nexport function EnvTime(key: EnvKeyInput, fallback?: TimeFallback): EnvaptFieldDecorator<number | null> {\n    return sugar(Converters.Time, key, fallback);\n}\n\n/**\n * Shorthand for `@Envapt(key, { converter: Converters.Url, fallback })`. The fallback is a `URL`\n * instance, not a URL string.\n * @public\n */\nexport function EnvUrl(key: EnvKeyInput, fallback: URL): EnvaptFieldDecorator<URL>;\nexport function EnvUrl(key: EnvKeyInput): EnvaptFieldDecorator<URL | null>;\nexport function EnvUrl(key: EnvKeyInput, fallback?: URL): EnvaptFieldDecorator<URL | null> {\n    return sugar(Converters.Url, key, fallback);\n}\n"],"mappings":"iJAMA,SAAS,EACL,EACA,EACA,EAC+B,CAG/B,OAAOA,EAAAA,wBAAmC,EAAK,CAC3C,YACA,WACA,YAAa,IAAa,IAAA,GAC1B,SAAU,GACV,OAAQ,IAAA,EACZ,CAAC,CACL,CAQA,SAAgB,EAAQ,EAAkB,EAA0D,CAChG,OAAO,EAAMC,EAAAA,WAAW,QAAS,EAAK,CAAQ,CAClD,CAQA,SAAgB,EAAO,EAAkB,EAAwD,CAC7F,OAAO,EAAMA,EAAAA,WAAW,OAAQ,EAAK,CAAQ,CACjD,CAQA,SAAgB,EAAO,EAAkB,EAAwD,CAC7F,OAAO,EAAMA,EAAAA,WAAW,OAAQ,EAAK,CAAQ,CACjD,CASA,SAAgB,EAAQ,EAAkB,EAA8D,CACpG,OAAO,EAAMA,EAAAA,WAAW,KAAM,EAAK,CAAQ,CAC/C,CASA,SAAgB,EAAO,EAAkB,EAAkD,CACvF,OAAO,EAAMA,EAAAA,WAAW,IAAK,EAAK,CAAQ,CAC9C"}

package/dist/node/decorators/legacy/SugarDecorators.d.cts

@@ -0,0 +1,40 @@
+import { TimeFallback } from "../../types/Conversion.cjs";
+import { EnvKeyInput } from "../../types/Env.cjs";
+import { EnvaptFieldDecorator } from "../../types/Decorator.cjs";
+
+//#region src/decorators/legacy/SugarDecorators.d.ts
+/**
+ * Shorthand for `@Envapt(key, { converter: Converters.Boolean, fallback })`.
+ * @public
+ */
+declare function EnvBool(key: EnvKeyInput, fallback: boolean): EnvaptFieldDecorator<boolean>;
+declare function EnvBool(key: EnvKeyInput): EnvaptFieldDecorator<boolean | null>;
+/**
+ * Shorthand for `@Envapt(key, { converter: Converters.Number, fallback })`.
+ * @public
+ */
+declare function EnvNum(key: EnvKeyInput, fallback: number): EnvaptFieldDecorator<number>;
+declare function EnvNum(key: EnvKeyInput): EnvaptFieldDecorator<number | null>;
+/**
+ * Shorthand for `@Envapt(key, { converter: Converters.String, fallback })`.
+ * @public
+ */
+declare function EnvStr(key: EnvKeyInput, fallback: string): EnvaptFieldDecorator<string>;
+declare function EnvStr(key: EnvKeyInput): EnvaptFieldDecorator<string | null>;
+/**
+ * Shorthand for `@Envapt(key, { converter: Converters.Time, fallback })`. The fallback is a
+ * millisecond number or a time string (`'15m'`), and the resolved value is always milliseconds.
+ * @public
+ */
+declare function EnvTime(key: EnvKeyInput, fallback: TimeFallback): EnvaptFieldDecorator<number>;
+declare function EnvTime(key: EnvKeyInput): EnvaptFieldDecorator<number | null>;
+/**
+ * Shorthand for `@Envapt(key, { converter: Converters.Url, fallback })`. The fallback is a `URL`
+ * instance, not a URL string.
+ * @public
+ */
+declare function EnvUrl(key: EnvKeyInput, fallback: URL): EnvaptFieldDecorator<URL>;
+declare function EnvUrl(key: EnvKeyInput): EnvaptFieldDecorator<URL | null>;
+//#endregion
+export { EnvBool, EnvNum, EnvStr, EnvTime, EnvUrl };
+//# sourceMappingURL=SugarDecorators.d.cts.map

package/dist/node/decorators/legacy/SugarDecorators.d.mts

@@ -0,0 +1,42 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { TimeFallback } from "../../types/Conversion.mjs";
+import { EnvKeyInput } from "../../types/Env.mjs";
+import { EnvaptFieldDecorator } from "../../types/Decorator.mjs";
+
+//#region src/decorators/legacy/SugarDecorators.d.ts
+/**
+ * Shorthand for `@Envapt(key, { converter: Converters.Boolean, fallback })`.
+ * @public
+ */
+declare function EnvBool(key: EnvKeyInput, fallback: boolean): EnvaptFieldDecorator<boolean>;
+declare function EnvBool(key: EnvKeyInput): EnvaptFieldDecorator<boolean | null>;
+/**
+ * Shorthand for `@Envapt(key, { converter: Converters.Number, fallback })`.
+ * @public
+ */
+declare function EnvNum(key: EnvKeyInput, fallback: number): EnvaptFieldDecorator<number>;
+declare function EnvNum(key: EnvKeyInput): EnvaptFieldDecorator<number | null>;
+/**
+ * Shorthand for `@Envapt(key, { converter: Converters.String, fallback })`.
+ * @public
+ */
+declare function EnvStr(key: EnvKeyInput, fallback: string): EnvaptFieldDecorator<string>;
+declare function EnvStr(key: EnvKeyInput): EnvaptFieldDecorator<string | null>;
+/**
+ * Shorthand for `@Envapt(key, { converter: Converters.Time, fallback })`. The fallback is a
+ * millisecond number or a time string (`'15m'`), and the resolved value is always milliseconds.
+ * @public
+ */
+declare function EnvTime(key: EnvKeyInput, fallback: TimeFallback): EnvaptFieldDecorator<number>;
+declare function EnvTime(key: EnvKeyInput): EnvaptFieldDecorator<number | null>;
+/**
+ * Shorthand for `@Envapt(key, { converter: Converters.Url, fallback })`. The fallback is a `URL`
+ * instance, not a URL string.
+ * @public
+ */
+declare function EnvUrl(key: EnvKeyInput, fallback: URL): EnvaptFieldDecorator<URL>;
+declare function EnvUrl(key: EnvKeyInput): EnvaptFieldDecorator<URL | null>;
+//#endregion
+export { EnvBool, EnvNum, EnvStr, EnvTime, EnvUrl };
+//# sourceMappingURL=SugarDecorators.d.mts.map

package/dist/node/decorators/legacy/SugarDecorators.mjs

@@ -0,0 +1,2 @@
+import"node:path";import"node:url";import.meta.url;import{Converters as e}from"../../converters/Converters.mjs";import{createPropertyDecorator as t}from"./createPropertyDecorator.mjs";function n(e,n,r){return t(n,{converter:e,fallback:r,hasFallback:r!==void 0,required:!1,schema:void 0})}function r(t,r){return n(e.Boolean,t,r)}function i(t,r){return n(e.Number,t,r)}function a(t,r){return n(e.String,t,r)}function o(t,r){return n(e.Time,t,r)}function s(t,r){return n(e.Url,t,r)}export{r as EnvBool,i as EnvNum,a as EnvStr,o as EnvTime,s as EnvUrl};
+//# sourceMappingURL=SugarDecorators.mjs.map

package/dist/node/decorators/legacy/SugarDecorators.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"SugarDecorators.mjs","names":[],"sources":["../../../../src/decorators/legacy/SugarDecorators.ts"],"sourcesContent":["import { createPropertyDecorator } from './createPropertyDecorator';\nimport { Converters } from '../../converters';\n\nimport type { ConverterToken } from '../../converters';\nimport type { EnvaptFieldDecorator, EnvKeyInput, TimeFallback } from '../../types';\n\nfunction sugar<TFallback>(\n    converter: ConverterToken,\n    key: EnvKeyInput,\n    fallback: TFallback | undefined\n): EnvaptFieldDecorator<TFallback> {\n    // the runtime installer is a plain (target, key) decorator, so the cast only adds a\n    // compile-time field-type constraint with no runtime counterpart\n    return createPropertyDecorator<TFallback>(key, {\n        converter,\n        fallback,\n        hasFallback: fallback !== undefined,\n        required: false,\n        schema: undefined\n    }) as EnvaptFieldDecorator<TFallback>;\n}\n\n/**\n * Shorthand for `@Envapt(key, { converter: Converters.Boolean, fallback })`.\n * @public\n */\nexport function EnvBool(key: EnvKeyInput, fallback: boolean): EnvaptFieldDecorator<boolean>;\nexport function EnvBool(key: EnvKeyInput): EnvaptFieldDecorator<boolean | null>;\nexport function EnvBool(key: EnvKeyInput, fallback?: boolean): EnvaptFieldDecorator<boolean | null> {\n    return sugar(Converters.Boolean, key, fallback);\n}\n\n/**\n * Shorthand for `@Envapt(key, { converter: Converters.Number, fallback })`.\n * @public\n */\nexport function EnvNum(key: EnvKeyInput, fallback: number): EnvaptFieldDecorator<number>;\nexport function EnvNum(key: EnvKeyInput): EnvaptFieldDecorator<number | null>;\nexport function EnvNum(key: EnvKeyInput, fallback?: number): EnvaptFieldDecorator<number | null> {\n    return sugar(Converters.Number, key, fallback);\n}\n\n/**\n * Shorthand for `@Envapt(key, { converter: Converters.String, fallback })`.\n * @public\n */\nexport function EnvStr(key: EnvKeyInput, fallback: string): EnvaptFieldDecorator<string>;\nexport function EnvStr(key: EnvKeyInput): EnvaptFieldDecorator<string | null>;\nexport function EnvStr(key: EnvKeyInput, fallback?: string): EnvaptFieldDecorator<string | null> {\n    return sugar(Converters.String, key, fallback);\n}\n\n/**\n * Shorthand for `@Envapt(key, { converter: Converters.Time, fallback })`. The fallback is a\n * millisecond number or a time string (`'15m'`), and the resolved value is always milliseconds.\n * @public\n */\nexport function EnvTime(key: EnvKeyInput, fallback: TimeFallback): EnvaptFieldDecorator<number>;\nexport function EnvTime(key: EnvKeyInput): EnvaptFieldDecorator<number | null>;\nexport function EnvTime(key: EnvKeyInput, fallback?: TimeFallback): EnvaptFieldDecorator<number | null> {\n    return sugar(Converters.Time, key, fallback);\n}\n\n/**\n * Shorthand for `@Envapt(key, { converter: Converters.Url, fallback })`. The fallback is a `URL`\n * instance, not a URL string.\n * @public\n */\nexport function EnvUrl(key: EnvKeyInput, fallback: URL): EnvaptFieldDecorator<URL>;\nexport function EnvUrl(key: EnvKeyInput): EnvaptFieldDecorator<URL | null>;\nexport function EnvUrl(key: EnvKeyInput, fallback?: URL): EnvaptFieldDecorator<URL | null> {\n    return sugar(Converters.Url, key, fallback);\n}\n"],"mappings":"wLAMA,SAAS,EACL,EACA,EACA,EAC+B,CAG/B,OAAO,EAAmC,EAAK,CAC3C,YACA,WACA,YAAa,IAAa,IAAA,GAC1B,SAAU,GACV,OAAQ,IAAA,EACZ,CAAC,CACL,CAQA,SAAgB,EAAQ,EAAkB,EAA0D,CAChG,OAAO,EAAM,EAAW,QAAS,EAAK,CAAQ,CAClD,CAQA,SAAgB,EAAO,EAAkB,EAAwD,CAC7F,OAAO,EAAM,EAAW,OAAQ,EAAK,CAAQ,CACjD,CAQA,SAAgB,EAAO,EAAkB,EAAwD,CAC7F,OAAO,EAAM,EAAW,OAAQ,EAAK,CAAQ,CACjD,CASA,SAAgB,EAAQ,EAAkB,EAA8D,CACpG,OAAO,EAAM,EAAW,KAAM,EAAK,CAAQ,CAC/C,CASA,SAAgB,EAAO,EAAkB,EAAkD,CACvF,OAAO,EAAM,EAAW,IAAK,EAAK,CAAQ,CAC9C"}

package/dist/node/decorators/legacy/createPropertyDecorator.cjs

@@ -0,0 +1,2 @@
+import"node:path";import"node:url";import.meta.url;const e=require("../../infra/Error.cjs"),t=require("../resolveDecoratorValue.cjs");function n(n,r){return function(i,a){let o=String(a),s=typeof i==`function`,c=t.decoratorCacheKey(s?i:i.constructor,s,o);Object.defineProperty(i,o,{get:function(){return t.resolveDecoratorValue(n,r,c)},set(){throw new e.EnvaptError(302,`Cannot assign to "${o}". @Envapt properties resolve from the environment and are read-only.`)},configurable:!1,enumerable:!0})}}exports.createPropertyDecorator=n;
+//# sourceMappingURL=createPropertyDecorator.cjs.map

package/dist/node/decorators/legacy/createPropertyDecorator.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"createPropertyDecorator.cjs","names":["decoratorCacheKey","resolveDecoratorValue","EnvaptError"],"sources":["../../../../src/decorators/legacy/createPropertyDecorator.ts"],"sourcesContent":["import { EnvaptError, EnvaptErrorCodes } from '../../infra/Error';\nimport { decoratorCacheKey, resolveDecoratorValue } from '../resolveDecoratorValue';\n\nimport type { EnvKeyInput } from '../../types';\nimport type { DecoratorConfig } from '../resolveDecoratorValue';\n\nexport function createPropertyDecorator<TFallback>(\n    key: EnvKeyInput,\n    config: DecoratorConfig<TFallback>\n): PropertyDecorator {\n    return function (target: object, prop: string | symbol): void {\n        const propKey = String(prop);\n        const isStatic = typeof target === 'function';\n        const owner = isStatic ? target : target.constructor;\n        const cacheKey = decoratorCacheKey(owner, isStatic, propKey);\n\n        Object.defineProperty(target, propKey, {\n            get: function () {\n                return resolveDecoratorValue(key, config, cacheKey);\n            },\n            set(): void {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.InvalidUserDefinedConfig,\n                    `Cannot assign to \"${propKey}\". @Envapt properties resolve from the environment and are read-only.`\n                );\n            },\n            configurable: false,\n            enumerable: true\n        });\n    };\n}\n"],"mappings":"sIAMA,SAAgB,EACZ,EACA,EACiB,CACjB,OAAO,SAAU,EAAgB,EAA6B,CAC1D,IAAM,EAAU,OAAO,CAAI,EACrB,EAAW,OAAO,GAAW,WAE7B,EAAWA,EAAAA,kBADH,EAAW,EAAS,EAAO,YACC,EAAU,CAAO,EAE3D,OAAO,eAAe,EAAQ,EAAS,CACnC,IAAK,UAAY,CACb,OAAOC,EAAAA,sBAAsB,EAAK,EAAQ,CAAQ,CACtD,EACA,KAAY,CACR,MAAM,IAAIC,EAAAA,YAAAA,IAEN,qBAAqB,EAAQ,sEACjC,CACJ,EACA,aAAc,GACd,WAAY,EAChB,CAAC,CACL,CACJ"}

package/dist/node/decorators/legacy/createPropertyDecorator.mjs

@@ -0,0 +1,2 @@
+import"node:path";import"node:url";import.meta.url;import{EnvaptError as e}from"../../infra/Error.mjs";import{decoratorCacheKey as t,resolveDecoratorValue as n}from"../resolveDecoratorValue.mjs";function r(r,i){return function(a,o){let s=String(o),c=typeof a==`function`,l=t(c?a:a.constructor,c,s);Object.defineProperty(a,s,{get:function(){return n(r,i,l)},set(){throw new e(302,`Cannot assign to "${s}". @Envapt properties resolve from the environment and are read-only.`)},configurable:!1,enumerable:!0})}}export{r as createPropertyDecorator};
+//# sourceMappingURL=createPropertyDecorator.mjs.map

package/dist/node/decorators/legacy/createPropertyDecorator.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"createPropertyDecorator.mjs","names":[],"sources":["../../../../src/decorators/legacy/createPropertyDecorator.ts"],"sourcesContent":["import { EnvaptError, EnvaptErrorCodes } from '../../infra/Error';\nimport { decoratorCacheKey, resolveDecoratorValue } from '../resolveDecoratorValue';\n\nimport type { EnvKeyInput } from '../../types';\nimport type { DecoratorConfig } from '../resolveDecoratorValue';\n\nexport function createPropertyDecorator<TFallback>(\n    key: EnvKeyInput,\n    config: DecoratorConfig<TFallback>\n): PropertyDecorator {\n    return function (target: object, prop: string | symbol): void {\n        const propKey = String(prop);\n        const isStatic = typeof target === 'function';\n        const owner = isStatic ? target : target.constructor;\n        const cacheKey = decoratorCacheKey(owner, isStatic, propKey);\n\n        Object.defineProperty(target, propKey, {\n            get: function () {\n                return resolveDecoratorValue(key, config, cacheKey);\n            },\n            set(): void {\n                throw new EnvaptError(\n                    EnvaptErrorCodes.InvalidUserDefinedConfig,\n                    `Cannot assign to \"${propKey}\". @Envapt properties resolve from the environment and are read-only.`\n                );\n            },\n            configurable: false,\n            enumerable: true\n        });\n    };\n}\n"],"mappings":"mMAMA,SAAgB,EACZ,EACA,EACiB,CACjB,OAAO,SAAU,EAAgB,EAA6B,CAC1D,IAAM,EAAU,OAAO,CAAI,EACrB,EAAW,OAAO,GAAW,WAE7B,EAAW,EADH,EAAW,EAAS,EAAO,YACC,EAAU,CAAO,EAE3D,OAAO,eAAe,EAAQ,EAAS,CACnC,IAAK,UAAY,CACb,OAAO,EAAsB,EAAK,EAAQ,CAAQ,CACtD,EACA,KAAY,CACR,MAAM,IAAI,EAAA,IAEN,qBAAqB,EAAQ,sEACjC,CACJ,EACA,aAAc,GACd,WAAY,EAChB,CAAC,CACL,CACJ"}

package/dist/node/decorators/modern/Envapt.cjs

@@ -0,0 +1,2 @@
+import"node:path";import"node:url";import.meta.url;const e=require("./createAccessorDecorator.cjs"),t=require("../parseEnvaptOptions.cjs");function n(n,r){return e.createAccessorDecorator(n,t.parseEnvaptOptions(r))}exports.Envapt=n;
+//# sourceMappingURL=Envapt.cjs.map

package/dist/node/decorators/modern/Envapt.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Envapt.cjs","names":["createAccessorDecorator","parseEnvaptOptions"],"sources":["../../../../src/decorators/modern/Envapt.ts"],"sourcesContent":["import { createAccessorDecorator } from './createAccessorDecorator';\nimport { parseEnvaptOptions } from '../parseEnvaptOptions';\n\nimport type { ArrayOf } from '../../converters';\nimport type { InferSchemaOutput, StandardSchemaV1 } from '../../infra/StandardSchema';\nimport type {\n    BuiltInConverter,\n    ConverterFunction,\n    EnvaptAccessorDecorator,\n    EnvKeyInput,\n    InferConverterFallbackType,\n    InferConverterReturnType,\n    InferPrimitiveReturnType,\n    PrimitiveConstructor,\n    SchemaConstraint\n} from '../../types';\n\n/**\n * A custom converter function with a fallback (both required), or a fallback only.\n *\n * @param key - Environment variable name(s) to load\n * @param options - Configuration options\n * @public\n * @example\n * ```ts\n * class Config {\n *   \\@Envapt('API_KEY', {\n *     fallback: 'default-key',\n *     converter(raw, _fallback) {\n *       if (!raw || raw.trim() === '') throw new Error('API_KEY required');\n *       return raw.trim();\n *     }\n *   })\n *   static accessor apiKey: string;\n *\n *   \\@Envapt('LOG_FILE', { fallback: '/var/log/app.log' })\n *   static accessor logFile: string;\n *\n *   \\@Envapt('RETRY_POLICY', { fallback: { retries: 3, backoff: 'exponential' } })\n *   static accessor retryPolicy: unknown;\n * }\n * ```\n */\nexport function Envapt(\n    key: EnvKeyInput,\n    options: { fallback: undefined; converter?: undefined }\n): EnvaptAccessorDecorator<string | undefined>;\nexport function Envapt<TFallback>(\n    key: EnvKeyInput,\n    options:\n        | { converter: (raw: string | undefined, fallback: TFallback) => TFallback; fallback: TFallback }\n        | { fallback: TFallback; converter?: undefined }\n): EnvaptAccessorDecorator<TFallback>;\n\n/**\n * A custom converter function without a fallback. Omit `required` to return the converter's\n * output (possibly `undefined`), or pass `required: true` to throw `MissingEnvValue` on\n * missing or empty values.\n *\n * @param key - Environment variable name(s) to load\n * @param options - Configuration options\n * @public\n * @example\n * ```ts\n * class Config {\n *   \\@Envapt('FEATURE_FLAGS', { converter(raw) {\n *     return raw ? raw.split('|').map(s => s.trim()) : [];\n *   } })\n *   static accessor featureFlags: string[];\n *\n *   \\@Envapt('JWT_SECRET', {\n *     converter: (raw) => Buffer.from(raw ?? '', 'base64'),\n *     required: true\n *   })\n *   static accessor jwtSecret: Buffer;\n * }\n * ```\n */\nexport function Envapt<TReturnType>(\n    key: EnvKeyInput,\n    options:\n        | { converter: ConverterFunction<TReturnType>; required?: false }\n        | { converter: ConverterFunction<TReturnType>; required: true }\n): EnvaptAccessorDecorator<TReturnType>;\n\n/**\n * A built-in or array converter with a fallback, or `required: true`. The fallback type tracks\n * the converter, so `Converters.Time` takes a number or time-string and `Converters.Url` takes\n * a `URL` instance.\n *\n * @param key - Environment variable name(s) to load\n * @param options - Configuration options\n * @public\n * @example\n * ```ts\n * import { Converters } from 'envapt';\n *\n * class Config {\n *   \\@Envapt('APP_PORT', { converter: Converters.Number, fallback: 3000 })\n *   static accessor port: number;\n *\n *   // the Url fallback is a URL instance, not a string\n *   \\@Envapt('APP_URL', { converter: Converters.Url, fallback: new URL('http://localhost:3000') })\n *   static accessor url: URL;\n *\n *   // prefers CANARY_URL when present, otherwise APP_URL\n *   \\@Envapt(['CANARY_URL', 'APP_URL'], { converter: Converters.Url })\n *   static accessor canaryUrl: URL | null;\n *\n *   // Time takes a number (milliseconds) or a time-string fallback (`<number><unit>`)\n *   \\@Envapt('REQUEST_TIMEOUT', { converter: Converters.Time, fallback: '10s' })\n *   static accessor requestTimeout: number;\n *\n *   \\@Envapt('ALLOWED_ORIGINS', {\n *     converter: Converters.array({ of: Converters.String }),\n *     fallback: ['https://example.com']\n *   })\n *   static accessor allowedOrigins: string[];\n *\n *   \\@Envapt('DATABASE_URL', { converter: Converters.Url, required: true })\n *   static accessor databaseUrl: URL;\n * }\n * ```\n */\nexport function Envapt<TConverter extends BuiltInConverter | ArrayOf>(\n    key: EnvKeyInput,\n    options:\n        | { converter: TConverter; fallback: InferConverterFallbackType<TConverter>; required?: false }\n        | { converter: TConverter; required: true }\n): EnvaptAccessorDecorator<InferConverterReturnType<TConverter>>;\nexport function Envapt<TConverter extends BuiltInConverter | ArrayOf>(\n    key: EnvKeyInput,\n    options: { converter: TConverter; fallback: undefined; required?: false }\n): EnvaptAccessorDecorator<InferConverterReturnType<TConverter> | undefined>;\nexport function Envapt<TConverter extends BuiltInConverter | ArrayOf>(\n    key: EnvKeyInput,\n    options: { converter: TConverter; required?: false }\n): EnvaptAccessorDecorator<InferConverterReturnType<TConverter> | null>;\n\n/**\n * A primitive constructor (`Number`, `Boolean`) with an optional fallback.\n *\n * @param key - Environment variable name(s) to load\n * @param options - Configuration options\n * @public\n * @example\n * ```ts\n * class Config {\n *   \\@Envapt('MAX_CONNECTIONS', { converter: Number, fallback: 100 })\n *   static accessor maxConnections: number;\n *\n *   \\@Envapt('FEATURE_ENABLED', { converter: Boolean, fallback: false })\n *   static accessor featureEnabled: boolean;\n * }\n * ```\n */\nexport function Envapt<TConstructor extends PrimitiveConstructor>(\n    key: EnvKeyInput,\n    options:\n        | { converter: TConstructor; fallback: InferPrimitiveReturnType<TConstructor>; required?: false }\n        | { converter: TConstructor; required: true }\n): EnvaptAccessorDecorator<InferPrimitiveReturnType<TConstructor>>;\nexport function Envapt<TConstructor extends PrimitiveConstructor>(\n    key: EnvKeyInput,\n    options: { converter: TConstructor; fallback: undefined; required?: false }\n): EnvaptAccessorDecorator<InferPrimitiveReturnType<TConstructor> | undefined>;\nexport function Envapt<TConstructor extends PrimitiveConstructor>(\n    key: EnvKeyInput,\n    options: { converter: TConstructor; required?: false }\n): EnvaptAccessorDecorator<InferPrimitiveReturnType<TConstructor> | null>;\n\n/**\n * Required, no converter (raw string). Throws `MissingEnvValue` on first access when the env\n * value is missing or empty after trimming, independent of the global `Envapter.strict` flag.\n * Pairing `required: true` with `fallback` matches no overload at compile time, and the runtime\n * Validator rejects dynamic objects that bypass the types.\n *\n * @param key - Environment variable name(s) to load\n * @param options - `{ required: true }`\n * @public\n * @example\n * ```ts\n * class Config {\n *   \\@Envapt('API_KEY', { required: true })\n *   static accessor apiKey: string;\n * }\n * ```\n */\nexport function Envapt(key: EnvKeyInput, options: { required: true }): EnvaptAccessorDecorator<string>;\n\n/**\n * No-fallback form. The property resolves from env or `null`.\n *\n * @param key - Environment variable name(s) to load\n * @public\n * @example\n * ```ts\n * class Config {\n *   \\@Envapt('SIMPLE_VALUE')\n *   static accessor simple: string | null;\n * }\n * ```\n */\nexport function Envapt(key: EnvKeyInput): EnvaptAccessorDecorator<string | null>;\n\n/**\n * A Standard Schema v1 adapter (zod, valibot, arktype, hand-rolled). Synchronous schemas only,\n * so a Promise-returning `validate` throws `InvalidUserDefinedConfig` at runtime. Pairing\n * `schema` with `converter` matches no overload at compile time, and the runtime Validator\n * rejects dynamic objects that bypass the types.\n * @public\n */\nexport function Envapt<Schema extends StandardSchemaV1>(\n    key: EnvKeyInput,\n    options:\n        | { schema: SchemaConstraint<Schema>; fallback?: InferSchemaOutput<Schema>; required?: false }\n        | { schema: SchemaConstraint<Schema>; required: true }\n): EnvaptAccessorDecorator<InferSchemaOutput<Schema>>;\n\n/**\n * Modern (TC39 Stage 3) accessor decorator that loads and converts an environment variable. The\n * decorated property uses the `accessor` keyword and needs no `experimentalDecorators` flag.\n * Instance accessors need the definite-assignment `!`, static accessors do not.\n *\n * @param key - Environment variable name(s) to load\n * @param options - Converter, fallback, `required`, or `schema`. See the overloads.\n * @public\n * @example\n * ```ts\n * import { Envapt, Converters } from 'envapt';\n *\n * class Config {\n *   \\@Envapt('APP_PORT', { converter: Converters.Number, fallback: 3000 })\n *   static accessor port: number;\n *\n *   \\@Envapt('DATABASE_URL', { converter: Converters.Url, required: true })\n *   accessor databaseUrl!: URL;\n * }\n * ```\n */\n/* v8 ignore start -- @preserve oxc (vitest's transform) breaks modern accessor decorators (context.name unset), so the tsc stage3-emit harness covers these, not vitest */\nexport function Envapt<TFallback = unknown>(key: EnvKeyInput, options?: unknown): EnvaptAccessorDecorator<unknown> {\n    return createAccessorDecorator(key, parseEnvaptOptions<TFallback>(options)) as EnvaptAccessorDecorator<unknown>;\n}\n/* v8 ignore stop */\n"],"mappings":"2IAiPA,SAAgB,EAA4B,EAAkB,EAAqD,CAC/G,OAAOA,EAAAA,wBAAwB,EAAKC,EAAAA,mBAA8B,CAAO,CAAC,CAC9E"}

package/dist/node/decorators/modern/Envapt.d.cts

@@ -0,0 +1,218 @@
+import { ArrayOf } from "../../converters/Converters.cjs";
+import { BuiltInConverter, ConverterFunction, InferConverterFallbackType, InferConverterReturnType, InferPrimitiveReturnType, PrimitiveConstructor } from "../../types/Conversion.cjs";
+import { InferSchemaOutput, StandardSchemaV1 } from "../../infra/StandardSchema.cjs";
+import { SchemaConstraint } from "../../types/Schema.cjs";
+import { EnvKeyInput } from "../../types/Env.cjs";
+import { EnvaptAccessorDecorator } from "../../types/Decorator.cjs";
+
+//#region src/decorators/modern/Envapt.d.ts
+/**
+ * A custom converter function with a fallback (both required), or a fallback only.
+ *
+ * @param key - Environment variable name(s) to load
+ * @param options - Configuration options
+ * @public
+ * @example
+ * ```ts
+ * class Config {
+ *   \@Envapt('API_KEY', {
+ *     fallback: 'default-key',
+ *     converter(raw, _fallback) {
+ *       if (!raw || raw.trim() === '') throw new Error('API_KEY required');
+ *       return raw.trim();
+ *     }
+ *   })
+ *   static accessor apiKey: string;
+ *
+ *   \@Envapt('LOG_FILE', { fallback: '/var/log/app.log' })
+ *   static accessor logFile: string;
+ *
+ *   \@Envapt('RETRY_POLICY', { fallback: { retries: 3, backoff: 'exponential' } })
+ *   static accessor retryPolicy: unknown;
+ * }
+ * ```
+ */
+declare function Envapt(key: EnvKeyInput, options: {
+  fallback: undefined;
+  converter?: undefined;
+}): EnvaptAccessorDecorator<string | undefined>;
+declare function Envapt<TFallback>(key: EnvKeyInput, options: {
+  converter: (raw: string | undefined, fallback: TFallback) => TFallback;
+  fallback: TFallback;
+} | {
+  fallback: TFallback;
+  converter?: undefined;
+}): EnvaptAccessorDecorator<TFallback>;
+/**
+ * A custom converter function without a fallback. Omit `required` to return the converter's
+ * output (possibly `undefined`), or pass `required: true` to throw `MissingEnvValue` on
+ * missing or empty values.
+ *
+ * @param key - Environment variable name(s) to load
+ * @param options - Configuration options
+ * @public
+ * @example
+ * ```ts
+ * class Config {
+ *   \@Envapt('FEATURE_FLAGS', { converter(raw) {
+ *     return raw ? raw.split('|').map(s => s.trim()) : [];
+ *   } })
+ *   static accessor featureFlags: string[];
+ *
+ *   \@Envapt('JWT_SECRET', {
+ *     converter: (raw) => Buffer.from(raw ?? '', 'base64'),
+ *     required: true
+ *   })
+ *   static accessor jwtSecret: Buffer;
+ * }
+ * ```
+ */
+declare function Envapt<TReturnType>(key: EnvKeyInput, options: {
+  converter: ConverterFunction<TReturnType>;
+  required?: false;
+} | {
+  converter: ConverterFunction<TReturnType>;
+  required: true;
+}): EnvaptAccessorDecorator<TReturnType>;
+/**
+ * A built-in or array converter with a fallback, or `required: true`. The fallback type tracks
+ * the converter, so `Converters.Time` takes a number or time-string and `Converters.Url` takes
+ * a `URL` instance.
+ *
+ * @param key - Environment variable name(s) to load
+ * @param options - Configuration options
+ * @public
+ * @example
+ * ```ts
+ * import { Converters } from 'envapt';
+ *
+ * class Config {
+ *   \@Envapt('APP_PORT', { converter: Converters.Number, fallback: 3000 })
+ *   static accessor port: number;
+ *
+ *   // the Url fallback is a URL instance, not a string
+ *   \@Envapt('APP_URL', { converter: Converters.Url, fallback: new URL('http://localhost:3000') })
+ *   static accessor url: URL;
+ *
+ *   // prefers CANARY_URL when present, otherwise APP_URL
+ *   \@Envapt(['CANARY_URL', 'APP_URL'], { converter: Converters.Url })
+ *   static accessor canaryUrl: URL | null;
+ *
+ *   // Time takes a number (milliseconds) or a time-string fallback (`<number><unit>`)
+ *   \@Envapt('REQUEST_TIMEOUT', { converter: Converters.Time, fallback: '10s' })
+ *   static accessor requestTimeout: number;
+ *
+ *   \@Envapt('ALLOWED_ORIGINS', {
+ *     converter: Converters.array({ of: Converters.String }),
+ *     fallback: ['https://example.com']
+ *   })
+ *   static accessor allowedOrigins: string[];
+ *
+ *   \@Envapt('DATABASE_URL', { converter: Converters.Url, required: true })
+ *   static accessor databaseUrl: URL;
+ * }
+ * ```
+ */
+declare function Envapt<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, options: {
+  converter: TConverter;
+  fallback: InferConverterFallbackType<TConverter>;
+  required?: false;
+} | {
+  converter: TConverter;
+  required: true;
+}): EnvaptAccessorDecorator<InferConverterReturnType<TConverter>>;
+declare function Envapt<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, options: {
+  converter: TConverter;
+  fallback: undefined;
+  required?: false;
+}): EnvaptAccessorDecorator<InferConverterReturnType<TConverter> | undefined>;
+declare function Envapt<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, options: {
+  converter: TConverter;
+  required?: false;
+}): EnvaptAccessorDecorator<InferConverterReturnType<TConverter> | null>;
+/**
+ * A primitive constructor (`Number`, `Boolean`) with an optional fallback.
+ *
+ * @param key - Environment variable name(s) to load
+ * @param options - Configuration options
+ * @public
+ * @example
+ * ```ts
+ * class Config {
+ *   \@Envapt('MAX_CONNECTIONS', { converter: Number, fallback: 100 })
+ *   static accessor maxConnections: number;
+ *
+ *   \@Envapt('FEATURE_ENABLED', { converter: Boolean, fallback: false })
+ *   static accessor featureEnabled: boolean;
+ * }
+ * ```
+ */
+declare function Envapt<TConstructor extends PrimitiveConstructor>(key: EnvKeyInput, options: {
+  converter: TConstructor;
+  fallback: InferPrimitiveReturnType<TConstructor>;
+  required?: false;
+} | {
+  converter: TConstructor;
+  required: true;
+}): EnvaptAccessorDecorator<InferPrimitiveReturnType<TConstructor>>;
+declare function Envapt<TConstructor extends PrimitiveConstructor>(key: EnvKeyInput, options: {
+  converter: TConstructor;
+  fallback: undefined;
+  required?: false;
+}): EnvaptAccessorDecorator<InferPrimitiveReturnType<TConstructor> | undefined>;
+declare function Envapt<TConstructor extends PrimitiveConstructor>(key: EnvKeyInput, options: {
+  converter: TConstructor;
+  required?: false;
+}): EnvaptAccessorDecorator<InferPrimitiveReturnType<TConstructor> | null>;
+/**
+ * Required, no converter (raw string). Throws `MissingEnvValue` on first access when the env
+ * value is missing or empty after trimming, independent of the global `Envapter.strict` flag.
+ * Pairing `required: true` with `fallback` matches no overload at compile time, and the runtime
+ * Validator rejects dynamic objects that bypass the types.
+ *
+ * @param key - Environment variable name(s) to load
+ * @param options - `{ required: true }`
+ * @public
+ * @example
+ * ```ts
+ * class Config {
+ *   \@Envapt('API_KEY', { required: true })
+ *   static accessor apiKey: string;
+ * }
+ * ```
+ */
+declare function Envapt(key: EnvKeyInput, options: {
+  required: true;
+}): EnvaptAccessorDecorator<string>;
+/**
+ * No-fallback form. The property resolves from env or `null`.
+ *
+ * @param key - Environment variable name(s) to load
+ * @public
+ * @example
+ * ```ts
+ * class Config {
+ *   \@Envapt('SIMPLE_VALUE')
+ *   static accessor simple: string | null;
+ * }
+ * ```
+ */
+declare function Envapt(key: EnvKeyInput): EnvaptAccessorDecorator<string | null>;
+/**
+ * A Standard Schema v1 adapter (zod, valibot, arktype, hand-rolled). Synchronous schemas only,
+ * so a Promise-returning `validate` throws `InvalidUserDefinedConfig` at runtime. Pairing
+ * `schema` with `converter` matches no overload at compile time, and the runtime Validator
+ * rejects dynamic objects that bypass the types.
+ * @public
+ */
+declare function Envapt<Schema extends StandardSchemaV1>(key: EnvKeyInput, options: {
+  schema: SchemaConstraint<Schema>;
+  fallback?: InferSchemaOutput<Schema>;
+  required?: false;
+} | {
+  schema: SchemaConstraint<Schema>;
+  required: true;
+}): EnvaptAccessorDecorator<InferSchemaOutput<Schema>>;
+//#endregion
+export { Envapt };
+//# sourceMappingURL=Envapt.d.cts.map