Improve PHPStan type hints

[fuzzyfox]

Why

I’m opening this PR because I really like the clean, composable
implementation this library provides. It helps reduce repeated inline and
static closures in my pipelines and makes pipe-heavy code much nicer to
read.

While using it in projects with PHPStan enabled, I ran into a practical
issue: some helpers did not preserve types accurately enough through the
pipeline for static analysis. That meant I couldn’t use all of the
utilities as-is in linted codebases, especially helpers like
str_replace() and preg_replace(), where the runtime behavior was fine
but the inferred types were too loose.

This PR is intended to improve that experience so the library’s ergonomic
runtime API is matched by more accurate type preservation in tools like
PHPStan.

Goal

Improve the project’s PHPStan-facing type hints so the utility helpers
preserve types more accurately through pipelines.

What changed

• tighten and verify type preservation across key helpers such as
  array_map, iterable_map, iterable_filter, collect, array_nth,
  and iterable_nth
• improve typing for helpers such as str_replace() and preg_replace()
  where preserving the subject type is especially important in real
  pipelines
• add and refine PHPStan type assertions to confirm inferred types match
  the intended helper behavior
• use a PHPStan stub file for the more advanced higher-order signatures
  that are difficult to express cleanly on the runtime wrappers
  themselves

Why the stub file exists

The library philosophy is to keep helpers as small unary functions with
minimal runtime machinery. Some of the stronger higher-order PHPStan
signatures are better expressed in analysis-only stubs than in the
runtime implementation.

This keeps the runtime code simple and aligned with the repo’s design,
while still giving users accurate type preservation when using tools like
PHPStan.

Validation

• composer analyse
• targeted PHPUnit coverage for the affected helpers

Authorship

This PR was produced with help from both Claude and Codex, with human
input, changes, and review throughout. This is PR started with a late
night claude mobile session on my way home from work, hence the
branch name.

[lrhoek]

Thank you! I will have a look at this later in the weekend.