BloomRpcContract<TInput, TOutput> class

Strongly-typed specification of an RPC network endpoint.

BloomRpcContract defines the network boundary contract shared between client applications and backend servers:

  • HTTP Method & Path: Specifies the HTTP verb (method) and URL path template (pathTemplate), supporting path parameter tokens (e.g. '/users/:id/posts/:postId').
  • Input & Output Types: Parameterized on TInput (request payload / query parameters) and TOutput (decoded response payload).
  • Codecs: Encodes inputs to JSON-compatible structures via encodeInput and decodes server responses into strongly typed Dart objects via decodeOutput.
  • Zero Transport Overhead: A contract is a pure description, carrying no transport or network logic itself. It can be declared as a compile-time const or top-level final.

End-to-End Type Safety Example

// 1. Shared contract declaration (shared across client and server)
class CreateTaskInput {
  final String title;
  final bool completed;
  CreateTaskInput({required this.title, this.completed = false});
  Map<String, dynamic> toJson() => {'title': title, 'completed': completed};
}

class Task {
  final String id;
  final String title;
  final bool completed;
  Task({required this.id, required this.title, required this.completed});
  factory Task.fromJson(Map<String, dynamic> json) => Task(
    id: json['id'] as String,
    title: json['title'] as String,
    completed: json['completed'] as bool? ?? false,
  );
}

const createTaskContract = BloomRpcContract<CreateTaskInput, Task>.post(
  '/tasks',
  encodeInput: (input) => input.toJson(),
  decodeOutput: Task.fromJson,
);

// 2. Client-side execution with full type inference
final client = BloomRpcClient(baseUrl: 'https://api.example.com');
final Task createdTask = await client.call(
  createTaskContract,
  CreateTaskInput(title: 'Write unit tests'),
);

See also:

Constructors

BloomRpcContract({required BloomHttpMethod method, required String pathTemplate, dynamic encodeInput(TInput input)?, TInput decodeInput(dynamic json)?, dynamic encodeOutput(TOutput output)?, TOutput decodeOutput(dynamic json)?, String? summary, String? description, List customCacheKey(TInput input)?})
Creates a BloomRpcContract with explicit method, pathTemplate, and codecs.
const
BloomRpcContract.delete(String pathTemplate, {dynamic encodeInput(TInput input)?, TInput decodeInput(dynamic json)?, dynamic encodeOutput(TOutput output)?, TOutput decodeOutput(dynamic json)?, String? summary, String? description, List customCacheKey(TInput input)?})
Shorthand constructor for an HTTP DELETE endpoint contract.
const
BloomRpcContract.get(String pathTemplate, {dynamic encodeInput(TInput input)?, TInput decodeInput(dynamic json)?, dynamic encodeOutput(TOutput output)?, TOutput decodeOutput(dynamic json)?, String? summary, String? description, List customCacheKey(TInput input)?})
Shorthand constructor for an HTTP GET endpoint contract.
const
BloomRpcContract.patch(String pathTemplate, {dynamic encodeInput(TInput input)?, TInput decodeInput(dynamic json)?, dynamic encodeOutput(TOutput output)?, TOutput decodeOutput(dynamic json)?, String? summary, String? description, List customCacheKey(TInput input)?})
Shorthand constructor for an HTTP PATCH endpoint contract.
const
BloomRpcContract.post(String pathTemplate, {dynamic encodeInput(TInput input)?, TInput decodeInput(dynamic json)?, dynamic encodeOutput(TOutput output)?, TOutput decodeOutput(dynamic json)?, String? summary, String? description, List customCacheKey(TInput input)?})
Shorthand constructor for an HTTP POST endpoint contract.
const
BloomRpcContract.put(String pathTemplate, {dynamic encodeInput(TInput input)?, TInput decodeInput(dynamic json)?, dynamic encodeOutput(TOutput output)?, TOutput decodeOutput(dynamic json)?, String? summary, String? description, List customCacheKey(TInput input)?})
Shorthand constructor for an HTTP PUT endpoint contract.
const

Properties

customCacheKey → List Function(TInput input)?
Optional custom cache key generator overriding default RPC cache key derivation.
final
decodeInput → TInput Function(dynamic json)?
Optional function that transforms raw JSON/query map into typed TInput on the server side.
final
decodeOutput → TOutput Function(dynamic json)?
Function that transforms decoded JSON response data into strongly typed TOutput. Decodes the raw JSON response into TOutput.
final
description → String?
Optional detailed description of this endpoint's behavior.
final
encodeInput → dynamic Function(TInput input)?
Optional function that transforms typed TInput into a JSON-encodable map, list, or primitive.
final
encodeOutput → dynamic Function(TOutput output)?
Optional function that transforms typed TOutput into a JSON-encodable payload on the server side.
final
hashCode → int
The hash code for this object.
no setterinherited
method → BloomHttpMethod
The HTTP verb used for this endpoint.
final
pathParameters → List<String>
Extracts all path parameter names defined in pathTemplate.
no setter
pathTemplate → String
The URL path template, optionally containing :parameter interpolation tokens.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
summary → String?
Optional human-readable short summary of this endpoint.
final

Methods

cacheKey(TInput input, {Map<String, dynamic>? pathParams, Map<String, dynamic>? queryParameters}) → List
Derives a structured cache key for integration with BloomData and BloomQuery.
matchPath(String requestPath) → Map<String, String>?
Matches an incoming requestPath against this contract's pathTemplate on the server side.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
resolvePath({Map<String, dynamic>? pathParams, dynamic input}) → String
Interpolates path parameters into pathTemplate, percent-encoding all parameter values.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited