Add combinator

[mikemedina]

It's common when validating multiple inputs (something like form validation) to have many possible results where you can only continue if they're all ok and you need to effectively short-circuit on any err.

Using Result::mapOk and Result::flatMapOk can be handy, but when you need to refer to the unwrapped ok values all within one scope, you end up with the "pyramid of doom" nested indentation:

public static Result<ExamplePrivilegeEgg, ExampleError> fromUrn(String urn) {
  String[] split = urn.split(":");
  if (split.length != 3) {
    return Result.err(ExampleError.INVALID_URN);
  }

  return Optional
    .ofNullable(Longs.tryParse(split[1]))
    .map(Result::<Long, ExampleError>ok)
    .orElseGet(() -> Result.err(ExampleError.INVALID_PRIVILEGE_ID))
    .flatMapOk(id ->
      EntityType
        .from(split[0])
        .flatMapOk(privilegeType ->
          GrantType
            .from(split[2])
            .flatMapOk(grantType ->
              Result.ok(
                // Here we need id, privilegeType, and grantType from the scopes above
                ExamplePrivilegeEgg
                  .builder()
                  .setEntityId(id)
                  .setEntityType(privilegeType)
                  .setGrantType(grantType)
                  .build()
              )
            )
        )
    );
}

An alternative approach is to check each intermediate result and return early with guard clauses which is much more readable but we end up having a pile of extra code blocks, isErr checks, and then having to unwrapOrElseThrow() a bunch of times at the end:

public static Result<ExamplePrivilegeEgg, ExampleError> fromUrn(String urn) {
  String[] split = urn.split(":");
  if (split.length != 3) {
    return Result.err(ExampleError.INVALID_URN);
  }

  Result<EntityType, ExampleError> entityResult = EntityType.from(split[0]);
  if (entityResult.isErr()) {
    return entityResult.coerceErr();
  }

  Result<GrantType, ExampleError> grantResult = GrantType.from(split[2]);
  if (grantResult.isErr()) {
    return grantResult.coerceErr();
  }

  Result<Long, ExampleError> idResult = Optional
    .ofNullable(Longs.tryParse(split[1]))
    .map(Result::<Long, ExampleError>ok)
    .orElseGet(() -> Result.err(ExampleError.INVALID_PRIVILEGE_ID));
  if (idResult.isErr()) {
    return idResult.coerceErr();
  }

  // unwrap, unwrap, unwrap, etc.
  return ExamplePrivilegeEgg.builder()
      .setEntityId(idResult.unwrapOrElseThrow())
      .setEntityType(entityResult.unwrapOrElseThrow())
      .setGrantType(grantResult.unwrapOrElseThrow())
      .build());
}

This PR adds a Result::combine utility method that let's you combine up to 9 separate results of any type, operate on them all within a single mapping function, and return a new result, short-circuiting if any of the input results contained errors.

public static Result<ExamplePrivilegeEgg, ExampleError> fromUrn(String urn) {
  String[] split = urn.split(":");
  if (split.length != 3) {
    return Result.err(ExampleError.INVALID_URN);
  }

  Result<EntityType, ExampleError> entityResult = EntityType.from(split[0]);
  Result<GrantType, ExampleError> grantResult = GrantType.from(split[2]);
  Result<Long, ExampleError> idResult = Optional
    .ofNullable(Longs.tryParse(split[1]))
    .map(Result::<Long, ExampleError>ok)
    .orElseGet(() -> Result.err(ExampleError.INVALID_PRIVILEGE_ID));

  // Clean, flat chain with safely typed, named parameters
  return Result.combine(idResult)
    .and(entityResult)
    .and(grantResult)
    .map((id, entityType, grantType) -> ExamplePrivilegeEgg
      .builder()
      .setEntityId(id)
      .setEntityType(entityType)
      .setGrantType(grantType)
      .build());
}