Major overhaul

Author: bwaidelich

Specification.md

@@ -1,72 +1,84 @@
-## EventStore
+# EventStore
 
-### Reading
+## Reading
 
 Expects a [StreamQuery](#StreamQuery) and an optional starting [SequenceNumber](#SequenceNumber) and returns an [EventStream](#EventStream).
 
-**Note:** The EventStore should also allow for _backwards_ iteration on the EventStream in order to support cursor based pagination.
+> [!NOTE]  
+> The EventStore should also allow for _backwards_ iteration on the EventStream in order to support cursor based pagination.
 
-### Writing
+## Writing
 
 Expects a set of [Events](#Events) and an [AppendCondition](#AppendCondition) and returns the last appended [SequenceNumber](#SequenceNumber).
 
-#### Potential API
+## API
+
+A potential interface of the `EventStore` (pseudo-code):
 
 ```
 EventStore {
+  read(query: StreamQuery, options?: ReadOptions): EventStream
+  append(events: Events|Event, condition: AppendCondition): SequenceNumber
+}
+```
 
-  read(query: StreamQuery, from?: SequenceNumber): EventStream
-  
-  readBackwards(query: StreamQuery, from?: SequenceNumber): EventStream
-  
-  append(events: Events, condition: AppendCondition): SequenceNumber
-  
+### ReadOptions
+
+An optional parameter to `EventStore.read()` that allows for cursor-based pagination of events.
+It has two parameters:
+- `backwards` a flag that, if set to `true`, returns the events in descending order (default: `false`)
+- `from` an optional [SequenceNumber](#SequenceNumber) to start streaming events from (depending on the `backwards` flag this is either a _minimum_ or _maximum_ sequence number of the resulting stream)
+
+```
+ReadOptions {
+  from?: SequenceNumber
+  backwards: bool
 }
 ```
 
-## StreamQuery
+### StreamQuery
 
-The `StreamQuery` describes constraints that must be matched by [Event](#Event)s in the [EventStore](#EventStore).
+The `StreamQuery` describes constraints that must be matched by [Event](#Event)s in the [EventStore](#EventStore)
+It effectively allows for filtering events by their [type](#EventType) and/or [tags](#Tags)
 
-* It _MAY_ contain a set of [StreamQuery Criteria](#StreamQuery-Criterion)
+* It _MAY_ contain a set of [StreamQuery Criteria](#StreamQuery-Criterion) – a `StreamQuery` with an empty criteria set is considered a "wildcard" query, i.e. it matches all events
 
-**Note:** All criteria of a StreamQuery are merged into a *logical disjunction*, so the example below matches all events, that match the first **OR** the second criterion.
+> [!NOTE]  
+> All criteria of a StreamQuery are merged into a *logical disjunction*, so events match the query if they match the first **OR** the second criterion...
 
-#### Potential serialization format
+### StreamQuery Criterion
 
-```json 
-{
-    "version": "1.0",
-    "criteria": [{
-        "type": "EventTypes",
-        "properties": {
-            "event_types": ["EventType1", "EventType2"]
-        }
-    }, {
-        "type": "Tags",
-        "properties": {
-            "tags": ["foo:bar", "baz:foos"],
-        }
-    }, {
-        "type": "EventTypesAndTags",
-        "properties": {
-            "event_types": ["EventType2", "EventType3"],
-            "tags": ["foo:bar", "foo:baz"],
-        }
-    }]
-}
-```
+Each criterion of a [StreamQuery](#StreamQuery) allows to target events by their [type](#EventType) and/or [tags](#Tags)
 
+> [!NOTE]  
+> event type filters of a single criterion are merged into a *logical disjunction*, so events match the criterion if they match **ANY** of the specified types
+> tags are merged into a *logical conjunction*, so events match the criterion if they are tagged with **ALL** specified tags
 
-## StreamQuery Criterion
+#### Example StreamQuery
 
-In v1 the only supported criteria types are:
+The following example query would match events that are either...
+- ...of type `EventType1` **OR** `EventType2`
+- ...tagged `foo:bar` **AND** `baz:foos`
+- ...of type `EventType2` **OR** `EventType3` **AND** tagged `foo:bar`**AND** `foo:baz`
 
-* `Tags` – allows to target one or more [Tags](#Tags)
-* `EventTypes` – allows to target one or more [EventType](#EventType)s
-* `EventTypesAndTags` – allows to target one or more [Tags](#Tags) and one or more [EventType](#EventType)s
+```json 
+{
+  "criteria": [
+    {
+      "event_types": ["EventType1", "EventType2"]
+    },
+    {
+      "tags": ["foo:bar", "baz:foos"]
+    },
+    {
+      "event_types": ["EventType2", "EventType3"],
+      "tags": ["foo:bar", "foo:baz"]
+    }
+  ]
+}
+```
 
-## SequenceNumber
+### SequenceNumber
 
 When an [Event](#Event) is appended to the [EventStore](#EventStore) a `SequenceNumber` is assigned to it.
 
@@ -77,8 +89,7 @@ It...
 * _CAN_ contain gaps
 * _SHOULD_ have a reasonably high maximum value (depending on programming language and environment)
 
-
-## EventStream
+### EventStream
 
 When reading from the [EventStore](#EventStore) an `EventStream` is returned.
 
@@ -89,94 +100,92 @@ It...
 * Individual [EventEnvelope](#EventEnvelope) instances _MAY_ be converted during iteration for performance optimization
 * Batches of events _MAY_ be loaded from the underlying storage at once for performance optimization
 
-## EventEnvelope
+### EventEnvelope
 
 Each item in the [EventStream](#EventStream) is an `EventEnvelope` that consists of the underlying event and metadata, like the [SequenceNumber](#SequenceNumber) that was added during the `append()` call.
 
+It...
+* It _MUST_ contain the [SequenceNumber](#SequenceNumber)
+* It _MUST_ contain the [Event](#Event)
+* It _CAN_ include more fields, like timestamps or metadata
+
+#### EventEnvelope example
+
 ```json
 {
     "event": {
-        "id": "15aaa216-4179-46d9-999a-75516e21a1c6",
         "type": "SomeEventType",
-        "data": "{\"some\":\"data\"}"
+        "data": "{\"some\":\"data\"}",
         "tags": ["type1:value1", "type2:value2"]
     },
-    "sequence_number": 1234
+    "sequence_number": 1234,
+    "recorded_at": "2024-12-10 14:02:40"
 }
 ```
 
-## Events
+### Events
 
 A set of [Event](#Event) instances that is passed to the `append()` method of the [EventStore](#EventStore)
 
 It...
 * _MUST_ not be empty
 * _MUST_ be iterable, each iteration returning an [Event](#Event)
 
-## Event
+### Event
 
-* It _MUST_ contain a globally unique [EventId](#EventId)
 * It _MUST_ contain an [EventType](#EventType)
 * It _MUST_ contain [EventData](#EventData)
 * It _MAY_ contain [Tags](#Tags)
+* It _MAY_ contain further fields, like metadata
 
 #### Potential serialization format
 
 ```json
 {
-    "id": "15aaa216-4179-46d9-999a-75516e21a1c6",
     "type": "SomeEventType",
-    "data": "{\"some\":\"data\"}"
+    "data": "{\"some\":\"data\"}",
     "tags": ["key1:value1", "key1:value2"]
 }
 ```
 
-## EventId
-
-String based globally unique identifier of an [Event](#Event)
-
-* It _MUST_ satisfy the regular expression `^[\w\-]{1,100}$`
-* It _MAY_ be implemented as a [UUID](https://www.ietf.org/rfc/rfc4122.txt)
-
-## EventType
+### EventType
 
-String based type of an event
+String based type of the event
 
 * It _MUST_ satisfy the regular expression `^[\w\.\:\-]{1,200}$`
 
-## EventData
+### EventData
 
 String based, opaque payload of an [Event](#Event)
 
 * It _SHOULD_ have a reasonable large enough maximum length (depending on language and environment)
 * It _MAY_ contain [JSON](https://www.json.org/)
 * It _MAY_ be serialized into an empty string
 
-## Tags
+### Tags
 
 A set of [Tag](#Tag) instances.
 
 * It _MUST_ contain at least one [Tag](#Tag)
-* It _MAY_ contain multiple [Tag](#Tag)s with the same value
-* It _SHOULD_ not contain muliple [Tag](#Tag)s with the same key/value pair
+* It _SHOULD_ not contain multiple [Tag](#Tag)s with the same value
 
-## Tag
+### Tag
 
-A `Tag` can add domain specific metadata (usually the ids of an entity or concept of the core domain) to an event allowing for custom partitioning
+A `Tag` can add domain specific metadata to an event allowing for custom partitioning
 
-**NOTE:** If the `value` is not specified, all tags of the given `key` will match (wildcard)
+> [!NOTE]
+> Usually a tag represents a concept of the domain, e.g. the type and id of an entity like `product:p123`
 
-* It _MUST_ contain a `key` that satisfies the regular expression `^[a-zA-Z0-9\-\_]{1,50}$`
-* It _CAN_ contain a `value` that satisfies the regular expression `^[a-zA-Z0-9\-\_]{1,50}$`
+* It _MUST_ satisfy the regular expression `/^[[:alnum:]\-\_\:]{1,150}`
 
-## AppendCondition
+### AppendCondition
 
 * It _MUST_ contain a [StreamQuery](#StreamQuery)
 * It _MUST_ contain a [ExpectedHighestSequenceNumber](#ExpectedHighestSequenceNumber)
 
-## ExpectedHighestSequenceNumber
+### ExpectedHighestSequenceNumber
 
-Can _either_ be an instance of [SequenceNumber](#SequenceNumber)
+Can _either_ represent an instance of [SequenceNumber](#SequenceNumber)
 Or one of:
 * `NONE` – No event must match the specified [StreamQuery](#StreamQuery)
 * `ANY` – Any event matches (= wildcard [AppendCondition](#AppendCondition))

composer.json

@@ -20,8 +20,7 @@
     }
   ],
   "require": {
-    "php": ">=8.1",
-    "ramsey/uuid": "^4.7",
+    "php": ">=8.4",
     "psr/clock": "^1",
     "webmozart/assert": "^1.11"
   },

src/EventStore.php

@@ -6,6 +6,7 @@
 
 use Wwwision\DCBEventStore\Exceptions\ConditionalAppendFailed;
 use Wwwision\DCBEventStore\Types\AppendCondition;
+use Wwwision\DCBEventStore\Types\Event;
 use Wwwision\DCBEventStore\Types\Events;
 use Wwwision\DCBEventStore\Types\ReadOptions;
 use Wwwision\DCBEventStore\Types\StreamQuery\StreamQuery;
@@ -23,21 +24,14 @@ interface EventStore
      */
     public function read(StreamQuery $query, ?ReadOptions $options = null): EventStream;
 
-    /**
-     * Returns an event stream that contains all events
-     *
-     * @param ReadOptions|null $options optional configuration for this interaction ({@see ReadOptions})
-     */
-    public function readAll(?ReadOptions $options = null): EventStream;
-
     /**
      * Commits the specified $events if the specified {@see AppendCondition} is satisfied
      *
      * NOTE: This is an atomic operation, so either _all_ events will be committed or _none_
      *
-     * @param Events $events The events to append to the event stream
-     * @param AppendCondition $condition The condition that has to be met
+     * @param Events|Event $events The events (or a single event) to append to the event stream
+     * @param AppendCondition $condition The condition that has to be met. Note: use {@see AppendCondition::noConstraints()} to skip constraint checks
      * @throws ConditionalAppendFailed If specified $condition is violated
      */
-    public function append(Events $events, AppendCondition $condition): void;
+    public function append(Events|Event $events, AppendCondition $condition): void;
 }

src/Helpers/InMemoryEventStore.php

@@ -91,11 +91,6 @@ public function read(StreamQuery $query, ?ReadOptions $options = null): InMemory
         return InMemoryEventStream::create(...$matchingEventEnvelopes);
     }
 
-    public function readAll(?ReadOptions $options = null): EventStream
-    {
-        return $this->read(StreamQuery::wildcard(), $options);
-    }
-
     private static function criterionMatchesEvent(Criterion $criterion, Event $event): bool
     {
         return match ($criterion::class) {
@@ -104,7 +99,7 @@ private static function criterionMatchesEvent(Criterion $criterion, Event $event
         };
     }
 
-    public function append(Events $events, AppendCondition $condition): void
+    public function append(Events|Event $events, AppendCondition $condition): void
     {
         if (!$condition->expectedHighestSequenceNumber->isAny()) {
             $lastEventEnvelope = $this->read($condition->query, ReadOptions::create(backwards: true))->first();
@@ -120,6 +115,9 @@ public function append(Events $events, AppendCondition $condition): void
         }
         $sequenceNumber = SequenceNumber::fromInteger(count($this->eventEnvelopes) + 1);
         $newEventEnvelopes = EventEnvelopes::none();
+        if ($events instanceof Event) {
+            $events = Events::fromArray([$events]);
+        }
         foreach ($events as $event) {
             $newEventEnvelopes = $newEventEnvelopes->append(
                 new EventEnvelope(