@obinexusmk2/hypernum 0.1.0

package/src/structures/big-array.ts

@@ -0,0 +1,306 @@
+import { Comparator } from '@/core';
+import { MinHeap, MaxHeap } from '../storage/Heap';
+
+/**
+ * Interface for segment tree node operations
+ */
+export interface SegmentTreeNode<T> {  value: T;
+  lazy?: T;
+  start: number;
+  end: number;
+}
+
+/**
+ * Type for BigArray operation result
+ */
+export type OperationResult<T> = {
+  success: boolean;
+  value?: T;
+  error?: string;
+};
+
+/**
+ * Options for BigArray initialization
+ */
+export interface BigArrayOptions<T> {
+  initialCapacity?: number;
+  growthFactor?: number;
+  comparator?: Comparator<T>;
+}
+
+/**
+ * A specialized array implementation for handling large numbers and providing
+ * efficient operations with segment tree support
+ */
+export class BigArray<T> {
+  private data: T[];
+  private segmentTree: Array<SegmentTreeNode<T> | null>;
+  private readonly growthFactor: number;
+  private readonly comparator: Comparator<T>;
+  private size: number;
+  private capacity: number;
+
+  constructor(options: BigArrayOptions<T> = {}) {
+    const {
+      initialCapacity = 16,
+      growthFactor = 2,
+      comparator = ((a: T, b: T): -1 | 0 | 1 => {
+        if (a < b) return -1;
+        if (a > b) return 1;
+        return 0;
+      }) as Comparator<T>
+    } = options;
+
+    this.capacity = initialCapacity;
+    this.growthFactor = growthFactor;
+    this.comparator = comparator;
+    this.size = 0;
+    this.data = new Array(this.capacity);
+    this.segmentTree = new Array(4 * this.capacity).fill(null);
+  }
+
+  /**
+   * Gets the current size of the array
+   */
+  public getSize(): number {
+    return this.size;
+  }
+
+  /**
+   * Gets the current capacity of the array
+   */
+  public getCapacity(): number {
+    return this.capacity;
+  }
+
+  /**
+   * Resizes the internal array when needed
+   */
+  private resize(newCapacity: number): void {
+    const newData = new Array(newCapacity);
+    for (let i = 0; i < this.size; i++) {
+      newData[i] = this.data[i];
+    }
+    this.data = newData;
+    this.capacity = newCapacity;
+    this.rebuildSegmentTree();
+  }
+
+  /**
+   * Appends an element to the end of the array
+   */
+  public push(value: T): OperationResult<number> {
+    try {
+      if (this.size >= this.capacity) {
+        this.resize(this.capacity * this.growthFactor);
+      }
+      this.data[this.size] = value;
+      this.updateSegmentTree(0, this.size, value);
+      this.size++;
+      return { success: true, value: this.size - 1 };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error during push'
+      };
+    }
+  }
+
+  /**
+   * Removes and returns the last element
+   */
+  public pop(): OperationResult<T> {
+    if (this.size === 0) {
+      return { success: false, error: 'Array is empty' };
+    }
+
+    const value = this.data[this.size - 1];
+    this.size--;
+    
+    // Shrink array if it's too sparse
+    if (this.size < this.capacity / (this.growthFactor * 2)) {
+      this.resize(Math.max(16, Math.floor(this.capacity / this.growthFactor)));
+    }
+
+    return { success: true, value };
+  }
+
+  /**
+   * Gets element at specified index
+   */
+  public get(index: number): OperationResult<T> {
+    if (index < 0 || index >= this.size) {
+      return { success: false, error: 'Index out of bounds' };
+    }
+    return { success: true, value: this.data[index] };
+  }
+
+  /**
+   * Sets element at specified index
+   */
+  public set(index: number, value: T): OperationResult<T> {
+    if (index < 0 || index >= this.size) {
+      return { success: false, error: 'Index out of bounds' };
+    }
+    
+    const oldValue = this.data[index];
+    this.data[index] = value;
+    this.updateSegmentTree(0, index, value);
+    
+    return { success: true, value: oldValue };
+  }
+
+  /**
+   * Rebuilds the segment tree after major changes
+   */
+  private rebuildSegmentTree(): void {
+    this.segmentTree = new Array(4 * this.capacity).fill(null);
+    if (this.size > 0) {
+      this.buildSegmentTree(0, 0, this.size - 1);
+    }
+  }
+
+  /**
+   * Builds a segment tree node recursively
+   */
+  private buildSegmentTree(node: number, start: number, end: number): void {
+    if (start === end) {
+      this.segmentTree[node] = {
+        value: this.data[start] as T,
+        start,
+        end
+      };
+      return;
+    }
+
+    const mid = Math.floor((start + end) / 2);
+    this.buildSegmentTree(2 * node + 1, start, mid);
+    this.buildSegmentTree(2 * node + 2, mid + 1, end);
+
+    const leftNode = this.segmentTree[2 * node + 1];
+    const rightNode = this.segmentTree[2 * node + 2];
+
+    if (leftNode && rightNode) {
+      this.segmentTree[node] = {
+        value: this.comparator(leftNode.value, rightNode.value) >= 0 
+          ? leftNode.value 
+          : rightNode.value,
+        start,
+        end
+      };
+    }
+  }
+
+  /**
+   * Updates the segment tree after a value change
+   */
+  private updateSegmentTree(node: number, index: number, value: T): void {
+    if (!this.segmentTree[node]) {
+      return;
+    }
+
+    const currentNode = this.segmentTree[node]!;
+    if (currentNode.start === currentNode.end) {
+      currentNode.value = value;
+      return;
+    }
+
+    const mid = Math.floor((currentNode.start + currentNode.end) / 2);
+    if (index <= mid) {
+      this.updateSegmentTree(2 * node + 1, index, value);
+    } else {
+      this.updateSegmentTree(2 * node + 2, index, value);
+    }
+
+    const leftNode = this.segmentTree[2 * node + 1];
+    const rightNode = this.segmentTree[2 * node + 2];
+
+    if (leftNode && rightNode) {
+      currentNode.value = this.comparator(leftNode.value, rightNode.value) >= 0 
+        ? leftNode.value 
+        : rightNode.value;
+    }
+  }
+
+  /**
+   * Queries the maximum value in a range
+   */
+  public queryRange(start: number, end: number): OperationResult<T> {
+    if (start < 0 || end >= this.size || start > end) {
+      return { success: false, error: 'Invalid range' };
+    }
+
+    const result = this.querySegmentTree(0, start, end);
+    return result 
+      ? { success: true, value: result }
+      : { success: false, error: 'Range query failed' };
+  }
+
+  /**
+   * Recursively queries the segment tree
+   */
+  private querySegmentTree(node: number, queryStart: number, queryEnd: number): T | null {
+    const currentNode = this.segmentTree[node];
+    if (!currentNode) {
+      return null;
+    }
+
+    if (queryStart <= currentNode.start && queryEnd >= currentNode.end) {
+      return currentNode.value;
+    }
+
+    if (queryEnd < currentNode.start || queryStart > currentNode.end) {
+      return null;
+    }
+
+    const leftResult = this.querySegmentTree(2 * node + 1, queryStart, queryEnd);
+    const rightResult = this.querySegmentTree(2 * node + 2, queryStart, queryEnd);
+
+    if (leftResult === null) return rightResult;
+    if (rightResult === null) return leftResult;
+
+    return this.comparator(leftResult, rightResult) >= 0 ? leftResult : rightResult;
+  }
+
+  /**
+   * Creates a heap from the current array
+   */
+  public toHeap(isMin: boolean = true): MinHeap<T> | MaxHeap<T> {
+    const heap = isMin 
+      ? new MinHeap<T>(this.comparator)
+      : new MaxHeap<T>(this.comparator);
+      
+    for (let i = 0; i < this.size; i++) {
+      if (this.data[i] !== undefined) {
+        if (this.data[i] !== undefined) {
+          heap.push(this.data[i] as T);
+        }
+      }
+    }
+    
+    return heap;
+  }
+
+  /**
+   * Sorts the array in-place
+   */
+  public sort(ascending: boolean = true): void {
+    const heap = this.toHeap(!ascending);
+    for (let i = this.size - 1; i >= 0; i--) {
+      const value = heap.pop();
+      if (value !== undefined) {
+        this.data[i] = value;
+      }
+    }
+    this.rebuildSegmentTree();
+  }
+
+  /**
+   * Returns array as native array
+   */
+  public toArray(): T[] {
+    return this.data.slice(0, this.size);
+  }
+}
+
+export default BigArray;

package/src/structures/index.ts

@@ -0,0 +1,4 @@
+export { AckermannStructure } from './ackermann';
+export { BigArray, type BigArrayOptions } from './big-array';
+export { NumberTree } from './number-tree';
+export { PowerTower } from './power-tower';

package/src/structures/number-tree.ts

@@ -0,0 +1,404 @@
+import { Comparator } from "@/core";
+
+/**
+ * Interface for tree node statistics
+ */
+interface NodeStats {
+  height: number;
+  size: number;
+  sum: bigint;
+  min: bigint;
+  max: bigint;
+}
+
+/**
+ * Interface for tree traversal configuration
+ */
+interface TraversalConfig {
+  includeStats?: boolean;
+  skipSubtrees?: boolean;
+  maxDepth?: number;
+}
+
+/**
+ * Class representing a node in the number tree
+ */
+class NumberNode {
+  value: bigint;
+  left: NumberNode | null;
+  right: NumberNode | null;
+  parent: NumberNode | null;
+  height: number;
+  size: number;
+  sum: bigint;
+
+  constructor(value: bigint | string | number) {
+    this.value = typeof value === 'bigint' ? value : BigInt(value);
+    this.left = null;
+    this.right = null;
+    this.parent = null;
+    this.height = 1;
+    this.size = 1;
+    this.sum = this.value;
+  }
+
+  /**
+   * Updates node statistics based on children
+   */
+  updateStats(): void {
+    this.height = 1 + Math.max(
+      this.left?.height ?? 0,
+      this.right?.height ?? 0
+    );
+    this.size = 1 + (this.left?.size ?? 0) + (this.right?.size ?? 0);
+    this.sum = this.value + 
+      (this.left?.sum ?? BigInt(0)) + 
+      (this.right?.sum ?? BigInt(0));
+  }
+
+  /**
+   * Gets balance factor of the node
+   */
+  getBalance(): number {
+    return (this.left?.height ?? 0) - (this.right?.height ?? 0);
+  }
+
+  /**
+   * Gets complete statistics for the node and its subtree
+   */
+  getStats(): NodeStats {
+    return {
+      height: this.height,
+      size: this.size,
+      sum: this.sum,
+      min: this.findMin().value,
+      max: this.findMax().value
+    };
+  }
+
+  /**
+   * Finds minimum value node in the subtree
+   */
+  findMin(): NumberNode {
+    let current: NumberNode = this;
+    while (current.left) {
+      current = current.left;
+    }
+    return current;
+  }
+
+  /**
+   * Finds maximum value node in the subtree
+   */
+  findMax(): NumberNode {
+    let current: NumberNode = this;
+    while (current.right) {
+      current = current.right;
+    }
+    return current;
+  }
+}
+
+/**
+ * AVL Tree implementation specialized for handling large numbers
+ */
+export class NumberTree {
+  private root: NumberNode | null;
+  private readonly comparator: Comparator<bigint>;
+
+  constructor(comparator?: Comparator<bigint>) {
+    this.root = null;
+    this.comparator = comparator ?? ((a: bigint, b: bigint): -1 | 0 | 1 => {
+      if (a < b) return -1;
+      if (a > b) return 1;
+      return 0;
+    });
+  }
+
+  /**
+   * Gets the root node if it exists
+   */
+  public getRoot(): NumberNode | null {
+    return this.root;
+  }
+
+  /**
+   * Inserts a new value into the tree
+   */
+  public insert(value: bigint | string | number): NumberNode {
+    const newValue = typeof value === 'bigint' ? value : BigInt(value);
+    this.root = this.insertNode(this.root, newValue);
+    return this.find(newValue)!;
+  }
+
+  /**
+   * Recursively inserts a new node
+   */
+  private insertNode(node: NumberNode | null, value: bigint): NumberNode {
+    if (!node) {
+      return new NumberNode(value);
+    }
+
+    const compareResult = this.comparator(value, node.value);
+    if (compareResult < 0) {
+      node.left = this.insertNode(node.left, value);
+      node.left.parent = node;
+    } else if (compareResult > 0) {
+      node.right = this.insertNode(node.right, value);
+      node.right.parent = node;
+    } else {
+      return node; // Duplicate value, return existing node
+    }
+
+    node.updateStats();
+    return this.balance(node);
+  }
+
+  /**
+   * Balances a node using AVL rotations
+   */
+  private balance(node: NumberNode): NumberNode {
+    const balance = node.getBalance();
+
+    // Left heavy
+    if (balance > 1) {
+      if (node.left && node.left.getBalance() < 0) {
+        node.left = this.rotateLeft(node.left);
+      }
+      return this.rotateRight(node);
+    }
+
+    // Right heavy
+    if (balance < -1) {
+      if (node.right && node.right.getBalance() > 0) {
+        node.right = this.rotateRight(node.right);
+      }
+      return this.rotateLeft(node);
+    }
+
+    return node;
+  }
+
+  /**
+   * Performs left rotation
+   */
+  private rotateLeft(node: NumberNode): NumberNode {
+    const rightChild = node.right!;
+    const rightLeftChild = rightChild.left;
+
+    rightChild.left = node;
+    node.right = rightLeftChild;
+
+    if (rightLeftChild) {
+      rightLeftChild.parent = node;
+    }
+    rightChild.parent = node.parent;
+    node.parent = rightChild;
+
+    node.updateStats();
+    rightChild.updateStats();
+
+    return rightChild;
+  }
+
+  /**
+   * Performs right rotation
+   */
+  private rotateRight(node: NumberNode): NumberNode {
+    const leftChild = node.left!;
+    const leftRightChild = leftChild.right;
+
+    leftChild.right = node;
+    node.left = leftRightChild;
+
+    if (leftRightChild) {
+      leftRightChild.parent = node;
+    }
+    leftChild.parent = node.parent;
+    node.parent = leftChild;
+
+    node.updateStats();
+    leftChild.updateStats();
+
+    return leftChild;
+  }
+
+  /**
+   * Removes a value from the tree
+   */
+  public remove(value: bigint | string | number): boolean {
+    const searchValue = typeof value === 'bigint' ? value : BigInt(value);
+    const nodeToRemove = this.find(searchValue);
+    
+    if (!nodeToRemove) {
+      return false;
+    }
+
+    this.root = this.removeNode(this.root, searchValue);
+    return true;
+  }
+
+  /**
+   * Recursively removes a node
+   */
+  private removeNode(node: NumberNode | null, value: bigint): NumberNode | null {
+    if (!node) {
+      return null;
+    }
+
+    const compareResult = this.comparator(value, node.value);
+    if (compareResult < 0) {
+      node.left = this.removeNode(node.left, value);
+      if (node.left) {
+        node.left.parent = node;
+      }
+    } else if (compareResult > 0) {
+      node.right = this.removeNode(node.right, value);
+      if (node.right) {
+        node.right.parent = node;
+      }
+    } else {
+      // Node to delete found
+      if (!node.left) {
+        return node.right;
+      }
+      if (!node.right) {
+        return node.left;
+      }
+
+      // Node has two children
+      const successor = node.right.findMin();
+      node.value = successor.value;
+      node.right = this.removeNode(node.right, successor.value);
+      if (node.right) {
+        node.right.parent = node;
+      }
+    }
+
+    node.updateStats();
+    return this.balance(node);
+  }
+
+  /**
+   * Finds a node by value
+   */
+  public find(value: bigint | string | number): NumberNode | null {
+    const searchValue = typeof value === 'bigint' ? value : BigInt(value);
+    let current = this.root;
+
+    while (current) {
+      const compareResult = this.comparator(searchValue, current.value);
+      if (compareResult === 0) {
+        return current;
+      }
+      current = compareResult < 0 ? current.left : current.right;
+    }
+
+    return null;
+  }
+
+  /**
+   * Traverses the tree in specified order and returns values
+   */
+  public traverse(order: 'inOrder' | 'preOrder' | 'postOrder' = 'inOrder', 
+                 config: TraversalConfig = {}): bigint[] {
+    const result: bigint[] = [];
+    
+    const traverse = (node: NumberNode | null, depth: number = 0): void => {
+      if (!node || (config.maxDepth !== undefined && depth >= config.maxDepth)) {
+        return;
+      }
+
+      if (order === 'preOrder') {
+        result.push(node.value);
+      }
+
+      if (!config.skipSubtrees) {
+        traverse(node.left, depth + 1);
+      }
+
+      if (order === 'inOrder') {
+        result.push(node.value);
+      }
+
+      if (!config.skipSubtrees) {
+        traverse(node.right, depth + 1);
+      }
+
+      if (order === 'postOrder') {
+        result.push(node.value);
+      }
+    };
+
+    traverse(this.root);
+    return result;
+  }
+
+  /**
+   * Gets overall tree statistics
+   */
+  public getTreeStats(): NodeStats | null {
+    return this.root?.getStats() ?? null;
+  }
+
+  /**
+   * Gets the nth smallest value in the tree
+   */
+  public getNthValue(n: number): bigint | null {
+    if (!this.root || n < 1 || n > this.root.size) {
+      return null;
+    }
+
+    const findNth = (node: NumberNode | null, position: number): bigint | null => {
+      if (!node) {
+        return null;
+      }
+
+      const leftSize = node.left?.size ?? 0;
+      
+      if (position === leftSize + 1) {
+        return node.value;
+      }
+      
+      if (position <= leftSize) {
+        return findNth(node.left, position);
+      }
+      
+      return findNth(node.right, position - leftSize - 1);
+    };
+
+    return findNth(this.root, n);
+  }
+
+  /**
+   * Gets a range of values between start and end (inclusive)
+   */
+  public getRange(start: bigint | string | number, 
+                 end: bigint | string | number): bigint[] {
+    const startValue = typeof start === 'bigint' ? start : BigInt(start);
+    const endValue = typeof end === 'bigint' ? end : BigInt(end);
+    const result: bigint[] = [];
+
+    const collectRange = (node: NumberNode | null): void => {
+      if (!node) {
+        return;
+      }
+
+      if (this.comparator(node.value, startValue) >= 0 && 
+          this.comparator(node.value, endValue) <= 0) {
+        collectRange(node.left);
+        result.push(node.value);
+        collectRange(node.right);
+      } else if (this.comparator(node.value, startValue) > 0) {
+        collectRange(node.left);
+      } else {
+        collectRange(node.right);
+      }
+    };
+
+    collectRange(this.root);
+    return result;
+  }
+}
+
+export default NumberTree;