API Reference ResultStatuses - ulfbou/Zentient.Results GitHub Wiki

๐Ÿ“˜ API Reference: static class โ€“ ResultStatuses

Namespace: Zentient.Results Assembly: Zentient.Results.dll Available since: v0.1.0

๐Ÿ“– Summary

ResultStatuses is a centralized static class providing a comprehensive set of predefined, immutable, thread-safe standard IResultStatus instances representing common HTTP-like status codes and their associated descriptions. It also exposes a cache-enabled factory method to retrieve or create custom statuses by numeric code.

This class acts as the authoritative source for status codes across the Zentient.Results ecosystem, enabling consistent and efficient status reuse, while allowing extensibility for custom codes.

๐Ÿ’ก Design Philosophy / Rationale

  • Designed to promote reuse and immutability of common statuses like Ok (200) or NotFound (404).
  • Implements a thread-safe internal cache (ConcurrentDictionary) for fast retrieval and deduplication of both standard and user-defined statuses.
  • Aligns closely with HTTP status semantics to foster familiarity and ease integration with web protocols and problem details standards (RFC 7807).
  • Facilitates structured result modeling where status codes carry business and transport meaning.
  • Provides both static properties for common statuses and dynamic creation for custom codes, promoting extensibility without compromising type safety or performance.

๐Ÿ”– Type Signature

public static class ResultStatuses

๐Ÿ“ฆ Properties

1.1. Ok

  • Type: IResultStatus
  • Summary: Represents the HTTP 200 OK status, indicating successful operation.
  • Remarks: Alias Success points to this same instance.

1.2. Success

  • Type: IResultStatus
  • Summary: Alias for Ok.

1.3. Other Status Properties (e.g., Created, BadRequest, NotFound, InternalServerError)

  • Type: IResultStatus
  • Summary: Predefined statuses for all common HTTP success, redirection, client error, and server error codes.
  • Remarks: Each status is an immutable ResultStatus instance carrying a Code and Description from ResultStatusConstants.

๐Ÿ”ง Methods

2.1. GetStatus(int code, string? description = null)

  • Signature: public static IResultStatus GetStatus(int code, string? description = null)

  • Summary: Retrieves an existing IResultStatus instance by its code if available; otherwise, creates and caches a new custom status with the provided code and optional description.

  • Parameters:

    • code (int): Numeric status code to retrieve or create.
    • description (string?): Optional textual description for the custom status.

  • Return Value: (IResultStatus) The existing or newly created status instance.

  • Behavior: Utilizes a thread-safe concurrent dictionary to avoid duplicate instances for the same code.

  • Example Usage:

var status = ResultStatuses.GetStatus(418, "I'm a teapot (custom)");

๐Ÿญ Inner Types

3.1. ResultStatus (private sealed class)

  • Implements IResultStatus for predefined statuses.
  • Stores immutable Code and Description properties.
  • Overrides ToString() to return a formatted string like [200] OK.

3.2. CustomResultStatus (private sealed class)

  • Implements IResultStatus for user-defined statuses created dynamically.
  • Stores immutable Code and Description.
  • Overrides ToString() to include (Custom) suffix for clarity.

๐Ÿงช Usage Examples

// Accessing a standard status
IResultStatus okStatus = ResultStatuses.Ok;
Console.WriteLine(okStatus.Code);         // 200
Console.WriteLine(okStatus.Description);  // "OK"

// Creating or retrieving a custom status
IResultStatus custom = ResultStatuses.GetStatus(499, "Client Closed Request");
Console.WriteLine(custom);                 // "[499] Client Closed Request (Custom)"

โš ๏ธ Remarks

  • All predefined statuses are immutable singleton instances for efficiency and safety.
  • GetStatus ensures that each numeric code corresponds to exactly one instance in the cache.
  • While modeled on HTTP codes, the class is transport-agnostic and usable in any domain requiring numeric status semantics.
  • Not thread-blocking; uses ConcurrentDictionary for lock-free concurrency.

๐Ÿงฉ Integration and Interoperability

  • Used extensively by Result<T> and other result implementations as the standard source of status codes.
  • Complements ResultStatusConstants which provides raw code and description constants.
  • Aligns with **HTTP status codes and **RFC 9457 problem details for error interoperability.
  • Extensible for custom domain-specific status codes beyond HTTP semantics.

๐Ÿ“š See Also

๐Ÿท๏ธ Tags

#ResultStatus #Immutable #Singletons #HTTPStatusCodes #ThreadSafe #ZentientCore #StableContract

Last Updated: 2025-06-21 Version: 0.4.0