mudis-ql 0.1.0

data/lib/mudis-ql/metrics_scope.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module MudisQL
+  # MetricsScope provides queryable access to mudis metrics data
+  class MetricsScope
+    attr_reader :metrics_data
+
+    def initialize
+      @metrics_data = Mudis.metrics
+      @conditions = []
+      @order_by = nil
+      @order_direction = :asc
+      @limit_value = nil
+      @offset_value = 0
+    end
+
+    # Get top-level metrics (hits, misses, evictions, etc.)
+    #
+    # @return [Hash] top-level metrics
+    def summary
+      @metrics_data.reject { |k, _| [:least_touched, :buckets].include?(k) }
+    end
+
+    # Query least touched keys
+    #
+    # @return [Scope] a new scope for least_touched array
+    def least_touched
+      data = @metrics_data[:least_touched] || []
+      create_scope_for_array(data.map { |key, count| { key: key, access_count: count } })
+    end
+
+    # Query bucket metrics
+    #
+    # @return [Scope] a new scope for buckets array
+    def buckets
+      data = @metrics_data[:buckets] || []
+      # Normalize to symbol keys
+      normalized = data.map do |bucket|
+        bucket.transform_keys(&:to_sym)
+      end
+      create_scope_for_array(normalized)
+    end
+
+    # Get total number of keys across all buckets
+    #
+    # @return [Integer] total key count
+    def total_keys
+      buckets_data = @metrics_data[:buckets] || []
+      buckets_data.sum { |b| (b[:keys] || b["keys"] || 0) }
+    end
+
+    # Get total memory across all buckets
+    #
+    # @return [Integer] total memory in bytes
+    def total_memory
+      @metrics_data[:total_memory] || 0
+    end
+
+    # Get hit rate as a percentage
+    #
+    # @return [Float] hit rate percentage
+    def hit_rate
+      hits = @metrics_data[:hits] || 0
+      misses = @metrics_data[:misses] || 0
+      total = hits + misses
+      return 0.0 if total.zero?
+
+      (hits.to_f / total * 100).round(2)
+    end
+
+    # Get cache efficiency metrics
+    #
+    # @return [Hash] efficiency statistics
+    def efficiency
+      {
+        hit_rate: hit_rate,
+        miss_rate: (100 - hit_rate).round(2),
+        eviction_rate: eviction_rate,
+        rejection_rate: rejection_rate
+      }
+    end
+
+    # Find buckets with high memory usage
+    #
+    # @param threshold [Integer] memory threshold in bytes
+    # @return [Array<Hash>] buckets exceeding threshold
+    def high_memory_buckets(threshold)
+      buckets_data = @metrics_data[:buckets] || []
+      buckets_data.select { |b| ((b[:memory_bytes] || b["memory_bytes"]) || 0) > threshold }
+    end
+
+    # Find buckets with many keys
+    #
+    # @param threshold [Integer] key count threshold
+    # @return [Array<Hash>] buckets exceeding threshold
+    def high_key_buckets(threshold)
+      buckets_data = @metrics_data[:buckets] || []
+      buckets_data.select { |b| ((b[:keys] || b["keys"]) || 0) > threshold }
+    end
+
+    # Get bucket distribution statistics
+    #
+    # @return [Hash] distribution stats
+    def bucket_distribution
+      buckets_data = @metrics_data[:buckets] || []
+      return default_distribution if buckets_data.empty?
+
+      key_counts = buckets_data.map { |b| (b[:keys] || b["keys"]) || 0 }
+      memory_values = buckets_data.map { |b| (b[:memory_bytes] || b["memory_bytes"]) || 0 }
+
+      {
+        total_buckets: buckets_data.size,
+        avg_keys_per_bucket: (key_counts.sum.to_f / buckets_data.size).round(2),
+        max_keys_per_bucket: key_counts.max || 0,
+        min_keys_per_bucket: key_counts.min || 0,
+        avg_memory_per_bucket: (memory_values.sum.to_f / buckets_data.size).round(2),
+        max_memory_per_bucket: memory_values.max || 0,
+        min_memory_per_bucket: memory_values.min || 0
+      }
+    end
+
+    # Get keys that have never been accessed
+    #
+    # @return [Array<String>] keys with 0 access count
+    def never_accessed_keys
+      data = @metrics_data[:least_touched] || []
+      data.select { |_key, count| count.zero? }.map(&:first)
+    end
+
+    # Refresh metrics data
+    #
+    # @return [MetricsScope] self
+    def refresh
+      @metrics_data = Mudis.metrics
+      self
+    end
+
+    private
+
+    def eviction_rate
+      evictions = @metrics_data[:evictions] || 0
+      total_ops = (@metrics_data[:hits] || 0) + (@metrics_data[:misses] || 0)
+      return 0.0 if total_ops.zero?
+
+      (evictions.to_f / total_ops * 100).round(2)
+    end
+
+    def rejection_rate
+      rejected = @metrics_data[:rejected] || 0
+      total_ops = (@metrics_data[:hits] || 0) + (@metrics_data[:misses] || 0)
+      return 0.0 if total_ops.zero?
+
+      (rejected.to_f / total_ops * 100).round(2)
+    end
+
+    def create_scope_for_array(data)
+      # Create a temporary store-like object for the array data
+      temp_store = Object.new
+      temp_store.define_singleton_method(:all) { data }
+      Scope.new(temp_store)
+    end
+
+    def default_distribution
+      {
+        total_buckets: 0,
+        avg_keys_per_bucket: 0.0,
+        max_keys_per_bucket: 0,
+        min_keys_per_bucket: 0,
+        avg_memory_per_bucket: 0.0,
+        max_memory_per_bucket: 0,
+        min_memory_per_bucket: 0
+      }
+    end
+  end
+end

data/lib/mudis-ql/scope.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module MudisQL
+  # Scope provides a chainable DSL for querying mudis cache data
+  class Scope
+    attr_reader :store
+
+    def initialize(store)
+      @store = store
+      @conditions = []
+      @order_by = nil
+      @order_direction = :asc
+      @limit_value = nil
+      @offset_value = 0
+    end
+
+    # Create a new independent scope instance
+    def clone
+      cloned = self.class.new(@store)
+      cloned.instance_variable_set(:@conditions, @conditions.dup)
+      cloned.instance_variable_set(:@order_by, @order_by)
+      cloned.instance_variable_set(:@order_direction, @order_direction)
+      cloned.instance_variable_set(:@limit_value, @limit_value)
+      cloned.instance_variable_set(:@offset_value, @offset_value)
+      cloned
+    end
+
+    # Filter records by conditions
+    #
+    # @param conditions [Hash] hash of field => value or field => proc
+    # @return [Scope] self for chaining
+    #
+    # @example
+    #   query.where(status: "active")
+    #   query.where(age: ->(v) { v > 18 })
+    #   query.where(name: /^A/)
+    def where(conditions)
+      @conditions = @conditions.dup unless @conditions.frozen?
+      @conditions << conditions
+      self
+    end
+
+    # Order results by a field
+    #
+    # @param field [Symbol, String] the field to order by
+    # @param direction [Symbol] :asc or :desc
+    # @return [Scope] self for chaining
+    def order(field, direction = :asc)
+      @order_by = field.to_s
+      @order_direction = direction
+      self
+    end
+
+    # Limit the number of results
+    #
+    # @param value [Integer] maximum number of results
+    # @return [Scope] self for chaining
+    def limit(value)
+      @limit_value = value
+      self
+    end
+
+    # Skip the first N results
+    #
+    # @param value [Integer] number of results to skip
+    # @return [Scope] self for chaining
+    def offset(value)
+      @offset_value = value
+      self
+    end
+
+    # Execute the query and return all matching records
+    #
+    # @return [Array<Hash>] array of matching records
+    def all
+      results = store.all
+      results = apply_conditions(results)
+      results = apply_order(results)
+      results = apply_pagination(results)
+      results
+    end
+
+    # Execute query and return first result
+    #
+    # @return [Hash, nil] first matching record or nil
+    def first
+      limit(1).all.first
+    end
+
+    # Execute query and return last result
+    #
+    # @return [Hash, nil] last matching record or nil
+    def last
+      all.last
+    end
+
+    # Count matching records
+    #
+    # @return [Integer] number of matching records
+    def count
+      apply_conditions(store.all).size
+    end
+
+    # Check if any records match
+    #
+    # @return [Boolean] true if at least one record matches
+    def exists?
+      count > 0
+    end
+
+    # Pluck specific fields from results
+    #
+    # @param fields [Array<Symbol, String>] fields to extract
+    # @return [Array] array of field values or arrays of values
+    def pluck(*fields)
+      fields = fields.map(&:to_s)
+      results = all
+
+      if fields.size == 1
+        results.map { |record| record[fields.first] }
+      else
+        results.map { |record| fields.map { |f| record[f] } }
+      end
+    end
+
+    private
+
+    def apply_conditions(results)
+      @conditions.reduce(results) do |filtered, condition|
+        filtered.select do |record|
+          condition.all? do |key, matcher|
+            field = key.to_s
+            value = record[field]
+
+            match_condition?(value, matcher)
+          end
+        end
+      end
+    end
+
+    def match_condition?(value, matcher)
+      case matcher
+      when Proc
+        matcher.call(value)
+      when Regexp
+        value.to_s =~ matcher
+      when Range
+        matcher.include?(value)
+      else
+        value == matcher
+      end
+    end
+
+    def apply_order(results)
+      return results unless @order_by
+
+      begin
+        sorted = results.sort_by 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]
+          else
+            [0, val.to_s]
+          end
+        end
+
+        @order_direction == :desc ? sorted.reverse : sorted
+      rescue ArgumentError => e
+        # If sorting fails, return unsorted results
+        results
+      end
+    end
+
+    def apply_pagination(results)
+      offset = [@offset_value, 0].max
+      results = results.drop(offset) if offset > 0
+      results = results.take(@limit_value) if @limit_value && @limit_value >= 0
+      results
+    end
+  end
+end

data/lib/mudis-ql/store.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "mudis"
+
+module MudisQL
+  # Store wraps mudis operations for a specific namespace
+  class Store
+    attr_reader :namespace
+
+    def initialize(namespace = nil)
+      @namespace = namespace
+    end
+
+    # Retrieve all keys from the namespace
+    #
+    # @return [Array<String>] array of keys
+    def keys
+      if namespace
+        Mudis.keys(namespace: namespace) || []
+      else
+        # When no namespace, mudis uses default internal namespace
+        # We need to call without the namespace parameter
+        []  # mudis doesn't support listing keys without namespace
+      end
+    end
+
+    # Read a value from the cache
+    #
+    # @param key [String] the key to read
+    # @return [Object, nil] the cached value or nil
+    def read(key)
+      if namespace
+        Mudis.read(key, namespace: namespace)
+      else
+        Mudis.read(key)
+      end
+    end
+
+    # Write a value to the cache
+    #
+    # @param key [String] the key to write
+    # @param value [Object] the value to store
+    # @param expires_in [Integer, nil] optional TTL in seconds
+    def write(key, value, expires_in: nil)
+      if namespace
+        Mudis.write(key, value, expires_in: expires_in, namespace: namespace)
+      else
+        Mudis.write(key, value, expires_in: expires_in)
+      end
+    end
+
+    # Delete a key from the cache
+    #
+    # @param key [String] the key to delete
+    def delete(key)
+      if namespace
+        Mudis.delete(key, namespace: namespace)
+      else
+        Mudis.delete(key)
+      end
+    end
+
+    # Retrieve all records from the namespace
+    #
+    # @return [Array<Hash>] array of records with their keys
+    def all
+      keys.map do |key|
+        value = read(key)
+        next unless value
+
+        if value.is_a?(Hash)
+          value.merge("_key" => key)
+        else
+          { "_key" => key, "value" => value }
+        end
+      end.compact
+    end
+  end
+end

data/lib/mudis-ql/version.rb

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

data/lib/mudis-ql.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "mudis-ql/version"
+require_relative "mudis-ql/store"
+require_relative "mudis-ql/scope"
+require_relative "mudis-ql/metrics_scope"
+
+# MudisQL provides a simple query DSL for mudis cache
+module MudisQL
+  class Error < StandardError; end
+
+  # Create a new scope for the given namespace
+  #
+  # @param namespace [String, nil] the mudis namespace to query (nil for default/no namespace)
+  # @return [MudisQL::Scope] a new scope object
+  def self.from(namespace = nil)
+    Scope.new(Store.new(namespace))
+  end
+
+  # Access mudis metrics with queryable interface
+  #
+  # @return [MudisQL::MetricsScope] a metrics scope object
+  def self.metrics
+    MetricsScope.new
+  end
+
+  # Configure MudisQL defaults
+  #
+  # @yield [Configuration] configuration object
+  def self.configure
+    yield configuration
+  end
+
+  # Get the current configuration
+  #
+  # @return [Configuration] current configuration
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  # Configuration class for MudisQL
+  class Configuration
+    attr_accessor :default_limit
+
+    def initialize
+      @default_limit = 100
+    end
+  end
+end