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

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

@@ -1,218 +0,0 @@
-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 { EnvaptFieldDecorator } from "../../types/Decorator.cjs";
-
-//#region src/decorators/legacy/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 extends Envapter {
- *   \@Envapt('API_KEY', {
- *     fallback: 'default-key',
- *     converter(raw, _fallback) {
- *       if (!raw || raw.trim() === '') throw new Error('API_KEY required');
- *       return raw.trim();
- *     }
- *   })
- *   static readonly apiKey: string;
- *
- *   \@Envapt('LOG_FILE', { fallback: '/var/log/app.log' })
- *   static readonly logFile: string;
- *
- *   \@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;
-}): EnvaptFieldDecorator<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 extends Envapter {
- *   \@Envapt('FEATURE_FLAGS', { converter(raw) {
- *     return raw ? raw.split('|').map(s => s.trim()) : [];
- *   } })
- *   static readonly featureFlags: string[];
- *
- *   \@Envapt('JWT_SECRET', {
- *     converter: (raw) => Buffer.from(raw ?? '', 'base64'),
- *     required: true
- *   })
- *   static readonly jwtSecret: Buffer;
- * }
- * ```
- */
-declare function Envapt<TReturnType>(key: EnvKeyInput, options: {
-  converter: ConverterFunction<TReturnType>;
-  required?: false;
-} | {
-  converter: ConverterFunction<TReturnType>;
-  required: true;
-}): EnvaptFieldDecorator<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 extends Envapter {
- *   \@Envapt('APP_PORT', { converter: Converters.Number, fallback: 3000 })
- *   static readonly 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 readonly url: URL;
- *
- *   // prefers CANARY_URL when present, otherwise APP_URL
- *   \@Envapt(['CANARY_URL', 'APP_URL'], { converter: Converters.Url })
- *   static readonly canaryUrl: URL | null;
- *
- *   // 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;
- * }
- * ```
- */
-declare function Envapt<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, options: {
-  converter: TConverter;
-  fallback: InferConverterFallbackType<TConverter>;
-  required?: false;
-} | {
-  converter: TConverter;
-  required: true;
-}): 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>;
-/**
- * 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 extends Envapter {
- *   \@Envapt('MAX_CONNECTIONS', { converter: Number, fallback: 100 })
- *   static readonly maxConnections: number;
- *
- *   \@Envapt('FEATURE_ENABLED', { converter: Boolean, fallback: false })
- *   static readonly featureEnabled: boolean;
- * }
- * ```
- */
-declare function Envapt<TConstructor extends PrimitiveConstructor>(key: EnvKeyInput, options: {
-  converter: TConstructor;
-  fallback: InferPrimitiveReturnType<TConstructor>;
-  required?: false;
-} | {
-  converter: TConstructor;
-  required: true;
-}): 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>;
-/**
- * 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 extends Envapter {
- *   \@Envapt('API_KEY', { required: true })
- *   static readonly apiKey: string;
- * }
- * ```
- */
-declare function Envapt(key: EnvKeyInput, options: {
-  required: true;
-}): EnvaptFieldDecorator<string>;
-/**
- * No-fallback form. The property resolves from env or `null`.
- *
- * @param key - Environment variable name(s) to load
- * @public
- * @example
- * ```ts
- * class Config extends Envapter {
- *   \@Envapt('SIMPLE_VALUE')
- *   static readonly simple?: string | null;
- * }
- * ```
- */
-declare function Envapt(key: EnvKeyInput): EnvaptFieldDecorator<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;
-}): EnvaptFieldDecorator<InferSchemaOutput<Schema>>;
-//#endregion
-export { Envapt };
-//# sourceMappingURL=Envapt.d.cts.map

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

@@ -1,220 +0,0 @@
-import __tsdown_shims_path from 'node:path';
-import __tsdown_shims_url from 'node:url';
-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/legacy/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 extends Envapter {
- *   \@Envapt('API_KEY', {
- *     fallback: 'default-key',
- *     converter(raw, _fallback) {
- *       if (!raw || raw.trim() === '') throw new Error('API_KEY required');
- *       return raw.trim();
- *     }
- *   })
- *   static readonly apiKey: string;
- *
- *   \@Envapt('LOG_FILE', { fallback: '/var/log/app.log' })
- *   static readonly logFile: string;
- *
- *   \@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;
-}): EnvaptFieldDecorator<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 extends Envapter {
- *   \@Envapt('FEATURE_FLAGS', { converter(raw) {
- *     return raw ? raw.split('|').map(s => s.trim()) : [];
- *   } })
- *   static readonly featureFlags: string[];
- *
- *   \@Envapt('JWT_SECRET', {
- *     converter: (raw) => Buffer.from(raw ?? '', 'base64'),
- *     required: true
- *   })
- *   static readonly jwtSecret: Buffer;
- * }
- * ```
- */
-declare function Envapt<TReturnType>(key: EnvKeyInput, options: {
-  converter: ConverterFunction<TReturnType>;
-  required?: false;
-} | {
-  converter: ConverterFunction<TReturnType>;
-  required: true;
-}): EnvaptFieldDecorator<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 extends Envapter {
- *   \@Envapt('APP_PORT', { converter: Converters.Number, fallback: 3000 })
- *   static readonly 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 readonly url: URL;
- *
- *   // prefers CANARY_URL when present, otherwise APP_URL
- *   \@Envapt(['CANARY_URL', 'APP_URL'], { converter: Converters.Url })
- *   static readonly canaryUrl: URL | null;
- *
- *   // 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;
- * }
- * ```
- */
-declare function Envapt<TConverter extends BuiltInConverter | ArrayOf>(key: EnvKeyInput, options: {
-  converter: TConverter;
-  fallback: InferConverterFallbackType<TConverter>;
-  required?: false;
-} | {
-  converter: TConverter;
-  required: true;
-}): 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>;
-/**
- * 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 extends Envapter {
- *   \@Envapt('MAX_CONNECTIONS', { converter: Number, fallback: 100 })
- *   static readonly maxConnections: number;
- *
- *   \@Envapt('FEATURE_ENABLED', { converter: Boolean, fallback: false })
- *   static readonly featureEnabled: boolean;
- * }
- * ```
- */
-declare function Envapt<TConstructor extends PrimitiveConstructor>(key: EnvKeyInput, options: {
-  converter: TConstructor;
-  fallback: InferPrimitiveReturnType<TConstructor>;
-  required?: false;
-} | {
-  converter: TConstructor;
-  required: true;
-}): 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>;
-/**
- * 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 extends Envapter {
- *   \@Envapt('API_KEY', { required: true })
- *   static readonly apiKey: string;
- * }
- * ```
- */
-declare function Envapt(key: EnvKeyInput, options: {
-  required: true;
-}): EnvaptFieldDecorator<string>;
-/**
- * No-fallback form. The property resolves from env or `null`.
- *
- * @param key - Environment variable name(s) to load
- * @public
- * @example
- * ```ts
- * class Config extends Envapter {
- *   \@Envapt('SIMPLE_VALUE')
- *   static readonly simple?: string | null;
- * }
- * ```
- */
-declare function Envapt(key: EnvKeyInput): EnvaptFieldDecorator<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;
-}): EnvaptFieldDecorator<InferSchemaOutput<Schema>>;
-//#endregion
-export { Envapt };
-//# sourceMappingURL=Envapt.d.mts.map

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

@@ -1,40 +0,0 @@
-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

@@ -1,42 +0,0 @@
-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