add documentation

README.md

@@ -4,7 +4,7 @@
 [![codecov](https://codecov.io/gh/innmind/validation/branch/develop/graph/badge.svg)](https://codecov.io/gh/innmind/validation)
 [![Type Coverage](https://shepherd.dev/github/innmind/validation/coverage.svg)](https://shepherd.dev/github/innmind/validation)
 
-Description
+This package is a monadic approach to data validation to easily compose validations rules.
 
 ## Installation
 
@@ -14,4 +14,69 @@ composer require innmind/validation
 
 ## Usage
 
-Todo
+```php
+use Innmind\Validation\{
+    Shape,
+    Is,
+    Each,
+    Failure,
+};
+use Innmind\Immutable\Sequence;
+
+$valid = [
+    'id' => 42,
+    'username' => 'jdoe',
+    'addresses' => [
+        'address 1',
+        'address 2',
+    ],
+    'submit' => true,
+];
+$invalid = [
+    'id' => '42',
+    'addresses' => [
+        'address 1',
+        null,
+    ],
+    'submit' => true,
+];
+
+$validate = Shape::of('id', Is::int())
+    ->with('username', Is::string())
+    ->with(
+        'addresses',
+        Is::array()
+            ->and(Is::list())
+            ->and(Each::of(Is::string())->map(
+                static fn(string $address) => new YourModel($address),
+            ))
+    );
+$result = $validate($valid)->match(
+    static fn(array $value) => $value,
+    static fn() => throw new \RuntimeException('invalid data'),
+);
+// Here $result looks like:
+// [
+//      'id' => 42
+//      'username' => 'jdoe',
+//      'addresses' [
+//          new YourModel('address 1'),
+//          new YourModel('address 2'),
+//      ],
+// ]
+$errors = $validate($invalid)->match(
+    static fn() => null,
+    static fn(Sequence $failures) => $failures
+        ->map(static fn(Failure $failure) => [
+            $failure->path()->toString(),
+            $failure->message(),
+        ])
+        ->toList(),
+);
+// Here $errors looks like:
+// [
+//      ['id', 'Value is not of type int'],
+//      ['$', 'The key username is mission'],
+//      ['addresses', 'Value is not of type string']
+// ]
+```