Rename Stream to Action.

[Laimiux]

I want to rename Stream to Action

• I think name is more fitting as it represents a deferred action that is executed and managed by Formula runtime.
• Renaming updates to actions will keep the naming more consistent
• Action.onInit and similar methods seems better named than Stream.onInit

Old	New
Stream	Action
RxStream	RxAction
FlowStream	FlowAction
BoundedStream	BoundedAction
Evaluation.updates	Evaluation.actions

[Laimiux]

A more elaborated documentation.

[FrancoisBlavoet]

💯 on being explicit on what the contract is here in regard to e.g. key

[Laimiux]

TODO: need to audit this and rename it.

[Laimiux]

TODO: I'd like to move this out of into an ActionBuilder

[Laimiux]

To have better naming downstream, it might be worth wrapping this into a data class?

data class Actions(val list: List<ICBoundAction<*>>)

[Laimiux]

TODO: add actions method.

[Laimiux]

TODO: renamed connection to action.

[Laimiux]

TODO: add @Deprecated

[carrotkite]

JaCoCo Code Coverage 80.64% ✅

Class	Covered	Meta	Status
com/instacart/formula/coroutines/FlowFormula	100%	0%	✅
com/instacart/formula/internal/SnapshotImpl	50%	0%	✅
com/instacart/formula/internal/FormulaManagerImpl	87%	0%	✅
com/instacart/formula/Evaluation	100%	0%	✅
com/instacart/formula/FormulaContext	58%	0%	✅
com/instacart/formula/ActionFormula	100%	0%	✅
com/instacart/formula/StreamFormula	100%	0%	✅
com/instacart/formula/ActionBuilder	100%	0%	✅

Generated by 🚫 Danger

[Laimiux]

Also, a good name could be DeferredAction.

[Laimiux]

TODO: rename this class to ActionManager

[johnwilde]

Just a few nits on doc syntax

[FrancoisBlavoet]

commenting so it disappears from my github PR list, happy to review it when it is updated

[FrancoisBlavoet]

💯 on being explicit on what the contract is here in regard to e.g. key

[Laimiux]

This reads better to me than fetchUserStream

[Laimiux]

Copy pasted from RxStream with documentation changes.

[Laimiux]

Copy pasted from Stream with big documentation changes

[johnwilde]

Still see Stream in the docs below. Intentional?

[Laimiux]

Good catch, updated

[Laimiux]

Copy pasted from StreamFormula

[Laimiux]

Maybe this should be buildActions?

[Jawnnypoo]

Maybe onEvent could instead be onAction with this name change? Just a thought

[FrancoisBlavoet]

Maybe onEvent could instead be onAction with this name change? Just a thought

what we get in "onEvent" is the result of the action though, unless I am very confused about the direction of this change, that would still be an event to me (or another "not action" naming),

[johnwilde]

Should this still be streams to keep with Rx terminology?

[mattkranzler5]

@Laimiux Just spitballing here but I'm wondering if Event makes more sense than Action. The callbacks which were renamed to onEvent() indicate to me that it's in response to a single Event where as the Stream concept is in response to handling multiple Events. This semantically to me looks more correct:

context.events {
    Events.fromData(...).onEvent {
        ...
    }
    Events.fromObservable(...).onEvent {
        ...
    }
    Events.fromFlow(...).onEvent {
        ...
    }
}

Thoughts?

[Laimiux]

Maybe onEvent could instead be onAction with this name change? Just a thought

what we get in "onEvent" is the result of the action though, unless I am very confused about the direction of this change, that would still be an event to me (or another "not action" naming),

That's correct, for example readUserFromDatabase is an action which then emits an event with user state. So, onEvent handles events emitted by the action.

Just spitballing here but I'm wondering if Event makes more sense than Action...

@mattkranzler5 I guess in my mind event is something that an action can produce/emit. For example, you can have an action which saves data to the backend and emits an event of success/failure status.

RxAction.fromObservable { userRepo.updateEmail(state.newEmail) }.onEvent { status ->
  when (status) {
     SUCCESS -> transition { toastManager.showToast("Email updated!") }
     ERROR -> transition { toastManager.showToast("Email failed to update") }
  }
}

[mattkranzler5]

I guess in my mind event is something that an action can produce/emit. For example, you can have an action which saves data to the backend and emits an event of success/failure status.

@Laimiux the way I read the above is that something from an Observable is going to produce RxActions. I think it also is a bit confusing for the Action.onData(...).onEvent {...} syntax. Action implies that anything passed into the builder will be an "Action" which can be a bit ambiguous. Whereas I feel like using Event implies whatever is passed into the builder will create Events. By consolidating to Event for both single use callbacks & emissions from a stream I think it could help with some of the naming complexity.

[johnwilde]

By consolidating to Event for both single use callbacks & emissions from a stream I think it could help with some of the naming complexity.

I like the idea of simplifying naming but I'd worry in this case that using the same term to refer to the callback and the emission would lead to more confusion. One downside to the rename is that in my mind Stream implied that it produced emissions whereas Action doesn't intuitively do that. However, I think I'll get used to it.

[Laimiux]

I guess in my mind event is something that an action can produce/emit. For example, you can have an action which saves data to the backend and emits an event of success/failure status.

@Laimiux the way I read the above is that something from an Observable is going to produce RxActions. I think it also is a bit confusing for the Action.onData(...).onEvent {...} syntax. Action implies that anything passed into the builder will be an "Action" which can be a bit ambiguous. Whereas I feel like using Event implies whatever is passed into the builder will create Events. By consolidating to Event for both single use callbacks & emissions from a stream I think it could help with some of the naming complexity.

With RxAction.fromObservable we are creating a deferred action which will subscribe to an observable and emits events from it. In the above example, it subscribes to an observable which updates the email and emits modification status. I'm hesitant to unify Action and Event together because I see them as distinct things. Event being a notification/message/callback and action being a mechanism that does something (producing event being one of type of action). For example

• Event<Event> would need to be Event<Data> or Event<T>
• Callback definitions currently are (Event) -> Unit which will clash with the Event type.

I do agree that Action.onInit and Action.onData could have a better name. I would even think that maybe they should be

Action.perform { analytics.trackPageOpened() }
Action.perform(key = data) { analytics.trackDataChanged(data) }
Action.performOnTermination() { analytics.trackPageClosed() }
Action.emit(data).onEvent { 
  // if you need to do a state change when data changes 
  transition()
}

But, I think this is a bigger change that needs to be thought through more (around the API and consistency).

[mattkranzler5]

• Event would need to be Event or Event
• Callback definitions currently are (Event) -> Unit which will clash with the Event type.

I was thinking that Stream<Event> would become Events<Event> or Events<Type> and then the other "adapters" (RxStream, FlowStream could just become extension functions on Events so you could have something like:

Events.fromValue(...) {}
Events.fromObservable(...) {}
Events.fromFlow(...) {}

The naming makes more sense to me but I'll get used to whatever we decide.