querykit 0.1.0

data/lib/querykit.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+# QueryKit - A lightweight query builder for Ruby
+# Inspired by SqlKata, built for simplicity
+#
+# @author kiebor81
+# @since 0.1.0
+
+require 'date'
+require 'time'
+
+require_relative 'querykit/version'
+require_relative 'querykit/configuration'
+require_relative 'querykit/query'
+require_relative 'querykit/insert_query'
+require_relative 'querykit/update_query'
+require_relative 'querykit/delete_query'
+require_relative 'querykit/connection'
+require_relative 'querykit/repository'
+require_relative 'querykit/adapters/adapter'
+require_relative 'querykit/adapters/sqlite_adapter'
+require_relative 'querykit/adapters/postgresql_adapter'
+require_relative 'querykit/adapters/mysql_adapter'
+
+# QueryKit is a lightweight, fluent query builder and micro-ORM for Ruby.
+# It provides a clean, chainable API for building SQL queries without the
+# overhead of Active Record.
+#
+# @example Basic usage
+#   db = QueryKit.connect(:sqlite, database: 'app.db')
+#   users = db.get(db.query('users').where('age', '>', 18))
+#
+# @example Using repository pattern
+#   class UserRepository < QueryKit::Repository
+#     table 'users'
+#     model User
+#   end
+#   repo = UserRepository.new(db)
+#   user = repo.find(1)
+module QueryKit
+  # Factory method for creating database connections
+  #
+  # @param adapter_type [Symbol] The type of database adapter to use
+  #   (:sqlite, :postgresql, :postgres, or :mysql)
+  # @param config [Hash, String] Configuration for the adapter. For SQLite,
+  #   can be a string path to the database file or a hash with :database key.
+  #   For PostgreSQL/MySQL, should be a hash with connection parameters.
+  #
+  # @return [Connection] A new database connection instance
+  #
+  # @raise [ArgumentError] if adapter_type is not supported
+  #
+  # @example SQLite connection
+  #   db = QueryKit.connect(:sqlite, database: 'app.db')
+  #   # or
+  #   db = QueryKit.connect(:sqlite, 'app.db')
+  #
+  # @example PostgreSQL connection
+  #   db = QueryKit.connect(:postgresql, 
+  #     host: 'localhost',
+  #     database: 'myapp',
+  #     user: 'postgres',
+  #     password: 'secret'
+  #   )
+  #
+  # @example MySQL connection
+  #   db = QueryKit.connect(:mysql,
+  #     host: 'localhost',
+  #     database: 'myapp',
+  #     username: 'root',
+  #     password: 'secret'
+  #   )
+  def self.connect(adapter_type, config)
+    adapter = case adapter_type
+    when :sqlite
+      Adapters::SQLiteAdapter.new(config)
+    when :postgresql, :postgres
+      Adapters::PostgreSQLAdapter.new(config)
+    when :mysql
+      Adapters::MySQLAdapter.new(config)
+    else
+      raise ArgumentError, "Unknown adapter type: #{adapter_type}. " \
+                           "Supported types: :sqlite, :postgresql, :mysql"
+    end
+
+    Connection.new(adapter)
+  end
+
+  # Load extensions into QueryKit
+  #
+  # Extensions are prepended to the Query class to allow method overrides
+  # and additional functionality. This enables opt-in features while keeping
+  # the core library minimal.
+  #
+  # @param extensions [Module, Array<Module>] One or more extension modules to load
+  #
+  # @return [void]
+  #
+  # @example Load single extension
+  #   require 'querykit/extensions/case_when'
+  #   QueryKit.use_extensions(QueryKit::CaseWhenExtension)
+  #
+  # @example Load multiple extensions
+  #   QueryKit.use_extensions([QueryKit::CaseWhenExtension, MyCustomExtension])
+  def self.use_extensions(*extensions)
+    extensions.flatten.each do |extension|
+      Query.prepend(extension)
+    end
+  end
+end

data/sig/adapters/adapter.rbs

@@ -0,0 +1,14 @@
+module QueryKit
+  module Adapters
+    # Abstract adapter base class
+    class Adapter
+      def execute: (String sql, ?Array[untyped] bindings) -> Array[Hash[String, untyped]]
+      def begin_transaction: () -> void
+      def commit: () -> void
+      def rollback: () -> void
+      def close: () -> void
+      def last_insert_id: () -> Integer
+      def affected_rows: () -> Integer
+    end
+  end
+end

data/sig/adapters/mysql_adapter.rbs

@@ -0,0 +1,15 @@
+module QueryKit
+  module Adapters
+    # MySQL database adapter
+    class MySQLAdapter < Adapter
+      def initialize: (Hash[Symbol, untyped] config) -> void
+      def execute: (String sql, ?Array[untyped] bindings) -> Array[Hash[String, untyped]]
+      def begin_transaction: () -> void
+      def commit: () -> void
+      def rollback: () -> void
+      def close: () -> void
+      def last_insert_id: () -> Integer
+      def affected_rows: () -> Integer
+    end
+  end
+end

data/sig/adapters/postgresql_adapter.rbs

@@ -0,0 +1,15 @@
+module QueryKit
+  module Adapters
+    # PostgreSQL database adapter
+    class PostgreSQLAdapter < Adapter
+      def initialize: (Hash[Symbol, untyped] config) -> void
+      def execute: (String sql, ?Array[untyped] bindings) -> Array[Hash[String, untyped]]
+      def begin_transaction: () -> void
+      def commit: () -> void
+      def rollback: () -> void
+      def close: () -> void
+      def last_insert_id: () -> Integer
+      def affected_rows: () -> Integer
+    end
+  end
+end

data/sig/adapters/sqlite_adapter.rbs

@@ -0,0 +1,15 @@
+module QueryKit
+  module Adapters
+    # SQLite database adapter
+    class SQLiteAdapter < Adapter
+      def initialize: (String | Hash[Symbol, untyped] config) -> void
+      def execute: (String sql, ?Array[untyped] bindings) -> Array[Hash[String, untyped]]
+      def begin_transaction: () -> void
+      def commit: () -> void
+      def rollback: () -> void
+      def close: () -> void
+      def last_insert_id: () -> Integer
+      def affected_rows: () -> Integer
+    end
+  end
+end

data/sig/case_builder.rbs

@@ -0,0 +1,23 @@
+module QueryKit
+  # Builder for SQL CASE expressions
+  class CaseBuilder
+    attr_reader column: String?
+    attr_reader whens: Array[Hash[Symbol, untyped]]
+    attr_reader else_value: untyped
+    attr_reader bindings: Array[untyped]
+
+    def initialize: (?String? column) -> void
+
+    # Add a WHEN condition
+    def when: (untyped condition, ?untyped then_value) -> self
+
+    # Set the ELSE value
+    def else: (untyped value) -> self
+
+    # Set an alias for the CASE expression
+    def as: (String alias_name) -> self
+
+    # Generate SQL
+    def to_sql: () -> String
+  end
+end

data/sig/configuration.rbs

@@ -0,0 +1,22 @@
+module QueryKit
+  # Configuration class for global Quby settings
+  class Configuration
+    attr_accessor adapter: Symbol?
+    attr_accessor connection_options: Hash[Symbol, untyped]
+
+    def initialize: () -> void
+
+    # Configure with adapter and options
+    def setup: (Symbol adapter, Hash[Symbol, untyped] options) -> void
+
+    # Check if configuration is set
+    def configured?: () -> bool
+
+    # Validate configuration
+    def validate!: () -> void
+  end
+
+  # Error raised when attempting to use Quby without configuration
+  class ConfigurationError < StandardError
+  end
+end

data/sig/connection.rbs

@@ -0,0 +1,36 @@
+module QueryKit
+  # Connection class to manage database interactions
+  class Connection
+    attr_reader adapter: Adapters::Adapter
+
+    def initialize: (Adapters::Adapter adapter) -> void
+
+    # Query builder factory methods
+    def query: (?String? table) -> Query
+    def from: (String table) -> Query
+    def table: (String table) -> Query
+
+    # Build query objects
+    def insert: (?String? table) -> InsertQuery
+    def update: (?String? table) -> UpdateQuery
+    def delete: (?String? table) -> DeleteQuery
+
+    # Execute queries
+    def get: (Query query, ?Class? model_class) -> Array[Hash[String, untyped] | untyped]
+    def first: (Query query, ?Class? model_class) -> (Hash[String, untyped] | untyped)?
+    def execute_insert: (InsertQuery query) -> Integer
+    def execute_update: (UpdateQuery query) -> Integer
+    def execute_delete: (DeleteQuery query) -> Integer
+    def execute_scalar: (Query query) -> untyped
+
+    # Raw SQL
+    def raw: (String sql, *untyped bindings, ?model_class: Class?) -> Array[Hash[String, untyped] | untyped]
+
+    # Transaction support
+    def transaction: () { () -> untyped } -> untyped
+
+    private
+
+    def map_to_model: (Hash[String, untyped] row, Class model_class) -> untyped
+  end
+end

data/sig/delete_query.rbs

@@ -0,0 +1,22 @@
+module QueryKit
+  # DeleteQuery class for building DELETE SQL queries
+  class DeleteQuery
+    attr_reader table: String?
+    attr_reader wheres: Array[Hash[Symbol, untyped]]
+    attr_reader bindings: Array[untyped]
+
+    def initialize: (?String? table) -> void
+
+    # Set the table to delete from
+    def from: (String table) -> self
+
+    # WHERE conditions
+    def where: (String column, ?String? operator, ?untyped value) -> self
+    def where_in: (String column, Array[untyped] values) -> self
+    def where_null: (String column) -> self
+
+    # Generate the SQL DELETE statement
+    def to_sql: () -> String
+    def to_s: () -> String
+  end
+end

data/sig/extensions/case_when.rbs

@@ -0,0 +1,10 @@
+module QueryKit
+  # Extension module that adds CASE WHEN support to Query
+  module CaseWhenExtension
+    # Start a CASE expression and return the builder
+    def select_case: (?String? column) -> CaseBuilder
+
+    # Override select to handle CaseBuilder objects
+    def select: (*String | CaseBuilder columns) -> Query
+  end
+end

data/sig/insert_query.rbs

@@ -0,0 +1,19 @@
+module QueryKit
+  # InsertQuery class for building INSERT SQL queries
+  class InsertQuery
+    attr_reader table: String?
+    attr_reader bindings: Array[untyped]
+
+    def initialize: (?String? table) -> void
+
+    # Set the table to insert into
+    def into: (String table) -> self
+
+    # Set the values to insert (also acts as getter via attr_reader in implementation)
+    def values: (Hash[String | Symbol, untyped] | Array[Hash[String | Symbol, untyped]] data) -> self
+
+    # Generate the SQL INSERT statement
+    def to_sql: () -> String
+    def to_s: () -> String
+  end
+end

data/sig/query.rbs

@@ -0,0 +1,83 @@
+module QueryKit
+  # Query builder for constructing SQL SELECT statements
+  class Query
+    attr_reader table: String?
+    attr_reader wheres: Array[Hash[Symbol, untyped]]
+    attr_reader selects: Array[String]
+    attr_reader joins: Array[Hash[Symbol, untyped]]
+    attr_reader orders: Array[String]
+    attr_reader groups: Array[String]
+    attr_reader limit_value: Integer?
+    attr_reader offset_value: Integer?
+    attr_accessor bindings: Array[untyped]
+
+    def initialize: (?String? table) -> void
+
+    # Table methods
+    def from: (String table) -> self
+
+    # SELECT methods
+    def select: (*String columns) -> self
+    def distinct: () -> self
+
+    # WHERE methods
+    def where: (String | Hash[String | Symbol, untyped] column, ?String? operator, ?untyped value) -> self
+    def or_where: (String column, ?String? operator, ?untyped value) -> self
+    def where_in: (String column, Array[untyped] values) -> self
+    def where_not_in: (String column, Array[untyped] values) -> self
+    def where_null: (String column) -> self
+    def where_not_null: (String column) -> self
+    def where_between: (String column, untyped min, untyped max) -> self
+    def where_raw: (String sql, *untyped bindings) -> self
+    def where_exists: (String | Query subquery) -> self
+    def where_not_exists: (String | Query subquery) -> self
+
+    # JOIN methods
+    def join: (String table, String first, ?String? operator, ?String? second) -> self
+    def left_join: (String table, String first, ?String? operator, ?String? second) -> self
+    def right_join: (String table, String first, ?String? operator, ?String? second) -> self
+    def cross_join: (String table) -> self
+
+    # ORDER BY, GROUP BY
+    def order_by: (String column, ?String direction) -> self
+    def group_by: (*String columns) -> self
+    def having: (String condition, *untyped bindings) -> self
+
+    # LIMIT, OFFSET
+    def limit: (Integer count) -> self
+    def offset: (Integer count) -> self
+    def skip: (Integer count) -> self
+    def take: (Integer count) -> self
+
+    # Pagination
+    def page: (Integer page_number, ?Integer per_page) -> self
+    def per_page: (Integer count) -> self
+
+    # Aggregates
+    def count: (?String? column) -> self
+    def sum: (String column) -> self
+    def avg: (String column) -> self
+    def min: (String column) -> self
+    def max: (String column) -> self
+
+    # UNION
+    def union: (Query query) -> self
+    def union_all: (Query query) -> self
+
+    # SQL generation
+    def to_sql: () -> String
+    def to_s: () -> String
+
+    private
+
+    def build_select_clause: () -> String
+    def build_from_clause: () -> String
+    def build_join_clause: () -> String
+    def build_where_clause: () -> String
+    def build_group_by_clause: () -> String
+    def build_having_clause: () -> String
+    def build_order_by_clause: () -> String
+    def build_limit_clause: () -> String
+    def build_union_clause: () -> String
+  end
+end

data/sig/querykit.rbs

@@ -0,0 +1,25 @@
+# Primary module for Quby query builder
+module QueryKit
+  VERSION: String
+
+  # Factory method for creating database connections
+  def self.connect: (Symbol adapter_type, (Hash[Symbol, untyped] | String) config) -> Connection
+
+  # Load extensions into Quby
+  def self.use_extensions: (*Module extensions) -> void
+
+  # Get the global configuration instance
+  def self.configuration: () -> Configuration
+
+  # Configure Quby globally
+  def self.configure: () { (Configuration) -> void } -> void
+
+  # Setup with parameters
+  def self.setup: (Symbol adapter, Hash[Symbol, untyped] options) -> void
+
+  # Get a connection using global configuration
+  def self.connection: () -> Connection
+
+  # Reset configuration
+  def self.reset!: () -> void
+end

data/sig/repository.rbs

@@ -0,0 +1,46 @@
+module QueryKit
+  # Base repository class for implementing the repository pattern
+  class Repository
+    attr_reader db: Connection
+
+    def self.table: (String name) -> void
+    def self.model: (Class klass) -> void
+    def self.table_name: () -> String?
+    def self.model_class: () -> Class?
+
+    def initialize: (?Connection? db) -> void
+
+    # Query methods
+    def all: () -> Array[untyped]
+    def find: (Integer | String id) -> untyped
+    def find_by: (String column, untyped value) -> untyped
+    def where: (String column, String | untyped operator_or_value, ?untyped value) -> Array[untyped]
+    def where_in: (String column, Array[untyped] values) -> Array[untyped]
+    def where_not_in: (String column, Array[untyped] values) -> Array[untyped]
+    def first: () -> untyped
+    def count: () -> Integer
+    def exists?: (?Integer | String? id) -> bool
+
+    # CRUD operations
+    def create: (Hash[String | Symbol, untyped] attributes) -> Integer
+    def insert: (Hash[String | Symbol, untyped] attributes) -> Integer
+    def update: (Integer | String id, Hash[String | Symbol, untyped] attributes) -> Integer
+    def delete: (Integer | String id) -> Integer
+    def destroy: (Integer | String id) -> Integer
+
+    # Bulk operations
+    def delete_all: () -> Integer
+    def update_all: (Hash[String | Symbol, untyped] attributes) -> Integer
+
+    # Advanced queries
+    def order_by: (String column, ?String direction) -> Array[untyped]
+    def limit: (Integer count) -> Array[untyped]
+    def paginate: (Integer page, ?Integer per_page) -> Array[untyped]
+
+    private
+
+    def query: () -> Query
+    def table_name: () -> String
+    def model_class: () -> Class?
+  end
+end

data/sig/update_query.rbs

@@ -0,0 +1,25 @@
+module QueryKit
+  # UpdateQuery class for building UPDATE SQL queries
+  class UpdateQuery
+    attr_reader sets: Hash[String, untyped]
+    attr_reader wheres: Array[Hash[Symbol, untyped]]
+    attr_reader bindings: Array[untyped]
+
+    def initialize: (?String? table) -> void
+
+    # Set the table to update (also acts as getter via attr_reader in implementation)
+    def table: (String table) -> self
+
+    # Set column values
+    def set: (Hash[String | Symbol, untyped] data) -> self
+
+    # WHERE conditions
+    def where: (String column, ?String? operator, ?untyped value) -> self
+    def where_in: (String column, Array[untyped] values) -> self
+    def where_null: (String column) -> self
+
+    # Generate the SQL UPDATE statement
+    def to_sql: () -> String
+    def to_s: () -> String
+  end
+end

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification
+name: querykit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- kiebor81
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2025-12-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.3'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.26'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.26'
+- !ruby/object:Gem::Dependency
+  name: minitest-reporters
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+description: QueryKit is a lightweight query builder and micro-ORM inspired by SqlKata
+  and Dapper, providing a clean, fluent API for building SQL queries without the overhead
+  of Active Record. Perfect for small projects and scripts.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/querykit.rb
+- lib/querykit/adapters/adapter.rb
+- lib/querykit/adapters/mysql_adapter.rb
+- lib/querykit/adapters/postgresql_adapter.rb
+- lib/querykit/adapters/sqlite_adapter.rb
+- lib/querykit/case_builder.rb
+- lib/querykit/configuration.rb
+- lib/querykit/connection.rb
+- lib/querykit/delete_query.rb
+- lib/querykit/extensions/case_when.rb
+- lib/querykit/insert_query.rb
+- lib/querykit/query.rb
+- lib/querykit/repository.rb
+- lib/querykit/update_query.rb
+- lib/querykit/version.rb
+- sig/adapters/adapter.rbs
+- sig/adapters/mysql_adapter.rbs
+- sig/adapters/postgresql_adapter.rbs
+- sig/adapters/sqlite_adapter.rbs
+- sig/case_builder.rbs
+- sig/configuration.rbs
+- sig/connection.rbs
+- sig/delete_query.rbs
+- sig/extensions/case_when.rbs
+- sig/insert_query.rbs
+- sig/query.rbs
+- sig/querykit.rbs
+- sig/repository.rbs
+- sig/update_query.rbs
+homepage: https://github.com/kiebor81/querykit
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/kiebor81/querykit
+  changelog_uri: https://github.com/kiebor81/querykit/blob/main/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.17
+signing_key: 
+specification_version: 4
+summary: Ruby SQL query builder and micro-ORM
+test_files: []