raii

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 9 Open GitHub ↗

Resource Acquisition Is Initialization (RAII) pattern for Dart, providing automated lifecycle management of resources.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# raii

A Flutter package that provides RAII (Resource Acquisition Is Initialization) pattern implementation for managing object lifecycles and ensuring proper resource cleanup.

## Features

- Automatic resource disposal through lifecycle management
- Fluent API for resource registration
- Debug logging support for lifecycle events
- Type-safe resource management
- Integration with Flutter's widget lifecycle
- Support for Material and Cupertino components
- Built-in support for common Flutter resources:
  - Controllers (Animation, Text, Scroll, etc.)
  - Notifiers and Listeners
  - Streams
  - App lifecycle

## Getting Started

Add the package to your `pubspec.yaml`:

```yaml
dependencies:
  raii: ^0.3.4
```

## Usage

### Basic Widget State Management

```dart
class MyWidgetState extends State<MyWidget>
    // Add RaiiStateMixin
    with SingleTickerProviderStateMixin, RaiiStateMixin {
  // Resources are automatically disposed together with widget
  late final controller = AnimationController(vsync: this)
    .withLifecycle(this, debugLabel: 'MyAnimation');

late final textController = TextEditingController()
    .withLifecycle(this, debugLabel: 'TextInput');

// Works like initState() but runs when widget is mounted and
  // context is accesible, you are free to move it to `initState`
  // if you don't need context access.
  @override
  void initLifecycle() {
    super.initLifecycle();

// Register listeners with automatic cleanup
    controller.addListenerWithLifecycle(
      this,
      () => setState(() {}),
      debugLabel: 'AnimationListener',
    );
  }
}
```

### Material Components

```dart
// Tab Controller
late final tabController = TabController(length: 3, vsync: this)
  .withLifecycle(this, debugLabel: 'TabBar');

// Search Controller
late final searchController = SearchController()
  .withLifecycle(this, debugLabel: 'SearchBar');

// Data Table Source
final dataSource = MyDataSource()
  .withLifecycle(this, debugLabel: 'TableDataSource');
```

### Cupertino Components

```dart
// Cupertino Tab Controller
late final cupertinoTabs = CupertinoTabController(initialIndex: 0)
  .withLifecycle(this, debugLabel: 'CupertinoTabs');

// Restorable Tab Controller
late final restorableTabs = RestorableCupertinoTabController(initialIndex: 0)
  .withLifecycle(this, debugLabel: 'RestorableTabs');
```

### Custom Resource Management

#### Using RaiiBox (Wrapper Approach)

```dart
class MyCustomResource {
  void initialize() { /* ... */ }

void cleanup() { /* ... */ }
}

// Usage in a widget state
class MyWidgetState extends State<MyWidget> with RaiiStateMixin {
  late final resource = RaiiBox.withLifecycle(
    this,
    instance: MyCustomResource(),
    init: (r) => r.initialize(),
    dispose: (r) => r.cleanup(),
    debugLabel: 'CustomResource',
  );
  // The resource will be automatically initialized and disposed
  // with the widget's lifecycle
}

// Alternative usage with RaiiManager
final raiiManager = RaiiManager();
final resource = RaiiBox.withLifecycle(
  raiiManager,
  instance: MyCustomResource(),
  init: (r) => r.initialize(),
  dispose: (r) => r.cleanup(),
  debugLabel: 'CustomResource',
);

// When done
// Will properly clean up the resource
raiiManager.disposeLifecycle();
```

#### Direct Lifecycle Implementation

```dart
// Implementing lifecycle directly in your resource class
class ManagedResource with RaiiLifecycleMixin {
  late final Socket _socket;
  late final StreamSubscription _subscription;

// Named constructor that immediately attaches to a lifecycle manager
  ManagedResource.withLifecycle(RaiiLifecycleAware lifecycleAware) {
    lifecycleAware.registerLifecycle(this);
  }

@override
  void initLifecycle() {
    super.initLifecycle();

// Initialize resources
    _socket = Socket.connect(...);
    _subscription = _socket.listen(...);

debugPrint('ManagedResource: Initialized socket and subscription');
  }

@override
  void disposeLifecycle() {
    // Clean up resources
    _subscription.cancel();
    _socket.close();

debugPrint('ManagedResource: Cleaned up socket and subscription');

super.disposeLifecycle();
  }
}

// Usage in a widget - cleaner syntax with .attach constructor
class MyWidgetState extends State<MyWidget> with RaiiStateMixin {
  late final resource = ManagedResource.withLifecycle(this);
  // The resource will be automatically initialized and disposed
  // with the widget's lifecycle
}

// Alternative usage with RaiiManager
final raiiManager = RaiiManager();
final resource = ManagedResource.withLifecycle(raiiManager);

// When done
// Will properly clean up the resource
raiiManager.disposeLifecycle();
```

Choose `RaiiBox` when:
- You need to add lifecycle to an existing class
- You don't control the resource's source code

Choose direct `RaiiLifecycleMixin` implementation when:
- You're creating a new resource class
- You prefer explicit lifecycle management in your class
- You want a cleaner API with `.withLifecycle` constructor pattern

## More Examples

### Stream Management

```dart
// Automatic stream subscription cleanup
myStream.listen(onData).withLifecycle(
  this,
  debugLabel: 'MyStreamSubscription',
);
```

### Listenable Management

```dart
class MyWidgetState extends State<MyWidget> with RaiiStateMixin {
  late final valueNotifier = ValueNotifier<int>(0)
    .withLifecycle(this, debugLabel: 'Counter');

@override
  void onLifecycleAttach() {
    // Simple listener
    valueNotifier.addListenerWithLifecycle(
      this,
      setState(() {}),
      debugLabel: 'ValueNotifierListener',
    );

// Multiple listeners for the same listenable
    valueNotifier.addListenerWithLifecycle(
      this,
      updateUI,
      debugLabel: 'UIListener',
    );

valueNotifier.addListenerWithLifecycle(
      this,
      saveToPreferences,
      debugLabel: 'StorageListener',
    );

// Listening to animation controller
    final controller = AnimationController(vsync: this)
      .withLifecycle(this, debugLabel: 'Animation');

controller.addListenerWithLifecycle(
      this,
      () => debugPrint('Animation value: ${controller.value}'),
      debugLabel: 'AnimationListener',
    );
  }
}
```

### App Lifecycle Observer

```dart
class MyWidgetState extends State<MyWidget> with RaiiStateMixin {
  @override
  void initLifecycle() {
    super.initLifecycle();

// Basic app lifecycle observer
    final observer = AppStateObserver();

// raii addObserver alternative that allows you to
    // attach to the state's lifecycle
    WidgetsBinding.instance.addObserverWithLifeycle(
      this,
      observer,
      debugLabel: 'AppLifecycle',
    );
  }
}

class AppStateObserver with WidgetsBindingObserver {
  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    switch (state) {
      case AppLifecycleState.resumed:
        debugPrint('App resumed - restore resources');
        break;
      case AppLifecycleState.inactive:
        debugPrint('App inactive - pause updates');
        break;
      case AppLifecycleState.paused:
        debugPrint('App paused - save state');
        break;
      case AppLifecycleState.detached:
        debugPrint('App detached - cleanup');
        break;
    }
  }

@override
  void didChangePlatformBrightness() {
    debugPrint('Brightness changed');
  }
}
```

### Timer Management

```dart
class TimerWidgetState extends State<TimerWidget> with RaiiStateMixin {
  @override
  void initLifecycle() {
    super.initLifecycle();

Timer(
      const Duration(seconds: 5),
      () => print('Ont-shot: 5 seconds pass'),
    ).withLifecycle(
      this,
      debugLabel: 'One-shot Timer',
    );

Timer.periodic(
      const Duration(seconds: 1),
      (t) => print('Periodic: ${t.tick} seconds pass'),
    ).withLifecycle(
      this,
      debugLabel: 'Periodic Timer',
    );
  }
}
```

### Global Resources

```dart
// Resources that live for the entire application lifetime
final globalResource = MyGlobalResource.withLifecycle(
  alwaysAliveRaiiManager,
);
```

### Transferring Lifecycle Ownership

Use `takeLifecycle` to move a resource from one owner to another without disposing it:

```dart
final ownerA = RaiiManager()..initLifecycle();
final ownerB = RaiiManager()..initLifecycle();

final resource = RaiiBox.withLifecycle(
  ownerA,
  instance: MyResource(),
  dispose: (r, _) => r.cleanup(),
  debugLabel: 'MyResource',
);

// Move resource from ownerA to ownerB
ownerB.takeLifecycle(resource);

ownerA.disposeLifecycle(); // resource is NOT disposed
ownerB.disposeLifecycle(); // resource IS disposed
```

## Important Notes

### Mixin Order

When using `RaiiStateMixin` with `TickerProviderStateMixin`, the order matters:

```dart
// Correct order:
class MyWidgetState extends State<MyWidget>
    with TickerProviderStateMixin, RaiiStateMixin {
  // ...
}

// Incorrect order - will cause incorrect resources disposal:
class MyWidgetState extends State<MyWidget>
    with RaiiStateMixin, TickerProviderStateMixin {
  // ...
}
```

### Debug Labels

Debug labels help track lifecycle events in the console:

```dart
late final animationController = AnimationController(vsync: this)
  .withLifecycle(this, debugLabel: 'MyAnimation');

late final textInput = EditingTextController()
  .withLifecycle(this, debugLabel: 'TextInput');
```

**Console output:**

```
[RAII] Init lifecycle: MyAnimation
[RAII] Init lifecycle: TextInput
...
[RAII] Dispose lifecycle: TextInput
[RAII] Dispose lifecycle: MyAnimation
```

## Additional Resources

### Core Concepts

- `RaiiLifecycle` - Base interface for objects with manageable lifecycles
- `RaiiLifecycleAware` - Interface for objects that aware about other lifecycles typically used for managing multiple lifecycles
- `RaiiLifecycleMixin` - Mixin that helps add basic lifecycle implementation
- `RaiiManagerMixin` - Mixin that helps implementat for managing multiple lifecycles, it implements `RaiiLifecycleAware` interface.
- `RaiiBox` - Container for managing custom resources

## License

Licensed under the MIT ([LICENSE](LICENSE) or <https://mit-license.org/>)

raii

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README