arcane/arcane_framework
1
0
Fork 0
mirror of https://github.com/hanskokx/arcane_framework.git synced 2026-05-14 02:19:08 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update service provider

Browse Source 
Signed-off-by: Hans Kokx <hans.d.kokx@gmail.com>
This commit is contained in:
Hans Kokx
2025-04-29 16:32:53 +02:00
parent 8711eae4d8
commit 87f86d8117
5 changed files with 303 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/analyze-and-unit-test.yaml
+2
View File
@@ -29,6 +29,8 @@ jobs:
flutter-version: ${{ env.PURO_FLUTTER_VERSION == 'stable' && '' || env.FLUTTER_VERSION }}
- name: Install dependencies
run: flutter pub get
- name: Run build_runner
run: dart run build_runner build -d
- name: Analyze
run: flutter analyze
- name: Test
CHANGELOG.md
+8 -1
View File
@@ -15,7 +15,14 @@
### ArcaneServiceProvider
- [BREAKING] `ArcaneServiceProvider.of(context)` now returns a nullable instance, rather than throwing an exception.
- [NEW] Added a new `ArcaneServiceProvider.maybeOf(context)` getter which returns a nullable `ArcaneServiceProvider` instance.
- [NEW] `ArcaneServiceProvider` now includes a `serviceOfType<T>(context)` getter to retrieve a nullable registered service instance.
- [NEW] An `addService` method was added to `ArcaneServiceProvider`
- [NEW] A `setServices` method was added to `ArcaneServiceProvider`. Invoking this method with a list of `ArcaneService` instances will replace all existing services in the `ArcaneServiceProvider`.
- [DEPRECATED] `context.serviceOfType<T>` has been deprecated in favor of `context.service<T>`.
- [NEW] `context.requiredService<T>` has been added to provide a mechanism for ensuring a particular service has been registered.
- [NEW] `ArcaneService<T>.of(context)` has been added for easy access to service instances. It returns a nullable service instance.
- [NEW] `ArcaneService<T>.requiredOf(context)` has been added. It returns a non-nullable service instance, and throws an exception if the service instance has not been registered.
### Authentication Service (ArcaneAuth)
README.md
+5 -7
View File
@@ -20,12 +20,11 @@ To use Arcane Framework in your Dart or Flutter project, follow these steps:
1. Add the dependency to your pubspec.yaml:
```yaml
dependencies:
arcane_framework: <latest>
```shell
flutter pub add arcane_framework
```
2. Wrap your `MaterialApp` or `CupertinoApp` with the `ArcaneApp` Widget, providing the necessary services and your root widget.
2. Wrap your `MaterialApp` or `CupertinoApp` with the `ArcaneApp` Widget, providing the necessary services and your root widget.
```dart
import 'package:arcane_framework/arcane_framework.dart';
@@ -36,7 +35,7 @@ To use Arcane Framework in your Dart or Flutter project, follow these steps:
services: [
MyArcaneService.I,
],
child: MyApp(...),
child: MainApp(),
),
);
}
@@ -74,7 +73,6 @@ class FavoriteColorService extends ArcaneService {
notifyListeners();
}
}
```
To register a service with Arcane, simply add the instance of the `ArcaneService` to your list of services when initializing the `ArcaneApp`.
@@ -84,7 +82,7 @@ ArcaneApp(
services: [
FavoriteColorService.I,
],
child: MyApp(...),
child: MainApp(),
),
```
lib/src/providers/service_provider.dart
+121 -39
View File
@@ -17,89 +17,171 @@ import "package:flutter/widgets.dart";
/// ```
/// To access the provided services:
/// ```dart
/// final provider = ArcaneServiceProvider.of(context);
/// final myService = ArcaneServiceProvider.of<MyService>(context);
/// ```
class ArcaneServiceProvider extends InheritedNotifier {
class ArcaneServiceProvider
extends InheritedNotifier<ValueNotifier<List<ArcaneService>>> {
/// A list of `ArcaneService` instances available through the provider.
final List<ArcaneService> serviceInstances;
List<ArcaneService> get serviceInstances => notifier!.value;
/// Creates an `ArcaneServiceProvider` that provides [serviceInstances] to the widget tree.
///
/// The [child] widget will be the root of the widget subtree that has access to the services.
@override
const ArcaneServiceProvider({
required this.serviceInstances,
ArcaneServiceProvider({
required List<ArcaneService> serviceInstances,
required super.child,
super.key,
});
}) : super(
notifier: ValueNotifier<List<ArcaneService>>(serviceInstances),
);
@override
bool updateShouldNotify(covariant ArcaneServiceProvider oldWidget) {
return !const DeepCollectionEquality().equals(
serviceInstances,
oldWidget.serviceInstances,
);
/// Retrieves the nearest `ArcaneServiceProvider` in the widget tree.
///
/// Returns null if no provider is found.
///
/// Example:
/// ```dart
/// final provider = ArcaneServiceProvider.maybeOf(context);
/// ```
static ArcaneServiceProvider? maybeOf(BuildContext context) {
return context.dependOnInheritedWidgetOfExactType<ArcaneServiceProvider>();
}
/// Retrieves the nearest `ArcaneServiceProvider` in the widget tree.
///
/// This method is used to access the `ArcaneServiceProvider` and its provided services
/// from any descendant widget. It throws an exception if no `ArcaneServiceProvider`
/// is found in the widget tree.
/// Throws an assertion error if no provider is found.
///
/// Example:
/// ```dart
/// final provider = ArcaneServiceProvider.of(context);
/// ```
static ArcaneServiceProvider? of(BuildContext context) {
return context.dependOnInheritedWidgetOfExactType<ArcaneServiceProvider>();
static ArcaneServiceProvider of<T extends ArcaneService>(
BuildContext context,
) {
final provider = maybeOf(context);
assert(provider != null, "No ArcaneServiceProvider found in context");
return provider!;
}
/// Retrieves a service of type `T` from the nearest provider.
///
/// Returns null if no service of type `T` is found or if no provider exists.
///
/// Example:
/// ```dart
/// final myService = ArcaneServiceProvider.of<MyService>(context);
/// ```
static T? serviceOfType<T extends ArcaneService>(BuildContext context) {
final provider = maybeOf(context);
if (provider == null) return null;
return provider.serviceInstances.whereType<T>().firstOrNull;
}
/// Updates the service instances in this provider.
///
/// This will trigger a rebuild of all widgets that depend on this provider.
void setServices(List<ArcaneService> newServices) {
notifier?.value = newServices;
}
/// Adds a new service to this provider.
///
/// If a service of the same type already exists, it will be replaced.
void addService(ArcaneService service) {
final int existingIndex = serviceInstances.indexWhere(
(s) => s.runtimeType == service.runtimeType,
);
final List<ArcaneService> newList =
List<ArcaneService>.from(serviceInstances);
if (existingIndex >= 0) {
newList[existingIndex] = service;
} else {
newList.add(service);
}
notifier?.value = newList;
}
}
/// An extension on `BuildContext` to provide easy access to `ArcaneService` instances
/// that are registered in an `ArcaneServiceProvider`.
///
/// This extension provides a `serviceOfType` method, which searches for a specific
/// service of type `T` in the current `ArcaneServiceProvider` or in the list of built-in
/// services.
/// This extension provides methods for retrieving services in various ways.
///
/// Example usage:
/// ```dart
/// final MyService? myService = context.serviceOfType<MyService>();
/// final myService = context.service<MyService>();
/// ```
extension ServiceProvider on BuildContext {
extension ServiceProviderExtension on BuildContext {
/// Finds and returns the `ArcaneService` instance of type `T` that has been registered
/// in the `ArcaneServiceProvider` or in the list of built-in services (`Arcane.services`).
///
/// If no such service is found, it returns `null`.
///
/// - `T`: The type of the service to be retrieved, which extends `ArcaneService`.
/// Example:
/// ```dart
/// final myService = context.service<MyService>();
/// ```
T? service<T extends ArcaneService>() {
// First check built-in services
final builtInService = Arcane.services.whereType<T>().firstOrNull;
if (builtInService != null) return builtInService;
// Then check provider
return ArcaneServiceProvider.serviceOfType<T>(this);
}
/// Finds and returns the `ArcaneService` instance of type `T` that has been registered
/// in the `ArcaneServiceProvider` or in the list of built-in services (`Arcane.services`).
///
/// Throws an assertion error if no service is found.
///
/// Example:
/// ```dart
/// final MyService? myService = context.serviceOfType<MyService>();
/// final myService = context.requiredService<MyService>();
/// ```
T? serviceOfType<T extends ArcaneService>() {
final T? builtInService =
Arcane.services.firstWhereOrNull((s) => s.runtimeType == T) as T?;
if (builtInService != null) return builtInService;
final T? foundService =
dependOnInheritedWidgetOfExactType<ArcaneServiceProvider>()
?.serviceInstances
.firstWhereOrNull((s) => s.runtimeType == T) as T?;
return foundService;
T requiredService<T extends ArcaneService>() {
final service = this.service<T>();
assert(service != null, "No service of type $T found");
return service!;
}
/// Legacy method to maintain backward compatibility.
///
/// Prefer using `service<T>()` instead.
@Deprecated("Use service<T>() instead")
T? serviceOfType<T extends ArcaneService>() => service<T>();
}
/// An abstract class representing a service in the Arcane architecture.
///
/// Classes that extend `ArcaneService` can use `ChangeNotifier` functionality
/// to notify listeners of changes. Services are typically registered in
/// `ArcaneServiceProvider` and can be accessed using the `serviceOfType`
/// `ArcaneServiceProvider` and can be accessed using the `service`
/// method on `BuildContext`.
abstract class ArcaneService<T> with ChangeNotifier {
abstract class ArcaneService with ChangeNotifier {
/// Retrieves a service of the specified type from the context.
///
/// Returns null if no service of type `T` is found.
///
/// Example:
/// ```dart
/// final myService = ArcaneService.of<MyService>(context);
/// ```
static T? of<T extends ArcaneService>(BuildContext context) =>
context.serviceOfType();
context.service<T>();
/// Retrieves a service of the specified type from the context.
///
/// Throws an assertion error if no service of type `T` is found.
///
/// Example:
/// ```dart
/// final myService = ArcaneService.requiredOf<MyService>(context);
/// ```
static T requiredOf<T extends ArcaneService>(BuildContext context) =>
context.requiredService<T>();
}
test/providers/service_provider_test.dart
+167 -17
View File
@@ -20,7 +20,7 @@ void main() {
child: Builder(
builder: (context) {
final provider = ArcaneServiceProvider.of(context);
expect(provider?.serviceInstances, equals(testServices));
expect(provider.serviceInstances, equals(testServices));
return const SizedBox();
},
),
@@ -28,13 +28,122 @@ void main() {
);
});
testWidgets("serviceOfType extension returns correct service",
testWidgets("static serviceOfType<T> method returns correct service",
(tester) async {
await tester.pumpWidget(
ArcaneApp(
services: testServices,
child: Builder(
builder: (context) {
final service =
ArcaneServiceProvider.serviceOfType<MockArcaneService>(
context,
);
expect(service, isNotNull);
expect(service, isA<MockArcaneService>());
return const SizedBox();
},
),
),
);
});
testWidgets(
"static serviceOfType<T> method returns correct service and returns null when not found",
(tester) async {
await tester.pumpWidget(
ArcaneApp(
services: testServices,
child: Builder(
builder: (context) {
// Should find this service
final service =
ArcaneServiceProvider.serviceOfType<MockArcaneService>(
context,
);
expect(service, isA<MockArcaneService>());
// Returns null for unregistered services
expect(
ArcaneServiceProvider.serviceOfType<UnregisteredService>(
context,
),
isNull,
);
return const SizedBox();
},
),
),
);
});
testWidgets("service<T> extension returns correct service", (tester) async {
await tester.pumpWidget(
ArcaneApp(
services: testServices,
child: Builder(
builder: (context) {
final service = context.service<MockArcaneService>();
expect(service, isNotNull);
expect(service, isA<MockArcaneService>());
return const SizedBox();
},
),
),
);
});
testWidgets(
"requiredService<T> extension returns correct service and throws when not found",
(tester) async {
await tester.pumpWidget(
ArcaneApp(
services: testServices,
child: Builder(
builder: (context) {
// Should find this service
final service = context.requiredService<MockArcaneService>();
expect(service, isA<MockArcaneService>());
// Should throw for missing service
expect(
() => context.requiredService<UnregisteredService>(),
throwsA(isA<AssertionError>()),
);
return const SizedBox();
},
),
),
);
});
testWidgets("service<T> returns null for unregistered service",
(tester) async {
await tester.pumpWidget(
ArcaneApp(
services: testServices,
child: Builder(
builder: (context) {
final service = context.service<UnregisteredService>();
expect(service, isNull);
return const SizedBox();
},
),
),
);
});
testWidgets("legacy serviceOfType method still works but is deprecated",
(tester) async {
await tester.pumpWidget(
ArcaneApp(
services: testServices,
child: Builder(
builder: (context) {
// ignore: deprecated_member_use_from_same_package
final service = context.serviceOfType<MockArcaneService>();
expect(service, isNotNull);
expect(service, isA<MockArcaneService>());
@@ -45,15 +154,49 @@ void main() {
);
});
testWidgets("serviceOfType returns null for unregistered service",
(tester) async {
testWidgets("service updates trigger rebuilds", (tester) async {
late ArcaneServiceProvider provider;
int buildCount = 0;
await tester.pumpWidget(
MaterialApp(
home: ArcaneServiceProvider(
serviceInstances: testServices,
child: Builder(
builder: (context) {
provider = ArcaneServiceProvider.of(context);
buildCount++;
// Access a service to create dependency
context.service<MockArcaneService>();
return const Text("Test");
},
),
),
),
);
expect(buildCount, 1);
// Update services and verify rebuild
provider.setServices([MockArcaneService(), AnotherMockService()]);
await tester.pump();
expect(buildCount, 2);
// Add a service and verify rebuild
provider.addService(UnregisteredService());
await tester.pump();
expect(buildCount, 3);
});
testWidgets("ArcaneService.of<T> static helper works", (tester) async {
await tester.pumpWidget(
ArcaneApp(
services: testServices,
child: Builder(
builder: (context) {
final service = context.serviceOfType<UnregisteredService>();
expect(service, isNull);
final service = ArcaneService.of<MockArcaneService>(context);
expect(service, isNotNull);
expect(service, isA<MockArcaneService>());
return const SizedBox();
},
),
@@ -61,25 +204,32 @@ void main() {
);
});
testWidgets("updateShouldNotify always returns true", (tester) async {
final provider = ArcaneServiceProvider(
serviceInstances: testServices,
child: const SizedBox(),
);
testWidgets("ArcaneService.requiredOf<T> static helper works",
(tester) async {
await tester.pumpWidget(
ArcaneApp(
services: testServices,
child: Builder(
builder: (context) {
final service =
ArcaneService.requiredOf<MockArcaneService>(context);
expect(service, isA<MockArcaneService>());
expect(
provider.updateShouldNotify(
ArcaneServiceProvider(
serviceInstances: testServices,
child: const SizedBox(),
expect(
() => ArcaneService.requiredOf<UnregisteredService>(context),
throwsA(isA<AssertionError>()),
);
return const SizedBox();
},
),
),
true,
);
});
});
}
// Mock classes for testing
class MockArcaneService extends ArcaneService {}
class AnotherMockService extends ArcaneService {}