ww-tech / roxie

Lightweight Android library for building reactive apps.

Roxie is a lightweight Android library for building reactive apps. We successfully use it for Android product development at WW (formerly Weight Watchers).

Why Roxie?

Roxie implements Unidirectional Data Flow (UDF) concepts introduced by Redux. The core idea is that user Actions get dispatched to a Store (State container) which uses Reducers to transform them into States. In Android world, this design pattern is known as MVI (Model-View-Intent) where Model describes State and Intent describes user interaction.

Roxie is a tiny library. It is implemented using widely adopted Lifecycle Google Architecture Components and RxJava2. Hopefully, the small footprint of this library will enable you to fully understand both concepts and implementation details.

Roxie in a nutshell

The Unidirectional Data Flow with Roxie can be summarized as follows:

1. User interaction events (Actions) get dispatched to ViewModel via a single pipeline.
2. Each Action gets transformed into Changes.
3. Each Change combined with a previous State produces a new State using a Reducer.
4. UI observes new States via a single pipeline and renders them as they come in.

Some of Roxie's strengths are:

• State Machine managing immutable States makes data predictable and easier to manage.
• Support for state restoration after device rotation and process death.
• A set of Actions, Changes, and States for each screen result in a thorough user-centric design.
• Logging of Actions and States makes both debugging and crash reporting extremely efficient.
• Rich RxJava APIs help achieve composable functional code.
• Meaningful and consistent unit tests asserting that given Actions and initial State produce correct new States.

Documentation

Check out the sample bundled and wiki pages to get started. Some of the topics covered are:

• ViewModel
• Actions
• Changes
• States
• Reducer
• Rendering State
• Logging
• Process Death
• Unit Tests

Installation

Add the following Gradle dependency to your project build.gradle file:

dependencies {
    implementation 'com.ww:roxie:0.5.0'
}

License

Copyright 2019 WW International, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

roxie's Issues

Dealing with one-time effects

Here is a scenario:

Your screen supports rotation. A particular Action can generate an error which should display a Snackbar.

How do we deal with it? Emit the error State initially but not after rotation to avoid displaying the Snackbar twice? What should the State be after rotation then?

Should we introduce a concept of Effects (single event type States)?

In the spirit of Roxie's lightweight way of doing things, it would be ideal to solve this with minimal code needed by the consumer apps.

Feature: Add some sort of project scaffolding

Roxie is pretty lightweight, but I'm also lazy so having to create different files each time I start up a new screen sometimes becomes a bit of copy/paste work from other screens.

Not sure how to go about this (probably just some shell script), but most likely it would generate these initial files for us:

• Action
• Change
• State
• ViewModel
• ViewModelTest 👍 👍 👍

Possibly dagger related jazz too.

Migrate to Maven Central

Hello,
jcenter is deprecated with the following message:

'jcenter' is deprecated
Builds will no longer be able to resolve artifacts from JCenter after February 1st, 2022
JCenter Maven repository is no longer receiving updates: newer library versions may be available elsewhere

https://jfrog.com/blog/into-the-sunset-bintray-jcenter-gocenter-and-chartcenter/

It would be great to have Roxie on the Maven Central.

Question: Suggested way to deal with "external" inputs?

Hello,

Thanks for Roxie. We took inspiration from this library for coming up with our own architecture. The separation between Actions and Changes really makes the code clean.

I have a question about how you would go about reacting to external inputs? If I understand the concept correctly, Actions are always user-initiated. How about things like - say, internet connection lost/regained? How would these be modelled?

We are considering making the ViewModel or domain layers deal with such inputs and emit either an Action or a Change.

Making it an Action enables easy testing (since all you need is to create the ViewModel under test and dispatch the appropriate action). However, this Action is internal to the ViewModel and it should not be exposed to the Activity.

Making it a Change is cleaner but it makes testing more difficult.

Do you have any inputs? Beyond the practical aspects of testing, are there any philosophical aspects to think about?

RxJava3 Support

Roxie is built using RxJava2 and RxJava3 is in the works.

Things to think about:

• The operators that we currently use, are they still available? Do their behavior change?
  • If not available, what do we use instead?
  • If behavior change, does it break our implementation? What do we use instead?
• Should we provided an RxJava2 artifact? What Roxie is today.

https://github.com/ReactiveX/RxJava/releases/tag/v3.0.0-RC0

Enable obfuscating Actions and States

Sometimes it makes sense not to log details of an Action or a State (for instance when they contain sensitive user info if we log in production). Enable easy overriding of toString() in those cases.

Coroutines?

As I understand, under the hood is used RXJava, are you planning to add the ability to use coroutines?

Changes occurring independent of user interaction

Hey there, I've been reading the wiki to figure out if this library is right for me. I like the idea of mapping actions into changes and having the UI respond to state changes but I feel like the use case might be a bit narrow.

Quite often a change occurs as a result of something other than user interaction, as an example let's say my app is polling a server for live sports results, normally these changes would come through the backend of the app and update a property in the ViewModel/Presenter which the UI is observing.

Is it possible (or even necessary) to represent external events as actions and treat them the same as user interaction, especially if they aren't coming from the UI layer?

Sample with Dagger

Could you extend sample with dagger implementation?

Image link broken

The image link as Data Flow with Roxie in home is broken. It seems to omit the raw=true.