feat: Add isSubjectPopulated precondition (#156)

Author: goloroden

README.md

@@ -86,6 +86,23 @@ written_events = await client.write_events(
 )
 ```
 
+#### Using the `isSubjectPopulated` precondition
+
+If you only want to write events in case a subject (such as `/books/42`) already has at least one event, import the `IsSubjectPopulated` class and pass it as the second argument as a list of preconditions:
+
+```python
+from eventsourcingdb import IsSubjectPopulated
+
+written_events = await client.write_events(
+  events = [
+    # events
+  ],
+  preconditions = [
+    IsSubjectPopulated('/books/42')
+  ],
+)
+```
+
 #### Using the `isSubjectOnEventId` precondition
 
 If you only want to write events in case the last event of a subject (such as `/books/42`) has a specific ID (e.g., `0`), import the `IsSubjectOnEventId` class and pass it as a list of preconditions in the second argument:

eventsourcingdb/__init__.py

@@ -10,7 +10,13 @@
 )
 from .read_event_types import EventType
 from .read_events import IfEventIsMissingDuringRead, Order, ReadEventsOptions, ReadFromLatestEvent
-from .write_events import IsEventQlQueryTrue, IsSubjectOnEventId, IsSubjectPristine, Precondition
+from .write_events import (
+    IsEventQlQueryTrue,
+    IsSubjectOnEventId,
+    IsSubjectPopulated,
+    IsSubjectPristine,
+    Precondition,
+)
 
 __all__ = [
     "Bound",
@@ -27,6 +33,7 @@
     "InternalError",
     "IsEventQlQueryTrue",
     "IsSubjectOnEventId",
+    "IsSubjectPopulated",
     "IsSubjectPristine",
     "ObserveEventsOptions",
     "ObserveFromLatestEvent",

eventsourcingdb/write_events/__init__.py

@@ -1,8 +1,15 @@
-from .preconditions import IsEventQlQueryTrue, IsSubjectOnEventId, IsSubjectPristine, Precondition
+from .preconditions import (
+    IsEventQlQueryTrue,
+    IsSubjectOnEventId,
+    IsSubjectPopulated,
+    IsSubjectPristine,
+    Precondition,
+)
 
 __all__ = [
     "IsEventQlQueryTrue",
     "IsSubjectOnEventId",
+    "IsSubjectPopulated",
     "IsSubjectPristine",
     "Precondition",
 ]

eventsourcingdb/write_events/preconditions.py

@@ -17,6 +17,14 @@ def to_json(self) -> dict[str, Any]:
         return {"type": "isSubjectPristine", "payload": {"subject": self.subject}}
 
 
+@dataclass
+class IsSubjectPopulated(Precondition):
+    subject: str
+
+    def to_json(self) -> dict[str, Any]:
+        return {"type": "isSubjectPopulated", "payload": {"subject": self.subject}}
+
+
 @dataclass
 class IsSubjectOnEventId(Precondition):
     subject: str

tests/test_write_events.py

@@ -1,7 +1,14 @@
 import pytest
 from aiohttp import ClientConnectorDNSError
 
-from eventsourcingdb import EventCandidate, IsEventQlQueryTrue, IsSubjectOnEventId, IsSubjectPristine, ServerError
+from eventsourcingdb import (
+    EventCandidate,
+    IsEventQlQueryTrue,
+    IsSubjectOnEventId,
+    IsSubjectPopulated,
+    IsSubjectPristine,
+    ServerError,
+)
 
 from .conftest import TestData
 from .shared.database import Database
@@ -130,6 +137,58 @@ async def test_is_pristine_precondition_fails_for_existing_subject(
                 [IsSubjectPristine("/")],
             )
 
+    @staticmethod
+    @pytest.mark.asyncio
+    async def test_is_subject_populated_precondition_fails_for_empty_subject(
+        database: Database,
+        test_data: TestData,
+    ) -> None:
+        client = database.get_client()
+
+        with pytest.raises(ServerError):
+            await client.write_events(
+                [
+                    EventCandidate(
+                        source=test_data.TEST_SOURCE_STRING,
+                        subject="/",
+                        type="com.foo.bar",
+                        data={},
+                    )
+                ],
+                [IsSubjectPopulated("/")],
+            )
+
+    @staticmethod
+    @pytest.mark.asyncio
+    async def test_is_subject_populated_precondition_works_for_existing_subject(
+        database: Database,
+        test_data: TestData,
+    ) -> None:
+        client = database.get_client()
+
+        await client.write_events(
+            [
+                EventCandidate(
+                    source=test_data.TEST_SOURCE_STRING,
+                    subject="/",
+                    type="com.foo.bar",
+                    data={"value": 23},
+                )
+            ]
+        )
+
+        await client.write_events(
+            [
+                EventCandidate(
+                    source=test_data.TEST_SOURCE_STRING,
+                    subject="/",
+                    type="com.foo.bar",
+                    data={"value": 42},
+                )
+            ],
+            [IsSubjectPopulated("/")],
+        )
+
     @staticmethod
     @pytest.mark.asyncio
     async def test_is_on_event_id_precondition_works_for_correct_id(