Refactor Arcane framework and enhance logging, theme, and auth services by hanskokx · Pull Request #8 · hanskokx/arcane_framework

hanskokx · 2026-05-26T14:07:08Z

Consolidates various improvements and new features across the Arcane framework, focusing on enhanced service management, reactive updates, and a more streamlined API for application integration. This release significantly refactors core services, introduces new provider patterns, and improves overall usability and extensibility.

Key Changes

Unified Service Management: ArcaneApp now centrally manages service registration, allowing built-in services (Arcane.features, Arcane.auth, Arcane.theme, Arcane.environment) to prefer instances registered with ArcaneApp and fall back to singletons when no provider is available.
Reactive Core: Introduces stream-based updates for authentication (statusChanges, signedInChanges), feature flags (enabledFeaturesChanges), logging (logStream), and theming (themeModeChanges, themeDataChanges), enabling more granular and reactive UI updates.
Logging Enhancements:
- Implements a robust logging interceptor system (LogInterceptor) for pre-processing log messages.
- New Interceptor Facade: A centralized interceptor facade (LoggingInterceptorsService) now manages registration, resolution, and lifecycle of log interceptors for all logging interfaces. This allows for global, per-interface, or per-event interception, modification, or filtering of log events, providing fine-grained control over logging behavior across the application.
- Provides optional lifecycle management for logging interfaces (LoggingInitializable), and adds support for tagging destinations with @LoggingFeature.
Improved Theming: Renames ArcaneReactiveTheme to ArcaneThemeService for clarity, introduces assignment-style theme setters (Arcane.theme.dark = ...), and refines system theme following and theme mode detection logic.
Flexible Feature Flags: Renames ArcaneFeatureFlags to ArcaneFeatureFlagService, adds ArcaneFeatureFlagProvider for widget tree integration, and provides convenient BuildContext extensions.
Modernized Environment Management: Replaces the ArcaneEnvironment Cubit with a ValueNotifier-backed ArcaneEnvironmentService and an InheritedWidget provider, offering better integration and direct access via Arcane.environment.
Streamlined ArcaneApp Integration: Introduces ArcaneApp.builder to provide a provider-aware BuildContext immediately at app root, deprecating the child property for improved developer experience.
Dependency Management: Removes the direct flutter_bloc dependency and updates version constraints for result_monad to ^4.0.0, arcane_helper_utils to ^1.4.7, and arcane_analysis to ^1.0.4.

Breaking Changes

Arcane Class: Now a static utility surface; no longer instantiable. Consumers directly importing from package:arcane_framework/src/... must update paths (e.g., src/providers/... to src/service/...).
ArcaneApp: The child property is deprecated; prefer builder for constructing the app root with a provider-aware BuildContext.
Service Locators: BuildContext.serviceOfType() is deprecated; use BuildContext.service() instead.
Authentication Service: ArcaneAuthInterface.logout now accepts an optional onLoggedOut callback. Implementers must update their method signature.
Feature Flag Service: ArcaneFeatureFlags is renamed to ArcaneFeatureFlagService. A typedef is provided for backward compatibility, but update to the new name is recommended. ArcaneFeatureFlagsScope is renamed to ArcaneFeatureFlagProvider.
Theme Service: ArcaneReactiveTheme is renamed to ArcaneThemeService. A typedef is provided for backward compatibility, but update to the new name is recommended. The legacy ThemeMode read from Arcane.theme.systemTheme.value should be replaced with Arcane.theme.currentModeOf(context).
Environment Service: The state getter has been removed from ArcaneEnvironment; use Arcane.environment.current instead. The AuthenticationStatus.debug status has been removed.
Logging Interface: LoggingInterface no longer includes built-in singleton state (initialized and init getters/methods are removed). Implement LoggingInitializable for interfaces requiring setup logic.
Logging Interceptor Facade: All log interceptor management is now handled through the new LoggingInterceptorsService facade. Custom or legacy interceptor registration logic should be migrated to use this centralized service for consistency and improved control.

How to Test

Run the example app: Navigate to example and run flutter run.
Verify Service Interactions:
- Toggle features, environment, and theme modes using the respective cards.
- Observe log messages in the console and the "Logging" section of the app.
- Sign in/out and check authentication status updates.
- Interact with the "Services" card to register/remove the custom FavoriteColorService and change colors, observing dynamic theme updates.
Inspect Logs: Ensure log messages appear as expected, including additional metadata (e.g., persistent metadata toggle) and proper level filtering (e.g., feature flag for logging). Test that interceptors registered via the facade are invoked as expected for all interfaces.
Check UI Responsiveness: Confirm that UI elements react dynamically to changes in feature flags, environment, and theme, especially the interactive elements in the example.
Validate Build/Analyze: Run flutter pub get, flutter analyze, and flutter test from the root of the repository to ensure all checks pass.

Review Focus

API Ergonomics: Review the new API patterns for ArcaneApp.builder, BuildContext extensions for services, feature flags, and themes for intuitiveness and ease of use.
Stream Integration: Verify the correct usage and disposal of stream controllers and subscriptions for all reactive services, particularly in the example app's widget lifecycles.
Logging Interceptors & Facade: Examine the implementation of LogInterceptor and the new LoggingInterceptorsService facade to ensure they provide robust and flexible control over log events, and that global/per-interface interception works as intended.
Backward Compatibility: Confirm that typedefs and deprecated aliases for renamed services function as expected during migration, and the impact of other breaking changes is clear.
Performance: Assess any potential performance implications from the new provider and stream architecture.
Test Coverage: Review the updated tests for new features and refactored logic, ensuring comprehensive validation.

UI Changes

The example application has been completely refactored to demonstrate the new API.

Changes: // ArcaneEnvironment breaking: context.read<ArcaneEnvironment>() -> ArcaneEnvironment.of(context) breaking: context.read<ArcaneEnvironment>().state -> ArcaneEnvironment.of(context).environment; // Feature flag service added: reset() // Logging service added: registerInterface() added: unregisterInterfaces() added: unregisterAllInterfaces() // ArcaneReactiveTheme fixed: currentMode, dark, light now actually emit new values when changed added: getters for lightTheme, darkTheme, and systemTheme TODO: test systemTheme Signed-off-by: Hans Kokx <hans.d.kokx@gmail.com>

- added: reset() - added: `skipAutodetection` option for module, method, and metadata - added: unregisterInterface() - Created FileAndLineNumber mixin Signed-off-by: Hans Kokx <hans.d.kokx@gmail.com>