JoltProvider<T> class

A widget that provides reactive resource management with lifecycle callbacks.

JoltProvider allows you to create and manage resources that can implement the JoltState interface, providing automatic lifecycle management with onMount and onUnmount callbacks.

The provided resource is accessible both directly via the builder function's parameter and through BuildContext using of or maybeOf static methods. This makes it easy to access resources from descendant widgets without prop drilling.

Resource Provision

Resources can be provided in two ways:

Using create: A function that creates the resource lazily (on first access). The provider manages the resource's lifecycle and will call onUnmount and dispose the resource when it's no longer needed.
Using value: A pre-existing resource instance. When using value, the provider does not manage the resource's lifecycle (no onUnmount or dispose is called by the provider). The resource should be managed externally.

You must provide either create or value, but not both.

Lifecycle Management

When using create, if the resource implements JoltState, lifecycle callbacks are automatically invoked:

onMount is called after the resource is created and the widget is mounted
onUnmount is called when the widget is unmounted or when a new resource replaces the old one

When using value, the provider does not manage the resource's lifecycle at all:

No onMount is called
No onUnmount is called
The resource is not disposed by the provider The resource should be managed externally.

Resource Updates

When the create function changes, the new function is only used if the value hasn't been initialized yet. Once the value is created (lazily on first access), subsequent changes to the create function will be ignored. This ensures that the resource is only created once and remains stable throughout its lifetime.

When the value changes, the provider simply updates the provided resource without calling lifecycle callbacks or disposing the old resource.

Parameters

builder: Function that builds the widget tree using the provided resource. The resource is passed as the second parameter and is also accessible via JoltProvider.of or JoltProvider.maybeOf in descendant widgets.
create: Optional function to create the resource lazily (on first access). If provided, the provider manages the resource's lifecycle. Cannot be used together with value.
value: Optional pre-existing resource instance. If provided, the provider does not manage the resource's lifecycle. Cannot be used together with create.

Example

Using create to create and manage a resource:

class MyStore extends JoltState {
  final counter = Signal(0);

  @override
  void onMount(BuildContext context) {
    print('Store mounted');
  }

  @override
  void onUnmount(BuildContext context) {
    print('Store unmounted');
  }
}

JoltProvider<MyStore>(
  create: (context) => MyStore(),
  builder: (context, store) => Text('${store.counter.value}'),
)

Using value to provide an externally managed resource:

// Singleton store managed elsewhere
final globalStore = MyStore();

JoltProvider<MyStore>(
  value: globalStore,
  builder: (context, store) => Text('${store.counter.value}'),
)

Accessing the resource from a descendant widget:

Builder(
  builder: (context) {
    final store = JoltProvider.of<MyStore>(context);
    return Text('Count: ${store.counter.value}');
  },
)

Inheritance

Constructors

JoltProvider({Key? key, required Widget builder(BuildContext context, T state), T create(BuildContext context)?, T? value}): Creates a JoltProvider that creates and manages a resource.
const
JoltProvider.value({Key? key, required T? value, required Widget builder(BuildContext context, T state)}): Creates a JoltProvider that provides a pre-existing resource.
const

Properties

builder → Widget Function(BuildContext context, T state): Function that builds the widget tree using the provided resource.
final
create → T Function(BuildContext context)?: Optional function to create the resource lazily (on first access).
final
hashCode → int: The hash code for this object.
no setterinherited
key → Key?: Controls how one widget replaces another widget in the tree.
finalinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
value → T?: Optional pre-existing resource instance to provide.
final

Methods

createElement() → JoltProviderElement<T>: Inflates this configuration to a concrete instance.
override
debugDescribeChildren() → List<DiagnosticsNode>: Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void: Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode: Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String: A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String: Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String: Returns a one-line detailed description of the object.
inherited
toStringShort() → String: A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Methods

maybeOf<T>(BuildContext context) → T?: Obtains the provided resource of type T from the widget tree, if available.
of<T>(BuildContext context) → T: Obtains the provided resource of type T from the widget tree.