stages-pages
API
Generated with
stages-pages/h8io.stages/h8io.stages.operators

h8io.stages.operators

package h8io.stages.operators

Members list

Type members

Classlikes

final case class And[-I, +LO, +RO, +E](left: Stage[I, LO, E], right: Stage[I, RO, E]) extends BaseBinaryOperator[I, LO, RO, (LO, RO), E]

A binary operator that applies left and right to the same input sequentially, producing a tuple of both outputs when both succeed.

A binary operator that applies left and right to the same input sequentially, producing a tuple of both outputs when both succeed.

The evaluation is short-circuit on the left side:

  • If left yields h8io.stages.Yield.Some, right is applied to the same input.
    • If right also yields Some, the result is Yield.Some((leftOut, rightOut), ...).
    • If right yields None, the result is Yield.None(mergedStatus, ...).
  • If left yields h8io.stages.Yield.None, right is not applied and the result is Yield.None(leftStatus, ...).

Statuses from both sides are merged with combine.

Type parameters

E

the error type (covariant)

I

the shared input type (contravariant)

LO

the left output type (covariant)

RO

the right output type (covariant)

Value parameters

left

the first stage to apply

right

the second stage to apply when left succeeds

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait BinaryOperator[Stage[I, LO, E], Stage[I, RO, E], I, (LO, RO), E]
trait Stage[I, (LO, RO), E]
trait I => Yield[I, (LO, RO), E]
class Object
trait Matchable
class Any
Show all
object And

Companion object for And.

Companion object for And.

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
And.type
final case class CompleteIfNone[I, O, E](alterand: Stage[I, O, E]) extends Decorator[I, O, E]

A decorator that stops the pipeline when the inner stage produces no output.

A decorator that stops the pipeline when the inner stage produces no output.

When the inner stage yields h8io.stages.Yield.None with h8io.stages.Status.Success, CompleteIfNone upgrades the status to h8io.stages.Status.Complete, signaling that processing should not continue. All other h8io.stages.Yield variants are forwarded unchanged (with the evolution mapped to preserve the decorator).

This is useful for stages that return None when their input stream is exhausted — wrapping them with CompleteIfNone turns the absence of output into a clean pipeline termination.

Type parameters

E

the error type

I

the input type

O

the output type

Value parameters

alterand

the inner stage to observe

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
trait Alterator[Stage[I, O, E], I, O, E]
trait Stage[I, O, E]
trait I => Yield[I, O, E]
class Object
trait Matchable
class Any
Show all
object CompleteIfSome extends Stage[Any, Any, Nothing] => Stage[Any, Any, Nothing]

A h8io.stages.base.Decoration that stops the pipeline as soon as the decorated stage produces an output value.

A h8io.stages.base.Decoration that stops the pipeline as soon as the decorated stage produces an output value.

CompleteIfSome appends h8io.stages.std.Complete after the decorated stage via ~>. If the stage yields h8io.stages.Yield.Some, Complete immediately emits h8io.stages.Status.Complete, terminating the pipeline. If the stage yields h8io.stages.Yield.None, Complete is not reached and the pipeline continues normally.

The singleton operates on Stage[Any, Any, Nothing] and can be cast to any concrete Decoration[I, O, E] via apply[I, O, E].

Example:

val stage: Stage[Int, Int, Nothing] = ...
val completing: Stage[Int, Int, Nothing] = CompleteIfSome(stage)
// Once stage produces a value, the pipeline stops.

Attributes

Supertypes
trait Stage[Any, Any, Nothing] => Stage[Any, Any, Nothing]
class Object
trait Matchable
class Any
Self type
object IAnd

Companion object for IAnd.

Companion object for IAnd.

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
IAnd.type
final case class IAnd[-I, +LO, +RO, +E](left: Stage[I, LO, E], right: Stage[I, RO, E]) extends BinaryOperator[Stage[I, LO, E], Stage[I, RO, E], I, (LO, RO), E]

An ''independent'' binary operator that applies two stages to the same input and combines their outputs into a tuple.

An ''independent'' binary operator that applies two stages to the same input and combines their outputs into a tuple.

Both left and right are always applied — unlike And, which skips right if left produces no output.

  • If both stages yield h8io.stages.Yield.Some, the result is h8io.stages.Yield.Some``((leftOut, rightOut), mergedStatus, ...).
  • If either stage yields h8io.stages.Yield.None, the result is h8io.stages.Yield.None``(mergedStatus, ...).

Statuses from both stages are merged with combine (i.e., leftStatus.combine(rightStatus)). The evolution pairs each branch's continuations symmetrically.

Type parameters

E

the error type (covariant)

I

the shared input type (contravariant)

LO

the left output type (covariant)

RO

the right output type (covariant)

Value parameters

left

the first stage

right

the second stage

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait BinaryOperator[Stage[I, LO, E], Stage[I, RO, E], I, (LO, RO), E]
trait Stage[I, (LO, RO), E]
trait I => Yield[I, (LO, RO), E]
class Object
trait Matchable
class Any
Show all
object Identity extends Stage[Any, Nothing, Nothing] => Stage[Any, Nothing, Nothing]

The identity h8io.stages.base.Decoration: returns the decorated stage unchanged.

The identity h8io.stages.base.Decoration: returns the decorated stage unchanged.

Identity is useful as a no-op placeholder in decoration pipelines or when a h8io.stages.base.Decoration is required by an API but no transformation is needed.

The singleton operates on Stage[Any, Nothing, Nothing] and can be safely cast to any concrete Decoration[I, O, E] via apply[I, O, E].

Example:

val dec: Decoration[String, Int, Nothing] = Identity[String, Int, Nothing]

Attributes

Supertypes
trait Stage[Any, Nothing, Nothing] => Stage[Any, Nothing, Nothing]
class Object
trait Matchable
class Any
Self type
Identity.type
object KeepLastOutput

A decorator that remembers the last output produced by the inner stage and re-emits it when the inner stage yields no value.

A decorator that remembers the last output produced by the inner stage and re-emits it when the inner stage yields no value.

The decorator has two internal states:

  • None state (initial): no output has been seen yet. The inner stage's h8io.stages.Yield.None is forwarded unchanged; a h8io.stages.Yield.Some is forwarded and transitions the wrapper to the Some state.
  • Some state: a previous output out is remembered, so the wrapper always emits a value. A new h8io.stages.Yield.Some from the inner stage is forwarded as is and updates the remembered value; on h8io.stages.Yield.None the remembered value is emitted instead.

In both states the evolution is mapped so that continuations remain wrapped in the appropriate KeepLastOutput variant, preserving the last-value semantics.

Both variants are internal to the package: the decorator is reached through the KeepLastOutput.apply factory, which always starts in the None state, and the state it is in afterwards is not part of the API.

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
final case class Lift[I, O, E](alterand: Stage[I, O, E]) extends Alterator[Stage[I, O, E], I, Option[O], E], Fruitful[I, Option[O], E]

A decorator that wraps a stage's optional output into an Option, making the result always present.

A decorator that wraps a stage's optional output into an Option, making the result always present.

  • If the inner stage yields h8io.stages.Yield.Some``(v, ...), Lift produces h8io.stages.Yield.Some``(Some(v), ...).
  • If the inner stage yields h8io.stages.Yield.None``(...), Lift produces h8io.stages.Yield.Some``(None, ...).

Because Lift always emits a value, it extends h8io.stages.base.Fruitful. The evolution of the result is mapped so that every continuation stage is also wrapped in Lift, preserving the lifting semantics across the entire pipeline.

Lift is the inverse of h8io.stages.projections.Unlift.

Type parameters

E

the error type

I

the input type

O

the inner output type; the outer output type becomes Option[O]

Value parameters

alterand

the inner stage whose output is optionally present

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
trait Fruitful[I, Option[O], E]
trait Alterator[Stage[I, O, E], I, Option[O], E]
trait Stage[I, Option[O], E]
trait I => Yield[I, Option[O], E]
class Object
trait Matchable
class Any
Show all
final case class LocalSoftDeadline[-I, +O, +E](tsSupplier: () => Long, now: () => Long, duration: Long, alterand: Stage[I, O, E]) extends Decorator[I, O, E]

A decorator that stops the pipeline when a time budget measured from the beginning of the current unit of work is exhausted.

A decorator that stops the pipeline when a time budget measured from the beginning of the current unit of work is exhausted.

Unlike h8io.stages.std.GlobalSoftDeadline, which measures time from the moment the stage is created and never resets, LocalSoftDeadline measures time from the apply call that started the current unit of work: the timestamp is captured at that call and preserved for as long as the evolution is invoked with h8io.stages.Status.Success. When the evolution is invoked with any other status, the clock is reset — the new window starts at the next apply call. The same reset happens after the deadline has been exceeded.

The deadline is ''soft'': it is checked after the inner stage has already been applied. If it is exceeded, a h8io.stages.Status.Success in the current h8io.stages.Yield is upgraded to an errorless h8io.stages.Status.Complete; any other status is left unchanged.

If duration ≤ 0 the factory methods return h8io.stages.std.DeadEnd directly, ensuring the pipeline immediately terminates.

Type parameters

E

the error type (covariant)

I

the input type (contravariant)

O

the output type (covariant)

Value parameters

alterand

the inner stage whose deadline is enforced

duration

the time budget in nanoseconds

now

a supplier of the current time in nanoseconds

tsSupplier

a thunk that returns the timestamp of the start of the current deadline window

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait Alterator[Stage[I, O, E], I, O, E]
trait Stage[I, O, E]
trait I => Yield[I, O, E]
class Object
trait Matchable
class Any
Show all
object LocalSoftDeadline

Companion object and factory for LocalSoftDeadline.

Companion object and factory for LocalSoftDeadline.

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class Or[-I, +LO, +RO, +E](left: Stage[I, LO, E], right: Stage[I, RO, E]) extends BinaryOperator[Stage[I, LO, E], Stage[I, RO, E], I, Either[LO, RO], E]

A binary operator that tries left first; if left produces no output, it falls back to right, wrapping the result in scala.util.Either.

A binary operator that tries left first; if left produces no output, it falls back to right, wrapping the result in scala.util.Either.

Evaluation rules for a given input:

  • If left yields h8io.stages.Yield.Some, the result is Yield.Some(Left(leftOut), leftStatus, ...). right is not applied.
  • If left yields h8io.stages.Yield.None, right is applied:
    • right yields Some → Yield.Some(Right(rightOut), mergedStatus, ...).
    • right yields None → Yield.None(mergedStatus, ...).

Statuses are merged with combine.

Type parameters

E

the error type (covariant)

I

the shared input type (contravariant)

LO

the left output type (covariant)

RO

the right output type (covariant)

Value parameters

left

the preferred stage; tried first

right

the fallback stage; tried only when left yields no output

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait BinaryOperator[Stage[I, LO, E], Stage[I, RO, E], I, Either[LO, RO], E]
trait Stage[I, Either[LO, RO], E]
trait I => Yield[I, Either[LO, RO], E]
class Object
trait Matchable
class Any
Show all
object Or

Companion object for Or.

Companion object for Or.

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
Or.type
final case class Safe[-I, +O, +E](alterand: Stage[I, O, E]) extends Alterator[Stage[I, O, E], I, O, Either[Throwable, E]], SafeStage[I, O, Either[Throwable, E]]

A decorator that catches non-fatal exceptions thrown by the inner stage and converts them into h8io.stages.Status.Complete error values.

A decorator that catches non-fatal exceptions thrown by the inner stage and converts them into h8io.stages.Status.Complete error values.

The error type is widened from E to Either[Throwable, E]:

  • Errors already carried by the inner stage are wrapped as Right(e).
  • Exceptions caught during apply are reported as Left(throwable) in a Yield.None(Status.error(Left(e)), this).

Only non-fatal exceptions (matched by scala.util.control.NonFatal) are caught; fatal errors such as OutOfMemoryError propagate normally.

The evolution is mapped so that every continuation stage remains wrapped in Safe, maintaining exception safety across the entire pipeline.

Safe is a crutch for the simplest cases — ''stateless'' stages. Per the ''Lifecycle'' contract in h8io.stages.Stage, a stage that throws from apply has already released its own resources, so the recovered continuation simply reuses the inner stage — retrying it on the next input — and carries a no-op dispose. A stage that owns resources should be made safe by itself instead of being wrapped: extend h8io.stages.base.SafeStage and supply a recover with the appropriate cleanup (the h8io.stages.base.ConstEvolution overload taking a dispose function exists for exactly this).

Type parameters

E

the original error type of the inner stage (covariant)

I

the input type (contravariant)

O

the output type (covariant)

Value parameters

alterand

the inner stage whose exceptions should be caught

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
trait SafeStage[I, O, Either[Throwable, E]]
trait Alterator[Stage[I, O, E], I, O, Either[Throwable, E]]
trait Stage[I, O, Either[Throwable, E]]
trait I => Yield[I, O, Either[Throwable, E]]
class Object
trait Matchable
class Any
Show all
Generated with