shoehorn
Shoehorn is a TypeScript testing utility that allows developers to pass incomplete (partial) objects to functions expecting complete types, eliminating the need for unsafe `as` type assertions. It provides type-safe primitives for legacy codebases and third-party library integration where refactoring full types is impractical.
Key facts
Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.
| Field | Value |
|---|---|
| Repository | total-typescript/shoehorn |
| Owner | total-typescript |
| Primary language | TypeScript |
| License | MIT — OSI-approved |
| Stars | 602 |
| Forks | 12 |
| Open issues | 10 |
| Latest release | v0.1.0 (2023-04-11) |
| Last updated | 2026-06-08 |
| Source | https://github.com/total-typescript/shoehorn |
What shoehorn is
A lightweight TypeScript library exposing three functions—`fromPartial()` for deep partial objects, `fromAny()` for untyped pass-through with autocomplete, and `fromExact()` for enforcing complete type coverage. It leverages TypeScript's type system to provide compile-time safety while working around structural typing constraints in test scenarios.
Get the shoehorn source
Clone the repository and explore it locally.
git clone https://github.com/total-typescript/shoehorn.gitcd shoehorn# follow the project's README for install & configurationNeed it deployed, integrated, or customized instead? DEV.co ships production installs.
Best use cases
Implementation considerations
- Shoehorn requires TypeScript 4.x+; verify compatibility with your project's TypeScript version.
- Use `fromPartial()` as default; reserve `fromAny()` for genuinely untypeable scenarios to maintain type safety benefits.
- Consider `fromExact()` as a stepping stone—enable it during refactoring to catch incomplete type specifications gradually.
- Document why `fromPartial()` is used in test files; this flags potential type design issues for future refactoring.
- Pair with a linter rule (e.g., ESLint) to prevent `as` assertions in test files, reinforcing shoehorn adoption.
When to avoid it — and what to weigh
- Greenfield Project with Clean Type Design — If your codebase uses well-designed, minimal types that require only the fields a function actually uses, shoehorn adds unnecessary abstraction—refactor types instead.
- Type System as Primary Documentation — Overusing partial mocks obscures what data a function truly requires; if type clarity is critical to your project, enforce complete object construction.
- Production Code (Not Tests) — Shoehorn is explicitly designed for tests. Using it in production code indicates a type design problem that should be addressed at the source.
- High-Security Contexts — In security-sensitive workflows where exhaustive type validation is required (e.g., payment processing), partial object construction increases risk of missing required fields.
License & commercial use
MIT License. Permissive OSI-approved license allowing commercial use, modification, and distribution with attribution.
MIT license permits unrestricted commercial use, including in proprietary applications. No commercial restrictions or warranty disclaimers beyond standard MIT terms. No license review required for commercial deployment.
DEV.co evaluation signals
Editorial assessment — not user reviews. Directional, with an explicit confidence level.
| Signal | Assessment |
|---|---|
| Maintenance | Active |
| Documentation | Strong |
| License clarity | Clear |
| Deployment complexity | Low |
| DEV.co fit | Good |
| Assessment confidence | High |
Shoehorn does not validate or sanitize data; it only relaxes type constraints for testing. No novel security risks introduced. Ensure incomplete test objects do not obscure missing validation logic in code under test. Not intended for cryptographic, credential, or sensitive data handling in tests.
Alternatives to consider
Raw `as` assertions
No type safety; widely discouraged. Shoehorn improves on this by catching structural mismatches at compile time.
Builder pattern / test factories
Explicit and maintainable but adds boilerplate per type. Best for complex objects; shoehorn is lighter-weight for simple partials.
ts-mockito / jest.mock()
Behavior mocking libraries; solve a different problem (function call tracking). Shoehorn is for object construction, not mocking behavior.
Build on shoehorn with DEV.co software developers
If your team is wrestling with deeply nested types and unsafe `as` assertions in tests, shoehorn can streamline test construction. Contact us to discuss integration into your codebase.
Talk to DEV.coRelated on DEV.co
Explore the category and the services that help you build with it.
shoehorn FAQ
Should I use `fromPartial()` or `fromAny()`?
Will this encourage bad test design?
Does shoehorn have runtime overhead?
Is this compatible with my test framework?
Work with a software development agency
DEV.co helps companies turn open-source tools like shoehorn into production software. Our software development services cover the full lifecycle — architecture, web development, integration, and maintenance — delivered by software developers and web developers who ship. Engage our software development agency to implement or customize it for your open-source testing stack.
Ready to reduce test boilerplate?
If your team is wrestling with deeply nested types and unsafe `as` assertions in tests, shoehorn can streamline test construction. Contact us to discuss integration into your codebase.