From b7361a191a3cc58c4f001c1edd83438ab70764fd Mon Sep 17 00:00:00 2001 From: Yanshuman Yadav Date: Mon, 29 Jun 2026 01:56:16 +0530 Subject: [PATCH 1/3] feat: warn about missing variables in .env.example fix: get_env error return for unset variables. --- .env.example | 12 ++++ src/dot_env.gleam | 95 +++++++++++++++++++++++------ src/dot_env/internal/template.gleam | 36 +++++++++++ src/dot_env_ffi.mjs | 2 +- test/dot_env_test.gleam | 54 +++++++++++++++- 5 files changed, 179 insertions(+), 20 deletions(-) create mode 100644 .env.example create mode 100644 src/dot_env/internal/template.gleam diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..30fb9dd --- /dev/null +++ b/.env.example @@ -0,0 +1,12 @@ +PORT= + +APP_NAME= +APP_ENV= +APP_KEY= +APP_DEBUG= +APP_URL= +APP_TIMEZONE= + +DATABASE_URL= +SECRET_KEY= +API_TOKEN= diff --git a/src/dot_env.gleam b/src/dot_env.gleam index 08e5342..40250eb 100644 --- a/src/dot_env.gleam +++ b/src/dot_env.gleam @@ -1,5 +1,6 @@ import dot_env/env import dot_env/internal/parser +import dot_env/internal/template import gleam/bool import gleam/io import gleam/result.{try} @@ -11,6 +12,8 @@ pub type Opts { Opts( /// The path to the .env file relative to the project root eg. .env and src/.env are two different things, .env points to the root of the project, src/.env points to the src folder in the root of the project path: String, + /// Warn if variables defined in {path}.example are missing from the environment. + check_example: Bool, /// Print debug information if something goes wrong debug: Bool, /// Force all keys to be uppercase @@ -24,11 +27,18 @@ pub type Opts { } pub opaque type DotEnv { - DotEnv(path: String, debug: Bool, capitalize: Bool, ignore_missing_file: Bool) + DotEnv( + path: String, + check_example: Bool, + debug: Bool, + capitalize: Bool, + ignore_missing_file: Bool, + ) } pub const default = DotEnv( path: ".env", + check_example: True, debug: True, capitalize: True, ignore_missing_file: True, @@ -44,6 +54,11 @@ pub fn new_with_path(path: String) -> DotEnv { DotEnv(..default, path: path) } +/// Todo +pub fn set_check_example(instance: DotEnv, check_example: Bool) -> DotEnv { + DotEnv(..instance, check_example: check_example) +} + /// Set whether to print debug information in the current DotEnv instance pub fn set_debug(instance: DotEnv, debug: Bool) -> DotEnv { DotEnv(..instance, debug: debug) @@ -88,6 +103,7 @@ pub fn path(instance: DotEnv) -> String { pub fn load(dotenv: DotEnv) -> Nil { load_with_opts(Opts( path: dotenv.path, + check_example: dotenv.check_example, debug: dotenv.debug, capitalize: dotenv.capitalize, ignore_missing_file: dotenv.ignore_missing_file, @@ -126,15 +142,13 @@ pub fn load_default() -> Nil { /// ``` pub fn load_with_opts(opts: Opts) { let dotenv = case opts { - Opts(path, debug, capitalize, ignore_missing_file) -> - DotEnv(path, debug, capitalize, ignore_missing_file) + Opts(path, check_example, debug, capitalize, ignore_missing_file) -> + DotEnv(path, check_example, debug, capitalize, ignore_missing_file) Default -> default } - let state = dotenv |> load_and_return_error - - case state { - Ok(_) -> Nil + case load_and_return_error(dotenv) { + Ok(conf) -> check_template(dotenv, conf) Error(msg) -> { use <- bool.guard(when: !dotenv.debug, return: Nil) io.println_error(msg) @@ -142,16 +156,47 @@ pub fn load_with_opts(opts: Opts) { } } -fn load_and_return_error(dotenv: DotEnv) -> Result(Nil, String) { +fn load_and_return_error( + dotenv: DotEnv, +) -> Result(List(#(String, String)), String) { use content <- try( - read_file(dotenv) + read_file(dotenv.path) |> handle_file_result(dotenv.ignore_missing_file), ) - use kv_pairs <- try(parser.parse(content)) + use conf <- try(parser.parse(content)) + + use _ <- try(dotenv |> recursively_set_environment_variables(conf)) + + Ok(conf) +} + +fn check_template(dotenv: DotEnv, conf: List(#(String, String))) -> Nil { + use <- bool.guard(when: !dotenv.check_example, return: Nil) - dotenv - |> recursively_set_environment_variables(kv_pairs) + // maybe add example_path as an option? + let template_path = dotenv.path <> ".example" + + let res = { + use content <- try(read_file(template_path)) + use conf_example <- try(parser.parse(content)) + + template.missing_keys(conf, conf_example, dotenv.capitalize) + |> warn_missing_keys + + Ok(Nil) + } + + case res { + Ok(_) -> Nil + Error(error) -> { + let msg = case dotenv.debug { + True -> error <> "\nSkipping template check" + False -> "Skipping template check" + } + io.println_error(msg) + } + } } fn handle_file_result( @@ -186,9 +231,9 @@ fn recursively_set_environment_variables( } } -fn read_file(dotenv: DotEnv) -> Result(String, String) { +fn read_file(path: String) -> Result(String, String) { use is_file <- result.try( - simplifile.is_file(dotenv.path) + simplifile.is_file(path) |> result.map_error(with: fn(_) { "Failed to access file, ensure the file exists and is a readable file" }), @@ -196,17 +241,33 @@ fn read_file(dotenv: DotEnv) -> Result(String, String) { use <- bool.guard( when: !is_file, - return: Error("Specified file at `" <> dotenv.path <> "` does not exist"), + return: Error("Specified file at `" <> path <> "` does not exist"), ) use contents <- result.try( - simplifile.read(dotenv.path) + simplifile.read(path) |> result.map_error(with: fn(_) { "Unable to read file at `" - <> dotenv.path + <> path <> "`, ensure the file exists and is readable" }), ) Ok(contents) } + +fn warn_missing_keys(keys: List(String)) { + case keys { + [] -> Nil + _ -> { + let joined_vars = string.join(keys, with: ", ") + let warning_msg = + "The following variables were defined in the example file but are not present in the environment:\n" + <> " " + <> joined_vars + <> "\n" + <> "Make sure to add them to your env file." + io.println_error(warning_msg) + } + } +} diff --git a/src/dot_env/internal/template.gleam b/src/dot_env/internal/template.gleam new file mode 100644 index 0000000..d952a85 --- /dev/null +++ b/src/dot_env/internal/template.gleam @@ -0,0 +1,36 @@ +import dot_env/env +import gleam/dict +import gleam/list +import gleam/string + +pub fn missing_keys( + conf: List(#(String, String)), + conf_example: List(#(String, String)), + capitalize: Bool, +) -> List(String) { + let conf_dict = dict.from_list(conf) + + list.fold(conf_example, [], fn(acc, kv) { + let #(key, _) = kv + + let look_up_key = case capitalize { + True -> string.uppercase(key) + False -> key + } + + let is_set = has_env(look_up_key) || dict.has_key(conf_dict, key) + case is_set { + True -> acc + False -> [key, ..acc] + } + }) + |> list.reverse +} + +// Todo check in os env +fn has_env(key: String) -> Bool { + case env.get_string(key) { + Ok(_) -> True + Error(_) -> False + } +} diff --git a/src/dot_env_ffi.mjs b/src/dot_env_ffi.mjs index ce0a773..5bfc1b2 100644 --- a/src/dot_env_ffi.mjs +++ b/src/dot_env_ffi.mjs @@ -62,7 +62,7 @@ export function get_env(key) { } if (value == Nil || value === undefined) { - return new GleamError(Nil); + return new GleamError(`key ${key} is not set`); } return new GleamOk(value); diff --git a/test/dot_env_test.gleam b/test/dot_env_test.gleam index d13a621..6c75ed2 100644 --- a/test/dot_env_test.gleam +++ b/test/dot_env_test.gleam @@ -1,5 +1,6 @@ import dot_env.{Opts} import dot_env/env +import dot_env/internal/template import gleeunit import gleeunit/should @@ -8,7 +9,13 @@ pub fn main() { } pub fn get_test() { - dot_env.load_default() + dot_env.load_with_opts(Opts( + path: ".env", + check_example: False, + debug: True, + capitalize: True, + ignore_missing_file: False, + )) env.get_string("DEFINITELY_NOT_A_REAL_KEY") |> should.be_error @@ -44,6 +51,7 @@ pub fn load_missing_env_file_test() { // This should not fail or crash dot_env.load_with_opts(Opts( path: ".definitely_not_a_real_file", + check_example: False, debug: True, capitalize: True, ignore_missing_file: True, @@ -54,7 +62,13 @@ pub fn load_missing_env_file_test() { } pub fn load_default_test() { - dot_env.load_default() + dot_env.load_with_opts(Opts( + path: ".env", + check_example: False, + debug: True, + capitalize: True, + ignore_missing_file: False, + )) env.get_string("PORT") |> should.equal(Ok("9000")) @@ -81,6 +95,7 @@ pub fn load_default_test() { pub fn load_normal_test() { dot_env.load_with_opts(Opts( path: ".env.normal", + check_example: False, debug: True, capitalize: True, ignore_missing_file: False, @@ -191,6 +206,7 @@ pub fn load_normal_test() { pub fn load_multiline_test() { dot_env.load_with_opts(Opts( path: ".env.multiline", + check_example: False, debug: True, capitalize: True, ignore_missing_file: False, @@ -257,6 +273,7 @@ pub fn load_multiline_test() { pub fn get_bool_test() { dot_env.load_with_opts(Opts( path: ".env.booleans", + check_example: False, debug: True, capitalize: True, ignore_missing_file: False, @@ -274,3 +291,36 @@ pub fn get_bool_test() { env.get_bool("BOOL_TRUE") |> should.equal(Ok(True)) } + +pub fn no_missing_keys_test() { + let conf = [ + #("PORT", "9000"), + #("HOST", "localhost"), + ] + + let example = [ + #("PORT", ""), + #("HOST", ""), + ] + + template.missing_keys(conf, example, True) + |> should.equal([]) +} + +pub fn missing_keys_test() { + let conf = [ + #("PORT", "9000"), + ] + + let example = [ + #("PORT", ""), + #("HOST", ""), + #("DATABASE_URL", ""), + ] + + template.missing_keys(conf, example, True) + |> should.equal([ + "HOST", + "DATABASE_URL", + ]) +} From 8273ff090cb17018e61821fac7d5c149b87d3b05 Mon Sep 17 00:00:00 2001 From: Yanshuman Yadav Date: Mon, 20 Jul 2026 17:23:25 +0530 Subject: [PATCH 2/3] remove check_exampls and add validate_template and add template_path option --- src/dot_env.gleam | 79 ++++++++++++++++++++++------- src/dot_env/internal/template.gleam | 11 ++-- test/dot_env_test.gleam | 27 ++++++---- 3 files changed, 82 insertions(+), 35 deletions(-) diff --git a/src/dot_env.gleam b/src/dot_env.gleam index 40250eb..1df9d31 100644 --- a/src/dot_env.gleam +++ b/src/dot_env.gleam @@ -3,6 +3,7 @@ import dot_env/internal/parser import dot_env/internal/template import gleam/bool import gleam/io +import gleam/option.{type Option, None, Some} import gleam/result.{try} import gleam/string import simplifile @@ -13,7 +14,9 @@ pub type Opts { /// The path to the .env file relative to the project root eg. .env and src/.env are two different things, .env points to the root of the project, src/.env points to the src folder in the root of the project path: String, /// Warn if variables defined in {path}.example are missing from the environment. - check_example: Bool, + validate_template: Bool, + /// Specify a template_path (by default `{path}.example` if not set explicitly) + template_path: Option(String), /// Print debug information if something goes wrong debug: Bool, /// Force all keys to be uppercase @@ -29,7 +32,8 @@ pub type Opts { pub opaque type DotEnv { DotEnv( path: String, - check_example: Bool, + validate_template: Bool, + template_path: Option(String), debug: Bool, capitalize: Bool, ignore_missing_file: Bool, @@ -38,7 +42,8 @@ pub opaque type DotEnv { pub const default = DotEnv( path: ".env", - check_example: True, + validate_template: True, + template_path: None, debug: True, capitalize: True, ignore_missing_file: True, @@ -54,9 +59,21 @@ pub fn new_with_path(path: String) -> DotEnv { DotEnv(..default, path: path) } -/// Todo -pub fn set_check_example(instance: DotEnv, check_example: Bool) -> DotEnv { - DotEnv(..instance, check_example: check_example) +/// Set whether to warn if variables defined in the template file (by default `{path}.example`) are missing from the environment. +/// +/// If set to `True`, a warning will be printed for any missing variables. +pub fn set_validate_template( + instance: DotEnv, + validate_template: Bool, +) -> DotEnv { + DotEnv(..instance, validate_template: validate_template) +} + +/// Set a specific file path to use as the template for environment variable validation. +/// +/// If not set, it defaults to the path of the `.env` file with `.example` appended (e.g., `.env.example`). +pub fn set_template_path(instance: DotEnv, template_path: String) -> DotEnv { + DotEnv(..instance, template_path: Some(template_path)) } /// Set whether to print debug information in the current DotEnv instance @@ -103,7 +120,8 @@ pub fn path(instance: DotEnv) -> String { pub fn load(dotenv: DotEnv) -> Nil { load_with_opts(Opts( path: dotenv.path, - check_example: dotenv.check_example, + validate_template: dotenv.validate_template, + template_path: dotenv.template_path, debug: dotenv.debug, capitalize: dotenv.capitalize, ignore_missing_file: dotenv.ignore_missing_file, @@ -135,15 +153,37 @@ pub fn load_default() -> Nil { /// /// ```gleam /// import dot_env +/// import gleam/option.{None} /// /// pub fn main() { -/// dot_env.load_with_opts(dot_env.Opts(path: "src/.env", debug: False, capitalize: False)) +/// dot_env.load_with_opts(dot_env.Opts( +/// path: "src/.env", +/// validate_template: True, +/// template_path: None, +/// debug: False, +/// capitalize: False, +/// ignore_missing_file: False, +/// )) /// } /// ``` pub fn load_with_opts(opts: Opts) { let dotenv = case opts { - Opts(path, check_example, debug, capitalize, ignore_missing_file) -> - DotEnv(path, check_example, debug, capitalize, ignore_missing_file) + Opts( + path, + validate_template, + template_path, + debug, + capitalize, + ignore_missing_file, + ) -> + DotEnv( + path, + validate_template, + template_path, + debug, + capitalize, + ignore_missing_file, + ) Default -> default } @@ -172,13 +212,17 @@ fn load_and_return_error( } fn check_template(dotenv: DotEnv, conf: List(#(String, String))) -> Nil { - use <- bool.guard(when: !dotenv.check_example, return: Nil) + use <- bool.guard(when: !dotenv.validate_template, return: Nil) - // maybe add example_path as an option? - let template_path = dotenv.path <> ".example" + let template_path = case dotenv.template_path { + Some(path) -> path + None -> dotenv.path <> ".example" + } let res = { - use content <- try(read_file(template_path)) + use content <- try( + read_file(template_path) |> handle_file_result(dotenv.ignore_missing_file), + ) use conf_example <- try(parser.parse(content)) template.missing_keys(conf, conf_example, dotenv.capitalize) @@ -190,11 +234,8 @@ fn check_template(dotenv: DotEnv, conf: List(#(String, String))) -> Nil { case res { Ok(_) -> Nil Error(error) -> { - let msg = case dotenv.debug { - True -> error <> "\nSkipping template check" - False -> "Skipping template check" - } - io.println_error(msg) + use <- bool.guard(when: !dotenv.debug, return: Nil) + io.println_error(error <> "\nSkipping template check") } } } diff --git a/src/dot_env/internal/template.gleam b/src/dot_env/internal/template.gleam index d952a85..972580b 100644 --- a/src/dot_env/internal/template.gleam +++ b/src/dot_env/internal/template.gleam @@ -4,13 +4,13 @@ import gleam/list import gleam/string pub fn missing_keys( - conf: List(#(String, String)), - conf_example: List(#(String, String)), + config: List(#(String, String)), + config_example: List(#(String, String)), capitalize: Bool, ) -> List(String) { - let conf_dict = dict.from_list(conf) + let config_dict = dict.from_list(config) - list.fold(conf_example, [], fn(acc, kv) { + list.fold(config_example, [], fn(acc, kv) { let #(key, _) = kv let look_up_key = case capitalize { @@ -18,7 +18,7 @@ pub fn missing_keys( False -> key } - let is_set = has_env(look_up_key) || dict.has_key(conf_dict, key) + let is_set = has_env(look_up_key) || dict.has_key(config_dict, key) case is_set { True -> acc False -> [key, ..acc] @@ -27,7 +27,6 @@ pub fn missing_keys( |> list.reverse } -// Todo check in os env fn has_env(key: String) -> Bool { case env.get_string(key) { Ok(_) -> True diff --git a/test/dot_env_test.gleam b/test/dot_env_test.gleam index 6c75ed2..f5679db 100644 --- a/test/dot_env_test.gleam +++ b/test/dot_env_test.gleam @@ -1,6 +1,7 @@ import dot_env.{Opts} import dot_env/env import dot_env/internal/template +import gleam/option.{None} import gleeunit import gleeunit/should @@ -11,7 +12,8 @@ pub fn main() { pub fn get_test() { dot_env.load_with_opts(Opts( path: ".env", - check_example: False, + validate_template: False, + template_path: None, debug: True, capitalize: True, ignore_missing_file: False, @@ -51,7 +53,8 @@ pub fn load_missing_env_file_test() { // This should not fail or crash dot_env.load_with_opts(Opts( path: ".definitely_not_a_real_file", - check_example: False, + validate_template: False, + template_path: None, debug: True, capitalize: True, ignore_missing_file: True, @@ -64,7 +67,8 @@ pub fn load_missing_env_file_test() { pub fn load_default_test() { dot_env.load_with_opts(Opts( path: ".env", - check_example: False, + validate_template: False, + template_path: None, debug: True, capitalize: True, ignore_missing_file: False, @@ -95,7 +99,8 @@ pub fn load_default_test() { pub fn load_normal_test() { dot_env.load_with_opts(Opts( path: ".env.normal", - check_example: False, + validate_template: False, + template_path: None, debug: True, capitalize: True, ignore_missing_file: False, @@ -206,7 +211,8 @@ pub fn load_normal_test() { pub fn load_multiline_test() { dot_env.load_with_opts(Opts( path: ".env.multiline", - check_example: False, + validate_template: False, + template_path: None, debug: True, capitalize: True, ignore_missing_file: False, @@ -273,7 +279,8 @@ pub fn load_multiline_test() { pub fn get_bool_test() { dot_env.load_with_opts(Opts( path: ".env.booleans", - check_example: False, + validate_template: False, + template_path: None, debug: True, capitalize: True, ignore_missing_file: False, @@ -293,7 +300,7 @@ pub fn get_bool_test() { } pub fn no_missing_keys_test() { - let conf = [ + let config = [ #("PORT", "9000"), #("HOST", "localhost"), ] @@ -303,12 +310,12 @@ pub fn no_missing_keys_test() { #("HOST", ""), ] - template.missing_keys(conf, example, True) + template.missing_keys(config, example, True) |> should.equal([]) } pub fn missing_keys_test() { - let conf = [ + let config = [ #("PORT", "9000"), ] @@ -318,7 +325,7 @@ pub fn missing_keys_test() { #("DATABASE_URL", ""), ] - template.missing_keys(conf, example, True) + template.missing_keys(config, example, True) |> should.equal([ "HOST", "DATABASE_URL", From 42ed098fe499799813319f79f3eb97cdb84ea1b1 Mon Sep 17 00:00:00 2001 From: Yanshuman Yadav Date: Tue, 21 Jul 2026 13:44:38 +0530 Subject: [PATCH 3/3] rename conf to config, check_template to validate_template, clear docs, and revert to original tests --- src/dot_env.gleam | 28 +++++++++++++--------------- test/dot_env_test.gleam | 18 ++---------------- 2 files changed, 15 insertions(+), 31 deletions(-) diff --git a/src/dot_env.gleam b/src/dot_env.gleam index 1df9d31..a486a15 100644 --- a/src/dot_env.gleam +++ b/src/dot_env.gleam @@ -13,7 +13,7 @@ pub type Opts { Opts( /// The path to the .env file relative to the project root eg. .env and src/.env are two different things, .env points to the root of the project, src/.env points to the src folder in the root of the project path: String, - /// Warn if variables defined in {path}.example are missing from the environment. + /// Warn if variables defined in the template file (by default `{path}.example`) are missing from both the `.env` file and the environment. validate_template: Bool, /// Specify a template_path (by default `{path}.example` if not set explicitly) template_path: Option(String), @@ -59,7 +59,7 @@ pub fn new_with_path(path: String) -> DotEnv { DotEnv(..default, path: path) } -/// Set whether to warn if variables defined in the template file (by default `{path}.example`) are missing from the environment. +/// Set whether to warn if variables defined in the template file (by default `{path}.example`) are missing from both the `.env` file and the environment. /// /// If set to `True`, a warning will be printed for any missing variables. pub fn set_validate_template( @@ -188,7 +188,7 @@ pub fn load_with_opts(opts: Opts) { } case load_and_return_error(dotenv) { - Ok(conf) -> check_template(dotenv, conf) + Ok(config) -> validate_template(dotenv, config) Error(msg) -> { use <- bool.guard(when: !dotenv.debug, return: Nil) io.println_error(msg) @@ -204,14 +204,14 @@ fn load_and_return_error( |> handle_file_result(dotenv.ignore_missing_file), ) - use conf <- try(parser.parse(content)) + use config <- try(parser.parse(content)) - use _ <- try(dotenv |> recursively_set_environment_variables(conf)) + use _ <- try(dotenv |> recursively_set_environment_variables(config)) - Ok(conf) + Ok(config) } -fn check_template(dotenv: DotEnv, conf: List(#(String, String))) -> Nil { +fn validate_template(dotenv: DotEnv, config: List(#(String, String))) -> Nil { use <- bool.guard(when: !dotenv.validate_template, return: Nil) let template_path = case dotenv.template_path { @@ -221,18 +221,16 @@ fn check_template(dotenv: DotEnv, conf: List(#(String, String))) -> Nil { let res = { use content <- try( - read_file(template_path) |> handle_file_result(dotenv.ignore_missing_file), + read_file(template_path) + |> handle_file_result(dotenv.ignore_missing_file), ) - use conf_example <- try(parser.parse(content)) + use config_example <- try(parser.parse(content)) - template.missing_keys(conf, conf_example, dotenv.capitalize) - |> warn_missing_keys - - Ok(Nil) + template.missing_keys(config, config_example, dotenv.capitalize) |> Ok } case res { - Ok(_) -> Nil + Ok(missing) -> warn_missing_keys(missing) Error(error) -> { use <- bool.guard(when: !dotenv.debug, return: Nil) io.println_error(error <> "\nSkipping template check") @@ -303,7 +301,7 @@ fn warn_missing_keys(keys: List(String)) { _ -> { let joined_vars = string.join(keys, with: ", ") let warning_msg = - "The following variables were defined in the example file but are not present in the environment:\n" + "The following variables were defined in the example file but are missing from both the `.env` file and the environment:\n" <> " " <> joined_vars <> "\n" diff --git a/test/dot_env_test.gleam b/test/dot_env_test.gleam index f5679db..9131c2b 100644 --- a/test/dot_env_test.gleam +++ b/test/dot_env_test.gleam @@ -10,14 +10,7 @@ pub fn main() { } pub fn get_test() { - dot_env.load_with_opts(Opts( - path: ".env", - validate_template: False, - template_path: None, - debug: True, - capitalize: True, - ignore_missing_file: False, - )) + dot_env.load_default() env.get_string("DEFINITELY_NOT_A_REAL_KEY") |> should.be_error @@ -65,14 +58,7 @@ pub fn load_missing_env_file_test() { } pub fn load_default_test() { - dot_env.load_with_opts(Opts( - path: ".env", - validate_template: False, - template_path: None, - debug: True, - capitalize: True, - ignore_missing_file: False, - )) + dot_env.load_default() env.get_string("PORT") |> should.equal(Ok("9000"))