Materials

I’ve used Ripstop by the Roll in the past, and I still think they’re best general source for MYOG projects (wide selection, good pricing, although shipping isn’t great).

• 0.66 oz MEMBRANE 10 Taffeta Nylon: One of the lightest options, fully downproof, and a nice feeling
• 0.5 oz Noseeum Mesh: I cut 3.5" strips from this, as it’s lighter than the precut baffle tape
• Gutermann Tera 80 thread
• Grosgrain ribbon: 3/8" and 3/4" widths
• Low profile center push buckles
• 1/16" Shock Cord
• Anchorable Cordlock (glow-in-the-dark, so I can find them at night)
• 900 FP goose down (from Amazon)

I considered 0.56 oz nylon, but my research concluded the weight savings weren’t worth the durability decrease.

The goose down is my main risk on this project. It’s not treated to handle water and is from an unknown source, but is way cheaper than RSBR’s 850 DWR down. Since I’m currently in a drier climate, I’m taking a risk on moisture management. Although I think the supplier shorted me a bit on weight (I think the 1 lb includes the bag it’s shipped in), I’m reasonably happy with it.

Patterning

I mostly did my own patterning. Dubber Designs has a generator, but I wasn’t able to import it properly into Apple Numbers or Google Sheets. It did provide some good guidance on down calculations. Ripstop by the Roll has a one-pager, but I didn’t do a full taper like they do.

vanCapare, HollowCartographer, and durianbae were good sources of inspiration on Reddit.

My rough down calculations are in Google Sheets.

Some of my decisions were:

• Long enough to fully cover my head. I generally sleep with my head fully covered and didn’t want to construct a separate hood.
• Partial taper around the legs. I get some weight savings this way, and it accommodates my side-sleeping.
• Four sleeping pad straps spaced along the body.
• Fully closed footbox. This means I don’t have a cinch at the foot, and prevents slipping off the pad.

My final measurements:

• 50" width
• 78" height
• 34" long taper, down to 35" wide at the toes
• Baffles are 3" thick and approximately 5" wide (10 vertical baffles, 6 horizontal baffles, and 2 in the footbox)
• ~10% overstuff

This required two shapes, cut twice for the top and bottom. The arc in the footbox’s length is the same length as the width of the bottom of the main body.

Baffles

Baffle design is a deep topic on its own, with a lot of options.

I seriously considered Karo baffles, but because I have experience sewing box baffles (from a pair of down pants I made my wife a few Christmases ago), I was confident enough to attempt them again.

I decided on a split vertical/horizontal design: upper body vertical and lower body horizontal. This seems to be the most popular option for DIY projects. Vertical avoids down clumping on the sides while sleeping, but it does make stitching a more complex (since you’re sewing along the long edge in a narrow tube). Horizontal is easier to construct, but down can clump at the sides when sleeping.

I do think chevron or diagonal designs could have benefits, but the complexity and margin for error seem quite a bit higher.

Construction

Construction of box baffling requires thinking inside out.

1. I started by sewing the box baffles on the wrong side of the bottom side layer of fabric. I tried to curve along the baffle material from my seam allowance to the center at the edges of my fabric, which adds a rounded finished edge.

2. I then sewed the footbox’s arc onto the base of the main body of the quilt.

3. Then, I sewed along the edge of the entire quilt except the top edge, wrong side to wrong side. This includes my straps, ensuring they’re on the inside. I now have an inside-out quilt, with box baffles sewn to one side, with raw edges exposed. When I flip this right side out, the edges are nicely finished, and my straps are exposed.

4. To fill with down, I used a length of PVC and PEX. I 3D-printed a removable cap for the PVC and a pusher to attach to the PEX. I filled and measured down into the PVC on a scale, slid the open end into my space to fill, removed the cap, and pushed the down into the cavity.

5. The next step is the most tedious. Working inside out from the base of the quilt, I sewed the unattached side of each box baffle to the wrong side of the top fabric. When I had 5 or so inches left to sew, I paused (with my needle down) and filled with the correct amount of down. Marking my lines was pretty tricky here, as the quilt was no longer a flat shape.

6. To finish the top edge I sewed a straight stitch, leaving a rough edge exposed. I then attached 3/8" grosgrain loops with my cordlocks attached. I then made a strip of bias tape with a double fold and finished ends, and sewed it on to cover the rough edge. Finally, I fed my shock cord through to finish it off.

Final product

The final product is around 22 oz and was more than warm enough for under 40℉.

Learnings

• The most common error I made was letting the fabric fold under itself while sewing, meaning I was sewing into an additional layer. I needed to pick this out and redo it each time.
• It was really difficult to mark up and keep accurate lines when I was partially through sewing. I’d prefer to figure out a method to fully mark out sewing lines while the fabric is flat. I need to find something better than chalk for this, as it needs to hold up through the several days of sewing.
• I’m not sure if the head cinch is necessary, based on how I sleep. Similarly, I don’t know if I need the strap closest to my head.
• If I were to redo this, I’d go with a shorter baffle with more overstuffing, to avoid down movement and save a little weight.

I’ve been working on solving this problem. Though it’s not perfect, this post describes what I’ve come up with.

For convenience, the example code in this post uses UIKit only and is simplified to focus on the essentials. Full code (runnable on iOS and macOS) can be found in the sample code GitHub repository. I assume familiarity with SwiftUI and Core Animation basics in this article, as Apple and others provide good documentation.

Architecture

First, we need to connect SwiftUI to the Core Animation layer. This uses UIViewRepresentable and UIView (AppKit’s NS equivalents on macOS).

flowchart TD
    SwiftUI
    ViewRepresentable[NSViewRepresentable/UIViewRepresentable]
    View[NSView/UIView]
    CALayer

    SwiftUI --> ViewRepresentable --> View --> CALayer

Data flow

Our animatable property can be passed through each of these layers. This is simpler with one-way data binding, but by providing access to the SwiftUI binding through the UIViewRepresentable’s coordinator, my example code is bidirectional.

Here’s how our animatable value is passed from SwiftUI into our CALayer’s draw function.

struct ContentView: some View {
    @State var value = 0.0 // source of truth

    var body: some View {
        CustomSwiftUIView(value: value)
    }
}

struct CustomSwiftUIView: UIViewRepresentable {
    @Binding var value: Double

    func makeUIView(context: Context) -> CustomPlatformView {
        let view = CustomPlatformView()
        // this link allows our UIView to write value (and read if needed outside of standard SwiftUI updates)
        view.delegate = context.coordinator
        return view
    }

    func updateUIView(_ uiView: CustomPlatformView, context: Context) {
        // this "pushes" changes into our CALayer reactively, following standard SwiftUI updates
        (view.layer as? CustomLayer)?.update(
            with: context.transaction,
            value: value
        )
    }

    // The coordinator provides access to the value binding from CustomPlatformView
    class Coordinator: NSObject, CustomDelegate {
        var parent: CustomSwiftUIView

        init(_ parent: CustomSwiftUIView) {
            self.parent = parent
        }
    }

    func makeCoordinator() -> Coordinator {
        Coordinator(self)
    }
}

class CustomPlatformView: UIView {
    // this coordinator provides read/write access to the value
    // for example, a custom gesture recognizer could update the binding
    var coordinator: CustomSwiftUIView.Coordinator?

    override class var layerClass: AnyClass {
        CustomLayer.self
    }
}

class CustomLayer: CALayer {
    @NSManaged var value: CGFloat // animatable property

    override func draw(in ctx: CGContext) {
        // use `value` as needed
    }

    func update(with transaction: SwiftUI.Transaction, value: Double) {
        // we'll fill this in later to respect animations
        self.value = value
    }
}

To summarize why we need each copy of value:

• ContentView: This is our main source of truth and should be considered the canonical one. SwiftUI and most reactive UI frameworks require top-down state passing.
• CustomSwiftUIView: Also inherent in SwiftUI is the data propagation model: passing properties throughout the hierarchy with a single source of truth. Because this is a binding, we can read and write it, but it could be a plain var if read-only access is needed.
• CustomLayer: This is needed for Core Animation to store intermediate values representing state mid-animation. Core Animation duplicates this again within the “model” and “presentation” parts of the layer tree. Writing to this value directly will result in state drift, you must use the Coordinator instead.

Note that we do not need to store the value inside the UIView layer. (In theory, we could move the drawing code into the UIView, but that kind of defeats the point of this post.) Instead, UIView relies on the Coordinator.

Animation

Now that we can read and write our animatable value, we want to animate it. Our goal is to drive all animation from a single place. Additionally, we’d like to use the most modern methods. For these reasons, and because we have to, we’ll use SwiftUI syntax.

Button {
    withAnimation {
        value = 0.5
    }
} label: {
    Text("Animate Value")
}

Custom CALayer Properties

First, we need to enable Core Animation for our custom value property. Two things are required:

1. Make value dynamic by specifying @NSManaged
2. Ensure Core Animation redraws when value changes

class CustomLayer: CALayer {
    static private let animationKeyPath = \CustomLayer.value
    static private var nsAnimationKeyPath: String {
        NSExpression(forKeyPath: animationKeyPath).keyPath
    }
    
    @NSManaged var value: CGFloat
    
    override class func needsDisplay(forKey key: String) -> Bool {
        key == nsAnimationKeyPath || super.needsDisplay(forKey: key)
    }
}

Bridging Transactions

The core component of this technique is using SwiftUI’s Transaction to determine if an animation is active when a property is changed. SwiftUI provides this in the context of a view representable’s update, which we can pass directly into our custom CALayer’s update.

struct CustomSwiftUIView: UIViewRepresentable {
    func updateUIView(_ uiView: CustomPlatformView, context: Context) {
        (uiView.layer as? CustomLayer)?.update(
            with: context.transaction,
            value: value
        )
    }
}

class CustomLayer: CALayer {
    static private let animationKey = "value-animation-key"

    func update(with transaction: SwiftUI.Transaction, value: Double) {
        // additional animation management is omitted

        if let animation = transaction.animation {
            // create Core Animation CAAnimation from transaction.animation
            let caAnimation: CAAnimation = ...
            add(caAnimation, forKey: animationKey)
        }
    }
}

Bridging Animations

Now, we need to transform the SwiftUI.Animation into a CAAnimation. This is a little more complicated. SwiftUI.Animation is fairly opaque. It doesn’t provide access to the type of animation, its configuration, or any way to execute itself as a function.

Instead, we use the fairly hacky technique of parsing the animation’s description and extracting parameters from it.

This is fairly straightforward for spring animations:

nonisolated(unsafe) let fluidSpringAnimationRegex =
#/FluidSpringAnimation\(response: (?<response>\d+\.\d+), dampingFraction: (?<dampingFraction>\d+\.\d+), blendDuration: (?<blendDuration>\d+\.\d+)\)/#

if let springParameters = try fluidSpringAnimationRegex.wholeMatch(in: description) {
    let caAnimation = CASpringAnimation()
    let response = CGFloat(Float(springParameters.response)!)
    let dampingFraction = CGFloat(Float(springParameters.dampingFraction)!)
    let omegaN = 2 * .pi / response
    caAnimation.stiffness = omegaN * omegaN * mass
    caAnimation.damping = dampingFraction * 2 * sqrt(caAnimation.stiffness * caAnimation.mass)
    return caAnimation
}

nonisolated(unsafe) let springAnimationRegex =
#/SpringAnimation\(mass: (?<mass>-?\d+\.\d+), stiffness: (?<stiffness>-?\d+\.\d+), damping: (?<damping>-?\d+\.\d+), initialVelocity: SwiftUI._Velocity<Swift.Double>\(valuePerSecond: (?<initialVelocity>-?\d+\.\d+)\)\)/#

if let springParameters = try springAnimationRegex.wholeMatch(in: description) {
    let caAnimation = CASpringAnimation()
    caAnimation.mass = CGFloat(Float(springParameters.mass)!)
    caAnimation.stiffness = CGFloat(Float(springParameters.stiffness)!)
    caAnimation.damping = CGFloat(Float(springParameters.damping)!)
    caAnimation.initialVelocity = CGFloat(Float(springParameters.initialVelocity)!)
    return caAnimation
}

And we can fairly easily recreate Apple’s default animation:

if description == "DefaultAnimation()" {
    // defaults changed in more recent versions
    if #available(iOS 17, macOS 14, tvOS 17, watchOS 10, *) {
        let caAnimation = CASpringAnimation()
        caAnimation.apply(response: 0.55, dampingFraction: 1)
        return caAnimation
    } else {
        let caAnimation = CABasicAnimation()
        caAnimation.timingFunction = .init(name: .easeInEaseOut)
        caAnimation.duration = 0.35
        return caAnimation
    }
}

However, traditional bezier animation curves are more difficult. SwiftUI produces descriptions that can be regex matched using:

#/BezierAnimation\(duration: (?<duration>\d+\.\d+), curve: \(extension in SwiftUI\):(?<cubicSolver>SwiftUI.UnitCurve.CubicSolver\(ax: (?<ax>-?\d+\.\d+), bx: (?<bx>-?\d+\.\d+), cx: (?<cx>-?\d+\.\d+), ay: (?<ay>-?\d+\.\d+), by: (?<by>-?\d+\.\d+), cy: (?<cy>-?\d+\.\d+)\))\)/#

However, I haven’t yet been able to figure out what the cubic solver is and how to convert its three two-dimensional coordinates ((ax, ay), (bx, by), (cx, cy)) into a bezier curve’s two two-dimensional control points (CAMediaTimingFunction.init(controlPoints:_:_:_:)).

Update 2024-12-10

Thanks to Eric from Play, I now know how to convert SwiftUI’s CubicSolver back to the original Bezier control points.

let pt1 = (
    x: cx / 3,
    y: cy / 3
)
let pt2 = (
    x: (bx + cx) / 3 + pt1.x,
    y: (by + cy) / 3 + pt1.y
)

caAnimation.timingFunction = .init(controlPoints: pt1.x, pt1.y, pt2.x, pt2.y)

Previously, I resorted to explicitly matching against standard timing curves I can explicitly create using SwiftUI and Core Animation. For example, ease in’s cubic solver is:

SwiftUI.UnitCurve.CubicSolver(ax: -0.7400000000000002, bx: 0.4800000000000002, cx: 1.26, ay: -2.0, by: 3.0, cy: 0.0)

And the Core Animation instance is:

let caAnimation = CABasicAnimation()
caAnimation.duration = Double(bezierParameters.duration)!
switch bezierParameters.cubicSolver {
case easeInAnimationCubicSolver:
    caAnimation.timingFunction = .init(name: .easeIn)
}
return caAnimation

Once the animation is created, we configure the keypath it modifies, and its start and end values without our layer’s update function. We also need to ensure we update the spring animation’s duration, as it depends on the value’s range. Core Animation will cut off the animation without this.

self.value = value

if let caAnimation = transaction.animation?.caAnimation {
    caAnimation.keyPath = Self.nsAnimationKeyPath
    caAnimation.fromValue = (presentation() ?? self).value
    caAnimation.toValue = value
    if let caAnimation = caAnimation as? CASpringAnimation {
        // Core Animation will cut off the animation if the duration is not updated
        caAnimation.duration = caAnimation.settlingDuration
    }

    add(caAnimation, forKey: Self.animationKey)
}

Final Result

For my final demo, I want to draw something that shows value animating. I’ll draw a circle that will animate through the vertical center axis of the view. I’ll also print the value as text to visually guarantee it’s changing.

let diameter = 20.0

override func draw(in ctx: CGContext) {
    ctx.clear(bounds)

    // set graphics context to support NSString drawing
    UIGraphicsPushContext(ctx)
    "\(value)".draw(
        in: bounds,
        withAttributes: fontAttributes
    )

    ctx.setFillColor(CGColor(red: 1, green: 0, blue: 0, alpha: 1))
    ctx.fillEllipse(
        in: CGRect(
            origin: CGPoint(
                x: (bounds.width - diameter) / 2,
                y: (bounds.height - diameter) * value
            ),
            size: CGSize(width: diameter, height: diameter)
        )
    )
}

Another feature I want to show is bidirectional data binding. When you click or tap on the custom view, it will interrupt the animation and set the parent to the current state, to keep everything in sync. We can also animate changes from the internal view using the same SwiftUI withAnimation function.

@objc func handleTap(gestureRecognizer: UIGestureRecognizer) {
    guard let coordinator else { return }
    coordinator.parent.value = (presentation() ?? self).value
    removeAnimation(forKey: Self.animationKey)
}

@objc func handleDoubleTap(gestureRecognizer: UIGestureRecognizer) {
    guard let coordinator else { return }
    withAnimation {
        coordinator.parent.value = (presentation() ?? self).value > 0.5 ? 0 : 1
    }
}

Complete code with an example app and Xcode project can be found at https://github.com/apexskier/swiftui-coreanimation.

Taking it further

I’m pretty happy with this approach, especially the ability to drive animations from multiple layers in the stack using the same mechanism. However, it’s not ideal for a few reasons.

From the SwiftUI spring documentation:

When mixed with other spring() or interactiveSpring() animations on the same property, each animation will be replaced by their successor, preserving velocity from one animation to the next. Optionally blends the response values between springs over a time period.

My approach does neither of these things. In theory, when an animated update propagates while an animation is in progress, we could look up the current animation and set the new animation’s initial velocity appropriately. The blocker is the opaqueness of CAAnimations, which don’t provide APIs for access to value or velocity at a given time.

Blending response values is even more difficult, as it would require dynamically changing CAAnimations over time, which isn’t supported.

As mentioned above, I haven’t figured out SwiftUI’s CubicSolver, which I think is a private struct implementing UnitCurve. It represents at least bezier curves, but I haven’t figured out the math or how it works. If you have any ideas, please get in touch!

Ultimately, these issues are due to the closed nature of SwiftUI and other Apple UIs. At the core, animation curves are math. Standard curves are simple functions over time (f(time) = value). Springs are more complex since they’re semi-stateful by taking the animated value into account, but are also deterministic. I’d like to be able to directly call these functions. Unfortunately, CABasicAnimation has no support for this. At first glance at the documentation, SwiftUI’s Animation appears to support this with func animate<V>(value: V, time: TimeInterval, context: inout AnimationContext<V>) -> V?. However, I have not found a way to get ahold of an AnimationContext outside of a custom Animation subclass, which makes this non-viable. SwiftUI’s UnitCurve has value(at:) and velocity(at:) functions that are exactly what I want, but don’t have a spring equivalent, and UnitCurves aren’t accessible from Animation. I could directly implement timing curve functions, but I’d prefer something built-in to avoid building it from scratch.

Update 2024-12-10

In additional to figuring out CubicSolver as mentioned above, I’ve extended the demo project on GitHub to show SwiftUI and CoreAnimation side by side, so you can visually confirm the animations are the same. SwiftUI has noticeable lag, but overall this approach works.

12/13 - The Claus Family

Especially considering the two sequels, not very good. Pretty unconvincing and to-be-expected storylines, both about Santa Claus and saving the biscuit factory. The humor wasn’t great either, but this was probably made worse by watching a dub.

★☆☆☆☆

12/16 - Family Switch

Family Freaky Friday, but not as good. Tenuous connection to Christmas. Lots of writing that had the appearance of jokes.

★☆☆☆☆

12/16 - Love Hard

Pretty good Christmas romantic comedy. The writing and acting were quite good in general, and the characters had more dimension than most rom-coms, especially Josh.

★★★★☆

12/17 - Holiday in the Vineyards

Pretty standard Hallmark-style Christmas romantic comedy, meaning not much comedy and a stretched connection to Christmas (who has a real estate deadline on Christmas Eve?). The son of a fancy wine company has to sneak around a small town to get inside info on buying the vineyard. Falls in love with a sexy local wine lady, and has to reveal his lies. Some gratuitous shirtless abs, and way too public sexy dancing.

★★☆☆☆

12/18 - Christmas with You

A slight deviation from the standard format, an aging pop star surprises a fan for the holidays, falls in love with the dad, and writes a hit Christmas song with him. Not terrible, but not one I need to watch again.

★★★☆☆

12/25 - Candy Cane Lane

This one was a wild ride. A neighborhood’s Christmas decoration contest escalates dramatically. This one was laugh-out-loud funny and I found the animation for the figurines quite effective.

★★★★★

Let’s start with a simple (though contrived) example. I’m writing some code that depends on the go-github library to interact with the GitHub API.

package before

import (
	"context"
	"fmt"

	"github.com/google/go-github/v47/github"
)

type obj struct {
	user string
	gh   *github.OrganizationsService
}

func New(user string) obj {
	return obj{
		user: user,
		gh:   github.NewClient(nil).Organizations,
	}
}

func (m *obj) CountOrganizations(ctx context.Context) (int, error) {
	orgs, _, err := m.gh.List(ctx, m.user, nil)
	if err != nil {
		return 0, fmt.Errorf("couldn't list organizations: %w", err)
	}
	return len(orgs), nil
}

func (m *obj) IsMemberOf(ctx context.Context, org string) (bool, error) {
	result, _, err := m.gh.IsMember(ctx, org, m.user)
	if err != nil {
		return false, fmt.Errorf("couldn't call IsMember: %w", err)
	}
	return result, nil
}

How do you test this? github.OrganizationsService is a struct type, so we’re required to have a direct instance of it to pass type checking. In many cases, this will force your tests to make network calls. Usually, you can pass http.Client and override its behavior, but that gets messy fast.

Setup

The key to testing this behavior is to depend on an interface type instead of the struct. Go makes this easy, which you may not know if you’re used to other languages. In Go, an interface describes behavior that both your code or dependency code can implement. This feature means we can define an interface in our code that github.OrganizationService implements and the compiler will recognize it.

type githubOrganizations interface {
}

type obj struct {
	user string
	gh   githubOrganizations
}

I usually start with an empty interface and add methods as needed. Doing this helps keep my interface as clean as possible, which makes understanding code when refactoring or changing dependencies later easier.

Swapping *github.OrganizationsService for githubOrganizations works because all structs conform to the empty interface. However, I now see errors wherever I use .gh: m.gh.List undefined (type githubOrganizations has no field or method List).

We need to add each of the undefined methods to the interface. If I’m too lazy to look at the docs, I’ll temporarily swap githubOrganizations back to *github.OrganizationsService, jump to the definition of the previously undefined method and port it over.

type githubOrganizations interface {
	List(ctx context.Context, user string, opts *github.ListOptions) ([]*github.Organization, *github.Response, error)
	IsMember(ctx context.Context, org, user string) (bool, *github.Response, error)
}

Writing a test

Now let’s use this interface to write a test verifying CountOrganizations works as expected.

func TestCountOrganizations(t *testing.T) {
	obj := obj{
		gh: mockGHList{},
	}

	c, err := obj.CountOrganizations(context.Background())
	if err != nil {
		t.Fatal(err)
	}
	if c != 3 {
		t.Fatalf("unexpected number of organizations: %d", c)
	}
}

Here’s the real magic: mockGHList is a struct that embeds a pointer to github.OrganizationsService, which we originally depended on.

type mockGHList struct {
	*github.OrganizationsService
}

Go pointer semantics and struct embedding rules mean all methods of *github.OrganizationsService can be called on mockGHList, even when the embedded value is nil. This allows us to run the test without compilation issues, but because github.OrganizationService is nil, the test panics.

--- FAIL: TestCountOrganizations (0.00s)
...
github.com/google/go-github/v47/github.(*OrganizationsService).List

A nil pointer was found when trying to call .List on the nil *github.OrganizationsService. Go struct embedding rules mean that methods defined on the mockGHList object override those on the nested *github.OrganizationsService object. This rule lets us write our mock method.

func (mockGHList) List(context.Context, string, *github.ListOptions) ([]*github.Organization, *github.Response, error) {
	return []*github.Organization{{}, {}, {}}, nil, nil
}

Rerun the test, and it passes!

--- PASS: TestCountOrganizations (0.00s)

Benefits

Single-use, minimal mocks

By wrapping the original struct, we only need to implement the methods our tests directly depend on. This encourages single-use, minimal mock objects instead of manually maintaining large shared mocks.

Any hardcoded mock codifies its expectations of how specific scenarios behave, usually the first tests it’s used in. Those expectations make it harder to use for new tests. As the codebase grows, it either doesn’t thoroughly test new behavior or combinatorially increases in complexity (by introducing [boolean flags](https://martinfowler.com/bliki/FlagArgument.html, for example). At some point, the mock deserves its own tests to track what it’s doing.

Fail-by-default

This pattern fails when executed code makes unexpected method calls, which can help catch accidental changes.

Mocking libraries

I’ve also successfully used this pattern with third-party mocking libraries.

Here’s an example of use with "github.com/stretchr/testify/mock".

type mockGHIsMember struct {
	mock.Mock
	*github.OrganizationsService
}

func (m *mockGHIsMember) IsMember(ctx context.Context, org, user string) (bool, *github.Response, error) {
	args := m.Called(ctx, org, user)
	return args.Bool(0), args.Get(1).(*github.Response), args.Error(2)
}

func TestIsMember(t *testing.T) {
	gh := mockGHIsMember{}
	obj := obj{
		user: "apexskier",
		gh:   &gh,
	}

	gh.On("IsMember", mock.MatchedBy(func(context.Context) bool { return true }), "org", obj.user).Return(true, (*github.Response)(nil), nil)

	result, err := obj.IsMemberOf(context.Background(), "org")
	require.NoError(t, err)
	assert.True(t, result)
}

I still only need to mock the method being called.

Caveats

• Defining an interface does not work when using struct fields since interfaces can only declare methods.
• Auto-complete won’t show other methods available on the original struct type. https://pkg.go.dev is your friend, or you can manually declare a variable of the original type and use auto-complete on that.

You can view the code from this post at https://github.com/apexskier/go-struct-mocking-demo/.

In most cases, the TODO should be filed in your team’s issue tracker immediately and cross-linked with the pull request. Some people have processes that track issues using TODOs, but I don’t believe source code works well for issue tracking. Source code represents the current state of your product. Reviewing historical context, though possible with version control, is not the primary interface. Issue tracking systems are built for prioritization, tracking context, linking related issues, and assigning responsibility.

TODOs are usually used to defer technical debt. Moving them to your issue tracker’s backlog allows prioritization against feature work by putting them in the same playing field and can be used as a metric to understand the depth of technical debt.

TODOs often describe an expected future change. It’s tough to predict the future, so the TODO might not make sense when the next person reads them. I still encourage using comments to describe the problem and the reasons for not addressing it, but not to prescribe action. In the future, you’ll have much better context when deciding how to fix the issue, or you might be able to just delete it.

Even though I don’t like seeing TODOs in a codebase, I often use them in my feature branches and scan through the diff once I’ve opened my draft PR to decide if it’s ready for review. They’re lighter weight than an issue tracker and can act as a checklist for a single task. Generally, though, they’re an indicator of poor quality and have more responsible alternatives.

Generally, I try to follow standard conventions in my personal configuration. I try to use the command line in a way that I don’t feel like I’m constantly stumbling in unfamiliar environments like remote servers, docker images such as node or golang, or a fresh Raspberry Pi. This practice also makes it much easier to help my coworkers—I can work within their terminal or help instruct them without needing to translate commands. It can be painful to watch someone with muscle memory for custom git aliases or non-standard shells working in a freshly provisioned EC2 instance.

Even considering these benefits, a lot of customization provides more than enough value to be worthwhile. A familiar shell makes the debugging experience much more pleasant, and installing the tools I need to investigate takes time. I’ve also spent years polishing my bash prompt, and I love using it.

My most common use case is debugging docker and Kubernetes networking behavior. For example, I can spin up a pod in our cluster running the toolbox image and use curl and dig to verify DNS behavior.

I also occasionally need to run an image that takes a long time to start or run using a wrapper utility that doesn’t bind ports on my host. In this case, I can run my toolbox within a local docker network and connect to the image without needing to restart it or dig into the internals of how it’s initialized.

Keeping my toolbox image up to date is automated directly in my dotfiles repository, using the same scripts I use when setting up a new computer. Whenever I push to the default branch, a GitHub action builds the image and publishes it to GitHub’s container registry¹.

The docker image builds from debian:stable-slim, copies my dotfiles, runs my installer and setup scripts, then runs bash. Putting this together was a nice way to verify the cross-compatibility of my setup. The only serious issue I ran into was ensuring my setup scripts could run non-interactively. I also took the opportunity to double-check that my dotfiles don’t contain too much personal information (like a preconfigured git user) to let other people use my setup without accidentally impersonating me.

Try it yourself by running

docker run --rm -it ghcr.io/apexskier/dotfiles/toolbox

You can read more about it and see exactly what’s installed by visiting my dotfiles.

One of my frequent use cases is iteration over a collection of varied objects. A type union allows me to avoid complicated merging and ordering logic and use simple conditional logic within the iteration body. It’s also used commonly in APIs I interact with, where a single resource can produce different but similar things, or I want to reduce ambiguity between conditional fields.

Type unions can be a stronger pattern than inheritance. In class-based inheritance, the possible set of types is unbounded, while type unions have an explicit set known at compile time. In languages like TypeScript (and Swift, as we’ll see), sub-types of a type union can be unrelated and have distinct inheritance chains.

In other languages

Type unions are simple in weakly typed languages like JavaScript or Python¹ since a variable can contain any value. Strongly typed languages take different approaches to support them.

TypeScript

TypeScript has first-class support with union types. Type narrowing is done with type predicates and custom functions.

interface Rabbit {
	name: string;
	eat(food: Carrot): void;
}
class Dog {
	name: string;
	pet() {}
}
interface Turtle {
	name: "turtle"
}

type Pet = Rabbit | Dog | Turtle

function whatIsIt(pet: Pet) {
	if (typeof pet == "string") {
		return "turtle"
	} else if (pet instanceof Dog) {
		pet.pet()
		return "dog"
	} else {
		return "rabbit"
	}
}

TypeScript is nice because it automatically casts the inspected variable’s type: within the conditional blocks, pet assumes the narrowed type. TypeScript automatically infers common attributes of the sub-types, allowing access to the common name property (pet.name).

Kotlin

Kotlin supports type unions with sealed classes. Type narrowing is done with when expressions.

sealed class Pet()
data class Rabbit(
	val name: String,
	val carrot: Double
) : Pet() {
	fun eat(food: Carrot) {}
}
class Dog(val name: String) : Pet() {
	fun pet() {}
}
object Turtle : Pet() {
	val name: String = "turtle"
}

fun whatIsIt(pet: Pet): String =
	when (pet) {
		is Rabbit -> "rabbit"
		is Dog -> {
			pet.pet()
			"dog"
		}
		is Turtle -> "turtle"
	}

Like TypeScript, variable types are automatically narrowed. Kotlin does not automatically infer common attributes, but they can be defined on the base sealed class, following standard inheritance patterns.

In Swift

The core construct for a type union in Swift is an enumeration with associated values. Type narrowing is done with case statements.

protocol Rabbit {
	var name: String { get }
	func eat(food: Carrot)
}
struct Dog {
	var name: String
	func pet() {}
}
typealias Turtle = String

enum Pet {
	case rabbit(Rabbit)
	case dog(Dog)
	case turtle(Turtle)
}

func whatIsIt(pet: Pet) -> String {
	switch pet {
	case .rabbit:
		return "rabbit"
	case .dog(let dog):
		dog.pet()
		return "dog"
	case .turtle:
		return "turtle"
	}
}

Notice that to get a variable of the narrowed type, a new variable is directly defined within the case expression (let dog).

A more concise form of type narrowing is also possible within an if statement².

if case .rabbit(let rabbit) = pet {
	// ...
}

The main downside to Swift’s form of type unions is that the value is nested within another. It’s not possible to directly use attributes on a Pet variable. To work around that, you need to define accessors on the enum itself³.

enum Pet {
	case rabbit(Rabbit)
	case dog(Dog)
	case turtle(Turtle)
	
	var name: String {
		switch self {
		case .rabbit(let rabbit):
			return rabbit.name
		case .dog(let dog):
			return dog.name
		case .turtle:
			return turtle
		}
	}
}

func example(pet: Pet) {
	pet.name
}

If the different sub-types share a protocol, you can define a single accessor to access the protocol.

protocol Mammal {
	var furColor: String { get }
}

enum Pet {
	case rabbit(Rabbit)
	case dog(Dog)
	case turtle(Turtle)
	
	var mammal: Mammal? {
		switch self {
		case .rabbit(let mammal as Mammal), .dog(let mammal as Mammal):
			return mammal
		case .turtle:
			return nil
		}
	}
}

func example(pet: Pet) {
	pet.mammal?.furColor
}

Taking this further, if all sub-types share a protocol, you can extend the enum itself from that protocol and delegate to that accessor.

protocol Animal {
	func sleep()
}

enum Pet: Animal {
	case rabbit(Rabbit)
	case dog(Dog)
	case turtle(Turtle)
	
	private var animal: Animal {
		switch self {
		case .rabbit(let animal as Animal),
			 .dog(let animal as Animal),
			 .turtle(let animal as Animal):
			return animal
		}
	}
	
	func sleep() {
		animal.sleep()
	}
}

func example(pet: Pet) {
	pet.sleep()
}

I find type unions significantly simplify my code and prevent mistakes by strengthening my type semantics. I hope this helps you out as well.

Running has been especially important to me because of coronavirus stresses and living in a foreign country. I find it really helpful as a grounding technique—it forces me to be immersed in the physical world and be aware of physical discomforts. Having an ambitious and achievable goal also helps keep me positive and stick to a regular running schedule.

My favorite part of running is exploration. In a new city, running lets me see the sights and tour the area without a plan or obligation. In my current city, I end up finding all sorts of hidden treasures and trails that most people never see. I usually open up a map in my area and try to connect the green areas using Strava’s global heatmap.

Some highlights include seeing the old town and some local parks in Gdansk, exploring several national parks, a snowy night run in Slovakia, and seeing castles along Szlak Orlich Gniazd (the Trail of the Eagle’s Nests). On the other hand, I’ve had some not-so-fun runs, including 10 kilometers on the same 0.2km stretch of cobble in my apartment complex during coronavirus lockdown, some smoggy morning winter runs, and my longest and farthest run to date—28 miles for my 28th birthday over 4 hours and 20 minutes. Aisha’s cheered me along from her bike for most of the long ones in her self-designated role as “sheepdog.”

Another aspect I enjoy is tracking statistics. I’ve used Strava for the last couple of years to store my historical running information. Throughout my 1,000 miles, I’ve spent almost six full days moving, climbed 54,775 feet (almost twice the height of Mount Everest), and burned an extra 114,267 calories (around 60 days worth of food for the average person).

You can see more data here.

Maps generated with https://github.com/erik/derive. Background imagery from CartoDB.

1. Messages are not searchable once you leave
2. Messages are not sharable
3. People can’t easily jump in and out
4. You can’t notify someone when you mention them
5. Workspace apps and bots aren’t present
6. They cultivate an “Us vs. them” culture
7. They foster unconscious biases by making it easy to exclude people
8. You can’t change your mind and make a private channel public

While there are uses for private channels, they hinder communication and transparency. Please make public channels your default.

I’ve been considering divesting from social media for some time, for mental health, ethics, and to own my content. I feel like Instagram reached a tipping point this summer, where it shifted from a positive place to share what my friends are up to, to a platform that amplifies outrages and meme sharing.

My approach is heavily inspired by Tom MacWright’s /photos, as are a few other aspects of this site’s design. I want it to be fast and simple, with low management overhead.

To post a photo, I run it through a script to process, resize, and upload to DigitalOcean spaces for long term storage. The script also creates a new post that I add some details to (location, title, description…), and all that’s left is to publish.

I spent quite a bit of time refining the user experience and trying out some fun new web technologies for the first time.

I generate custom CSS to keep the images centered and constrained within the window. I use CSS scroll snapping to snap to and center on them as you scroll through. The page uses no JavaScript.

The fanciest feature is a custom placeholder displayed as the images load. My script extracts average colors for the top, left, right, and bottom of the image, then injects them into an inlined SVG background image for the <picture> element. The SVG is made of four radial shapes of the extracted average colors, with a blur applied on top of it to form a geometric approximation of a downsampled version of the image.

Overall, it was a fun project to show off some of my favorite photos. I hope you like them too.

Let’s start with a basic example of creating and using a component. HelloProps is an interface that describes precisely what properties the component accepts and requires.

interface HelloProps {
    readonly compiler: string;
    readonly framework: string;
}

export function Hello({ compiler, framework }: HelloProps) {
    return (
        <h1>Hello from {compiler} and {framework}!</h1>
    )
}

import { Hello } from "./hello"

function App() {
    return <Hello compiler="TypeScript" framework="React" />;
}

There are two main component-related types used when writing React code. I tend to get them mixed up.

1. React.ComponentType is what’s in your JSX (except for html primitives)
2. React.ReactElement (or JSX.Element) is what your JSX produces

import * as React from "react";

class Test extends React.Component<{ Comp: React.ComponentType }> {
    render() {
        const el: React.ReactElement = <this.props.Comp />;
        return <>{el}</>
    }
}

React.ComponentType is composed of React.ComponentClass, for class-based components, and React.FunctionComponent² for functional components.

You also might encounter more “exotic” types of components extending from React.ExoticType. These include forwarded ref components, context providers, and memoized components. All have different behavior restrictions at runtime, so most difficulties you’ll encounter have a good reason behind them.

Nullable or optional props?

interface MyComponentProps {
    requiredProp: string;
    optionalProp?: string;
    nullableProp: string | null;
}

If a property isn’t required, you should generally make it nullable instead of optional. Optional properties can be omitted, which means they’re easy to forget. Nullable properties require explicitness, which is especially helpful when introducing a new property into a large codebase—the compiler will tell you if you’ve missed anything.

Only use optional properties when the property has a default value or if forgetting it won’t break the user experience.

Avoid using properties that are both optional and nullable. They have the disadvantages of optionals and make the codebase more complex.

I also recommend avoiding undefined for any variable type because it allows accidental mistakes through forgotten initialization. This also helps avoid needing nullableProp={value ?? null}.

Don’t export properties types

As a codebase grows, it makes sense to export property interfaces to reuse in other components and keep things DRY, especially as your codebase expands, or you start making use of higher-order components and composition.

import { ButtonProps } from "../props";

export function FooButton(props: ButtonProps) {}

import { ButtonProps } from "../props";

export function BarButton(props: ButtonProps) {}

This is a pattern I used commonly in the past. I now avoid it because it increases coupling and information leaking. If FooButton doesn’t need a property from ButtonProps, you can’t remove it without affecting BarButton. If BarButton needs a new property, you can’t hide it from FooButton and it’s required everywhere FooButton is used.

Sharing interfaces is especially attractive to those coming from an object-oriented world. I advise trying to avoid habitually using inheritance and conformance and instead focus on “the shape that values have.”

Instead, each component should own its own properties. This results in more explicitness and increases flexibility at the minor cost of duplicated code.

import * as React from "react";

interface FooButtonProps {
    a: number;
    b: number; // this is a new property
}

declare function FooButton(props: FooButtonProps): React.ReactElement;

interface BarButtonProps {
    a: number;
}

declare function BarButton(props: FooButtonProps): React.ReactElement;

declare const conditional: boolean;

function Test() {
    const Button = conditional ? FooButton : BarButton;
    return <Button a={123} b={456} />;
}

Higher-order components

Higher-order components are an advanced React pattern for reuse of component logic. In TypeScript, higher-order components are generic to decouple them from the components being wrapped.

Correctly typing higher-order components is a pain in the ass. That being said, I’ll try to explain my approach and the problems you’ll encounter.

When writing or refactoring a higher-order component into TypeScript, you need to understand the wrapped component’s properties and the returned component’s properties. The wrapped, or parameter, component’s properties can be divided into those that the higher-order component uses and those that it doesn’t. The types that the higher-order component doesn’t need to know about are generally represented by a generic type: let’s call it P.

On occasion, you need to know the type of component returned. If possible, I recommend using the widest type possible (React.ComponentType) or relying on type interference (not specifying an explicit return type). You may need an explicitly narrower type if your component returns an exotic type, like a ref forwarder.

By convention, I use the names “Provides” and “Requires”. Provided properties are those that the higher-order component provides to its wrapped component, and required properties are those additionally needed by the returned component.

function withExtraFunctionality<P>(
    WrappedComponent: React.ComponentType<P & ExtraFunctionalityProvidesProps>
): React.ComponentType<P & ExtraFunctionalityRequiresProps>;

import * as React from "react";

declare function getDisplayName(component: React.ElementType): string;

interface ExtraFunctionalityProvidesProps {
    a: string;
    b: string;
}

interface ExtraFunctionalityRequiresProps {
    b: string;
    c: string;
}

function withExtraFunctionality<P>(
    WrappedComponent: React.ComponentType<P & ExtraFunctionalityProvidesProps>
): React.ComponentType<P & ExtraFunctionalityRequiresProps> {
    function ExtraFunctionality(
        props: P & ExtraFunctionalityRequiresProps
    ) {
        // shared, internalized logic, e.g.
        const [a] = React.useState("");
        
        return <WrappedComponent a={a} {...props} />;
    }
    ExtraFunctionality.displayName = `withExtraFunctionality(${getDisplayName(WrappedComponent)})`;
    return ExtraFunctionality;
}

declare function BaseComponent(props: { d: string }): React.ReactElement;

// P inferred correctly as { d: string }
const WrappedBaseComponent = withExtraFunctionality(BaseComponent);

<BaseComponent d="d" />;
<WrappedBaseComponent d="d" b="b" c="c" />;

A common error I encounter is some variety of the following:

'P' could be instantiated with an arbitrary type which could be unrelated to…

The most common cause of this is the higher-order component “stealing” properties from the wrapped component (or TypeScript thinks this is happening). It highlights that a property name visible to the higher-order component could overlap with one in P required by the wrapped component.

import * as React from "react";

interface ExtraFunctionalityProvidesProps {
    a: string;
}

interface ExtraFunctionalityRequiresProps {
    b: string;
    c: string;
}

function withExtraFunctionality<P>(
    WrappedComponent: React.ComponentType<P & ExtraFunctionalityProvidesProps>
): React.ComponentType<P & ExtraFunctionalityRequiresProps> {
    return function ExtraFunctionality(
        props: P & ExtraFunctionalityRequiresProps
    ) {
        // shared, internalized logic, e.g.
        const [a] = React.useState("");
        const { b, ...rest } = props;
        // do something with b
        
        //      ↓ error
        return <WrappedComponent a={a} {...rest} />;
    }
}

declare function BaseComponent(props: { d: string }): React.ReactElement;

// P inferred correctly as { d: string }
const WrappedBaseComponent = withExtraFunctionality(BaseComponent);

<BaseComponent d="d" />;
<WrappedBaseComponent d="d" b="b" c="c" />;

To fix this, you’ll need to refactor your code to avoid the name conflict or explicitly type Provides and Requires props to prevent the stolen prop, which is error-prone.

Higher-order components and TypeScript can be a pain, but each upgrade of TypeScript seems to make it smoother (or maybe it’s just me learning). I’m hopeful that #10727, #9252, and #12936 will address some of the remaining issues.

Refs

Refs are another place where typing can be tricky. The main cause of this is not understanding the fundamentals of what refs are—a pointer to the underlying runtime object driving your component. The React.createRef function takes a single type parameter that describes this object.

function Component() {
    const ref = React.createRef<HTMLDivElement>();
    ref.current?.scrollTop; // <-- properly typed
    return <div ref={ref} />;
}

Most examples show refs to DOM elements and other “basic” components, but it works the same way with any component.

function Component() {
    const ref = React.createRef<ChildComponent>();
    ref.current?.doSomething;
    return <ChildComponent ref={ref} />;
}

declare class ChildComponent extends React.Component {
    doSomething(): void;
    render(): JSX.Element;
}

As your app gets more complex, so will your ref usage. Unfortunately, the way ref types are defined prevents abstracting into an interface easily.

PropTypes

If you’re migrating a JavaScript React project to TypeScript, you’re hopefully already using PropTypes to provide some degree of runtime type checking to your project. With TypeScript, PropTypes become mostly unnecessary. TypeScript’s type system is much more powerful and can replace any PropType except for strict shapes³ and custom validator functions.

function Component(props) { /* ... */ }
Component.propTypes = {
    optionalUnion: PropTypes.oneOfType([
        PropTypes.string,
        PropTypes.number,
        PropTypes.instanceOf(Message)
    ]),
    
    optionalObjectWithShape: PropTypes.shape({
        color: PropTypes.string,
        fontSize: PropTypes.number
    }),
}

function Component(props: ComponentProps) { /* ... */ }
interface ComponentProps {
    optionalUnion?: string | number | Message;
    optionalObjectWithShape?: {
        color: string;
        fontSize: number;
    };
}

PropTypes are still necessary if using the legacy context API. I recommend pairing contextTypes and childContextTypes with an interface to add some type safety at build-time.

import * as React from "react";
import * as PropTypes from "prop-types";

const messageContextTypes = {
    color: PropTypes.string,
};

interface MessageContext {
    color?: string;
}

interface MessageListProps {
    messages: ReadonlyArray<{ text: string }>;
}

class MessageList extends React.Component<MessageListProps> {
    static childContextTypes = messageContextTypes;

    getChildContext(): MessageContext {
        return { color: "purple" };
    }

    render() {
        return (
            <div>
                {this.props.messages.map((message) => (
                    <Message text={message.text} />
                ))}
            </div>
        );
    }
}

interface MessageProps {
    text: string;
}

function Message({ text }: MessageProps) {
    return (
        <div>
            {text} <Button>Delete</Button>
        </div>
    );
}

interface ButtonProps {
    children: React.ReactNode;
}

function Button({ children }: ButtonProps, context: MessageContext) {
    return <button style={{ background: context.color }}>{children}</button>;
}

Button.contextTypes = messageContextTypes;

If you’re using the current context API, you don’t have much to worry about. It works very well with TypeScript.

Return type of render

The return type of a render function must be JSX.Element | null in TypeScript, but the React docs allow strings, numbers, and arrays.

import * as React from "react";

function RenderArray() {
    return [
        <div key="1">A</div>,
        <div key="2">B</div>
    ];
}

<RenderArray />;

function RenderString() {
    return "testing";
}

<RenderString />;

This is easy to resolve; just wrap the return in a fragment: return <>{value}</>.

Panic is an independent software development company based in Portland, OR that I’ve been a fan of for a long time. When I first started programming, I used their previous web-development focused editor Coda, and I still use many of their products today. I’m a fan of Panic because they do interesting things with amazingly high quality. I see this as a major difference between much of the industry’s focus on growth and speed over quality.

Nova is their new code editor. It’s been in beta for a while now, and the first version was released a couple of weeks ago.

What I’m excited about

I’m excited about Nova’s potential for a few reasons:

It’s a native app with the potential for better stability and performance than editors like Atom and VS Code (my primary GUI editor). Although most of my career has been focused on the web, I still prefer native apps over web technology-based ones (one of the reasons I use Apple Photos over Google Photos).

It’s a for-profit product with a single owner. Although Microsoft’s been doing a pretty great job with VS Code, it’s hard to get around the fact that open source and free products have a higher chance of atrophying over time. This can be due to bloat (like I experienced with Atom), contributors switching focus, or just random chance.

It’s got some valuable features. Tasks aren’t exactly novel but are well implemented and have good potential to grow. Savable Search Scopes are really powerful and new to me. I’m impressed that remote files, projects, and editing is so stable in a first release.

Finally, Panic’s focus on quality and close affinity with the Apple community could align really well with a high-quality, curated Extension Library.

What I’m worried about

But, there are a few things that worry me:

There’s no debugger support yet. It sounds like this is on the roadmap, but I can’t ignore that it’s critical for many of my workflows. In the JavaScript landscape I can use Chrome’s debugging GUI, but many other languages don’t have great options outside of an IDE. Being able to work on the code I’m stepping through directly is immensely valuable.

Nova doesn’t support Vim keybindings, and the extension API doesn’t support different editing modes. I don’t see myself fully committing to a code editor without Vim emulation—the ubiquity of them while programming makes them second nature to me at this point.

I’m worried about the feasibility of an extension community for a paid product. Most extensions are open-source, but the product isn’t, so some of what draws me to open-source development is missing. I’m hoping these fears end up unfounded—there’s definitely precedent for good extension support with other paid products.

Finally, I’m unsure of the target industry and how well a single product will keep up. Most of what I’ve seen around Nova revolves around the JavaScript ecosystem, but I think the overall vision is general-purpose. Panic needs a deep understanding of various software development communities and the compatibilities between different communities’ workflows.

One counter-example to many of my worries is JetBrains’ IDEs. In many ways, IntelliJ and friends are similar to Nova: paid product, solid extension library, power-user focused code editor; but there are some significant differences: JetBrains is a much larger company and has broken their products into niche IDEs for specific types of programming (JVM, Golang, Python, etc.). They also offer a fully free version.

Most of the people I’ve talked to have agreed that Nova’s ultimate success will depend on its extension ecosystem. That’s what I’ve been mostly playing with, so let’s jump in.

Extension development

I’m not going to cover extension development in detail. For that, read the docs. I’m also not going to cover the differences between extension development for Nova and other editors since this is my first experience with extension development.

Extensions can provide functionality through two mechanisms: static files and a JavaScriptCore based runtime. Certain features are available through both mechanisms; certain features are only available through one. For example, language syntax highlighting is defined only through static XML files, but auto-completion can be provided through XML files or a synchronous JavaScript API.

There are definitely some annoying limitations and missing features of the JavaScript API, but overall it’s very nice for a V1 release. Because the runtime is JavaScriptCore, extensions are isolated and have a hard time interfering with each other or the editor’s core functionality (theoretically, there are still some major extension-triggered crashes). Having a single runtime is very refreshing—no browser incompatibilities or cross-platform differences to work around.

The static file interface for extensions makes sense—it provides a low barrier to entry to get basic extension functionality working—but is painful for more advanced extensions. One example is conditionally enabling and disabling commands. For my ESLint extension, I can prevent “Suggest a Fix” commands from applying when the editor isn’t in focus, but I can’t prevent it when no suggestions are available.

My favorite part of Nova’s approach to extensions is support for Language Server Protocol servers. The Language Server Protocol (LSP) is a Microsoft-backed open standard for editor/language features like code navigation, refactoring, and auto-completion. It’s a smart way to avoid custom implementations of common code functionality in Nova while potentially supporting a wide variety of languages. My TypeScript extension runs an LSP for most of its functionality, and the protocol has been great to work with. Nova’s support for LSP features is not great (the Go to Definition command doesn’t even use the active LSP client), but there’s a lot of potential.

Community

Extensions aside, one of the biggest reasons Nova could succeed is a passionate community. People love Panic—they’re the dream example of a software company for many, including myself—and want to see this type of product succeed.

Reach out to me to join the Nova community Discord, where we’re talking about extension development, bugs, and the product’s future.

If you give Nova a try, check out my extensions.

But maybe you don’t want to disable that nice physics interaction and want to have some fun with it instead. The goal here is to use css to add some sort of “hidden” content in the background of the site that’s only visible when over-scrolling.

By default, there are already two elements to play with: <html> and <body>. The first thing to understand is the sizing of these elements. Both element’s intrinsic content size is that of the containing content, but the <html> element is special, since its background takes up the full window size.

First, I want to make sure the <body> always covers the full content, so I don’t have anything in the background of the <html> peeking out at the bottom. I also need to make sure my layout doesn’t have any margins collapsing outside of the body, which in this demo I’ll do by making my body flex.

body {
	min-height: 100vh; /* full height */
	display: flex; /* optional - prevents margin collapse */
}

With a background color on the <html> element it’s visible when I overscroll. However, this is “fake” content on desktop browsers—the html is still scrolling so its contents aren’t shown (for example, a background image).

There are a couple of approaches I want to try to get content in there.

1. Don’t scroll the html - scroll the body instead

Unfortunately (at least in the desktop browsers I tested) this doesn’t work as I want. The only element that allows scrolling outside of its content is the <html> tag, so the behavior is the same as if I set overscroll-behavior: none.

html {
	overflow: hidden;
}

body {
	overflow: scroll;
	height: 100vh;
	overscroll-behavior: contain;
}

2. Add fake fixed elements that don’t scroll

I can use some trusty pseudo elements to add content, right?

html::before {
	z-index: 0;
	content: "";
	width: 100px;
	height: 100px;
	right: 0;
	background-color: red;
	position: fixed;
}

body::before {
	z-index: 0;
	content: "";
	width: 100px;
	height: 100px;
	background-color: blue;
	position: fixed;
}

body {
	z-index: 2;
	background-color: white;
}

Well, not really. On desktop, even position: fixed and position: sticky won’t scroll into the overflow area, just like a background-image of <html>. Another issue is that html pseudo elements display above the background of the <body>. Generally, a pseudo element follows the standard stacking context: body { background-color: white } should cover pseudo elements of <html> the same as it covers <html>.

However, this confirms that iOS doesn’t scroll fixed content when overscrolling. The body background issue persists though.

3. Add a wrapper element

Now the the DOM gets a little messy. We can introduce a wrapper element (instead of using <body>) to cover the full document with a non-opaque background color.

#wrapper {
	min-height: 100vh;
	min-width: 100vw;
	background-color: white;
}

<html>
	<body>
		<div id="wrapper"><!-- content --></div>
	</body>
</html>

And we finally have a hidden background element!

html::before {
	z-index: -1;
	position: fixed;
	height: 100vh;
	width: 100vw;
	content: "";
}

However, the browser support is pretty limited. As discovered above, desktop browsers scroll fixed elements during overscroll, meaning they’re not “revealed” like I want. In iOS Safari, however, it’s a pretty nice effect.

Unfortunately, there’s some glitchy behavior on desktop Safari where the background texture shows through un-rendered content.

Bonus!

We can use a hidden element and position: sticky to emulate snapchat’s pull-to-refresh ghost animation with pure CSS.

Try it here

The IDE, the language, and the execution of the code itself all support and guide me as I write code. Especially when executing on a pre-designed plan or refactoring, I can rely on the compiler to let me know when I’ve made a mistake and I can look at the UI to see if I’ve done it right. Some tasks can even feel refreshing because they don’t require hard thinking while seeing a lot of output.

Pure technical design is far harder. Without supporting tools, a higher percent of the cost comes from my brain. I can’t lean on a program to tell me I’m doing something wrong or tell me what to think about next.

To help, I try to prototype in parallel. Whatever code I produce I leave out of review to avoid sunk-cost bias and avoid “can’t see the forest for the trees” effect.

The issue is that I can’t see the future. It’s close to impossible to understand the details of the future use cases I’m building for, and more often then not I’m going to get it not quite right. Once that happens, the work I put in building my abstraction layer is far less valuable and it often gets in the way, making my job harder.

Working in a fast-growing company also means that a lot of the time the future use case I’m building for just never happens. We decide to go another direction, or pause on that project, or it just doesn’t get prioritized. Two years later, the system has evolved to the point where what I built just doesn’t make sense.

Truth is relative

Over time, my understanding of systems will always change, due to the complex and changing environment I work in. Be it because of the tools we use, the people we work with, or the size of the organization, decisions are never binary or always correct. Choosing to use a statically typed language might be more important if the scale of the project is larger, or if a coworker hasn’t developed the muscles to think dynamically. Building a massively scalable microservice architecture might mean you can’t deliver an MVP in time to get the funding needed to start growing your start-up. Implementing a policy to never force-upgrade an app version doesn’t work once Brexit happens.

Build defensively

What you can do is build defensively. In essence, this means building with the understanding that it will be wrong in the future. Encapsulation helps a lot with this, as it enables you to extract or split apart functionality with less pain. Another simple defensive technique is to write less code and save the up-front and maintenance cost.

My rule of thumb

Unless you have three real use cases to build against, don’t spend extra time making the solution generic.

The word “real” is intentional because of my comments on predicting the future.

The words “extra time” are also intentional. Generic abstractions can be useful on their own, to hide complex logic or simplify a difficult to use API, or to build a layer of defence; but if the main value in abstraction is for future elegance it’s not worth it.

Building an abstraction layer is the most problematic with only a single use case, primarily because it usually adds more maintenance overhead which slows iteration and maintenance. The “abstract” interface will often look very similar to the internal one and refactoring is often not any easier than IDE assisted renaming.

Building with two use cases is also problematic. It will be very tempting to add flag-based logic into the implementation, or worse, the external interface. When a third use case is added, the most obvious method is to continue using flag-logic, which ends up coupling the interface to the implementation. The value of the abstraction is lower but maintenance cost isn’t.

Three use cases, however, covers enough complexity that you’re forced to understand what the real value of the abstraction is and create it in a way that makes it easier to work with.

One of the fundamentals of programming is defining interfaces, or contracts between parts of systems. Interfaces create layers of abstraction and allow scaling code beyond the complexity a single person can hold in their head. They appear at the level of function signatures, to dependency signatures, up to service-to-service network calls.

There are almost always grey areas within an individual interface; areas where behavior isn’t explicitly defined. This causes a couple problems. Interpretations of behavior can differ between people or over time, leading to subtle bugs due to drifting behavior in different modules. It also requires overhead and more error handling in each consumer, as you’ll see below.

In a strongly typed language there are some not-immediately-obvious techniques to reduce this ambiguity and create a more intuitive design.

I’ll provide code examples throughout this post, available in several different languages.

The basics: Comments

As the author, the easiest way to avoid ambiguity is through documenting your code.

interface Foo {
  type: string; // describes how foo should be represented
}

interface Bar {
  discount?: number;
  discountApplied?: boolean; // indicates if `discount` is possible, or actually applied, not present if no discount
}

data class Foo(
  val type: String // describes how foo should be represented
)

data class Bar(
  val discount: String?,
  val discountApplied: Boolean? // indicates if `discount` is possible, or actually applied, not present if no discount
)

type Foo struct {
	Type string // describes how foo should be represented
}

type Bar struct {
	Discount        *string
	DiscountApplied *bool // indicates if `discount` is possible, or actually applied, not present if no discount
}

components:
  schemas:
    Foo:
      type: object
      properties:
        type:
          type: string
          description: describes how foo should be represented
    Bar:
      type: object
      properties:
        discount:
          type: string
          nullable: true
        discountApplied:
          type: boolean
          nullable: true
          description: indicates if `discount` is possible, or actually applied, not present if no discount

This helps, but couples you to additional tooling within your editor to expose without reading the source. Comments don’t protect against human issues, such as misinterpretation or plain laziness, and conformance can’t automatically be verified by build tooling.

Taking advantage of typing

Enums

A simple pattern is to use enumeration values. Explicit enumerations can reduce the need for inline error handling and allows for self-documentation through good naming. This sounds simple, but I see people forget about enums often. The key question to ask is:

Do I care about how the consumer uses this value?

If the answer is yes, a string type doesn’t capture the correct nuance.

interface Foo {
  type: string;
}

function convertFooTypeToX(x: Foo): string {
  switch (x.type) {
    case "a":
      return "1";
    case "b":
      return "2";
    case "c":
      return "3";
    default:
      throw new Error(`unknown type: ${x.type}`);
  }
}

enum FooType {
  a = "a",
  b = "b",
  c = "c"
}

interface Foo {
  type: FooType;
}

function convertFooTypeToX(x: Foo): string {
  switch (x.type) {
    case FooType.a:
      return "1";
    case FooType.b:
      return "2";
    case FooType.c:
      return "3";
    // no default is required to satisfy type checking
  }
}

data class Foo(
    var type: String
)

fun convertFooTypeToX(x: Foo): String = when (x.type) {
    "a" -> "1"
    "b" -> "2"
    "c" -> "3"
    else -> throw Exception("unknown type: ${x.type}")
}

enum class FooType {
    a,
    b,
    c,
}

data class Foo(
    val type: FooType
)

fun convertFooTypeToX(x: Foo): String = when (x.type) {
    FooType.a -> "1"
    FooType.b -> "2"
    FooType.c -> "3"
    // no else is required to satisfy type checking
}

type Foo struct {
	Type string
}

func ConvertFooTypeToX(x Foo) string {
	switch x.Type {
	case "a":
		return "1"
	case "b":
		return "2"
	case "c":
		return "3"
	}
	panic(fmt.Sprintf("unknown type: %s", x.Type))
}

type FooType string

const (
	FooTypeA FooType = "a"
	FooTypeB         = "b"
	FooTypeC         = "c"
)

type Foo struct {
	Type FooType
}

func ConvertFooTypeToX(x Foo) string {
	switch x.Type {
	case FooTypeA:
		return "1"
	case FooTypeB:
		return "2"
	case FooTypeC:
		return "3"
  }
  // unfortunately, without real enums in go, we still need this
	panic(fmt.Sprintf("unknown type: %s", x.Type))
}

components:
  schemas:
    Foo:
      schema:
        type: string

components:
  schemas:
    Foo:
      schema:
        type: string
        enum: [a, b, c]

String formats

Enums work well, but only work for explicit sets of values—they can’t be applied if I don’t know the full set of values. If I do know, adding anything new breaks backwards compatibility.

To get around this, I can use a type alias to provide more semantic information.

type HtmlType = string;

typealias HtmlType = String

type HtmlType string

components:
  schemas:
    Foo:
      schema:
        type: string
        format: html

There’s a loophole: The consumer could create their own string and pass it in place of HtmlType. Depending on the serialization library and language, it can be possible to discourage this with custom deserialization of a non-constructable type.

type HtmlType = string & { __t: "html_type" }

function read(response: Response): HtmlType {
  return response.body as HtmlType;
}

class HtmlTypeDeserializer extends JsonDeserializer<HtmlType> {
  @Override
  fun deserialize(JsonParser jp, DeserializationContext ctx) throws IOException, JsonProcessingException {
    // read contents of jp...
    return HtmlType(content)
  }
}

@JsonDeserialize(using = HtmlTypeDeserializer::class)
class HtmlType private constructor(private val content: String)

// no example in this language

# no example in this language

In the real world, it’s risky to migrate to a format from an existing enumeration. There’s often logic in the client that depends on knowledge of a specific value, and all that logic needs to be transformed into an api driven model. It’s tempting to keep it in the client, but that makes removal of the value not-backwards compatible and undocumented.

Nested nullables

A common pattern I see when designing api responses is to use a flat structure like the following.

interface Workout {
  swim_id: string | null;
  swim_miles: number | null;
  swim_time: Time | null;
  bike_id: string | null;
  bike_miles: number | null;
  bike_time: Time | null;
  run_id: string | null;
  run_miles: number | null;
  run_time: Time | null;
}

import kotlin.time.Duration;

data class Workout(
    var swim_id: String?,
    var swim_miles: String?,
    var swim_time: Duration?,
    var bike_id: String?,
    var bike_miles: Double?,
    var bike_time: Duration?,
    var run_id: String?,
    var run_miles: Double?,
    var run_time: Duration?
)

type Workout struct {
	SwimID    *string
	SwimMiles *float64
	SwimTime  *time.Duration
	BikeID    *string
	BikeMiles *float64
	BikeTime  *time.Duration
	RunID     *string
	RunMiles  *float64
	RunTime   *time.Duration
}

components:
  schemas:
    Workout:
      type: object
      properties:
        swim_id:
          type: string
          nullable: true
        swim_miles:
          type: number
          nullable: true
        swim_time:
          type: number
          nullable: true
        bike_id:
          type: string
          nullable: true
        bike_miles:
          type: number
          nullable: true
        bike_time:
          type: number
          nullable: true
        run_id:
          type: string
          nullable: true
        run_miles:
          type: number
          nullable: true
        run_time:
          type: number
          nullable: true

This leads to open questions: What happens a mix of id, miles, and time is present? Should I always expect miles to be present if id is present? How does time relate to miles?

By breaking up the flat structure these can be answered.

Here, it’s clear that an id is always paired with miles and time, and each type of activity might be missing:

interface Segment {
  id: string;
  miles: number;
  time: Time;
}

interface Workout {
  swim: Segment | null;
  bike: Segment | null;
  run: Segment | null;
}

import kotlin.time.Duration;

data class Segment(
    val id: String,
    val miles: Double,
    val time: Duration
)

data class Workout(
    var swim: Segment?,
    var bike: Segment?,
    var run: Segment?
)