mirror of
https://github.com/hanskokx/arcane_helper_utils.git
synced 2026-05-14 10:29:07 +02:00
hans
89e49d60e8
- Migrate linting rules to use arcane_analysis Signed-off-by: Hans Kokx <hans.d.kokx@gmail.com>
320 lines
9.0 KiB
Markdown
320 lines
9.0 KiB
Markdown
# Overview
|
|
|
|
Arcane Helper Utils is a Dart package designed to enhance Dart development by
|
|
providing utility functions and extensions that simplify common tasks.
|
|
|
|
[](https://pub.dev/packages/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, 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.
|