{"id":12212,"library":"type-samurai","title":"type-samurai","description":"`type-samurai` is a TypeScript library offering a collection of advanced utility types designed to extend TypeScript's native type manipulation capabilities. Currently at version 1.1.1, the package provides types for arithmetic operations (e.g., `Sum`), logical statements (`If`, `And`, `Or`), string manipulations, and type introspection (`IsAny`, `IsUnknown`, `IsNever`). It differentiates itself by providing complex, often recursive, type-level computations that are not available in the standard TypeScript utility types. While there's no explicit release cadence mentioned, the library appears to be actively maintained, providing a robust toolkit for highly intricate type-safe programming patterns. This library is entirely focused on compile-time type checking and does not include any runtime code, making it a zero-runtime dependency.","status":"active","version":"1.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/KamilHs/type-samurai","tags":["javascript","typescript","types","ts","math","arithmetics","color","generics","utilities"],"install":[{"cmd":"npm install type-samurai","lang":"bash","label":"npm"},{"cmd":"yarn add type-samurai","lang":"bash","label":"yarn"},{"cmd":"pnpm add type-samurai","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This library exports only types. Always use `import type` to avoid runtime errors or unnecessary imports.","wrong":"import { Sum } from 'type-samurai'","symbol":"Sum","correct":"import type { Sum } from 'type-samurai'"},{"note":"CommonJS `require` syntax is not supported as this is a type-only module for ESM environments, primarily used for compile-time type checking.","wrong":"const If = require('type-samurai')","symbol":"If","correct":"import type { If } from 'type-samurai'"},{"note":"For optimal performance and clarity, prefer named type imports over namespace imports when only a few specific types are needed.","wrong":"import * as TypeSamurai from 'type-samurai'","symbol":"IsAny","correct":"import type { IsAny } from 'type-samurai'"}],"quickstart":{"code":"import type { Sum, IfExtends, IsNever, ReturnItselfIfExtends } from 'type-samurai';\n\n// Example 1: Type-level arithmetic\ntype Total = Sum<123, 456>; // Evaluates to 579\n// console.log(Total); // This is a type, not a runtime value\n\n// Example 2: Conditional types\ntype ResultBasedOnExtension = IfExtends; // 'Is String'\ntype AnotherResult = IfExtends; // 'Not String'\n\n// Example 3: Type introspection\ntype CheckNever = IsNever<'hello'>; // false\ntype CheckNeverActual = IsNever; // true\n\n// Example 4: Returning itself conditionally\ntype MyType = ReturnItselfIfExtends<{ a: string }, object, { a: string }>; // { a: string }\ntype FallbackType = ReturnItselfIfExtends; // 'Not an object'\n\n// These operations are purely compile-time. There is no runtime JavaScript code generated.","lang":"typescript","description":"Demonstrates type-level arithmetic, conditional type evaluation, and type introspection, showcasing the library's compile-time utility without generating runtime code."},"warnings":[{"fix":"Refactor complex type logic into smaller, composable types. Consider if the complexity is truly necessary or if a simpler runtime check could suffice.","message":"Extremely complex or deeply recursive type computations using `type-samurai` utilities can lead to TypeScript compiler errors like 'Type instantiation is excessively deep and possibly infinite' (error TS2589) or 'Expression produces a union type that is too complex to represent' (error TS2590).","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Monitor compilation times. Use these advanced types judiciously for critical type safety needs rather than for every minor type manipulation. Consider creating simpler type aliases for common patterns.","message":"While `type-samurai` is zero-runtime, heavy usage of its advanced types can significantly increase TypeScript compilation times, especially in large codebases.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Always consult the library's GitHub releases or `package.json`'s `peerDependencies` (if any) for the officially supported TypeScript version. Pin your TypeScript version to avoid unexpected breaking changes in type inference.","message":"As a library heavily relying on advanced TypeScript features, `type-samurai` may introduce breaking changes or require specific minimum TypeScript versions for full functionality due to changes in TypeScript's type system.","severity":"breaking","affected_versions":">=1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Simplify the type arguments passed to `type-samurai` utilities, or break down a single complex type into multiple intermediate types. Increase TypeScript's `maxNodeModuleJsDepth` (though this is often a band-aid).","cause":"Too many recursive type evaluations or very deep generic type instantiations.","error":"Type instantiation is excessively deep and possibly infinite. (2589)"},{"fix":"Restructure the types to produce less expansive union types. Consider if the full range of values needs to be strictly typed at compile-time or if some runtime checks are more appropriate.","cause":"The resulting union type from a `type-samurai` operation (especially with large number types or string manipulations) exceeds TypeScript's internal complexity limits.","error":"Expression produces a union type that is too complex to represent. (2590)"},{"fix":"Ensure `type-samurai` is installed using `npm install --save-dev type-samurai`, and `tsconfig.json` includes `node_modules` in its `include` or `files` array, or that `typeRoots` is correctly configured if custom paths are used.","cause":"The package was likely installed without `--save-dev` or TypeScript is not configured to include `node_modules/@types` or the library's own type declarations.","error":"Cannot find module 'type-samurai' or its corresponding type declarations. (2307)"}],"ecosystem":"npm"}