0
# Unique Random
1

2
Unique Random generates random numbers that are consecutively unique. It provides two distinct algorithms: consecutive uniqueness (ensuring no two consecutive random numbers are the same) and exhaustive uniqueness (cycling through all possible values before repeating). Both functions return callable functions that are also iterable, making them versatile for different usage patterns.
3

4
## Package Information
5

6
- **Package Name**: unique-random
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install unique-random`
10

11
## Core Imports
12

13
```javascript
14
import { consecutiveUniqueRandom, exhaustiveUniqueRandom } from "unique-random";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { consecutiveUniqueRandom, exhaustiveUniqueRandom } = require("unique-random");
21
```
22

23
## Basic Usage
24

25
```javascript
26
import { consecutiveUniqueRandom } from "unique-random";
27

28
const random = consecutiveUniqueRandom(1, 10);
29

30
console.log(random(), random(), random());
31
//=> 5 2 6
32
```
33

34
The returned function is also iterable:
35

36
```javascript
37
import { exhaustiveUniqueRandom } from "unique-random";
38

39
const random = exhaustiveUniqueRandom(1, 10);
40

41
for (const number of random) {
42
  console.log(number);
43
  
44
  // The unique numbers will be iterated over infinitely
45
  if (stopCondition) {
46
    break;
47
  }
48
}
49
```
50

51
## Capabilities
52

53
### Consecutive Unique Random
54

55
Generate random numbers that are consecutively unique, meaning that each number in the sequence is distinct from the one immediately before it.
56

57
```typescript { .api }
58
/**
59
 * Generate random numbers that are consecutively unique
60
 * @param minimum - Lower bound of random range (inclusive)
61
 * @param maximum - Upper bound of random range (inclusive)
62
 * @returns A function that returns random numbers, also implements Symbol.iterator
63
 */
64
function consecutiveUniqueRandom(
65
  minimum: number, 
66
  maximum: number
67
): (() => number) & {[Symbol.iterator](): Iterator<number>};
68
```
69

70
**Usage Examples:**
71

72
```javascript
73
import { consecutiveUniqueRandom } from "unique-random";
74

75
// Basic function calls
76
const random = consecutiveUniqueRandom(1, 5);
77
console.log(random()); // e.g., 3
78
console.log(random()); // e.g., 1 (never 3 again immediately)
79
console.log(random()); // e.g., 4 (never 1 again immediately)
80

81
// Iterator usage
82
const randomIterator = consecutiveUniqueRandom(1, 3);
83
for (const value of randomIterator) {
84
  console.log(value); // Infinite sequence: 2, 1, 3, 2, 1, ...
85
  if (someCondition) break;
86
}
87

88
// Manual iterator
89
const manualRandom = consecutiveUniqueRandom(1, 10);
90
const iterator = manualRandom[Symbol.iterator]();
91
console.log(iterator.next().value); // Random number 1-10
92
console.log(iterator.next().value); // Different from previous
93
```
94

95
**Behavior:**
96
- Ensures consecutive calls never return the same value
97
- If minimum === maximum, always returns that same value
98
- Generates infinite sequences without memory accumulation
99
- Suitable for slideshows, games, and scenarios requiring immediate variety
100

101
### Exhaustive Unique Random
102

103
Generate random numbers that do not repeat until the entire range has appeared. This function cycles through all possible values before repeating any value.
104

105
```typescript { .api }
106
/**
107
 * Generate random numbers that do not repeat until the entire range has appeared
108
 * @param minimum - Lower bound of random range (inclusive)
109
 * @param maximum - Upper bound of random range (inclusive)
110
 * @returns A function that returns random numbers, also implements Symbol.iterator
111
 */
112
function exhaustiveUniqueRandom(
113
  minimum: number, 
114
  maximum: number
115
): (() => number) & {[Symbol.iterator](): Iterator<number>};
116
```
117

118
**Usage Examples:**
119

120
```javascript
121
import { exhaustiveUniqueRandom } from "unique-random";
122

123
// Exhaustive cycling through range
124
const random = exhaustiveUniqueRandom(1, 3);
125
console.log(random()); // e.g., 2
126
console.log(random()); // e.g., 1 (not 2)
127
console.log(random()); // e.g., 3 (not 2 or 1)
128
console.log(random()); // Now cycle resets, could be any of 1, 2, 3
129

130
// Iterator usage
131
const exhaustiveIterator = exhaustiveUniqueRandom(1, 4);
132
const values = [];
133
for (let i = 0; i < 8; i++) {
134
  values.push(exhaustiveIterator().next ? exhaustiveIterator() : exhaustiveIterator());
135
}
136
// values contains all numbers 1-4 twice, but in random order within each cycle
137

138
// Fair distribution for games
139
const diceRoll = exhaustiveUniqueRandom(1, 6);
140
// Guarantees each number 1-6 appears once before any repeats
141
```
142

143
**Behavior:**
144
- Cycles through all possible values in the range before repeating
145
- Also maintains consecutive uniqueness (no immediate repeats)
146
- Resets after exhausting all unique values in the range
147
- If minimum === maximum, always returns that same value
148
- Memory usage scales with range size (stores unconsumed values)
149
- Ideal for fair distribution scenarios and preventing long streaks
150

151
## Types
152

153
```typescript { .api }
154
// Return type for both functions - callable and iterable
155
type UniqueRandomFunction = (() => number) & {
156
  [Symbol.iterator](): Iterator<number>;
157
};
158

159
// Iterator interface
160
interface Iterator<T> {
161
  next(): { value: T; done: boolean };
162
}
163
```
164

165
## Edge Cases
166

167
- **Equal bounds**: When `minimum === maximum`, both functions always return the same value
168
- **Single value range**: `consecutiveUniqueRandom(5, 5)` and `exhaustiveUniqueRandom(5, 5)` both always return 5
169
- **Range validation**: No explicit parameter validation - relies on mathematical operations
170
- **Memory considerations**: `exhaustiveUniqueRandom` keeps an array of unconsumed values proportional to range size
171
- **Infinite iteration**: Both functions produce infinite sequences - always include break conditions in loops
172

173
## Common Use Cases
174

175
- **Slideshows**: Prevent immediate slide repetition with `consecutiveUniqueRandom`
176
- **Game mechanics**: Fair dice rolls or card draws with `exhaustiveUniqueRandom`
177
- **Background rotation**: Cycle through backgrounds/themes without immediate repeats
178
- **Playlist shuffling**: Ensure all songs play before any repeat with `exhaustiveUniqueRandom`
179
- **Testing scenarios**: Generate varied test data with uniqueness constraints