flow

Name UI states, navigate between them, remember where you've been.

2,786

241

2,786

View on GitHub View on NPM

Top Related Projects

RxJava

47,834

RxJava – Reactive Extensions for the JVM – a library for composing asynchronous and event-based programs using observable sequences for the Java VM.

akka

13,024

Build highly concurrent, distributed, and resilient message-driven applications on the JVM

reactor-core

4,914

Non-Blocking Reactive Foundation for the JVM

Quick Overview

Flow is a static type checker for JavaScript developed by Facebook. It aims to find type errors in JavaScript code and can be used to add static typing to JavaScript projects, improving code quality and developer productivity.

Pros

Improves code reliability by catching type-related errors early in development
Enhances code readability and maintainability with type annotations
Provides intelligent autocompletion and refactoring support in compatible IDEs
Allows gradual adoption, enabling developers to add types incrementally

Cons

Requires additional setup and configuration compared to vanilla JavaScript
Learning curve for developers new to static typing in JavaScript
May introduce some overhead in the development process
Not as widely adopted as TypeScript, potentially limiting community support

Code Examples

Basic type annotation:

// @flow
function add(a: number, b: number): number {
  return a + b;
}

Using Maybe type for optional values:

// @flow
function greet(name: ?string): string {
  if (name) {
    return `Hello, ${name}!`;
  }
  return "Hello, stranger!";
}

Working with object types:

// @flow
type Person = {
  name: string,
  age: number,
};

function printPerson(person: Person): void {
  console.log(`${person.name} is ${person.age} years old.`);
}

Getting Started

Install Flow:

npm install --save-dev flow-bin

Initialize Flow in your project:

npx flow init

Add // @flow to the top of files you want to check.
Run Flow:

npx flow

(Optional) Add a script to your package.json:

{
  "scripts": {
    "flow": "flow"
  }
}

Now you can run Flow with npm run flow.

Competitor Comparisons

RxJava

47,834

RxJava – Reactive Extensions for the JVM – a library for composing asynchronous and event-based programs using observable sequences for the Java VM.

Pros of RxJava

More comprehensive and feature-rich, offering a wide range of operators for complex reactive programming
Better suited for handling asynchronous data streams and event-based programming
Extensive documentation and large community support

Cons of RxJava

Steeper learning curve due to its complexity and vast API
Can lead to overengineering for simpler use cases
Potential performance overhead for basic operations

Code Comparison

Flow:

class MyPresenter extends Presenter {
  @Override protected void onLoad(Bundle savedInstanceState) {
    // Handle view logic
  }
}

RxJava:

Observable.just("data")
    .map(s -> s.toUpperCase())
    .subscribe(result -> {
        // Handle result
    });

Key Differences

Flow focuses on managing the lifecycle of Android UI components, while RxJava is a general-purpose reactive programming library
Flow is more lightweight and specific to Android, whereas RxJava can be used in various Java environments
RxJava provides more powerful tools for composing and transforming asynchronous data streams

Use Cases

Flow: Ideal for simple Android apps with straightforward UI logic
RxJava: Better suited for complex applications with multiple data sources, event streams, and advanced concurrency requirements

akka

13,024

Build highly concurrent, distributed, and resilient message-driven applications on the JVM

Pros of Akka

More comprehensive actor-based concurrency model
Supports distributed systems and clustering out of the box
Offers a wider range of features for building reactive systems

Cons of Akka

Steeper learning curve due to its complexity
Requires more boilerplate code for simple use cases
JVM-based, limiting its use to JVM languages

Code Comparison

Akka (Scala):

class MyActor extends Actor {
  def receive = {
    case "hello" => println("Hello, world!")
    case _       => println("Unknown message")
  }
}

Flow (Kotlin):

class MyFlow : Flow {
  @Observe(on = "hello")
  fun sayHello() {
    println("Hello, world!")
  }
}

Summary

Akka is a more powerful and feature-rich framework for building distributed and concurrent systems, while Flow focuses on simplicity and ease of use for Android development. Akka offers a comprehensive actor model and supports clustering, making it suitable for complex, distributed applications. However, it has a steeper learning curve and requires more setup.

Flow, on the other hand, provides a simpler API for managing asynchronous operations and data streams in Android apps. It's more lightweight and easier to integrate into existing Android projects, but lacks the advanced features and scalability of Akka.

Choose Akka for complex, distributed systems, and Flow for Android-specific reactive programming needs.

reactor-core

4,914

Non-Blocking Reactive Foundation for the JVM

Pros of Reactor Core

More comprehensive and feature-rich reactive programming library
Better integration with Spring ecosystem and other reactive frameworks
Supports backpressure handling out of the box

Cons of Reactor Core

Steeper learning curve due to more complex API
Potentially higher overhead for simpler use cases
Less focus on Android-specific optimizations

Code Comparison

Reactor Core:

Flux.range(1, 5)
    .map(i -> i * 2)
    .subscribe(System.out::println);

Flow:

Flow.range(1, 5)
    .map(i -> i * 2)
    .subscribe(System.out::println);

Both libraries provide similar basic functionality for creating and manipulating reactive streams. However, Reactor Core offers more advanced operators and features for complex scenarios, while Flow focuses on simplicity and Android compatibility.

Reactor Core is better suited for server-side applications and complex reactive systems, especially within the Spring ecosystem. Flow, on the other hand, is more appropriate for Android development and simpler reactive programming needs.

The choice between the two depends on the specific requirements of your project, target platform, and desired level of complexity in your reactive programming implementation.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Deprecated

Flow had a good run and served us well, but new use is strongly discouraged. The app suite at Square that drove its creation is in the process of replacing Flow with Square Workflow.

Flow

"Name-giving will be the foundation of our science." — Linnaeus

"The winds and waves are always on the side of the ablest navigators." — Gibbon

"Memory is the treasury and guardian of all things." — Cicero

Flow gives names to your Activity's UI states, navigates between them, and remembers where it's been.

Features

Navigate between UI states. Support the back button easily without confusing your users with surprising results.

Remember the UI state, and its history, as you navigate and across configuration changes and process death.

Manage resources with set-up/tear-down hooks invoked for each UI state. UI states can easily share resources, and they'll be disposed when no longer needed.

Manage all types of UIs-- complex master-detail views, multiple layers, and window-based dialogs are all simple to manage.

Using Flow

Gradle:

compile 'com.squareup.flow:flow:1.0.0-alpha3'

Install Flow into your Activity:

public class MainActivity {
  @Override protected void attachBaseContext(Context baseContext) {
    baseContext = Flow.configure(baseContext, this).install();
    super.attachBaseContext(baseContext);
  }
}

By default, Flow will take over your Activity's content view. When you start your Activity, you should see a "Hello world" screen. Of course you'll want to change this-- that's covered under Controlling UI below.

Defining UI states with key objects

Your Activity's UI states are represented in Flow by Objects, which Flow refers to as "keys". Keys are typically value objects with just enough information to identify a discrete UI state.

Flow relies on a key's equals and hashCode methods for its identity. Keys should be immutable-- that is, their equals and hashCode methods should always behave the same.

To give an idea of what keys might look like, here are some examples:

public enum TabKey {
  TIMELINE,
  NOTIFICATIONS,
  PROFILE
}

public final class HomeKey extends flow.ClassKey {
}

public final class ArticleKey {
  public final String articleId;

  public ArticleKey(String articleId) {
    this.articleId = articleId;
  }

  public boolean equals(Object o) {
    return o instanceof ArticleKey
        && articleId.equals(((ArticleKey) o).articleId);
  }
  
  public int hashCode() {
    return articleId.hashCode();
  }
}

See the Sample Projects below for more example keys.

Navigation and History

Flow offers simple commands for navigating within your app.

Flow#goBack() -- Goes back to the previous key. Think "back button".

Flow#set(key) -- Goes to the requested key. Goes back or forward depending on whether the key is already in the History.

Flow also lets you rewrite history safely and easily.

Flow#setHistory(history, direction) -- Change history to whatever you want.

See the Flow class for other convenient operators.

As you navigate the app, Flow keeps track of where you've been. And Flow makes it easy to save view state (and any other state you wish) so that when your users go back to a place they've been before, it's just as they left it.

Controlling UI

Navigation only counts if it changes UI state. Because every app has different needs, Flow lets you plug in your own logic for responding to navigation and updating your UI.

See the Basic Sample, Tree Sample, and MultiKey Sample below for examples.

Managing resources

Your app requires different resources when it's in different states; sometimes those resources are shared between states. Flow makes it easy to associate resources with keys so they're set up when needed and torn down (only) when they're not anymore.

See the Tree Sample for an example.

Surviving configuration changes and process death

Android is a hostile environment. One of its greatest challenges is that your Activity or even your process can be destroyed and recreated under a variety of circumstances. Flow makes it easy to weather the storm, by automatically remembering your app's state and its history.

You supply the serialization for your keys, and Flow does the rest. Flow automatically saves and restores your History (including any state you've saved), taking care of all of the Android lifecycle events so you don't have to worry about them.

Sample projects

Hello World - A starting point for integration.
Basic Sample - Fully configured Flow.
Tree Sample - Uses TreeKeys to define scopes and share state.
MultiKey Sample - Uses MultiKeys to represent screens with dialogs as discrete states.

License

Copyright 2013 Square, 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.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot