auction_fun_core 0.8.7 → 0.8.9

data/lib/auction_fun_core/operations/auction_context/processor/unpause_operation.rb

@@ -12,7 +12,21 @@ module AuctionFunCore
           include Import["repos.auction_context.auction_repository"]
           include Import["contracts.auction_context.processor.unpause_contract"]
 
-          # @todo Add custom doc
+          ##
+          # Executes the unpause operation with the provided attributes.
+          #
+          # @param attributes [Hash] The attributes for the unpause operation.
+          # @option attributes auction_id [Integer] The ID of the auction.
+          # @yield [Dry::Matcher::Evaluator] The block to handle the result of the operation.
+          # @return [Dry::Matcher::Evaluator] The result of the operation.
+          #
+          # @example
+          #   attributes = { auction_id: 123 }
+          #
+          #   AuctionFunCore::Operations::AuctionContext::Processor::UnpauseOperation.call(attributes) do |result|
+          #     result.success { |auction| puts "Unpaused auction sucessfully! #{auction.to_h}" }
+          #     result.failure { |failure| puts "Failed to unpause auction: #{failure.errors.to_h}"}
+          #   end
           def self.call(attributes, &block)
             operation = new.call(attributes)
 
@@ -21,6 +35,27 @@ module AuctionFunCore
             Dry::Matcher::ResultMatcher.call(operation, &block)
           end
 
+          ##
+          # Performs the unpause of an auction.
+          #
+          # @param attributes [Hash] The attributes for the unpause operation.
+          # @option attributes auction_id [Integer] The ID of the auction.
+          # @return [Dry::Monads::Result::Success, Dry::Monads::Result::Failure] The result of the operation.
+          #
+          # @example
+          #   attributes = { auction_id: 123 }
+          #
+          #   operation = AuctionFunCore::Operations::AuctionContext::Processor::UnpauseOperation.call(attributes)
+          #
+          #   if operation.success?
+          #     auction = operation.success
+          #     puts "Unpaused auction sucessfully! #{auction.to_h}"
+          #   end
+          #
+          #   if operation.failure?
+          #     failure = operation.failure
+          #     puts "Failed to unpause auction: #{failure.errors.to_h}"
+          #   end
           def call(attributes)
             attrs = yield validate(attributes)
 

data/lib/auction_fun_core/relations/auctions.rb

@@ -40,12 +40,30 @@ module AuctionFunCore
       struct_namespace Entities
       auto_struct(true)
 
+      # Retrieves a paginated list of auctions along with related information.
+      # By default, it retrieves the first page with 10 auctions per page and includes information for the top 3 bidders.
+      #
+      # @param page [Integer] The page number to retrieve (default is 1).
+      # @param per_page [Integer] The number of auctions per page (default is 10).
+      # @param options [Hash] Additional options for customization (default is {bidders_count: 3}).
+      # @option options [Integer] :bidders_count The number of top bidders to include in the result (default is 3).
+      # @return [Array<Hash>] An array of hashes representing the auctions and related information.
+      # @example Retrieve the first page of auctions with 10 per page and include information for the top 3 bidders
+      #   all_auctions = all
+      #
+      # @example Retrieve the second page of auctions with 5 per page and include information for the top 5 bidders
+      #   all_auctions = all(2, 5, { bidders_count: 5 })
+      #
+      # @example Retrieve the third page of auctions with 15 per page and include information for the top 2 bidders
+      #   all_auctions = all(3, 15, { bidders_count: 2 })
+      #
+      # @raise [RuntimeError] if either `page` or `per_page` argument is not an integer.
       def all(page = 1, per_page = 10, options = {bidders_count: 3})
         raise "Invalid argument" unless page.is_a?(Integer) && per_page.is_a?(Integer)
 
         offset = ((page - 1) * per_page)
 
-        read("
+        sql = <<-SQL
           SELECT a.id, a.title, a.description, a.kind, a.status, a.started_at, a.finished_at, a.stopwatch, a.initial_bid_cents,
           (SELECT COUNT(*) FROM (SELECT * FROM bids WHERE bids.auction_id = a.id) dt) AS total_bids,
           CASE
@@ -69,17 +87,37 @@ module AuctionFunCore
           WHEN a.kind = 'closed' THEN
             json_build_object('minimal', (a.initial_bid_cents + (a.initial_bid_cents * 0.10))::int)
           END as bids
-        FROM auctions as a
-        LEFT JOIN LATERAL (SELECT * FROM bids WHERE auction_id = a.id ORDER BY value_cents DESC LIMIT #{options[:bidders_count]}) as bi ON a.id = bi.auction_id
-        LEFT JOIN users ON bi.user_id = users.id AND bi.auction_id = a.id
-        GROUP BY a.id
-        LIMIT #{per_page} OFFSET #{offset}")
+          FROM auctions as a
+          LEFT JOIN LATERAL (SELECT * FROM bids WHERE auction_id = a.id ORDER BY value_cents DESC LIMIT #{options[:bidders_count]}) as bi ON a.id = bi.auction_id
+          LEFT JOIN users ON bi.user_id = users.id AND bi.auction_id = a.id
+          GROUP BY a.id
+          LIMIT #{per_page} OFFSET #{offset}
+        SQL
+
+        read(sql)
       end
 
+      # Retrieves detailed information about a specific auction.
+      #
+      # @param auction_id [Integer] The ID of the auction to retrieve information for.
+      # @param options [Hash] Additional options for customization (default is {bidders_count: 3}).
+      # @option options [Integer] :bidders_count The number of top bidders to include in the result (default is 3).
+      # @return [Hash] A hash representing the auction and related information.
+      #
+      # @example Retrieve information for auction with ID 123
+      #   auction_info = info(123)
+      #
+      # @example Retrieve information for auction with ID 456 and include information for the top 5 bidders
+      #   auction_info = info(456, { bidders_count: 5 })
+      #
+      # @example Retrieve information for auction with ID 789 and include information for the top 2 bidders
+      #   auction_info = info(789, { bidders_count: 2 })
+      #
+      # @raise [RuntimeError] if `auction_id` argument is not an integer.
       def info(auction_id, options = {bidders_count: 3})
         raise "Invalid argument" unless auction_id.is_a?(Integer)
 
-        read("
+        sql = <<-SQL
           SELECT a.id, a.title, a.description, a.kind, a.status, a.started_at, a.finished_at, a.stopwatch, a.initial_bid_cents,
           (SELECT COUNT(*) FROM (SELECT * FROM bids WHERE bids.auction_id = #{auction_id}) dt) AS total_bids,
           CASE
@@ -103,11 +141,14 @@ module AuctionFunCore
           WHEN a.kind = 'closed' THEN
             json_build_object('minimal', (a.initial_bid_cents + (a.initial_bid_cents * 0.10))::int)
           END as bids
-        FROM auctions as a
-        LEFT JOIN LATERAL (SELECT * FROM bids WHERE auction_id = a.id ORDER BY value_cents DESC LIMIT #{options[:bidders_count]}) as bi ON a.id = bi.auction_id AND a.id = #{auction_id}
-        LEFT JOIN users ON bi.user_id = users.id AND bi.auction_id = a.id
-        WHERE a.id = #{auction_id}
-        GROUP BY a.id")
+          FROM auctions as a
+          LEFT JOIN LATERAL (SELECT * FROM bids WHERE auction_id = a.id ORDER BY value_cents DESC LIMIT #{options[:bidders_count]}) as bi ON a.id = bi.auction_id AND a.id = #{auction_id}
+          LEFT JOIN users ON bi.user_id = users.id AND bi.auction_id = a.id
+          WHERE a.id = #{auction_id}
+          GROUP BY a.id
+        SQL
+
+        read(sql)
       end
 
       # Retrieves the standard auction winner and other participating bidders for a specified auction.
@@ -125,22 +166,26 @@ module AuctionFunCore
       def load_standard_auction_winners_and_participants(auction_id)
         raise "Invalid argument" unless auction_id.is_a?(Integer)
 
-        read("SELECT a.id, a.kind, a.status, w.user_id AS winner_id, COALESCE(COUNT(b.id), 0) AS total_bids,
-          COALESCE(
-            ARRAY_REMOVE(ARRAY_AGG(DISTINCT b.user_id ORDER BY b.user_id), w.user_id), ARRAY[]::INT[]
-          ) AS participant_ids
-        FROM auctions a
-        LEFT JOIN bids b ON a.id = b.auction_id
-        LEFT JOIN (
-          SELECT auction_id, user_id, MAX(value_cents) AS value_cents
-          FROM bids
-          WHERE auction_id = #{auction_id}
-          GROUP BY auction_id, user_id
-          ORDER BY value_cents DESC
-          LIMIT 1
-        ) AS w ON a.id = w.auction_id
-        WHERE a.id = #{auction_id}
-        GROUP BY a.id, w.user_id")
+        sql = <<-SQL
+          SELECT a.id, a.kind, a.status, w.user_id AS winner_id, COALESCE(COUNT(b.id), 0) AS total_bids,
+            COALESCE(
+              ARRAY_REMOVE(ARRAY_AGG(DISTINCT b.user_id ORDER BY b.user_id), w.user_id), ARRAY[]::INT[]
+            ) AS participant_ids
+          FROM auctions a
+          LEFT JOIN bids b ON a.id = b.auction_id
+          LEFT JOIN (
+            SELECT auction_id, user_id, MAX(value_cents) AS value_cents
+            FROM bids
+            WHERE auction_id = #{auction_id}
+            GROUP BY auction_id, user_id
+            ORDER BY value_cents DESC
+            LIMIT 1
+          ) AS w ON a.id = w.auction_id
+          WHERE a.id = #{auction_id}
+          GROUP BY a.id, w.user_id
+        SQL
+
+        read(sql)
       end
 
       # Retrieves the penny auction winner and other participating bidders for a specified auction.
@@ -158,21 +203,25 @@ module AuctionFunCore
       def load_penny_auction_winners_and_participants(auction_id)
         raise "Invalid argument" unless auction_id.is_a?(Integer)
 
-        read("SELECT a.id, a.kind, a.status, w.user_id AS winner_id, COALESCE(COUNT(b.id), 0) AS total_bids,
-          COALESCE(
-            ARRAY_REMOVE(ARRAY_AGG(DISTINCT b.user_id ORDER BY b.user_id), w.user_id), ARRAY[]::INT[]
-          ) AS participant_ids
-        FROM auctions a
-        LEFT JOIN bids b ON a.id = b.auction_id
-        LEFT JOIN (
-          SELECT auction_id, user_id
-          FROM bids
-          WHERE auction_id = #{auction_id}
-          ORDER BY bids.created_at DESC
-          LIMIT 1
-        ) AS w ON a.id = w.auction_id
-        WHERE a.id = #{auction_id}
-        GROUP BY a.id, w.user_id")
+        sql = <<-SQL
+          SELECT a.id, a.kind, a.status, w.user_id AS winner_id, COALESCE(COUNT(b.id), 0) AS total_bids,
+            COALESCE(
+              ARRAY_REMOVE(ARRAY_AGG(DISTINCT b.user_id ORDER BY b.user_id), w.user_id), ARRAY[]::INT[]
+            ) AS participant_ids
+          FROM auctions a
+          LEFT JOIN bids b ON a.id = b.auction_id
+          LEFT JOIN (
+            SELECT auction_id, user_id
+            FROM bids
+            WHERE auction_id = #{auction_id}
+            ORDER BY bids.created_at DESC
+            LIMIT 1
+          ) AS w ON a.id = w.auction_id
+          WHERE a.id = #{auction_id}
+          GROUP BY a.id, w.user_id
+        SQL
+
+        read(sql)
       end
 
       # Retrieves the closed auction winner and other participating bidders for a specified auction.
@@ -190,70 +239,102 @@ module AuctionFunCore
       def load_closed_auction_winners_and_participants(auction_id)
         raise "Invalid argument" unless auction_id.is_a?(Integer)
 
-        read("SELECT a.id, a.kind, a.status, w.user_id AS winner_id, COALESCE(COUNT(b.id), 0) AS total_bids,
-          COALESCE(
-            ARRAY_REMOVE(ARRAY_AGG(DISTINCT b.user_id ORDER BY b.user_id), w.user_id), ARRAY[]::INT[]
-          ) AS participant_ids
-        FROM auctions a
-        LEFT JOIN bids b ON a.id = b.auction_id
-        LEFT JOIN (
-          SELECT auction_id, user_id, MAX(value_cents) AS value_cents
-          FROM bids
-          WHERE auction_id = #{auction_id}
-          GROUP BY auction_id, user_id
-          ORDER BY value_cents DESC
-          LIMIT 1
-        ) AS w ON a.id = w.auction_id
-        WHERE a.id = #{auction_id}
-        GROUP BY a.id, w.user_id")
+        sql = <<-SQL
+          SELECT a.id, a.kind, a.status, w.user_id AS winner_id, COALESCE(COUNT(b.id), 0) AS total_bids,
+            COALESCE(
+              ARRAY_REMOVE(ARRAY_AGG(DISTINCT b.user_id ORDER BY b.user_id), w.user_id), ARRAY[]::INT[]
+            ) AS participant_ids
+          FROM auctions a
+          LEFT JOIN bids b ON a.id = b.auction_id
+          LEFT JOIN (
+            SELECT auction_id, user_id, MAX(value_cents) AS value_cents
+            FROM bids
+            WHERE auction_id = #{auction_id}
+            GROUP BY auction_id, user_id
+            ORDER BY value_cents DESC
+            LIMIT 1
+          ) AS w ON a.id = w.auction_id
+          WHERE a.id = #{auction_id}
+          GROUP BY a.id, w.user_id
+        SQL
+
+        read(sql)
       end
 
+      # Loads statistics for the winner of a specific auction.
+      #
+      # @param auction_id [Integer] The ID of the auction to load statistics for.
+      # @param winner_id [Integer] The ID of the winner to load statistics for.
+      # @return [Hash] A hash representing the statistics for the winner of the auction.
+      #
+      # @example Load statistics for the winner of auction with ID 123 and winner with ID 456
+      #   winner_stats = load_winner_statistics(123, 456)
+      #
+      # @raise [RuntimeError] if either `auction_id` or `winner_id` arguments are not integers.
       def load_winner_statistics(auction_id, winner_id)
         raise "Invalid argument" unless auction_id.is_a?(Integer) && winner_id.is_a?(Integer)
 
-        read("SELECT a.id, COUNT(b.id) AS auction_total_bids, MAX(b.value_cents) AS winner_bid,
-          date(a.finished_at) as auction_date,
-          (SELECT COUNT(*) FROM bids b2
-            WHERE b2.auction_id = #{auction_id}
-            AND b2.user_id = #{winner_id}
-          ) AS winner_total_bids
-        FROM auctions a
-        LEFT JOIN bids b ON a.id = b.auction_id AND a.id = #{auction_id}
-        LEFT JOIN users u ON u.id = b.user_id AND u.id = #{winner_id}
-        LEFT JOIN (
-          SELECT auction_id, user_id, MAX(value_cents) AS value_cents
-          FROM bids
-          WHERE auction_id = #{auction_id}
-          GROUP BY auction_id, user_id
-          ORDER BY value_cents DESC
-          LIMIT 1
-        ) AS w ON a.id = w.auction_id
-        WHERE a.id = #{auction_id}
-        GROUP BY a.id")
+        sql = <<-SQL
+          SELECT a.id, COUNT(b.id) AS auction_total_bids, MAX(b.value_cents) AS winner_bid,
+            date(a.finished_at) as auction_date,
+            (SELECT COUNT(*) FROM bids b2
+              WHERE b2.auction_id = #{auction_id}
+              AND b2.user_id = #{winner_id}
+            ) AS winner_total_bids
+          FROM auctions a
+          LEFT JOIN bids b ON a.id = b.auction_id AND a.id = #{auction_id}
+          LEFT JOIN users u ON u.id = b.user_id AND u.id = #{winner_id}
+          LEFT JOIN (
+            SELECT auction_id, user_id, MAX(value_cents) AS value_cents
+            FROM bids
+            WHERE auction_id = #{auction_id}
+            GROUP BY auction_id, user_id
+            ORDER BY value_cents DESC
+            LIMIT 1
+          ) AS w ON a.id = w.auction_id
+          WHERE a.id = #{auction_id}
+          GROUP BY a.id
+        SQL
+
+        read(sql)
       end
 
+      # Loads statistics for a participant in a specific auction.
+      #
+      # @param auction_id [Integer] The ID of the auction to load statistics for.
+      # @param participant_id [Integer] The ID of the participant to load statistics for.
+      # @return [Hash] A hash representing the statistics for the participant in the auction.
+      #
+      # @example Load statistics for the participant with ID 456 in auction with ID 123
+      #   participant_stats = load_participant_statistics(123, 456)
+      #
+      # @raise [RuntimeError] if either `auction_id` or `participant_id` arguments are not integers.
       def load_participant_statistics(auction_id, participant_id)
         raise "Invalid argument" unless auction_id.is_a?(Integer) && participant_id.is_a?(Integer)
 
-        read("SELECT a.id, COUNT(b.id) AS auction_total_bids, MAX(b.value_cents) AS winner_bid,
-          date(a.finished_at) as auction_date,
-          (SELECT COUNT(*) FROM bids b2
-            WHERE b2.auction_id = #{auction_id}
-            AND b2.user_id = #{participant_id}
-          ) AS winner_total_bids
-        FROM auctions a
-        LEFT JOIN bids b ON a.id = b.auction_id AND a.id = #{auction_id}
-        LEFT JOIN users u ON u.id = b.user_id AND u.id = #{participant_id}
-        LEFT JOIN (
-          SELECT auction_id, user_id, MAX(value_cents) AS value_cents
-          FROM bids
-          WHERE auction_id = #{auction_id}
-          GROUP BY auction_id, user_id
-          ORDER BY value_cents DESC
-          LIMIT 1
-        ) AS w ON a.id = w.auction_id
-        WHERE a.id = #{auction_id}
-        GROUP BY a.id")
+        sql = <<-SQL
+          SELECT a.id, COUNT(b.id) AS auction_total_bids, MAX(b.value_cents) AS winner_bid,
+            date(a.finished_at) as auction_date,
+            (SELECT COUNT(*) FROM bids b2
+              WHERE b2.auction_id = #{auction_id}
+              AND b2.user_id = #{participant_id}
+            ) AS winner_total_bids
+          FROM auctions a
+          LEFT JOIN bids b ON a.id = b.auction_id AND a.id = #{auction_id}
+          LEFT JOIN users u ON u.id = b.user_id AND u.id = #{participant_id}
+          LEFT JOIN (
+            SELECT auction_id, user_id, MAX(value_cents) AS value_cents
+            FROM bids
+            WHERE auction_id = #{auction_id}
+            GROUP BY auction_id, user_id
+            ORDER BY value_cents DESC
+            LIMIT 1
+          ) AS w ON a.id = w.auction_id
+          WHERE a.id = #{auction_id}
+          GROUP BY a.id
+        SQL
+
+        read(sql)
       end
     end
   end

data/lib/auction_fun_core/relations/bids.rb

@@ -23,6 +23,24 @@ module AuctionFunCore
 
       struct_namespace Entities
       auto_struct(true)
+
+      # Retrieves a list of unique user IDs who have placed bids in a specified auction.
+      # A participant in an auction is defined as a user who has placed one or more bids.
+      #
+      # @param auction_id [Integer] the ID of the auction.
+      # @return [Array<Integer>] Returns an array of unique user IDs who have participated in the auction.
+      # @raise [RuntimeError] Raises an error if the auction_id is not an integer.
+      def participants(auction_id)
+        raise "Invalid argument" unless auction_id.is_a?(Integer)
+
+        sql = <<-SQL
+          SELECT COALESCE(ARRAY_AGG(DISTINCT user_id), ARRAY[]::INT[]) AS participant_ids
+          FROM bids
+          WHERE auction_id = #{auction_id}
+        SQL
+
+        read(sql)
+      end
     end
   end
 end

data/lib/auction_fun_core/repos/auction_context/auction_repository.rb

@@ -3,7 +3,30 @@
 module AuctionFunCore
   module Repos
     module AuctionContext
-      # SQL repository for auctions.
+      # Repository for handling repository operations related to auctions.
+      #
+      # This repository provides methods to interact with auction data in the database,
+      # including creating, updating, deleting, and retrieving auctions.
+      #
+      # @example
+      #   auction_repo = AuctionFunCore::Repos::AuctionContext::AuctionRepository.new
+      #
+      #   # Retrieve all auctions
+      #   all_auctions = auction_repo.all
+      #
+      #   # Get the total number of auctions
+      #   total_auctions = auction_repo.count
+      #
+      #   # Find an auction by its ID
+      #   auction = auction_repo.by_id(123)
+      #
+      #   # Find an auction by its ID and raise an error if not found
+      #   auction = auction_repo.by_id!(123)
+      #
+      # @see AuctionFunCore::Entities::Auction Struct representing auction data
+      # @see https://rom-rb.org/learn/sql/3.3/queries/
+      # @see https://api.rom-rb.org/rom-sql/ROM/SQL/Relation/Reading
+      #
       class AuctionRepository < ROM::Repository[:auctions]
         include Import["container"]
 
@@ -11,28 +34,34 @@ module AuctionFunCore
         commands :create, update: :by_pk, delete: :by_pk
 
         # Returns all auctions in the database.
-        # @return [Array<ROM::Struct::Auction>, []]
+        # @return [Array<ROM::Struct::Auction>]
         def all
           auctions.to_a
         end
 
-        # Returns the total number of auctions in database.
-        # @return [Integer]
+        # Returns the total number of auctions in the database.
+        #
+        # @return [Integer] Total number of auctions.
+        #
         def count
           auctions.count
         end
 
-        # Search auction in database by primary key.
-        # @param id [Integer] Auction ID
-        # @return [ROM::Struct::Auction, nil]
+        # Retrieves an auction from the database by its primary key.
+        #
+        # @param id [Integer] The ID of the auction to retrieve.
+        # @return [ROM::Struct::Auction, nil] The retrieved auction, or nil if not found.
+        #
         def by_id(id)
           auctions.by_pk(id).one
         end
 
-        # Search auction in database by primary key.
-        # @param id [Integer] Auction ID
-        # @raise [ROM::TupleCountMismatchError] if not found on database
-        # @return [ROM::Struct::Auction]
+        # Retrieves an auction from the database by its primary key, raising an error if not found.
+        #
+        # @param id [Integer] The ID of the auction to retrieve.
+        # @raise [ROM::TupleCountMismatchError] if the auction is not found.
+        # @return [ROM::Struct::Auction] The retrieved auction.
+        #
         def by_id!(id)
           auctions.by_pk(id).one!
         end

data/lib/auction_fun_core/repos/bid_context/bid_repository.rb

@@ -3,21 +3,43 @@
 module AuctionFunCore
   module Repos
     module BidContext
-      # SQL repository for bids.
+      # Repository for handling repository operations related to bids.
+      #
+      # This repository provides methods to interact with bid data in the database,
+      # including creating, updating, deleting, and retrieving bids.
+      #
+      # @example
+      #   bid_repo = AuctionFunCore::Repos::BidContext::BidRepository.new
+      #
+      #   # Get the total number of bids
+      #   total_bids = bid_repo.count
+      #
+      #   # Checks if a bid exists based on the provided conditions.
+      #   bid_repo.exists?(id: 123)
+      #
+      # @see AuctionFunCore::Entities::Bid Struct representing bid data
+      # @see https://rom-rb.org/learn/sql/3.3/queries/
+      # @see https://api.rom-rb.org/rom-sql/ROM/SQL/Relation/Reading
+      #
       class BidRepository < ROM::Repository[:bids]
         include Import["container"]
 
         struct_namespace Entities
         commands :create, update: :by_pk, delete: :by_pk
 
-        # Returns the total number of bids in database.
-        # @return [Integer]
+        # Returns the total number of bids in the database.
+        #
+        # @return [Integer] Total number of bids.
+        #
         def count
           bids.count
         end
 
-        # @param conditions [Hash] DSL Dataset
-        # @return [Boolean]
+        # Checks if a bid exists based on the provided conditions.
+        #
+        # @param conditions [Hash] The conditions to check (DSL Dataset).
+        # @return [Boolean] true if a bid exists that matches the conditions, otherwise false.
+        #
         def exists?(conditions)
           bids.exist?(conditions)
         end