@cloudglides/nox 1.0.1

package/.github/workflows/build-on-tag.yml

@@ -0,0 +1,67 @@
+name: Build on Tag
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: pnpm/action-setup@v2
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Extract version from tag
+        id: version
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Update package.json version
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          pnpm exec jq --arg v "$VERSION" '.version = $v' package.json > package.json.tmp
+          mv package.json.tmp package.json
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Run tests
+        run: pnpm test
+
+      - name: Publish to npm
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Get commit history
+        id: commits
+        run: |
+          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || git rev-list --max-parents=0 HEAD)
+          COMMITS=$(git log $PREV_TAG..HEAD --oneline --no-decorate)
+          {
+            echo "commit_log<<EOF"
+            echo "$COMMITS"
+            echo "EOF"
+          } >> $GITHUB_OUTPUT
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          body: ${{ steps.commits.outputs.commit_log }}
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/IMPROVEMENTS.md

@@ -0,0 +1,58 @@
+# 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

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# nox
+
+Simple, unpredictable random number generator.
+
+## Install
+
+```bash
+npm install nox
+```
+
+## Quick Start
+
+```javascript
+import { rng, deterministic } from 'nox';
+
+const r = rng();
+
+r.nextFloat();      // 0.742...
+r.nextInt(100);     // 47
+r.int(1, 100);      // 73
+r.bool(0.3);        // true/false (30% chance)
+r.range(10, 20, 2); // Pick from range: 10, 12, 14, 16, 18, 20
+r.choice([1, 2, 3]); // Pick one element
+
+// Batch operations
+r.floats(5);        // [0.123, 0.456, ...]
+r.ints(5, 100);     // [47, 82, 23, ...]
+r.bools(5);         // [true, false, true, ...]
+```
+
+## Reproducible
+
+```javascript
+import { deterministic } from 'nox';
+
+const r = deterministic(42);
+// Always same sequence
+```
+
+## Distributions
+
+```javascript
+import { rng, normal, exponential, uniform, poisson } from 'nox';
+
+const r = rng();
+
+normal(r, mean=0, stddev=1);
+exponential(r, lambda=1);
+uniform(r, min=0, max=1);
+poisson(r, lambda=5);
+```
+
+## Sampling
+
+```javascript
+import { rng, shuffle, pick, sample } from 'nox';
+
+const r = rng();
+
+shuffle([1, 2, 3], r);
+pick(['a', 'b', 'c'], r);
+sample([1, 2, 3, 4, 5], 3, r);
+```
+
+## State
+
+```javascript
+import { rng, saveState, restoreState } from 'nox';
+
+const r = rng();
+const snapshot = saveState(r);
+
+r.nextFloat();
+restoreState(r, snapshot);
+r.nextFloat(); // Same value
+```
+
+## Weighted Sampling
+
+```javascript
+import { rng, weightedPick, reservoirSample } from 'nox';
+
+const r = rng();
+const items = ['A', 'B', 'C'];
+const weights = [0.5, 0.3, 0.2];
+
+weightedPick(items, weights, r);        // Pick with probabilities
+reservoirSample(stream, k, r);          // Sample k from large stream
+```
+
+## Statistical Tests
+
+```javascript
+import { rng, meanTest, varianceTest, kolmogorovSmirnovTest } from 'nox';
+
+const r = rng();
+const data = r.floats(1000);
+
+const mean = meanTest(data);            // Test mean ≈ 0.5
+const variance = varianceTest(data);    // Test variance ≈ 1/12
+const ks = kolmogorovSmirnovTest(data); // Test uniform distribution
+```
+
+## Generators
+
+For reproducible results or specific generator properties:
+
+```javascript
+import { RNG, PCG64, MT19937, Xorshift64, Splitmix64 } from 'nox';
+
+const r = new RNG(PCG64, seed);      // PCG64 (default, fast, high quality)
+const r = new RNG(MT19937, seed);    // MT19937 (Mersenne Twister)
+const r = new RNG(Xorshift64, seed); // Xorshift64 (simple, fast)
+const r = new RNG(Splitmix64, seed); // Splitmix64 (statistical mixing)
+```
+
+## License
+
+ISC

package/docs/API.md

@@ -0,0 +1,70 @@
+# API
+
+## Core
+
+### `rng()`
+Create a random number generator with automatic entropy.
+
+```javascript
+const r = rng();
+r.nextFloat();  // [0, 1)
+r.nextInt(100); // [0, 100)
+r.int(1, 100);  // [1, 100]
+r.bool(0.3);    // true 30% of time
+```
+
+### `deterministic(seed)`
+Create a generator with fixed seed for reproducibility.
+
+```javascript
+const r = deterministic(42);
+// Always same sequence
+```
+
+## Distributions
+
+```javascript
+import { rng, normal, exponential, uniform, poisson } from 'nox';
+
+const r = rng();
+normal(r, mean=0, stddev=1);
+exponential(r, lambda=1);
+uniform(r, 0, 1);
+poisson(r, lambda=5);
+```
+
+## Sampling
+
+```javascript
+import { rng, shuffle, pick, sample } from 'nox';
+
+const r = rng();
+shuffle([1, 2, 3], r);         // Shuffled copy
+pick(['a', 'b', 'c'], r);      // Random element
+sample([1, 2, 3, 4, 5], 3, r); // 3 elements without replacement
+```
+
+## State
+
+```javascript
+import { rng, saveState, restoreState } from 'nox';
+
+const r = rng();
+const snapshot = saveState(r);
+
+r.nextFloat();
+restoreState(r, snapshot);
+r.nextFloat(); // Same as before
+```
+
+## Generators
+
+Advanced: use specific generators directly.
+
+```javascript
+import { PCG64, MT19937, Xorshift64 } from 'nox';
+
+new PCG64(seed);      // Best quality (default)
+new MT19937(seed);    // Classic, very fast
+new Xorshift64(seed); // Fast, good quality
+```

package/example/README.md

@@ -0,0 +1,26 @@
+# nox Demo
+
+Interactive demo of the @cloudglides/nox random number generator library.
+
+## Setup
+
+```bash
+npm install
+npm run dev
+```
+
+Visit http://localhost:5173
+
+## Features Demonstrated
+
+- **Basic Operations**: nextFloat, int, bool, range, choice
+- **Batch Operations**: Generate multiple values at once
+- **Distributions**: Normal and exponential distributions
+- **Statistical Tests**: Mean, variance, and Kolmogorov-Smirnov tests
+- **Deterministic Mode**: Reproducible sequences with seeds
+
+## Technology
+
+- React 18
+- Vite
+- @cloudglides/nox v1.1.0

package/example/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>nox - RNG Demo</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>