mudis-ql 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8ca84afb158da1ef68705edf7990481b4248356318f76cb591ae6a640f6a3fd
-  data.tar.gz: 0c50f8055c99f60448003e67812d8b5b0ec9c630f7a4f981fddee572678354be
+  metadata.gz: ca08d464b1ccfec7dcca637fa7fcf3e80e59fc5175ad1875ae785a6e6e204f9a
+  data.tar.gz: a00f60cf704c7b7b7df56570c2addbb926beb31599c411047d209dea47d3b4f5
 SHA512:
-  metadata.gz: aa080b7e1efdd7ab898550b1261e9af054c3f40848285b1a77a5f9f56f15cb38790eabf1be32e425e35ba5058ee49a302e714ebe677ed2824205b36d55497db2
-  data.tar.gz: '084565dea25c30c6e206238e61d5b9e184be59fef8e84135ec5c5a9eb726876c141b6308d1c09ce1e23b240fc839dd2def97eea3123a578d0bcd757fe30db63e'
+  metadata.gz: 934c5dc7d6bfd8fd3dd71dc875a0cc967b33c618cc1ca2b47602462ef31db0d09dc40d8a6d67e93cd3472a2d78cc2a9d52aa583b620c6d95e4ca2278b5b9ab2f
+  data.tar.gz: bb29da619a4be61e0090955cab91ae96cdfd0824a65b3becce4694ae23aa87c37b00ea873f2a4cc897f3f02851b403b24c748fc861a7544566b8fc29a75dc9d3

data/README.md

@@ -7,7 +7,7 @@ A simple query DSL for [mudis](https://github.com/kiebor81/mudis) cache. Mudis-Q
 
 ## Why Mudis-QL?
 
-**Mudis** is an excellent in-memory cache, but it only supports key-value retrieval. From the mudis documentation:
+**Mudis** has been a great in-memory cache for most of my needs, but it was only ever designed to support simple key-value retrieval. From the documentation:
 
 > "No SQL or equivalent query interface for cached data. Data is per Key retrieval only."
 
@@ -18,7 +18,7 @@ A simple query DSL for [mudis](https://github.com/kiebor81/mudis) cache. Mudis-Q
 - Count and check existence
 - Pluck specific fields
 
-All while maintaining mudis's speed, thread-safety, and in-memory efficiency.
+The goal is to retain Mudis's speed, thread-safety, and in-memory efficiency, but provide an opt-in gem fro advanced retrieval options if needed.
 
 ### Best Practice: Use Namespaces
 
@@ -42,8 +42,8 @@ Namespaces provide logical separation and enable Mudis-QL to retrieve all keys i
 flowchart TD
     Start([User Code]) --> Entry{Entry Point}
     
-    Entry -->|mudis-ql.from| CreateScope[Create Scope Instance]
-    Entry -->|mudis-ql.metrics| CreateMetrics[Create MetricsScope]
+    Entry -->|MudisQL.from| CreateScope[Create Scope Instance]
+    Entry -->|MudisQL.metrics| CreateMetrics[Create MetricsScope]
     
     CreateScope --> InitStore[Initialize Store with namespace]
     InitStore --> Scope[Scope Object]
@@ -126,7 +126,7 @@ $ gem install mudis-ql
 
 ## Requirements
 
-- Ruby >= 2.7.0
+- Ruby >= 3.0.0
 - mudis gem
 
 ## Usage
@@ -155,16 +155,16 @@ Mudis.write('user3', { name: 'Charlie', age: 35, status: 'inactive' }, namespace
 
 ```ruby
 # Get all users from a namespace
-users = mudis-ql.from('users').all
+users = MudisQL.from('users').all
 # => [{"name"=>"Alice", "age"=>30, "status"=>"active", "_key"=>"user1"}, ...]
 
 # Filter by exact match
-active_users = mudis-ql.from('users')
+active_users = MudisQL.from('users')
   .where(status: 'active')
   .all
 
 # Chain multiple conditions
-result = mudis-ql.from('users')
+result = MudisQL.from('users')
   .where(status: 'active')
   .where(age: ->(v) { v >= 25 })
   .all
@@ -174,17 +174,17 @@ result = mudis-ql.from('users')
 
 ```ruby
 # Use proc for custom conditions
-adults = mudis-ql.from('users')
+adults = MudisQL.from('users')
   .where(age: ->(age) { age >= 18 })
   .all
 
 # Use regex for pattern matching
-a_names = mudis-ql.from('users')
+a_names = MudisQL.from('users')
   .where(name: /^A/i)
   .all
 
 # Use ranges
-young_adults = mudis-ql.from('users')
+young_adults = MudisQL.from('users')
   .where(age: 18..25)
   .all
 ```
@@ -193,23 +193,23 @@ young_adults = mudis-ql.from('users')
 
 ```ruby
 # Order by field (ascending by default)
-sorted_users = mudis-ql.from('users')
+sorted_users = MudisQL.from('users')
   .order(:age)
   .all
 
 # Order descending
-sorted_desc = mudis-ql.from('users')
+sorted_desc = MudisQL.from('users')
   .order(:age, :desc)
   .all
 
 # Limit results
-top_5 = mudis-ql.from('users')
+top_5 = MudisQL.from('users')
   .order(:age, :desc)
   .limit(5)
   .all
 
 # Pagination with offset
-page_2 = mudis-ql.from('users')
+page_2 = MudisQL.from('users')
   .order(:name)
   .limit(10)
   .offset(10)
@@ -220,30 +220,30 @@ page_2 = mudis-ql.from('users')
 
 ```ruby
 # Get first matching record
-first_active = mudis-ql.from('users')
+first_active = MudisQL.from('users')
   .where(status: 'active')
   .first
 
 # Get last matching record
-last_user = mudis-ql.from('users')
+last_user = MudisQL.from('users')
   .order(:age)
   .last
 
 # Count matching records
-count = mudis-ql.from('users')
+count = MudisQL.from('users')
   .where(status: 'active')
   .count
 
 # Check if any records match
-has_inactive = mudis-ql.from('users')
+has_inactive = MudisQL.from('users')
   .where(status: 'inactive')
   .exists?
 
 # Pluck specific fields
-names = mudis-ql.from('users').pluck(:name)
+names = MudisQL.from('users').pluck(:name)
 # => ["Alice", "Bob", "Charlie"]
 
-name_age_pairs = mudis-ql.from('users').pluck(:name, :age)
+name_age_pairs = MudisQL.from('users').pluck(:name, :age)
 # => [["Alice", 30], ["Bob", 25], ["Charlie", 35]]
 ```
 
@@ -251,7 +251,7 @@ name_age_pairs = mudis-ql.from('users').pluck(:name, :age)
 
 ```ruby
 # Complex query combining multiple operations
-result = mudis-ql.from('users')
+result = MudisQL.from('users')
   .where(status: 'active')
   .where(age: ->(age) { age >= 25 })
   .order(:age, :desc)
@@ -261,7 +261,7 @@ result = mudis-ql.from('users')
 
 # Or using method chaining for pagination
 def get_active_users(page: 1, per_page: 10)
-  mudis-ql.from('users')
+  MudisQL.from('users')
     .where(status: 'active')
     .order(:name)
     .limit(per_page)
@@ -270,6 +270,31 @@ def get_active_users(page: 1, per_page: 10)
 end
 ```
 
+#### Aggregation
+
+```ruby
+# Sum numeric values
+total_salary = MudisQL.from('users')
+  .where(status: 'active')
+  .sum(:salary)
+
+# Calculate average
+avg_age = MudisQL.from('users')
+  .average(:age)
+
+# Group by field value
+by_department = MudisQL.from('users')
+  .where(status: 'active')
+  .group_by(:department)
+# => { "engineering" => [...], "sales" => [...], "marketing" => [...] }
+
+# Aggregation with complex filtering
+avg_high_earners = MudisQL.from('users')
+  .where(status: 'active')
+  .where(salary: ->(s) { s > 100000 })
+  .average(:salary)
+```
+
 ## How It Works
 
 mudis-ql works by:
@@ -298,7 +323,7 @@ class UserCacheService
   end
 
   def self.active_users(limit: 50)
-    mudis-ql.from(NAMESPACE)
+    MudisQL.from(NAMESPACE)
       .where(status: 'active')
       .order(:created_at, :desc)
       .limit(limit)
@@ -306,7 +331,7 @@ class UserCacheService
   end
 
   def self.search_by_name(pattern)
-    mudis-ql.from(NAMESPACE)
+    MudisQL.from(NAMESPACE)
       .where(name: /#{Regexp.escape(pattern)}/i)
       .all
   end
@@ -323,14 +348,14 @@ module MyApp
       NAMESPACE = 'users'
 
       def find_active(limit: 50)
-        mudis-ql.from(NAMESPACE)
+        MudisQL.from(NAMESPACE)
           .where(status: 'active')
           .limit(limit)
           .all
       end
 
       def find_by_age_range(min:, max:)
-        mudis-ql.from(NAMESPACE)
+        MudisQL.from(NAMESPACE)
           .where(age: min..max)
           .order(:age)
           .all
@@ -348,7 +373,7 @@ mudis-ql provides a powerful interface for querying mudis cache metrics:
 
 ```ruby
 # Get a metrics scope
-metrics = mudis-ql.metrics
+metrics = MudisQL.metrics
 
 # Top-level metrics summary
 summary = metrics.summary
@@ -466,7 +491,7 @@ current_metrics = metrics.refresh
 
 # Monitor cache performance over time
 def cache_health_check
-  m = mudis-ql.metrics
+  m = MudisQL.metrics
   
   {
     timestamp: Time.now,
@@ -483,10 +508,10 @@ end
 class MetricsController < ApplicationController
   def show
     render json: {
-      summary: mudis-ql.metrics.summary,
-      efficiency: mudis-ql.metrics.efficiency,
-      distribution: mudis-ql.metrics.bucket_distribution,
-      top_keys: mudis-ql.metrics.least_touched.order(:access_count, :desc).limit(10).all
+      summary: MudisQL.metrics.summary,
+      efficiency: MudisQL.metrics.efficiency,
+      distribution: MudisQL.metrics.bucket_distribution,
+      top_keys: MudisQL.metrics.least_touched.order(:access_count, :desc).limit(10).all
     }
   end
 end
@@ -494,17 +519,17 @@ end
 
 ## API Reference
 
-### mudis-ql.from(namespace)
+### MudisQL.from(namespace)
 
 Creates a new scope for the specified mudis namespace.
 
-**Returns:** `mudis-ql::Scope`
+**Returns:** `MudisQL::Scope`
 
-### mudis-ql.metrics
+### MudisQL.metrics
 
 Access mudis metrics with a queryable interface.
 
-**Returns:** `mudis-ql::MetricsScope`
+**Returns:** `MudisQL::MetricsScope`
 
 ### Scope Methods
 
@@ -520,6 +545,11 @@ Access mudis metrics with a queryable interface.
 | `count` | Count matching records | `Integer` |
 | `exists?` | Check if any records match | `Boolean` |
 | `pluck(*fields)` | Extract specific fields | `Array` |
+| `sum(field)` | Sum numeric values of a field | `Integer` or `Float` |
+| `average(field)` | Average numeric values of a field | `Float` |
+| `group_by(field)` | Group records by field value | `Hash` |
+| `exists?` | Check if any records match | `Boolean` |
+| `pluck(*fields)` | Extract specific fields | `Array` |
 
 ### MetricsScope Methods
 
@@ -540,7 +570,7 @@ Access mudis metrics with a queryable interface.
 
 ### Condition Matchers
 
-mudis-ql supports multiple types of matchers in `where` conditions:
+Mudis-QL supports multiple types of matchers in `where` conditions:
 
 ```ruby
 # Exact match
@@ -570,8 +600,7 @@ For very large datasets or complex queries, consider using a proper database alo
 1. **Full scan required**: Unlike databases with indexes, mudis-ql must load all records from a namespace to filter them
 2. **In-memory processing**: All filtering happens in Ruby memory, not at the storage layer
 3. **No joins**: Cannot join data across namespaces (each query targets one namespace)
-4. **No aggregations**: No built-in support for GROUP BY, SUM, AVG, etc.
-5. **Namespaces required for queries**: mudis-ql requires mudis namespaces to list and query collections. Keys stored without namespaces cannot be queried as a collection (individual key access still works via mudis directly).
+4. **Namespaces required for queries**: mudis-ql requires mudis namespaces to list and query collections. Keys stored without namespaces cannot be queried as a collection (individual key access still works via mudis directly).
 
 These limitations are by design to maintain simplicity and compatibility with mudis's key-value architecture.
 
@@ -579,17 +608,6 @@ These limitations are by design to maintain simplicity and compatibility with mu
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/kiebor81/mudisql.
 
-## Roadmap
-
-Future enhancements under consideration:
-
-- [ ] Index support for common query patterns
-- [ ] Aggregation methods (sum, average, group_by)
-- [ ] Multi-namespace queries
-- [ ] Query result caching
-- [ ] Bulk operations support
-- [ ] Custom serialization per namespace
-
 ## See Also
 
 - [Mudis](https://github.com/kiebor81/mudis)

data/lib/mudis-ql/scope.rb

@@ -108,6 +108,48 @@ module MudisQL
       count > 0
     end
 
+    # Sum numeric values of a field across matching records
+    #
+    # @param field [Symbol, String] the field to sum
+    # @return [Integer, Float] sum of numeric values, 0 if none found
+    def sum(field)
+      field_str = field.to_s
+      apply_conditions(store.all).sum do |record|
+        value = record[field_str]
+        value.is_a?(Numeric) ? value : 0
+      end
+    end
+
+    # Calculate average of numeric values for a field across matching records
+    #
+    # @param field [Symbol, String] the field to average
+    # @return [Float] average of numeric values, 0.0 if no records
+    def average(field)
+      field_str = field.to_s
+      results = apply_conditions(store.all)
+      return 0.0 if results.empty?
+
+      total = results.sum do |record|
+        value = record[field_str]
+        value.is_a?(Numeric) ? value : 0
+      end
+
+      (total.to_f / results.size).round(2)
+    end
+
+    # Group matching records by the value of a field
+    #
+    # @param field [Symbol, String] the field to group by
+    # @return [Hash] hash of field_value => array of records
+    def group_by(field)
+      field_str = field.to_s
+      filtered = apply_conditions(store.all)
+      
+      filtered.group_by do |record|
+        record[field_str]
+      end
+    end
+
     # Pluck specific fields from results
     #
     # @param fields [Array<Symbol, String>] fields to extract
@@ -125,6 +167,9 @@ module MudisQL
 
     private
 
+    # Apply where conditions to results
+    # @param results [Array<Hash>] array of records
+    # @return [Array<Hash>] filtered records
     def apply_conditions(results)
       @conditions.reduce(results) do |filtered, condition|
         filtered.select do |record|
@@ -138,6 +183,9 @@ module MudisQL
       end
     end
 
+    # Check if a value matches a condition
+    # @param value [Object] the field value
+    # @param matcher [Object, Proc, Regexp, Range] the condition to match
     def match_condition?(value, matcher)
       case matcher
       when Proc
@@ -151,29 +199,50 @@ module MudisQL
       end
     end
 
+    # Apply ordering to results
+    # @param results [Array<Hash>] array of records
+    # @return [Array<Hash>] ordered records
     def apply_order(results)
       return results unless @order_by
 
       begin
-        sorted = results.sort_by do |record|
+        # Separate nil and non-nil values
+        non_nil_results = []
+        nil_results = []
+        
+        results.each do |record|
           val = record[@order_by]
-          # Handle nil values and type-safe comparison
           if val.nil?
-            [@order_direction == :asc ? 1 : -1, ""]
-          elsif val.is_a?(Numeric)
-            [0, val]
+            nil_results << record
           else
-            [0, val.to_s]
+            non_nil_results << record
           end
         end
 
-        @order_direction == :desc ? sorted.reverse : sorted
+        # Sort non-nil values
+        sorted = non_nil_results.sort_by do |record|
+          val = record[@order_by]
+          if val.is_a?(Numeric)
+            val
+          else
+            val.to_s
+          end
+        end
+
+        # Reverse if descending
+        sorted = sorted.reverse if @order_direction == :desc
+
+        # Append nil values at the end
+        sorted + nil_results
       rescue ArgumentError => e
         # If sorting fails, return unsorted results
         results
       end
     end
 
+    # Apply limit and offset to results
+    # @param results [Array<Hash>] array of records
+    # @return [Array<Hash>] paginated records
     def apply_pagination(results)
       offset = [@offset_value, 0].max
       results = results.drop(offset) if offset > 0

data/lib/mudis-ql/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MudisQL
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/sig/mudis-ql/metrics_scope.rbs

@@ -0,0 +1,54 @@
+module MudisQL
+  # MetricsScope provides queryable access to mudis metrics data
+  class MetricsScope
+    attr_reader metrics_data: Hash[Symbol, untyped]
+
+    def initialize: () -> void
+
+    # Get top-level metrics (hits, misses, evictions, etc.)
+    def summary: () -> Hash[Symbol, untyped]
+
+    # Query least touched keys
+    def least_touched: () -> Scope
+
+    # Query bucket metrics
+    def buckets: () -> Scope
+
+    # Get total number of keys across all buckets
+    def total_keys: () -> Integer
+
+    # Get total memory across all buckets
+    def total_memory: () -> Integer
+
+    # Get hit rate as a percentage
+    def hit_rate: () -> Float
+
+    # Get cache efficiency metrics
+    def efficiency: () -> Hash[Symbol, Float]
+
+    # Find buckets with high memory usage
+    def high_memory_buckets: (Integer threshold) -> Array[Hash[Symbol, untyped]]
+
+    # Find buckets with many keys
+    def high_key_buckets: (Integer threshold) -> Array[Hash[Symbol, untyped]]
+
+    # Get bucket distribution statistics
+    def bucket_distribution: () -> Hash[Symbol, untyped]
+
+    # Get keys that have never been accessed
+    def never_accessed_keys: () -> Array[String]
+
+    # Refresh metrics data
+    def refresh: () -> MetricsScope
+
+    private
+
+    def eviction_rate: () -> Float
+
+    def rejection_rate: () -> Float
+
+    def create_scope_for_array: (Array[Hash[Symbol, untyped]] data) -> Scope
+
+    def default_distribution: () -> Hash[Symbol, untyped]
+  end
+end

data/sig/mudis-ql/scope.rbs

@@ -0,0 +1,60 @@
+module MudisQL
+  # Scope provides a chainable DSL for querying mudis cache data
+  class Scope
+    attr_reader store: Store
+
+    def initialize: (Store store) -> void
+
+    # Create a new independent scope instance
+    def clone: () -> Scope
+
+    # Filter records by conditions
+    def where: (Hash[String | Symbol, untyped] conditions) -> Scope
+
+    # Order results by a field
+    def order: (String | Symbol field, ?Symbol direction) -> Scope
+
+    # Limit the number of results
+    def limit: (Integer value) -> Scope
+
+    # Skip the first N results
+    def offset: (Integer value) -> Scope
+
+    # Execute the query and return all matching records
+    def all: () -> Array[Hash[String, untyped]]
+
+    # Execute query and return first result
+    def first: () -> Hash[String, untyped] | nil
+
+    # Execute query and return last result
+    def last: () -> Hash[String, untyped] | nil
+
+    # Count matching records
+    def count: () -> Integer
+
+    # Check if any records match
+    def exists?: () -> bool
+
+    # Pluck specific fields from results
+    def pluck: (*String | Symbol fields) -> Array[untyped]
+
+    # Sum numeric values of a field
+    def sum: (String | Symbol field) -> Integer | Float
+
+    # Calculate average of numeric values for a field
+    def average: (String | Symbol field) -> Float
+
+    # Group matching records by field value
+    def group_by: (String | Symbol field) -> Hash[untyped, Array[Hash[String, untyped]]]
+
+    private
+
+    def apply_conditions: (Array[Hash[String, untyped]] results) -> Array[Hash[String, untyped]]
+
+    def match_condition?: (untyped value, untyped matcher) -> bool
+
+    def apply_order: (Array[Hash[String, untyped]] results) -> Array[Hash[String, untyped]]
+
+    def apply_pagination: (Array[Hash[String, untyped]] results) -> Array[Hash[String, untyped]]
+  end
+end

data/sig/mudis-ql/store.rbs

@@ -0,0 +1,23 @@
+module MudisQL
+  # Store wraps mudis operations for a specific namespace
+  class Store
+    attr_reader namespace: String?
+
+    def initialize: (String? namespace) -> void
+
+    # Retrieve all keys from the namespace
+    def keys: () -> Array[String]
+
+    # Read a value from the cache
+    def read: (String key) -> untyped
+
+    # Write a value to the cache
+    def write: (String key, untyped value, ?expires_in: Integer?) -> untyped
+
+    # Delete a key from the cache
+    def delete: (String key) -> untyped
+
+    # Retrieve all records from the namespace
+    def all: () -> Array[Hash[String, untyped]]
+  end
+end

data/sig/mudis-ql.rbs

@@ -0,0 +1,25 @@
+module MudisQL
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  # Create a new scope for the given namespace
+  def self.from: (String? namespace) -> Scope
+
+  # Access mudis metrics with queryable interface
+  def self.metrics: () -> MetricsScope
+
+  # Configure MudisQL defaults
+  def self.configure: () { (Configuration) -> void } -> void
+
+  # Get the current configuration
+  def self.configuration: () -> Configuration
+
+  # Configuration class for MudisQL
+  class Configuration
+    attr_accessor default_limit: Integer
+
+    def initialize: () -> void
+  end
+end

data/spec/mudis-ql/scope_spec.rb

@@ -165,5 +165,96 @@ RSpec.describe MudisQL::Scope do
       expect(results.map { |r| r["name"] }).to eq(["Mouse", "Keyboard"])
     end
   end
+
+  describe "#sum" do
+    it "sums numeric values of a field" do
+      total = scope.sum(:price)
+      # Laptop (1200) + Mouse (25) + Desk (300) + Chair (150) + Keyboard (75) = 1750
+      expect(total).to eq(1750)
+    end
+
+    it "sums only matching records" do
+      # Desk (300) + Chair (150) = 450
+      total = scope.where(category: "furniture").sum(:price)
+      expect(total).to eq(450)
+    end
+
+    it "ignores non-numeric values" do
+      total = scope.sum(:name)
+      expect(total).to eq(0)
+    end
+
+    it "returns 0 when no records" do
+      total = scope.where(name: "nonexistent").sum(:price)
+      expect(total).to eq(0)
+    end
+  end
+
+  describe "#average" do
+    it "calculates average of numeric values" do
+      # (1200 + 25 + 300 + 150 + 75) / 5 = 1750 / 5 = 350.0
+      avg = scope.average(:price)
+      expect(avg).to eq(350.0)
+    end
+
+    it "averages only matching records" do
+      # Electronics: (1200 + 25 + 75) / 3 = 1300 / 3 = 433.33
+      avg = scope.where(category: "electronics").average(:price)
+      expect(avg).to eq(433.33)
+    end
+
+    it "ignores non-numeric values" do
+      avg = scope.average(:name)
+      expect(avg).to eq(0.0)
+    end
+
+    it "returns 0.0 when no records" do
+      avg = scope.where(name: "nonexistent").average(:price)
+      expect(avg).to eq(0.0)
+    end
+
+    it "rounds to 2 decimal places" do
+      # Furniture average: (300 + 150) / 2 = 225.0
+      avg = scope.where(category: "furniture").average(:price)
+      expect(avg).to eq(225.0)
+    end
+  end
+
+  describe "#group_by" do
+    it "groups records by field value" do
+      grouped = scope.group_by(:category)
+      expect(grouped.keys).to contain_exactly("electronics", "furniture")
+    end
+
+    it "includes all records in correct groups" do
+      grouped = scope.group_by(:category)
+      expect(grouped["electronics"].size).to eq(3)
+      expect(grouped["furniture"].size).to eq(2)
+    end
+
+    it "groups correctly with filters applied" do
+      # Only stock >= 30: Mouse (50), Keyboard (30)
+      grouped = scope.where(stock: ->(s) { s >= 30 }).group_by(:category)
+      expect(grouped["electronics"].size).to eq(2)
+      expect(grouped["furniture"]).to be_nil
+    end
+
+    it "groups by non-string fields" do
+      grouped = scope.group_by(:stock)
+      # stock values: 5, 50, 10, 20, 30
+      expect(grouped.keys).to contain_exactly(5, 50, 10, 20, 30)
+    end
+
+    it "includes nil as a group key" do
+      Mudis.write("item_nil_cat", { name: "Unknown", price: 50 }, namespace: namespace)
+      grouped = scope.group_by(:category)
+      expect(grouped).to have_key(nil)
+    end
+
+    it "returns empty hash when no records match" do
+      grouped = scope.where(name: "nonexistent").group_by(:category)
+      expect(grouped).to eq({})
+    end
+  end
 end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: mudis-ql
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - kiebor81
 bindir: bin
 cert_chain: []
-date: 2025-12-07 00:00:00.000000000 Z
+date: 2026-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mudis
@@ -65,11 +65,15 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.22'
-description: Mudis-QL extends Mudis by providing a SQL-like query interface for data
-  stored in the mudis cache
+description: Mudis-QL extends Mudis by providing a fluent SQL-like query interface
+  for data stored in the mudis cache
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- sig/mudis-ql/metrics_scope.rbs
+- sig/mudis-ql/scope.rbs
+- sig/mudis-ql/store.rbs
+- sig/mudis-ql.rbs
 files:
 - README.md
 - lib/mudis-ql.rb
@@ -77,6 +81,10 @@ files:
 - lib/mudis-ql/scope.rb
 - lib/mudis-ql/store.rb
 - lib/mudis-ql/version.rb
+- sig/mudis-ql.rbs
+- sig/mudis-ql/metrics_scope.rbs
+- sig/mudis-ql/scope.rbs
+- sig/mudis-ql/store.rbs
 - spec/mudis-ql/error_handling_spec.rb
 - spec/mudis-ql/integration_spec.rb
 - spec/mudis-ql/metrics_scope_spec.rb