https://github.com/flarebyte/beaming_yggdrasil
Pure Dart client primitives for a Yggdrasil-style service
https://github.com/flarebyte/beaming_yggdrasil
client dart flutter yggdrasil
Last synced: 2 days ago
JSON representation
Pure Dart client primitives for a Yggdrasil-style service
- Host: GitHub
- URL: https://github.com/flarebyte/beaming_yggdrasil
- Owner: flarebyte
- License: mit
- Created: 2025-09-12T08:27:36.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-05-25T08:32:53.000Z (about 2 months ago)
- Last Synced: 2026-05-25T10:26:06.616Z (about 2 months ago)
- Topics: client, dart, flutter, yggdrasil
- Language: Dart
- Homepage: https://github.com/flarebyte/beaming_yggdrasil
- Size: 314 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# beaming_yggdrasil
Pure Dart client primitives for a Yggdrasil-style service, designed to embed
cleanly inside Flutter applications.
This package is currently best understood as a spec-aligned client foundation:
it provides immutable models, typed wire DTOs, an optional Rx adapter, and a
testing-only snapshot control surface. It does not yet ship production HTTP or
WebSocket transport implementations.
The package currently provides:
- immutable client-side key, value, result, and event models
- a classic `Future` and `Stream` client surface
- an optional Rx-friendly adapter layered on top of the classic client
- a separate testing client for snapshot seeding in tests
- typed REST and light WebSocket DTOs
The package does not currently provide:
- a production HTTP implementation
- a production WebSocket transport
- an offline cache engine
- Flutter widgets or `BuildContext` integrations
## Package Scope
- pure Dart library, intended to run inside Flutter apps
- current value payload contract is string-only
- recovery and diagnostics are explicit hooks, not hidden framework behavior
- snapshot replacement is testing-only and not part of the real client API
## Flutter-Friendly Usage
The core library stays pure Dart, so a Flutter app can wrap it in its own
controller, view model, or state-management layer.
```dart
import 'dart:async';
import 'package:beaming_yggdrasil/beaming_yggdrasil.dart';
class TreeController {
final BeamingYggdrasilClient client;
StreamSubscription? _subscription;
List snapshot = const [];
TreeController(this.client);
Future load(String rootKeyId) async {
snapshot = await client.getSnapshot(rootKeyId);
}
Future startWatching(String rootKeyId) async {
await _subscription?.cancel();
_subscription = client.watch([rootKeyId]).listen((event) {
if (event is BeamingSetEvent) {
_applyValue(event.keyValue);
}
});
}
Future dispose() async {
await _subscription?.cancel();
}
void _applyValue(BeamingValue nextValue) {
final current = snapshot.toList();
final index = current.indexWhere(
(value) => value.key.keyId == nextValue.key.keyId,
);
if (index == -1) {
current.add(nextValue);
} else {
current[index] = nextValue;
}
snapshot = List.unmodifiable(current);
}
}
```
## Local Example
See `example/example.dart` for a complete example showing:
- snapshot bootstrap
- watch subscription
- create flow
- the optional Rx adapter
The example uses a local support harness outside `lib/`. That harness is not
part of the published runtime API.
## Public API Overview
- `BeamingYggdrasilClient`
Main consumer surface using `Future` and `Stream`.
- `BeamingYggdrasilRxClient`
Optional adapter for Rx-style composition over the classic client.
- `BeamingYggdrasilTestingClient`
Testing-only snapshot seeding surface.
- `BeamingRestEnvelope` and related DTOs
Typed REST request and response models.
- `BeamingServerMessage` and related DTOs
Typed light WebSocket protocol models.
- `BeamingRecoveryExecutor`
Explicit recovery-policy boundary for refresh and resubscribe flows.
## Development
Useful commands:
- `make format-dart`
- `make analyze`
- `make test-unit`
- `make test-e2e`
- `make package-check`
- `make publish-dry-run`
- `make publish-check`
`make test-e2e` expects the sibling mock-server repo at `../chatty-ratatoskr`.
## License
`beaming_yggdrasil` is available under the [LICENSE](LICENSE).