zeba_academy_map_utils 0.0.1

A collection of generic and type-safe utilities for working with Dart maps, including safe lookup, filtering, transformations, merging, inversion, and grouping.

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:

25

And:

print(updated['age']);

Output:

26

---

➖ 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:

85

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:

1. Fork the repository.
2. Create a feature branch.
3. Make your changes.
4. Add or update tests.
5. Run dart format.
6. Run flutter analyze.
7. Run flutter test.
8. 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

Copyright © 2026 Zeba Academy

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.