Provide app.storage.client as a location to store volatile data which only matters for the current connection

nicegui/client.py

@@ -20,6 +20,7 @@
 from .favicon import get_favicon_url
 from .javascript_request import JavaScriptRequest
 from .logging import log
+from .observables import ObservableDict
 from .outbox import Outbox
 from .version import __version__
 
@@ -73,6 +74,7 @@ def __init__(self, page: page, *, shared: bool = False) -> None:
         self._body_html = ''
 
         self.page = page
+        self.state = ObservableDict()
 
         self.connect_handlers: List[Union[Callable[..., Any], Awaitable]] = []
         self.disconnect_handlers: List[Union[Callable[..., Any], Awaitable]] = []

nicegui/storage.py

@@ -16,7 +16,9 @@
 from starlette.responses import Response
 
 from . import background_tasks, context, core, json, observables
+from .context import get_slot_stack
 from .logging import log
+from .observables import ObservableDict
 
 request_contextvar: contextvars.ContextVar[Optional[Request]] = contextvars.ContextVar('request_var', default=None)
 
@@ -156,6 +158,18 @@ def general(self) -> PersistentDict:
         """General storage shared between all users that is persisted on the server (where NiceGUI is executed)."""
         return self._general
 
+    @property
+    def client(self) -> ObservableDict:
+        """A volatile storage that is only kept during the current connection to the client.
+
+        Like `app.storage.tab` data is unique per browser tab but is even more volatile as it is already discarded
+        when the connection to the client is lost through a page reload or a navigation."""
+        if self._is_in_auto_index_context():
+            raise RuntimeError('app.storage.client can only be used with page builder functions '
+                               '(https://nicegui.io/documentation/page)')
+        client = context.get_client()
+        return client.state
+
     @property
     def tab(self) -> observables.ObservableDict:
         """A volatile storage that is only kept during the current tab session."""
@@ -183,6 +197,8 @@ def clear(self) -> None:
         """Clears all storage."""
         self._general.clear()
         self._users.clear()
+        if not self._is_in_auto_index_context() and get_slot_stack():
+            self.client.clear()
         self._tabs.clear()
         for filepath in self.path.glob('storage-*.json'):
             filepath.unlink()

tests/test_client_state.py

@@ -0,0 +1,40 @@
+import pytest
+
+from nicegui import ui, app, context
+from nicegui.testing import Screen
+
+
+def test_session_state(screen: Screen):
+    def increment():
+        app.storage.client['counter'] = app.storage.client['counter'] + 1
+
+    @ui.page('/')
+    async def page():
+        app.storage.client['counter'] = 123
+        ui.button('Increment').on_click(increment)
+        ui.label().bind_text(app.storage.client, 'counter')
+        ui.button('Increment').on_click(increment)
+        ui.label().bind_text(app.storage.client, 'counter')
+
+    screen.open('/')
+    screen.should_contain('123')
+    screen.click('Increment')
+    screen.wait_for('124')
+    screen.switch_to(1)
+    screen.open('/')
+    screen.should_contain('123')
+    screen.switch_to(0)
+    screen.should_contain('124')
+
+
+def test_clear(screen: Screen):
+    with pytest.raises(RuntimeError):  # no context (auto index)
+        app.storage.client.clear()
+
+    @ui.page('/')
+    async def page():
+        app.storage.client['counter'] = 123
+        app.storage.client.clear()
+        assert 'counter' not in app.storage.client
+
+    screen.open('/')

website/documentation/content/storage_documentation.py

@@ -14,13 +14,20 @@
 
 @doc.demo('Storage', '''
     NiceGUI offers a straightforward mechanism for data persistence within your application. 
-    It features four built-in storage types:
+    It features five built-in storage types:
 
     - `app.storage.tab`:
         Stored server-side in memory, this dictionary is unique to each tab session and can hold arbitrary objects.
         Data will be lost when restarting the server until <https://github.com/zauberzeug/nicegui/discussions/2841> is implemented.
         This storage is only available within [page builder functions](/documentation/page) 
         and requires an established connection, obtainable via [`await client.connected()`](/documentation/page#wait_for_client_connection).
+    - `app.storage.client`:
+        Also stored server-side in memory, this dictionary is unique to each client connection and can hold arbitrary objects.
+        Data will be discarded when the page is reloaded or the user navigates to another page.
+        Unlike data stored in `app.storage.tab` which can be persisted on the server even for days, 
+        `app.storage.client` helps caching resource-hungry objects such as a streaming or database connection you need to keep alive 
+        for dynamic site updates but would like to discard as soon as the user leaves the page or closes the browser. 
+        This storage is only available within [page builder functions](/documentation/page).
     - `app.storage.user`:
         Stored server-side, each dictionary is associated with a unique identifier held in a browser session cookie.
         Unique to each user, this storage is accessible across all their browser tabs.
@@ -107,3 +114,29 @@ def tab_storage():
     with ui.column():  # HIDE
         app.storage.tab['count'] = app.storage.tab.get('count', 0) + 1
         ui.label(f'Tab reloaded {app.storage.tab["count"]} times')
+        ui.button("Reload page", on_click=lambda: ui.navigate.reload())
+
+
+@doc.demo('Short-term memory', '''
+          The goal of `app.storage.client` is to store data only for the duration of the current page visit.
+          In difference to data stored in `app.storage.tab` 
+          - which is persisted between page changes and even browser restarts as long as the tab is kept open - 
+          the data in `app.storage.client` will be discarded if the user closes the browser, reloads the page or navigates to another page.
+          This is beneficial for resource hungry or intentionally very short lived data such as a database connection 
+          which should be closed as soon as the user leaves the page, sensitive data or 
+          if you on purpose want to return a page with the default settings every time the user reloads the page 
+          while keeping the data alive during in-page navigation or when updating elements on the site in intervals such as a live feed.
+          ''')
+def short_term_memory():
+    from nicegui import app
+
+    # @ui.page('/')
+    # async def index(client):
+    with ui.column():  # HIDE
+        cache = app.storage.client
+        cache['counter'] = 0
+        ui.label().bind_text_from(cache, 'counter',
+                                  backward=lambda n: f'Content updated {n} times')
+        ui.button('Update content',
+                  on_click=lambda: cache.update({"counter": cache["counter"] + 1}))
+        ui.button("Reload page", on_click=lambda: ui.navigate.reload())