HTTP Semantics for Dart 🚀

A lightweight, type-safe library for representing HTTP status codes and methods with semantic metadata and easy classification. 🎯

This package provides a more robust alternative to using raw integers or strings, offering built-in classification (e.g., isSuccess, isError, safe, idempotent) and descriptive metadata.

✨ Features

• ✅ Type-safe Status Codes: Predefined constants for all standard status codes (e.g., HttpStatus.ok, HttpStatus.notFound, HttpStatus.continueStatus).
• 📊 Semantic Classification: Easily check status groups with isInformational, isSuccess, isRedirection, isClientError, isServerError, and isError.
• 🛠️ HTTP Methods Semantics: Constants for standard methods (GET, POST, etc.) with RFC-defined safe and idempotent flags.
• 🧩 Custom Extensions: Create your own status codes or methods while maintaining full semantic integration.
• 🌍 Cross-platform: Pure Dart package that works on Web, Mobile, and Desktop.
• 🔒 Immutable & Sealed: Designed for safety and predictable behavior.

🚀 Usage

import 'package:http_semantics/http_semantics.dart';

void main() {
  // --- Working with Status Codes ---
  final status = HttpStatus.ok;
  print(status); // 200 OK
  print('Is success: ${status.isSuccess}'); // true

  final notFound = HttpStatus.of(404);
  print('Is client error: ${notFound.isClientError}'); // true
  print('Is error: ${notFound.isError}'); // true

  // --- Working with Methods ---
  final getMethod = HttpMethod.get;
  print('Method: $getMethod'); // GET
  print('Is safe: ${getMethod.safe}'); // true
  print('Is idempotent: ${getMethod.idempotent}'); // true

  final postMethod = HttpMethod.post;
  print('Is $postMethod safe? ${postMethod.safe}'); // false
  print('Is $postMethod idempotent? ${postMethod.idempotent}'); // false

  // Custom methods or dynamic lookup
  final report = HttpMethod.custom('REPORT', idempotent: true);
  print('Custom method: $report, idempotent: ${report.idempotent}'); // true

  final dynamicMethod = HttpMethod.of('put'); // Case-insensitive lookup
  print('Resolved: $dynamicMethod, match: ${dynamicMethod == HttpMethod.put}'); // true
}

🤔 Why use this instead of dart:io?

The standard dart:io provides some constants, but it is often unavailable in Web or certain Flutter environments. http_semantics is:

1. 📦 Truly Multiplatform: Works everywhere Dart runs (including Flutter Web).
2. 🧩 Object-Oriented: Provides methods and properties instead of just raw values.
3. 📖 Rich Metadata: Includes RFC-standard attributes like idempotency and safety for methods, and comprehensive classification for status codes.

📝 License

MIT 📄