Merge pull request #1625 from jwelmac/add-replace-method

add replace method to specify alternate instance

@@ -6,12 +6,13 @@
     - [Get.putAsync](#getputasync)
     - [Get.create](#getcreate)
   - [Using instantiated methods/classes](#using-instantiated-methodsclasses)
+  - [Specifying an alternate instance](#specifying-an-alternate-instance)
   - [Differences between methods](#differences-between-methods)
   - [Bindings](#bindings)
-    - [How to use](#how-to-use)
+    - [Bindings class](#bindings-class)
     - [BindingsBuilder](#bindingsbuilder)
     - [SmartManagement](#smartmanagement)
-      - [How to change](#How-to-change)
+      - [How to change](#how-to-change)
       - [SmartManagement.full](#smartmanagementfull)
       - [SmartManagement.onlyBuilders](#smartmanagementonlybuilders)
       - [SmartManagement.keepFactory](#smartmanagementkeepfactory)
@@ -202,6 +203,25 @@ To remove an instance of Get:
 Get.delete<Controller>(); //usually you don't need to do this because GetX already delete unused controllers
 ```
 
+## Specifying an alternate instance
+
+A currently inserted instance can be replaced with a similar or extended class instance by using the `replace` method. This can then be retrieved by using the original class.
+
+```dart
+class ParentClass {}
+
+class ChildClass extends ParentClass {
+  bool isChild = true;
+}
+
+Get.put(ParentClass());
+
+Get.replace<ParentClass, ChildClass>(ChildClass());
+
+final instance = Get.find<ParentClass>();
+print(instance is ChildClass); //true
+```
+
 ## Differences between methods
 
 First, let's of the `fenix` of Get.lazyPut and the `permanent` of the other methods.

@@ -128,4 +128,29 @@ extension Inst on GetInterface {
   /// `Get.lazyPut()`, is registered in memory.
   /// - [tag] optional, if you use a [tag] to register the Instance.
   bool isPrepared<S>({String? tag}) => GetInstance().isPrepared<S>(tag: tag);
+
+  /// Replace a parent instance of a class in dependency management
+  /// with a [child] instance
+  /// - [tag] optional, if you use a [tag] to register the Instance.
+  void replace<P>(P child, {String? tag}) {
+    final info = GetInstance().getInstanceInfo<P>(tag: tag);
+    final permanent = (info.isPermanent ?? false);
+    delete<P>(tag: tag, force: permanent);
+    put(child, tag: tag, permanent: permanent);
+  }
+
+  /// Replaces a parent instance with a new Instance<P> lazily from the
+  /// [<P>builder()] callback.
+  /// - [tag] optional, if you use a [tag] to register the Instance.
+  /// - [fenix] optional
+  ///
+  ///  Note: if fenix is not provided it will be set to true if
+  /// the parent instance was permanent
+  void lazyReplace<P>(InstanceBuilderCallback<P> builder,
+      {String? tag, bool? fenix}) {
+    final info = GetInstance().getInstanceInfo<P>(tag: tag);
+    final permanent = (info.isPermanent ?? false);
+    delete<P>(tag: tag, force: permanent);
+    lazyPut(builder, tag: tag, fenix: fenix ?? permanent);
+  }
 }

 import 'package:flutter_test/flutter_test.dart';
 import 'package:get/get.dart';
+
 import 'util/matcher.dart' as m;
 
 class Mock {
@@ -9,7 +10,9 @@ class Mock {
   }
 }
 
-class DisposableController extends GetLifeCycle {}
+abstract class MyController extends GetLifeCycle {}
+
+class DisposableController extends MyController {}
 
 // ignore: one_member_abstracts
 abstract class Service {
@@ -168,6 +171,86 @@ void main() {
       expect(instance.initialized, true);
     });
   });
+
+  group('Get.replace test for replacing parent instance that is', () {
+    tearDown(Get.reset);
+    test('temporary', () async {
+      Get.put(DisposableController());
+      Get.replace<DisposableController>(Controller());
+      final instance = Get.find<DisposableController>();
+      expect(instance is Controller, isTrue);
+      expect((instance as Controller).init, greaterThan(0));
+    });
+
+    test('permanent', () async {
+      Get.put(DisposableController(), permanent: true);
+      Get.replace<DisposableController>(Controller());
+      final instance = Get.find<DisposableController>();
+      expect(instance is Controller, isTrue);
+      expect((instance as Controller).init, greaterThan(0));
+    });
+
+    test('tagged temporary', () async {
+      final tag = 'tag';
+      Get.put(DisposableController(), tag: tag);
+      Get.replace<DisposableController>(Controller(), tag: tag);
+      final instance = Get.find<DisposableController>(tag: tag);
+      expect(instance is Controller, isTrue);
+      expect((instance as Controller).init, greaterThan(0));
+    });
+
+    test('tagged permanent', () async {
+      final tag = 'tag';
+      Get.put(DisposableController(), permanent: true, tag: tag);
+      Get.replace<DisposableController>(Controller(), tag: tag);
+      final instance = Get.find<DisposableController>(tag: tag);
+      expect(instance is Controller, isTrue);
+      expect((instance as Controller).init, greaterThan(0));
+    });
+
+    test('a generic parent type', () async {
+      final tag = 'tag';
+      Get.put<MyController>(DisposableController(), permanent: true, tag: tag);
+      Get.replace<MyController>(Controller(), tag: tag);
+      final instance = Get.find<MyController>(tag: tag);
+      expect(instance is Controller, isTrue);
+      expect((instance as Controller).init, greaterThan(0));
+    });
+  });
+
+  group('Get.lazyReplace replaces parent instance', () {
+    tearDown(Get.reset);
+    test('without fenix', () async {
+      Get.put(DisposableController());
+      Get.lazyReplace<DisposableController>(() => Controller());
+      final instance = Get.find<DisposableController>();
+      expect(instance, isA<Controller>());
+      expect((instance as Controller).init, greaterThan(0));
+    });
+
+    test('with fenix', () async {
+      Get.put(DisposableController());
+      Get.lazyReplace<DisposableController>(() => Controller(), fenix: true);
+      expect(Get.find<DisposableController>(), isA<Controller>());
+      (Get.find<DisposableController>() as Controller).increment();
+
+      expect((Get.find<DisposableController>() as Controller).count, 1);
+      Get.delete<DisposableController>();
+      expect((Get.find<DisposableController>() as Controller).count, 0);
+    });
+
+    test('with fenix when parent is permanent', () async {
+      Get.put(DisposableController(), permanent: true);
+      Get.lazyReplace<DisposableController>(() => Controller());
+      final instance = Get.find<DisposableController>();
+      expect(instance, isA<Controller>());
+      (instance as Controller).increment();
+
+      expect((Get.find<DisposableController>() as Controller).count, 1);
+      Get.delete<DisposableController>();
+      expect((Get.find<DisposableController>() as Controller).count, 0);
+    });
+  });
 }
 
 class PermanentService extends GetxService {}