Introduce SearchResult and SearchResults.

src/main/java/org/springframework/data/domain/Page.java

@@ -69,4 +69,5 @@ static <T> Page<T> empty(Pageable pageable) {
  */
 @Override
 <U> Page<U> map(Function<? super T, ? extends U> converter);
+
 }

src/main/java/org/springframework/data/domain/Score.java

@@ -0,0 +1,125 @@
+/*
+ * Copyright 2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.domain;
+
+import java.io.Serializable;
+
+import org.springframework.util.ObjectUtils;
+
+/**
+ * Value object to represent search result scores determined by a {@link ScoringFunction}. Scores are used to rank
+ * search results and typically, a higher score indicates a more relevant result.
+ *
+ * @author Mark Paluch
+ * @since 4.0
+ */
+public sealed class Score implements Serializable permits Similarity {
+
+private final double value;
+private final ScoringFunction function;
+
+Score(double value, ScoringFunction function) {
+this.value = value;
+this.function = function;
+}
+
+/**
+ * Creates a new {@link Score} from a plain {@code score} value using {@link ScoringFunction#UNSPECIFIED}.
+ *
+ * @param score the score value without a specific {@link ScoringFunction}.
+ * @return the new {@link Score}.
+ */
+public static Score of(double score) {
+return of(score, ScoringFunction.UNSPECIFIED);
+}
+
+/**
+ * Creates a new {@link Score} from a {@code score} value using the given {@link ScoringFunction}.
+ *
+ * @param score the score value.
+ * @param function the scoring function that has computed the {@code score}.
+ * @return the new {@link Score}.
+ */
+public static Score of(double score, ScoringFunction function) {
+return new Score(score, function);
+}
+
+/**
+ * Creates a {@link Range} between the given {@link Score}.
+ *
+ * @param min can be {@literal null}.
+ * @param max can be {@literal null}.
+ * @return will never be {@literal null}.
+ */
+public static Range<Score> between(Score min, Score max) {
+return Range.from(Range.Bound.inclusive(min)).to(Range.Bound.inclusive(max));
+}
+
+/**
+ * Creates a new {@link Range} by creating minimum and maximum {@link Score} from the given values without
+ * {@link ScoringFunction#UNSPECIFIED specifying a scoring function}.
+ *
+ * @param minValue minimum value.
+ * @param maxValue maximum value.
+ * @return the {@link Range} between the given values.
+ */
+public static Range<Score> between(double minValue, double maxValue) {
+return between(minValue, maxValue, ScoringFunction.UNSPECIFIED);
+}
+
+/**
+ * Creates a new {@link Range} by creating minimum and maximum {@link Score} from the given values.
+ *
+ * @param minValue minimum value.
+ * @param maxValue maximum value.
+ * @param function the scoring function to use.
+ * @return the {@link Range} between the given values.
+ */
+public static Range<Score> between(double minValue, double maxValue, ScoringFunction function) {
+return between(Score.of(minValue, function), Score.of(maxValue, function));
+}
+
+public double getValue() {
+return value;
+}
+
+public ScoringFunction getFunction() {
+return function;
+}
+
+@Override
+public boolean equals(Object o) {
+if (!(o instanceof Score other)) {
+return false;
+}
+if (value != other.value) {
+return false;
+}
+return ObjectUtils.nullSafeEquals(function, other.function);
+}
+
+@Override
+public int hashCode() {
+return ObjectUtils.nullSafeHash(value, function);
+}
+
+@Override
+public String toString() {
+return function instanceof UnspecifiedScoringFunction ? Double.toString(value)
+: "%s (%s)".formatted(Double.toString(value), function.getName());
+}
+
+}

src/main/java/org/springframework/data/domain/ScoringFunction.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.domain;
+
+/**
+ * @author Mark Paluch
+ * @since 4.0
+ */
+public interface ScoringFunction {
+
+/**
+ * The default {@link ScoringFunction} when none is specified.
+ */
+ScoringFunction UNSPECIFIED = UnspecifiedScoringFunction.INSTANCE;
+
+String getName();
+}

src/main/java/org/springframework/data/domain/SearchResult.java

@@ -0,0 +1,102 @@
+/*
+ * Copyright 2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.domain;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.util.function.Function;
+
+import org.jspecify.annotations.Nullable;
+
+import org.springframework.util.Assert;
+import org.springframework.util.ObjectUtils;
+
+/**
+ * Value object capturing some arbitrary object plus a distance.
+ *
+ * @author Mark Paluch
+ * @since 4.0
+ */
+public final class SearchResult<T> implements Serializable {
+
+private static final @Serial long serialVersionUID = 1637452570977581370L;
+
+private final T content;
+private final Score score;
+
+public SearchResult(T content, Score score) {
+
+Assert.notNull(content, "Content must not be null");
+Assert.notNull(score, "Score must not be null");
+
+this.content = content;
+this.score = score;
+}
+
+public SearchResult(T content, double score) {
+this(content, Score.of(score));
+}
+
+public T getContent() {
+return this.content;
+}
+
+public Score getScore() {
+return this.score;
+}
+
+@Override
+public boolean equals(@Nullable Object o) {
+
+if (this == o) {
+return true;
+}
+
+if (!(o instanceof SearchResult<?> result)) {
+return false;
+}
+
+if (!ObjectUtils.nullSafeEquals(content, result.content)) {
+return false;
+}
+
+return ObjectUtils.nullSafeEquals(score, result.score);
+}
+
+@Override
+public int hashCode() {
+return ObjectUtils.nullSafeHash(content, score);
+}
+
+@Override
+public String toString() {
+return String.format("SearchResult [content: %s, score: %s]", content, score);
+}
+
+/**
+ * Returns new {@link SearchResults} with the content of the current one mapped by the given {@link Function}.
+ *
+ * @param converter must not be {@literal null}.
+ * @return a new {@link SearchResults} with the content of the current one mapped by the given {@link Function}.
+ */
+public <U> SearchResult<U> map(Function<? super T, ? extends U> converter) {
+
+Assert.notNull(converter, "Function must not be null");
+
+return new SearchResult<>(converter.apply(getContent()), getScore());
+}
+
+}

src/main/java/org/springframework/data/domain/SearchResults.java

@@ -0,0 +1,99 @@
+/*
+ * Copyright 2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.data.domain;
+
+import java.io.Serializable;
+import java.util.Collections;
+import java.util.Iterator;
+import java.util.List;
+import java.util.function.Function;
+import java.util.stream.Collectors;
+
+import org.springframework.util.Assert;
+import org.springframework.util.ObjectUtils;
+import org.springframework.util.StringUtils;
+
+/**
+ * Value object to capture {@link SearchResult}s.
+ *
+ * @author Mark Paluch
+ * @since 4.0
+ */
+public class SearchResults<T> implements Iterable<SearchResult<T>>, Serializable {
+
+private final List<? extends SearchResult<T>> results;
+
+public SearchResults(List<SearchResult<T>> results) {
+this.results = results;
+}
+
+/**
+ * Returns the actual content of the {@link SearchResult}s.
+ *
+ * @return the actual content.
+ */
+public List<SearchResult<T>> getContent() {
+return Collections.unmodifiableList(results);
+}
+
+@Override
+public Iterator<SearchResult<T>> iterator() {
+return (Iterator<SearchResult<T>>) results.iterator();
+}
+
+/**
+ * Returns new {@link SearchResults} with the content of the current one mapped by the given {@link Function}.
+ *
+ * @param converter must not be {@literal null}.
+ * @return a new {@link SearchResults} with the content of the current one mapped by the given {@link Function}.
+ */
+public <U> SearchResults<U> map(Function<? super T, ? extends U> converter) {
+
+Assert.notNull(converter, "Function must not be null");
+
+List<SearchResult<U>> result = results.stream().map(it -> {
+
+SearchResult<U> mapped = it.map(converter);
+return mapped;
+}).collect(Collectors.toList());
+
+return new SearchResults<>(result);
+}
+
+@Override
+public boolean equals(Object o) {
+
+if (o == this) {
+return true;
+}
+
+if (!(o instanceof SearchResults<?> that)) {
+return false;
+}
+return ObjectUtils.nullSafeEquals(results, that.results);
+}
+
+@Override
+public int hashCode() {
+return ObjectUtils.nullSafeHashCode(results);
+}
+
+@Override
+public String toString() {
+return String.format("SearchResults: [results: %s]", StringUtils.collectionToCommaDelimitedString(results));
+}
+
+}