DEV Community: Paul Johnson

Hacn: React components using javascript generators.

Paul Johnson — Sun, 29 Mar 2020 03:01:47 +0000

Hacn

Hacn is a "skin" over React components that provides a powerful approach to programming UI's using javascript generators. Its heavily inspired by react hooks and a concept called algebraic effects and is very similar to redux-saga.

Hacn is hard to explain, so it's easier to start with an example:

Let's say we want to show a loading element while we fetch some data. To make it look nice we don't want to show the loading element at all if the fetch is quick. We also don't want to flash the loading element on and off the screen rapidly if the data loads shortly after we start displaying the loading element.

The logic in psuedo javascript is roughly:

show(null);
const loading = fetch("https://example.org/data");

const finished_first = any(loading, timeout(100));
if (finished_first === "timeout") {
  show(<div>Loading...</div>);
  timeout(200);
  wait(loading);
}

show(<div>{loading.data}</div>);

To implement this in a react component using hooks you might do something like:

const Loading = () => {
  const [data, setData] = useState(null);
  const [show, setShow] = useState("starting");

  useEffect(() => {
    if (show === "starting") {
      fetch("https://example.org/data", (data) => {
        setData(data);
        if (show !== "loading") {
          setShow("done");
        }
      });
      setTimeout(() => {
        if (data === null) {
          setShow("loading");
          setTimeout(() => {
            if (data) {
              setShow("done");
            }
          }, 200);
        }
      }, 100);
    }
  }, [show]);

  if (show === "starting") {
    return null;
  }

  if (show === "loading") {
    return <div>Loading</div>;
  }

  return <div>{data}</div>;
};

In Hacn this becomes:

const Loading = hacn(function* (props) {
    yield _continue(null);

    const fetchEffect = yield _continue(json'https://example.org/data');

    const firstTimeout = yield _continue(timeout(100));

    let [data, _] = yield any(fetchEffect, firstTimeout);

    if (!data) {
        yield _continue(<div>Loading...</div>);
        yield timeout(200);
        data = yield suspend(fetchEffect);
    }

    return (<div>{data}</div>);
});

There's a lot going on here, but it should be obvious how Hacn transforms a complex useEffect handler into a simple linear sequence of events.

I'll explain line by line what's happening:

const Loading = hacn(function* (props) {

To create a Hacn component you pass a javascript generator to the hacn function. Generators are usually explained as a technique for looping over arrays and other structures without creating intermediate arrays. But they are much more powerful than this, you can think of them as a construct that lets you pause and save a function in the middle of it's execution so it can be restarted later. Hacn uses this to save the executing function inside the state of a regular react component and resumes it every time react renders the component.

The yield statements throughout the function return objects called 'effects'. Effects instruct Hacn on what to do e.g. fetch some data or pause execution for a period of time.

yield _continue(null);

_continue is an effect that takes another effect and carries on executing the function, often performing some action as a side effect. null and jsx tags are treated as a special case and are transformed into the render effect, which is used to render results during execution.

const fetchEffect = yield _continue(json'https://example.org/data');
const firstTimeout = yield _continue(timeout(100));

json and timeout are effects that fetch data and start a timer respectively, we wrap them in _continue, because we don't want to wait for them to complete just yet. _continue effects generally return the wrapped effect, so that we can wrap the effect again later.

let [data, _] = yield any(fetchEffect, firstTimeout);

any is an effect that stops execution and restarts once one of the effects passed to it signals to Hacn that it is complete and it should continue executing. Effects default to suspending and have to be explicitly wrapped in _continue() to make them contine.

if (!data) {
  yield _continue(<div>Loading...</div>);
  yield timeout(200);
  data = yield suspend(fetchEffect);
}

This part checks if data has not returned, renders the loading message without waiting, suspends waiting for the timeout effect to finish and then suspends on the fetchEffect that was returned from the _continue(json...) call above.

return <div>{data}</div>;

Finally we render the data.

Capturing events

Handling events also works a little bit differently from in regular react, rather than a callback you use the capture parameter to return events from a render effect:

const Capture = hacn(function* (props, capture) {
  let enteredText = "";

  while (enteredText !== "hello") {
    const changeEvent = yield (
      <div>
        {'Enter "hello":'}:
        <input
          type="text"
          name="hello"
          value={enteredText}
          // Capture the onChange event and return it.
          onChange={capture}
        />
      </div>
    );

    enteredText = changeEvent.target.value;
  }
  yield <div>hello to you to!</div>;
});

Error handling

Hacn also handles errors in component rendering by throwing them into the generator, letting you catch them using the normal javascript try/catch statements:

const ErroringComponent = (props: any) => {
  throw new Error("This component has errors");
};

const Test = hacn(function* () {
  try {
    yield <ErroringComponent />;
  } catch (e) {
    yield <div>An error occurred: {e.message}</div>;
  }
});

The Craziest Example

One problem with generators is that they don't let you jump back to an earlier part of the function execution. We can hack around this by using an obscure feature of javascript loops called 'labels'. These are effectively a restricted form of goto that allow you to break out of inner loops to outer loops.

const CrazyComponent = hacn(function* (props, capture) {
  first: do {
    let event = yield (
      <div>
        <button id="forward" onClick={capture.tag("forward")}>
          Forward
        </button>
      </div>
    );
    second: do {
      let event = yield (
        <div>
          <button id="beginning" onClick={capture.tag("beginning")}>
            Beginning
          </button>
          <button id="back" onClick={capture.tag("back")}>
            Back
          </button>
          <button id="forward" onClick={capture.tag("forward")}>
            Forward
          </button>
        </div>
      );
      if ("back" in event) {
        continue first;
      } else if ("beginning" in event) {
        continue first;
      }
      third: do {
        let event = yield (
          <div>
            <button id="beginning" onClick={capture.tag("beginning")}>
              Beginning
            </button>
            <button id="back" onClick={capture.tag("back")}>
              Back
            </button>
            <button id="forward" onClick={capture.tag("forward")}>
              Forward
            </button>
          </div>
        );
        if ("back" in event) {
          continue second;
        } else if ("beginning" in event) {
          continue first;
        }
        break first;
      } while (true);
    } while (true);
  } while (true);

  return <div id="foo">Done!</div>;
});

This is the craziest example I can come up with and should never actually be used.

Status

This is still a work in progress and there is a lot of stuff still to do, particularly around documentation and performance testing. Any feedback is welcome!

vrpc: types, services and clients for forwards and backwards compatibility.

Paul Johnson — Sun, 24 Nov 2019 01:01:32 +0000

vrpc (versioned rpc) is an idea that I've been working on for awhile, It's goal is to make it easy to build http services and clients that are simple to make backwards and forwards compatible as servers and clients evolve.

It combines two related ideas, the first is to structure type and service configuration as a log of changes rather than as a static file, kind of like a version control system. The second is to use the config log to generate a series of types and service stubs that are versioned. This makes it easy to handle backwards compatibility on the server and forward compatibility on the client.

Right now this is something I'm still working on, so the code isn't very functional, but you can see it at: https://github.com/pj/vrpc.

As an example, rather than a static definition of a type like:

type Order {
    order_id: number;
    date_created: Date;
    entries: OrderEntry[]
}

type OrderEntry {
    item_name: string;
}

The types would be defined as a log of actions:

[
    {
        "action": "Newtype", 
        "name": "Order"
    },
    {
        "action": "AddField", 
        "name": "order_id", 
        "type": "Order", 
        "dataType": "number"
    },
    {
        "action": "NewType", 
        "name": "OrderEntry"
    },
    {
        "action": "AddField", 
        "name": "item_name", 
        "type": "OrderEntry", 
        "dataType": "string"
    },
    {
        "action": "AddField", 
        "name": "entries", 
        "type": "Order", 
        "dataType": "OrderEntry", 
        "repeated": true
    }, 
    {
        "action": "AddField", 
        "name": "date_created", 
        "type": "Order", 
        "dataType": "Date"
    }
]

Which would be used to generate a series of versioned types like:

class Order_V1 {
    order_id: number;
}

class OrderEntry_V1 {
    item_name: string
}

class Order_V2 {
    order_id: number;
    entries: OrderEntry[];
}

class Order_V3 {
    order_id: number;
    entries: OrderEntry[];
    date_created: Date;
}

Since generating a new version for every small change leads to excessive new types, there's also a system to group actions:

[
    {
        "action": "Group",
        "actions": [
            {
                "action": "Newtype", 
                "name": "Order"
            },
            {
                "action": "AddField", 
                "name": "order_id", 
                "type": "Order", 
                "dataType": "number"
            },
            {
                "action": "NewType", 
                "name": "OrderEntry"
            },
            {
                "action": "AddField", 
                "name": "item_name", 
                "type": "OrderEntry", 
                "dataType": "string"
            },
            {
                "action": "AddField", 
                "name": "entries", 
                "type": "Order", 
                "dataType": "OrderEntry", 
                "repeated": true
            }, 
            {
                "action": "AddField", 
                "name": "date_created", 
                "type": "Order", 
                "dataType": "Date"
            }
        ]
    }
]

Generating:

class OrderEntry_V1 {
    item_name: string
}

class Order_V1 {
    order_id: number;
    entries: OrderEntry_V1[];
    date_created: Date;
}

This helps to enforce the versioning at the type level making it easy to understand how your interface is changing.

To prevent someone from modifying previous log entries and invalidating the versioning, the fields of every action are hashed together with the hash of the previous entry. This is similar to the way that git or blockchains work (technically a merkle tree).

Services

The log can also be used to define services, which are basically a name and a set of input and output types for the service. Right now a service can have multiple input types for a single output type, but not multiple output types for each input type.

For example:

[
  {
    "action": "NewTypeAction",
    "typeName": "Order",
  },
  {
    "action": "AddFieldTypeAction",
    "type": "Order",
    "name": "name",
    "dataType": "string",
  },
  {
    "action": "NewTypeAction",
    "type": "OrderResponse",
  },
  {
    "action": "AddFieldTypeAction",
    "type": "OrderResponse",
    "name": "friendly_greeting",
    "dataType": "string",
  },
  {
    "action": "NewServiceAction",
    "name": "OrderService",
  },
  {
    "action": "AddVersionServiceAction",
    "name": "OrderService",
    "inputType": "Order",
    "inputVersion": 1,
    "outputType": "OrderResponse",
    "outputVersion": 1
  },
  {
    "action": "AddFieldTypeAction",
    "type": "Order",
    "name": "title",
    "dataType": "string",
  },
  {
    "action": "AddVersionServiceAction",
    "name": "OrderService",
    "inputType": "Order",
    "inputVersion": 2,
    "outputType": "OrderResponse",
    "outputVersion": 1
  }
]

This would let you define services using generated stubs like so:

import {Express, express} from "express";
import {
  Order_V1,
  Order_V2,
  OrderResponse_V1
} from "./vrpc/types";
import {
  OrderService
} from "./vrpc/services";
const app = express();

OrderService(app, function (input: Order_V1 | Order_V2): OrderResponse_V1 {
    if (input instanceof Order_V1) {
        return new OrderResponse_V1(`hello ${input.name}`);
    } else {
        return new OrderResponse_V1(`hello ${input.title} ${input.name}`);
    }
});

app.listen(3000, () => console.log(`Example app listening on port 3000!`)

Why not just use git?

Partly for fun, partly for a bit more flexibility in how the log is served. For example you could host the log on an SQL server, or as part of a distributed system using something like PAXOS or raft to store and update the log.

Also it makes it easier to enforce proper use of the log, since you can have code to ensure that new entries are valid before adding them.

Status

You can see the current code at https://github.com/pj/vrpc.

Right now the code is grad student quality and was really just a test to see if I could get the concept working. There are a whole bunch of things that need to be added:

Different backends e.g. SQL.
More log validation - validate that log entries make sense.
Generate easy to use forwards compatible clients.
Handle multiple concurrent users.
Real system to submit changes to the log.
Expanded type system e.g. arrays, unions, intersections, better ways of composing types.
Caching the log and generated artifacts.

I think this approach could be generalized to most system boundaries e.g. database schemas could be defined as log entries and then rows versioned based on it. This would make it easier to ensure backwards compatibility as the database schema evolves over time, the same way it would work for service definitions.

Config logs could probably be generalised into a kind of metalog, so the schema of different types of log entries would be added to the config log itself. Validation and more complicated logic could be added as webassembly.