mirror of
https://github.com/hanskokx/arcane_helper_utils.git
synced 2026-06-09 15:15:55 +02:00
@@ -0,0 +1,317 @@
|
||||
# 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, including JWT parsing.
|
||||
|
||||
## Getting Started
|
||||
|
||||
To use this package in your Dart project, add it to your project's
|
||||
`pubspec.yaml` file:
|
||||
|
||||
```yaml
|
||||
dependencies:
|
||||
arcane_helper_utils: any
|
||||
```
|
||||
|
||||
Then import it in your Dart files where needed:
|
||||
|
||||
```dart
|
||||
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.
|
||||
|
||||
```dart
|
||||
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?`:
|
||||
|
||||
```json
|
||||
{
|
||||
"valueIsMaybeNull": "",
|
||||
"valueIsDouble": "123.456",
|
||||
"valueIsInt": "123"
|
||||
}
|
||||
```
|
||||
|
||||
```dart
|
||||
@freezed
|
||||
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
|
||||
|
||||
#### 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.
|
||||
|
||||
```dart
|
||||
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.
|
||||
|
||||
```dart
|
||||
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.
|
||||
|
||||
```dart
|
||||
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.
|
||||
|
||||
```dart
|
||||
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).
|
||||
|
||||
```dart
|
||||
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).
|
||||
|
||||
```dart
|
||||
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.
|
||||
|
||||
```dart
|
||||
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.
|
||||
|
||||
```dart
|
||||
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.
|
||||
|
||||
```dart
|
||||
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.
|
||||
|
||||
```dart
|
||||
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`.
|
||||
|
||||
```dart
|
||||
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.
|
||||
|
||||
```dart
|
||||
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.
|
||||
|
||||
```dart
|
||||
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.
|
||||
|
||||
```dart
|
||||
final DateTime today = DateTime(2024, 9, 10); // Tuesday
|
||||
final DateTime sunday = today.firstDayOfWeek; // Sunday
|
||||
```
|
||||
|
||||
### 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:
|
||||
|
||||
- Extracting the email address (`jwt["sub"]`)
|
||||
|
||||
```dart
|
||||
String jwt = "your.jwt.token";
|
||||
final String? email = jwt.jwtEmail(); // Returns the email address in the JWT
|
||||
```
|
||||
|
||||
- Extracting the token expiration time (`jwt["exp"]`)
|
||||
|
||||
```dart
|
||||
String jwt = "your.jwt.token";
|
||||
// Returns a `DateTime?` when the token expires
|
||||
final DateTime? email = jwt.jwtExpiryTime();
|
||||
```
|
||||
|
||||
- Extracting the user ID (`jwt["uid"]`)
|
||||
|
||||
```dart
|
||||
String jwt = "your.jwt.token";
|
||||
final String? uid = jwt.jwtUserId(); // Returns the UID value 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.
|
||||
|
||||
```dart
|
||||
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.
|
||||
|
||||
```dart
|
||||
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.
|
||||
|
||||
```dart
|
||||
const String text = "DartLang";
|
||||
final List<String> result = text.splitByLength(3); // ["Dar", "tLa", "ng"]
|
||||
```
|
||||
|
||||
- `capitalize`: Capitalizes the first letter of a given `String`
|
||||
|
||||
```dart
|
||||
const String text = "hello";
|
||||
final String capitalized = text.capitalize; // "Hello"
|
||||
```
|
||||
|
||||
Additionally, the `CommonString` class provides a quick shortcut to common
|
||||
strings, such as punctuation marks that are otherwise cumbersome to find or type.
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome! Feel free to fork the repository and submit pull
|
||||
requests.
|
||||
Reference in New Issue
Block a user