Utilities

1. Requirement Document

1.1 Overview

The kUtil package is a lightweight Flutter utility library designed to standardize and simplify commonly used operations across applications.

It focuses on:

• String validation and manipulation
• DateTime formatting and calculations
• Time conversions
• Color handling utilities

The goal is to reduce repetitive boilerplate code and ensure consistency across projects.

1.2 User Stories

• String Utilities: As a developer, I want to check if a string contains a valid value in a single method and avoid repetitive null/empty checks.
• DateTime Utilities: As a developer, I want to convert DateTime into predefined formats, parse strings safely, and access derived dates like week start/end.
• Time Utilities: As a developer, I want to convert between String and TimeOfDay seamlessly.
• Color Utilities: As a developer, I want to safely handle nullable colors, convert between String and Color, and perform operations like opacity adjustment and blending.

1.3 Functional Requirements

1.3.1 String Utilities

• hasValue → bool

Example:

value.hasValue;

1.3.2 DateTime Formatting

Supported formats:

Example:

date.mmmDyyyy;

1.3.3 String to Date/Time

• String → DateTime
• String → TimeOfDay
• TimeOfDay → hhmma

Example:

"2026-04-05".toDateTime;
"10:30 AM".toTimeOfDay;
time.toHHMMA;

1.3.4 DateTime Getters

Example:

date.weekStartDate;
date.isSameDay(otherDate);
date.agoTime;

1.3.5 Color Utilities

• nonNull(Color?, fallback)
• setOpacity(double)
• operator + (blend colors)
• String → Color
• Color → String

Example:

color.nonNull(Colors.black);
color.setOpacity(0.5);
"#FF5733".toColor;
color.toHex;

1.4 Non-Functional Requirements

• Performance: Minimal execution overhead, avoid unnecessary object creation.
• Reusability: Designed using extension methods for seamless integration.
• Maintainability: Clear naming conventions and centralized format definitions.
• Scalability: Easily extendable for new utilities.
• Testability: Full unit test coverage required.

1.5 Assumptions & Constraints

• Flutter/Dart environment only.
• Minimal external dependencies (prefer pure Dart or intl).
• Consistent formatting standards across the app.

2. Technical Document

2.1 Architecture

2.2 API Design

String API

extension KStringExt on String? {
  bool get hasValue;
}

DateTime API

extension KDateTimeExt on DateTime {
  String get mmmDhhmmaa;
  String get mmmDyyyy;
  String get dmmmm;
  // ... other format getters
 
  DateTime get weekStartDate;
  DateTime get weekEndDate;
  DateTime get nextDate;
  DateTime get previousDate;
 
  bool isSameDay(DateTime other);
}

Parsing API

extension KStringDateExt on String {
  DateTime get toDateTime;
  TimeOfDay get toTimeOfDay;
}

Time API

extension KTimeExt on TimeOfDay {
  String get toHHMMA;
}

Color API

extension KColorExt on Color? {
  Color nonNull(Color fallback);
}
 
extension KColorOps on Color {
  Color setOpacity(double opacity);
  Color operator +(Color other);
  String get toHex;
}
 
extension KStringColor on String {
  Color get toColor;
}

2.3 Additional Considerations

• Error Handling: Invalid inputs should either throw controlled exceptions or return nullable values (DateTime?) based on design choice.
• Testing Strategy: Unit tests must cover all date formats, edge cases (leap year, month boundaries), and invalid inputs.

2.4 Example End-to-End Usage

final now = DateTime.now();
 
// Formatting
print(now.mmmDyyyy);
 
// Date calculations
print(now.weekStartDate);
print(now.nextMonthDate);
 
// String parsing
final date = "2026-04-05".toDateTime;
 
// Time
final time = "10:30 AM".toTimeOfDay;
print(time.toHHMMA);
 
// Color
final color = "#FF5733".toColor.setOpacity(0.8);