CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-ts-toolbelt

TypeScript's largest utility library providing 200+ type utilities for advanced type manipulation.

Pending
Overview
Eval results
Files

number.mddocs/

Number Module

Type-level arithmetic operations using an internal iteration system supporting mathematical operations from -100 to 100 with full type safety.

Capabilities

Basic Arithmetic

Core mathematical operations implemented at the type level.

/**
 * Add two numbers at type level
 * @param N1 - First number to add
 * @param N2 - Second number to add
 * @returns Sum of N1 and N2
 */
type Add<N1 extends number, N2 extends number> = AddImpl<N1, N2>;

/**
 * Subtract second number from first at type level
 * @param N1 - Number to subtract from
 * @param N2 - Number to subtract
 * @returns Difference of N1 minus N2
 */
type Sub<N1 extends number, N2 extends number> = SubImpl<N1, N2>;

/**
 * Get absolute value of number
 * @param N - Number to get absolute value of
 * @returns Absolute value of N
 */
type Absolute<N extends number> = AbsoluteImpl<N>;

/**
 * Negate a number (multiply by -1)
 * @param N - Number to negate
 * @returns Negated value of N
 */
type Negate<N extends number> = NegateImpl<N>;

Usage Examples:

import { N } from "ts-toolbelt";

// Basic arithmetic
type Sum = N.Add<5, 3>; // 8
type Difference = N.Sub<10, 4>; // 6
type AbsValue = N.Absolute<-15>; // 15
type Negated = N.Negate<7>; // -7

// With negative numbers
type NegativeSum = N.Add<-5, 3>; // -2
type NegativeDiff = N.Sub<-10, -4>; // -6

// Edge cases
type Zero = N.Add<0, 0>; // 0
type Identity = N.Sub<42, 0>; // 42
type AbsOfZero = N.Absolute<0>; // 0

Comparison Operations

Compare numbers and determine relationships between them.

/**
 * Check if first number is greater than second
 * @param N1 - First number to compare
 * @param N2 - Second number to compare
 * @returns 1 if N1 > N2, 0 otherwise
 */
type Greater<N1 extends number, N2 extends number> = GreaterImpl<N1, N2>;

/**
 * Check if first number is greater than or equal to second
 * @param N1 - First number to compare
 * @param N2 - Second number to compare
 * @returns 1 if N1 >= N2, 0 otherwise
 */
type GreaterEq<N1 extends number, N2 extends number> = GreaterEqImpl<N1, N2>;

/**
 * Check if first number is lower than second
 * @param N1 - First number to compare
 * @param N2 - Second number to compare
 * @returns 1 if N1 < N2, 0 otherwise
 */
type Lower<N1 extends number, N2 extends number> = LowerImpl<N1, N2>;

/**
 * Check if first number is lower than or equal to second
 * @param N1 - First number to compare
 * @param N2 - Second number to compare
 * @returns 1 if N1 <= N2, 0 otherwise
 */
type LowerEq<N1 extends number, N2 extends number> = LowerEqImpl<N1, N2>;

Usage Examples:

import { N } from "ts-toolbelt";

// Greater than comparisons
type IsGreater1 = N.Greater<10, 5>; // 1
type IsGreater2 = N.Greater<3, 8>; // 0
type IsGreater3 = N.Greater<5, 5>; // 0

// Greater than or equal
type IsGreaterEq1 = N.GreaterEq<10, 5>; // 1
type IsGreaterEq2 = N.GreaterEq<5, 5>; // 1
type IsGreaterEq3 = N.GreaterEq<3, 8>; // 0

// Less than comparisons
type IsLower1 = N.Lower<3, 8>; // 1
type IsLower2 = N.Lower<10, 5>; // 0
type IsLower3 = N.Lower<5, 5>; // 0

// Less than or equal
type IsLowerEq1 = N.LowerEq<3, 8>; // 1
type IsLowerEq2 = N.LowerEq<5, 5>; // 1
type IsLowerEq3 = N.LowerEq<10, 5>; // 0

// With negative numbers
type NegComparison1 = N.Greater<-5, -10>; // 1 (true, -5 > -10)
type NegComparison2 = N.Lower<-2, 3>; // 1 (true, -2 < 3)

Number Classification

Utility operations to classify and check properties of numbers.

/**
 * Check if number is zero
 * @param N - Number to check
 * @returns 1 if N is 0, 0 otherwise
 */
type IsZero<N extends number> = N extends 0 ? 1 : 0;

/**
 * Check if number is positive (greater than zero)
 * @param N - Number to check
 * @returns 1 if N > 0, 0 otherwise
 */
type IsPositive<N extends number> = IsPositiveImpl<N>;

/**
 * Check if number is negative (less than zero)
 * @param N - Number to check
 * @returns 1 if N < 0, 0 otherwise
 */
type IsNegative<N extends number> = IsNegativeImpl<N>;

Usage Examples:

import { N } from "ts-toolbelt";

// Zero checking
type CheckZero1 = N.IsZero<0>; // 1
type CheckZero2 = N.IsZero<5>; // 0
type CheckZero3 = N.IsZero<-3>; // 0

// Positive checking
type CheckPos1 = N.IsPositive<10>; // 1
type CheckPos2 = N.IsPositive<0>; // 0
type CheckPos3 = N.IsPositive<-5>; // 0

// Negative checking
type CheckNeg1 = N.IsNegative<-10>; // 1
type CheckNeg2 = N.IsNegative<0>; // 0
type CheckNeg3 = N.IsNegative<5>; // 0

Range Operations

Generate ranges and sequences of numbers.

/**
 * Generate a range of numbers from start to end
 * @param From - Starting number (inclusive)
 * @param To - Ending number (inclusive)
 * @returns Tuple containing range of numbers
 */
type Range<From extends number, To extends number> = RangeImpl<From, To>;

Usage Examples:

import { N } from "ts-toolbelt";

// Generate number ranges
type SmallRange = N.Range<1, 5>; // [1, 2, 3, 4, 5]
type NegativeRange = N.Range<-3, 2>; // [-3, -2, -1, 0, 1, 2]
type SingleNumber = N.Range<7, 7>; // [7]

// Practical usage with other utilities
type IndexRange = N.Range<0, 10>; // [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
type CountdownRange = N.Range<10, 0>; // [10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0]

Practical Examples

Real-world usage patterns combining number operations.

Usage Examples:

import { N, L } from "ts-toolbelt";

// Calculate array indices
type ArrayLength = 5;
type LastIndex = N.Sub<ArrayLength, 1>; // 4
type ValidIndices = N.Range<0, LastIndex>; // [0, 1, 2, 3, 4]

// Pagination calculations
type PageSize = 10;
type PageNumber = 3;
type OffsetCalculation = N.Sub<N.Add<PageNumber, 1>, 1>; // Page index calculation
type StartIndex = N.Add<N.Sub<PageNumber, 1>, PageSize>; // Skip calculation

// Range validation
type MinValue = 0;
type MaxValue = 100;
type TestValue = 75;
type IsInRange = N.Greater<TestValue, MinValue> extends 1 
  ? N.Lower<TestValue, MaxValue> extends 1 
    ? 1 
    : 0 
  : 0; // 1 (true, 75 is between 0 and 100)

// Counter operations
type CurrentCount = 42;
type Increment = N.Add<CurrentCount, 1>; // 43
type Decrement = N.Sub<CurrentCount, 1>; // 41
type Reset = 0;

// Conditional arithmetic
type ConditionalAdd<A extends number, B extends number> = 
  N.IsZero<B> extends 1 ? A : N.Add<A, B>;

type Result1 = ConditionalAdd<5, 0>; // 5 (no addition when B is 0)
type Result2 = ConditionalAdd<5, 3>; // 8 (normal addition)

Implementation Notes

The Number module uses an internal iteration system that supports operations within the range of -100 to 100. This is implemented through:

  • Iteration Types: Internal tuple-based system for counting and arithmetic
  • Lookup Tables: Pre-computed results for performance optimization
  • Recursive Types: Step-by-step computation for complex operations
  • Boundary Handling: Proper handling of edge cases like zero and negative numbers

The module provides type-safe arithmetic that is evaluated at compile time, enabling mathematical operations in TypeScript's type system itself.

Types

// Core types are number literals within the supported range [-100, 100]
// All operations return number literal types when possible

Install with Tessl CLI

npx tessl i tessl/npm-ts-toolbelt

docs

any.md

boolean.md

class.md

community.md

function.md

index.md

iteration.md

list.md

misc.md

number.md

object.md

string.md

testing.md

union.md

tile.json