rng-with-intention 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Todd Wilson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# rng-with-intention
+
+A random number generator that uses human intention as a seed, designed for divination and contemplative practices.
+
+## Philosophy
+
+Digital randomness often feels hollow in spiritual or contemplative contexts because it lacks the intentionality present in physical practices like shuffling tarot cards or casting runes. This library bridges that gap by:
+
+1. **Using intention as the primary input** - Your words, thoughts, or questions become part of the randomness
+2. **Capturing the precise moment** - The exact millisecond you submit your intention matters
+3. **Remaining ephemeral** - Intentions are never stored, only used to seed that single moment
+4. **Adding true randomness** - System entropy ensures the same intention at different moments produces different results
+
+## Installation
+
+```bash
+npm install rng-with-intention
+```
+
+## Usage
+
+### Basic usage
+
+```javascript
+import { RngWithIntention } from 'rng-with-intention';
+
+const rngi = new RngWithIntention();
+
+// Draw a single card from a 78-card tarot deck
+const result = rngi.draw("What do I need to know today?", 78);
+console.log(result);
+// { index: 42, timestamp: '2024-12-31T09:47:23.847Z' }
+```
+
+### Drawing multiple values
+
+```javascript
+// Draw a 3-card spread
+const spread = rngi.drawMultiple("Past, present, future", 78, 3);
+console.log(spread);
+// { indices: [5, 32, 67], timestamp: '2024-12-31T09:47:23.847Z' }
+
+// Draw unique cards (no duplicates)
+const uniqueSpread = rngi.drawMultiple("Celtic Cross", 78, 10, false);
+```
+
+### Configuration options
+
+```javascript
+// Disable timestamp (makes draws deterministic for same intention)
+const deterministicRng = new RngWithIntention({
+  includeTimestamp: false,
+  includeEntropy: false
+});
+
+// Same intention will always produce same result
+const result1 = deterministicRng.draw("test", 100);
+const result2 = deterministicRng.draw("test", 100);
+// result1.index === result2.index (always true)
+```
+
+## API
+
+### `new RngWithIntention(options)`
+
+Create a new instance with optional configuration.
+
+**Options:**
+- `includeTimestamp` (boolean, default: `true`) - Include timestamp in seed
+- `includeEntropy` (boolean, default: `true`) - Include cryptographic randomness in seed
+
+### `draw(intention, max)`
+
+Draw a single random number.
+
+**Parameters:**
+- `intention` (string, required) - Your intention, question, or focus
+- `max` (number, required) - Maximum value (exclusive, returns 0 to max-1)
+
+**Returns:**
+- `{ index: number, timestamp: string }`
+
+### `drawMultiple(intention, max, count, allowDuplicates)`
+
+Draw multiple random numbers with a single intention.
+
+**Parameters:**
+- `intention` (string, required) - Your intention
+- `max` (number, required) - Maximum value for each draw
+- `count` (number, required) - Number of values to draw
+- `allowDuplicates` (boolean, default: `true`) - Whether to allow repeated indices
+
+**Returns:**
+- `{ indices: number[], timestamp: string }`
+
+## Use Cases
+
+- **Tarot readings** - Digital card draws with intentionality
+- **Oracle cards** - Any deck-based divination system
+- **I Ching** - Hexagram generation
+- **Rune casting** - Random rune selection
+- **Creative constraints** - Intentional prompts for writing, art, music
+- **Journaling** - Daily prompts seeded by your current state
+- **Decision making** - When you need the universe to weigh in
+
+## How It Works
+
+1. You provide an intention (any string)
+2. The exact timestamp is captured (down to milliseconds)
+3. System entropy is added (cryptographic randomness)
+4. These are combined and hashed with SHA-256
+5. The hash is converted to a number in your desired range
+6. The intention is discarded (never stored)
+
+The result is randomness that feels **shaped by your intention** rather than purely mechanical.
+
+## License
+
+MIT
+
+## Contributing
+
+Issues and pull requests welcome! This library aims to remain simple and focused.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "rng-with-intention",
+  "version": "0.1.0",
+  "description": "A random number generator that uses human intention as a seed, designed for divination and contemplative practices",
+  "main": "src/index.js",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/**/*.test.js"
+  },
+  "keywords": [
+    "random",
+    "rng",
+    "intention",
+    "divination",
+    "tarot",
+    "contemplative",
+    "seed"
+  ],
+  "author": "Todd Wilson",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/w8s/rng-with-intention.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/RngWithIntention.js

@@ -0,0 +1,123 @@
+import crypto from 'crypto';
+
+/**
+ * RngWithIntention - A random number generator seeded by human intention
+ * 
+ * This class creates random numbers using a combination of:
+ * - User intention (as text or any string)
+ * - Precise timestamp (when intention is submitted)
+ * - System entropy (cryptographic randomness)
+ * 
+ * The intention is never stored - it exists only as the seed for that moment.
+ */
+export class RngWithIntention {
+  /**
+   * Create a new RngWithIntention instance
+   * @param {Object} options - Configuration options
+   * @param {boolean} options.includeTimestamp - Include timestamp in seed (default: true)
+   * @param {boolean} options.includeEntropy - Include system entropy in seed (default: true)
+   */
+  constructor(options = {}) {
+    this.options = {
+      includeTimestamp: true,
+      includeEntropy: true,
+      ...options
+    };
+  }
+
+  /**
+   * Draw a random number based on intention
+   * @param {string} intention - The user's intention (any text)
+   * @param {number} max - Maximum value (exclusive, returns 0 to max-1)
+   * @returns {Object} { index: number, timestamp: string }
+   */
+  draw(intention, max) {
+    if (!intention || typeof intention !== 'string') {
+      throw new Error('Intention must be a non-empty string');
+    }
+    
+    if (!Number.isInteger(max) || max <= 0) {
+      throw new Error('Max must be a positive integer');
+    }
+
+    // Capture the exact moment
+    const timestamp = new Date().toISOString();
+    
+    // Build the seed from components
+    let seedComponents = [intention];
+    
+    if (this.options.includeTimestamp) {
+      seedComponents.push(timestamp);
+    }
+    
+    if (this.options.includeEntropy) {
+      // Add cryptographic randomness
+      const entropy = crypto.randomBytes(16).toString('hex');
+      seedComponents.push(entropy);
+    }
+    
+    // Create seed (ephemeral - not stored)
+    const seedString = seedComponents.join('::');
+    
+    // Hash the seed to get deterministic bytes
+    const hash = crypto.createHash('sha256').update(seedString).digest();
+    
+    // Convert hash bytes to a number in range [0, max)
+    // Use multiple bytes to reduce modulo bias
+    const bytes = hash.readUInt32BE(0);
+    const index = bytes % max;
+    
+    return {
+      index,
+      timestamp
+    };
+  }
+
+  /**
+   * Draw multiple random numbers with a single intention
+   * @param {string} intention - The user's intention
+   * @param {number} max - Maximum value for each draw
+   * @param {number} count - Number of values to draw
+   * @param {boolean} allowDuplicates - Whether to allow the same index multiple times (default: true)
+   * @returns {Object} { indices: number[], timestamp: string }
+   */
+  drawMultiple(intention, max, count, allowDuplicates = true) {
+    if (!Number.isInteger(count) || count <= 0) {
+      throw new Error('Count must be a positive integer');
+    }
+    
+    if (!allowDuplicates && count > max) {
+      throw new Error('Cannot draw more unique values than max allows');
+    }
+
+    const timestamp = new Date().toISOString();
+    const indices = [];
+    const used = new Set();
+
+    for (let i = 0; i < count; i++) {
+      // Modify intention slightly for each draw to ensure different results
+      const modifiedIntention = `${intention}::draw${i}`;
+      const result = this.draw(modifiedIntention, max);
+      
+      if (allowDuplicates) {
+        indices.push(result.index);
+      } else {
+        // Keep drawing until we get an unused index
+        let attempts = 0;
+        let index = result.index;
+        while (used.has(index) && attempts < max * 2) {
+          const retry = this.draw(`${modifiedIntention}::retry${attempts}`, max);
+          index = retry.index;
+          attempts++;
+        }
+        used.add(index);
+        indices.push(index);
+      }
+    }
+
+    return {
+      indices,
+      timestamp
+    };
+  }
+}

package/src/index.js

@@ -0,0 +1 @@
+export { RngWithIntention } from './RngWithIntention.js';