feat: derivatives basis & calendar-spread indicators (part 3 of 3) (#128)

* feat(derivatives): TermStructureBasis indicator (core)

* feat(derivatives): CalendarSpread indicator (core)

* feat(derivatives): Python, Node and WASM bindings for basis & calendar-spread indicators

* test(derivatives): Python and Node tests for basis & calendar-spread indicators

* docs(derivatives): README row + counter 242->244, CHANGELOG part 3; fuzz basis indicators

bindings/python/tests/test_input_validation.py

@@ -268,3 +268,13 @@ def test_oi_price_divergence_zero_window_raises():
 def test_oi_weighted_non_positive_mark_raises():
     with pytest.raises(ValueError):
         ta.OIWeighted().update(0.0, 100.0)
+
+
+def test_term_structure_basis_non_positive_index_raises():
+    with pytest.raises(ValueError):
+        ta.TermStructureBasis().update(100.0, 0.0)
+
+
+def test_calendar_spread_non_positive_mark_raises():
+    with pytest.raises(ValueError):
+        ta.CalendarSpread().update(100.0, 0.0)

bindings/python/tests/test_known_values.py

@@ -1013,3 +1013,16 @@ def test_liquidation_features_reference_value():
     # 30 long vs 10 short: (long, short, net, total, imbalance).
     out = ta.LiquidationFeatures().update(30.0, 10.0)
     assert out == pytest.approx((30.0, 10.0, 20.0, 40.0, 0.5))
+
+
+def test_term_structure_basis_reference_value():
+    # futures 102 vs index 100 -> 0.02 (contango).
+    assert ta.TermStructureBasis().update(102.0, 100.0) == pytest.approx(0.02)
+    # Backwardation reads negative.
+    assert ta.TermStructureBasis().update(98.0, 100.0) == pytest.approx(-0.02)
+
+
+def test_calendar_spread_reference_value():
+    # futures 101 vs perpetual mark 100 -> 0.01.
+    assert ta.CalendarSpread().update(101.0, 100.0) == pytest.approx(0.01)
+    assert ta.CalendarSpread().update(99.0, 100.0) == pytest.approx(-0.01)

bindings/python/tests/test_new_indicators.py

@@ -2047,3 +2047,29 @@ def test_liquidation_features_streaming_equals_batch():
     for i in range(n):
         row = streamer.update(long_liq[i], short_liq[i])
         assert tuple(batch[i]) == pytest.approx(row)
+
+
+def test_basis_indicators_streaming_equals_batch():
+    n = 40
+    index = np.array([100.0 + math.sin(i * 0.2) for i in range(n)], dtype=np.float64)
+    mark = np.array([index[i] + 0.05 * math.cos(i * 0.3) for i in range(n)], dtype=np.float64)
+    futures = np.array(
+        [index[i] + 0.5 + 0.1 * math.sin(i * 0.25) for i in range(n)], dtype=np.float64
+    )
+
+    # TermStructureBasis; update(futures_price, index_price).
+    batch = ta.TermStructureBasis().batch(futures, index)
+    streamer = ta.TermStructureBasis()
+    streamed = np.array(
+        [streamer.update(futures[i], index[i]) for i in range(n)], dtype=np.float64
+    )
+    assert batch.shape == (n,)
+    assert _eq_nan(batch, streamed)
+
+    # CalendarSpread; update(futures_price, mark_price).
+    batch = ta.CalendarSpread().batch(futures, mark)
+    streamer = ta.CalendarSpread()
+    streamed = np.array(
+        [streamer.update(futures[i], mark[i]) for i in range(n)], dtype=np.float64
+    )
+    assert _eq_nan(batch, streamed)