DEV Community: Jared Jones

Inverse Reducers

Jared Jones — Fri, 15 May 2020 21:13:45 +0000

Check out this post on my website as well!

If you are a JavaScript developer, especially a React developer, you have probably heard of something called the "reducer pattern". While the idea isn't incredibly new it has become increasingly popular, not only because of Redux and similar libraries, but beacuse React itself solidified the pattern in their library with the new Hooks API (useReducer).

If you are unfamiliar with reducers they are essentially definitions of how an application's state changes in response to "actions". "actions" are just predefined changes your state can undergo. So all you need is some state object, a collection of "actions", and your actual reducer function that enacts the actions changes on the state. Here's an example of what that typically looks like:

const state = {
  count: 0
}

const ACTIONS = {
  COUNT_UP: 'COUNT_UP',
  COUNT_DOWN: 'COUNT_DOWN'
}

function reducer(state, action) {
  switch(action.type) {
    case ACTIONS.COUNT_UP:
      return { ...state, count: state.count + 1 };
    case ACTIONS.COUNT_DOWN:
      return { ...state, count: state.count - 1 };
    default:
      return state;
  }
}

There are thousands and thousands of code bases out there that have some slight variation of this reducer pattern. So obviously it works, people seem to like it, but it has always rubbed me the wrong way.

I have always been partial to switch statements. I don't think they read very well, you either have to return or manage awkward break statements. However, what is really worse is that each case isn't it's own block. This means any variables defined aren't scoped to the case but to the entire reducer function. Here's an simple example:

function reducer(state, action) {
  switch (action.type) {
    case ACTIONS.REMOVE_FROM_LIST:
      const i = state.list.find(action.item);
      return {
        ...state,
        list: [
          ...state.list.slice(0, i),
          ...state.list.slice(i + 1, state.list.length),
        ],
      };
    case ACTIONS.REMOVE_FROM_LIST_B:
      // This line will throw an error
      const i = state.listB.find(action.item);
      return {
        ...state,
        list: [
          ...state.listB.slice(0, i),
          ...state.listB.slice(i + 1, state.listB.length),
        ],
      };
    // ...
  }
}

While this example may seem relatively benign, imagine you are working in a large codebase with dozens of actions. You can easily lose track of what variables are being used or defined and doing something as simple as adding a new case can be frustrating especially to a new developer. You could solve this by replacing the switch statement with a large if-else chain, but then your cases become harder to scan since the syntax of if-else obscures the case more than a switch.

So how can we use the reducer pattern without long chains of if/else's or big switch statements? That's where the "inverse reducer" comes into play. Instead of defining our types and then writing their logic inside the reducer, we are going to write them together.

const ACTIONS = {
  COUNT_UP: (state, action) => ({
    ...state,
    count: state.count + 1,
  }),
  COUNT_DOWN: (state, action) => ({
    ...state,
    count: state.count - 1,
  }),
};

function reducer(state, action) {
  return action.type(state, action);
}

Look how simple our reducer becomes, and how easy it is to find out what each action actually does! We also gain block scoping in each action so we don't have to worry about defining our variables at the top of a giant switch block and mutating them later. Let's look at that list example again:

const ACTIONS = {
  REMOVE_FROM_LIST: (state, action) => {
    const i = state.list.find(action.item);
    return {
      ...state,
      list: [
        ...state.list.slice(0, i),
        ...state.list.slice(i + 1, state.list.length),
      ],
    };
  },
  REMOVE_FROM_LIST_B: (state, action) => {
    const i = state.listB.find(action.item);
    return {
      ...state,
      list: [
        ...state.listB.slice(0, i),
        ...state.listB.slice(i + 1, state.listB.length),
      ],
    };
  },
};

function reducer(state, action) {
  return action.type(state, action);
}

All we are doing is instead of having a single massive function that handles all of the reducing logic, we create many tiny reducing functions. This inversion of control better shows the separation of concerns and improves readability.

Something I know people will say is, "Now you are passing around functions instead of strings for types, won't that cause problems?". The easy answer is no because JS passes everything except for primitive values by reference. Now when you say ACTIONS.REMOVE_FROM_LIST instead of a string you are getting a reference to the actions reducing function. References are 8 bytes in JS so passing it around instead of a string is likely taking less memory and since JS's strict comparison checks the identity it will compare the reference when doing any equality checks. This could be improved even further if JS has a native concept of enums, but comparing the function references isn't that bad.

What are some flaws I missed? How could this make your project simpler? Let me know your thoughts on this pattern. I haven't found any real examples of this being used in JS projects, so I'm curious if you have seen this before, thanks for reading!

Faking React for VSCode Webviews

Jared Jones — Mon, 10 Feb 2020 21:48:56 +0000

I recently worked on a hackathon project at work that involved creating a custom webview for previewing YAML specs. If you haven't worked with the VS Code webview API before, it is very simplistic and involves sending a string of an HTML page to VS Code that it will manually render. A very simple example would look something like this:

// Taken from the visual studio docs
import * as vscode from "vscode";

export function activate(context: vscode.ExtensionContext) {
  context.subscriptions.push(
    vscode.commands.registerCommand("catCoding.start", () => {
      // Create and show panel
      const panel = vscode.window.createWebviewPanel(
        "catCoding",
        "Cat Coding",
        vscode.ViewColumn.One,
        {}
      );

      // And set its HTML content
      panel.webview.html = getWebviewContent();
    })
  );
}

function getWebviewContent() {
  return `<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Cat Coding</title>
</head>
<body>
    <img src="https://media.giphy.com/media/JIX9t2j0ZTN9S/giphy.gif" width="300" />
</body>
</html>`;
}

I'm sure you can see where this post is going... this can become very cumbersome very quickly. Writing complex logic in template strings is messy and doesn't give you intellisense on errors which just makes things harder to debug. Now I write React components all day, so I wanted to be able to use JSX to make my life easier. JSX isn't something that is "react only", it's simply a bit of syntactic sugar that makes a function call look like HTML. The function it is hiding is called createElement which converts a html element definition into a React node that it can handle. In my case all I need is for createElement to spit out an HTML string so that I can pass it to VS Code. So let's see if we can write our own createElement that will turn JSX into a string!

If we take a look at the React createElement function we can see it takes 3 arguments:

function createElement(type, config, children) { ... }

Let's go over what these mean: type is the type of element we are going to render (like h1 or div), config allows us to pass options to our element like attributes and props, and finally children are the nested elements to render within my current element. If we look a bit harder we can also see a comment about the children:

// ...
// Children can be more than one argument, and those are transferred onto
// the newly allocated props object.
const childrenLength = arguments.length - 2;
// ...

This lets us know that when there are multiple children it will pass them as multiple arguments, in their implementation they are opting to look at the arguments array but we can also handle this with the "rest" syntax (opposite of "spread" but with the same syntax). For our solution we don't need alot of the fancy bits React handles, in fact we don't really need custom components because we can just use functions and make our job much simpler, so instead of config the options are just going to be the attributes we want to attach to the actual DOM element. With all of that we have figured out the definition for our createElement function!

function createElement(type, attributes, ...children) { ... }

Before we go much further, you may be thinking to yourself "So what if we can write our own createElement function? How are we going to get our JSX to use that?". So let's talk about how React deals with compiling JSX. If you are familiar with tools like create-react-app this process is often obfuscated from you, but it is very simple! React uses babel to compile everything down to vanilla JS that can run everywhere, so all we need to do is copy the build process React uses by setting up babel ourselves. We will need 3 packages:

@babel/cli
@babel/core
@babel/plugin-transform-react-jsx

The important one here is @babel/plugin-transform-react-jsx which handles the transpiling of our JSX to createElement function calls. And the coolest part of this package is that it allows us to specify our own createElement function by defining a "pragma". This is just a string of the function babel should use when making the JSX calls, the default is React.createElement (that's why you have to import react in any file where you use JSX in a normal React project). In our .babelrc file let's set up the plugin:

{
  "plugins": [
    ["@babel/plugin-transform-react-jsx", { "pragma": "createElement" }]
  ]
}

Here we are telling babel, "When you run use the plugin plugin-transform-react-jsx and give it the options object that tells you to call createElement instead of React.createElement". Now the only thing we have to do to get our JSX to work is run babel and ensure we have our createElement function in scope anywhere we use JSX! To get our VS Code extension to run babel before the extension launches we need to add a build script to our package.json that runs babel, and then we need to define a preLaunchTask in our .vscode/launch.json file.

// package.json
{
  //...
  "scripts": {
    "build": "babel src -d dist"
  }
  //...
}

{
  //...
  "configurations": [
    {
      "name": "Extension",
      "type": "extensionHost",
      "request": "launch",
      "runtimeExecutable": "${execPath}",
      "args": [
        "--extensionDevelopmentPath=${workspaceFolder}"
      ],
      "preLaunchTask": "npm: build"
    }
  ]
  //...
}

Now that we have all of the configuration stuff squared away we can get back to developing our createElement function! Remember our goal is to turn JSX into an HTML string that can be read by VS Code's webview API. Let's start simple: getting it to create the right type of element in a string:

function createElement(type) {
  return `<${type}></${type}>`;
}

Easy enough. We could add some error handling to ensure that we are only passing in valid HTML elements, but let's stick with simplicity for now. Next up is adding the attributes to our element:

function createElement(type, attributes = {}) {
  const attributeString = Object.entries(attributes)
    .map(([attr, value]) => `${attr}="${value}"`)
    .join(" ");
  return `<${type} ${attributeString}></${type}>`;
}

All we need to do is create a string where each attribute has the format: attribute="value". We can take our object and map over it's entries and then join the string we created for each. I also added a default to the attributes parameter so we don't have to pass it in every time. Easy peasy! Lastly let's deal with those pesky children. This one may be the most confusing, because many people's initial reaction would be to use recursion to handle creating the children strings, however that is already handled for us. Given the way that JS runs the most nested function call with be evaluated first so by the time we are looking at a child it has already been converted from it's function form into it's resulting string.

function createElement(type, attributes = {}, ...children) {
  const attributeString = Object.entries(attributes)
    .map(([attr, value]) => `${attr}="${value}"`)
    .join(" ");
  const childrenString = Array.isArray(children)
    ? children.filter(c => c !== null).join("")
    : children || "";
  return `<${type} ${attributeString}>${childrenString}</${type}>`;
}

Voila! We have handled our children whether there are multiple or only a single one. That's really it, that will convert our JSX into stringified HTML that can be read by VS Code as long as we use valid HTML element types. Let's convert that earlier example into nice clean JSX code and add some logic real easily:

const vscode = require("vscode");
// Even though we don't use this line it is required to be in scope
const createElement = require('./createElement.js');

export function activate(context: vscode.ExtensionContext) {
  context.subscriptions.push(
    vscode.commands.registerCommand("catCoding.start", () => {
      // Create and show panel
      const panel = vscode.window.createWebviewPanel(
        "catCoding",
        "Cat Coding",
        vscode.ViewColumn.One,
        {}
      );

      // And set its HTML content
      panel.webview.html = getWebviewContent();
    })
  );
}

function getWebviewContent() {
  const images = [
    "https://media.giphy.com/media/JIX9t2j0ZTN9S/giphy.gif",
    "https://media.giphy.com/media/VbnUQpnihPSIgIXuZv/giphy.gif"
  ];
  return (
    <html lang="en">
      <head>
          <meta charset="UTF-8">
          <meta name="viewport" content="width=device-width, initial-scale=1.0">
          <title>Cat Coding</title>
      </head>
      <body>
        {images.map(img => (
          <img src={img} width="300" />
        ))}
      </body>
    </html>
  );
}

Just like that we can write UI code just like we are used to! It is important to note that while this may feel very familiar this is not React, we are only imitating the syntax. We don't have any sort of vDOM or any kind of dynamic updating. Once the functions are run it's just a string not some fancy fiber tree that can detect changes for us. If we want the webview to be updated we are going to have to run everything over again with the updated values, and keep track of that manually. That isn't to say that any of our changes made this worse, we would have to do that anyways, it's just how the webviews are designed.

I hope this post was informative to anyone else who got annoyed writing wild template strings in their webviews. And don't forget this pattern can be used anywhere that you feel JSX might help you out, don't be afraid to experiment in your projects!

My Take on Enums in JS

Jared Jones — Sun, 14 Jul 2019 13:10:00 +0000

Have you ever found yourself writing something like this?

const PERIODS = {
  week: 'week',
  day: 'day',
  hour: 'hour',
  minute: 'minute'
};

// OR

const STATUSES = {
  pending: 0,
  inReview: 1,
  approved: 2,
  rejected: 3
};

I find myself using this pattern all the time, and see it in tons of the codebases I have worked on. It's really common to need a set of related constant values, so common in fact that many lanugages have a construct specifically to describe them: Enums. Sadly, JavaScript is not one of those languages. That is why we are left with a half-hearted alternative, these "constant object" definitions. Perhaps one day we may get enums as a build-in language feature ( enum is actually a reserved word in JavaScript), but for now we are left with what I consider: a lacking alternative.

Though I have disparaged this "constant object" pattern, I haven't explained why they are lacking, or why enums solve any of their problems. In JavaScript when specifying our object definition with const we are only prevented from reassigning the variable, not actually prevented from mutating that variable entirely. If I defined some object x using const, I could later go and modify one of its properties, add a new one, or completely delete it. When it comes to true constant values this is less than ideal. We want to avoid somewhere in our program someone coming in and taking away our "pending" status and causing all sorts of bad behavior. While safety is by far the most important feature of enums, I also believe that our "constant objects" are a bit long hand and could use some syntactic sugar to make them a bit nicer (because in the end we have to write this kind of code everyday). So I took it upon myself to try and come up with a way to get enum-like behavior in my code.

Caveat: I don't use typescript, they have enums that work great and are exactly what I am talking about. However I don't always have the opportunity to write typescript and many people don't, so I wanted something I could use in any JS project.

While I was looking at enums in other languages and fantasizing about them in JavaScript, I came across this proposal for enums in ECMAScript by Ron Buckton (This guy is a senior engineer working on TypeScript so think he knows a thing or two about enums). I really liked the proposal, it had roots in enums from Java, C++, C#, and TypeScript, and a very clear definition of the functionality. One feature I really like that was core to his proposal was the "Automatic Initialization" and the use of "auto-initializers". This means that you could determine the value that would be assigned to your enum by simply specifying the initializer you wanted to use, it looks like this:

enum Colors of Number {
  red,
  green,
  blue
}

enum PlayState of String {
  idle,
  running,
  paused
}

This seemed like a perfect method of removing the clunky object key/value syntax used in the "constant objects" pattern. Rather than have to directly specify the value of your enum it could be implied. Now obviously, any tool I could write wouldn't have all of the niceties of specialized syntax like the proposal (without me having to go to the extraordinary lengths of writing a full blown babel plugin or something). So I decided on a semi-functional looking approach where I could pass in the initializer function to set up my enum creator and then pass in my enum definition into that creator. Let's look at what my original examples would look like in the syntax I was dreaming up:

const PERIODS = enums(string)('week', 'day', 'hour', 'minute');
const STATUSES = enums(number)('pending', 'inReview', 'approved', 'rejected');

This format gives the tool a lot of power and potential for growth. The auto-initializer function (like string and number) passed into enums is designed to work just like a mapping function you would pass into Array.prototype.map. As long as an initializer returns a value for each enum passed to it, the tool will create an enum with that value. An initializer function is provided the current enum value as well as the previous value assigned: function initializer(currentEnum[, previousValue]) {} this allows you to modify the given enum or increment based on the last value. Hopefully this initializer API is robust enough to allow for large amounts of customization, so your specific use-case can be packaged and reused. Both number and string auto-initializers are bundled into the core package. Here are the implementations for both string and number:

function string(en) {
  return en; // Super simple, we just return the given enum string
}

// number is the default initializer, if you don't pass anything in to `enums` it uses this function
function number(en, prevVal) {
  return prevVal !== undefined && prevVal !== null ? prevVal + 1 : 0;
}

To show a custom example, an initializer that returns a capitalized string value of the given enum key might look something like this:

function capitalize(enm) {
  return enm.charAt(0).toUpperCase() + enm.slice(1);
}

Obviously not every case is so cut and dry, sometimes we want custom values for each enum that don't map cleanly based on the enum string. To handle this the tool provides support for an override syntax to allow directly specifying the values rather than relying on auto-initialization. This ends up requiring the user to pass in a full JS object from which the enum will be constructed:

const COLORS = enums()({ red: '#f44242', green: '#27c65a', blue: '#003bff' });

At this point you might be asking: "Why use this tool if I am just going to be writing an object anyways? Now it's even longer to type!". Here is where those natural benefits of safety come in, let's dig into the implementation a bit.

Enums Implementation

Here is the implementation of the enums tool, it's only 39 lines:

function enums(initializer = number) {
  function generator(...args) {
    if (!args || !args.length) return undefined;
    const enums = args.length > 1 ? args : args[0];
    let en = {};
    let pv;

    if (Array.isArray(enums)) {
      for (let val of enums) {
        const v = initializer(val, pv);
        pv = v;
        en[val] = v;
      }
    } else if (typeof enums === "object") {
      for (let val of Object.entries(enums)) {
        const key = val[0];
        const value = val[1];
        if (!value || Array.isArray(value) || typeof value === "object") {
          const v = initializer(key, pv);
          pv = v;
          en[key] = Object.freeze(v);
        } else {
          en[key] = Object.freeze(value);
        }
      }
    }

    giveMethods(en); // Not showing this method definition for conciseness, check out Github for the 'full' source

    return Object.freeze(en);
  }

  return generator;
}

You may have noticed the use of Object.freeze, this is how we can attempt to guarantee immutibility and safety of our enum implementation. Object.freeze will prevent properties from being added or removed from our underlying JS object by "[failing] either silently or by throwing a TypeError exception"*. It will also prevent values from being changed, "the writable and configurable attributes are set to false..."*. With freeze and const we are able to emulate object immutability to ensure our enums aren't modified by us or another developer. Freeze does have it's limitations, it can only freeze one level deep in an object. In the implementation not only is the top level "enum" object being frozen but any custom defined values are being frozen at the top level as well. This means that if you are assigning your enum values to nested objects the nested object is still in danger of being mutated. Make sure when doing this that you "deep freeze" your objects before assigning them to an enum. Deep freezing was left out of this implementation as the use of deeply nested objects isn't a pattern I see often, but I wanted to be sure to point it out for anyone that might have that use-case.

* Quotes from linked MDN docs on Object.freeze

Along with the safety of immutability Ron Bucktons enum proposal defined a set of methods allowed on an enum type.

let Enum: {
  keys(E: object): IterableIterator<string | symbol>;
  values(E: object): IterableIterator<any>;
  entries(E: object): IterableIterator<[string | symbol, any]>;
  has(E: object, key: string | symbol): boolean;
  hasValue(E: object, value: any): boolean;
  getName(E: object, value: any): string | undefined;
  format(E: object, value: any): string | symbol | undefined;
  parse(E: object, value: string): any;
  create(members: object): object;
  flags(descriptor: EnumDescriptor): EnumDescriptor;
};

Rather than include a global Enum object in the package with methods, the methods can be called directy on your enum:

const PERIODS = enums()('week', 'day', 'hour', 'minute'); // auto-initialized to 'number'

PERIODS.keys() // ['week', 'day', 'hour', 'minute']
PERIODS.values() // [0, 1, 2, 3]
PERIODS.entries() // [['week', 0], ['day', 1], ['hour', 2], ['minute', 3]]
PERIODS.has('month') // false
PERIODS.hasValue(0) // true
PERIODS.getName(0) // 'week'

The initial reasoning behind including the methods on the enum created (and break from the proposal format) was for ease of use, since a true global object can't be created for Enum you would have to import that as well when you wanted these helper functions. I'm still not certain if this was the correct choice for the tools API, hopefully with continued use and some community testing this implementation can be finalized with an API that works best for it's users.

Conclusion

I love enums, and really wish we could have a true enum in JavaScript without having to use TypeScript. However for now this little tool will hold me over, and I hope it piques your interest too! You can install fun-enums with npm or yarn and start using it today in your projects. The package is a mere 807 bytes minzipped, with zero dependencies, and tested with above 95% code coverage! Feel free to leave comments or problems as issues on the github repository, thanks for reading!