migrate-to-shoehorn

Migrate to Shoehorn (Migrate to Shoehorn)

Why use shoehorn?

shoehorn lets you pass partial data in tests while maintaining TypeScript type safety. It replaces as assertions with a type-safe alternative.

shoehorn lets you pass partial data in tests while keeping TypeScript happy. It replaces as assertions with type-safe alternatives.

Test code only. Never use shoehorn in production code.

Test code only. Never use shoehorn in production code.

Using as in tests has these problems:

Problems with as in tests:

• is trained not to use it

  Trained not to use it

• must manually specify the target type

  Must manually specify target type

• requires double as for intentionally wrong data (as unknown as Type）

  Double-as (as unknown as Type) for intentionally wrong data

Install (Install)

npm i @total-typescript/shoehorn

Migration patterns (Migration patterns)

Large objects with many properties but only a few needed

Before:

Before:

type Request = {
  body: { id: string };
  headers: Record<string, string>;
  cookies: Record<string, string>;
  // ...20 more properties
};

it("gets user by id", () => {
  // Only care about body.id but must fake entire Request
  getUser({
    body: { id: "123" },
    headers: {},
    cookies: {},
    // ...fake all 20 properties
  });
});

After:

After:

import { fromPartial } from "@total-typescript/shoehorn";

it("gets user by id", () => {
  getUser(
    fromPartial({
      body: { id: "123" },
    }),
  );
});

as Type → fromPartial()

Before:

Before:

getUser({ body: { id: "123" } } as Request);

After:

After:

import { fromPartial } from "@total-typescript/shoehorn";

getUser(fromPartial({ body: { id: "123" } }));

as unknown as Type → fromAny()

Before:

Before:

getUser({ body: { id: 123 } } as unknown as Request); // wrong type on purpose

After:

After:

import { fromAny } from "@total-typescript/shoehorn";

getUser(fromAny({ body: { id: 123 } }));

When to use each function (When to use each)

Function	Use case
fromPartial()	Pass partial data that still passes type checking
fromAny()	Pass intentionally wrong data (preserves autocomplete)
fromExact()	Enforce complete objects (can later be swapped for fromPartial)

Function	Use case
fromPartial()	Pass partial data that still type-checks
fromAny()	Pass intentionally wrong data (keeps autocomplete)
fromExact()	Force full object (swap with fromPartial later)

Workflow (Workflow)

1. Gather requirements - Ask the user:

   Gather requirements - ask user:

   • Which test files have problematic as assertions?

     What test files have as assertions causing problems?

   • Are you dealing with large objects where only some properties matter?

     Are they dealing with large objects where only some properties matter?

   • Do you need to pass intentionally wrong data for error tests?

     Do they need to pass intentionally wrong data for error testing?

2. Install and migrate：

   Install and migrate:

   • Install:npm i @total-typescript/shoehorn

     Install: npm i @total-typescript/shoehorn

   • Find test files with as assertions:grep -r " as [A-Z]" --include="*.test.ts" --include="*.spec.ts"

     Find test files with as assertions: grep -r " as [A-Z]" --include="*.test.ts" --include="*.spec.ts"

   • Replace as Type with fromPartial()

     Replace as Type with fromPartial()

   • Replace as unknown as Type with fromAny()

     Replace as unknown as Type with fromAny()

   • From @total-typescript/shoehorn add imports

     Add imports from @total-typescript/shoehorn

   • Run type checking to verify

     Run type check to verify