DEV Community: Je We

Wrestling With Time: Creating a Sequencer with NexusUI & Tone.js

Je We — Sat, 30 May 2020 17:33:16 +0000

Hello again! I'm continuing what has become a series of blogs about integrating NexusUI with Tone.js to create musical instruments for the web. You can read the other posts here, here, and here.

My latest challenge was to build a sequencer. If you don't know what a sequencer is, it's an interface that allows the user to plan out a loop of sounds, which will then be played back very precisely by an internal clock. The contents of this loop can also be changed in real time. You sit back and relax as a robot plays back your perfect arpeggios, and soon you're making star-gazing cheese like this.

NexusUI provides a very nice-looking sequencer interface:

Rendering the sequencer is simple:

const sequencer = new Nexus.Sequencer('#seq', {
   size: [400, 200],
   mode: 'toggle',
   rows: 6,
   columns: 16,
 });

This will create a new sequencer on the page, injected into the element with id 'seq', with the specified number of rows and columns. Each row represents a possible instrument or sound, and each column represents a beat in the cycle. Any number of the squares in each column can be toggled on or off. To proceed to the next beat, simply use the sequencer's next method. This will trigger a 'step' event on the sequencer, which will allow us to track the value of that beat.

sequencer.next();

sequencer.on('step', (col) => {
  console.log(col) // [0, 1, 0, 1, 1]
});

The value of the beat is returned in an array of 1's and 0's (1 meaning instrument on, 0 meaning off), listing the column from bottom to top.

This first beat of this sequencer would return [1, 0, 0, 0, 0]

And the first beat of this one would return [0, 0, 0, 0, 1]

This setup provides us with a nice road map for going forward: on each step of the sequencer, simply iterate through the value of the current column, and for any toggled indices, trigger synths stored in an array with corresponding indices. There is one big obstacle though: TIME.

At first, I didn't know this would be a problem. I attempted a naive solution in which I used Tone Transport, which allows the scheduling of one-time audio events as well as loops. I went for Tone Transport's scheduleRepeat method, which allows for a callback function to be called at a specified interval. It looked a little like this:

sequencer.on('step', (col) => {
  this.col = col; // store current value of col
 });

Tone.Transport.scheduleRepeat(() => {
   this.sequencer.next(); // step to next beat
   this.col.forEach((state, i) => { // iterate through new col value
     if (state) { // if toggled, trigger corresponding synth/note
       this.synths[i].triggerAttackRelease(this.notes[i]);
     }
   });
 }, '0.5'); // repeat every half second

I sat back, relaxed, and listened to my sequencer. It sounded extremely drunk. I was about to discover that JavaScript hates music. You might notice that my use of scheduleRepeat above basically amounts to a fancy version of setInterval. It turns out that setInterval and setTimeout, while seemingly very exact to the human eye & intuition, are actually noticeably inexact when it comes to musical timing. This is because, since setInterval and setTimeout are asynchronous, their callbacks are only executed once the callstack of synchronous, blocking code is cleared, leading to slight fluctuations in timing that are not usually noticeable to reasonable people, but are noticeable to those people's unreasonable ears. More can be read on the subject here. The Web Audio Clock, on the other hand, is an independent entity, free from any conflicting concerns that might effect its accuracy, and so the best context for scheduling audio events.

I had even read (but chosen to ignore) this revealing sentence in Tone's docs:

"Unlike browser-based timing (setInterval, requestAnimationFrame) Tone.Transport timing events pass in the exact time of the scheduled event in the argument of the callback function. Pass that time value to the object you’re scheduling."

Luckily, the solution is simple. Tone synths can be triggered immediately (as I was doing), or they can be given a time to be played. Tone Transport passes this exact Web Audio time to its callback function, which can then use it to schedule the appropriate synths at the appropriate times:

Tone.Transport.scheduleRepeat((time) => {
   this.sequencer.next();
   this.col.forEach((state, i) => {
     if (state) {
       this.synths[i].triggerAttackRelease(this.notes[i], '8n', time);
     }
   });
 }, '0.5');

The arguments to triggerAttackRelease are pitch, length, and scheduled time. This will give us a very rhythmically accurate sequencer!

Hope you've enjoyed reading. Please post any questions you might have, and have some fun playing with my demo here! It has some features, like tempo control and custom scales/voices, which I'll cover in a future post.

Sending Audio Over Sockets Using Socket.io and Tone.js

Je We — Sun, 24 May 2020 19:34:38 +0000

Recently, I've been working to create collaborative music chat rooms. I knew to do this I'd need to send audio information over a socket connection. At first, I assumed this would be a long, difficult problem, but when I took a step back I realized that I could send relatively simple information over sockets, as long as I implemented a way to interpret that data when received and trigger the correct audio response.

Of course, the first step was to set up my socket connection. For my back end, I'm using Express. Here's a simplified version of my initial setup:

const express = require('express');
const socketio = require('socket.io');

const app = express();

const server = app.listen(8081);

const io = socketio(server);

io.on('connection', (socket) => {
  // socket event listeners go here
});

I'm using VueJS for my front end, so I took advantage of Vue-Socket.io, which allows for some convenient ways to emit and receive socket messages from any component within your app. Now, if you're not using Vue, don't give up on this guide! Some of your client-side will necessarily look different, but the logic should be pretty similar.

Now, to be able to use Vue-Socket.io, I needed to set up a client-side connection to the server-side socket, and then use that as the connection option for my globally available Vue-Socket.io plugin.

import 'socketio' from 'socket.io-client';
import 'VueSocketIO' from 'vue-socket.io';

// make connection to server socket
export const connection = socket.io(':8081');

// make Vue-Socket.io globally available
Vue.use(VueSocketIO, connection);

Thanks are due to this very clear guide by Joshua Bemenderfer for this setup.

Now, I wanted to create a way for the music jam rooms to be distinct from each other, meaning that only users in the same room would be able to hear each other, rather than everyone being lumped together in one noisy room. This would mean assigning each jam room a unique socket namespace, which could be accessed through that jam room's URL query.

First, I dealt with the situation in which someone makes a new jam room, simply by navigating to the Jam component. I'm using Vue Router, which allows for a variety of navigation-related hooks. In this case, I used beforeRouteEnter, which executes before the navigation is completed, to add a random string as the route's query. I used the aptly named randomstring library to create this random query. My plan was to use this query as the unique namespace for the jam room, meaning that anyone with the link would automatically be connected to the same namespace.

beforeRouteEnter(to, from, next) {
  if (to.fullPath === '/jam') { // only runs if this is a new jam room
    next({
      path: '/jam',
      query: { room: randomstring.generate() },
    });
  } else { // do nothing if following a link to existing room
    next();
  }
}

This gives me a unique URL, e.g. http://localhost:8080/jam?room=WwwCbmpKGaPBoXNAvKx9ln2wfbfYCDZ7. If not using Vue Router, the above could also be accomplished by manually setting window.location.search for certain conditions.

Now that every jam room had its own unique query, the next step was to use that query to connect to a socket namespace. On mount, the unique namespace was accessible with this.$route.query.room. Thanks to Vue-Socket.io, I was able to emit a socket message from any component using this.$socket.

mounted() {
 this.$socket.emit('join', this.$route.query.room);
}

This sends out a 'join' message for this particular room, but is anyone listening? Not at the moment. I needed to add a server-side listener for this message that would subscribe this particular client's socket to this room's namespace:

io.on('connection', (socket) => {
  socket.on('join', (room) => socket.join(room));
});

Now, with distinct jam rooms, the next step was to actually start sending some audio information over those sockets. At this point, I already had a keyboard-controlled piano that made sound on the individual client (you can read about its setup here and here), so it was just a matter of sending and interpreting messages that allowed those same sounds to be reproduced on other clients.

The meat of the piano code is the piano change event handler, which starts a note when a key is toggled on, and stops the same note when that key is toggled off:

piano.on('change', (k) => {
  if (k.state) {
    if (!activeSynth[k.note]) {
      activeSynths[k.note] = new Tone.Synth().toMaster();
    }
    activeSynths[k.note].triggerAttack(note(k.note));
  } else {
    activeSynths[k.note].triggerRelease();
  }

So what if I just sent out start and stop messages to the appropriate room, containing the note in question?

piano.on('change', (k) => {
  if (k.state) {
    if (!activeSynth[k.note]) {
      activeSynths[k.note] = new Tone.Synth().toMaster();
    }
    activeSynths[k.note].triggerAttack(note(k.note));
    this.$socket.emit('startNote', {
      note: k.note,
      room: this.$route.query.room
    });
  } else {
    activeSynths[k.note].triggerRelease();
    this.$socket.emit('stopNote', {
      note: k.note,
      room: this.$route.query.room
    });
  }

Working with sockets is really like coordinating a game of catch. Now that my piano was sending out start and stop messages, I needed my server to catch these messages and then distribute to the other clients in the same room. Because I didn't want the user playing the piano to receive their own sound, I used socket.broadcast to exclude their client.

socket.on('startNote', ({ note, room }) => {
  socket.broadcast.to(room).emit('receiveStart', note);
});

socket.on('stopNote', ({ note, room }) => {
  socket.broadcast.to(room).emit('receiveStop', note);
});

Finally, I bounce back to the client and add some socket listeners there. With Vue-Socket.io, I can do this in the sockets object, with methods named for the messages for which they listen. Upon receiving a signal to start or stop a note, I essentially wanted to reproduce the behavior already in place locally when a user presses a key on their keyboard.

sockets: {
  receiveStart(midi) {
    // if there is not yet a dedicated synth for this note, create one
    if (!this.activeExternalSynths[midi]) {
      const synth = { [midi] : new Tone.Synth().toMaster() };
      // add new synth to activeExternalSynths object
      this.activeExternalSynths = {...this.activeExternalSynths, ...synth };
    }
    // start playing the note
    this.activeExternalSynths[midi].triggerAttack(note(midi));
  },
  receiveStop(midi) {
    // release the currently playing note
    this.activeExternalSynths[midi].triggerRelease();
  },
},

And that's all there is to it! Of course, as you start wanting to create more and more complex sounds, there will be more information you need to send and interpret to share these sounds with other users, but this should be a good starting point. Thanks for reading!

Building a Simple Piano with Tone.js and NexusUI (Part 2)

Je We — Sun, 17 May 2020 17:56:53 +0000

Hello! I'm back this week to finish up what I started. I've got a visually working piano that I can control with my keyboard. Now it's time to hook up those key toggles to some sound toggles.

I'm going to use Tone.js for my audio. Tone.js is an easy-to-use web audio library. Let's start with a few basics. The first step to playing a sound is to create a new Tone Synth:

const synth = new Tone.Synth().toMaster();

This will create an instance of the Tone Synth, which can be called upon to play notes in the future. toMaster() tells that synth to route its output to the user's default speakers. Playing a note with the synth is very simple:

synth.triggerAttack('C4');

This will tell the synth to start playing the pitch denoted by C4. This article might be helpful for understanding what 'C4' means if you're not music-savvy. triggerAttack can also take arguments for a delay time to wait before triggering the note and a volume, but I won't need either because I want to play the note immediately and I want it at full ear-splitting volume. Now, triggerAttack is only half the story. Once I start the note, it will keep playing until I slowly lose my grip on reality. This where triggerRelease comes in:

synth.triggerRelease()

Once again, a delay argument is possible, but not needed in this case. As you may have noticed, we can actually use one synth to play and release any number of notes (provided they're one at a time). However, I want to be able to play any number of notes at any time, and hold them down for arbitrary lengths of time, so I'm going to create a dedicated synth for each piano key.

Let's go back to the NexusUI Piano for a second. I have my keystrokes toggling each of the piano's keys visually. Each of these visual changes is accompanied by a 'change' event which can be listened for on the Piano instance, like so:

piano.on('change', (k) => {
  // do something
});

The makeup of each change event is this:

// toggled on
{
  note: 72,
  state: true
}

// toggled off
{
  note: 72,
  state: true
}

An important thing to notice here is that the note properties are in MIDI, but Tone.js expects string representations of notes (like 'C4'). In MIDI, 72 is the equivalent to C4. Luckily, there's a nice little package called midi-note which can do this conversion for us. I'm importing midi-note as 'note', and I can use it like this:

note(72) // returns 'C4'

So I know that for each piano change event I want to either start or stop a note. I can tell this based on the event's state. If it's true I want to start the note, and if not I want to stop the already-playing note. So, I can set up my initial structure for the event listener like so:

piano.on('change', (k) => {
  if (k.state) {
   // play a note
  } else {
    // stop a note
  }
});

The next thing to consider is that once a synth for a particular note is started, I don't necessarily know when it's going to stop, but I do want to be able to locate it when it does, so that I can trigger the release. For this reason I'm going to create an object to store my synths:

const activeSynths = {};

When it comes time to trigger a particular note, I'll check to see if I've already created a synth for that note. If I haven't, I'll create one and add it to activeSynths:

piano.on('change', (k) => {
  if (k.state) {
    if (!activeSynth[k.note]) {
      activeSynths[k.note] = new Tone.Synth().toMaster();
    }
  } else {
    // stop a note
  }
});

Now, to play that note, I simply trigger a note (converted from MIDI to scientific pitch notation) on the synth stored at that note address:

piano.on('change', (k) => {
  if (k.state) {
    if (!activeSynth[k.note]) {
      activeSynths[k.note] = new Tone.Synth().toMaster();
    }
    activeSynths[k.note].triggerAttack(note(k.note));
  } else {
    // stop a note
  }
});

Finally, to stop a note, I just locate the same synth and release it:

piano.on('change', (k) => {
  if (k.state) {
    if (!activeSynth[k.note]) {
      activeSynths[k.note] = new Tone.Synth().toMaster();
    }
    activeSynths[k.note].triggerAttack(note(k.note));
  } else {
    activeSynths[k.note].triggerRelease();
  }

And there you have it. A working piano for all your next masterpiece.

Building a Simple Piano with Tone.js and NexusUI (Part 1)

Je We — Sun, 10 May 2020 19:51:12 +0000

Hello! This week I set up a simple computer-keyboard-controlled piano. I used Tone.js for audio and NexusUI's Piano for an interface. I am definitely NOT the first person to do so, but I'm just here to take you on my personal journey.

I'm going to write this blog in two parts. In part one I'll describe creating a piano interface and allowing its visual state to be controlled by the keyboard. In part two I'll describe hooking up the piano's state to actual sound.

My objective was to create a one-octave piano, easily controlled by the computer keyboard, with the ability to change the octave range. NexusUI furnishes a very neat-looking piano interface:

Getting it on your page is as easy as supplying a div id as a point for injection. Here's the function I wrote for creating a new piano with a custom range at a div with id '#piano-keyboard':

const createPiano = (lowNote, highNote) => {
  const newPiano = new Nexus.Piano('#piano-keyboard', {
    size: [300, 125],
    mode: 'toggle',
    lowNote,
    highNote,
  });

  return newPiano;
}

The reason I wrote it as a function instead of creating it right away will become clear later on. To actually create a piano I simply run:

let lowNote = 72;
let highNote = 84;
let piano = createPiano(lowNote, highNote);

NexusUI's Piano keys have note values in MIDI, so the range of 72 to 84 will give me the octave from C4 to C5. Now I have the piano on the page, and if I click on any of they keys they will toggle to an 'on' state, changing from their original color to light blue.

That's great, but I want to be able to toggle the keys with my keyboard. First, I came up with what I thought was an intuitive set of controls:

NexusUI's Piano has a method to toggle its keys based on their index, called toggleIndex:

piano.toggleIndex(0, true); // toggles lowest note on
piano.toggleIndex(0, false); // toggles lowest note off

The next step was to map the key-names to the index of the key I'd want them to correspond to:

const keyMapper = {
  a: 0,
  w: 1,
  s: 2,
  e: 3,
  d: 4,
  f: 5,
  t: 6,
  g: 7,
  y: 8,
  h: 9,
  u: 10,
  j: 11,
  k: 12,
}

Now I needed to add key up and key down event listeners which would use the keyMapper object to toggle the correct key on and off.

document.addEventListener('keydown', (event) => {
  const keyIndex = keyMapper[event.key];
  keyIndex !== undefined && !piano.keys[keyIndex]._state.state ? 
  piano.toggleIndex(keyIndex, true) : null;
});

document.addEventListener('keyup', (event) => {
  const keyIndex = keyMapper[event.key];
  keyIndex !== undefined && piano.keys[keyIndex]._state.state ? 
  piano.toggleIndex(keyIndex, false) : null;
});

The ._state.state looks pretty icky (please let me know if you know a better way to access a particular key's state), but it gets the job done. Essentially, before toggling a key, I want to check if that key is not already in the state to which I'm about to toggle. While toggling an active key to 'on' won't actually be noticeable visibly, it will actually fire a 'change' event on the piano. Holding a key down would fire many of these events per second, which would cause problems down the line integrating the piano's key states with starting and stopping Tone.js synths.

Now, the Nexus UI Piano does not allow changing of its lowNote and highNote properties once the piano has been created, so to allow octave-changing the current piano has to be destroyed, and a new one created in its place with the new desired octave range.

I added specific cases to the key down event listener to generate a new range, destroy the current piano, and use my createPiano function to create a new piano with the new range. The '<' key shifts down an octave, and the '>' key shifts up.

 if (event.key === ',' && lowNote > 24) {
    piano.destroy();
    highNote = lowNote;
    lowNote -= 12;
    piano = createPiano(lowNote, highNote);  
  }

  if (event.key === '.' && highNote < 120) {
    piano.destroy();
    lowNote = highNote;
    highNote += 12;
    piano = createPiano(lowNote, highNote);  
  }

Alright, now my keyboard is in full control of my virtual piano. Next week I'll talk about how to get this silent piano singing.

MySQL Time and Date Queries

Je We — Sun, 03 May 2020 20:40:11 +0000

Recently, I was working with my team to create a query that would fetch upcoming events from our MySQL database, find any phone numbers RSVP'd for those events, and send reminder texts to those phone numbers using Twilio. I was prepared for this to be a painful process, so I was pleasantly surprised when a simple search revealed a plethora of built-in time and date functions for MySQL. This is an area I'm excited to dig deeper into in the future (you can see just how many possibilities there are in the Date Functions section here). For now, I'm going to tell you about my experience using these functions to solve this specific problem.

First, a brief explanation of the relevant portion of our schema. We have two tables: rooms and rsvps. Our upcoming event information is stored in the rooms table, while subscriptions to these events paired with phone numbers are stored in the rsvps table.

Here's a simplified version of our rooms table and a couple example entries:

And here's our rsvps table and examples of subscriptions to our two rooms:

Our objective was to check once a minute (using a cron worker) for any events starting in ~ 10 minutes, and send text messages containing the name of the room to any RSVP'd phone numbers. I like to build a query step by step, making it more specific as I go along, so the first one I came up with was one to query out the two pieces of information I needed (room names and RSVP'd phone numbers):

SELECT rooms.name, rsvps.phone_number FROM rooms, rsvps 
WHERE rooms.id = rsvps.room_id;

And my result:

This is good, we have the room names associated with their RSVP'd phone numbers. However, we're only interested in events happening today (May 3rd, 2020). This is where the curdate function comes in handy. In MySQL, curdate() will return today's date! So, to narrow down our results to today's events we simply run:

SELECT rooms.name, rsvps.phone_number FROM rooms, rsvps 
WHERE rooms.id = rsvps.room_id
AND rooms.date = curdate();

Resulting in:

Getting warmer, but our cron worker is going to send out texts once a minute. It would be pretty annoying to receive reminders once a minute for an entire day. In fact, we only want to send out one text per RSVP, when the event is coming up in about ten minutes. If our worker is running once a minute, then it's safe to say that it will be true of each event exactly once that its start time is between 9 and 10 minutes from the current time.

Here we can use three more of MySQL's date functions: curtime, TIMEDIFF, and TIME_TO_SEC. curtime, similar to curdate, returns the current time in the format 'HH:MM:SS'. TIMEDIFF takes two time arguments and returns the difference between the two(subtracting the second argument from the first). TIMESEC takes a time string (such as the one that will be returned by TIMEDIFF) and converts it into an equivalent number of seconds. We can use these three functions to find out if an event's start time is between 9 minutes (540 seconds) and 10 minutes (600 seconds) away:

SELECT rooms.name, rsvps.phone_number FROM rooms, rsvps 
WHERE rooms.id = rsvps.room_id
AND rooms.date = curdate();
AND TIME_TO_SEC(TIMEDIFF(rooms.start, curtime())) <= 600
AND TIME_TO_SEC(TIMEDIFF(rooms.start, curtime())) > 540;

This query will give us the same result we got above, but only once on May 3rd, 2020 at 2:50PM, allowing us to send a correctly timed reminder text. Given the amount of date functions MySQL offers, I'm sure there are many, possibly better, ways to accomplish what this query does. I'll keep digging. Thanks for reading!

Character Frequency

Je We — Mon, 06 Apr 2020 01:36:59 +0000

Hello everyone! Pictured above is how I looked when I went to the grocery store today. While we're all bored let's go through a toy problem! This one is called Character Frequency, and you might be able to guess from the name that we're going to count characters. What's more fun than counting? At summer camp we had an activity called Rock Counting which was always in high demand.

Specifically, Character Frequency is going to be a function that takes a string and spits out an array of tuples, one for each character, indicating character frequencies, e.g. ['a', 5]. These tuples should be arranged from highest frequency to lowest, and characters of equal frequency should be sorted alphabetically.

Let's dive right in. I chose to do this problem recursively because I love recursion to a fault. So, knowing I wanted to work recursively and that I'd be building an array, I started with this base case:

  if(!string) return [];

If we think ahead, we know that we want our results sorted alphabetically after they're sorted by frequency. We don't know the frequency, but it's easy enough to sort the string alphabetically. We can use a neat little trick, splitting the string into an array so we can sort it alphabetically, and then rejoining it back into a string:

  string = string.split('').sort().join('');

Now, since I'm working recursively, I know I'm only going to care about one character at a time, so how about setting up a counter for that character?

  let frequency = 0;

Alright, let's count this sucker by iterating through the string and incrementing frequency where appropriate. And by "this sucker" I mean the first character of the string AKA string[0]:

  for(let char of string) {
    if(char === string[0]) frequency++;
  }

OK, we've got our full count, so let's store our tuple for use later:

  const tuple = [string[0], frequency];

It's safe to say it would be a waste of to count any character's frequency twice, so let's go ahead and remove all instances of the current character from the string. We can do this using the string replace method, and a RegExp for the character with a global flag (to replace all occurrences).

  string = string.replace(new RegExp(string[0], 'g'), '');

This is the way we'll whittle down the string for our recursive calls rather than the familiar pattern of string.slice(1). Now we just want to return ALL the tuples in one big happy collection, so we return the one we just built with all the rest that we accept on faith we'll get from our recursive call:

  return [tuple].concat(characterFrequency(string))

That's not quite the whole story, though. We want our tuples to be sorted by frequency. We know that the frequency of each character can be found at its tuple's 1st index, so we can use this to sort our return:

  return [tuple].concat(characterFrequency(string))
  .sort((tuple1, tuple2) => tuple1[1] > tuple2[1] ? -1 : 1);

This looks kind of confusing. I always found the array sort method a bit strange. The idea is that the callback takes two elements from the array to compare, and then based on whether the callback returns a negative or positive number, the first element or the second element gets sorted first, respectively. So, what the code above says is: if a character's frequency is greater than the next character's frequency, return -1 (sort it first), otherwise return 1 (sort it after).

Now this is going to work, take my word for it. However, I had an idea while writing this post for a little refactor. You might notice that when we're counting a character's frequency we waste a little time counting through the whole string. Since we've alphabetized the string, we know that as soon as a character doesn't equal the character we're counting, that there are no more occurrences of that character in the string. For example, if we alphabetize 'feed', it becomes 'eedf'. When we're iterating through 'eedf', once we hit 'd' we know we've counted all the e's. So what if we count character frequency using a while loop that runs until the next character ISN'T the current character? Like so:

  let i = 1;
  let frequency = 1;
  while(string[i] === string[0]) {
    frequency++;
    i++;
  }

Now, we can use whatever value i ends up at to determine where to start the slice for the recursive call:

  return [[string[0], frequency]].concat(characterFrequency(string.slice(i)))
  .sort((tuple1, tuple2) => tuple1[1] > tuple2[1] ? -1 : 1);

Alright, that might save us marginal amounts of time! Thanks for reading!

Spiral Traversal

Je We — Mon, 30 Mar 2020 07:26:04 +0000

Take my hand.
What are you afraid of?
Afraid of finding something out about yourself...?
Maybe even about the fabric of reality itself?
Let's see what lies at the center of this spiral.
Yes, of course, I'm talking about the spiral on my shirt.

What am I talking about? I don't know. It probably has something to do with the toy problem I worked on this week called: Spiral Traversal. I had a lot of fun solving this problem and I'd like to walk you through my journey.

First an explanation of the problem: given a matrix, return an array that traces all the values found in a spiral from the matrix's upper left corner into its center.

Here's a matrix:

A spiral traversal looks something like this:

Writing that out, the array we'd want to return is:
[1, 2, 3, 4, 5, 10, 15, 20, 25, 24, 23, 22, 21, 16, 11, 6, 7, 8, 9, 14, 19, 18, 17, 12, 13]
Now that's a mouthful.

Let's take it step by step, following the diagram above. The first thing we want to do is grab the whole first row of the matrix and load it into our spiral. This could easily be accomplished by grabbing matrix[0] and pushing it into our spiral array. However, wouldn't it be nice to no longer have this row on the playing field moving forward? We can kill two birds with one stone by using shift.

  let spiral = matrix.shift();

Because shift returns what it removes, we have now set our spiral equal to that first row. Now, we probably want our function to be pure, so we should make a copy of matrix before we rudely splice off part of it. The most obvious approach would be:

  matrix = [...matrix];

However, if we think ahead a little bit, some parts of the traversal will only be grabbing PARTS of rows, which will mean altering the matrix's sub-arrays. These sub-arrays have their own references, so even if we make a copy of the matrix, any changes made to its rows will actually be side-effects. Knowing this, a more thorough approach is to make a copy of each row instead:

  matrix = matrix.map(row => [...row]);

Now we are safe from accidentally altering both the matrix itself and any of its rows.

Let's get back to it. Our matrix now looks like this:

The next part of the traversal is down the right-most column (10, 15, 20, 25). So, we want to iterate through the matrix, popping off the last element of each row and tacking it onto our spiral.

  matrix.forEach(row => {
    spiral.push(row.pop());
  });

Pop, like shift, returns what it removes, so we can push the elements into our spiral at the same time as we remove them from the matrix rows. Pretty cool!
Our matrix is getting smaller...

Up next we have to do a fancy little trick: add the bottom row...BACKWARDS! Actually, it's not that fancy because JS has a reverse method.

    spiral = spiral.concat(matrix.pop().reverse());

Look at that cute little matrix:

Alright, next we need to traverse up the left-most column. So, we iterate BACKWARDS through the matrix, removing the first element of each row and adding it to our spiral.

  for(let i = matrix.length - 1; i >= 0; i--) {
    spiral.push(matrix[i].shift());
  }

Wow! Our matrix is almost bite-size!

Cool! So...what next? Grab the first row from left to right, correct? Well...this is awkward. Aren't we about to repeat the same sequence of actions we just went through? What if we were dealing with a much larger matrix? How would we know how many times to repeat this sequence. We wouldn't! So let's recurse, like so:

  return spiral.concat(spiralTraversal(matrix));

Easy enough. But what are our stopping conditions? Let's take a moment to visualize. When we call spiralTraversal on this 3 x 3 matrix, we will be performing this sequence:

So, when we get to the end of the sequence we'll be recursing again on the poor lonely 1 x 1 matrix: [ [ 13 ] ]. That 13 is totally the end of our spiral, so our stopping condition can be something like this:

  if(matrix.length === 1) return matrix[0]

This stopping condition is essentially saying: if the matrix only has one row, go ahead and add that row as the end of the spiral. Now, up till now we've only considered square matrices. But let's consider a wide matrix and see if this stopping condition still works.

Starting matrix:

First traversal:

Matrix to recurse on:

We just want to tack this final [ 6 , 7 ] onto our spiral, and our base case will do just that. Looks like we're safe. How about a tall matrix?

Starting matrix:

First traversal:

Matrix to recurse on:

This matrix has only one column. Isn't safe we want the end of our spiral to be the contents of this column: [5, 8] ? We have one base case right now that says to add the whole row if there's only one left. How about we make another base case that says to add the whole column if there's only one left?

  if(matrix.every(row => row.length === 1)) {
    return matrix.reduce((col, row) => col.concat(row));
  }

If every row in the matrix has only one element, that means there's only one column. We use the reduce to transform [ [5], [8] ] into [5, 8] for easy concatenation onto the end of our spiral.

Whew! All done, right? Wrong. We haven't considered one possibility: a square matrix with even-numbered dimensions! Let's visualize the simplest case.

Starting matrix:

First traversal:

Matrix to recurse on:

The first thing you might notice is that we didn't even get to complete our sequence on the first traversal! When it came time to traverse up the left-most column, there was already nothing left in the matrix. If you recall our code for this part of the traversal:

  for(let i = matrix.length - 1; i >= 0; i--) {
    spiral.push(matrix[i].shift());
  }

We won't get an error, because i will initialize at a value of -1 (since the length is 0), meaning the loop never runs. After this, we call spiralTraversal on an empty matrix. Wouldn't you say we're done with our spiral though? I sure hope so. So it looks like we've found our final base case. If the matrix is empty we should just return an empty array to end it all.

  if(matrix.length === 0) return [];

So now, if we put it all together with our base cases preceding our traversal sequence, it should look a something like this:

  const spiralTraversal = (matrix) => {
    //if matrix is empty, return empty array
    if(matrix.length === 0) return [];

    //if matrix only has one row, return that row
    if(matrix.length === 1) return matrix[0];

    //if matrix has just one column, return that column
    if(matrix.every(row => row.length === 1)) {
      return matrix.reduce((col, row) => col.concat(row));
    }

    //make a copy of matrix
    matrix = matrix.map(row => [...row]);

    //start with spiral set to the entire first row of the matrix
    let spiral = matrix.shift();

    //iterate through remaining rows, adding each row's final element to spiral
    matrix.forEach(row => {
      spiral.push(row.pop());
    });

    //add a reversed version of final row to spiral
    spiral = spiral.concat(matrix.pop().reverse());

    //iterate backwards through remaining rows, adding each row's first element 
    //to spiral
    for(let i = matrix.length - 1; i >= 0; i--) {
      spiral.push(matrix[i].shift());
    }

    //return the spiral so far, concatenated with a spiral traversal of the 
    //remaining matrix
    return spiral.concat(spiralTraversal(matrix));
  };

And that's it! Hope you enjoyed reading. See you on the other side...

Deep Equality

Je We — Mon, 23 Mar 2020 01:39:49 +0000

My warmest greetings to all the spiritually awakened coders out there. Are you sick of shallow equality that barely scratches the surface? Looking to take the next step in your journey towards a deep equality that reveals the underlying cosmic truth about JavaScript objects? You've come to the right place.

When it comes to primitive data types (numbers, strings, etc.), JavaScript's strict equality operator (===) is plenty for comparing two values. However, you'll know if you've ever tried to compare two objects, not one of those three equal signs is going to do you any good. The strict equality operator, applied to objects and other complex data, only compares references to determine equality. The actual content of the two objects means diddlysquat.

In this example, the strict equality operator will tell us that yes, these objects are equal, because they both have the same reference i.e. they occupy the same place in memory.

  const meMyselfMe = {
    firstName: 'Je',
    lastName: 'We'
  }

  const myClone = meMyselfMe;

  console.log(meMyselfMe === myClone) // => true

However, if we create two objects separately, with coincidentally identical key-value pairs, when it comes time to compare these two objects, strict equality will betray us.

  const anotherClone = {
    firstName: 'Je',
    lastName: 'We'
  }

  console.log(meMyselfMe === anotherClone) // => false

Now there are definitely scenarios in which this behavior might be useful, so we won't take it personally. However, wouldn't it be nice to be able to compare objects based on their contents? Let's go ahead and write a deep equality function then!

How to get started? Well, we'd expect that two object's whose keys are associated with the same values would be deeply equal. So let's write some code which will return whether every key-value on one object is the same on the other.

  const deepEquals = (obj1, obj2) => {
    return Object.keys(obj1).every(key => obj1[key] === obj2[key]);
  }

OK, this seems like a good start for a very simple scenario. However, imagine that obj2 has equal values for all of obj1's keys, but it has some keys of its own that aren't present on obj1. We definitely wouldn't call these objects deeply equal, but our code as written would still return true. So how about we add some code that will check if our objects have the same amount of keys. Objects with different numbers of keys can never be deeply equal, so this code will let us stop when this is the case and return false right away, without wasting any more time.

  const deepEquals = (obj1, obj2) => {
    if(Object.keys(obj1).length !== Object.keys(obj2).length) return false;
    return Object.keys(obj1).every(key => obj1[key] === obj2[key]);
  }

Looking pretty good. This will work...except in the case of nested objects. We're using strict equality in our callback function, so if our objects have values that are themselves objects, even if those values are deeply equal, we'll still return false. So we're going to need to refactor our code to deal with nesting. We're going to have to be set up to deal with indeterminate nested objects, which should get some bells ringing for recursion. So how about we have a little faith that our deepEquals function will do what we want it to do, and check if every key-value pair is DEEPLY equal rather than strictly equal?

  const deepEquals = (obj1, obj2) => {
    if(Object.keys(obj1).length !== Object.keys(obj2).length) return false;
    return Object.keys(obj1).every(key => deepEquals(obj1[key], obj2[key]));
  }

The only problem here is that we have no stopping condition for our recursion. It's safe to say that, whenever the endless nightmare of nested objects come to a close, we'll be back to comparing primitive data types, for which the strict equality operator is a great tool! So, whenever deepEquals is called on two non-objects, it's safe to go ahead and return their strict equality. These simple comparisons will serve as our stopping condition.

  const deepEquals = (obj1, obj2) => {
    if(typeof obj1 !== 'object' && typeof obj2 !== 'object') return obj1 === obj2
    if(Object.keys(obj1).length !== Object.keys(obj2).length) return false;
    return Object.keys(obj1).every(key => deepEquals(obj1[key], obj2[key]));
  }

And now we have it! We can use this function to determine the deep equality of two objects. It's been fun. See you at the next planetary alignment!

Eventing Library

Je We — Sun, 15 Mar 2020 17:14:13 +0000

Shh! Quiet! This is a library!

Welcome everyone. If you'll keep your voices down, I'll show you how we can give our JavaScript objects the ability to build their own eventing libraries. What would this mean exactly? It would mean the object in question could file specified functions under an event name. If this event were ever triggered, these functions would then be executed.

Hmm. This sounds a lot like an object method. Why would we go to all this extra effort when we could just write an object method and then call that method?

Consider a situation in which, given certain conditions, you might want to add additional lines of code to an object's method. We can do this by reassigning the object's method to a function which calls its old method and then executes any additional lines of code. This is a bit clunky. An object with an eventing library can dynamically add additional code to any of its pre-existing events.

If you've worked with jQuery this idea should be pretty familiar. Any jQuery object can listen for events from the user's keyboard or mouse, and we can define what behaviors that object has (if any) for those events using .on().

Consider sleepySlacker, an employee taking a nap on the job. The sleepySlacker object magically already has the ability to add events (using .on) and execute those events (using .trigger).

sleepySlacker has an event called "wake-up", that, when triggered, will log "huh? what?" This is all fine and dandy, but imagine at some later time the boss walks into the room. It's going to look pretty bad if sleepySlacker just says "huh? what?" They should probably cover for themselves; they were only resting their eyes after all...

Now when someone wakes the sleepySlacker, their previous behavior will execute (logging "huh? what?"), but it will then be followed by the new behavior (logging "i wasn't sleeping i swear!").

You might be thinking this is a pretty trivial example. That's pretty rude, but you're right. It is. The important take-away is that an eventing library is very powerful for dealing with asynchronous situations. We don't know when sleepySlacker's boss is going to walk into the room, but when they do we're able to adjust sleepySlacker's behavior upon being awakened accordingly.

Now that you're convinced, let's go over how to implement a function which will add these magical "on" and "trigger" methods to any object. We'll call this function eventSystemDecorator.

Here we have our general objectives outlined. eventSystemDecorator should take in an object and return that object with "on" and "trigger" methods added. The "on" method should allow us to associate a callback function of our choosing with an event name of our choosing. Multiple callback functions should be able to be associated with the same event. The "trigger" method should be able to locate all the callbacks associated with a given event and execute all of them.

Let's start with "on":

If the event does not already exist, we add that event as a property on obj. We want to be able to possibly store multiple callbacks for this event in the future, so we initiate this event's value as an array with the callback as its only member. If we had chosen to simply assign the event's value to the callback directly (as in obj[event] = callback), any time we wanted to add a new callback to the same event, we'd be overwriting the previous callback. If the event DOES exist, we simply add the current callback to that event's existing collection of callbacks.

Now for "trigger":

First we check to see whether the object has this event. If it doesn't we don't want to do anything. If it does, we iterate through all callback functions associated with this event, calling each passing in the arguments passed to "trigger".

All we have left to do is return the object to which we've added these useful methods. Our object can now add and respond to events! Thanks for reading everybody!