feat: Add support for the isEventQlTrue precondition (#108)

* feat: add IsEventQLTrue precondition and corresponding tests

* chore: adjust precondition casing

* chore: adjust readme

* chore: remove escape sequences from example query in README

Author: matthiasharzer

README.md

@@ -105,6 +105,25 @@ written_events = await client.write_events(
 
 *Note that according to the CloudEvents standard, event IDs must be of type string.*
 
+#### Using the `isEventQlTrue` precondition
+
+If you want to write events depending on an EventQL query, import the `IsEventQlTrue` class and pass it as a list of preconditions in the second argument:
+
+```python
+from eventsourcingdb import IsEventQlTrue
+
+written_events = await client.write_events(
+  events = [
+    # events
+  ],
+  preconditions = [
+    IsEventQlTrue('FROM e IN events WHERE e.type == "io.eventsourcingdb.library.book-borrowed" PROJECT INTO COUNT() < 10')
+  ],
+)
+```
+
+*Note that the query must return a single row with a single value, which is interpreted as a boolean.*
+
 ### Reading Events
 
 To read all events of a subject, call the `read_events` function with the subject as the first argument and an options object as the second argument. Set the `recursive` option to `False`. This ensures that only events of the given subject are returned, not events of nested subjects.
@@ -530,4 +549,4 @@ In case you need to set up the client yourself, use the following functions to g
 - `get_host()` returns the host name
 - `get_mapped_port()` returns the port
 - `get_base_url()` returns the full URL of the container
-- `get_api_token()` returns the API token
+- `get_api_token()` returns the API token

eventsourcingdb/__init__.py

@@ -10,7 +10,7 @@
 )
 from .read_event_types import EventType
 from .read_events import IfEventIsMissingDuringRead, Order, ReadEventsOptions, ReadFromLatestEvent
-from .write_events import IsSubjectOnEventId, IsSubjectPristine, Precondition
+from .write_events import IsEventQlTrue, IsSubjectOnEventId, IsSubjectPristine, Precondition
 
 __all__ = [
     "Bound",
@@ -25,6 +25,7 @@
     "IfEventIsMissingDuringObserve",
     "IfEventIsMissingDuringRead",
     "InternalError",
+    "IsEventQlTrue",
     "IsSubjectOnEventId",
     "IsSubjectPristine",
     "ObserveEventsOptions",

eventsourcingdb/write_events/__init__.py

@@ -1,6 +1,7 @@
-from .preconditions import IsSubjectOnEventId, IsSubjectPristine, Precondition
+from .preconditions import IsEventQlTrue, IsSubjectOnEventId, IsSubjectPristine, Precondition
 
 __all__ = [
+    "IsEventQlTrue",
     "IsSubjectOnEventId",
     "IsSubjectPristine",
     "Precondition",

eventsourcingdb/write_events/preconditions.py

@@ -27,3 +27,15 @@ def to_json(self) -> dict[str, Any]:
             "type": "isSubjectOnEventId",
             "payload": {"subject": self.subject, "eventId": self.event_id},
         }
+
+@dataclass
+class IsEventQlTrue(Precondition):
+    query: str
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            'type': 'isEventQlTrue',
+            'payload': {
+                'query': self.query
+            }
+        }

tests/shared/docker/eventsourcingdb/Dockerfile

@@ -1 +1 @@
-FROM thenativeweb/eventsourcingdb:1.0.3
+FROM thenativeweb/eventsourcingdb:preview

tests/test_write_events.py

@@ -1,7 +1,7 @@
 import pytest
 from aiohttp import ClientConnectorDNSError
 
-from eventsourcingdb import EventCandidate, IsSubjectOnEventId, IsSubjectPristine, ServerError
+from eventsourcingdb import EventCandidate, IsEventQlTrue, IsSubjectOnEventId, IsSubjectPristine, ServerError
 
 from .conftest import TestData
 from .shared.database import Database
@@ -184,6 +184,60 @@ async def test_is_subject_on_event_id_fails_for_wrong_id(
                 [IsSubjectOnEventId("/", "2")],
             )
 
+    @staticmethod
+    @pytest.mark.asyncio
+    async def test_is_event_ql_true_precondition_works(
+        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={}
+                )
+            ]
+        )
+
+        await client.write_events(
+            [
+                EventCandidate(
+                    source=test_data.TEST_SOURCE_STRING, subject="/", type="com.foo.bar", data={}
+                )
+            ],
+            [IsEventQlTrue("FROM e IN events PROJECT INTO COUNT() > 0")]
+        )
+
+    @staticmethod
+    @pytest.mark.asyncio
+    async def test_is_event_ql_true_precondition_fails(
+        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={}
+                )
+            ]
+        )
+
+        with pytest.raises(ServerError):
+            await client.write_events(
+                [
+                    EventCandidate(
+                        source=test_data.TEST_SOURCE_STRING,
+                        subject="/",
+                        type="com.foo.bar",
+                        data={},
+                    )
+                ],
+                [IsEventQlTrue("FROM e IN events PROJECT INTO COUNT() == 0")]
+            )
+
     @staticmethod
     @pytest.mark.asyncio
     async def test_throws_error_if_event_does_not_match_schema(