type-samurai

library1.1.1jsnpmunverified

`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.

type-stubs

npm install type-samurai

github ↗package ↗

INSTALL

IMPORT

SIG · TYPE-SAMURAI

type-samurai

type-stubsjavascriptv1.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Sum

✓ import type { Sum } from 'type-samurai'

✗ import { Sum } from 'type-samurai'

This library exports only types. Always use `import type` to avoid runtime errors or unnecessary imports.

✓ import type { If } from 'type-samurai'

✗ const If = require('type-samurai')

CommonJS `require` syntax is not supported as this is a type-only module for ESM environments, primarily used for compile-time type checking.

IsAny

✓ import type { IsAny } from 'type-samurai'

✗ import * as TypeSamurai from 'type-samurai'

For optimal performance and clarity, prefer named type imports over namespace imports when only a few specific types are needed.

Demonstrates type-level arithmetic, conditional type evaluation, and type introspection, showcasing the library's compile-time utility without generating runtime code.

import type { Sum, IfExtends, IsNever, ReturnItselfIfExtends } from 'type-samurai'; // Example 1: Type-level arithmetic type Total = Sum<123, 456>; // Evaluates to 579 // console.log(Total); // This is a type, not a runtime value // Example 2: Conditional types type ResultBasedOnExtension = IfExtends<string, string | number, 'Is String', 'Not String'>; // 'Is String' type AnotherResult = IfExtends<number, string, 'Is String', 'Not String'>; // 'Not String' // Example 3: Type introspection type CheckNever = IsNever<'hello'>; // false type CheckNeverActual = IsNever<never>; // true // Example 4: Returning itself conditionally type MyType = ReturnItselfIfExtends<{ a: string }, object, { a: string }>; // { a: string } type FallbackType = ReturnItselfIfExtends<null, object, 'Not an object'>; // 'Not an object' // These operations are purely compile-time. There is no runtime JavaScript code generated.

Debug

Known issues

gotchaExtremely 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).

fix

Refactor complex type logic into smaller, composable types. Consider if the complexity is truly necessary or if a simpler runtime check could suffice.

affects: >=1.0

gotchaWhile `type-samurai` is zero-runtime, heavy usage of its advanced types can significantly increase TypeScript compilation times, especially in large codebases.

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.

affects: >=1.0

breakingAs 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.

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.

affects: >=1.0

Errors

Common errors & fixes

Type instantiation is excessively deep and possibly infinite. (2589)

Too many recursive type evaluations or very deep generic type instantiations.

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).

Expression produces a union type that is too complex to represent. (2590)

The resulting union type from a `type-samurai` operation (especially with large number types or string manipulations) exceeds TypeScript's internal complexity limits.

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.

Cannot find module 'type-samurai' or its corresponding type declarations. (2307)

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.

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.

Upgrade

Version history

1.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/KamilHs/type-samurai ↗

packagehttps://www.npmjs.com/package/type-samurai ↗