Forem: Samuel Rouse

Chaos Proxy: JavaScript Shenanigans

Samuel Rouse — Sat, 27 Dec 2025 20:34:04 +0000

JavaScript Proxies can do almost anything. To demonstrate, let's set up a simple proxy that will sometimes return incorrect values for a proxied function.

Requirements

Accepts a target function
Accepts odds of the error (as a fraction of 1)
Accepts alternative function to execute instead of the normal response.

The Code

Nothing special here. We're just using the apply trap for functions.

const chaosProxy = (source, odds, alternative) => new Proxy(source, {
  apply(target, context, args) {
    return Math.random() - odds >= 0
      ? alternative.apply(context, args)
      : target.apply(context, args);
  }
});

This basic implementation doesn't have much to it. Simple odds calculation, and you execute one function or the other.

Trying It

const circleArea = (radius) => Math.PI * radius ** 2;
const circleAreaClose = (radius) => 3.14 * radius ** 2;

const roughArea = chaosProxy(circleArea, 0.5, circleAreaClose);

roughArea(2); // 12.566370614359172
roughArea(2); // 12.56
roughArea(2); // 12.56
roughArea(2); // 12.56
roughArea(2); // 12.566370614359172

Variations

I'm not going to build these; I leave them as exercises for the reader. Maybe one of these will speak to you and you'll try solving it.

Supporting multiple alternatives with different weights/probabilities.
Support manipulating async/promise values.
Modify arguments objects to see if mutations cause problems in your app.
Return a consistent sequence of responses rather than random ones.
Introduce random delays in asynchronous responses rather than changes.

Conclusion

Sure, there are other ways to go about this, but awareness of different parts of JavaScript can come in handy one day. Don't forget to spend a little time trying things. It can sharpen your skills, broaden your perspective, and help you solve real problems in the future.

Git Bits: Symbols

Samuel Rouse — Tue, 21 Oct 2025 12:59:39 +0000

Git is...complicated. This series focuses on breaking git down into commit-sized pieces.

Symbols

Some of the confusion around git comes from the different special symbols and references used to navigate through repository history, compare changes between commits, and manipulate branches. These may look cryptic at first, but learning what and how they work can change the way you think about git.

HEAD

Not quite a symbol, but an important foundation. This is the "You are here" sign on the map that is your git graph. HEAD is a reference to the current commit you're working on.

While each branch has a "head" (lowercase) that refers to the latest commit on that branch, the HEAD (uppercase) refers to where you are currently working. While it is most often pointed at a branch, it can point to a tag or a commit as well.

HEAD: The current commit
HEAD^: The parent of the current commit
HEAD@{1}: The previous value of HEAD (where HEAD was before the last command that moved it)

Ancestry References

Needing to traverse the graph happens. Perhaps you need to quickly see if one of your recent changes caused a defect, or you realize you meant to split off a related feature branch three commits ago. These operators allow you to walk the graph.

The Tilde (~) Operator

The tilde operator allows you to reference previous commits – or ancestors – relative to a starting point:

HEAD~1: Refers to the commit one step before HEAD
main~3: References the commit three steps before the tip of the main branch
HEAD~: Shorthand for HEAD~1

# Combine the last 3 commits into one
git reset --soft HEAD~3
git commit -m "Combined commit message"

Branch Prediction

When using the tilde operator, you may run into merge commits. Git follows the first parent in these cases. This is particularly useful when you want to go back in history in a linear fashion.

# Show what was committed one commit ago
git show HEAD~1

# Check out the version from three commits before
git checkout HEAD~3

To help understand, the first parent was the checked out or current branch when the merge happened. Looking back at a merge, you might think of the current branch as the merge destination or receiving branch. When resolving merge conflicts, you may see the terminology "ours" vs. "theirs".

# Checkout "our" branch
git checkout main

# Merge "their" branch into "our" branch
git merge develop

"Our" branch is the first parent in a merge; the checked out branch. "Theirs" is the branch being added.

The Caret (^) Operator

The caret operator also references ancestors but is focused on navigating merge commits:

HEAD^: Refers to the first parent of HEAD (same as HEAD~)
HEAD^2: Refers to the second parent of HEAD (only meaningful for merge commits)
main^^: References the grandparent of the main branch if the last two commits were merges (same effect as main~2)

# Show the first parent of a merge commit
git show HEAD^1

# Show the second parent of a merge commit (the branch that was merged in)
git show HEAD^2

If you are troubleshooting a defect and want to see the state of a feature branch before it was merged into main, you might use ^2 to navigate onto "their" branch without needing to know the branch name or details.

Stacking Symbols

These symbols describe a path through the graph to a particular point. What's more interesting: you aren't limited to one. You can combine a series of traversal operators to get to a specific commit.

# 1. Go back one commit: ~1
# 2. Go back on a merge to the incoming or "their" branch: ^2
# 3. Go back three more commits on that branch: ~3
git checkout HEAD~1^2~3

You won't use this style very often, but I think knowing about it helps understand what's happening. These symbols aren't references to specific things; they are instructions to navigate the history graph. That's why they are called operators: unlike commits which are a state, these represent an action.

If you look at the history like a map, you might read HEAD~1^2~3 like this:

Starting at your current location (HEAD).
Go back one intersection (commit).
Take the other road that merged into this one.
Go straight three more times.

Commit-ish

Not only can you perform these traversal actions from special references like HEAD and branches, you can perform them from any commit or commit-ish reference like a tag.

# Two steps back from a specific commit
git checkout 0269f84~2

# Get "their" branch from a merge commit tagged as v2.1.0
git checkout v2.1.0^2

Range References

Double Dot Notation (..)

The double dot notation helps you see differences between two references:

main..develop: Shows commits that are in develop but not in main
HEAD..origin/main: Shows what commits will be pulled from origin/main

This is one of the most commonly used notations for comparing branches:

# List commits in develop that aren't yet in main
git log main..develop

# See what changes will be pushed to origin
git diff HEAD..origin/main

You can use this style to output a patch file for sharing with others:

git diff HEAD..origin/main > activeWork.patch

Triple Dot Notation (...)

The triple dot notation shows commits that are in either reference but not in both:

main...develop: Shows commits unique to both main and develop
HEAD...FETCH_HEAD: Shows changes between local branch and what was just fetched

This is useful for seeing the complete picture of how two branches diverged:

# See all commits that are in main or develop, but not in both
git log main...develop

# Visualize the divergence between branches
git log --graph --oneline --all main...develop

The @ Syntax

The @ syntax provides a way to reference points in the reflog. Unlike the regular git log, git reflog keeps track of activity on your particular clone of the repo, including branch switches. Navigating through this will be pretty rare, but can be useful for seeing what you've been up to.

main@{yesterday}: Where the tip of main was yesterday
HEAD@{2}: Where HEAD was two moves ago
HEAD@{upstream} or @{u}: The upstream branch of the current branch

# See what the branch looked like yesterday
git show main@{yesterday}

# Compare with what you had yesterday
git diff main@{yesterday}

# Find commit where you accidentally removed code (from reflog)
git log -p HEAD@{2}

Commit Ranges for Operations

These symbols aren't just for viewing history; they're also used for operations:

git rebase -i HEAD~3: Interactively rebase from three commits back
git cherry-pick main..feature: Apply all commits from main to feature onto the current branch
git revert HEAD~5..HEAD~2: Revert a range of commits

When performing operations with ranges, you can use git log --oneline with your range to verify which commits will be affected.

Conclusion

Git's special symbols and revision references let you control how you navigate your repository's history. The syntax might seem arcane at first, but the operators let you navigate, compare, and manipulate your history with precision.

Whether you're analyzing branches, cherry-picking changes, or fixing mistakes in your commits, knowing the symbols puts you in charge of your version control tools.

Author's note: The first draft of this article was produced with the assistance of generative AI.

git commit -am 'Symbols'
git push

Reactive Data With JavaScript Proxies

Samuel Rouse — Tue, 30 Sep 2025 15:58:29 +0000

Stale data is one of the major headaches in modern web development. Especially in React, where hooks require you to manage dependencies manually. Other libraries adopted a variety of techniques to do this automatically.

Libraries that automatically update values when their dependencies change are often referred to as reactive.

JavaScript Proxies provide a lot of interesting capabilities, so today let's take a look at one way we might leverage Proxies to identify and maintain reactive data. We aren't building out an entire framework, but digging into things out ourselves can help us better understand the language and tools we use.

Scope

I want to walk through building a basic data layer with Proxies. I encourage you to take that base and make changes beyond the scope of the article. I use RunJS to write and test the code in this article. It can be a great tool for trying out coding concepts like this, and I recommend it if you want to follow along with each step and try out the code.

Foundation

I'm starting very roughly from a concept I liked from the moment I first saw the Vue library: computed properties. Providing a clear storage distinction between static and computed data, and handling caching and invalidation of these computed values was something that interested me, especially because the consumer doesn't need to know that one is a property and one is a function under the hood.

Proxies are a great tool for this; they can abstract away some of that complexity in the data layer. In fact, Vue 3 uses proxies for reactivity.

I'm not just copying from Vue's design, though. I want to make something of my own to try to understand what is necessary.

Let's dig into some requirements.

Requirements

Create a Proxy object.
When properties are set, separate functions into "computed" and everything else into "static"
Return values when properties are accessed, executing the functions in "computed" through normal property access (no user function calls).
Allow computed functions access to the proxy object so it can consume other values on the object.
Cache function calls so we don't repeat computed work if not necessary.
Track dependencies accessed by computed properties from the proxy.
When properties are updated, use the dependencies information to clear any cached values.

There are more requirements necessary to create a robust, production-ready system, but this is a good starting point.

The Data Underneath

From our requirements, we can gather that we'll need some objects:

static - Static values
computed - Functions for computed properties
cache - Stored results of computed functions
deps - Some way of storing the relationships

I went with deps over dependencies mostly for width considerations in our code. Let's create that starting object.

There are lots of ways we could arrange this data structure, but lets start here.

const source = {
  static: {},
  computed: {},
  cache: {},
  deps: {},
};

Create a Proxy

Proxies accept a target object (or function!) and a handler; an object which defines how the Proxy works. Handlers contain zero or more traps - a term that dates back at least to 1955 which was used to interrupt the usual execution of a program, typically for debugging. These traps will prevent the normal execution of property access to do all the interesting things we want from our Proxy. There are a large number of different traps available to us – the object internal methods - but we're going to focus on get and set.

const data = new Proxy(source, {
  get(target, property, receiver) {
    // Temporarily do the default
    return Reflect.get(target, property);
  },
  set(target, property, value, receiver) {
    // Temporarily do the default
    return Reflect.set(target, property, value);
  },
});

Some notes on these function arguments:

target - The target object specified when we created the proxy. This avoids any need for a closure or external reference to access the original object.
property - The name of the property being accessed on the proxy.
value - For set we need to pass the actual value to be set.
receiver - In some cases we will need to refer back to the object that received the property access request. This – our proxy – is the receiver.

Now we have a proxy object data that will access the target source. It has traps for get and set, but they don't do anything special yet. We've temporarily inserted Reflect calls to provide the original ability of an object getter and setter. At this point the proxy is just a pass-through for normal operations.

// Set a property on the proxy
data.foo = 2;

// The same thing happens on the source
source.foo; // 2

Segmented Set

We specified we want to separate computed functions from static. We could let the user set these directly, but I want to abstract the knowledge of the source object where possible. So let's update the set trap.

const data = new Proxy(source, {
  get(target, property, receiver) {
    // Temporarily do the default
    return Reflect.get(target, property);
  },
  set(target, property, value, receiver) {
    if (typeof value === 'function') {
      target.computed[property] = value;
      return value;
    }
    target.static[property] = value;
    return value;
  },
});

Now it will save values and functions to different places.

// Set a property on the proxy
data.foo = 2;
data.bar = () => 3;

// This goes into values on the source
source.static.foo; // 2

// But we haven't updated our getter
data.foo; // undefined

However, our getter needs work.

Return Values

We have two different places data can live. At first I was tempted to use nullish coalescing to check for static or computed...

get(target, property, receiver) {
  return target.static[property]
    ?? target.computed[property]();
},

But this would cause incorrect behavior for intentional nullish values. We need to use in or, better yet, Object.hasOwn to get values that exist on the correct object, even if they are null, undefined, or falsy.

Return Code

const data = new Proxy(source, {
  get(target, property, receiver) {
    if (Object.hasOwn(target.static, property)) {
      return target.static[property];
    }
    if (Object.hasOwn(target.computed, property)) {
      return target.computed[property]();
    }
    // Default is undefined, just like normal.
  },
  set(target, property, value, receiver) {
    if (typeof value === 'function') {
      target.computed[property] = value;
      return value;
    }
    target.static[property] = value;
    return value;
  },
});

Return Validation

You'll notice we executed the computed entry rather than returning the function. This lets us avoid knowing if a value is computed or not.

data.foo = 2;
data.bar = () => 3;

data.foo; // 2
data.bar; // 3

Computed Data Access

Computed values are not very useful if they can't access the other data to perform work, though, so we need to update our get trap to support that change. There are a couple ways we could do that.

We can pass the data proxy to the computed functions as the first argument. This gives them full access to static and computed values. This is where the receiver argument becomes useful.

Computed Code

const data = new Proxy(source, {
  get(target, property, receiver) {
    if (Object.hasOwn(target.static, property)) {
      return target.static[property];
    }
    if (Object.hasOwn(target.computed, property)) {
      // Log the computation for demonstration
      console.log(`Computing ${property}`);
      return target.computed[property](receiver);
    }
    // Default is undefined, just like normal.
  },
  set(target, property, value, receiver) {
    if (typeof value === 'function') {
      target.computed[property] = value;
      return value;
    }
    target.static[property] = value;
    return value;
  },
});

Computed Validation

Now, we can use static and computed properties as values.

// Some static values;
data.radius = 3;
data.base = 10;
data.height = 5;

// Some computed values.
data.areaCircle = (data) => data.radius ** 2 * Math.PI;
data.areaRect = (data) => data.base * data.height;
data.areaTriangle = (data) => data.areaRect / 2;

data.radius;       // 3

data.areaCircle;   // 28.274333882308138
'Computing areaCircle'

data.areaRect;     // 50
'Computing areaRect'

data.areaTriangle; // 25
'Computing areaTriangle'
'Computing areaRect'

Note that areaTriangle uses areaRect. Because we passed the proxy and not the "source" object, we can consume computed values inside computed values. But this means we're computing areaRect twice.

Cache Functions

While our examples are pretty trivial, computed values might end be expensive operations, so caching the output will prevent us from doing the same work repeatedly. Adding caching is very straightforward. We can check for a cached value first, and if one is not found perform the work and add it to the cache before returning.

Caching Code

const data = new Proxy(source, {
  get(target, property, receiver) {
    if (Object.hasOwn(target.static, property)) {
      return target.static[property];
    }
    if (Object.hasOwn(target.cache, property)) {
      return target.cache[property];
    }
    if (Object.hasOwn(target.computed, property)) {
      // Log the computation for demonstration
      console.log(`Computing ${property}`);

      const output = target.computed[property](receiver);
      target.cache[property] = output;
      return output;
    }
    // Default is undefined, just like normal.
  },
  set(target, property, value, receiver) {
    if (typeof value === 'function') {
      target.computed[property] = value;
      return value;
    }
    target.static[property] = value;
    return value;
  },
});

Cache Validation

Now we'll only process areaRect once. The second time it is accessed, we use the cache.

data.radius;        // 3

data.areaCircle;   // 28.274333882308138
'Computing areaCircle'

data.areaRect;     // 50
'Computing areaRect'

data.areaTriangle; // 25
'Computing areaTriangle'

Track Dependencies

Now we have computed properties and caching, but if we change something our cache can get out of date. A naive cache strategy would be to wipe the whole cache whenever any value is set, but that's not very helpful. What we need is to track our dependencies. And proxies are well-suited to solve this problem.

We've already seen that we can intercept property access with a get trap. So we can see each property that is accessed. We can use a second proxy specific to computed properties to solve this.

Dependency Proxy

const tracker = new Set();
const depsTracker = new Proxy(receiver, {
  get(depTarget, depProp) {
    tracker.add(depProp);
    return depTarget[depProp];
  }
});

This get-only proxy will record each property name accessed using a Set to avoid duplicates. This adds some overhead to using a computed value, but that's why we have caching!

Once we have the tracked dependencies, we can add them to the deps object. Because we're concerned about the dependencies changing, we want the keys inside deps to be the properties we depend on. We can take the tracker and populate deps from it.

tracker.forEach(dependency => {
  target.deps[dependency] ??= new Set();
  target.deps[dependency].add(property);
});

// Something very roughly like this
const deps = {
 radius: ['areaCircle'],
};

Dependency Code

Let's put that all together. I've also eliminated the console.log in the computed logic. Adding log statements can help you understand the order of operations, but you can add your own if you are interested.

const data = new Proxy(source, {
  get(target, property, receiver) {
    if (Object.hasOwn(target.static, property)) {
      return target.static[property];
    }
    if (Object.hasOwn(target.cache, property)) {
      return target.cache[property];
    }
    if (Object.hasOwn(target.computed, property)) {
      const tracker = new Set();
      const depsTracker = new Proxy(receiver, {
        get(depTarget, depProp) {
          tracker.add(depProp);
          return depTarget[depProp];
        }
      });

      const output = target.computed[property](depsTracker);
      target.cache[property] = output;

      tracker.forEach(dependency => {
        target.deps[dependency] ??= new Set();
        target.deps[dependency].add(property);
      });

      return output;
    }
    // Default is undefined, just like normal.
  },
  set(target, property, value, receiver) {
    if (typeof value === 'function') {
      target.computed[property] = value;
      return value;
    }
    target.static[property] = value;
    return value;
  },
});

Validated Dependencies

Now, let's run the same code:

// Some static values;
data.radius = 3;
data.base = 10;
data.height = 5;

// Some computed values.
data.areaCircle = (data) => data.radius ** 2 * Math.PI;
data.areaRect = (data) => data.base * data.height;
data.areaTriangle = (data) => data.areaRect / 2;

data.radius;       // 3
data.areaCircle;   // 28.274333882308138
data.areaRect;     // 50
data.areaTriangle; // 25

And check our deps object:

source.deps;

{
  radius: Set(1) {
    'areaCircle',
  },
  base: Set(1) {
    'areaRect',
  },
  height: Set(1) {
    'areaRect',
  },
  areaRect: Set(1) {
    'areaTriangle',
    }
  }
}

We can see that we tracked each direct dependency. We aren't using that information, yet, just collecting it, so we'll need to look at our set trap for that.

Clear Cache

When we call set we know the property that is changing, so it's a perfect time to check the deps to see if we need to remove anything from the cache.

set(target, property, value, receiver) {
  // Make a function for recursion
  const depClean = (prop) => {
    target.deps[prop]?.forEach(dep => {
      delete target.cache[dep];
      depClean(dep);
    });
  };

  depClean(property);

  if (typeof value === 'function') {
    target.computed[property] = value;
    return value;
  }
  target.static[property] = value;
  return value;
},

We created a small recursive function to ensure any nested dependencies – like areaTriangle – are cleared. We didn't bother with any "exists" checks beforehand. A property should have no dependencies to check if it is being set for the first time.

Invalidation Code

const data = new Proxy(source, {
  get(target, property, receiver) {
    if (Object.hasOwn(target.static, property)) {
      return target.static[property];
    }
    if (Object.hasOwn(target.cache, property)) {
      return target.cache[property];
    }
    if (Object.hasOwn(target.computed, property)) {
      const tracker = new Set();
      const depsTracker = new Proxy(receiver, {
        get(depTarget, depProp) {
          tracker.add(depProp);
          return depTarget[depProp];
        }
      });

      const output = target.computed[property](depsTracker);
      target.cache[property] = output;

      tracker.forEach(dependency => {
        target.deps[dependency] ??= new Set();
        target.deps[dependency].add(property);
      });

      return output;
    }
    // Default is undefined, just like normal.
  },
  set(target, property, value, receiver) {
    // Make a function for recursion
    const depClean = (prop) => {
      target.deps[prop]?.forEach(dep => {
        delete target.cache[dep];
        depClean(dep);
      });
    };

    depClean(property);

    if (typeof value === 'function') {
      target.computed[property] = value;
      return value;
    }
    target.static[property] = value;
    return value;
  },
});

Invalidation…Validation

Let's perform some operations to populate the cache, and then prove that the cache is cleared base on dependencies.

// Access properties to create cache entries
data.radius;       // 3
data.areaCircle;   // 28.274333882308138
data.areaRect;     // 50
data.areaTriangle; // 25

// View the cache
source.cache;

{
  areaCircle: 28.274333882308138,
  areaRect: 50,
  areaTriangle: 25
}

// Change a property with dependencies
data.base = 8;

// View the updated cache
source.cache;

{
  areaCircle: 28.274333882308138
}

We can see that changing base cleared both areaRect and areaTriangle, so our recursive dependency check worked.

Now, if we call those computed properties again, their values should change.

data.areaRect;     // 40
data.areaTriangle; // 20

Result

We've now worked through each of our requirements, and we have a basic reactive data model. We can support static and computed properties. We can access computed properties without knowing there are functions underneath. We cache those computed values, and create a dependency tree that lets us invalidate that cache when properties are updated.

Let's take a look at the completed code.

const source = {
  static: {},
  computed: {},
  cache: {},
  deps: {},
};

const data = new Proxy(source, {
  get(target, property, receiver) {
    // Check for static properties first
    if (Object.hasOwn(target.static, property)) {
      return target.static[property];
    }
    // Check the cache for saved computed properties
    if (Object.hasOwn(target.cache, property)) {
      return target.cache[property];
    }
    if (Object.hasOwn(target.computed, property)) {
      // Build the dependencies and cache the compute value
      const tracker = new Set();
      const depsTracker = new Proxy(receiver, {
        get(depTarget, depProp) {
          tracker.add(depProp);
          return depTarget[depProp];
        }
      });

      const output = target.computed[property](depsTracker);
      target.cache[property] = output;

      tracker.forEach(dependency => {
        target.deps[dependency] ??= new Set();
        target.deps[dependency].add(property);
      });

      return output;
    }
    // Default is undefined, just like normal.
  },
  set(target, property, value, receiver) {
    // Use recursion to clean nested dependencies
    const depClean = (prop) => {
      target.deps[prop]?.forEach(dep => {
        delete target.cache[dep];
        depClean(dep);
      });
    };

    depClean(property);

    if (typeof value === 'function') {
      target.computed[property] = value;
      return value;
    }
    target.static[property] = value;
    return value;
  },
});

Proxy Proof-of-Concept

All this in under 60 lines of code! While it doesn't do everything, proxies provided us the tools to build a system to support automatic dependency detection and caching quickly and relatively easily.

Your Turn?

There are plenty of things to add and improve in this design. Try your hand at adding onto the code and see where it takes you.

Add support for in and Object.keys from the proxy.
Add support for deleting properties.
Clean up dependencies when a property is deleted.
Only calculate the dependencies when the computed property changes.
Support changing properties from static to computed or vice versa.
Avoid dependency checks on initial set?
Should we re-compute values when dependencies change, or wait for them to be accessed?

Conclusion

Proxies provide nearly unlimited flexibility in JavaScript. Starting from a rough idea we built up a reactive data layer with caching and dependency tracking.

I hope you found this article interesting. Are there better ways to create this functionality? Is part of this confusing and needs better explanation? Let me know!

Promise Hashes

Samuel Rouse — Sun, 28 Sep 2025 00:17:52 +0000

Promises provide powerful asynchronous program flow-control, but one of the things they do not currently handle are maps/hashes of promises. Promise.all() accepts an array, but it can be cumbersome to track things by index when multiple async actions are needed, e.g. setting up a form or executing an action that requires permissions.

It would be nice, sometimes, to be able to pass a named object instead of an array.

// An imaginary future where this concept exists
Promise.hash({
  config: getAppConfig(),
  i18n: getFormattingDirectives(),
  l10n: getLocaleStrings(),
  permissions: getPermissions(),
  rules: getFormRules(),
});

While we don't have such a method, creating one turns out to be really straightforward. Let's take a look.

Requirements

Accept a "promise hash" – an object with key-value pairs where the values may be promises.
Extract the values as an array and pass them to Promise.all().
If successful, re-connect the array of results with the original keys and return this new "value hash". Otherwise, pass the rejection.
Return the promise chain containing the "value has" object.

Not All Promises

Note the word may in the first requirement. If you aren't familiar with the inner workings of Promise.all() you might not know that it accepts non-promises and treats them the same as resolved promises. This provides flexibility so a function can be asynchronous or not.

Promise.all([
  // Immediately resolved promise
  Promise.resolve(1),
  // Normal values or function returns are treated as "resolved"
  2,
  // A promise with a little delay
  new Promise(res => setTimeout(res, 100, 3)),
  // This function is returned as a value, not executed
  (a) => a + 2,
]).then(console.log);
// [1, 2, 3, ƒ() ])

This isn't something you have to worry about, but it can really come in handy when testing & mocking, as you don't have to create async functions if they don't initiate promise chains.

Coding

Now, let's build based on our requirements.

Accept a "promise hash"

Not much to accomplish in this step.

const promiseHash = (inputHash) => {};

Extract the values...to Promise.all()

Updated versions of JavaScript make this quite simple:

const promiseHash = (inputHash) => {
  Promise.all(Object.values(inputHash));
};

If successful...return the new "value hash"

const promiseHash = (inputHash) => {
  Promise.all(Object.values(inputHash))
    .then(results => {
      const keys = Object.keys(inputHash);
      const entries = results
        .map((value, index) => [keys[index], value]);
      return Object.fromEntries(entries);
    });
};

You'll notice we didn't do anything about rejection handling. We get that "for free" with Promise.all(). The first promise to reject gets the rejection, so that is passed through automatically.

Return the promise chain


const promiseHash = (inputHash) => Promise 
  .all(Object.values(inputHash))
  .then(results => {
    const keys = Object.keys(inputHash);
    const entries = results
      .map((value, index) => [keys[index], value]);
    return Object.fromEntries(entries);
  });

There's not a lot to it. The object prototype methods really simplify the transformation from and to object for us.

Hardening

I'm going to pause here for a change. While this meets our requirements, there's a time difference between when we extract the keys and values. This is unlikely to cause a problem, but it can if we modify the inputHash object before the promises resolve.

To prevent this, even from intentionally mischievous code, we can use Object.entries() to extract the matching pairs only once to ensure they always line up. We could do this more efficiently but I'd be more concerned about the consuming code if we get to a point where the object hash transform is a performance issue.

const promiseHash = (inputHash) => {
  // Convert the object once for stable ordering.
  const entries = Object.entries(inputHash);
  // Split keys and values
  const keys = entries.map(([key]) => key);
  const values = entries.map(([, value]) => value);

  // Merge the results and keys back together
  return Promise.all(values)
    .then(results => Object.fromEntries(results
      .map((result, index) => [keys[index], result])));
};

We could write the last bit differently, depending on your comfort reading nested function operations:

  // Merge the results and keys back together
  return Promise.all(values).then(results => {
    const valueHash = results.map((result, index) => [
      keys[index],
      result,
    ]);
    return Object.fromEntries(valueHash);
  });

Example

A simple demonstration of the design:

const hash = {
  a: Promise.resolve(1),
  b: new Promise((res) => setTimeout(res, 100, 2)),
}

promiseHash(hash).then(console.log)
// { a: 1, b: 2 }

Use Cases

Every now and then I see a group of similar requests in a Promise.all()...

const entitlements = Promise.all([
  getUserPermissions(),
  getPostPermissions(),
  getModeratorPermissions(),
]).then(([ userPerms, postPerms, modPerms ]) => {
  if (userPerms.canEdit) {
    // ...
  }
});

This pattern is brittle. It depends on the developer keeping two "unrelated" arrays in sync. If we add, remove, or rearrange the entries, we can unintentionally change or break the application.

const entitlements = Promise.all([
  // Adding an entry out-of-order breaks the .then()
  getAdminPermissions(),
  getUserPermissions(),
  getPostPermissions(),
  getModeratorPermissions(),
]).then(([ userPerms, postPerms, modPerms ]) => {
  if (userPerms.canEdit) {
    // ...
  }
});

Hashes prevent this problem.

const entitlements = promiseHash({
  // Adding a key doesn't change the .then()
  admin: getAdminPermissions(),
  user: getUserPermissions(),
  post: getPostPermissions(),
  mod: getModeratorPermissions(),
]).then((perms) => {
  if (perms.user.canEdit) {
    // ...
  }
});

Variations on a Theme

We could also use Promise.allSettled() underneath this design instead of Promise.all().

const promiseSettledHash = (inputHash) => {
  // Convert the object once for stable ordering.
  const entries = Object.entries(inputHash);
  // Split keys and values
  const keys = entries.map(([key]) => key);
  const values = entries.map(([, value]) => value);

  // Merge the results and keys back together
  return Promise.allSettled(values)
    .then(results => Object.fromEntries(results
      .map((result, index) => [keys[index], result])));
};

We could even make this an optional second argument so you can choose which operation handles your hash.

const promiseHash = (inputHash, useSettled = false) => {
  // Convert the object once for stable ordering.
  const entries = Object.entries(inputHash);
  // Split keys and values
  const keys = entries.map(([key]) => key);
  const values = entries.map(([, value]) => value);

  // Merge the results and keys back together
  return (useSettled
    ? Promise.allSettled(values)
    : Promise.all(values)
  ).then(results => Object.fromEntries(results
    .map((result, index) => [keys[index], result])));
};

You'll note that we included the full name in each call. Promise methods must be called on the Promise object, so the alternate code below throws an error.

(useSettled ? Promise.allSettled : Promise.all)(values)
// TypeError: Promise.all called on non-object

Summary

Honestly, there isn't that much to creating a Promise hash, but it can be a useful tool if you find yourself collecting a few promises. There may be other ways to design your application design to avoid the Promise.all() risks, but a simple wrapper to provide hash support can make your code a little easier to follow.

Git Bits: The Graph

Samuel Rouse — Sat, 20 Sep 2025 17:47:27 +0000

Git is...complicated. This series focuses on breaking git down into commit-sized pieces.

The Graph

The foundation of git is a directed acyclic graph. You can dive into the Wikipedia article for more information than you probably want, but the basics as they relate to Git are this:

Each commit in a Git repo is a node on the graph.
Each commit "knows about" (references) the one or more nodes that came before it.
We can trace the history of commits through the graph.
We can't go backward, so there are no loops, but it is possible to have multiple paths between two nodes.

Notes about Graphs

Fig.1 - Example graph of commits on multiple branches

This graph was created with the absolutely amazing Mermaid.js. It represents commits with a number and a hash by default, like 0-2b99de5. The number is the order they appear in the graph definition. The hash is a randomly generated hexadecimal to simulate what actual hashes in git look like.

Nodes

There are mostly two types of "nodes" on the graph in git: commits and merges.

You can see that 2-a0f289f on the develop branch has a line that leads back to 1-10ed042, which in turn has a line that leads back to 0-2b99de5, the start of this graph. You can walk the graph and see the history of each commit in this way.

Merges

Fig.2 - Example graph pointing out a merge commit

Looking at the graph, you can see a node where the changes from the feature branch are merged into develop. That node is connected to two parents: 5-ca2ed61 on develop and 6-fdcd8eb on feature.

It is possible to perform a merge of more than two sources – an "octopus merge" – but it is very uncommon.

Branches

Git's branching system is sometimes referred to as lightweight branching. Compared to some version control systems which make whole copies for new branches, git branches are essentially just a pointer to a commit on the graph, so making a new branch is basically instantaneous. Let's see that in action.

I've created an empty repo and committed a simple README file. If I run git log, it gives me the commit.

commit 1df473a77206a3208ef8c9213dbd298e0ad9b369 (HEAD -> main)
Author: Me <me@example.com>
Date:   Fri Sep 19 12:10:39 2025 -0400

    Initial commit

If I make a new branch with git branch develop and run git log again, I see that this same commit is now represented on main and develop.

commit 1df473a77206a3208ef8c9213dbd298e0ad9b369 (HEAD -> main, develop)
Author: Me <me@example.com>
Date:   Fri Sep 19 12:10:39 2025 -0400

    Initial commit

Even though I've created a branch, I haven't changed the contents of the repo. The branch is metadata – information about the commits.

Divergence

Interestingly, the branch doesn't keep track of every commit on it. The branch only has to know about the latest commit, because that one knows about the commit that came before it, and so on.

Going back to our branch diagram from earlier, the develop branch can build the list of commits in its history, and discover where it has one in common with main – 0-2b99de5, so we can say develop diverged from main at 1-10ed042.

Timeless Representation

One important distinction is that time is not actually a necessary part of the graph. We think of them in time order because it's helpful to us, but the graph is really only concerned with direction.

The HEAD

While there are timestamps on commits, there's really only one time git is interested in: right now. Git represents "wherever you are right now" as a value called HEAD.

If we look at that git log command again, we can see that HEAD is pointing to the main branch, even though we also created a develop branch.

commit 1df473a77206a3208ef8c9213dbd298e0ad9b369 (HEAD -> main, develop)

If we git checkout develop we'll still be on the same commit, but HEAD will be different.

commit 1df473a77206a3208ef8c9213dbd298e0ad9b369 (HEAD -> develop, main)

You can use commands to move back from HEAD, like git checkout HEAD~1 which will check out one commit before the current HEAD.

Re-writing History

The Graph keeps track of the relationship between things, but it is not written in stone. There are several ways you can change the past, but, just as in the movies, there are risks of doing so.

Most of the concerns with re-writing history are around shared branches. Because git is decentralized, there isn't something that says which history is correct if histories diverge. You create a different timeline that didn't happen for everyone. It's a science-fiction nightmare, but for code.

Still, when you are on your personal branch, re-writing history can be really useful.

git commit --amend let's you change the last commit you created. If you misspelled a word or forgot an update, --amend can let you create a history where that didn't happen. For simple changes that exist only for you, this is an easy way to avoid having a commit with an obvious error.

Rebase

Rebasing has a bad reputation. Rebasing is when you change history by "moving the start of your branch". This usually happens during parallel development when two or more people are submitting changes to a branch or repository. When one developer's work is accepted and merged, another developer may need to incorporate that work.

Fig.3 - Branch feature1 is merged in while we are working on feature2

Now that feature1 is merged, we have a couple options. We could create a merge from main to feature2 with git merge main while we are on the feature2 branch.

Fig.4 - Merge main into feature2

If feature2 is a branch that multiple people are working on, that's usually the correct solution. But if it's just one developer, using git rebase main creates a "cleaner" history, because there is no longer a point where history diverged.

Fig.5 - Rebase feature2 onto main

We can say, "feature2 was rebased onto main." History has changed, and there is no record that it was ever attached to the earlier commit.

We'll talk more about rebasing another time. But from the simple diagrams we can see that rebase picks up part of the graph and connects it somewhere else.

Resources

Some information in this article comes from the unassailable git-scm.com site and the Pro Git Book available to read there for free.

The section Branches in a Nutshell provides some really good detail and diagrams on the graph and branching.

Summary

Let's bring it back together. Git is a directed graph of commits, each representing a snapshot of the repo. Branches and tags are metadata that point to specific commits. You can add to, change, or even move parts of the graph.

git commit -am 'The Graph'
git push

Git Bits: Basic Terminology

Samuel Rouse — Fri, 19 Sep 2025 10:00:00 +0000

Git is...complicated. This series focuses on breaking git down into commit-sized pieces.

Working Words

The decentralized nature of Git creates some confusion about the different words you might use, so let's try to clear that up.

Repo

Repository, or repo, is the place data is stored. People sometimes will use "project" interchangeably with a repo. The repo usually contains the project history.

When you work with a project on GitHub, there is a repo on the server. When you clone that repo, there is a repo on your computer as well.

A server isn't necessary, though. If you run git init you create a new repo on your computer. It doesn't exist anywhere else in that moment.

Clone

We usually refer to our copy of a repo as a clone. This helps differentiate between our copy and the server. While there is no actual distinction, we tend to still think in that centralized concept, so most people refer to the server's copy as the repo.

Fork

Forking is the idea that you split from the original repo and have your own copy. Perhaps you want to do something different with the project, or this can be the first step in making a copy so you can contribute in the open-source fork-and-pull model.

This terminology is really about the centralized server-side repositories. Clones are for working with the original server-side repository. Forks are making a copy of that server-side repository.

Remote

A remote is another copy of the repo, usually on a server. When you clone a repo, it will create a default remote of origin pointing back to the source. In many branch-based workflows, you only set up one remote. In a fork-and-pull style, you might set up origin for your personal fork and upstream for the repository you forked from.

Summary

Does this line up with how you use these words? Let me know!

git commit -am 'Basic Terminology'
git push

Git Bits: Working Without a Server

Samuel Rouse — Thu, 18 Sep 2025 17:14:39 +0000

Git is...complicated. This series focuses on breaking git down into commit-sized pieces.

The Server Is Optional

Git is a distributed version control system. Most of the time this isn't very relevant, because we usually work with a single, central repository, but we don't have to. Because we clone the whole repo to our computers, each copy contains everything.

Unlike centralized version control, you don't have to stop collaborating when the server goes down. You can still sync and share and merge work directly with other developers, whether there's an outage or you are working in an environment without Internet access.

Decentralized Differences

This disconnect from "traditional" centralized version control systems dating back to the 1960s can be hard to grasp, as git isn't like most of our models of servers we connect to. We download and view content from a web server, but the server remains the "source of truth". If we make a post or comment on this site, they are stored on the server, not our computer.

You might think of git repos more like operating systems. The device where you are reading this has a full copy of its operating system. It might pull updates from a server, but we each have a whole "working copy" of the OS.

It's more than that, because programs and operating systems are generally artifacts (outputs) of development, and git typically stores the source (inputs).

Going Serverless

Git supports connections using https:// and ssh:// – and its own git:// protocol – but also a local file protocol which allows you to push and pull from the file system. If your repository server is down, you can still share work with others.

# Set up a file system remote
git remote add teammate /Users/alex/work/project

# Load and merge your team's updates
git fetch teammate
git merge teammate/main

Git even supports offline transfer of updates using git-bundle, so you can bundle up changes from a common point that you know another person has in their local clone of the repo, and send them the changes. This was the original use of git. Make changes, bundle them into a patch file, and send them off to a maintainer of the project.

All you need is two laptops and a flash drive to use this flow.

# Bundle the differences between main and my feature
git bundle create updates.bundle main..feature

# Merge in a bundle
git pull path/to/updates.bundle main

Summary

Each Git clone is a complete repository with its own history. Two developers can collaborate using the local file protocol or by exchanging offline bundles. The server is convenient but not required.

git commit -am 'Working Without a Server'
git push

Mac Headaches: External Monitors

Samuel Rouse — Wed, 10 Sep 2025 01:57:01 +0000

Macs have been the "It Just Works" computer for decades, but connecting multiple monitors frequently creates questions or problems. I connected five monitors to a Macintosh IIx back in the 1990s, so what happened?! Back then it was very straightforward: each monitor required a separate video card and cable from the computer. A lot has changed and it can be complicated to connect multiple displays, now. Let's get into it.

Your Mac May Vary
The Simple Solution
USB-C Isn't One Thing
DisplayPort: USB v Thunderbolt
Bandwidth Bummers
Multi-Stream Transport
DisplayLink Docks
Docks vs. Hubs
Other Articles
Conclusion

Your Mac May Vary

Different computers have different external monitor support, but this is true for Macs even more than most. As good as the Apple Silicon processor line is, it brings more variations. Even in the same model and year of computer (e.g. 2025 MacBook Pro), differences exist.

There are a number of Apple Support articles that can help you identify your computer, which then link to the Tech Specs for the different models. If you are considering purchasing a new or used Mac and have specific display requirements, these pages may help.

Identify Your Mac

You can start with the Identify the model of your Apple device article, or go to the specific type directly:

External Monitor Support

Apple has support articles for understanding how many external displays your computer supports. These are a good starting point, but there is a lot of additional nuance between these "base" specs and a specific desk setup, so keep that in min.

Monitor support varies mostly by processor type. The MacBook Pro can have a "base" M-series processor, or a Pro or Max chip. Each of these have different rules by processor type and generation, so an M2 and an M3 may not be the same.

For instance, the Apple Silicon MacBook Air supported only one external monitor until the MacBook Air M3 (March, 2024).

You'll probably notice most of these articles talk specifically about Thunderbolt rather than USB. We'll get to that distinction.

Closed Lid Limits

How you use the computer makes a difference, too. I bought a 2024 M3 MacBook Air, and it's great, but I wanted to use two external monitors. It supports that, but not how I expected. Some Macs, like the one I own, only support multiple external monitors with the lid closed. This is also called "clamshell mode".

As long as it has to run the internal display, my M3 MacBook Air will power only one external display. I have a setup where I use two displays with the laptop to the side for "auxiliary" content like email or Discord, but I couldn't do that with the M3 Air. It's a great computer, but that limitation led me to get a MacBook Pro M4 Max.

If you use your laptop with the lid closed – in a dock, tucked below the monitor, or just off to the side – you may be able to avoid the "Pro tax" while still getting two external displays.

It hopefully goes without saying, but in a closed-lid setup you need an external keyboard and pointing device.

Special Cases

We won't dig into them, but your Mac also supports some special cases, like using an iPad as a second screen with Sidecar or streaming to a television using AirPlay, where you can mirror or extend your desktop, again depending on the device. It's not currently clear to me how these work with the limit on monitors for specific devices, but I wanted to mention these possibilities.

The Simple Solution

Before we go too much further; most Macs support multiple external displays. You can usually accomplish that the same was I did back in the 90s – every monitor connected directly to the computer. This is generally fine on desktops but not ideal with laptops that sometimes leave the desk.

Still, if your Mac has the ports and hardware support, this is the most reliable solution. If you – like most people – are looking for a one-cable (or at least few cable) solution, read on.

USB-C Isn't One Thing

The biggest confusion comes from the USB-C port. The USB name covers both physical connectors, like USB-C, as well as data and power specifications.

If you're interested, Consolidated Cables has an article about USB ports and basic specs.

But wait, there's more! USB-C connectors also support "alternate modes" which let the same connector provide DisplayPort, Thunderbolt 3 or later, and other less-common signals.

Wikipedia's USB-C article is long but thorough if you want details. I recognize most people truly don't care, but it is good to know it's an option.

The three relevant protocols that a Mac's USB-C port can offer are USB, Thunderbolt, & DisplayPort. But there is still a lot of confusing detail.

DisplayPort: USB v Thunderbolt

Because the connector is the same, we have to be aware of the differences in the protocols. Most Macs provide Thunderbolt, but they support the DisplayPort Alt-mode over USB as well. And there are different rules for the two protocols, even if the port is the same.

Apple has an article to help you Identify the ports on your Mac so you know which standards your Mac uses. Be aware that while all Apple Silicon Macs offer Thunderbolt, not on all of the USB-C ports on some models are Thunderbolt, especially the front ports on the Mac mini and Mac Studio...depending on processor.

Just to make things confusing, the USB4 spec contains support for Thunderbolt 3/4, so USB4 devices may support Thunderbolt but they don't have to.

It really is complicated.

Chaining and Splitting

Thunderbolt mostly uses daisy-chaining, or connecting devices in series. Most Macs with Thunderbolt 3 or later have the ability to support two displays on one port, which is ideal for docking stations. There are limitations on this, so please reference the Apple Support articles above for your specific computer. I have not personally confirmed this, but it seems in some cases you can chain a DisplayPort monitor from a Thunderbolt monitor. This was not the case with the Apple Thunderbolt Display (using Thunderbolt 2 over a Mini-DisplayPort connector), and does depend on the Thunderbolt controller of the first display.

On devices which support chaining multiple monitors over Thunderbolt, at least the first monitor must have two Thunderbolt ports. Such monitors are usually from the professional display market and are often much more expensive than their DisplayPort counterparts – a quick search found only one for under $1000 USD – but they do exist.

Most of the time, though, monitors with a USB-C port are offering DisplayPort Alt-mode over USB. Macs support this, but with only one display per port – more accurately one display per chain*. This is where many of the headaches happen when people try to use a dock for one-cable convenience.

* I say one display per chain because you might be able to run two DisplayPort adapters off a USB-C hub or dock. I have not been able to find a reputable source for this, though. Most of the examples of this are using one of the solutions further down this article.

Bandwidth Bummers

When we start getting into specific docks, we can also run into the issue of supported bandwidth. The number of pixels each screen has (resolution), and the number of times per second they update (refresh rate) adds up to certain bandwidth limits. These concerns are more rare with modern docks, but Apple's tendency toward "Retina" high-resolution (generically called HiDPI) can make this a possible concern.

This is why the descriptions in the Display Support section on the Mac Tech Specs have so much detail:

M4 Max
Simultaneously supports full native resolution on the built-in display at 1 billion colors and:
Up to four external displays: Up to three external displays with 6K resolution at 60Hz over Thunderbolt and one external display with up to 4K resolution at 144Hz over HDMI
Up to three external displays: Up to two external displays with 6K resolution at 60Hz over Thunderbolt and one external display with up to 8K resolution at 60Hz or one external display with 4K resolution at 240Hz over HDMI

Your Mac will output the preferred resolution of the monitor, no matter what you select in the Displays screen; even choosing "low resolution" modes. Older macOS versions supported disabling HiDPI (Retina) modes, but those commands do not appear to work on more recent versions macOS.

So while there are some limits within the Mac itself, there may be lower limits on the docks or devices you use.

A Dell Community Forum thread from 2019 does an excellent job of explaining some of these details on the Dell WD19TB, where the internal design of the dock may be a limiting factor. I use 4k displays. Even when I select a scaled resolution, the Mac outputs the high resolution signal. This may have prevented me from testing whether I could get three separate displays working on my WD19TB simply because 4K requires more bandwidth.

Multi-Stream Transport

Some docks – and monitors – support DisplayPort Multi-Stream Transport which allow you to either daisy-chain multiple monitors together or use a dock that splits a single DisplayPort channel to multiple separate displays. This is fairly common in the PC world, and you can even find inexpensive devices that support four monitors on Windows, but it is completely unsupported by macOS.

Apple has never supported DisplayPort MST in the fifteen years it has been available, even when it was usable on Intel-based Macintosh hardware running Windows. As I understand it, Apple Silicon display controllers do not include MST support at all, so MST support cannot be added to current devices.

If you have a dual-monitor dock or a chain of monitors that works on Windows using DisplayPort MST, it will not work on macOS. Depending on the design, it may allow you to use one external monitor or mirror the same output on both displays, but there seem to be cases where multi-monitor docks do not work at all.

MST Documentation Problems

Awareness of MST is especially important if you are looking at docks originally focused on the Windows market. Most of the Windows world assumes MST support is available and it may not even be mentioned in the user guide. This inconsistency is one of the biggest risks as a Mac user looking for docks with multi monitor support.

I use a Dell Thunderbolt WD19TB dock for work. It drives my two external 4k displays – one over Thunderbolt and one over HDMI. The dock is advertised as supporting four displays, as the WD19TB manual indicates. After playing around with different ports and resolutions, I was able to get three external displays working, but only with mirroring the DisplayPort-over-USB-C to the second regular DisplayPort. The third (mirrored) monitor does not appear in the OS at all. This is a pretty common symptom of MST.

Despite no mention of MST or Multi-Stream Transport in the product specs or even the User Guide, a table in the W19TB Administrator's Guide section about firmware update timings mentions MST.

Thunderbolt Docks

There have been a variety of Thunderbolt docks available or years, but a Thunderbolt dock does not mean it is free of complexity. The afore-mentioned Dell WD19TB is one such, where despite Thunderbolt support it uses MST for some of the display connectors and has internal bandwidth limits.

When selecting a dock, check for Macintosh support. Brands like CalDigit and especially OWC are known for working with Macs.

DisplayLink Docks

An option that appeared well before MST and Thunderbolt is DisplayLink. Using software to create virtual displays and stream that information over USB, DisplayLink works around lacking hardware support.

DisplayLink requires a software driver to be installed on the operating system. It is widely supported on Mac, Windows & Linux, but it isn't plug-and-play. If you are on a work-managed device, you may need permissions to install the DisplayLink driver.

Some people have had negative experiences with DisplayLink, but that has not been the case for me. If you have a Mac with limited support for external monitors, it might be a useful alternative.

Not Without Limits

DisplayLink is an acceptable general computing solution. It uses software to simulate display support, meaning it leverages your processor to do the work. For most casual computer use – word processing, code editing, browsing the web – this may be a viable choice.

What it doesn't do well is motion, either gaming or video. The DisplayLink software layer causes increased lag to the display, and uses various compression methods which may limit the image quality.

While some of the DisplayLink systems do support higher frame rates, you should not expect it from these devices in general. DisplayLink also may have issues with DRM – Digital Rights Management – which is required to play most video at 1080p or higher quality. This means you may get a black box trying to view most video content on a DisplayLink monitor. Some users have found that disabling hardware acceleration in their browser resolves the issue. If you are able to stream content on DisplayLink, the image quality may be degraded by the limits of software processing and the USB bandwidth.

A 2020 post to the DisplayLink forums includes a response from a member of the support team clarifying that color profiles and some software display controls are not supported through DisplayLink. If color accuracy is important, this is probably not the solution you are looking for.

Identification

It may be difficult to distinguish an MST dock from a DisplayLink dock when comparing or shopping, but the specs usually mention DisplayLink. Multi-monitor docks that provide no information on their product pages are likely using MST.

As an example, the Targus DOCK430USZ makes no mention of either MST or DisplayLink on the product page. After locating the PDF Manual there's a small blurb that clarified it uses MST (complete with spelling error):

Graphic adapter supporting Multi-Stream
Transport (MST) Mode is reuqired for dual or tri monitor
display mode

Other Software-Required Alternatives

There are even more alternatives to the alternative. The less-known multi-monitor solution called InstantView by SiliconMotion, and another from j5create.

InstantView doesn't require installing a DisplayLink driver, you do have to run the InstantView software and grant it permissions. There are a handful of USB hubs from Hyper and Anker that supports a second monitor through "no install InstantView" software. It's still loading the second display driver in software, and using some OS tricks to do it. Experiences vary with performance, resolution issues, color inconsistency, and lag. A Reddit post to r/Mac comparing them in 2024 was not very complimentary, though.

j5create seems to use their own separate hardware and driver combination. Information was more limited on these products.

Docks vs. Hubs

We've identified a number of considerations for docks, but we need to talk about hubs. Unlike docks, which provide a variety of ports, hubs are almost exclusively focused on providing more of a specific type of port. This is the case with simple USB Hubs – one USB in, two or more USB ports out.

Some USB-only hubs support USB-C DisplayPort Alt-mode, allowing you access to regular USB ports without preventing you from using the USB-C capabilities. Hubs like these might be good for on-the-go use, but they are still limited to one DisplayPort output per port to the best of my ability to find information.

Thunderbolt Hubs

Thunderbolt standardized on the USB-C connector, and USB4 is essentially Thunderbolt 3. Thunderbolt 4 and 5 are mostly incremental bandwidth improvements. While actual Thunderbolt docks have been around for some time – I used a Thunderbolt 2 dock with my 2013 MacBook Air – many of these used Thunderbolt but did not provide multiple Thunderbolt ports for more devices. There are now true Thunderbolt Hubs which allow you to add more Thunderbolt devices without daisy-chaining. This opens up possibilities both for devices and displays.

A single Thunderbolt port on most Macs these days does support two displays – only one if it is an 8K monitor or using high refresh rates – and Thunderbolt Hubs provide support for this.

I haven't used one of these devices, but something like OWC's Thunderbolt 5 Hub is definitely on my radar for my next desk update. I have seen a video demonstrating three displays on the Thunderbolt 5 Hub. Still, I have not tried it, personally. OWC does also provide their own Apple Silicon External Display support article to attempt to clarify display support.

Conclusion

There are honestly too many things to keep in mind when trying to determine exactly how to connect a specific Mac to more than one external display. Much depends on your setup and use cases.

How many displays do you want to connect?
What resolution are those displays?
Will you use the computer with the lid closed?
How many cables are you willing to put up with?
Are the trade-offs of software-based solutions acceptable?

There aren't any universal answers to these problems, other than saying, "Do your homework." I hope I've provided some sources and starting points to help you on your multi-monitor journey.

If you have some wisdom or experience to share, or if you spot a mistake, please comment and share! Thanks!

useCallback is a Lie!

Samuel Rouse — Thu, 14 Aug 2025 19:40:10 +0000

Well, not exactly, but it may not work quite how you expect. It didn't work how I expected.

Functions Not Required

The useCallback docs provide a couple of interesting clues (emphasis mine). It's a big block of text, but it's all relevant.

fn: The function value that you want to cache. It can take any arguments and return any values. React will return (not call!) your function back to you during the initial render. On next renders, React will give you the same function again if the dependencies have not changed since the last render. Otherwise, it will give you the function that you have passed during the current render, and store it in case it can be reused later. React will not call your function. The function is returned to you so you can decide when and whether to call it.

Let's break that down:

useCallback receives a (function) value and a dependency array.
It caches and returns that (function) value.
Whenever the calling function is re-run it returns the original (function) value unless the dependencies array changes.
Whenever the dependencies change, it will store and return that new (function) value.

Hooks, Closures, and Stale Values

This is really important for functions in React. Functions have access to the scope in which they were created (closures!), including the values of props and other hooks. Most hooks return immutable values, so if the props or other hooks change, the closure in which the callback was created becomes stale. It will still have old values if we call the function. We need to let go of the copy with a stale closure and get a fresh one.

Call Me, Maybe?

The docs say twice that useCallback doesn't call our function. It just holds onto it for us so we can call it later if we ever need to. And the dependencies are there in case our ~~phone number changes~~ scope changes and we need a fresh version with fresh scope.

But since React never calls the function, it doesn't matter if it's a function! React is just storing a value. We've just agreed by naming convention that value will be a function. But it doesn't have to be.

First Class Functions FTW

JavaScript lets us store functions as values and pass them as arguments. That's exactly what this higher-order useCallback function expects us to do. But we can pass a number, an object, a Promise, or anything.

// No dependencies, so it never changes
const something = useCallback([1, '2', 'c', new Date('4')], []);
const another = useRef(something);

something === another.current; // true

Cough SIGNALS Cough

Incidentally, signals return a function rather than a value, where the function is a consistent return and the signal manages the scope internally rather than the component. This is why signals ~~rule~~ don't require manual dependency tracking and do not experience stale values.

Just sayin'.

Simpler `useEffect`?

If you are hanging onto a simple object or computation, it might look like this:

// useEffect & useState Edition
const MyComponent = ({ input, color, shape }) => {
  const [state, setState] = useState();
  useEffect(() => {
    setState({ input, shape });
  }, [input, shape]);

  return (<Nested ...state />);
};

Or, probably better if you use useMemo for this.

// useMemo Edition
const MyComponent = ({ input, color, shape }) => {
  const state = useMemo(
    () => ({input, shape }),
    [input, shape],
  );

  return (<Nested ...state />);
};

But you could just pass that directly to useCallback.

// useCallback Edition
const MyComponent = ({ input, color, shape }) => {
  const state = useCallback({ input, shape }, [input, shape]);

  return (<Nested ...state />);
};

`const useMemoValue = useCallback;`

What we really have here is a function that accepts a value and will hold onto it until there is a change in the dependencies array. No types. No function executions. Nothing. Just holding onto some value.

You could even use this as a slightly sketchy useRef alternative, where you can keep and mutate an object until a dependency forces you to update it. If you have a useRef that gets updated in a useEffect, you might be able to merge those two operations with a misused useCallback.

But you probably shouldn't.

You Still Want `useMemo`

Except in rare cases like the example above where the operation is trivial, the difference between misusing useCallback and correctly using useMemo is that useMemo doesn't do any of the work in the function you pass it until the props change. Whatever is passed to useCallback, it will do that work every time it renders the component. With useMemo the work is creating a function, not executing the contents of that function.

Simple things like restructuring a single object in our example work well with useCallback, but processing an array is a bad choice.


// Only executes the `.map()` when the dependencies change
const good = useMemo(
  () => bigData.map(entry => complexTransform(entry, someState),
  [ bigData, someState ],
);

// Runs the `.map()` every time the component is rendered
const questionable = useCallback(
  bigData.map(entry => complexTransform(entry, someState),
  [ bigData, someState ],
);

To be honest, trying to use useCallback this way is probably a bad choice in general.

Convention is Communication

As the code author, you might understand that useCallback doesn't have to store a callback function and has this "off label" use. However, other developers may not. Even future you would likely pause at that code and wonder if you meant to use a different hook. You would probably end up adding a comment to clarify the usage, and justify your decision to other developers or to your future self.

All of that means that anyone reading that code will have to stop whatever analysis they are doing to read the comment and understand why this obviously wrong code is not actually wrong and isn't part of the problem they're looking for...unless of course it is, because in doing something non-standard we created some other unexpected defect.

So you really do want useMemo. It does what we expect. It does what the next developer expects. It doesn't require extra mental overhead to understand or explain itself.

Consistency provides a lot of benefit. When we decide to write "interesting" or clever code, it comes at the cost of maintainability and future efficiency. Sometimes it's worth it, but often it isn't.

Summary

So, useCallback is a lie. It's not about the callback; it's about the closure. It's good to know this is the case, because it will help you understand why omitting dependencies can cause problems, but it's also good to know not to use it in this way unless you have a really good reason to do so.

Use Slice, not Substring

Samuel Rouse — Thu, 17 Jul 2025 03:51:32 +0000

JavaScript String.prototype.substring() and it's confusingly similar yet deprecated cousin .substr() have been around a long time, but so has the better solution: .slice().

Slice is most compatible with modern JavaScript. It accepts one or two indices, supports negative indices, and operates predictably.

Of Indexes and Indices

Indexes and indices are interchangeable plurals for index. Databases usually use indexes to refer to optimized lookup tables. Array operations usually refers to indices. Math often uses indices and while much of programming follows from math, there is a mix. The MDN article on substring uses both, for instance.

Substr: Right Out

Substr is deprecated. It was never part of the core spec, and unlike most other string operations it takes index and length. I've added it to the example comparison because it lives in many older codebases, but it's not recommended.

Honestly, substr is "closer to the metal", meaning it's more closely aligned with the computer hardware than the conceptual logic being executed. The strncopy method in C accepts a size similar to the length parameter. This is essentially replicating how memory is copied at the hardware level; a starting point and a number of bytes.

When we work in applications, we are often less concerned with how the underlying hardware will handle a task. We might need to find the start and end, and have to perform math to know how many characters to copy. So we let the computer do that math for us, and just provide the indices.

Substring: Just Trying to Help

Substring has two "helpful" quirks to be aware of: clamped values and index swapping. These aren't bad, but can have unexpected results if you aren't aware of them.

Parameter Swapping

Let's say you have a little program that calculates the start and end of a substring you need to extract, and you get back two indices: start and end. Sadly, there's a simple error in your logic, and the end is smaller than the start value! As explained in the substr section above, the low-level logic is converting the pair of indices to a size for string copies. Subtracting the indices would give us a negative number, which doesn't work as a length.

So substring assumes you made a mistake, and swaps the order for you! No matter how you pass your arguments, it will figure out which is lower, and put it first.

'abcde'.substring(4, 2); // 'cd'

In most places this would either error, or return an empty string. The latter is what .slice() does.

'abcde'.slice(4, 2); // ''

Substrings parameter swapping might seem like a helpful choice, but it has the possibility to hurt more than help. If our logic is wrong, it can return values that could confuse or delay identifying the defect.

Clamped Values

Substring doesn't support negative numbers. Many of the more recent JavaScript additions that accept indices allow you to provide negative numbers as a representation of "from the end", where positive numbers are "from the beginning".

'abcde'.at(1);  // 'a'
'abcde'.at(-1); // 'e'

Substring assumes you must have been mistaken, and clamps values to zero if they are negative. You can't start before zero, right? That's why indexOf returns -1 if something is not found. So substring won't go below zero.

Now, all of the methods will convert non-numeric values to zero, but substring not supporting negatives means it works differently.

// Bad values
'abcde'.substring({}, 3); // 'abc'
'abcde'.substr('cat', 3); // 'abc'
'abcde'.slice([], 3);     // 'abc'

// Negative values
'abcde'.substring(-2); // 'abcde'
'abcde'.substr(-2);    // 'de'
'abcde'.slice(-2);     // 'de'

It gets especially complicated if you thought you could use negative indices to get several characters near the end of a string.

'abcde'.slice(-3, -1);     // 'cd'
'abcde'.substring(-3, -1); // ''

And mixing positive and negative numbers is even worse.

'!Hola¡'.slice(1, -1);     // 'Hola'
'!Hola¡'.substring(1, -1); // '!'

Substring clamps this as (1, 0), and then swaps the order for you.

Examples

Here's a small chart of different inputs and what the functions produce. This is all run against a string that contains the alphabet.

Args	`substring`	`substr`	`slice`
`fn(20)`	'uvwxyz'	'uvwxyz'	'uvwxyz'
`fn(-5)`	'abcdefghijklmnopqrstuvwxyz'	'vwxyz'	'vwxyz'
`fn(5, 10)`	'fghij'	'fghijklmno'	'fghij'
`fn(5, -5)`	'abcde'	''	'fghijklmnopqrstu'
`fn(-10, -5)`	''	''	'qrstu'
`fn(-5, -10)`	''	''	''
`fn(10, 5)`	'fghij'	'klmno'	''

The last two entries return an empty string for .slice(), but they are the "incorrect" arguments where the index of the second argument is lower than the first.

Summary

substring has some unusual conditions that could be helpful but are incompatible with more modern use of negative indices. substr is deprecated. slice is where you want to be.

What do you think?

Brevity At Work

Samuel Rouse — Tue, 08 Jul 2025 22:25:22 +0000

It seems that perfection is attained not when there is nothing more to add, but when there is nothing more to remove.
— Antoine de Saint-Exupéry, translated from Terre des hommes

Core Principles

Get to the Point

We talk too much. We send long emails. We restate and repeat and ramble. It's hard to learn to stop talking, but we can do things differently. We just need tools.

Get Confirmation

Over-explaining prevents misunderstandings, but wastes time. Confirmation to the rescue!

Ask before giving a long explanation.
Pause frequently to confirm if others understand.
Check if you need to continue.
Don't assume.

Know Your Audience

Being very concise may seem rude to some. Expectations can vary by interaction and culture. We avoid interrupting customers or managers because of policy or power dynamics.

What does your audience need to know? What is their motivation? Do you need their awareness, interest, or action?

Think like a storyteller.

Remove everything that has no relevance to the story. If you say in the first chapter that there is a rifle hanging on the wall, in the second or third chapter it absolutely must go off. If it’s not going to be fired, it shouldn’t be hanging there.
— Anton Chekhov

Consider the goals of the communication.
Give the short summary and offer to provide more information.

Finding Balance

Taking it Too Far

Too little information is also bad. Newer team members may not know things. New projects may need explanation. Not everyone can do research before a meeting. Some detail is necessary.

Don't expect others to know everything you do.
Don't omit detail without asking for confirmation of understanding.
Don't be rude if someone does not understand.

If it is not working, try more detail. Call out the change so others are aware.

Cutting People Off

Sometimes you must stop someone from carrying on. This is difficult and can cause hurt feelings.

Avoid rejecting the information presented.
Provide a reason for the interruption.

"Sorry to cut you off, but there's a hand raised we need to address."

"I'd like to bring us back to the high-level discussion for now."

"This is good information, but let's stay focused on this."

"Let's add this to the parking lot."

Be humble. Sometimes others may need to interrupt you, too.

Tools and Channels

Different interactions require different techniques.

When defining the problem, get frequent confirmation.
For follow-up meetings, don't restate the whole problem.
For status calls, summarize, don't narrate.

Concise Communication

Bullet-point lists can be referenced more reliably than paragraphs.
Add an executive summary to save time if readers don't need detail.
Call out participants of relevant sections in meetings and messages.

Writing

Writing tools like the Hemingway Editor or Grammarly can help make your writing concise. AI tools like ChatGPT, Claude, and various iterations of the AI assistants available in note/documentation apps like Notion can do the same.

Digital Communication

Email is all about prioritization. Titles set the tone. They should be clear and distinct.

Avoid long titles. They may be cut off on some screens.
Avoid questions or links in titles. Those are details.

No: "Questions about Next Year's Upcoming Project TICKET-1234"
Yes: "TICKET-1234 - Questions"

For one-on-one or small group chats, try the no hello method.

Meetings

Many meetings styles identify different efficiency tools.

Set an agenda.
Set expectations for communication, or ask if none are provided.
Use a "parking lot" of questions & topics to avoid getting distracted from the agenda.
Use raised hands to interrupt long responses.

Long meetings are difficult. You cannot keep everyone's full attention indefinitely. Act accordingly.

Call out a respondent's name before asking a question.
Ask for everyone's attention when you need it.
Use raised hands to confirm people are attentive if needed.
Let people know when "all focus" time ends.

A Culture of Learning

We all have different things to learn. If people can say, "I don't know," they can ask for clarity when they need it. Management must consistently support this, or employees will stop asking. If they stop asking, we have to explain just in case, and we are back to wasting time.

Reinforce a learning culture.
Express appreciation when someone says, "I don't know."
Never embarrass or belittle someone for not knowing.

This is not a free pass for team members to be lazy, but understanding that we all know different things is important, and sharing knowledge is critical to everyone's success.

Summary

Be brief.
Get Confirmation.
Know your audience.
Don't overdo it.
Encourage "I don't know."
Foster learning.
Respect people's time and attention.

Say what you need to say.
— John Mayer

More to Say?

What do you think?

Bad Interview, Good Practice

Samuel Rouse — Fri, 20 Jun 2025 17:53:30 +0000

LeetCode, Codewars, and similar sites that "test your skill" as a developer aren't good interview tools, but they can be good personal skill builders.

Relevance vs Regurgitation

Rather than highlighting developers who can follow direction and solve problems, using sites like these as skill-validation tools can strongly favor developers who memorized the answer rather than developers who can demonstrate skill in reading requirements, following instructions, and solving problems.

Don't get me wrong; knowing the answer is an important part of development. Not reinventing the wheel saves us time, complexity, and risk. But there are different aspects of the role of developer, and knowing about a linked list is different than demonstrating the ability to recreate one while racing a clock.

Skill Builder

As a personal development tool, sites that offer challenges are great. Not only can you try something outside your usual experience, but you can often see hundreds of solutions and consider the benefits and problems with each. This can help you understand the problem space better, learn about style or language features you aren't familiar with, and reason about code that is very different than what you would typically produce.

Try New Things

While trying different types of tasks can be helpful, these sites are also a great way to try new coding styles.

Have you been meaning to practice more with JavaScript Array prototype methods instead of imperative for loops? What about seeing how compact you can make a given function?

Clever Coding

Coding challenge sites are a great place to try clever coding techniques, where you can accomplish something in a unique way. Maybe you can use an unexpected type conversion or bitwise XOR ^ to shave characters off your solution.

Clever coding is usually discouraged in business because it often trades readability and maintainability for efficiency or character count. Expecting every future developer to understand the particular tricks used and the full problem space adds unnecessary risk.

But in a coding challenge site, it's a great time to try out unusual, risky, or just different code. This can also help you develop the ability to read compiled or obfuscated code. It may be particularly helpful when looking at optimized library methods, which may choose to sacrifice readability for performance.

Conclusion

These are useful pursuits: building familiarity, trying new language features, and practicing your skills in a low-risk environment.

Interviewing is a difficult process, and it's easy to focus on the wrong details. Coding sites can be a good tool for a developer and provide a shortcut when interviewing, but in over a decade of being an interviewer for enterprise developer roles, I've never relied on them because they often don't differentiate between practice and process.

Ask the Audience: Skill Builder Sites?

There are a number of different skill testing sites like these. I'm going to mention Regex Golf. Regex is difficult for a lot of people and learning how to solve problems in it can be very useful.

What are your favorites?