arcane_helper_utils 1.4.5
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.
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 filteringList
items, as well as getters forisNullOrEmpty
,isEmptyOrNull
,isNotNullOrEmpty
, andisNotEmptyOrNull
. Furthermore, anequals
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?
toint?
String?
todouble?
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 newDateTime
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 newDateTime
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 newDateTime
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 newDateTime
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 newDateTime
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 newDateTime
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 newDateTime
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 newDateTime
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 newDateTime
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 newDateTime
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
: Returnstrue
if the providedDateTime
is today, otherwise returnsfalse
.final DateTime today = DateTime(2024, 9, 10); final bool notToday = DateTime(2001, 12, 31).isToday; // false
-
isSameDayAs
: Compares twoDateTime
objects and returnstrue
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 anint
with the number of days in a provided month.final int daysInMonth = DateTime(2024, 9).daysInMonth; // 30
-
firstDayOfWeek
: Returns a newDateTime
object where the time stamp is set to the beginning of the first day (Sunday) of the originalDateTime
's week.final DateTime today = DateTime(2024, 9, 10); // Tuesday final DateTime sunday = today.firstDayOfWeek; // Sunday
"Yesterday" and "tomorrow" getters
-
yesterday
: returns a newDateTime
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 newDateTime
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 abool
corresponding to whether a given year is a leap year. This can also be used directly on anint
.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
: Returnstrue
if aString?
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
: Returnstrue
if aString?
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 aString
into aList<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 givenString
const String text = "hello"; final String capitalized = text.capitalize; // "Hello"
-
capitalizeWords
: Capitalizes the first letter of each word in a givenString
String text = "hello world"; String capitalizedWords = text.capitalizeWords; // "Hello World"
-
spacePascalCase
: Adds spaces between words in a PascalCaseString
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 newList
or filter the existing list by specifying theinplace
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.