You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+34-34Lines changed: 34 additions & 34 deletions
Original file line number
Diff line number
Diff line change
@@ -8,17 +8,17 @@ Typical usage:
8
8
* Accessing service objects like REST API clients, databases so that they easily can be mocked.
9
9
* Accessing View/AppModels/Managers/BLoCs from Flutter Views
10
10
11
-
>**Breaking Change with V4.0.0**
11
+
>**Breaking Change with V4.0.0**
12
12
Principle on how to synchronize your registered instances creation has been rethought and improved :-)
13
13
Please see [Synchronizing asynchronous initialisations of Singletons](#synchronizing-asynchronous-initialisations-of-singletons).
14
14
15
15
## Why GetIt
16
16
17
-
When your App grows at some point you you will start to put your app's logic in classes that are separated from your Widgets and have no dependency to Flutter which makes your code better organized and easier to test and maintain.
17
+
When your App grows at some point you will start to put your app's logic in classes that are separated from your Widgets and have no dependency to Flutter which makes your code better organized and easier to test and maintain.
18
18
But now you need a way how to access these objects from your UI code. When I came to Flutter from the .Net world the only way to do this was the use of InheritedWidgets. I found the way to use them by wrapping them in a StatefulWidget quite cumbersome and had always problems getting it updating the widgets to work. Also:
19
19
20
20
* I was missing the ability to easily switch the implementation for a business object for a mocked one without changing the UI.
21
-
* The fact that you need a `BuildContext` to access your objects made it unusable to use them from inside the Business layer.
21
+
* The fact that you need a `BuildContext` to access your objects made it unusable to use them from inside the Business layer.
22
22
23
23
Accessing an object from anywhere in an App can be done by other ways too but:
24
24
@@ -47,7 +47,7 @@ final getIt = GetIt.instance;
47
47
void setup() {
48
48
getIt.registerSingleton<AppModel>(AppModel());
49
49
50
-
// Alternatively you could write it if you don't like global variables
50
+
// Alternatively you could write it if you don't like global variables
51
51
GetIt.I.registerSingleton<AppModel>(AppModel());
52
52
}
53
53
```
@@ -85,7 +85,7 @@ Through this any call to `instance` in any package of a project will get the sam
85
85
GetIt getIt = GetIt.instance;
86
86
```
87
87
88
-
> You can use any name you want which makes Brian happy like (`sl, backend, services...`) ;-)
88
+
> You can use any name you want which makes Brian happy like (`sl, backend, services...`) ;-)
89
89
90
90
Before you can access your objects you have to register them within `GetIt` typically direct in your start-up code.
91
91
@@ -125,7 +125,7 @@ var myAppModel = GetIt.I<AppModel>();
125
125
126
126
#### Factory
127
127
128
-
```Dart
128
+
```Dart
129
129
void registerFactory<T>(FactoryFunc<T> func)
130
130
```
131
131
@@ -135,7 +135,7 @@ You have to pass a factory function `func` that returns an NEW instance of an im
135
135
>Although I always would recommend using an abstract base class as registration type so that you can vary the implementations you don't have to do this. You can also register concrete types.
136
136
137
137
```Dart
138
-
void registerSingleton<T>(T instance)
138
+
void registerSingleton<T>(T instance)
139
139
```
140
140
141
141
You have to pass an instance of `T` or a derived class of `T` that you will always get returned on a call to `get<T>()`.
@@ -145,14 +145,14 @@ As creating this instance can be time consuming at app start-up you can shift th
You have to pass a factory function `func` that returns an instance of an implementation of `T`. Only the first time you call `get<T>()` this factory function will be called to create a new instance. After that you will always get the same instance returned.
150
150
151
151
152
152
153
153
### Overwriting registrations
154
154
If you try to register a type more than once you will get an assertion in debug mode because normally this is not needed and not advised and probably a bug.
155
-
If you really have to overwrite a registration, then you can by setting the property `allowReassignment==true`.
155
+
If you really have to overwrite a registration, then you can by setting the property `allowReassignment==true`.
156
156
157
157
### Testing if a Singleton is already registered
158
158
You can check if a certain Type or instance is already registered in GetIt with:
@@ -168,13 +168,13 @@ If you need to you can also unregister your registered singletons and factories
168
168
169
169
```Dart
170
170
/// Unregister a factory/ singletons by Type [T] or by name [instanceName]
171
-
/// If its a singleton/lazySingleton you can unregister an existing registered object instance
172
-
/// by passing it as [instance]. If a lazysingleton wasn't used before expect
171
+
/// If its a singleton/lazySingleton you can unregister an existing registered object instance
172
+
/// by passing it as [instance]. If a lazysingleton wasn't used before expect
173
173
/// this to throw an `ArgumentError`
174
174
/// if you need to dispose any resources you can do it using [disposingFunction] function
175
175
/// that provides a instance of your class to be disposed
Additionally you can register asynchronous Singletons which means Singletons that have an initialisation that requires async function calls. To be able to control such asynchronous start-up behaviour GetIt supports mechanisms to ensure the correct initialization sequence.
223
+
Additionally you can register asynchronous Singletons which means Singletons that have an initialisation that requires async function calls. To be able to control such asynchronous start-up behaviour GetIt supports mechanisms to ensure the correct initialization sequence.
224
224
225
-
You create an Singleton with an asynchronous creation function
225
+
You create an Singleton with an asynchronous creation function
@@ -232,7 +232,7 @@ You create an Singleton with an asynchronous creation function
232
232
```
233
233
234
234
The difference to a normal Singleton is that you don't pass an existing instance but provide an factory function
235
-
that returns a `Future` that completes at the end of `factoryFunc` and signals that the Singleton is ready to use unless `true` is passed for `signalsReady`. (see next chapter)
235
+
that returns a `Future` that completes at the end of `factoryFunc` and signals that the Singleton is ready to use unless `true` is passed for `signalsReady`. (see next chapter)
236
236
To synchronize with other "async Singletons" you can pass a list of `Type`s in `dependsOn` that have to be ready before the passed factory is executed.
237
237
238
238
There are two possible ways to signal the system that an instance is ready.
@@ -271,7 +271,7 @@ If you register any async Singletons `allReady` will complete only after all of
When using `dependsOn` you ensure that the registration waits with creating its singleton on the completion of the type defined in `dependsOn`.
318
+
When using `dependsOn` you ensure that the registration waits with creating its singleton on the completion of the type defined in `dependsOn`.
319
319
320
320
321
321
### Manually signalling the ready state of a Singleton
322
322
Sometimes the mechanism of `dependsOn` might not give you enough control. For this case you can use `isReady` to wait for a certain singelton:
323
323
324
324
```Dart
325
-
/// Returns a Future that completes if the instance of an Singleton, defined by Type [T] or
325
+
/// Returns a Future that completes if the instance of an Singleton, defined by Type [T] or
326
326
/// by name [instanceName] or by passing the an existing [instance], is ready
327
327
/// If you pass a [timeout], an [WaitingTimeOutException] will be thrown if the instance
328
-
/// is not ready in the given time. The Exception contains details on which Singletons are
328
+
/// is not ready in the given time. The Exception contains details on which Singletons are
329
329
/// not ready at that time.
330
330
/// [callee] optional parameter which makes debugging easier. Pass `this` in here.
331
331
Future<void> isReady<T>({
@@ -339,7 +339,7 @@ Sometimes the mechanism of `dependsOn` might not give you enough control. For th
339
339
To signal that it is ready a singleton can use `signalReady` to be able to use that you have to set the optional `signalsReady` parameter when registering it OR make your registration type implement the empty abstract class `WillSignalReady`. In that case `allReady` will wait on a call to signalsReady. No automatic signalling will happen in that case.
340
340
341
341
```Dart
342
-
/// Typically this is used in this way inside the registered objects init
342
+
/// Typically this is used in this way inside the registered objects init
343
343
/// method `GetIt.instance.signalReady(this);`
344
344
void signalReady(Object instance);
345
345
```
@@ -385,25 +385,25 @@ In some cases its handy if you could pass changing values to factories when call
385
385
/// [instanceName] if you provide a value here your factory gets registered with that
386
386
/// name instead of a type. This should only be necessary if you need to register more
387
387
/// than one instance of one type. Its highly not recommended
The reason why I settled to use two parameters is that I can imagine some scenarios where you might want to register a builder function for Flutter Widgets that need to get passed a `BuildContext` and some data object.
406
+
The reason why I settled to use two parameters is that I can imagine some scenarios where you might want to register a builder function for Flutter Widgets that need to get passed a `BuildContext` and some data object.
407
407
408
408
When accessing these factories you pass the parameters a optional arguments to `get()`:
409
409
@@ -457,12 +457,12 @@ If you have a mocked version of a Service you can easily switch between that and
457
457
This should only be your last resort as you can loose your type safety and lead the concept of a singleton add absurdum.
458
458
This was added following a request at https://github.com/fluttercommunity/get_it/issues/10
459
459
460
-
Ok you have been warned. All register functions have an optional named parameter `instanceName`. If you provide a value here
460
+
Ok you have been warned. All register functions have an optional named parameter `instanceName`. If you provide a value here
461
461
your factory/singleton gets registered with that name instead of a type. Consequently `get()` has also an optional parameter `instanceName` to access
462
462
factories/singletons that were registered by name.
463
463
464
-
**IMPORTANT:** Each name for registration can only used once.
465
-
Both way of registration are complete separate from each other.
464
+
**IMPORTANT:** Each name for registration can only used once.
465
+
Both way of registration are complete separate from each other.
This new instance does not share any registrations with the singleton instance
480
480
481
481
## Acknowledgements
482
-
Many thanks to the insightful discussions on the API with [Brian Egan](https://github.com/brianegan) and [Simon Lightfoot](https://github.com/slightfoot)
482
+
Many thanks to the insightful discussions on the API with [Brian Egan](https://github.com/brianegan) and [Simon Lightfoot](https://github.com/slightfoot)
0 commit comments