Class NonEmptyMap<K,V>

java.lang.Object
dmx.fun.NonEmptyMap<K,V>
Type Parameters:
K - the type of keys
V - the type of values
@NullMarked public final class NonEmptyMap<K,V> extends Object
An immutable, non-empty map: a map guaranteed at construction time to contain at least one entry.

This type makes the non-emptiness constraint part of the static type system. APIs that require at least one entry can declare NonEmptyMap<K, V> instead of Map<K, V> and eliminate runtime emptiness checks entirely.

Insertion order is preserved (backed by LinkedHashMap). The first entry inserted is the headKey() / headValue().

This class is @NullMarked: all keys, values, and parameters are non-null by default.

The rationale for introducing dedicated non-empty collection types instead of using standard JDK types with runtime checks is documented in ADR-018 — NonEmptyList<T>, NonEmptySet<T>, NonEmptyMap<K,V> as structural guarantee types.

  • Method Details

    • of

      public static <K,V> NonEmptyMap<K,V> of(K key, V value, Map<? extends K, ? extends V> rest)
      Creates a NonEmptyMap with the given head entry and additional entries.

      If rest contains key, that duplicate is ignored — the provided value is always used for the head key.

      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      key - the head key; must not be null
      value - the head value; must not be null
      rest - additional entries; must not be null; keys and values must not be null
      Returns:
      a new NonEmptyMap
      Throws:
      NullPointerException - if key, value, rest, or any key/value inside rest is null

    • singleton

      public static <K,V> NonEmptyMap<K,V> singleton(K key, V value)
      Creates a NonEmptyMap containing exactly one entry.
      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      key - the sole key; must not be null
      value - the sole value; must not be null
      Returns:
      a singleton NonEmptyMap
      Throws:
      NullPointerException - if key or value is null

    • fromMap

      public static <K,V> Option<NonEmptyMap<K,V>> fromMap(Map<? extends K, ? extends V> map)
      Attempts to construct a NonEmptyMap from a plain Map.
      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      map - the source map; must not be null; keys and values must not be null
      Returns:
      Option.some(Object) wrapping the NonEmptyMap if the map is non-empty, or Option.none() if the map is empty
      Throws:
      NullPointerException - if map or any key/value is null

    • fromOptional

      public static <K,V> Option<NonEmptyMap<K,V>> fromOptional(Optional<? extends Map<? extends K, ? extends V>> optional)
      Attempts to construct a NonEmptyMap from a JDK Optional wrapping a plain Map.

      If the optional is present and the wrapped map is non-empty, returns Option.some(Object) wrapping the NonEmptyMap. If the optional is empty, or if the wrapped map is itself empty, returns Option.none().

      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      optional - the source optional; must not be null
      Returns:
      Option.some(Object) if the optional is present and the map is non-empty, Option.none() otherwise
      Throws:
      NullPointerException - if optional is null

    • collector

      public static <T,K,V> Collector<T, ?, Option<NonEmptyMap<K,V>>> collector(Function<? super T, ? extends K> keyMapper, Function<? super T, ? extends V> valueMapper)
      Returns a Collector that accumulates a Stream<T> into an Option<NonEmptyMap<K, V>> using the provided key and value extractor functions.

      Produces Option.some(Object) for a non-empty stream and Option.none() for an empty stream. If multiple stream elements map to the same key, later elements overwrite earlier ones (last-write-wins semantics).

      Example: 

      Option<NonEmptyMap<String, Integer>> result =
    employees.stream()
        .collect(NonEmptyMap.collector(Employee::name, Employee::score));
      Type Parameters:
      T - the stream element type
      K - the key type
      V - the value type
      Parameters:
      keyMapper - extracts the key from each element; must not be null or return null
      valueMapper - extracts the value from each element; must not be null or return null
      Returns:
      a collector producing Option<NonEmptyMap<K, V>>
      Throws:
      NullPointerException - if keyMapper or valueMapper is null

    • headKey

      public K headKey()
      Returns the guaranteed head key of this map.
      Returns:
      the head key (never null)

    • headValue

      public V headValue()
      Returns the value associated with the head key.
      Returns:
      the head value (never null)

    • size

      public int size()
      Returns the number of entries in this map. Always ≥ 1.
      Returns:
      the size

    • get

      public Option<V> get(K key)
      Returns the value associated with key, or Option.none() if absent.
      Parameters:
      key - the key to look up; must not be null
      Returns:
      Some(value) if the key is present, None otherwise
      Throws:
      NullPointerException - if key is null

    • containsKey

      public boolean containsKey(K key)
      Returns true if this map contains an entry for key.
      Parameters:
      key - the key to test; must not be null
      Returns:
      true if the key is present
      Throws:
      NullPointerException - if key is null

    • keySet

      public NonEmptySet<K> keySet()
      Returns a NonEmptySet containing all keys of this map in insertion order. The head key of this map is the head of the returned set.
      Returns:
      a NonEmptySet<K> of all keys (never null)

    • values

      public NonEmptyList<V> values()
      Returns a NonEmptyList containing all values of this map in insertion order. The head value of this map is the head of the returned list. Duplicate values are preserved (unlike keys, values need not be unique).
      Returns:
      a NonEmptyList<V> of all values (never null)

    • toMap

      public Map<K,V> toMap()
      Returns an unmodifiable Map containing all entries (head entry first, then tail entries in insertion order). The same instance is returned on repeated calls (lazily initialized, thread-safe).
      Returns:
      an unmodifiable map with all entries

    • toStream

      public Stream<Map.Entry<K,V>> toStream()
      Returns a sequential Stream of all entries in insertion order.

      The stream always contains at least one element (the head entry). Use it to bridge NonEmptyMap into the standard Java stream API.

      Returns:
      a non-empty stream of Map.Entry elements in insertion order

    • mapValues

      public <R> NonEmptyMap<K,R> mapValues(Function<? super V, ? extends R> mapper)
      Applies mapper to every value and returns a new NonEmptyMap with the same keys and mapped values.
      Type Parameters:
      R - the result value type
      Parameters:
      mapper - a non-null function to apply to each value; must not return null
      Returns:
      a new NonEmptyMap with mapped values
      Throws:
      NullPointerException - if mapper is null or returns null

    • mapValuesWithKey

      public <R> NonEmptyMap<K,R> mapValuesWithKey(BiFunction<? super K, ? super V, ? extends R> mapper)
      Applies mapper to every key-value pair and returns a new NonEmptyMap with the same keys and mapped values.

      Unlike mapValues(Function), the mapper receives both the key and the value, enabling value transformations that depend on the key.

      Type Parameters:
      R - the result value type
      Parameters:
      mapper - a non-null function to apply to each key-value pair; must not return null
      Returns:
      a new NonEmptyMap with mapped values
      Throws:
      NullPointerException - if mapper is null or returns null

    • mapKeys

      public <R> NonEmptyMap<R,V> mapKeys(Function<? super K, ? extends R> mapper)
      Applies mapper to every key and returns a new NonEmptyMap with the mapped keys and the original values.

      If multiple keys map to the same new key, head-wins semantics apply: the head entry is always preserved, and any tail entry whose mapped key collides with the mapped head key is silently dropped.

      Type Parameters:
      R - the result key type
      Parameters:
      mapper - a non-null function to apply to each key; must not return null
      Returns:
      a new NonEmptyMap with mapped keys
      Throws:
      NullPointerException - if mapper is null or returns null

    • filter

      public Option<NonEmptyMap<K,V>> filter(BiPredicate<? super K, ? super V> predicate)
      Returns a new NonEmptyMap containing only entries for which predicate returns true, wrapped in Option.some(Object). Returns Option.none() if no entries pass the predicate.
      Parameters:
      predicate - a non-null predicate to test each key-value pair
      Returns:
      Some(filteredMap) if at least one entry passes, None otherwise
      Throws:
      NullPointerException - if predicate is null

    • merge

      public NonEmptyMap<K,V> merge(NonEmptyMap<K,V> other, BinaryOperator<V> mergeFunction)
      Returns a new NonEmptyMap that is the union of this map and other. When both maps contain the same key, mergeFunction is applied to the two values.
      Parameters:
      other - the other map; must not be null
      mergeFunction - function to resolve value conflicts; must not be null; must not return null (a null return would violate the non-null value contract and is rejected immediately)
      Returns:
      a new NonEmptyMap containing all entries from both maps
      Throws:
      NullPointerException - if other, mergeFunction, or the result of mergeFunction is null

    • toNonEmptyList

      public NonEmptyList<Map.Entry<K,V>> toNonEmptyList()
      Converts this map to a NonEmptyList of its entries in insertion order.
      Returns:
      a NonEmptyList<Map.Entry<K, V>>

    • sequenceOption

      public static <K,V> Option<NonEmptyMap<K,V>> sequenceOption(NonEmptyMap<K, Option<V>> nem)
      Sequences a NonEmptyMap<K, Option<V>> into an Option<NonEmptyMap<K, V>>.

      Returns Option.some(Object) containing all unwrapped values if every entry's value is Some; returns Option.none() as soon as any entry's value is None (fail-fast in inspection — the method stops iterating after the first None; entries are already materialized in the map before sequencing, so later entries are not inspected but were already evaluated).

      Type Parameters:
      K - the key type
      V - the unwrapped value type
      Parameters:
      nem - a NonEmptyMap<K, Option<V>>; must not be null
      Returns:
      Some(NonEmptyMap<K, V>) if all values are present, None otherwise
      Throws:
      NullPointerException - if nem is null

    • sequenceTry

      public static <K,V> Try<NonEmptyMap<K,V>> sequenceTry(NonEmptyMap<K,Try<V>> nem)
      Sequences a NonEmptyMap<K, Try<V>> into a Try<NonEmptyMap<K, V>>.

      Returns Try.success(Object) if all values succeed; returns Try.failure(Throwable) from the first failing entry (fail-fast in inspection — the method stops iterating after the first failure; entries are already materialized in the map before sequencing, so later entries are not inspected but were already evaluated).

      Type Parameters:
      K - the key type
      V - the success value type
      Parameters:
      nem - a NonEmptyMap<K, Try<V>>; must not be null
      Returns:
      Success(NonEmptyMap<K, V>) if all succeed, Failure otherwise
      Throws:
      NullPointerException - if nem is null

    • sequenceEither

      public static <K,E,V> Either<E, NonEmptyMap<K,V>> sequenceEither(NonEmptyMap<K, Either<E,V>> nem)
      Sequences a NonEmptyMap<K, Either<E, V>> into an Either<E, NonEmptyMap<K, V>>.

      Returns Either.right(Object) if all values are right; returns Either.left(Object) from the first left entry (fail-fast in inspection — the method stops iterating after the first left; entries are already materialized in the map before sequencing, so later entries are not inspected but were already evaluated).

      Type Parameters:
      K - the key type
      E - the left (error) type
      V - the right (success) type
      Parameters:
      nem - a NonEmptyMap<K, Either<E, V>>; must not be null
      Returns:
      right(NonEmptyMap<K, V>) if all are right, left(E) otherwise
      Throws:
      NullPointerException - if nem is null

    • sequenceResult

      public static <K,V,E> Result<NonEmptyMap<K,V>, E> sequenceResult(NonEmptyMap<K, Result<V,E>> nem)
      Sequences a NonEmptyMap<K, Result<V, E>> into a Result<NonEmptyMap<K, V>, E>.

      Returns Result.ok(Object) if all values are ok; returns Result.err(Object) from the first error entry (fail-fast in inspection — the method stops iterating after the first err; entries are already materialized in the map before sequencing, so later entries are not inspected but were already evaluated).

      Type Parameters:
      K - the key type
      V - the ok value type
      E - the error type
      Parameters:
      nem - a NonEmptyMap<K, Result<V, E>>; must not be null
      Returns:
      ok(NonEmptyMap<K, V>) if all succeed, err(E) otherwise
      Throws:
      NullPointerException - if nem is null

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object