lovecommunity/love.dart

A state management library that is declarative, predictable and elegant.

love.dart's Issues

refactor - rename parameter `skipFirst*` to `skipInitial*`

We are trying to improve code readbility by rename parameter skipFirst* to skipInitail*:

before:

    .reactState(
      skipFirstState: true,
      effect: (state, dispatch) { ... },
    )

after:

    .reactState(
      skipInitialState: true,
      effect: (state, dispatch) { ... },
    )

Related Operators:

• system.react
• system.reactLatest
• system.reactState

refactor - extract `Equals<T>` to another library

Breaking

no

Description

We suggest extract Equals<T> to another library typedef_equals, so that other libraies can use and share Equals<T> type.

docs - improve the accuracy of docs

tasks:

• fix typos
• remove unused operators
• add miyoyo to thanks

break - refactor - rename `Dispose` to `Disposer`

Current type Dispose defined in love has name conflict with Dispose defined in Provider:
https://pub.dev/documentation/provider/6.0.0/provider/Dispose.html

Although we can use import ** as p; to resolve conflict, but do it with high rate is tedious. We suggest to rename Dispose to Disposer instead:

- typedef Dispose = void Function();
+ typedef Disposer = void Function();

test - increase code coverage percent

test - increase code coverage percent

refactor - change operator `system.react*` parameter `skipFisrt*` default to true

Since operator system.react* parameter skipFisrt* is often passed with true from the call side, we'd better default this parameter to true (previously is false).

Related Operators:

• reactState
• react
• reactLatest

docs - add instruction about package `flutter_love_provider`

docs - adds instruction about package flutter_love_provider

refactor - rename `areEqual` to `equals` to be consistent with dart

Dart language prefers equals to describe equality:
https://pub.dev/documentation/collection/latest/collection/Equality/equals.html

We are planing to make these changes for consistency:

- typedef AreEqual<T> = bool Function(T it1, T it2);
+ typedef Equals<T> = bool Function(T it1, T it2);

System<State, Event> reactState({
- AreEqual<State>? areEqual,
+ Equals<State>? equals, 
  bool skipInitialState = true,
  required void Function(State state, Dispatch<Event> dispatch) effect,
}) { ... }

break - refactor - rename extension names to have a `x` suffix

As x stands for Extension, for example Rx is short for ReactiveExtension.

We suggest to naming extension with a x suffix:

- extension LogOperators<State, Event> on System<State, Event> { ... }
+ extension LogX<State, Event> on System<State, Event> { ... }

- extension ReactOperators<State, Event> on System<State, Event> { ... }
+ extension ReactX<State, Event> on System<State, Event> { ... }

...
- export 'src/systems/log_on_system.dart';
+ export 'src/systems/log_x.dart';

- export 'src/systems/react_on_system.dart';
+ export 'src/systems/react_x.dart';
...

It's easy to read and write.

docs - improve API documentation

Current API documentation is too simple, we may need a detailed API documentation.

• system.dart
• on_x.dart
• react_x.dart

feature - add `system.log` operator for debug

issued from discussion #76.

Before

We have explained how to add log effect from docs:

  system
    .add(effect: (state, oldState, event, dispatch) {
      print('\nEvent: $event');
      print('State: $state');
      print('OldState: $oldState');
    })

output:

Event: null
State: 0
OldState: null

Event: Instance of 'CounterEventIncrease'
State: 1
OldState: 0

After:

We are proposal to add built in log operator:

  system
-    .add(effect: (state, oldState, event, dispatch) {
-      print('\nEvent: $event');
-      print('State: $state');
-      print('OldState: $oldState');
-    })
+   .log()

Output:

System<int, CounterEvent> Run
System<int, CounterEvent> Update {
  event: null
  oldState: null
  state: 0
}
System<int, CounterEvent> Update {
  event: Instance of 'CounterEventIncrease'
  oldState: 0
  state: 1
}
System<int, CounterEvent> Stop

It not only log when system update state, but also log when systen run and dispose which maybe useful for debugging.

This log operator will provide configuration for customization like this:

  system
    .log(
      onRun: (initialState) {
        customLogger.log('CounterSystem run');
      },
      onUpdate: (state, oldState, event) {
        customLogger.log('CounterSystem update state: $state');
      },
      onDispose: () {
        customLogger.log('CounterSystem dispose');
      },
    )

This will override default log behavior with our custom implementation.

We are trying to design this operator with a simple and flexible API.

docs - improve API documentation for `systems/react_x.dart`

docs - improve API documentation for systems/react_x.dart

docs - improve API documentation for `systems/on_x.dart`

docs - improve API documentation for systems/on_x.dart

docs - improve API documentation for `system.dart`

docs - improve API documentation for system.dart

release v0.1.0

release v0.1.0

release v0.1.2

release v0.1.2

feature - add `system.eventInterceptor` operator to intercept event

This issue is an extension to #84 (add event filter operators).
We are proposal to add low level system.eventInterceptor operaror, this operator can be used to support system.ignoreEvent and system.debounceOn operators as metioned in #84,

Here is initial imaging of low level system.eventInterceptor. The key point for this operator is, we are associating a Context with it:

  system
    .eventInterceptor<SomeContext>(
      createContext: () => ...// create context here,
      updateContext: (context, state, oldState, event, dispatch) {
          // update context here if needed.
      },
      interceptor: (context, dispatch, event) {
         // inercept event base on the context,
         // call `dispatch(event);` if we pass the event,
         // don't call `dispatch(event);` if we ignore the event.
      },
      dispose: (context) {
         // dispose the context if needed.
      }
    );
  }

With this low level operator, we can implement high level operator system.ignoreEvent like this:

class _IgnoreEventContext<State> {
  late State state;
}

extension FilterEventOperators<State, Event> on System<State, Event> {

  ...

  System<State, Event> ignoreEvent({
    required bool Function(State state, Event event) when
  }) {
    final test = when;
    return eventInterceptor<_IgnoreEventContext<State>>( //  <-- call `this.eventInterceptor`
      createContext: () => _IgnoreEventContext(),
      updateContext: (context, state, oldState, event, dispatch) {
        context.state = state; // cache current state in context
      },
      interceptor: (context, dispatch, event) {
        final _shouldIgnoreEvent = test(context.state, event);
        if (_shouldIgnoreEvent) return;
        dispatch(event);
      },
    );
  }
}

Usage of system.ignoreEvent:

  futureSystem
    ...
    .ignoreEvent(
      when: (state, event) => event is TriggerLoadData && state.loading
    ) 
    ...

Above code shown if the system is already in loading status, then upcoming TriggerLoadData event will be ignored.

We can treat system.ignoreEvent as a special case of system.eventInterceptor,
As an analogy, if we say system.ignoreEvent is a sqare, then system.eventInterceptor is a rectangle.

feature - add event filter operators like `system.ignoreEvent`, `system.debounceOn`

We are proposal to add event filter operators. these operators can prevent unnecessary event dispatching. Here is initial imaging of these operators, it may change before we implementing them, but we issued the demand first:

• system.ignoreEvent - ignore candidate event when it met some condition
• system.debounceOn - apply debounce logic to some events

system.ignoreEvent

Ignore candidate event when it met some condition.

Usage:

  futureSystem
    ...
    .ignoreEvent(
      when: (state, event) => event is TriggerLoadData && state.loading // ignore trigger if already loading
    ) 
    ...

Above code shown if the system is already in loading status, then upcoming TriggerLoadData event will be ignored.
This operator will intercept event if some condition is met based on current state and the candidate event.

system.debounceOn

Apply debounce logic to some events

Usage:

  searchSystem
    ...
    .on<UpdateKeyword>(
      reduce: (state, event) => state.copyWith(keyword: event.keyword)
    )
    .debounceOn<UpdateKeyword>(duration: const Duration(seconds: 1))
    ...

Above code shown if UpdateKeyword event is dispatched with high frequency (quick typing), system will intercept these events to reduce unnecessary dispatching, it will pass (not inercept) event if 1 seconds has passed without dispatch another UpdateKeyword event.