querykit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: feea6ca48b1ea6f3c73857cce133cc97e557893a483f2eb8938e836530a27a97
+  data.tar.gz: 82d4ea4e022afea3078fde535396f48b6d3abd7934c1e25abb2035e632662450
+SHA512:
+  metadata.gz: 6cae19bde22463189de0f810a2646f8f2f2fe6269bfe0119fe2bb83ea1e7578d77872df929126fea43f8bbd5f79c01690d2d372521ce969fdeb229b590b5a377
+  data.tar.gz: 0173d4cef8f6e875e414858dd5d2d11ada2e09cfd697f48cc5440e2c346e8a7a55d46c17557c937842e5b7db2513bf48e53ebd8e0fee28587e0ee731353ad64c

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## [0.1.0]
+
+### Added
+- Initial release of Quby
+- Fluent query builder for SELECT, INSERT, UPDATE, DELETE
+- WHERE conditions with operators: =, >, <, >=, <=, !=, LIKE
+- WHERE variants: where_in, where_not_in, where_null, where_not_null, where_between, where_raw
+- JOIN support: INNER, LEFT, RIGHT
+- ORDER BY, GROUP BY, HAVING clauses
+- LIMIT, OFFSET, and pagination helpers
+- Database adapters for SQLite3, PostgreSQL, MySQL
+- Transaction support
+- Raw SQL execution

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kiebor81
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,179 @@
+# QueryKit 
+
+A fluent, intuitive query builder and micro-ORM for Ruby inspired by .NET''s SqlKata. Perfect for projects where Active Record feels like overkill.
+
+## Features
+
+- **Zero dependencies** (except database drivers)
+- **Fluent, chainable API** inspired by SqlKata
+- **Multiple database adapters** (SQLite3, PostgreSQL, MySQL)
+- **Comprehensive WHERE clauses** (operators, IN, NULL, BETWEEN, EXISTS, raw SQL)
+- **JOIN support** (INNER, LEFT, RIGHT, CROSS)
+- **Aggregate shortcuts** (count, avg, sum, min, max)
+- **UNION/UNION ALL** for combining queries
+- **Optional model mapping** (Dapper-style)
+- **Optional repository pattern** (C#-style)
+- **Transaction support**
+- **Raw SQL when you need it**
+- **SQL injection protection** via parameterized queries
+
+## Installation
+
+```bash
+
+gem install querykit
+
+```
+
+Then your preferred database driver.
+
+```bash
+# SQLite
+gem install sqlite3
+
+# PostgreSQL
+gem install pg
+
+# MySQL
+gem install mysql2
+```
+## Quick Start
+
+See [`demo.rb`](examples/demo.rb) for more extensive examples.
+
+```ruby
+require_relative 'querykit'
+
+# Configure once
+QueryKit.setup(:sqlite, database: 'app.db')
+
+# Query builder
+users = QueryKit.connection.get(
+  QueryKit.connection.query('users')
+    .where('age', '>', 18)
+    .order_by('name')
+    .limit(10)
+)
+
+# Repository pattern (query scoping)
+class UserRepository < QueryKit::Repository
+  table ''users''
+  model User
+end
+
+repo = UserRepository.new
+user = repo.find(1)
+users = repo.where('age', '>', 18)
+```
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md) - Setup and basic usage
+- [Query Builder](docs/query-builder.md) - SELECT, INSERT, UPDATE, DELETE
+- [Advanced Features](docs/advanced-features.md) - Model mapping, repositories, transactions
+- [API Reference](docs/api-reference.md) - Complete API documentation
+- [Security Best Practices](docs/security.md) - SQL injection protection and safe usage
+- [Concurrency & Thread Safety](docs/concurrency.md) - Multi-threaded usage and connection management
+- [CASE WHEN Extension](docs/extensions/case-when.md) - Optional fluent CASE expressions
+
+**Full documentation site:** https://kiebor81.github.io/querykit
+
+**API documentation (YARD):** Generate locally with `rake doc`
+
+## Why QueryKit?
+
+**vs Active Record:** Much lighter, no DSL, no magic. Just build queries and execute them.
+
+**vs Sequel:** Simpler API, fewer features by design. If you need a full ORM, use Sequel.
+
+**vs Raw SQL:** Type-safe, composable queries with protection against SQL injection.
+
+## Security
+
+QueryKit uses **parameterized queries by default**, protecting against SQL injection when used correctly:
+
+```ruby
+# SAFE - Values are automatically parameterized
+db.query('users').where('email', user_input)
+
+# UNSAFE - Never interpolate user input
+db.raw("SELECT * FROM users WHERE email = '#{user_input}'")
+
+# SAFE - Use placeholders with raw SQL
+db.raw('SELECT * FROM users WHERE email = ?', user_input)
+```
+
+**See [Security Best Practices](docs/security.md) for detailed guidance.**
+
+## Philosophy
+
+- **Minimal dependencies** - Only database drivers required
+- **Simple and explicit** - No hidden magic or metaprogramming
+- **Composable** - Build queries piece by piece
+- **Flexible** - Use what you need, ignore what you don't
+- **Extensible** - Opt-in extensions for advanced features
+
+## Extensions
+
+QueryKit supports optional extensions that add advanced features without bloating the core:
+
+```ruby
+require 'querykit/extensions/case_when'
+
+# Load extensions at startup
+QueryKit.use_extensions(QueryKit::CaseWhenExtension)
+
+# Or load multiple extensions
+QueryKit.use_extensions([Extension1, Extension2])
+```
+
+Available extensions:
+- **CASE WHEN** - Fluent CASE expression builder ([docs](docs/extensions/case-when.md))
+
+Extensions use Ruby's `prepend` to cleanly override methods without monkey-patching.
+
+## What QueryKit Doesn't Do
+
+These features are intentionally excluded to maintain simplicity:
+
+- **Migrations** - Use a dedicated migration tool
+- **Associations** - Write explicit JOINs instead
+- **Validations** - Handle in your business logic layer
+- **Callbacks** - Keep side effects explicit
+- **Soft Deletes** - Implement as a WHERE filter in repositories
+- **Eager Loading** - Use JOINs or accept N+1 queries
+
+For advanced SQL features, use raw SQL:
+
+```ruby
+# Common Table Expressions (CTEs)
+db.raw(<<~SQL, user_id)
+  WITH ranked_orders AS (
+    SELECT *, ROW_NUMBER() OVER (PARTITION BY user_id ORDER BY created_at DESC) as rn
+    FROM orders
+  )
+  SELECT * FROM ranked_orders WHERE rn = 1 AND user_id = ?
+SQL
+
+# Window Functions
+db.raw('SELECT *, AVG(salary) OVER (PARTITION BY department) as dept_avg FROM employees')
+
+# Upsert (SQLite)
+db.raw('INSERT INTO users (id, name) VALUES (?, ?) ON CONFLICT(id) DO UPDATE SET name=excluded.name', id, name)
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+This project adheres to the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
+
+## Acknowledgments
+
+Inspired by [SqlKata](https://sqlkata.com/) (.NET) and [Arel](https://github.com/rails/arel) (Ruby).
+
+## License
+
+This is a personal project, but suggestions and bug reports are welcome via issues.
+
+MIT License - see [LICENSE](LICENSE) for details.

data/lib/querykit/adapters/adapter.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module QueryKit
+  module Adapters
+    # Abstract adapter base class
+    class Adapter
+      def execute(sql, bindings = [])
+        raise NotImplementedError, "#{self.class} must implement #execute"
+      end
+
+      def begin_transaction
+        raise NotImplementedError, "#{self.class} must implement #begin_transaction"
+      end
+
+      def commit
+        raise NotImplementedError, "#{self.class} must implement #commit"
+      end
+
+      def rollback
+        raise NotImplementedError, "#{self.class} must implement #rollback"
+      end
+
+      def close
+        # Optional: Override if adapter needs cleanup
+      end
+    end
+  end
+end

data/lib/querykit/adapters/mysql_adapter.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative 'adapter'
+
+module QueryKit
+  module Adapters
+    class MySQLAdapter < Adapter
+      def initialize(config)
+        require 'mysql2'
+        @client = Mysql2::Client.new(config)
+      end
+
+      def execute(sql, bindings = [])
+        stmt = @client.prepare(sql)
+        @last_result = stmt.execute(*bindings)
+        @last_result.map { |row| row }
+      end
+
+      def last_insert_id
+        @client.last_id
+      end
+
+      def affected_rows
+        @last_result ? @last_result.count : 0
+      end
+
+      def begin_transaction
+        @client.query("START TRANSACTION")
+      end
+
+      def commit
+        @client.query("COMMIT")
+      end
+
+      def rollback
+        @client.query("ROLLBACK")
+      end
+
+      def close
+        @client.close
+      end
+    end
+  end
+end

data/lib/querykit/adapters/postgresql_adapter.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative 'adapter'
+
+module QueryKit
+  module Adapters
+    class PostgreSQLAdapter < Adapter
+      def initialize(config)
+        require 'pg'
+        @conn = PG.connect(config)
+      end
+
+      def execute(sql, bindings = [])
+        # Convert ? placeholders to $1, $2, etc.
+        placeholder_count = 0
+        sql = sql.gsub('?') { |_| "$#{placeholder_count += 1}" }
+        
+        @last_result = @conn.exec_params(sql, bindings)
+        @last_result.map { |row| row }
+      end
+
+      def last_insert_id
+        result = @conn.exec("SELECT lastval()")
+        result[0]['lastval'].to_i
+      rescue PG::Error
+        nil
+      end
+
+      def affected_rows
+        @last_result ? @last_result.cmd_tuples : 0
+      end
+
+      def begin_transaction
+        @conn.exec("BEGIN")
+      end
+
+      def commit
+        @conn.exec("COMMIT")
+      end
+
+      def rollback
+        @conn.exec("ROLLBACK")
+      end
+
+      def close
+        @conn.close
+      end
+    end
+  end
+end

data/lib/querykit/adapters/sqlite_adapter.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative 'adapter'
+
+module QueryKit
+  module Adapters
+    class SQLiteAdapter < Adapter
+      def initialize(database_path)
+        require 'sqlite3'
+        @db = SQLite3::Database.new(database_path)
+        @db.results_as_hash = true
+      end
+
+      def execute(sql, bindings = [])
+        @db.execute(sql, bindings)
+      end
+
+      def last_insert_id
+        @db.last_insert_row_id
+      end
+
+      def affected_rows
+        @db.changes
+      end
+
+      def begin_transaction
+        @db.execute("BEGIN TRANSACTION")
+      end
+
+      def commit
+        @db.execute("COMMIT")
+      end
+
+      def rollback
+        @db.execute("ROLLBACK")
+      end
+
+      def close
+        @db.close
+      end
+    end
+  end
+end

data/lib/querykit/case_builder.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module QueryKit
+  # Builder for CASE WHEN expressions
+  # Used internally by Query when select_case is called
+  class CaseBuilder
+    attr_reader :column, :whens, :else_value, :alias_name
+
+    def initialize(column = nil)
+      @column = column
+      @whens = []
+      @else_value = nil
+      @alias_name = nil
+    end
+
+    # Add a WHEN condition
+    # @param condition [String, Array] Column name or [column, operator, value]
+    # @param operator [String, Object] Operator or value if condition is column name
+    # @param value [Object] Value to compare (only if operator provided)
+    def when(condition, operator = nil, value = nil)
+      if @column && operator.nil?
+        # Simple CASE with column: when('value') -> WHEN ? (comparing against @column)
+        @whens << { value: condition, then: nil }
+      elsif value.nil? && !operator.nil?
+        # when('age', 18) -> WHEN age = 18
+        @whens << { column: condition, operator: '=', value: operator, then: nil }
+      elsif !value.nil?
+        # when('age', '>', 18) -> WHEN age > 18
+        @whens << { column: condition, operator: operator, value: value, then: nil }
+      else
+        # when('age > 18') -> WHEN age > 18 (raw condition)
+        @whens << { raw: condition, then: nil }
+      end
+      self
+    end
+
+    # Set the THEN value for the last WHEN
+    def then(value)
+      raise 'No WHEN clause to add THEN to' if @whens.empty?
+      @whens.last[:then] = value
+      self
+    end
+
+    # Set the ELSE value
+    def else(value)
+      @else_value = value
+      self
+    end
+
+    # Set the alias for the CASE expression
+    def as(alias_name)
+      @alias_name = alias_name
+      self
+    end
+
+    # Build the CASE expression
+    def to_sql
+      raise 'CASE expression must have at least one WHEN clause' if @whens.empty?
+      
+      sql = 'CASE'
+      sql += " #{@column}" if @column
+      
+      @whens.each do |w|
+        if w[:raw]
+          sql += " WHEN #{w[:raw]} THEN ?"
+        elsif @column
+          # Simple CASE: CASE column WHEN value THEN result
+          sql += " WHEN ? THEN ?"
+        else
+          # Searched CASE: CASE WHEN column op value THEN result
+          sql += " WHEN #{w[:column]} #{w[:operator]} ? THEN ?"
+        end
+      end
+      
+      sql += ' ELSE ?' if @else_value
+      sql += ' END'
+      sql += " AS #{@alias_name}" if @alias_name
+      
+      sql
+    end
+
+    # Get bindings for the CASE expression
+    def bindings
+      bindings = []
+      
+      @whens.each do |w|
+        if @column && !w[:raw]
+          # Simple CASE: need value in WHEN clause
+          bindings << w[:value]
+        elsif !w[:raw]
+          # Searched CASE: value goes in condition
+          bindings << w[:value]
+        end
+        bindings << w[:then]
+      end
+      
+      bindings << @else_value if @else_value
+      
+      bindings
+    end
+  end
+end

data/lib/querykit/configuration.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require 'mutex_m'
+
+module QueryKit
+  # Configuration class for global QueryKit settings
+  #
+  # @note This class is used internally by the global configuration methods.
+  #   Most users should use {QueryKit.setup} or {QueryKit.configure} instead.
+  class Configuration
+    attr_accessor :adapter, :connection_options
+
+    def initialize
+      @adapter = nil
+      @connection_options = {}
+    end
+
+    # Configure with adapter and options
+    #
+    # @param adapter [Symbol] the database adapter type
+    # @param options [Hash] connection options
+    # @return [void]
+    def setup(adapter, options = {})
+      @adapter = adapter
+      @connection_options = options
+    end
+
+    # Check if configuration is set
+    #
+    # @return [Boolean] true if adapter is configured
+    def configured?
+      !@adapter.nil?
+    end
+
+    # Validate configuration
+    #
+    # @raise [ConfigurationError] if not configured
+    # @return [void]
+    def validate!
+      raise ConfigurationError, "QueryKit not configured. Call QueryKit.configure first." unless configured?
+    end
+  end
+
+  # Error raised when attempting to use QueryKit without configuration
+  class ConfigurationError < StandardError; end
+
+  class << self
+    # Get the global configuration instance
+    #
+    # @return [Configuration] the global configuration object
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure QueryKit globally
+    #
+    # @yield [Configuration] the configuration object
+    # @return [void]
+    #
+    # @example
+    #   QueryKit.configure do |config|
+    #     config.adapter = :sqlite
+    #     config.connection_options = { database: 'db/app.db' }
+    #   end
+    def configure
+      yield(configuration) if block_given?
+    end
+
+    # Setup with parameters (alternative to configure block)
+    #
+    # @param adapter [Symbol] the database adapter type (:sqlite, :postgresql, :mysql)
+    # @param options [Hash] connection options specific to the adapter
+    # @return [void]
+    #
+    # @example
+    #   QueryKit.setup(:sqlite, database: 'db/app.db')
+    # Setup with parameters (alternative to configure block)
+    #
+    # @param adapter [Symbol] the database adapter type (:sqlite, :postgresql, :mysql)
+    # @param options [Hash] connection options specific to the adapter
+    # @return [void]
+    #
+    # @example
+    #   QueryKit.setup(:sqlite, database: 'db/app.db')
+    def setup(adapter, options = {})
+      configuration.setup(adapter, options)
+    end
+
+    # Get a connection using global configuration
+    #
+    # Creates a singleton connection that is reused across calls.
+    # The connection is lazily initialized on first access.
+    #
+    # @return [QueryKit::Connection] the global connection instance
+    # @raise [ConfigurationError] if QueryKit has not been configured
+    #
+    # @note Thread-safety: The connection singleton creation is thread-safe,
+    #   but individual database operations depend on the underlying adapter's
+    #   thread-safety. SQLite connections should not be shared across threads.
+    #   For multi-threaded applications, create separate connections per thread
+    #   using {QueryKit.connect} instead of using the global connection.
+    #
+    # @example Single-threaded usage (safe)
+    #   QueryKit.setup(:sqlite, database: 'app.db')
+    #   db = QueryKit.connection
+    #   users = db.get(db.query('users'))
+    #
+    # @example Multi-threaded usage (use separate connections)
+    #   threads = 10.times.map do
+    #     Thread.new do
+    #       # Create a new connection per thread
+    #       db = QueryKit.connect(:sqlite, database: 'app.db')
+    #       users = db.get(db.query('users'))
+    #     end
+    #   end
+    #   threads.each(&:join)
+    #
+    # @see QueryKit.connect for creating separate connection instances
+    def connection
+      configuration.validate!
+      
+      # Thread-safe singleton initialization
+      @connection_mutex ||= Mutex.new
+      @connection_mutex.synchronize do
+        @connection ||= begin
+          # Normalize connection options for SQLite (expects string path)
+          config = if configuration.adapter == :sqlite
+            configuration.connection_options[:database] || configuration.connection_options
+          else
+            configuration.connection_options
+          end
+          
+          connect(configuration.adapter, config)
+        end
+      end
+    end
+
+    # Reset configuration (useful for testing)
+    #
+    # Clears the global configuration and connection singleton.
+    #
+    # @return [void]
+    #
+    # @note This method is primarily intended for testing. In production,
+    #   you typically configure once at application startup.
+    #
+    # @example
+    #   QueryKit.setup(:sqlite, database: 'test.db')
+    #   # ... tests ...
+    #   QueryKit.reset!
+    #   QueryKit.setup(:sqlite, database: 'other.db')
+    def reset!
+      @connection_mutex&.synchronize do
+        @connection = nil
+      end
+      @configuration = nil
+      @connection_mutex = nil
+    end
+  end
+end