querykit 0.1.0

data/lib/querykit/query.rb

@@ -0,0 +1,473 @@
+# frozen_string_literal: true
+
+module QueryKit
+  # Query builder for constructing SQL SELECT statements.
+  #
+  # Provides a fluent, chainable API for building complex SQL queries
+  # with automatic parameter binding for security.
+  #
+  # @example Basic query
+  #   query = Query.new('users')
+  #     .select('id', 'name', 'email')
+  #     .where('age', '>', 18)
+  #     .order_by('name')
+  #     .limit(10)
+  #
+  # @example Complex query with joins
+  #   query = Query.new('users')
+  #     .join('posts', 'users.id', 'posts.user_id')
+  #     .where('users.active', true)
+  #     .where('posts.published', true)
+  #     .select('users.*', 'COUNT(posts.id) as post_count')
+  #     .group_by('users.id')
+  class Query
+    # @return [String, nil] the table name for this query
+    attr_reader :table
+    
+    # @return [Array<Hash>] the WHERE conditions
+    attr_reader :wheres
+    
+    # @return [Array<String>] the columns to select
+    attr_reader :selects
+    
+    # @return [Array<Hash>] the JOIN clauses
+    attr_reader :joins
+    
+    # @return [Array<String>] the ORDER BY clauses
+    attr_reader :orders
+    
+    # @return [Array<String>] the GROUP BY columns
+    attr_reader :groups
+    
+    # @return [Integer, nil] the LIMIT value
+    attr_reader :limit_value
+    
+    # @return [Integer, nil] the OFFSET value
+    attr_reader :offset_value
+    
+    # @return [Array] the parameter bindings for safe query execution
+    attr_accessor :bindings
+
+    # Initialize a new Query instance.
+    #
+    # @param table [String, nil] the table name to query
+    #
+    # @example
+    #   query = Query.new('users')
+    #   query = Query.new  # table can be set later with from()
+    def initialize(table = nil)
+      @table = table
+      @selects = []
+      @wheres = []
+      @joins = []
+      @orders = []
+      @groups = []
+      @havings = []
+      @limit_value = nil
+      @offset_value = nil
+      @bindings = []
+      @distinct = false
+      @unions = []
+    end
+
+    # Set the table name for this query.
+    #
+    # @param table [String] the table name
+    # @return [Query] self for method chaining
+    #
+    # @example
+    #   query.from('users')
+    def from(table)
+      @table = table
+      self
+    end
+
+    # Specify columns to select.
+    #
+    # @param columns [Array<String>] column names to select. Defaults to '*' if none provided.
+    # @return [Query] self for method chaining
+    #
+    # @example Select specific columns
+    #   query.select('id', 'name', 'email')
+    #
+    # @example Select with aliases
+    #   query.select('users.id', 'users.name as user_name')
+    #
+    # @example Select all columns (default)
+    #   query.select  # equivalent to SELECT *
+    def select(*columns)
+      columns = ['*'] if columns.empty?
+      @selects.concat(columns.flatten)
+      self
+    end
+
+    # Set the query to return distinct results.
+    #
+    # @return [Query] self for method chaining
+    #
+    # @example
+    #   query.select('country').distinct
+    def distinct
+      @distinct = true
+      self
+    end
+
+    # Add a WHERE condition to the query.
+    #
+    # Supports multiple calling patterns for flexibility.
+    # Values are automatically parameterized for SQL injection protection.
+    #
+    # @overload where(column, value)
+    #   @param column [String] the column name
+    #   @param value [Object] the value to compare (assumes = operator)
+    #   @example
+    #     query.where('status', 'active')
+    #
+    # @overload where(column, operator, value)
+    #   @param column [String] the column name
+    #   @param operator [String] comparison operator (=, >, <, >=, <=, !=, LIKE)
+    #   @param value [Object] the value to compare
+    #   @example
+    #     query.where('age', '>', 18)
+    #     query.where('name', 'LIKE', 'John%')
+    #
+    # @overload where(hash)
+    #   @param hash [Hash] column-value pairs (all use = operator)
+    #   @example
+    #     query.where(status: 'active', country: 'USA')
+    #
+    # @return [Query] self for method chaining
+    def where(column, operator = nil, value = nil)
+      # Handle different argument patterns
+      if column.is_a?(Hash)
+        column.each { |k, v| where(k, '=', v) }
+        return self
+      end
+
+      if value.nil? && !operator.nil?
+        value = operator
+        operator = '='
+      end
+
+      @wheres << { type: 'basic', column: column, operator: operator, value: value, boolean: 'AND' }
+      @bindings << value unless value.nil?
+      self
+    end
+
+    # Add an OR WHERE condition to the query.
+    #
+    # @param column [String] the column name
+    # @param operator [String, Object] the operator or value (if value is nil)
+    # @param value [Object, nil] the value to compare
+    #
+    # @return [Query] self for method chaining
+    #
+    # @example
+    #   query.where('status', 'active').or_where('priority', 'high')
+    def or_where(column, operator = nil, value = nil)
+      if value.nil? && !operator.nil?
+        value = operator
+        operator = '='
+      end
+
+      @wheres << { type: 'basic', column: column, operator: operator, value: value, boolean: 'OR' }
+      @bindings << value unless value.nil?
+      self
+    end
+
+    # WHERE IN clause
+    def where_in(column, values)
+      @wheres << { type: 'in', column: column, values: values, boolean: 'AND' }
+      @bindings.concat(values)
+      self
+    end
+
+    # WHERE NOT IN clause
+    def where_not_in(column, values)
+      @wheres << { type: 'not_in', column: column, values: values, boolean: 'AND' }
+      @bindings.concat(values)
+      self
+    end
+
+    # WHERE IS NULL / IS NOT NULL
+    def where_null(column)
+      @wheres << { type: 'null', column: column, boolean: 'AND' }
+      self
+    end
+
+    # WHERE IS NOT NULL
+    def where_not_null(column)
+      @wheres << { type: 'not_null', column: column, boolean: 'AND' }
+      self
+    end
+
+    # WHERE BETWEEN
+    def where_between(column, min, max)
+      @wheres << { type: 'between', column: column, min: min, max: max, boolean: 'AND' }
+      @bindings << min << max
+      self
+    end
+
+    # Raw WHERE clause
+    def where_raw(sql, *bindings)
+      @wheres << { type: 'raw', sql: sql, boolean: 'AND' }
+      @bindings.concat(bindings)
+      self
+    end
+
+    # WHERE EXISTS
+    def where_exists(subquery)
+      sql = subquery.is_a?(String) ? subquery : subquery.to_sql
+      @wheres << { type: 'exists', sql: sql, boolean: 'AND' }
+      @bindings.concat(subquery.bindings) if subquery.respond_to?(:bindings)
+      self
+    end
+
+    # WHERE NOT EXISTS
+    def where_not_exists(subquery)
+      sql = subquery.is_a?(String) ? subquery : subquery.to_sql
+      @wheres << { type: 'not_exists', sql: sql, boolean: 'AND' }
+      @bindings.concat(subquery.bindings) if subquery.respond_to?(:bindings)
+      self
+    end
+
+    # JOIN clauses
+    def join(table, first, operator = nil, second = nil)
+      if operator.nil?
+        operator = '='
+        second = first
+      end
+      @joins << { type: 'INNER', table: table, first: first, operator: operator, second: second }
+      self
+    end
+
+    # LEFT JOIN
+    def left_join(table, first, operator = nil, second = nil)
+      if operator.nil?
+        operator = '='
+        second = first
+      end
+      @joins << { type: 'LEFT', table: table, first: first, operator: operator, second: second }
+      self
+    end
+
+    # RIGHT JOIN
+    def right_join(table, first, operator = nil, second = nil)
+      if operator.nil?
+        operator = '='
+        second = first
+      end
+      @joins << { type: 'RIGHT', table: table, first: first, operator: operator, second: second }
+      self
+    end
+
+    # CROSS JOIN
+    def cross_join(table)
+      @joins << { type: 'CROSS', table: table }
+      self
+    end
+
+    # ORDER BY
+    def order_by(column, direction = 'ASC')
+      @orders << { column: column, direction: direction.upcase }
+      self
+    end
+
+    # Set the query to order results in descending order
+    def order_by_desc(column)
+      order_by(column, 'DESC')
+    end
+
+    # GROUP BY
+    def group_by(*columns)
+      @groups.concat(columns.flatten)
+      self
+    end
+
+    # HAVING
+    def having(column, operator = nil, value = nil)
+      if value.nil? && !operator.nil?
+        value = operator
+        operator = '='
+      end
+
+      @havings << { column: column, operator: operator, value: value, boolean: 'AND' }
+      @bindings << value unless value.nil?
+      self
+    end
+
+    # LIMIT and OFFSET
+    def limit(value)
+      @limit_value = value
+      self
+    end
+
+    # Set the query offset
+    def offset(value)
+      @offset_value = value
+      self
+    end
+
+    # Alias methods for offset and limit
+    def skip(value)
+      offset(value)
+    end
+
+    # Alias methods for offset and limit
+    def take(value)
+      limit(value)
+    end
+
+    # Pagination
+    def page(page_number, per_page = 15)
+      offset((page_number - 1) * per_page).limit(per_page)
+    end
+
+    # Aggregate shortcuts
+    def count(column = '*')
+      select("COUNT(#{column}) as count")
+    end
+
+    def avg(column)
+      select("AVG(#{column}) as avg")
+    end
+
+    def sum(column)
+      select("SUM(#{column}) as sum")
+    end
+
+    def min(column)
+      select("MIN(#{column}) as min")
+    end
+
+    def max(column)
+      select("MAX(#{column}) as max")
+    end
+
+    # UNION / UNION ALL
+    def union(query)
+      @unions << { type: 'UNION', query: query }
+      self
+    end
+
+    def union_all(query)
+      @unions << { type: 'UNION ALL', query: query }
+      self
+    end
+
+    # Build SQL
+    def to_sql
+      raise "No table specified" unless @table
+
+      sql = []
+      sql << "SELECT"
+      sql << "DISTINCT" if @distinct
+      sql << (@selects.empty? ? '*' : @selects.join(', '))
+      sql << "FROM #{@table}"
+
+      # JOINs
+      # JOINs
+      @joins.each do |join|
+        if join[:type] == 'CROSS'
+          sql << "CROSS JOIN #{join[:table]}"
+        else
+          sql << "#{join[:type]} JOIN #{join[:table]} ON #{join[:first]} #{join[:operator]} #{join[:second]}"
+        end
+      end
+
+      # WHERE
+      unless @wheres.empty?
+        sql << "WHERE"
+        where_clauses = []
+        @wheres.each_with_index do |where, index|
+          clause = build_where_clause(where)
+          if index == 0
+            where_clauses << clause
+          else
+            where_clauses << "#{where[:boolean]} #{clause}"
+          end
+        end
+        sql << where_clauses.join(' ')
+      end
+
+      # GROUP BY
+      unless @groups.empty?
+        sql << "GROUP BY #{@groups.join(', ')}"
+      end
+
+      # HAVING
+      unless @havings.empty?
+        sql << "HAVING"
+        having_clauses = []
+        @havings.each_with_index do |having, index|
+          clause = "#{having[:column]} #{having[:operator]} ?"
+          if index == 0
+            having_clauses << clause
+          else
+            having_clauses << "#{having[:boolean]} #{clause}"
+          end
+        end
+        sql << having_clauses.join(' ')
+      end
+
+      # ORDER BY
+      unless @orders.empty?
+        sql << "ORDER BY #{@orders.map { |o| "#{o[:column]} #{o[:direction]}" }.join(', ')}"
+      end
+
+      # LIMIT
+      sql << "LIMIT #{@limit_value}" if @limit_value
+
+      # OFFSET
+      sql << "OFFSET #{@offset_value}" if @offset_value
+
+      # Build main query
+      main_sql = sql.join(' ')
+
+      # UNION / UNION ALL
+      unless @unions.empty?
+        union_parts = [main_sql]
+        @unions.each do |union|
+          union_sql = union[:query].is_a?(String) ? union[:query] : union[:query].to_sql
+          union_parts << "#{union[:type]} #{union_sql}"
+          @bindings.concat(union[:query].bindings) if union[:query].respond_to?(:bindings)
+        end
+        return union_parts.join(' ')
+      end
+
+      main_sql
+    end
+
+    def to_s
+      to_sql
+    end
+
+    private
+
+    # Build individual WHERE clause
+    def build_where_clause(where)
+      case where[:type]
+      when 'basic'
+        "#{where[:column]} #{where[:operator]} ?"
+      when 'in'
+        placeholders = (['?'] * where[:values].size).join(', ')
+        "#{where[:column]} IN (#{placeholders})"
+      when 'not_in'
+        placeholders = (['?'] * where[:values].size).join(', ')
+        "#{where[:column]} NOT IN (#{placeholders})"
+      when 'null'
+        "#{where[:column]} IS NULL"
+      when 'not_null'
+        "#{where[:column]} IS NOT NULL"
+      when 'between'
+        "#{where[:column]} BETWEEN ? AND ?"
+      when 'raw'
+        where[:sql]
+      when 'exists'
+        "EXISTS (#{where[:sql]})"
+      when 'not_exists'
+        "NOT EXISTS (#{where[:sql]})"
+      end
+    end
+  end
+end

data/lib/querykit/repository.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module QueryKit
+  # Base repository class for implementing the repository pattern
+  # 
+  # Usage:
+  #   class UserRepository < QueryKit::Repository
+  #     table 'users'
+  #     model User
+  #   end
+  #
+  #   repo = UserRepository.new(db)
+  #   user = repo.find(1)
+  #   users = repo.all
+  #   users = repo.where('age', '>', 18)
+  class Repository
+    attr_reader :db
+
+    class << self
+      # Set the table name for this repository
+      def table(name)
+        @table_name = name
+      end
+      
+      # Set the model class for this repository
+      def model(klass)
+        @model_class = klass
+      end
+      
+      # Get the table name
+      def table_name
+        @table_name
+      end
+      
+      # Get the model class
+      def model_class
+        @model_class
+      end
+    end
+    
+    attr_reader :db
+    
+    # Initialize repository with optional database connection
+    # If no connection provided, uses global QueryKit.connection
+    # @param db [QueryKit::Connection, nil] Database connection
+    def initialize(db = nil)
+      @db = db || QueryKit.connection
+    end
+    
+    # Get all records
+    def all
+      @db.get(query, model_class)
+    end
+    
+    # Find a record by ID
+    def find(id)
+      @db.first(query.where('id', id), model_class)
+    end
+    
+    # Find a record by column value
+    def find_by(column, value)
+      @db.first(query.where(column, value), model_class)
+    end
+    
+    # Find multiple records by column value
+    def where(column, operator_or_value, value = nil)
+      if value.nil?
+        # Two arguments: column and value (assumes =)
+        @db.get(query.where(column, operator_or_value), model_class)
+      else
+        # Three arguments: column, operator, value
+        @db.get(query.where(column, operator_or_value, value), model_class)
+      end
+    end
+    
+    # Find records where column is IN array
+    def where_in(column, values)
+      @db.get(query.where_in(column, values), model_class)
+    end
+    
+    # Find records where column is NOT IN array
+    def where_not_in(column, values)
+      @db.get(query.where_not_in(column, values), model_class)
+    end
+    
+    # Get first record matching conditions
+    def first
+      @db.first(query, model_class)
+    end
+    
+    # Count all records
+    def count
+      result = @db.first(query.select('COUNT(*) as count'))
+      result ? result['count'] : 0
+    end
+    
+    # Check if any records exist
+    def exists?(id = nil)
+      if id
+        count_query = query.select('COUNT(*) as count').where('id', id)
+      else
+        count_query = query.select('COUNT(*) as count')
+      end
+      
+      result = @db.first(count_query)
+      result && result['count'] > 0
+    end
+    
+    # Insert a new record
+    # @param attributes [Hash] The attributes for the new record
+    # @return [Integer] The ID of the inserted record
+    def insert(attributes)
+      @db.execute_insert(@db.insert(table_name).values(attributes))
+    end
+    alias_method :create, :insert
+    
+    # Update a record by ID
+    # @param id [Integer] The record ID
+    # @param attributes [Hash] The attributes to update
+    # @return [Integer] Number of affected rows
+    def update(id, attributes)
+      @db.execute_update(@db.update(table_name).set(attributes).where('id', id))
+    end
+    
+    # Delete a record by ID
+    # @param id [Integer] The record ID
+    # @return [Integer] Number of affected rows
+    def delete(id)
+      @db.execute_delete(@db.delete(table_name).where('id', id))
+    end
+    alias_method :destroy, :delete
+    
+    # Delete all records matching conditions
+    # @param conditions [Hash] WHERE conditions
+    # @return [Integer] Number of affected rows
+    def delete_where(conditions)
+      delete_query = @db.delete(table_name)
+      conditions.each { |column, value| delete_query.where(column, value) }
+      @db.execute_delete(delete_query)
+    end
+    
+    # Execute a custom query with model mapping
+    # @param custom_query [QueryKit::Query] A custom query object
+    # @return [Array] Array of model instances
+    def execute(custom_query)
+      @db.get(custom_query, model_class)
+    end
+    
+    # Execute a custom query and return first result
+    # @param custom_query [QueryKit::Query] A custom query object
+    # @return [Object, nil] Model instance or nil
+    def execute_first(custom_query)
+      @db.first(custom_query, model_class)
+    end
+    
+    # Begin a transaction
+    def transaction(&block)
+      @db.transaction(&block)
+    end
+    
+    protected
+    
+    # Get a new query object for this repository's table
+    def query
+      @db.query(table_name)
+    end
+    
+    # Get the table name from class configuration
+    def table_name
+      name = self.class.table_name
+      raise "Table name not configured for #{self.class.name}. Use: table 'table_name'" unless name
+      name
+    end
+    
+    # Get the model class from class configuration
+    def model_class
+      klass = self.class.model_class
+      raise "Model class not configured for #{self.class.name}. Use: model ModelClass" unless klass
+      klass
+    end
+  end
+end

data/lib/querykit/update_query.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module QueryKit
+  # UpdateQuery class for building SQL UPDATE statements.
+  class UpdateQuery
+    attr_reader :table, :values, :wheres, :bindings
+
+    # Initialize a new UpdateQuery instance.
+    def initialize(table = nil)
+      @table = table
+      @values = {}
+      @wheres = []
+      @bindings = []
+    end
+
+    # Set the values to update.
+    def set(data)
+      @values.merge!(data)
+      self
+    end
+
+    # Add a WHERE condition to the update query.
+    def where(column, operator = nil, value = nil)
+      if value.nil? && !operator.nil?
+        value = operator
+        operator = '='
+      end
+
+      @wheres << { type: 'basic', column: column, operator: operator, value: value, boolean: 'AND' }
+      self
+    end
+
+    # Generate the SQL UPDATE statement.
+    def to_sql
+      raise "No table specified" unless @table
+      raise "No values to update" if @values.empty?
+
+      @bindings = @values.values + @wheres.map { |w| w[:value] }
+
+      sql = []
+      sql << "UPDATE #{@table}"
+      sql << "SET"
+      sql << @values.keys.map { |k| "#{k} = ?" }.join(', ')
+
+      unless @wheres.empty?
+        sql << "WHERE"
+        where_clauses = @wheres.map { |w| "#{w[:column]} #{w[:operator]} ?" }
+        sql << where_clauses.join(' AND ')
+      end
+
+      sql.join(' ')
+    end
+
+    # Return the SQL UPDATE statement as a string.
+    def to_s
+      to_sql
+    end
+  end
+end

data/lib/querykit/version.rb

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