primitives library

Contains fundamental primitives and change notification types used throughout the extensions package.

This library provides isolated types that are shared across multiple components, inspired by Microsoft.Extensions.Primitives.

Change Tokens

A change token signals that something it watches has changed:

final source = CancellationTokenSource();
final changeToken = CancellationChangeToken(source.token);

changeToken.registerChangeCallback(
  (state) => print('callback fired with state: $state'),
  'cancelled',
);

print('hasChanged before cancel: ${changeToken.hasChanged}');
source.cancel();
print('hasChanged after cancel: ${changeToken.hasChanged}');

Treat several tokens as one with CompositeChangeToken:

final first = CancellationTokenSource();
final second = CancellationTokenSource();

// The composite reports a change as soon as *any* member changes.
final composite = CompositeChangeToken([
  CancellationChangeToken(first.token),
  CancellationChangeToken(second.token),
]);

print('hasChanged initially: ${composite.hasChanged}');
second.cancel();
print('hasChanged after one member fired: ${composite.hasChanged}');

Change Token Patterns

ChangeToken.onChange re-registers after every change, so one registration survives repeated reloads:

// The producer is called again after each change, so a single registration
// survives repeated reloads — the pattern configuration reload uses.
var generation = 0;
var source = CancellationTokenSource();

final registration = ChangeToken.onChange(
  () {
    generation++;
    return CancellationChangeToken(source.token);
  },
  () => print('configuration reloaded (generation $generation)'),
);

final previous = source;
source = CancellationTokenSource();
previous.cancel();

registration.dispose();

Validation

Use validation results for options validation:

ValidationResult.success();
ValidationResult.fail('Invalid value');

Classes

CancellationChangeToken

A ChangeToken implementation using CancellationToken.

ChangeToken

Propagates notifications that a change has occurred.

CompositeChangeToken

An ChangeToken which represents one or more ChangeToken instances.

ValidationResult

Typedefs

ChangeCallback = void Function(Object? state)

Callback signature for change notifications.

ChangeTokenConsumer = void Function()

Action called when the token changes.

ChangeTokenProducer = ChangeToken? Function()

Produces the change token.

ChangeTokenTypedConsumer<TState> = void Function(TState? state)

Action called when the token changes with state.

VoidCallback = void Function()

Exceptions / Errors

AggregateException

Represents one or more errors that occur during application execution.