feat: release version 1.3.0 with environment key exception removal and enhanced documentation

Author: LeadcodeDev

CHANGELOG.md

@@ -1,5 +1,7 @@
+## 1.3.0
+- Remove existing environment key exception for `DART_ENV`
+
 ## 1.2.0
-- Remove existing environment key exception
 - Add `toJson()` method to convert environment variables to a Map
 
 ## 1.1.0

lib/src/env.dart

@@ -67,6 +67,32 @@ final class Env {
     return _envParser.parse(content);
   }
 
+  /// Parses environment variables from a string content into a Map.
+  ///
+  /// Takes a [content] string containing environment variable definitions in the format:
+  /// ```dotenv
+  /// KEY1=value1
+  /// KEY2=value2
+  /// ```
+  ///
+  /// Returns a [Map<String, dynamic>] where each key is the environment variable name
+  /// and the value is the parsed string value.
+  ///
+  /// Example:
+  /// ```dart
+  /// final content = '''
+  ///   PORT=8080
+  ///   HOST=localhost
+  /// ''';
+  ///
+  /// final schema = {
+  ///   'PORT': env.number().integer(),
+  ///   'HOST': env.string(),
+  /// };
+  ///
+  /// final validatedEnv = env.validate(schema, envVars);
+  /// // Returns: {'PORT': 8080, 'HOST': 'localhost'}
+  /// ```
   Map<String, dynamic> validate(
     Map<String, EnvSchema> schema,
     Map<String, dynamic> data,
@@ -94,6 +120,33 @@ final class Env {
     return resultMap;
   }
 
+  /// Validates environment variables against a schema.
+  ///
+  /// Takes a [schema] defining the expected structure and validation rules for environment variables,
+  /// and [data] containing the actual environment variable values to validate.
+  ///
+  /// Returns a [Map] containing the validated environment variables. The returned map will have
+  /// the same keys as the schema, with values converted and validated according to the schema rules.
+  ///
+  /// Throws an [EnvGuardException] if any validation errors occur. The exception will contain details
+  /// about which validations failed.
+  ///
+  /// Example:
+  /// ```dart
+  /// final schema = {
+  ///   'PORT': env.number().integer(),
+  ///   'HOST': env.string(),
+  /// };
+  ///
+  /// final data = {
+  ///   'PORT': '8080',
+  ///   'HOST': 'localhost'
+  /// };
+  ///
+  /// final validated = env.validate(schema, data);
+  /// // Returns: {'PORT': 8080, 'HOST': 'localhost'}
+  /// ```
+
   void define(
     Map<String, EnvSchema> schema, {
     Directory? root,
@@ -123,7 +176,8 @@ final class Env {
     if (current != null) {
       final values = _envParser.parse(current.content);
       for (final element in values.entries) {
-        if (_environments.containsKey(element.key)) {
+        if (element.key != 'DART_ENV' &&
+            _environments.containsKey(element.key)) {
           throw Exception('Environment variable ${element.key} already exists');
         }
       }
@@ -138,6 +192,31 @@ final class Env {
     }
   }
 
+  /// Defines environment variables using a class that implements [DefineEnvironment].
+  ///
+  /// This method provides a more structured way to define environment variables using a class-based approach.
+  /// The class must implement [DefineEnvironment] interface which requires a [schema] property.
+  ///
+  /// Parameters:
+  /// - [source]: A function that returns an instance of type [T] which implements [DefineEnvironment]
+  /// - [root]: Optional directory where the .env files are located. Defaults to current directory if not specified
+  /// - [includeDartEnv]: Whether to include Dart's environment variables. Defaults to true
+  ///
+  /// Example:
+  /// ```dart
+  /// class AppEnv implements DefineEnvironment {
+  ///   static final String host = 'HOST';
+  ///   static final String port = 'PORT';
+  ///
+  ///   @override
+  ///   final Map<String, EnvSchema> schema = {
+  ///     host: env.string(),
+  ///     port: env.number().integer(),
+  ///   };
+  /// }
+  ///
+  /// env.defineOf(AppEnv.new);
+  /// ```
   void defineOf<T extends DefineEnvironment>(
     T Function() source, {
     Directory? root,

pubspec.yaml

@@ -1,6 +1,6 @@
 name: env_guard
 description: A simple, robust, and typed environment validation library for Dart/Flutter, designed to simplify and secure environment in applications
-version: 1.2.0
+version: 1.3.0
 repository: https://github.com/LeadcodeDev/env_guard
 
 environment: