auction_fun_core 0.8.5 → 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/operations/bid_context/create_bid_penny_operation.rb

@@ -7,8 +7,10 @@ module AuctionFunCore
       # Operation class for create new bids for penny auctions.
       #
       class CreateBidPennyOperation < AuctionFunCore::Operations::Base
-        include Import["contracts.bid_context.create_bid_penny_contract"]
         include Import["repos.bid_context.bid_repository"]
+        include Import["repos.auction_context.auction_repository"]
+        include Import["contracts.bid_context.create_bid_penny_contract"]
+        include Import["workers.operations.auction_context.processor.finish.penny_operation_job"]
 
         # @todo Add custom doc
         def self.call(attributes, &block)
@@ -21,10 +23,13 @@ module AuctionFunCore
 
         # @todo Add custom doc
         def call(attributes)
-          values = yield validate(attributes)
+          auction, values = yield validate_contract(attributes)
 
           bid_repository.transaction do |_t|
             @bid = yield persist(values)
+            updated_auction = yield update_end_auction(auction)
+
+            yield reschedule_end_auction(updated_auction)
             yield publish_bid_created(@bid)
           end
 
@@ -35,19 +40,42 @@ module AuctionFunCore
         # of the informed attributes.
         # @param attrs [Hash] bid attributes
         # @return [Dry::Monads::Result::Success, Dry::Monads::Result::Failure]
-        def validate(attrs)
+        def validate_contract(attrs)
           contract = create_bid_penny_contract.call(attrs)
 
           return Failure(contract.errors.to_h) if contract.failure?
 
-          Success(contract.to_h)
+          Success([contract.context[:auction], contract.to_h])
+        end
+
+        # Updates the end time of an auction if it has already started.
+        #
+        # This method checks whether an auction is currently running. If the auction is running,
+        # it calculates a new end time based on the current time and the duration specified
+        # by the auction's stopwatch. The auction's finish time is then updated in the repository.
+        # If the auction has not started, it returns the auction as is without any modifications.
+        #
+        # @param auction [ROM::Struct::Auction] An instance of Auction to be checked and potentially updated.
+        # @return [Dry::Monads::Result::Success<ROM::Struct::Auction>, Dry::Monads::Result::Failure]
+        def update_end_auction(auction)
+          return Success(auction) unless started_auction?(auction)
+
+          updated_attributes = {
+            finished_at: Time.current + auction.stopwatch.seconds,
+            kind: auction.kind,
+            status: auction.status
+          }
+
+          updated_auction, _ = auction_repository.update(auction.id, updated_attributes)
+
+          Success(updated_auction)
         end
 
         # Calls the bid repository class to persist the attributes in the database.
         # @param result [Hash] Bid validated attributes
-        # @return [ROM::Struct::Bid]
-        def persist(result)
-          Success(bid_repository.create(result))
+        # @return [Dry::Monads::Result::Success<ROM::Struct::Bid>, Dry::Monads::Result::Failure]
+        def persist(values)
+          Success(bid_repository.create(values))
         end
 
         # Triggers the publication of event *bids.created*.
@@ -58,6 +86,28 @@ module AuctionFunCore
 
           Success()
         end
+
+        # TODO: Added a small delay to perform operations (such as sending broadcasts and/or other operations).
+        # Reschedules the end time of an auction's background job if the auction has already started.
+        #
+        # This method checks if the auction is running. If so, it schedules a background job to
+        # execute at the auction's current finish time using the job class defined by the
+        # penny_operation_job attribute of the auction. If the auction has not started, it
+        # simply returns a Success object with no parameters.
+        #
+        # @return [Dry::Monads::Result::Success<ROM::Struct::Auction>, Dry::Monads::Result::Success<String>]
+        def reschedule_end_auction(auction)
+          # binding.pry
+          return Success(auction) unless started_auction?(auction)
+
+          perform_at = auction.finished_at
+
+          Success(penny_operation_job.class.perform_at(perform_at, auction.id))
+        end
+
+        def started_auction?(auction)
+          auction.status == "running"
+        end
       end
     end
   end

data/lib/auction_fun_core/operations/staff_context/registration_operation.rb

@@ -21,6 +21,7 @@ module AuctionFunCore
         # @todo Add custom doc
         def call(attributes)
           values = yield validate_contract(attributes)
+          values = yield assign_default_values(values)
           values_with_encrypt_password = yield encrypt_password(values)
 
           staff_repository.transaction do |_t|
@@ -44,6 +45,15 @@ module AuctionFunCore
           Success(contract.to_h)
         end
 
+        # By default, there can only be a single root staff. All other members have their type set to 'common'.
+        # @param attrs [Hash] user attributes
+        # @return [Dry::Monads::Result::Success]
+        def assign_default_values(attrs)
+          attrs[:kind] = "common"
+
+          Success(attrs)
+        end
+
         # Transforms the password attribute, encrypting it to be saved in the database.
         # @param result [Hash] Staff valid contract attributes
         # @return [Hash] Valid staff database

data/lib/auction_fun_core/relations/auctions.rb

@@ -7,13 +7,13 @@ module AuctionFunCore
     class Auctions < ROM::Relation[:sql]
       use :pagination, per_page: 10
 
-      KINDS = Types::Coercible::String.default("standard").enum("standard", "penny", "closed")
-      STATUSES = Types::Coercible::String.default("scheduled")
-        .enum("scheduled", "running", "paused", "canceled", "finished")
+      KINDS = Types::Coercible::String.enum("standard", "penny", "closed")
+      STATUSES = Types::Coercible::String.enum("scheduled", "running", "paused", "canceled", "finished")
 
       schema(:auctions, infer: true) do
         attribute :id, Types::Integer
         attribute :staff_id, Types::ForeignKey(:staffs)
+        attribute :winner_id, Types::ForeignKey(:users)
         attribute :title, Types::String
         attribute :description, Types::String
         attribute :kind, KINDS
@@ -32,6 +32,7 @@ module AuctionFunCore
 
         associations do
           belongs_to :staff, as: :staff, relation: :staffs
+          belongs_to :winner, as: :winner, relation: :users, foreign_key: :winner_id
           has_many :bids, as: :bids, relation: :bids
         end
       end
@@ -39,23 +40,32 @@ 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})
-        offset = ((page - 1) * per_page)
-
-        read(all_auctions_with_bid_info(per_page, offset, options))
-      end
-
-      def info(auction_id, options = {bidders_count: 3})
-        raise "Invalid argument" unless auction_id.is_a?(Integer)
+        raise "Invalid argument" unless page.is_a?(Integer) && per_page.is_a?(Integer)
 
-        read(auction_with_bid_info(auction_id, options))
-      end
-
-      private
+        offset = ((page - 1) * per_page)
 
-      def auction_with_bid_info(auction_id, options = {bidders_count: 3})
-        "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,
+        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
           WHEN a.kind = 'standard' THEN
             json_build_object(
@@ -77,16 +87,39 @@ 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
+          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
 
-      def all_auctions_with_bid_info(per_page, offset, options = {bidders_count: 3})
-        "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,
+      # 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)
+
+        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
           WHEN a.kind = 'standard' THEN
             json_build_object(
@@ -108,11 +141,200 @@ 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 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.
+      #
+      # This method queries the database to fetch the winner based on the highest bid and collects an array
+      # of other participants who placed bids in the auction, all except for the winner. The method returns
+      # structured data that includes the auction ID, winner's ID, total number of bids,
+      # and a list of participant IDs.
+      #
+      # @return [Hash] a hash containing details about the auction, including winner and participants:
+      #   - :id [Integer] the ID of the auction
+      #   - :winner_id [Integer] the ID of the winning bidder
+      #   - :total_bids [Integer] the total number of bids placed in the auction
+      #   - :participants [Array<Integer>] an array of user IDs of the other participants, excluding the winner
+      def load_standard_auction_winners_and_participants(auction_id)
+        raise "Invalid argument" unless auction_id.is_a?(Integer)
+
+        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.
+      #
+      # This method queries the database to fetch the winner based on the latest bid and collects an array
+      # of other participants who placed bids in the auction, all except for the winner. The method returns
+      # structured data that includes the auction ID, winner's ID, total number of bids,
+      # and a list of participant IDs.
+      #
+      # @return [Hash] a hash containing details about the auction, including winner and participants:
+      #   - :id [Integer] the ID of the auction
+      #   - :winner_id [Integer] the ID of the winning bidder
+      #   - :total_bids [Integer] the total number of bids placed in the auction
+      #   - :participants [Array<Integer>] an array of user IDs of the other participants, excluding the winner
+      def load_penny_auction_winners_and_participants(auction_id)
+        raise "Invalid argument" unless auction_id.is_a?(Integer)
+
+        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.
+      #
+      # This method queries the database to fetch the winner based on the highest bid and collects an array
+      # of other participants who placed bids in the auction, all except for the winner. The method returns
+      # structured data that includes the auction ID, winner's ID, total number of bids,
+      # and a list of participant IDs.
+      #
+      # @return [Hash] a hash containing details about the auction, including winner and participants:
+      #   - :id [Integer] the ID of the auction
+      #   - :winner_id [Integer] the ID of the winning bidder
+      #   - :total_bids [Integer] the total number of bids placed in the auction
+      #   - :participants [Array<Integer>] an array of user IDs of the other participants, excluding the winner
+      def load_closed_auction_winners_and_participants(auction_id)
+        raise "Invalid argument" unless auction_id.is_a?(Integer)
+
+        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)
+
+        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)
+
+        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/relations/staffs.rb

@@ -7,7 +7,7 @@ module AuctionFunCore
     class Staffs < ROM::Relation[:sql]
       use :pagination, per_page: 10
 
-      STAFF_KINDS = Types::Coercible::String.default("common").enum("root", "common")
+      STAFF_KINDS = Types::Coercible::String.enum("root", "common")
 
       schema(:staffs, infer: true) do
         attribute :id, Types::Integer

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