file: extensions/map.dart
dependencies: import 'package:dart_helper_utils/dart_helper_utils.dart';

_makeValueEncodable(dynamic value): (Function) *Private*
   Define: Converts a value to a JSON-encodable representation.
   Parameters:
        value: (dynamic) The value to convert.
    Returns: (dynamic) - A JSON-encodable representation of the value.  Handles primitive types, Enums, Lists, Sets, and Maps. Converts other types to String using `.toString()`.
    Operational Notes:
      Recursive: Handles nested Lists and Sets recursively.
      Uses: encodableCopy for Maps, this makes sure that it uses this function recursively on map values.

DHUMapExtension: (Extension on `Map<K, V>`)
    Define: Provides extension methods for non-nullable `Map` objects.
    Methods:
        swapKeysWithValues(): Returns a new map with keys and values swapped.  If values are duplicated, the *last* key-value pair is used.
        encodableCopy: (Map<String, dynamic>, get) - Returns a new map suitable for JSON encoding.  Keys are converted to strings, and values are recursively processed by `_makeValueEncodable`.
        encodedJsonString: (String, get) - Returns a pretty-printed JSON string representation of the map (using `encodableCopy`).
        setIfMissing(K key, V value): Inserts the key-value pair if the key is not already present.  Returns the value associated with the key (either the existing one or the newly inserted one).
        update(K key, V Function(V value) updater): Updates the value for an existing key using the provided `updater` function.  Does nothing if the key is not present.
        keysWhere(bool Function(V) condition): Returns an iterable of keys where the corresponding values satisfy the given condition.
        mapValues<V2>(V2 Function(V) transform): Transforms the *values* of the map using the provided function, returning a new map with the same keys.
        filter(bool Function(K key, V value) predicate): Returns a new map containing only the entries that satisfy the given predicate.
        valuesList: (List<V>, get) - Returns a list of the map's values.
        keysList: (List<K>, get) - Returns a list of the map's keys.
        valuesSet: (Set<V>, get) - Returns a set of the map's values.
        keysSet: (Set<K>, get) - Returns a set of the map's keys.
    Operational Notes:
        Dependencies:  Uses `_makeValueEncodable` for JSON encoding.

DHUMapNullableExtension: (Extension on `Map<K, V>?`)
  Define: Provides extension methods for nullable `Map` objects.
  Methods:
    isEqual(Map<K, V>? b): checks if two maps are equal, uses [gf.isEqual] to check equality, considers nulls.
    isPrimitive(): Checks if the map has primitive keys and all primitive values. Uses top level functions [isTypePrimitive] and [isValuePrimitive].
    isEmptyOrNull: (bool, get) if map is null or empty.
    isNotEmptyOrNull: (bool, get) if map is not null or empty.

DHUMapExt: (Extension on `Map<K extends String, V>`)
  Define: Provides extension methods for non-nullable `Map` objects where the keys are Strings.
    Methods:
      flatMap({String delimiter = '.', bool excludeArrays = false}): Flattens a nested map into a single-level map, using the provided delimiter. returns the result.
