@cloudglides/nox 1.1.6 → 3.0.0

package/src/utils/stochastic.js

@@ -1,32 +1,92 @@
 export const brownianMotion = (rng, steps, dt = 1) => {
-  const path = [0];
-  for (let i = 0; i < steps; i++) {
-    const drift = -0.5 * dt;
-    const diffusion = Math.sqrt(dt) * (rng.nextFloat() * 2 - 1);
-    const nextVal = path[i] + drift + diffusion;
-    path.push(nextVal);
-  }
-  return path;
-};
-
-export const ornsteinUhlenbeck = (rng, steps, theta = 0.1, mu = 0, sigma = 1) => {
-  const path = [mu];
-  for (let i = 0; i < steps; i++) {
-    const drift = theta * (mu - path[i]);
-    const diffusion = sigma * (rng.nextFloat() * 2 - 1);
-    const nextVal = path[i] + drift + diffusion;
-    path.push(nextVal);
-  }
-  return path;
-};
-
-export const geometricBrownian = (rng, steps, mu = 0.05, sigma = 0.2, dt = 0.01) => {
-  const path = [1];
-  for (let i = 0; i < steps; i++) {
-    const drift = (mu - 0.5 * sigma * sigma) * dt;
-    const diffusion = sigma * Math.sqrt(dt) * (rng.nextFloat() * 2 - 1);
-    const nextVal = path[i] * Math.exp(drift + diffusion);
-    path.push(nextVal);
-  }
-  return path;
-};
+    if (!rng || typeof rng.nextFloat !== 'function') {
+      throw new TypeError('First argument must be RNG instance');
+    }
+    if (typeof steps !== 'number' || !Number.isInteger(steps)) {
+      throw new TypeError('steps must be an integer');
+    }
+    if (steps <= 0) {
+      throw new RangeError('steps must be positive');
+    }
+    if (typeof dt !== 'number') {
+      throw new TypeError('dt must be a number');
+    }
+    if (dt <= 0) {
+      throw new RangeError('dt must be positive');
+    }
+   const path = [0];
+   for (let i = 0; i < steps; i++) {
+     const drift = -0.5 * dt;
+     const diffusion = Math.sqrt(dt) * (rng.nextFloat() * 2 - 1);
+     const nextVal = path[i] + drift + diffusion;
+     path.push(nextVal);
+   }
+   return path;
+ };
+ 
+ export const ornsteinUhlenbeck = (rng, steps, theta = 0.1, mu = 0, sigma = 1) => {
+   if (!rng || typeof rng.nextFloat !== 'function') {
+     throw new TypeError('First argument must be RNG instance');
+   }
+   if (typeof steps !== 'number' || !Number.isInteger(steps)) {
+     throw new TypeError('steps must be an integer');
+   }
+   if (steps <= 0) {
+     throw new RangeError('steps must be positive');
+   }
+   if (typeof theta !== 'number') {
+     throw new TypeError('theta must be a number');
+   }
+   if (typeof mu !== 'number') {
+     throw new TypeError('mu must be a number');
+   }
+   if (typeof sigma !== 'number') {
+     throw new TypeError('sigma must be a number');
+   }
+   if (sigma <= 0) {
+     throw new RangeError('sigma must be positive');
+   }
+   const path = [mu];
+   for (let i = 0; i < steps; i++) {
+     const drift = theta * (mu - path[i]);
+     const diffusion = sigma * (rng.nextFloat() * 2 - 1);
+     const nextVal = path[i] + drift + diffusion;
+     path.push(nextVal);
+   }
+   return path;
+ };
+ 
+ export const geometricBrownian = (rng, steps, mu = 0.05, sigma = 0.2, dt = 0.01) => {
+   if (!rng || typeof rng.nextFloat !== 'function') {
+     throw new TypeError('First argument must be RNG instance');
+   }
+   if (typeof steps !== 'number' || !Number.isInteger(steps)) {
+     throw new TypeError('steps must be an integer');
+   }
+   if (steps <= 0) {
+     throw new RangeError('steps must be positive');
+   }
+   if (typeof mu !== 'number') {
+     throw new TypeError('mu must be a number');
+   }
+   if (typeof sigma !== 'number') {
+     throw new TypeError('sigma must be a number');
+   }
+   if (sigma <= 0) {
+     throw new RangeError('sigma must be positive');
+   }
+   if (typeof dt !== 'number') {
+     throw new TypeError('dt must be a number');
+   }
+   if (dt <= 0) {
+     throw new RangeError('dt must be positive');
+   }
+   const path = [1];
+   for (let i = 0; i < steps; i++) {
+     const drift = (mu - 0.5 * sigma * sigma) * dt;
+     const diffusion = sigma * Math.sqrt(dt) * (rng.nextFloat() * 2 - 1);
+     const nextVal = path[i] * Math.exp(drift + diffusion);
+     path.push(nextVal);
+   }
+   return path;
+ };

package/src/utils/stratified.js

@@ -0,0 +1,108 @@
+export function stratifiedSample(r, data, strata, n) {
+  if (!Array.isArray(data) || data.length === 0) {
+    throw new TypeError('data must be a non-empty array');
+  }
+  if (typeof strata !== 'function') {
+    throw new TypeError('strata must be a function that returns stratum key');
+  }
+  if (typeof n !== 'number' || n < 1) {
+    throw new RangeError('n must be a positive integer');
+  }
+
+  const groups = new Map();
+  
+  for (let i = 0; i < data.length; i++) {
+    const key = strata(data[i]);
+    if (!groups.has(key)) {
+      groups.set(key, []);
+    }
+    groups.get(key).push(data[i]);
+  }
+
+  const result = [];
+  const groupCount = groups.size;
+  const samplesPerGroup = Math.floor(n / groupCount);
+  let remaining = n - samplesPerGroup * groupCount;
+
+  for (const [key, group] of groups) {
+    const k = samplesPerGroup + (remaining > 0 ? 1 : 0);
+    if (remaining > 0) remaining--;
+
+    if (k >= group.length) {
+      result.push(...group);
+    } else {
+      for (let i = 0; i < k; i++) {
+        const idx = r.nextInt(group.length);
+        result.push(group[idx]);
+        group[idx] = group[group.length - 1];
+        group.pop();
+      }
+    }
+  }
+
+  return result;
+}
+
+export function stratifiedSampleProportional(r, data, strata, n) {
+  if (!Array.isArray(data) || data.length === 0) {
+    throw new TypeError('data must be a non-empty array');
+  }
+  if (typeof strata !== 'function') {
+    throw new TypeError('strata must be a function');
+  }
+  if (typeof n !== 'number' || n < 1) {
+    throw new RangeError('n must be a positive integer');
+  }
+
+  const groups = new Map();
+  
+  for (let i = 0; i < data.length; i++) {
+    const key = strata(data[i]);
+    if (!groups.has(key)) {
+      groups.set(key, []);
+    }
+    groups.get(key).push(data[i]);
+  }
+
+  const result = [];
+  const total = data.length;
+
+  for (const [key, group] of groups) {
+    const k = Math.round(n * group.length / total);
+    
+    if (k >= group.length) {
+      result.push(...group);
+    } else if (k > 0) {
+      const copy = [...group];
+      for (let i = 0; i < k; i++) {
+        const idx = r.nextInt(copy.length);
+        result.push(copy[idx]);
+        copy[idx] = copy[copy.length - 1];
+        copy.pop();
+      }
+    }
+  }
+
+  return result;
+}
+
+export function stratify(data, strata) {
+  if (!Array.isArray(data) || data.length === 0) {
+    throw new TypeError('data must be a non-empty array');
+  }
+  if (typeof strata !== 'function') {
+    throw new TypeError('strata must be a function');
+  }
+
+  const groups = new Map();
+  
+  for (let i = 0; i < data.length; i++) {
+    const key = strata(data[i]);
+    if (!groups.has(key)) {
+      groups.set(key, []);
+    }
+    groups.get(key).push(data[i]);
+  }
+
+  return Object.fromEntries(groups);
+}

package/src/utils/timeseries.js

@@ -0,0 +1,166 @@
+export function diff(data, order = 1) {
+  if (!Array.isArray(data) || data.length === 0) {
+    throw new TypeError('data must be non-empty array');
+  }
+  if (typeof order !== 'number' || order < 1) {
+    throw new RangeError('order must be positive integer');
+  }
+
+  let result = [...data];
+  
+  for (let o = 0; o < order; o++) {
+    const prev = result;
+    result = new Array(prev.length - 1);
+    for (let i = 0; i < prev.length - 1; i++) {
+      result[i] = prev[i + 1] - prev[i];
+    }
+  }
+
+  return result;
+}
+
+export function lag(data, lags = 1) {
+  if (!Array.isArray(data) || data.length === 0) {
+    throw new TypeError('data must be non-empty array');
+  }
+  if (typeof lags !== 'number' || lags < 1) {
+    throw new RangeError('lags must be positive integer');
+  }
+
+  const result = new Array(data.length);
+  
+  for (let i = 0; i < data.length; i++) {
+    result[i] = i < lags ? null : data[i - lags];
+  }
+
+  return result;
+}
+
+export function shift(data, periods = 1) {
+  if (!Array.isArray(data) || data.length === 0) {
+    throw new TypeError('data must be non-empty array');
+  }
+  if (typeof periods !== 'number') {
+    throw new RangeError('periods must be integer');
+  }
+
+  const result = new Array(data.length);
+  
+  if (periods > 0) {
+    for (let i = 0; i < data.length; i++) {
+      result[i] = i < periods ? null : data[i - periods];
+    }
+  } else if (periods < 0) {
+    for (let i = 0; i < data.length; i++) {
+      result[i] = i < -periods ? null : data[i - periods];
+    }
+  } else {
+    return [...data];
+  }
+
+  return result;
+}
+
+export function sma(data, window) {
+  if (!Array.isArray(data) || data.length === 0) {
+    throw new TypeError('data must be non-empty array');
+  }
+  if (typeof window !== 'number' || window < 1) {
+    throw new RangeError('window must be positive integer');
+  }
+
+  const result = new Array(data.length);
+  
+  for (let i = 0; i < data.length; i++) {
+    if (i < window - 1) {
+      result[i] = null;
+    } else {
+      let sum = 0;
+      for (let j = i - window + 1; j <= i; j++) {
+        sum += data[j];
+      }
+      result[i] = sum / window;
+    }
+  }
+
+  return result;
+}
+
+export function ema(data, window) {
+  if (!Array.isArray(data) || data.length === 0) {
+    throw new TypeError('data must be non-empty array');
+  }
+  if (typeof window !== 'number' || window < 1) {
+    throw new RangeError('window must be positive integer');
+  }
+
+  const alpha = 2 / (window + 1);
+  const result = new Array(data.length);
+  
+  result[0] = data[0];
+  
+  for (let i = 1; i < data.length; i++) {
+    result[i] = alpha * data[i] + (1 - alpha) * result[i - 1];
+  }
+
+  return result;
+}
+
+export function acf(data, maxLag = 40) {
+  if (!Array.isArray(data) || data.length === 0) {
+    throw new TypeError('data must be non-empty array');
+  }
+  if (typeof maxLag !== 'number' || maxLag < 1) {
+    throw new RangeError('maxLag must be positive integer');
+  }
+
+  const mean = data.reduce((a, b) => a + b, 0) / data.length;
+  const centered = data.map(x => x - mean);
+
+  let c0 = 0;
+  for (let i = 0; i < data.length; i++) {
+    c0 += centered[i] * centered[i];
+  }
+
+  const result = new Array(Math.min(maxLag + 1, data.length));
+  result[0] = 1;
+
+  for (let k = 1; k < result.length; k++) {
+    let ck = 0;
+    for (let i = 0; i < data.length - k; i++) {
+      ck += centered[i] * centered[i + k];
+    }
+    result[k] = ck / c0;
+  }
+
+  return result;
+}
+
+export function pacf(data, maxLag = 40) {
+  if (!Array.isArray(data) || data.length === 0) {
+    throw new TypeError('data must be non-empty array');
+  }
+  if (typeof maxLag !== 'number' || maxLag < 1) {
+    throw new RangeError('maxLag must be positive integer');
+  }
+
+  const correlations = acf(data, maxLag);
+  const result = [1];
+
+  for (let k = 1; k < correlations.length; k++) {
+    let numerator = correlations[k];
+    
+    for (let j = 1; j < k; j++) {
+      numerator -= result[j] * correlations[k - j];
+    }
+
+    let denominator = 1;
+    for (let j = 1; j < k; j++) {
+      denominator -= result[j] * correlations[j];
+    }
+
+    result.push(numerator / denominator);
+  }
+
+  return result;
+}

package/src/utils/transforms.js

@@ -0,0 +1,146 @@
+export function zscore(data) {
+  if (!Array.isArray(data) || data.length === 0) {
+    throw new TypeError('data must be non-empty array');
+  }
+
+  const mean = data.reduce((a, b) => a + b, 0) / data.length;
+  let variance = 0;
+
+  for (let i = 0; i < data.length; i++) {
+    variance += (data[i] - mean) ** 2;
+  }
+
+  const stddev = Math.sqrt(variance / data.length);
+
+  if (stddev === 0) {
+    throw new RangeError('cannot z-score data with zero variance');
+  }
+
+  return data.map(x => (x - mean) / stddev);
+}
+
+export function standardize(data) {
+  if (!Array.isArray(data) || data.length === 0) {
+    throw new TypeError('data must be non-empty array');
+  }
+
+  const mean = data.reduce((a, b) => a + b, 0) / data.length;
+  return data.map(x => x - mean);
+}
+
+export function minMaxScale(data, min = 0, max = 1) {
+  if (!Array.isArray(data) || data.length === 0) {
+    throw new TypeError('data must be non-empty array');
+  }
+  if (typeof min !== 'number' || typeof max !== 'number') {
+    throw new TypeError('min and max must be numbers');
+  }
+
+  const dataMin = Math.min(...data);
+  const dataMax = Math.max(...data);
+  const range = dataMax - dataMin;
+
+  if (range === 0) {
+    throw new RangeError('cannot scale data with zero range');
+  }
+
+  return data.map(x => ((x - dataMin) / range) * (max - min) + min);
+}
+
+export function logTransform(data, base = Math.E) {
+  if (!Array.isArray(data) || data.length === 0) {
+    throw new TypeError('data must be non-empty array');
+  }
+  if (typeof base !== 'number' || base <= 0 || base === 1) {
+    throw new RangeError('base must be positive number != 1');
+  }
+
+  for (let i = 0; i < data.length; i++) {
+    if (data[i] <= 0) {
+      throw new RangeError('all values must be positive');
+    }
+  }
+
+  const logBase = Math.log(base);
+  return data.map(x => Math.log(x) / logBase);
+}
+
+export function sqrtTransform(data) {
+  if (!Array.isArray(data) || data.length === 0) {
+    throw new TypeError('data must be non-empty array');
+  }
+
+  for (let i = 0; i < data.length; i++) {
+    if (data[i] < 0) {
+      throw new RangeError('all values must be non-negative');
+    }
+  }
+
+  return data.map(x => Math.sqrt(x));
+}
+
+export function rank(data) {
+  if (!Array.isArray(data) || data.length === 0) {
+    throw new TypeError('data must be non-empty array');
+  }
+
+  const indexed = data.map((val, i) => [val, i]);
+  indexed.sort((a, b) => a[0] - b[0]);
+
+  const ranks = new Array(data.length);
+  let i = 0;
+
+  while (i < indexed.length) {
+    let j = i;
+    while (j < indexed.length && indexed[j][0] === indexed[i][0]) {
+      j++;
+    }
+
+    const rank = (i + 1 + j) / 2;
+    for (let k = i; k < j; k++) {
+      ranks[indexed[k][1]] = rank;
+    }
+
+    i = j;
+  }
+
+  return ranks;
+}
+
+export function robustScale(data, center = 'median', scale = 'iqr') {
+  if (!Array.isArray(data) || data.length === 0) {
+    throw new TypeError('data must be non-empty array');
+  }
+
+  let centerVal;
+  if (center === 'median') {
+    const sorted = [...data].sort((a, b) => a - b);
+    centerVal = sorted.length % 2 === 0
+      ? (sorted[sorted.length / 2 - 1] + sorted[sorted.length / 2]) / 2
+      : sorted[Math.floor(sorted.length / 2)];
+  } else if (center === 'mean') {
+    centerVal = data.reduce((a, b) => a + b, 0) / data.length;
+  } else {
+    throw new RangeError('center must be "median" or "mean"');
+  }
+
+  let scaleVal;
+  if (scale === 'iqr') {
+    const sorted = [...data].sort((a, b) => a - b);
+    const q1 = sorted[Math.floor(sorted.length * 0.25)];
+    const q3 = sorted[Math.floor(sorted.length * 0.75)];
+    scaleVal = q3 - q1;
+  } else if (scale === 'mad') {
+    const centered = data.map(x => Math.abs(x - centerVal));
+    const sorted = [...centered].sort((a, b) => a - b);
+    scaleVal = sorted[Math.floor(sorted.length / 2)];
+  } else {
+    throw new RangeError('scale must be "iqr" or "mad"');
+  }
+
+  if (scaleVal === 0) {
+    throw new RangeError('scale value is zero');
+  }
+
+  return data.map(x => (x - centerVal) / scaleVal);
+}

package/test/comprehensive.js

@@ -61,10 +61,11 @@ console.log(`  State restored correctly: ${val2 === val2_restored}`);
 
 console.log('\n7. Generator Cloning');
 const orig = deterministic(12345);
-const origSeq = orig.floats(3);
+orig.floats(3);
 const cloned = cloneGenerator(orig);
-const clonedSeq = cloned.floats(3);
-console.log(`  Clone has same sequence: ${JSON.stringify(origSeq) === JSON.stringify(clonedSeq)}`);
+const origNext = orig.floats(3);
+const clonedNext = cloned.floats(3);
+console.log(`  Clone has same sequence: ${JSON.stringify(origNext) === JSON.stringify(clonedNext)}`);
 
 console.log('\n8. Weighted Sampling');
 const items = ['A', 'B', 'C'];

package/test/new-features.js

@@ -0,0 +1,52 @@
+import { rng, binomial, geometric, normals, exponentials, sampleWithReplacement, permute, range, cycle, clz, ctz, popcountNum, reverseBits, setBit, clearBit, toggleBit } from '../src/index.js';
+
+console.log('=== NEW FEATURES TEST ===\n');
+
+const r = rng();
+
+console.log('1. Binomial Distribution');
+const binom = binomial(r, 20, 0.5);
+console.log(`   binomial(20, 0.5): ${binom} (between 0-20)`);
+
+console.log('\n2. Geometric Distribution');
+const geom = geometric(r, 0.3);
+console.log(`   geometric(0.3): ${geom} (number of trials)`);
+
+console.log('\n3. Batch Normal Distribution (with caching)');
+const normals_arr = normals(r, 5);
+console.log(`   normals(5): [${normals_arr.map(n => n.toFixed(2)).join(', ')}]`);
+
+console.log('\n4. Batch Exponential Distribution');
+const exps = exponentials(r, 4, 1);
+console.log(`   exponentials(4): [${exps.map(e => e.toFixed(2)).join(', ')}]`);
+
+console.log('\n5. Sampling with Replacement');
+const sampled = sampleWithReplacement(['A', 'B', 'C'], 8, r);
+console.log(`   sampleWithReplacement([A,B,C], 8): [${sampled.join(', ')}]`);
+
+console.log('\n6. Permutation (alias for shuffle)');
+const perm = permute([1, 2, 3, 4], r);
+console.log(`   permute([1,2,3,4]): [${perm.join(', ')}]`);
+
+console.log('\n7. Range Generation');
+const r1 = range(0, 5);
+const r2 = range(10, 5, -1);
+console.log(`   range(0, 5): [${r1.join(', ')}]`);
+console.log(`   range(10, 5, -1): [${r2.join(', ')}]`);
+
+console.log('\n8. Cycle (repeat array)');
+const cyc = cycle(['X', 'Y'], 6);
+console.log(`   cycle([X, Y], 6): [${cyc.join(', ')}]`);
+
+console.log('\n9. Bit Operations');
+const val = 0b11010110n;
+console.log(`   Value: 0b11010110`);
+console.log(`   clz(): ${clz(val)}`);
+console.log(`   ctz(): ${ctz(val)}`);
+console.log(`   popcountNum(214): ${popcountNum(214)}`);
+console.log(`   reverseBits() [8-bit]: 0b${reverseBits(val, 8).toString(2).padStart(8, '0')}`);
+console.log(`   setBit(0b11010110, 0): 0b${setBit(val, 0).toString(2).padStart(8, '0')}`);
+console.log(`   clearBit(0b11010110, 1): 0b${clearBit(val, 1).toString(2).padStart(8, '0')}`);
+console.log(`   toggleBit(0b11010110, 4): 0b${toggleBit(val, 4).toString(2).padStart(8, '0')}`);
+
+console.log('\n✓ All new features working correctly');

package/IMPROVEMENTS.md

@@ -1,58 +0,0 @@
-# Improvements Made (Hour 2)
-
-## Batch Operations
-- Added `batch(count, fn)` - Execute custom function n times
-- Added `floats(count)` - Generate array of floats
-- Added `ints(count, max)` - Generate array of integers
-- Added `bools(count, probability)` - Generate array of booleans
-
-## RNG API Enhancements
-- Added `range(min, max, step)` - Pick random value from stepped range
-- Added `choice(arr)` - Pick random element from array
-- Better error messages with TypeError vs RangeError distinctions
-
-## Statistical Improvements
-- Added `kolmogorovSmirnovTest(data)` - KS goodness-of-fit test
-- Added `meanTest(data, expected)` - Test mean of distribution
-- Added `varianceTest(data, expected)` - Test variance of distribution
-- All tests return detailed result objects with pass/fail indicators
-
-## Sampling Enhancements
-- Improved `weightedPick()` with comprehensive validation
-- Improved `weightedSample()` with type checking
-- Improved `reservoirSample()` with better error handling
-
-## Generator Optimizations
-- Removed modulo bias in `nextInt()` - uses rejection sampling instead
-- Applied to: PCG64, Xorshift64, Splitmix64, MT19937
-- Ensures uniform distribution across all ranges
-
-## Performance & Caching
-- Added crypto cache in entropy source for performance
-- Added `clearCryptoCache()` export for testing
-- Better entropy mixing with proper BigInt operations
-
-## Type Safety
-- Added `IGenerator` interface for type consistency
-- Added `GeneratorConstructor` type definition
-- Added generic types to shuffle, pick, sample functions
-- Added test result interfaces: `TestResult`, `KSTestResult`
-- Complete TypeScript definitions for all new APIs
-
-## Documentation
-- Updated README with batch operations examples
-- Added weighted sampling section
-- Added statistical tests section
-- Enhanced generator selection documentation
-
-## Testing
-- Added comprehensive test suite (test/comprehensive.js)
-- Added advanced features test (test/advanced.js)
-- All tests pass successfully
-
-## Code Quality
-- Total lines: 1107 → 1318 (+211)
-- Files modified: 10
-- Lines added/changed: 286
-- Consistent error handling patterns
-- Full backward compatibility maintained