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:

Values matching the predicate
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:

Fork the repository.
Create a feature branch.
Add or update tests.
Run formatting.
Run static analysis.
Run the complete test suite.
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

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. 🚀

zeba_academy_list_utils

✨ Features

📦 Installation

🚀 Quick Start

📚 API Reference

chunk()

Invalid size

partition()

distinct()

distinctBy()

flatten()

elementAtOrNull()

↩️ rotateLeft()

Large rotation values

↪️ rotateRight()

🔄 move()

Moving backwards

⬆️ moveToStart()

⬇️ moveToEnd()

🧩 Generic Type Support

🔒 Immutability

🧪 Testing

📁 Project Structure

🎯 Use Cases

💡 Example: Preparing Grid Data

💡 Example: Separating Active and Inactive Items

💡 Example: Reordering Items

⚡ Design Principles

Simple

Generic

Dependency-free

Safe

Predictable

Flutter-friendly

📋 API Overview

🛠️ Requirements

🤝 Contributing

🐛 Issues

📄 License

👨‍💻 About Me

🎓 Your All-in-One Learning Hub!

⭐ Support the Project

❤️ Thank You

Libraries

zeba_academy_list_utils package

`chunk()`

`partition()`

`distinct()`

`distinctBy()`

`flatten()`

`elementAtOrNull()`

↩️ `rotateLeft()`

↪️ `rotateRight()`

🔄 `move()`

⬆️ `moveToStart()`

⬇️ `moveToEnd()`