trpc_dart 0.2.0
trpc_dart: ^0.2.0 copied to clipboard
Pure Dart runtime for tRPC v11 clients - links, batching, SuperJSON, typed errors, and a state-agnostic query cache.
trpc_dart #
Pure Dart runtime for tRPC v11 clients. Provides a composable link pipeline, automatic HTTP batching, SuperJSON decoding, typed error hierarchies, and a state-agnostic query cache.
Works anywhere Dart runs: Flutter (iOS, Android, Web, macOS, Windows, Linux), Dart CLI tools, and backend Dart servers.
Part of the rpc-dart monorepo.
Features #
- Composable link pipeline: Chain middleware for authentication, retries, logging, context, and transport.
- HTTP batching transport:
HttpBatchLinkcombines multiple procedure calls dispatched in the same event-loop tick into a single index-aligned HTTP request. - SuperJSON envelope support: Decodes
DateintoDateTime,bigintintoBigInt,NaN/Infinity,Set, andUriwithout silent data loss. - Zero-cast JSON reader:
RpcJsonparses JSON with Dart 3 pattern matching, attaching field breadcrumbs (UserGetByIdOutput.receipt.authorizedAt) to any type mismatch. - Three-state PATCH handling:
RpcOpt<T>distinguishes omitted keys, explicitnull, and updated values. - Framework-free query cache:
RpcQueryCachemanages query deduplication, invalidation streams, and optimistic updates without tying you to any state management library. - Typed exception table: Exceptions map directly to the tRPC v11 error specification (
RpcBadRequestException,RpcUnauthorizedException,RpcNotFoundException, and more).
Installation #
Add trpc_dart to your pubspec.yaml:
dependencies:
trpc_dart: ^0.2.0
Then run:
dart pub get
# or for Flutter:
flutter pub get
Quickstart #
Generated client code uses RpcClient to execute procedure calls:
import 'package:trpc_dart/trpc_dart.dart';
void main() async {
// 1. Configure client and link chain
final client = RpcClient(
endpoint: Uri.parse('https://api.example.com/trpc'),
transformer: RpcTransformer.superjson,
links: [
// Logs requests and responses, redacting secrets automatically
LoggingLink(onEvent: (event) => print('[rpc] ${event.event} ${event.path}')),
// Retries transient failures with exponential backoff
RetryLink(policy: const RpcRetryPolicy(maxAttempts: 3)),
// Automatically refreshes tokens on 401 UNAUTHORIZED
AuthLink(
getHeaders: () async => {'authorization': 'Bearer my-token'},
onUnauthorized: () async => refreshSessionToken(),
),
// Terminal transport: coalesces calls into batched HTTP requests
HttpBatchLink(endpoint: Uri.parse('https://api.example.com/trpc')),
],
);
// 2. Execute procedure directly or through generated bindings
try {
final response = await client.execute(const RpcRequest(
path: 'user.getById',
kind: RpcProcedureKind.query,
input: {'id': 'user-123'},
));
print('Raw response: $response');
} on RpcUnauthorizedException {
print('Session expired');
} on RpcBadRequestException catch (e) {
print('Validation failed: ${e.fieldErrors}');
} on RpcException catch (e) {
print('RPC error (${e.code}): ${e.message}');
}
}
Future<void> refreshSessionToken() async {
// Fetch fresh credentials
}
Composable Link Pipeline #
Links execute in the order declared in the links list:
final client = RpcClient(
endpoint: Uri.parse('https://api.example.com/trpc'),
links: [
// 1. Request logging with automatic redaction
LoggingLink(
onEvent: (e) => print('${e.event} ${e.path} (${e.durationMs}ms)'),
redactHeaders: {'x-custom-secret'},
),
// 2. Correlation IDs and dynamic application headers
ContextLink(
correlate: true, // generates and attaches x-request-id
dynamicHeaders: () async => {'x-client-version': '1.0.0'},
),
// 3. Authentication with single-flight refresh lock
AuthLink(
getHeaders: () async => {'authorization': 'Bearer $token'},
onUnauthorized: () async => authService.refreshToken(),
),
// 4. Retry link: queries retry automatically; mutations only retry if idempotent
RetryLink(
policy: RpcRetryPolicy(
maxAttempts: 3,
backoff: const Duration(milliseconds: 250),
),
),
// 5. Terminal batch transport (exactly one termination link required)
HttpBatchLink(
endpoint: Uri.parse('https://api.example.com/trpc'),
maxBatchSize: 10,
),
],
);
Query Cache & Invalidation #
RpcQueryCache runs independently of Flutter and state-management packages:
final cache = client.cache;
// Watch a query: returns an RpcQueryRef with a broadcast stream
final ref = cache.watch(
const RpcQueryKey(path: ['user', 'me']),
() => fetchCurrentUser(),
);
ref.stream.listen((state) {
switch (state) {
case RpcAsyncLoading():
print('Loading user...');
case RpcAsyncData(:final data):
print('Loaded user: $data');
case RpcAsyncError(:final error):
print('Query failed: $error');
}
});
// Invalidate specific query keys or entire subtrees:
cache.invalidate(const RpcQueryKey(path: ['user'])); // refetches all 'user.*' watchers
// Listen to invalidations:
cache.onInvalidate().listen((key) {
print('Cache invalidated: ${key.path.join(".")}');
});
// Optimistic update:
cache.setQueryData(
const RpcQueryKey(path: ['user', 'me']),
updatedUser,
);
Zero-Cast Deserialization (RpcJson) #
RpcJson eliminates uncaught TypeError crashes when server contracts change:
// Type-safe extraction with breadcrumb paths:
final name = RpcJson.asString(data['name'], 'User.name');
final count = RpcJson.asInt(data['count'], 'User.count');
final date = RpcJson.asDateTime(data['createdAt'], 'User.createdAt');
final items = RpcJson.asList(data['items'], (item, path) => Item.fromJson(item as Map<String, Object?>));
If the server sends a number instead of a string, RpcJson throws RpcDecodeException:
RpcDecodeException(DECODE) at User.name (expected String, got int): expected String but received int
Links #
- Documentation
- CLI Generator (rpc-dart)
- Flutter Bridge (trpc_flutter)
- GitHub Repository
- Issue Tracker
License #
MIT © Aditya Jandu
Real-time subscriptions #
SSE and WebSocket transports with automatic reconnection and tracked() resume:
final client = RpcClient(
endpoint: Uri.parse('http://127.0.0.1:8787/trpc'),
links: [
SplitLink(
unaryLink: HttpBatchLink(endpoint: endpoint),
subscriptionLink: HttpSubscriptionLink(endpoint: endpoint),
),
],
);
final ticks = client.subscribe<Map<String, Object?>>(
path: 'streams.onServerTick',
input: null,
decode: (value) => value! as Map<String, Object?>,
);
See docs/guides/subscriptions.md for the full guide.