fiber_stream 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1cc93666d0610e659313a12dc756fca935579e62711972a9ea65d9ad818f6020
-  data.tar.gz: 97f315765ba573a5c047752fd083006db89404eff06e92bda5afbfa0f1933ed1
+  metadata.gz: b729811e8b39efdfa4203d0e6167709105d524ec098f018fdc120986c0b73b14
+  data.tar.gz: 162a3bf8a893fe13ae994ec77c8a2df7c8c44f9c5ab11895ee3b3b0ddfe31192
 SHA512:
-  metadata.gz: 5e635531f9e34510ef0eab76254c33e70f36124be779f48d2f9692c351a2f26ed36c7c14fa0d1d596c5645b511bb4fa1abe2bb773fc434c1f4da39a6e19dbefc
-  data.tar.gz: 67eb50ae0a1d727c65fd172be572f7bf08ba82b3ee0cf4d9094c7e9ad579aac327155cc772bcd4e94b778cef53f63decf64a08e12e7ea5ef6949a6d813336b04
+  metadata.gz: edd97c825b99250b4169443764cb384330fd8c3176e4086c6a1a93834c67fd288b5f0583fce50b68277936de1fe9f303162063ff182523beed3af935b568d2e0
+  data.tar.gz: dcb33221af26887b3a914f428c0b58e6d8ecf8511c384c0282b889e8b74b1d17fecd6e5ba86b465dfc466252bef0bb960f9bcfd66229c9e6ccd0b12cf7b3a768

data/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## Unreleased
+
+## 0.6.0 - 2026-07-27
+
+### Added
+
+- `Flow.ractor_unordered_map(workers:)` and `Source#ractor_unordered_map` for
+  Ractor-backed CPU-bound mapping that emits results in completion order.
+- `Sink.find { |element| ... }` for predicate-based terminal search with
+  early upstream completion.
+- `Sink.any? { |element| ... }` for predicate-based existential checks with
+  early upstream completion.
+- `Sink.all? { |element| ... }` for predicate-based universal checks with
+  early upstream completion.
+- Example and benchmark coverage for unordered Ractor-backed mapping.
+
+### Changed
+
+- Added a rate-limiting tutorial covering local, shared in-process,
+  database-backed, and Redis-backed quota policies.
+- Centralized the local and release verification gates and added documentation
+  index validation.
+
+## 0.5.0 - 2026-06-21
+
+### Added
+
+- `Flow.tap { |element| ... }` for lazy pass-through observation without
+  changing emitted elements.
+- `Flow.filter_map { |element| ... }` and `Source#filter_map` for combined
+  transformation and falsey-value dropping.
+- `Flow.reject { |element| ... }` and `Source#reject` for complement
+  predicate filtering.
+- `Flow.compact` and `Source#compact` for nil-only filtering while preserving
+  `false`.
+- `Flow.map_concat { |element| enumerable }` and `Source#map_concat` for
+  one-to-many element expansion.
+- `Flow.throttle(...)`, `Source#throttle(...)`, and `RateLimiter` for
+  pull-driven rate limiting with optional shared quota state.
+- `Sink.count` for counting stream elements without accumulating them.
+
+### Changed
+
+- Expanded README and website reference coverage for the flow operators and
+  rate limiter added in 0.5.0.
+- Promoted completed flow product specs and design docs from draft to accepted
+  status.
+
 ## 0.4.0 - 2026-06-09
 
 ### Added

data/README.md

@@ -1,7 +1,10 @@
 # FiberStream
- FiberStream is a Ruby library for linear stream processing with pull-based backpressure. 
 
-It builds lazy Source definitions, transforms values with Flow stages, and materializes results with Sink objects.
+FiberStream is a Ruby library for linear stream processing with pull-based
+backpressure.
+
+It builds lazy `Source` definitions, transforms values with `Flow` stages, and
+materializes results with `Sink` objects.
 
 [![Gem Version](https://badge.fury.io/rb/fiber_stream.svg)](https://badge.fury.io/rb/fiber_stream)
 
@@ -30,11 +33,13 @@ Implemented capabilities:
 - in-memory, IO, FiberStream-owned Ractor producer, backpressure-aware Ractor
   port, and Ractor port merge sources
 - lazy source concatenation, zipping, and scheduler-backed merging
-- mapping, filtering, limiting, predicate-based limiting and dropping,
-  fixed-prefix dropping, fixed-size grouping, line splitting, buffering, async
-  boundaries, ordered and unordered parallel mapping, and ordered
-  Ractor-backed mapping
-- array, first-element, fold, foreach, and IO sinks
+- mapping, filtering, transform-and-filter, nil compaction, side-effect
+  observation, one-to-many expansion, limiting, predicate-based limiting and
+  dropping, fixed-prefix dropping, fixed-size grouping, line splitting,
+  buffering, async boundaries, throttling, ordered and unordered parallel
+  mapping, and ordered and unordered Ractor-backed mapping
+- array, first-element, predicate search/check, count, fold, foreach, and IO
+  sinks
 - reusable flow composition and runnable pipelines
 - foreground and scheduler-backed background pipeline execution
 - public RBS signatures
@@ -205,6 +210,62 @@ FiberStream::Source.each([" a ", "", " b "])
 # => ["a", "b"]
 ```
 
+Use `reject` when the predicate names values to drop. Truthy predicate results
+drop the original element; `false` and `nil` results pass it through unchanged:
+
+```ruby
+result =
+  FiberStream::Source.each([1, 2, 3, 4])
+    .reject(&:even?)
+    .run_with(FiberStream::Sink.to_a)
+
+result # => [1, 3]
+```
+
+Use `filter_map` when filtering and transformation are one decision. Truthy
+block results are emitted as transformed values; `false` and `nil` are
+dropped:
+
+```ruby
+ids =
+  FiberStream::Source.each([{ id: 1 }, {}, { id: 3 }])
+    .filter_map { |record| record[:id] }
+    .run_with(FiberStream::Sink.to_a)
+
+ids # => [1, 3]
+```
+
+Use `compact` to drop only `nil` while keeping `false`, and `map_concat` to
+expand one upstream element into zero or more downstream elements:
+
+```ruby
+tokens =
+  FiberStream::Source.each(["alpha beta", nil, "gamma"])
+    .compact
+    .map_concat { |line| line.split }
+    .run_with(FiberStream::Sink.to_a)
+
+tokens # => ["alpha", "beta", "gamma"]
+```
+
+Use `Flow.tap` for observation inside a reusable flow without changing the
+element:
+
+```ruby
+seen = []
+
+observed =
+  FiberStream::Flow.tap { |value| seen << value }
+    .via(FiberStream::Flow.map { |value| value * 10 })
+
+FiberStream::Source.each([1, 2])
+  .via(observed)
+  .run_with(FiberStream::Sink.to_a)
+# => [10, 20]
+
+seen # => [1, 2]
+```
+
 Use `parallel_map` for ordered scheduler-backed mapping when each element
 waits on non-blocking IO. It preserves input order while allowing up to
 `concurrency` mapping operations to be in flight:
@@ -249,8 +310,10 @@ responses =
 responses
 ```
 
-Use `ractor_map` for ordered CPU-bound mapping in Ractor workers. The mapper
-must be shareable, usually by creating it with `Ractor.shareable_proc`.
+Use `ractor_map` for ordered CPU-bound mapping in Ractor workers, and
+`ractor_unordered_map` when later completed CPU-bound results should not wait
+behind a slower earlier input. The mapper must be shareable, usually by
+creating it with `Ractor.shareable_proc`.
 
 ```ruby
 require "digest"
@@ -283,6 +346,19 @@ digests =
 or `output_transfer: :move` only when the moved object will not be reused by
 the sender.
 
+`ractor_unordered_map` uses the same Ractor transfer and shareability rules,
+but emits values in worker completion order:
+
+```ruby
+fastest_first =
+  FiberStream::Source.each(records)
+    .ractor_unordered_map(workers: 2, input_transfer: :move, &HASH_RECORD)
+    .run_with(FiberStream::Sink.to_a)
+
+# Results are in completion order, not necessarily input order.
+fastest_first
+```
+
 ### Sinks
 
 A `Sink` consumes the stream and returns a materialized value.
@@ -293,6 +369,38 @@ FiberStream::Source.each([1, 2, 3])
 # => 6
 ```
 
+Use `Sink.count` when only the number of elements matters:
+
+```ruby
+FiberStream::Source.each([1, 2, 3])
+  .run_with(FiberStream::Sink.count)
+# => 3
+```
+
+Use `Sink.find` when the stream should stop after the first matching element:
+
+```ruby
+FiberStream::Source.each([1, 2, 3, 4])
+  .run_with(FiberStream::Sink.find(&:even?))
+# => 2
+```
+
+Use `Sink.any?` when only the existence of a matching element matters:
+
+```ruby
+FiberStream::Source.each([1, 2, 3, 4])
+  .run_with(FiberStream::Sink.any?(&:even?))
+# => true
+```
+
+Use `Sink.all?` when every element must satisfy a predicate:
+
+```ruby
+FiberStream::Source.each([2, 4, 6])
+  .run_with(FiberStream::Sink.all?(&:even?))
+# => true
+```
+
 Use `Sink.foreach` when the terminal operation is a side effect and the stream
 values should not be accumulated:
 
@@ -473,12 +581,15 @@ does not provide CPU parallelism. Use producer ractors with
 `Source.ractor_producer` or `Source.ractor_merge_producers` when producer work
 needs true isolation.
 
-`Flow.buffer(count)` allows bounded prefetch. `Flow.async`, `Flow.buffer`,
+`Flow.buffer(count)` allows bounded prefetch. `Flow.throttle(rate:, per:)`
+paces elements before downstream side effects. `Flow.async`, `Flow.buffer`,
 `Flow.parallel_map`, `Flow.parallel_unordered_map`, `Source.io`,
 `Source#merge`, `Sink.io`, and `Pipeline#run_async` require an installed
 `Fiber.scheduler` and a non-blocking current fiber when demanded or started.
-FiberStream does not install a scheduler and does not depend on Async at
-runtime.
+`Flow.throttle` requires that scheduler context only when it needs to wait.
+Pass `throttle(limiter:)` with a `FiberStream::RateLimiter` when multiple
+pipelines or repeated runs should share quota state. FiberStream does not
+install a scheduler and does not depend on Async at runtime.
 
 ## API Surface
 
@@ -498,10 +609,15 @@ Source convenience methods:
 - `Source#zip(source)`
 - `Source#merge(source)`
 - `Source#map { |element| ... }`
+- `Source#filter_map { |element| ... }`
+- `Source#compact`
+- `Source#map_concat { |element| enumerable }`
 - `Source#parallel_map(concurrency:) { |element| ... }`
 - `Source#parallel_unordered_map(concurrency:) { |element| ... }`
 - `Source#ractor_map(workers:, input_transfer: :copy, output_transfer: :copy) { |element| ... }`
+- `Source#ractor_unordered_map(workers:, input_transfer: :copy, output_transfer: :copy) { |element| ... }`
 - `Source#select { |element| ... }`
+- `Source#reject { |element| ... }`
 - `Source#take(count)`
 - `Source#drop(count)`
 - `Source#grouped(count)`
@@ -510,6 +626,8 @@ Source convenience methods:
 - `Source#drop_while { |element| ... }`
 - `Source#async`
 - `Source#buffer(count)`
+- `Source#throttle(rate:, per: 1, burst: nil)`
+- `Source#throttle(limiter:)`
 - `Source#lines(chomp: true, max_length: nil)`
 - `Source#split(separator, keep_separator: false, max_length: nil)`
 - `Source#to(sink)`
@@ -518,10 +636,16 @@ Source convenience methods:
 Flows:
 
 - `FiberStream::Flow.map { |element| ... }`
+- `FiberStream::Flow.filter_map { |element| ... }`
+- `FiberStream::Flow.compact`
+- `FiberStream::Flow.map_concat { |element| enumerable }`
+- `FiberStream::Flow.tap { |element| ... }`
 - `FiberStream::Flow.parallel_map(concurrency:) { |element| ... }`
 - `FiberStream::Flow.parallel_unordered_map(concurrency:) { |element| ... }`
 - `FiberStream::Flow.ractor_map(workers:, input_transfer: :copy, output_transfer: :copy) { |element| ... }`
+- `FiberStream::Flow.ractor_unordered_map(workers:, input_transfer: :copy, output_transfer: :copy) { |element| ... }`
 - `FiberStream::Flow.select { |element| ... }`
+- `FiberStream::Flow.reject { |element| ... }`
 - `FiberStream::Flow.take(count)`
 - `FiberStream::Flow.drop(count)`
 - `FiberStream::Flow.grouped(count)`
@@ -530,10 +654,14 @@ Flows:
 - `FiberStream::Flow.drop_while { |element| ... }`
 - `FiberStream::Flow.async`
 - `FiberStream::Flow.buffer(count)`
+- `FiberStream::Flow.throttle(rate:, per: 1, burst: nil)`
+- `FiberStream::Flow.throttle(limiter:)`
 - `FiberStream::Flow.lines(chomp: true, max_length: nil)`
 - `FiberStream::Flow.split(separator, keep_separator: false, max_length: nil)`
 - `Flow#via(flow)`
 - `Flow#to(sink)`
+- `FiberStream::RateLimiter.new(rate:, per: 1, burst: nil)`
+- `FiberStream::RateLimiter#acquire(permits: 1)`
 
 `lines` and `split` default to `max_length: nil`, which allows one
 unterminated line or frame to buffer without bound. Set a positive
@@ -543,6 +671,10 @@ Sinks:
 
 - `FiberStream::Sink.to_a`
 - `FiberStream::Sink.first`
+- `FiberStream::Sink.find { |element| truthy_or_falsey }`
+- `FiberStream::Sink.any? { |element| truthy_or_falsey }`
+- `FiberStream::Sink.all? { |element| truthy_or_falsey }`
+- `FiberStream::Sink.count`
 - `FiberStream::Sink.fold(initial) { |accumulator, element| ... }`
 - `FiberStream::Sink.foreach { |element| ... }`
 - `FiberStream::Sink.io(io, close: false, flush: false)`
@@ -568,6 +700,7 @@ bundle exec ruby examples/file_copy.rb
 bundle exec ruby examples/backpressure_buffer.rb
 bundle exec ruby examples/background_execution.rb
 bundle exec ruby examples/ractor_map_hashing.rb
+bundle exec ruby examples/ractor_unordered_map_hashing.rb
 bundle exec ruby examples/ractor_producer_sources.rb
 bundle exec ruby examples/ractor_port_source.rb
 bundle exec ruby examples/ractor_merge_ports_and_map.rb
@@ -581,6 +714,9 @@ events so the difference between direct demand and bounded prefetch is visible.
 `examples/ractor_map_hashing.rb` demonstrates ordered Ractor-backed hashing
 with a shareable mapper proc and `input_transfer: :move`.
 
+`examples/ractor_unordered_map_hashing.rb` demonstrates completion-order
+Ractor-backed hashing for uneven CPU-bound work.
+
 `examples/ractor_producer_sources.rb` demonstrates high-level owned producer
 Ractors with `Source.ractor_producer` and `Source.ractor_merge_producers`.
 
@@ -618,6 +754,14 @@ Install dependencies:
 bundle install
 ```
 
+Install website dependencies when building documentation locally:
+
+```sh
+cd website
+npm ci
+cd ..
+```
+
 Run the test suite:
 
 ```sh
@@ -642,6 +786,18 @@ Run all default checks:
 bundle exec rake
 ```
 
+Run the default local verification gate explicitly:
+
+```sh
+bundle exec rake verify
+```
+
+Run the full release-readiness gate, including the website build:
+
+```sh
+bundle exec rake verify:full
+```
+
 Build the gem:
 
 ```sh

data/examples/README.md

@@ -10,6 +10,7 @@ bundle exec ruby examples/file_copy.rb
 bundle exec ruby examples/backpressure_buffer.rb
 bundle exec ruby examples/background_execution.rb
 bundle exec ruby examples/ractor_map_hashing.rb
+bundle exec ruby examples/ractor_unordered_map_hashing.rb
 bundle exec ruby examples/ractor_port_source.rb
 bundle exec ruby examples/ractor_producer_sources.rb
 bundle exec ruby examples/ractor_merge_ports_and_map.rb
@@ -44,6 +45,10 @@ the foreground fiber keeps doing scheduler-managed work.
 `input_transfer: :move` because the input records are not reused after the
 pipeline runs.
 
+`ractor_unordered_map_hashing.rb` hashes independent payloads in Ractor workers
+and emits results as workers finish. It shows how a slower earlier input no
+longer holds back later completed CPU-bound work.
+
 `ractor_port_source.rb` demonstrates a producer Ractor connected to
 `Source.ractor_port`. The producer creates its acknowledgment port, waits for
 `RactorPort::Ack`, and sends one typed `RactorPort::Element` per downstream

data/examples/ractor_unordered_map_hashing.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "digest"
+require "fiber_stream"
+
+records = [
+  { name: "slow-alpha.bin", payload: +"A" * 160_000, rounds: 1_200 },
+  { name: "fast-bravo.bin", payload: +"B" * 120_000, rounds: 120 },
+  { name: "fast-charlie.bin", payload: +"C" * 140_000, rounds: 120 },
+  { name: "medium-delta.bin", payload: +"D" * 100_000, rounds: 450 }
+]
+
+HASH_RECORD =
+  Ractor.shareable_proc do |record|
+    payload = record.fetch(:payload)
+    digest = Digest::SHA256.hexdigest(payload)
+
+    record.fetch(:rounds).times do
+      digest = Digest::SHA256.hexdigest(digest)
+    end
+
+    {
+      name: record.fetch(:name),
+      bytes: payload.bytesize,
+      rounds: record.fetch(:rounds),
+      sha256: digest
+    }
+  end
+
+puts "Input order"
+records.each.with_index(1) do |record, index|
+  puts format(
+    "%<index>2d. %-16<name>s %4<rounds>d rounds",
+    index: index,
+    name: record.fetch(:name),
+    rounds: record.fetch(:rounds)
+  )
+end
+
+digests =
+  FiberStream::Source.each(records)
+    .ractor_unordered_map(workers: 2, input_transfer: :move, &HASH_RECORD)
+    .run_with(FiberStream::Sink.to_a)
+
+puts
+puts "Completion order"
+digests.each.with_index(1) do |digest, index|
+  puts format(
+    "%<index>2d. %-16<name>s %7<bytes>d bytes %4<rounds>d rounds  %<sha256>s",
+    index: index,
+    name: digest.fetch(:name),
+    bytes: digest.fetch(:bytes),
+    rounds: digest.fetch(:rounds),
+    sha256: digest.fetch(:sha256)
+  )
+end
+
+puts
+puts "Results are emitted as Ractor workers finish, not by input position."
+puts "input_transfer: :move is safe here because the input records are not reused."

data/lib/fiber_stream/flow.rb

@@ -13,6 +13,51 @@ module FiberStream
       new { |upstream| Pull.map(upstream, block) }
     end
 
+    # Creates a transform-and-filter flow.
+    #
+    # The block is called once for each upstream element observed by this
+    # stage. Truthy block results are emitted downstream as transformed values;
+    # false and nil results are dropped. Exceptions raised by the block fail the
+    # stream and are re-raised from `Source#run_with`.
+    def self.filter_map(&block)
+      raise ArgumentError, "missing block" unless block
+
+      new { |upstream| Pull.filter_map(upstream, block) }
+    end
+
+    # Creates a nil-dropping flow.
+    #
+    # The flow drops `nil` elements and passes every non-`nil` element through
+    # unchanged, including `false`.
+    def self.compact
+      new { |upstream| Pull.compact(upstream) }
+    end
+
+    # Creates a one-to-many mapping flow.
+    #
+    # The block is called once for each upstream element whose expansion is
+    # needed. It must return an object that responds to `#each`; yielded values
+    # are emitted in order before the next upstream element is pulled.
+    # Exceptions raised by the block or by the returned object's `#each` fail
+    # the stream and are re-raised from `Source#run_with`.
+    def self.map_concat(&block)
+      raise ArgumentError, "missing block" unless block
+
+      new { |upstream| Pull.map_concat(upstream, block) }
+    end
+
+    # Creates a pass-through observing flow.
+    #
+    # The block is called once for each element before that element is emitted
+    # downstream. The block return value is ignored and the original element is
+    # passed through unchanged. Exceptions raised by the block fail the stream
+    # and are re-raised from `Source#run_with`.
+    def self.tap(&block)
+      raise ArgumentError, "missing block" unless block
+
+      new { |upstream| Pull.tap(upstream, block) }
+    end
+
     # Creates an ordered scheduler-backed parallel mapping flow.
     #
     # The stage starts internal scheduled fibers on first downstream demand and
@@ -66,6 +111,26 @@ module FiberStream
       new { |upstream| Pull.ractor_map(upstream, workers, input_transfer, output_transfer, block) }
     end
 
+    # Creates an unordered Ractor-backed mapping flow.
+    #
+    # The mapper runs inside worker ractors and must be shareable, typically
+    # created with `Ractor.shareable_proc`. Results are emitted in worker
+    # completion order, and at most `workers` upstream elements are pulled but
+    # not yet emitted. `input_transfer` and `output_transfer` must be `:copy`
+    # or `:move` and are passed to Ractor message sends for element and result
+    # transfer.
+    def self.ractor_unordered_map(workers:, input_transfer: :copy, output_transfer: :copy, &block)
+      raise ArgumentError, "missing block" unless block
+      raise TypeError, "workers must be an Integer" unless workers.is_a?(Integer)
+      raise ArgumentError, "workers must be positive" unless workers.positive?
+
+      Internal::RactorTransferPolicy.validate!(:input_transfer, input_transfer)
+      Internal::RactorTransferPolicy.validate!(:output_transfer, output_transfer)
+      raise TypeError, "block must be shareable" unless Ractor.shareable?(block)
+
+      new { |upstream| Pull.ractor_unordered_map(upstream, workers, input_transfer, output_transfer, block) }
+    end
+
     # Creates a filtering flow.
     #
     # The block is called for upstream elements until it returns a truthy value
@@ -78,6 +143,19 @@ module FiberStream
       new { |upstream| Pull.select(upstream, block) }
     end
 
+    # Creates a complement filtering flow.
+    #
+    # The block is called for upstream elements until it returns `false` or
+    # `nil`, or upstream completes. Truthy predicate results drop the original
+    # element; false and nil results pass the element through unchanged.
+    # Exceptions raised by the block fail the stream and are re-raised from
+    # `Source#run_with`.
+    def self.reject(&block)
+      raise ArgumentError, "missing block" unless block
+
+      new { |upstream| Pull.reject(upstream, block) }
+    end
+
     # Creates a limiting flow.
     #
     # The flow emits at most `count` elements. `take(0)` completes without
@@ -180,6 +258,19 @@ module FiberStream
       new { |upstream| Pull.buffer(upstream, count) }
     end
 
+    # Creates a scheduler-aware throttling flow.
+    #
+    # The `rate:` form creates a fresh `RateLimiter` for each materialization.
+    # The `limiter:` form uses the supplied limiter object, which must respond
+    # to `acquire(permits:)` and return only after permits are acquired. When
+    # FiberStream-owned waiting is required, the current fiber must be
+    # non-blocking with an installed `Fiber.scheduler`.
+    def self.throttle(**options)
+      limiter = build_throttle_limiter(options)
+
+      new { |upstream| Pull.throttle(upstream, limiter.call) }
+    end
+
     # Creates a line-splitting flow.
     #
     # The flow accepts String chunks and emits lines split on "\n". By default
@@ -222,6 +313,38 @@ module FiberStream
       new(&attach)
     end
 
+    def self.build_throttle_limiter(options)
+      unknown_keywords = options.keys - [:rate, :per, :burst, :limiter]
+      raise ArgumentError, "unknown keywords: #{unknown_keywords.join(", ")}" unless unknown_keywords.empty?
+
+      rate_given = options.key?(:rate)
+      per_given = options.key?(:per)
+      burst_given = options.key?(:burst)
+      limiter_given = options.key?(:limiter)
+
+      if limiter_given
+        raise ArgumentError, "cannot pass rate and limiter together" if rate_given
+        raise ArgumentError, "cannot pass per with limiter" if per_given
+        raise ArgumentError, "cannot pass burst with limiter" if burst_given
+
+        limiter = options.fetch(:limiter)
+        raise TypeError, "limiter must respond to acquire" unless limiter.respond_to?(:acquire)
+
+        return -> { limiter }
+      end
+
+      raise ArgumentError, "missing rate or limiter" unless rate_given
+
+      rate = options.fetch(:rate)
+      per = options.fetch(:per, 1)
+      burst = options.fetch(:burst, nil)
+      RateLimiter.validate_options!(rate:, per:, burst:)
+
+      -> { RateLimiter.new(rate:, per:, burst:) }
+    end
+
+    private_class_method :build_throttle_limiter
+
     # Returns a reusable flow that applies this flow and then `flow`.
     #
     # Construction is lazy. No upstream stream is attached and no elements are

data/lib/fiber_stream/pull/compact.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module FiberStream
+  module Pull
+    # Nil-dropping stage.
+    #
+    # A single downstream demand may pull multiple upstream elements until a
+    # non-nil value is observed or upstream completes. Dropped nil values are
+    # discarded immediately and are not buffered.
+    class Compact
+      def initialize(upstream)
+        @upstream = upstream
+        @closed = false
+        @done = false
+      end
+
+      def next
+        return DONE if @closed || @done
+
+        loop do
+          value = @upstream.next
+          if Pull.done?(value)
+            @done = true
+            return DONE
+          end
+
+          return value unless value.nil?
+        end
+      end
+
+      def close
+        return if @closed
+
+        @closed = true
+        @upstream.close
+      end
+    end
+  end
+end

data/lib/fiber_stream/pull/filter_map.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module FiberStream
+  module Pull
+    # Transform-and-filter stage.
+    #
+    # A single downstream demand may pull multiple upstream elements until the
+    # transform returns a truthy value or upstream completes. Falsey transform
+    # results are discarded immediately and are not buffered.
+    class FilterMap
+      def initialize(upstream, transform)
+        @upstream = upstream
+        @transform = transform
+        @closed = false
+        @done = false
+      end
+
+      def next
+        return DONE if @closed || @done
+
+        loop do
+          value = @upstream.next
+          if Pull.done?(value)
+            @done = true
+            return DONE
+          end
+
+          result = @transform.call(value)
+          return result if result
+        end
+      end
+
+      def close
+        return if @closed
+
+        @closed = true
+        @upstream.close
+      end
+    end
+  end
+end