zeba_academy_map_utils

A lightweight collection of type-safe, generic map utilities for Dart and Flutter.

zeba_academy_map_utils provides convenient helpers for common map operations such as safe lookup, filtering, key/value transformations, map merging, inversion, grouping, null removal, and immutable-style updates.

It is designed to reduce repetitive map-handling code while keeping APIs simple, readable, and reusable.

✨ Features

🔍 Safe map lookup
🧩 Check whether a key exists
🔎 Filter map entries
🔑 Transform map keys
💎 Transform map values
🔄 Transform keys and values together
🎯 Pick specific keys
🚫 Omit specific keys
🔗 Merge multiple maps
🔀 Merge two maps
🔁 Invert key/value relationships
📦 Group iterable items
🗂️ Group map entries
🧹 Remove null values
➕ Add/update map values without mutating the original
➖ Remove keys without mutating the original
🏗️ Create maps from iterables
✅ every and any helpers
🔍 Find the first matching value
🧰 Convenient map extension methods
💯 Generic and type-safe APIs
🚫 No external runtime dependencies

📦 Installation

Add zeba_academy_map_utils to your pubspec.yaml:

dependencies:
  zeba_academy_map_utils: ^0.1.0

Then run:

flutter pub get

For Dart-only projects:

dart pub get

🚀 Import

import 'package:zeba_academy_map_utils/zeba_academy_map_utils.dart';

🔍 Safe Lookup

Safely retrieve a value from a map.

final user = {
  'name': 'Sarvesh',
  'age': 25,
};

final name = ZebaMapUtils.get(
  user,
  'name',
);

print(name);

Output:

Sarvesh

You can also provide a default value:

final city = ZebaMapUtils.get(
  user,
  'city',
  defaultValue: 'Unknown',
);

print(city);

Output:

Unknown

🔑 Check Key Existence

final user = {
  'name': 'Sarvesh',
  'age': 25,
};

final exists = ZebaMapUtils.containsKey(
  user,
  'name',
);

print(exists);

Output:

true

🔎 Filter Maps

Filter entries using a custom condition.

final scores = {
  'Math': 90,
  'Science': 75,
  'English': 85,
};

final passed = ZebaMapUtils.filter(
  scores,
  (subject, score) => score >= 80,
);

print(passed);

Output:

{
  Math: 90,
  English: 85
}

🔑 Transform Keys

Transform every key while keeping the values unchanged.

final user = {
  'firstName': 'Sarvesh',
  'lastName': 'M',
};

final result = ZebaMapUtils.mapKeys(
  user,
  (key) => key.toUpperCase(),
);

print(result);

Output:

{
  FIRSTNAME: Sarvesh,
  LASTNAME: M
}

💎 Transform Values

Transform every value while keeping keys unchanged.

final numbers = {
  'first': 10,
  'second': 20,
};

final result = ZebaMapUtils.mapValues(
  numbers,
  (value) => value * 2,
);

print(result);

Output:

{
  first: 20,
  second: 40
}

🔄 Transform Keys and Values

Transform both keys and values using mapEntries.

final numbers = {
  'a': 1,
  'b': 2,
};

final result = ZebaMapUtils.mapEntries(
  numbers,
  (key, value) {
    return MapEntry(
      key.toUpperCase(),
      value * 10,
    );
  },
);

print(result);

Output:

{
  A: 10,
  B: 20
}

🎯 Pick Keys

Select only specific keys from a map.

final user = {
  'name': 'Sarvesh',
  'age': 25,
  'city': 'Hosur',
  'role': 'Flutter Developer',
};

final result = ZebaMapUtils.pick(
  user,
  ['name', 'role'],
);

print(result);

Output:

{
  name: Sarvesh,
  role: Flutter Developer
}

🚫 Omit Keys

Remove selected keys from the resulting map.

final user = {
  'name': 'Sarvesh',
  'age': 25,
  'city': 'Hosur',
};

final result = ZebaMapUtils.omit(
  user,
  ['age'],
);

print(result);

Output:

{
  name: Sarvesh,
  city: Hosur
}

🔗 Merge Multiple Maps

Merge multiple maps into a new map.

final result = ZebaMapUtils.merge([
  {
    'name': 'Sarvesh',
  },
  {
    'age': 25,
  },
  {
    'city': 'Hosur',
  },
]);

print(result);

Output:

{
  name: Sarvesh,
  age: 25,
  city: Hosur
}

Duplicate Keys

When duplicate keys exist, the value from the later map wins.

final result = ZebaMapUtils.merge([
  {
    'name': 'Old Name',
  },
  {
    'name': 'New Name',
  },
]);

Result:

{
  name: New Name
}

🔗 Merge Two Maps

For merging exactly two maps:

final first = {
  'name': 'Sarvesh',
  'age': 25,
};

final second = {
  'age': 26,
  'city': 'Hosur',
};

final result = ZebaMapUtils.mergeTwo(
  first,
  second,
);

Result:

{
  name: Sarvesh,
  age: 26,
  city: Hosur
}

The second map takes precedence when keys overlap.

🔁 Invert Maps

Swap map keys and values using invert.

final original = {
  'apple': 1,
  'banana': 2,
  'orange': 3,
};

final inverted = ZebaMapUtils.invert(
  original,
);

print(inverted);

Result:

{
  1: apple,
  2: banana,
  3: orange
}

Note: If multiple keys have the same value, the last key encountered will be retained.

📦 Group Items

Group an iterable using a generated key.

final fruits = [
  'apple',
  'avocado',
  'banana',
  'blueberry',
];

final grouped = ZebaMapUtils.groupBy(
  fruits,
  (fruit) => fruit[0],
);

print(grouped);

Result:

{
  a: [
    apple,
    avocado
  ],
  b: [
    banana,
    blueberry
  ]
}

🗂️ Group Map Entries

Group map entries based on a custom rule.

final scores = {
  'Math': 90,
  'Science': 80,
  'English': 70,
  'History': 60,
};

final grouped = ZebaMapUtils.groupMap(
  scores,
  (subject, score) {
    return score >= 80 ? 'high' : 'low';
  },
);

Result:

{
  high: {
    Math: 90,
    Science: 80
  },
  low: {
    English: 70,
    History: 60
  }
}

🧹 Remove Null Values

Remove entries whose values are null.

final user = <String, String?>{
  'name': 'Sarvesh',
  'city': null,
  'role': 'Flutter Developer',
};

final result = ZebaMapUtils.removeNulls(
  user,
);

print(result);

Result:

{
  name: Sarvesh,
  role: Flutter Developer
}

This is especially useful before sending data to APIs or Firebase.

➕ Set a Value

Create a new map with a value added or updated.

final user = {
  'name': 'Sarvesh',
  'age': 25,
};

final updated = ZebaMapUtils.set(
  user,
  'age',
  26,
);

The original map remains unchanged.

print(user['age']);

Output:

And:

print(updated['age']);

Output:

➖ Remove a Key

Create a new map without a particular key.

final user = {
  'name': 'Sarvesh',
  'age': 25,
};

final result = ZebaMapUtils.remove(
  user,
  'age',
);

The original map is not modified.

🏗️ Create a Map from an Iterable

Use fromIterable to construct a map using key and value selectors.

final names = [
  'Sarvesh',
  'Arun',
  'Kumar',
];

final result = ZebaMapUtils.fromIterable(
  names,
  keyOf: (name) => name,
  valueOf: (name) => name.length,
);

print(result);

Result:

{
  Sarvesh: 7,
  Arun: 4,
  Kumar: 5
}

✅ Check Every Entry

final scores = {
  'Math': 90,
  'Science': 85,
  'English': 88,
};

final result = ZebaMapUtils.every(
  scores,
  (subject, score) => score >= 80,
);

print(result);

Output:

true

🔎 Check Any Entry

final scores = {
  'Math': 60,
  'Science': 85,
  'English': 70,
};

final result = ZebaMapUtils.any(
  scores,
  (subject, score) => score >= 80,
);

print(result);

Output:

true

🔍 Find the First Matching Value

final scores = {
  'Math': 60,
  'Science': 85,
  'English': 70,
};

final result = ZebaMapUtils.firstWhere(
  scores,
  (subject, score) => score >= 80,
);

print(result);

Output:

You can also provide a fallback:

final result = ZebaMapUtils.firstWhere(
  scores,
  (subject, score) => score >= 100,
  orElse: () => 0,
);

🧰 Extension Methods

The package also provides convenient extensions.

Safe Lookup

final user = {
  'name': 'Sarvesh',
};

final name = user.getOrNull('name');

Default Value

final city = user.getOrDefault(
  'city',
  'Unknown',
);

Filter

final result = {
  'a': 10,
  'b': 20,
  'c': 30,
}.whereEntries(
  (key, value) => value >= 20,
);

Transform Keys

final result = {
  'name': 'Sarvesh',
  'city': 'Hosur',
}.transformKeys(
  (key) => key.toUpperCase(),
);

Transform Values

final result = {
  'a': 10,
  'b': 20,
}.transformValues(
  (value) => value * 2,
);

Transform Entries

final result = {
  'a': 1,
  'b': 2,
}.transformEntries(
  (key, value) {
    return MapEntry(
      key.toUpperCase(),
      value * 10,
    );
  },
);

Pick

final result = {
  'name': 'Sarvesh',
  'age': 25,
  'city': 'Hosur',
}.pick([
  'name',
  'city',
]);

Omit

final result = {
  'name': 'Sarvesh',
  'age': 25,
  'city': 'Hosur',
}.omit([
  'age',
]);

Set a Value

final result = {
  'name': 'Sarvesh',
}.withValue(
  'role',
  'Flutter Developer',
);

Remove a Key

final result = {
  'name': 'Sarvesh',
  'age': 25,
}.withoutKey(
  'age',
);

Invert

final result = {
  'one': 1,
  'two': 2,
}.inverted();

Remove Null Values

final result = <String, String?>{
  'name': 'Sarvesh',
  'city': null,
}.withoutNullValues();

🧪 Testing

Run the complete test suite:

flutter test

Run static analysis:

flutter analyze

Format the package:

dart format lib test

Before publishing, run:

flutter pub publish --dry-run

📊 API Overview

Method	Description
`get`	Safely retrieve a value
`containsKey`	Check whether a key exists
`filter`	Filter map entries
`mapKeys`	Transform keys
`mapValues`	Transform values
`mapEntries`	Transform keys and values
`pick`	Keep selected keys
`omit`	Remove selected keys
`merge`	Merge multiple maps
`mergeTwo`	Merge two maps
`invert`	Swap keys and values
`groupBy`	Group iterable items
`groupMap`	Group map entries
`entries`	Convert entries to a list
`fromIterable`	Build a map from an iterable
`every`	Test all entries
`any`	Test at least one entry
`firstWhere`	Find first matching value
`removeNulls`	Remove null values
`set`	Add/update a value
`remove`	Remove a key

🎯 Design Goals

zeba_academy_map_utils is designed around a few principles:

Simple

APIs should be easy to understand and remember.

Generic

Utilities should work with different key and value types.

Type-safe

The package uses Dart generics wherever practical.

Lightweight

No unnecessary dependencies or complex abstractions.

Reusable

Utilities should work across Flutter applications, Dart packages, and general Dart code.

Non-destructive

Operations such as set, remove, pick, omit, and transformations return new maps rather than unexpectedly modifying the original map.

📁 Project Structure

zeba_academy_map_utils/
│
├── lib/
│   ├── src/
│   │   ├── map_grouping.dart
│   │   ├── map_extensions.dart
│   │   └── map_utils.dart
│   │
│   └── zeba_academy_map_utils.dart
│
├── test/
│   └── map_utils_test.dart
│
├── CHANGELOG.md
├── LICENSE
├── README.md
├── analysis_options.yaml
└── pubspec.yaml

🤝 Contributing

Contributions are welcome!

If you find a bug, have an improvement, or want to propose a new utility:

Fork the repository.
Create a feature branch.
Make your changes.
Add or update tests.
Run dart format.
Run flutter analyze.
Run flutter test.
Submit a pull request.

Please keep contributions focused, documented, tested, and consistent with the existing API design.

🐛 Issues and Feature Requests

If you discover a bug or have an idea for a new feature, please open an issue in the project's GitHub repository.

When reporting a bug, include:

Dart/Flutter version
Package version
Expected behavior
Actual behavior
Minimal reproduction example

📄 License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

You may use, modify, and distribute this software under the terms of the GPL-3.0 license.

See the LICENSE file for the complete license text.

👨‍💻 About Me

✨ I’m Sufyan bin Uzayr, an open-source developer passionate about building and sharing meaningful projects.

You can learn more about me and my work at sufyanism.com or connect with me on LinkedIn.

🎓 Your All-in-One Learning Hub!

🚀 Explore courses and resources in coding, tech, and development at zeba.academy and code.zeba.academy.

Empower yourself with practical skills through curated tutorials, real-world projects, and hands-on experience. Level up your tech game today! 💻✨

Zeba Academy is a learning platform dedicated to coding, technology, and development.

➡ Visit our main site: zeba.academy

➡ Explore hands-on courses and resources at: code.zeba.academy

➡ Check out our YouTube for more tutorials: zeba.academy

➡ Follow us on Instagram: zeba.academy

⭐ Support the Project

If zeba_academy_map_utils is useful to you:

⭐ Star the repository
📦 Use the package in your Flutter/Dart projects
🐛 Report bugs
💡 Suggest improvements
🤝 Contribute to the project
📢 Share it with other Dart and Flutter developers

Every contribution helps make the project better.

Thank You

Thank you for visiting zeba_academy_map_utils! ❤️

Built with Dart & Flutter by Zeba Academy.

zeba_academy_map_utils

✨ Features

📦 Installation

🚀 Import

🔍 Safe Lookup

🔑 Check Key Existence

🔎 Filter Maps

🔑 Transform Keys

💎 Transform Values

🔄 Transform Keys and Values

🎯 Pick Keys

🚫 Omit Keys

🔗 Merge Multiple Maps

Duplicate Keys

🔗 Merge Two Maps

🔁 Invert Maps

📦 Group Items

🗂️ Group Map Entries

🧹 Remove Null Values

➕ Set a Value

➖ Remove a Key

🏗️ Create a Map from an Iterable

✅ Check Every Entry

🔎 Check Any Entry

🔍 Find the First Matching Value

🧰 Extension Methods

Safe Lookup

Default Value

Filter

Transform Keys

Transform Values

Transform Entries

Pick

Omit

Set a Value

Remove a Key

Invert

Remove Null Values

🧪 Testing

📊 API Overview

🎯 Design Goals

Simple

Generic

Type-safe

Lightweight

Reusable

Non-destructive

📁 Project Structure

🤝 Contributing

🐛 Issues and Feature Requests

📄 License

👨‍💻 About Me

🎓 Your All-in-One Learning Hub!

⭐ Support the Project

Thank You

Libraries

zeba_academy_map_utils package