feat: add fromResult()/fromValidatedResult() — never-throw error accumulation

Safe-parse alternative to from()/tryFrom(): tries every parameter and collects every failure into a HydrationResult instead of aborting on the first one, with dot-path keys for nested BaseData/#[DataCollection] errors. Compiled and cached separately from the hydration hot path, so from()/tryFrom() pay nothing for it.

Author: yuriizee

CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to `std-out/simple-data-objects` are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.23.0] — 2026-08-08
+
+### Added
+- **`fromResult()` / `fromValidatedResult()`** — a "safe parse" alternative
+  to `from()`/`tryFrom()` that never throws. Every parameter is tried, and
+  every failure is collected into a `HydrationResult` instead of aborting
+  on the first one.
+  - **`HydrationResult`** — `ok()`, `value()` (throws `LogicException` if
+    called on a failed result), `valueOrNull()`, `errors()`.
+  - **Dot-path errors for nested structure**: a nested `BaseData` or
+    `#[DataCollection]` field recurses into the target class's own
+    `fromResult()`, merging its errors under `field.name` /
+    `field.index.name`. `#[Flatten]` merges flat, with no prefix, since its
+    fields already live in the parent's own namespace.
+  - `#[RejectUnknownKeys]` reports a `'$unknown'` entry instead of
+    aborting; a failing class-level `#[Pipe]` reports `'$pipeline'` (and
+    skips per-field extraction, since the transform left the input
+    unreliable); a throwing constructor reports `'$construct'`; invalid
+    non-array input reports `'$input'`.
+  - **`fromValidatedResult()`** merges `#[Rules]`/`#[InferRules]` failures
+    into the same error map (the first message per field; a validation
+    message wins over a hydration message on the same key).
+  - Compiled the same way `from()` is — a specialized closure per class,
+    cached separately and lazily — so `from()`/`tryFrom()` pay nothing for
+    it, whether or not a class ever calls `fromResult()`.
+- **Documentation:** see [fromResult() — Error Accumulation](https://std-out.github.io/simple-data-objects/features/error-accumulation).
+
 ## [1.22.0] — 2026-08-05
 
 ### Added

README.md

@@ -181,6 +181,20 @@ public function store(CreateOrderData $data) { /* already validated */ }
 CreateOrderData::validate($rawArray); // throws ValidationException
 ```
 
+### Never-throw error accumulation
+
+`fromResult()` tries every field instead of stopping at the first one, with dot-paths for nested DTOs and collections:
+
+```php
+$result = CreateOrderData::fromResult($request->all());
+
+$result->ok();       // bool
+$result->errors();   // ['deliveryDate' => 'Invalid date format', 'items.2.price' => '...']
+$result->value();    // CreateOrderData — throws if !ok()
+
+// fromValidatedResult() merges in #[Rules] failures the same way
+```
+
 ---
 
 ## All Attributes

docs/.vitepress/config.mjs

@@ -76,6 +76,7 @@ export default defineConfig({
             { text: 'Hydration', link: '/features/hydration' },
             { text: 'Serialization', link: '/features/serialization' },
             { text: 'Validation', link: '/features/validation' },
+            { text: 'fromResult() — Error Accumulation', link: '/features/error-accumulation' },
             { text: 'DataPipe — Preprocessing', link: '/features/pipes' },
             { text: 'Immutable Copies — with()', link: '/features/with' },
             { text: 'Comparison — equals() & diff()', link: '/features/comparison' },

docs/attributes/reject-unknown-keys.md

@@ -73,3 +73,7 @@ Both combinations are rejected at metadata-build time, not silently ignored:
 ## Standalone constructor-less, hybrid, and lazy classes
 
 Works the same on [constructor-less and hybrid DTOs](../features/hydration.md#constructor-less-dtos) — the known-key set includes properties populated via constructor injection and via post-construction assignment alike. With [`fromLazy()`](../features/hydration.md#lazy-hydration), the check runs on first property access, same as any other hydration error.
+
+## Interaction with fromResult()
+
+Under [`fromResult()`](../features/error-accumulation.md), an unknown key doesn't abort — it's reported as a `'$unknown'` entry alongside whatever field errors also accumulated, instead of throwing immediately.

docs/features/error-accumulation.md

@@ -0,0 +1,72 @@
+# fromResult() — Error Accumulation
+
+`from()`/`tryFrom()` are fail-fast: the first invalid field throws (or `tryFrom()` swallows it and returns `null`, losing the reason). `fromResult()` is the "safe parse" alternative — analogous to zod's `safeParse` or pydantic's `ValidationError` — it never throws, tries every field, and returns every problem at once.
+
+```php
+use StdOut\SimpleDataObjects\HydrationResult;
+
+$result = OrderData::fromResult($input);
+
+$result->ok();          // bool
+$result->value();       // OrderData — throws LogicException if !ok()
+$result->valueOrNull(); // OrderData|null
+$result->errors();      // ['deliveryDate' => 'Invalid date format', 'items.2.price' => '...']
+```
+
+## Dot-path errors for nested DTOs and collections
+
+A nested `BaseData` property or a `#[DataCollection]` recurses into the target class's own `fromResult()`, so a failure several levels deep is still reported with a precise path:
+
+```php
+class OrderData extends BaseData
+{
+    public function __construct(
+        public readonly string $customerName,
+        public readonly AddressData $shippingAddress,
+        #[DataCollection(ItemData::class)]
+        public readonly TypedDataCollection $items,
+    ) {}
+}
+
+$result = OrderData::fromResult([
+    'customerName' => 'Ada',
+    'shippingAddress' => ['street' => '1 Ave'],       // missing 'city'
+    'items' => [
+        ['sku' => 'A', 'price' => 10],
+        ['sku' => 'B'],                                // missing 'price'
+    ],
+]);
+
+$result->errors();
+// [
+//   'shippingAddress.city' => "Missing required field 'city' for AddressData.",
+//   'items.1.price' => "Missing required field 'price' for ItemData.",
+// ]
+```
+
+[`#[Flatten]`](../attributes/flatten.md) fields are the one exception: since a flattened DTO's keys already live in the parent's own namespace, its errors merge in without a prefix.
+
+## What's never a per-field error
+
+- `#[RejectUnknownKeys]` reports unrecognized keys as a single `'$unknown'` entry, alongside any field errors — it doesn't abort the rest of the accumulation.
+- A failing class-level [`#[Pipe]`](../attributes/pipe.md) reports a single `'$pipeline'` entry. Since the array transform itself failed, per-field extraction is skipped for that call — there's nothing reliable left to read.
+- An exception from the constructor itself (e.g. an invariant check in the constructor body) is reported as `'$construct'`.
+- Invalid non-array input (a malformed JSON string, or a type `InputNormalizer` can't convert) is reported as `'$input'`.
+
+## fromValidatedResult() — merge in Rules validation too
+
+Runs `fromResult()` and, if the class declares `#[Rules]` (or [`#[InferRules]`](../attributes/infer-rules.md)), also validates the raw input and merges in the first message per failing rule. A validation message wins over a hydration message on the same key.
+
+```php
+$result = OrderData::fromValidatedResult($request->all());
+
+if (! $result->ok()) {
+    return response()->json(['errors' => $result->errors()], 422);
+}
+
+$order = $result->value();
+```
+
+## Performance
+
+`fromResult()` compiles its own specialized closure per class — the same code-generation strategy `from()` uses, not an interpreted walk over metadata — so it stays fast even though it never throws. It's compiled lazily and cached separately from `from()`'s hydrator: classes that never call `fromResult()` pay nothing for it, and `from()`/`tryFrom()` are completely unaffected either way.

docs/features/hydration.md

@@ -79,6 +79,8 @@ if ($user === null) {
 Use `tryFrom()` when you want to handle bad input gracefully. Use `from()` for trusted internal data.
 :::
 
+`tryFrom()` tells you *that* hydration failed, but not *why* — it discards the reason and stops at the first bad field. When you need every problem at once (with a field name attached to each), use [`fromResult()`](./error-accumulation.md) instead.
+
 ## Nested DTOs
 
 Type-hint a property as another `BaseData` subclass and it is hydrated automatically:

docs/features/validation.md

@@ -126,3 +126,7 @@ class CreateUserController
     }
 }
 ```
+
+## Never throwing: fromValidatedResult()
+
+`fromValidated()`/`validate()` throw on the first problem. For a "collect every error and never throw" alternative — merging `#[Rules]` failures with hydration failures into one map, with dot-paths for nested DTOs and collections — see [`fromResult()` — Error Accumulation](./error-accumulation.md).

docs/guide/introduction.md

@@ -42,7 +42,7 @@ $order->toJson();        // JSON string
 ## Core Concepts
 
 ### Hydration
-`from()` is a universal factory: it accepts arrays, Eloquent models and any `Arrayable`, `stdClass`, `JsonSerializable`, any `Traversable`, JSON strings, and plain objects. Nested DTOs, enums, and collections are resolved automatically.
+`from()` is a universal factory: it accepts arrays, Eloquent models and any `Arrayable`, `stdClass`, `JsonSerializable`, any `Traversable`, JSON strings, and plain objects. Nested DTOs, enums, and collections are resolved automatically. `tryFrom()` returns `null` instead of throwing; `fromResult()` goes further and never throws either, collecting every field's error (dot-pathed for nested DTOs and collections) instead of stopping at the first one.
 
 ### Serialization
 `toArray()` and `toJson()` serialize the object back to its wire format. Casts apply in both directions — hydration reads them, serialization writes them.

src/BaseData.php

@@ -110,6 +110,35 @@ public static function tryFrom(mixed $data): ?static
         }
     }
 
+    /**
+     * Like from(), but never throws — every failure is collected into the
+     * returned result instead of aborting on the first one.
+     *
+     * @return HydrationResult<static>
+     */
+    public static function fromResult(mixed $data): HydrationResult
+    {
+        $collect = HydratorCompiler::$collectingHydrators[static::class] ?? HydratorCompiler::compileCollecting(static::class);
+
+        if (is_array($data)) {
+            /** @var HydrationResult<static> */
+            return $collect($data);
+        }
+
+        if ($data instanceof static) {
+            return HydrationResult::success($data);
+        }
+
+        try {
+            $data = InputNormalizer::normalize(static::class, $data);
+        } catch (DataHydrationException $e) {
+            return HydrationResult::failure(['$input' => $e->getMessage()]);
+        }
+
+        /** @var HydrationResult<static> */
+        return $collect($data);
+    }
+
     /**
      * @return TypedDataCollection<static>
      */
@@ -208,6 +237,57 @@ public static function fromValidated(mixed $data): static
         return static::from($array);
     }
 
+    /**
+     * fromResult(), with Rules validation errors merged into the same map
+     * (validation errors win on a key collision). Never throws.
+     *
+     * @return HydrationResult<static>
+     */
+    public static function fromValidatedResult(mixed $data): HydrationResult
+    {
+        if (! is_array($data)) {
+            try {
+                $data = InputNormalizer::normalize(static::class, $data);
+            } catch (DataHydrationException $e) {
+                return HydrationResult::failure(['$input' => $e->getMessage()]);
+            }
+        }
+
+        $meta = MetadataRegistry::get(static::class);
+
+        // Same delegation as fromValidated(): the concrete class's rules apply
+        if ($meta->discriminatorField !== null) {
+            try {
+                $target = self::resolveDiscriminated($meta, $data);
+            } catch (DataHydrationException $e) {
+                return HydrationResult::failure([(string) $meta->discriminatorField => $e->getMessage()]);
+            }
+
+            /** @var HydrationResult<static> */
+            return $target::fromValidatedResult($data);
+        }
+
+        $result = static::fromResult($data);
+
+        if ($meta->validationRules === []) {
+            return $result;
+        }
+
+        $validator = static::validatorFactory()->make($data, $meta->validationRules);
+
+        if (! $validator->fails()) {
+            return $result;
+        }
+
+        $validationErrors = [];
+
+        foreach ($validator->errors()->messages() as $key => $messages) {
+            $validationErrors[$key] = $messages[0];
+        }
+
+        return HydrationResult::failure([...$result->errors(), ...$validationErrors]);
+    }
+
     /** @throws ValidationException */
     public static function validate(mixed $data): void
     {

src/HydrationResult.php

@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StdOut\SimpleDataObjects;
+
+/**
+ * @template T
+ */
+final class HydrationResult
+{
+    /**
+     * @param  T|null  $value
+     * @param  array<string, string>  $errors
+     */
+    private function __construct(
+        private readonly bool $ok,
+        private readonly mixed $value,
+        private readonly array $errors,
+    ) {}
+
+    /**
+     * @template U
+     *
+     * @param  U  $value
+     * @return self<U>
+     */
+    public static function success(mixed $value): self
+    {
+        return new self(true, $value, []);
+    }
+
+    /**
+     * @param  array<string, string>  $errors
+     * @return self<never>
+     */
+    public static function failure(array $errors): self
+    {
+        return new self(false, null, $errors);
+    }
+
+    public function ok(): bool
+    {
+        return $this->ok;
+    }
+
+    /** @return T */
+    public function value(): mixed
+    {
+        return $this->ok
+            ? $this->value
+            : throw new \LogicException('Cannot read value() of a failed HydrationResult — check ok() or use errors() first.');
+    }
+
+    /** @return T|null */
+    public function valueOrNull(): mixed
+    {
+        return $this->ok ? $this->value : null;
+    }
+
+    /** @return array<string, string> */
+    public function errors(): array
+    {
+        return $this->errors;
+    }
+}