refactor: update caching strategy and response handling documentation

- Clarified usage of `whenConstOrNull` and `toRegisteredStatusCode()`
- Improved regex pattern for status code matching with negative lookarounds
- Enhanced test cases for regex pattern validation

Author: tsinis

extension/mcp/prompts/cache_strategy.md

@@ -27,10 +27,10 @@ Follow these steps:
    - `501 Not Implemented` — long TTL, unlikely to change soon
    - `204`, `203`, `206`, `300`, `414` — short to moderate TTL depending on use case
 
-   Use `whenConstOrNull` to express this as a compile-time mapping:
+   Use `whenConstOrNull` to express this as a compile-time mapping (`whenConstOrNull` is on `StatusCode`, so convert from raw `int` first):
 
    ```dart
-   final ttl = statusCode.whenConstOrNull(
+   final ttl = rawStatusCode.toRegisteredStatusCode()?.whenConstOrNull(
      okHttp200: Duration(minutes: 5),
      noContentHttp204: Duration(minutes: 1),
      notFoundHttp404: Duration(minutes: 10),
@@ -47,5 +47,5 @@ Follow these steps:
 4. **Emit a complete, reusable function** that:
    - Checks `isStatusCode` before doing anything (guards against invalid codes)
    - Uses `isCacheable` to gate the write
-   - Uses `whenConstOrNull` or `whenConst` for TTL assignment (no runtime allocations)
+   - Uses `toRegisteredStatusCode()?.whenConstOrNull(...)` for TTL assignment — convert first since these methods are on `StatusCode`, not raw `int` (no runtime allocations)
    - Falls back gracefully for non-cacheable codes (log and skip, do not throw)

extension/mcp/prompts/handle_response.md

@@ -37,7 +37,7 @@ Follow these steps:
 
 4. **Emit null-safe, idiomatic Dart**:
    - Prefer `?.` and `??` over null-checks
-   - Use `const` callbacks with `whenConstStatusCode` / `whenConstOrNull` when the return values are constants
+   - Use `whenConstStatusCode` / `whenConstOrNull` when the return values are constants — these accept **direct values**, not closures (e.g. `isSuccess: 'ok'`, never `isSuccess: () => 'ok'`); they must be called on a `StatusCode` value after `toRegisteredStatusCode()` conversion
    - Avoid `if (code >= 200 && code < 300)` — use `.isSuccess` / `.isError` / `.isCacheable` etc.
 
 5. **Handle the specific code** {{#status_code}}({{status_code}}){{/status_code}} with a dedicated branch inside `maybeMap` or `maybeWhen` on the `StatusCode`, using the constant name `<camelName>Http<NNN>`.

extension/mcp/resources/api_reference.md

@@ -130,26 +130,29 @@ response.statusCode.maybeWhenStatusCode(
   isSuccess: () => true,
 )
 
-// Const-value variant (no closures — direct values)
+// Const-value variant — all 5 categories required, no orElse, asserts in-range
 response.statusCode.whenConstStatusCode(
   isInformational: 'info',
   isSuccess: 'ok',
   isRedirection: 'redirect',
   isClientError: 'client error',
   isServerError: 'server error',
-  orElse: 'unknown',
 )
 
-// Returns null instead of requiring orElse
+// Nullable variant — all params optional, orElse is also optional
 response.statusCode.whenConstStatusCodeOrNull(
   isSuccess: 'ok',
   isClientError: 'client error',
+  orElse: 'unknown',
 )
 
-// Convert then map in one step
+// Convert then map per category in one step
 response.statusCode.mapToRegisteredStatusCode(
-  mapper: (statusCode) => statusCode.reason,
-  orElse: (raw) => 'Unknown: $raw',
+  isInformational: (code) => code?.reason ?? 'info',
+  isSuccess: (code) => code?.reason ?? 'success',
+  isRedirection: (code) => code?.reason ?? 'redirect',
+  isClientError: (code) => code?.reason ?? 'client error',
+  isServerError: (code) => code?.reason ?? 'server error',
 )
 ```
 

extension/mcp/resources/patterns.md

@@ -83,10 +83,10 @@ final icon = statusCode.whenConstOrNull(
 );
 ```
 
-Category-level const mapping via `whenConstStatusCode`:
+Category-level const mapping via `whenConstStatusCodeOrNull`:
 
 ```dart
-final label = rawCode.whenConstStatusCode(
+final label = rawCode.whenConstStatusCodeOrNull(
   isInformational: 'informational',
   isSuccess: 'success',
   isRedirection: 'redirect',
@@ -188,15 +188,15 @@ import 'package:functional_status_codes/functional_status_codes.dart';
 test('handler returns null for any client error', () {
   for (var i = 0; i < 50; i++) {
     final code = StatusCode.random(from: StatusCode.clientErrorCodes);
-    expect(handleResponse(code), isNull);
+    expect(handleResponse(code, () => 'body'), isNull);
   }
 });
 
-test('cache is written for any cacheable code', () {
+test('cache is written for any cacheable code', () async {
   for (var i = 0; i < 20; i++) {
     final code = StatusCode.random(from: StatusCode.cacheableCodes);
     expect(code.isCacheable, isTrue);
-    fetchAndCache('key', () async => Response(statusCode: code));
+    await fetchAndCache('key', () async => Response(statusCode: code));
     expect(cache.has('key'), isTrue);
   }
 });
@@ -213,6 +213,6 @@ test('unknown code is handled gracefully', () {
   final unknown = StatusCode.custom(999);
   expect(unknown.isCustom, isTrue);
   expect(unknown.toRegisteredStatusCode(), isNull);
-  expect(handleResponse(unknown), isNull);
+  expect(handleResponse(unknown, () => 'body'), isNull);
 });
 ```

lib/src/status_code.dart

@@ -687,9 +687,10 @@ extension type const StatusCode._(int _code) implements int {
   ///
   /// This pattern is commonly used to identify HTTP status codes within a
   /// string. HTTP status codes are typically 3-digit integers ranging from 100
-  /// to 599. The pattern is defined by the regular expression `[1-5]\d{2}`,
-  /// which matches digits starting with 1-5 followed by exactly two more
-  /// digits, covering the full 100-599 range.
+  /// to 599. The pattern is defined by the regular expression
+  /// `(?<!\d)[1-5]\d{2}(?!\d)`, which matches a digit 1–5 followed by exactly
+  /// two more digits and uses negative lookarounds to prevent matching
+  /// sub-sequences inside longer digit runs (e.g. `6100` will not yield `100`).
   ///
   /// Examples of matching strings:
   /// - '200' for OK
@@ -703,18 +704,18 @@ extension type const StatusCode._(int _code) implements int {
   /// See also:
   /// - [RegExp], the class used to work with regular expressions in Dart.
   /// - [StatusCode], which contains standard HTTP status codes.
-  static const pattern = r'[1-5]\d{2}';
+  static const pattern = r'(?<!\d)[1-5]\d{2}(?!\d)';
 
   /// A getter that returns a [RegExp] object configured with [pattern] to match
-  /// HTTP status codes in the range 100–599.
+  /// HTTP status codes in the range 100-599.
   ///
   /// The matching is unanchored, meaning that this regular expression can find
   /// matches anywhere in the input string. This allows for the extraction of
   /// status codes from within larger bodies of text.
   ///
-  /// The [pattern] is defined by the regular expression `[1-5]\d{2}`, which
-  /// matches a digit 1–5 followed by exactly two more digits, covering the
-  /// full valid HTTP status code range (100–599).
+  /// The [pattern] uses negative lookarounds (`(?<!\d)` / `(?!\d)`) to ensure
+  /// that a three-digit sequence is not part of a longer number, covering the
+  /// full valid HTTP status code range (100-599) without false positives.
   ///
   /// Example usage:
   /// ```dart
@@ -1251,10 +1252,11 @@ extension type const StatusCode._(int _code) implements int {
     Iterable<StatusCode> from = values,
     Random? random,
   }) {
-    assert(from.isNotEmpty, 'The provided `from` iterable must not be empty');
-    final elementAt = (random ?? Random()).nextInt(from.length);
+    final list = from is List<StatusCode> ? from : from.toList();
+    assert(list.isNotEmpty, 'The provided `from` iterable must not be empty');
+    final elementAt = (random ?? Random()).nextInt(list.length);
 
     // ignore: avoid-unsafe-collection-methods, length is guaranteed to be > 0.
-    return from.elementAt(elementAt);
+    return list[elementAt];
   }
 }

test/src/status_code_test.dart

@@ -215,8 +215,9 @@ void main() => group('$StatusCode', () {
     );
 
     test(
-      'should extract first three-digit match from longer number',
-      // '12003' matches '120' first — not a registered code.
+      'should return null for longer number with embedded valid range digits',
+      // '12003': lookahead/lookbehind prevents matching '120' (followed by digit)
+      // or '200' (preceded by digit) — no isolated [1-5]xx sequence found.
       () => expect(StatusCode.tryParse('12003'), isNull),
     );
 
@@ -232,6 +233,58 @@ void main() => group('$StatusCode', () {
     );
   });
 
+  group('pattern and regExp', () {
+    test(
+      'pattern matches the expected regex string',
+      () => expect(StatusCode.pattern, r'(?<!\d)[1-5]\d{2}(?!\d)'),
+    );
+
+    test(
+      'regExp is a RegExp built from pattern',
+      () => expect(StatusCode.regExp, isA<RegExp>()),
+    );
+
+    test(
+      'regExp matches a bare valid code',
+      () => expect(StatusCode.regExp.hasMatch('200'), isTrue),
+    );
+
+    test(
+      'regExp matches a code preceded by non-digit characters',
+      () => expect(StatusCode.regExp.hasMatch('status: 404.'), isTrue),
+    );
+
+    test(
+      'regExp matches a code followed by non-digit characters',
+      () => expect(StatusCode.regExp.hasMatch('200 OK'), isTrue),
+    );
+
+    test(
+      'regExp does not match a 6xx code',
+      () => expect(StatusCode.regExp.hasMatch('600'), isFalse),
+    );
+
+    test(
+      'regExp does not match a 9xx code',
+      () => expect(StatusCode.regExp.hasMatch('999'), isFalse),
+    );
+
+    test(
+      'regExp does not match a valid-range code embedded in a longer number',
+      () => expect(StatusCode.regExp.hasMatch('12003'), isFalse),
+    );
+
+    test(
+      'regExp does not match when code is preceded by a digit',
+      () => expect(StatusCode.regExp.hasMatch('1200'), isFalse),
+    );
+
+    test(
+      'regExp does not match when code is followed by a digit',
+      () => expect(StatusCode.regExp.hasMatch('2001'), isFalse),
+    );
+  });
+
   group('custom constructor edge cases', () {
     test('valid custom code in gap between standard codes', () {
       const custom = StatusCode.custom(109);