envapt 7.0.0-next.0 → 7.0.0-next.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (125) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/dist/browser/engine/PortableEnvapter.mjs +2 -0
  3. package/dist/browser/engine/PortableEnvapter.mjs.map +1 -0
  4. package/dist/browser/engine/installFileApiStubs.mjs +1 -1
  5. package/dist/browser/engine/installFileApiStubs.mjs.map +1 -1
  6. package/dist/browser/index.mjs +1 -2
  7. package/dist/{node → types}/engine/NodeEnvapter.d.mts +0 -2
  8. package/dist/types/engine/PortableEnvapter.d.mts +14 -0
  9. package/dist/{node → types}/index.d.mts +0 -2
  10. package/dist/{browser/index.d.mts → types/index.portable.d.mts} +2 -2
  11. package/dist/{node/sources/NodeEnvSource.d.cts → types/sources/NodeEnvSource.d.mts} +2 -2
  12. package/dist/workerd/engine/PortableEnvapter.mjs +2 -0
  13. package/dist/workerd/engine/PortableEnvapter.mjs.map +1 -0
  14. package/dist/workerd/engine/installFileApiStubs.mjs +1 -1
  15. package/dist/workerd/engine/installFileApiStubs.mjs.map +1 -1
  16. package/dist/workerd/index.mjs +1 -2
  17. package/package.json +25 -22
  18. package/dist/browser/index.mjs.map +0 -1
  19. package/dist/node/config.d.mts +0 -2
  20. package/dist/node/converters/Converters.d.cts +0 -93
  21. package/dist/node/converters/Converters.d.mts +0 -95
  22. package/dist/node/converters/ValueConverter.d.cts +0 -25
  23. package/dist/node/converters/ValueConverter.d.mts +0 -27
  24. package/dist/node/core/AdvancedMethods.d.cts +0 -76
  25. package/dist/node/core/AdvancedMethods.d.mts +0 -78
  26. package/dist/node/core/EnvapterBase.d.cts +0 -75
  27. package/dist/node/core/EnvapterBase.d.mts +0 -77
  28. package/dist/node/core/EnvironmentMethods.d.cts +0 -115
  29. package/dist/node/core/EnvironmentMethods.d.mts +0 -117
  30. package/dist/node/core/PrimitiveMethods.d.cts +0 -70
  31. package/dist/node/core/PrimitiveMethods.d.mts +0 -72
  32. package/dist/node/decorators/legacy/Envapt.d.cts +0 -218
  33. package/dist/node/decorators/legacy/Envapt.d.mts +0 -220
  34. package/dist/node/decorators/legacy/SugarDecorators.d.cts +0 -40
  35. package/dist/node/decorators/legacy/SugarDecorators.d.mts +0 -42
  36. package/dist/node/decorators/modern/Envapt.d.cts +0 -218
  37. package/dist/node/decorators/modern/Envapt.d.mts +0 -220
  38. package/dist/node/decorators/modern/SugarDecorators.d.cts +0 -40
  39. package/dist/node/decorators/modern/SugarDecorators.d.mts +0 -42
  40. package/dist/node/engine/Envapter.d.cts +0 -70
  41. package/dist/node/engine/Envapter.d.mts +0 -72
  42. package/dist/node/engine/NodeEnvapter.d.cts +0 -73
  43. package/dist/node/engine/TemplateResolver.d.cts +0 -17
  44. package/dist/node/engine/TemplateResolver.d.mts +0 -19
  45. package/dist/node/index.d.cts +0 -19
  46. package/dist/node/infra/Debug.d.cts +0 -13
  47. package/dist/node/infra/Debug.d.mts +0 -15
  48. package/dist/node/infra/Dotenv.d.cts +0 -17
  49. package/dist/node/infra/Dotenv.d.mts +0 -19
  50. package/dist/node/infra/Error.d.cts +0 -72
  51. package/dist/node/infra/Error.d.mts +0 -74
  52. package/dist/node/infra/StandardSchema.d.cts +0 -59
  53. package/dist/node/infra/StandardSchema.d.mts +0 -61
  54. package/dist/node/legacy.d.cts +0 -4
  55. package/dist/node/legacy.d.mts +0 -6
  56. package/dist/node/sources/ManualEnvSource.d.cts +0 -19
  57. package/dist/node/sources/ManualEnvSource.d.mts +0 -21
  58. package/dist/node/sources/NodeEnvSource.d.mts +0 -22
  59. package/dist/node/sources/WorkerEnvSource.d.cts +0 -19
  60. package/dist/node/sources/WorkerEnvSource.d.mts +0 -21
  61. package/dist/node/types/Conversion.d.cts +0 -123
  62. package/dist/node/types/Conversion.d.mts +0 -125
  63. package/dist/node/types/Decorator.d.cts +0 -26
  64. package/dist/node/types/Decorator.d.mts +0 -28
  65. package/dist/node/types/Env.d.cts +0 -17
  66. package/dist/node/types/Env.d.mts +0 -19
  67. package/dist/node/types/Options.d.cts +0 -39
  68. package/dist/node/types/Options.d.mts +0 -41
  69. package/dist/node/types/Schema.d.cts +0 -12
  70. package/dist/node/types/Schema.d.mts +0 -14
  71. package/dist/node/types/Source.d.cts +0 -44
  72. package/dist/node/types/Source.d.mts +0 -46
  73. package/dist/workerd/converters/Converters.d.mts +0 -93
  74. package/dist/workerd/converters/ValueConverter.d.mts +0 -25
  75. package/dist/workerd/core/AdvancedMethods.d.mts +0 -76
  76. package/dist/workerd/core/EnvapterBase.d.mts +0 -75
  77. package/dist/workerd/core/EnvironmentMethods.d.mts +0 -115
  78. package/dist/workerd/core/PrimitiveMethods.d.mts +0 -70
  79. package/dist/workerd/decorators/legacy/Envapt.d.mts +0 -218
  80. package/dist/workerd/decorators/legacy/SugarDecorators.d.mts +0 -40
  81. package/dist/workerd/decorators/modern/Envapt.d.mts +0 -218
  82. package/dist/workerd/decorators/modern/SugarDecorators.d.mts +0 -40
  83. package/dist/workerd/engine/Envapter.d.mts +0 -70
  84. package/dist/workerd/engine/TemplateResolver.d.mts +0 -17
  85. package/dist/workerd/index.d.mts +0 -18
  86. package/dist/workerd/index.mjs.map +0 -1
  87. package/dist/workerd/infra/Debug.d.mts +0 -13
  88. package/dist/workerd/infra/Dotenv.d.mts +0 -17
  89. package/dist/workerd/infra/Error.d.mts +0 -72
  90. package/dist/workerd/infra/StandardSchema.d.mts +0 -59
  91. package/dist/workerd/legacy.d.mts +0 -4
  92. package/dist/workerd/sources/ManualEnvSource.d.mts +0 -19
  93. package/dist/workerd/sources/WorkerEnvSource.d.mts +0 -19
  94. package/dist/workerd/types/Conversion.d.mts +0 -123
  95. package/dist/workerd/types/Decorator.d.mts +0 -26
  96. package/dist/workerd/types/Env.d.mts +0 -17
  97. package/dist/workerd/types/Options.d.mts +0 -39
  98. package/dist/workerd/types/Schema.d.mts +0 -12
  99. package/dist/workerd/types/Source.d.mts +0 -44
  100. /package/dist/{node/config.d.cts → types/config.d.mts} +0 -0
  101. /package/dist/{browser → types}/converters/Converters.d.mts +0 -0
  102. /package/dist/{browser → types}/converters/ValueConverter.d.mts +0 -0
  103. /package/dist/{browser → types}/core/AdvancedMethods.d.mts +0 -0
  104. /package/dist/{browser → types}/core/EnvapterBase.d.mts +0 -0
  105. /package/dist/{browser → types}/core/EnvironmentMethods.d.mts +0 -0
  106. /package/dist/{browser → types}/core/PrimitiveMethods.d.mts +0 -0
  107. /package/dist/{browser → types}/decorators/legacy/Envapt.d.mts +0 -0
  108. /package/dist/{browser → types}/decorators/legacy/SugarDecorators.d.mts +0 -0
  109. /package/dist/{browser → types}/decorators/modern/Envapt.d.mts +0 -0
  110. /package/dist/{browser → types}/decorators/modern/SugarDecorators.d.mts +0 -0
  111. /package/dist/{browser → types}/engine/Envapter.d.mts +0 -0
  112. /package/dist/{browser → types}/engine/TemplateResolver.d.mts +0 -0
  113. /package/dist/{browser → types}/infra/Debug.d.mts +0 -0
  114. /package/dist/{browser → types}/infra/Dotenv.d.mts +0 -0
  115. /package/dist/{browser → types}/infra/Error.d.mts +0 -0
  116. /package/dist/{browser → types}/infra/StandardSchema.d.mts +0 -0
  117. /package/dist/{browser → types}/legacy.d.mts +0 -0
  118. /package/dist/{browser → types}/sources/ManualEnvSource.d.mts +0 -0
  119. /package/dist/{browser → types}/sources/WorkerEnvSource.d.mts +0 -0
  120. /package/dist/{browser → types}/types/Conversion.d.mts +0 -0
  121. /package/dist/{browser → types}/types/Decorator.d.mts +0 -0
  122. /package/dist/{browser → types}/types/Env.d.mts +0 -0
  123. /package/dist/{browser → types}/types/Options.d.mts +0 -0
  124. /package/dist/{browser → types}/types/Schema.d.mts +0 -0
  125. /package/dist/{browser → types}/types/Source.d.mts +0 -0
@@ -1,76 +0,0 @@
1
- import { ArrayOf } from "../converters/Converters.mjs";
2
- import { AdvancedConverterReturn, BuiltInConverter, ConditionalReturn, ConverterFunction, InferConverterReturnType, TimeFallback } from "../types/Conversion.mjs";
3
- import { InferSchemaOutput, StandardSchemaV1 } from "../infra/StandardSchema.mjs";
4
- import { SchemaConstraint } from "../types/Schema.mjs";
5
- import { EnvKeyInput } from "../types/Env.mjs";
6
- import { PrimitiveMethods } from "./PrimitiveMethods.mjs";
7
-
8
- //#region src/core/AdvancedMethods.d.ts
9
- interface GetUsingRequiredOptions<TConverter> {
10
- converter: TConverter;
11
- required: true;
12
- }
13
- interface GetWithRequiredOptions<TReturnType> {
14
- converter: ConverterFunction<TReturnType>;
15
- required: true;
16
- }
17
- /**
18
- * Mixin for advanced methods for environment variable conversion using built-in and custom converters
19
- * @internal
20
- */
21
- declare class AdvancedMethods extends PrimitiveMethods {
22
- /**
23
- * Get an environment variable using a built-in converter.
24
- *
25
- * Supports both scalar tokens (e.g. `Converters.Number`) and `ArrayOf<...>` tokens
26
- * produced by `Converters.array(...)`. The key can be a single name or an ordered list;
27
- * the first defined value wins.
28
- */
29
- static getUsing<TFallback extends TimeFallback | undefined = undefined>(key: EnvKeyInput, converter: 'time', fallback?: TFallback): ConditionalReturn<number, TFallback>;
30
- static getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(key: EnvKeyInput, converter: TConverter, fallback?: TFallback): AdvancedConverterReturn<TConverter, TFallback>;
31
- static getUsing<TReturn>(key: EnvKeyInput, converter: BuiltInConverter | ArrayOf, fallback?: TReturn): TReturn;
32
- static getUsing(key: EnvKeyInput, options: GetUsingRequiredOptions<'time'>): number;
33
- static getUsing<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, options: GetUsingRequiredOptions<TConverter>): InferConverterReturnType<TConverter>;
34
- /**
35
- * @see {@link AdvancedMethods.getUsing}
36
- */
37
- getUsing<TFallback extends TimeFallback | undefined = undefined>(key: EnvKeyInput, converter: 'time', fallback?: TFallback): ConditionalReturn<number, TFallback>;
38
- getUsing<TConverter extends BuiltInConverter | ArrayOf, TFallback = undefined>(key: EnvKeyInput, converter: TConverter, fallback?: TFallback): AdvancedConverterReturn<TConverter, TFallback>;
39
- getUsing<TReturn>(key: EnvKeyInput, converter: BuiltInConverter | ArrayOf, fallback?: TReturn): TReturn;
40
- getUsing(key: EnvKeyInput, options: GetUsingRequiredOptions<'time'>): number;
41
- getUsing<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, options: GetUsingRequiredOptions<TConverter>): InferConverterReturnType<TConverter>;
42
- /**
43
- * Get an environment variable using a custom converter function.
44
- * Accepts a single key or an ordered list for automatic fallback.
45
- */
46
- static getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(key: EnvKeyInput, converter: ConverterFunction<TReturnType>, fallback?: TFallback): ConditionalReturn<TReturnType, TFallback>;
47
- static getWith<TReturnType>(key: EnvKeyInput, options: GetWithRequiredOptions<TReturnType>): TReturnType;
48
- /**
49
- * @see {@link AdvancedMethods.getWith}
50
- */
51
- getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(key: EnvKeyInput, converter: ConverterFunction<TReturnType>, fallback?: TFallback): ConditionalReturn<TReturnType, TFallback>;
52
- getWith<TReturnType>(key: EnvKeyInput, options: GetWithRequiredOptions<TReturnType>): TReturnType;
53
- /**
54
- * Validate an environment variable through a {@link StandardSchemaV1}-conformant schema
55
- * (zod, valibot, arktype, etc). Throws `MissingEnvValue` if the env value is absent and
56
- * no fallback is provided. The fallback, when provided, is returned as-is on missing;
57
- * it does NOT pass through the schema (mirrors custom-converter behavior).
58
- *
59
- * Synchronous schemas only. A Promise-returning `validate` triggers an
60
- * `InvalidUserDefinedConfig` throw at the call site.
61
- *
62
- * @example
63
- * ```ts
64
- * import { z } from 'zod';
65
- * const port = Envapter.parse('PORT', z.coerce.number().min(1024).max(65535), 3000);
66
- * ```
67
- */
68
- static parse<Schema extends StandardSchemaV1>(key: EnvKeyInput, schema: SchemaConstraint<Schema>, fallback?: InferSchemaOutput<Schema>): InferSchemaOutput<Schema>;
69
- /**
70
- * @see {@link AdvancedMethods.parse}
71
- */
72
- parse<Schema extends StandardSchemaV1>(key: EnvKeyInput, schema: SchemaConstraint<Schema>, fallback?: InferSchemaOutput<Schema>): InferSchemaOutput<Schema>;
73
- }
74
- //#endregion
75
- export { AdvancedMethods };
76
- //# sourceMappingURL=AdvancedMethods.d.mts.map
@@ -1,75 +0,0 @@
1
- import { DebugLevel } from "../infra/Debug.mjs";
2
- import { EnvFileOptions } from "../infra/Dotenv.mjs";
3
- import { EnvKeyInput } from "../types/Env.mjs";
4
- import { EnvSource, FileEnvSource } from "../types/Source.mjs";
5
-
6
- //#region src/core/EnvapterBase.d.ts
7
- /** @internal */
8
- declare abstract class EnvapterBase {
9
- protected static _envPaths: string[];
10
- protected static _envPathsExplicitlySet: boolean;
11
- protected static _baseDir: string | undefined;
12
- protected static _userDefinedEnvFileOptions: EnvFileOptions;
13
- protected static _strict: boolean;
14
- protected static _syncProcessEnv: boolean;
15
- protected static _dotenvAddedKeys: Set<string>;
16
- protected static _source: EnvSource;
17
- /**
18
- * Enable or disable strict mode. Default `false`. Setting refreshes the cache so
19
- * previously-cached converted values get re-evaluated under the new rule.
20
- */
21
- static set strict(value: boolean);
22
- static get strict(): boolean;
23
- /**
24
- * Set the debug log level. Defaults to `silent`. When unset, reads `ENVAPT_DEBUG` from the
25
- * bound source on first access; the setter overrides any env-var value. Output goes to stderr
26
- * on Node (the console elsewhere), prefixed with `[envapt]`.
27
- */
28
- static set debug(level: DebugLevel);
29
- static get debug(): DebugLevel;
30
- /**
31
- * Opt-in mirror of dotenv-loaded keys back to `process.env`. Default `false`.
32
- *
33
- * Only keys the loader actually wrote are mirrored, so collision behavior follows
34
- * `envFileOptions.override`: with the default `false`, pre-existing `process.env` values
35
- * are preserved; with `true`, the file value wins in both the cache and the mirror.
36
- *
37
- * Flipping `false → true` mirrors the existing tracked delta immediately (no cache
38
- * refresh). Flipping `true → false` is one-way: previously mirrored keys remain in
39
- * `process.env` until the process exits.
40
- */
41
- static set syncProcessEnv(value: boolean);
42
- static get syncProcessEnv(): boolean;
43
- protected static treatAsMissing(value: string | undefined): boolean;
44
- protected static resolveAgainstBase(candidate: string): string;
45
- protected static assertFileApiSupported(api: string, source: EnvSource): asserts source is FileEnvSource;
46
- protected static sourceFileExists(path: string): boolean;
47
- protected static refreshCache(): void;
48
- protected static mirrorToProcessEnv(): void;
49
- protected static resolveEffectivePaths(): string[];
50
- protected static resolveKeyInput(keyInput: EnvKeyInput): {
51
- key: string;
52
- value: string | undefined;
53
- };
54
- protected static get config(): Map<string, unknown>;
55
- /**
56
- * Eagerly load the `.env` cascade now instead of lazily on the first read. Idempotent: a no-op
57
- * once the cache is built. Useful before mirroring to `process.env` (see {@link syncProcessEnv}),
58
- * which is what the `envapt/config` side-effect entry does.
59
- */
60
- static load(): void;
61
- /**
62
- * Bind the environment {@link EnvSource}. On Node the entry binds {@link NodeEnvSource} for you
63
- * (a `process.env` snapshot plus the `.env` cascade); on the browser or Workers, pass a
64
- * `ManualEnvSource` / `WorkerEnvSource` (or any `EnvSource`) before reading. Clears and rebuilds
65
- * the cache.
66
- */
67
- static useSource(source: EnvSource): void;
68
- /**
69
- * Read an environment variable as its raw string, skipping parsing and conversion.
70
- */
71
- getRaw(key: EnvKeyInput): string | undefined;
72
- }
73
- //#endregion
74
- export { EnvapterBase };
75
- //# sourceMappingURL=EnvapterBase.d.mts.map
@@ -1,115 +0,0 @@
1
- import { EnvapterBase } from "./EnvapterBase.mjs";
2
- import { ProfilesConfig } from "../types/Options.mjs";
3
-
4
- //#region src/core/EnvironmentMethods.d.ts
5
- /**
6
- * Environment types supported by Envapter
7
- * @public
8
- */
9
- declare enum Environment {
10
- Development = 0,
11
- Staging = 1,
12
- Production = 2,
13
- Test = 3
14
- }
15
- /**
16
- * Mixin for environment detection and checking methods
17
- * @internal
18
- */
19
- declare class EnvironmentMethods extends EnvapterBase {
20
- protected static _environment: Environment | undefined;
21
- protected static _environmentExplicitlySet: boolean;
22
- protected static _profiles: ProfilesConfig | undefined;
23
- protected static determineEnvironment(env?: string | Environment): void;
24
- private static firstEnvKeyValue;
25
- /**
26
- * Get the current application environment
27
- */
28
- static get environment(): Environment;
29
- /**
30
- * Set the application environment. Accepts either Environment enum or string value.
31
- */
32
- static set environment(env: string | Environment);
33
- /**
34
- * @see {@link EnvironmentMethods.environment}
35
- */
36
- get environment(): Environment;
37
- /**
38
- * @see {@link EnvironmentMethods.environment}
39
- */
40
- set environment(env: string | Environment);
41
- /**
42
- * Check if the current environment is production
43
- */
44
- static get isProduction(): boolean;
45
- /**
46
- * @see {@link EnvironmentMethods.isProduction}
47
- */
48
- get isProduction(): boolean;
49
- /**
50
- * Check if the current environment is staging
51
- */
52
- static get isStaging(): boolean;
53
- /**
54
- * @see {@link EnvironmentMethods.isStaging}
55
- */
56
- get isStaging(): boolean;
57
- /**
58
- * Check if the current environment is development
59
- */
60
- static get isDevelopment(): boolean;
61
- /**
62
- * @see {@link EnvironmentMethods.isDevelopment}
63
- */
64
- get isDevelopment(): boolean;
65
- /**
66
- * Check if the current environment is test
67
- */
68
- static get isTest(): boolean;
69
- /**
70
- * @see {@link EnvironmentMethods.isTest}
71
- */
72
- get isTest(): boolean;
73
- protected static refreshCache(): void;
74
- /**
75
- * Reads the source's raw vars (not `this.config`, which would recurse: cascade selection runs
76
- * before the `.env` load). `Envapter.environment` may differ post-load if a file sets `ENVIRONMENT`.
77
- * @internal
78
- */
79
- protected static getCascadeEnvironment(): Environment;
80
- /**
81
- * Build the dotenv-flow cascade for a given environment, in dotenv first-wins precedence
82
- * order (highest precedence first). Missing files are silently filtered.
83
- *
84
- * Precedence is **most-specific-wins** (matches Vite / Astro / Vocs):
85
- * `.env.${env}.local` \> `.env.${env}` \> `.env.local` \> `.env`
86
- *
87
- * This differs from dotenv-flow / Next.js convention which puts `.env.local` above
88
- * `.env.${env}`. We chose the most-specific-wins order so committed env-specific files
89
- * (`.env.production`) are authoritative for that environment regardless of whether a
90
- * stray `.env.local` is present.
91
- * @internal
92
- */
93
- protected static buildCascadePaths(env: Environment): string[];
94
- private static normalizeProfilePaths;
95
- /**
96
- * Override the base implementation to layer the dotenv-flow cascade + any
97
- * `Envapter.configureProfiles` overrides on top of `_envPaths` when the user has NOT
98
- * explicitly set `envPaths`.
99
- *
100
- * Precedence (passed to dotenv with first-wins semantics):
101
- * 1. profile-configured paths for the current env (if any)
102
- * 2. `.env.${env}.local`
103
- * 3. `.env.${env}`
104
- * 4. `.env.local`
105
- * 5. `.env`
106
- *
107
- * If `useDefaults: false` is set on the profiles config, only (1) is loaded, no cascade.
108
- * If `envPaths` was explicitly set, only `envPaths` is loaded (everything else ignored).
109
- * @internal
110
- */
111
- protected static resolveEffectivePaths(): string[];
112
- }
113
- //#endregion
114
- export { Environment, EnvironmentMethods };
115
- //# sourceMappingURL=EnvironmentMethods.d.mts.map
@@ -1,70 +0,0 @@
1
- import { ConditionalReturn } from "../types/Conversion.mjs";
2
- import { EnvironmentMethods } from "./EnvironmentMethods.mjs";
3
- import { EnvKeyInput, EnvapterService } from "../types/Env.mjs";
4
- import { ValueConverter } from "../converters/ValueConverter.mjs";
5
- import { TemplateResolver } from "../engine/TemplateResolver.mjs";
6
-
7
- //#region src/core/PrimitiveMethods.d.ts
8
- /**
9
- * @internal
10
- */
11
- declare class PrimitiveMethods extends EnvironmentMethods implements EnvapterService {
12
- private static readonly service;
13
- protected static readonly templateResolver: TemplateResolver;
14
- protected static readonly valueConverter: ValueConverter;
15
- isStrict(): boolean;
16
- private static _get;
17
- /**
18
- * Get a string environment variable with optional fallback.
19
- * Supports template variable resolution using `${VAR}` syntax.
20
- * Accepts a single key or an ordered array of keys (first match wins).
21
- */
22
- static get<Default extends string | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<string, Default>;
23
- /**
24
- * @see {@link PrimitiveMethods.get}
25
- */
26
- get<Default extends string | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<string, Default>;
27
- /**
28
- * Get a number environment variable with optional fallback.
29
- * Automatically converts string values to numbers.
30
- * Accepts a single key or an ordered array of keys (first match wins).
31
- */
32
- static getNumber<Default extends number | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<number, Default>;
33
- /**
34
- * @see {@link PrimitiveMethods.getNumber}
35
- */
36
- getNumber<Default extends number | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<number, Default>;
37
- /**
38
- * Get a boolean environment variable with optional fallback.
39
- * Recognizes: `1`, `yes`, `true`, `on` as **true**; `0`, `no`, `false`, `off` as **false** (case-insensitive).
40
- * Accepts a single key or an ordered array of keys (first match wins).
41
- */
42
- static getBoolean<Default extends boolean | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<boolean, Default>;
43
- /**
44
- * @see {@link PrimitiveMethods.getBoolean}
45
- */
46
- getBoolean<Default extends boolean | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<boolean, Default>;
47
- /**
48
- * Get a bigint environment variable with optional fallback.
49
- * Automatically converts string values to bigint.
50
- * Accepts a single key or an ordered array of keys (first match wins).
51
- */
52
- static getBigInt<Default extends bigint | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<bigint, Default>;
53
- /**
54
- * @see {@link PrimitiveMethods.getBigInt}
55
- */
56
- getBigInt<Default extends bigint | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<bigint, Default>;
57
- /**
58
- * Get a symbol environment variable with optional fallback.
59
- * Creates a symbol from the string value.
60
- * Accepts a single key or an ordered array of keys (first match wins).
61
- */
62
- static getSymbol<Default extends symbol | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<symbol, Default>;
63
- /**
64
- * @see {@link PrimitiveMethods.getSymbol}
65
- */
66
- getSymbol<Default extends symbol | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<symbol, Default>;
67
- }
68
- //#endregion
69
- export { PrimitiveMethods };
70
- //# sourceMappingURL=PrimitiveMethods.d.mts.map
@@ -1,218 +0,0 @@
1
- import { ArrayOf } from "../../converters/Converters.mjs";
2
- import { BuiltInConverter, ConverterFunction, InferConverterFallbackType, InferConverterReturnType, InferPrimitiveReturnType, PrimitiveConstructor } from "../../types/Conversion.mjs";
3
- import { InferSchemaOutput, StandardSchemaV1 } from "../../infra/StandardSchema.mjs";
4
- import { SchemaConstraint } from "../../types/Schema.mjs";
5
- import { EnvKeyInput } from "../../types/Env.mjs";
6
- import { EnvaptFieldDecorator } from "../../types/Decorator.mjs";
7
-
8
- //#region src/decorators/legacy/Envapt.d.ts
9
- /**
10
- * A custom converter function with a fallback (both required), or a fallback only.
11
- *
12
- * @param key - Environment variable name(s) to load
13
- * @param options - Configuration options
14
- * @public
15
- * @example
16
- * ```ts
17
- * class Config extends Envapter {
18
- * \@Envapt('API_KEY', {
19
- * fallback: 'default-key',
20
- * converter(raw, _fallback) {
21
- * if (!raw || raw.trim() === '') throw new Error('API_KEY required');
22
- * return raw.trim();
23
- * }
24
- * })
25
- * static readonly apiKey: string;
26
- *
27
- * \@Envapt('LOG_FILE', { fallback: '/var/log/app.log' })
28
- * static readonly logFile: string;
29
- *
30
- * \@Envapt('RETRY_POLICY', { fallback: { retries: 3, backoff: 'exponential' } })
31
- * static readonly retryPolicy: unknown;
32
- * }
33
- * ```
34
- */
35
- declare function Envapt(key: EnvKeyInput, options: {
36
- fallback: undefined;
37
- converter?: undefined;
38
- }): EnvaptFieldDecorator<string | undefined>;
39
- declare function Envapt<TFallback>(key: EnvKeyInput, options: {
40
- converter: (raw: string | undefined, fallback: TFallback) => TFallback;
41
- fallback: TFallback;
42
- } | {
43
- fallback: TFallback;
44
- converter?: undefined;
45
- }): EnvaptFieldDecorator<TFallback>;
46
- /**
47
- * A custom converter function without a fallback. Omit `required` to return the converter's
48
- * output (possibly `undefined`), or pass `required: true` to throw `MissingEnvValue` on
49
- * missing or empty values.
50
- *
51
- * @param key - Environment variable name(s) to load
52
- * @param options - Configuration options
53
- * @public
54
- * @example
55
- * ```ts
56
- * class Config extends Envapter {
57
- * \@Envapt('FEATURE_FLAGS', { converter(raw) {
58
- * return raw ? raw.split('|').map(s => s.trim()) : [];
59
- * } })
60
- * static readonly featureFlags: string[];
61
- *
62
- * \@Envapt('JWT_SECRET', {
63
- * converter: (raw) => Buffer.from(raw ?? '', 'base64'),
64
- * required: true
65
- * })
66
- * static readonly jwtSecret: Buffer;
67
- * }
68
- * ```
69
- */
70
- declare function Envapt<TReturnType>(key: EnvKeyInput, options: {
71
- converter: ConverterFunction<TReturnType>;
72
- required?: false;
73
- } | {
74
- converter: ConverterFunction<TReturnType>;
75
- required: true;
76
- }): EnvaptFieldDecorator<TReturnType>;
77
- /**
78
- * A built-in or array converter with a fallback, or `required: true`. The fallback type tracks
79
- * the converter, so `Converters.Time` takes a number or time-string and `Converters.Url` takes
80
- * a `URL` instance.
81
- *
82
- * @param key - Environment variable name(s) to load
83
- * @param options - Configuration options
84
- * @public
85
- * @example
86
- * ```ts
87
- * import { Converters } from 'envapt';
88
- *
89
- * class Config extends Envapter {
90
- * \@Envapt('APP_PORT', { converter: Converters.Number, fallback: 3000 })
91
- * static readonly port: number;
92
- *
93
- * // the Url fallback is a URL instance, not a string
94
- * \@Envapt('APP_URL', { converter: Converters.Url, fallback: new URL('http://localhost:3000') })
95
- * static readonly url: URL;
96
- *
97
- * // prefers CANARY_URL when present, otherwise APP_URL
98
- * \@Envapt(['CANARY_URL', 'APP_URL'], { converter: Converters.Url })
99
- * static readonly canaryUrl: URL | null;
100
- *
101
- * // Time takes a number (milliseconds) or a time-string fallback (`<number><unit>`)
102
- * \@Envapt('REQUEST_TIMEOUT', { converter: Converters.Time, fallback: '10s' })
103
- * static readonly requestTimeout: number;
104
- *
105
- * \@Envapt('ALLOWED_ORIGINS', {
106
- * converter: Converters.array({ of: Converters.String }),
107
- * fallback: ['https://example.com']
108
- * })
109
- * static readonly allowedOrigins: string[];
110
- *
111
- * \@Envapt('DATABASE_URL', { converter: Converters.Url, required: true })
112
- * static readonly databaseUrl: URL;
113
- * }
114
- * ```
115
- */
116
- declare function Envapt<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, options: {
117
- converter: TConverter;
118
- fallback: InferConverterFallbackType<TConverter>;
119
- required?: false;
120
- } | {
121
- converter: TConverter;
122
- required: true;
123
- }): EnvaptFieldDecorator<InferConverterReturnType<TConverter>>;
124
- declare function Envapt<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, options: {
125
- converter: TConverter;
126
- fallback: undefined;
127
- required?: false;
128
- }): EnvaptFieldDecorator<InferConverterReturnType<TConverter> | undefined>;
129
- declare function Envapt<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, options: {
130
- converter: TConverter;
131
- required?: false;
132
- }): EnvaptFieldDecorator<InferConverterReturnType<TConverter> | null>;
133
- /**
134
- * A primitive constructor (`Number`, `Boolean`) with an optional fallback.
135
- *
136
- * @param key - Environment variable name(s) to load
137
- * @param options - Configuration options
138
- * @public
139
- * @example
140
- * ```ts
141
- * class Config extends Envapter {
142
- * \@Envapt('MAX_CONNECTIONS', { converter: Number, fallback: 100 })
143
- * static readonly maxConnections: number;
144
- *
145
- * \@Envapt('FEATURE_ENABLED', { converter: Boolean, fallback: false })
146
- * static readonly featureEnabled: boolean;
147
- * }
148
- * ```
149
- */
150
- declare function Envapt<TConstructor extends PrimitiveConstructor>(key: EnvKeyInput, options: {
151
- converter: TConstructor;
152
- fallback: InferPrimitiveReturnType<TConstructor>;
153
- required?: false;
154
- } | {
155
- converter: TConstructor;
156
- required: true;
157
- }): EnvaptFieldDecorator<InferPrimitiveReturnType<TConstructor>>;
158
- declare function Envapt<TConstructor extends PrimitiveConstructor>(key: EnvKeyInput, options: {
159
- converter: TConstructor;
160
- fallback: undefined;
161
- required?: false;
162
- }): EnvaptFieldDecorator<InferPrimitiveReturnType<TConstructor> | undefined>;
163
- declare function Envapt<TConstructor extends PrimitiveConstructor>(key: EnvKeyInput, options: {
164
- converter: TConstructor;
165
- required?: false;
166
- }): EnvaptFieldDecorator<InferPrimitiveReturnType<TConstructor> | null>;
167
- /**
168
- * Required, no converter (raw string). Throws `MissingEnvValue` on first access when the env
169
- * value is missing or empty after trimming, independent of the global `Envapter.strict` flag.
170
- * Pairing `required: true` with `fallback` matches no overload at compile time, and the runtime
171
- * Validator rejects dynamic objects that bypass the types.
172
- *
173
- * @param key - Environment variable name(s) to load
174
- * @param options - `{ required: true }`
175
- * @public
176
- * @example
177
- * ```ts
178
- * class Config extends Envapter {
179
- * \@Envapt('API_KEY', { required: true })
180
- * static readonly apiKey: string;
181
- * }
182
- * ```
183
- */
184
- declare function Envapt(key: EnvKeyInput, options: {
185
- required: true;
186
- }): EnvaptFieldDecorator<string>;
187
- /**
188
- * No-fallback form. The property resolves from env or `null`.
189
- *
190
- * @param key - Environment variable name(s) to load
191
- * @public
192
- * @example
193
- * ```ts
194
- * class Config extends Envapter {
195
- * \@Envapt('SIMPLE_VALUE')
196
- * static readonly simple?: string | null;
197
- * }
198
- * ```
199
- */
200
- declare function Envapt(key: EnvKeyInput): EnvaptFieldDecorator<string | null>;
201
- /**
202
- * A Standard Schema v1 adapter (zod, valibot, arktype, hand-rolled). Synchronous schemas only,
203
- * so a Promise-returning `validate` throws `InvalidUserDefinedConfig` at runtime. Pairing
204
- * `schema` with `converter` matches no overload at compile time, and the runtime Validator
205
- * rejects dynamic objects that bypass the types.
206
- * @public
207
- */
208
- declare function Envapt<Schema extends StandardSchemaV1>(key: EnvKeyInput, options: {
209
- schema: SchemaConstraint<Schema>;
210
- fallback?: InferSchemaOutput<Schema>;
211
- required?: false;
212
- } | {
213
- schema: SchemaConstraint<Schema>;
214
- required: true;
215
- }): EnvaptFieldDecorator<InferSchemaOutput<Schema>>;
216
- //#endregion
217
- export { Envapt };
218
- //# sourceMappingURL=Envapt.d.mts.map
@@ -1,40 +0,0 @@
1
- import { TimeFallback } from "../../types/Conversion.mjs";
2
- import { EnvKeyInput } from "../../types/Env.mjs";
3
- import { EnvaptFieldDecorator } from "../../types/Decorator.mjs";
4
-
5
- //#region src/decorators/legacy/SugarDecorators.d.ts
6
- /**
7
- * Shorthand for `@Envapt(key, { converter: Converters.Boolean, fallback })`.
8
- * @public
9
- */
10
- declare function EnvBool(key: EnvKeyInput, fallback: boolean): EnvaptFieldDecorator<boolean>;
11
- declare function EnvBool(key: EnvKeyInput): EnvaptFieldDecorator<boolean | null>;
12
- /**
13
- * Shorthand for `@Envapt(key, { converter: Converters.Number, fallback })`.
14
- * @public
15
- */
16
- declare function EnvNum(key: EnvKeyInput, fallback: number): EnvaptFieldDecorator<number>;
17
- declare function EnvNum(key: EnvKeyInput): EnvaptFieldDecorator<number | null>;
18
- /**
19
- * Shorthand for `@Envapt(key, { converter: Converters.String, fallback })`.
20
- * @public
21
- */
22
- declare function EnvStr(key: EnvKeyInput, fallback: string): EnvaptFieldDecorator<string>;
23
- declare function EnvStr(key: EnvKeyInput): EnvaptFieldDecorator<string | null>;
24
- /**
25
- * Shorthand for `@Envapt(key, { converter: Converters.Time, fallback })`. The fallback is a
26
- * millisecond number or a time string (`'15m'`), and the resolved value is always milliseconds.
27
- * @public
28
- */
29
- declare function EnvTime(key: EnvKeyInput, fallback: TimeFallback): EnvaptFieldDecorator<number>;
30
- declare function EnvTime(key: EnvKeyInput): EnvaptFieldDecorator<number | null>;
31
- /**
32
- * Shorthand for `@Envapt(key, { converter: Converters.Url, fallback })`. The fallback is a `URL`
33
- * instance, not a URL string.
34
- * @public
35
- */
36
- declare function EnvUrl(key: EnvKeyInput, fallback: URL): EnvaptFieldDecorator<URL>;
37
- declare function EnvUrl(key: EnvKeyInput): EnvaptFieldDecorator<URL | null>;
38
- //#endregion
39
- export { EnvBool, EnvNum, EnvStr, EnvTime, EnvUrl };
40
- //# sourceMappingURL=SugarDecorators.d.mts.map