From 1e17382169894a9167097a7a01ff0ffd03b999cc Mon Sep 17 00:00:00 2001
From: Alex Gaetano Padula <me@alexpadula.com>
Date: Fri, 20 Feb 2026 10:16:27 -0500
Subject: [PATCH] addition of range cost, updated rockspec

---
 src/tidesdb.lua                               | 10 ++++-
 tests/test_tidesdb.lua                        | 39 +++++++++++++++++++
 ...5.2-1.rockspec => tidesdb-0.5.3-1.rockspec |  4 +-
 3 files changed, 50 insertions(+), 3 deletions(-)
 rename tidesdb-0.5.2-1.rockspec => tidesdb-0.5.3-1.rockspec (95%)

diff --git a/src/tidesdb.lua b/src/tidesdb.lua
index 55e5735..9768f1f 100644
--- a/src/tidesdb.lua
+++ b/src/tidesdb.lua
@@ -159,6 +159,7 @@ ffi.cdef[[
     int tidesdb_get_stats(void* cf, tidesdb_stats_t** stats);
     void tidesdb_free_stats(tidesdb_stats_t* stats);
     int tidesdb_get_cache_stats(void* db, tidesdb_cache_stats_t* stats);
+    int tidesdb_range_cost(void* cf, const uint8_t* key_a, size_t key_a_size, const uint8_t* key_b, size_t key_b_size, double* cost);
 
     // Backup operations
     int tidesdb_backup(void* db, const char* dir);
@@ -552,6 +553,13 @@ function ColumnFamily:update_runtime_config(config, persist_to_disk)
     check_result(result, "failed to update runtime config")
 end
 
+function ColumnFamily:range_cost(key_a, key_b)
+    local cost = ffi.new("double[1]")
+    local result = lib.tidesdb_range_cost(self._cf, key_a, #key_a, key_b, #key_b, cost)
+    check_result(result, "failed to estimate range cost")
+    return cost[0]
+end
+
 function ColumnFamily:get_stats()
     local stats_ptr = ffi.new("tidesdb_stats_t*[1]")
     local result = lib.tidesdb_get_stats(self._cf, stats_ptr)
@@ -1053,6 +1061,6 @@ function tidesdb.save_config_to_ini(ini_file, section_name, config)
 end
 
 -- Version
-tidesdb._VERSION = "0.5.2"
+tidesdb._VERSION = "0.5.3"
 
 return tidesdb
diff --git a/tests/test_tidesdb.lua b/tests/test_tidesdb.lua
index 8880885..fad1aff 100644
--- a/tests/test_tidesdb.lua
+++ b/tests/test_tidesdb.lua
@@ -637,6 +637,45 @@ function tests.test_transaction_reset()
     print("PASS: test_transaction_reset")
 end
 
+function tests.test_range_cost()
+    local path = "./test_db_range_cost"
+    cleanup_db(path)
+    
+    local db = tidesdb.TidesDB.open(path)
+    db:create_column_family("test_cf")
+    local cf = db:get_column_family("test_cf")
+    
+    -- Insert some data
+    local txn = db:begin_txn()
+    for i = 1, 20 do
+        txn:put(cf, string.format("key:%04d", i), string.format("value:%04d", i))
+    end
+    txn:commit()
+    txn:free()
+    
+    -- Estimate range cost
+    local cost = cf:range_cost("key:0001", "key:0020")
+    assert_true(cost ~= nil, "range cost should not be nil")
+    assert_true(type(cost) == "number", "range cost should be a number")
+    assert_true(cost >= 0, "range cost should be >= 0")
+    
+    -- Compare two ranges (wider range should cost >= narrower range)
+    local cost_wide = cf:range_cost("key:0001", "key:0020")
+    local cost_narrow = cf:range_cost("key:0005", "key:0010")
+    assert_true(cost_wide >= 0, "wide range cost should be >= 0")
+    assert_true(cost_narrow >= 0, "narrow range cost should be >= 0")
+    
+    -- Key order should not matter
+    local cost_ab = cf:range_cost("key:0001", "key:0020")
+    local cost_ba = cf:range_cost("key:0020", "key:0001")
+    assert_eq(cost_ab, cost_ba, "range cost should be the same regardless of key order")
+    
+    db:drop_column_family("test_cf")
+    db:close()
+    cleanup_db(path)
+    print("PASS: test_range_cost")
+end
+
 -- Run all tests
 local function run_tests()
     print("Running TidesDB Lua tests...")
diff --git a/tidesdb-0.5.2-1.rockspec b/tidesdb-0.5.3-1.rockspec
similarity index 95%
rename from tidesdb-0.5.2-1.rockspec
rename to tidesdb-0.5.3-1.rockspec
index 9f1ac0b..f8f0d59 100644
--- a/tidesdb-0.5.2-1.rockspec
+++ b/tidesdb-0.5.3-1.rockspec
@@ -1,8 +1,8 @@
 package = "tidesdb"
-version = "0.5.2-1"
+version = "0.5.3-1"
 source = {
    url = "git://github.com/tidesdb/tidesdb-lua.git",
-   tag = "v0.5.2"
+   tag = "v0.5.3"
 }
 description = {
    summary = "Official Lua bindings for TidesDB - A high-performance embedded key-value storage engine",