add docs & missing events function in criteria builder

docs/pages/our-backward-compatibility-promise.md

@@ -44,3 +44,4 @@ In our docs the features are marked like this:
 
     This feature is still experimental and may change in the future.
     Use it with caution.
+

docs/pages/store.md

@@ -321,6 +321,7 @@ use Patchlevel\EventSourcing\Store\Criteria\AggregateIdCriterion;
 use Patchlevel\EventSourcing\Store\Criteria\AggregateNameCriterion;
 use Patchlevel\EventSourcing\Store\Criteria\ArchivedCriterion;
 use Patchlevel\EventSourcing\Store\Criteria\Criteria;
+use Patchlevel\EventSourcing\Store\Criteria\EventsCriterion;
 use Patchlevel\EventSourcing\Store\Criteria\FromIndexCriterion;
 
 $criteria = new Criteria(
@@ -329,6 +330,7 @@ $criteria = new Criteria(
     new FromPlayheadCriterion(2),
     new FromIndexCriterion(100),
     new ArchivedCriterion(true),
+    new EventsCriterion(['profile.created', 'profile.name_changed']),
 );
 ```
 Or you can the criteria builder to create the criteria.
@@ -342,6 +344,7 @@ $criteria = (new CriteriaBuilder())
     ->fromPlayhead(2)
     ->fromIndex(100)
     ->archived(true)
+    ->events(['profile.created', 'profile.name_changed'])
     ->build();
 ```
 #### Stream

docs/pages/subscription.md

@@ -645,6 +645,44 @@ There are two options here:
 
 In order for the subscription engine to be able to do its work, you have to assemble it beforehand.
 
+### Message Loader
+
+The subscription engine needs a message loader to load the messages.
+We provide two implementations by default.
+Which one has a better performance depends on the use case.
+
+#### Store Message Loader
+
+The store message loader loads all the messages from the event store.
+
+```php
+use Patchlevel\EventSourcing\Store\Store;
+use Patchlevel\EventSourcing\Subscription\Engine\StoreMessageLoader;
+
+/** @var Store $store */
+$messageLoader = new StoreMessageLoader($store);
+```
+#### Event Filtered Store Message Loader
+
+The event filtered store message loader loads only the messages that are relevant for the subscribers.
+It looks before loading the messages which subscribers are interested in the events.
+Then it loads with a filter only the relevant messages.
+
+```php
+use Patchlevel\EventSourcing\Metadata\Event\EventMetadataFactory;
+use Patchlevel\EventSourcing\Subscription\Engine\EventFilteredStoreMessageLoader;
+
+/**
+ * @var Store $store
+ * @var EventMetadataFactory $eventMetadataFactory
+ * @var SubscriberRepository $subscriberRepository
+ */
+$messageLoader = new EventFilteredStoreMessageLoader(
+    $store,
+    $eventMetadataFactory,
+    $subscriberRepository,
+);
+```
 ### Subscription Store
 
 The Subscription Engine uses a subscription store to store the status of each subscription.
@@ -730,24 +768,24 @@ $subscriberAccessorRepository = new MetadataSubscriberAccessorRepository([
 ### Subscription Engine
 
 Now we can create the subscription engine and plug together the necessary services.
-The event store is needed to load the events, the Subscription Store to store the subscription state
+The message loader is needed to load the messages, the Subscription Store to store the subscription state
 and we need the subscriber accessor repository. Optionally, we can also pass a retry strategy.
 
 ```php
-use Patchlevel\EventSourcing\Store\Store;
 use Patchlevel\EventSourcing\Subscription\Engine\DefaultSubscriptionEngine;
+use Patchlevel\EventSourcing\Subscription\Engine\MessageLoader;
 use Patchlevel\EventSourcing\Subscription\RetryStrategy\NoRetryStrategy;
 use Patchlevel\EventSourcing\Subscription\Store\DoctrineSubscriptionStore;
 use Patchlevel\EventSourcing\Subscription\Subscriber\MetadataSubscriberAccessorRepository;
 
 /**
- * @var Store $eventStore
+ * @var MessageLoader $messageLoader
  * @var DoctrineSubscriptionStore $subscriptionStore
  * @var MetadataSubscriberAccessorRepository $subscriberAccessorRepository
  * @var NoRetryStrategy $retryStrategy
  */
 $subscriptionEngine = new DefaultSubscriptionEngine(
-    $eventStore,
+    $messageLoader,
     $subscriptionStore,
     $subscriberAccessorRepository,
     $retryStrategy,

src/Store/Criteria/CriteriaBuilder.php

@@ -13,6 +13,9 @@ final class CriteriaBuilder
     private int|null $fromPlayhead = null;
     private bool|null $archived = null;
 
+    /** @var list<string>|null */
+    private array|null $events = null;
+
     /** @experimental */
     public function streamName(string|null $streamName): self
     {
@@ -56,6 +59,14 @@ public function archived(bool|null $archived): self
         return $this;
     }
 
+    /** @param list<string>|null $events */
+    public function events(array|null $events): self
+    {
+        $this->events = $events;
+
+        return $this;
+    }
+
     public function build(): Criteria
     {
         $criteria = [];
@@ -84,6 +95,10 @@ public function build(): Criteria
             $criteria[] = new ArchivedCriterion($this->archived);
         }
 
+        if ($this->events !== null) {
+            $criteria[] = new EventsCriterion($this->events);
+        }
+
         return new Criteria(...$criteria);
     }
 }

tests/Unit/Store/Crtieria/CriteriaBuilderTest.php

@@ -9,6 +9,7 @@
 use Patchlevel\EventSourcing\Store\Criteria\ArchivedCriterion;
 use Patchlevel\EventSourcing\Store\Criteria\Criteria;
 use Patchlevel\EventSourcing\Store\Criteria\CriteriaBuilder;
+use Patchlevel\EventSourcing\Store\Criteria\EventsCriterion;
 use Patchlevel\EventSourcing\Store\Criteria\FromIndexCriterion;
 use Patchlevel\EventSourcing\Store\Criteria\FromPlayheadCriterion;
 use PHPUnit\Framework\TestCase;
@@ -33,6 +34,7 @@ public function testFull(): void
             ->fromIndex(1)
             ->fromPlayhead(1)
             ->archived(true)
+            ->events(['foo', 'bar'])
             ->build();
 
         self::assertEquals(
@@ -42,6 +44,7 @@ public function testFull(): void
                 new FromIndexCriterion(1),
                 new FromPlayheadCriterion(1),
                 new ArchivedCriterion(true),
+                new EventsCriterion(['foo', 'bar']),
             ),
             $criteria,
         );