use_query and use_mutation

docs/features/hooks.md

@@ -2,6 +2,55 @@
 
     Check out the [IDOM Core docs](https://idom-docs.herokuapp.com/docs/reference/hooks-api.html?highlight=hooks) on hooks!
 
+## Use Query and Use Mutation
+
+<!-- TODO: Add description -->
+
+```python
+from example_project.my_app.models import TodoItem
+from idom import component, html
+from django_idom.hooks import use_query, use_mutation
+
+
+def get_items():
+    return TodoItem.objects.all()
+
+def add_item(text: str):
+    TodoItem(text=text).save()
+
+
+@component
+def todo_list():
+    items_query = use_query(get_items)
+    add_item_mutation = use_mutation(add_item, refetch=get_items)
+    item_draft, set_item_draft = use_state("")
+
+    if items_query.loading:
+        items_view = html.h2("Loading...")
+    elif items_query.error:
+        items_view = html.h2(f"Error when loading: {items.error}")
+    else:
+        items_view = html.ul(html.li(item, key=item) for item in items_query.data)
+
+    if add_item_mutation.loading:
+        add_item_status = html.h2("Adding...")
+    elif add_item_mutation.error:
+        add_item_status = html.h2(f"Error when adding: {add_item_mutation.error}")
+    else:
+        add_item_status = ""
+
+    def handle_add_item(event):
+        set_item_draft("")
+        add_item_mutation.execute(text=item_draft)
+
+    return html.div(
+        html.label("Add an item:")
+        html.input({"type": "text", "onClick": handle_add_item})
+        add_item_status,
+        items_view,
+    )
+```
+
 ## Use Websocket
 
 You can fetch the Django Channels websocket at any time by using `use_websocket`.

requirements/pkg-deps.txt

@@ -1,3 +1,4 @@
 channels >=3.0.0
 idom >=0.39.0, <0.40.0
 aiofile >=3.0
+typing_extensions

src/django_idom/hooks.py

@@ -1,9 +1,19 @@
-from typing import Dict, Type, Union
+from __future__ import annotations
 
+from dataclasses import dataclass
+from threading import Thread
+from types import FunctionType
+from typing import Any, Callable, DefaultDict, Generic, Sequence, Type, TypeVar, Union
+
+from django.db.models.base import Model
+from django.db.models.query import QuerySet
+from idom import use_callback
 from idom.backend.types import Location
-from idom.core.hooks import Context, create_context, use_context
+from idom.core.hooks import Context, create_context, use_context, use_effect, use_state
+from typing_extensions import ParamSpec
 
 from django_idom.types import IdomWebsocket
+from django_idom.utils import UNDEFINED
 
 
 WebsocketContext: Type[Context[Union[IdomWebsocket, None]]] = create_context(
@@ -19,7 +29,7 @@ def use_location() -> Location:
     return Location(scope["path"], f"?{search}" if search else "")
 
 
-def use_scope() -> Dict:
+def use_scope() -> dict[str, Any]:
     """Get the current ASGI scope dictionary"""
     return use_websocket().scope
 
@@ -30,3 +40,145 @@ def use_websocket() -> IdomWebsocket:
     if websocket is None:
         raise RuntimeError("No websocket. Are you running with a Django server?")
     return websocket
+
+
+_REFETCH_CALLBACKS: DefaultDict[FunctionType, set[Callable[[], None]]] = DefaultDict(
+    set
+)
+
+
+_Data = TypeVar("_Data")
+_Params = ParamSpec("_Params")
+
+
+def use_query(
+    query: Callable[_Params, _Data],
+    *args: _Params.args,
+    fetch_deferred_fields: bool = True,
+    **kwargs: _Params.kwargs,
+) -> Query[_Data]:
+    given_query = query
+    query, _ = use_state(given_query)
+    if given_query is not query:
+        raise ValueError(f"Query function changed from {query} to {given_query}.")
+
+    data, set_data = use_state(UNDEFINED)
+    loading, set_loading = use_state(True)
+    error, set_error = use_state(None)
+
+    @use_callback
+    def refetch() -> None:
+        set_data(UNDEFINED)
+        set_loading(True)
+        set_error(None)
+
+    @use_effect(dependencies=[])
+    def add_refetch_callback():
+        # By tracking callbacks globally, any usage of the query function will be re-run
+        # if the user has told a mutation to refetch it.
+        _REFETCH_CALLBACKS[query].add(refetch)
+        return lambda: _REFETCH_CALLBACKS[query].remove(refetch)
+
+    @use_effect(dependencies=None)
+    def execute_query():
+        if data is not UNDEFINED:
+            return
+
+        def thread_target():
+            try:
+                query_result = query(*args, **kwargs)
+            except Exception as e:
+                set_data(UNDEFINED)
+                set_loading(False)
+                set_error(e)
+                return
+
+            if isinstance(query_result, QuerySet):
+                if fetch_deferred_fields:
+                    for model in query_result:
+                        _fetch_deferred_fields(model)
+                else:
+                    # still force query set to execute
+                    for _ in query_result:
+                        pass
+            elif isinstance(query_result, Model):
+                if fetch_deferred_fields:
+                    _fetch_deferred_fields(query_result)
+            elif fetch_deferred_fields:
+                raise ValueError(
+                    f"Expected {query} to return Model or Query because "
+                    f"{fetch_deferred_fields=}, got {query_result!r}"
+                )
+
+            set_data(query_result)
+            set_loading(False)
+            set_error(None)
+
+        # We need to run this in a thread so we don't prevent rendering when loading.
+        # We also can't do this async since Django's ORM doesn't support this yet.
+        Thread(target=thread_target, daemon=True).start()
+
+    return Query(data, loading, error, refetch)
+
+
+@dataclass
+class Query(Generic[_Data]):
+    data: _Data
+    loading: bool
+    error: Exception | None
+    refetch: Callable[[], None]
+
+
+def use_mutation(
+    mutate: Callable[_Params, None],
+    refetch: Callable[..., Any] | Sequence[Callable[..., Any]],
+) -> Mutation[_Params]:
+    loading, set_loading = use_state(True)
+    error, set_error = use_state(None)
+
+    @use_callback
+    def call(*args: _Params.args, **kwargs: _Params.kwargs) -> None:
+        set_loading(True)
+
+        def thread_target():
+            try:
+                mutate(*args, **kwargs)
+            except Exception as e:
+                set_loading(False)
+                set_error(e)
+            else:
+                set_loading(False)
+                set_error(None)
+                for query in (refetch,) if isinstance(refetch, Query) else refetch:
+                    refetch_callback = _REFETCH_CALLBACKS.get(query)
+                    if refetch_callback is not None:
+                        refetch_callback()
+
+        # We need to run this in a thread so we don't prevent rendering when loading.
+        # We also can't do this async since Django's ORM doesn't support this yet.
+        Thread(target=thread_target, daemon=True).start()
+
+    @use_callback
+    def reset() -> None:
+        set_loading(False)
+        set_error(None)
+
+    return Query(call, loading, error, reset)
+
+
+@dataclass
+class Mutation(Generic[_Params]):
+    execute: Callable[_Params, None]
+    loading: bool
+    error: Exception | None
+    reset: Callable[[], None]
+
+
+_Model = TypeVar("_Model", bound=Model)
+
+
+def _fetch_deferred_fields(model: _Model) -> _Model:
+    for field in model.get_deferred_fields():
+        value = getattr(model, field)
+        if isinstance(value, Model):
+            _fetch_deferred_fields(value)

src/django_idom/utils.py

@@ -133,3 +133,12 @@ def _register_components(self, components: Set) -> None:
                     "\033[0m",
                     component,
                 )
+
+
+class _Undefined:
+    def __repr__(self):
+        return "UNDEFINED"
+
+
+UNDEFINED = _Undefined()
+"""Sentinel for undefined values"""