type-samurai

Advanced utility types for TypeScript

This package contains many useful utility types that are currently not available in TypeScript, including simple arithmetic operations, color validations, conditional statements, string manipulations, and many more.

Install

npm install --save-dev type-samurai

Usage

import type { Sum } from 'type-samurai'

// 912468
type Result = Sum<123456, 789012>

API Overview

• Statements

  • And - Returns result of logical multiplication of two params
  • AndArr - Returns the result of logical multiplication of all elements inside the passed array type
  • Extend - Returns boolean whether the first argument extends the second argument
  • IfExtends - Returns the third argument if the first argument extends the second argument (defaults to true), otherwise returns the fourth argument (defaults to false)
  • IfNotExtends - Returns the third argument if the first argument doesn't extend the second argument (defaults to true), otherwise returns the fourth argument (defaults to false)
  • If - Returns the second argument if the first argument is true (defaults to true), otherwise returns the third argument (defaults to false)
  • IfNot - Returns the second argument if the first argument is false (defaults to true), otherwise returns the third argument (defaults to false)
  • NotExtends - Returns boolean whether the first argument doesn't extend the second argument
  • Not - Accepts a boolean and returns true if the passed type is false, otherwise returns true
  • Or - Returns result of logical addition of two params.
  • OrArr - Returns result of logical addition of all elements inside the passed array type
  • ReturnItselfIfExtends - Returns the first argument if it extends the second argument, returns the third argument otherwise
  • ReturnItselfIfNotExtends - Returns the first argument if it doesn't extend the second argument, returns the third argument otherwise
  • Switch - type implementation of switch. Accepts value, cases, and optional default value (defaults to never)

• Any

  • AnifyProperties - Turns all properties of an object to type any. If makeOptional option is true, makes all properties optional
  • IfAny - Returns the second argument if the first argument is any (defaults to true), otherwise returns the third argument (defaults to false)
  • IsAny - Returns a boolean if the passed type is any

• Unknown

  • IfUnknown - Returns the second argument if the first argument is unknown (defaults to true), otherwise returns the third argument (defaults to false)
  • IsUnknown - Returns a boolean if the passed type is unknown
  • UnkownifyProperties - Turns all properties of an object to type unknown. If makeOptional option is true, makes all properties optional

• Never

  • IfNever - Returns the second argument if the first argument is never (defaults to true), otherwise returns the third argument (defaults to false)
  • IsNever - Returns a boolean if the passed type is never
  • NeverifyProperties - Turns all properties of an object to type never. If makeOptional option is true, makes all properties optional

• Number

  • CompareNumberLength - Accepts two numbers, returns the third argument (defaults to never) if the first number is shorter, otherwise returns the fourth argument (defaults to never) if the second argument is shorter, if numbers have the same length returns the fifth argument (defaults to never)
  • DigitsTuple - Accepts an integer argument and returns a tuple of its digits
  • FirstDigit - Returns the first digit of the number argument
  • Float - Accepts a number and returns it if it is a float, returns never otherwise
  • GetFloatNumberParts - Returns a tuple of whole and fraction part of the passed float number
  • IfFloat - Returns the second argument if the first argument is float (defaults to true), otherwise returns the third argument (defaults to false)
  • IfNegative - Returns the second argument if the first argument is negative (defaults to true), otherwise returns the third argument (defaults to false)
  • IfNegativeFloat - Returns the second argument if the first argument is a negative float (defaults to true), otherwise returns the third argument (defaults to false)
  • IfNegativeInteger - Returns the second argument if the first argument is a negative integer (defaults to true), otherwise returns the third argument (defaults to false)
  • IfPositive - Returns the second argument if the first argument is positive (defaults to true), otherwise returns the third argument (defaults to false)
  • IfInteger - Returns the second argument if the first argument is an integer (defaults to true), otherwise returns the third argument (defaults to false)
  • IfPositiveFloat - Returns the second argument if the first argument is a positive float (defaults to true), otherwise returns the third argument (defaults to false)
  • IfPositiveInteger - Returns the second argument if the first argument is a positive integer (defaults to true), otherwise returns the third argument (defaults to false)
  • Integer - Accepts a number and returns it if it is an integer, returns never otherwise
  • IsFloat - Returns a boolean if the passed number is float
  • IsInteger - Returns a boolean if the passed number is an integer
  • IsLongerNumber - Accepts two numbers, returns a boolean whether the first argument is longer
  • IsNegative - Returns a boolean if the passed number is negative
  • IsNegativeFloat - Returns a boolean if the passed number is a negative float
  • IsNegativeInteger - Returns a boolean if the passed number is a negative integer
  • IsPositive - Returns a boolean if the passed number is positive
  • IsPositiveFloat - Returns a boolean if the passed number is a positive float
  • IsPositiveInteger - Returns a boolean if the passed number is a positive integer
  • IsSameLengthNumber - Accepts two numbers, returns a boolean whether numbers have the same length
  • IsShorterNumber - Accepts two numbers, returns a boolean whether the first number is shorter
  • Negative - Accepts a number and returns it if it is a negative number, returns never otherwise
  • NegativeFloat - Accepts a number and returns it if it is a negative float, returns never otherwise
  • NegativeInteger - Accepts a number and returns it if it is a negative integer, returns never otherwise
  • NumberLength - Returns number of digits of the passed number
  • ParseNumber - Accepts a string type and parses it to number and returns it, if the string isn't parsable returns never
  • Positive - Accepts a number and returns it if it is a positive number, returns never otherwise
  • PositiveFloat - Accepts a number and returns it if it is a positive float, returns never otherwise
  • PositiveInteger - Accepts a number and returns it if it is a positive integer, returns never otherwise

• String

  • AreAnagrams - Returns a boolean whether two passed string literals are anagrams
  • CompareStringLength - Accepts two strings, returns the third argument (defaults to never) if the first string is shorter, otherwise returns the fourth argument (defaults to never) if the second argument is shorter if strings have the same length returns the fifth argument (defaults to never)
  • EmptyString - Accepts a string and returns it if it is an empty string, returns never otherwise
  • EndsWith - Returns a boolean whether the first string argument ends with the second one
  • FirstCharacter - Accepts a string and returns its first character if possible, returns never otherwise. If includeRest option is true, returns the first character and the remaining string in the format of a tuple: [FirstCharacter, Rest]
  • IfEmptyString - Returns the second argument if the first argument is an empty string (defaults to true), otherwise returns the third argument (defaults to false)
  • IfNonEmptyString - Returns the second argument if the first argument is a non-empty string (defaults to true), otherwise returns the third argument (defaults to false)
  • IndexOf - Type version of Array.prototype.indexOf() and String.prototype.indexOf(). Returns the index of the second argument in the first argument
  • IsEmptyString - Returns a boolean if the passed string is an empty string
  • IsLetter - Returns a boolean whether the passed argument is a letter (Only for letters that have both upper and lower case)
  • IsLongerString - Accepts two strings, and returns a boolean whether the first argument is longer. Range of string length [0, 1000]
  • IsNonEmptyString - Returns a boolean if the passed string is an empty string
  • IsSameLengthString - Accepts two strings, returns a boolean whether strings have the same length. Range of string length [0, 1000]
  • IsShorterString - Accepts two strings, and returns a boolean whether the first string is shorter. Range of string length [0, 1000]
  • IsStringLiteral - Returns a boolean whether the passed argument is literal string
  • Join - Type version of Array.prototype.join(). Joins the first array argument by the second argument.
  • LastCharacter - Accepts a string and returns its first character if possible, returns never otherwise. If includeRest option is true, returns the last character and the remaining string in the format of a tuple: [LastCharacter, Rest]. Range of string length [0, 1000]
  • NonEmptyString - Accepts a string and returns it if it is a non-empty string, returns never otherwise
  • IsPalindrome - Check whether a string or number is a palindrome
  • RemoveLeading - Accepts a string and removes leading characters specified in the second argument
  • Repeat - Repeats the first argument number of times specified in the second argument. Range [0,999]
  • Replace - Replaces the first occurrence of the second string argument with the third string argument in the first string argument
  • ReplaceAll - Replaces all occurrences of the second string argument with the third string argument in the first string argument
  • Split - Type version of String.prototype.split(). Splits the first string argument by the second string argument
  • StartsWith - Returns a boolean whether the first string arguments starts with the second string argument
  • Stringify - Transform numbers, booleans, strings, bigints to string.
  • StringLength - Returns the length of the passed string. Range of string length [0, 3968]

• Array

  • ArrayElementType - Returns the type of the element of the passed array argument
  • Concat - Type version of Array.prototype.concat(). Concatenates two arrays into one.
  • EmptyArray - Returns the first argument if it is an empty array, otherwise returns never
  • IfEmptyArray - Returns the second argument if the first argument is an empty array (defaults to true), otherwise returns the third argument (defaults to false)
  • IfNonEmptyArray - Returns the second argument if the first argument is a non-empty array (defaults to true), otherwise returns the third argument (defaults to false)
  • Includes - Returns a boolean whether the second argument is in the first array argument
  • IndexOf - Type version of Array.prototype.indexOf() and String.prototype.indexOf(). Returns the index of the second argument in the first argument
  • IsArray - Returns a boolean whether the passed argument is an array
  • IsArrayIndex - Returns a boolean whether the passed argument is a valid array index
  • IsEmptyArray - Returns a boolean whether the passed argument is an empty array
  • IsMutableArray - Returns a boolean whether the passed argument is a mutable array
  • IsNonEmptyArray - Returns a boolean whether the passed argument is a non-empty array
  • IsReadonlyArray - Returns a boolean whether the passed argument is a read-only array
  • Pop - Removes last element from the first array argument. If the includeRemoved option is true return the removed element with the new array in the format of [rest, removed]
  • Push - Pushes the second argument in the first argument and returns the new array Removes the first element from the first array argument. If the includeRemoved option is true return the removed element with the new array in the format of [rest, removed]
  • Reverse - Returns a new array with the elements in reverse order
  • Shift - Removes the first element from the first array argument. If the includeRemoved option is true return the removed element with the new array in the format of [rest, removed]
  • Slice - Type version of Array.prototype.slice() method. Returns a shallow copy of a portion of an array into a new array object selected from start to end (end not included)
  • Sort - Sorts a tuple of numbers in ascending order
  • Swap - Swaps the position of two elements in a tuple
  • Unshift - Adds the second argument to the beginning of the first array argument.

• Math

  • Abs - Accepts a number and returns the absolute value of it
  • Ceil - Type version of Math.ceil(). Returns ceiled value of the passed number
  • Decrement - Accepts an integer and returns the decremented value of it. Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • Div - Returns integer division of two numbers. Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • Even - Accepts an integer and returns it if it is even, returns never otherwise
  • Factorial - Accepts an integer argument and returns it mathematical factorial. Range: [0, 21]
  • Fibonacci - Returns the fibonacci sequence number under the passed integer index. Range: [0, 78]
  • Floor - Type version of Math.floor(). Returns floored value of the passed number
  • IfEven - Returns the second argument if the first argument is even (defaults to true), otherwise returns the third argument (defaults to false)
  • IfGreaterOrEqual - Returns the third argument if the first argument (integer) is greater than the second argument (integer) or equal (defaults to true), otherwise returns the fourth argument (defaults to false). Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • IfGreaterThan - Returns the third argument if the first argument (integer) is greater than the second argument (integer) (defaults to true), otherwise returns the fourth argument (defaults to false). Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • IfLowerOrEqual - Returns the third argument if the first argument (integer) is lower than the second argument (integer) or equal (defaults to true), otherwise returns the fourth argument (defaults to false). Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • IfLowerThan - Returns the third argument if the first argument (integer) is lower than the second argument (integer) (defaults to true), otherwise returns the fourth argument (defaults to false). Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • IfOdd - Returns the second argument if the first argument is odd (defaults to true), otherwise returns the third argument (defaults to false)
  • Increment - Accepts an integer and returns the incremented value of it. Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • IsBetween - Returns a boolean whether the first integer argument is between the second and the third integer argument. By default borders of the interval are included, which can be modified by the second argument. minIncluded, maxIncluded options show whether to include the lower and the higher borders respectively. Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • IsDivisible - Returns a boolean whether the first integer argument is divisible by the second integer argument. Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • IsDivisibleByFive - Accepts an integer argument and returns a boolean whether it is divisible by five. Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • IsDivisibleByHundred - Accepts an integer argument and returns a boolean whether it is divisible by hundred. Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • IsDivisibleBySix - Accepts an integer argument and returns a boolean whether it is divisible by six. Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • IsDivisibleByTen - Accepts an integer argument and returns a boolean whether it is divisible by ten. Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • IsDivisibleByTwo - Accepts an integer argument and returns a boolean whether it is divisible by two. Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • IsDivisibleByThree - Accepts an integer argument and returns a boolean whether it is divisible by three. Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • IsEven - Returns a boolean if the passed number is even
  • IsGreaterOrEqual - Returns a boolean whether the first passed integer is greater than the second integer or equal. Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • IsGreaterThan - Returns a boolean whether the first passed integer is greater than the second integer. Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • IsLowerOrEqual - Returns a boolean whether the first passed integer is lower or equal to the second integer. Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • IsLowerThan - Returns a boolean whether the first passed integer is lower than the second integer. Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • IsOdd - Returns a boolean if the passed number is odd
  • Max - Accepts two integers and returns the maximum among them. Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • MaxArr - Accepts an array of integers and returns the maximum among its elements. Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • Min - Accepts two integers and returns the minimum among them. Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • MinArr - Accepts an array of integers and returns the minimum among its elements. Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • Mult - Accepts two integers and returns their multiplication. Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • Mod - Returns the remainder of the division of two numbers.
  • Negate - Accepts a number and returns the absolute negative value of it
  • Odd - Accepts an integer and returns it if it is even, returns never otherwise
  • Pow - Returns the first integer parameter raised to the factor of the second integer parameter. The range for factor: [0, ...]. Range for result: [-2^54,2^54]
  • Round - Type version of Math.round(). Returns the value of a number rounded to the nearest integer
  • Sub - Accepts two integers and returns their subtraction. Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • Sum - Accepts two integers and returns their sum. Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • SumArr - Accepts an array of integers and returns the sum of its elements. Range: [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]
  • Trunc - Type version of Math.trunc(). Returns the integer part of a number by removing any fractional digits.

• Color

  • Color - Returns the first string argument if it is a valid RGB or HEX or HSL color, otherwise returns never. The second argument is an object type with rgbOptions: RGBOptions and hslOptions: hslOptions properties, which can accept the separator between color parameters (defaults to ', ')
  • IfColor - Returns the third argument if the first argument is valid RGB or HEX or HSL color (defaults to true), otherwise returns the fourth argument (defaults to false). The second argument is an object type with rgbOptions: RGBOptions and hslOptions: hslOptions properties, which can accept the separator between color parameters (defaults to ', ')
  • IfHex - Returns the second argument if the first argument is valid HEX color (defaults to true), otherwise returns the third argument (defaults to false)
  • IfHSL - Returns the third argument if the first argument is valid HSL color (defaults to true), otherwise returns the fourth argument (defaults to false). The second argument is an object type with separator: string property, which shows the separator between color parameters (defaults to ', ')
  • IfRGB - Returns the third argument if the first argument is valid RGB color (defaults to true), otherwise returns the fourth argument (defaults to false). The second argument is an object type with separator: string property, which shows the separator between color parameters (defaults to ', ')
  • IsColor - Returns a boolean whether the first string argument is a valid RGB or HEX or HSL color. The second argument is an object type with rgbOptions: RGBOptions and hslOptions: hslOptions properties, which can accept the separator between color parameters (defaults to ', ')
  • IsHEX - Returns a boolean whether the first string argument is a valid HEX color.
  • IsHSL - Returns a boolean whether the first string argument is a valid HSL color. The second argument is an object type with the separator: string property, which shows the separator between color parameters (defaults to ', ')
  • IsRGB - Returns a boolean whether the first string argument is a valid RGB color. The second argument is an object type with the separator: string property, which shows the separator between color parameters (defaults to ', ')
  • HEX - Returns the first string argument if it is a valid HEX color, otherwise returns never
  • HSL - Returns the first string argument if it is a valid HSL color, otherwise returns never. The second argument is an object type with the separator: string property, which shows the separator between color parameters (defaults to ', ')
  • RGB - Returns the first string argument if it is a valid RGB color, otherwise returns never. The second argument is an object type with the separator: string property, which shows the separator between color parameters (defaults to ', ')

• Utilities

  • Dot - Returns the result of the concatenation of two string literals with '.' if the second literal is not empty. otherwise returns the first string literal.
  • IfEqual - Accepts two types and returns the third argument if the first two are equal (defaults to true), otherwise returns the fourth argument (defaults to false)
  • IfNotEqual - Returns the third argument if the first two are not equal (defaults to true), otherwise returns the fourth argument (defaults to false)
  • IfTuple - Returns the second argument if the first array argument is a fixed length tuple (defaults to true), otherwise returns the third argument (defaults to false)
  • IsEqual - Returns a boolean whether the passed two arguments are equal
  • IsNotEqual - Returns a boolean whether the passed two arguments are not equal
  • IsTuple - Returns a boolean whether the first array argument is a fixed length tuple
  • IsUnion - Returns a boolean whether the passed argument is a union
  • LooseLiteral - Improves the autocompletion of loose literal types
  • Mutable - Make all properties in the passed argument mutable (removes readonly). If recursive is set to true, it will also make all nested properties mutable
  • MutableExcept - Make all properties in the passed argument mutable except for the passed properties (removes readonly)
  • MutableOnly - Make passed properties in the passed argument mutable (removes readonly)
  • NonNullableObject - Make all properties in the passed argument non-nullable
  • NonNullableObjectExcept - Make all properties in the passed argument non-nullable except for the passed properties
  • NonNullableObjectOnly - Make passed properties in the passed argument non-nullable
  • PartialExcept - Make all properties in the passed argument optional except for the passed properties
  • PartialOnly - Make passed properties in the passed argument optional
  • PathToFields - Get all possible paths to fields in an object
  • Prettify - Accepts a type and returns its simplified version for better readability. Transforms interface to type, simplifies intersections. If recursive option is true transforms the children object properties as well
  • ReadonlyExcept - Make all properties in the passed argument readonly except for the passed properties
  • ReadonlyOnly - Make passed properties in the passed argument readonly
  • RequiredExcept - Make all properties in the passed argument required except for the passed properties
  • RequiredOnly - Make passed properties in the passed argument required
  • RemoveIndexSignature - Removes the index signature from the passed type
  • ToPrimitive - Turns accepted literal type argument to its primitive
  • TupleToObject - Accepts a tuple of string, number or symbol and returns the object type, where the key values are the elements of the tuple
  • UnionToIntersection - Turns the passed union type to an intersection
  • ValueOf - Get the values of properties in an object
  • ValueOfArray - Get the types of elements in an array
  • ValueOfExcept - Get the values of properties in an object except for the passed properties
  • ValueOfOnly - Get the values of properties in an object only for the passed properties

Contributors

• Kamil Salimli