{"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<string, string | number, 'Is String', 'Not String'>; // 'Is String'\ntype AnotherResult = IfExtends<number, string, 'Is String', 'Not String'>; // 'Not String'\n\n// Example 3: Type introspection\ntype CheckNever = IsNever<'hello'>; // false\ntype CheckNeverActual = IsNever<never>; // true\n\n// Example 4: Returning itself conditionally\ntype MyType = ReturnItselfIfExtends<{ a: string }, object, { a: string }>; // { a: string }\ntype FallbackType = ReturnItselfIfExtends<null, object, 'Not an object'>; // '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,"search_vec":"'1.1.1':30 'activ':88 'advanc':15 'appear':85 'arithmet':36,132 'avail':68 'cadenc':81 'capabl':26 'check':112 'code':119 'collect':13 'color':133 'compil':109 'compile-tim':108 'complex':58 'comput':64 'current':27 'depend':126 'design':18 'differenti':54 'e.g':38 'entir':105 'explicit':79 'extend':20 'focus':106 'generic':134 'high':95 'includ':116 'intric':96 'introspect':49 'isani':50 'isnev':52 'isunknown':51 'javascript':127 'level':63 'librari':10,84,103 'logic':40 'maintain':89 'make':120 'manipul':25,46 'math':131 'mention':82 'nativ':23 'offer':11 'often':59 'oper':37 'packag':32 'pattern':101 'program':100 'provid':33,57,90 'recurs':60 'releas':80 'robust':92 'runtim':118,125 'safe':99 'samurai':3,6 'standard':71 'statement':41 'string':45 'sum':39 'time':110 'toolkit':93 'ts':130 'type':2,5,17,24,34,48,62,74,98,111,129 'type-level':61 'type-saf':97 'type-samurai':1,4 'typescript':9,21,72,128 'util':16,73,135 'version':29 'zero':124 'zero-runtim':123","created_at":"2026-04-19T13:42:00.301900+00:00","updated_at":"2026-04-19T13:42:00.301900+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/KamilHs/type-samurai","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/type-samurai","openapi_spec":null,"status_page":null,"smithery":null,"categories":["type-stubs"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}