docs: Add better Output docs, and include toCollection()

Author: dshafik

docs/.vitepress/config.mts

@@ -67,6 +67,7 @@ export default withMermaid({
           { text: 'Transformers', link: '/transformers' },
           { text: 'Validation', link: '/validation' },
           { text: 'Computed Properties', link: '/computed-properties' },
+          { text: 'Output', link: '/output' },
           { text: 'Wrapping', link: '/wrapping' },
           { text: 'Factories / Testing', link: '/testing' },
         ]

docs/casting.md

@@ -9,7 +9,7 @@ or simply transform it in some way. For example, you can cast a number to a `\Br
 
 Casts can act on both input and output, depending on if they implement `CastsPropertySet` or `CastsPropertyGet`.
 
-Output casts are applied when calling `toArray()`, or when serializing to JSON.
+Output casts are applied when calling `toArray()`, `toCollection()`, or when serializing to JSON.
 
 The following annotations are available:
 
@@ -50,7 +50,7 @@ When you access the `dateOfBirth` property directly, it will be a `\Carbon\Carbo
 dump($value->dateOfBirth); // CarbonImmutable
 ```
 
-However, if you call `toArray()` then it will be formatted using the format you specified:
+However, if you call `toArray()` or `toCollection()` then it will be formatted using the format you specified:
 
 ```php
 dump($value->toArray()); // ['name' => 'Davey Shafik', 'age' => 40, 'dateOfBirth' => '1984-05-31']

docs/hidden.md

@@ -23,7 +23,7 @@ class MyValue extends Bag {
 }
 ```
 
-In the above example, the `hiddenProperty` will not be included when calling `toArray()` or `json_encode()`:
+In the above example, the `hiddenProperty` will not be included when calling `toArray()`, `toCollection()` or `json_encode()`:
 
 ```php
 $value = MyValue::from([

docs/how-bag-works.md

@@ -68,6 +68,7 @@ The `OutputPipeline` is responsible transforming the Bag data to the desired out
 ```mermaid
 graph TD;
 toArray("Bag->toArray()") --> processParameters
+toCollection("Bag->toCollection()") --> processParameters
 toJson("Bag->toJson()") --> processParameters
 jsonEncode("json_encode($bag)") --> processParameters
 get("Bag->get()") --> processParameters
@@ -82,11 +83,12 @@ processParameters(Process Parameters)
 --> wrap(Wrap Output*)
 --> output(array or JSON string)
 
-class toArray,toJson,jsonEncode,get,unwrapped mermaid-start
+class toArray,toCollection,toJson,jsonEncode,get,unwrapped mermaid-start
 class output mermaid-end
 class hide,hideJson,wrap mermaid-conditional
 
 click toArray "https://github.com/dshafik/bag/blob/main/src/Bag/Concerns/WithArrayable.php" _blank
+click toCollection "https://github.com/dshafik/bag/blob/main/src/Bag/Concerns/WithCollections.php" _blank
 click toJson "https://github.com/dshafik/bag/blob/main/src/Bag/Concerns/WithJson.php" _blank
 click get "https://github.com/dshafik/bag/blob/main/src/Bag/Concerns/WithOutput.php" _blank
 click unwrapped "https://github.com/dshafik/bag/blob/main/src/Bag/Concerns/WithOutput.php" _blank
@@ -138,6 +140,50 @@ click extra "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/Ex
 click validate "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/Validate.php" _blank
 ```
 
+## The Without Validate Pipeline
+
+The [`WithoutValidationPipeline`](https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/WithoutValidationPipeline.php) is identical to the `InputPipeline` but does not perform validation. The pipeline
+consists of the following steps:
+
+```mermaid
+graph TD;
+start("Bag::from($data)")
+--> transform(Transform Input)
+--> process(Process Parameters) 
+--> variadic(Is Variadic?)
+--> mapInput(Map Input)
+--> laravelParams(Laravel Route Parameter Binding)
+-- Finalized Input Values --> missing(Missing Parameters) --> missingError{Error?}
+missingError -- Yes --> errorMissingParameters(MissingPropertiesException)
+missingError -- No --> extra(Extra Parameters) --> extraError{Error?}
+extraError -- Yes --> errorExtraParameters(ExtraPropertiesException)
+extraError -- No
+--> construct("new Bag(...)")
+--> computed(Verify Computed Values)
+--> initialized{Initialized?}
+initialized -- No --> errorInitialization(ComputedPropertyUninitializedException)
+initialized -- Yes
+--> bag(Bag Value Returned)
+
+class start mermaid-start
+class missingError,extraError,valid,initialized mermaid-decision
+class bag mermaid-end
+class errorMissingParameters,errorExtraParameters,errorValidation,errorInitialization mermaid-error
+
+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 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
+click extra "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/ExtraParameters.php" _blank
+click validate "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/Validate.php" _blank
+click cast "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/CastInputValues.php" _blank
+click construct "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/FillBag.php" _blank
+click computed "https://github.com/dshafik/bag/blob/main/src/Bag/Pipelines/Pipes/ComputedValues.php" _blank
+```
+
 ## The Output Collection Pipeline
 
 The `OutputCollectionPipeline` is responsible for transforming the Bag collection data to the desired output array or JSON. The pipeline consists of the following steps:

docs/mapping.md

@@ -130,7 +130,7 @@ Input mapping is applied when calling `Bag::from()` or `Bag::withoutValidation()
 > [!TIP]
 > [Validation](validation) is applied to the original property name, not the mapped name.
 
-Output mapping is applied when calling `$Bag->toArray()` or `$Bag->toJson()` (or when using `json_encode()`).
+Output mapping is applied when calling `$Bag->toArray()`, `$Bag->toCollection()`, or `$Bag->toJson()` (or when using `json_encode()`).
 
 ## Mapping Hierarchy
 

docs/output.md

@@ -0,0 +1,30 @@
+# Output
+
+Once you have created a Bag value object, you can access the properties using object notation:
+
+```php
+use App\Values\MyValue;
+
+$value = new MyValue(name: 'Davey Shafik', age: 40);
+$value->name; // 'Davey Shafik'
+```
+
+## Casting to Other Types
+
+Bag supports casting to arrays and [`\Bag\Collections`](/collections##extending-laravel-collections) using the
+`Bag->toArray()` and `Bag->toCollection()` methods.
+
+Both methods will apply casting and mapping, as well as respect [hidden properties](/hidden).
+
+## JSON Serialization
+
+In addition, you can serialize a Bag object to JSON using `json_encode()` or `Bag->toJson():
+
+```php
+$value = MyValue::from(name: 'Davey Shafik', age: 40);
+
+$value->toJson(); // {"name": "Davey Shafik", "age": 40}
+json_encode($value, JSON_THROW_ON_ERROR); // {"name": "Davey Shafik", "age": 40}
+```
+
+Both `Bag->toJson()` and `json_encode()` will respect [hidden properties](/hidden).