jameskerr.blog

I Will Not Become My Heros

Sun, 22 Feb 2026 21:24:25 -0800

A version of how I thought my life would look died today. Now my life will look different.

I am afraid.

There are thousands of other stories my life might tell, but I don’t know any of them. I haven’t imagined them once. This unknown future is terrifying for my ego and its need for control.

I want to be important. I want to win life. I attach my worth to the outcome of riches, status, fame, intelligence, and independence. I know that life is for living, not winning. But why is it so hard to let it go?

I do not know.

I will not become my heros. I can’t.

I will become my own self which has never been done before.

I cannot control the outcomes of my efforts. I cannot win the games others have set up for me play. So many of us will not be famous. So many will not be rich. The games we play can only allow 1 winner and the rest of us.

I can control what I do. I can control what I choose to do.

I will be honest. I will be kind. I will make good things. I will forgive. I will have self-control. I will be for life. I will see the richness of life in the plants, rocks, animals and people around me. I will seek friendship. I will listen to children. I will be patient with immaturity. I look for the specialness in you, because if you are special, maybe so am I.

God help me.

I do not know my future, yet when I think of unknown possibilities, there is an excitement as well.

I Lost My Airpods

Mon, 09 Feb 2026 10:01:50 -0800

Quiet the noise. Uncomfortable, yet alluring. You get used to it. We get used to anything. So choose carefully what to get used to. Less. Giving up. Missing out. It’s not amazing. It’s not revolutionary. It’s quiet. It’s simple. It’s better. There is more space to cry. Rest is a shorter distance away. Lingering on a word or a moment gets easier, naturally. I miss the sounds. I crave them. But it’s hard to deny the ease of time passing by. There’s a lot more inside than I was aware of. Even when years pass and ability fades, The treausre that hides within the mountain of my simple existence, Is enough to keep things very interesting. Until the end. When the next adventure begins.

The poem was written in a Pete’s Coffee in Lafayette, CA. It’s reveals my feelings after misplacing my AirPods, removing Spotify, and turning off all notifications on the Phone.

It’s better, but its not amazing. I like it, but it’s uncomfortable. By definition, stillness is not that exciting, but it is mysteriously enriching.

I do hope I find my AirPods, but it’s pretty nice without them.

Music feels like a treat. Maybe for the first time.

It's hard to deny the simple beauty of a function

Tue, 02 Dec 2025 10:08:36 -0800

I love object-oriented programming. I love naming concepts and materializing them with a class. I love dot notation. I love hiding implementation behind a seemingly simple accessor. I’ve always leaned a little more on the side of OOP in the holy war against FP.

But the more code I write, the harder it gets to deny the simple beauty of a function.

Data in, behavior, data out.

Everything you need to understand it is at hand; no bouncing around the file to gather the necessary context. It’s all right there.

The function is the “aha moment” of learning to program.

As the years went by, I drifted away from using them because they look naive when put next to advanced constructs like classes, meta-programming, design patterns, or inheritance. But a few recent experiences might be changing that.

In Sandy Metz’s book 99 Bottles of OOP, she shocks readers with her initial implementation of a program to print the lyrics of the famous “99 Bottles of Beer” song.

def verse(number)
  case number
  when 0
    "No more bottles of beer on the wall, " +
    "no more bottles of beer.\n" +
    "Go to the store and buy some more, " +
    "99 bottles of beer on the wall.\n"
  when 1
    "1 bottle of beer on the wall, " +
    "1 bottle of beer.\n" +
    "Take it down and pass it around, " +
    "no more bottles of beer on the wall.\n"
  when 2
    "2 bottles of beer on the wall, " +
    "2 bottles of beer.\n" +
    "Take one down and pass it around, " +
    "1 bottle of beer on the wall.\n"
  else
    "#{number} bottles of beer on the wall, " +
    "#{number} bottles of beer.\n" +
    "Take one down and pass it around, " +
    "#{number-1} bottles of beer on the wall.\n"
  end
end

Shameless simplicity. I can understand this code instantly. This was her default take and the most legible way to write it, even if it broke away from “best practices”.

Just last month at the SF Ruby conference, well-published author Dave Thomas gave his talk about not needing the class construct for much of our programs. His point was, unless you need a bunch of different instances of a thing, use a function.

# Dave critiques this common ruby style.
EmailService.new(user).send
# And says why not just write it like this.
EmailService.send(user)

I love when people in authority voice something we all intuitively know, but can’t put words to for fear of sounding naive.

It seems we need permission from respected people just to keep things simple.

And as a Ruby programmer, I’ve always typed “c” “l” “a” “s” “s” when I wanted to bring something into existence. But today I’ll pause and see if the simple function might be a better fit.

module Summary
  def self.totals_by_category(scope)
    scope
      .group(:category)
      .sum(:amount)
    # ...
  end
end

Someone on the internet remixed Michael Pollan’s famous advice about eating food, and it might be good advice to follow:

Write code, not too much, mostly functions.

DOM IDs are a real pain in my apps

Wed, 17 Sep 2025 10:42:40 -0700

The standard way to dynamically update HTML content in Ruby on Rails relies heavily on DOM IDs. These IDs are used to identify the target HTML element for an update. The ID must be present on the original page, and in the subsequent partial updates.

Here’s a very simple example of replacing content with a turbo stream.

<form id="settings_form"></form>

turbo_stream.replace "settings_form", ...

To me, this is a problem. My faulty human memory is tasked with keeping these IDs in sync. I will inevitably misspell an ID or forget to update an instance during a rename and won’t encounter the bug until I manually click test through the page update.

During my work on Tend Cash over the last 2 years, I’ve tried to mitigate this. First I reached for the view_component gem, then tried regular view helpers, and finally created my own simple solution inspired by the way React manages references to HTML elements.

Solution 1: view_component

Using the view_component gem, I could encapsulate the ID within the component class. This allowed me to reference it within the template and in the controller during an update.

class SettingsFormComponent
  def id = "settings_form"
end

<form id="<%= id %>"></form>

turbo_stream.replace SettingsFormComponent.new.id

This was a little awkward because I needed the ID in the instance and on the class essentially. Too much overhead just to help with an ID.

Solution 2: View Helpers

Next I went back to the defaults and just made view helpers to keep the IDs safe.

def settings_form_id = "settings_form"

<form id="<%= settings_form_id %>"></form>

turbo_stream.replace settings_form_id

But I was longing for something better. At this point, I noticed that the method names and DOM ID strings were always the same. Some metaprogramming could help me avoid all that double typing. I wished for something that worked like this.

Refs.define do
  ref :settings_form
end

<form id="<%= ref.settings_form %>"></form>

turbo_stream.replace ref.settings_form

Final Solution: Refs

And that’s what I’m using today. I made a very small library inspired by React’s concept of a “ref”. In React, a ref is a way to grab an HTML element without needing a string identifier.

First I define all my string DOM IDs in a file called config/refs.rb.

Refs.define do
  ref :settings_form
end

Then in my views and controllers I have access to this “ref” object with methods that match the identifiers I’ve defined.

<form id="<%= ref.settings_form %>"></form>

turbo_stream.replace ref.settings_form

If a reference doesn’t exist, I get an error in Ruby when the template is being rendered. Much better.

How It Works

Here’s all of the code to copy & paste as you desire.

# lib/refs.rb
class Refs
  def self.ref(name)
    define_method(name) { name.to_s }
  end

  def self.define(&block)
    class_eval(&block) if block_given?
  end

  def self.instance
    @instance ||= new
  end
end

# app/controllers/application_controller.rb
def ref = Refs.instance
helper_method :ref

# config/initializers/refs.rb
Rails.application.config.to_prepare do
  load Rails.root.join("lib", "refs.rb")
  load Rails.root.join("config", "refs.rb")
end

# config/refs.rb
Refs.define do
  ref :settings_form
end

A New Ruby Gem: refs-rails

I’ve packaged up the code above into a ruby gem called refs-rails. Enjoy.

Are you dealing with this ID problem in another way? I’d love to hear about it. Please reach out.

When you put yourself out there, you’ll feel exposed

Thu, 24 Jul 2025 20:19:32 -0700

Yesterday, I got my first conference talk proposal rejection. It was going to be about folder structures, so I’m guessing there wasn’t enough AI to make the final cut.

When I got the email, I felt both disappointed and relieved. It would have been a thrill to speak but I don’t have a ton of time and I love focusing on my main project Tend Cash.

In that arena, I was also rejected yesterday! Right after the kids went to bed, a user signed up, spent about 15 minutes scheduling her expenses, linked a bank, and then deleted her account. She responded to my intro email saying it wasn’t what she was looking for.

As I was falling asleep, the feeling I had was like being out in the open sea without a sail. Like being in an open field with nowhere to hide from the enemy at the tree line. It was a vulnerable feeling. I was exposed.

Then I remembered the common phrase: “put yourself out there.” It did feel like I was “out there” wherever “there” was. And that is exactly where I want to be! I want to speak at conferences and sell my own software and post my own articles.

So today, I’m encouraged. If my goal is to put myself out there, it’s a good sign to feel exposed.

SuperDB Website Build Review

Thu, 13 Feb 2025 10:57:27 -0800

My work designing and developing the superdb.org website is finished. The first commit was on October 4th, 2024 and the final commit was on February 5th, 2025. It took 4 months of work with some holidays mixed in.

The landing page was the first thing I designed. I only planned to make a marketing site with a blog for the project, but later decided to include the docs as well.

Last year, my company decided to change the name of our project from Zed to SuperDB. It was an exciting moment. Communicating what we are building became so much easier. That “DB” at the end signals where we fit in the market.

I played off the word “super” and ran with a superhero theme. I took inspiration from this Superman comic book, borrowing the colors, the 3D text, and “WHAM-O!” speech bubbles. It was a fun one to develop.

Rig Sans was the font I chose for body and headings. I picked a yellow accent color with red and blue secondary accents. No one ever asks for a “light mode”, so I themed it dark from the start.

The old docs site contained over 100 pages of content. It got built using Docusaurus. There are quite a few things I don’t care for about Docusaurus (and all React-Based website builders). They make me relearn everything I know about building websites. I need to use their a brand new way to include a “script” tag for instance. The class names in Docusaurus are unreadable (they fixed this in recent versions), the way to extend it (swizzling) is complicated, and it’s slow to build because JavaScript does the building.

This was the old site.

At this stage of my life, I’m drawn to simple, stable tools. I lean into vanilla HTML, JS, and CSS as much as I can. They are pretty freaking good now.

I use Hugo for all my static site needs. It has downsides as well, but at least it’s fast, it lets me write standard HTML, CSS, and JS, and gives me good data structures for pages, sections, menus, markdown, metadata, and partials. The downside is having to write Go templates. It’s an awkward and verbose language. But the upsides are too good, so I’m getting over it.

While working on this, I discovered even more features of Hugo like the virtual union file system. That allowed me to render the docs in the site without moving the files into the website folder.

[[mounts]]
  source = "../super/docs"
  target = "content/docs"

I learned how to provide a custom renderer for code blocks. This let me render an interactive playground based on a block of code in the markdown.

The code in this file…

…will turn this code block in the markdown…

…into this interactive playground on the website!

I used @hotwired/turbo for all JavaScript interactions. It paired very nicely with Hugo.

I learned that everything you setup in the "turbo:load" event must get torn down in the "turbo:before-cache” event. I felt pretty clever after discovering that – until I stumbled across this post at better-stimulus. The “good” way to integrate JS libraries is with a stimulus controller using the connect() and disconnect() callbacks. I also learned that each time you add data-controller=“my-controller”, that element is attached to a single instance of the controller. Good to know.

I got to play around with new more vibrant colors like this:

@supports (color: oklch(0% 0 0)) {
  :root {
    --color-accent: oklch(0.93 0.2 102);
    --color-accent-2: oklch(0.68 0.27 30.01 / 1);
  }
}

That overrides my previous color variables with the new fancy ones.

The biggest question mark I had about the project was how to support multiple documentation “versions”. Hugo did not let me down. It took some deeper understanding of the data structures, but I had all the tools I needed. When I needed to build the versions dropdown popover, I reached for the css anchor positioning spec and grabbed a polyfill so that I could use the future syntax. I can’t wait until that is supported everywhere (as well as scroll animations).

The final discovery to share is how I got the GitHub Star count in the header. Instead of using JavaScript to fetch the number after the page loads, I used Hugo to make the HTTP request at build time. The downside is that the number only gets updated when you deploy the site, but I like that no JS is involved. It’s pretty easy to trigger a deploy these days.

Here was my template to grab the star count.

{{ template "utils/star_count.html" "brimdata/super" }}

And the implementation.

{{ $url := fmt.Printf "https://api.github.com/repos/%s" . }}
{{ with try (resources.GetRemote $url) }}
  {{ with .Err }}
    {{ errorf "%s" . }}
  {{ else }}
    {{ $data := .Value | transform.Unmarshal }}
    {{ $count := $data.stargazers_count }}
    {{ if gt $count 1000 }}
      {{ $thousands := math.Div $data.stargazers_count 1000 }}
      {{ fmt.Printf "%.1f" $thousands }}k
    {{ else }}
      {{ $count }}
    {{ end }}
  {{ end }}
{{ else }}
  {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}

I loved working on this project. Learned a lot. Here’s the link again. Check it out.

superdb.org

useStateObject: A Simple, Convenient API Around useState

Thu, 15 Aug 2024 16:34:22 -0700

I am loving this API for working with React state. It’s a very light wrapper around useState. I call it useStateObject.

Here’s how it looks:

const state = useStateObject({
  offset: 0,
  src: 1,
  size: 200,
});

That’s how I set it up with the initial state. I can access any of those state properties with dot syntax.

state.src * state.size;

I get to use the following methods in my event handlers. This is how to merge another object with the state.

state.merge({ src: null, offset: 0 });

Here I provide a whole new value to the state.

state.set({ src: 2, offset: 200, size: 100 });

Just set one property.

state.setItem("offset", 999);

Reset the state back to its initial value.

state.reset();

Here’s the code if you want to see what this API feels like in your own project.

import { useRef, useState } from "react";

export function useStateObject(init) {
  const initialState = useRef(init).current;
  const [state, setState] = useState(init);

  return {
    ...state,
    set: setState,
    setItem: (key, value) => {
      setState((prev) => ({ ...prev, [key]: value }));
    },
    merge: (newState) => {
      setState({ ...state, ...newState });
    },
    reset() {
      setState({ ...initialState });
    },
  };
}

…and for you TypeScripters…

import { useRef, useState } from "react";

export function useStateObject<T>(init: T) {
  const initialState = useRef(init).current;
  const [state, setState] = useState<T>(init);

  return {
    ...state,
    set: setState,
    setItem: (key: string, value: any) => {
      setState((prev) => ({ ...prev, [key]: value }));
    },
    merge: (newState: Partial<T>) => {
      setState({ ...state, ...newState });
    },
    reset() {
      setState({ ...initialState });
    },
  };
}

export type StateObject<S> = S & ReturnType<typeof useStateObject>;

Anyone want to figure out how to type the setItem(key, value) method? Email me and I’ll update the post.

Update August 22, 2024

Thank you to the folks who responded to my request for TypeScript help. I have been taught that what the setItem arguments need is a implied generic type that extends a union of the state object’s keys (how’s that for some shop talk). Then I can use that generic to index the main state type, which is another implied generic. Nifty.

setItem<K extends keyof T>(key: K, value: T[K]) {
  // ...
}

The complete TypeScript version is thus:

import { useRef, useState } from "react";

export function useStateObject<T extends object>(init: T) {
  const initialState = useRef(init).current;
  const [state, setState] = useState<T>(init);

  return {
    ...state,
    set: setState,
    setItem: <K extends keyof T>(key: K, value: T[K]) => {
      setState((prev) => ({ ...prev, [key]: value }));
    },
    merge: (newState: Partial<T>) => {
      setState({ ...state, ...newState });
    },
    reset: () => {
      setState({ ...initialState });
    },
  };
}

The “implied generics” work great when you pass a literal into the function, but in case you need to type the return value explicitly, here’s a utility type for that.

export type StateObject<T extends object> = T & {
  set: React.Dispatch<React.SetStateAction<T>>;
  setItem: <K extends keyof T>(key: K, value: T[K]) => void;
  merge: (newState: Partial<T>) => void;
  reset: () => void;
};

The 3 Types of CSS Utility Classes

Mon, 01 Jul 2024 17:33:58 -0700

A 9.0 earthquake shook my front-end world when I discovered “layout primitives” at every-layout.dev. Then an aftershock rolled through when I learned about fluid sizing and spacing tokens from utopia.fyi. It’s completely changed the way I write HTML and CSS.

Programming is the most fun when I am composing primitives. If those primitives are at the right level of abstraction, programming feels like magic.

In the aftermath of the quake, I am curiously focused on creating the perfect primitive CSS classes to compose in my HTML. In doing so, I have noticed three categories of classes emerging from the stylesheet.

Aesthetic classes
Layout classes
Spacing classes

Note

Before this personal evolution, I thought it best practice to scope and isolate CSS, avoid utility classes, and name everything something semantic. It left me with code that was too coupled, hard to keep consistent, and difficult to understand a few months later. I queried Google for “Alternative to BEM CSS” which led me to Dave Rupert’s article, which led me to Andy Bell’s CUBE CSS. I’ve never looked back.

Aesthetic Classes

The sole concern of an aesthetic class is the look of the element. The “(B)locks” in CUBE. They are specific to the branding of the company or project. They will be named things like: .card, .aside, .quote, .note, .toast, .dialog, .menu, and .tab and contain properties like color:, background:, border:, and box-shadow:. They SHOULD NOT contain things like padding:, display:, or margin:. Those go in the next two types.

Layout Classes

A layout class is solely focused on laying out elements. Not the look (above) and not the spacing between the elements (below). They are usually placed on the parent element and have names like .center, .cluster, .repel, .cover, .stack, .flow, .prose, .scroller, and .switcher. The CSS properties within them should be things like: display:, align-items:, justify-content:, flex-wrap:, grid-template-columns:, and overflow:.

Spacing Classes

Spacing classes are focused only on the space between elements that have been laid out with one of the classes above. If you have never surfed over to utopia.fyi, run as fast as you can to that link to generate fluid spacing and sizing tokens. Once you have those custom properties generated, use Tailwind or SCSS to generate spacing utility classes based on those spacing tokens (or just copy and paste some if you don’t have the tooling).

Spacing classes should have names like .gap-s, .gap-m, .gap-l, .gutter-s, .gutter-m, .gutter-l, .stack-s, .stack-m, stack-l and only contain properties like gap:, margin:, padding:, and their variations.

DO NOT MIX CONTENTS

These CSS concerns are best not to be mixed into the same class. This is where I’ve gone wrong in the past. I used to write CSS like this:

<div class="card">
  <h2>Summary</h2>
  <p>Here you'll find the summary of the complicated data.</p>
  <a href="/details">View Details</a>
</div>

.card {
  background: white;
  border: 1px solid var(--border);
  padding: 1rem;
  margin-inline: auto;
  display: flex;
  flex-direction: column;
  gap: 0.5rem;
  box-shadow: 0 0 5px rgba(0, 0, 0, 0.5);

  & h2 {
    color: var(--brand);
  }
  & p {
    color: var(--text-less);
  }
}

While the HTML looks clean, discovering what the CSS is doing is not immediately obvious. It is highly coupled to the markup and I will certainly be bouncing between to the two files to make changes.

Let’s rewrite it using the three types of primitives described above. Split the aesthetic, layout, and spacing concerns into their own classes and compose a masterpiece in the HTML.

<div class="card-1 stack box gap-xs">
  <h2 class="color-brand">Summary</h2>
  <p class="color-text-less">
    Here you'll find the summary of the complicated data.
  </p>
  <a href="/details">View Details</a>
</div>

/* Asthetic */
.card-1 {
  background: white;
  box-shadow: 0 0 5px rgba(0, 0, 0, 0.5);
  border: 1px solid var(--border);
}

.color-brand {
  color: var(--brand);
}

.color-text-less {
  color: var(--text-less);
}

/* Layout */
.stack {
  display: flex;
  flex-direction: column;
  gap: var(--space-s);
}

/* Spacing */
.box {
  padding: var(--space-s);
}

.gap-xs {
  /* Generated by tools (or not) */
  gap: var(--space-xs);
}

Why is this better?

Each of those CSS classes is focused on one thing like all good software components are. Once they are written, I can reuse them over and over in my HTML. If I don’t like the look of “.card-1” for this element, I can swap it out for “.card-2” by changing one character in the HTML class. Once the core primitives are written, I don’t need to leave my HTML nearly as much to style things. It makes development very fun. This is why Tailwind took off.

The Tailwind Phenomenon

For those of you thinking, “This is exactly what I already do with my Tailwind classes.” Well, it’s not quite the same. Tailwind does allow us to stay in the HTML, but in my opinion, its utilities are too primitive. Heydon Pickering has a great article on this.

For example, here I am centering a div with Tailwind.

<div class="mx-auto max-w-5">
  <h1>Too Much Implementation Detail</h1>
</div>

And here it is with a “center” layout class.

<div class="center">
  <h1>Much Easier To Read</h1>
</div>

Tailwind achieves that same thing as the “.center” layout class, but it shows all the implementation details. The “center” class is more descriptive, concise, and easier to remember.

And for those of you thinking, “YUCK, utility classes are ruining front-end web development” like I was, remember composing primitives is what makes this job fun. If you nail the primitives, programming feels like the sun on your back.

Ship That Code • Publish That Post

Wed, 26 Jun 2024 11:38:31 -0700

Two articles I read this week have inspired the heck out of me. The first was by Jared Turner of thoughtbot with the punchy title “WIP is waste”. Jared described how zero value is delivered to the users of your software until it is shipped. The longer code changes remain on your machine, the more pure cost it is to the organization. Those words have been ringing in my head for days, and I have personal experience to confirm their truth.

Nothing kills motivation than being stuck in a “code hole”. You know you’re in a code hole when you have 100+ type errors to fix, tests are not passing, you are “refactoring” something distantly related to what you set out to do, and the diff from main is so big the PR is unreviewable.

I’ve been there many times. It takes persistent effort to resist digging myself into one of these. I must remind myself to stop, focus on something small and ship it. It feels good! Get that little improvement out into the world. Take a small step toward the big vision.

Ship that code.

The second article was about the journey of my favorite web analytics company, Plausible. They began in 2018. They raised zero dollars. They spent zero dollars on marketing. They simply wrote blogs. They were open and honest about everything. They had an ethic to their business practices, and it paid off. Their team of 4 made a million bucks in 2022 when the post was written. I love hearing stories like this. It’s exactly how I am going to grow and build Tend, my simple budgeting software.

“I’ll write my way out!” is what Hamilton sang in his musical and it’s true for software startups over 200 years later. Put another link on the internet.

Publish that post.

How to Debug NodeJS with Breakpoints in VSCode

Thu, 13 Jun 2024 15:29:18 -0700

I made a quick screen recording using the VSCode debugger to break on a line of code in my NodeJS electron process. It’s a pretty nifty trick!

*(main process, not main client 👍)

Hope this helps someone!

The One Thing Missing in Every Budget App: Spending Commitments

Sun, 02 Jun 2024 08:34:44 -0700

The one thing missing in every budgeting application is the “Spending Commitment”.

Definition: “A thing I am already committed to paying for”

This concept a fundamental part of any budgeting system. Why?

Let’s back up. Why does one create a budget in the first place? I have thought hard to distill a clear answer for this. Here it is.

A good budget must answer:

Is my lifestyle sustainable?

Should I buy this thing in front of me right now?

To answer the first question, I absolutely need to know how much money I’ve already committed to spending. These are all those repeating payments I have. This total will tell me if my lifestyle is sustainable. If it is not, I will need to make dramatic changes like move, get a cheaper car, or add a side job.

To answer the second question, I need need to know how much cash is not already committed. To get this number, I take my income and subtract the committed spending. This is my “free cash”. Can I buy this thing in front of me right now? If I have the free cash to spend, yes, otherwise no.

In so many budgeting apps, this information is not prominently displayed.

Take the classic bar chart of how much I’ve spent each month. This was my go-to chart in Mint for years. Since my committed and free spending are not separated, even if I was the most frugal I’ve ever been during one month, a single large yearly expense would make it appear that I overspent. The data is polluted. I would need to make an extra effort to see if I actually overspent or not. Maybe you’ve felt this pain too. We need to clearly separate the things we can control month-to-month (free spending) from the things we can’t (committed spending).

A chart that only shows me how much free cash I’ve spent each month would be so much more helpful. It would compare apples to apples. If the bar is high one month, it actually meant that I went crazy with the credit card.

This separation of committed spending and free spending is so helpful for understanding your personal finances, I’m surprised it’s not built in to most budgeting apps.

It’s built in to Tend, though.

Fix for Kamal Deploy Assets Not Updating

Tue, 23 Apr 2024 10:31:32 -0700

Does this sound like you?

You are using Sprockets to pre-compile assets for production.
You are using Kamal to deploy.
You have asset bridging enabled in your deploy.yml file.

If that is you, you will find that your assets are not updated about 50% of the time. Randomly.

The fix is to disable asset bridging in deploy.yml.

# comment this out 👇
asset_path: /rails/public/assets

April 25, 2024 Update

Wait! There is another way to fix this without disabling asset bridging. See the section at the end of this post. But keep reading to understand the problem.

Why?

When the deploy pipeline runs rails assets:precompile a file will be created called .sprockets-manifest-randomhex.json. This manifest file maps the name of your asset to the digested name that will be used in production for stylesheet_link_tag and the like.

From the Rails Guide:

The command also generates a .sprockets-manifest-randomhex.json (where randomhex is a 16-byte random hex string) that contains a list with all your assets and their respective fingerprints. This is used by the Rails helper methods to avoid handing the mapping requests back to Sprockets.

Now what is asset bridging in kamal? Here a snippet from their docs.

If there are changes to CSS or JS files, we may get requests for the old versions on the new container and vice-versa. To avoid 404s we can specify an asset path. Kamal will replace that path in the container with a mapped volume containing both sets of files. This requires that file names change when the contents change (e.g. by including a hash of the contents in the name).

You can enable this behavior by specifying the asset_path: option in your deply.yml.

# Again, this is the problem.
asset_path: /rails/public/assets

With this option set, kamal will keep both the current and the previous versions of the assets on your server. That means there will be two .sprockets-manifest-randomhex.json files. The Rails server will choose the first one it finds! It might be the new one, it might be the old one depending on where that random hex puts it on the file system.

The fix for now is to turn off asset bridging. The cost is low. It will only affect people who have in-flight requests right as the server restarts. They would just have to re-load the page again.

In the future, this could be fixed by only keeping one version of the manifest file, or specifiying which manifest to use somehow.

Thank you so much to reddit user ignurant for their detailed explanation in this comment.

Update on April 25, 2024

There is another solution that allows you to still bridge the assets. You explicitly set the name of the manifest file in your production.rb file like this:

# config/environments/production.rb

config.assets.manifest = Rails.root.join('config', 'manifest.json')

This removes the random hash, allowing the new file to overwrite the old one on deploy. I don’t know the reason for the random hash by default or the implications of removing it, but this would fix the problem outlined in this post. Thank you to you reddit user _skp for their help in this comment.

How to Set Output Values in Github Actions

Mon, 22 Apr 2024 14:15:10 -0700

This is the syntax for setting an output parameter in a Github Actions step.

echo "{name}={value}" >> "$GITHUB_OUTPUT"

Here’s an example of using this syntax in a workflow step.

- name: Expose the artifact path
  id: paths
  run: echo "artifact='app-setup.exe'" >> "$GITHUB_OUTPUT"

Here’s an example of using the output of a command as the value.

run: echo "artifact='$(yarn run artifact-path)'" >> "$GITHUB_OUTPUT"

And here is how you would access that output value in a later step.

- name: Later Step
  run: ./bin/codesign ${{ steps.paths.outputs.artifact }}

The syntax is steps.[step_id].outputs.[output_name].

It took me several attempts to discover this snippet on the Github Actions docs, so I decided to post it here.

Happy hacking.

Responsive Sizing for React Arborist Tree Component

Wed, 17 Apr 2024 10:00:47 -0700

Many people ask me about how to dynamically set the width and height of the Tree component based on its parent using react-arborist.

<TreeView width={300} height={500} />
// How do I make these responsive?

The component only accepts fixed pixels for the height and width because it virtualizes the rows. It uses the tree height, scroll position, and row height to render only the nodes that are visible to the user. Nodes are mounted as soon as they are scrolled into view and unmounted when they overflow.

This is great, but I almost always want my tree to be the same width and height of its parent, not a fixed size.

Here’s how to do it.

Let’s get the HTML marked up so that the parent will grow and shrink as the window resizes.

<div className="sidebar">
  <div className="tree-parent">
    <TreeView />
  </div>
</div>

We will first style the .sidebar class.

.sidebar {
  height: 100vh;
  width: 300px;

  display: flex;
  flex-direction: column;
}

We make this element as high as the viewport and 300px wide to make it look like a sidebar. Then we make it a flex parent setting the flex-direction to “column” so the children stack vertically.

Next is the .tree-parent class.

.tree-parent {
  flex-grow: 1;
  min-block-size: 0;
}

Here we make the element grow to fill all available empty space and set the min-block-size to zero.

Note

I always forget about the min-block-size (min-height). If you omit this style, growing the parent will work fine, but shrinking it will not shrink the tree. The reason is the default value for min-height is “auto”. The browser will consider how tall the children are to determine the height of the parent. The issue is we want the the child (tree) to set its height to whatever the parent is. It’s like a co-dependent DOM relationship. Setting the minimum height to zero tells the element not to concern itself with its children’s height. Just grow and shrink as if you have no children.

To summarize, we tell this element to grow to fill all available space, and always shrink if your parent gets smaller. Don’t worry about what your children are doing.

Now we need to get the size of the .tree-parent element and pass those pixels to the <TreeView /> component, while responding to resizing. For this we reach for the ResizeObserver DOM API.

import { TreeView } from "react-arborist";
import useResizeObserver from "use-resize-observer";

function Sidebar() {
  const { ref, width, height } = useResizeObserver();

  return (
    <div className="sidebar">
      <div className="tree-parent" ref={ref}>
        <TreeView width={width} height={height} />
      </div>
    </div>
  );
}

We could write the hook from scratch, but it will probably end up looking exactly like this small, well-written library use-resize-observer.

You attach the ref to the .tree-parent and now you have its width and height in pixels. Those variables will be updated every time that element is resized in the DOM and the component will re-render with updated width and height values.

This is exactly where we want to be. We can pass those dimensions to the <TreeView /> component and it will always be the same size as its parent.

Cache the Result of a JavaScript Getter Method

Tue, 16 Apr 2024 12:49:54 -0700

My first programming language was Ruby. Well, it was actually Microsoft Excel, then VBA, then C# for a university class, then Ruby.

Ruby’s syntax is designed for developer happiness. What a wonderful goal. In Ruby, you don’t need to add parenthesis to method calls if there are no arguments.

class FSEntry
  def stat
    File.stat(path)
  end
end

# And you can call it like this
entry = Entry.new
entry.stat # no parens!

However, when I don’t see parens it’s not obvious whether this is a cheap or expensive operation. In this case, we are hitting the file system each time we call it.

So it’s a common practice in Ruby to “memoize” expensive methods. In simpler terms, to cache the result of a method body in a private instance variable.

This is how it looks in Ruby.

def stat
  @_stat ||= File.stat(path)
end

I love what I call the “or-equals” operator in Ruby. Others call it the “short-circuit” operator. It works like this. If the variable @_stat is falsey, it will run File.stat and store the result in the @_stat variable. Finally, since Ruby always returns the result of the last expression in a block or method, the resulting @_stat value is returned. This has the effect of only running File.stat the first time this method is invoked. All other times, we just get the cached @_stat value.

Can this type of thing be done in JavaScript?

Not so long ago, JavaScript added “getter” and “setter” methods to classes. Like Ruby, you can call these methods without parenthesis.

class FSEntry {
  get stats() {
    return fs.statsSync(this.path);
  }
}

const entry = new FSEntry(path);
entry.stats; // No parens!

Now to cache the result, we can port the same strategy we used in Ruby. Create a private instance variable to cache the result the first time the method is called.

class FSEntry {
  get stats() {
    if (this._stats !== undefined) return this._stats;
    const result = fs.statsSync(this.path);
    this._stats = result;
    return result;
  }
}

This gets the job done, but it’s painfully verbose. No developer happiness increase. And if you’re using TypeScript it’s even worse.

class FSEntry {
  private _stats: undefined | fs.Stats;
  get stats() {
    if (this._stats !== undefined) return this._stats;
    const result = fs.statsSync(this.path);
    this._stats = result;
    return result;
  }
}

This is ridiculous.

After some thought, I found a way to reign in the chaos. First, I made a utility function off in a different file that looks like this.

function cache(self, prop, func) {
  const cache = self[prop];
  if (cache !== undefined) return cache;
  const result = func();
  self[prop] = result;
  return result;
}

This function checks for a property prop on the self argument. If it exists, return it. If not, run the func and assign the result to that property and return it.

Here’s how we call it.

import { cache } from "../utils.js";

class FSEntry {
  get stats() {
    return cache(this, "_stats", () => fs.statSync(this.path));
  }
}

And we’re back! To a one-liner! Now we can cache methods all over the place.

What about Type Safety?

All you TypeScript purists may wince at that memo function. But to me, the tradeoff is so so worth it. Here’s how I typed the cache function in my app.

function cache<T>(self: object, prop: string, func: () => T): T {
  const cache = self[prop];
  if (cache !== undefined) return cache;
  const result = func();
  self[prop] = result;
  return result;
}

The return type of the func parameter is inferred and used as the return type for the whole cache function.

Pretty sweet.

The Friend Is You

Tue, 16 Apr 2024 07:46:19 -0700

Imagine hanging out with someone all day who berates you. They make final judgements about your character. They criticize anything you do imperfectly. They gossip about everyone you meet. They treat everyone like this. They even shame you for having such a shitty friend around all the time. You desperately want them to go away, but they won’t stop following you. They never leave. The moment you wake up until the moment you fall asleep. Every conscious moment, their stream of negative comments flows into your ear.

What would you do?

You would escape.

You would fill your life with noise to distract yourself them. When you are inevitably alone, you would do anything to alter your mind and shut them out for a few moments because solitude is abusive.

Now imagine a true best friend. They arrive the moment you arise. This friend knows everything you’ve ever done, good and bad. They know. They care. They love you. All day, they listen to you. They never make a final judgement. They say things that encourage you to live into higher and higher versions of yourself. They fully accept where you’re at today and they understand the difficult moments you’ll feel as you grow. They are fascinated by your unique personality. They don’t gossip about other people. In fact, they see everyone like this. Even your enemies. They only speak truth to you in the service of love.

What would you do?

The sky’s the limit. Solitude is no longer scary, it is grounding.

We don’t get to choose many things, but we get to choose our friends.

Finally Understanding How Array.sort(comparator) Works

Thu, 28 Mar 2024 11:39:07 -0700

After 13 years of JavaScript, I finally have a way to remember how the comparator function in Array.sort() works.

I think the trouble is that all the examples use this shorthand syntax.

array.sort((a, b) => b - a); // too hard for James

This is beyond confusing for me. In the past, I would just try b - a then try a - b and pick which one gave me the result I wanted. But now I have a mental model simple enough for me to remember.

First, the sole purpose of the comparator function is to answer this quesions:

Where should “a” be placed in the new sorted array? To the left of “b” or to the right?

The arguments passed to the comparator function are usually named a and b. This makes sense to me, since the first arg comes before the second arg, and a comes before b in the English alphabet. These arguments represent two items in the array.

Now let’s think about the return value. The function must return a number. Numbers exist on a number line going from left to right just like the items in an array. The negative numbers are on the left, zero is in the middle, and the positive numbers on the right.

-3   -2   -1   0   1   2   3
----------------------------
    a good ol' number line

So check it out, if your comparator function returns a negative number, the first argument a will come first, before b. Just like negative numbers on the number line come first!

If the function returns a positive number, the first argument a will come after b. The a item will be on the “right” side of of b, just like the positive numbers are on the “right” side of the number line!

🤯

If the function returns 0, there will be no change to the existing order of the elements. This one was pretty easy to remember.

To summarize, we just want to find out where a goes. Does it go to the left or right of b. Negative means left, positive means right. Number line. Left to right.

The “left-to-right-ness” of the number line, the items in an array, the alphabet, and the positional arguments all finally clicked for me today.

Maybe this will click for you too and you can save yourself 13 years of googling “How does array.sort(comparator) work again?”.

Using @monaco-editor/react in Electron without Internet Connection

Wed, 27 Mar 2024 16:58:00 -0700

The Monaco Editor is awesome. It’s what powers VSCode. I wanted to use it to power the query editor pane in Zui, the data exploration app I work on. I reached for @monaco-editor/react because it fit well in the app’s NextJS, React, and Electron tech stack. Loading the actual monaco-editor code seems to be a bit of a headache, so in an effort to make setup simple, @monaco-editor/react fetches the minified monaco-editor files from jsdelivr over the network.

This was a problem. Zui should work without needing to be connected to the internet.

My solution involved a configuration change in @monaco-editor/react, custom protocol handlers in electron, and disabling the webSecurity option in my browser window instances (only in development).

The first step was to add the monaco-editor package to my dependencies.

yarn add monaco-editor

Then I configured the @monaco-editor/react loader to fetch the files from my own made up url. This code should run in the browser window before react mounts up.

import { loader } from "@monaco-editor/react";

// This is how you change the source of the monaco files.
loader.config({
  paths: {
    vs: "app-asset://zui/node_modules/monaco-editor/min/vs",
  },
});

What’s the deal with that url? I just made it up. It can be anything because I will intercept requests to it in electron’s main process using the protocol module. Then I can fetch the appropriate file from the node_modules directory on disc and return it.

Here was my finished code. This should run in the main process during initialization before any browser windows are created.

import { app, protocol } from "electron";
import { AssetUrl } from "../protocols/asset-url";
import { AssetServer } from "../protocols/asset-server";

protocol.registerSchemesAsPrivileged([
  {
    scheme: "app-asset",
    privileges: {
      standard: true,
      supportFetchAPI: true,
      bypassCSP: true,
    },
  },
]);

const server = new AssetServer();

app.whenReady().then(() => {
  protocol.handle("app-asset", (request) => {
    const asset = new AssetUrl(request.url);

    if (asset.isNodeModule) {
      return server.fromNodeModules(asset.relativeUrl);
    } else {
      return server.fromPublic(asset.relativeUrl);
    }
  });
});

First we register the "app-asset" scheme with “standard” privileges, making it behavie like the "http" scheme. Read more about that here.

Then I new up my little AssetServer class which is responsible for finding the files on the file system to return to the requestor. That code is posted below.

Once the app fires the "ready" event, I intercept all requests to the "app-asset" scheme, using protocol.handle(). If the pathname starts with “/node_modules” I look it up using Node’s require.resolve and return it. Otherwise I look for that file in the public directory and return it.

Here’s the code for the AssetServer class.

import { app, net } from "electron";
import path from "node:path";
import { pathToFileURL } from "node:url";

export class AssetServer {
  fromNodeModules(relativePath: string) {
    const file = require.resolve(relativePath);
    const url = pathToFileURL(file).toString();
    return net.fetch(url, { bypassCustomProtocolHandlers: true });
  }

  fromPublic(relativeUrl: string) {
    const file = path.join(app.getAppPath(), "out", relativeUrl);
    const url = pathToFileURL(file).toString();
    return net.fetch(url, { bypassCustomProtocolHandlers: true });
  }
}

Notice the {bypassCustomProtocolHandlers: true} option. This is just in case I have other protocol handlers in my app for the "file://" scheme. If I don’t bypass, then my other custom protocol handlers will intercept this new request. Took me a whole day to figure that one out.

And the code for the AssetUrl class.

export class AssetUrl {
  url: URL;

  constructor(url: string) {
    this.url = new URL(url);
  }

  get isNodeModule() {
    return this.url.pathname.startsWith("/node_modules");
  }

  get relativeUrl() {
    if (this.isNodeModule) {
      return this.url.pathname.replace("/node_modules/", "");
    } else {
      return this.url.pathname.replace(/^\//, "");
    }
  }
}

Now depending on how you are serving your HTML file, you may see this error below in the dev tools.

Failed to construct 'Worker': Script at 'app-asset://node_modules/monaco-editor/min/vs/base/worker/workerMain.js#editorWorkerService' cannot be accessed from origin 'http://localhost:4567'.

I was serving my HTML files from the NextJS development server on port 4567. This is my code that loads the HTML in electron.

const url = env.isDevelopment
  ? `http://localhost:4567${this.path}?id=${this.id}&name=${this.name}`
  : `app-asset://zui${this.path}.html?id=${this.id}&name=${this.name}`;

browserWindow.loadURL(url);

The reason for the error is the “same-origin” policy enforced by the browser window. This means that JavaScript can’t load more JavaScript from a different site. In my setup, the monaco code was trying to fetch a file at the app-asset://zui origin, but it was running on the http://localhost:4567 origin.

As you can see above, in production, the html file is also loaded from the app-asset://zui origin so this error will not occur.

To fix it in development, I decided to disable the same-origin check on the browser window, by passing false to the webSecurity option in webPreferences.

const browserWindow = new BrowserWindow({
  webPreferences: {
    webSecurity: env.isProduction,
  },
});

That env object is a utility module I created to check for environment variables like process.NODE_ENV === "production" .

And that’s all folks. I am happy with the resulting code and now the app works offline. What a concept.

Transitions All Settled

Tue, 05 Mar 2024 20:26:00 -0800

I just published a JavaScript library called transitions-all-settled that allows you to wait for CSS transitions to settle before you do something.

The package exports a single function that accepts an HTML node and returns a promise. The promise resolves when all CSS transitions on the HTML node and its children have settled.

import { transitionsAllSettled } from "transitions-all-settled";

await transitionsAllSettled(node);

The term “settled” means that if a node received a transitionstart event, it also received a transitionend or transitioncancel event.

This is useful for exit animations to wait for all CSS transitions to settle before removing the node from the DOM.

Here is a demo. Click any square.

Here’s the code that makes that happen. Here’s the HTML.

<div id="canvas" class="flow">
  <div class="square first"></div>
  <div class="square second"></div>
  <div class="square third"></div>
</div>

The CSS.

.square {
  width: var(--step-3);
  height: var(--step-3);
  background-color: var(--color-text);
  transition-duration: 1s;
}
.clicked .square {
  background-color: var(--color-primary);
  transform: translateX(100%) rotate(90deg);
}
.first {
  transition-delay: 0;
}
.second {
  transition-delay: 500ms;
}
.third {
  transition-delay: 1000ms;
}

Here’s the JavaScript.

import { transitionsAllSettled } from "transitions-all-settled";

const canvas = document.getElementById("canvas");

canvas.addEventListener("click", async () => {
  canvas.classList.toggle("clicked");
  await transitionsAllSettled(canvas);
  alert("Transitions All Settled");
});

The package is very small. Take a look at the source to see exactly how it works.

GitHub: jameskerr/transitions-all-settled

There Are Only Two Types of Transactions

Wed, 08 Nov 2023 09:40:46 -0800

There are only two types of transactions.

The ones you are present for.
The ones you are not.

This just dawned on me. It’s easy to keep track of the spending you are present for (groceries, shopping, fun). It’s hard to keep track of the ones that happen in the background (rent, insurance, subscriptions). Even harder to try and manage both in your head!

Ideally, you have a tool that tracks all background transactions for the month/pay-period and gives you the total. Subtract that from your income and you have the only number you need to keep track of. The amount you are able to spend in-person. Type #1.

Income - Background Transactions = Remaining for In-Person Transactions

Remember when you were a kid and got 40 bucks? It was easy to keep track of it because there were no background transactions on that $40. You were present for every transaction. We’ve got to get back to that.

Against Single Element React Components

Mon, 06 Nov 2023 15:51:23 -0800

It's not uncommon to see this type of single element React component.

function Title({ children, ...rest }) {
  return <h1 {...rest}>{children}</h1>;
}

If you use a library like styled-components, you’re very much encouraged to write in this way.

const Nav = styled.nav``;
const List = styled.ul``;
const Item = styled.li``;
const Link = styled.a``;

function MyApp() {
  return (
    <Nav>
      <List>
        <Item>
          <Link href="/home">Home</Link>
        </Item>
        <Item>
          <Link href="/blog">Blog</Link>
        </Item>
        <Item>
          <Link href="/about">About</Link>
        </Item>
      </List>
    </Nav>
  );
}

Problems with Single Element Components

I have written my share of the code above. I won’t anymore.

Take a look at that <Link /> component. What props does it take? Where is the documentation for it? Well, just scroll up and see that it’s actually just an anchor tag. What if it’s exported from another file? Ok, just open up the file. Now what about every other component written this way? I’m going to be scrolling and opening all sorts of files to see what these tiny components do until I memorize them for my specific app.

Now take a look at this code:

<a></a>

No scrolling needed. No lookups needed. We all know exactly what an anchor tag does. And if we don’t remember something, there are loads of docs on this and every other HTML element.

We’ve all put countless hours in learning HTML. Hiding the underlying element with a tiny React component throws all that knowledge away.

Components that Slightly Change the API

To make this worse, some components slightly change the established HTML API. I see it often with buttons.

We all know this API.

<button type="submit">Click Me</button>

But many times I’ve wrapped this up into something like:

<Button isPrimary text="Click Me" />

Now everyone needs to memorize or lookup the new API whenever they need a button. Hard.

The Solution is HTML with a Class Attribute

When we use the single element component pattern, we give up the well-known HTML APIs to encapsulate some visual styles. Not a fair trade. Especially when HTML has a built-in, stone-age solution for encapsulating visual styles: the class attribute.

import styles from "./app.module.css";

function MyApp() {
  return (
    <nav className={styles.mainNav}>
      <li>
        <a href="/home">Home</a>
      </li>
      <li>
        <a href="/blog">Blog</a>
      </li>
      <li>
        <a href="/about">About</a>
      </li>
    </nav>
  );
}

Nobody is going to wonder what’s going on here ☝️.

Conclusion

The leaf nodes of our component trees should be full of good ‘ol HTML because it is universally known and documented. Don’t throw all that out just to wrap up a visual style.

How to Optimize Your Hugo Blogging Workflow on Mac

Fri, 27 Oct 2023 09:22:36 -0700

I love this quote by John Cutler from his post on disincentives.

“Good things can happen when you make it easier to do good things.” –John Cutler

He advises to focus less on incentivizing desired behavior, and more on removing disincentives from desired behavior. It’s brilliant.

My desired behavior is to write more posts on my Hugo blog.

I like Hugo because it’s free, fast, and fun to develop. But look at all these hurdles I had to jump when publishing!

Open a terminal
Type hugo new posts/my-interesting-post
Remember 👆 syntax since I don’t do it frequently
Open the new file in a markdown editor
🌟 WRITE THE WORDS (desired behavior)
Back to the terminal
Run hugo serve to preview
Open up the browser
Navigate to localhost:1313
Back to the terminal to git add . git push
Thankfully, Netlify will automatically deploy on push

Here’s how I removed all that friction.

macOS Shortcuts

I used the macOS Shortcuts app to automate the steps above. Then I put the shortcut icons in my dock for a “one-click” experience.

Here’s my new workflow.

One click to start writing a new post.
One click to preview it a browser.
One click to publish.

It Worked!

I’m writing much more now that I’ve got these buttons. Here are screenshots showing you how to set these up for yourself.

1. ‘New Post Bundle’ Shortcut

What's going on here?

The first action prompts me for the title text
Then the second action has my response in the $1 variable
Change directory in my blog
Run hugo new posts/$1
Open my markdown editor iA Writer

Notice I had to write the full path to the hugo binary. Not sure why.

2. ‘Preview Blog’ Shortcut

What's going on here?

First I kill all exisiting hugo processes
Change directory into the blog
Run hugo serve & putting the server process in the background 4. Then I open localhost:1313 in the default browser

3. ‘Publish Blog’ Shortcut

What's going on here?

Changes directory into blog
Git add everything
Push it to main

Is there an app that makes confetti fall from the top of the screen? That’s the missing piece of this shortcut.

Video Demo

To see this all in action, here’s a video of me creating, writing, and publishing this exact post that you’re reading!

A Better Goal Than Sinless Perfection

Sun, 22 Oct 2023 13:46:13 -0700

Any two people in a close relationship are bound to eventually hurt each other. To most of us, it is no surprise when this happens. It’s simply accepted as the cost of growing close.

Even though it feels terrible to be hurt, it would be a pointless endeavor to define success in the relationship as perfectly avoiding ever hurting the other’s feelings.

Instead, I would say success is using the conflict and the wounds to grow into a bigger, deeper person and to strengthen the relationship by repairing the tears. The cycle of wounding and healing results in strength and resilience. It’s true in relationships, our bodies, our minds, and our natural world.

However, with this knowledge and a desire for optimal efficiency, I might attempt a shortcut to growth by intentionally inflicting the wounds. This will not work. It does not pass the any common sense check. Instead, I wait. The wounds and the hurt will inevitably come. They are always painful but they are also expected.

This is a wonderful way for me think about sin and God. The goal is not to perfectly avoid sinning. It is not a rare, shameful, embarrassing thing and it is not surprising when it happens. It’s painful, but expected. And when it occurs, the perfect forgiveness of God draws me into new depths of being. I use the sin and the forgiveness, the wound and the repair to humbly grow into the best versions of myself. I learn to forgive myself and everyone else from God’s example.

Therefore, let me change the goal from being perfectly sinless to becoming a deep, humble, forgiving human. Let me use my inevitable sin and God’s complete forgiveness to get there.

Progress, not perfection.

I Have Enough

Tue, 17 Oct 2023 09:28:23 -0700

I have enough food in my kitchen.

I have enough water to drink.

I have enough clothes to wear.

I have enough things in my house.

I have enough skill to work.

I have enough ideas to think.

I have enough people that love me.

I have enough people to love.

I have enough people to talk to.

I have enough people to laugh with.

I have enough time to relax.

I have enough life to experience.

I have enough.

Enough.

A quote from my from my pastor last week at church has been rolling around in my head all this week.

“Money is a useful tool for moving things around, so that everyone can have what they need.”

It made me think of “everything I need.” Truth is, I have too many things. I don’t want more things around me. Yet, I always wish I had more money. For what? I was then inspired to think of all the ways I have enough and write it up in a poem.

What a liberating thing to realize.

Company Culture & Church Community

Thu, 12 Oct 2023 11:06:12 -0700

This is a great podcast episode about company culture. The gist is, it doesn’t matter what people say or write about what the culture is. It’s what people are actually doing that matters. In fact, it may be even worse if what is said about the culture doesn’t match what people are actually doing.

There was one sound-bite that stood out to me from DHH at minute 7:15.

The more companies are eager to talk, talk, talk, about culture, culture, culture all the time, the more suspicious I am that there is a bunch of bullshit hidden under the carpet. … If you are obsessed with talking about culture, writing it down, it’s probably because you’re trying to cover something up.

Then it hit me. This is exactly how I feel when churches talk, talk, talk about “community”. In fact, if you listen to the beginning of this podcast and replace every time they say “company” with “church” and “culture” with “community”, it would be spot on.

There is a lesson here for us. If churches spend less time talking about community and more time simply doing things together, an authentic community will form naturally. And the actions of the leaders in the church, much more than the words, will be the blueprint for the rest of the congregation.

Let It Flow

Mon, 02 Oct 2023 12:02:50 -0700

I was just in the gym and as I lifted a weight I thought of the energy flowing out of me to lift it. I thought, it’s good for me to get this energy out. It feels good and my body is healthier when I send the energy out into the weight.

Then I exhaled. That air was also flowing out of me. It was good for it to go out of me. If I held it in, I would be poisoned. It needed to leave for me to live.

Then I thought about my work. I have these words, ideas, and products that cry out for extraction.

And money. What is money if it doesn’t leave me? It’s nothing. Useless paper.

Then there is my love. It too must leave. Out of me and into others.

Of course, there is time. It’s always leaving me. Coming and going. Moving. Flowing. Starting and ending and starting forever.

And music, and sports, and art, and food, and relationships, and kids, and feelings, and God. They all must flow in and flow out.

It seems that, to achieve fulfillment, everything must come out of me. To hold on to anything is to poison myself. The whole gift of being that was given at my conception must flow out from my soul and into Life.

It’s for my joy to fully exhale all that God breaths into me. Let it flow.

How to Pipe a NodeJS Readable Stream into a Child Process

Fri, 22 Sep 2023 10:00:27 -0700

I love pipes. Anytime I can pipe something somewhere, it seems that order has claimed a victory over chaos. In fact, there is pipe-related photo of me at the end of this article for your viewing pleasure.

The other day I was working in NodeJS and wanted to pipe a readable stream to a spawned child process.

I wanted something that could do this.

const process = createProcess(args);
const zq = createTransformStream(process);
const data = input.pipe(zq); // <-- Very cool

await client.load(data);

The child process needed to be a wrapped in a transform stream that would feed data to stdin and pass on data from stdout.

Spawn a Child Process

First, I spawned my process. NodeJS provides the spawn function to fire up an executable on your file system. The return value is a ChildProcess object.

function createProcess(args) {
  // Massage your args for the binary you're using.
  return spawn(bin, spawnargs);
}

Wrap the Child Process in a Transform Stream

Now we need to wrap that process in a transform stream so that we can pipe, pipe, pipe.

The steps:

Receive a chunk of data as an argument in the transform function.
Write that chunk to the child’s stdin .
Receive data coming from the child’s stdout .
Push that data into the transform stream.
Handle errors and clean up.

Here is the code.

function createTransformStream(child) {
  const stream = new Stream.Transform({
    transform(chunk, encoding, callback) {
      if (child.stdin.write(chunk, encoding)) {
        process.nextTick(callback);
      } else {
        child.stdin.once("drain", callback);
      }
    },

    flush(callback) {
      child.stdin.end();
      if (child.stdout.destroyed) callback();
      else child.stdout.on("close", () => callback());
    },
  });

  child.stdin.on("error", (e) => {
    if (e.code === "EPIPE") {
      // finished before reading the file finished (i.e. head)
      stream.emit("end");
    } else {
      stream.destroy(e);
    }
  });

  child.stdout
    .on("data", (data) => stream.push(data))
    .on("error", (e) => stream.destroy(e));

  child.stderr
    .on("data", (data) => stream.destroy(new Error(data.toString())))
    .on("error", (e) => stream.destroy(e));

  return stream;
}

Before we go into detail about what this code does, let’s discuss a very confusing topic for me, NodeJS streams.

Understanding NodeJS Readables

A readable is like a file. Call readable.read() to get the first chunk of data from the file.

const chunk = readable.read();

But if I am creating my own readable, it starts off empty. There is no data to read. To add some, use the readable.push() method.

readable.push("my-chunk-of-data");

This was confusing to me, because I am essentially “writing” data into the readable. But don’t say it like that, because the write() method name is already taken as we’ll see next.

Understanding NodeJS Writables

A writable is a destination for data to land. The writable thing takes the data I give it with writable.write() and does something with it. To indicate that I have written all the data I have to it, I call writable.end().

writable.write("first chunk");
writable.write("second chunk");
writable.write("ok, i'm done");
writable.end();

Understanding NodeJS Duplex Streams

To make everything super confusing, some objects can be both readable and writable. This means I can call .push(), .read(), .write(), and .end() on these things.

A special type of duplex stream is called the transform stream. It provides a shorthand way of reading from a source and writing to a destination. That’s what I used in the code above.

Detailed Code Breakdown

First we create the transform stream which will be the return value. We implement two methods in the constructor, transform() and flush(). The first is called when a chunk of data is read from a source, the second is called when there’s no more data to read.

The Transform Function

transform(chunk, encoding, callback) {
  if (child.stdin.write(chunk, encoding)) {
		process.nextTick(callback);
  } else {
		child.stdin.once('drain', callback);
  }
}

The transform function has the arguments chunk, encoding, and callback. The chunk is the bit of data that was just read and the callback is supposed to be called after I’ve processed it.

I pass that bit of data to my child process by writing to the process stdin. If stdin.write() returns true, it’s ready to accept more data so I call the callback on the next tick. If it returns false, it wants me to wait for the "drain" event before continuing, so we call the callback once that event is fired. This is called “respecting back-pressure.” Respect.

The Flush Function

flush(callback) {
  child.stdin.end();
  if (child.stdout.destroyed) callback();
  else child.stdout.on('close', () => callback());
}

The flush function is called when the stream has finished reading the source. It has one callback argument that should be called when I’ve cleaned everything up. In the body, I tell the child process’ stdin that I will no longer write any more data. Then I wait for the child process’ stdout to close before calling the callback.

Listening to stdout

child.stdout
  .on("data", (data) => stream.push(data))
  .on("error", (e) => stream.destroy(e));

This is where I “push” the data that comes out of my child process into the transform stream. If there’s an error, I call destroy and pass in the error.

Listening to stderr

child.stderr
  .on("data", (data) => stream.destroy(new Error(data.toString())))
  .on("error", (e) => stream.destroy(e));

This is some error handling. In my case, if anything gets pushed into stderr, I consider it an error and destroy the transform stream providing the appropriate error text.

Listening to stdin

child.stdin.on("error", (e) => {
  if (e.code === "EPIPE") {
    // the process finished before reading the file finished
    stream.emit("end");
  } else {
    stream.destroy(e);
  }
});

More error handling. Sometimes the child process would finish before I had given it all of the file. (The case where I only want the first 5 lines of a long file.) I write to stdin, but it’s closed up and emits the error code "EPIPE". I handle that by emitting the "end" event on the transform stream. This was the only way I could get it to work. I tried calling .end() but that didn’t cut it. I had to emit the event manually.

If the error code is anything else, I destroy the stream like above.

article.end()

That’s is how I wrapped a NodeJS ChildProcess with a Stream.Transform object so that I can pipe data to and from it. I hope this saves you some time so that you can get back to your pipes.

Here’s me with my pipes in 2015.

Waiting for a Comet

Wed, 20 Sep 2023 09:53:06 -0700

Comets are constantly falling.

We don’t know when.

But if we’re open, our eyes are open,

The comment will appear.

It is not me.

And it will change everything.

If we’d only wait for it to appear.

This poem was written on a backpacking trip through the Wind River Range in Wyoming. I slept under the stars. A meteor broke into pieces in the middle of the night and it seemed I was the only one in the audience. Later, the moon rose over the mountains. As I lied under the terrifying vastness of the space above me, I was moved to mutter, “I surrender to you God.” Then for some reason I thought, “I have children. Vanessa carried them for us.”

A Battle of Wit

Sat, 16 Sep 2023 17:44:44 -0700

Swords drawn, Draw blood, Blood in the water

Recover, Respond, Respect

Cross the line, Cut too deep, Feel the heat

Reach out a hand, Pull up to stand

Love wrapped up in a sheath

This was written on a backpacking trip where eight men hiked for four days in the wilderness. Whenever a group of friends are together, you’re bound to find this battlefield.

Partially Controlled Components: A Declarative Design Pattern in React

Tue, 01 Aug 2023 12:00:00 -0800

A common distinction in React is Controlled vs Uncontrolled components. But the real world is not so black and white…

To summarize:

Uncontrolled components manage changes within themselves, internally.
Controlled components have their changes managed for them, from the outside, externally.

I recently authored a tree view React component called react-arborist. After working on a complex component like this I felt the absence of a necessary concept in our React community.

✨ Partially Controlled Components ✨'

You’ve felt it too? Let’s get into this.

Gradually Controllable Complex Components

As a library author, I want the “Getting Started " experience to be dead simple.

<Tree initialData={myData} />

By default, the component takes care of everything internally: selection, drag-and-drop, and renaming. As it integrates into an app, users can take control of only the parts they need. Common needs are persisting the state, initializing the state, or changing the tree from elsewhere in the app.

Declarative vs Imperative Control

There are only two ways to control a component from the outside:

Attaching a Ref (imperative)
Providing Props (declarative)

Let’s look at some real world component libraries to showcase these two approaches.

Imperative Control in react-resizable-panes

First we will examine react-resizable-panes, a promising new React component library by Brian Vaughn. The Panel component is uncontrolled by default (win), and provides a ref handle to control it from the outside.

import {Panel} from "react-resizable-panels";


function MyApp() {
	const ref = useRef(null);

  const onClick = () => {
		ref.current?.collapse();
  };

  return (
    ...
    <Panel collapsible ref={ref}>
      ...
    </Panel>
    ...
    <button onClick={onClick}>Collapse</button>
	)
}

We can control the collapsible state from the outside by calling the collapse() method on the Panel’s imperative handle.

Declarative Control in Tanstack Table

In the React version of tanstack-table, the go-to component library for everything tabular, Tanner Linsley allows us to partially control the state of our table by passing arguments to the useReactTable hook.

His library only provides a hook and leaves rendering for us, but this is essentially passing props to a component. When the arguments to the hook change, React will re-render our table.

const table = useReactTable({
  data,
  columns,
  state: {
    columnVisibility, // visibility value
    columnOrder, // order value
  },
  onColumnVisibilityChange: setColumnVisibility, // visibility setter
  onColumnOrderChange: setColumnOrder, // order setter
});

Look at that partial control! I really think he’s onto something. Since the component/hook does so many things, the state is divided into logical slices. Each slice can either be controlled or uncontrolled depending on the presence of an on[SliceName]Change handler. I love this pattern. However, to me, its undesirable that the value and change handler are not co-located. It is also a bit verbose. But it is declarative and much more “React”.

API Inspiration from React Input Elements

Let’s get back to our roots. The basic React <input /> element is where the concept of controlled/uncontrolled components was born. The React authors decided on this API:

by default the input is uncontrolled
by adding props, you opt-in to control
The relevant prop names are value, defaultValue, and onChange

1. Uncontrolled

<input />

2. Uncontrolled with an initial value

<input defaultValue="hello" />

3. Controlled

<input value={value} onChange={(e) => setValue(e.currentTarget.value)} />

A Declarative Pattern for Partially Controlled Components

Let’s expand on all the patterns we saw above and design a new API for partially controlled components. We’ll use react-arborist as an example use case.

Use Case 1: A user wants control over just the tree’s selection state.

const [selection, setSelection] = useState(initial());

return (
  <Tree
    selectionState={{
      value: selection,
      onChange: (state) => setSelection(state),
    }}
  />
);

Use Case 2: They want to control the editing state as well.

<Tree
  selectionState={{
    value: selection,
    onChange: (state) => setSelection(state)
  }}
  editingState={{
    value: editing
    onChange: (state) => setEditing(state)
  }}
/>

Use Case 3: Provide only an initial state for which nodes are expanded/collapsed?

<Tree
  selectionState={{
    value: selection,
    onChange: (state) => setSelection(state)
  }}
  editingState={{
    value: editing
    onChange: (state) => setEditing(state)
  }}
  expandedState={{
    defaultValue: expanded
  }}
/>

Use Case 4: Control all the state in a Redux store.

const treeState = useSelector(MyApp.selectTreeState);
const dispatch = useDispatch();

return (
  <Tree
    rootState={{
      value: treeState,
      onChange: (state) => dispatch(MyApp.setTreeState(state),
    }}
  />
);

Each logical group of state has its own prop object for users to control. The presence of this prop indicates to the component that its state slice will be managed externally.

I like this pattern for a few reasons.

It’s declarative
It’s familiar
Values and handlers are co-located
It’s uncontrolled by default
It’s easy to gradually take control

What’s Next?

What do you think of this design? Depending on your feedback, I may make this the API in version 4 of react-arborist.

Curious how one would implement an API like this? Keep a lookout for part two!

Others May Know More

Mon, 10 Jul 2023 04:13:00 -0700

A child knows nothing about itself. Its body is a mystery, its ideas, its dreams, its feelings. The child relies on caregivers to teach her everything. The caregivers know more about who she is than she does.

Does this ever stop? Do any of us ever fully know who we are? No matter what age I am, will there be others who know more about me than I do?

Maybe not me as James, but me as human being. Me as human spirit.

I cannot assume that I know everything about what it means to be human and I must assume that others or God or scriptures can know more.

What a humbling thought: Others may know more about me than I do.

It’s Good to Wonder About Mysteries

Thu, 29 Jun 2023 10:15:00 -0700

I was talking with a group of friends trying to come up with possible answers to unanswerable questions like:

What happens when we die?
How does the way we live affect things after our death?

We can never know the answers to these questions with certainty. They are fundamentally unknowable. So what is the point of spending so much energy on something you’ll never be able to fully answer?

A friend provided a profound response. While we can’t be certain of any particular theory, the conclusions we make will change the way we our lives right now. For example, if you believe our choices today affect the next life, you’ll behave differently than if you didn’t.

It seems as if we first need to decide what kind of person we want to become; how we hope to live. Then as we evaluate possible answers to these unknowable questions, we judge them by how much they enable us to become that person.

This thought is backwards when compared to the primary pursuit of truth common in religious circles. But it might be more true than we realize.

Let’s make this personal. Today, I want to become a more generous, confident, humble, strong, meek, realistic, hopeful, creative, life-enhancing human.

If a tenant of my worldview doesn’t help me get closer to those goals, why keep believing it? Because it’s true? If it’s one of these unanswerable questions, how can we ever know with certainty?

React Hook for Avoiding Flash of Empty UI While Data Transitions

Tue, 27 Jun 2023 11:55:19 -0700

I’m working on a React app that has frequent data transitions. Each time a user submits a query, the state is reset as we wait for a response from the server. The new data can arrive quickly or slowly. If it arrives quickly, a flash of empty UI will render as the data is transitioning from the previous results to the current results.

Before

Notice the flash of emptiness in the histogram.

Even though it’s not that big of a deal, I want to avoid that. Let’s write a short hook that will do this for us called useDataTransition.

At a high level, we need to prevent child React components from seeing the new data in their props until the transition is finished (we have all the new data) or a timeout expires (the new data is taking a while to arrive).

Return Value

Let’s work backward starting with the return value. The hook should return the real data or a cache of the previous data. If we are “in transition” and the timeout has not expired, return the cached data, otherwise the real data.

if (inTransition && !timeExpired) {
  return cache;
} else {
  return real;
}

Cache

Let’s figure out when to cache. We must save the data before the transition starts. Let’s put this in an effect that runs when inTransition changes or when the data changes. Only cache if isTransition is false.

const cache = useRef(data);

useEffect(() => {
  if (!inTransition) cache.current = data;
}, [inTransition, data]);

This always caches the data while the we are not transitioning. Since we don’t need to re-render when the cache changes, we can store it in a ref.

Timer

Let’s set that timeExpired variable. Whenever isTransitioning changes to true, start a timer. When that timer finishes, update the timeExpired state.

const [timeExpired, setTimeExpired] = useState(false);

useEffect(() => {
  let id;
  if (inTransition) {
    id = setTimeout(() => setTimeExpired(true), dur);
  } else {
    setTimeExpired(false);
  }
  return () => clearTimeout(id);
}, [inTransition, dur]);

We do want to re-render when timeExpired changes so we useState.

The Finished Code

Now to bring it all together with TypeScript types.

export function useDataTransition<T>(
  real: T,
  inTransition: boolean,
  timeout: number,
) {
  const [timeExpired, setTimeExpired] = useState(false);
  const cache = useRef(real);

  useEffect(() => {
    if (!inTransition) cache.current = real;
  }, [inTransition, real]);

  useEffect(() => {
    let id: number;
    if (inTransition) {
      id = setTimeout(() => setTimeExpired(true), timeout);
    } else {
      setTimeExpired(false);
    }
    return () => clearTimeout(id);
  }, [inTransition, timeout]);

  if (inTransition && !timeExpired) return cache.current;
  else return real;
}

We can use it like this:

function HistogramContainer() {
  const isFetching = useSelector(getIsFetching);
  const noDataYet = useSelector(getIsEmpty);
  const realData = useSelector(getRealData);

  const data = useDataTransition(realData, isFetching && noDataYet, 300);

  return <Histogram data={data} />;
}

In the example above, we consider the data transitioning if we are in the middle of fetching and if we have not yet received any results. If either of those change, the transition will be done and the real data displayed. If they remain true for longer than 300ms, the real data will again be displayed which probably means some loading UI.

After

Post Script

At first, I put this logic in “thunks”; outside of React components. But because it was a UI issue, not part of business logic, it felt right to move it to the rendering layer.

Also, my first implementation wasn’t working and I was struggling to figure out why. As a means to help me think clearly, I started writing this post and ended up with something that worked. Win, win!

I wrote this hook while working on the Zui app by Brim Data. Check us out if you ever need to work with heterogeneous datasets.

Confronting a Man at the Playground

Wed, 21 Jun 2023 12:00:00 -0700

While at a playground this weekend a man talked to my 3-year-old son in a way that upset me and I had to do something about it. I thought carefully about what was true for me, then walked over and told him.

Earlier that evening I observed this man enthusiastically playing with an 18-month-old boy we’ll call JJ. He wasn’t the dad, maybe a friend or an uncle. He took little JJ down the big slide multiple times. At one point the boy’s dad walked over and stood at the bottom of the slide. The man decided JJ should go down on his own. “3-2-1 GO!”, but JJ shook his head and asked for one of them to go down with him. After failing to convince JJ it would be fun, the man pretended to go down with him and at the last minute, sent the boy down solo.

I’ve been there. I’m a former “slide-pusher” myself. It may even be motivated by good intention. We want to push our children to face their fears and build courage. But at a certain point, a child is simply not able or willing to try something. Respecting this is also good. It gives them a feeling of autonomy and control over their own life.

I’ve given up on slide pushing and now wait (not easy) until the kid wants to go down. My son was formerly hesitant about the big slide, but now rips down it like it’s going out of style. He was ready when he was ready. He probably feels proud of himself and doesn’t have to worry about pleasing me on this front. That is good.

Now for the incident. It’s 5pm and my son is tired. He’s playing on this thing that spins you around. It’s small. Two kids can spin on it, but kids often spin one at a time. JJ walks over to the spinner and wants a turn. The man is walking away to sit down with his friends when he notices JJ and my son about to get into some classic toddler conflict.

He asks my son, “Will you share the spinner with JJ?”

My son shakes his head.

“C’mon, both of you can do it. It’ll be so fun!”

My son refuses again. “No.”

Then the dude says, “You have to share!” and when my son still refuses he starts loudly repeating his message, “Share! SHARE!”.

My son breaks down crying and runs over to me.

My wife was sitting on the bench near the friends and overheard him say to them as he sat down, “That kid’s a jerk.”

If you have some paternal energy and feel like you’re about to flip your shit, so was I.

I had just finished reading the chapter in Jordan Peterson’s excellent book, 12 Rules of Life, called “Tell the Truth (or at least don’t lie).” He stresses the importance of telling the truth to yourself and the world. He gave some examples of times when it was uncomfortable, but had great benefits. When you decide to say something honest, his advice is to be concise, direct, and clear. Go slow and choose the words carefully.

I was upset by the way the man spoke to my son. That was it. That was my truth.

As a big fan of non-violent communication, I tried to perceive what the man was feeling in that moment. He was probably frustrated, because toddlers are frustrating, especially when trying to teach them to share. That was also true.

As we were leaving the park, I decided it was time to speak. I walked over and sat next to him. He was in front of four other adults so my heart was pumping.

I said, “Hey brother, I know that toddlers can be frustrating, but I was upset by the way you spoke to my son by the spinner thing.”

He responded, “Sorry about that. I was just trying to get him to share with our little JJ. Sorry about that.”

I said thanks and we left.

I am proud of myself. It was nerve-racking to do, but I had to do something and telling the truth seemed like a good option. Maybe he will learn something from that experience, but it was mostly for me. I want to practice that kind of thing. Maybe there’ll be a time where it’s harder to speak up, but even more necessary.

Let me add this. The next day I was filled with anxiety. I kept wondering if I would run into that dude on the street. I was surprised by this. As I reflected on it, it seemed similar to my experiences in jr. high when other kids treated me poorly. There was a terrible feeling of powerlessness I felt then. If someone picked on me, I had no recourse. I wasn’t the fighting type, being a tattle-tail wasn’t cool, and I couldn’t chose not to be around them. Somehow this experience brought me back to those days. Who knows…

It did suck having to deal with all of this. It was an emotionally rigorous day and a half. But I got to practice telling the truth. Maybe next time it’ll be easier.

Persisting the Human Experience

Mon, 19 Jun 2023 00:00:00 +0000

Experiences compress into memories.
Memories compress into feelings.
Feelings compress into instincts.
Instincts compress into the unconscious.
The unconscious compresses into the collective human unconscious.

There’s an analogy in software. When you make a song in music software, you start with big uncompressed files. All the sound layers are stored separately. When the song is finished, it gets flattened into one layer resulting in the same sounds, but a smaller file size. We can then compress that file even more with general compression algorithms. Finally, it can be uploaded to the cloud and streamed to millions of others without having to take up any of their disk space.

Maybe that’s how the immesurable data from billions of experiences get mysteriously persisted into our human nature.

Joshua Tree Trip

Wed, 31 May 2023 00:00:00 +0000

We took a trip down to Joshua Tree this weekend for a cousin’s wedding. For the first time, I could appreciate the gifts of a desert climate. There is much less visual input stimulating the brain. The plants don’t grow dense or tall so you can see everything around you. It’s calming not to wonder what’s behind the trees. And the heat makes you want to just sleep or sit in the pool or not do anything. If you need to rest or think, the dessert is a great place to do it.

We drove to the Hi-View Trailhead outside of Yucca Valley and walked about 100 feet down the path from the parking lot before turning back. Short, sweet and hot. But long enough to take some great photos of the Joshua Trees.

Later that day we left the kids with Papa and headed to the wedding. Vanessa and Sarah put the final touches on the wedding cake which traveled all the way from San Francisco.

The next day we stopped by Hemet, CA to visit grandparents. They fired up the 1940s era bulldozer that was in full working order.

My favorite picture of the weekend. There is symbolism here that I can’t fully put words to. The great-grandmother with her cane, leaning the on the powerful machine of the past, looking down at the toddlers who carry the future. Just beautiful.

Jet Fuel

Fri, 05 May 2023 16:10:00 -0700

We build an engine for it.
It propels us to new heights.
It explodes.
It destroys everything around it.
It takes us to heavenly places.
It burns.
It brings us to life.
It transcends the earth.
Handle with care.
Enjoy its power.
Summon it for good.
Rest in the potential within.
Sacred energy.
For purpose.
For pleasure.
For life.

5 Tricks for Taking Great Photos

Thu, 04 May 2023 12:39:05 -0700

I’ve owned a full frame camera for over 5 years. I’ve acquired 3 lenses and snapped many thousands of photos. And yet, last week I discovered these five tricks and was shocked by my ignorance of them.

While watching a lesson on incorporating images in website designs, my instructor presented these five qualities of great images.

The Five Qualities of Great Images:

There should be one obvious subject in an image.
The subject must be well lit and in focus.
The center of the subject must be framed on a horizontal third or a vertical third or both.
There needs to be a flow of energy in the photo for your eyes to follow, ideally towards the subject.
The background must not be distracting.

Let me break these down with my own experience.

1. A Single Subject

I take pictures of landscapes and I often make the mistake of having no clear subject. Pick a cool tree or one of the buildings or the giant rock. It can be anything, but you must choose it. If you’re photographing a group of things, make a one or a few of them the clear protagonists of the image.

2. Well Lit and In Focus

This seems obvious, but I have taken otherwise great pictures where the people’s faces are a complete shadow. If I had only moved them a little into the light.

3. Rule of Thirds

I learned part of this in film school, but now it’s hitting home. Divide the frame into thirds vertically and horizontally. Place your subject where those lines intersect. It looks pro.

4. Find the Movement

This was brand new to me but so true! There needs to be a flow of energy through the photo. A path for eyes to follow. Ideally, the energy flows to the subject. For example, lines on the horizon, trunks of trees, the stem of a flower, or a long shadow. Lines. Paths. Flow. Motion. It’s a subtle thing. When photos have this “movement” in them, they just feel good, but most of us can’t say why. This is why!

5. Clean Background

The subject should stand out from the background. Anything busy or random in the background is going to take away from that sweet shot.

So next time you snap a pic:

Pick a subject
Light it up
Find the flow
Simplify the background
Frame it in thirds
Snap

These came from Erik Kennedy in his online course Learn UI Design. Thanks Erik!

It’s a Gift for Me to Be Angry

Mon, 03 Apr 2023 14:43:39 -0700

When I’m angry I stop needing everyone to like me. I don’t care if they approve of what I do. My face doesn’t hurt from smiling all the time. When people talk to me, I give myself a moment to evaluate if I agree or not before automatically nodding in agreement. It’s liberating.

Some people on the other end of the spectrum are angry all the time. I’m on the overly agreeable side. I wish I could be 10% more angry to balance out my people pleasing defaults.

I was just a retreat center near Petaluma, CA where a speaker spoke on balance. He said we all have the full spectrum of characteristics within us: anger, joy, selfishness, caring, pride, humility, etc. We get into trouble when one of them tries to be the only player on the field while all the others are benched. That’s when we make errors in our behavior. When this happens, we can pause and pray for the right counter-characteristics to arise within us to balance our response.

Selfishness <> Caring

Anger <> Peace

Rigid <> Flexible

Permissive <> Controlling

Every single character trait is helpful in the right circumstance and destructive in the wrong circumstance.

How cool. There’s nothing about me that I need to “remove”. It all belongs. I just need help learning the dosage required for the situation.

13 Decisions to Make Before Publishing JavaScript to NPM

Thu, 30 Mar 2023 09:00:00 -0700

This post is half rant, half guide. Each of these 13 questions reveals tradeoffs that take time and mental energy to research. In case you don’t already have enough to decide today, here’s what you must consider when creating and publishing a new JavaScript package.

1. Do you want to write it in TypeScript?

If so, you’ll need to compile it before publishing. Bookmark the the tsconfig.json reference.

2. Do you want to compile using tsc, swc, or esbuild?

By default, TypeScript uses tsc to type check and transpile your source .ts files into regular JavaScript. It’s slower because it’s written in JavaScript. Other tools like swc (Rust) or esbuild (Go) transpile much faster, but do not type check. Nobody likes waiting around for a build, but maybe you’d rather have one tool.

3. Do you want it to run in Node?

Now you need to decide your module format.

4. Do you want to output your package as ESM or CJS?

CommonJS modules (CJS) was the original way to include code from another file in Node. ECMAScript modules (ESM) is now the standard way to include JS code and Node just recently implemented support for it. The community wants us to move to pure ESM, but many things are CJS and they don’t exactly interop seamlessly.

5. Are any of your dependencies pure ESM?

Using them in your CJS project is not going to work out of the box.

6. Are any of your dependents CJS?

They won’t be able to use your pure ESM library out of the box.

7. Since Node can run ESM and CJS, do you want to support both?

Then you need to avoid the Dual Package Hazard when both versions of your library might end up loaded at the same time.

8. Do you want it to run in browsers?

Since all browsers can run ESM, you’ll probably choose that as your module format, as opposed to AMD or an IIFE.

9. Will you bundle all your code into a single JS file?

This will make it download faster. You probably want it minified too.

10. Will you inline your dependencies in the bundle?

This will make it download slower, but it will be more portable.

11. Will you use a CDN to get it into the browser?

You’ll need to know about services like jsDelivr or Skypack which automatically serve packages in the npm registry. Some services let you leave the npm dependencies out of the bundle while their CDNs serve them for you. Otherwise your users will need to download the bundle like the old days or npm install it and link to it in node_modules from their HTML page. ES modules must have an explicit path to a real file, no index.js or package.json magic. Or you can use import maps.

12. Do you want to bundle it for node?

Esbuild talks about doing this in their docs. It can be faster to read from the disc.

13. Where will you specify your entry point in package.json?

The top choices for your entry point are: “exports”, “main”, and “browser”. Each runtime and build tool will use this information to run or compile your code.

What. A. Nightmare.

To simply share some JavaScript you’ve got to consider JS runtimes, module formats, and build tools with no one true way. Was it easier when cross-browser compatibility was the big headache?

My Answers

I had to spend the time making these decisions for my own package @brimdata/zed-js. A JavaScript client package for the Zed data platform. Here’s what I came up with.

I will write TypeScript.

I will use nx to generate the project because their developers have many sane decisions for me. Thank you!

I will build a sole CJS version for Node since I plan to consume this package in an Electron app and Electron doesn’t yet support ESM. This was a hard decision because respected community members are pushing valiantly for pure ESM packages. I agree philosophically 100%. If I wasn’t the one consuming this package, I’d go pure ESM. However, I don’t feel like hacking around Electron to get my own code to run, so I’m compromising on my values for today.

I will use tsc to build the CJS version to avoid another tool. If my project were huge, I’d use to swc to build and tsc to lint.

I will leave the CJS version unbundled because…what happens in node_modules, stays in node_modules.

I will use the “exports” field in package.json to point to the Node entry point. It has some advantages over “main” and will make it easier to switch to pure ESM in the future.

I will use esbuild to bundle an ESM version for the web.

I will inline my dependencies because I don’t have many and they are not big. If they were big, I’d consider using a CDN like Skypack.

I will use the “browser” field in package.json to point to the bundle.

Hope For Brighter Days

My introduction to programming came from Ruby on Rails. It championed the principle “convention over configuration” when the back-end landscape was overgrown with XML config files for Java VMs.

Today we are in having a “configuration-heavy” moment in the front-end world, but I have hope that good conventions will emerge. Then we can get back to doing the real work.

Netflix Does Not Have My Best Interest

Thu, 23 Mar 2023 18:59:18 -0700

I watch Netflix because I’m too tired to do anything else. The kids are finally sleeping and I’m spent.

It’s meant to be a quick escape from life before I do what I really need to do which is sleep.

But then Netflix launches the attack!

They release every episode to a show all at once.
They give me 3 seconds to stop the next show from automatically playing.

I’m too tired to get up and stop the next episode! I’m watching because I’m too tired to do anything else. Theres not sufficient willpower to instantly stop the next show once the current one finishes resulting in me watching TV way later than I want to and becoming even more tired the next day. A vicious cycle.

What if Netflix gave me 60 seconds to savor the last scene of that episode, see some credits, listen to some music, and decide if I want to make a good choice for my health or not.

What if I could set my computer to force shut down after a given time frame. Set that up before the show starts. And it would need to really force close everything. If it gave me a popup to confirm I’d probably dismiss it. I can’t trust myself past 9pm.

Netflix, your defaults are not looking out for me.

Embedded Divinity

Wed, 22 Mar 2023 10:52:26 -0700

What if we didn’t think of God as infinite.

What if God poured itself into this particular universe. What if He’s completely bound to this one cosmos. It’s life is it’s life. Our “being” is only because the Source is fully giving itself to the existence.

If we think this way, God is embedded into the material around us. He’s not a distant cosmic scientist creating life in his lab, doing experiments, always able to try again, no one instance too important.

What if this is the only finite instance! God has gone all in, nothing saved for a backup plan, fully committed.

Thinking like this helps me want to love God and my existence. Maybe God risked everything for this one universe. There is no Plan B. If things go wrong, there is no do-over; only repair, forgiveness, recovery, and mercy.

Adults Don't Share

Fri, 23 Dec 2022 09:00:00 -0700

All the time at the playground I hear, “good sharing!” and “no no Jackson, you need to share”.

We parents think it is some critical skill that children need to learn. A skill that must be forcefully developed in order to be a contributing member of society.

Then one day I thought: We adults never share! How weird would it be to ask for someone’s phone to play a game.

- “Do you have any apps on your phone I could play with for a while”

- “Yeah, I’d love to share my phone with you. Have fun! I’ll set a timer so we know when it’s my turn again.”

- “While you wait, here are the keys to my car. It’s the Audi A5 over there.”

What good sharing!

It’s probably not harming kids to help them understand what sharing is, but I certainly don’t practice what I preach. I wonder why we care so much about sharing at the toddler stages.

TypeScript Classes Are Giving Me Carpal Tunnel

Wed, 21 Dec 2022 10:37:00 -0700

Whenever a class needs a few arguments in TypeScript, I cringe because I know I’m going to need to perform a ceremony to make it happy.

Let’s start with the simple case. If a Class needs two arguments, I’d do this:

class Point {
  x: number;
  y: number;
  constructor(x: number, y: number) {
    this.x = x;
    this.y = y;
  }
}

There is some repetition to get the types and initialization right. Fortunately, the TypeScript authors created a shorthand syntax to calm this down.

class Point {
  constructor(
    public x: number,
    public y: number,
  ) {}
}

Very nice. By providing a typescript keyword public, private, protected, or readonly before the argument name, the class will make it a member variable and initialize it with the argument for you!

This is amazing but…

new GiantObjectWithManyArgs(field, table, null, null, undefined, "init", () =>
  console.log("callback"),
);

…it breaks down when you have more than 1 or 2 arguments. To fix this, a common pattern is to pass a single object argument.

new GiantObjectWithManyArgs({
  field: myField,
  table: myTable,
  parent: null,
  children: null,
  status: "init",
  onComplete: () => console.log("callback"),
});

This is so much better than positional arguments.

They have names!
The order doesn’t matter!
The optional args can be omitted!

In JavaScript, this would be a piece of cake to setup in the constructor.

class GiantObjectWithManyArgs {
  constructor(args) {
    Object.assign(this, args);
  }
}

Everything in the args object becomes a member of the class. But in TypeScript, the amount of code needed to make this work explodes!

This is the least verbose way I know to write it.

type Args = {
  field: zed.Field;
  table: zed.Table;
  parent: GiantObject | null;
  children: GiantObject[] | null;
  status: "init" | "complete";
  onComplete?: () => void;
};

class GiantObject {
  field: Args["field"];
  table: Args["table"];
  parent: Args["parent"];
  children: Args["children"];
  status: Args["status"];
  onComplete: Args["onComplete"];

  constructor(args: Args) {
    this.field = args.field;
    this.table = args.table;
    this.parent = args.parent;
    this.children = args.children;
    this.status = args.status;
    this.onComplete = args.onComplete;
  }
}

I’ve got blisters on my fingers!

TypeScript authors…you saw the the need for positional argument shorthand. I’m sure you see the need for object argument shorthand as well.

I’m no language designer so here is my blind stab in the dark for syntax ideas.

type Args = {
  field: zed.Field
  table: zed.Table
  parent: GiantObject | null
  children: GiantObject[] | null
  status: "init" | "complete"
  onComplete?: () => void
}

// Not Real TypeScript
class GiantObject {
  constructor(public assign args: Args) {}

  // Aww, it's probably hard to specifiy
  // some as a private and others as public...
}
// Or mabye
class GiantObjects assigns Args {
  constructor(args: Args) {
    for (let key in args) this[key] = args[key]
  }
}

Workaround

My workaround for this is to assign the whole object to a member variable called “args”.

type Args = {
  // ...
};

class GiantObject {
  args: Args;

  constructor(private args: Args) {}
}

Then I have to make getters for each of the pieces I need. It’s not a bad way to go, but I’m coding around something because the tooling makes the preferred style difficult.

Object arguments are so much better than positional arguments, but the boilerplate in TypeScript compared to plain JavaScript makes them almost not worth it.

Sharing Steps in Github Action Workflows

Mon, 13 Jun 2022 13:00:00 -0700

I’ve got an electron app that needs to be built on all three platforms. I’ve got three workflow files all with slightly differing steps. Is there way to share whats common? Yes. It’s called composite actions.

Update (Jan 4, 2024): There is another way to reuse workflows thats described in the reusing workflows section of the docs.

What is a Composite Action?

The name is not the most intuitive (why not “shared action”?), but it’s a group of steps that are intended to be “used” within a workflow file. This is GitHub’s solution for sharing steps between workflows. Here is an example of the simplest composite action.

name: "My Shared Steps"
runs:
  using: "composite" # <-- this is the important part
  steps:
    - run: echo "Hello, World"
      shell: bash

First, make a file like this and set the top-level runs: property to the string "composite".

Also, Action files are different from Workflow files. Once such difference is that your steps must specify a shell property if they use run: . That knowledge will save you from this error.

Where do I put this file?

It can go anywhere in your repo. Or in it’s own repo. But, I want mine in the .github/actions folder at the root of my repository. Something like:

.github/actions/my-shared-steps/action.yml

Notice that I needed to create a directory containing a file called action.yml. This is the required structure for an action. I tried naming the file something else and it didn’t like that.

Important: the action must be a directory containing an action.yml file.

How do I use it?

If you read that error above closely, you noticed an important catch. Before I could use this action, I had to first checkout the repo. That makes sense, since the file is…well…in the repo. Here’s how the steps of my workflow job look:

steps:
	- uses: actions/checkout@v3 # required first
	- uses: ./.github/actions/my-shared-steps

Since I am using an action that is in our repo, I specify the path to the file from the root of the repository starting with a ./ (that’s required). If your action is not in the repo, here are your options for using it.

Passing Data to the Action

More errors revealed that I couldn’t use the ${{ secrets }} variable in my composite action. I had to pass it data using the inputs: property in the action, and the with: property in the workflow. Here’s an example:

# .github/actions/build-win/action.yml

name: Build Windows
description: Specific steps to build for Windows
inputs:
  csc_key_password:
    required: true
  csc_link:
    required: true
  gh_token:
    required: true
runs:
  using: "composite"
  steps:
    - name: Build Signed Release
      shell: bash
      run: yarn electron-builder --win
      env:
        CSC_KEY_PASSWORD: ${{ inputs.csc_key_password }}
        CSC_LINK: ${{ inputs.csc_link }}
        GH_TOKEN: ${{ inputs.gh_token }}

And I used it like this:

# .github/workflows/win-release-candidate.yml

name: Brim Windows release candidate creation
on:
  pull_request:
jobs:
  build:
    runs-on: windows-2019
    steps:
      - uses: actions/checkout@v2
      - uses: ./.github/actions/setup-brim
      - uses: ./.github/actions/build-win # <--- Using the composite action here
        with:
          csc_key_password: ${{ secrets.WINDOWS_SIGNING_PASSPHRASE }}
          csc_link: ${{ secrets.WINDOWS_SIGNING_PFX_BASE64 }}
          gh_token: ${{ secrets.GITHUB_TOKEN }}

Can I publish it?

Yes. This article in the docs titled “Creating a composite action” shows how to make a compsite action in it’s own repo with inputs and outputs, then uses it in a workflow.

I’ve now DRY’d out my CI workflows with composite actions. One installs Go and Node then runs yarn install. Another publishes artifacts to our private Google Cloud bucket. It’s great.

Post Script

Debugging CI is a pain. You know. You edit a workflow file, you commit, you push, you open the browser, you wait, it fails, your YAML was not indented enough, repeat. It sucks. There has got to be a better way. To start, it would be great to at least validate my workflow file with some CLI tool before I push. Or a local VM I could test it in? If this exists already, someone please tell me.

Update (Jan 4, 2024): I have been informed there is a tool for this called act. I have not used it yet, but the repo has 46K stars so they must be doing something right.

How to useRef and forwardRef in React

Tue, 03 May 2022 00:00:00 -0700

What do I do when my component uses a ref internally but also needs to forward a ref from its parent? The short answer is merge the refs into a single ref function. If what that means is not immediatly obvious, you’re like me. Read on.

What is a ref?

Look at what get’s returned from useRef.

const ref = useRef();
console.log(ref);

/* prints */
{
  current: undefined;
}

This ref is an object with one property current that can be set to whatever you want.

What happens when I pass it to an HTML element?

<button ref={ref} />

For years I just thought this was magic, but today I grepped “ref” in my node_modules/react-dom folder and it’s not complicated. After react-dom creates the HTML button instance, it will attach the ref like so:

if (typeof ref === 'function') {
  	ref(instanceToUse)
  } else {
  	ref.current = instanceToUse
  }
}

The ref prop will only accept three things:

a function
a plain object with a single current property
null

This means these two lines result in the same thing.

<button ref={ref} />
<button ref={(instance) => ref.current = instance} />

What about forwardRef?

When in doubt, console.log it out.

const MyButton = forwardRef(function(props, ref) {
  console.log(ref)
  ...
})

What gets printed depends on the ref value given to the component. If you create that MyButton component without passing it a ref, you’ll see null printed to the console.

<MyButton />; // with no ref

/* prints */
null;

Now let’s try it with a ref from useRef.

const ref = useRef()
<MyButton ref={ref} />

/* prints */
{current: undefined}

Ok, this is starting to make sense. Whatever you pass as the ref prop to the MyButton component will be the same as second argument in the forwardRef function.

<MyButton ref={ref} />; // this ref is the same as...
forwardRef(function (props, ref) {}); // ...this ref

The name “forwardRef” is starting to make a lot of sense. Let’s test this out by passing a function as the ref property.

const func = (node) => console.log("Hi")
<MyButton ref={func} />

/* prints */
'(node) => console.log("Hi")'
/* the string representation of the function */

Merging Two Refs

So to deliver on the promise of this blog’s title, here’s how we can have useRef and forwardRef in the same function component.

const MyButton = forwardRef(function (props, forwardedRef) {
  const localRef = useRef();

  return (
    <button
      ref={(instance) => {
        // first we set the local ref
        localRef.current = instance;

        // then we handle the forwarded ref
        // it can be a function, an object, or null
        if (typeof forwardedRef === "function") {
          forwardedRef(instance);
        } else if (typeof forwardedRef === "object") {
          forwardedRef.current = instance;
        }
      }}
    />
  );
});

This uses a function to properly set both the local and the forwarded refs.

At this point, you probably can’t help yourself from writing this mergeRefs function.

function mergeRefs(...refs) {
  return (instance) => {
    refs.forEach((ref) => {
      if (typeof ref === "function") {
        ref(instance);
      } else if (ref != null) {
        ref.current = instance;
      }
    });
  };
}

To be used like this:

const MyButton = forwardRef(function (props, forwardedRef) {
  const localRef = useRef();

  return <button ref={mergeRefs(localRef, forwardedRef)} />;
});

Turns out, Greg Bergé has created a utility that does just this called react-merge-refs. That mergeRefs function above is almost copied strait from his code. Thanks Greg.

So that’s how you do it.