arcane_helper_utils 1.4.5 copy "arcane_helper_utils: ^1.4.5" to clipboard
arcane_helper_utils: ^1.4.5 copied to clipboard

Provides a variety of helpful utilities and extensions for Flutter and Dart.

Overview #

Arcane Helper Utils is a Dart package designed to enhance Dart development by providing utility functions and extensions that simplify common tasks.

style: arcane analysis

Features #

  • Ticker Utility: A utility class that facilitates time-based actions, perfect for animations or any timing-related operations.
  • JSON Converter: Simplifies the process of converting JSON data into Dart objects.
  • DateTime Extensions: Adds additional functionality to the DateTime class, making it easier to format dates and calculate differences.
  • String Extensions: Enhances the String class by adding new methods for common transformations and checks.
  • JWT Utilities: Provides getters to parse a JWT token from a String, then get common properties from it.
  • List Extensions: Adds a new unique operator for filtering List items, as well as getters for isNullOrEmpty, isEmptyOrNull, isNotNullOrEmpty, and isNotEmptyOrNull. Furthermore, an equals extension has been introduced which can be used to compare two lists.

Getting Started #

To use this package in your Dart project, add it to your project's pubspec.yaml file:

dependencies:
  arcane_helper_utils: any

Then import it in your Dart files where needed:

import 'package:arcane_helper_utils/arcane_helper_utils.dart';

Usage Examples #

Here are some examples of how to use the utilities and extensions provided by this package:

Ticker #

The Ticker can be used as a countdown or interval timer.

final Stream<int> ticker = const Ticker().tick(
  timeout: Duration(seconds: 30),
  interval: Duration(seconds: 5)
);

await for (final int ticksRemaining in ticker) {
  if (ticksRemaining == 0) print("Time's up!");
  print('Tick! $ticksRemaining');
}

JSON Conversion #

These helper methods are used in conjunction with the Freezed package to annotate fields that need to be converted from one data type to another. The available conversions are:

  • String? to int?
  • String? to double?

Provided the following JSON output, the valueIsMaybeNull field will be converted from an empty String to null, the valueIsDouble field will be converted from a String? to a double?, and the valueIsInt field will be converted from a String? to an int?:

{
  "valueIsMaybeNull": "",
  "valueIsDouble": "123.456",
  "valueIsInt": "123"
}
@freezed
abstract class MyFreezedClass with _$MyFreezedClass {
  const factory MyFreezedClass({
    @DecimalConverter() double? valueIsMaybeNull,
    @DecimalConverter() double? valueIsDouble,
    @IntegerConverter() int? valueIsInt,
  }) = _MyFreezedClass;

  factory MyFreezedClass.fromJson(Map<String, dynamic> json) =>
      _$MyFreezedClassFromJson(json);

  const MyFreezedClass._();
}

DateTime Extensions #

These extensions add helpful methods to the DateTime class, making it easier to handle common date and time operations such as formatting, comparisons, and calculations.

These are broken down into the following categories:

  • Start and end of period calculations
  • Comparison operations
  • Period information operations
  • "Yesterday" and "tomorrow" getters

Start and End of Period Calculations

The following operations are now available on a DateTime object:

  • startOfHour: Returns a new DateTime object where the time stamp is set to the beginning of the given hour.

    final DateTime dateTime = DateTime(2019, 1, 1, 13, 45);
    print(dateTime); // 2019-01-01T13:45:00.0
    print(dateTime.startOfHour); // 2019-01-01T13:00:00.0
    
  • endOfHour: Returns a new DateTime object where the time stamp is set to the end of the given hour.

    final DateTime dateTime = DateTime(2019, 1, 1, 13, 45);
    print(dateTime); // 2019-01-01T13:45:00.0
    print(dateTime.endOfHour); // 2019-01-01T13:59:59.999
    
  • startOfDay: Returns a new DateTime object where the time stamp is set to the beginning of the day.

    final DateTime dateTime = DateTime(2019, 1, 1, 13, 45);
    print(dateTime); // 2019-01-01T13:45:00.0
    print(dateTime.startOfDay); // 2019-01-01T00:00:00.0
    
  • endOfDay: Returns a new DateTime object where the time stamp is set to the end of the day.

    final DateTime dateTime = DateTime(2019, 1, 1, 13, 45);
    print(dateTime); // 2019-01-01T13:45:00.0
    print(dateTime.endOfDay); // 2019-01-01T23:59:59.9
    
  • startOfWeek: Returns a new DateTime object where the time stamp is set to the beginning of the week (Monday).

    final DateTime dateTime = DateTime(2023, 9, 10);
    print(dateTime); // 2023-09-10
    print(dateTime.startOfWeek); // 2023-09-04
    
  • endOfWeek: Returns a new DateTime object where the time stamp is set to the end of the week (Sunday).

    final DateTime dateTime = DateTime(2023, 9, 10);
    print(dateTime); // 2023-09-10
    print(dateTime.endOfWeek); // 2023-09-17T23:59:59.999999
    
  • startOfMonth: Returns a new DateTime object where the time stamp is set to the beginning of the month.

    final DateTime dateTime = DateTime(2023, 9, 10);
    print(dateTime); // 2023-09-10
    print(dateTime.startOfMonth); // 2023-09-01T00:00:00.0
    
  • endOfMonth: Returns a new DateTime object where the time stamp is set to the end of the month.

    final DateTime dateTime = DateTime(2023, 9, 10);
    print(dateTime); // 2023-09-10
    print(dateTime.endOfMonth); // 2023-09-30T23:59:59.999999
    
  • startOfYear: Returns a new DateTime object where the time stamp is set to the beginning of the year.

    final DateTime dateTime = DateTime(2023, 9, 10);
    print(dateTime); // 2023-09-10
    print(dateTime.startOfYear); // 2023-01-01T00:00:00.0
    
  • endOfYear: Returns a new DateTime object where the time stamp is set to the end of the year.

    final DateTime dateTime = DateTime(2023, 9, 10);
    print(dateTime); // 2023-09-10
    print(dateTime.endOfYear); // 2023-12-31T23:59:59.999999
    

Comparison Operations

  • isToday: Returns true if the provided DateTime is today, otherwise returns false.

    final DateTime today = DateTime(2024, 9, 10);
    final bool notToday = DateTime(2001, 12, 31).isToday; // false
    
  • isSameDayAs: Compares two DateTime objects and returns true if they represent the same day.

    final DateTime first = DateTime(2001, 1, 1);
    final DateTime second = DateTime(2001, 1, 2);
    final DateTime third = DateTime(2001, 1, 1);
    
    final bool firstAndSecond = first.isSameDayAs(second); // false
    final bool firstAndThird = first.isSameDayAs(third); // true
    

Period Information Operations

  • daysInMonth: Returns an int with the number of days in a provided month.

    final int daysInMonth = DateTime(2024, 9).daysInMonth; // 30
    
  • firstDayOfWeek: Returns a new DateTime object where the time stamp is set to the beginning of the first day (Sunday) of the original DateTime's week.

    final DateTime today = DateTime(2024, 9, 10); // Tuesday
    final DateTime sunday = today.firstDayOfWeek; // Sunday
    

"Yesterday" and "tomorrow" getters

  • yesterday: returns a new DateTime object for the previous start of day.

    final DateTime now = DateTime.now(); // 2024-10-07 13:37:48.274
    final DateTime yesterday = DateTime(0).yesterday; // 2024-10-06 00:00:00.000
    
  • tomorrow: returns a new DateTime object for tomorrow's start of day.

    final DateTime now = DateTime.now(); // 2024-10-07 13:37:48.274
    final DateTime tomorrow = DateTime(0).tomorrow; // 2024-10-08 00:00:00.000
    

Leap Years

  • isLeapYear: returns a bool corresponding to whether a given year is a leap year. This can also be used directly on an int.

    print(DateTime(2024).isLeapYear); // true
    print(DateTime(2025).isLeapYear); // false
    print(2024.isLeapYear); // true
    print(2025.isLeapYear); // false
    

JWT Parsing #

These extensions enhance the String class with JWT-specific functionalities, making it easier to handle JSON Web Tokens directly as String objects.

Here are some examples of how these methods can be utilized:

  • Parse a JWT string

    String token = "your.jwt.token";
    final JwtPayload? payload = token.jwt; // Returns the JWT's payload
    
  • Extracting the email address (jwt["sub"])

    String jwt = "your.jwt.token";
    final String? email = jwt.jwt.email; // Returns the email address in the JWT
    
  • Extracting the token expiration time (jwt["exp"])

    String jwt = "your.jwt.token";
    // Returns a `DateTime?` when the token expires
    final DateTime? email = jwt.jwt.expiryTime;
    
  • Extracting the user ID (jwt["uid"])

    String jwt = "your.jwt.token";
    final String? uid = jwt.jwt.userId; // Returns the UID value from the token
    
  • Extracting the given name (jwt["given_name"])

    String jwt = "your.jwt.token";
    final String? uid = jwt.jwt.givenName; // Returns the given name from the token
    
  • Extracting the family name (jwt["family_name"])

    String jwt = "your.jwt.token";
    final String? uid = jwt.jwt.familyName; // Returns the family name from the token
    

String Utilities #

The following utilities have been added to enhance working with String objects:

  • isNullOrEmpty: Returns true if a String? is either null or consists of only whitespace.

    const String? nullString = null;
    const String? emptyString = " ";
    const String? nonEmptyString = "Hello World!";
    
    print(nullString.isNullOrEmpty) // true
    print(emptyString.isNullOrEmpty) // true
    print(nonEmptyString.isNullOrEmpty) // false
    
  • isNotNullOrEmpty: Returns true if a String? is neither null nor consists of only whitespace.

    const String? nullString = null;
    const String? emptyString = " ";
    const String? nonEmptyString = "Hello World!";
    
    print(nullString.isNotNullOrEmpty) // false
    print(emptyString.isNotNullOrEmpty) // false
    print(nonEmptyString.isNotNullOrEmpty) // true
    
  • splitByLength(int length): Splits a String into a List<String> where each value is of the maximum length provided.

    const String text = "DartLang";
    final List<String> result = text.splitByLength(3); // ["Dar", "tLa", "ng"]
    
  • capitalize: Capitalizes the first letter of a given String

    const String text = "hello";
    final String capitalized = text.capitalize; // "Hello"
    
  • capitalizeWords: Capitalizes the first letter of each word in a given String

    String text = "hello world";
    String capitalizedWords = text.capitalizeWords; // "Hello World"
    
  • spacePascalCase: Adds spaces between words in a PascalCase String

    String text = "ArcaneHelperUtils";
    String spaced = text.spacePascalCase; // "Arcane Helper Utils"
    

Additionally, the CommonString class provides a quick shortcut to common strings, such as punctuation marks that are otherwise cumbersome to find or type.

List Extensions #

The following extensions have been added to the List object:

  • unique([Id Function(E element)? id, bool inplace = true]): Filters a list by a given element, returning only non-duplicate values. Can return either a new List or filter the existing list by specifying the inplace option.

    const List<int> list = [1, 2, 2, 3, 4, 4];
    final List<int> uniqueList = list.unique();
    print(uniqueList); // Output: [1, 2, 3, 4]
    const List<Person> people = [
      Person(id: 1, name: 'Alice'),
      Person(id: 2, name: 'Bob'),
      Person(id: 1, name: 'Alice Duplicate'),
    ];
    final List<Person> uniquePeople = people.unique((person) => person.id);
    print(uniquePeople.map((p) => p.name)); // Output: ['Alice', 'Bob']
    
  • isNullOrEmpty: Checks if a list is either null or empty.

    const List<int> list = [1, 2, 3];
    print(list.isNullOrEmpty); // Output: false
    final List<int> emptyList = <int>[];
    print(emptyList.isNullOrEmpty); // Output: true
    final List<int>? nullList = null;
    print(nullList.isNullOrEmpty); // Output: true
    
  • isNullOrEmpty: Checks if a list is either null or empty.

    final List<int> list = [1, 2, 3];
    print(list.isNullOrEmpty); // Output: false
    final List<int> emptyList = <int>[];
    print(emptyList.isNullOrEmpty); // Output: true
    final List<int>? nullList = null;
    print(nullList.isNullOrEmpty); // Output: true
    
  • equals: Compares two lists to see if they are equal.

    List<int?>? list1 = [1, 2, null, 4];
    List<int?>? list2 = [1, 2, null, 4];
    List<int?>? list3 = [1, 2, 3, 4];
    List<int?>? list4 = null;
    List<int?>? list5 = [1, 2, 3, null];
    
    print(list1.equals(list2)); // Output: true
    print(list1.equals(list3)); // Output: false
    print(list1.equals(list4)); // Output: false
    print(list4.equals(null));  // Output: true
    print(list5.equals([1,2,3,null])); // Output: true
    
    // Example with ignoreSorting:
    List<int>? list6 = [1, 2, 3];
    List<int>? list7 = [3, 1, 2];
    
    // Output: true (order doesn't matter)
    print(list6.equals(list7, ignoreSorting: true));
    
    // Output: false (order matters)
    print(list6.equals(list7, ignoreSorting: false));
    
    List<String>? list8 = ["apple", "banana", "cherry"];
    List<String>? list9 = ["cherry", "apple", "banana"];
    
    // Output: true
    print(list8.equals(list9, ignoreSorting: true));
    
    // Output: false
    print(list8.equals(list9, ignoreSorting: false));
    

Contributing #

Contributions are welcome! Feel free to fork the repository and submit pull requests.

1
likes
160
points
220
downloads

Publisher

verified publisherflutterperfect.dev

Weekly Downloads

Provides a variety of helpful utilities and extensions for Flutter and Dart.

Repository (GitHub)
View/report issues
Contributing

Topics

#extensions #arcane-framework #helper-utils

Documentation

API reference

License

BSD-3-Clause (license)

Dependencies

freezed_annotation, week_number

More

Packages that depend on arcane_helper_utils