docs: Add docs to reflect support for union types and nullables

docs/basic-usage.md

@@ -66,7 +66,7 @@ $value = MyValue::from('Davey Shafik', 40);
 
 ## Type Casting
 
-Bag will cast all values to their defined type _automatically_ for all scalar types, as well as the following:
+If the input value matches the type of the property (including [union types](https://www.php.net/manual/en/language.types.type-system.php#language.types.type-system.composite.union)), it will be used as-is. Otherwise, Bag will cast all values to their defined type _automatically_ for all scalar types, as well as the following:
 
 - `Bag` objects
 - `\Bag\Collection` and `\Illuminate\Support\Collection` objects
@@ -77,6 +77,46 @@ Bag will cast all values to their defined type _automatically_ for all scalar ty
 > [!TIP]
 > We recommend using `\Carbon\CarbonImmutable` for all date times.
 
+## Default Values
+
+You can define default values for your properties by setting them in the constructor:
+
+```php
+use Bag\Bag;
+
+readonly class MyValue extends Bag {
+    public function __construct(
+        public string $name,
+        public int $age = 40,
+    ) {
+    }
+}
+
+$value = MyValue::from([
+    'name' => 'Davey Shafik',
+])->toArray(); // ['name' => 'Davey Shafik', 'age' => 40]
+```
+
+## Nullable Values
+
+Bag will fill missing nullable values without a default value with `null`:
+
+```php
+use Bag\Bag;
+
+readonly class MyValue extends Bag {
+    public function __construct(
+        public string $name,
+        public ?int $age,
+    ) {
+    }
+}
+
+$value = MyValue::from([
+    'name' => 'Davey Shafik',
+])->toArray(); // ['name' => 'Davey Shafik', 'age' => null]
+```
+
 ### Modifying a Value Object
 
 Value Objects are immutable, so you cannot change their properties directly. Instead, you can create a new instance with the updated values using the `Bag->with()` or `Bag->append()` methods:

docs/how-bag-works.md

@@ -25,6 +25,7 @@ start("Bag::from($data)")
 --> transform(Transform Input)
 --> process(Process Parameters) 
 --> variadic(Is Variadic?)
+--> fillNulls(Fill Nulls)
 --> mapInput(Map Input)
 --> laravelParams(Laravel Route Parameter Binding)
 -- Finalized Input Values --> missing(Missing Parameters) --> missingError{Error?}
@@ -51,6 +52,7 @@ click start "https://github.com/dshafik/bag/blob/main/src/Bag/Bag.php" _blank
 click transform "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/Transform.php" _blank
 click process "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/ProcessParameters.php" _blank
 click variadic "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/IsVariadic.php" _blank
+click fillNull "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/FillNulls.php" _blank
 click mapInput "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/MapInput.php" _blank
 click laravelParams "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/LaravelRouteParameters.php" _blank
 click missing "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/MissingParameters.php" _blank
@@ -115,6 +117,7 @@ start("Bag::validate($data)")
 --> transform(Transform Input)
 --> process(Process Parameters) 
 --> variadic(Is Variadic?)
+--> fillNulls(Fill Nulls)
 --> mapInput(Map Input)
 -- Finalized Input Values --> missing(Missing Parameters) --> missingError{Error?}
 missingError -- Yes --> errorMissingParameters(MissingPropertiesException)
@@ -134,6 +137,7 @@ click start "https://github.com/dshafik/bag/blob/main/src/Bag/Concerns/WithValid
 click transform "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/Transform.php" _blank
 click process "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/ProcessParameters.php" _blank
 click variadic "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/IsVariadic.php" _blank
+click fillNulls "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/FillNulls.php" _blank
 click mapInput "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/MapInput.php" _blank
 click missing "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/MissingParameters.php" _blank
 click extra "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/ExtraParameters.php" _blank
@@ -151,6 +155,7 @@ start("Bag::from($data)")
 --> transform(Transform Input)
 --> process(Process Parameters) 
 --> variadic(Is Variadic?)
+--> fillNulls(Fill Nulls)
 --> mapInput(Map Input)
 --> laravelParams(Laravel Route Parameter Binding)
 -- Finalized Input Values --> missing(Missing Parameters) --> missingError{Error?}
@@ -174,6 +179,7 @@ click start "https://github.com/dshafik/bag/blob/main/src/Bag/Bag.php" _blank
 click transform "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/Transform.php" _blank
 click process "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/ProcessParameters.php" _blank
 click variadic "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/IsVariadic.php" _blank
+click fillNulls "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/FillNulls.php" _blank
 click mapInput "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/MapInput.php" _blank
 click laravelParams "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/LaravelRouteParameters.php" _blank
 click missing "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/MissingParameters.php" _blank