Files can be tagged in a robust and portable way by using a naming convention which embeds tags in the file names. I use these tags to filter long lists of files down to the intersection of some topics.

This is how I organize my notes, links, and even my Emacs configuration. Manually naming all files in this manner would be tedious, but software can expedite the process. In my case, I use the Denote Emacs package, which is where I got the idea.

(use-package dired-narrow
  :ensure t
  :bind ((:map dired-mode-map
               ("C-s" . dired-narrow))))

I use org-mode in Emacs for project management. Most of my to-do items are fairly concrete, but some are high-level goals. Often times these high-level goals have some overlapping sub-tasks, so nesting tasks would be a poor-fit. Thankfully, org-mode supports tagging to-do items, and querying by tags. And I think it's quite nice if those high-level to-do's act as links to all the associated sub-tasks, so I built a command to create those links.

(defun my/org-tags-link (tags-string link-text todo-only)
  "Insert org-mode link text in buffer at point matching tags
defined in TAGS-STRING. Link, when visited, will produce a sparse
tree of org headings matching TAGS-STRING.

When called interactively, prompt the user for tags."
  (interactive
   (let* ((buffer-tags (mapcan #'identity (org-get-buffer-tags)))
          (tags-list-included
           (completing-read-multiple "With tag(s): " buffer-tags nil t nil))
          (tags-list-excluded
           (completing-read-multiple "Excluding tag(s): " buffer-tags nil t nil)))
     (list
      ;; tags-string
      (concat (apply #'concat
                     (mapcar (lambda (tag)
                               (concat "+" tag))
                             tags-list-included))
              (apply #'concat
                     (mapcar (lambda (tag)
                               (concat "-" tag))
                             tags-list-excluded)))
      ;; link-text
      (read-string "Description: ")
      ;; todo only?
      (intern (completing-read "Todo only? " '(t nil))))))
  (insert (format "[[elisp:(org-match-sparse-tree %s \"%s\")][%s]]" todo-only tags-string link-text)))

When I find something cool on the web that I want to save for a rainy day, I don't like to use my browser's bookmark system because a) there's no support for tags and b) I don't want my collection of links to be tied to a particular browser or computer. And most times, when I'm searching the information I have stored, I care little whether a file happens to be on my computer or someone else's. So I figured, why not treat my collected web-links as first-class citizens among the rest of my note files? In practice, this means I have a file for each link I want to save, and I configured my file browser in Emacs to treat files with the weblink tag in a special way—opening the embedded URL in my browser when I would otherwise be visiting the file. When I want to save a new link to my notes, I have a keybinding which writes a file to my notes directory based on the URL in my clipboard.

(use-package denote-dired-weblinks
 :ensure (:host github :repo "Duncan-Britt/denote-dired-weblinks") 
 :hook (dired-mode . denote-dired-weblinks-mode)
 :bind (("s-b" . denote-dired-weblinks-create-bookmark)))

• Synchronization: Editing and saving the Python buffer automatically updates the Jupyter notebook
• Cell execution commands: Run individual cells or the entire notebook
• Navigation tools: Jump between cells with simple commands
• Cell management: Create new cells and toggle between code and markdown types
• Enhanced markdown editing:
  • Edit markdown cells in dedicated markdown buffers (similar to Org mode's special edit mode)
  • Automatic comment insertion when pressing return in markdown cells
• Setup utilities: Commands for starting Jupyter notebooks and creating synchronized file pairs

Jupyter Ascending is available on MELPA.

Create a notebook pair with M-x jupyter-ascending-create-notebook-pair RET example RET Or, equivalently python3 -m jupyter_ascending.scripts.make_pair --base example This creates synced files: example.sync.py and example.sync.ipynb

If you have an existing Jupyter notebook, create a python file from it: M-x jupyter-ascending-convert-notebook RET example.ipynb RET Or, equivalently, jupytext --to py:percent <file_name> and then add the .sync suffix to both files

Start Jupyter and open the notebook: With example.sync.py open, M-x jupyter-ascending-start-notebook Or, equivalently, python3 -m jupyter notebook example.sync.ipynb

Within your Python file, a line starting with # %% deliminates a new cell.

# %% [markdown]
# This is a markdown cell.
# Below is a code cell.

# %%
def g(x):
  return 3*x

When you edit and save the Python source file, you should see the Jupyter notebook running in your browser update straight away.

I recommend you create keybindings for all the following commands:

This package only works with Python notebooks because the Jupyter Ascending command line tool only supports Python notebooks. See here: https://github.com/imbue-ai/jupyter_ascending/issues/25

I think this blog post from 2023 gives a good overview of the other options for editing Jupyter Notebooks from Emacs. It covers emacs-jupyter and ein.

I created this package because many of my Computer Science courses force me to use Jupyter notebooks. Of course, I would rather use Org mode, but that's life. And I've since come to appreciate the ability to have auto-completions while editing notebooks, or just treat the notebook as a normal Python file and execute it without Jupyter. I was aware of the other Emacs packages for working with Jupyter, which have the benefit of not being limited to just Python. But this package suits my personal taste very well, so I'm a happy user.

The same issue of clutter—the fear of removing things and regretting it—applies to not just files but the contents of files, such as headings in an Org file in Emacs. While Emacs Org-mode does have a built in command for archiving headings, the resulting archive contains a flat list of archived headings. In other words, the original document structure is not preserved. So I created an Emacs command to archive Org agenda headings in an archive file that mirrors the structure of the agenda.

• Source

The program is so far organized into a few loops that run asynchronously. This means that we describe distinct sequences of events which run in parrallel, repeatedly and independently of one another, over different and varying time intervals. These loops can communicate with one another by modifying the variables which comprise the state of the program.

So for instance, we have a loop which is concerned with planning the robot's path. It waits for the robot's path to be interrupted by an obstacle and then computes a path towards the goal destination using the robot's belief about its current position and known obstacles. Another loop is concerned with executing this plan. The plan for the robots future motion is part of the shared state of the program, and so the planning loop is able to communicate with the plan execution loop by modifying the plan.

The plan consists of a queue of desired destinations, represented as coordinates on a 2D plane. Going from one destination to another is broken down into two steps: First, turn to face the desired destination. Next, go forward until you've gone far enough. The plan execution loop described previously is concerned with deciding that the robot has arrived at its destination and computing the two steps that need to be taken in order to get to the next destination on the path. It modifies the plan by eliminating the next destination in the queue once it has arrived.

Another loop is concerned with the execution of the two steps necessary to go from one destination to the next: the rotation and the translation. I've called these two loops the major and minor plan execution loops in the above diagram. The major loop communicates to the minor loop by deciding those two steps, which are represented as poses. A pose combines position with orientation, so it is a 2D coordinate and a rotation with respect to the x axis. The minor loop decides that the next pose has been achieved and removes it from the queue, modifying the state of the program. This is how the minor loop communicates with what I've called the PID control loop, which is concerned with the low level control of the motors for motion control, among other things.

The PID loop is always trying to achieve the next goal pose. It uses sensor data, the robots belief about where it is, and the next desired pose to calculate a correction to be applied to the voltages currently being sent to the motor control pins. Every so often, the robot must check its sensors and then reevaluate its belief about where it is. Only then is it in a position to apply a correction to the motor control. It communicates with the other loops by updating the robot's belief about its current position and updating sensor readings.

AsyncLoop loop_obstacle;
AsyncLoop loop_positions;
AsyncLoop loop_poses;
AsyncLoop loop_pid;

void setup() 
{
    //... omitted
    loop_obstacle
        .when(path_interrupted)
        .then(stop) // empty the position queue and enqueue nearby position
        .when((void*)+[]() -> bool { // wait for the robot to stop
            return idx_pose_array == 1 && pose_achieved();
        })
        .then(reroute);

    loop_positions
        .when(position_achieved)
        .then((void*)+[]() -> void { // Enqueue poses, dequeue position.
            if (!(position_queue.empty())) {
                Pose_enqueue_transition(&pose_current, position_queue.front(), pose_array);
                idx_pose_array = 0;
                position_queue.dequeue();
            }
        });

    loop_poses
        .when(pose_achieved)
        .then((void*)+[]() -> void { // dequeue pose
            idx_pose_array = 1; // go to the second pose
        });

    loop_pid
        .when(time_elapsed_ms_50)
        .then(update_perception_localize_and_pid);
}

void loop() 
{
    loop_obstacle();
    loop_positions();
    loop_poses();
    loop_pid();
}

In the following sections I attempt to describe the components of the program in more detail.

We need to figure out how to decide whether an obstacle has been detected and whether it interrupts our path forward, as well as where we believe the obstacle is. We also need to figure out how to persist this knowledge in a way that will consume the least amount of memory.

Equipped with knowledge of where obstacles lie, we can model the landscape surrounding the robot as an occupancy grid.

In the field of mobile robotics, there are a variety of commonly used path planning algorithms. Originally I implemented one of them called A* (A-Star). But I quickly ran into the limits of the Arduino Uno's memory capacity so I've started implementing alternative methods which I expect will consume less memory.

For the sake of testing these algorithms and visualizing the paths they produce, I've written some code that allows us to be able to create an occupancy grid in the Arduino's memory from human readable text, and to be able to print a visual representation of the path it produces. Here's a demonstration in which we ask it to find a path from the top right corner to the bottom left:

#define DEBUG_GRID_STRING "\
  ........\n\
  ........\n\
  ...##...\n\
  ....#...\n\
  ....#...\n\
  ....##..\n\
  ........\n\
  ........"

// testing our implementation of the A* search algorithm on an occupancy grid
void test_a_star() 
{
    Grid grid;
    grid_init_str(DEBUG_GRID_STRING, &grid);        
    grid_print(&grid);
    DEBUG_PRINTLN(F(""));
    uint16_t path[MAX_PATH_SIZE]; // [0, 65535]
    uint8_t path_size = 0; // [0, 255]
    grid_find_path(&grid, 7, 56, path, &path_size, MAX_PATH_SIZE);
    grid_print_path(&grid, path, path_size);
    free(grid.obstacles);
}

The #'s represent obstacles and the .'s represent open space. It produces the following output in which @'s are positions along our path:

. . . . . . . . 
. . . . . . . . 
. . . # # . . . 
. . . . # . . . 
. . . . # . . . 
. . . . # # . . 
. . . . . . . . 
. . . . . . . . 

. . . . . . . @ 
. . . @ @ @ @ . 
. . @ # # . . . 
. . @ . # . . . 
. . @ . # . . . 
. . @ . # # . . 
. @ . . . . . . 
@ . . . . . . . 

Based on the memory available to us, we'll have to decide how large to make the grid and how many \(\mathrm{cm}^2\) can be represented by a single grid space. More fidelity is better, but consumes more memory. Given a limited grid size, we'll also have to choose where to position the grid in the global coordinate system. One note about the grid: I was thinking perhaps we should expand the size of obstacles in the grid to account for the size of the robot and then treat the robot as a point mass.

The grid is implemented as an array of bits. 0's are open spaces and 1's are obstacles:

0 0 0 0 0
0 1 1 0 0
0 0 1 0 0
0 0 0 0 0

The indices of the above grid are laid out as follows:

 0  1  2  3  4
 5  6  7  8  9
10 11 12 13 14
15 16 17 18 19

typedef struct Grid {
    uint8_t* obstacles; // bit array
    uint8_t cols; // [0, 255]
    uint8_t rows; // [0, 255]
} Grid;

The smallest data type available to us is an 8-bit integer, but we only need one bit to represent whether a given grid space is occupied. So, to make the grid take up as little memory as possible, a single unsigned 8-bit integer is used to represent 8 grid spaces, and the whole grid is just a one dimensional array of unsigned 8-bit integers.

One of the things to consider is perhaps having a non uniform cell representation in our grid, for the sake of saving memory and gaining a higher fidelity representation of the surroundings.

The PID algorithm can be used to deal with the low level motor control of our robot. We can adjust the speed and direction of the motors using a function of the magnitude and direction of the discrepancy between where the robot is and where it wants to be at any given time, typically referred to as the error value in the context of PID. In addition to the error value \(e(t)\), PID also uses the accumulation of these error values over time \(\int{e(t)dt}\), and the rate at which the discrepancy is changing \(\frac{de}{dt}\).

\[ u(t) = K_p e(t) + K_i \int e(t) dt + K_d \frac{de}{dt} \] where \(K_p\), \(K_i\), and \(K_d\) are constants that give weight to each of the terms, and must be decided through trial and error. PID stands for proportional, integral, derivative and is named for each of the 3 terms in the equation.

In code, the integral term can simply be a running total of the error values, and the derivative term would be the difference between the current error value and the previous error value from say, 50 ms ago.

//... somewhere in our code, hypothetically:
e_integral += e_current * timestep;
e_derivative = (e_current - e_previous) / timestep;

We still need to implement all of this. These two videos do a good job of explaining PID control:

• Mobile Robot Systems Course - Lecture 3: Motion Control 58:52-1:10:04 https://youtu.be/tocxIukOa-I?t=3532
• PID Control: A brief introduction https://youtu.be/UR0hOmjaHp0

For any of the sensors we end up using, we'll need to write code that we can use to query the sensor for data. Currently we have a third party library for the Sharp IR sensor which makes getting distance data as easy as sensor_IR.distance().

There's a very real possibility that our estimate of our current position relative to the starting point won't be great and will become terrible as time goes on. The thing that is really important though is that we can maintain our sense of direction, and that's why a compass would be valuable. This way, we can make sure we are at least headed in the right general direction.

We didn't end up having time to implement all the feature I had planned for. A week before the challenge in April, we discovered the robot lacked sufficient torque to be able to turn in place. There wasn't enough time left to fix the hardware, but I could make the robot do wide turns by applying more power to either side. The plan became to have the robot do many-point turns.

We also had yet to attach wheel encoders to the robot, so without the ability to localize or turn in place, I set about an entirely different strategy which involved having the robot attempt to go in the direction that was forward when the robot was turned on, and avoiding abstacles by turning away for a short time.

When we got to the sand dunes we realized the courses were much narrower and shorter than we had anticipated. To accomodate this, I rewrote the driving script for our program several times while at the sand dunes, over the course of about 4 hours. Another source of difficulty we discovered at the dunes was that our IR sensors returned noisy distance readings and regularly picked up the ground, leading to false positives in obstacle detection. To deal with this, I attempted to avoid false pasitives by taking 10 consecutive measurements and only considering an obstacle detected if all measurements were within the threshold. It worked reasonably well, but we still didn't have enough space to turn with digging the robot into the sand and getting stuck.

loop_main
.when((void*)time_elapsed_ms_50)
.then((void*)+[]() -> void {
    float xl = (float)sensor_left.distance();
    float xr =  (float)sensor_right.distance();
    int current_left = xl - ((0 - 3) * pow(10.0, 14.0) * pow((xl + 66.0), -7.42)) + 1.7;
    int current_right = xr - 1.718 * sin((xr + 40.8) / (11.7802)) + 1.26; // sensor calibrations
    for (int i = 9; i > 0; i--) {
        prev_left[i] = prev_left[i - 1];
        prev_right[i] = prev_right[i - 1];
    }

    prev_left[0] = current_left;
    prev_right[0] = current_right;

    bool left_detected = true;
    bool right_detected = true;
    for (int i = 0; i < 10; ++i) {
        if (prev_left[i] > 25) {
            left_detected = false;                  
        }

        if (prev_right[i] > 25) {
            right_detected = false;
        }

        if ((!left_detected) || (!right_detected)) {
            break;
        } 
    }

    if (left_detected) { // back up to the left
        motors_set_velocity_left(-10);
        motors_set_velocity_right(-100);
        delay(2000);
    } else if (right_detected) { // back up to the right
        motors_set_velocity_right(-10);
        motors_set_velocity_left(-100);
        delay(2000);
    }
    motors_set_velocity(100);
 });

We were able to clear 3 of 5 obstacle courses, and we won an award for my navigation system despite that it was not in use at the dunes.

I made an HTML templating language that I call Splice. It was a fun and educational exercise. Splice supports nesting, partial templates, iterators, conditionals, variable assignment, local scope, comments, escape characters, and escapes HTML by default. In its minified form, it is only 3.06 KB uncompressed, and has no dependencies.

I've written extensively about how to use Splice, and that writing is available on the documentation website. I will use this space to talk about the implementation of the language, design process/choices, challenges, and open issues.

The AST for Splice begins not with a single root node, but with a collection of its children - the root node is imaginary. There are three types of nodes in the AST:

• text
• binding
• operator

Text nodes and binding nodes are leaf nodes, whereas operator nodes have a body property which is a subtree. (I think of the body as just a special kind of argument that always comes last). For example, the AST for the following splice template:

<p>Hello, (: username :)! Here are your todos:</p>
<ul>
  (:~ each todos as 'todo {
  <li>
    <h2>(: todo.name :)</h2>
    <p>(: todo.description :)</p>
  </li>
  }:)
</ul>

would look something like this:

The lexer and parser work together to turn the former template into the latter AST. The job of a lexer is to split up the text of a program into relevant tokens, and the job of a parser is to create the AST from those tokens. In my program, these roles are intertwined- tokens are parsed as soon as they are identified. My lexing/parsing function takes the template and returns an AST. Within, it runs a loop which invokes a function that identifies a single token, parses it, and returns the remaining template.

// parse :: String -> Array{Object}
function parse(template) {
  const ast = [];
​
  while (template) {
    template = parseToken(template, ast);
  }
​
  return ast;
}

When an operator body token is identified, the parser simply creates an AST from the operator body token by recursively invoking the main lexing/parsing function. The recursive nature of the lexer/parser reflects the recursive nature of the syntax tree- operator bodies are subtrees.

// parseFunction :: String -> Array{String, Object}
function parseFunction(template) {
  //... code omitted for brevity
  [ token, bodyAST ] = parseBody(template);
  //...
  const expr = {
    type: 'op',
    name: op,
    args: args,
    body: bodyAST,
  };
  //...
}
​
// parseBody :: String -> Array{String, Array{Object}}
function parseBody(template) {
  //...
  return [resultToken, parse(body)];
}

Now the hard work is done! All thats left is to turn the tree into text again. A reminder, when someone uses the compiler, they pass an object with the data to be filled into the template. That object can be thought of as the global scope for the Splice program. The job of the generator is to use the scope and the AST to render the final text output.

The generator has knowledge of the three node types. For operator nodes, it must return the result of invoking the associated function, as all valid operators in the language have an internal function associated with them.

Valid bindings refer to some property of the scope object, so all generator has to do is look up that property for a given binding node and return it. And of course, for text nodes, just return text!

// evaluateAll :: Array, Object -> String
function evaluateAll(ast, scope) {
  return ast.reduce((html, expr) => html + evaluate(expr, scope), "");
}
​
// evaluate :: Object, Object -> String
function evaluate(expr, scope) {
  switch (expr.type) {
    case "op":
      return templateFns[expr.name](scope, ...expr.args, expr.body);
    case "binding":
      let value = expr.chain.reduce((data, prop) => data[prop], scope[expr.name]);
      if (typeof value == 'string') {
        return expr.escape ? escapeHTML(value) : value;
      }
​
      return value;
    case 'text':
      return escapeChars(expr.value);
  }
}

My original design for the syntax didn't stick. It looked like this:

<<~ each madlibs >>
  <p>The << $.adjective >> << $.noun >> << $.verb >></p>
<< end >>

I got as far as making a prototype documentation site but decided I didn't love the amount of angle brackets. It wasn't much trouble to change the syntax, but even so, it goes to show that it's worthwhile to make sure you're solving the right problem before you start coding.

For the implementation, I started by hardcoding a prototype AST as well as a test 'scope'- a set of data with which to test the compiler. Then I went on to writing the generator of the language. I think this was wise because it allowed me to easily modify the AST to suit the needs of the generator when I discovered something needed to change, without having to rewrite components of the parser.

After creating the documentation website using Splice and thinking that it was good to go, I ventured to try opening the website in Safari, and lo and behold, the site crashed immediately. I learned the hard way that not all browsers support look-behinds in regular expressions, because I had 49 of them in my Splice compiler.

The need for these look-behinds in my regular expressions was to avoid my escape character: \. This meant that I had to replace much of the logic for tokenization without the benefit of regular expressions. On the bright side, I think the readability of my code has benefited significantly from this change.

To do this, I wrote a helper function to do most of the heavy lifting:

// strTok :: String, String -> String, String
function strTok(text, endChars, chop = false) {
  let i = 0;
  let j = endChars.length;
  while (j <= text.length) {
    if (text.slice(i, j) == endChars && text.slice(i-1, j) != '\\' + endChars) {
      if (chop) {
        return [text.slice(0, i), text.slice(i + endChars.length)];
      } else {
        return [text.slice(0, i), text.slice(i)];
      }
    }
    i++;
    j++;
  }
  return [text, ''];
}

To get a token and the remaining template it can be used like this:

[ token, template ] = strTok(template, '(:');

It would be good to enable pre-compilation of the templates to enable faster performance. My idea is to have an executable that will parse the template(s) within an html file and compile the syntax tree into javascript code, and then write it to a file. The resulting js file would contain a function which contains the syntax tree written as object/array/string literals. That way there is no parsing client-side, only compilation to html.

Some other things to work on:

• improving the error messages for the language
• writing more extensive tests
• enabling a user to register a helper function
• enable syntax highlighting for the atom text editor

This web app generates word ladders and asks the user to solve them within a maximum number of steps. The puzzles are generated by the server in response to a request and stored in session data. At a high level, the word ladder puzzles are generated by

1. making a random word ladder using the 5000 most common English words
2. finding the shortest path between those first and last words in the ladder using only the 5000 most common English words

The length of this shortest path determines the maximum number of steps for the user to solve the puzzle.

The backend for the Web App is written in Ruby and uses Sinatra, ERB, and a PostgreSQL database.

User input steps are considered valid if

1. there is one letter of difference between the step and the previous step
2. and the word can be found among the 200,000 most commonly used English words.

I parsed the data from a csv file of 5,000 most commonly used English words into a graphical representation of the data, which I then serialized to a YAML file so that my ruby code can more efficiently recreate it. Each vertex in the graph represents a word. The neighbors of every vertex in the graph are the vertices whose word is "adjacent" to the word stored by the vertex.

Among my 5k words, it is possible find two words between which there simply is no path. So in order to not waste time solving for the shortest path between two words for which no path exists, my program first creates a ladder randomly.

Then, my program takes the first and last words from the random ladder, ignores the rest, and attempts to find the shortest path between them using a breadth first search of the graph. If it takes too long, (if the queue is getting too long) it will inform the calling method which will try again with an entirely new random word ladder.

class Vertex
  #...
  def traverse(end_point)
    return [self.data, end_point.data] if self.neighbors.include? end_point
    ​
    queue = [[self]]
    while (queue.length != 0)
      if queue.length > 1_000_000
        return :timeout
      end
      path = queue.shift
      node = path[-1]
      return path.map { |n| n.data } if node == end_point
      ​
      node.neighbors.each do |neighbor|
        next if path.include?(neighbor)
        new_path = path.dup
        new_path << neighbor
        queue.push(new_path)
      end
    end
  end
  #...
end

I decided to use 5,000 words after some amount of trial and error. With larger word sets, it takes longer and longer to deserialize the graph. I would like it be able to make use of a broader vocabulary, and I have some ideas for how to make that happen. Although there are probably a variety of ways I could improve the speed of generation of puzzles (multithreading, for instance), I think the best solution is to make it a non-issue by caching previously generated word ladders and reusing them. The reason I haven't done that already basically comes down to the fact that I wanted to get the app up and running, and caching previously generated word ladders introduces some complexity I didn't want to deal with just yet. But that would be the next step.

Caching previously generated puzzles opens up a number of possibilities such as:

• displaying other user's solutions for the same puzzle
• ranking puzzles based on quality/difficulty
• Algorithmically determining which puzzle to show the user
• Massively broadening the vocabulary of the word set

I have some plans to make the puzzles more conceptually interesting by making them out of conceptually related words rather than just random, but that requires a greater vocabulary first.

Another issue is that the leaderboard is too simplistic. It only measures the number of puzzles a user has solved. There's no extra credit for getting a puzzle in fewer steps, solving a puzzler faster, solving a harder puzzle, etc….

If you’re not already familiar with execution context in JavaScript, it is a topic worthy of a separate and lengthy article in and of itself. I recommend this one. A brief review:

The execution context of an invocation is what is referenced by the key word this within a function definition. The implicit execution context of an invocation is the receiver- whether an implicit receiver (as in function invocation) or an explicit receiver (as in method invocation).

As we shall see, this is useful because it allows programmers to reference the calling object and its properties from within the definition of a method which is shared among many objects.

In Javascript, functions are a type of object. As such, they contain properties like any object can. Every function has a prototype property which, by default, references an object. This prototype object contains a constructor property which, by default, references the function.

To demonstrate this with code, try the following in your browser’s console:

function aFunction() {
  // ...
}
​
aFunction.prototype; // {constructor: ƒ}
aFunction.prototype.constructor === aFunction; // true  

In JavaScript, every object has an object prototype referenced by its [[Prototype] property. This property can be accessed by the __proto__ accessor method. (It’s pronounced “dunder proto” due to its leading and trailing double underscores). It’s important to note the distinction between a function’s prototype property and the [[Prototype]] property which belongs to all objects (including functions).

Before going further, I should mention that accessing an object’s [[Prototype]] directly via the __proto__ accessor is deprecated. JavaScript provides the methods Object.getPrototypeOf and Object.setPrototypeOf to access an object’s [[Prototype]]. However, I will continue to use __proto__ for explanatory purposes. If you want to test my code in your browser and you find that __proto__ doesn’t work, you can substitute foo.__proto__ with Object.getPrototypeOf(foo) and it should work.

When creating an object via an object literal, its [[Prototype]] property refers to the same object referenced by Object.prototype, which serves as the base [[Prototype]] for all objects. This base prototype object has its own [[Prototype]] property which stores null.

( {} ).__proto__ === Object.prototype; // true;
Object.prototype.__proto__ === null; // true;  

Functions being objects, they also have their own [[Prototype]] which I have omitted from the above diagram since its not central to the point of this article. However, for those who are curious, here’s something to chew on:

The prototype chain of an object refers to the series of objects referenced by each others' [[Prototype]] properties.

A parent is the [[Prototype]] of its child. When you attempt to access a property of an object, if JavaScript doesn’t find the property within the object, it will search the object’s prototype chain until it either finds the property or reaches the end of the chain, in which case it returns undefined. This is why you can sometimes invoke a method on an object which hasn’t been assigned to a property of that object. All JavaScript objects by default have access to the properties of the object referenced by Object.prototype since it is at the end of their prototype chain.

({}).notAProperty; // undefined
({}).hasOwnProperty('foo'); // false
({}).toString(); // '[object Object]'  ​  

Type Object.prototype into your browser’s console to view the available methods.

When an object uses methods which are not assigned to one of its own properties, but are referenced further along the prototype chain, we can call it behavior delegation since the requested invocation is passed along, or delegated, to an object further along the chain. Sometimes this is referred to as prototypal inheritance.

A constructor function is merely a function whose intended purpose is to instantiate objects. Purely by convention, the name of a constructor function is capitalized to distinguish it from other functions. From the perspective of JavaScript, constructor functions are no different from any other functions and are treated the exact same way (despite that the syntax highlighting in your text editor might lead you to believe otherwise).

When a function invocation is prefixed with the new keyword, the execution context for the invocation is set to a new object, sometimes referred to as an instance, which is returned by the expression. (Note: It is only returned by the expression if an object isn’t explicitly returned within the function definition.) Therefore, within the definition of a constructor function, this can be used to assign instance properties to values. If you forget to use new when invoking your constructor function, you’ll assign values to properties of the global object. Don’t do that.

function Constructor(val) {
  this.foo = val;
}
​
const instance = new Constructor('bar');
instance.__proto__ === Constructor.prototype; // true
​
const instance2 = new Constructor('baz');
instatnce2.__proto__ === Constructor.prototype; // true
​
instance.foo; // 'bar'
instance2.foo; // 'baz'

Notice that the [[Prototype]] of the instances is the same object referenced by Constructor.prototype. We can define functions as properties of the prototype to create shared methods accessible to all instances.

Constructor.prototype.xyz = function() {
  return this;
}
​
instance.xyz();                 //  {foo: 'bar'}
instance2.xyz();                //  {foo: 'baz'}
instance.hasOwnProperty('xyz'); // false;

Supposing we want to create a subtype of object that inherits from Constructor. Our first naive attempt might look something like this:

// bad
function ChildConstructor(val, ownValue) {
  Constructor.call(this, val);
  this.qux = ownValue;
}
​
const childInstance = new ChildConstructor('xyzzy', 5);
​
childInstance.xyz(); // Uncaught TypeError:
// childInstance.xyz is not a function  

The problem with this is that the [[Prototype]] property of ChildConstructor.prototype points to Object.prototype.

childConstructor.prototype.__proto__ === Object.prototype;
// true  

Therefore, no property by the name of xyz can be found on the child instance’s prototype chain. In order to have access to xyz, we need to put Constructor.prototype on the child instance’s prototype chain by setting ChildConstructor.prototype~’s ~[[Prototype]] to be Constructor.prototype. What a mouthful! Our next naive attempt might look something like this:

// less bad
function ChildConstructor(val, ownValue) {
  Constructor.call(this, val);
  this.qux = ownValue;
}
​
ChildConstructor.prototype.__proto__ = Constructor.prototype;
​
const childInstance = new ChildConstructor('xyzzy', 5);
​
childInstance.xyz(); // {foo: 'xyzzy', qux: 5}

This works, however, it is recommended that you avoid altering the [[Prototype]] of an object for performance reasons. This article on MDN offers a better explanation. Alternatively, you can reassign the child constructor’s prototype property to a new object whose [[Prototype]] is already the desired object, using Object.create.

// not bad
function ChildConstructor(val, ownValue) {
  Constructor.call(this, val);
  this.qux = ownValue;
}
​
ChildConstructor.prototype = Object.create(Constructor.prototype);
ChildConstructor.prototype.constructor = ChildConstructor;
​
ChildConstructor.prototype.childFunction = function() {
  return this.foo;
}
​
const childInstance = new ChildConstructor('xyzzy', 5);
​
childInstance.xyz();                                    
// {foo: 'xyzzy', qux: 5}
childInstance.childFunction();                          
// 'xyzzzy';
childInstance.qux;                                      
// 5
childInstance.__proto__ === ChildConstructor.prototype;
// true
childInstance.constructor === ChildConstructor;         
// true

Object.create, when called, creates and returns a new object whose [[Prototype]] is the argument to the invocation of Object.create. But this new object doesn’t have its own constructor property. Notice that we assign ChildConstructor to ChildConstructor.prototype.constructor. Otherwise the expression childInstance.constructor would return Constructor instead of ChildConstructor.

To quickly build a mental model of the OLOO pattern of object creation, compare the above diagram to the following:

The purpose of Object.create is worth reiterating:

Object.create, when called, creates and returns a new object whose [[Prototype]] is the argument to the invocation of Object.create.

We can use an object literal to create a prototype. Then we’ll use Object.create to make objects which link to that object. We can use an initializer method to set the values of instance properties on our newly created object.

const Prototype = {
  addA: function(n) {
    return this.a + n;
  }
  ​
  init: function(n) {
    this.a = a;
    return this;
  }
}
​
const instance = Object.create(Prototype).init(20);
​
instance.a;                       // 20
instance.addA(10);                // 30
instance.__proto__ === Prototype; // true  ​  

The process for making a subtype is fairly straightforward.

const ChildPrototype = Object.create(Prototype);
ChildPrototype.init = function(a, b) {
  Prototype.init(this, a);
  this.b = b;
  return this;
};
​
const childInstance = Object.create(ChildPrototype).init(5, 7);
childInstance;         // {a: 5, b: 7}
childInstance.addA(3); // 8
childInstance.__proto__ === ChildPrototype; // true
childInstance.hasOwnPrototype('addA');      // false  

In a class-based Object Oriented language, we might think of (instance) methods as functions which are defined by a class and are associated with/accessible to instances of the class. This definition is problematic in JavaScript for two reasons.

1. Despite the class syntax introduced in ES6, JavaScript doesn’t have true classes.
2. JavaScript functions are first class.

Let’s focus on the second point. When a function is assigned to a property of an object, we can call it one of the object’s methods. But the same function which is assigned to a property of an object may also be assigned to a variable, or another object’s property.

const foo = function() {
  console.log('Hello, World!');
}

const object = { bar: foo };

foo();        // prints Hello, World!
object.bar(); // prints Hello, World!

Rather than thinking in terms of functions vs methods, in JavaScript, it makes more sense to think in terms of function invocation — via foo(); vs method invocation — à la object.bar(). Method invocation in JavaScript is when a function is called on an object. Another way of saying this is that it is invoked with an explicit receiver — whereas function invocation is when a function is invoked with an implicit receiver. The implicit receiver of a (function) invocation is the global object. In a browser, this is the window object.

Normally, within a function/method definition, this references the receiver of an invocation thereof. Even so, the consequences might seem strange. Consider the following code snippet:

const doubler = {
  multiplier: 2,

  double: function(n) {
    return n * this.multiplier; // n * undefined => NaN
  },

  doubleAll: function(numbers) {
    return numbers.map(this.double);
  },
};

doubler.doubleAll([1, 2, 3]); // returns [NaN, NaN, NaN]

It might be tempting to think the code should return [2, 4, 6]. The trouble is that within the body of map our double function is referenced by a parameter and is invoked with an implicit receiver. To illustrate this, imagine that JavaScript’s Array.prototype.map method is implemented thusly:

Array.prototype.map = function(funcParam) {
  newArray = [];

  this.forEach(item => {
    newArray.push(funcParam(item)); // function invocation
  });               // ^^^ funcParam invoked with an implicit receiver

  return newArray;
};

It is irrelevant that double is a property of the doubler object. It’s not where the function is defined that determines its this binding, but rather, the context in which it is invoked. The term implicit execution context is used to refer to the receiver of an invocation.

• this references the execution context of a function/method invocation.
• The implicit execution context of an invocation is the receiver, whether explicit (as in method invocation) or implicit (as in function invocation).

In the last example, the fact that this within double doesn’t reference doubler when invoked is called context loss. There are a variety of strategies to deal with context loss. 

Conveniently, many of JavaScript’s built array methods allow you to pass in an object which will serve as the execution context for the function which is passed in. Using this strategy in our previous example would look like this: 

const doubler = {
  multiplier: 2,

  double: function(n) {
    return n * this.multiplier;
  },

  doubleAll: function(numbers) {
    return numbers.map(this.double, this); // <- this argument
  },
};

doubler.doubleAll([1, 2, 3]); // returns [2, 4, 6]

Alternatively, we could wrap the double function in an arrow function. This works because, unlike other JavaScript functions, the this binding of an arrow function is determined lexically, on the basis of where it is defined, not how it is invoked.

const doubler = {
    multiplier: 2,

    double: function(n) {
        return n * this.multiplier;
    },

    doubleAll: function(numbers) {
        return numbers.map(n => this.double(n)); // <- arrow function
    },
};

doubler.doubleAll([1, 2, 3]); // returns [2, 4, 6]

Since our arrow function is defined within the body of doubleAll, this within the arrow function references the execution context of the invocation of doubleAll.

Another idiom for dealing with context loss is to assign `this` to a local variable, such as `self`, and replace `this` with `self` within the callback function.

const doubler = {
  multiplier: 2,

  double: function(n) {
    return n * this.multiplier;
  },

  doubleAll: function(numbers) {
    const self = this;
    return numbers.map(function(n) {
      return self.double(n);
    });
  },
};

doubler.doubleAll([1, 2, 3]); // returns [2, 4, 6]

This works because the object referenced by self is not context dependent. self is simply a local variable, forever accessible to nested functions via closure.

We could use the bind method to return a new function whose execution context is permanently and irreversibly hard bound to the first argument of bind.

const doubler = {
  multiplier: 2,

  double: function(n) {
    return n * this.multiplier;
  },

  doubleAll: function(numbers) {
    const self = this;
    return numbers.map(this.double.bind(this));
  },
};

doubler.doubleAll([1, 2, 3]); // returns [2, 4, 6]

This example problem doesn’t lend itself to the final idiom for dealing with context loss that I will show you, so I’ll offer a different example. The call and apply methods can each be used to to invoke a function with its execution context set to the first argument to the invocation thereof. Behold:

function xyzzy() {
  return this.a;
}

foo = { a: 5 };

xyzzy.call(foo); // returns 5