DEV Community: Tim Bright

DDD: Anti-Corruption Layers for Handling Vendor Data

Tim Bright — Mon, 03 Aug 2026 17:16:41 +0000

This is an article written by Claude but guided by me. I hate a lot of the domain-driven design articles because IMO they all talk around the issue but it's never actionable (read: helpful).

Hopefully you think this is different.

The Anti-Corruption Layer in Go: One Flight Model, Many Vendors

Every airline operations system eventually integrates with something it didn't design. A legacy movement-message feed, a crew rostering package bought in 2009, a ground handler's REST API that returns "9999-12-31" when it means "unknown." Each of these ships a model of the world along with its data, and that model is almost never yours.

An anti-corruption layer (ACL) is the code that stops the vendor's model from leaking into your domain. It's a translation boundary: foreign representations in, your aggregates out, and nothing partial in between.

What you actually get from it

Three things, in order of importance:

One model instead of N. Without an ACL, STATUS_CD == "OUT" shows up in your scheduling service, your delay reporting, and your gate display logic. Now the vendor's enum is your domain vocabulary, and it will diverge from what your business actually means. With an ACL, that string is resolved to a flight.Status exactly once.

Invariants enforced at a single door. Your Flight aggregate has rules: no off-block time without an assigned tail, no delay over fifteen minutes without a reason code. An ACL makes translation go through those rules rather than around them. Foreign data becomes a candidate state that the aggregate accepts or rejects.

A named place for corruption to fail. Sentinel dates, empty strings meaning "unknown," a status code the vendor added last Tuesday — these become explicit translation errors at the edge, instead of a zero-valued time.Time quietly propagating into a delay report.

The domain, expressed on its own terms

The aggregate depends on nothing outside the standard library. That constraint is the whole design.

package flight

type Status int

const (
    Scheduled Status = iota
    OffBlocks
    Airborne
    OnBlocks
    Cancelled
)

// Flight is the aggregate root. All fields unexported: no
// caller can assemble an invalid Flight.
type Flight struct {
    id           LegID
    designator   Designator // e.g. UA 1174
    origin, dest Station
    scheduledOut time.Time // always UTC
    actualOut    *time.Time
    tail         Tail // zero until an aircraft is assigned
    delay        Delay
    status       Status
}

func (f *Flight) RecordOffBlocks(at time.Time) error {
    if f.status != Scheduled {
        return fmt.Errorf("off-blocks from status %v: %w", f.status, ErrIllegalTransition)
    }
    if f.tail.IsZero() {
        return ErrNoAircraftAssigned
    }
    f.actualOut, f.status = &at, OffBlocks
    if d := at.Sub(f.scheduledOut); d > 15*time.Minute && f.delay.reason == "" {
        return ErrDelayReasonRequired
    }
    return nil
}

The aggregate also needs a way to be reconstituted from outside state — from your own database, and from a vendor. Give it exactly one such door:

// Snapshot is inbound state awaiting validation. It is not a
// Flight; it is a request to become one.
type Snapshot struct {
    ID                LegID
    Designator        Designator
    Origin, Dest      Station
    ScheduledOut      time.Time
    ActualOut         *time.Time
    Tail              Tail
    Delay             Delay
    Status            Status
}

func Rehydrate(s Snapshot) (*Flight, error) {
    if s.ScheduledOut.IsZero() || s.ScheduledOut.Location() != time.UTC {
        return nil, ErrScheduleTimeInvalid
    }
    if s.Status >= OffBlocks && s.Status != Cancelled {
        if s.ActualOut == nil {
            return nil, ErrMissingActualOut // "OUT" with no OUT time
        }
        if s.Tail.IsZero() {
            return nil, ErrNoAircraftAssigned
        }
    }
    if s.Delay.Minutes > 15 && s.Delay.Reason == "" {
        return nil, ErrDelayReasonRequired
    }
    // ... remaining checks
    return &Flight{id: s.ID, /* ... */ status: s.Status}, nil
}

Rehydrate is what makes this a real anti-corruption layer and not just a mapper. If the translator could fill in a Flight's fields directly, it could build a flight your rules say is impossible — one already off the gate with no aircraft assigned to it. Because all it can hand over is a Snapshot, the domain gets to say no.

The port belongs to the consumer

OpsHub is the ground handler's operations platform: their system of record for flight legs, on their infrastructure, versioned on their release schedule. They ship a generated Go client for its API, and you own the adapter package that wraps that client. So when your scheduler needs one leg before reassigning an aircraft, what the vendor offers you is this — OpsHub's key in, OpsHub's record out:

// package opshubsdk — the vendor's generated client, not yours
func (c *Client) GetFlightLegV2(ctx context.Context, key string) (*legDTO, error)

Calling that from the scheduler would bind the scheduler to legDTO and to OpsHub's idea of a key. The fix is to put the interface where it is used rather than where it is implemented — the domain declares the capability it needs, in its own terms:

package flight

// Named and owned here; implemented elsewhere.
type LegRepository interface {
    Find(ctx context.Context, id LegID) (*Flight, error)
}

Go implementations don't declare which interfaces they satisfy, so opshub.Adapter can fit LegRepository without the domain ever mentioning opshub. Pin that in the adapter package, where the dependency is allowed to exist:

var _ flight.LegRepository = (*Adapter)(nil)

Dependencies now point inward — opshub imports flight, never the reverse, and flight imports only the standard library. That arrow is the mechanical difference between an ACL and a shared "types" package, and the compiler enforces it: an import ".../opshub" inside flight is a review-stopping defect. Swap ground handlers and LegRepository and every caller above it are untouched; you write one new adapter.

The foreign model, quarantined

Everything below is code you own: the opshub package is the anti-corruption layer. It holds three types with three separate jobs. legDTO mirrors the vendor's JSON exactly, warts included, and stays unexported so nothing outside the package can depend on its shape. Translator does the mapping — one legDTO in, one flight.Snapshot out, no I/O anywhere in it, which is why it's trivial to test. Adapter wires the two together and is the type that satisfies flight.LegRepository: fetch, translate, hand to the domain.

package opshub

type legDTO struct {
    LegKey   string `json:"LEG_KEY"`
    FltNbr   string `json:"FLT_NBR"`  // "1174", sometimes " 174"
    DepStn   string `json:"DEP_STN"`
    ArrStn   string `json:"ARR_STN"`
    SkdOut   string `json:"SKD_OUT"`  // naive station-local time
    ActOut   string `json:"ACT_OUT"`  // "" or "9999-12-31 00:00"
    StatusCd string `json:"STATUS_CD"`
    AcReg    string `json:"AC_REG"`
    DlyMins  int    `json:"DLY_MINS"`
    DlyRsnCd string `json:"DLY_RSN_CD"`
}

var statuses = map[string]flight.Status{
    "SKD": flight.Scheduled,
    "OUT": flight.OffBlocks,
    "OFF": flight.Airborne,
    "ON":  flight.Airborne, // wheels-on is not a state we model
    "IN":  flight.OnBlocks,
    "CNL": flight.Cancelled,
}

type Translator struct {
    zones ZoneResolver // station -> IANA time zone
}

func (t Translator) toSnapshot(d legDTO) (flight.Snapshot, error) {
    status, ok := statuses[d.StatusCd]
    if !ok {
        // Vendor enum drift. Refuse; do not guess.
        return flight.Snapshot{}, fmt.Errorf("%w: STATUS_CD %q", ErrUnmappable, d.StatusCd)
    }

    origin, err := flight.NewStation(d.DepStn)
    if err != nil {
        return flight.Snapshot{}, fmt.Errorf("DEP_STN: %w", err)
    }

    skdOut, err := t.toUTC(d.SkdOut, origin)
    if err != nil {
        return flight.Snapshot{}, fmt.Errorf("SKD_OUT: %w", err)
    }

    var actOut *time.Time
    if !isNullish(d.ActOut) { // "", "9999-12-31 00:00", "0000-00-00"
        v, err := t.toUTC(d.ActOut, origin)
        if err != nil {
            return flight.Snapshot{}, fmt.Errorf("ACT_OUT: %w", err)
        }
        actOut = &v
    }

    return flight.Snapshot{
        ID:           flight.LegID(d.LegKey),
        Origin:       origin,
        ScheduledOut: skdOut,
        ActualOut:    actOut,
        Tail:         flight.ParseTail(d.AcReg), // zero if ""
        Delay:        flight.Delay{Minutes: d.DlyMins, Reason: t.mapReason(d.DlyRsnCd)},
        Status:       status,
        // ...
    }, nil
}

// Find is the port implementation: vendor call, translation, then the domain.
func (a Adapter) Find(ctx context.Context, id flight.LegID) (*flight.Flight, error) {
    dto, err := a.client.fetchLeg(ctx, string(id))
    if err != nil {
        return nil, err
    }
    snap, err := a.translator.toSnapshot(dto)
    if err != nil {
        return nil, err
    }
    return flight.Rehydrate(snap) // domain has final say
}

Note what the ACL absorbed: naive local times and the station-to-time-zone lookup they require, whitespace in flight numbers, three spellings of null, a wheels-on state your business doesn't track, and vendor delay codes mapped to your own taxonomy. None of that is visible past the Find method's signature.

Note also what it refuses to do. An unknown STATUS_CD is not defaulted to Scheduled. A "OUT" leg with no ACT_OUT does not become an OffBlocks flight with a zero timestamp — Rehydrate rejects it. Translation is total or it fails: every foreign value either maps to a domain concept or produces an error naming the field. Silent defaulting is how vendor corruption gets into a delay-cost report, and by then the trail is cold.

Testing at the boundary

The ACL is the cheapest thing in your system to test, because it's a pure function over bytes.

Golden payloads. Keep real (scrubbed) vendor responses in testdata/ and assert the resulting Snapshot. When the vendor changes something in production, the diff shows up here first.
An unknown-code case. Assert that a novel STATUS_CD returns ErrUnmappable. This test is the one that pays for the layer.
Domain rules tested separately, with hand-built Snapshots and no vendor JSON in sight. Rehydrate and RecordOffBlocks don't know OpsHub exists.

When the payload updates an aggregate you already have

Rehydrate covers the read-through case: you hold no state of your own, so you build a Flight out of the vendor's picture of it. Movement messages are the harder case. OpsHub pushes an update for a leg you already have, and your copy holds decisions the vendor knows nothing about — the delay reason a controller keyed in, the tail your own scheduler assigned.

The tempting move is to translate the payload into a full Snapshot and Rehydrate over the top. Don't. That makes the vendor win every field, and its blanks quietly erase your data.

Translate the payload into an intention instead — a command, in domain vocabulary:

package flight

// A Command is a claim about what happened, not a new state.
type Command interface{ ApplyTo(*Flight) error }

type OffBlocksReported struct{ At time.Time }

func (c OffBlocksReported) ApplyTo(f *Flight) error {
    return f.RecordOffBlocks(c.At) // the aggregate may still refuse
}

The translator's job becomes deciding which domain command the payload represents:

package opshub

func (t Translator) toCommand(d legDTO) (flight.Command, error) {
    switch d.StatusCd {
    case "OUT":
        at, err := t.toUTC(d.ActOut, /* origin station */)
        if err != nil {
            return nil, fmt.Errorf("ACT_OUT: %w", err)
        }
        return flight.OffBlocksReported{At: at}, nil
    case "CNL":
        return flight.CancellationReported{Reason: t.mapReason(d.DlyRsnCd)}, nil
    // ...
    default:
        return nil, fmt.Errorf("%w: STATUS_CD %q", ErrUnmappable, d.StatusCd)
    }
}

Applying it belongs in your application service, not in the ACL — load from your own store, apply, save:

func (s Service) ApplyLegUpdate(ctx context.Context, id flight.LegID, cmd flight.Command) error {
    f, err := s.legs.Find(ctx, id) // s.legs is your database, not OpsHub
    if err != nil {
        return err
    }
    if err := cmd.ApplyTo(f); err != nil {
        return err
    }
    return s.legs.Save(ctx, f)
}

Three things fall out of this that a snapshot-and-overwrite approach can't give you. Vendors send partial payloads, and a command carries only what changed, so you're never forced to invent values for the fields the message omitted. Movement messages arrive late and duplicated, and a replayed "OUT" hits RecordOffBlocks on a flight that is already off blocks and comes back as ErrIllegalTransition — a rejected duplicate rather than a rewritten history. And when one payload spans two aggregates — leg movement plus a crew change — the translator emits one command each, so the vendor's message shape doesn't get to define your transaction boundaries. Each aggregate stays its own unit of consistency, which is the whole reason you drew the boundary.

That is the real job of the layer. Not moving fields between structs, but deciding what an outside system is allowed to assert about a model you own.

DDD: The Repository Pattern with Rich Domain Models

Tim Bright — Thu, 23 Jul 2026 17:11:45 +0000

This is an article written by Claude but guided by me. I hate all the explanations about combining repository pattern, domain models, and domain-driven design because IMO they all talk around the issue but it's never actionable (read: helpful).

Hopefully you think this is different.

Here's an example of the repository Pattern with rich domain models in the context of an airline's flight operations:

Most Go codebases handle persistence the same way: a struct full of exported fields, a db package that scans rows into it, and business rules scattered across handlers and services. It works, until the rules get interesting. Airline flight operations is a domain where the rules get interesting fast, so let's use it to show what two patterns each buy you — and how they meet in the DDD concept of an aggregate.

The division of labor is clean and worth stating up front. A rich domain model is about keeping the business rules inside the domain model — the flight decides whether it can depart. The Repository pattern is about how data gets loaded into that model and saved back out — without the model ever knowing where it came from. One governs behavior, the other governs movement. Confuse the two and you get models that know SQL, or repositories that make business decisions.

The anemic starting point

Here's the version you've seen a hundred times:

type Flight struct {
    ID          string
    Status      string
    Crew        []CrewAssignment
    DepartedAt  *time.Time
}

Everything is exported, so anything can do this:

flight.Status = "DEPARTED" // with zero crew assigned, at a gate, in the past

The struct is a bag of data — an anemic model. The rule "a flight cannot depart without a full crew complement" has to live somewhere else: a service, a handler, a stored procedure, or worst of all, three of those places with slight differences. Nothing in the type system stops a new teammate from writing the invalid assignment above. The business rules live outside the model — that's the disease a rich domain model cures.

Rich domain models: the rules live inside

A rich domain model inverts this. Data becomes unexported; the only way in is through methods that enforce the rules of the domain:

package flight

type Status int

const (
    Scheduled Status = iota
    Boarding
    Departed
    Cancelled
)

type Flight struct {
    id     ID
    status Status
    crew   []CrewAssignment
    events []DomainEvent
}

const minCrew = 4

// Depart is the ONLY way a flight departs.
func (f *Flight) Depart(now time.Time) error {
    if f.status != Boarding {
        return fmt.Errorf("flight %s: cannot depart from status %v", f.id, f.status)
    }
    if len(f.crew) < minCrew {
        return ErrInsufficientCrew
    }
    f.status = Departed
    f.events = append(f.events, FlightDeparted{FlightID: f.id, At: now})
    return nil
}

func (f *Flight) AssignCrew(m CrewMember) error {
    if f.status == Departed || f.status == Cancelled {
        return ErrFlightClosed
    }
    for _, c := range f.crew {
        if c.MemberID == m.ID {
            return ErrAlreadyAssigned
        }
    }
    f.crew = append(f.crew, CrewAssignment{MemberID: m.ID, Role: m.Role})
    return nil
}

What this affords you: the business rules now live inside the model, and nowhere else. Because status and crew are unexported, code outside the flight package cannot construct or mutate a Flight that violates the rules — invalid states become unrepresentable. Depart isn't a setter with validation bolted on; it's the domain operation itself, encoding the legal state machine (Scheduled → Boarding → Departed, with Cancelled reachable until departure). Ask "can this flight depart?" and there is exactly one place the answer can come from. Go gives you this almost for free: package-level encapsulation via lowercase fields is the enforcement mechanism, no annotations or frameworks required.

Note what the model deliberately knows nothing about: databases, rows, transactions. It answers what is allowed to happen; it has no opinion on how it got into memory. That second question belongs to a different pattern.

The aggregate: drawing the consistency boundary

Notice that Flight owns its []CrewAssignment. That's deliberate, and it's what DDD calls an aggregate: a cluster of objects treated as a single unit for data changes, with one entry point — the aggregate root (Flight).

The boundary is chosen by asking one question: what has to be true at save time? Whatever must hold the instant a transaction commits goes inside the aggregate; everything else stays out. "Minimum four crew before departure" must be true the moment a departed flight hits the database — there is no acceptable window where a departed flight has three crew. So the flight and its crew list must change together, and crew assignments live inside the aggregate.

By contrast, "a crew member can't work two flights the same day" spans many flights. Pulling every flight a crew member touches into one aggregate would mean one giant lock over half the schedule. So that rule is allowed to be true eventually: a domain service or an event handler detects the conflict after commit and triggers a reassignment. CrewMember itself is a separate aggregate that Flight references only by ID.

This is the real payoff of the aggregate concept: the boundary is your consistency dial. Inside the aggregate, invariants are strongly consistent — enforced in one transaction, never observable in a broken state. Across aggregates, consistency is eventual — reconciled by events, sagas, or background checks. Draw the boundary too wide and you've serialized your writes; too narrow and rules that must hold at commit time can't be enforced at all.

Two working rules fall out of this:

Outside code holds a reference only to the root. Nobody reaches into a flight and edits crew[2] directly.
The aggregate is the unit of loading and saving — which brings us to repositories.

The Repository: how aggregates get in and out of memory

If the rich model owns the rules, the repository owns the movement: it is the mechanism by which data is loaded from storage into a domain model, and by which a changed model gets back out. It presents aggregates as if they were an in-memory collection — you Get a flight, you Save a flight, and the fact that rows, documents, or a map were involved is invisible. The interface lives in the domain package, expressed purely in domain terms:

package flight

type Repository interface {
    Get(ctx context.Context, id ID) (*Flight, error)
    Save(ctx context.Context, f *Flight) error
    DepartingBetween(ctx context.Context, window TimeRange) ([]*Flight, error)
}

No *sql.DB, no column names, no ORM types. What this affords you:

Dependency inversion. The domain defines the interface; the postgres package implements it. Your business logic imports nothing from your storage layer — the arrow points the other way. This is idiomatic Go anyway: interfaces are defined by the consumer.
One repository per aggregate, operating on whole aggregates. Save persists the flight and its crew assignments in one transaction — the repository is what makes "true at save time" literally true, because the aggregate's transactional boundary becomes the database's. There is no CrewAssignmentRepository: crew assignments aren't independently addressable, and giving them their own save path would let callers commit a partial aggregate.
Testability. A memoryRepository backed by a map makes domain and application tests trivial, no database container needed.

Equally important is what the repository must not do: decide anything. It never checks crew counts or flips statuses — it faithfully moves state between storage and model. All judgment stays inside the aggregate.

The application service ties it together, and stays thin because loading is the repository's job and deciding is the model's:

func (s *OpsService) DepartFlight(ctx context.Context, id flight.ID) error {
    f, err := s.flights.Get(ctx, id)
    if err != nil {
        return err
    }
    if err := f.Depart(s.clock.Now()); err != nil {
        return err // domain said no
    }
    return s.flights.Save(ctx, f)
}

Repository loads, model decides, repository saves. Every use case reads like this, and each line stays in its lane. If you find business logic creeping into the service — or worse, into a repository implementation — it belongs on the aggregate.

The rehydration wrinkle

There's one honest tension in Go: if fields are unexported, how does the Postgres implementation rebuild a Flight from rows? Don't weaken encapsulation with setters. Instead, export a single reconstitution function from the domain package:

// Rehydrate rebuilds a Flight from persisted state.
// For repository use only; it bypasses creation rules
// because the state was already validated when written.
func Rehydrate(id ID, status Status, crew []CrewAssignment) *Flight {
    return &Flight{id: id, status: status, crew: crew}
}

It's a trust boundary, documented as such — a small price for keeping every mutation path guarded.

How the three ideas lock together

Each concept answers a different question, and each depends on the next. The rich domain model answers where do the business rules live? — inside the model, enforced by encapsulation. The aggregate answers what has to be true at save time? — it draws the line between the strongly consistent (inside, one transaction) and the eventually consistent (across boundaries, reconciled later), and names a root to guard it. The repository answers how does data get loaded into that model and saved back out? — atomically, wholesale, behind a domain-owned interface.

Skip any one and the others sag. A repository over an anemic model is just a fancy DAO — the rules still leak. A rich model without an aggregate boundary can't tell you what a transaction should contain. An aggregate without a repository gets persisted piecemeal by whatever SQL each caller writes, and the boundary evaporates at the database.

Together, in a domain like flight ops, they give you the thing that actually matters at 4 a.m. during irregular operations: a codebase where an illegal flight state is not a bug you catch in review, but a program that doesn't compile — or an error the domain hands back before anything touches the database.

Frontend Code from a Backend Perspective

Tim Bright — Tue, 26 Nov 2024 03:03:52 +0000

I don't call myself a frontend developer.

To be clear, I know how to do frontend work. I'm trying to keep myself up-to-date with all the newest ways to try to more easily put content on the browser in a performant way. I build web applications, so you have to know how to build a user-facing client to call your backend.

I would call myself a backend developer.

But I definitely wouldn't call myself a frontend developer.

People say the frontend is the "easy" work. I don't. For me, it's a special kind of hell where you have every tool available but none of the right ones. It always seemed to me that it was inevitable that frontend code always ends up in spaghetti and you have to scrap and redo it periodically.

Recently, I found a paradigm that resonates with me and I thought I'd share my thinking. It came to me from a more backend-focused perspective, but the more I think about it, I see it's just good programming practice.

"Architecture: The Lost Years"

One of the talks that influenced me the most was one Robert "Uncle Bob" Martin has that's titled "Architecture: The Lost Years".

In it, he laments how software development evolved over the last few decades:

"I call this talk 'The Lost Years' [...] because from 1993 until now we have forgotten this thing we were on the verge of learning...and do you know what drove it out of our heads? The Web. The Web was so all-consuming [...] and it drove all those ideas out of our brains for [years] and they're just now starting to come back..."

Now, I will say Uncle Bob has some hot takes. There are a lot of people that disagree with him on his version of what "clean code" is (and I'm one of them). I try not to blindly parrot his or anyone's takes, or follow them without a deeper understanding of what they're trying to say. I can't speak to this "Middle Ages of Software Architecture" that he seems to be referring to. Back in 1991 when the Web was new, I think I was just starting to write my first "Hello world" applications in C++. Compared to him and lot of others, I'm a relative n00b.

However, I have noticed that there seems to be a rift between what people say we should do, and what we actually do in practice. For example: why do most of the web app test suites I've ever seen require the web server to be running in order to run the tests?

Unless you're testing for the actual user responses being received (which can be tested independent of the business logic), there's absolutely no reason for the web server to be running. Whenever I've seen it, it's an artifact of treating the web server as the central abstraction of the application. The application then becomes a web server spidered with business logic. In order to test the code, you need to run the web server for the tests and do mock HTTP calls to it. This makes your testing unnecessarily slow because you have the web server in the middle of it.

I've seen the same thing with frontend code. In a lot of cases, you're not able to test the business logic independent of the UI. Why should I have to render the React code to test fetching data from the backend? React is a UI framework; it should never be the central abstraction for my frontend code. However, that's what it seems most frontend clients are: "React apps" instead of applications using React. It also seems that most tutorials (and even some tools!) direct you to "Reactify" all your code, further feeding into this pattern of making React the center of your application.

The "Ports and Adapters" Pattern

So how can we avoid this?

Uncle Bob's architectural recommendation in that talk is remarkably similar to the "ports and adapters" pattern for hexagonal architecture. What Uncle Bob calls the interactor object is a part of the application. It implements a specific interface that defines the functions of how the application object should be interacted with. To use the "ports and adapters" language, the interface is a port, and the interactor is an adapter.

interface Application {
  doAppFunction(): void;
}

class Interactor extends Application {
  constructor(...) { }

  public doAppFunction() {
    ...execute some application code
  }
}

This adapter can be plugged into another bit of code that uses the port, perhaps as an argument to a function or it can be dependency injected at creation time.

class UI {
   constructor(app: Application) { this.app = app; }

   someUIFunction() {
      ...

      this.app.doAppFunction();

      ... do other UI code
   }
}

This way, the UI can do application-specific functions via the Application interface but the UI code does not contain any of that code. This allows you to test the Interactor object independently from the UI, meaning you don't have to run the UI and also you don't have to run the app to do UI unit tests.

Working with React

So how would this work with React?

One way to do this is to make a React Context that holds an Application object and then just fetch the object with useContext whenever you need to interact with something outside of React:

const AppContext = createContext<Application>(undefined);

export const useApplication = () => {
  const context = useContext(AppContext);
  if (!context) {
    throw new Error("useApplication must be used within a ApplicationProvider");
  }
  return context;
};

export const ApplicationProvider = (props) => {
  const { children, value } = props;
  return <AppContext.Provider value={value}>{children}</AppContext.Provider>;
};

You can create the Interactor object just before you render your React application:

const application = new Interactor();

export const renderApp = () => {
  const root = document.getElementById("root");
  ReactDOM.createRoot(root).render(
    <React.StrictMode>
      <ApplicationProvider value={application}>
        <MyReactApp />
      </ApplicationProvider>
    </React.StrictMode>,
  );
};

Now you can use the hook in the children to get access to the Application object:

export const MyReactApp = () => {
  const app = useApplication();
  app.doAppFunction();

  return <> ... </>;
};

This pattern allows you to separate your UI from what essentially are your models and controllers. You can now work with app state and not have to bind it with React's UI state, which gives you a lot of control. However, you can still use tools like @tanstack/query to control overzealous calls to your application object.

Your Mileage May Vary

I know I'm going against the grain on this one.

I'm probably going to get a lot of comments like, "You shouldn't do that because ___ and _____, you n00b!"

And that's okay.

I don't claim to be a frontend developer.

But I will say my frontend code became a lot more simple once I started using this pattern. This same thing actually happened when I started doing this with my backend code as well. I would inject my app dependencies into my app object, and then I would inject my app object as a dependency to my REST/GraphQL/gRPC code. It abstracted a lot of the unnecessary details away and kept my concerns separate.

Try it out. You might like it.

Distribute your Go CLI tools with GoReleaser and Homebrew

Tim Bright — Fri, 01 Sep 2023 22:01:08 +0000

Cobra is awesome.

At Duro, my team and I made a sweet CLI tool that allows us to create microservices for our platform quickly and easily. The tool sets up a standard service configuration for TypeScript, linting, integration with our shared library, and specific Github Actions for pushing the service to the cloud. It's been really nice to have.

We're constantly tweaking things with it, fixing little things and changing our configurations. We decided to use GoReleaser to help us version the tool and create the binaries and publish them to Github. It's been awesome.

Until we had to distribute it.

Revisions started increasing and it was a hassle trying to make sure that you have the latest version of the tool. In the spirit of "get things done", we just had everyone download it and delete it when they were done. Not a great solution, but hey, we had more things to worry about.

Lately, I decided to take it upon myself to show this tool some love (and curry favor with my fellow devs) to try to manage versions of this tool via Homebrew. I didn't know the internals of how Homebrew worked, so I decided to dig in.

Homebrew Basics

Homebrew is a package manager that allows users to install packages through a simple interface. If you need curl and you don't have it, you can simply run brew install curl and Homebrew will fetch it. You can even specify specific versions of a package if you need.

How does Homebrew know where to get things from?

Homebrew has a list of core packages you can browse here and those are available when you type in brew install. Each of these packages has a formula, which is just a Ruby file that shows what the latest SHA is of a package and allows Homebrew to select the right binary based on your operating system. Here's an example of a formula:

class Wget < Formula
  homepage "https://www.gnu.org/software/wget/"
  url "https://ftp.gnu.org/gnu/wget/wget-1.15.tar.gz"
  sha256 "52126be8cf1bddd7536886e74c053ad7d0ed2aa89b4b630f76785bac21695fcd"

  def install
    system "./configure", "--prefix=#{prefix}"
    system "make", "install"
  end
end

The repository that this formula is stored in is called a tap. In fact, the list of core package are stored in the core tap. This is not only tap you can have; you can create your own tap.

How do I create a tap and what happens when I do?

There's standard documentation on how to create a tap.

The short version is that when you type in brew tap <tap_name> <URL>, it will go to that URL and clone the repository there and save it in $(brew --repository)/Library/Taps. Then, when you type in brew install <package>, it will search the core tap first and then any additional taps you've created. It will then look for the formula Ruby file and grab the latest package (or the version you specify) from the specified location in the formula and put it in Homebrew's path so you can access it.

How do I create a formula?

You can create one by hand, but GoReleaser can do it for you.

Here's the basic config:

brews:
  -
    # Name of the recipe
    #
    # Default: ProjectName
    # Templates: allowed
    name: some_app

    # Folder inside the repository to put the formula.
    folder: Formula

    # Your app's description.
    #
    # Templates: allowed
    description: "Put in description here."

    # Repository to push the generated files to.
    repository:
      owner: example
      name: some_app
      branch: brew-releases/{{ .Version }}
      token: "{{ .Env.GITHUB_TOKEN }}"
      pull_request:
        enabled: true
        base:
          owner: example
          name: some_app
          branch: master

    # NOTE: make sure the url_template, the token and given repo (github or
    # gitlab) owner and name are from the same kind.
    # We will probably unify this in the next major version like it is
    # done with scoop.

    # URL which is determined by the given Token (github, gitlab or gitea).
    #
    # Default depends on the client.
    # Templates: allowed
    url_template: "https://github.com/example/some_app/releases/download/{{ .Tag }}/{{ .ArtifactName }}"

    # Allows you to set a custom download strategy. Note that you'll need
    # to implement the strategy and add it to your tap repository.
    # Example: https://docs.brew.sh/Formula-Cookbook#specifying-the-download-strategy-explicitly
    download_strategy: GitHubPrivateRepositoryReleaseDownloadStrategy

    custom_require: './custom_release_strategy'

    # Git author used to commit to the repository.
    commit_author:
      name: goreleaserbot
      email: goreleaserbot@example.com

    # The project name and current git tag are used in the format string.
    #
    # Templates: allowed
    commit_msg_template: "Brew formula update for {{ .ProjectName }} version {{ .Tag }}"

Here, GoReleaser will generate the Ruby formula file for you and try to commit it into the Formula folder in this repository. In my case, we made our main branch protected so we had to specify the section that auto-creates a PR with the new formula.

We also have a Github Action that uses GoReleaser's custom action to trigger a release whenever a new tag is created in our repo. Now all one of us has to do is create a release with a new tag and the GitHub Action will prepare a release with the binaries and then auto-create the PR with the updated formula. Once it's merged in, Homebrew should take care of updating the revisions.

Then it's just the brew tap and brew install combo FTW!(You might need to have a GitHub personal access token in your HOMEBREW_GITHUB_API_TOKEN env variable).

That doesn't sound so bad! Why were you complaining about it being a pain?

Ah, that's right. The gotcha.

Homebrew uses several different methods to download/clone repos, such as CurlDownloadStrategy (which does exactly what it says).

They used to support one called GitHubPrivateRepositoryReleaseDownloadStrategy. It's exactly what the name implies: it downloads releases from GitHub private repositories. At the time I was doing my research into doing this myself, there was a good amount of documentation floating around that says to use that strategy for fun and profit.

Problem is, Homebrew no longer supports that strategy. Then GoReleaser stopped supporting it.

Screwed? Not really, thanks to some help from the community and open source software!

This comment in a GoReleaser issue showed me I can copy the old code from older versions of Homebrew and include them into my formula with GoReleaser.

I think in the end we used the recommendation made here with the code contained in this Gist link. We put that code into the same Formula folder in the repo and named it custom_release_strategy.rb. That file is pointed to in the custom_require field in the brews section and automatically includes it in the formula file so Homebrew knows how to download the packages.

Hope that helps anyone who wants to build their own CLI tool and ship it via Homebrew!

React Context with React Router v6.4

Tim Bright — Sun, 27 Nov 2022 21:16:51 +0000

I searched for a while to find how to use the Context API with createBrowserRouter. What I found is that you can use layout routes to wrap your components with the provider:

import { Outlet } from 'react-router-dom';
export default function ContextLayout() {
  return (
    <ContextProvider>
      <Outlet />
    </ContextProvider>
  );
};

Then, you can create a RouteObject without a path that renders that layout route with the children as the components you want to wrap in the provider.

import { createBrowserRouter, RouterProvider } from 'react-router-dom';
const router = createBrowserRouter([
  {
    element: <ContextLayout />,
    children: [
      {
        path: '/some/path',
        element: <SomeContextConsumer />
      }
    ]
  },
  ...
]);

export default () => {
  const rootElement = document.getElementById('root');
  const root = createRoot(rootElement!);
  root.render(
    <RouterProvider router={router} />
  );
};

That's it! Hopefully this saves someone the time it took me to figure this out.