Forem: craig martin

A High Level Introduction to Machine Learning

craig martin — Mon, 16 Dec 2019 14:12:10 +0000

The goal of this article is to explain at a high level the concept of machine learning. We'll say nothing about implementation details.

Lets say my name is Tom, and I start a car insurance company with 50 customers. We'll pretend this number is normal for car insurance companies.

Year 1

A Simple Average Across the Board

I charge all 50 customers an average amount. Things are going well. We lose a customer every once in a while. But that's normal. We gain one, too, every once in a while. However, over the course of the year we're becoming less and less profitable!

I look at the data and realize that our best customers (the ones that very rarely get into accidents) are the ones that are leaving, and the customers that are staying (and our new ones) are bad customers (ones that get into accidents alot!) Yikes! Other insurance companies must have some rubric for recognizing good customers, and be luring away our good customers with a better-than-average price.

Year 2

Introducing My Pre-Conceived Stereotypes

I gather all the information we know about our customers (age, type of car, city) and make a chart.

Age	Car Type	City
25	2008 Honda Civic	Nashville
65	2018 Toyota Prius	Brentwood
45	2001 Ford Torus	Coopertown
...

I think to myself: young drivers and older drivers are probably more likely to get into accidents; people living in cities probably are more likely too. And I change our prices accordingly.

Year 3

Single-purpose Input Data and Result-based Human Learning

Things have actually gotten worse. Most surprisingly, this was driven by two "bad" customers leaving, and two "good" customers joining.

I realize my conception about drivers is not accurate, and it's costing me. I realize I must use actual results data (accidents) to derive my conception of a good/bad customers. However, even my inputs have implicit connotations. I make a new chart with fine-tuned inputs conveying exactly one thing (no secret (secondary) connotations), and add the result data as the final column.

Here is my new table I'll use to inform my learning:

Driver Age	Car Age	Car Self Stop	Car Blindspot Detection	City Density (population per sq mile)	Number of Accidents
25	11	no	yes	80,000	1
65	1	yes	yes	20,000	0
45	18	no	no	10,000	1
...

Using result data, I can start to see trends: car safety features matter a lot, age is a mixed bag, city density seems to matter... I adjust prices accordingly.

Year 4

Getting Better Data for my Human Learning

Things have started to get better! Every few months I look at the data again (with updated results / new drivers) and immensely enjoy looking for the thread that connects good drivers vs bad drivers. To my frustration, though, I keep bumping up against a limit - insufficient data. Not results data, but input data. I'll be finding a nice thread, only to see it disappear for some reason that isn't on my chart. Age for example. There are cases where it is the only factor to explain higher percentages of accidents, but there are other cases where it seems to be a non-factor. I am missing some other data input that would account for this. Maybe old age is a factor but only for those driving at night a lot.. I am obsessed with finding the thread, and learn about hardware customers can put in their car so that I can gather data about their actual driving behavior! I immediately offer 10% for drivers who install it.

A month later I get the first data dump, and it is like Christmas morning!! I have average data into: speed, acceleration from stop, deceleration to stop, music level, percentage of times blinker applied when turning, percentage of time driving with headlights on.

I add these attributes to my data:

Driver Age	Car Age	Car Self Stop	Car Blindspot Detection	City Density (population per sq mile)	Avg. Speed	Avg. Accel	Avg. Decel	Avg. Music Level	Pct. Blinker When Turning	Pct. Headlights	Number of Accidents
25	11	no	yes	80,000	25	1.4	1.2	40	88	22	1
65	1	yes	yes	20,000	45	.8	1.9	30	92	2	0
45	18	no	no	10,000	55	1	1	32	97	30	1
...

Wow! I spend days and days in my office trying to find the thread... elderly who drive at night a lot and decelerate quickly, young who have loud music and don't use their blinkers when turning... these make sense in my mind (perhaps vision problems and distraction, respectively). But it bothers me that while it is a very strong indicator, there are notable exceptions for each case. Using the previous data, there was a weak indication with many outliers. Now it is a stronger indication (75%!), and with less outliers, but it feels like I'm missing a third or even fourth or fifth factor for each of these cases!

Year 5

The Crossroads

My company is doing great again, even with a model that is not as accurate as I want it to be. But I find myself at a cross-roads. I've learned of two paths I could go down.

The first approach would be to create a feedback mechanism into the car hardware. Based on the learnings from my data, I can have the hardware "beep" at the driver to indicate they are in a bad situation. For example, the young driver can have loud music (23%), or occasionally miss applying a blinker (31%), but if both (75%) it crosses my chosen 70% threshold, and will beep. It seems like this would help drivers be safer, and turn bad drivers into good ones! This would help our company!

The second approach is to apply Machine Learning to the data. With machine learning, an algorithm would look at the data inputs and result (accidents) and itself decide what inputs (by themselves, but more likely coupled with any number of other inputs) are factors. I read that whereas humans have a difficult time finding deeply-nested related factors, machines can do this easily. The tradeoff of this approach, is that I no longer know which inputs are the ones which result in the projected output - and even if I did, it might be so intertwined and nuanced (maybe even touching every input under different circumstance) - that I can not have the hardware "beep" at the driver: it'd be far too nuanced for a human to backward derive from a simple "beep".

I've seen so much promise with my Human Learning model, that I decide to go the second path and see if a machine can push it further.

Year 6

Machine Learning

I spend some time "normalizing" my inputs for machine learning. I already have each input expressing only one thing, but now need to adjust all values to be values between 0 and 1.

const normalize = (val, min, max) => (val - min) / (max - min);

I assume a min/max based on the data I have, not theoretical. (EG, min age is 25, max is 65). For any new data I get, everything is recomputed anyway.

Driver Age	Car Age	Car Self Stop	Car Blindspot Detection	City Density (population per sq mile)	Avg. Speed	Avg. Accel	Avg. Decel	Avg. Music Level	Pct. Blinker When Turning	Pct. Headlights	Number of Accidents
0	.6	0	1	1	0	1	.2	1	0	.7	1
1	0	1	1	.1	.7	0	1	0	.4	0	0
.5	1	0	0	0	1	.3	0	.2	1	1	1
...

I am curious how the machine does! So, like before, I omit one record at random, perform the learning (machine instead of my own), and check the one omitted record. The record has an accident, and the machine correctly projects it! I do this over and over, and find that it has a 92% correct projection! Not just under a favorite situation (my "old age" logic accounting for elderly drivers at night was 85% - but that was my cherry-picked best scenario!) but as an average across any driver data.

I am incredulous, and spend the year changing my business model.

Year 6

Use Machine Learning to Upset the Market

I create hardware similar to the data-gathering hardware I used before, but which transmits the data in real time to our servers. Customers pay based on their real time risk. There is no 6 month plans or contracts of any type. We don't run any background information or offer any pre-set pricing. You incur cost as you drive, commensurate with your real-time driving behavior.

By year end, we upset the coverage industry and have almost half the market. The following year we eat the whole pie.

Reflections from the Caymans

As I sip a Mojito, retired on a beach, I think back through my years.

My first year neglected that patterns exist: I charged every driver the same.

The next few years I struggled to identify the patterns.

The final years I realized the futility of the human mind to maintain large number of interconnected factors (A if a lot of B and no C, coupled with D if alot of A otherwise E, negated if F, always disregarding the popular G as a red herring, etc, etc). Human minds cannot handle many factors; machines can; and so I had machines making these decisions.

I think to myself how cruel the human condition: receiving an overload of inputs in life, and not having the mechanism to correctly understand the true patterns. How thousands of years of history have seen humans erecting systems of understandings based on low-hanging fruit, not deep and nuanced learnings, that unfairly classifies and discriminates - that mistakes the important issues (and solutions) for popular red herrings. How stereotypes exist as the reduction of the true number of factors constituting a realty.

But what do I know, I'm just a car insurance guy drunk on a beach.

Hooks for those who know React

craig martin — Tue, 12 Nov 2019 15:01:43 +0000

Hooks are not a new concept in React - they are a re-implementation (a new API) for state and side effects in React that better aligns with two existing concepts in react: the concept of Components as the primitive model for UIs, and of these components being declarative.

Let's look at the concept of Components as the UI Primitives first. Before hooks, Components are a mental idea that don't map directly to either of the two existing implementations: the class-based or function-based. While the mental model was right, the implementation was forced. And so you’d have to sometimes switch between them.

What’s going on is there is a missing primitive for components: a single Component implementation which is like stateful functions with effects - and that is what hooks enable.

Before looking at how Hooks solves for this, let’s look at the other concept hooks are better aligned with: Using declarative code to make components easier to reason about.

React components have always allowed declarative code to be mapped to an imperative DOM. In the case of functional components, this declarative approach included not just the render, but the whole component (b/c the whole component was just a render): a mapping of data to an object describing the UI. React would take this object and surgically (imperatively) update the DOM.

However, if a component needed local state or side-effects - it had to be implemented as a class components. And while the render function was still declarative, the class instance itself (where the state lived and side-effects were managed) was mutable. State and side-effects were tied to a mutating instance, which made them harder to reason about.

The react team wanted the single missing component primitive to itself be declarative (as functional components were), even when it included state and side-effects.

Hooks provide for this missing component primitive. They allow components to be truly declarative even if they contain state and side-effects. They are a re-conception and re-implemenation of state and side-effects in React - an implementation instead of in class components, is in functional components making use of "hooks".

"Ok, Yeah, cool, whatever.. So what are hooks?"

Hooks are functions used with functional components that let you "hook into" React state and perform side-effects (as previously done with lifecycle hooks).

React provides built-in Hooks, and these can even be used to build more advanced custom hooks.

By convention hook functions are prefixed with “use”.

While hooks are “just functions”, they are not your father’s functions... They do not behave like normal functions. We'll come back to that.

The `useState` hook for managing local state

Rather than the state living on a mutable this instance of the component (this.state and this.setState), state is declaratively retrieved from the useState hook.

State is now retrieved and set declaratively without mutating the structure of the component (ie as the class instance would be).

The highlighted line shows the useState hook. The value passed is the initial value. The hook returns an array for two items, state and a setter for that state, and we destructure them to variables count and setCount.

The `useEffect` hook for managing side-effects

Rather than side-effects being aligned with the component's mutation (componentDidMount, componentDidUpdate, componentWillUnmount), they are now declaratively aligned with state using the useEffect hook.

useEffect orients the side effect (and it’s clean-up) with the state, rather than component’s mutation.

The highlighted line shows the useEffect hook. We pass in a function that performs some side-effect, and the state that that effect is coupled with. Whenever that state changes, the effect function is run.

"But hold on.. WTF.. wouldn't these hooks be reset every render?"

"The hooks are created inside the functional component which are called for every render. Looking back up at the useState example, wouldn't const [count, setCount] = useState(0); be called every render and keep reseting the count to the initial value of 0?"

It would seem that way, if useState was a typical function - but it's not. Hooks are impure* functions - but that impurity is an implementation detail in React that is abstracted away from userland code.
*They are impure as a consequence of JS being the host language, which does not support Algebraic Effects.

An example using hooks

Here is a contrived example using the useState and useEffect hooks, vs using class components and lifecycle methods.

Here is live code of the hooks version (on the left): https://codesandbox.io/s/greeting-hooks-2uwdg

Here is live code of the class component version (on the right):
https://codesandbox.io/s/greeting-classes-7bmql

Notice how in the hook version, state and effects are kept together.

A second example using hooks

Lets look at a second example of using hooks. Here are two versions of a contrived component which lets you search for a user, and edit their name.

Here is the hooks version: https://codesandbox.io/s/react-hooks-are-a-better-mental-model-f9kql

Here is the class version: https://codesandbox.io/s/react-classes-are-the-wrong-mental-model-n9zbs

Notice how, again, the state and effects are kept together with hooks - but more-so this time that a bug is avoided which is in the class component version. ("Save" a user, and while it is saving change the users name. The confirmation message will confirm the wrong name - the newly updated one rather than the one which was saved. This is because by the time the save side-effect finishes, the state is mutated. With hooks, state is functionally-scoped and closed-over, and each render introduces new immutable state.)

Custom Hooks add the missing primitive for state/effect sharing.

Now that we've got a grasp on hooks - how functional components using hooks are a new UI primitive which make state and side-effects easier to reasonable through a declarative API - there is one more important note: beyond just co-locating the state and side-effects, these can be abstracted out into a custom re-useable hook. Hooks represent a primitive for state/effect sharing, as Components are a primitive for UI sharing. Building custom Hooks allow for extracting component logic into reusable functions.

Looking back at our first example. We can build a custom useWidth hook that extracts the width state and effect. Then that hook can be re-used by any component!

Here is live code showing the above: https://codesandbox.io/s/greeting-hooks-as-a-primative-xb0o0

At first glance, it may look like this code-sharing could have been achieved by making a Width component. But that gets at the heart of it: we don't want a re-useable UI primitive, we want a re-useable state/effect primitive. If it were a UI primitive, the state and effects would be tied to a UI representation - we just want the data, so it can be presented however different components decide.

What other built-in Hooks are there?

Basic Hooks

useState
useEffect
useContext

Additional Hooks

useReducer
useCallback
useMemo
useRef
useImperativeHandle
useLayoutEffect
useDebugValue

More resources

Introducing Hooks (reactjs.org)
Making Sense of React Hooks (medium.com)
A Complete Guide to useEffect (overreacted.io)
Thinking in React Hooks (wattenberger.com)

Individual Photos of Class vs Hooks code with and without Highlighting

Classes: https://thepracticaldev.s3.amazonaws.com/i/9t0sa5bfzos9nh8yfumy.png
Classes Highlighted: https://thepracticaldev.s3.amazonaws.com/i/ah9b8plpz32jejub7nfl.png

Hooks: https://thepracticaldev.s3.amazonaws.com/i/gupc51cvr005gnkuzriu.png
Hooks Highlighted: https://thepracticaldev.s3.amazonaws.com/i/p0tr7pzokmlovbm1v3bw.png

Together:
https://thepracticaldev.s3.amazonaws.com/i/8kt6btrmwqpa1mnffzi9.png
Together Highlighted:
https://thepracticaldev.s3.amazonaws.com/i/bqk4xi68eidx7jmwq6ca.png

React Hooks are a More Accurate Implementation of the React Mental Model

craig martin — Thu, 26 Sep 2019 03:29:56 +0000

React Functional Components using Hooks are a More Accurate Implementation of the React Mental Model for State and Effects, than React Classes

TL;DR React made updating the DOM declarative. Hooks made components themselves declarative.

The key of React was allowing declarative code to be mapped to an imperative DOM.

This was especially true of functional components, which would simply map data to an object describing the UI. React would take this object and surgically (imperatively) update the DOM.

However, with class components, while the render function was still declarative, the class instance itself (where the state lived) is mutable - which made it harder to reason about.

The implementation for state and side-effects were within these class components - tied to the mutating instance.

React hooks are a re-conception and re-implemenation of state and side-effects in React - an implementation instead of in class components, is in functional components. As a basic definition they are functions that let you "hook into" React state and lifecycle features. But the key is their implementation with functional components in a declarative api.

"But why is this a 'more accurate implementation of the react mental model'?"

React hooks allow components to be truly declarative even if they contain state and side-effects.

State is now retrieved declaratively without mutating the structure of the component (ie as the class instance would be).

Side-effects are now declaratively aligned with state, instead of with the component's mutation.

Just as the first key of react was a declarative mapper to the DOM, hooks are the second key: providing a declarative api in the component for state and side effects.

"Um, OK, sure.. How about some code?"

Lets look at two versions of doing the same thing. The first version uses the initial class-based implementation of state and effects, and second uses the new hook-based implementation.

The example is an (very contrived) User component. An input will search for the user and display their name, which can be edited and saved.

Using React's initial class-based implementation of state and effects

https://codesandbox.io/s/react-classes-are-the-wrong-mental-model-n9zbs

/*
 * A code sample to show how React class components are
 * not the best implementation of the react mental model.
 *
 * Limitations:
 * - 1. With react classes, `this` is mutable and harder
 *      to reason about
 * - 2. With react classes, the lifecyle hooks are aligned
 *      with the component instead of the data.
 *
 * To see 1: save a user's name, and then immediately
 * change it again. You'll see the confirmation alert has
 * the wrong name (the new one, not the one which was saved).
 * Because "this" is mutated before the save finishes,
 * the wrong data is surfaced to the user.
 *
 * To see 2: Notice how the code for componentDidUpdate
 * and componentDidMount is doing the same thing? What we
 * care about is changes to "username" data but instead
 * the model here is built around changes to the component.
 */

import React from "react";

class User extends React.Component {
  state = {
    username: this.props.username
  };

  handleUsernameChange = e => {
    this.setState({ username: e.target.value });
  };

  handleNameChange = e => {
    const name = e.target.value;
    this.setState(state => ({
      ...state,
      user: {
        ...state.user,
        name
      }
    }));
  };

  save = () => {
    // Pretend save that takes two seconds
    setTimeout(
      () => alert(`User's name has been saved to "${this.state.user.name}`),
      2000
    );
  };

  async fetchUser() {
    const response = await fetch(
      `https://api.github.com/users/${this.state.username}`
    );
    if (!response.ok) {
      return {};
    }
    return await response.json();
  }

  async componentDidMount() {
    if (this.props.username) {
      if (this.state.username) {
        const user = await this.fetchUser();
        this.setState({ user });
      }
    }
  }

  async componentDidUpdate(prevProps, prevState) {
    if (this.state.username !== prevState.username) {
      if (this.state.username) {
        const user = await this.fetchUser();
        this.setState({ user });
      }
    }
  }

  componentWillUnmount() {
    // clean up any lingering promises
  }

  render() {
    return (
      <>
        Search
        <input
          value={this.state.username || ""}
          placeholder="Github Username"
          onChange={this.handleUsernameChange}
        />
        <hr />
        {this.state.user && (
          <>
            <h2>Name</h2>
            <input
              value={this.state.user.name}
              onChange={this.handleNameChange}
            />
            <button onClick={this.save}>Save</button>
          </>
        )}
      </>
    );
  }
}

export default User;

Here is the live code running. You can see point 1 described in the code comment above: save a user's name, and then immediately change it again. You'll see the confirmation alert has the wrong name (the new one, not the one which was saved).

Now lets look at...

Using React's new hook-based implementation of state and effects

https://codesandbox.io/s/react-hooks-are-a-better-mental-model-f9kql

/*
 * A code sample to show how React functional components useing "hooks" are a
 * better implementation of the react mental model.
 */
import React, { useState, useEffect } from "react";

const fetchUser = async username => {
  if (!username) return await {};
  const response = await fetch(`https://api.github.com/users/${username}`);
  if (!response.ok) return {};
  return await response.json();
};

const saveUser = user => {
  // Pretend save that takes two seconds
  setTimeout(() => alert(`User's name has been saved to "${user.name}`), 2000);
};

export default ({ username: initialUsername = "" }) => {
  const [user, setUser] = useState({});
  const [username, setUsername] = useState(initialUsername);

  useEffect(() => {
    const doFetchAndSet = async () => {
      const u = await fetchUser(username);
      setUser(u);
    };
    doFetchAndSet();
  }, [username]);

  return (
    <>
      Search
      <input
        value={username || ""}
        placeholder="Github Username"
        onChange={e => setUsername(e.target.value)}
      />
      <hr />
      {user.name && (
        <>
          <h2>Name</h2>
          <input
            value={user.name}
            onChange={e => setUser({ ...user, name: e.target.value })}
          />
          <button onClick={() => saveUser(user)}>Save</button>
        </>
      )}
    </>
  );
};

Again, here is this live code running. If you try to reproduce the bug from the first example, you won't be able to.

What insights am I missing? What did I neglect or exaggerate? Let me know!

Making Await More Functional in JavaScript

craig martin — Fri, 23 Aug 2019 21:13:04 +0000

In The Problem with Promises in Javascript I looked at how the API and design of promises felt casually dangerous to writing responsible and safe code.

I included a section proposing a library (fPromise) which used a functional approach to overcome these problems.

After it was published, Mike Sherov was kind enough to respond to a tweet about the article and offered his take on it: that I under-appreciated the value of the async/async syntax (that it abstracts out the tricky then/catch API, and returns us to "normal" flow) and that the problems that remain (ie, bad error handling) are problems with JavaScript itself (which TC39 is always evolving).

I am very grateful for his thoughts on this, and helping elucidate a counter-narrative to the one I proposed!!

Here's what Mike says:

// Detect dark theme var iframe = document.getElementById('tweet-1164169660973092864-964'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1164169660973092864&theme=dark" }

// Detect dark theme var iframe = document.getElementById('tweet-1164180648044716032-87'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1164180648044716032&theme=dark" }

// Detect dark theme var iframe = document.getElementById('tweet-1164170411044679682-734'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1164170411044679682&theme=dark" }

Lets look at an example from the Problems article:

const handleSave = async rawUserData => {
  try {
    const user = await saveUser(rawUserData);
    createToast(`User ${displayName(user)} has been created`);
  } catch {
    createToast(`User could not be saved`));
  }
};

I had balked at this, as the try was "catching" too much, and used the point that if displayName threw, the user would be alerted that no user was saved, even though it was. But - though the code is a bit monotonous - this is overcome-able - and was a bad job out me for not showing.

If our catch is smart about error handling, this goes away.

const handleSave = async rawUserData => {
  try {
    const user = await saveUser(rawUserData);
    createToast(`User ${displayName(user)} has been created`);
  } catch (err) {
    if (err instanceof HTTPError) {
      createToast(`User could not be saved`));
    } else {
      throw err;
    }
  }
};

And if the language's evolution includes better error handling, this approach would feel better:

// (code includes fictitious catch handling by error type)
const handleSave = async rawUserData => {
  try {
    const user = await saveUser(rawUserData);
    createToast(`User ${displayName(user)} has been created`);
  } catch (HTTPError as err) {
    createToast(`User could not be saved`));
  }
};

While this is much better, I still balk about having too much in the try. I believe catch's should only catch for the exception they intend to (bad job out of me in the original post), but that the scope of what is being "tried" should be as minimal as possible.

Otherwise, as the code grows, there are catch collisions:

// (code includes fictitious catch handling by error type)
const handleSave = async rawUserData => {
  try {
    const user = await saveUser(rawUserData);
    createToast(`User ${displayName(user)} has been created`);
    const mailChimpId = await postUserToMailChimp(user);
  } catch (HTTPError as err) {
    createToast(`Um...`));
  }
};

So here is a more narrow approach about what we are catching:

// (code includes fictitious catch handling by error type)
const handleSave = async rawUserData => {
  try {
    const user = await saveUser(rawUserData);
    createToast(`User ${displayName(user)} has been created`);
    try {
        const mailChimpId = await postUserToMailChimp(user);
        createToast(`User ${displayName(user)} has been subscribed`);
    } catch (HTTPError as err) {
        createToast(`User could not be subscribed to mailing list`));
    }
  } catch (HTTPError as err) {
    createToast(`User could not be saved`));
  }
};

But now we find ourselves in a try/catch block "hell". Lets try to get out of it:

// (code includes fictitious catch handling by error type)
const handleSave = async rawUserData => {
  let user;
  try {
    user = await saveUser(rawUserData);
  } catch (HTTPError as err) {
    createToast(`User could not be saved`));
  }
  if (!user) {
    return;
  }
  createToast(`User ${displayName(user)} has been created`);

  let mailChimpId;
  try {
    await postUserToMailChimp(rawUserData);
  } catch (HTTPError as err) {
    createToast(`User could not be subscribed to mailing list`));
  }
  if (!mailChimpId) {
    return;
  }
  createToast(`User ${displayName(user)} has been subscribed`);
};

Despite that this is responsible and safe code, it feels the most unreadable and like we're doing something wrong and ugly and working uphill against the language. Also, remember this code is using a succinct fictitious error handler, rather than the even more verbose (real) code of checking the error type and handling else re-throwing it.

Which is (I believe) exactly Mike's point, that error handling (in general) needs improved, and exactly my point - that doing async code with promises is casually dangerous, as it makes dangerous code clean and ergonomic, and responsible code less readable and intuitive.

So, how could this be better? What if there was -

Await catch handling

What if we could do something like this?

// (code includes fictitious await catch handling by error type)
const handleSave = async rawUserData => {
  const [user, httpError] = await saveUser(rawUserData) | HTTPError;
  if (httpError) {
    return createToast(`User could not be saved`));
  }
  createToast(`User ${displayName(user)} has been created`);

  const [id, httpError] = await saveUser(rawUserData) | HTTPError;
  if (httpError) {
    return createToast(`User could not be subscribed to mailing list`));
  }
  createToast(`User ${displayName(user)} has been subscribed`);
};

This reads nicely and is safe and responsible! We are catching exactly the error type we intend to. Any other error causes the await to "throw".

And it could be used with multiple error types. Eg,

// (code includes fictitious catch handling by error type)
const [user, foo, bar] = await saveUser(rawUserData) | FooError, BarThing;

How close can we get to this in userland?

Pretty close. Introducing fAwait (as in functional-await).

const {fa} = require('fawait');
const [user, httpError] = await fa(saveUser(rawUserData), HTTPError);
const [user, foo, bar] = await fa(saveUser(rawUserData), FooError, BarThing);

Thanks for reading!

craigmichaelmartin / fawait

A javascript library for making await more functional

`fAwait`

What is `fAwait`?

fAwait is a javascript library for working with the await syntax in a more functional way.

How To Use It

Wrap your promise with the fa function, and provide error types you want to catch, and you'll receive an array you can unpack to those values. If error types are provided, and the promise rejects with one not specified, it will be thrown. Error types can be the built-ins, or your own custom error types. If no error types are provided, all will be caught.

const { fa } = require('fawait');
const [data, myError] = await fa(promise, MyError);
// If the promise resolves, data will be defined.
// If the promise rejects with my own custom error, myError will be defined.
// If the promise rejects with any other error, the await will

…

View on GitHub

Making JavaScript Promises More Functional

craig martin — Fri, 23 Aug 2019 16:54:51 +0000

[This article was extracted out of The Problem with Promises in JavaScript. It was the final section, but given that it is only one possible solution to the problems enumerated, thought it should live separately. After the short introduction, it is unedited from when it was the final section of the mentioned article.]

A few years ago I created a new repo for a Node-backend web app, and spent some time considering how to deal with promises in my code. In other Node side-projects, I had begun to see some recurring issues with promises: that the API seemed to have the best ergonomics when used dangerously, that they lacked a convenient API to safely work with data, and that rejected promises and unintended runtime exceptions were co-mingled and left for the developer to sort out.

You can read more about these issues in The Problem with Promises in JavaScript.

This article is one (out of an infinite number of solutions to these problems - and probably a really bad one) thought experiment on what might be a solution.. which turned into a library: fPromise

craigmichaelmartin / fpromise

Making promise usage safe, convenient, and readable.

`fPromise`

Installation

npm install --save fpromise

What is `fPromise`?

fPromise is a javascript library for working with promises.

It seeks to resolve three problems with promises:

Promises have an API which encourages casually dangerous code
Promises co-mingle rejected promises with unintended native exceptions
Promises lack a suite of convenient API methods to work with results

(For background, and probably a better explanation about this library, read that article about the problems with promises).

fPromise solves these issues by adding a layer of abstraction within promises - re-designing promises's two path design (resolved/rejected) into three paths: a data path, a non-native exception path (ie, for promises rejected by your own intentions), and a native exception path.

With these three paths, we can have an API which is safe, intentional, convenient, and more readable.

Importantly this abstraction:

using promises
leave the promise prototype untouched
provide a safe API for…

View on GitHub

If you haven't read the The Problem with Promises in JavaScript, you may want to.

So, lets begin from a thought experiment about what better promises might have looked like, and see if we can get there in userland code. By "better" - I mean immune to the problems above.

What might a "better" Promise implementation look like?

It feels right that await throws for native exceptions (just like regularly synchronous code would). What is not ideal is that non-native errors are in that bucket, and so have to be caught, and with the new block scopes decreasing readability and making the code more disjointed.

Imagine if promises used rejected promises only for native runtime exceptions, and used a special object for data/issues. Lets call that special object an Either. It is iterable to a two element array with data as the first element, issue as the second. To our earlier point, it also specifies methods like map/imap (issue map) and tap/itap (issue tap) which its two implementations (Data and Issue) implement. Data has no-ops for imap and itap. Issue has no-ops for map and tap. map/imap re-wrap the result as Data/Issue respectively, unless explicitly transformed to the other. The tap methods are side-effect only who's returns are not used.

Promise.resolve creates a "regular" promise wrapping the value in Data. Promise.reject creates a "regular" promise wrapping the value in Issue if the reject is not a native error; otherwise, it creates an actually "rejected" promise.

We could write code like:

// Made up API below!

// data-access/user.js
const save = user => db.execute(user.getInsertSQL());
// As long as there is no native Exceptions, this returns a
// promise in the "regular" state.

// service/user.js
const save = data =>
  save(User(data))
    .tap(getStandardLog('user_creation'))   // Fictional
    .map(User.parseUserFromDB)              // Fictional
    .itap(logError);                        // Fictional

// controllers/user.js
const postHandler = async (userDate, response) => {
  // No need to use try/catch, as everything is in the "regular" state
  const [user, error] = await save(userData);  // Fictional
  if (error) {
    const errorToCode = { 'IntegrityError': 422 }; 
    return response.send(errorToCode[error.constructor.name] || 400);
  }
  response.send(204);
  postEmailToMailChimp(user.email).tapError(logError);
};

Features of this approach:

rejected promises are only used for native exceptions, so no need to use a try/catch block - more readable, cohesive code. Everything else is in the "regular" path, but as a Data or Issue.
map, tap, itap helper utilities which apply the functions to "regular" path promise values. (Remember, map/tap are no-ops on Error, imap/itap are no-ops on Data.)
"regular" promises values (Data|Either) destructure to an array with the data or issue (but, again, never native runtime errors - those throw (and could here be caught in a try/catch, but no one programs for that level of fear: eg try { Math.random() } catch (err) { console.log('Just in case I typo-ed the string "Math" }))
await allows us to stay in the callstack (allowing return)

This to me feels like promises done right.

How close can we get to the above code?

We can actually get pretty close.

We'll

[x] use promises
[x] leave the promise prototype untouched
[x] provide a safe API for using them which isn't casually dangerous
[x] ensure unintentional runtime errors are not handled (and so throw when awaited)
[x] provide utility methods for working with the data
[x] increase readability/cohesion (vs try blocks)
[x] keeps control in main call block (so returns work)

By providing a safe API within the Promise structure, this "library" we'll make can be used anywhere promises are, without hijacking the prototype or needing to introduce a new primitive.

We'll create an Either type which specify

map
imap
tap
itap
etc

and ensures it is iterable (destructure-able) to a two element array.

Data and Issue implement this Either interface.

const Data = x => ({
  map: f => Data(f(x)),          // transform the data by applying the fn
  imap: f => Data(x),            // no-op (method targets Issue)
  bmap: (f, g) => Data(f(x)),    // run respective fn on data
  tap: f => (f(x), Data(x)),     // runs side effect fn on data
  itap: f => Data(x),            // no-op (method targets Issue)
  btap: (f, g) => (f(x), Data(x)),// run respective sideeffect fn on data
  val: () => [x],
  isData: true,
  isIssue: false,
  [Symbol.iterator]: function *() { yield x; }
});

const Issue = x => ({
  map: f => Issue(x),            // no-op (method targets Data)
  imap: f => Issue(f(x)),        // transform the issue by applyin the fn
  bmap: (f, g) => Issue(g(x)),   // run respective fn on issue
  tap: f => Issue(x),            // no-op (method target Data)
  itap: f => (f(x), Issue(x)),   // runs side effect fn on issue
  btap: (f, g) => (g(x), Issue(x)),//run respective sideeffect f on issue
  val: () => [, x],
  isData: false,
  isIssue: true,
  [Symbol.iterator]: function *() { yield void 0; yield x; }
});

We'll need an fp which transforms a current promise to play by our safe rules.

const ensureData = data =>
  data instanceof Data ? data : Data(data);

const nativeExceptions = [ EvalError, RangeError, ReferenceError, SyntaxError, TypeError, URIError ];

const ensureIssue = error => {
  if (error instanceof nativeException) {
    throw error;
  }
  return error instanceof Error ? error : Error(error);
};

const fp = promise => promise.then(ensureData, ensureIssue);

To make these more functional, we could also add:

const map = f => [o => ensureData(o).map(f), o => ensureIssue(o).map(f)];
const imap = f => [o => ensureData(o).imap(f), o => ensureIssue(o).imap(f)];
const bmap = (f, g) => [o => ensureData(o).bmap(f, g), o => ensureIssue(o).bmap(f, g)];
const tap = f => [o => ensureData(o).tap(f), o => ensureIssue(o).tap(f)];
const itap = f => [o => ensureData(o).itap(f), o => ensureIssue(o).itap(f)];
const btap = (f, g) => [o => ensureData(o).btap(f, g), o => ensureIssue(o).btap(f, g)];

To re-write the fictional promise code from above, it's pretty straight forward. We:

wrap the initial promise with a fp to get the promise to play by our rules (again, it remains a completely regular promise).
(await promise) before we can call our utility methods. This is because our utility methods are on the Either that the promise resolves to, not the promise itself. To the point above, we are not touching/modifying promises, just layering on top of them.

// data-access/user.js
const save = user => fp(db.execute(user.getInsertSQL()))

// service/user.js
const save = async data =>
  (await save(User(data)))
    .tap(getStandardLog('user_creation))
    .map(User.parseUserFromDB)
    .itap(logError)

// controllers/user.js
const postHandler = async (userDate, response) => {
  const [user, error] = await save(userData);
  // ...
}

If we wanted to use the more functional approach, no need for initially wrapping the promise:

// data-access/user.js
const save = user => db.execute(user.getInsertSQL();

// service/user.js
const save = data => save(data)
  .then(...tap(getStandardLog('user_creation)))
  .then(...map(User.parseUserFromDB))
  .then(...itap(logError))

// controllers/user.js
const postHandler = async (userDate, response) => {
  const [user, error] = await save(userData);
  // ...
}

Notice for both of these, all of are conditions are met. We are:

[x] using promises
[x] leave the promise prototype untouched
[x] provide a safe API for using them which isn't casually dangerous
[x] ensures unintentional runtime errors are not handled
[x] provides utility methods for working with the data
[x] increases readability (vs try blocks)
[x] keeps control in main call block (so returns work)

If we want to move even further in the functional direction, we could:

// data-access/user.js
const save = user => db.execute(user.getInsertSQL();

// service/user.js
const save = data => save(data)
  .then(...tap(getStandardLog('user_creation')))
  .then(...map(User.parseUserFromDB))
  .then(...itap(logError))

// controllers/user.js
const postHandler = (userDate, response) =>
  save(userData).then(...map(
    user => //...
    error => //...
  );

If you're interested in this fPromise idea, help with it on github

craigmichaelmartin / fpromise

Making promise usage safe, convenient, and readable.

`fPromise`

Installation

npm install --save fpromise

What is `fPromise`?

fPromise is a javascript library for working with promises.

It seeks to resolve three problems with promises:

Promises have an API which encourages casually dangerous code
Promises co-mingle rejected promises with unintended native exceptions
Promises lack a suite of convenient API methods to work with results

(For background, and probably a better explanation about this library, read that article about the problems with promises).

With these three paths, we can have an API which is safe, intentional, convenient, and more readable.

Importantly this abstraction:

using promises
leave the promise prototype untouched
provide a safe API for…

View on GitHub

or check out similar-

Actually Good Projects in this space

Articles About This Stuff From Smart People:

The Problem with Promises in JavaScript

craig martin — Fri, 16 Aug 2019 02:32:22 +0000

Spending a lot of time in Node recently, I keep coming accross 3 recurring problems with promises:

Promises have an API which encourages casually dangerous code
Promises lack a convenient API to safely work with data.
Promises co-mingle rejected promises and unintended runtime exceptions

While the await syntax is happy addition to the language, and part of a solution to these problems, its value - increasing readability and keeping control in the original callstack (ie allowing for returns) - is unrelated to the second two issues, and only sometimes mitigating of the first problem.

Promises have an API which encourages casually dangerous code.

Lets take an example of saving a user:

// Promises (without using await)
// Casually dangerous code
const handleSave = rawUserData => {
  saveUser(rawUserData)
    .then(user => createToast(`User ${displayName(user)} has been created`))
    .catch(err => createToast(`User could not be saved`));
};

This code looks readable and explicit: a clearly defined path for success and for failure.

However, while trying to be explicit, we have attached our catch not just to the saveUser request, but also to the success path. Thus, if the then throws (eg, the displayName function throws) then the user will be notified that no user was saved, even though it was.

One might think, lets switch the order of the then/catch, so that the catch is attached to the saveUser call directly. This introduces another issue, we'll look at further below (as the third issue).

Using await doesn't necessarily help. It is agnostic to using the API correctly, and because of its block scoping it also makes it easier and prettier to write it dangerously as above:

// Promises with Async/Await doesn't necessarily help
// Casually dangerous code
const handleSave = async rawUserData => {
  try {
    const user = await saveUser(rawUserData);
    createToast(`User ${displayName(user) has been created`);
  } catch {
    createToast(`User could not be saved`));
  }
};

Because of the block scoping, it is more convenient to include the createToast line in the try, but then this code has the same issue as above.

The responsible refactor of this using native promises looks worse/ugly/bad/complicated. Lets look at the case of not using await first.

For the case of not using await, two anonymous functions in the correct order (error function first? success function first?) must be passed to the then, which feels less organized than using an explicit catch block:

// Promises done responsibly _look_ worse/ugly/bad/complicated :(
const handleSave = rawUserData => {
  saveUser(rawUserData)
    .then(
      user => createToast(`User ${displayName(user)} has been created`),
      err => createToast(`User could not be saved`));
    );
};

To be clear, this isn't a bad API in itself. But considering the rightful intention of being explicit as a developer, there is a temptation of using a named function for each, rather than one then with the two callbacks. The responsible code is less explicit and readable than dangerous code - it is temptingly dangerous to misuse the API - while feeling more explicit and readable!

The responsible refactor using async/await looks even more so wrong/ugly/bad/complicated. Having to define variables in a higher scope feels like a bad control flow. It feels like we're working against the language:

// Promises done responsibly _look_ worse/ugly/bad/complicated :(
const handleSave = async rawUserData => {
  let user;
  try {
    user = await saveUser(rawUserData);
  } catch {
    createToast(`User could not be saved`));
  }
  createToast(`User ${displayName(user)} has been created`);
};

Notice the code above isn't even correct. We'd need to return from the catch (something I try to avoid as it further confuses control flow - especially if there is a finally) or wrap everything after the try if an if (user) { /*...*/ } block - creating another block. It feels like we're working uphill.

It's also worth noting that the API is also unintuitive (but this time the other way!) when chaining multiple thens.

Whereas the examples above are dangerous because the catch is meant to be attached to the "root" async call (the HTTP request) - there is also a danger with long chains of thinking the catch is associated with the most recent then.

(It's neither attached to the root promise nor the most recent promise - it is attached to the entire chain preceding it.)

For example:

// Casually dangerous code
const userPostHandler = rawUserData => {
  saveUser(rawUserData)
    .then(sendWelcomeEmail)
    .catch(queueWelcomeEmailForLaterAttempt)
};

which looks and reads cleanly, compared to the responsible:

// Promises done responsibly _look_ worse/ugly/bad/complicated :(
const userPostHandler = rawUserData => {
  saveUser(rawUserData)
    .then(user =>
      sendWelcomeEmail(user)
        .catch(queueWelcomeEmailForLaterAttempt)
    );
};

Lets go further with the example above, to see one last way the API is casually dangerous: lets add logging for if the user can't be created:

// Dangerous code
const userPostHandler = rawUserData => {
  saveUser(rawUserData)
    .catch(writeIssueToLog)
    .then(sendWelcomeEmail)
    .catch(queueWelcomeEmailForLaterAttempt)
};

What we want is to write the issue to our logs if the user save fails.

However, because our catch doesn't re-throw or explicitly reject, it returns a resolved promise and so the next then (sendWelcomeEmail) will run, and because there is no user, it will throw, and we'll create a queued email for a non-existing user.

The casual promise API makes unintentionally recovering from an exception easy/sleek/elegant.

Again, the fix looks bad:

// Promises done responsibly _look_ worse/ugly/bad/complicated :(
const userPostHandler = rawUserData => {
  saveUser(rawUserData)
    .then(
      writeIssueToLog,
      user =>
          sendWelcomeEmail(user)
            .catch(queueWelcomeEmailForLaterAttempt)
      );
};

Wrapping up this section, we've seen how promise's API for handling errors while seemingly sleek, is casually dangerous: both due to the readability and convenience of catching separately from the then (ie, using an explicit catch function - which if in a chain includes errors not just from the "root" promise, nor from the most recent promise, but from any promise in the chain), as well as by fostering an unintentional recovery of errors.

While the addition of the async operator can help, it does so within a try scope - making the right code look disjointed, and irresponsible code (placing too much in the try) look cleaner/sleeker.

I would prefer an API which at a minimum optimizes aesthetics and readability (by working with the language) for the responsible behavior, and preferably which precludes irresponsible or casually dangerous code.

Promises lack a convenient API to safely work with data.

In the section above, we looked at how the existing promise API is temptingly dangerous (using two explicit named functions vs one with anonymous parameters for each function), and how it fosters unintentionally recovering from errors.

This second case is a problem only because the promise API doesn't offer more helpers.

In the last example above where our .catch(logError) inadvertently resolved the error, what we were really wanting was something else: a tap side-effect function for errors.

Promises co-mingle rejected promises and unintended runtime exceptions

Apart from how the API is structured - promises have another major flaw: they treat unintentional native runtime exceptions and intentional rejected promises - which are two drastically different intentions - in the same "path".

const userPostHandler = rawUserData => {
  saveUser(userData)
    .then(() => response.send(204))
    .then({email} => postEmailToMailChimp(email))
    .catch(logError)
};

What this code is trying to express is pretty straightforward. (I want to save a user and post their email to my mailchimp list and log if there is an issue).

However, I accidentally typo'd the function name as "MailChimp" instead of "Mailchimp" - and rather than the runtime error alerting me while developing - I now have to hope that I look at the log - which I intended for mailchimp issues, not basic programming issues!

In explaining the root issue here with promises, I abbreviated the behavior slightly: promises treat all errors (not just native errors) the same as rejected promises. Treating throw and Promise.reject synonymously seems reasonable. What does not seem reasonable is using this one "path" to handle two worlds-different "types" of errors without distinction: "strategic" errors (eg saveUser(user) throwing a custom Integrity error), and basic javascript runtime errors (eg saveUsr(user) having a typo and throwing a ReferenceError). These are two fundamentally different realties, but they are bundled together in the same "rejected promise" path.

With promises, there are really three paths: the data "path", a non-native error "path" (eg, custom, business-logic errors), and a native error "path", yet the API does not make this distinction: and treats all errors and rejected promises the same.

[Two updates]

[Update] This article previously continued with a theoretical section on what "better" Promises might look like... "What comes next is one (out of an infinite number of solutions to these problems - and probably a really bad one) thought experiment on what might be a solution.. which turned into a library." If you're interested you can see read it here, Making JavaScript Promises More Functional

[Update] Mike Sherov was kind enough to respond to a tweet about this article and offered his take on this: that I under-appreciated the value of the async/async syntax (that it abstracts out the tricky then/catch API, and returns us to "normal" flow) and that the problems that remain (ie, bad error handling) are problems with JavaScript itself (which TC39 is always evolving). I expand on that idea, including the creation of a very simple library, in Making Await More Functional in Javascript

User Types and Roles in an Activity-based Permission Systems

craig martin — Fri, 04 Jan 2019 03:01:53 +0000

Decoupling User Types from User Roles in Activity-based Permission Systems

TLDR;

Lets say we are developing an app. In our app we should have lots of granular, atomic permissions. We should support roles (groupings of permissions) but as something defined by admin-users for their organization, and so be 100% arbitrary to us. These roles should exist within Profile types, which are defined by us, and are used to know which "type" of user we are dealing with. A user can have multiple roles within and across multiple profiles, but can only be acting as one profile at a time. Our app code, when dealing with a user, can check their Profile (ie user.is(Profile) to answer the question "where should we send them?") or perform permission checks (ie, user.can(Operation, Object) to answer the question "what should they be able to do/see when they get there?").

Concepts

Permissions

A Permission is a granular activity-based access control.
Permissions are specified by the development team.

Profiles

A Profile is a supported user type in the app.
Profiles are specified by the development team.
Profiles (user types) are used to determined where a user should go based. They correspond with tracks built the app (eg, which dashboard to go to).
For each Profile an organization creates their own roles.
A user may have roles in more than one profile.

Roles

A Role is a group of permissions for a Profile.
Roles are not specified by the development team and are completely arbitrary, and instead are specified by privileged users for their organization.
A user may have more than one role per profile.

User

A user has exactly one active profile (which has at least one role), but can switch profiles.
A user may have roles in multiple organizations.

Organization

An Organization is a grouping entity with an internal hierarchy.
Roles exist for a Profile for an Organization.

Profiles exist to answer questions related to which "type" of user the app is dealing with. Permissions exist to answer questions related to what access the user can have. (EG, Profile: "Should the user be routed to the admin or affiliate dashboard?" vs Permission: "What should they see and be able to edit once they are routed?") Roles exist to in service of making permissions manageable.

Without profiles, you end up with a set of faux permissions - "permissions" which really are just interested in what type the user is (eg, canSeeAdminDashboard and canSeeAffiliateDashboard are really just questions about what is the type of user using the app).

Without roles, every user is a one-off set of permissions. For example, If you're creating multiple users for managing invoices, you'd have to re-select exactly the same permissions for each user, including months later after you hire another person to manage invoices. Or, suppose for example a new invoice feature comes out later. You'd have to remember which users are doing invoice work, and update each of them with this new permission.

Without organizations, roles would have to be global and governed by the development team. Instead, each organization in the system can configure their own roles for their applicable profiles - choosing permissions defined by the development team for that profile.

Schema

operation               # actions types in the system (read, edit, create, etc)
- id

object                  # entity types to be acted upon (invoices, customers, etc)
- id

permission              # atomic abilities in the app
- id
- operation_id
- object_id

role                    # an organization's group of permissions for a profile
- id
- value
- label
- profile_id
- organization_id

role_permission         # specifies which permissions are in a role
- id
- role_id
- permission_id

profile                 # a supported user identity type in the app
- id
- value
- label

profile_permission      # specifies which profiles a permission is valid for
- id
- permission_id
- profile_id

organization
- id

user
- id
- active_profile_id

user_role               # specifies the roles a user has
- user_id
- role_id

# There would be no `user_profile` table, as access to a profile is a permission

Code

User

is(Profile) - returns whether the user is actively acting as a certain profile type (answering questions like "where should we send this user?")
can(Operation, Object, Organization?) - iterates through the user's roles (for a specific organization if supplied) for their active profile, to identify if they have permission (answering questions like "what resources should the user be able to see/change?")
switchProfile(Profile) - changes the user's active profile

Making it Less Abstract: An Example

Let's say you and I create an app for lawn care businesses.

Lawn Care Owners log in to create clients, create employees, assign jobs to employees, send invoices to their clients, and write monthly newsletters about lawn care tips to their clients.
Lawn Care Workers log in to see their schedule.
Clients log in to pay their invoices, and see past invoices.
As part of an affiliate-system, Home Owner Associations can log in to see clients in their neighborhoods.
Product Marketing Companies can log in to post ads to this app, since its free to the business owner.
Finally, Internal Staff (you and I and our employees) can log in to see data and metrics and charts and stuff.

Thus, we create these six Profiles:

Lawn Care Administrator
Lawn Care Worker
Client
Homeowner Association Rep
Brand Rep
Internal Staff

While, each profile is known and has special meaningful to us, roles are all user-generated and are never referenced or known in our code.

Let's start by looking at the first three.

In the beginning, the owner makes one role within each profile, and assigns it to himself. As the company grows, he hires employees for each of these, and soon has multiple employees type: Just in administration, a manager to schedule clients and assign lawn care workers to them; a bookkeeper to see the paid/unpaid finances; a marketing intern to write up the newsletters. Similarly, there arises a hierarchy within his growing crew of lawn care workers, constraining permissions for new guys and allowing the full breadth of permissions for his team lead. Lastly, as commercial clients are taken on, a role with different permissions is created.

Administrator
 - Scheduler
 - Bookkeeper
 - Marketer

Lawn Care Worker
 - Entry Level
 - Experienced
 - Team Lead

Client
 - Residential
 - Commercial

In reality, these roles would be not be focused on the "who" and instead on the "what". For example, if the difference between residential and commercial as defined above is really about the difference in how the owner allows the client to pay, it would make more sense to have a "trusted_payer" permission, which allows the client to not have their credit card on file and be invoiced instead, etc. Then, when the owners favorite customer reads about credit card scams and asks to be invoiced rather than his card on file, that user's account can be meaningfully updated. Remember, a user can have multiple roles, it's not an either or. Permissions are just about "grouping" permissions for convenience and consistency! They're not about creating fully descriptive categories. (Composition vs Category)

The next type of user who will be logging in to our app is a Homeowner Association Rep. They decide to create a role with limited permissions and allow the HOA members to see some of the metrics for this new source of income for the HOA.

Homeowner Association Rep
 - President
 - Member

The next type of user is a Brand Rep. They log in to see ad metrics for their campaigns, and created a role with limited permissions for their intern.

Brand Rep
 - Full
 - Intern

The last type of user is an Internal Staff user. These are your and my employees, and they log in to see and configure data.

Internal Staff
 - Superuser
 - Customer Support
 - Marketer

Each of these roles under the six above profiles are specific to the "organization" that made them. In the case of the fist three profiles, those roles are part of the lawn care business's organization; for the HOA rep profile, the hoa organization; for the brand rep profile, the brand organization; and finally for our employers, an internal staff organization.

This might sound odd, that these organizations aren't parallel. That's true if an organization includes the business or hoa or brand specific details, but our organizations do not. There would be a separate "business"/"hoa"/"brand" table for this data. An organization is just an entity used for permissions, and not coupled with a business, or hoa, or brand, or tenant, or conglomerate, or whatever-grouping-you-may-use.

A user can perform the actions within an organization according to their roles (which are organization-aware).

Lets say a user is:

a client who uses both Tom's Lawn Care (for weekly mowing) and Jack's Landscaping (for less frequent landscaping tune-ups)
the president of a Home Owner's Association, and use the affiliate referral program to raise money for their HOA (Blue Meadows)
a marketing employee for our app company, using the staff app.

This user account is associated with four different organizations: Tom's, Jack's, Blue Meadows, and Internal Staff. It is associated with three different profiles: client, homeowner association rep, and internal staff.

When this user logs in, they are presented with their profiles. If they choose Internal Staff, they see can see metrics and data to better market our app. If they choose Homeowner Association Rep, they see a dashboard with their referral kickbacks. If they choose Client, they see the invoices from Tom and Jack, and since Jack has given them more permissions, for his they can see line items of his costs. One day, Tom gets spooked by the internet and removes all client permissions, and so only Jack's show up here.

Thus, a user may have multiple profiles with multiple roles across multiple organizations - but our app code only cares about profiles, organizations, and permissions (not roles). If a

It is important to note, roles within an organization within a profile "add up" - even if the permission is missing in one role in a profile, if it is present in another, the user has that permission.

Example UIs

Super rough demo example UI of permissions when a business owner is associating a new user with his organization:

Super rough demo example of a business owner adding a new role for his organization:

When a user with more than one profile logs in, the app must enforce only allowing the user to act as one profile (and so making the user select which profile, or defaulting them to the last profile, etc).

Inspiration / Better Articles:

Role-Based Access Control by the National Institute of Standards and Technology
Role Based Access Control by Square
Don’t Do Role-Based Authorization Checks; Do Activity-Based Checks by Derick Bailey

Forem: craig martin

A High Level Introduction to Machine Learning

Year 1

Year 2

Year 3

Year 4

Year 5

Year 6

Year 6

Reflections from the Caymans

Hooks for those who know React

"Ok, Yeah, cool, whatever.. So what are hooks?"

The useState hook for managing local state

The useEffect hook for managing side-effects

"But hold on.. WTF.. wouldn't these hooks be reset every render?"

An example using hooks

A second example using hooks

Custom Hooks add the missing primitive for state/effect sharing.

What other built-in Hooks are there?

More resources

Individual Photos of Class vs Hooks code with and without Highlighting

React Hooks are a More Accurate Implementation of the React Mental Model

Using React's initial class-based implementation of state and effects

Using React's new hook-based implementation of state and effects

Making Await More Functional in JavaScript

Await catch handling

How close can we get to this in userland?

craigmichaelmartin / fawait

A javascript library for making await more functional

fAwait

What is fAwait?

How To Use It

Making JavaScript Promises More Functional

craigmichaelmartin / fpromise

Making promise usage safe, convenient, and readable.

fPromise

Installation

What is fPromise?

What might a "better" Promise implementation look like?

How close can we get to the above code?

craigmichaelmartin / fpromise

Making promise usage safe, convenient, and readable.

fPromise

Installation

What is fPromise?

Actually Good Projects in this space

Articles About This Stuff From Smart People:

The Problem with Promises in JavaScript

Promises have an API which encourages casually dangerous code.

Promises lack a convenient API to safely work with data.

Promises co-mingle rejected promises and unintended runtime exceptions

User Types and Roles in an Activity-based Permission Systems

TLDR;

Concepts

Schema

Code

Making it Less Abstract: An Example

Example UIs

Inspiration / Better Articles:

The `useState` hook for managing local state

The `useEffect` hook for managing side-effects

`fAwait`

What is `fAwait`?

`fPromise`

What is `fPromise`?

`fPromise`

What is `fPromise`?