Forem: Toby Parent

A Simple Observer in Vanilla Javascript

Toby Parent — Sun, 15 Oct 2023 19:39:19 +0000

(Photo by Jennifer Uppendahl on Unsplash )

This one is going to be a bit involved, as I view it as an interim step to a much larger conversation about design patterns in general, and how they're all around us. We use them all the time, both in programming and in life, and we take them for granted.

Design patterns, as the development community knows them, evolved from conversations between four developers often referred to as the Gang of Four. They saw issues in the Object-oriented programming world, and saw that a formal description of useful patterns could help the "maturing" of development as a whole.

Some of the patterns are creational (dealing with the construction or creation of data), while some are structural (dealing with how different things might be related or connected, and how we define them as parts of a system), and a third group are behavioral (defining ways that communication between things might be handled efficiently or effectively).

The one I want to talk about here is a behavioral pattern. It is all about defining how a particular type of communication might be handled between objects, while keeping them as decoupled as possible. When I talk about "decoupling", I mean that each piece works in its own right, each doesn't need to be aware of the other, each just works - but they can communicate, in clean ways.

Observers in the Real World

We encounter observers all the time, they're things we use often without even thinking about how they work.

Alarm clocks: we have these little things that are watching the time, all the time. And when the time being watched matches the time we've set, they buzz or the radio goes off or the electro-shock collar zaps. Or is that last only me?
Motion-sensing lights: we have these little things we've mounted outside our homes or places of business. They watch the lot or the given area, all the time. And when the area being watched indicates some movement, the light turns on or the siren goes off or the electro-shock collar... you get the idea.
Traffic lights: we have these lights posted at street intersections, and they turn colors. And as we're driving, we watch these lights as we pull up. If they turn certain colors, we alter our speed appropritately.

So each of these have something in common: there is some sort of state, some default thing that is being watched for some sort of change. And, when that change occurs, some functionality is run based on the current state.

In the case of the clock, the time represents the state, and when the observed time matches that of the set alarm, an alert functionality is triggered.

In the case of the motion-sensors, the lot is the state. Something moves in the lot, the motion sensor sees the state change, the lights come on.

In the case of the traffic lights, the light itself is the state. When that light changes, certain behaviors on the part of motorists observing that light is triggered.

Observers You May Already Know

If you've been programming in javascript for a bit, and you've started working with the DOM, then you've already likely encountered observers. Here's a very common one:

const getDetailsOfMovie = (event)=>{
  const clickedMovieID = event.target.dataset.id;
  if(!clickedMovieID) return;
  // maybe we fetch the details of a given movie title,
  // based on that id. Maybe we add it to a shopping cart.
  // We do something with it, anyway:
  console.log(clickedMovieId);
}
const moviesContainer = document.querySelector(".movies-container");

// and we attach the function as the event handler:
moviesContainer.addEventListener("click", getDetailsOfMovie);

So that getDetailsOfMovie is the behavior we want to happen when the given DOM element is clicked. So the DOM itself is the thing we're using as our state here, and the Events API is triggering all sorts of things for a great many events occuring around that DOM.

This is an Observer (or an Observable. In particular, this is an application of the observer referred to as Publish/Subscribe (or PubSub).

The Events API is responsible for triggering a great number of events around the DOM, bubbling and capturing those events, and calling the functions we've provided. We are subscribing to the events that the Events API publishes.

Further, when that "click" event happens and our function is run, Mozilla tells us exactly what our function will be provided, in the Event object. So not only is our function run, but its also provided with useful information about that state change (the click, the keyboard event, the scroll).

Observers Are Not Standalone

We aren't likely to have an Observer in isolation. It might be in the context of some other design - Creational patterns might contain observers within them. For example, the DOM is a creational structure with a great deal of other functionality, as well as this observer behavior.

We can do much the same. We can create our objects, using any creational or structural design we like, and we can incorporate the observer pattern in. To do so, let's consider a useful example of how this might work.

The Scenario

Suppose we are working on an email app. We might have a page displayed with a sidebar listing the various folders in which we collect our emails, and when we click on a folder, we want to list out the emails associated with that folder. Further, when we click on one of the emails in that listing, we want to see the details of that email. This is mostly to give us a visual of what we're considering, but the consideration here isn't really about the DOM, so much as it's about the state data that drives the DOM.

What do I mean by this? When we click on one of the folders in the sidebar, we are telling our app "this is the currently-selected folder." In other words, we are altering the state of the app in some way, by specifying a selectedFolder or some such.

But the thing is, when that folder is clicked and that selectedFolder state value changes? We also want other things to happen. We want to update the DOM, we might want to persist some stored value (so when the user re-opens the app, they see the same place they left off), we might play a noise or do some other effect.

The issue is, if we simply do

listOfFolders.addEventListener("click", (e)=>{
  selectedFolder = e.target.dataset.folderid;
})

we might set that variable, but the rest of our app has no way of knowing about that. It has no way of saying "Hey, this thing has updated, I better do something-something."

But remember, we're talking about Observers. We can create an Observable thing, and we can define ways of telling that thing itself "Hey, when your value changes, do something-something on our behalf." In much the way the Event API triggers when an event happens (when the state of the DOM is somehow affected), we can define triggers when our own state changes.

Exploring an interface

The way we work with an Observable should really be as simple as possible. It is a container, and it should be able to contain anything. And we want to be able to pass it functions, in order to run them for us when the contained value changes.

So let's define that interface, as simply as we can:

Observable {
  get value,
  set value,
  subscribe,
  unsubscribe
}

That's pretty much it. A .value getter and setter to define or retrieve the stored value, and methods to add or remove a "subscriber" or listener method.

Incidentally, if we were to look at this from the React-type model (which is way more robust, way more structured and probably way better than this), our getter and setter are akin to the useState hooks, and the subscribe and unsubscribe are similar to the useEffect hooks in that they cause a "side effect" whenever the subscribed value changes.

Not exactly the same, but similar in intent and what I'd consider "the lazy man's implementation."

Starting Steps

Simply because I like 'em, we will define this as a closure. We could as easily do this with a class, and it would work in much the same way, but I like the whole private variable scope thing. So let's start by defining our core Observable:

const Observable = (initialValue) =>{
  let value = initialValue;

  return {
    get value(){ return value;},
    set value(val){ value = val; }
  }
}

There we go. A container. We can use that like this:

const myName = Observable('Toby');

// accessing the getter
console.log( myName.value ); // 'Toby'
// accessing the setter
myName.value = 'TobyPlaysTheUke';
// accessing both
myName.value = myName.value.toUpperCase();

It works - it simply stores something inside itself, and we can replace that as we like. Note that while I defined it as a const, it is the Observable container that is a const, and not the value it contains.

I had asked a friend (and someone way smarter than me) to proof this, and to make suggestions (Thanks, Morgân!). Some of them I have listened to (and I'll note them when we encounter them), and some I have listened to but still gone with what I prefer. This is one of those pivot points: a closure, or a constructor?

She presents valid points: why not simply make it a constructor function, make the value a property (or even a property getter), thus allowing for the new keyword and for things like instanceOf Observable. And we could do that, it would be a small change, wouldn't really break anything, but I tend to have a kneejerk reflex where constructors and classes are concerned, largely due to the this thing. It is very easy, in implementing a constructor, for this to shift unexpectedly. That said, it isn't terribly difficult to remake this as a constructor function, and I'll include Morgie's at the end, for further exploration.

And the value can be anything:

const myTodo = Observable({
  title: 'Make breakfast',
  description: 'No idea what',
  priority: 'normal',
  dueDate: Date.now(),
})

myTodo.value = {
  ...myTodo.value,
  description: 'I feel like a fat-boy sammich!',
}

Works fine, it's clean, it does the job. But as I look at that, I'm seeing something that might make more sense: rather than defining a setter, and giving the user the idea that they're simply setting a value, we might change that a bit - if we explicitly define an update method, for example, it makes plain that we aren't simply setting a value, but that we're initiating a process of updating. Also, with an update, we might be able to provide options - if the user passes a function to update, we could run that function with the current value, but if the user passes something else, we simply replace the value we're storing.

So we will still have a getter, simply for convenience, but let's define an update method:

const Observable = (initialValue) => {
  let value = initialValue;

  const update = (updater) => {
    if(typeof updater === 'function'){
      value = updater(value);
    } else {
      value = updater;
    }
  }
  // shorthand of the same thing, for those who like that stuff:
  // const update = (updater) => _ = typeof updater ==='function' ? updater(value): updater
  return Object.freeze({
    get value(){ return value; },
    update,
  })
}

And to use this version, we could:

const myName = Observable('Toby');
myName.update('tobyPlaysTheUke');
myName.update((oldVal)=>oldVal.toUpperCase());

The first .update is simply overwriting the stored value, the second runs the function we've passed in and replaces the stored value with the return.

And with a stored object?

const myTodo = Observable({
  title: 'Make breakfast',
  description: 'No idea what',
  priority: 'normal',
  dueDate: Date.now();
})

myTodo.update((oldVal)=>({
  ...oldVal,
  description: 'How about fat-boy sammiches?',
}))

So we aren't explicitly extracting and replacing the value, we are simply providing a function that our Observable runs for us. Gives us some flexibility, and might be a bit more useful later.

Okay, so what?

Yeah, at this point, it isn't much more than a glorified variable. We are storing a value, and we are retrieving it. We have that .update method, great and good, but it still just sets a value. What's the benefit?

That was setting the groundwork. Now the fun can begin! What we want now is to define the rest of the interface. If we go back to thinking about event listeners, we'll implement one similar to the Event API:

addEventListener <=> subscribe
removeEventListener <=> unsubscribe

As we might already be comfortable with the way we add and remove event listeners, we can add and remove subscribers in the same way!

We'll need an array of subscriber functions, and when we .subscribe we simply add one. To .unsubscribe we need to pass in the original function reference, and we filter that one out, keeping all the others.

const Observable = (initialValue) => {
  let value = initialValue;
  let subscribers = [];

  const subscribe = (subscriber) => 
    subscribers = [...subscribers, subscriber];

  const unsubscribe = (subscriber) => 
    subscribers = subscribers.filter(fn=>fn!==subscriber);

  const update = (updater) => 
    value = typeof updater === 'function' ?
      updater(value) :
      updater

  return Object.freeze({
    get value(){ return value; },
    update,
    subscribe,
    unsubscribe,
  })
}

This was another spot she was kind enough to point out I'm an idiot. Those subscribe and unsubscribe methods work, but there is an unintended side effect. Because I've used a single-line fat-arrow function, they are returning the result of those single lines: basically, I'm exposing all my subscribers each time.

To fix this, we might look to what adding to an array or removing from an array should do: when we push onto an array, we are given the length of the array, and when we remove an array... well, let's do the same, return the array's length.

She also asked why I wasn't simply .push()ing the subscriber on, and I could, really - we never expose the array, so we can. Normally, because I'm becoming a huge fan of treating data as immutable, I prefer creating a new array each time, but here it really doesn't matter. So those changes will give us this:

// this will simply return the new length of subscribers
const subscribe = (subscriber) => 
  subscribers.push(subscriber);
// as will this. 
const unsubscribe = (subscriber) => {
  subscribers = subscribers.filter( fn=>fn!==subscriber);
  return subscribers.length;
}

There we go. We can define a value, update that value, subscribe and unsubscribe to our Observable. The only thing we haven't yet implemented is triggering the subscribed functions when the value changes.

By defining that .update function, we have really limited the ways the user can play with the value internally. So long as they are calling .update, we know we want to run each subscriber.

We need to think, though: what information does that subscriber need to know from us? When we run those actions later on by proxy, what should we be telling those functions?

We know we'll need to tell it about that new value, but might it also be useful to provide the old one? By doing that, if the subscriber is performing some "delta function" or a "the value has changed by N", we can help with that. Let's use that as our baseline, and see where we get in changing that .update method:

const Observable = (initialValue) => {
  let value = initialValue;
  let subscribers = [];

  const subscribe = (subscriber) => 
    subscribers.push(subscriber);

  const unsubscribe = (subscriber) => { 
    subscribers = subscribers.filter(fn=>fn!==subscriber);
    return subscribers.length;
  }

  const update = (updater) => {
    // we store the value as it is, and then we update.
    let oldVal = _;
    value = typeof updater === 'function' ?
      updater(value) :
      updater;

    // next, we call each subscriber function with both!
    subscribers?.forEach((subscriber)=>subscriber(value, oldVal))
  }

  return Object.freeze({
    get value(){ return value; },
    update,
    subscribe,
    unsubscribe,
  })
}

Now, each time we call .update with any value, whether a function or not, we run each subscriber with a before and after value. Neat!

Going back to go forward

Remember the original scenario? That selectedFolder thing in our email app? How might this Observable help us in that case?

Our state here is the selectedFolder, so let's define that:

const selectedFolder = Observable('');

We'll imagine each folder has an id, and that that value is a string of some sort. So that container simply holds the id of the selected folder, neat and tidy.

But when the value changes, we might want to trigger a couple functions:

const showInConsole = (newValue, oldValue) =>
  console.log(`Switched from ${listOfFolders[oldValue]?.name} to ${listOfFolders[newValue]?.name}`);

const updateEmailListPane = (newValue) => {
  // more complex, this simply takes the new id, gets the folder
  const currentFolder = listOfFolders[newValue];

  // and likely runs some DOM updating for us based on that.
}

selectedFolder.subscribe(showInConsole);
selectedFolder.subscribe(updateEmailListPane);

Now, any time selectedFolder's stored value changes, those two functions will run for us.

foldersPanel.addEventListener("click", (e)=>{
  if(e.target.classList.contains('folder-name')){
    // a click on a folder updates the observable
    selectedFolder.update(e.target.dataset.id)
  }
});

That would log both the old and new folder's names, assuming we had any, and would also update the list of emails displayed.

Well yeah, but... why??

The advantage here is that we can set the Observable value without explicitly needing to trigger those other functions, without needing to know they exist. Those functions don't need to be informed about possible places where updates might happen.

We have decoupled the actions and the values on which those actions depend. We use the Observable to connect them, it acts as a manager between them, but the value and the listeners are able to be defined and maintained separately.

We can define DOM methods, as we did with the event listener on foldersPanel, that update our Observable - and that will simply run whatever subscribed methods we have given that without the Event API needing to run them directly.

Okay, so mostly this was a thought experiment, and something I think might be useful if overly simple. But tell me.... what do you think?

Extra Credit

So it is a weird thing, to have to keep the reference to the original function like that in order to unsubscribe it. It means we can do things like:

selectedFolder.subscribe(logToConsole);

// and later
selectedFolder.unsubscribe(logToConsole);

so long as we have a reference. But we can't do something like this:

selectedFolder.subscribe((newValue, oldValue)=>console.log(`folder switched from ${oldValue} to ${newValue}`));

// okay so how might we unsubscribe that?

The argument goes, if we are defining an inline anonymous function, we aren't planning on unsubscribing it. But that is an opinion that perhaps isn't the domain of our Observable to decide.

So suppose we wanted to make it different? Suppose we made it so that, when we subscribe to a thing, the action of subscribing returns a readymade unsubscribe method? So we could do something like:

const unsubscribe = selectedFolder.subscribe( (newValue, oldValue) => console.log(`folder switched from ${oldvalue} to ${newValue}`));

window.addEventListener("unload", ()=>{
  unsubscribe();
})

So the subscribe method itself gives us back what we need. Can you see how you might implement that, based on the fact that subscribe creates a closure within our Observable? What might that look like?

Message in the comments, or find me on the Odin Project Discord group and let's talk about it!

For those who are looking for the constructor-based version of this, who would like to be able to simply do:

const myCoords = new Observable({
  x: undefined,
  y: undefined
});

Here's how that might work, thanks to Morgân von Brylân (a helpful human I met in the Javascripters | Web Development, Node.js, TypeScript and more Discord:

function Observable(initialValue) {
  let value = initialValue;
  let subscribers = [];

  Object.defineProperty(this, "value", { get: () => value });

  this.subscribe = (subscriber) =>
    subscribers.push(subscriber);

  this.unsubscribe = (subscriber) => {
    subscribers = subscribers.filter((fn) => fn !== subscriber);
    return subscribers.length;
  }

  this.update = (updater) => {
    // we store the value as it is, and then we update.
    const oldVal = value;
    value = typeof updater === 'function' ?
      updater(value) :
      updater;

    // next, we call each subscriber function with both!
    subscribers.forEach((subscriber)=>subscriber(value, oldVal));
  }

  Object.freeze(this);
}

Templating with TinyBase, Tailwind, and RippleUI

Toby Parent — Mon, 20 Feb 2023 22:23:17 +0000

In the last section, First Steps With TinyBase, we built the data models we would need to support the front end of a Todo app. We will come back around to those. At this point, it might make sense to set up a "template view", one that sets up our sections/containers.

For ease of use, we'll continue with Vite and TinyBase, but we'll also add in two more packages: Tailwind CSS and RippleUI. For those who haven't used it yet, Tailwind CSS is a great utility package that will allow us to style directly in our HTML, by applying classes to elements. And RippleUI is a component framework that builds on Tailwind. So together, they're a powerful team.

In addition to building the basic site itself, we'll also work with some features of TinyBase that will be very useful both here and going forward. We will set up some values in TinyBase, rather than the tables we used in the last section. We will set up persistence, allowing the TinyBase store to save/load localStorage as needed.
And finally, we'll explore listeners and reactivity in TinyBase, allowing us to listen to change events on a store and respond accordingly.

Some Setup Stuff

First, we'll add in the packages we'll need. Let's begin with an entirely new Vite project:

npm create vite@latest app-skeleton --template vanilla 
// OR
yarn create vite app-skeleton --template vanilla

Going forward, I'll be using yarn, but take as given that you can use npm if you prefer. Next, we'll install the packages so far and add in TinyBase:

cd app-skeleton
npm install tinybase

That installs the existing packages, as well as adding TinyBase. Next, we will get Tailwind CSS and its dependencies (taken from https://tailwindcss.com/docs/guides/vite):

yarn add tailwindcss postcss autoprefixer -D

WIth the modules added, we can create the tailwind.config.cjs and postcss.config.cjs:

npx tailwindcss init -p

That will set up two files for us in the root of our Vite project. We'll need to tell Tailwind's JIT parser where to work, so we'll edit the tailwind.config.cjs first:

// tailwind.config.cjs

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    // add in these two lines
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
  ], 
  theme: {
    extend: {},
  }, 
  plugins: [], 
}

We don't need to add the ts,jsx,tsx options at this point, but if some of you are working in Typescript, you might want them.

Next, we need to edit the postcss.config.cjs, just to be sure it's set up properly. If you left the -p option off the npx tailwindcss init, you won't have that file, so you'd just need to create it yourself. Either way, make sure it contains:

// postcss.config.js

module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  }
}

Finally, we need to tell Vite to go ahead and bring in the Tailwind classes. In our style.css, we place this at the top:

@tailwind base;
@tailwind components;
@tailwind utilities;

At that point, we have tailwind all set up and ready to go. Let's also add in RippleUI at this point:

yarn add rippleui

With the package installed, we need Tailwind to be made aware of it. So we go back to the tailwind.config.cjs and add a plugin:

// tailwind.config.cjs

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {},
  },
  // EDIT THIS LINE
  plugins: [require('rippleui')],
}

With that done, we should be good to go. At this point, we can start the dev server and begin playing!

npm run dev
// OR
yarn dev

One more thing to include, simply to create icons quickly and easily: open up the index.html, and we'll add a link to Bootstrap Icons via CDN:

<link rel='stylesheet' href='https://cdn.jsdelivr.net/npm/bootstrap-icons@1.10.3/font/bootstrap-icons.css'>

We could as easily have added this via npm or yarn, do what works for you.

A Handy Utility Snippet

We'll need an easy way of converting strings to DOM trees, as we will be wanting to construct and style some pretty complex DOM nodes. David Walsh writes about a very useful method for just this (https://davidwalsh.name/convert-html-stings-dom-nodes), which we'll leverage into a toHtml method:

// src/util/toHtml.js

const toHtml = (str)=>document.createRange()
  .createContextualFragment(
    str.trim()
  ).firstChild;

export default toHtml;

This will take in an HTML string and convert it into a DOM tree for us. This can become powerful, as we aren't obligated to provide static strings - we can use template literals as we like, and dynamically create our DOM!

const getTimeEl = ()=> toHtml(`
<span class='time'>${new Date().toTimeString()}</span>
`)

That function will dynamically update the template literal, and create a new <span> containing the current time for us.

I'll be using the toHtml function quite a lot, for building and populating templates.

A Header Template

// src/templates/header.js
import toHtml from "../util/toHtml";

const Header = toHtml(`
<header >
  <h1>App Title</h1>
  <div class='header-controls'>
    <div class='light-switch'>
      <i class="bi-brightness-high"></i>
    </div>
  </div>
</header>`);

export default Header;

So the HTML here is pretty straightforward, and at this point, we have three classes included: header-controls, light-switch and bi-brightness-hight. The last one is a Bootstrap Icons class, showing a circle with rays. The first two are ones we will hook into later - the .light-switch will be used for toggling between light and dark mode.

But we'll want to add in some Tailwind classes to pretty things up:

import toHtml from "../util/toHtml";

const Header = toHtml(`
<header class='flex justify-between px-3 py-2'>
  <h1 class='inline-block text-3xl font-black text-indigo-800 p-6'>App Title</h1>
  <div class='header-controls'>
    <div class='light-switch text-3xl font-black text-secondary'>
      <i class="bi-brightness-high"></i>
    </div>
  </div>
</header>`);

export default Header;

And finally, I would like that .light-switch to display as a button. Things like this are why I've added RippleUI:

    <div class='light-switch btn btn-outline-secondary text-3xl font-black text-secondary'>
      <i class="bi-brightness-high"></i>
    </div>

So I added the btn btn-outline-secondary classes to the .light-switch, and the RippleUI button styles will be applied.

... And a Layout Template

For the layout, I would like to have a sidebar and a main content area. Also, simply because we can, we'll make that sidebar collapsible.

import toHtml from "../util/toHtml"

const Layout = toHtml(`
<main class='container flex'>
  <div>
    <input type='checkbox' id='drawer-left' class='drawer-toggle' />
    <label for='drawer-left' class='btn btn-secondary'>
      <span class='bi bi-list font-black text-xl'></span>
    </label>
    <label class='overlay' for='drawer-left'></label>
    <div class='drawer'>
      <div class='drawer-content'>
        <label class='absolute top-4 right-4' for='drawer-left'>
          <span class='bi bi-x-circle text-secondary font-black text-xl'></span>
        </label>
        <p>Sidebar Content</p>
      </div>
    </div>
  </div>
  <div class='main-content'></div>
</main>`);

export default Layout;

In the <main>, we have two divs: one for the sidebar, and one for the remaining content. The sidebar is a bit more complex, as it does have some moving parts - all of which are being managed and defined from RippleUI. The class="drawer-toggle" applied to the input hides it, but also sets up the toggle functionality for the sidebar as a drawer component.

Now, if we revisit the index.html, we have something like this:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>TobyPlaysTheUke :: Template App</title>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.10.3/font/bootstrap-icons.css">
  </head>
  <body>
    <div id="app" class="w-full h-full"></div>
    <script type="module" src="/main.js"></script>
  </body>
</html>

I've added the class="w-full h-full" to the app container, simply so that it is forced to the full screen size.

Composing the View

In our main.js, we will import those templates, and we'll drop them in:

// main.js

import "./style.css"

import Header from './src/templates/header';
import Layout from './src/templates/layer';

document.querySelector("#app").append(Header, Layout);

And, at this point, the page should be set. The hamburger menu opens an empty sidebar, the header content displays as we like, but we haven't set up the responsivity yet - we can't click the light switch. Let's work on that next!

Getting Back to TinyBase

There may be other site configuration we want to do later, so we will set up a second TinyBase data store, leaving the one from the last lesson alone. It will still be set up as a service, like so:

// src/services/config.js
import { createStore } from 'tinybase';

const configStore = createStore();

export default configStore;

Now, we want to not only switch between dark mode and light, but we want that choice to persist. Fortunately, TinyBase comes with a great localStorage interface that we'll consume, createLocalPersister:

// src/services/config.js
import { createStore, createLocalPersister } from 'tinybase';

const configStore = createStore();
const configPersister = createLocalPersister(configStore, 'siteConfig')

export default configStore;

createLocalPersister takes two parameters: the store we want to persist, and a key for localStorage . With that, our configPersister is ready to run.

As I mentioned, later we might want to add more user-configurable values (color preferences, position of components, whatever). At this point, we only have one property we'll want to deal with, which I'll call colorMode. In order to make this updateable later, we can create a defaultConfig.json file. Doing that, we can have a set of defaults if the user hasn't specified one:

// src/defaultConfig.json
{
  "colorMode": "light"
}

We'll default to light mode for now. But how do we tell our configStore to use that? Further, we don't always want to use that - we only want to use that if there isn't a value in the localStorage yet!

Fortunately, TinyBase has us covered. We can tell the configPersister to start saving/loading automatically any time a value is changed, and we can provide a default for the autoload! Let's see how that works:

import {createStore, createLocalPersister} from 'tinybase';
import * as initialConfig from '../defaultConfig.json';

const configStore = createStore();
const configPersister = createLocalPersister(configStore, 'siteConfig');

configPersister.startAutoLoad( {}, initialConfig );
configPersister.startAutoSave();

export default configStore;

So we call configPersister.startAutoLoad(), passing in two parameters. The first would define the tables we'd want to default to, and the second is the values object we want as our defaults. We aren't using tables here at all, so I've passed in an empty object, but for our values, I pulled the defaultConfig.json into a variable, initialConfig.

That will check localStorage for the "siteConfig" key and, if it exists, populate the configStore from that. If localStorage doesn't have that key, it will use the initialConfig to set the store's values for us.

And then we call configPersister.startAutoSave() - and this will automatically write our store back into localStorage any time anything changes. That's it for the configStore, let's jump back to main.js and see how we might consume this!

Updating the Color Theme

The way Tailwind and RippleUI handle dark mode, we want to set a data-theme attribute and color-scheme style on the <html> tag. But what do we want to set them to? Well, we have the configStore defined for exactly this purpose:

// main.js
import "./style.css";
import configStore from './src/services/config';

import Header from './src/templates/header';
import Layout from './src/templates/layout';

const setColor = () =>{
  document.documentElement.dataset.theme = configStore.getValue('colorMode');
  document.documentElement.style.colorScheme = configStore.getValue('colorMode');
}

setColor();

document.querySelector('#app').append(Header, Layout);

So we're setting the documentElement.dataset.theme, which is the <html> tag's "data-theme" attribute, to the current value of configStore.getValue('colorMode') - which by default is "light". And we do the same to the inline style element. If you examine the <html> element in the Dev Tools > Element Inspector, you'll see those attributes now set.

Wiring the Light Switch

Now, in the Header, we included a ".light-switch" element. When that is clicked, we want to update the configStore, flipping it from "light" to "dark" or vice versa.

// main.js

const setColor = () =>{
  document.documentElement.dataset.theme = configStore.getValue('colorMode');
  document.documentElement.style.colorScheme = configStore.getValue('colorMode');
}

setColor();

document.querySelector('#app').append(Header, Layout);

Header.querySelector(".light-switch").addEventListener("click", (e)=>{
  configStore.setValue(
    'colorMode', 
    configStore.getValue('colorMode')==='dark' ?
      'light' :
      'dark'
  );
  e.currentTarget.querySelector("i").classList.toggle("bi-brightness-high");
  e.currentTarget.querySelector("i").classList.toggle("bi-moon-stars");
})

so the configStore.setValue() is being changed based on its current value. If that value is "dark", we set it to "light". Otherwise, we set it to "dark". At the same we can toggle the light mode and dark mode icons, flipping the icon to match the theme.

But we've flipped the configStore, and we've switched the button - we haven't yet changed the page itself. This is where we explore reactivity in TinyBase.

Responding to Changes

We've got everything set, and we could have simply called setColor from within the event listener for the switch - but what if we wanted to add other functionality, other side effects, when the colorMode changes? We would either have to go back to the lightswitch method and keep adding more mess there, or we need to be able to observe and respond to changes.

Fortunately (again), TinyBase comes to the rescue with a full suite of responsivity methods! Here, we only need one: we're listening to one particular value, "colorMode", and we want to respond any time that one value is altered.

Looking at https://tinybase.org/guides/the-basics/listening-to-stores/, we can see that there are many ways we could listen to a store. We can listen for changes to any one or all values or value id (think the "key" for that value), as well as any or all tables, table rows, or cells, or any of their id values. If any of that changes, we can listen to whatever level of granularity we might need.

For this, we can get away with simplicity: we are only responding based on the change of a particular value: "colorMode". So to listen to that, we add this last line:

configStore.addValueListener("colorMode", setColor)

That will call the setColor method each time the colorMode value changes in the store, toggling the page itself between light mode and dark.

To Recap

Again, this is a simple reactive use, we could do considerably more with it (and in the next lesson, we will get reactive with tabular data). But we've set up a pretty solid skeleton project here, and one that I have published as my repo template. In this, TinyBase may seem like a small part, but the significance of not having to deal with localStorage, with having default values, and with reactive listeners is significant.

The repo, which is also my template repo, is available: https://codeberg.org/tobyPlaysTheUke/vite-tailwindcss-rippleui-vanilla-template/src/branch/main

First Steps With TinyBase

Toby Parent — Thu, 16 Feb 2023 15:28:12 +0000

So TinyBase was one of those thing that came across my feed, and I wondered what the point was. It's a reactive client-side data store, which takes a little parsing to understand.

What exactly is a data store? Simply, it is a structure we use to store data. An array, an object, a Map, a Set... these are data stores.

What exactly do we mean by a "client-side data store"? It's a library that lets us build objects or arrays in the browser. Which, on the face of it, seems silly. We can always just create an array or object, right?

The key lies in the "reactive" bit. Not only does this allow us to construct a data store, but it allows us to respond to changes in that data store. We can observe those changes, and respond appropriately.

Reactive Data Store

What do we mean by respond appropriately? Any sort of action we might like. Think of the event listeners in the DOM, only with data.

We might want to update the DOM, say a grid of employee <card> elements, when one is added or removed. Or we might need to update the contents of a card if one is edited.
We might want to store data locally when a change happens (localStorage, sessionStorage or IndexedDb). Tinybase provides for that.
We might want to handle some remote call, say passing a message to a Socket.
We might not want to store data locally - when something changes, we might want to handle that change via a debouncer, so when the user stops editing for a given period, we handle a remote save request. While Tinybase provides for the remote storage, we would write our own debouncer.

Note that last, it is one of the strengths of this library. It doesn't dictate how we might use it or encapsulate it or consume it, it simply does this one thing, and does it quite well.

Note that TinyBase actually provides two storage mechanisms: we can store values by key, or we can store tabular data. That is, we can do either or both of these things:

// we can set key/value pairs, just as in localStorage:
const store = createStore()
  .setValue('currentProject', projectId)
  .setValue('colorMode', 'dark');

console.log(store.getValues()); 
// {
//   currentProject: '36b8f84dd-df4e-4d49-b662-bcde71a8764f',
//   colorMode: 'dark'
// }

// or we can store tabular data:
store.setTable('todos', {
  crypto.randomUUID(), {
    title: 'Look into TinyBase',
    description: 'A pretty darn okay reactive local data store.',
    priority: 'normal',
    done: false
  }
});

So with the first part of that, we defined two keys: currentProject and colorMode. We defined values for them, and we're able to use either store.getValue(key) or store.getValues() to view those things.

In the second, we are defining a row of data in the todos table in our store. Note that we didn't specify any particular ordering or columns to that table, we simply went ahead and created the object. We could (and in future parts we will) define schemas or relations between tables - this project will let us do this, and more.

It's a data store powerhouse, but it is intentionally limited to that domain. It does one thing well, without needing to do all things.

A Quick Idea...

To begin, let's consider how we might create a Todos data model, first with plain javascript and then by leveraging TinyBase.

// Todos-service.js
let todos = [];

const isAMatch = (id) => (obj) => Object.keys(obj)[0] === id;

export const add = (todoObject) => {
  const id = crypto?.randomUUID();
  todos = [...todos, {[id]: todoObject}];
  return {[id]: todoObject};
}

export const update = (todoId, todoObject) => {
  todos = todos.map( todo =>
    isAMatch( todoId)(todo) ?
      {[todoId]: {...Object.values(todo)[0], ...todoObject} :
      todo
    )
}
export const remove = (todoId) => {
  todos = todos.filter( todo => !isAMatch(todoId)(todo));
}
export const findById = (todoId) => todos.find( isAMatch(todoId) )
export const findAll = () => [...todos];

All our basic functionality for Todo things to be collected, in a nice tidy package. Later, when we want to consume it, we simply

import * as Todos from './services/Todos-service';

Todos.add({
  title: 'Learn about TinyBase', 
  descripton: 'Client-side reactive data stores!',
  due: '2023-02-17',
  priority: 'normal',
  done: false
});
console.log(Todos.findAll() );

And that's great. Let's see the same basic functionality with TinyBase:

import { createStore } from 'tinybase';
const store = createStore();

export const add = (todoObject) => {
  const id = crypto?.randomUUID();
  store.setRow('todos', id, todoObject);

  return {[id]: store.getRow('todos', id) };
}

export const update = (todoId, todoObject)=>
  store
    .setPartialRow('todos', todoId, todoObject)
    .getRow('todos', todoId);

export const remove = (todoId) =>
  store.delRow('todos', todoId);

export const findById = (todoId) =>
  store.getRow('todos', todoId);

export const findAll = () => 
  store.getTable('todos');

This is giving us all the same functionality as an array, but it is abstracting that internal array into an external data store. And if this was all we were doing with it, we really haven't gained anything.

But as a first step, we can see that, basically, the use is very similar - only rather than using array methods, we're using TinyBase store methods.

Getting Started

1. Setting up shop

To build this one, we'll use a bundler and a few packages. Of late, my preferred bundler is Vite - it is quick, clean, and minimal. So we'll open the console and:

yarn create vite vanilla-todo-app --template vanilla

That will create a directory, vanilla-todo-app, and set up the package.json and dependencies for us. Then we will cd vanilla-todo-app to get in there, and

yarn add tinybase

And that will both install the package.json, as well as adding the TinyBase package for us. If we have other dependencies we might like, we can add them - but for what we're about to do, that's everything we'll need.

At this point, we can open this in our editor. I'll be using VS Code, simply because it's fairly universal:

code .

This opens the editor with the current directory as the workspace. We will be able to clean up the template quite a bit, we don't need any of the content in the main.js, or the files to which it refers - so we can delete javascript.svg and counter.js, and remove everything but the import './style.css' from the main.js. At that point, we're ready to start!

2. Creating a Store

Now we need to create a data store. And we'll want to place it into its own file, importable by others - we might want to allow for multiple data sets (for example, we might want a "todos" and a "projects"). Let's start there.

Create a src directory to keep the root tidy, we'll work in there for the most part. Within there, we'll create a services directory.
Inside that services directory, we'll create a store.js file.

// /src/services/store.js
import { createStore } from 'tinybase';

const store = createStore();

export store;

And there we go. We have our datastore defined! At this point, that's all we'll need in the store.js, though later we'll add a few other useful things to this file.

While we could interact directly with the store wherever we might need, a better approach might be to define an interface that can consume a particular service. With that, if we choose to swap out our data provider later, it would only require editing one place rather than scattered throughout our code.

3. Defining an Abstract Model

The interface methods for each are fairly standard: add, update, remove, byId, and all will do. We'll start by defining a generic Model.js:

// src/models/Model.js
import { store } from '../services/store';


const Model = (table) => {
  const add = (object) => {
    const id = crypto.randomUUID();
    store.setRow(table, id, object);
    return {[id]: object };
  }
  const update = (id, object) =>
    store
      .setPartialRow(table, id, object)
      .getRow(table, id);  
  const remove = (id) => store.delRow(table, id);
  const byId = (id) => store.getRow(table, id);
  const all = () => store.getTable(table);

  return {
    add,
    update,
    remove,
    byId,
    all
  }
}

export default Model;

We've defined this as a factory function. To consume it, we could simply call const Todos = Model('todo'), providing it with the name of the data table we wish to use.

Now, when we are adding an object, we are getting a uuid for the project, and we are using the TinyBase setRow method to create a row in the given table.

Side note, when I refer to the projects table, it may be easier to think of the store as an object, and the projects as a key on that object that contains an array of {[id]: object} things.

When we update a project, TinyBase provides the setPartialRow method. With that, we provide a table id, a row id, and an updater object. That updater object doesn't need to redefine all the properties in our original object, only the ones we might want to update. And the setPartialRow method returns the TinyBase store instance, so we can chain that and call getRow() to get and return the updated value of our object.

To delete a row, we simply call delRow with the table and row ids.

Now, if we look at that code, there is nothing there that is unique to the Project model. In fact, it's fairly abstract - the only thing identifying it is the const table = 'projects' line. And that is deliberate.

To create the Todos.model.js, we can use the same code. Simply by changing that one line to const table = 'todos', we will be performing those same CRUD operations elsewhere in our store.

And this is a pretty good abstraction, to my mind. We can reuse this as a template for each of our data models.

4. Creating Instance Models

// src/models/Todos.model.js
import Model from './Model'; 

const Todos = Model('todos');

export default Todos;

And that's all we need at this point. We can do the same for projects:

// src/models/Projects.model.js
import Model from './Model';

const Projects= Model('projects');

export default Projects;

At that point, we have two functional tables of data we can stuff into our store service.

Let's Consider Structure

Up to this point, we haven't really considered how we should structure things. We set up a data store, we defined an interface to consume that data store, and we created a couple of basic data models. But we would do well to step back and think about how our data should be structured.

Let's examine the Todos model first, in isolation.

// Todo:
{
  [id]: {
    title: 'Default Todo Title',
    description: 'Default description',
    priority: 'normal', // ['low','normal','high','critical']
    created: '2023-02-02',
    due: '2023-02-09',
    done: false
  }
}

So note that we have that priority key, which can be one of four values. Now, if we wanted to get all the high priority todos, we could simply get them all and use .filter, but TinyBase gives us an option. This would be a good candidate for an index.

With an index, we can select all rows from a table that match a given index value. When we query the index, we get back an array of keys, all of which meet that index condition. And that array we get back is reactive - so as we add/edit/remove rows, the indexes are dynamically updating.

So we have a basic structure - the priority key will be indexed, and we want to be able to get two key pieces of information back from our Todos: all currently-used indexes, and sets of ids that meet a given index. So we'll be adding two methods to the Todos object: priorities and byPriority. The first will get an array of priority keys, while the second will get a complete list of the Todos with a given priority value.

But we're using the Model to generate the Todo.model - can we somehow add to or compose that?

We Have the Power!

We can, actually. We want to first add an export to the store service, allowing for indexing:

// src/services/store.js
import { createStore, createIndexes } from "tinybase/store";

export const store = createStore();
export const indexes = createIndexes(store);

That will let us set up an index in the Todos.model.js:

// src/models/Todos.model.js
import Model from './Model';
import { store, indexes } from '../services/store';

indexes.setIndexDefinition(
  'byPriority',
  'todos',
  'priority'
);

const Todos = Model('todos');

export default Todos;

At that point, we have defined our index column. setIndexDefinition is a method on the indexes instance, and we tell it to create an index with the id of byPriority (so we can retrieve it later), that is working on the todos table, and in particular is indexing the priority field in that table.

Extending the Data Models

In the above Todo.model.js, we now have a good index, but we aren't actually using it yet. And what we'd like to do, if possible. But what that means is, we want to take in the basic Model functionality, and add to that.

// src/models/Todos.model.js
import Model from './Model';
import { store, indexes } from '../services/store';

indexes.setIndexDefinition(
  'byPriority',
  'todos',
  'priority'
);

const Todos =(()=>{
  // our base functionality...
  const baseTodos = Model('todos');

  return {
    ...baseTodos
  }
})();

export default Todos;

So we have changed Todos from simply being an instance of our Model factory to being an IIFE that is returning all the methods of that baseTodos, which is still the instance. We're composing the functionailty from Model with some custom methods.

Within that Todos IIFE, let's add this:

  const baseTodos = Model('todos');

  // get all the todo ids associated with this project
  const priorities = () =>
    indexes.getSliceIds('byPriority');
  const idsByPriority = (priority) =>
    indexes.getSliceRowIds('byPriority', priority);
  const byPriority = (priority) =>
    idsByPriority(priority).map( baseTodos.byId )

  return {
    ...baseTodos,
    priorities,
    byPriority
  }

So we've added two methods to the Todos model: priorities and byPriority. The first gets all the currently-used priority values, while the second gets the todos themselves with a given priority.

To get the array of priority values, we use the Index module's getSliceIds method. That gets us all possible key values for the indexed cell (all the possible values for priority currently used in our data store).

The Indexes module also gives us the getSliceRowIds method, which simply gets the id for each row that meets its condition. In our case, the condition is a matching priority.

And we can leverage that in the byPriority function - we get the ids for each row, and then use those to get each individual row for the project.

Finally, we spread the ...baseTodo object, exposing its methods on the Todos returned object as references to this inner baseTodos thing. And we compose that interface, by adding two more methods to the Todos returned object.

Indexes vs Relationships

The next bit of structuring to consider is the relationship between the Project and the Todo. Each thing has a unique id assigned to it, and that is used as the key of its row in the data table.

And a project can contain any number of todo elements, but each todo can only belong to one project. This is, in relational database terms, a one-to-many relationship.

Typically, in a relational database, we might give the Todos.model a field for the projectId, some way of identifying with which project it is associated. So, for example, to find all the Personal project's todos, we could select all the todo elements with that projectId.

So note how, in the model of the Todo, we show a projectId:

// Project:
{
  [id]: {
    title: 'Default Project Title',
    description: 'Default Description',
    created: '2023-02-02',
  }
}

// Todo:
{
  [id]: {
    projectId: [projectId], // <-- the key from `projects`
    title: 'Default Todo Title',
    description: 'Default description',
    priority: 'normal', // ['low','normal','high','critical']
    created: '2023-02-02',
    due: '2023-02-09',
    done: false
  }
}

Indexes vs. Relationships:
We discussed indexes above, and now we're discussing relationships. They are similar, and if you've worked with relational data, you may likely already know the difference, but here it is in a nutshell:

indexes are used within the context of a table, to facilitate searching for a particular property value within that table (for example, priority==='high').

relationships are used within the dynamic of multiple tables, indicating a connection between one (a local table) and the other (the remote). In this case, the relationship would be todo.projectId === project.id. We're still comparing to something - but with indexes, we're typically getting information about a table while a relationship is giving us information about multiple tables through a common point.

In order to support relationships between data tables, we will need to provide the Relationships module:

import { 
  createStore,
  createIndexes,
  createRelationships  
} from 'tinybase';

export const store = createStore();
export const indexes = createIndexes(store);
export const relations = createRelationships(store);

So we now have a relations module in which we can define our many-to-one relationship. As this is primarily the domain of the Project, we'll put it in the Project.model.js for now.

// src/models/Projects.model.js
import { relations } from '../services/store';

import Model from './Model';
import Todos from './Todos.model';

relations.setRelationshipDefinition(
  'projectTodos',  // the id of the relationship
  'todos',         //  the 'many', or local side of the relation
  'projects',      //  the 'one', or remote side of the relation
  'projectId'      //  the local key containing the remote id
);

const Projects = (()=>{
  const baseProjects = Model('projects');

  return {
    ...baseProjects,
  }
})();

export default Projects;

Note that we import just the relations export, as we don't need an instance of the store itself. All we need to define the relationship is the relationship module itself. Also, we import the Todos module, as we want to add an array of todos to the project.

relations.setRelationshipDefinition defines the relationship between projects and todos, and gives that relationship the id projectTodos. The parameters for that function are:

relationshipId: a unique string to identify this relationship.
localTableId: the id of the local table for the relationship. Note that the local table is the 'many' side of the many-to-one relationship.
remoteTableId: the id of the remote table for the relationship. This is the 'one' side of that many-to-one, representing the unique project that can relate to zero or more todo rows.
getRemoteRowId: the name on this threw me for a bit, but it is the cell in the local row that contain the unique id of the remote row. So, in our case, this would be projectId, as that is the todos row reference to projects.id

Finally, we can consume that relationship within the definition of the Projects model itself:

// src/models/Projects.model.js
const Projects = (()=>{
  const baseProjects = Model('projects');

  const byId = (projectId) => {
    const project = baseProjects.byId(projectId);
    project.todos = relations.getLocalRowIds('projectTodos', projectId)
      .map(Todos.byId);

    return project;
  };

  return {
    ...baseProjects,
    byId
  }
})();

Again, we expose the interface of the baseProject, and replace the stock byId method with a custom one.

That's Nice and All, But... Why?

This post is about how to interface with and consume TinyBase's store, using plain vanilla javascript. And to this point, it's pretty darn okay. But if that was all there was, it wouldn't have much going for it.

In the next post, we will explore the reactive aspect of that store. We can set listeners on tables, rows, cells or data values, and we can respond when those points change.

We will also look at data storage and persistence. TinyBase, in itself, includes some great mechanisms for both local and remote storing, and also describes how to write your own storage "hooks."

This is something I'm still playing with, something I'm still learning as I go - if y'all find something neat (or something I missed), lemme know!

Extending Collections

Toby Parent — Fri, 16 Dec 2022 23:28:06 +0000

So in the last article, I wrote about how a Collection is an abstract constructor (not a constructor, but a builder of objects) that, in essence, builds an array with some added functionality. We are using it to store things, but we're also wrapping those stored things with a unique _id tag, so we can find them later.

At this point, we haven't actually made those _id values unique - the downside to using an array for the internal implementation. That is a thing we can address in this one, whether we simply add a check or use a different internal store within the Collection.

What Does That Even Mean?

When we say a thing is Observable, we are saying "this thing will have some actions (or events) that we can observe, and we can act on the result of those actions."

When we write event handlers in javascript:

const handleButtonClick = (event) => {
  event.target.classList.add("someClass");
  console.log(`the ${event.id} button was clicked!`);
}

document.querySelectorAll("button").forEach((button)=>{
  // we *observe* the click event on each button
  button.addEventListener( "click", handleButtonClick )
})

That is adding a listener on (or subscribing to) an event that might, at some point, take place on that <button> element. The button is an Observable, and our handleButtonClick is the observer.

The neat thing is, this is not exclusive to the core javascript language. This is a thing we can do ourselves, and pretty easily. Just... with a little knowledge and application.

A Little Background

In order to make something observable, we need to define at what points our stuff can be observed, and how we want to handle that observation. In the case of the Collection, we don't need to observe the find events, as that isn't changing anything - so perhaps the add, remove and update functions are good observation points.

And how might we do that? We'll steal a page from the Events API, with a string to identify which action and a function to run when that action occurs. If you aren't sure about passing in functions, take a look at Understanding Higher-Order Functions to see what I mean. We'll take this same idea and build upon it.

So, looking at our Collection, we have this:

// helper function to generate random UUID
const createUUID = function b(a){return a?(a^Math.random()*16>>a/4).toString(16):([1e7]+-1e3+-4e3+-8e3+-1e11).replace(/[018]/g,b)}

const Collection = (title='Default Collection', _id=createUUID()) => {
  let stuff = [];

  const add = (item, _id=createUUID() )=> {
    const thing = Object.freeze({_id, data: item})
    stuff = [...stuff, thing];
  }
  const remove = (id) => {
    stuff = stuff.filter(thing => thing._id != id);
  }
  const findById = (id) => stuff.find(thing=>thing._id === id)
  const find = (func) => stuff.filter(({data})=>func(data) );
  const findAll = () => [...stuff];
  const update = (id, updateFunc) => {
    stuff = stuff.map(
      (thing) => thing._id===id ?
        Object.freeze({_id, data: updateFunc(thing.data)}) :
        thing
      );
    return findById(id);
  }

  return {
    get _id(){ return _id; },
    get title(){ return title;},
    add,
    remove,
    find,
    findAll,
    update
  }
}

To begin, we'll need to have some way to keep track of those functions. As we're expecting a string for the action and a function, an object might be useful:


const Collection = (title='Default Collection', _id=createUUID()) => {
  let stuff = [];
  let observers = {};

  const add = (item, _id=createUUID() )=> {
    const thing = Object.freeze({_id, data: item})
    stuff = [...stuff, thing];
    return thing;
  }

  /* and all the rest of our handy-dandy functionality */
  return {
    get _id(){ return _id; },
    get title(){ return title;},
    add,
    remove,
    find,
    findAll,
    update
  }
}

So we will add them to observers as we are given them. But we also need a couple of methods, just like addEventListener and removeEventListener. In our case, we will call them subscribe and unsubscribe, as the pattern we're using is often referred to as Publish/Subscribe or PubSub. So what might those two methods look like?


const Collection = (title='Default Collection', _id=createUUID()) => {
  let stuff = [];
  let observers = {};

  const add = (item, _id=createUUID() )=> {
    const thing = Object.freeze({_id, data: item})
    stuff = [...stuff, thing];
    return thing;
  }

  // when a function is subscribed, we simply add it to the
  //  observers object, in an array stored under the action.
  const subscribe = (action, observerFunction) => {
    if(!observers.hasOwnProperty(action)){
      observers[action]=[];
    }
    observers[action].push(observerFunction)
  }

  // and to unsubscribe, we reverse that. Just as with
  //  event listeners, we can only remove functions with
  //  the same reference by which we subscribed 'em.
  const unsubscribe = (action, observerFunction) => {
    observers[action] = observers[action].filter(
      func => func !== observerFunction
    );
  }

  /* and all the rest of our handy-dandy functionality */
  return {
    get _id(){ return _id; },
    get title(){ return title;},
    add,
    remove,
    find,
    findAll,
    update,
    subscribe,
    unsubscribe
  }
}

That will let us add and remove observer functions, placing them into or removing them out of the observers object as we like. To use it, we might:

const myDictionary = Collection("Toby's Devils Dictionary");
myDictionary.subscribe("add", (item)=> console.log(`**${item.term}**: *${item.definition}*`))

And that would add an inline function to our observers.add array. Note, though, as we've defined it as an inline function, we have no reference to it with which we can remove it! This is exactly the same behavior as we see in Events API, so I'm not too worried about it.

If we wanted to be able to remove it later, we would need to keep a reference:

const logInUpperCase = (item) => console.log(`**${item.term.toUpperCase()}**: *${item.definition}*`);

myDictionary.subscribe("add", logInUpperCase)

// and later, if we wanted:
myDictionary.unsubscribe("add", logInUpperCase)

So long as we have a reference to the function we subscribed, we can always unsubscribe it.

Well Yeah, But What Do We DO With It?

At this point, we have an object of arrays, but we aren't doing anything with them. We're storing them, and they're there, but we haven't actually executed anything yet!

Patience. Here it comes.

When we add something to the Collection, we do a few things:

We change the array stored within the Collection,
We generate a new _id for the thing we're adding,
We return the thing we've added, in its new container.

When we call our "add" observer function, those are the things we will want to pass into it. Do note that the parameters we will pass change, depending on the action. If we're calling the "delete" observer, the data being passed will likely be different.

But in this case, let's work with the "add" observers, and see how we might use them. To begin, we need to tell the add() method about the its observers, if there are any:

const Collection = (title='Default Collection', _id=createUUID()) => {
  let stuff = [];
  let observers = {};

  const add = (item, _id=createUUID() )=> {
    const thing = Object.freeze({_id, data: item})
    stuff = [...stuff, thing];
    observers.add?.forEach(
      /* and in here, we do something for each observer function */
    )
    return thing;
  }


  /* and all the rest of our handy-dandy functionality */
  return {
    get _id(){ return _id; },
    get title(){ return title;},
    add,
    remove,
    find,
    findAll,
    update,
    subscribe,
    unsubscribe
  }
}

Note the syntax of the line I added there: observers.add?.forEach(). That's a pretty funky syntax, when we look at it. What's that question mark doing in there?

The ?. is a pretty neat new feature referred to as Optional Chaining. What it says is, "If the thing before the ? exists, go ahead and run the function after the . - but if the thing before the ? does not exist, stop now and evaluate to undefined." In effect, if we have no add property on observers, we simply stop evaluating the expression and bypass the .forEach() bit.

This is well-supported in modern browsers, but if we wanted to avoid using newish features, we could:

  const add = (item, _id=createUUID() )=> {
    const thing = Object.freeze({_id, data: item})
    stuff = [...stuff, thing];
    if(observers.hasOwnProperty("add")){
      observers.add.forEach(
        /* and in here, we do something for each observer function */
      )
    }
    return thing;
  }

Does exactly the same thing.

Either way, we now have a forEach() we need to handle. And each thing is a function that we've been passed, and that we want to execute, remembering to pass in the values we've outlined.

const Collection = (title='Default Collection', _id=createUUID()) => {
  let stuff = [];
  let observers = {};

  const add = (item, _id=createUUID() )=> {
    const thing = Object.freeze({_id, data: item})
    stuff = [...stuff, thing];
    observers.add?.forEach( (observerFunc) =>
      // we'll pass as arguments:
      //  - the wrapped item,
      //  - the collection as pure data
      observerFunc(thing, {_id, title, collection:[...stuff]} )
    )
    return thing;
  }


  /* and all the rest of our handy-dandy functionality */
  return {
    get _id(){ return _id; },
    get title(){ return title;},
    add,
    remove,
    find,
    findAll,
    update,
    subscribe,
    unsubscribe
  }
}

With that, each time we run add(), we also execute each observers.add function, passing in the arguments we said we would. And just as with the Event API, we can't actually return anything from those functions.

To Recap

So the idea here is to add some functionality to the Collection, letting it execute functions on our behalf at some future time. As we've discussed, this is a Publish/Subscribe pattern, as we "publish" events to which other objects or functions can "subscribe". In a formal sense, this is an Observer pattern.

The usefulness of the pattern might be observed by how we could use it later:

// suppose we've defined each of the parts we'll use
//  as factories (a Collection factory)
//  or imported modules (TodoAppDom and saveToLocalStorage)
const myTodoApp = ((manager, dom, storage)=>{
  // create our Collection,
  const myDictionary = Collection("Toby's Devils Dictionary");

  // set specific parameters for the DOM and storage, perhaps:
  dom.container = document.querySelector('#my-todo-app');
  storage.key = myDictionary._id;

  // listen to collection changes and reflect them to the DOM
  myDictionary.subscribe("add", dom.addTodo );
  myDictionary.subscribe("remove", dom.displayAllTodos );
  myDictionary.subscribe("update", dom.updateOneTodo );

  // listen for those same changes, and update localStorage
  myDictionary.subscribe("add", storage.save );
  myDictionary.subscribe("remove", storage.save );
  myDictionary.subscribe("update", storage.save );

})(Collection('My Todo App'), TodoAppDom, saveToLocalStorage)

If we know the function signature for each of those listeners, then we can write methods on the DOM module or the storage module to pass right in. And, in this case, the function signatures are pretty straightforward:

"add", function( wrappedItem, collectionObject)
"remove", function(deletedItemId, collectionObject)
"update", function(wrappedItem, collectionObject)

So each observer receives the same number of parameters, allowing us to define a saveToLocalStorage object:

const saveToLocalStorage = () =>{
  let key='Default Key';
  const load = () =>
    JSON.parse(localStorage.getItem(key));
  const save = async ( _, collection ) => 
    localStorage.setItem(
      key, JSON.stringify(collection)
    );
  return {
    save,
    load
    set key(value){key=value;}
  }
}
export default saveToLocalStorage;

Note that I haven't defined the observers entirely - you get somehomework! How might the delete observer work? And the update?

How about, what kinds of actions might you be able to trigger on each action? What possibilities have you got? Adding a sound effect on save, perhaps, or causing a flyout notification?

What other actions might make sense? Is there a benefit to having a "beforeadd" and "afteradd" action? Or a more general, "before<action>" and "after<action>" type? How many make sense to you?

Let's have a conversation about this!

Understanding Higher-Order Functions

Toby Parent — Fri, 16 Dec 2022 20:05:53 +0000

Working on a few article ideas, and I'm realizing that quite a few of them are dealing with callbacks, or higher-order functions. Might make sense to talk about what they are, how they work, what they mean, and the superpowers with which they can endow us.

The What

When we talk about higher-order functions, we're simply talking about a function that either takes in another function (as a parameter), or gives back another function (as a return value), or both.

An example of a function that takes in a function might be:

document.querySelector("#container").addEventListener(
  "click",
  function(event){
    console.log(`You clicked on ${event.target.dataset.name}!`);
  }
)

We are telling the addEventListener function about two parameters: the first is a string, and the second is a function. The Event API will take that function in and, when that event occurs on that element, it will call the function for us.

An example of a function that returns a function might be this one:

const addTwoThings = function(first){
  return function(second){
    // and here, we have both first and second variables!
      return first + second;
  }
}

const add7 = addTwoThings(7);
const sayHello = addTwoThings("Hello, ");

// those are both now references to functions,
//   and those functions are scoped to unique instances of
//   addTwoThings. Let's see how we can use 'em:
console.log(sayHello("Bert")); // "Hello, Bert"
console.log(add7(28)); // 35

// Let's just complicate the crap out of things:
console.log(sayHello( add7( add7(28) ) ) ); // "Hello, 42"

So we can pass functions in, and we can pass functions back. And this can be very powerful.

The Why

Why is this significant? Consider the ES6 array methods: filter, map, forEach, reduce, some, every for example. Each of them take in a function, and the function's signature that we are passing in is very similar for each of them. The interface is pretty uniform, which makes remembering how they work a bit easier.

A common lesson in online courses might have us write a map function, simulating the way map works in our own implementation. So I don't want to give away the answer to that one, but let's try making our own implementation of filter, and see how that might work.

First, we need to understand exactly what .filter() is doing, step by step. It is looping over the array, and testing each element in that array with a given function. The function takes in up to three parameters, the element, its index, and the original array reference, and returns a truthy or falsy value. If that returned value is truthy, we persist that element. If it is not, we don't. And then we return a new array, containing just the elements that met our function.

Incidentally, a function that returns a true/false value is often referred to as a predicate function, as in "the decision was made predicated on the outcome of this thing."

We want our myFilter to work the same way, so we would be able to call it like this:

// filter out every other element:
[1,2,3,4,5,6,7,8,9].myFilter((_, index)=>index%2===0);
// [1,3,5,7,9]

So we'll start by defining a new Array method (which isn't best practice, but for the purpose of this test I'll just... do... bad things.)

Array.prototype.myFilter = function(/* some stuff here */){
  // and do some stuff here.
}

First thing to note, I used a function(){...} here, and not a ()=>{...} (a traditional function, vs a lambda or fat-arrow function). I did so, because within the function this will refer to the array itself. We need a valid this, so we can't use a lambda here.

So we know we need a starting empty array, and we need a loop:

Array.prototype.myFilter = function(/* some stuff here */){
  let stuffWeWant = [];
  for(let i=0; i<this.length; i++){
    // some kind of testing?
  }
  return stuffWeWant;
}

Now, if we refer back to how we call it, we want to be able to pass in a function. And inside the loop, we need to call that function:

Array.prototype.myFilter = function( aFilterFunction ){
  let stuffWeWant = [];
  for(let i=0; i<this.length; i++){
    if( aFilterFunction(/* but what should go here? */) ){
      // if that returns true, we'll be in here.
    }
  }
  return stuffWeWant;
}

What do we want to pass into the function? We've told the user that the function's parameters will be the current element, the current index and the array reference:

Array.prototype.myFilter = function( aFilterFunction ){
  let stuffWeWant = [];
  for(let i=0; i<this.length; i++){
    const currentElement = this[i];
    const index = i;
    const array = this;
    if( aFilterFunction(currentElement, index, array) ){
      // if that returns true, we'll be in here.
    }
  }
  return stuffWeWant;
}

We could have simply defined those in place, if we prefer:

Array.prototype.myFilter = function( aFilterFunction ){
  let stuffWeWant = [];
  for(let i=0; i<this.length; i++){
    if( aFilterFunction(this[i], i, this) ){
      // if that returns true, we'll be in here.
    }
  }
  return stuffWeWant;
}

And get the same result. So now we're testing with that aFilterFunction, so if we get a truthy value back, we will simply add this[i] to our stuffWeWant array!

Array.prototype.myFilter = function( aFilterFunction ){
  let stuffWeWant = [];
  for(let i=0; i<this.length; i++){
    if( aFilterFunction(this[i], i, this) ){
      stuffWeWant.push(this[i]);
    }
  }
  return stuffWeWant;
}

And with that, we have a working myFilter function, that looks and acts exactly the same as the ES6 filter.

Meanwhile, Back On The Farm...

Yeah, that was a bit of a sidetrack, but it does have a point - in our myFilter, we are receiving a function. And that function is being run for us, by the myFilter function. It is calling the function just as we would, passing in the expected parameters.

We are running the passed-in function by proxy. We don't need to know its name, we don't need to know where it came from, we just know it's being passed in as a parameter so we have a reference, and it will take our defined parameters or it will fail.

So it's "higher-order" - we are passing in a function and we are delegating the execution of that function to myFilter. It's a neat idea, and it seems pretty simple, but it opens up a LOT of possibilities.

Looking Ahead

This was a little bit of a sidestep from the last article, but it is a lead-in to the next one - so make sure you come back for that!

Are You a Collector?

Toby Parent — Fri, 16 Dec 2022 03:11:00 +0000

In javascript, when we're thinking about "groupings of like things," we tend to think of arrays. And that's not wrong, arrays are powerful, intentful, and very useful. But they're also pretty basic.

When we start building projects, we often find ourselves reaching for a way to group things, but to do so at a higher level than that of an array. It might be handy to add to a grouping without having to consider how it is being implemented. It might be useful to find an thing by an id, for example, or to be able to implement a find function such as the array uses, while not necessarily using an array to store that stuff internally.

We want to abstract the data structuring away within a Collection, and simply provide a useful interface that we can consume.

What might a `Collection` look like?

We define the Collection, from the outside, by what it does. What behaviors does it have? How can we talk to it? What can it tell us, and what can we tell it? Let's start by defining some basic methods:

Collection:
  .add( item )
  .find( findFunction )
  .findAll()
  .update( updateFunction )
  .remove( item )

That's the basic, core functionality we might want. The idea is, a collection should contain instances of the same type of thing, making our find or update pretty universal (for a collection of Book objects, we might want a find function that can find by ISBN for all of them).

So we might use it like this:

const playlist = Collection();
playList.add(Song('Si Mi Clean', 'Buju Banton', '3:00'));
playlist.add(Song("Eleanor Rigby - 2022 Mix", "The Beatles", "2:06"));
// we can find things...
const aSong = playlist.find( song => song.title.startsWith("Si")[0];
// and we can update things.
playList.update(aSong.id, song => song.setLike(true) )

So we might create that basic functionality:

const Collection = (title='Default Collection') => {
  let stuff = [];

  const add = (item)=> {
    stuff = [...stuff, item];
  }
  const remove = (item) => {
    stuff = stuff.filter(thing => thing != item);
  }
  const find = (func) => stuff.filter( func );
  const findAll = () => [...stuff];
  const update = (updateFunc)=>stuff=stuff.map(updateFunc)

  return {
    get title(){ return title;},
    add,
    remove,
    find,
    findAll,
    update
  }
}

Looks pretty clean, does what we want... but its not great. I mean, really, all it actually does is wrap an array, and act as an intermediary to an array. It's not like we are adding any functionality to it, right?

So what's the point?

The Point

Let's revisit the original idea, and use a more concrete example. Suppose we have a Library - it's just a collection. It holds a variety of media, and when queried, can retrieve a unique thing, can interact with that thing, can update or remove it. We can add items to the Library, without needing to sweat "Hey, so how is this thing unique?"

If we were to implement that, we might create a Book factory (or constructor, up to you):

const Book = (
  title='Default title',
  author='Default Author',
  publicationDate=Date.now(),
  pages=0
) => {
  const toString = () => `${title} by ${author} (${pages}pp)`
  return {
    get title(){ return title },
    get author(){ return author },
    get publicationDate(){ return publicationDate },
    get pages(){ return pages },
    toString
  }
}

So that defines the basic structure of a Book: title, author, publication date, pages. And as far as it goes, it's exactly what we'd need.

But if you were to go down that path in one of the online courses you might be advised, "Okay, but now what? are you going to use the title or title-author combo to uniquely identify each book?" When we use these Book things, we will likely want to be able to find a particular one, in a library of hundreds or thousands. We need an id.

And that, right there, has bugged me for a while. You see, the id of a book (or of most objects) is fundamentally not a part of the data. The Book doesn't care about it, it doesn't use it internally, it doesn't need to reference it. It is not intrinsic to the object itself.

But we still need it. It might not be a part of the Book, but it helps us to identify the book. It isn't intrinsic, so it's extrinsic. By that, I mean that the id might help us recognize a book as unique, but it is not a fundamental part of the Book "blueprint".

A Step Closer

If we know that the id should indicate the thing it is tagging, but it isn't a core part of that thing's functionality, how might that look? Well, we might start where we want to end:

const myBook = {
  _id: 'eddc45f3-c35b-4717-940a-a92021a450b3',
  data: // our Book object
}

So we can wrap our Book, or whatever we're collecting, inside another object - and that one simply contains two properties: _id and data. I'm using crypto.randomUUID() or a shim here to generate that _id value, but whatever makes sense.

Doesn't look like much, but it's a bit of functionality we will see often. If we store a value to Google's Firestore, it will come back looking very similar to this - it is just a container for our data, with a unique key attached.

Yeah, But How Does That Help?

Let's revisit the Collection, and keep this wrapping-id thing in mind as we do.

// helper function to generate random UUID
const createUUID = function b(a){return a?(a^Math.random()*16>>a/4).toString(16):([1e7]+-1e3+-4e3+-8e3+-1e11).replace(/[018]/g,b)}

const Collection = (title='Default Collection', _id=createUUID()) => {
  let stuff = [];

  const add = (item, _id=createUUID() )=> {
    const thing = Object.freeze({_id, data: item})
    stuff = [...stuff, thing];
  }
  const remove = (id) => {
    stuff = stuff.filter(thing => thing._id != id);
  }
  const findById = (id) => stuff.find(thing=>thing._id === id)
  const find = (func) => stuff.filter(({data})=>func(data) );
  const findAll = () => [...stuff];
  const update = (id, updateFunc) => {
    stuff = stuff.map(
      (thing) => thing._id===id ?
        Object.freeze({_id, data: updateFunc(thing.data)}) :
        thing
      );
    return findById(id);
  }

  return {
    get _id(){ return _id; },
    get title(){ return title;},
    add,
    remove,
    find,
    findAll,
    update
  }
}

This took a little more thinking: rather than dealing with our objects directly, we now have an added layer of object in there. So when we pass in a find function, we want to find on the passed in thing, not on our container. When we update, we want to leave the container alone - the user can consume the data, but shouldn't be able to alter our _id.

Also note that, rather than rely on the system's crypto.randomUUID(), I'm using a pretty common createUUID(). Does much the same thing, and won't be facing the security limitations that crypto might.

Yeah, But Why?

A good question, "what's the point?" Let's see what that gets us:

const myDictionary = Collection(`Toby's Private Word Bank`);
myDictionary.add({term: "Cabbage", definition: "n. A familiar kitchen-garden vegetable about as large and wise as a man's head."});
myDictionary.add({term: "Cat", definition: "n. A soft, indestructible automaton provided by nature to be kicked when things go wrong in the domestic circle."})
myDictionary.add({term: "Famous", definition: "adj. Conspicuously miserable."})
myDictionary.add({term: "History", definition: "n. An account mostly false, of events mostly unimportant, which are brought about by rulers mostly knaves, and soldiers mostly fools."});
myDictionary.add({term: "Resident", definition: "adj. Unable to leave."});

So we can add things to it. And as we added each one, we were returned a value that we could have caught: the original object in its new wrapper. That could be handy, if we wanted to report its addition or wanted to add something to, for example, the DOM.

Let's see if we can find stuff:

console.log(
  myDictionary.find(
    (el)=>el.definition.startsWith('adj')
  )
)
// [
//  {
//    _id: '6a9fd02e-10b9-4e96-a454-50a4b53839ff',
//    data: { term: 'Famous', definition: 'adj. Conspicuously miserable.' }
//  },
//  {
//    _id: 'ed277d50-f9f7-4c5f-888c-67dbd09ca416',
//    data: { term: 'Resident', definition: 'adj. Unable to leave.' }
//  }
//]

And again, when we find the two that match (Famous and Resident), we are getting the item itself, and its container.

We can place anything in that collection, and each placed thing will receive a unique _id we can use elsewhere. Build a collection of words, each word will be tagged. Build a collection of books, each book will be tagged. And so on.

One More Possibility...

Suppose we want to take this, and build a Project Manager type thing. Basically, a todo list manager app. Well, each todo list is just a Collection, so we could:

const todoLists = [
  Collection("Personal Tasks"),
  Collection("Work: Group Projects"),
  Collection("Work: Personal Goals"),
  Collection("Family Chores")
]

And we have any number of Todo lists, just like that. Each will let us tag our Todos as we add them, giving them a unique id for us.

But that array? It's also a collection:

const todoAppManager = Collection('My Todo App Manager')

todoLists.forEach( todoList =>{
  // each created TodoList has its own unique id already. Let's 
  // leverage that!
  todoAppManager.add(todoList, todoList._id)
})

So we have a collection... of collections!

Next Steps

In the next one, I'd like to look at how we might make this handle callbacks. It could be useful, when an item is added to a collection, to fire off an observer, handling activities outside of the collection (saving the collection to localStorage or a remote database, updating the DOM, popping up a flyout notification... whatever we might like).

Factories and Closures, or Classes and Constructors... Does It Matter?

Toby Parent — Sun, 12 Jun 2022 02:23:55 +0000

There is all kinds of debate about which is better, classes/constructors or factory functions using closures. There are advantages and disadvantages to each, perhaps, but I'm kind of curious, so I did a thing.

Someone was asking about the Linked List data structure, and how it might be implemented in Javascript. They'd read some on FreeCodeCamp's news feed, and they'd seen some YouTube videos on the subject, but it wasn't really making sense. So the question was asked. Basically, what and why?

Fair warning: This one is long. I got a little heated because someone accused me of hating on classes, and someone else DM'ed me about my hating on factories... Fact is, I love both. I use both. And in this, I am writing about why it doesn't matter.

To see the end result as ES6 classes, https://replit.com/@TobiasParent/LinkedListsInJavascript. To see the same thing with Factory functions, https://replit.com/@TobiasParent/LinkedListsInJavascriptFactoryEdition

The What

What, precisely, is meant by a Linked List? What is it, why do we need it, and how might we use it?

The idea of a linked list is, we have a collection of things that we want to keep in some sort of order. We could use an array, but a Linked List differs in that we keep track of one thing: the first item in the list. Then, we tell that item that it is responsible for keeping track of the thing after it.

As we add things to the list, we simply tell the last thing in the list that it is responsible for keeping track of (or keeping the reference to) the thing that follows it. Doing this, we get something that might look like:

LinkedList {
  head: ListNode {
    data: 'A',
    next: ListNode {
      data: 'B',
      next: ListNode {
        data: 'C',
        next: ListNode {
          data: 'D',
          next: null
        }
      }
    }
  }
}

So this looks pretty straightforward - we have a LinkedList, which tracks that head element. And that head should be of a particular type, a ListNode - which needs two attributes to begin: data and next.

data is simply the value we are storing in this position. Could be a string, a number, an array, an object... it doesn't really matter - it's simply data.

next, on the other hand, is another ListNode, or a null value if it's the last one in the chain.

The Why

An implementation example might make this more readable and understandable. Suppose we were teachers in a third-grade classroom, and we have nineteen students in our class. We've organized a field trip, sent out permission slips to parents, and gotten fifteen back. So we're taking fifteen students to the Boston Aquarium!

Now, being the sort of teacher who likes things organized and simple, we have arranged a buddy system. We would like to arrange the students in a sort of chain, each one holding onto the loop on the backpack of the child in front of them. We will bring up the rear, holding that student's backpack strap - and, by proxy, holding the strap of each child in the line.

So we will hold onto the strap of Janice's bag. As we are ultimately responsible for the entire thing, we contain the parade in the one strap we hold. So by saying that we hold Janice's strap, and Janice holds Reuben's, and Reuben holds Sammy's, we can say that we hold, indirectly, all of them.

In terms of our LinkedList, we might have something like:

buddySystem = LinkedList {
  head: ListNode {
    data: 'Janice',
    next: ListNode {
      data: 'Reuben',
      next: ListNode {
        data: 'Sammy',
        data: null
      }
    }
  }
}

As each child is added to the parade, we simply tell the last one who is next, and we create the attachment between them.

In code, that might look as simple as:

// we create the thing, by passing in the head
const buddySystem = new LinkedList(new ListNode('Janice'));

buddySystem.head.next= new ListNode('Reuben');
buddySystem.head.next.next = new ListNode('Sammy');

// and so on, until we are adding the fifteenth:
buddySystem.head.next.next.next.next.next.next.next.next.next.next.next.next.next = new ListNode('Raheem')

Hrm... that doesn't look so simple, for a few reasons that really bug me. Let's see what we can do about those.

The Bugs

So there are a few things bugging me here:

We are using new LinkedList() and new ListNode(), explicitly saying "this is a constructor of some sort, deal with it.". So, later, we can't swap that out for a factory, if we wanted to see how that might work. We're stuck
We are explicitly having to tell each datapoint "Hey, you're a ListNode, okay?" There is no need to state that from the outside - we shouldn't care about that. We simply want to organize our bookshelves, not create, label and package each book before we do.
We are explicitly having to head.next.next.next each time. That is a terrible interface design. We can, and should, do better.

Let's tackle these in reverse order, as resolving the third issue will help with the second, and finding a solution to the second will flow upward to the first.

Issue 3: We need an interface

The solution to not having to do that whole chain of next to get to a particular value is simply to define an interface for our collection as a whole, and perhaps one for each item in the collection.

How might we want to interact with the collection? We might want to:

1. append (add a value to the end of the collection),
2. prepend (add a value to the beginning of the collection),
3. after (add a value after another value within the collection),
4. find (find a particular value and anything after it),
5. remove (find a particular value and remove it, splicing the collection),
6. clear (remove everything),

Now, that's a great start, but I'm going to add one more interface point that might be useful, taken from the functional world. Referring to our example of the field trip, what if we wanted to tell all the kids to put on their reflective school vests? We should have a way to tell the first, who applies the instruction to herself and then passes the instruction to the next, and so on.

In other words, we want a way to map functions across the entire thing. In the world of fucntional programming, this is making our LinkedList a Functor, or a Mappable. We don't need to do this, but it'll be fun.

Further, as this is a collection, we likely want it to be array-like. What exactly does that mean? We likely want to know how many things are in our collection. So let's add

7. map (apply a function to all values in the collection),
8. length (get the count of items in the collection).

There, so now we have an interface. With that, rather than doing

buddySystem.head.next.next.next.next = new ListNode("Jessica");

we might simply

buddySystem.append(new ListNode("Jessica"));

Much cleaner, and we don't need to track how long the list is in order for this to work. With that, let's look at the next thing that bugs me:

Issue 2: Data as Data

I really don't like that last bit of code:

buddySystem.append(new ListNode("Jessica"));

Better would be to just pass in the data to the Linked List, and let it handle any management of types internally:

buddySystem.append("Jessica");

It is easier, more readable, more intuitive. We are appending data to the list, and letting the list itself worry about how it handles managing that stuff. In order for this to work, the LinkedList needs to know about the ListNode type, but we don't. We simply care that our data remains our data, in each element.

Now, moving on to my big issue, which is the reason I wrote this whole silly thing in the first place!

Issue 1: Constructors vs Closures... should it matter?

I have gotten in hot water for opinions, from folks on both sides of this debate. Some feel very strongly that classes and constructors are the best way to implement OO in javascript. Others feel just as strongly that Factory functions and closures, in patterns like FP, are the best way.

My take on the matter is... does it really matter?

Both return an object that either contains or references some sort of data.
Both returned objects often have some sort of interface defined.
Both can work with that data, both getting and setting values within their domain.

Yes, there are differences, and yes, they matter. But in most applications they can be used pretty darn interchangeably!

Let's look at what I mean:

// Class constructor for the ListNode element
class ListNode {
  constructor(data=null){
    this.data = data;
    this.next = null;
  }
  map(fn){
    // handle mapping both data and next properties
  }
}

// Factory function for the ListNode element
const ListNode = (data=null) => {
  let state = {
    data,
    next:null
  }
  const map = (fn)=>{/* function to update that state object*/}

  return {
    get data(){return state.data},
    set data(value){state.data=ListNode.of(value)},
    get next(){return state.next},
    set next(value){state.next=value},
    map
  }
}

These both create a ListNode element, with a data attribute, a next attribute, and a map method. Yes, the class is placing that map on the prototype, rather than directly in the returned object, but does that really matter, in terms of usage?

The only difference is how we implement them:

// class
const node1 = new ListNode("Sammy");

// factory
const node2 = ListNode("Renee")

So again, we are dictating to the end user "Hey, this is a particular type of thing, you must create it in this particular way." In effect, this is the same (to my mind) as requiring that we manually create those silly ListNode elements, when all we care about is the data!

What if we define a method on both, same name, that handles the implementation for us?

// for the class, we
class ListNode{
  // all the rest exactly as it was, and then
  static of(data=null){ return new ListNode(data)}
}

// and for the Factory, after we've defined it:
ListNode.of = (data=null)=>ListNode(data)

Now, regardless of internal implementation, we can just do

const node1 = ListNode.of("Jamal");

And either way, we get back a handy-dandy accessor object. Personally, I find an .of() method makes considerable sense, as it is turning the implementation of class vs closure into simply another interface we can use.

Enough of That, More Code

To begin with, let's start at the end. What I mean is, let's create some implementation so we can see how we might use these pieces we'll be writing.

// Implementation of the LinkedList
const buddySystem = LinkedList.of("Janice");
buddySystem.append("Benji");
buddySystem.append("Sammmy");

// the data is all there. The first thing is .head,
//  the second is .head.next, the third .head.next.next
//  and so on.
console.log(buddySystem.head.data);
console.log(buddySystem.head.next.data);
console.log(buddySystem.head.next.next.data);
console.log(JSON.stringify(buddySystem, null, 2))

// we can also add to the beginning of the list, in 
//  effect pushing everything *back*.
buddySystem.prepend("Alphonse");
// and we can add things after other things!
buddySystem.after("Benji", "Rosette");
// finally, we can find "sub-lists", from a given node
//  and on.
console.log(JSON.stringify(buddySystem.find("Benji"),null,2) );



buddySystem.map(val => val.toUpperCase())
console.log(JSON.stringify(buddySystem, null, 2));
console.log(buddySystem.length)

We can create the thing by LinkedList.of(data), and that data could be anything. Might be a text string, might be a number, might be an object. Doesn't matter. Our LinkedList is just a linked collection of containers for stuff.

We can append or prepend to that list, we can view it at any time (in whole or in part), we can find particular nodes, we can map functions to all values in it. In all, I think this works.

Now - to the Lab!

All right, so enough jabber. You're here for the code, and to see if this stuff actually works. Let's go with the factory version for now, and start with the ListNode:

const ListNode = (data=null) => {
  let state = {
    data,
    next:null
  }
  const map = (fn)=>state = {data:fn(data), next: (state.next ? state.next.map(fn):null)}

  return Object.freeze({
    get data(){return state.data},
    set data(value){state.data=ListNode.of(value)},
    get next(){return state.next},
    set next(value){state.next=value},
    map
  });
}
ListNode.of = (data)=>ListNode(data);

That creates the ListNode, and gives it all the functionality it needs: it has a data and a next attribute, and a map method. We need the ListNode to have a .map, so we can pass that along the chain.

What might the same thing look like, if it were a class?

class ListNode {
  constructor(data=null){
    this.data = data;
    this.next = null;
  }
  map(fn){
    this.data = fn(this.data);
    this.next = this.next ? this.next.map(fn) : null;
    return this;
  }
  static of(value){
    return new ListNode(value);
  }
}

In terms of usage, we access them the exact same way. Though we never use them directly, we could, by ListNode.of({name: "Bob", age: 42}). Again, we don't care if it's a class or a factory - we get an object, we use the object, and we interface with it in the same way.

What about the LinkedList itself? It's a bit more complex, but here goes. Again, the Factory version first:

const LinkedList = (head=null,...data) => {
  const append = (data=null)=>{
    const getLast = (item)=>item.next ? getLast(item.next) : item;
    getLast(state.head).next = ListNode.of(data);
  }
  const prepend = (data=null)=>{
    const newHead = ListNode.of(data);
    newHead.next = state.head;
    state.head = newHead;
  }
  const after = (beforeItem, data)=>{
    const itemBefore = find(beforeItem);
    const newItem = ListNode.of(data);
    newItem.next = itemBefore.next;
    itemBefore.next = newItem;
  }
  const find = (data, item = state.head)=>{
    return (item.data === data) ? item: item.next ? find( data, item.next) : null;
  }
  const length = (el = state.head, len = 1)=>el.next ? length(el.next, len+1) : len;
  const map = (fn)=> state.head = state.head ? 
                     state.head.map(fn) :
                     null;

  let state = {
    head: ListNode.of(head),
    next: null
  }
  data.forEach(element => append(element) )

  return Object.freeze({
    get head(){return state.head},
    set head(value){ state.head = ListNode.of(value) },
    get length(){ return length() },
    append,
    prepend,
    after,
    find,
    map
  })
}
LinkedList.of = (...data)=>LinkedList(...data);

That's a massive wall of code, but it parses well. We wrote all our interface methods, and then we return them. All the functions in there are the ones we talked about way back when we defined our interface.

Of course, I did sneak something by you. With the factory version, we can do this:

const buddyList = LinkedList.of("Janice");
buddyList.append("Fred");
buddyList.append("Charlie");

Or, we can do this:

const buddyList = LinkedList.of("Janice", "Fred", "Charlie");

Because of the way I defined the .of for the factory, we call the append method while we're creating the thing. I couldn't really figure out how to do the same behavior in the class-based one, but if you've ideas, I'd love to hear them!

On to the class-based version:

class LinkedList {
  constructor(head=null){
    this.head = ListNode.of(head);
  }
  append(data=null){
    const getLast = (item)=>item.next ? getLast(item.next) : item;
    const last = getLast(this.head);
    last.next = ListNode.of(data);
    return this;
  }
  prepend(data=null){
    const newHead = ListNode.of(data);
    newHead.next = this.head;
    this.head = newHead;
    return this;
  }
  after(find, data){
    const itemBefore = this.find(find, this.head);
    const newItem = ListNode.of(data);
    newItem.next = itemBefore.next;
    itemBefore.next = newItem;
    return this;
  }
  find(data, item = this.head){
    return (item.data === data) ? item: item.next !==null ? this.find( data, item.next) : null;
  }

  map(fn){
    this.head = this.head?.map(fn);
  }
  static of(value=null){
    return new LinkedList(value)
  }
}

So, when this one is made, the only thing directly in there is the head property. Everything else, as this is a class, is in the prototype. That's the significant difference between the two: the factory-based object is composed of all its functionality, while the class-based object inherits it from the class.

But again, because of that .of creation interface, we can work with both transparently. We don't need to know if it is a class or a factory or a cheezburger. We just want one made, no muss no fuss.

The Recap

This was a ramble, and if you made it to the end, you're clearly a masochist or a nerd. Either way, I loves ya.

The points to take away, to my mind, are:

If we have an interface both for use and creation of our objects, then we can sidestep the implementation of either classes or factories. They become a non-conversation.
If we don't need to know what something is going to use inside, if we just want to cram data in there? Ignorance is bliss. Let the LinkedList worry about how it will handle its own guts. We just care about data, TYSVM.
Plan and design from an interface. Everything else flows from that.

Fairy Tales, and the Implications of Immutability

Toby Parent — Tue, 22 Feb 2022 19:39:53 +0000

This is a bit of an aside, less directed to a particular project and more directed to a particular question. One of my recent posts, Decomposing Composition, led to a someone asking that I perhaps talk about the dangers of the Array.prototype.reverse function and others like it:

One more thing... I know you're not trying to re-create "Composing Software", but would it be worth addressing how Array.reverse() actually modifies the passed array, as well as returning a reference to it? Mutation! Mutation!

That's unlike the other JS functions, which just return something new.

And what implications does that have in a pipeline or composition?

Thanks, Greg! Both the question and what it implies has had me thinking some. And with that...

The Fairy Tale

The story is well-known: a certain little towheaded kid decides to take a walk in the woods, break into a home, raid the larder, destroy the furniture, and ransack the bedrooms. Upon being caught, she flees the scene.

Yes, I'm referring to Goldilocks and the Three Bears. In the story, a family of bears has gone for a walk, to allow their meal time to cool. While out walking, Goldilocks enters their home and samples each ones' food, and chair, and bedding - and in the process consuming or breaking each ones' things.

If you search "What is the moral of Goldilocks and the Three Bears," you might find this:

The moral of the story is the need to respect the privacy and property of others and how your actions hurt others. In conclusion, the story Goldilocks and the three bears illustrate the need to respect others' privacy and property. ...
(Taken from PEDIAA)

Now, that's a moral, and not a bad one, but my suspicion is that the teller of this story was a developer.

A Different Moral

It seems to me that the story illustrates a very important point: the bears went out, secure in leaving their stuff in their home. They trusted in the fact that, when they returned, their stuff would be exactly as they'd left it. Instead, the warning is a dire one: on looking at their possessions again, things have changed. In the case of the Baby Bear, things had changed disastrously.

As developers, we can see this as a warning about immutability. When we store a value into a variable:

const myName = "Toby";

We are doing a few different things here.

We are placing a variable, myName, into the current execution scope's lookup tables;
We are placing a string, "Toby", into memory somewhere;
We are "wiring" that variable to that value;
By the const, we are telling that variable that it cannot be rewired.

So we have two different points to note:

First, primitive types are immutable. You can't change them in-place. If we were to toUpperCase() that string, we would have a new instance, in a new memory location. The original cannot be changed.
Next, a const can only be declared at initialization. From that point forward, that reference is immutable. So not only can't the value be changed, the variable can't be changed.

This implies that we can trust that myName will remain exactly what we've defined. Any time I call up on myName, I will get the same value. In effect, we have placed it in a house and locked the house.

Consider a different case:

const myFriends = ['Therese','Daniel','Greg','Annika'];

We've done the same here. myFriends is a const now, so it will always point to that same array. All great and fine and wonderful... until we do this:

myFriends.sort((a,b)=>a.localeCompare(b))

console.log(myFriends);
// ['Annika','Daniel','Greg','Therese']

So we placed that array into a variable, a const no less... but then we sorted that array. And Array.prototype.sort is one of those pesky "in-place" array methods. We have mutated the myFriends array.

In smaller simpler cases, that may not seem like a big deal. I mean, I made that array, and I then changed it - what's wrong with that?

The Problem

If I can mutate a thing publicly, can I trust that thing? Say we have an admin control panel we're building, and we're storing our data structure like that. That admin control panel might have a number of different controls, but to make it easy to work with, we just let them store their data in arrays, scoped to the AdminControlPanel module. They're contained, so they're not contaminating the global namespace.

Imagine further that we designed the thing to be modular. Folks could create their own control panel components, and load them in as they like. When they run, they create their data-pools as needed within that AdminControLPanel, they do their initialization, and they toddle on about their things.

But what if two of those components used the Friends array? Say one of them allows me to add notes about those friends, while another might look up their contact information. Imagine that we load up the AddNotesAboutFriends admin module, create the array, and even have a common object style between other things accessing Friends that allow for extra details. Works great, loads all the records about our friends, and lets us add, edit and view notes we've made. Great!

Then we have the ViewFriendDetails component. Given that we defined a uniform format for those friends, this one might let us search for friends, sort them to make it easier to find, and show a detail view for a selected one. Also works great, no worries.

But... what just happened? If our ViewFriendDetails component sorts that array of Friends and the AddNotesAboutFriends was looking at that array? We may have broken the trust there. We can't rely on the Friends array, because something outside of our control is now mutating that thing, leaving it in an unexpected and unreliable state!

Why Immutability Matters

We need, as developers, to work with data. We need to know that, when we look away from it, it won't be like the Weeping Angels in Dr. Who, sneaking about and changing position and doing dangerous stuff. We need, in short, to trust that data.

In that article I linked up top, I explored alternative ways to do the reverseString lesson common to most programming curricula. One of them was this:

// some utility functions, curried.
const splitOn = (splitString) =>
  (original) =>
    original.split(splitString);

const joinWith = (joinString) =>
  (original) =>
    original.join(joinString);

const reverse = (array) => array.reverse();


const reverseString = compose(
  joinWith(''),
  reverse,
  splitOn('')
);

Not going to explain it all, I think that last article did pretty well. But some of those small, simple functions are great:

splitOn takes a string to use for our "splitter", and a string to split. From that, it returns an array.
joinWith does the reverse: it takes a string to use as our "joiner", and then joins an array of values into a string.

In both of those cases, as we're transforming that data, we have an entirely new thing. We aren't transforming the string itself in place, we are making something new.

Then we have the reverse function. I wanted to write a simple wrapper, so I could simply pass in an array and flip it about. Rather than calling array.reverse(), I wanted to be able to call reverse(array). But I lost sight of those implications.

"That reverse function, in this particular case, really doesn't matter." We only use it on transitional data anyway, so the value ends up thrown away. So really, it doesn't matter that array.reverse() isn't returning a new thing, right?

Wrong.

It matters. Why? Because I can't know the application of my functions. I have no way of knowing where that reverse function may get used down the line. It is a great and useful function, it might pop up all over the place. The whole point of the "Functional Programming" concept is, we can create these small simple one- or two-line functions, and interconnect 'em. And they will work.

But in this case, array.reverse() is Goldilocks. We have reached back to the original array reference and mutated it. Due to the way javascript passes values, both the original array and the one inside of the function are a shared reference. They both view the same memory location, and either can mutate that. This, folks, is a bad idea.

Why?

A key principle in Functional Programming is "purity". When we talk about purity, we mean that our functions should:

Given the same input, return the same output, and
Not cause side effects.

So, for that reverse function, we get the same thing every time: when we pass in an array, the return value is the array reversed. But we have caused a side effect! We have mutated the original array, as well as returning it.

We need to be able to trust that, not only does our function do as intended, but that it doesn't do anything unintended. For example, altering the original array.

Simple Fixes

In this case, the fix is simple: rather than simply reversing the array, we want to reverse a copy of the array:

// bad:
const reverse = (array) => array.reverse();

// better:
const reverse = ([...array]) => array.reverse();

In that one, when we are receiving that array, we immediately spread it into a new array. We no longer refer to the original, so when we array.reverse() we are working on our own local copy. And when we return the value, the original array remains untouched.

With that version, regardless of where we use it, when it gets composed into other functions, we are creating a transformation rather than causing a mutation.

Other Gotchas

There are other methods and places that we need to be watchful. Here's a typical warning, taken from the MDN:

The splice() method changes the contents of an array by removing or replacing existing elements and/or adding new elements in place. To access part of an array without modifying it, see slice().
(Bolding added for emphasis)

In the Mozilla docs, if we see an array method marked as in place, these are mutators. They will alter the original thing, if we are not careful. They will Goldilocks us, eating our porridge and breaking our chairs.

There are others. The use of objects for storing exposed data can be problematic, as that exposed data can mutate at any time and we have no real way of knowing. We can't trust objects, unless we are very careful and very explicit - they can very easily be mutated.

We can render them more trust-worthy, some of which I've written in other articles: rather than using a class and creating an exposed object, use a Factory function, and Object.freeze() the returned accessor.

The Point

The moral of the story is, to my mind, trust. We need to be able to store our data, and trust that it will be what we expect when we return to it. We can't do that with data that is publicly exposed and in a mutable structure. We need to plan, and we need to be preventative.

Concerning the Separation of Concerns

Toby Parent — Tue, 15 Feb 2022 01:54:20 +0000

Working through the lessons on online coding schools, we are often taught HTML and CSS, then basic javascript, and then move into basic DOM manipulation. All great and logical steps: learn about the content, learn about presenting the content, learn about coding, and then learn about using that code to make the content somewhat interactive.

But we never really learn about development, in the sense of how to strategize. For example, when we are building things like the Todo project or the Library project, some planning and design are essential. And it's no shortcoming of the courses, it's something we tend to learn as we go. We try things, we find what doesn't work, and we try something else.

I'm hoping to use this as an idea, and a conversation starter. Before we begin, replit has what we're going for.

The Problem

We'll create an artificial example, rather than give the answers away to any given course project. Let us imagine that we have been given the assignment to create a "Word Blanks" style game. Users are presented a few text input boxes, and a filled version of the string. Clicking "Show me!" should check if all the input elements have been completed, and if they have, display the original phrase with the words inserted into the blanks. And, once the thing has been displayed, let's add a qualification: if the user types into an input once the phrase has been displayed, we update that word as they type.

Not overly complicated, good DOM manipulation practice, and we can have some fun. But we'll also add a few more challenges: first, the DOM manipulation should be encapsulated, and kept separate from the internal state of the Word Blanks. Let's require that the DOM manipulation be handled by a javascript module, while the mad-lib itself be a factory function. But the word blanks state shouldn't know about the DOM, and the DOM should know as little as possible about the internal state. We want to keep them discrete, completely separate from each other.

That sounds a little more challenging, and will require some planning and foresight. And this is where we start strategizing.

First Steps

So we know we will need a WordBlanksFactory, and a WordBlanksDisplay module. And we know we want to keep them separate, as much as possible. The factory should keep charge of the data, while the module handles the display. In terms of "design patterns", we might think of this along the lines of the MVC (Model/View/Controller) - we have the factory storing the data model, and we have the module handling the display of that data... but we need to somehow connect them. They can't know about each other directly, but what about some way of communicating indirectly?

When we need to have two components of our code to be able to interact with each other, but we also need them to be completely separate, it is time to think about a third component. In MVC, that's the controller: it takes the data from the model and communicates that to the view, and also takes interaction from the view (clicking buttons, typing text, hovering) and commnicates that back to the model.

In that way, we keep the data (the state) consistent, and keeps the view in step with that data.

But how might we apply that to this particular project?

Modelling the Data

Let's start by planning out what our data might look like. Doing that, we can start to see some patterns of communication.

To begin, a word-blank will display a sentence or paragraph of text. Let's lay out a sample of what one might look like:

"To be or not to be, that is the __noun__. Whether 'tis __adjective__ to __verb__ the slings and arrows of outrageous fortune..."

That sort of gives an idea, we will have a sentence, phrase or paragraph. In it, there should be blanks of some sort that we will fill. It'd be nice to know what part of speech goes into the string, so we can allow for that functionality too.

Looking at that, we can see some useful things: we will likely have an array of words to be inserted, and we will also likely have that phrase as a "template," into which we'll be injecting those words. At a quick glance, that might be a useful start.

A Quick Aside...

It is key to introduce a common concept or mantra at this point, as I suspect it will become very important here: "Plan to an interface, not an implementation." What does this actually mean, in practical terms? In this context, it means "Don't overplan." We have some ideas what sorts of data we might be dealing with, in a general sense, but we haven't gotten too deeply into how we'll make it happen.

It is very easy to get lost in the bog of "how" we'll make a thing happen, and lose sight of the "what" we want to happen. Often, when faced with the data ideas in that last section, we might jump into mapping out the data, figuring if an array or hash or object or whatever are the way to go, how we'll handle that internally, whether we'll use for loops or .map() to work with the array.... and we've suddenly lost focus.

We don't care how the data is implemented, we don't care how the DOM is displayed, we don't care how we'll update the model when the input changes... that is all implementation. Instead, we need to watch what each piece can say, and can hear. We need to define the external what, not the internal how.

Back on Task: Planning Interfaces

So we know we'll have three components of some sort: a WordBlanksFactory and a WordBlanksDisplay, both of which talk to each other indirectly, by communicating through an intermediary that we'll call WordBlanksController. In this way, we can decouple the display from the data. Each can work independently, and be tested independently.

What might be a useful interface for the data? Perhaps, when we create the data model, we want to pass in something to start. Further, we likely want to be able to query the data for its blanks, and for the full string, perhaps before and after applying the supplied words. We might want to be able to get or set the value of a particular word. Much more than that... not really. That's basically the entire interface for the data:

WordBlanksFactory(string){
  get {
    originalString // the original, undoctored string
    filledString   // the edited string, with either blanks or word values in
    words          // the array of WordBlank words
    blanks         // the array of WordBlank types
    wordBlanks     // a copy of the array of WordBlank things
  }
  set (
    word
  )
  reset
  save
}

There may be more methods we want to add later, but this gives us a general idea: we want to provide an interface that lets us pass in a starting thing, which sets up an internal state; we want to be able to view that state or alter it as needed, and we might want to add some functionality to handle resetting and perhaps "exporting" the word-blank in case we want to save this state for later use..

Note, I'm not defining any kind of input types, or export types. I'm not saying how we'll export the thing, I'm not specifying what the reset should do, I'm not defining how the setter will look - I'm just preparing my interface wish list.

But that leads to another Factory we may want: a WordBlank. That should take the __proper name__ and return us an accessor. What might that look like:

WordBlank(string){
  get{
    id,
    type,
    word
  }
  set{
    word
  }
  reset
}

That one's pretty basic, doesn't need a lot of functionality. That's enough to move on for now.

Let's do the same with the WordBlanksDisplay module. This one doesn't have an awful lot, really: we want to be able to provide it with some data and have it display that data. If the data changes somehow, we might want to let the display module know to re-render, likely by simply calling the rendering method again. We might also want some way for the display to let us know if the words change, might be handy to know.

WordBlanksDisplay(container){
  render
  * updateModel
}

that updateModel is a tricky one - it's more an idea at this point, not really a function. Do we want to have something we subscribe to? Do we want to have some event outside the Display that we trigger? How might we.... and there we are, falling down the rabbit hole. Don't go there. It's enough to know, at this point, that we want to somehow comunicate back that we have had a change. Again, we're simply exploring interface ideas, not implementing it yet.

I do have some ideas, as I write this, but honestly they're just kind of percolating and will evolve as we go.

Now, we've talked some about the two main components that we can see when we first consider the project, but what about that third one I'd mentioned? Some sort of a controller that acts as the "glue" between these two? It might need some methods of its own, and it also needs to be able to connect to the other two. Let's ideate!

WordBlanksGame(container){
  set{
    wordBlankTemplate
  }
  get{
    wordBlank
  }
  load
  save
  reset
}

Offhand, that looks pretty solid. the game itself doesn't need a lot of externally-available instance methods. It'd be nice to be able to pass in a new word blank template string, and to save or load the existing one.

When I'm defining the interfaces, for the most part I'm not even thinking about the DOM. I'm not so concerned with how I might talk to the thing, just that I can. I often picture using the entire thing from the console or command line, simply calling interface methods directly. When we use our factories or modules, that's what we'll be doing - calling their interface methods from other factories or modules. So why shouldn't we test in that same way?

Start Building Something Already!

Let's start with the core WordBlanksFactory, the thing we'll use to handle the data bits. To begin, we might just make an outline. At the same time, we can define the WordBlank, as it's a pretty simple factory as well.

const WordBlank = (string) => {
  const id = crypto.randomUUID();
  const type = string.replaceAll('_','');
  let entry = '';

  return Object.freeze({
    id,
    type,
    get entry(){ return entry; },
    set entry(value){ entry = value;},
    reset(){ entry = ''; }
  })
}

const WordBlanksFactory = (string)=>{
  // Break the string into words...
  const blanks = string.split(' ')
                // remove anything that's not a blank...
                .filter((word)=>word.startsWith('__'))
                // and make each blank a WordBlank thing!
                .map(WordBlank);
  return Object.freeze({
    get originalString(){ return string; },
    get filledString(){
      return String.raw({raw: string.split(/__[a-z\s]*[a-z]__/i)}, 
             ...blanks.map((blank)=>blank.entry ? blank.entry : '_______'))
    },
    byId: (id)=>blanks.find(blank => blank.id===id),
    get words(){=>return blanks.map((blank)=>blank.entry) },
    get blanks(){=>return blanks.map((blank)=>blank.type) },
    get wordBlanks(){ return blanks.map({blank}=>({...blank}) ) },
    reset: ()=> blanks.forEach(blank=>blank.reset() ),
  })
};

As that was being built, you may have noticed a few methods and a factory we didn't really plan on. We don't need the abstraction of a WordBlank factory, but it makes storing the complex data object a little tidier. And, in the process of defining that, I was seeing other methods that could be useful: being able to get either the types of each word, or the actual word for each word; being able to get a particular blank by id.

Further, note that I wrapped the returned object in an Object.freeze(). By doing this, I am ensuring that any getting or setting being done happens within the closure, and not on the returned object. This is important, as it is easy to lose sight of the fact that they're two different things.

Finally, note the get wordBlanks function: it doesn't return the array of WordBlank objects, it returns a static copy of each, containing an id, a type and an entry. It loses all WordBlank functionality, but it provides everything needed to reference and display each entry! By doing this, I ensure that we can't simply access write or reset methods from the display - the display can only consume that data.

The only really funky bit of this whole thing that I really had to research was how can I built a tagged template...without having a tagged template? That's what's going on in the filledString getter function. To see what that's actually doing, feel free to ask or view the docs in MDN (well worth the read, because it explains what's actually happening inside of template literals!)

With that one, we have the data side ready. that's really all there is to it. We can create the data model by

const wbModel = WordBlanksFactory("To be or not to be, that is the __noun__. Whether 'tis __adjective__ to __verb__ the slings and arrows of outrageous fortune...");

console.log(wbModel.filledString);
//To be or not to be, that is the _______. Whether 'tis _______ to _______ the slings and arrows of outrageous fortune...
console.log(wbModel.wordBlanks)
//[
//  { id: 'a3392c30-df20-4353-922d-429ec4e7eb28',
//    type: 'noun',
//    entry: '',
//  },
//  { id: 'd13f57f8-7342-479b-a238-25ed35f26918',
//    type: 'adjective',
//    entry: '',
//  },
//  { id: '790161d5-ee88-4cbf-840a-af845f0bf98f',
//    type: 'verb',
//    entry: '',
//  }
//]
wbModel.byId('790161d5-ee88-4cbf-840a-af845f0bf98f').entry='snozz'

We can create and tinker with that model entirely from the console, or from a script if we like. It is completely testable, and it doesn't depend on the DOM at all. But now, lets switch tracks. Lets look at the DOM and how that might work.

Meanwhile, Out Front of the Curtain...

The display parts might take some planning. Again, I think the idea of having two different parts going makes some sense. Perhaps a function that can create the WordBlank inputs, to look like:

<label class="wordblank-label"><span>noun:</span> 
  <input class="wordblank-input" 
         type="text" 
         placeholder="noun" 
         data-id="a3392c30-df20-4353-922d-429ec4e7eb28">
</label>

Everything in there can be got from the WordBlankFactory's .wordBlank getter - it gives us an array of exactly what we need. So let's start by defining a createWordBlankInput function - we pass that the object and it returns that DOM node.

I should pause here for a minute, because I've been asked often what I think of the whole innerHTML vs createElement mess, in terms of creating entire DOM trees. Each has its advantages and disadvantages. innerHTML is fast and easy, you pass in a string and it parses it as DOM in place, but it is insecure and dangerous. createElement and DOM creation/manipulation is great for small jobs, or for simple elements, but it quickly gets ridiculous to maintain. On the plus side, though, with createElement and in-memory DOM creation, we can attach listeners and populate the thing in memory before we even inject it.

But I have found a third way I like, which seems to combine the best of both worlds. Thanks to David Walsh's Blog, I can take a string (or string literal) and create my DOM structure in memory, and then manipulate it I like before injecting it.

That said, I created a utility function for the purpose:

const toHtml = (str) => document.createRange()
               .createContextualFragment(str.trim())
               .firstChild;

So passing in a valid DOM string consisting of a root node and any number of descendants, we get back a DOM tree. Very handy, and way easier to just type toHtml() to create simple or complex structures.

Now, back on task. The createWordBlankInput:

import toHtml from './toHtml.js';

const createWordBlankInput = ({id, type, entry})=>{
  const input = toHtml(`
<label class='wordblank-label'><span>${type}:</span>
  <input class='wordblank-input'
         type='text'
         placeholder="${type}"
         data-id="${id}"
         ${entry && `value="${entry}"`}>
</label>`)

  return input;
}

So that does the entire thing, creates the input and sets the custom values for us. In the parameters, we destructure the wordBlank object, pulling out the properties we'll use, and then we use those in the string literal.

What about the rest of the HTML for the WordBlanks game? That creates the inputs, but we need to wrap them in something! That'd be the WordBlankView:

const WordBlankView = ({filledString, wordBlanks})=>{
  let state = {
    blanks: wordBlanks.map(createWordBlankInput),
    filledString
  };

  const domEl = toHtml(`
<main class='wordblank-game'>
  <section class='blanks-pane'>
    <header><h2>Word Blanks!</h2></header>
    <ul></ul>
  </section>
  <section class='filled-pane'>
    <p></p>
  </section>
</main>`);

// just to tinker with the DOM in memory,since we *can*:
domEl.querySelector(".filled-pane p").textContent = state.filledString;
domEl.querySelector(".blanks-pane ul").textContent='';

domEl.querySelector(".blanks-pane ul").append(...state.blanks.map(blank=>{
  // and we take each of those `wordBlank` input elements we created
  //  in the state, wrap them in a <li></li> tag
  const el = document.createElement(`li`)
  el.append(blank);
  return el;
}) );

There it is: the WordBlankView expects an object with a string (the filledString) and an array of wordBlank objects. Using those, it creates an internal state, to hold the the filledString and blanks (which are those createWordBlankInput DOM elements).

We create the DOM using the same toHtml function, and then we can add stuff to that DOM as we like in memory, treating it as a DOM tree in itself. And finally, we return the DOM node we've created.

That's it. That's all there is. Mostly.

Yeah, but Wait.

Yep. We have the DOM and it is complete and self-contained. We have the model, and it is complete and self-contained. Each works independently of the other, so we could do this:

import WordBlanksFactory from './wordBlanksFactory.js';
import WordBlanksView from './wordBlanksView.js';

// we create the data model...
const wbModel = WordBlanksFactory("To be or not to be, that is the __noun__. Whether 'tis __adjective__ to __verb__ the slings and arrows of outrageous fortune...");

// and we create the view, passing in the model
const wbView = WordBlanksView(wbModel);

With that, the view doesn't care that it's getting a data model: it only expects an object with two properties. It doesn't matter what we passed in, so long as we adhered to that interface we defined in the view's function parameters, it's happy.

So now comes the sketchy bit: we can create the DOM, and the data model, but how can we track changes to the one and update them in the other?

Most commonly, folks would look at the DOM we've created, and create the listeners:

wbView.querySelector("input.wordblank-input").forEach((input)=>{
  input.addEventListener("input", (event)=>{
    const { dataset, value } = event.currentTarget; 
    wbModel.byId(dataset.id).entry = value;
    wbView.querySelector(".filled-pane p").textContent = wbModel.filledString
  })
})

And yaaay, it works! Celebration all around! Except nope. Remember, the view can't know about the data directly, and the data can't know about the view directly. We are creating a listener by poking inside the DOM (in effect breaking the encapsulation of the DOM component, and in that listener, we're poking stuff into and out of the data.

That, folks, is pollution. And we have a better way.

What if...

What if we could have the input itself tell us it was doing something? What if we don't attach listeners to the input ourselves, but we attach them to the view component? What if those events themselves told us, in an easy-to-consume way, what we needed to know? And what if we could tell the view to do things too?

We can. We have the CustomEvent API to do just that. Let's create a listener on the inputs themselves, and have them shout a custom event for us:

import toHtml from './toHtml.js';
// this is all exactly the same...
const createWordBlankInput = ({id, type, entry})=>{
  const input = toHtml(`
<label class='wordblank-label'><span>${type}:</span>
  <input class='wordblank-input'
         type='text'
         placeholder="${type}"
         data-id="${id}"
         ${entry && `value="${entry}"`}>
</label>`)

  // but before we return this, let's add an event handler:
  input.querySelector('input').addEventListener("input", (event)=>{
    // our custom event. It will bubble, so the main view will also
    //  be able to respond to it, and the detail property carries our
    //  custom payload.
    const changedEvent = new CustomEvent('wordblank.changed', {
      bubbles: true,
      detail: {
        id: event.currentTarget.dataset.id,
        value: event.currentTarget.value,
      }
    })

    // finally, we add our custom event to the event pipeline.
    input.dispatchEvent(changedEvent)
  })

  return input;
}

That is all we need. Just like that, our input element is shouting "Hey! Hey you! I've got a wordblank.changed for you! It happened on event.detail.id, which now contains event.detail.value, if you care!"

Why does that matter? Because our event handling can now change:

wbView.addEventListener("wordblank.changed", (event)=>{
  // we can destructure the event.detail to get the data we need,
  const {id, value} = event.detail;

  // tell the model to update that one value...
  wbModel.byId(id).entry=value;

  // and finally, notify the view that the data it uses has changed.
  const updatedEvent = new CustomEvent("wordblank.updated", {
    detail: wbModel
  })
  wbView.dispatchEvent(updatedEvent);
})

So rather than having to dip our sticky fingers into the view component, we simply listen for an event that the view component itself passes along. We use that event, taking the detail we need, notifying the model to update, and then we fire another custom event back into the view. We do that, because in updating one of the inputs, we have changed the filledString. So we pass the wordblank.updated event into the pipeline, passing the data back to the view.

Which means the view needs to be aware of this:


const WordBlankView = ({filledString, wordBlanks})=>{
  let state = {
    blanks: wordBlanks.map(createWordBlankInput),
    filledString
  };

  const domEl = toHtml(`
<main class='wordblank-game'>
  <section class='blanks-pane'>
    <header><h2>Word Blanks!</h2></header>
    <ul></ul>
  </section>
  <section class='filled-pane'>
    <p></p>
  </section>
</main>`);

  domEl.querySelector(".filled-pane p").textContent = state.filledString;
  domEl.querySelector(".blanks-pane ul").textContent='';

  domEl.querySelector(".blanks-pane ul").append(
    ...state.blanks.map(blank=>{
      const el = document.createElement(`li`);
      el.append(blank);
      return el;
    })
  );

  // and the new stuff: what event we pass *in*, and how to handle it.
  domEl.addEventListener("wordblank.updated", (event)=>{
    state.filledString = event.detail.filledString;
    domEl.querySelector(".filled-pane p").textContent = state.filledString;
  });

  return domEl
}

that last domEl.addEventListener is the handler for our custom event. When we notify it, it pulls the filledString out of the passed object, updates its own state, and updates its own DOM content as needed.

Note that, if we wanted, we could add functions internally to the view. If we wanted to hide the final string, for example, and only display it when the user has filled all the inputs? That is all functionality that could be contained within the view generator. It doesn't impact anything outside that scope, so you could (for extra credit) create a "Show the Quote" or "Edit the Words" toggle, flipping between those two panes. Doing so would not alter its functionality, or trigger any changes to the WordBlanks data.

Recap

Our goal was not to confuse you, but there are quite a few different ideas going on here. The goal was to decouple the data from whatever we use to display that data.

With the WordBlanksFactory, we could interface that to anything. It doesn't rely on any other component to function, it simply waits for updates, and tells us about those updates if we ask.

With the WordBlanksView, we have a complete DOM tree, completely separate from the data. It doesn't require a WordBlanksFactory to work, it simply requires an object that provides the data in a format it knows to expect. It emits and handles custom events, allowing us to talk to and listen to it, as though it were any other interface.

What we've done is weird, I grant. We have one traditional Factory function, with a nice interface, and a second traditional DOM tree, with an interface of its type... and we simply manage the communications between the two.

As always, I look forward to hearing questions, comments, snide remarks. Until next time!

Playing Around with DOM Styles

Toby Parent — Fri, 28 Jan 2022 15:42:17 +0000

If you've been at the front-end dev thing for a while, and you've learned all you need to know about manipulating the DOM and clever javascript, this is not for you. If you're brand-new, and you're learning that we can manipulate the DOM with javascript, this will eventually be for you, but it may be too much right now.

This is directed to a very particular set of learners: when we start tinkering with the DOM, and we find ourselves doing the same thing over and over again, we should consider how we can automate a solution to that. Any time we are repeating ourselves in code, it's a candidate worth refactoring. This is sort of an exploration of that refactoring thought process.

The Problem

When going through an online curriculum and learning about "DOM manipulation with javascript", you'll often see styles being set inline. At one point, it was considered bad form to apply styles inline, but that's a different animal: the reference is saying "don't apply styles directly in your HTML." For good reason: inline styles are the highest priority in the CSS realm. When we apply styles in the HTML, and we then move on to writing a stylesheet, we can't override those inline styles without resorting to !important. And, if we find ourselves using the !important style rule? We're doing something wrong.

But there is quite a lot of usefulness to setting styles inline, via javascript. We can do so in a few ways:

We could toggle a css class on a particular DOM node on or off, setting the styles for that element as we like (so long as that CSS selector rule has been defined),
We could directly tinker with the domNode.style attribute, setting styles inline.

That second one is what this is all about!

Option 1

There are times we want to be able to style DOM nodes, inline, with javascript. And that is fairly easily done. We can simply set all the styles we like, directly on the node, like this:

document.querySelector("#myNode").style = "background-color:red; color: aliceblue; font-size: 1.75em;";

And with that line, we set the styles for the element. Works great. Except that, if we have existing styles on the element, we have replaced the styles. By setting the style directly like that, we have effectively said "Whatever you had in the style before? Toss it. Here's the new style."

So if there were styles for padding, or border, or line-spacing... they have been completely replaced. Let's try someting similar, but a little different.

Option 2

Rather than setting the entire style, we can set attributes of that style. With this, the only thing being replaced is the particular attribute we are updating:

const myNode = document.querySelector("#myNode");
myNode.style.backgroundColor = 'red';
myNode.style.color = 'aliceblue';
myNode.style.fontSize = '1.75em';

This also works. We are setting each style as we like, we aren't blowing the entire style property away. So this is better, but we are far from best.

Since we're trying to find a way to optimize or automate that, and the core javascript system might not include the functionality we want built-in, it might be a great place to consider writing one or more functions. Suppose we wanted a function that simply lets us pass in a DOM node and a color, and updates the style.color for us:

const setColor = (domNode, color)=> domNode.style.color = color;

Seems a little silly like that. We wrote a function in three times the characters, to do what we could simply do inline. Still, it is an automated process. Let's make that a little more functional. What if we add a parameter in there, call it styleProp? That might be the style property name. Given the DOM node, the style property, and the CSS value, we can set that directly:

const setCSSProperty = (domNode, styleProp, value) => domNode.style[styleProp] = value;
// and how it might get used:
const myNode = document.querySelector('#myNode');
setCSSProperty(myNode, "backgroundColor", "red");
setCSSProperty(myNode, "color", "aliceblue");
setCCSSProperty(myNode, "fontSize", "1.75em");

It's more generic, maybe, but it's still longer than just editing the style properties ourselves. How is this saving us time?

It isn't any shorter to type, maybe, but it is a little more abstract. We can now automate that, if we want. For my own peace of mind, and because I like currying, let's rewrite that last one as a curried function:

const setCSSOn = (domNode) =>
  (styleProp) =>
    (value) => domNode.style[styleProp] = value;
// now, we can do this:
const myNode = document.querySelector("#myNode");
const styleMyNode = setCSSOn(myNode);
styleMyNode("backgroundColor")("red");
styleMyNode("color")("aliceblue");
styleMyNode("fontSize")("1.75em")

A curried function is useful in a case like this - note how we only pass in which node we want to style the first time? We have created a closure in that outer function, which stores the value domNode locally and reuses that each time we call styleMyNode.

I like this, this is a good direction. But it would be nice to not have to do each line like that, it's kind of ugly and not really saving us anything. So far, there is no benefit. But that last function, setCSSOn()? We want to keep that in mind. It is going to be in the sequel.

Option 3

So we have a way of setting a style on a node, functionally. That's great. But what if, like in that last one, we want to set a bunch of styles? Our function is useful, but not much more than simply setting the styles directly. We still haven't gained much.

Ah, Grasshopper, we're nearly there. What if we had a way to do this:

const myNode = document.querySelector("#myNode");
const styleMyNode= setStylesOn(myNode);

styleMyNode({
  backgroundColor: 'red',
  color: 'aliceblue',
  fontSize: '1.75em'
});

That starts to look pretty darn juicy, doesn't it? It is clean, it says exactly what we're trying to do, it is very functional, it can be automated... and let's face it: it's darn pretty. So how do we get there?

Let's look at what it is we want to do, given the function signature. We show a function, styleMyNode, that takes a DOM node, just like the setCSSOn function we just wrote. But then, rather than taking a property name and value, we have passed in an object. That object contains the style names in javascript format (so camelCase, rather than CSS's kebab-case), as keys to the data.

So we want to go through that object, pull each "key/value" pair out, and apply it to that DOM node. Seems pretty straightforward when we talk it through like that, huh? Let's try:

const styleMyNode = (domNode) =>
  (styleObject) => {
  Object.entries(styleObject).forEach( ([key, value])=>{
    setCSSOn(domNode)(key)(value) 
  })
}

so Object.entries takes an object, and returns an array of [key, value] pairs. In the case of our passed styleObject in the example, it looks like:

[
  ['backgroundColor', 'red'],
  ['color', 'aliceblue'],
  ['fontSize', '1.75em']
]

Then we forEach over that outer array, giving us each of those pairs in turn. Within that forEach, we destructure the array pair into a key and a value variable - which we then pass into our handy-dandy setCSSOn function.

A nice way to use something like this might be if we need to apply similar styles to all nodes of a given class:

const myStyles = {
  border: "1px solid silver",
  borderRadius: "10px",
  margin: "5px auto",
  padding: ".25rem .5rem 0 .75rem"
};

const myCells = document.querySelectorAll(".cell");

myCells.forEach((cell)=>styleMyNode(cell)(myStyles));

Now, that is cleaner - we can see at a glance what we're doing. For each element in myCells, we are calling styleMyNode and applying that style object we created. Wonderful!

Of course, not entirely what we like. Ideally, we might have been able to just call myCells.forEach(applyMyStyles) and not define that function inline. The problem we have is that we arranged the curried parameters in a particular order. Nothing wrong with that, until we see it in use.

As a rule, it's useful to arrange curried parameters from those less likely to change (the "static parameters") to those more likely to change (the "dynamic parameters"). In this case, as each element is getting the same style object, the static parameter is that style object - because each time we call the function, we want the same style object, but a different DOM node.

In order to fix this, in order to use this as a passable function, we need simply reorder the parameters:

const applyStylePair = ((domNode)=>
                        ([key, value])=> setCssOn(domNode)(key)(value))

const setStyles = (styleObject) =>
  (domNode) =>Object.entries(styleObject).forEach(applyStylePair(domNode))

// with that, we can now:
const applyMyStyles = setStyles(myStyles);

const myCells = document.querySelectorAll(".cell");

// now, when we pass the applyMyStyles function, it already
//  encloses that `myStyles` reference. We simply tell each
//  member of `myCells` to run that function, on that cell.
myCells.forEach(applyMyStyles)

Conclusion

Yes, it seems like work. Have we gained anything for all this? Well, sort of. Hopefully, we gained some understanding of ways to tinker with the DOM, and with objects in general. We have had a bit of a thought experiment, we've seen some impact regarding the order of parameters, and we've had a bit of fun.

Is this something you'll use every day? Not likely. Being able to apply multiple styles to multiple DOM nodes is fun and educational, but practically speaking, there may be other and better ways up this mountain. Tools like React's styled components do this same thing, and we often use them without necessarily thinking about what that represents.

Decomposing Composition

Toby Parent — Thu, 16 Dec 2021 05:21:45 +0000

Functional libraries like Ramda.js are great, and give us some very powerful, useful, simple functionality. But they’re the kind of thing you might not know you need, unless you know you need them.

I’ve been reading (well, okay, _devouring) Eric Elliott’s Composing Software book (and before that, the series of blog posts). Powerful read, easy to understand, lot of meat under that skin. But it’s easy to get lost in there. Trying to understand both the what and why of function composition (and later, object composition) can be challenging.

So I wanted to break it down into a step-by-step, and see if we can make more sense of this as an “evolution of the idea.”

Defining the Problem

Let’s take an absurd example, reversing a string. It’s a lesson we see in all sorts of introductory lessons, and the steps are pretty easy to follow:

turn the string into an array of letters,
reverse the array of letters,
rejoin the reversed array back into a string,
return the reversed (transformed) string.

Easy to follow, and easy to write. A perfect introduction to methods of core objects in javascript.

Step 1

const reverseString = function reverseString(string){
  const stringArray = string.split('');
  const reversedStringArray = stringArray.reverse();
  const joinedReversedStringArray = reversedStringArray.join('');

  return joinedReversedStringArray;
}

So we take each step of the problem, and do that thing. Each step is assigned to a variable because we can, and that variable is passed to the next step as its input. Easy to read, but kind of wasteful.

Wasteful why? Because of method chaining. When we call String.prototype.split(), that returns an array, and we can chain directly onto that. The Array.prototype.reverse() acts on an array and modifies it in place, returning the same array, and Array.prototype.join() returns a string, which we are returning. So we can call each of those methods on their returned result, without needing the intermediary variables

Step 2

const reverseString = function reverseString(string){
  return string.split('').reverse().join('');
}

And that does all four steps in one line. Beauty! Note the order of the functions being called there — we split the string, we reverse the array, we join the array.

It is much shorter, and it reads very well. This is often the solution that we as mentors in online programming courses might point to as the cleanest and easiest solution, and it really works. And it does get us closer to where I want us to be.

But this? This is about functional composition. We’ve got a ways to go yet, but we’re closer. Let’s look at another way of doing much the same thing, see if that helps.

Pre-Step 3

While chaining is a great way to go, in terms of readability, it doesn’t really compose well. We can’t build with chained methods like Lego blocks, snapping them together and rearranging as we like. To do that, we need to consider another way of passing data from one function to another.

The pattern of what we’re about to do, in a mathematical sense, might look more like this:

// given functions f, g, and h, and a data point x:  
return f( g( h( x ) ) )

We are taking value x, pushing it into function h (getting “the h of x”), and then taking the returned value from that and pushing it into g (getting “the g of h of x”), and then taking the returned evaluation from that and pushing it into f (getting “the f of g of h of x”).

It makes sense, but it hurts to think in f and g and h and x hurt my little button-head. Let’s make it a bit more concrete.

/***
 * for reference, this was the mathematical idea:
 *
 * return f(
 *         g(
 *           h(
 *             x  
 *           )
 *         )
 *       );
 ***/

// and the concrete example:
return join(
          reverse(
            split(
              string  
            )
          )
       );

So that is doing the same thing - it gets the "split of string", passes that to get "reverse of (split of string), then passes that out to get "join of reverse of split of string." Sounds silly worded that way, but it's part of the mental model. Our function is composed of these steps, in this order.

Step 3

// some utility functions, curried.
const splitOn = (splitString) =>
  (original) =>
    original.split(splitString);

const joinWith = (joinString) =>
  (original) =>
    original.join(joinString);

const reverse = (array) => [...array].reverse();


const reverseString = (string) => {
  // partially-applied instances of our utilities
  const split = splitOn('');
  const join = joinWith('')

  return join(
           reverse(
             split(
               string
             )
           )
         );
}

There is quite a bit more meat to this one, and it will require some explanation to grok fully what is going on.

First, before we do the reverseString, we want to turn those Array or String methods into composable functions. We’ll make some curried functions, because who doesn’t like abstraction?

splitOn is an abstract wrapper for the String.prototype.split method, taking as its first parameter the string on which we’ll split.
joinWith is an abstract wrapper for the Array.protoype.join method, taking as its first parameter the string we’ll use for our join.
reverse doesn’t take any parameters, but it turns Array.prototype.reverse into a composable function in itself.

Now, within our reverseString, the first step is to partially apply those two abstract functions. We tell split that it is a reference to splitOn(''), we tell join that it is a reference to join.with(''), and then we have all the parts we need to combine three functions into one call.

This is much better, as we can now see each function, and the order in which they are applied. But this reads a little bit differently than the original chained example. That one read in left-to-right order:

// given string, call split, then call reverse, then call join  
return string.split('').reverse().join('');

In functional circles, this is considered “pipe” order. The term comes from the Unix/Linux world, and leads down a whole ‘nother rabbit hole.

Our latest code, rather than reading left-to-right, is processed inside-to-outside:

return join(  
  reverse(  
    split(  
      string  
    )  
  )  
);

So if we read these in that same left-to-right order, join, reverse, split, we execute them exactly backwards of that. This would be considered “composed” order, and now we’re about to venture into composed-function-land!

Pre Step 4

This is where things start to get fun. First thing to remember is this: functions in javascript are just another kind of data (and thanks, Dan Abramov for the mental models from JustJavascript!). In javascript, we can pass ’em, we can store ’em in arrays or objects, we can manipulate them in fun and exciting ways… and we can combine ’em. And that’s just what we’ll do.

In this iteration, we are going to place all our functions in an array, and then we will simply ask that array to perform each function in turn on a given piece of data. The concept is easy to understand, but again — concrete examples are helpful.

Step 4

// again, the helpers:
const splitOn = (splitString) =>
  (original) =>
    original.split(splitString);
const joinWith= (joinString) =>
  (original) =>
    original.join(joinString);
const reverse = (array) => [...array].reverse();

// with those, we can write this:
const reverseString = (string) => {
  const instructions = [
    splitOn(''),
    reverse,
    joinWith('')
  ];

  // let's define our transforming variable
  let workingValue = string;

  for(let i=0; i<instructions.length; i++){
    // apply each function and transform our data.
    workingValue = instructions[i](workingValue)
  }

  return workingValue;
}

This is nicely abstracted — inside the reverseString, we simply create an array of instructions and then we process each one, passing the most recently transformed data in.

If that sounds like a sneaky way of saying we are reducing the array of instructions, you’re either paying attention or reading ahead. 😉

That is exactly where we are going. We are taking an array of instructions, using workingValue as the starting “accumulator” of that array, and reducing the workingValue to the final evaluation of each of those instructions, applying the workingValue each time. This is precisely what Array.prototype.reduce is for, and it works a treat. Let’s go there next!

Step 5

// I'll leave those helper methods as written.
// Imagine we've placed them in a util library.
import { splitOn, reverse, joinWith } from './utils/util.js';

const reverseString = (string) =>{
  const instructions = [
    splitOn(''),
    reverse,
    joinWith('')
  ];

  return instructions.reduce(
    (workingValue, instruction) => instruction(workingValue),
    // and use string as the initial workingValue
    string
  )
}

Here, we’ve taken that imperative for loop and made it a declarative reduce statement. We simply tell javascript "reduce the original workingValue by applying each instruction to it in turn." It is a much more structured way to code, and if we want, we can always add, alter, rearrange the instructions without breaking the way that reduce function call works. It simply sees instructions, and does instructions. Is a beautiful thing.

But it would be a colossal pain to have to write each function that way. The concept will be much the same any time we want to combine a number of functions — we write the instructions, then we transform some datapoint based on those instructions. Sounds like another candidate for abstraction.

Pre Step 6

Given that we’re working with the instructions in first-to-last order, we’ll talk about writing a pipe function first. It’s an easy step from that to reduce, and in terms of how we think, pipe order may make more sense.

So what we want is a function that takes an array of functions, and applies them to a particular data point. Internally, we know it’ll be a reducer, but how might that look?

const pipe = (...arrayOfInstructions) =>
  (value) =>
    arrayOfInstructions.reduce(
      (workingValue, instruction)=>instruction(workingValue), value
    );

// or, with shorter variable names:
const pipe = (...fns) => (x) => fns.reduce( (acc, fn)=>fn(acc), x)

Those two are exactly the same — the first simply has longer variable names to make it easier to see what’s happening.

So we’ve made a curryable function here. By partially applying it (passing in any number of functions), we get back a function that wants a value. When we give it a value, it will apply each of the instructions to that value in turn, transforming the value as it goes along. Each time, the latest iteration of that transformed value will be used for the next step, until we reach the end and return the final transformation.

How might that help us? Remember, we want returnString to be a function that takes a value. And we want to give it a series of instructions. So how’s this look?

// again with our utility functions:
import { splitOn, reverse, joinWith } from './utils/util.js';
import { pipe } from './utils/pipe';

const reverseString = pipe(
  splitOn(''),
  reverse,
  joinWith('')
);

So we call in our utility functions, and we call in our pipe function, and then we’re ready to begin. We partially apply the instructions to pipe, which returns a function expecting a value — which is exactly what we want reverseString to be! Now, when we call reverseString with a string argument, it uses that string as the final argument to the reducer, runs each of those instructions, and gives us a return result!

Look closely, though: our reverseString is a function, defined without a body! I can't stress enough, this is weird. This is not what we're accustomed to when we write functions. We expect to write a function body, to arrange some instructions, to do some stuff - but that is all happening for us. The pipe function takes all the function references passed in above, and then returns a function... awaiting a value. We aren't writing a reverseString function, we're sitting in the pipe function's closure!

Remember above when I explained that we can look at pipe as similar to chained order? If you read the above pipe call, you can read it in the same order. But when we compose, it is the reverse of pipe — while we might read it left-to-right (or outermost to innermost), it should process from right to left. Let’s write a compose function, and compare it to pipe.

// remember,this is our pipe function in the compact terms
const pipe = (...fns) =>
  (x) =>
    fns.reduce( (acc, fn) => fn(acc), x);

// compose is eerily similar - we just want to reverse-order
const compose = (...fns) =>
  (x) =>
    fns.reduceRight( (acc, fn) => fn(acc), x);

If you look at those two functions, the only difference between them is that pipe uses fns.reduce() while compose uses fns.reduceRight(). Otherwise, nothing has changed. We could test them easily, if we wanted:

import { splitOn, reverse, joinWith } from './utils/util.js';
import { pipe, compose } from './utils/my_fp_lib.js';

const pipedReverseString = pipe(
  splitOn(''),
  reverse,
  joinWith('')
);

const composedReverseString = compose(
  joinWith(''),
  reverse,
  splitOn('')
);

// let's use them!
console.log(
  pipedReverseString('Hello World')===composedReverseString('Hello World')
);
// logs true

Note that this is hardly the best explanation or implementation of pipe and reduce. There are far better, more robust FP libraries out there doing a far better job of implementing this. But what I’m doing here is more about explaining the how of it, for some who might be intimidated by the whole idea of functional composition. It doesn’t have to be intimidating, really. When we break it down to smaller steps, we can see that we already know most of this — it is simply how we combine that knowledge together.

And when I wrote something similar to this some time back, the biggest critique I got was “what’s the point? I’m not gaining anything by writing little functions for every little detail!” There is some truth to that, for the person who made the comment. For me, having that compose functionality means that my more complex functions become testable and debuggable quickly and easily, my development becomes more about what I want to do and less about how I’ll do it, my thinking becomes more abstract.

For example, suppose we wanted to add some inline debugging to the pipe version of our reverseString function? We could easily add that, without breaking anything:

import {splitOn, reverse, joinWith} from './utils/util.js';
import { pipe } from './utils/my_fp_lib.js';

// this would be a candidate for a useful function to add to util.js
const trace = (message) => {
  (value) => console.log(message, value);
  return value;
}

const reverseString = pipe(
  trace('Starting Value'),
  splitOn(''),
  trace('After split'),
  reverse,
  trace('After reverse'),
  joinWith('')
);

console.log(
  reverseString('Hello World')  
);
/***
 * logs out
 * Starting Value Hello World
 *
 * After split [
 *   'H', 'e', 'l', 'l',
 *   'o', ' ', 'W', 'o',
 *   'r', 'l', 'd'
 * ]
 *
 * After reverse [
 *  'd', 'l', 'r', 'o',
 *  'W', ' ', 'o', 'l',
 *  'l', 'e', 'H'
 * ]
 *
 * dlroW olleH
 ***/

The only thing we’ve changed here is that we’ve added a trace function, something we couldn’t do with a chained function call or a normal nested series of functions. This is one of the secret superpowers of composition — we can combine things easily that might not be easy or obvious otherwise.

Edit: There was a typo in the trace function - we want that to return the value, so we continue to pass it up (or down) the pipe (or compose).

Recap

I hope this helped clear up some, for those (like me) who were initially confused looking at Eric’s compose and pipe functions. Not because they were poorly written at all, simply because I was still thinking in a linear style and these functions are next-level.

I wanted to take us from the 101-level javascript, and start looking at how we might easily take the knowledge we already have and turn it into something more. First, by exploring two different ways of doing the same things — chained methods or nested function calls. Each does similar things, but the mindset and reading-order behind both are a bit different. Both are equally valid, and both apply to functional composition.

If you got these concepts, you’re already well on your way down the functional programming rabbit-hole. Welcome to the madhouse, have a hat! If you didn’t quite get the concepts yet, it’s not a failing — these are deep and twisty applications of ideas. You get a hat anyway!

Getting Funky With Filters

Toby Parent — Mon, 13 Dec 2021 17:21:06 +0000

Some time back, I was playing around with filters. Again, the question had been asked, "can I filter an array of objects by more than one property? The answer, of course, is yes. There are two main ways of doing this, using Array.prototype.filter(), and we'll start by talking about both.

Let's say, for the sake of argument, that we had a sample data JSON object of 1000 users. If you want to make one to play around with, I found a GREAT data-fakery site that created a 1000-user JSON object for me, over at Mockaroo . It's pretty customizeable, and for this, it worked WONDERS. Here's a sample of one of the objects:

{
    "id": 617,
    "first_name": "Orly",
    "last_name": "Ilieve",
    "email": "oilieveh4@bloomberg.com",
    "job_title": "Structural Analysis Engineer",
    "age": 75,
    "gender": "Female",
    "language": "Fijian",
    "favorite_color": "Crimson",
    "last_login": "7/19/2019",
    "online": true
  },

So we have a users array, containing 1000 of those. Suppose we wanted to filter by language=="Arabic" and also online==true. We could do this easily, using Array.prototype.filter(), in one of two ways:

First, we could filter once, then reduce the filtered array by filtering again.

const arabicSpeakers = users.filter(user => user.language=="Arabic");
const arabicOnline = arabicSpeakers.filter(user=> user.online===true);

Or in a single pass:

const arabicOnline = users.filter(user=>user.language=="Arabic").filter(user=>user.online);

And that works great. I did shorthand the second filter, as the filter function is checking for a true/false value - and if the user is online, we simply return that true.

The downside is, if there are a LOT of records returned by the first filter, then we're repeatedly touching all those records... twice. filter() is not a fast alternative to a simple for(...) loop, in fact it has considerable overhead - particularly if the dataset is massive.

So the second option: we could check all the object properties at once, simply filter for more than one property. This requires that we understand a little about javascript's logic operators, as we'll use || or && (logical OR and logical AND, in order), but let's see how that would look:

const arabicOnline = users.filter(user=>user.language=="Arabic" && user.online )

That is considerably shorter, and loses the overhead of touching multiple records every time. That does the trick! But...

Here we go.

What if we wanted to change that filter some? Suppose we wanted to get all users currently online who spoke Arabic, or who were women who like the color Crimson? Well, that gets a little more complicated, but if we parse it out, we get something like:

if user.online AND (
   user.language=="Arabic" OR (
     user.gender=="Female" AND 
     user.favorite_color=="Crimson"
   )
)

We will use the parentheses in our function, but the use of conjunctions will change:

const filteredList = users.filter(user => user.online && (user.language=="Arabic" || (user.gender=="Female" && user.favorite_color="Crimson" ) );

And that can get tedious. But there are TWO points I'm making here. First, we can do really complex filters on arrays of objects, and they work just fine. And second, there's got to be a better, cleaner way. And that's what this post is about!

Teeny tiny bites

So, the point of all this is... functional programming. I was so excited last week, got all crazy excited, because I was building these insanely massively nested filter queries, and it was WORKING. Blew my mind, and I was so excited about sharing it. Until I actually shared it.

The folks I chose to share with are professionals, both peers and those I consider to be mentors of mine. And, while they thought it was neat, they were just not as excited as I was. And that bothered me, for quite a while, until I realized - they weren't excited because it's a fundamental thing.

There are things that are so simple that, when we realize them, we wonder that they weren't common knowledge before. But they likely were. The issue isn't the knowledge, then, but that I may not be part of the "tribe" where that knowledge is common.

So, if you're one of those who already know this, great! This may just be a refresher for you. And that's okay. But for the rest of the class, this can be eye-opening.

So let's jump back a bit. We have a number of filter functions, right? If we look back at that last compound filter, there are four basic conditions we check for:

Is user.online===true?
Is user.language==='Arabic'?
Is user.gender==='Female'?
Is user.favorite_color==='Crimson'

Those are the basic conditions. Each of those can be run as unique, independent functions, each can be used as a filter, and each is testable in isolation. And (and here's the power of functional programming) each is composable.

What does this mean? Let's start by writing out each of those four as a function in themselves:

const isOnline = user => user.online;
const isArabic = user => user.language === 'Arabic';
const isFemale = user => user.gender==='Female';
const likesCrimson = user => user.favorite_color==='Crimson';

And that works fine. Each one is testable against an array of objects, each returns a true or false based on the user's property matching as we want, each does what it says on the box. Incidentally, in terms of conventions, functions that return a true or false are called predicate functions (as in "decisions are predicated on this thing").

But it's ugly, and inelegant. I don't like it. Nope. Nuh-uh.

Why not? Because each line does the exact same thing: given a property, find a given matching value on some object. They all do the same thing. So we're repeating code unnecessarily. What can we do? We can step back one step further. We can abstract that out, by writing a generic function, which we'll call filterByProp(). I use the full name like that, because I also have a sortByProp(), a findByProp() and a reduceByProp(), all of which use the same basic idea: given an array of objects, work with a given property. Here's how this one might look:

const filterByProp = (prop) 
  => (val) 
    => (obj) => obj[prop]===val;

That's it. That's the whole shebang. We start by calling filterByProp() with the property name we want to filter by, and we get a function back. That function is waiting for a value to which we compare that property. So we call the function we just got back, passing a value, and we get another function back, that's waiting for the object itself. This third function? That's the one that our filter function can consume.

And here's one way to look at using it:

const byOnlineStatus = filterByProp("online");
// byOnlineStatus is now a function, waiting to be
//  given a value to match that property against.

const isOnline = byOnlineStatus(true);
// and isOnline is now the same function as we wrote
//  above: isOnline = (user) => user.online===true;

What we've done here is functional currying. We've started with a function, and passed in a value, and got back a function awaiting a second value. When we pass in that second value, we get a function awaiting the third, the final object against which we'll check. A shorthand version of the same isOnline() might look like this:

const isOnline = filterByProp("online")(true);
const isArabic = filterByProp("language")("Arabic");
const isFemale = filterByProp("gender")("Female");
const likesCrimson = filterByProp("favorite_color")("Crimson");

Again, they each work in isolation, they can each be tested, both in isolation and in integration, they are tidy, and they are elegant.

When I speak of elegance here, I mean that, within our filterByProp() function, I have zero knowledge of what's going on inside our object. I don't hard-code into the function itself what those properties or values might be, I simply create a function that says "Hey, I've got some object - tell me if it has this property-value pair". It's object-agnostic.

So with those pieces, we could now do:

const filteredList = users.filter(
  user => isOnline(user) &&
         (isArabic(user) ||
           ( isFemale(user) && likesCrimson(user) 
         )
       );

Much more succinct, much more readable, our filter has become... well wait. Not so much. In order to compose our functions, we need to call them all inside our outer function. The way we've done this, you'll note that each of our inner filter functions is being called independently. Not so pretty, not so well documenting.

What to do, what to do...

Here's my thinking: what if we had a mechanism that would let us compose those functions into larger pieces, each of which can simply be plugged in as a filter function?

To do this, we'll need functions that combine our filters, and we want to combine them in two different ways: we want to replace the && with a function we'll call and(), and replace the || with a function we'll call or(). Each of these should take multiple functions as parameters, and return a function that checks if all the conditions of those functions are met (in the case of and), or if some of them are met (in the case of or). So let's dive in:

// So we pass in any number of parameters, and we turn
//  that into an array of funcs. We want every func in
//  that array to return true for a given object.

const and = (...funcs) => obj => funcs.every(func => func(obj) ) 

// now to use this, we can combine our functions, taking
//  (isFemale(user) && likesCrimson(user) ) and turning it to:
const isFemaleAndLikesCrimson = and(isFemale, likesCrimson);

// The or function is exactly the same, except for the function
//   we use on the array of funcs:
const or = (...funcs) => obj => funcs.some(func => func(obj) );
// Here, we are saying "if one or more of these pass, I'm good!"

// with this one, we can combine the next level out: We've gone from
//  (isArabic(user) || (isFemale(user) && likesCrimson(user) ) )
// to
//  (isArabic(user) || isFemaleAndLikesCrimson)
// so next we simply:
const isArabicOr_IsFemaleAndLikesCrimson = or(isArabic, isFemaleAndLikesCrimson);

// and, for the final piece of our complex filter function:
const isOnlineAnd_IsArabicOr_IsFemaleAndLikesCrimson = and(isOnline, isArabicOr_IsFemaleAndLikesCrimson);

Note that I used the underscores simply to denote groupings, but they're not necessary. I worked from the innermost combination out, composing larger and larger functions that, as a final result, return the exact same data type as the composed functions. Why does that matter? They become interchangeable. Our ridiculously-long-named function can now be used as a filter function's callback:

const filteredList = users.filter(isOnlineAnd_isArabicOr_isFemaleAndLikesCrimson);

So that function we pass into the filter function is now complete and self-documenting. We can see at a glance what we're filtering for (though I would really prefer a way to delineate the separation between ors and ands - if anyone has suggestions, I'm open to them!), we can read what's happening, we can test each smaller part in isolation, and each larger part as we grow, and we have a great start for a functional toolkit.

I suppose, if we wanted to keep it nice and legible, we could back it up a small step:

const filteredList = users.filter( 
  and(isOnline, 
    or( isArabic, 
      and(isFemale, likesCrimson)
    )
  )
);

That is a more readable version. The outermost and(...) is the function actually being called by the filter(...), and that one is simply composing its two parameters into an array on the fly, and so on, down the line.

What's the takeaway?

Good question, that. First, that we can compose small, simple functions into very complex ones that still do simple things. Second, that those small parts, while unaware of things outside themselves, can be very powerful with those things of which they are aware. And third, that we have the beginnings of a functional library:

// This is a great tool to add to a functional library, and one you can use over and over for other situations.
const filterByProp = (prop) => (value) => (obj) => obj[prop]===value;

// the two functions, and() and or(), are powerful composers.
const and = (...funcs) => (obj) => funcs.every(func => func(obj) );
const or = (...funcs) => (obj) => funcs.some(func => func(obj) );

There are others, we'll continue to grow this collection, but this is a good place to start.

Forem: Toby Parent

A Simple Observer in Vanilla Javascript

Observers in the Real World

Observers You May Already Know

Observers Are Not Standalone

The Scenario

Exploring an interface

Starting Steps

Okay, so what?

Going back to go forward

Well yeah, but... why??

Extra Credit

Templating with TinyBase, Tailwind, and RippleUI

Some Setup Stuff

A Handy Utility Snippet

A Header Template

... And a Layout Template

Composing the View

Getting Back to TinyBase

Updating the Color Theme

Wiring the Light Switch

Responding to Changes

To Recap

First Steps With TinyBase

Reactive Data Store

A Quick Idea...

Getting Started

1. Setting up shop

2. Creating a Store

3. Defining an Abstract Model

4. Creating Instance Models

Let's Consider Structure

We Have the Power!

Extending the Data Models

Indexes vs Relationships

That's Nice and All, But... Why?

Extending Collections

What Does That Even Mean?

A Little Background

Well Yeah, But What Do We DO With It?

To Recap

Understanding Higher-Order Functions

The What

The Why

Meanwhile, Back On The Farm...

Looking Ahead

Are You a Collector?

What might a Collection look like?

The Point

A Step Closer

Yeah, But How Does That Help?

Yeah, But Why?

One More Possibility...

Next Steps

Factories and Closures, or Classes and Constructors... Does It Matter?

The What

The Why

The Bugs

Issue 3: We need an interface

Issue 2: Data as Data

Issue 1: Constructors vs Closures... should it matter?

Enough of That, More Code

Now - to the Lab!

The Recap

Fairy Tales, and the Implications of Immutability

The Fairy Tale

A Different Moral

The Problem

Why Immutability Matters

Wrong.

Why?

Simple Fixes

Other Gotchas

The Point

Concerning the Separation of Concerns

The Problem

First Steps

Modelling the Data

A Quick Aside...

Back on Task: Planning Interfaces

What might a `Collection` look like?