zeba_academy_list_utils 1.0.0

Generic list helper utilities for Dart and Flutter including chunking, partitioning, distinct values, flattening, safe indexing, rotation, and moving items.

zeba_academy_list_utils

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

zeba_academy_list_utils provides convenient helpers for common list operations such as chunking, partitioning, distinct values, flattening, safe indexing, rotating, and moving items.

No external runtime dependencies. No platform-specific code. Just simple, reusable Dart utilities.

---

✨ Features

• 📦 Chunk lists into fixed-size groups
• 🔀 Partition lists into matching and non-matching values
• 🧹 Remove duplicate values
• 🔑 Distinct by key for custom objects
• 📚 Flatten nested iterables
• 🛡️ Safe list indexing without RangeError
• ↩️ Rotate lists left
• ↪️ Rotate lists right
• 🔄 Move items between positions
• ⬆️ Move items to the beginning
• ⬇️ Move items to the end
• 🧩 Fully generic and type-safe
• 🪶 Lightweight and dependency-free
• 🔒 Null-safe
• 📝 Well-documented API
• 🧪 Comprehensive unit tests

---

📦 Installation

Add zeba_academy_list_utils to your pubspec.yaml:

dependencies:
  zeba_academy_list_utils: ^1.0.0

Then run:

flutter pub get

For a pure Dart project:

dart pub get

---

🚀 Quick Start

Import the package:

import 'package:zeba_academy_list_utils/zeba_academy_list_utils.dart';

You can then use:

final chunks = ZebaListUtils.chunk(
  [1, 2, 3, 4, 5],
  2,
);

print(chunks);
// [[1, 2], [3, 4], [5]]

---

📚 API Reference

chunk()

Splits an iterable into groups containing at most the specified number of elements.

final result = ZebaListUtils.chunk(
  [1, 2, 3, 4, 5],
  2,
);

print(result);

Output:

[[1, 2], [3, 4], [5]]

Invalid size

The size must be greater than zero.

ZebaListUtils.chunk(
  [1, 2, 3],
  0,
);

Throws:

ArgumentError

---

partition()

Splits values into two lists:

1. Values matching the predicate
2. Values not matching the predicate

final result = ZebaListUtils.partition(
  [1, 2, 3, 4, 5],
  (value) => value.isEven,
);

print(result);

Output:

[[2, 4], [1, 3, 5]]

---

distinct()

Removes duplicate values while preserving the order of their first occurrence.

final result = ZebaListUtils.distinct(
  [1, 2, 2, 3, 1, 4],
);

print(result);

Output:

[1, 2, 3, 4]

Works with strings as well:

final result = ZebaListUtils.distinct(
  ['Flutter', 'Dart', 'Flutter', 'Firebase'],
);

print(result);

Output:

[Flutter, Dart, Firebase]

---

distinctBy()

Removes duplicates based on a selected key.

This is particularly useful with model objects.

final users = [
  User(id: 1, name: 'Sarvesh'),
  User(id: 2, name: 'Arun'),
  User(id: 1, name: 'Another User'),
];

final uniqueUsers = ZebaListUtils.distinctBy(
  users,
  (user) => user.id,
);

The first object for each unique key is preserved.

---

flatten()

Flattens one level of nested iterables.

final result = ZebaListUtils.flatten<int>(
  [
    [1, 2],
    [3, 4],
    [5, 6],
  ],
);

print(result);

Output:

[1, 2, 3, 4, 5, 6]

It also works with other iterable types:

final result = ZebaListUtils.flatten<String>(
  [
    {'A', 'B'},
    {'C', 'D'},
  ],
);

---

elementAtOrNull()

Safely accesses an element by index.

Instead of:

final value = items[10];

which may throw a RangeError, use:

final value = ZebaListUtils.elementAtOrNull(
  items,
  10,
);

If the index is invalid:

null

Example:

final numbers = [10, 20, 30];

print(
  ZebaListUtils.elementAtOrNull(numbers, 1),
);
// 20

print(
  ZebaListUtils.elementAtOrNull(numbers, 10),
);
// null

Negative indexes are also handled safely:

final value = ZebaListUtils.elementAtOrNull(
  [1, 2, 3],
  -1,
);

print(value);
// null

---

↩️ rotateLeft()

Rotates list elements to the left.

final result = ZebaListUtils.rotateLeft(
  [1, 2, 3, 4, 5],
  2,
);

print(result);

Output:

[3, 4, 5, 1, 2]

The original list is not modified.

Large rotation values

final result = ZebaListUtils.rotateLeft(
  [1, 2, 3],
  4,
);

print(result);

Output:

[2, 3, 1]

The number of steps is automatically normalized.

---

↪️ rotateRight()

Rotates list elements to the right.

final result = ZebaListUtils.rotateRight(
  [1, 2, 3, 4, 5],
  2,
);

print(result);

Output:

[4, 5, 1, 2, 3]

The original list is not modified.

---

🔄 move()

Moves an element from one index to another.

final result = ZebaListUtils.move(
  ['A', 'B', 'C', 'D'],
  0,
  2,
);

print(result);

Output:

[B, C, A, D]

Moving backwards

final result = ZebaListUtils.move(
  ['A', 'B', 'C', 'D'],
  3,
  1,
);

print(result);

Output:

[A, D, B, C]

The original list remains unchanged.

---

⬆️ moveToStart()

Moves an element to index 0.

final result = ZebaListUtils.moveToStart(
  ['A', 'B', 'C', 'D'],
  2,
);

print(result);

Output:

[C, A, B, D]

---

⬇️ moveToEnd()

Moves an element to the last position.

final result = ZebaListUtils.moveToEnd(
  ['A', 'B', 'C', 'D'],
  1,
);

print(result);

Output:

[A, C, D, B]

---

🧩 Generic Type Support

The package is designed around Dart generics.

It works with integers:

final numbers = ZebaListUtils.distinct(
  [1, 2, 2, 3],
);

Strings:

final names = ZebaListUtils.distinct(
  ['A', 'B', 'A'],
);

Custom classes:

final products = ZebaListUtils.distinctBy(
  productList,
  (product) => product.id,
);

And other Dart types:

final dates = ZebaListUtils.distinct(
  dateList,
);

---

🔒 Immutability

Operations that transform a list return a new list rather than modifying the original list.

For example:

final original = ['A', 'B', 'C'];

final result = ZebaListUtils.move(
  original,
  0,
  2,
);

print(original);
// [A, B, C]

print(result);
// [B, C, A]

This makes the utilities suitable for state-management approaches where immutable state updates are preferred.

---

🧪 Testing

Run the complete test suite:

flutter test

Or:

dart test

Format the package:

dart format lib test

Analyze the package:

flutter analyze

Before publishing:

flutter pub publish --dry-run

---

📁 Project Structure

zeba_academy_list_utils/
│
├── lib/
│   ├── src/
│   │   └── zeba_list_utils.dart
│   │
│   └── zeba_academy_list_utils.dart
│
├── test/
│   └── zeba_academy_list_utils_test.dart
│
├── analysis_options.yaml
├── CHANGELOG.md
├── LICENSE
├── README.md
└── pubspec.yaml

---

🎯 Use Cases

zeba_academy_list_utils can be useful for:

• Flutter UI list manipulation
• Pagination preparation
• Grid data preparation
• Batch processing
• Search result processing
• Removing duplicate records
• Categorizing data
• Reordering lists
• Drag-and-drop list interfaces
• State management
• Data transformation
• Collection preprocessing
• Model list manipulation

---

💡 Example: Preparing Grid Data

final products = [
  'Product 1',
  'Product 2',
  'Product 3',
  'Product 4',
  'Product 5',
  'Product 6',
];

final rows = ZebaListUtils.chunk(
  products,
  2,
);

for (final row in rows) {
  print(row);
}

Output:

[Product 1, Product 2]
[Product 3, Product 4]
[Product 5, Product 6]

---

💡 Example: Separating Active and Inactive Items

final result = ZebaListUtils.partition(
  users,
  (user) => user.isActive,
);

final activeUsers = result[0];
final inactiveUsers = result[1];

---

💡 Example: Reordering Items

This can be useful when implementing custom list reordering:

final reordered = ZebaListUtils.move(
  items,
  oldIndex,
  newIndex,
);

The original collection remains untouched.

---

⚡ Design Principles

This package follows a few simple principles:

Simple

APIs should be easy to understand and remember.

Generic

Utilities should work with any suitable Dart type.

Dependency-free

The package has no runtime dependencies.

Safe

Operations validate indexes and invalid arguments where appropriate.

Predictable

Transformation utilities return new lists rather than unexpectedly mutating existing data.

Flutter-friendly

The package can be used with any Flutter state-management architecture.

---

📋 API Overview

API	Description
chunk()	Splits items into fixed-size groups
partition()	Separates items using a predicate
distinct()	Removes duplicate values
distinctBy()	Removes duplicates using a key
flatten()	Flattens one level of nested iterables
elementAtOrNull()	Safely accesses an item by index
rotateLeft()	Rotates items to the left
rotateRight()	Rotates items to the right
move()	Moves an item between indexes
moveToStart()	Moves an item to the first position
moveToEnd()	Moves an item to the final position

---

🛠️ Requirements

• Dart SDK: ^3.12.0
• Flutter: Compatible with modern Flutter releases

The package does not require:

• Firebase
• REST APIs
• Native plugins
• External services
• Code generation
• Build runners
• Runtime dependencies

---

🤝 Contributing

Contributions are welcome.

If you find a bug or have an improvement:

1. Fork the repository.
2. Create a feature branch.
3. Add or update tests.
4. Run formatting.
5. Run static analysis.
6. Run the complete test suite.
7. Submit a pull request.

Example:

dart format lib test
flutter analyze
flutter test

Please keep contributions focused, documented, and covered by tests.

---

🐛 Issues

If you encounter a bug or have a feature request, please open an issue in the project's GitHub repository.

When reporting a bug, include:

• Dart version
• Flutter version
• Package version
• Minimal reproduction
• Expected behavior
• Actual behavior

---

📄 License

Copyright © 2026 Zeba Academy.

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

You may use, study, modify, and redistribute this software according to the terms of the GPL-3.0 license.

See the LICENSE file for the complete license text.

For the full license terms, visit:

https://www.gnu.org/licenses/gpl-3.0.html

---

👨‍💻 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:

https://sufyanism.com/

or connect with me on LinkedIn:

https://www.linkedin.com/in/sufyanism

---

🎓 Your All-in-One Learning Hub!

🚀 Explore courses and resources in coding, tech, and development at 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:

https://zeba.academy

➡️ Explore hands-on courses and resources:

https://code.zeba.academy

➡️ Check out our YouTube channel for more tutorials:

https://www.youtube.com/@zeba.academy

➡️ Follow Zeba Academy on Instagram:

https://www.instagram.com/zeba.academy/

---

⭐ Support the Project

If you find zeba_academy_list_utils useful:

• ⭐ Star the repository
• 📦 Use the package in your Flutter/Dart projects
• 🐛 Report issues
• 💡 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_list_utils.

Built with ❤️ for the Dart and Flutter community by Zeba Academy.

Keep learning. Keep building. Keep sharing. 🚀