dev-env-toolkit 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,170 @@
+/**
+ * Represents a validation error for an environment variable
+ */
+interface EnvValidationError {
+    key: string;
+    message: string;
+    value?: string;
+    expected?: string;
+}
+/**
+ * Result of parsing environment variables
+ */
+type EnvParseResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    errors: EnvValidationError[];
+};
+/**
+ * Options for the env parser
+ */
+interface EnvParseOptions {
+    /** Path to .env file (optional) */
+    path?: string;
+    /** Whether to throw on validation errors (default: true) */
+    throwOnError?: boolean;
+    /** Custom environment object (default: process.env) */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Base validator interface
+ */
+interface Validator<T> {
+    _type: T;
+    _optional: boolean;
+    _default?: T;
+    parse(value: string | undefined, key: string): T;
+    optional(): Validator<T | undefined>;
+    default(value: T): Validator<T>;
+}
+/**
+ * String validator with additional methods
+ */
+interface StringValidator extends Validator<string> {
+    min(length: number): StringValidator;
+    max(length: number): StringValidator;
+    url(): StringValidator;
+    email(): StringValidator;
+    regex(pattern: RegExp): StringValidator;
+}
+/**
+ * Number validator with additional methods
+ */
+interface NumberValidator extends Validator<number> {
+    min(value: number): NumberValidator;
+    max(value: number): NumberValidator;
+    int(): NumberValidator;
+    positive(): NumberValidator;
+    port(): NumberValidator;
+}
+/**
+ * Boolean validator
+ */
+interface BooleanValidator extends Validator<boolean> {
+}
+/**
+ * Enum validator
+ */
+interface EnumValidator<T extends string> extends Validator<T> {
+}
+/**
+ * Array validator with additional methods
+ */
+interface ArrayValidator extends Validator<string[]> {
+    separator(sep: string): ArrayValidator;
+    min(length: number): ArrayValidator;
+    max(length: number): ArrayValidator;
+}
+/**
+ * Schema definition type - maps keys to validators
+ */
+type EnvSchema = Record<string, Validator<unknown>>;
+/**
+ * Infer the output type from a schema
+ */
+type InferEnv<T extends EnvSchema> = {
+    [K in keyof T]: T[K]['_optional'] extends true ? T[K]['_type'] | undefined : T[K]['_type'];
+};
+
+/**
+ * Parse a .env file and return key-value pairs
+ */
+declare function parseEnvFile(filePath: string): Record<string, string>;
+/**
+ * Load environment variables from a .env file into the current environment
+ */
+declare function loadEnvFile(filePath?: string, options?: {
+    override?: boolean;
+}): Record<string, string>;
+
+/**
+ * Custom error class for environment validation errors
+ */
+declare class EnvValidationException extends Error {
+    readonly errors: EnvValidationError[];
+    constructor(errors: EnvValidationError[]);
+}
+/**
+ * Custom error for parsing errors
+ */
+declare class EnvParseError extends Error {
+    readonly key: string;
+    readonly value?: string;
+    constructor(key: string, message: string, value?: string);
+}
+
+/**
+ * Create a type-safe environment configuration
+ *
+ * @example
+ * ```typescript
+ * import { env } from 'dev-env-toolkit';
+ *
+ * const config = env.create({
+ *   PORT: env.number().default(3000),
+ *   DATABASE_URL: env.string(),
+ *   NODE_ENV: env.enum(['development', 'production', 'test']),
+ *   DEBUG: env.boolean().default(false),
+ * });
+ *
+ * // Fully typed!
+ * console.log(config.PORT); // number
+ * console.log(config.DEBUG); // boolean
+ * ```
+ */
+declare function create<T extends EnvSchema>(schema: T, options?: EnvParseOptions): InferEnv<T>;
+/**
+ * Safely parse environment variables without throwing
+ *
+ * @example
+ * ```typescript
+ * const result = env.safeParse({
+ *   PORT: env.number(),
+ * });
+ *
+ * if (result.success) {
+ *   console.log(result.data.PORT);
+ * } else {
+ *   console.error(result.errors);
+ * }
+ * ```
+ */
+declare function safeParse<T extends EnvSchema>(schema: T, options?: Omit<EnvParseOptions, 'throwOnError'>): EnvParseResult<InferEnv<T>>;
+/**
+ * The main env object with all utilities
+ */
+declare const env: {
+    create: typeof create;
+    safeParse: typeof safeParse;
+    string: () => StringValidator;
+    number: () => NumberValidator;
+    boolean: () => BooleanValidator;
+    enum: <T extends string>(values: readonly T[]) => EnumValidator<T>;
+    array: () => ArrayValidator;
+    load: typeof loadEnvFile;
+    parse: typeof parseEnvFile;
+};
+
+export { type ArrayValidator, type BooleanValidator, type EnumValidator, EnvParseError, type EnvParseOptions, type EnvParseResult, type EnvSchema, type EnvValidationError, EnvValidationException, type InferEnv, type NumberValidator, type StringValidator, type Validator, env as default, env };

package/dist/index.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Represents a validation error for an environment variable
+ */
+interface EnvValidationError {
+    key: string;
+    message: string;
+    value?: string;
+    expected?: string;
+}
+/**
+ * Result of parsing environment variables
+ */
+type EnvParseResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    errors: EnvValidationError[];
+};
+/**
+ * Options for the env parser
+ */
+interface EnvParseOptions {
+    /** Path to .env file (optional) */
+    path?: string;
+    /** Whether to throw on validation errors (default: true) */
+    throwOnError?: boolean;
+    /** Custom environment object (default: process.env) */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Base validator interface
+ */
+interface Validator<T> {
+    _type: T;
+    _optional: boolean;
+    _default?: T;
+    parse(value: string | undefined, key: string): T;
+    optional(): Validator<T | undefined>;
+    default(value: T): Validator<T>;
+}
+/**
+ * String validator with additional methods
+ */
+interface StringValidator extends Validator<string> {
+    min(length: number): StringValidator;
+    max(length: number): StringValidator;
+    url(): StringValidator;
+    email(): StringValidator;
+    regex(pattern: RegExp): StringValidator;
+}
+/**
+ * Number validator with additional methods
+ */
+interface NumberValidator extends Validator<number> {
+    min(value: number): NumberValidator;
+    max(value: number): NumberValidator;
+    int(): NumberValidator;
+    positive(): NumberValidator;
+    port(): NumberValidator;
+}
+/**
+ * Boolean validator
+ */
+interface BooleanValidator extends Validator<boolean> {
+}
+/**
+ * Enum validator
+ */
+interface EnumValidator<T extends string> extends Validator<T> {
+}
+/**
+ * Array validator with additional methods
+ */
+interface ArrayValidator extends Validator<string[]> {
+    separator(sep: string): ArrayValidator;
+    min(length: number): ArrayValidator;
+    max(length: number): ArrayValidator;
+}
+/**
+ * Schema definition type - maps keys to validators
+ */
+type EnvSchema = Record<string, Validator<unknown>>;
+/**
+ * Infer the output type from a schema
+ */
+type InferEnv<T extends EnvSchema> = {
+    [K in keyof T]: T[K]['_optional'] extends true ? T[K]['_type'] | undefined : T[K]['_type'];
+};
+
+/**
+ * Parse a .env file and return key-value pairs
+ */
+declare function parseEnvFile(filePath: string): Record<string, string>;
+/**
+ * Load environment variables from a .env file into the current environment
+ */
+declare function loadEnvFile(filePath?: string, options?: {
+    override?: boolean;
+}): Record<string, string>;
+
+/**
+ * Custom error class for environment validation errors
+ */
+declare class EnvValidationException extends Error {
+    readonly errors: EnvValidationError[];
+    constructor(errors: EnvValidationError[]);
+}
+/**
+ * Custom error for parsing errors
+ */
+declare class EnvParseError extends Error {
+    readonly key: string;
+    readonly value?: string;
+    constructor(key: string, message: string, value?: string);
+}
+
+/**
+ * Create a type-safe environment configuration
+ *
+ * @example
+ * ```typescript
+ * import { env } from 'dev-env-toolkit';
+ *
+ * const config = env.create({
+ *   PORT: env.number().default(3000),
+ *   DATABASE_URL: env.string(),
+ *   NODE_ENV: env.enum(['development', 'production', 'test']),
+ *   DEBUG: env.boolean().default(false),
+ * });
+ *
+ * // Fully typed!
+ * console.log(config.PORT); // number
+ * console.log(config.DEBUG); // boolean
+ * ```
+ */
+declare function create<T extends EnvSchema>(schema: T, options?: EnvParseOptions): InferEnv<T>;
+/**
+ * Safely parse environment variables without throwing
+ *
+ * @example
+ * ```typescript
+ * const result = env.safeParse({
+ *   PORT: env.number(),
+ * });
+ *
+ * if (result.success) {
+ *   console.log(result.data.PORT);
+ * } else {
+ *   console.error(result.errors);
+ * }
+ * ```
+ */
+declare function safeParse<T extends EnvSchema>(schema: T, options?: Omit<EnvParseOptions, 'throwOnError'>): EnvParseResult<InferEnv<T>>;
+/**
+ * The main env object with all utilities
+ */
+declare const env: {
+    create: typeof create;
+    safeParse: typeof safeParse;
+    string: () => StringValidator;
+    number: () => NumberValidator;
+    boolean: () => BooleanValidator;
+    enum: <T extends string>(values: readonly T[]) => EnumValidator<T>;
+    array: () => ArrayValidator;
+    load: typeof loadEnvFile;
+    parse: typeof parseEnvFile;
+};
+
+export { type ArrayValidator, type BooleanValidator, type EnumValidator, EnvParseError, type EnvParseOptions, type EnvParseResult, type EnvSchema, type EnvValidationError, EnvValidationException, type InferEnv, type NumberValidator, type StringValidator, type Validator, env as default, env };