wiretap library

Classes

BasicToken<T>

DisposeRef

Can be used to register dispose listeners to do some clean up work. Use the disposeRef Token to inject an instance of DisposeRef.

InjectableValue<T>

A value representation eagerly instantiated at WiretapContext instantiation. A InjectableValue can and should be lazily evaluated when possible. Any InjectableValue can use the Inject instance passed to it when get is being called to derive any value from the injection context.

LazyValue<T>

Most commonly used instance of InjectableValue. Allows for specifying a factory function which is 1. evaluated lazily and 2. has access to an instance of Inject to derive any value from the injection context.

ModuleProvider<T>

ModuleProvider is a Provider that allows to declare multiple providers as a single one. This can be used for "Module" declarations.

Provider

Providers can be passed to any WiretapContext to override or initially set any value associated with an Token specified by a createToken function or any of its friends.

SingleProvider<T>

SingleProvider is the actual Provider which links a InjectableValue creation function to an token. Declaring your own SingleProvider is not necessarily expected. In most if not all cases you should be able to use the provideFoo methods like BasicToken.provideOverride to easily create a Provider instance.

StaticValue<T>

Simple InjectableValue for value instances being specified without any factory that don't need or should not be evaluated lazily. Only in use for the createValueToken function.

Token<T>

Bare bones interface to mark any value that can be injected. Its instance acts as a key for the values stored in the WiretapContext.

ValueCollection<T>

Represents an aggregate injectable value. It is iterable for easy access but its instance is not modifiable

WiretapContext

The core of inject. WiretapContext is the stateful place where every value is stored. It's inject function is expected to be passed down to the usage site to access any value held by WiretapContext.

Enums

ProviderMode

The mode in which the providers for a WiretapContext are applied. This controls ordering as well as duplication behavior.

Extensions

ValueCollectionTokenExtension on Token<ValueCollection<T>>

Adds additional provider declarations on Tokens with a generic type of ValueCollection.

Properties

disposeRef → BasicToken<DisposeRef>

Enables access to the DisposeRef of the current context.

final

Functions

createCollectionToken<T>([Factory<Iterable<T>>? factory]) → BasicToken<ValueCollection<T>>

Shorthand for creating an token with a ValueCollection generic type.

createToken<T>([Factory<T>? factory]) → BasicToken<T>

Creates an token with an optional factory as a default or fallback value.

createValueToken<T>(T value) → BasicToken<T>

Same as createToken but with a static, non dependent value.

provideExperimentalLifecycleApi() → Provider

Enables the experimental lifecycle api when passed as a provider to the WiretapContext. The lifecycle api includes DisposeRef and provideInitializer.

provideInitializer(FutureOr<void> listener(Inject inject)) → Provider

Provide an initializer function to do some setup on startup. You can call some initialization functions that should run immediatly: provideInitializer((inject) => inject(FooService).initialize())

runDisposers(Inject inject) → Future<void>

Runs the dispose listeners in parallel and throws a ParallelWaitError if any of the listeners fails.

runInitializers(Inject inject) → Future<void>

Runs the initializes in parallel and throws a ParallelWaitError if any of the initializers fails.

Typedefs

Factory<T> = T Function(Inject inject)

Function signature for factory provider. They receive an inject parameter of type Inject so that they themselves can depend on other provided values.

Inject = T Function<T>(Token<T> token)

Function signature for the inject() function. This should be the type of what is passed down to the actual usage site. Not the WiretapContext itself.

ProviderFactory<T> = InjectableValue<T> Function(InjectableValue<T>? previousValue)

Function signature for the actual provider value creation.

Exceptions / Errors

CircularDependencyError

A CircularDependencyError is being thrown when a circular dependency in the injection graph has been detected.

DuplicateOverrideError

A DuplicateOverrideError is being thrown when multiple (non modifying) providers have been registered for the same instance of WiretapContext. It would technically be possible to allow multiple overrides so that the last override actually wins and is allowed to specify the value. This behaviour is explicitly prohibited to improve injection predictability.

LifecycleManagementDisabledError

A LifecycleManagementDisabledError occurs when using a wiretap lifecycle feature without opting into it using the provideLifecycle() provider.

MissingProviderError

A MissingProviderError is being thrown when an Inject function is being called without any Provider associated with it in the WiretapContext being used. An Token with a fallback (default) value will never throw a MissingProviderError as it itself provides the value that can be injected.