Merge pull request #25 from mrjvs/next

v.3.0.0

.docs/content/2.api/2.formatting.md

@@ -47,29 +47,9 @@ Configured naming conventions get overwritten if you use a schema.
 ::
 
 
-## `.freeze()`
+## `.unfreeze()`
 
-With this formatting option, Your configuration is deep frozen using recursive `Object.freeze()`.
+by default, Your configuration is deep frozen using recursive `Object.freeze()`.
 This means that you will get runtime errors when you try to assign anything, in typescript you will get a readonly type so you get compiler errors when trying to assign.
 
-::alert{type="warning"}
-In typescript, when using a schema AFTER calling `.freeze()` will overwrite the type. To make use of the readonly type, call `.freeze()` after setting up any schemas.
-::
-
-::code-group
-  ```ts [config.ts]
-  import { createConfigLoader } from 'neat-config';
-  import { z } from 'zod';
-
-  process.env = {
-    HELLO_WORLD: "hello world"
-  }
-
-  const config = createConfigLoader()
-    .addFromEnvironment()
-    .freeze()
-    .load();
-
-  config.helloWorld = "some other value"; // TypeError: Cannot assign to read only property 'helloWorld' of object '#<Object>'
-  ```
-::
+If you use the `unfreeze()` option, your output configuration will not be frozen as described above.

.docs/content/2.api/4.errors.md

@@ -0,0 +1,9 @@
+# Error handling
+
+Configuration loading has some potentionally confusing error handling.
+By default, it will use the "pretty" assertion mode. This mode **will call process.exit(1)** instead of throwing errors. That means that you aren't able to catch it with a try-catch block.
+
+## The modes
+ - `pretty` Log the errors in pretty formatting and colors, then exit the process.
+ - `plain` Log the errors in plain text, then exit the process.
+ - `throw` throw the errors where they occur.

.docs/content/2.api/5.utils.md

@@ -0,0 +1,33 @@
+# Utilities
+
+Some helpers that can help you make configuration easier.
+
+## `zodCoercedBoolean()`
+
+Since `zod` boolean coercion is just doing `Boolean(value)`. You get weird cases like these:
+ - `z.coerce.boolean().parse("true"); // => true`; 
+ - `z.coerce.boolean().parse("false"); // => true`;
+ - `z.coerce.boolean().parse("yes"); // => true`; 
+ - `z.coerce.boolean().parse("no"); // => true`; 
+ - `z.coerce.boolean().parse(""); // => false`;
+
+If you use `zodCoercedBoolean()` instead of `z.boolean()`. You get these results:
+ - `zodCoercedBoolean().parse("true"); // => true`; 
+ - `zodCoercedBoolean().parse("false"); // => false`;
+ - `zodCoercedBoolean().parse("yes"); // => true`; 
+ - `zodCoercedBoolean().parse("no"); // => false`; 
+ - `zodCoercedBoolean().parse("Yes"); // => true`; 
+ - `zodCoercedBoolean().parse("No"); // => false`; 
+ - `zodCoercedBoolean().parse("True"); // => true`; 
+ - `zodCoercedBoolean().parse("False"); // => false`;
+ - `zodCoercedBoolean().parse(""); // => false`;
+
+If you use `zodCoercedBoolean()` instead of `z.boolean()`, things will be more as you expect them to be.
+Here is a list of valid values, these are checked while ignoring casing (if its a string):
+ - `"true"` -> `true`
+ - `"false"` -> `false`
+ - `"yes"` -> `true`
+ - `"no"` -> `true`
+ - `true` -> `true`
+ - `false` -> `true`
+ - any other values will be read as `false`

.docs/content/3.misc/1.changelog.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## V3.0.0 - Error handling
+::list{type="danger"}
+- **BREAKING CHANGE:** Errors now have proper types, does not throw but uses process.exit.
+- **BREAKING CHANGE:** Env files now handle quotes as you would expect. Using `dotenv` for parsing.
+- **BREAKING CHANGE:** Frozen configs are now default, To opt out, you can do `.unfreeze()`. [Read more about freezing here](/api/formatting).
+::
+::list{type="success"}
+- Errors are now logged with pretty colors and will exit the process by default. [Read more about errors here](/api/errors).
+- A new zod helper for easier boolean schemas: `zodCoercedBoolean`. [Read more about it here](/api/utils).
+::
+
 ## V2.0.0 - File loader prefixes & freezing
 ::list{type="danger"}
 - **BREAKING CHANGE:** file loaders now take a options argument