A higher-order API does not only accept data.
It accepts behavior slots with contracts.

Good API design makes those slots explicit:
  - what input is given?
  - what output is expected?
  - may it mutate?
  - may it throw?
  - is order important?
  - is it called once, many times, lazily, eagerly?
  - who owns side effects?
  - how are diagnostics preserved?

Mendesain API berbasis composition pipeline yang memungkinkan behavior disusun tanpa kehilangan type safety, semantic clarity, diagnostics, dan evolvability.

Higher-order API design:
  ├─ identify behavior variation points
  ├─ choose correct functional shape
  ├─ name behavior using domain roles
  ├─ define stage input/output contract
  ├─ compose behavior deterministically
  ├─ preserve diagnostics and failure context
  ├─ avoid function soup
  ├─ avoid hidden side effects
  ├─ design fluent/staged APIs responsibly
  ├─ balance generic flexibility vs usability
  ├─ make ordering rules explicit
  └─ test contracts at composition boundary

Function<T, R> everywhere
Predicate returning false without reason
Consumer hiding business mutation
Pipeline stages with implicit ordering
Callback hell in Java form
Boolean blindness
Stringly-typed hooks
Side-effectful mappers
Generic signatures too clever for users
Framework magic without contract clarity

List<CaseFile> highRisk = cases.stream()
    .filter(CaseFile::isHighRisk)
    .toList();

Decision decision = DecisionPipeline.<CaseCommand>builder()
    .validate(command -> command.caseId() != null)
    .authorize((actor, command) -> actor.can("CASE_APPROVE"))
    .transform(command -> command.normalized())
    .decide(command -> Decision.approved(command.caseId()))
    .execute(command, actor);

Apakah API ini menjelaskan kontrak behavior dengan cukup jelas?

Function<String, String> normalize = String::trim;
Predicate<CaseFile> highRisk = CaseFile::isHighRisk;
Supplier<Instant> now = clock::instant;
Consumer<AuditEvent> publishAudit = auditPublisher::publish;
UnaryOperator<CaseDraft> sanitize = CaseDraft::sanitized;

public Decision execute(
    Function<Request, Request> f1,
    Predicate<Request> f2,
    Consumer<Request> f3
) { ... }

public Decision execute(
    RequestNormalizer normalizer,
    EligibilityRule eligibilityRule,
    AuditSink auditSink
) { ... }

@FunctionalInterface
public interface RequestNormalizer {
    Request normalize(Request request);
}

@FunctionalInterface
public interface EligibilityRule {
    EligibilityResult evaluate(Request request);
}

@FunctionalInterface
public interface AuditSink {
    void record(AuditEvent event);
}

Function<Request, Request> says shape.
RequestNormalizer says intent.

Predicate<Request> says boolean.
EligibilityRule says business decision point.

Consumer<AuditEvent> says side effect.
AuditSink says side-effect boundary.

Function<CaseFile, CaseFile> f;

normalize case
redact sensitive fields
apply defaults
calculate derived fields
sanitize unsafe text
upgrade schema
remove invalid attachments

Use java.util.function for local code and obvious transformations.
Use named functional interfaces for public API, framework extension point, domain rule, or anything with non-trivial semantics.

Predicate<CaseCommand> valid = command -> command.caseId() != null;

false means what?
  - missing case id?
  - invalid format?
  - forbidden state?
  - external policy failed?

@FunctionalInterface
public interface Validator<T> {
    ValidationResult validate(T value);
}

public record ValidationResult(
    boolean valid,
    List<Violation> violations
) {
    public static ValidationResult ok() {
        return new ValidationResult(true, List.of());
    }

    public static ValidationResult failed(Violation violation) {
        return new ValidationResult(false, List.of(violation));
    }
}

Validator<CaseCommand> hasCaseId = command ->
    command.caseId() == null
        ? ValidationResult.failed(new Violation("caseId", "caseId is required"))
        : ValidationResult.ok();

Function<String, String> trim = String::trim;
Function<String, String> upper = String::toUpperCase;

Function<String, String> normalize = trim.andThen(upper);

String result = normalize.apply("  abc  "); // "ABC"

input -> trim -> upper -> output

Function<String, String> normalize = upper.compose(trim);

input -> trim -> upper -> output

Predicate<CaseFile> open = CaseFile::isOpen;
Predicate<CaseFile> highRisk = CaseFile::isHighRisk;

Predicate<CaseFile> actionable = open.and(highRisk);

Consumer<AuditEvent> log = logger::info;
Consumer<AuditEvent> publish = auditPublisher::publish;

Consumer<AuditEvent> audit = log.andThen(publish);

Kalau log berhasil tapi publish gagal, apa status operasi?
Kalau log gagal, apakah publish tetap jalan?
Apakah urutan observable oleh user?
Apakah operation idempotent?

Pipeline
  ├─ input contract
  ├─ stage list
  ├─ stage order
  ├─ context propagation
  ├─ failure semantics
  ├─ result semantics
  ├─ diagnostics model
  └─ extension policy

public interface Stage<I, O> {
    O apply(I input);
}

@FunctionalInterface
public interface PipelineStage<I, O> {
    StageResult<O> apply(I input, PipelineContext context);
}

public sealed interface StageResult<T>
    permits StageResult.Continue, StageResult.Stop {

    record Continue<T>(T value) implements StageResult<T> {}

    record Stop<T>(PipelineFailure failure) implements StageResult<T> {}

    static <T> StageResult<T> proceed(T value) {
        return new Continue<>(value);
    }

    static <T> StageResult<T> stop(PipelineFailure failure) {
        return new Stop<>(failure);
    }
}

public record PipelineContext(
    String correlationId,
    Actor actor,
    Instant startedAt,
    Map<String, Object> attributes
) {}

Stage can continue or stop explicitly.
Business failure is not encoded as null.
Diagnostics have a home.
Context is explicit.

public record CaseCommand(
    String caseId,
    String action,
    String reason
) {}

public record Violation(String field, String message) {}

public record ValidationReport(List<Violation> violations) {
    public boolean valid() {
        return violations.isEmpty();
    }

    public ValidationReport merge(ValidationReport other) {
        var merged = new ArrayList<Violation>(violations);
        merged.addAll(other.violations);
        return new ValidationReport(List.copyOf(merged));
    }

    public static ValidationReport ok() {
        return new ValidationReport(List.of());
    }

    public static ValidationReport failed(String field, String message) {
        return new ValidationReport(List.of(new Violation(field, message)));
    }
}

@FunctionalInterface
public interface CaseValidator {
    ValidationReport validate(CaseCommand command);

    default CaseValidator and(CaseValidator next) {
        Objects.requireNonNull(next, "next validator must not be null");
        return command -> this.validate(command).merge(next.validate(command));
    }
}

CaseValidator requireCaseId = command ->
    command.caseId() == null || command.caseId().isBlank()
        ? ValidationReport.failed("caseId", "caseId is required")
        : ValidationReport.ok();

CaseValidator requireReason = command ->
    command.reason() == null || command.reason().isBlank()
        ? ValidationReport.failed("reason", "reason is required")
        : ValidationReport.ok();

CaseValidator validator = requireCaseId.and(requireReason);

ValidationReport report = validator.validate(new CaseCommand(null, "CLOSE", ""));

Composition rule belongs to CaseValidator.
Failure diagnostics are preserved.
No exception for expected validation failure.
No boolean blindness.
No framework required.

@FunctionalInterface
public interface CaseCommandTransformer {
    CaseCommand transform(CaseCommand command);

    default CaseCommandTransformer andThen(CaseCommandTransformer next) {
        Objects.requireNonNull(next, "next transformer must not be null");
        return command -> next.transform(this.transform(command));
    }
}

CaseCommandTransformer trimFields = command -> new CaseCommand(
    trim(command.caseId()),
    trim(command.action()),
    trim(command.reason())
);

CaseCommandTransformer uppercaseAction = command -> new CaseCommand(
    command.caseId(),
    command.action() == null ? null : command.action().toUpperCase(Locale.ROOT),
    command.reason()
);

CaseCommandTransformer normalize = trimFields.andThen(uppercaseAction);

private static String trim(String value) {
    return value == null ? null : value.trim();
}

A transformer should return a value.
A transformer should not secretly publish events, write database rows, or mutate global state.

BiPredicate<Actor, CaseCommand> canApprove;

@FunctionalInterface
public interface AuthorizationPolicy<C> {
    AuthorizationDecision decide(Actor actor, C command);
}

public sealed interface AuthorizationDecision
    permits AuthorizationDecision.Allowed, AuthorizationDecision.Denied {

    record Allowed() implements AuthorizationDecision {}

    record Denied(String reasonCode, String message) implements AuthorizationDecision {}

    static AuthorizationDecision allowed() {
        return new Allowed();
    }

    static AuthorizationDecision denied(String code, String message) {
        return new Denied(code, message);
    }
}

public final class AuthorizationPolicies {
    private AuthorizationPolicies() {}

    public static <C> AuthorizationPolicy<C> allOf(List<AuthorizationPolicy<C>> policies) {
        return (actor, command) -> {
            for (AuthorizationPolicy<C> policy : policies) {
                AuthorizationDecision decision = policy.decide(actor, command);
                if (decision instanceof AuthorizationDecision.Denied) {
                    return decision;
                }
            }
            return AuthorizationDecision.allowed();
        };
    }
}

Authorization sering butuh stop on first deny.
Validation sering butuh collect all violations.
Transformation biasanya sequential.
Audit biasanya best-effort atau transactional tergantung requirement.

Pipeline.builder()
    .execute(input); // compile, tapi belum ada stage penting

public final class CasePipeline {
    private final CaseCommandTransformer transformer;
    private final CaseValidator validator;
    private final AuthorizationPolicy<CaseCommand> authorization;
    private final CaseHandler handler;

    private CasePipeline(
        CaseCommandTransformer transformer,
        CaseValidator validator,
        AuthorizationPolicy<CaseCommand> authorization,
        CaseHandler handler
    ) {
        this.transformer = transformer;
        this.validator = validator;
        this.authorization = authorization;
        this.handler = handler;
    }

    public static TransformerStep builder() {
        return transformer -> validator -> authorization -> handler ->
            new CasePipeline(transformer, validator, authorization, handler);
    }

    public interface TransformerStep {
        ValidatorStep transformer(CaseCommandTransformer transformer);
    }

    public interface ValidatorStep {
        AuthorizationStep validator(CaseValidator validator);
    }

    public interface AuthorizationStep {
        HandlerStep authorization(AuthorizationPolicy<CaseCommand> authorization);
    }

    public interface HandlerStep {
        CasePipeline handler(CaseHandler handler);
    }
}

CasePipeline pipeline = CasePipeline.builder()
    .transformer(normalize)
    .validator(validator)
    .authorization(policy)
    .handler(handler);

Cannot build without required pieces.
Order is visible.
Behavior roles are named.

More types.
More boilerplate.
Can be overkill for small APIs.

Use staged builders when invalid construction is costly or common.
Use simple constructors/factories when API is small and obvious.

public ExecutionResult execute(CaseCommand rawCommand, Actor actor) {
    CaseCommand command = transformer.transform(rawCommand);

    ValidationReport validation = validator.validate(command);
    if (!validation.valid()) {
        return ExecutionResult.rejected(validation);
    }

    AuthorizationDecision authz = authorization.decide(actor, command);
    if (authz instanceof AuthorizationDecision.Denied denied) {
        return ExecutionResult.forbidden(denied);
    }

    return handler.handle(command, actor);
}

Easy to test.
Easy to debug.
Easy to trace.
No hidden reflection.
No annotation magic.
No lifecycle surprise.

public <T, R> List<R> map(
    List<? extends T> values,
    Function<? super T, ? extends R> mapper
) {
    return values.stream().map(mapper).toList();
}

values may produce T or subtype of T.
mapper may accept T or supertype of T.
mapper may return R or subtype of R.

public interface Transformer<I, O> {
    O transform(I input);
}

public static <I, O> List<O> transformAll(
    List<? extends I> inputs,
    Transformer<? super I, ? extends O> transformer
) {
    List<O> result = new ArrayList<>();
    for (I input : inputs) {
        result.add(transformer.transform(input));
    }
    return List.copyOf(result);
}

Supplier<Token> tokenSupplier = authClient::fetchToken;

Apakah fetchToken dipanggil saat API dibuat?
Saat execute?
Setiap request?
Hanya saat token expired?
Apakah hasil di-cache?
Apakah thread-safe?

public interface TokenProvider {
    Token currentToken(); // may cache, may refresh, documented
}

public final class ClientOptions {
    private final Supplier<Token> tokenSupplier;

    /**
     * The supplier is invoked for every outbound request.
     * Implementations should be fast and thread-safe if the client is shared.
     */
    public ClientOptions(Supplier<Token> tokenSupplier) {
        this.tokenSupplier = Objects.requireNonNull(tokenSupplier);
    }
}

When accepting Supplier, document execution timing and caching semantics.

public interface ImportListener {
    void onRowAccepted(int rowNumber);
    void onRowRejected(int rowNumber, List<Violation> violations);
    void onCompleted(ImportSummary summary);
}

Consumer<Integer> onAccepted;
BiConsumer<Integer, List<Violation>> onRejected;
Consumer<ImportSummary> onCompleted;

Listener groups related callbacks.
Default methods can provide optional hooks.
Lifecycle is easier to document.
Future extension is easier.

public interface ImportListener {
    default void onRowAccepted(int rowNumber) {}
    default void onRowRejected(int rowNumber, List<Violation> violations) {}
    default void onCompleted(ImportSummary summary) {}
}

Default no-op methods make hooks optional.
But they can hide missing implementation if user expected callback to run.

Listener observes.
Interceptor participates.

void onDecisionMade(Decision decision);

Decision aroundDecision(DecisionRequest request, DecisionChain chain);

@FunctionalInterface
public interface DecisionInterceptor {
    Decision intercept(DecisionRequest request, DecisionChain chain);
}

@FunctionalInterface
public interface DecisionChain {
    Decision proceed(DecisionRequest request);
}

DecisionInterceptor timing = (request, chain) -> {
    long started = System.nanoTime();
    try {
        return chain.proceed(request);
    } finally {
        long elapsed = System.nanoTime() - started;
        metrics.record("decision.elapsed", elapsed);
    }
};

May call proceed zero, one, or multiple times?
May replace request?
May replace response?
May throw?
Is order deterministic?

Interceptor may call proceed at most once.
Interceptor order follows registration order.
Exceptions propagate unless documented otherwise.

public Pipeline add(Stage stage) {
    stages.add(stage); // maybe NPE later
    return this;
}

public Pipeline add(Stage stage) {
    stages.add(Objects.requireNonNull(stage, "stage must not be null"));
    return this;
}

Empty transformation pipeline = identity?
Empty validation pipeline = valid?
Empty authorization policy = deny all or allow all?

public static CaseCommandTransformer identity() {
    return command -> command;
}

public static CaseValidator alwaysValid() {
    return command -> ValidationReport.ok();
}

public static <C> AuthorizationPolicy<C> denyAll() {
    return (actor, command) -> AuthorizationDecision.denied(
        "POLICY_NOT_CONFIGURED",
        "No authorization policy configured"
    );
}

public final class OrderedStage<I, O> {
    private final int order;
    private final PipelineStage<I, O> stage;
}

enum StagePhase {
    NORMALIZE,
    VALIDATE,
    AUTHORIZE,
    DECIDE,
    AUDIT
}

If order changes behavior, make order visible in API or type structure.

StageResult<O> result = stage.apply(input, context);
if (result == null) {
    throw new IllegalStateException(
        "Stage " + stageName + " returned null; stages must return StageResult"
    );
}

NullPointerException

Stage 'normalize-case-id' returned null. Pipeline stages must return StageResult.proceed(value) or StageResult.stop(failure).

pipeline.add(command -> normalize(command));

pipeline.add("normalize-case-id", command -> normalize(command));

public Pipeline add(String name, CaseCommandTransformer transformer) {
    stages.add(new NamedStage<>(
        requireValidName(name),
        Objects.requireNonNull(transformer)
    ));
    return this;
}

public interface NamedTransformer<T> extends UnaryOperator<T> {
    String name();
}

Every user-provided behavior in framework-like APIs should have a diagnostic identity.

register(
    x -> x.a() != null,
    x -> x.b().trim(),
    (x, y) -> x.can(y),
    x -> publisher.publish(x),
    x -> mapper.toDto(x)
);

Readers must reverse-engineer role by position.
Parameter order is fragile.
Debugging is poor.
Future extension breaks callers.

CaseActionDefinition definition = CaseActionDefinition.builder()
    .eligibilityRule(hasOpenCase())
    .normalizer(trimActionFields())
    .authorizationPolicy(requiresPermission("CASE_APPROVE"))
    .auditSink(auditPublisher::publish)
    .responseMapper(CaseResponseMapper.standard())
    .build();

When behavior count > 2, prefer named builder/factory over positional arguments.

var names = users.stream()
    .filter(User::active)
    .map(User::name)
    .toList();

public interface UserEligibilityRule {
    EligibilityDecision evaluate(User user, EligibilityContext context);
}

@FunctionalInterface
public interface Rule<F> {
    RuleResult evaluate(F fact);

    default Rule<F> and(Rule<F> next) {
        Objects.requireNonNull(next, "next rule must not be null");
        return fact -> {
            RuleResult first = this.evaluate(fact);
            if (!first.matched()) {
                return first;
            }
            return next.evaluate(fact);
        };
    }

    default Rule<F> or(Rule<F> alternative) {
        Objects.requireNonNull(alternative, "alternative rule must not be null");
        return fact -> {
            RuleResult first = this.evaluate(fact);
            if (first.matched()) {
                return first;
            }
            return alternative.evaluate(fact);
        };
    }
}

public record RuleResult(
    boolean matched,
    String code,
    String explanation
) {
    public static RuleResult match(String code, String explanation) {
        return new RuleResult(true, code, explanation);
    }

    public static RuleResult noMatch(String code, String explanation) {
        return new RuleResult(false, code, explanation);
    }
}

Rule<CaseFile> hasEvidence = file ->
    file.evidenceCount() > 0
        ? RuleResult.match("HAS_EVIDENCE", "Case has evidence")
        : RuleResult.noMatch("NO_EVIDENCE", "Case has no evidence");

Rule<CaseFile> isOpen = file ->
    file.status() == CaseStatus.OPEN
        ? RuleResult.match("CASE_OPEN", "Case is open")
        : RuleResult.noMatch("CASE_NOT_OPEN", "Case is not open");

Rule<CaseFile> actionable = isOpen.and(hasEvidence);

Pipeline.define("case-approval")
    .normalize(trimFields())
    .validate(requireCaseId())
    .validate(requireReason())
    .authorize(requiresPermission("CASE_APPROVE"))
    .handle(approveCase())
    .build();

method chain terlalu panjang
state internal mutable tidak jelas
urutan bebas padahal tidak valid
error baru muncul saat runtime
terlalu banyak overload ambiguous
lambda parameter names tidak membantu

Fluent API should encode workflow, not hide it.

allocation/capture risk
indirection call
less obvious stack trace
potential megamorphic call site
debugger step-through cost

public final class CaseService {
    private final CasePipeline pipeline;

    public CaseService(CasePipeline pipeline) {
        this.pipeline = Objects.requireNonNull(pipeline);
    }

    public ExecutionResult execute(CaseCommand command, Actor actor) {
        return pipeline.execute(command, actor);
    }
}

@Test
void executesTransformersInRegistrationOrder() {
    List<String> calls = new ArrayList<>();

    CaseCommandTransformer first = command -> {
        calls.add("first");
        return command;
    };
    CaseCommandTransformer second = command -> {
        calls.add("second");
        return command;
    };

    CaseCommandTransformer composed = first.andThen(second);
    composed.transform(new CaseCommand("C-1", "APPROVE", "ok"));

    assertEquals(List.of("first", "second"), calls);
}

@Test
void authorizationStopsAtFirstDeny() {
    AtomicBoolean secondCalled = new AtomicBoolean(false);

    AuthorizationPolicy<CaseCommand> deny = (actor, command) ->
        AuthorizationDecision.denied("DENIED", "No access");

    AuthorizationPolicy<CaseCommand> second = (actor, command) -> {
        secondCalled.set(true);
        return AuthorizationDecision.allowed();
    };

    var policy = AuthorizationPolicies.allOf(List.of(deny, second));

    policy.decide(actor, command);

    assertFalse(secondCalled.get());
}

@Test
void reportsStageNameWhenStageReturnsNull() {
    Pipeline pipeline = Pipeline.builder()
        .add("bad-stage", input -> null)
        .build();

    IllegalStateException ex = assertThrows(
        IllegalStateException.class,
        () -> pipeline.execute(input)
    );

    assertTrue(ex.getMessage().contains("bad-stage"));
}

1. What behavior varies?
2. Is the behavior local or public extension point?
3. Is java.util.function expressive enough?
4. Does the behavior need a domain name?
5. What is input/output contract?
6. May it mutate input?
7. May it perform side effects?
8. May it throw checked/unchecked exceptions?
9. Is failure expected or exceptional?
10. Is composition sequential, parallel, short-circuiting, or aggregating?
11. Does order matter?
12. How are diagnostics preserved?
13. What is the default empty behavior?
14. What happens if user returns null?
15. How will the API evolve later?

Predicate<Command> valid;

Validator<Command> validator;

Function<Command, Command> normalize = command -> {
    auditPublisher.publish(...);
    return command.normalized();
};

pipeline.add(validate);
pipeline.add(normalize);

configure(a -> ..., b -> ..., c -> ...);

Pipeline failed in lambda$configure$2

Ambil service method besar yang memiliki banyak if/else policy.
Pisahkan menjadi:
  - transformer
  - validator
  - authorization policy
  - handler
  - audit sink

Desain custom functional interface untuk validation.
Jangan return boolean.
Return report dengan violation list.

Buat staged builder yang tidak bisa build pipeline tanpa validator dan handler.

Tambahkan diagnostic stage name dan test error message ketika stage return null.

Bandingkan dua desain:
  - API dengan Function/Predicate/Consumer langsung
  - API dengan named domain functional interfaces
Nilai readability dan evolvability-nya.

Use behavior-as-value to expose controlled variation points.
Name domain behavior when semantics matter.
Keep pipeline ordering explicit.
Preserve diagnostics.
Separate transformation, decision, validation, and side effects.
Prefer result objects for expected business failure.
Use fluent API only when it improves correctness and readability.

A good composition API is not just flexible.
It is constrained in the right places.