✨ New Features #

• Native HTTP Connection Pooling Settings (idleTimeout & maxConnectionsPerHost):
  • Added idleTimeout (Duration?) and maxConnectionsPerHost (int?) to RestApiGlobalConfiguration, RestClientConfig, BasicRestClientConfig, RestGlobalConfig, and RestClientBuilder.
  • Configures Dio's underlying IOHttpClientAdapter and native HttpClient with custom idle socket keep-alive duration (e.g. 90 seconds) and maximum concurrent connections per host, eliminating costly TCP/TLS handshake latency on sequential API calls.
  • Safely falls back to platform defaults when omitted and no-ops on non-IO platforms (e.g. Flutter Web).

🚀 Package Split (Zero Runtime Overhead) #

• Separated Codegen from Runtime: All code-generation tools (analyzer, build, source_gen, code_builder, dart_style, glob) have been extracted into a dedicated companion package: rest_client_builder_generator.
• rest_client_builder is now purely a runtime and annotation package containing Dio, RestResult, and annotations with zero transitive compiler dependencies.
• This completely eliminates any potential dependency conflicts (such as Flutter SDK meta pins or objectbox_generator analyzer version locks) in consumer app runtime graphs.

Consumer Setup:

dependencies:
  rest_client_builder: ^1.4.3

dev_dependencies:
  rest_client_builder_generator: ^1.4.3
  build_runner: ^2.4.15

✨ New Features #

• @RestKey Multi-Key Fallback: Introduced @RestKey(['id', '_id', 'userId']) for @RestModel fields. Deserialization tries each key in order and maps the first non-null value found. Useful for APIs returning different field names across backends (e.g., MongoDB _id vs SQL id).

  @RestModel()
  class User {
    const User({required this.id});
  
    @RestKey(['id', '_id'])
    final String id;
  }
  

• Null-Safety for @Query Parameters: Optional nullable query parameters (e.g. @Query('filter') String? filter) are automatically omitted from the request query map when null.

📖 Documentation & Pub Score #

• Added dedicated Getting Started section to README.
• Updated all installation instructions and import paths.

⚠ Breaking Change — Output Directory Renamed #

The default output folder for generated files has changed from lib/rest_client_builder/ to lib/generated/.

Migration steps for existing consumers:

dart run build_runner clean
dart run build_runner build --delete-conflicting-outputs

Then update any direct imports from rest_client_builder/… to generated/…. If you want to keep the old folder, add this to your app's build.yaml:

targets:
  $default:
    builders:
      rest_client_builder|rest_model:
        options:
          output_dir: rest_client_builder
      rest_client_builder|rest_api:
        options:
          output_dir: rest_client_builder
      rest_client_builder|rest_configuration:
        options:
          output_dir: rest_client_builder

New Features #

• Configurable output_dir — the folder where generated files land is now configurable via options.output_dir in the consumer's build.yaml. Default is generated. All cross-file import resolution inside generators automatically uses the configured folder.

• Auto-refreshed barrel export builder (rest_export) — opt-in builder that writes lib/<output_dir>.g.dart after every build. The barrel contains one export statement per generated .dart file in lib/<output_dir>/, sorted alphabetically. Because build_runner removes outputs for deleted source files before this builder runs, stale exports never accumulate.

  Enable in your build.yaml:

  targets:
    $default:
      builders:
        rest_client_builder|rest_export:
          enabled: true
          options:
            output_dir: generated   # must match other builders
  

  Usage after enabling:

  import 'package:my_app/generated.g.dart'; // one import — all generated code
  

Bug Fixes #

• Fixed: Flutter 3.38.x / ObjectBox compatibility — resolved an unsolvable pub constraint graph when rest_client_builder was used alongside objectbox_generator ^5.3.2 on Flutter 3.38.x.

  Root cause: analyzer: '>=10.2.0 <15.0.0' required meta: ^1.18.0. Flutter 3.38.1 pins meta to 1.17.0, making the constraint unsatisfiable.

  Fix: Lowered the analyzer lower-bound to >=8.1.1 <11.0.0 — the same band used by objectbox_generator 5.3.2. Also widened dart_style to '>=2.3.7 <4.0.0' and relaxed source_gen to ^4.0.1.

  No API changes. No consumer code changes required (other than the output_dir migration above).

• Cross-File @RestModel Import Resolution:
  • Fixed an issue where @RestModel classes referencing nested models or enums defined across separate files generated .g.dart files that failed to compile with Method not found: 'rest<Type>FromJson' and The method 'toJson' isn't defined for type '<Type>'.
  • The model generator now automatically inspects model field types (including types nested in List<T> and Map<K, V>) and emits explicit imports for both the source declaration file and its generated .g.dart counterpart.
  • No manual export statements or consumer code changes required.

• Migrated from int Milliseconds to Duration:
  • Replaced all raw millisecond int fields with Dart's idiomatic Duration type across annotations, configuration, runtime interfaces, and builders.
  • Annotations:
    • @ConnectTimeout(Duration(seconds: 10)) (was @ConnectTimeout(10000) with milliseconds property).
    • @ReceiveTimeout(Duration(seconds: 30)) (was @ReceiveTimeout(30000) with milliseconds property).
    • @SendTimeout(Duration(seconds: 15)) (was @SendTimeout(15000) with milliseconds property).
    • @Retry(3, Duration(milliseconds: 200)) (was delayMs: int).
    • @Cache(duration: Duration(minutes: 5)) (was durationMs: int).
    • @SSE(reconnectDelay: Duration(seconds: 3)) (was reconnectMs: int).
  • Configuration & Runtime Interfaces:
    • RestClientConfig: connectTimeout, receiveTimeout, sendTimeout, retryDelay are now Duration.
    • RestApiGlobalConfiguration: connectTimeout, receiveTimeout, sendTimeout, retryDelay are now Duration?.
    • RestRequest / BasicRestRequest: connectTimeout, receiveTimeout, sendTimeout are now Duration?.
    • RestClientBuilder: .timeouts(connectTimeout: ..., receiveTimeout: ..., sendTimeout: ...) and .retry(delay: ...) now accept Duration.
    • RestResponseCache: put(key, response, Duration duration) now accepts Duration.
    • SSEEvent: retry field is now Duration? parsed automatically from the SSE wire format.
  • Generator:
    • Updated code generator to read Duration from annotations and emit clean Duration values into generated client code.

• Restored compatibility with Flutter SDK meta 1.17.0 pin:
  • Relaxed the meta dependency constraint from ^1.19.0 to >=1.17.0 <2.0.0.
  • Flutter stable SDKs (e.g. Flutter 3.38.x) pin meta to 1.17.0 via flutter/flutter_test. The previous tight constraint caused pub get to fail for consumers even though the package only uses @Target/TargetKind from package:meta/meta_meta.dart — both of which are fully available since meta 1.15.0.
  • No API changes. No dependency_overrides required by consumers.

• Documentation & Example Improvements:
  • Refined README examples with accurate import/export usage.
  • Corrected streaming download result handling using .when().
  • Added documentation for missing RestResult combinators (.flatMap(), .mapAsync(), .flatMapAsync(), .getOrElse()).
  • Added full working examples for RestClientBuilder and queue management.
• Code Quality:
  • Resolved analyzer lints and removed unused generator imports.
  • Added missing documentation comments on public generator builder members.

• Renamed to @ResilientQueue (@OfflineQueue preserved as alias):
  • Renamed primary annotation to @ResilientQueue to convey network stability, breakable connection resilience, rate limiting, and server error retries.
  • @OfflineQueue is supported as a backward-compatible typedef alias (typedef OfflineQueue = ResilientQueue;).
• Status Code Trigger Configuration (enqueueOnStatusCodes):
  • Added enqueueOnStatusCodes: List<int> (e.g. [502, 503, 504, 429]) to specify HTTP status codes that automatically trigger queueing in RestQueueInterceptor.

New Features #

• @SSE — Server-Sent Events Annotation (Stream<SSEEvent>):

  • Annotate API methods with @SSE to subscribe to live Server-Sent Event streams (lib/src/annotations/http/sse_annotation.dart).
  • Spec-compliant HTML §9.2 parser (SseParser) handling data:, event:, id:, retry:, comments (:), and multi-line data concatenation.
  • Direct Stream<SSEEvent> return type support without Future or RestResult wrapping.
  • Runtime execution support in DioRestClient.executeSSE().

• @OfflineQueue — Resilient Offline Request Queueing:

  • Declarative @OfflineQueue annotation for auto-queueing failed requests on connection drop, timeout, or 5xx server error (lib/src/annotations/queue/offline_queue_annotation.dart).
  • RestRequestQueue in-memory queue engine with reactive live stream (itemsStream), item list (items), filtering/removal (removeWhere), and flush replay (flush).
  • RestQueueInterceptor for auto-enqueueing failed requests matching trigger rules.
  • Custom removal logic support via RestQueueResolver.

New Features #

• @HTTP — Generic Custom HTTP Verb Annotation (lib/src/annotations/http/http_annotations.dart):
  Enables non-standard HTTP verbs beyond the built-in shortcuts (@GET, @POST, etc.).
  Supports WebDAV (REPORT, COPY, MOVE, LOCK), CDN (PURGE), and any custom protocol verb.
  The method string is automatically uppercased.

  @HTTP('REPORT', '/analytics')
  Future<RestResult<Map<String, dynamic>>> report(@Body() Map<String, dynamic> q);
  

• @Streaming — Streaming Response Annotation (lib/src/annotations/http/streaming_annotation.dart):
  Marks a method to receive the HTTP response body as a raw Stream<List<int>> without loading it into RAM.
  Backed by Dio's ResponseType.stream under the hood.
  Return type must be Future<RestResult<Stream<List<int>>>>.
  Compile-time error if combined with @Multipart or @FormUrlEncoded.

  @Streaming()
  @GET('/files/{id}')
  Future<RestResult<Stream<List<int>>>> downloadFile(@Path('id') String id);
  

• RestResponseMapper.mapStream(): New static mapper that extracts a Stream<List<int>> from a Dio ResponseBody (for real HTTP calls) or falls back to wrapping bodyBytes/bodyString into a single-chunk stream (for test clients and mocks).

Improvements #

• Visitor and writer updated to propagate isStreaming through the full code generation pipeline.
• Validator now rejects @Streaming methods that also declare @Multipart or @FormUrlEncoded.
• API docs table in generated files now shows [streaming] flag next to streamed endpoints.

• Repository Migration: Updated all repository, homepage, and package documentation references to the new Git repository https://github.com/corevantdev/rest_client_builder.
• Unit Test Stability: Updated outdated unit test assertions to match the new clean abstract class and generated UserApiImpl pattern.

• Minor Refinements: Internal documentation updates and dependency package adjustments.

• Zero-Setup DX Top-Level Getters: Automatically generates clean top-level getters (demoApi, productApi, paymentApi) so controllers can invoke APIs directly with zero RestClient management or dependency injection boilerplate.
• Pure Abstract API Declarations: Completely eliminated factory constructor requirements on @RestApi() classes.
• In-Memory Response Caching (@Cache): Added @Cache(durationMs: ...) annotation for class and method levels. Eliminates network roundtrips for cached responses via RestResponseCache.
• Multi-Service & Microservice Architecture: Flexible support for single shared socket connection pools, microservice custom base URLs, and dedicated isolated client pools (@RestApi(configuration: ...)).
• Generator Variable Shadowing Fix: Renamed internal request variable in generated code to prevent shadowing method parameter names (request, body, etc.).

• Refactored Code Generation: The builder now generates standalone .g.dart files, completely removing the need for part files.
• Zero-Boilerplate Models: Removed the requirement to manually define fromJson/toJson mappings inside your @RestModel() classes.
• Smart Imports: API generation automatically detects dependencies and imports the necessary source and generated files.
• Static Analysis & Dependencies: Updated analyzer, dio, and other constraints. Addressed all static analysis warnings and documentation issues to achieve a perfect pub.flutter-io.cn score.

Initial stable release.

Added #

• @RestApi annotation-driven REST client code generation via build_runner.
• @RestModel JSON code generation (fromJson / toJson) with full JsonKey support.
• RestResult<T> sealed success/failure type with when, fold, map, flatMap, mapAsync, flatMapAsync, getOrThrow, and getOrElse.
• RestError transport-agnostic structured error with factory constructors: unknown, validation, timeout, cancelled, connection, http, and serialization.
• DioRestClient with retry, timeouts, header merging, logging, and interceptor resolution.
• RestPart.fromBytes / RestPart.fromBase64 for web-safe multipart uploads (no dart:io).
• BasicCancelToken for cooperative cancellation with isCancelled / whenCancelled.
• RestProgressCallback for upload and download progress.
• @UseInterceptor / @ExcludeInterceptor per class or method.
• @Retry, @ConnectTimeout, @ReceiveTimeout, @SendTimeout, @EnableLog overrides at the global, API, and endpoint levels.
• Compile-time validation: duplicate routes, GET/HEAD + body, missing @Path, invalid multipart combinations, and invalid return types.
• RestApiGlobalConfiguration contract with createRestClient() factory (shared singleton) and createFreshRestClient() (isolated, for tests).
• RestApiClientRegistry for shared Dio connection-pool reuse.
• CallbackRestClient for easy unit testing without a network layer.
• DefaultInterceptorPipeline with forward-request / reverse-response / reverse-error order.
• LoggingRestInterceptor with sensitive-header redaction (Authorization, Cookie, etc.).
• Generated ApiDocs.endpoints list and dartdoc tables in every *.rest.g.dart file.
• build.yaml builder registration — no consumer build.yaml required.
• Full CRUD + multipart example under example/.
• 7 test suites covering core, runtime, validators, generator, and REST parts.