async-enumerable 0.1.0

data/lib/async/enumerable/methods/converters.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Async
+  module Enumerable
+    module Methods
+      # Methods that convert enumerables to other types.
+      module Converters
+        def self.included(base) = base.include(Configurable) # Dependency for collection resolution
+
+        # Converts enumerable to array.
+        # @return [Array] Array representation
+        def to_a
+          source = __async_enumerable_collection
+          # If source is self, we need to use super to avoid infinite recursion
+          (source == self) ? super : source.to_a
+        end
+        alias_method :sync, :to_a
+      end
+    end
+  end
+end

data/lib/async/enumerable/methods/each.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Async
+  module Enumerable
+    module Methods
+      module Each
+        def self.included(base)
+          base.include(::Enumerable) # Dependency
+          base.include(ConcurrencyBounder) # Dependency
+          base.include(Configurable) # Dependency for collection resolution
+        end
+
+        # Executes block for each element in parallel.
+        #
+        # This is the core of Async::Enumerable, as most of the enumerable
+        # methods _require_ #each in order to function. This definition of each
+        # is automatically included when `Async::Enumerable` is included, but it
+        # can be overridden by the including class. Here be dragons, though.
+        #
+        # @yield [item] Block to run for each element
+        # @return [self, Enumerator] Self for chaining or Enumerator without block
+        def each(&block)
+          return enum_for(__method__) unless block_given?
+
+          __async_enumerable_bounded_concurrency do |barrier|
+            __async_enumerable_collection.each do |item|
+              barrier.async do
+                block.call(item)
+              end
+            end
+          end
+
+          # Return self to allow chaining, like standard each
+          self
+        end
+      end
+    end
+  end
+end

data/lib/async/enumerable/methods/iterators.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Async
+  module Enumerable
+    module Methods
+      # Iterators module for enumerable iteration helper methods.
+      #
+      # Iteration helper methods are inherited from the standard Enumerable
+      # module. When used with async enumerables, these methods build on our
+      # async #each implementation, though some maintain sequential semantics
+      # where required by their nature.
+      #
+      # Methods available through Enumerable:
+      # - each_with_index: Iterates with index (block executes async)
+      # - each_with_object: Iterates with an accumulator object (block executes async)
+      # - each_cons: Iterates over consecutive n-element slices (maintains order)
+      # - each_slice: Iterates over n-element slices (block executes async per slice)
+      # - cycle: Cycles through elements repeatedly (block executes async)
+      # - with_index: Adds index to any enumerator
+      module Iterators
+        def self.included(base) = base.include(Each) # Dependency
+        # This module is intentionally empty as iteration methods are
+        # inherited from Enumerable
+      end
+    end
+  end
+end

data/lib/async/enumerable/methods/predicates/all.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Async
+  module Enumerable
+    module Methods
+      module Predicates
+        module All
+          def self.included(base)
+            base.include(::Enumerable) # Dependency
+            base.include(Configurable) # Dependency for collection resolution
+            base.include(ConcurrencyBounder) # Dependency
+          end
+
+          # Returns true if all elements satisfy the condition (parallel, early termination).
+          # @yield [item] Test condition for each element
+          # @return [Boolean] true if all elements match
+          def all?(pattern = nil, &block)
+            # Delegate pattern/no-block cases to wrapped enumerable to avoid break issues
+            if pattern
+              return __async_enumerable_collection.all?(pattern)
+            elsif !block_given?
+              return __async_enumerable_collection.all?
+            end
+
+            failed = Concurrent::AtomicBoolean.new(false)
+
+            __async_enumerable_bounded_concurrency(early_termination: true) do |barrier|
+              __async_enumerable_collection.each do |item|
+                break if failed.true?
+
+                barrier.async do
+                  unless block.call(item)
+                    failed.make_true
+                    # Stop the barrier early when we find a failure
+                    barrier.stop
+                  end
+                end
+              end
+            end
+
+            !failed.true?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/async/enumerable/methods/predicates/any.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Async
+  module Enumerable
+    module Methods
+      module Predicates
+        module Any
+          def self.included(base)
+            base.include(::Enumerable) # Dependency
+            base.include(Configurable) # Dependency for collection resolution
+            base.include(ConcurrencyBounder) # Dependency
+          end
+
+          # Returns true if any element satisfies the condition (parallel, early termination).
+          # @yield [item] Test condition for each element
+          # @return [Boolean] true if any element matches
+          def any?(pattern = nil, &block)
+            # Delegate pattern/no-block cases to wrapped enumerable to avoid break issues
+            if pattern
+              return __async_enumerable_collection.any?(pattern)
+            elsif !block_given?
+              return __async_enumerable_collection.any?
+            end
+
+            found = Concurrent::AtomicBoolean.new(false)
+
+            __async_enumerable_bounded_concurrency(early_termination: true) do |barrier|
+              __async_enumerable_collection.each do |item|
+                break if found.true?
+
+                barrier.async do
+                  if block.call(item)
+                    found.make_true
+                    # Stop the barrier early when we find a match
+                    barrier.stop
+                  end
+                end
+              end
+            end
+
+            found.true?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/async/enumerable/methods/predicates/find.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Async
+  module Enumerable
+    module Methods
+      module Predicates
+        module Find
+          def self.included(base)
+            base.include(::Enumerable) # Dependency
+            base.include(Configurable) # Dependency for collection resolution
+            base.include(ConcurrencyBounder) # Dependency
+          end
+
+          # Returns first element that satisfies condition (parallel, early termination).
+          # @note Returns the **fastest completing** match, not necessarily the first by position.
+          #   Due to parallel execution, whichever element completes evaluation first will be returned.
+          #   Use synchronous `find` if positional order matters.
+          # @yield [item] Test condition for each element
+          # @return [Object, nil] First matching element or nil
+          def find(ifnone = nil, &block)
+            return super unless block_given?
+
+            result = Concurrent::AtomicReference.new(nil)
+
+            __async_enumerable_bounded_concurrency(early_termination: true) do |barrier|
+              __async_enumerable_collection.each do |item|
+                break unless result.get.nil?
+
+                barrier.async do
+                  if block.call(item)
+                    # Use compare_and_set to ensure only the first match wins
+                    if result.compare_and_set(nil, item)
+                      # Stop the barrier early when we find a match
+                      barrier.stop
+                    end
+                  end
+                end
+              end
+            end
+
+            found = result.get
+            if found.nil? && ifnone
+              ifnone.call
+            else
+              found
+            end
+          end
+
+          # Alias for find.
+          alias_method :detect, :find
+        end
+      end
+    end
+  end
+end

data/lib/async/enumerable/methods/predicates/find_index.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Async
+  module Enumerable
+    module Methods
+      module Predicates
+        module FindIndex
+          def self.included(base)
+            base.include(::Enumerable) # Dependency
+            base.include(Configurable) # Dependency for collection resolution
+            base.include(ConcurrencyBounder) # Dependency
+          end
+
+          # Returns index of first matching element (parallel, early termination).
+          # @note Returns the index of the **fastest completing** match, not necessarily the first by position.
+          #   Due to parallel execution, whichever element completes evaluation first will have its index returned.
+          #   Use synchronous `find_index` if positional order matters.
+          # @param value [Object] Value to find or omit for block form
+          # @return [Integer, nil] Index of first match or nil
+          def find_index(value = (no_value = true), &block)
+            if no_value && !block_given?
+              return enum_for(__method__)
+            end
+
+            result_index = Concurrent::AtomicReference.new(nil)
+
+            __async_enumerable_bounded_concurrency(early_termination: true) do |barrier|
+              __async_enumerable_collection.each_with_index do |item, index|
+                break unless result_index.get.nil?
+
+                barrier.async do
+                  match = no_value ? block.call(item) : (item == value)
+                  if match
+                    # Use compare_and_set to ensure only the first match wins
+                    if result_index.compare_and_set(nil, index)
+                      # Stop the barrier early when we find a match
+                      barrier.stop
+                    end
+                  end
+                end
+              end
+            end
+
+            result_index.get
+          end
+        end
+      end
+    end
+  end
+end

data/lib/async/enumerable/methods/predicates/include.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Async
+  module Enumerable
+    module Methods
+      module Predicates
+        module Include
+          def self.included(base) = base.include(Any) # Dependency
+
+          # Checks if enumerable includes the object (parallel, early termination).
+          # @param obj Object to search for
+          # @return [Boolean] true if found
+          def include?(obj)
+            any? { |item| item == obj }
+          end
+
+          # Alias for include?.
+          alias_method :member?, :include?
+        end
+      end
+    end
+  end
+end

data/lib/async/enumerable/methods/predicates/none.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Async
+  module Enumerable
+    module Methods
+      module Predicates
+        module None
+          def self.included(base) = base.include(Any) # Dependency
+
+          # Returns true if no elements satisfy the condition (parallel, early termination).
+          # @yield [item] Test condition for each element
+          # @return [Boolean] true if no elements match
+          def none?(pattern = nil, &block)
+            # Delegate pattern/no-block cases to wrapped enumerable to avoid break issues
+            if pattern
+              return __async_enumerable_collection.none?(pattern)
+            elsif !block_given?
+              return __async_enumerable_collection.none?
+            end
+            # For blocks, use our async any? and negate
+            !any?(&block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/async/enumerable/methods/predicates/one.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Async
+  module Enumerable
+    module Methods
+      module Predicates
+        module One
+          def self.included(base)
+            base.include(::Enumerable) # Dependency
+            base.include(Configurable) # Dependency for collection resolution
+            base.include(ConcurrencyBounder) # Dependency
+          end
+
+          # Returns true if exactly one element satisfies the condition (parallel).
+          # @yield [item] Test condition for each element
+          # @return [Boolean] true if exactly one element matches
+          def one?(pattern = nil, &block)
+            # Delegate pattern/no-block cases to wrapped enumerable to avoid break issues
+            if pattern
+              return __async_enumerable_collection.one?(pattern)
+            elsif !block_given?
+              return __async_enumerable_collection.one?
+            end
+
+            count = Concurrent::AtomicFixnum.new(0)
+
+            __async_enumerable_bounded_concurrency(early_termination: true) do |barrier|
+              __async_enumerable_collection.each do |item|
+                break if count.value > 1
+
+                barrier.async do
+                  if block.call(item)
+                    if count.increment > 1
+                      # Stop the barrier early when we have too many matches
+                      barrier.stop
+                    end
+                  end
+                end
+              end
+            end
+
+            count.value == 1
+          end
+        end
+      end
+    end
+  end
+end

data/lib/async/enumerable/methods/predicates.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "async/enumerable/methods/predicates/all"
+require "async/enumerable/methods/predicates/any"
+require "async/enumerable/methods/predicates/find"
+require "async/enumerable/methods/predicates/find_index"
+require "async/enumerable/methods/predicates/include"
+require "async/enumerable/methods/predicates/none"
+require "async/enumerable/methods/predicates/one"
+
+module Async
+  module Enumerable
+    module Methods
+      # Predicates contains async implementations of enumerable predicate methods
+      # that can terminate early when their condition is met or violated.
+      module Predicates
+        def self.included(base)
+          base.include All
+          base.include Any
+          base.include Find
+          base.include FindIndex
+          base.include Include
+          base.include None
+          base.include One
+        end
+      end
+    end
+  end
+end

data/lib/async/enumerable/methods/slicers.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Async
+  module Enumerable
+    module Methods
+      # Slicers module for enumerable slicing and filtering methods.
+      #
+      # Slicing and filtering methods are inherited from the standard Enumerable
+      # module. When used with async enumerables, methods that accept blocks
+      # automatically benefit from parallel execution through our async #each
+      # implementation.
+      #
+      # Methods available through Enumerable:
+      # - drop/drop_while: Drops elements from the beginning (block executes async)
+      # - take/take_while: Takes elements from the beginning (delegated for efficiency)
+      # - grep/grep_v: Filters elements matching/not matching a pattern (block executes async)
+      # - partition: Splits into two arrays based on a predicate (block executes async)
+      # - chunk/chunk_while: Groups consecutive elements (maintains order)
+      # - slice_before/slice_after/slice_when: Slices based on conditions (block executes async)
+      module Slicers
+        def self.included(base)
+          base.include(Each) # Dependency
+          base.include(Configurable) # Dependency for collection resolution
+
+          # Delegate non-parallelizable slicer methods directly to the collection
+          base.extend(Forwardable)
+          base.def_delegators :__async_enumerable_collection, :first, :take, :take_while
+        end
+        # This module is intentionally empty as slicing methods are
+        # inherited from Enumerable and automatically use our async #each
+      end
+    end
+  end
+end

data/lib/async/enumerable/methods/transformers/compact.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Async
+  module Enumerable
+    module Methods
+      module Transformers
+        module Compact
+          def self.included(base) = base.include(Each) # Dependency
+
+          # Async version of compact that returns an Async::Enumerator for chaining
+          def compact
+            Async::Enumerator.new(super, __async_enumerable_config)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/async/enumerable/methods/transformers/filter_map.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Async
+  module Enumerable
+    module Methods
+      module Transformers
+        module FilterMap
+          def self.included(base) = base.include(Each) # Dependency
+
+          # Async version of filter_map that returns an Async::Enumerator for chaining
+          def filter_map(&block)
+            return enum_for(__method__) unless block_given?
+            Async::Enumerator.new(super, __async_enumerable_config)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/async/enumerable/methods/transformers/flat_map.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Async
+  module Enumerable
+    module Methods
+      module Transformers
+        module FlatMap
+          def self.included(base) = base.include(Each) # Dependency
+
+          # Async version of flat_map that returns an Async::Enumerator for chaining
+          def flat_map(&block)
+            return enum_for(__method__) unless block_given?
+            Async::Enumerator.new(super, __async_enumerable_config)
+          end
+          alias_method :collect_concat, :flat_map
+        end
+      end
+    end
+  end
+end

data/lib/async/enumerable/methods/transformers/map.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Async
+  module Enumerable
+    module Methods
+      module Transformers
+        module Map
+          def self.included(base) = base.include(Each) # Dependency
+
+          # Maps elements in parallel, returns async enumerator.
+          # @yield [item] Transform for each element
+          # @return [Async::Enumerator] Transformed collection
+          def map(&block)
+            return enum_for(__method__) unless block_given?
+            Async::Enumerator.new(super, __async_enumerable_config)
+          end
+          alias_method :collect, :map
+        end
+      end
+    end
+  end
+end

data/lib/async/enumerable/methods/transformers/reject.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Async
+  module Enumerable
+    module Methods
+      module Transformers
+        module Reject
+          def self.included(base) = base.include(Each) # Dependency
+
+          # Async version of reject that returns an Async::Enumerator for chaining
+          def reject(&block)
+            return enum_for(__method__) unless block_given?
+            Async::Enumerator.new(super, __async_enumerable_config)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/async/enumerable/methods/transformers/select.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Async
+  module Enumerable
+    module Methods
+      module Transformers
+        module Select
+          def self.included(base) = base.include(Each) # Dependency
+
+          # Async version of select that returns an Async::Enumerator for chaining
+          def select(&block)
+            return enum_for(__method__) unless block_given?
+            Async::Enumerator.new(super, __async_enumerable_config)
+          end
+          alias_method :filter, :select
+          alias_method :find_all, :select
+        end
+      end
+    end
+  end
+end

data/lib/async/enumerable/methods/transformers/sort.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Async
+  module Enumerable
+    module Methods
+      module Transformers
+        module Sort
+          def self.included(base) = base.include(Each) # Dependency
+
+          # Async version of sort that returns an Async::Enumerator for chaining
+          def sort(&block)
+            Async::Enumerator.new(super, __async_enumerable_config)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/async/enumerable/methods/transformers/sort_by.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Async
+  module Enumerable
+    module Methods
+      module Transformers
+        module SortBy
+          def self.included(base) = base.include(Each) # Dependency
+
+          # Async version of sort_by that returns an Async::Enumerator for chaining
+          def sort_by(&block)
+            return enum_for(__method__) unless block_given?
+            Async::Enumerator.new(super, __async_enumerable_config)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/async/enumerable/methods/transformers/uniq.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Async
+  module Enumerable
+    module Methods
+      module Transformers
+        module Uniq
+          def self.included(base) = base.include(Each) # Dependency
+
+          # Async version of uniq that returns an Async::Enumerator for chaining
+          def uniq(&block)
+            Async::Enumerator.new(super, __async_enumerable_config)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/async/enumerable/methods/transformers.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "async/enumerable/methods/transformers/compact"
+require "async/enumerable/methods/transformers/filter_map"
+require "async/enumerable/methods/transformers/flat_map"
+require "async/enumerable/methods/transformers/map"
+require "async/enumerable/methods/transformers/reject"
+require "async/enumerable/methods/transformers/select"
+
+require "async/enumerable/methods/transformers/sort"
+require "async/enumerable/methods/transformers/sort_by"
+require "async/enumerable/methods/transformers/uniq"
+
+module Async
+  module Enumerable
+    module Methods
+      # Transformers contains async implementations of enumerable transformation methods
+      # that transform collections into new collections.
+      module Transformers
+        def self.included(base)
+          base.include Compact
+          base.include FilterMap
+          base.include FlatMap
+          base.include Map
+          base.include Reject
+          base.include Select
+
+          base.include Sort
+          base.include SortBy
+          base.include Uniq
+        end
+      end
+    end
+  end
+end