Back to Details

migrate-to-shoehorn

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Migrate to Shoehorn

迁移至Shoehorn

Replace unsafe TypeScript 
as
assertions in test files with type-safe alternatives from 
@total-typescript/shoehorn
.
将测试文件中不安全的TypeScript 
as
断言替换为
@total-typescript/shoehorn
提供的类型安全替代方案。

When to use this skill

适用场景

  • Modernizing test code to eliminate 
    as
    type assertion anti-patterns
  • Making test data creation type-safe with autocomplete support
  • Migrating from 
    as unknown as Type
    double-assertions
  • 现代化测试代码，消除
    as
    类型断言的反模式
  • 创建具有自动补全支持的类型安全测试数据
  • 从
    as unknown as Type
    双重断言迁移

When not to use this skill

不适用场景

  • Production code (shoehorn is test code only)
  • Non-TypeScript projects
  • Runtime type validation → use a library like 
    zod
  • 生产代码（Shoehorn仅适用于测试代码）
  • 非TypeScript项目
  • 运行时类型验证 → 使用
    zod
    等库

Installation

安装

bash
npm i @total-typescript/shoehorn
bash
npm i @total-typescript/shoehorn

The three functions

三个核心函数

fromPartial<T>(partial)
— incomplete objects

fromPartial<T>(partial)
—— 不完整对象

Use when you only need a few properties of a large type:
typescript
// Before (unsafe)
const user = { name: "Alice" } as User

// After (type-safe, keeps autocomplete)
import { fromPartial } from "@total-typescript/shoehorn"
const user = fromPartial<User>({ name: "Alice" })
当你只需要大型类型中的部分属性时使用：
typescript
// 之前（不安全）
const user = { name: "Alice" } as User

// 之后（类型安全，保留自动补全）
import { fromPartial } from "@total-typescript/shoehorn"
const user = fromPartial<User>({ name: "Alice" })

fromAny<T>(value)
— intentionally wrong data

fromAny<T>(value)
—— 故意构造的错误数据

Use when testing with deliberately incorrect data (error cases, edge cases):
typescript
// Before (verbose double-as)
const badInput = { invalid: true } as unknown as User

// After
import { fromAny } from "@total-typescript/shoehorn"
const badInput = fromAny<User>({ invalid: true })
在测试错误场景、边缘场景等需要使用刻意构造的错误数据时使用：
typescript
// 之前（冗长的双重断言）
const badInput = { invalid: true } as unknown as User

// 之后
import { fromAny } from "@total-typescript/shoehorn"
const badInput = fromAny<User>({ invalid: true })

fromExact<T>(complete)
— enforced complete objects

fromExact<T>(complete)
—— 强制要求完整对象

Use when the test requires a fully-specified object (no missing fields):
typescript
// Before
const user = { name: "Alice", email: "alice@example.com", id: 1 } as User

// After (TypeScript will error if any field is missing)
import { fromExact } from "@total-typescript/shoehorn"
const user = fromExact<User>({ name: "Alice", email: "alice@example.com", id: 1 })
当测试需要完全指定的对象（无缺失字段）时使用：
typescript
// 之前
const user = { name: "Alice", email: "alice@example.com", id: 1 } as User

// 之后（若缺失任何字段，TypeScript会报错）
import { fromExact } from "@total-typescript/shoehorn"
const user = fromExact<User>({ name: "Alice", email: "alice@example.com", id: 1 })

Migration workflow

迁移流程

1. Find all 
as
assertions in test files

1. 查找测试文件中所有
as
断言

bash
grep -rn " as " --include="*.test.ts" --include="*.spec.ts" --include="*.test.tsx"
bash
grep -rn " as " --include="*.test.ts" --include="*.spec.ts" --include="*.test.tsx"

2. Classify each assertion

2. 对每个断言进行分类

  • Partial object, only some fields needed → 
    fromPartial()
  • Intentionally wrong/invalid data → 
    fromAny()
  • Complete object, all fields present → 
    fromExact()
  • 仅需部分字段的不完整对象 → 使用
    fromPartial()
  • 故意构造的错误/无效数据 → 使用
    fromAny()
  • 包含所有字段的完整对象 → 使用
    fromExact()

3. Replace and add import

3. 替换断言并添加导入语句

typescript
import { fromPartial, fromAny, fromExact } from "@total-typescript/shoehorn"
typescript
import { fromPartial, fromAny, fromExact } from "@total-typescript/shoehorn"

4. Verify TypeScript still compiles

4. 验证TypeScript仍可正常编译

bash
npx tsc --noEmit
bash
npx tsc --noEmit

Critical constraint

关键约束

Test code only. Never use 
fromPartial
, 
fromAny
, or 
fromExact
in production code. These functions bypass type safety for testing purposes only.
仅适用于测试代码。切勿在生产代码中使用
fromPartial
、
fromAny
或
fromExact
。这些函数仅为测试目的而绕过类型安全。

Instructions

操作步骤

  1. Identify the task trigger and expected output.
  2. Follow the workflow steps in this skill from top to bottom.
  3. Validate outputs before moving to the next step.
  4. Capture blockers and fallback path if any step fails.
  1. 识别任务触发条件和预期输出。
  2. 从上到下遵循本技能中的流程步骤。
  3. 进入下一步前验证输出结果。
  4. 记录任何阻塞问题及备用方案（若某步骤失败）。

Examples

示例

  • Example: Apply this skill to a small scope first, then scale to full scope after validation passes.
  • 示例：先在小范围内应用本技能，验证通过后再扩展至全范围。

Best practices

最佳实践

  • Keep outputs deterministic and auditable.
  • Prefer small reversible changes over broad risky edits.
  • Record assumptions explicitly.
  • 确保输出结果可预测且可审计。
  • 优先选择小范围、可回滚的变更，而非大范围、高风险的编辑。
  • 明确记录假设条件。

References

参考资料

  • Project standards: 
    .agent-skills/skill-standardization/SKILL.md
  • Validator script: 
    .agent-skills/skill-standardization/scripts/validate_skill.sh
  • 项目标准：
    .agent-skills/skill-standardization/SKILL.md
  • 验证脚本：
    .agent-skills/skill-standardization/scripts/validate_skill.sh