Node.js Backend Refactor Case Studies · Remote Since Forever

Upgrading TypeORM 0.3 to 1.0 in Production: A NestJS Case Study

2026-08-17T11:00:00+02:00

A backend service I work on runs on TypeORM. Earlier this year we jumped from 0.x to the new 1.0 release. The old line had gone almost five years without a breaking change, and a class of quietly-wrong-answer bugs had piled up in it: queries that returned bad data instead of raising an error. The 1.0 release fixes them by making the bad queries fail loudly instead. It also forced an @nestjs/typeorm upgrade at the same time, since the NestJS glue layer for TypeORM crashes at startup on the new TypeORM if you are still on the old version. But the catch with any major ORM upgrade is that every entity, every query builder, every database factory in the test suite gets touched.

The team had two constraints. "Do not block the rest of the work" and "do not break production." On a service that deploys every day, with a long backlog of feature work that the product team had committed to, an upgrade that needed the whole team to stop and migrate together would have been the wrong shape. We had to find the order that let the migration happen alongside the feature work, with the test suite green at every commit and production unaware that anything had changed.

The order we ended up with: a staging branch that absorbed the breaking changes, the test-harness migration ahead of the runtime, the Docker image pinned in parallel, and the eight or so smaller follow-ups that landed after the main upgrade so nobody had to read a five-thousand-line PR.

Two terms before we go further

TypeORM is a TypeScript ORM for SQL databases. It maps decorated TypeScript classes to tables and gives you a query builder, an entity manager, and a migration runner. The 0.x to 1.0 upgrade is the kind of release that touches every file in the codebase that talks to the database.
Test harness, in this post, is the infrastructure around the test suite: the factories that build entities, the per-test database setup and teardown, the mocked services, the rate-limit mocks, the fixtures. None of it ships to production. All of it has to be green for CI to pass.

Four places the upgrade broke

The breaking surface on the upgrade landed in four places.

Factory APIs. TypeORM's setSeederFactory shape changed. Every factory we had (about thirty of them, one per major entity) needed a new signature.

Repository methods. A handful of methods that had a "first one wins" behaviour in 0.x became "explicit single or throw" in 1.0. findOne() without an options argument is no longer valid; you have to pass findOne({ where: { id } }) or use findOneBy({ id }). This was a global codemod.

Entity manager transactions. The transaction API tightened. Some callsites that had been relying on implicit transaction propagation needed explicit manager.withRepository(...) calls.

Decorator metadata. @PrimaryGeneratedColumn got stricter about its options. A handful of entities with custom configurations needed a small rewrite.

None of those were hard individually. All four at once, on a codebase with hundreds of entities, was the upgrade.

The order we ran it in

Three pieces of work, three landing windows, one merge to main. The Docker base spent a week proving itself inert, the test harness landed while the runtime was still on 0.x, and the runtime upgrade lived on a staging branch long enough for every feature PR to rebase onto it.

Each step below has its own commit (or branch) and was reviewable on its own.

One. Pin the new Docker image and Node version on a parallel branch.

TypeORM 1.0 requires Node 22. Our production image was on Node 20. Before any code changed, the new image had to be built and tested. We landed Node 22.17.1 + production stage yarn setup for typeorm@1.0.0 as the first commit on the upgrade branch:

# Dockerfile (shortened)
FROM node:22.17.1-bookworm-slim AS builder
WORKDIR /app
COPY package.json yarn.lock .yarnrc.yml ./
COPY .yarn .yarn
RUN yarn install --immutable

FROM node:22.17.1-bookworm-slim AS production
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY . .
RUN yarn install --immutable --production
CMD ["node", "dist/server.js"]

The build target uses the production-stage yarn setup because the new TypeORM brings transitive dependencies that the old --immutable flag was tolerant of and the new one is not. We ran the new image against the old code for a week in staging to make sure the runtime change itself was inert.

Two. Migrate the test harness before the runtime.

This is the step that decided whether the upgrade would block the team or not. The test harness is what runs in CI on every PR. If the test harness is half-migrated, nobody can ship anything. So the test harness goes first, in its own PR, with the old TypeORM still in production:

// database/factories/address.factory.ts (before)
import { define } from "typeorm-seeding";
import { Address } from "../../modules/address/address.entity";

define(Address, (faker) => {
  const address = new Address();
  address.street = faker.location.street();
  address.city = faker.location.city();
  return address;
});

// database/factories/address.factory.ts (after)
import { setSeederFactory } from "typeorm-extension";
import { Address } from "../../modules/address/address.entity";

export default setSeederFactory(Address, (faker) => {
  const address = new Address();
  address.street = faker.location.street();
  address.city = faker.location.city();
  return address;
});

About thirty factories, all the same shape, all migrated in one commit. We landed the test harness work as a series of "complete TypeORM 1.0 test-harness migration" commits. Runtime was still on 0.x, test setup was ready for 1.0. The two coexisted because the factories are dev-time only.

Three. Bump the runtime on a staging branch.

The actual package.json change. Roughly fifteen lines changed in the manifest, a hundred or so callsites changed across the source for the findOne → findOneBy codemod and the transaction-API tightening. We landed it on a staging branch that lived for about a week.

{
  "dependencies": {
    "typeorm": "^1.0.0",
    // ... transitive updates for things that wanted Node 22
  }
}

During that week, every other PR rebased onto the staging branch as it was merged. Conflicts happened (entity decorators and query builders both got touched), but they stayed bounded. We had a Slack channel for "my PR is breaking on the staging rebase, who else has touched this file" and it never had more than one or two messages a day.

Four. Fix the small tests that quietly broke.

Once the runtime was on 1.0, a small set of tests broke for reasons the code diff itself did not show. The framework was behaving slightly differently now, and the tests were catching it. A rate-limit mock had assumed the old library called it at one specific moment; the new library called it a moment later. A recaptcha mock had relied on a method name that had been renamed. Some test suites we had not touched in a long time were quietly assuming old data-object shapes and stopped compiling once the underlying types changed.

We landed these as a series of small commits with names like "test: align auth assertions and complete rate-limit mock" and "test: fix constructor drift in the compile-failing test suites." Each one was a few hours of work and a small PR. Nothing dramatic.

Five. Ship the security fixes we had queued up.

This one was a bonus. The TypeORM upgrade gave us a single PR window where every service was already being touched. We pulled in a handful of unrelated security findings (bugs where an attacker could swap in another user's ID, and write endpoints that let one user modify another user's data) and shipped them in the same staging branch. "While we are in here" is a real shipping pattern; we used it once, deliberately, on the boundary the upgrade had opened anyway.

Two conflicts we planned for and didn't need

Two conflicts I want to call out because they are the ones I was expecting and did not get.

Production rollback. We had a plan. The plan was "deploy the new image, watch the error rate, roll back if anything spikes." We did not need it. The week of staging burn-in caught everything that would have spiked.

Migration runner. TypeORM 1.0 has a different migrations API than 0.x. We were prepared to rewrite our migration files. We did not need to. The existing migrations are run-once historical records that the new runner reads cleanly without changes. The new migrations going forward use the new API, but the catalogue of historical migrations is untouched.

What we'd do again on the next one

Test harness first, runtime second. If the harness is broken, every other PR is blocked. If the runtime is broken, only the upgrade PR is blocked.
Pin the new base image on a parallel branch. Node version upgrades that come bundled with the main one should be tested as their own change before the code change lands on top.
Codemod the global API changes in one commit. findOne() → findOneBy() is hundreds of callsites. One mechanical commit beats fifty thoughtful ones.
Keep the staging branch alive for a week. Let other PRs rebase onto it. The conflicts are real but they are bounded if the staging branch is fresh.
Pull in the "while we are in here" fixes deliberately. Big PRs are scary, but a major version upgrade is the one PR window where every file gets touched anyway. The marginal cost of an extra security fix is much lower in that window than in any other.

Splitting a Mega-Service Into Four: The Service-Facade Refactor (Plus a Reusable Skill)

2026-08-05T11:00:00+02:00

On a backend I work on, user.service.ts had crossed 1,307 lines. Nobody on the team could hold the whole file in their head. New hires bounced off it on day one. Reviews took twice as long because the reviewer did not remember the surrounding code the diff was sitting in, and the blame view was a quilt of contributors going back years.

We split the file into four sub-services behind a stable facade, landed the whole thing in one PR without changing a test, and wrote the procedure up as a reusable Claude skill for the next time.

Two terms before we go further

Facade, in this post, is a class that exposes the same public methods as the old service did, but delegates each method to the right one of the new sub-services. The old import path keeps working; the internal shape moves.
Sub-service is one of the new files the mega-service is split into. Each sub-service owns one slice of responsibility (querying, mutating, membership-state, stats) and is named after that slice.

The split we shipped

src/modules/user/
├── user.service.ts                   #  facade — was 1,307 lines, now ~120
├── user-query.service.ts             #  349 lines — read paths
├── user-mutation.service.ts          #  460 lines — write paths
├── user-membership.service.ts        #  288 lines — membership-state changes
├── user-stats.service.ts             #  307 lines — derived counts and aggregates
└── user.service.password-reset.spec.ts

The split ran along responsibility inside the service layer, not up through the controller and model layers. Reading a user and updating a user are different jobs on the same domain object, and they grow at different rates. On this service, the read methods stayed small and stable while the write methods kept picking up business rules.

Query — anything that returned a user (or a list of users) without mutating state. findById, findByEmail, findByCompany, searchByKeyword. The query service does not write.

Mutation — anything that wrote a user row (create, update, updatePreferences, softDelete, restore). The mutation service loads a row, mutates it, saves it.

Membership — methods that flip the user's membership state: upgrade tier, downgrade tier, transfer membership, attach to company, detach from company. The state transitions are tangled enough to justify their own file.

Stats — derived counts and aggregates. "How many users in this company are active," "how many memberships expire this month," "how many users by role." Reading across many rows is a different job from finding a single user.

A few methods did not fit any of the four. Some were doing two things and got split before they moved. Some were orchestration — they touched two or more sub-services in a single flow — and stayed on the facade.

The facade — keep the public API stable

The facade is the file every other module imports. Its surface area is identical to the old service: every method other modules called still exists, with the same signature.

// user.service.ts — the facade, after the split
@Service()
export class UserService {
  constructor(
    private readonly query: UserQueryService,
    private readonly mutation: UserMutationService,
    private readonly membership: UserMembershipService,
    private readonly stats: UserStatsService,
  ) {}

  // ─── Read methods delegate to query ─────────────────────────────────
  findById = this.query.findById.bind(this.query);
  findByEmail = this.query.findByEmail.bind(this.query);
  findByCompany = this.query.findByCompany.bind(this.query);
  searchByKeyword = this.query.searchByKeyword.bind(this.query);

  // ─── Write methods delegate to mutation ─────────────────────────────
  create = this.mutation.create.bind(this.mutation);
  update = this.mutation.update.bind(this.mutation);
  updatePreferences = this.mutation.updatePreferences.bind(this.mutation);
  softDelete = this.mutation.softDelete.bind(this.mutation);
  restore = this.mutation.restore.bind(this.mutation);

  // ─── Membership ─────────────────────────────────────────────────────
  upgradeMembership = this.membership.upgrade.bind(this.membership);
  downgradeMembership = this.membership.downgrade.bind(this.membership);
  attachMemberToCompany = this.membership.attachToCompany.bind(this.membership);

  // ─── Stats ──────────────────────────────────────────────────────────
  countActiveByCompany = this.stats.countActiveByCompany.bind(this.stats);
  countExpiringMemberships = this.stats.countExpiringMemberships.bind(this.stats);

  // ─── Orchestration methods stay here ────────────────────────────────
  // Methods that genuinely coordinate across two or more sub-services.
  async passwordResetFlow(email: string, newPassword: string) {
    const user = await this.query.findByEmail(email);
    if (!user) return { success: false };

    await this.mutation.updatePassword(user.id, newPassword);
    await this.stats.recordSecurityEvent(user.id, "password-reset");
    return { success: true };
  }
}

The bind-and-assign shape looks unusual on first read, but each method on the facade is the same function object as the one on the sub-service — no wrapper indirection, no extra logging. userService.findById(42) runs with the same overhead it always had.

Orchestration methods stay on the facade because they touch several sub-services in one flow. passwordResetFlow above hits the query, mutation, and stats services in sequence, so it belongs to none of them alone.

How the split landed in one PR

The PR added around sixteen hundred lines and deleted around twelve hundred. Most of it was file moves. The tests did not need to change: because the facade's public API is byte-identical to the old service, every test that imported UserService kept passing untouched. That is the safety net the whole refactor rides on.

Three disciplines made the PR reviewable.

One sub-service per commit. Four code commits, one per sub-service, plus a fifth that thins the facade. The reviewer reads one sub-service at a time.

Method-by-method migration. Each method moved with its tests. If a test in the suite was targeting a single method, that test stayed near the method, in the same commit as the move.

No behavioural changes. Every method moved is byte-identical to what was in the old service. Behavioural refactors — N+1 fixes, added logging, tighter authorization — go in follow-up PRs after the split lands.

The reusable skill — `service-facade-refactor`

The skill file lives at .claude/skills/service-facade-refactor/SKILL.md in this codebase and in our internal skill library. The next mega-service does not need to re-derive any of this.

A Claude skill is a small Markdown file documenting a reusable procedure in enough detail that an LLM-assisted contributor can apply it without having lived through the original work.

The skill in full:

# Service Facade Refactor

A pattern for splitting a single mega-service file into multiple
responsibility-tagged sub-services behind a stable public facade,
without breaking any caller.

## When to use this skill

A single service file has crossed roughly 800 lines, the team is
avoiding it on PRs, and the file mixes more than one of:
read paths, write paths, state-machine transitions, derived stats.

If the file is large but coherent (one responsibility, just verbose),
this is not the right skill — use a method-extraction refactor instead.

## Inputs

- The mega-service file (path).
- The full test suite (must be green before starting).
- One hour of uninterrupted reading time, before any code moves.

## Steps

1. **Tag every method on the existing service.** Read top-to-bottom.
   Each method gets exactly one tag:
   - **Read** — returns the entity, no writes.
   - **Write** — mutates the entity, may read first.
   - **State machine** — tier upgrades, status transitions, lifecycle.
   - **Stats** — counts, aggregates, derived values across many entities.
   - **Orchestration** — coordinates across two or more of the above.

   If a method does not fit one tag, it is doing two things; split
   the method *before* you split the service.

2. **Each non-orchestration tag becomes a sub-service.**
   File naming: `<domain>-<tag>.service.ts`. Example: `user-query.service.ts`.

3. **Move methods one tag at a time, in their own commit, with
   their tests.** The test file moves with the method, or, if the
   tests are integration-style, stay in place and reference the
   sub-service through the facade.

4. **Rewrite the original service file as a facade.**
   - For each method on a sub-service, `bind`-and-assign on the facade:
     `findById = this.query.findById.bind(this.query);`
   - For orchestration methods (touch two or more sub-services), keep
     the implementation on the facade.

5. **Run the full test suite. It should pass with no test changes.**
   The facade's public API is byte-identical to the original service.

6. **Land as a single PR with one commit per sub-service plus one
   for the facade.** Behavioural changes (N+1 fixes, new logging,
   tightened authz) are *follow-up PRs*, not part of the split.

## Output shape

- One facade file, exposing the same methods the original did.
- Four (or fewer) sub-service files, each named by its tag.
- Zero test changes.
- A single PR, multi-commit, readable one sub-service at a time.

## What this is not

- Not a layered split (controller / service / model). The split is
  by responsibility within the service layer, not by layer.
- Not a behavioural change. Save the perf and authz fixes for after.
- Not appropriate for files under ~500 lines. The overhead of the
  split is worse than the readability win at that size.

Step 1 is where the split gets decided. The tagging walks top-to-bottom on five yes/no questions, and the first "yes" wins.

First "yes" wins. A method that answers no to all five is doing two things and needs to be split before it is moved.

The skill works across codebases because it does not name a specific domain. Any TypeScript codebase with service classes and a mega-service problem can apply it the same way.

The judgement calls in the skill took longer to write than the steps. The "if the file is large but coherent, this is not the right skill" line at the top and the "what this is not" section at the bottom are what keep the skill from getting misapplied. A skill that only describes the happy path gets used wrong the first time somebody reaches for it.

The next mega-service on this codebase — finance.service.ts, around eleven hundred lines — is queued up for the same treatment.

Node.js Backend Refactor Case Studies · Remote Since Forever

Upgrading TypeORM 0.3 to 1.0 in Production: A NestJS Case Study

Two terms before we go further

Four places the upgrade broke

The order we ran it in

Two conflicts we planned for and didn't need

What we'd do again on the next one

Splitting a Mega-Service Into Four: The Service-Facade Refactor (Plus a Reusable Skill)

Two terms before we go further

The split we shipped

The facade — keep the public API stable

How the split landed in one PR

The reusable skill — service-facade-refactor

The reusable skill — `service-facade-refactor`