async-enumerable 0.1.0

data/docs/reference/methods/converters.md

@@ -0,0 +1,97 @@
+# Converter Methods
+
+Converter methods transform async enumerables into other data types, typically arrays.
+
+## to_a
+
+Converts the wrapped enumerable to an array.
+
+This method simply converts the wrapped enumerable to an array without any async processing. Note that async operations like map and select already return arrays internally.
+
+### Returns
+`Array` - The wrapped enumerable converted to an array
+
+### Examples
+
+```ruby
+# Basic conversion
+async_enum = (1..3).async
+async_enum.to_a  # => [1, 2, 3]
+
+# Converting a Set
+async_set = Set[1, 2, 3].async
+async_set.to_a  # => [1, 2, 3] (order may vary)
+
+# After transformations
+[1, 2, 3].async.map { |n| n * 2 }.to_a  # => [2, 4, 6]
+```
+
+### Implementation Notes
+- Uses `enumerable_source` to get the appropriate source
+- Handles self-referential sources to avoid infinite recursion
+- Delegates to the source's `to_a` method
+
+## sync
+
+Synchronizes the async enumerable back to a regular array. This is an alias for `to_a` that provides a more semantic way to end an async chain and get the results.
+
+### Returns
+`Array` - The wrapped enumerable converted to an array
+
+### Examples
+
+```ruby
+# Chaining with sync
+result = [:foo, :bar].async
+                     .map { |sym| fetch_data(sym) }
+                     .sync
+# => [<data for :foo>, <data for :bar>]
+
+# Alternative to to_a
+data.async.select { |x| x.valid? }.sync  # same as .to_a
+
+# Complete async pipeline
+[1, 2, 3, 4, 5].async
+  .map { |n| expensive_operation(n) }
+  .select { |result| result.success? }
+  .map { |result| result.value }
+  .sync  # Materializes final results
+```
+
+### Why Use sync?
+
+The `sync` method provides semantic clarity:
+- `to_a` implies conversion to array format
+- `sync` implies waiting for async operations to complete and collecting results
+- Both do the same thing, but `sync` better expresses intent in async contexts
+
+## Usage Patterns
+
+### Basic Conversion
+```ruby
+# Simple enumerable to array
+(1..5).async.to_a  # => [1, 2, 3, 4, 5]
+```
+
+### After Async Operations
+```ruby
+# Process data asynchronously, then collect results
+urls.async
+  .map { |url| fetch_data(url) }
+  .select { |data| data.valid? }
+  .sync  # Get final array of valid data
+```
+
+### With Custom Enumerables
+```ruby
+class MyCollection
+  include Enumerable
+  def each
+    yield 1
+    yield 2
+    yield 3
+  end
+end
+
+MyCollection.new.async.to_a  # => [1, 2, 3]
+```

data/docs/reference/methods/predicates.md

@@ -0,0 +1,254 @@
+# Predicate Methods
+
+Predicate methods test elements in the enumerable and return boolean values. All async predicate methods support early termination - they stop processing as soon as the result is determined.
+
+## any?
+
+Asynchronously checks if any element satisfies the given condition.
+
+Executes the block for each element in parallel and returns true as soon as any element returns a truthy value. Short-circuits and stops processing remaining elements once a match is found.
+
+### Parameters
+- `pattern` (optional): Pattern to match against elements
+- `&block`: Block to test each element
+
+### Returns
+`Boolean` - true if any element satisfies the condition, false otherwise
+
+### Examples
+
+```ruby
+# Check if any number is negative
+[1, 2, -3].async.any? { |n| n < 0 }  # => true (stops after -3)
+[1, 2, 3].async.any? { |n| n < 0 }   # => false
+
+# With API calls
+servers.async.any? { |server| server_responding?(server) }
+# Checks all servers in parallel, returns true on first response
+```
+
+### Implementation Notes
+- Uses `Concurrent::AtomicBoolean` for thread-safe early termination
+- Delegates pattern/no-block cases to wrapped enumerable to avoid break issues
+- Stops barrier execution as soon as a match is found
+
+## all?
+
+Asynchronously checks if all elements satisfy the given condition.
+
+Executes the block for each element in parallel and returns false as soon as any element returns a falsy value. Short-circuits and stops processing remaining elements once a non-match is found.
+
+### Parameters
+- `pattern` (optional): Pattern to match against elements
+- `&block`: Block to test each element
+
+### Returns
+`Boolean` - true if all elements satisfy the condition, false otherwise
+
+### Examples
+
+```ruby
+# Check if all numbers are positive
+[1, 2, 3].async.all? { |n| n > 0 }  # => true
+[1, -2, 3].async.all? { |n| n > 0 } # => false (stops after -2)
+
+# With validation
+forms.async.all? { |form| validate_form(form) }
+# Validates all forms in parallel, returns false on first invalid
+```
+
+### Implementation Notes
+- Uses `Concurrent::AtomicBoolean` to track if any element fails the test
+- Delegates pattern/no-block cases to wrapped enumerable
+- Stops barrier execution as soon as a non-match is found
+
+## none?
+
+Asynchronously checks if no elements satisfy the given condition.
+
+Executes the block for each element in parallel and returns false as soon as any element returns a truthy value. Short-circuits and stops processing remaining elements once a match is found.
+
+### Parameters
+- `pattern` (optional): Pattern to match against elements
+- `&block`: Block to test each element
+
+### Returns
+`Boolean` - true if no elements satisfy the condition, false otherwise
+
+### Examples
+
+```ruby
+# Check if no numbers are negative
+[1, 2, 3].async.none? { |n| n < 0 }  # => true
+[1, -2, 3].async.none? { |n| n < 0 } # => false (stops after -2)
+
+# With validation
+errors.async.none? { |error| error.critical? }
+# Checks all errors in parallel, returns false on first critical
+```
+
+### Implementation Notes
+- Uses `Concurrent::AtomicBoolean` to track if any element matches
+- Essentially the inverse of `any?`
+- Delegates pattern/no-block cases to wrapped enumerable
+
+## one?
+
+Asynchronously checks if exactly one element satisfies the given condition.
+
+Executes the block for each element in parallel and returns true if exactly one element returns a truthy value. Short-circuits and returns false as soon as a second match is found.
+
+### Parameters
+- `pattern` (optional): Pattern to match against elements
+- `&block`: Block to test each element
+
+### Returns
+`Boolean` - true if exactly one element satisfies the condition
+
+### Examples
+
+```ruby
+# Check for single admin
+users.async.one? { |u| u.admin? }  # => true if exactly one admin
+
+# With validation
+configs.async.one? { |c| c.primary? }
+# Validates all configs in parallel, ensures only one is primary
+```
+
+### Implementation Notes
+- Uses `Concurrent::AtomicFixnum` to count matches
+- Stops barrier execution when count exceeds 1
+- Delegates pattern/no-block cases to wrapped enumerable
+
+## find / detect
+
+Asynchronously finds the first element that satisfies the given condition.
+
+**Important:** Returns the **fastest completing** match, not necessarily the first element by position in the collection. Due to parallel execution, whichever element completes evaluation first will be returned. If you need the first element by position, use synchronous `find` instead.
+
+### Parameters
+- `ifnone` (optional): Proc to call if no element is found
+- `&block`: Block to test each element
+
+### Returns
+The first matching element, or nil/ifnone result if not found
+
+### Examples
+
+```ruby
+# Find any prime number (fastest to compute)
+numbers.async.find { |n| prime?(n) }
+
+# With fallback
+users.async.find(-> { User.new }) { |u| u.admin? }
+# Returns new User if no admin found
+
+# With expensive checks - returns fastest result
+documents.async.find { |doc| analyze_content(doc).contains_keyword? }
+# Analyzes all documents in parallel, returns fastest match
+
+# When order matters, use synchronous version
+first_prime = numbers.find { |n| prime?(n) }
+```
+
+### Implementation Notes
+- Uses `Concurrent::AtomicReference` with compare-and-set for first completion
+- Returns whichever matching element completes evaluation first
+- Supports `ifnone` proc for custom fallback behavior
+- Stops all remaining evaluations once a match is found
+
+## find_index
+
+Asynchronously finds the index of the first element that satisfies the given condition.
+
+**Important:** Returns the index of the **fastest completing** match, not necessarily the first by position in the collection. Due to parallel execution, whichever element completes evaluation first will have its index returned. If you need the first index by position, use synchronous `find_index` instead.
+
+### Parameters
+- `value` (optional): Value to find the index of
+- `&block`: Block to test each element
+
+### Returns
+`Integer` or `nil` - Index of first matching element, or nil if not found
+
+### Examples
+
+```ruby
+# Find index of any large file (fastest to check)
+files.async.find_index { |f| f.size > 1_000_000 }
+
+# Find specific value - returns index of fastest equality check
+items.async.find_index("target")
+
+# With validation - returns index of fastest validation
+results.async.find_index { |r| r.status == :success }
+
+# When order matters, use synchronous version
+first_index = data.find_index { |item| expensive_check(item) }
+```
+
+### Implementation Notes
+- Uses `Concurrent::AtomicReference` with compare-and-set for first completion
+- Returns index of whichever element completes evaluation first
+- Handles both value-based and block-based searches
+- Stops all remaining evaluations once a match is found
+
+## include? / member?
+
+Asynchronously checks if the enumerable includes a given value.
+
+Checks all elements in parallel for equality with the given value. Short-circuits and returns true as soon as a match is found.
+
+### Parameters
+- `obj`: Object to search for
+
+### Returns
+`Boolean` - true if the enumerable includes the object
+
+### Examples
+
+```ruby
+# Check for value
+[1, 2, 3].async.include?(2)  # => true
+
+# With objects
+users.async.include?(target_user)
+
+# Complex equality
+configs.async.include?(production_config)
+```
+
+### Implementation Notes
+- Uses `Concurrent::AtomicBoolean` for thread-safe early termination
+- Relies on the object's `==` method for comparison
+- Short-circuits on first match
+
+## Pattern Matching Support
+
+When called with a pattern argument instead of a block, predicate methods delegate to the wrapped enumerable's synchronous implementation. This ensures correct behavior with Ruby's pattern matching:
+
+```ruby
+# Pattern matching
+[1, 2, 3].async.any?(Integer)     # => true
+[:a, :b].async.all?(Symbol)       # => true
+[1, 2, 3].async.none?(String)     # => true
+[1, 2, 3].async.one?(2)           # => true
+```
+
+## No-Block Behavior
+
+When called without a block or pattern, predicate methods check for truthiness:
+
+```ruby
+[nil, false, 1].async.any?        # => true (1 is truthy)
+[1, 2, 3].async.all?              # => true (all truthy)
+[nil, false].async.none?          # => true (none truthy)
+[nil, false, 1].async.one?        # => true (exactly one truthy)
+```
+
+## Performance Considerations
+
+- All predicate methods use early termination to minimize unnecessary work
+- Thread-safe atomic variables prevent race conditions
+- Barrier stops immediately when result is determined
+- Pattern/no-block cases delegate to avoid async overhead when not needed

data/docs/reference/methods/transformers.md

@@ -0,0 +1,104 @@
+# Transformer Methods
+
+Transformer methods create modified collections from the original enumerable. All transformer methods return an `Async::Enumerator` for chaining operations.
+
+## Overview
+
+Transformer methods delegate to the standard Enumerable implementation but wrap the result in a new `Async::Enumerator` to enable continued chaining. The actual transformation happens through the parent Enumerable module.
+
+## Available Methods
+
+### map / collect
+
+Transforms each element using the given block.
+
+```ruby
+[1, 2, 3].async.map { |n| n * 2 }  # => Async::Enumerator([2, 4, 6])
+```
+
+### select / filter / find_all
+
+Selects elements for which the block returns true.
+
+```ruby
+[1, 2, 3, 4].async.select { |n| n.even? }  # => Async::Enumerator([2, 4])
+```
+
+### reject
+
+Rejects elements for which the block returns true.
+
+```ruby
+[1, 2, 3, 4].async.reject { |n| n.even? }  # => Async::Enumerator([1, 3])
+```
+
+### filter_map
+
+Maps and filters in a single pass, removing nil values.
+
+```ruby
+[1, 2, 3, 4].async.filter_map { |n| n * 2 if n.even? }  # => Async::Enumerator([4, 8])
+```
+
+### flat_map / collect_concat
+
+Maps and flattens the result by one level.
+
+```ruby
+[[1, 2], [3, 4]].async.flat_map { |arr| arr.map { |n| n * 2 } }
+# => Async::Enumerator([2, 4, 6, 8])
+```
+
+### compact
+
+Removes nil elements.
+
+```ruby
+[1, nil, 2, nil, 3].async.compact  # => Async::Enumerator([1, 2, 3])
+```
+
+### uniq
+
+Removes duplicate elements.
+
+```ruby
+[1, 1, 2, 2, 3].async.uniq  # => Async::Enumerator([1, 2, 3])
+```
+
+### sort
+
+Sorts elements using their natural ordering or a provided comparison.
+
+```ruby
+[3, 1, 2].async.sort  # => Async::Enumerator([1, 2, 3])
+[3, 1, 2].async.sort { |a, b| b <=> a }  # => Async::Enumerator([3, 2, 1])
+```
+
+### sort_by
+
+Sorts elements by the result of the given block.
+
+```ruby
+users.async.sort_by { |u| u.age }  # Sorts users by age
+files.async.sort_by { |f| f.size }  # Sorts files by size
+```
+
+## Chaining
+
+All transformer methods return an `Async::Enumerator`, enabling method chaining:
+
+```ruby
+result = [1, 2, 3, 4, 5].async
+  .map { |n| n * 2 }        # [2, 4, 6, 8, 10]
+  .select { |n| n > 4 }      # [6, 8, 10]
+  .map { |n| n + 1 }         # [7, 9, 11]
+  .sort { |a, b| b <=> a }   # [11, 9, 7]
+  .sync                      # Materializes the result
+```
+
+## Implementation Notes
+
+- Transformer methods leverage the standard Enumerable module for transformation logic
+- Each method wraps the result in a new `Async::Enumerator` with the same fiber limit
+- Methods returning enumerators without blocks are handled correctly
+- The `max_fibers` setting is preserved through the transformation chain

data/lib/async/enumerable/comparable.rb

@@ -0,0 +1,26 @@
+module Async
+  module Enumerable
+    module Comparable
+      def self.included(base)
+        base.include(::Comparable)
+      end
+
+      # Compares with another enumerable.
+      # @param other [Object] Object to compare
+      # @return [Integer, nil] Comparison result
+      def <=>(other)
+        return nil unless other.respond_to?(:to_a)
+        to_a <=> other.to_a
+      end
+
+      # Checks equality with another enumerable.
+      # @param other [Object] Object to compare
+      # @return [Boolean] True if equal
+      def ==(other)
+        return false unless other.respond_to?(:to_a)
+        to_a == other.to_a
+      end
+      alias_method :eql?, :==
+    end
+  end
+end

data/lib/async/enumerable/concurrency_bounder.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Async
+  module Enumerable
+    # Provides bounded concurrency control for async operations.
+    # See docs/reference/concurrency_bounder.md for detailed documentation.
+    # @api private
+    module ConcurrencyBounder
+      def self.included(base) = base.include(Configurable)
+
+      # Executes block with bounded concurrency.
+      # @param early_termination [Boolean] Support early stop
+      # @yield [barrier] Barrier for spawning async tasks
+      def __async_enumerable_bounded_concurrency(early_termination: false, limit: nil, &block)
+        Sync do |parent|
+          limit ||= __async_enumerable_config.max_fibers
+          semaphore = Async::Semaphore.new(limit, parent:)
+          barrier = Async::Barrier.new(parent: semaphore)
+
+          # Yield the barrier for task spawning
+          yield barrier
+
+          # Wait for all tasks to complete (or early termination)
+          if early_termination
+            begin
+              barrier.wait
+            rescue Async::Stop
+              # Expected when barrier.stop is called for early termination
+            end
+          else
+            barrier.wait
+          end
+        end
+      end
+    end
+  end
+end

data/lib/async/enumerable/configurable.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Async
+  module Enumerable
+    # Manages configuration and collection resolution for async enumerables.
+    # Provides a DSL for defining async enumerable sources and configuration.
+    module Configurable
+      # Configuration data class for managing async enumerable settings.
+      # Uses Ruby's Data class for immutability and clean API.
+      class Config < Data.define(:collection_ref, :max_fibers)
+        DEFAULT_MAX_FIBERS = 1024
+
+        def initialize(collection_ref: nil, max_fibers: DEFAULT_MAX_FIBERS)
+          super
+        end
+
+        # Define the struct class once to avoid redefinition warnings
+        ConfigStruct = Struct.new(*members)
+
+        # Creates mutable struct for configuration editing.
+        # @return [ConfigStruct] Mutable config struct
+        def to_struct
+          ConfigStruct.new(*deconstruct)
+        end
+      end
+
+      class << self
+        def included(base)
+          unless base.instance_variable_get(:@__async_enumerable_config_ref)
+            ref = Concurrent::AtomicReference.new
+            base.instance_variable_set(:@__async_enumerable_config_ref, ref)
+          end
+        end
+      end
+
+      # Class methods for defining async enumerable sources
+      module ClassMethods
+        # Defines enumerable source for async operations.
+        # @param collection_ref [Symbol] Method/ivar returning enumerable
+        # @param kwargs [Hash] Configuration options (max_fibers, etc.)
+        def def_async_enumerable(collection_ref = nil, **kwargs)
+          # Store only the class-specific overrides, not a full config
+          @__async_enumerable_class_overrides = {collection_ref:}.compact.merge(kwargs)
+        end
+
+        # Gets the collection reference from config.
+        # @return [Symbol, nil] Collection reference
+        def __async_enumerable_collection_ref
+          __async_enumerable_config.collection_ref
+        end
+
+        # Gets config with class-level overrides merged.
+        # @return [Config] Merged configuration
+        def __async_enumerable_config
+          # Dynamically merge module config with class overrides
+          base = Async::Enumerable.config
+          if @__async_enumerable_class_overrides
+            base.with(**@__async_enumerable_class_overrides)
+          else
+            base
+          end
+        end
+
+        # Returns nil as classes don't cache config refs.
+        # @return [nil] Always nil for class level
+        def __async_enumerable_config_ref
+          nil
+        end
+      end
+
+      # Instance methods for configuration and collection resolution
+
+      # Gets or updates configuration with block.
+      # @yield [ConfigStruct] Mutable config for editing
+      # @return [Config] Current or updated configuration
+      def __async_enumerable_configure
+        # Get the current config (with hierarchy)
+        if @__async_enumerable_config_ref
+          current = @__async_enumerable_config_ref.get
+        else
+          # Build config from hierarchy
+          current_hash = __async_enumerable_merge_all_config
+          current = Config.new(**current_hash)
+        end
+
+        return current unless block_given?
+
+        mutable = current.to_struct
+        yield mutable
+        final = __async_enumerable_merge_all_config(mutable.to_h)
+
+        Config.new(**final).tap do |updated|
+          @__async_enumerable_config_ref = Concurrent::AtomicReference.new(updated)
+        end
+      end
+      alias_method :__async_enumerable_config, :__async_enumerable_configure
+
+      # Merges configs from all hierarchy levels.
+      # @param config [Hash, nil] Additional config to merge
+      # @return [Hash] Merged configuration hash
+      def __async_enumerable_merge_all_config(config = nil)
+        [Async::Enumerable.config].tap do |arr|
+          class_cfg = self.class.respond_to?(:__async_enumerable_config) ? self.class.__async_enumerable_config : nil
+
+          arr << class_cfg
+          arr << @__async_enumerable_config
+          arr << config
+        end.compact.map(&:to_h).reduce(&:merge)
+      end
+
+      # Gets the config reference for this object.
+      # @return [AtomicReference] Config reference
+      def __async_enumerable_config_ref
+        # First check for instance-level config ref
+        @__async_enumerable_config_ref || Async::Enumerable.config_ref
+      end
+
+      # Collection resolution methods
+
+      # Gets collection reference from class.
+      # @return [Symbol, nil] Collection reference
+      def __async_enumerable_collection_ref
+        self.class.__async_enumerable_collection_ref
+      end
+
+      # Resolves the actual enumerable collection.
+      # @return [Enumerable] The collection to enumerate
+      def __async_enumerable_collection
+        return self unless __async_enumerable_collection_ref.is_a?(Symbol)
+
+        ref = __async_enumerable_collection_ref
+        if ref.to_s.start_with?("@")
+          instance_variable_get(ref)
+        else
+          send(ref)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Async
+  module Enumerable
+    module Methods
+      # Aggregators module for enumerable aggregation methods.
+      #
+      # Aggregation methods like reduce, inject, sum, count, and tally are
+      # inherited from the standard Enumerable module. When used with async
+      # enumerables, these methods automatically benefit from parallel execution
+      # through our async #each implementation.
+      #
+      # The block passed to these methods (when applicable) executes concurrently
+      # for each element, though the aggregation itself maintains correct ordering
+      # and thread-safe accumulation.
+      #
+      # Methods available through Enumerable:
+      # - reduce/inject: Combines elements using a binary operation
+      # - sum: Calculates the sum of elements (block executes async)
+      # - count: Counts elements matching a condition (block executes async)
+      # - tally: Counts occurrences of each element
+      # - min/max/minmax: Finds minimum/maximum elements (block executes async)
+      # - min_by/max_by: Finds elements by computed values (block executes async)
+      module Aggregators
+        def self.included(base)
+          base.include(Each) # Dependency
+          base.include(Configurable) # Dependency for collection resolution
+
+          # Delegate non-parallelizable aggregator methods directly to the collection
+          base.extend(Forwardable)
+          # is lazy really an aggregator? no, but i don't want to figure out
+          # _what_ it is either
+          base.def_delegators :__async_enumerable_collection, :size, :length, :lazy
+        end
+        # This module is intentionally empty as aggregation methods are
+        # inherited from Enumerable and automatically use our async #each
+      end
+    end
+  end
+end