Release/2.1.0 (#6)

Author: gustavofreze

README.md

@@ -39,18 +39,17 @@ interface AggregateRoot extends Entity
      *
      * @return SequenceNumber The current sequence number.
      */
-    public function getSequenceNumber(): SequenceNumber;
+    public function sequenceNumber(): SequenceNumber;
 
     /**
      * Returns the schema version of this aggregate type.
      *
-     * <p>Resolved from the protected <code>modelVersion()</code> method, defaults to <code>0</code>
-     * when the method is not overridden. Used by consumers to migrate aggregate schemas when loading older
-     * persisted state.</p>
+     * <p>Defaults to <code>ModelVersion::initial()</code> (value 0) when not overridden. Used by consumers
+     * to migrate aggregate schemas when loading older persisted state.</p>
      *
-     * @return SequenceNumber The declared model version, or 0 when not overridden.
+     * @return ModelVersion The declared model version.
      */
-    public function getModelVersion(): SequenceNumber;
+    public function modelVersion(): ModelVersion;
 
     /**
      * Returns the short class name of this aggregate.
@@ -60,5 +59,5 @@ public function getModelVersion(): SequenceNumber;
      *
      * @return string The short class name.
      */
-    public function buildAggregateName(): string;
+    public function aggregateName(): string;
 }

src/Aggregate/AggregateRoot.php

@@ -12,7 +12,7 @@
 use TinyBlocks\BuildingBlocks\Event\EventRecords;
 use TinyBlocks\BuildingBlocks\Event\EventType;
 use TinyBlocks\BuildingBlocks\Event\SequenceNumber;
-use TinyBlocks\BuildingBlocks\Event\SnapshotData;
+use TinyBlocks\BuildingBlocks\Snapshot\SnapshotData;
 use TinyBlocks\Time\Instant;
 
 trait AggregateRootBehavior
@@ -23,44 +23,44 @@ trait AggregateRootBehavior
 
     private SequenceNumber $sequenceNumber;
 
-    public function getSequenceNumber(): SequenceNumber
+    public function sequenceNumber(): SequenceNumber
     {
         return $this->sequenceNumber ?? SequenceNumber::initial();
     }
 
-    public function getModelVersion(): SequenceNumber
+    public function modelVersion(): ModelVersion
     {
-        return SequenceNumber::of(value: $this->modelVersion());
+        return ModelVersion::initial();
     }
 
-    public function buildAggregateName(): string
+    public function aggregateName(): string
     {
-        return new ReflectionClass(static::class)->getShortName();
+        return new ReflectionClass(objectOrClass: static::class)->getShortName();
     }
 
-    protected function modelVersion(): int
+    protected function nextSequenceNumber(): void
     {
-        return 0;
+        $this->sequenceNumber = $this->sequenceNumber()->next();
     }
 
-    protected function nextSequenceNumber(): void
+    protected function generateSnapshotData(): SnapshotData
     {
-        $this->sequenceNumber = $this->getSequenceNumber()->next();
+        return new SnapshotData(payload: $this->snapshotState());
     }
 
-    public function recordedEvents(): EventRecords
+    protected function snapshotState(): array
     {
-        $records = $this->recordedEvents ?? EventRecords::createFromEmpty();
+        $state = get_object_vars($this);
+        unset($state['recordedEvents'], $state['sequenceNumber']);
 
-        return EventRecords::createFrom(elements: $records);
+        return $state;
     }
 
-    protected function generateSnapshotData(): SnapshotData
+    public function recordedEvents(): EventRecords
     {
-        $state = get_object_vars($this);
-        unset($state['recordedEvents']);
+        $records = $this->recordedEvents ?? EventRecords::createFromEmpty();
 
-        return new SnapshotData(payload: $state);
+        return EventRecords::createFrom(elements: $records);
     }
 
     protected function buildEventRecord(DomainEvent $event): EventRecord
@@ -69,12 +69,12 @@ protected function buildEventRecord(DomainEvent $event): EventRecord
             id: Uuid::uuid4(),
             type: EventType::fromEvent(event: $event),
             event: $event,
-            identity: $this->getIdentity(),
+            identity: $this->identity(),
             revision: $event->revision(),
             occurredOn: Instant::now(),
             snapshotData: $this->generateSnapshotData(),
-            aggregateType: $this->buildAggregateName(),
-            sequenceNumber: $this->getSequenceNumber()
+            aggregateType: $this->aggregateName(),
+            sequenceNumber: $this->sequenceNumber()
         );
     }
 }

src/Aggregate/AggregateRootBehavior.php

@@ -54,7 +54,7 @@ public function recordedEvents(): EventRecords;
      *
      * @param Identity $identity The identity to assign to the new aggregate.
      * @return static A new aggregate in its initial state.
-     * @throws MissingIdentityProperty When the property referenced by <code>identityName()</code> does not exist.
+     * @throws MissingIdentityProperty When the property referenced by <code>identityProperty()</code> does not exist.
      */
     public static function blank(Identity $identity): static;
 
@@ -69,7 +69,7 @@ public static function blank(Identity $identity): static;
      * @param iterable<EventRecord> $records The event stream to replay, ordered by sequence number.
      * @param Snapshot|null $snapshot Optional snapshot to restore from before replay.
      * @return static The reconstituted aggregate.
-     * @throws MissingIdentityProperty When the property referenced by <code>identityName()</code> does not exist.
+     * @throws MissingIdentityProperty When the property referenced by <code>identityProperty()</code> does not exist.
      */
     public static function reconstitute(Identity $identity, iterable $records, ?Snapshot $snapshot = null): static;
 
@@ -83,12 +83,12 @@ public static function reconstitute(Identity $identity, iterable $records, ?Snap
      *
      * @return array<string, mixed> Keyed by property name.
      */
-    public function getSnapshotState(): array;
+    public function snapshotState(): array;
 
     /**
      * Restores aggregate state from the given snapshot.
      *
-     * <p>Implementations read {@see Snapshot::getAggregateState()} and copy the relevant fields into
+     * <p>Implementations read {@see Snapshot::aggregateState()} and copy the relevant fields into
      * their own properties. The sequence number is applied automatically by
      * <code>reconstitute()</code>; implementations should not touch it.</p>
      *

src/Aggregate/EventSourcingRoot.php

@@ -39,7 +39,7 @@ public static function reconstitute(
 
         if (!is_null($snapshot)) {
             $aggregate->applySnapshot(snapshot: $snapshot);
-            $aggregate->sequenceNumber = $snapshot->getSequenceNumber();
+            $aggregate->sequenceNumber = $snapshot->sequenceNumber();
         }
 
         foreach ($records as $record) {
@@ -54,7 +54,7 @@ public function eventHandlers(): array
         return [];
     }
 
-    public function getSnapshotState(): array
+    public function snapshotState(): array
     {
         $state = get_object_vars($this);
         unset($state['recordedEvents'], $state['sequenceNumber']);

src/Aggregate/EventSourcingRootBehavior.php

@@ -10,9 +10,15 @@
  * Aggregate root variant that records domain events for eventual publication via transactional outbox.
  *
  * <p>State is persisted as the source of truth; events are emitted as side effects and delivered
- * at-least-once to external consumers. The repository is expected to drain
- * <code>recordedEvents()</code> after persisting the aggregate state and then call
- * <code>clearRecordedEvents()</code> to reset the buffer for the next unit of work.</p>
+ * at-least-once to external consumers. The repository drains <code>recordedEvents()</code> after
+ * persisting the aggregate state.</p>
+ *
+ * <p><strong>Use-once contract:</strong> the recorded-events buffer is never cleared. After the
+ * repository drains <code>recordedEvents()</code> and persists the records to the outbox, the aggregate
+ * instance must be discarded. Re-saving the same instance attempts to push the same envelopes again and
+ * fails with a duplicate-event error from the outbox. Applications that need to perform multiple
+ * operations on the same logical aggregate within one process must reload from the repository between
+ * operations.</p>
  *
  * <p>Sibling of {@see EventSourcingRoot}, not a parent. Outbox and event sourcing are mutually exclusive
  * persistence strategies: an aggregate either persists its state and emits events as side effects, or
@@ -25,19 +31,12 @@
 interface EventualAggregateRoot extends AggregateRoot
 {
     /**
-     * Returns a copy of the events recorded since the last clear.
+     * Returns a copy of all events recorded since the aggregate was created.
      *
      * <p>Always returns a fresh copy: external mutation of the returned collection does not leak into the
      * aggregate's internal buffer.</p>
      *
      * @return EventRecords A snapshot of the recorded events, safe to iterate and mutate.
      */
     public function recordedEvents(): EventRecords;
-
-    /**
-     * Discards all recorded events.
-     *
-     * <p>Typically called by the repository after the events have been persisted to the outbox.</p>
-     */
-    public function clearRecordedEvents(): void;
 }

src/Aggregate/EventualAggregateRoot.php

@@ -11,11 +11,6 @@ trait EventualAggregateRootBehavior
 {
     use AggregateRootBehavior;
 
-    public function clearRecordedEvents(): void
-    {
-        $this->recordedEvents = EventRecords::createFromEmpty();
-    }
-
     protected function push(DomainEvent $event): void
     {
         $this->nextSequenceNumber();

src/Aggregate/EventualAggregateRootBehavior.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\BuildingBlocks\Aggregate;
+
+use TinyBlocks\BuildingBlocks\Internal\Exceptions\InvalidModelVersion;
+use TinyBlocks\Vo\ValueObject;
+use TinyBlocks\Vo\ValueObjectBehavior;
+
+final readonly class ModelVersion implements ValueObject
+{
+    use ValueObjectBehavior;
+
+    private function __construct(public int $value)
+    {
+        if ($value < 0) {
+            throw new InvalidModelVersion(value: $value);
+        }
+    }
+
+    public static function of(int $value): ModelVersion
+    {
+        return new ModelVersion(value: $value);
+    }
+
+    public static function initial(): ModelVersion
+    {
+        return new ModelVersion(value: 0);
+    }
+}

src/Aggregate/ModelVersion.php

@@ -11,7 +11,7 @@
  * unique (for example <code>(tenantId, appointmentId)</code> in multi-tenant contexts). Not a concept
  * from Evans.</p>
  *
- * <p>All declared properties participate in the identity: <code>getIdentityValue()</code> returns them
+ * <p>All declared properties participate in the identity: <code>identityValue()</code> returns them
  * as an associative array keyed by property name.</p>
  */
 interface CompoundIdentity extends Identity

src/Entity/CompoundIdentity.php

@@ -10,7 +10,7 @@ trait CompoundIdentityBehavior
 {
     use ValueObjectBehavior;
 
-    public function getIdentityValue(): mixed
+    public function identityValue(): mixed
     {
         return get_object_vars($this);
     }