immortal 1.0.0

immortal #

Trve immutable wrapper classes for Dart collections.

Introduction #

This library provides a more functional wrapper around the dart:core collections List, Set and Map called ImmortalList, ImmortalSet and ImmortalMap.

It is designed with usability and readability in mind while staying close to the method names of their mutable counterparts. This should make switching from mutable to Immortal collections in existing applications fairly easy.

In order to reach complete immutability, the elements have to be immutable as well.

If you want to go fully functional, however, you should consider using dartz instead.

The key objectives for this library are the following:

  • Mutation methods return new instances instead of throwing exceptions
  • No builder pattern to create new instances
  • Optionals for nullable returns values
  • High fault tolerance in general, e.g. list indices passed as parameters are adjusted to fit inside the list's boundaries
  • Return the same instance if no changes were made in mutation methods (there is still some potential to improve and extend this in future updates of this library)
  • No assumptions about the order of elements in a set: ImmortalSet does not provide methods like elementAt, first, skip etc. even though the underlying implementation of Dart's Set might do so.
  • Provide more common names in addition to the Dart method names, like flatMap for expand (this is something that might be extended in future updates as well)
  • Addition of useful methods missing in dart:core, e.g. mapKeys and mapValues on ImmortalMap (this is again something that might be extended in future library updates).
  • Encourage further usage of immutable collections by prefering Immortal parameters.
  • Designed to write elegant code - not neccessarily the most performant. But immutability usually comes with a price anyways 🤷 (this might still be improved in future versions of this library)

Motivation #

Yet another implementation of immutable collections for Dart..?

I was never fully satisfied with other libraries that provide immutable collections for Dart. They either do not provide mutation methods to create new, modified instances or only do so by the usage of the builder pattern. This way they are often cumbersome to use and I felt I had to write too much code in order to perform simple tasks such as adding or updating a single element.

So I decided to write my own.

The main purpose of use for me is inside Redux or other component states in Flutter applications. I want to write short and simple reducer functions while being able to check for identity alone when I want to find out if the state has changed. As checks for state changes usually happen a lot more frequently (to find out if a component has to be rebuilt) as actual changes to the state, the performance of creating and updating instances was not my main focus while writing this library.

Why Immortal?

I wanted to prevent name clashes with other libraries - and I just think the name is fitting and cool 🤘

In eternity and time the same still the tundra lay untouched

1.0.0 #

  • Initial release

example/main.dart

import 'package:immortal/immortal.dart';

void main() {
  listExample();
  setExample();
  mapExample();
}

void listExample() {
  final list = ImmortalList([1, 2, 3]);
  final modifiedList = list
      .add(4)
      .followedBy(ImmortalList([1, 2]))
      .where((value) => value.isEven)
      .map((value) => value * 2)
      .skip(1)
      .take(1);
  print(list);         // prints "Immortal[1, 2, 3]"
  print(modifiedList); // prints "Immortal[8]"
}

void setExample() {
  final set = ImmortalSet({1, 2, 3});
  final modifiedSet = set
      .add(4)
      .union(ImmortalSet({1, 2}))
      .where((value) => value.isEven)
      .map((value) => value * 2)
      .remove(4);
  print(set);         // prints "Immortal{1, 2, 3}"
  print(modifiedSet); // prints "Immortal{8}"
}

void mapExample() {
  final map = ImmortalMap({1: 'a', 2: 'b', 3: 'c'});
  final modifiedMap = map
      .add(4, 'd')
      .mapKeys((key, _) => key * 2)
      .putIfAbsent(4, () => 'e')
      .removeWhere((key, value) => key < 2 || value != 'd')
      .update(8, (value) => value.toUpperCase());
  print(map);         // prints "Immortal{1: 'a', 2: 'b', 3: 'c'}"
  print(modifiedMap); // prints "Immortal{8: 'D'}"
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  immortal: ^1.0.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:immortal/immortal.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
16
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
92
Overall:
Weighted score of the above. [more]
56
Learn more about scoring.

We analyzed this package on Jul 11, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.4.0
  • pana: 0.12.19

Platforms

Detected platforms: Flutter, web, other

No platform restriction found in primary library package:immortal/immortal.dart.

Maintenance suggestions

The package description is too short. (-8 points)

Add more detail to the description field of pubspec.yaml. Use 60 to 180 characters to describe the package, what it does, and its target use case.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.2.0 <3.0.0
optional ^3.0.2+1 3.0.2+1
Dev dependencies
test ^1.0.0

Admin