refactor(database): type-check immutable filter builders (#360)

* refactor(database): keep filter state on concrete builders

* test(database): reject invalid filter mutations

Author: swkeever

maintainers/quality-policy.lock.json

@@ -272,7 +272,8 @@
         "src/volcano_sdk/realtime.py",
         "src/volcano_sdk/auth.py",
         "src/volcano_sdk/storage.py",
-        "src/volcano_sdk/functions.py"
+        "src/volcano_sdk/functions.py",
+        "src/volcano_sdk/database.py"
       ]
     },
     "mypy": {

pyproject.toml

@@ -426,6 +426,7 @@ type_check_command = [
   "src/volcano_sdk/auth.py",
   "src/volcano_sdk/storage.py",
   "src/volcano_sdk/functions.py",
+  "src/volcano_sdk/database.py",
 ]
 cache_invalidation_files = ["tests/**/*.py"]
 pytest_add_cli_args_test_selection = ["tests/unit"]

scripts/check_quality_policy.py

@@ -18,7 +18,7 @@
     from collections.abc import Iterable
 
 GENERATED = "src/volcano_sdk/_generated"
-LOCK_SHA256 = "0929858d578e0b330eaaaedf739e16a0053aff1659604b4f8c0fd9cbc4d20b2e"
+LOCK_SHA256 = "217925dcf7067ed20a1f560c54d2fccfd47df28702ded83e9f4352fc69334651"
 TYPE_FIXTURES = {
     "tests/typing/contract_steps.py",
     "tests/typing/durable_callbacks.py",

src/volcano_sdk/database.py

@@ -19,6 +19,16 @@
 _INVALID_DATABASE_ROWS = "Expected a list of database rows with string keys"
 
 
+def _is_object_mapping(value: object) -> TypeGuard[Mapping[object, object]]:
+    return isinstance(value, Mapping)
+
+
+def _is_object_sequence(
+    value: object,
+) -> TypeGuard[list[object] | tuple[object, ...]]:
+    return isinstance(value, (list, tuple))
+
+
 def _is_database_row(value: object) -> TypeGuard[dict[str, object]]:
     if not isinstance(value, dict):
         return False
@@ -54,12 +64,10 @@ def _snapshot_row(values: Mapping[str, JSONValue]) -> dict[str, JSONValue]:
 
 
 def _snapshot_filter_value(value: object) -> object:
-    if isinstance(value, Mapping):
-        mapping = cast("Mapping[object, object]", value)
-        return {key: _snapshot_filter_value(item) for key, item in mapping.items()}
-    if isinstance(value, (list, tuple)):
-        sequence = cast("list[object] | tuple[object, ...]", value)
-        return [_snapshot_filter_value(item) for item in sequence]
+    if _is_object_mapping(value):
+        return {key: _snapshot_filter_value(item) for key, item in value.items()}
+    if _is_object_sequence(value):
+        return [_snapshot_filter_value(item) for item in value]
     return value
 
 
@@ -86,10 +94,8 @@ class _OrderClause(TypedDict):
 class FilterBuilder:
     """Shared immutable filters for database operations."""
 
-    _filters: tuple[_FilterCondition, ...] = ()
-
-    def _with_filters(self, filters: tuple[_FilterCondition, ...]) -> Self:
-        del filters
+    def _append_filter(self, condition: _FilterCondition) -> Self:
+        del condition
         raise NotImplementedError
 
     def eq(self, column: str, value: object) -> Self:
@@ -208,7 +214,7 @@ def _filter(self, column: str, operator: str, value: object) -> Self:
             "operator": operator,
             "value": _snapshot_filter_value(value),
         }
-        return self._with_filters((*self._filters, condition))
+        return self._append_filter(condition)
 
 
 @dataclass(frozen=True, slots=True)
@@ -319,8 +325,8 @@ def offset(self, count: int) -> QueryBuilder:
         return replace(self, _offset=count)
 
     @override
-    def _with_filters(self, filters: tuple[_FilterCondition, ...]) -> QueryBuilder:
-        return replace(self, _filters=filters)
+    def _append_filter(self, condition: _FilterCondition) -> QueryBuilder:
+        return replace(self, _filters=(*self._filters, condition))
 
     def _request_body(self) -> dict[str, object]:
         body: dict[str, object] = {"table": self._table}
@@ -402,8 +408,8 @@ class UpdateBuilder(FilterBuilder):
     _filters: tuple[_FilterCondition, ...] = ()
 
     @override
-    def _with_filters(self, filters: tuple[_FilterCondition, ...]) -> UpdateBuilder:
-        return replace(self, _filters=filters)
+    def _append_filter(self, condition: _FilterCondition) -> UpdateBuilder:
+        return replace(self, _filters=(*self._filters, condition))
 
     def execute(self) -> list[dict[str, object]]:
         """Update matching rows and return them.
@@ -440,8 +446,8 @@ class DeleteBuilder(FilterBuilder):
     _filters: tuple[_FilterCondition, ...] = ()
 
     @override
-    def _with_filters(self, filters: tuple[_FilterCondition, ...]) -> DeleteBuilder:
-        return replace(self, _filters=filters)
+    def _append_filter(self, condition: _FilterCondition) -> DeleteBuilder:
+        return replace(self, _filters=(*self._filters, condition))
 
     def execute(self) -> list[dict[str, object]]:
         """Delete matching rows and return them.

tests/unit/test_database_snapshots.py

@@ -52,4 +52,21 @@ def handle(request: httpx.Request) -> httpx.Response:
 
 def test_filter_base_requires_a_concrete_builder() -> None:
     with pytest.raises(NotImplementedError):
-        _ = FilterBuilder()._with_filters(())
+        _ = FilterBuilder()._append_filter(
+            {"column": "id", "operator": "eq", "value": 1}
+        )
+
+
+@pytest.mark.parametrize("value", [True, False])
+def test_identity_filter_preserves_boolean_values(value: object) -> None:
+    requests: list[httpx.Request] = []
+
+    def handle(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        return rows_response()
+
+    query = make_client(handle).database("db").from_("items").is_("enabled", value)
+    assert query.execute() == [{"id": 1}]
+    assert json.loads(requests[0].content)["filters"] == [
+        {"column": "enabled", "operator": "is", "value": value}
+    ]