cognesy/instructor-pipeline

Pipeline processing functionality for Instructor PHP library

v2.0.0 2026-03-13 19:49 UTC

Requires

• php: ^8.3
• cognesy/instructor-utils: ^2.0
• psr/event-dispatcher: ^1.0

Requires (Dev)

• icanhazstring/composer-unused: ^0.9.0
• jetbrains/phpstorm-attributes: ^1.2
• maglnet/composer-require-checker: ^4.16
• pestphp/pest: ^2.34
• phpbench/phpbench: ^1.4
• phpstan/phpstan: ^1.11
• roave/security-advisories: dev-latest
• vimeo/psalm: ^6.0

MIT

• Dariusz Debowczyk

README

Small immutable pipelines for value transformations with Result-backed state.

What It Is

The package now exposes one pipeline implementation:

• value-oriented steps via through() and throughAll()
• side effects via tap() and onFailure()
• final shaping via finally()
• lazy execution via PendingExecution
• immutable state via ProcessingState
• post-processing helpers via TransformState

Basic Usage

use Cognesy\Pipeline\Pipeline;
use Cognesy\Pipeline\ProcessingState;

$result = Pipeline::builder()
    ->through(fn(string $value) => trim($value))
    ->through(fn(string $value) => strtoupper($value))
    ->create()
    ->executeWith(ProcessingState::with(' hello '))
    ->value();

Failure Handling

use Cognesy\Pipeline\StateContracts\CanCarryState;
use Cognesy\Utils\Result\Result;

$result = Pipeline::builder()
    ->through(fn() => throw new RuntimeException('broken'))
    ->onFailure(fn(CanCarryState $state) => report($state->exception()))
    ->finally(fn(CanCarryState $state) => match ($state->isSuccess()) {
        true => $state->result(),
        false => Result::failure('pipeline failed'),
    })
    ->create()
    ->executeWith(ProcessingState::with('input'))
    ->result();

State Helpers

ProcessingState stores:

• a Result
• ordered tags

TransformState is a small helper for mapping, recovery, and tag-preserving state transformations after pipeline execution.