Iteration Module

/**
 * Iteration type representing a step in type-level arithmetic
 * Tuple format: [value: number, sign: '-'|'0'|'+', prev: IterationKey, next: IterationKey, oppo: IterationKey]
 */
type Iteration = [number, '-' | '0' | '+', IterationKey, IterationKey, IterationKey];

/**
 * Key type for iteration mapping (supports range -100 to 100)
 */
type Key = string;

import { I } from "ts-toolbelt";

// Iteration represents a position in arithmetic operations
// Internal structure: [current_value, sign, previous_key, next_key, opposite_key]

// This is typically used internally by Number module operations
// Users generally don't interact with Iteration directly

/**
 * Convert number to iteration type for arithmetic operations
 * @param N - Number to convert (must be in supported range -100 to 100)
 * @returns Iteration representation of the number
 */
type IterationOf<N extends number> = IterationOfImpl<N>;

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

// Convert numbers to iteration form (used internally)
type Iter5 = I.IterationOf<5>; // Internal iteration representation of 5
type IterNeg3 = I.IterationOf<-3>; // Internal iteration representation of -3
type Iter0 = I.IterationOf<0>; // Internal iteration representation of 0

// This enables the Number module to perform arithmetic
type Addition = N.Add<5, 3>; // Uses I.IterationOf<5> and I.IterationOf<3> internally

/**
 * Get the next iteration in sequence
 * @param I - Current iteration
 * @returns Next iteration in sequence
 */
type Next<I extends Iteration> = NextImpl<I>;

/**
 * Get the previous iteration in sequence
 * @param I - Current iteration
 * @returns Previous iteration in sequence
 */
type Prev<I extends Iteration> = PrevImpl<I>;

/**
 * Get the position/value from iteration
 * @param I - Iteration to extract position from
 * @returns Position value as number
 */
type Pos<I extends Iteration> = PosImpl<I>;

import { I } from "ts-toolbelt";

// These operations work with iteration types internally
// Used by Number module for incrementing/decrementing

// Example conceptual usage (actual types are complex internal structures)
type CurrentIter = I.IterationOf<5>;
type NextIter = I.Next<CurrentIter>; // Represents iteration for 6
type PrevIter = I.Prev<CurrentIter>; // Represents iteration for 4

type Position = I.Pos<CurrentIter>; // 5

// Chain operations for multi-step arithmetic
type TwoStepsForward = I.Next<I.Next<CurrentIter>>; // Represents iteration for 7
type BackAndForth = I.Prev<I.Next<CurrentIter>>; // Back to original (5)

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

// The iteration system enables complex arithmetic operations
// All Number module operations use this internally

// Example: How N.Add<3, 2> works conceptually:
// 1. Convert 3 to I.IterationOf<3>
// 2. Navigate forward by 2 steps using I.Next
// 3. Extract final position using I.Pos
// Result: 5

// Range limitations
type MinSupported = I.IterationOf<-100>; // Minimum supported value
type MaxSupported = I.IterationOf<100>; // Maximum supported value

// Out of range numbers cannot be converted
// type OutOfRange = I.IterationOf<101>; // Would fail
// type TooNegative = I.IterationOf<-101>; // Would fail

// Practical usage through Number module
type Calculation1 = N.Add<10, 5>; // 15 (uses iteration internally)
type Calculation2 = N.Sub<20, 8>; // 12 (uses iteration internally)
type Comparison = N.Greater<7, 3>; // 1 (uses iteration internally)

// The iteration system provides:
// - Consistent arithmetic operations
// - Type-safe range checking
// - Sequential navigation
// - Bidirectional operations

// Performance considerations
// - Pre-computed lookup tables for efficiency
// - Bounded range prevents infinite recursion
// - Optimized for common arithmetic patterns

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

// Using iteration system for custom arithmetic
type CustomIncrement<N extends number> = I.Pos<I.Next<I.IterationOf<N>>>;
type Result1 = CustomIncrement<5>; // 6
type Result2 = CustomIncrement<-10>; // -9

// Multi-step operations
type AddThree<N extends number> = I.Pos<I.Next<I.Next<I.Next<I.IterationOf<N>>>>>;
type Result3 = AddThree<7>; // 10

// Conditional arithmetic using iteration
type SafeIncrement<N extends number> = N extends 100 
  ? N // At maximum, don't increment
  : I.Pos<I.Next<I.IterationOf<N>>>;

type SafeResult1 = SafeIncrement<99>; // 100
type SafeResult2 = SafeIncrement<100>; // 100 (unchanged)

// Integration with other modules
type CountElements<L extends readonly any[]> = L['length'] extends number
  ? L['length'] extends infer Len
    ? Len extends number
      ? Len extends 0
        ? 0
        : I.Pos<I.IterationOf<Len>>
      : never
    : never
  : never;

type ElementCount = CountElements<[1, 2, 3, 4, 5]>; // 5

// Range validation
type IsInRange<N extends number> = N extends number
  ? N extends -100 | -99 | -98 // ... (would list all valid values)
    ? true
    : N extends 98 | 99 | 100
    ? true  
    : false
  : false;

// Arithmetic validation
type CanAdd<A extends number, B extends number> = 
  N.Add<A, B> extends number ? true : false;

type ValidAddition = CanAdd<50, 30>; // true (80 is in range)
type InvalidAddition = CanAdd<90, 20>; // false (110 exceeds range)

// Core iteration types
type Iteration = [number, '-' | '0' | '+', IterationKey, IterationKey, IterationKey];
type Key = string; // Iteration key for mapping
type IterationKey = Key; // Alias for clarity