tarsier 0.1.0

data/lib/tarsier/query.rb

@@ -0,0 +1,495 @@
+# frozen_string_literal: true
+
+module Tarsier
+  # Database-agnostic query builder
+  #
+  # Provides a fluent, chainable interface for building SQL queries.
+  # All methods return a new Query instance, making queries immutable.
+  #
+  # @example Basic queries
+  #   User.where(active: true)
+  #   User.where(role: 'admin').order(:name)
+  #   User.where(age: 18..65).limit(10)
+  #
+  # @example Chaining
+  #   User.where(active: true)
+  #       .where_not(role: 'guest')
+  #       .order(created_at: :desc)
+  #       .limit(10)
+  #       .offset(20)
+  #
+  # @since 0.1.0
+  class Query
+    include Enumerable
+
+    # @return [Class] the model class
+    attr_reader :model
+
+    # @return [Array] query conditions
+    attr_reader :conditions
+
+    # @return [Array] order clauses
+    attr_reader :order_clauses
+
+    # @return [Integer, nil] limit value
+    attr_reader :limit_value
+
+    # @return [Integer, nil] offset value
+    attr_reader :offset_value
+
+    # @return [Array] columns to select
+    attr_reader :select_columns
+
+    # @return [Array] join clauses
+    attr_reader :join_clauses
+
+    # @return [Array] associations to eager load
+    attr_reader :include_associations
+
+    # Create a new query
+    #
+    # @param model [Class] the model class to query
+    def initialize(model)
+      @model = model
+      @conditions = []
+      @order_clauses = []
+      @limit_value = nil
+      @offset_value = nil
+      @select_columns = ["*"]
+      @join_clauses = []
+      @include_associations = []
+      @loaded = false
+      @records = nil
+    end
+
+    # Add WHERE conditions
+    #
+    # @param conditions [Hash, String] conditions
+    # @return [Query] new query with conditions
+    #
+    # @example
+    #   User.where(active: true)
+    #   User.where(age: 18..30)
+    #   User.where('created_at > ?', 1.day.ago)
+    def where(conditions = nil, *values, **hash_conditions)
+      clone_with do |q|
+        case conditions
+        when Hash
+          conditions.each { |k, v| q.add_condition(k, :eq, v) }
+        when String
+          q.add_raw_condition(conditions, values)
+        when nil
+          hash_conditions.each { |k, v| q.add_condition(k, :eq, v) }
+        end
+      end
+    end
+
+    # Add WHERE NOT conditions
+    #
+    # @param conditions [Hash] conditions
+    # @return [Query] new query with conditions
+    #
+    # @example
+    #   User.where_not(role: 'guest')
+    def where_not(**conditions)
+      clone_with do |q|
+        conditions.each { |k, v| q.add_condition(k, :neq, v) }
+      end
+    end
+
+    # Add ORDER BY clause
+    #
+    # @param columns [Symbol, Hash] columns to order by
+    # @return [Query] new query with ordering
+    #
+    # @example
+    #   User.order(:name)
+    #   User.order(created_at: :desc)
+    #   User.order(:role, created_at: :desc)
+    def order(*columns, **hash_order)
+      clone_with do |q|
+        columns.each { |col| q.add_order(col, :asc) }
+        hash_order.each { |col, dir| q.add_order(col, dir) }
+      end
+    end
+
+    # Set LIMIT
+    #
+    # @param value [Integer] limit value
+    # @return [Query] new query with limit
+    def limit(value)
+      clone_with { |q| q.instance_variable_set(:@limit_value, value) }
+    end
+
+    # Set OFFSET
+    #
+    # @param value [Integer] offset value
+    # @return [Query] new query with offset
+    def offset(value)
+      clone_with { |q| q.instance_variable_set(:@offset_value, value) }
+    end
+
+    # Set SELECT columns
+    #
+    # @param columns [Array<Symbol>] columns to select
+    # @return [Query] new query with select
+    def select(*columns)
+      clone_with { |q| q.instance_variable_set(:@select_columns, columns.flatten) }
+    end
+
+    # Add JOIN clause
+    #
+    # @param table [Symbol, String] table to join
+    # @param on [String] join condition
+    # @param type [Symbol] join type (:inner, :left, :right)
+    # @return [Query] new query with join
+    #
+    # @example
+    #   User.joins(:posts, on: 'users.id = posts.user_id')
+    #   User.joins(:posts, type: :left)
+    def joins(table, on: nil, type: :inner)
+      clone_with do |q|
+        q.join_clauses << { table: table, on: on, type: type }
+      end
+    end
+
+    # Eager load associations
+    #
+    # @param associations [Array<Symbol>] associations to include
+    # @return [Query] new query with includes
+    #
+    # @example
+    #   User.includes(:posts, :comments)
+    def includes(*associations)
+      clone_with do |q|
+        q.instance_variable_set(:@include_associations, associations.flatten)
+      end
+    end
+
+    # Get first record
+    #
+    # @return [Model, nil]
+    def first
+      limit(1).to_a.first
+    end
+
+    # Get last record
+    #
+    # @return [Model, nil]
+    def last
+      order(@model.primary_key => :desc).limit(1).to_a.first
+    end
+
+    # Get record count
+    #
+    # @return [Integer]
+    def count
+      sql, params = build_count_sql
+      result = @model.db.get(sql, *params)
+      result[:count] || result.values.first
+    end
+
+    # Check if any records exist
+    #
+    # @return [Boolean]
+    def exists?
+      return false unless database_available?
+
+      limit(1).count > 0
+    end
+
+    # Check if no records exist
+    #
+    # @return [Boolean]
+    def empty?
+      !exists?
+    end
+
+    # Find or create a record
+    #
+    # @param attributes [Hash] attributes to find/create by
+    # @param create_with [Hash] additional attributes for creation
+    # @return [Model]
+    def find_or_create_by(attributes, create_with: {})
+      where(attributes).first || @model.create(attributes.merge(create_with))
+    end
+
+    # Find or initialize a record
+    #
+    # @param attributes [Hash] attributes to find/initialize by
+    # @return [Model]
+    def find_or_initialize_by(attributes)
+      where(attributes).first || @model.new(attributes)
+    end
+
+    # Iterate over records
+    #
+    # @yield [Model] each record
+    def each(&block)
+      load_records unless @loaded
+      @records.each(&block)
+    end
+
+    # Convert to array
+    #
+    # @return [Array<Model>]
+    def to_a
+      load_records unless @loaded
+      @records
+    end
+
+    # Build SQL query string (for debugging)
+    #
+    # @return [String]
+    def to_sql
+      parts = []
+
+      # SELECT
+      columns = @select_columns.map { |c| c == "*" ? "*" : c.to_s }.join(", ")
+      parts << "SELECT #{columns}"
+
+      # FROM
+      parts << "FROM #{@model.table}"
+
+      # JOINS
+      @join_clauses.each do |join|
+        join_type = join[:type].to_s.upcase
+        parts << "#{join_type} JOIN #{join[:table]}"
+        parts << "ON #{join[:on]}" if join[:on]
+      end
+
+      # WHERE
+      unless @conditions.empty?
+        where_parts = @conditions.map { |c| condition_to_display_sql(c) }
+        parts << "WHERE #{where_parts.join(' AND ')}"
+      end
+
+      # ORDER BY
+      unless @order_clauses.empty?
+        order_parts = @order_clauses.map { |o| "#{o[:column]} #{o[:direction].to_s.upcase}" }
+        parts << "ORDER BY #{order_parts.join(', ')}"
+      end
+
+      # LIMIT
+      parts << "LIMIT #{@limit_value}" if @limit_value
+
+      # OFFSET
+      parts << "OFFSET #{@offset_value}" if @offset_value
+
+      parts.join(" ")
+    end
+
+    # Pluck specific columns
+    #
+    # @param columns [Array<Symbol>] columns to pluck
+    # @return [Array]
+    #
+    # @example
+    #   User.pluck(:id)
+    #   User.pluck(:id, :name)
+    def pluck(*columns)
+      select(*columns).to_a.map do |record|
+        if columns.size == 1
+          record.to_h[columns.first]
+        else
+          columns.map { |c| record.to_h[c] }
+        end
+      end
+    end
+
+    # Get IDs only
+    #
+    # @return [Array]
+    def ids
+      pluck(@model.primary_key)
+    end
+
+    # Update all matching records
+    #
+    # @param attributes [Hash] attributes to update
+    # @return [Integer] number of updated records
+    def update_all(attributes)
+      where_clause, where_params = build_where
+      set_clause = attributes.keys.map { |k| "#{k} = ?" }.join(", ")
+
+      sql = "UPDATE #{@model.table} SET #{set_clause}"
+      sql += " WHERE #{where_clause}" unless where_clause.empty?
+
+      @model.db.execute(sql, *attributes.values, *where_params)
+      @model.db.send(:affected_rows)
+    end
+
+    # Delete all matching records
+    #
+    # @return [Integer] number of deleted records
+    def delete_all
+      where_clause, where_params = build_where
+
+      sql = "DELETE FROM #{@model.table}"
+      sql += " WHERE #{where_clause}" unless where_clause.empty?
+
+      @model.db.execute(sql, *where_params)
+      @model.db.send(:affected_rows)
+    end
+
+    protected
+
+    def add_condition(column, operator, value)
+      @conditions << { column: column, operator: operator, value: value }
+    end
+
+    def add_raw_condition(sql, values)
+      @conditions << { raw: sql, values: values }
+    end
+
+    def add_order(column, direction)
+      @order_clauses << { column: column, direction: direction }
+    end
+
+    private
+
+    def clone_with
+      clone = self.class.new(@model)
+      clone.instance_variable_set(:@conditions, @conditions.dup)
+      clone.instance_variable_set(:@order_clauses, @order_clauses.dup)
+      clone.instance_variable_set(:@limit_value, @limit_value)
+      clone.instance_variable_set(:@offset_value, @offset_value)
+      clone.instance_variable_set(:@select_columns, @select_columns.dup)
+      clone.instance_variable_set(:@join_clauses, @join_clauses.dup)
+      clone.instance_variable_set(:@include_associations, @include_associations.dup)
+      yield clone
+      clone
+    end
+
+    def build_sql
+      parts = []
+      params = []
+
+      # SELECT
+      columns = @select_columns.map { |c| c == "*" ? "*" : c.to_s }.join(", ")
+      parts << "SELECT #{columns}"
+
+      # FROM
+      parts << "FROM #{@model.table}"
+
+      # WHERE
+      where_clause, where_params = build_where
+      unless where_clause.empty?
+        parts << "WHERE #{where_clause}"
+        params.concat(where_params)
+      end
+
+      # ORDER BY
+      unless @order_clauses.empty?
+        order_parts = @order_clauses.map { |o| "#{o[:column]} #{o[:direction].to_s.upcase}" }
+        parts << "ORDER BY #{order_parts.join(', ')}"
+      end
+
+      # LIMIT
+      parts << "LIMIT #{@limit_value}" if @limit_value
+
+      # OFFSET
+      parts << "OFFSET #{@offset_value}" if @offset_value
+
+      [parts.join(" "), params]
+    end
+
+    def build_count_sql
+      parts = ["SELECT COUNT(*) as count", "FROM #{@model.table}"]
+      params = []
+
+      where_clause, where_params = build_where
+      unless where_clause.empty?
+        parts << "WHERE #{where_clause}"
+        params.concat(where_params)
+      end
+
+      [parts.join(" "), params]
+    end
+
+    def build_where
+      return ["", []] if @conditions.empty?
+
+      clauses = []
+      params = []
+
+      @conditions.each do |condition|
+        if condition[:raw]
+          clauses << condition[:raw]
+          params.concat(condition[:values])
+        else
+          clause, value = condition_to_sql(condition)
+          clauses << clause
+          params.concat(Array(value)) unless value.nil?
+        end
+      end
+
+      [clauses.join(" AND "), params]
+    end
+
+    def condition_to_sql(condition)
+      column = condition[:column]
+      value = condition[:value]
+      operator = condition[:operator]
+
+      case value
+      when nil
+        [operator == :eq ? "#{column} IS NULL" : "#{column} IS NOT NULL", nil]
+      when Range
+        ["#{column} BETWEEN ? AND ?", [value.begin, value.end]]
+      when Array
+        placeholders = (["?"] * value.size).join(", ")
+        op = operator == :eq ? "IN" : "NOT IN"
+        ["#{column} #{op} (#{placeholders})", value]
+      else
+        op = operator == :eq ? "=" : "!="
+        ["#{column} #{op} ?", [value]]
+      end
+    end
+
+    def condition_to_display_sql(condition)
+      return condition[:raw] if condition[:raw]
+
+      column = condition[:column]
+      value = condition[:value]
+      operator = condition[:operator]
+
+      case value
+      when nil
+        operator == :eq ? "#{column} IS NULL" : "#{column} IS NOT NULL"
+      when Range
+        "#{column} BETWEEN #{quote_value(value.begin)} AND #{quote_value(value.end)}"
+      when Array
+        values = value.map { |v| quote_value(v) }.join(", ")
+        op = operator == :eq ? "IN" : "NOT IN"
+        "#{column} #{op} (#{values})"
+      else
+        op = operator == :eq ? "=" : "!="
+        "#{column} #{op} #{quote_value(value)}"
+      end
+    end
+
+    def quote_value(value)
+      case value
+      when String then "'#{value.gsub("'", "''")}'"
+      when nil then "NULL"
+      when true then "TRUE"
+      when false then "FALSE"
+      else value.to_s
+      end
+    end
+
+    def load_records
+      sql, params = build_sql
+      rows = @model.db.execute(sql, *params)
+      @records = rows.map { |row| @model.from_row(row) }
+      @loaded = true
+    end
+
+    def database_available?
+      Tarsier::Database.connected?
+    rescue StandardError
+      false
+    end
+  end
+end