Typesense Backend [FC-0091]

requirements/base.in

@@ -16,3 +16,4 @@ elasticsearch>=7.8.0,<8.0.0
 edx-toggles
 event-tracking
 meilisearch
+typesense

requirements/base.txt

@@ -127,6 +127,7 @@ pyyaml==6.0.3
     # via code-annotations
 requests==2.32.5
     # via meilisearch
+    #   typesense
 six==1.17.0
     # via
     #   edx-ccx-keys
@@ -141,6 +142,8 @@ stevedore==5.6.0
     #   edx-opaque-keys
 text-unidecode==1.3
     # via python-slugify
+typesense==1.1.1
+    # via -r requirements/base.in
 typing-extensions==4.15.0
     # via
     #   edx-opaque-keys

requirements/dev.txt

@@ -390,6 +390,7 @@ requests==2.32.5
     #   -r requirements/quality.txt
     #   -r requirements/testing.txt
     #   meilisearch
+    #   typesense
 six==1.17.0
     # via
     #   -r requirements/quality.txt
@@ -421,6 +422,10 @@ tomlkit==0.13.3
     #   pylint
 tox==4.32.0
     # via -r requirements/ci.txt
+typesense==1.1.1
+    # via
+    #   -r requirements/quality.txt
+    #   -r requirements/testing.txt
 typing-extensions==4.15.0
     # via
     #   -r requirements/quality.txt

requirements/quality.txt

@@ -268,6 +268,7 @@ requests==2.32.5
     # via
     #   -r requirements/testing.txt
     #   meilisearch
+    #   typesense
 six==1.17.0
     # via
     #   -r requirements/testing.txt
@@ -291,6 +292,8 @@ text-unidecode==1.3
     #   python-slugify
 tomlkit==0.13.3
     # via pylint
+typesense==1.1.1
+    # via -r requirements/testing.txt
 typing-extensions==4.15.0
     # via
     #   -r requirements/testing.txt

requirements/testing.txt

@@ -224,6 +224,7 @@ requests==2.32.5
     # via
     #   -r requirements/base.txt
     #   meilisearch
+    #   typesense
 six==1.17.0
     # via
     #   -r requirements/base.txt
@@ -244,6 +245,8 @@ text-unidecode==1.3
     # via
     #   -r requirements/base.txt
     #   python-slugify
+typesense==1.1.1
+    # via -r requirements/base.txt
 typing-extensions==4.15.0
     # via
     #   -r requirements/base.txt

search/tests/test_utils.py

@@ -1,9 +1,13 @@
-"""Tests for utility functions in search.utils module."""
-
+"""
+Test for the utility functions shared by multiple search engines.
+"""
 import unittest
+
 from ddt import ddt, data, unpack
+import django.test
+from django.utils import timezone
 
-from search.utils import normalize_bool
+from search.utils import convert_doc_datatypes, normalize_bool, restore_doc_datatypes
 
 
 @ddt
@@ -44,3 +48,107 @@ def test_invalid_string_values(self, value):
     @unpack
     def test_other_types(self, value, expected):
         assert normalize_bool(value) is expected
+
+
+class EngineUtilsTests(django.test.TestCase):
+    """
+    Utils tests.
+    """
+
+    def test_convert_empty_document(self):
+        assert not convert_doc_datatypes({})
+
+    def test_convert_document_recursive(self):
+        """
+        Test converting a document to Meilisearch/Typesense compatible format
+        """
+        now = timezone.datetime(2025, 8, 25)
+        document = {
+            "timestamp": now,
+            "dict_field": {
+                "inner_value": timezone.datetime(2024, 1, 1),
+            },
+        }
+        processed = convert_doc_datatypes(document)
+        assert {
+            "timestamp": 1756080000.0,
+            "timestamp__utcoffset": 0,
+            "dict_field": {
+                "inner_value": 1704067200.0,
+                "inner_value__utcoffset": 0,
+            }
+        } == processed
+
+    def test_convert_datetime_with_tz(self):
+        """
+        Test converting a document to Meilisearch/Typesense compatible format,
+        including non-UTC datetimes.
+        """
+        # With timezone
+        document = {
+            "id": "1",
+            "dt": timezone.datetime(
+                2024,
+                1,
+                1,
+                tzinfo=timezone.get_fixed_timezone(timezone.timedelta(seconds=3600)),
+            ),
+        }
+        processed = convert_doc_datatypes(document)
+        assert 1704063600.0 == processed["dt"]
+        assert 3600 == processed["dt__utcoffset"]
+        # reverse serialisation
+        reverse = restore_doc_datatypes(processed)
+        assert document == reverse
+
+    def test_convert_document_with_null(self):
+        """
+        Test converting a document to Meilisearch/Typesense compatible format,
+        including NULL values
+        """
+        document = {
+            "foo": "bar",
+            "count": 17,
+            "null_value": None,
+            "dict_value": {
+                "null_value": None,
+                "bar": "foo",
+            },
+        }
+        processed = convert_doc_datatypes(document)
+        assert {
+            "foo": "bar",
+            "count": 17,
+            # null_value removed
+            "dict_value": {
+                # null_value removed
+                "bar": "foo",
+            },
+        } == processed
+
+    def test_convert_document_with_null_separate(self):
+        """
+        Test converting a document to Typesense compatible format, marking NULL
+        values using a separate field as recommended at
+        https://typesense.org/docs/guide/tips-for-searching-common-types-of-data.html#searching-for-null-or-empty-values
+        """
+        document = {
+            "foo": "bar",
+            "count": 17,
+            "null_value": None,
+            "dict_value": {
+                "null_value": None,
+                "bar": "foo",
+            },
+        }
+        processed = convert_doc_datatypes(document, record_nulls=True)
+        assert {
+            "foo": "bar",
+            "count": 17,
+            "null_value__is_null": True,
+            "dict_value": {
+                "null_value__is_null": True,
+                "bar": "foo",
+            },
+        } == processed
+        assert document == restore_doc_datatypes(processed)