feat: caching introduced for categories endpoint

Author: raven-wing

goodmap/core_api.py

@@ -361,6 +361,22 @@ def get_categories():
 
         return jsonify({"categories": categories, "categories_help": proper_categories_help})
 
+    @core_api_blueprint.route("/categories-full", methods=["GET"])
+    @spec.validate()
+    def get_categories_full():
+        """Get all categories with their subcategory options in a single request.
+
+        Returns combined category data to reduce API calls for filter panel loading.
+        This endpoint eliminates the need for multiple sequential requests.
+        """
+        categories_data = database.get_category_data()
+        result = []
+        for key, options in categories_data["categories"].items():
+            result.append(
+                {"key": key, "name": gettext(key), "options": make_tuple_translation(options)}
+            )
+        return jsonify({"categories": result})
+
     @core_api_blueprint.route("/languages", methods=["GET"])
     @spec.validate()
     def get_languages():

goodmap/db.py

@@ -2,7 +2,7 @@
 import logging
 import os
 import tempfile
-from functools import partial
+from functools import lru_cache, partial
 from typing import Any
 
 from goodmap.core import get_queried_data
@@ -20,6 +20,52 @@
 #  it should be replaced with dynamic solution
 
 
+# ------------------------------------------------
+# Caching utilities for database operations
+# ------------------------------------------------
+
+
+@lru_cache(maxsize=32)
+def _cached_read_json_file(file_path: str) -> str:
+    """Read and cache a JSON file's raw content.
+
+    Uses lru_cache to avoid repeated disk I/O for frequently accessed files.
+    Returns raw string (not dict) because lru_cache requires hashable,
+    immutable return values to prevent cache corruption from mutations.
+
+    Args:
+        file_path: Absolute path to the JSON file.
+
+    Returns:
+        str: Raw file content. Caller must use json.loads() to parse.
+    """
+    with open(file_path, "r") as file:
+        return file.read()
+
+
+def _get_cached_json_data(file_path: str) -> dict[str, Any]:
+    """Get parsed JSON data from cache, reading from disk only on cache miss.
+
+    Args:
+        file_path: Absolute path to the JSON file.
+
+    Returns:
+        dict: Parsed JSON data. Note: caller should not mutate the result.
+    """
+    raw_data = _cached_read_json_file(file_path)
+    return json.loads(raw_data)
+
+
+def clear_cache():
+    """Clear all JSON file caches.
+
+    Must be called after any file modification to prevent stale reads.
+    Automatically invoked by json_file_atomic_dump().
+    """
+    _cached_read_json_file.cache_clear()
+    logger.debug("Database caches cleared")
+
+
 def __parse_pagination_params(query):
     """Extract and validate pagination parameters from query."""
     try:
@@ -68,6 +114,8 @@ def json_file_atomic_dump(data, file_path):
         temp_file.flush()
         os.fsync(temp_file.fileno())
     os.replace(temp_file.name, file_path)
+    # Clear cache after file write to ensure fresh data on next read
+    clear_cache()
 
 
 class PaginationHelper:
@@ -521,8 +569,9 @@ def json_db_get_categories(self):
 
 
 def json_file_db_get_categories(self):
-    with open(self.data_file_path, "r") as file:
-        return json.load(file)["map"]["categories"].keys()
+    """Retrieve category names from JSON file database (cached)."""
+    data = _get_cached_json_data(self.data_file_path)
+    return data["map"]["categories"].keys()
 
 
 def google_json_db_get_categories(self):
@@ -561,21 +610,29 @@ def json_db_get_category_data(self, category_type=None):
 
 
 def json_file_db_get_category_data(self, category_type=None):
-    with open(self.data_file_path, "r") as file:
-        data = json.load(file)["map"]
-        if category_type:
-            return {
-                "categories": {category_type: data["categories"].get(category_type, [])},
-                "categories_help": data.get("categories_help", []),
-                "categories_options_help": {
-                    category_type: data.get("categories_options_help", {}).get(category_type, [])
-                },
-            }
+    """Retrieve category data from JSON file database (cached).
+
+    Args:
+        category_type: If provided, return data for this category only.
+                       If None, return all categories.
+
+    Returns:
+        dict: Contains 'categories', 'categories_help', and 'categories_options_help'.
+    """
+    data = _get_cached_json_data(self.data_file_path)["map"]
+    if category_type:
         return {
-            "categories": data["categories"],
+            "categories": {category_type: data["categories"].get(category_type, [])},
             "categories_help": data.get("categories_help", []),
-            "categories_options_help": data.get("categories_options_help", {}),
+            "categories_options_help": {
+                category_type: data.get("categories_options_help", {}).get(category_type, [])
+            },
         }
+    return {
+        "categories": data["categories"],
+        "categories_help": data.get("categories_help", []),
+        "categories_options_help": data.get("categories_options_help", {}),
+    }
 
 
 def google_json_db_get_category_data(self, category_type=None):

goodmap/goodmap.py

@@ -77,7 +77,7 @@ def create_app_from_config(config: GoodmapConfig) -> platzky.Engine:
 
         # Use the extended db method directly (already bound by extend_db_with_goodmap_queries)
         try:
-            category_data = app.db.get_category_data()
+            category_data = app.db.get_category_data()  # type: ignore[attr-defined]
             categories = category_data.get("categories", {})
         except (KeyError, AttributeError):
             # Handle case where categories don't exist in the data
@@ -121,7 +121,7 @@ def index():
         """
         # Prepare location schema for frontend dynamic forms
         # Include full schema from Pydantic model for better type information
-        category_data = app.db.get_category_data()
+        category_data = app.db.get_category_data()  # type: ignore[attr-defined]
         categories = category_data.get("categories", {})
 
         # Get full JSON schema from Pydantic model

tests/unit_tests/test_core_api.py

@@ -141,6 +141,73 @@ def test_category_data_endpoint_with_none_categories_options_help():
     assert data["categories_options_help"] == []
 
 
+# --- Categories-full endpoint tests ---
+
+
+@mock.patch("goodmap.core_api.gettext", fake_translation)
+def test_categories_full_endpoint_returns_proper_structure(test_app):
+    response = test_app.get("/api/categories-full")
+    assert response.status_code == 200
+    data = response.json
+    assert "categories" in data
+    assert isinstance(data["categories"], list)
+
+
+@mock.patch("goodmap.core_api.gettext", fake_translation)
+def test_categories_full_endpoint_returns_categories_with_required_fields(test_app):
+    response = test_app.get("/api/categories-full")
+    assert response.status_code == 200
+    data = response.json
+    assert len(data["categories"]) > 0
+    category = data["categories"][0]
+    assert "key" in category
+    assert "name" in category
+    assert "options" in category
+
+
+@mock.patch("goodmap.core_api.gettext", fake_translation)
+def test_categories_full_endpoint_returns_translated_name(test_app):
+    response = test_app.get("/api/categories-full")
+    assert response.status_code == 200
+    data = response.json
+    category = data["categories"][0]
+    assert category["key"] == "test-category"
+    assert category["name"] == "test-category-translated"
+
+
+@mock.patch("goodmap.core_api.gettext", fake_translation)
+def test_categories_full_endpoint_returns_translated_options(test_app):
+    response = test_app.get("/api/categories-full")
+    assert response.status_code == 200
+    data = response.json
+    category = data["categories"][0]
+    # Options should be translated tuples (key, translated_name)
+    assert isinstance(category["options"], list)
+    assert len(category["options"]) == 2
+    assert category["options"][0] == ["test", "test-translated"]
+    assert category["options"][1] == ["test2", "test2-translated"]
+
+
+@mock.patch("goodmap.core_api.gettext", fake_translation)
+def test_categories_full_endpoint_with_multiple_categories():
+    test_app = create_test_app(
+        db_overrides={
+            "categories": {
+                "category1": ["opt1", "opt2"],
+                "category2": ["opt3"],
+            }
+        }
+    )
+    response = test_app.get("/api/categories-full")
+    assert response.status_code == 200
+    data = response.json
+    assert data is not None
+    assert len(data["categories"]) == 2
+    keys = [cat["key"] for cat in data["categories"]]
+    assert "category1" in keys
+    assert "category2" in keys
+
+
 # --- Locations endpoint tests ---