feat: add unique and uniqueByInput methods

feat: add unique and uniqueByInput methods

Author: avallete

README.md

@@ -354,7 +354,7 @@ copycat.phoneNumber('foo')
 ```
 ```js
 copycat.phoneNumber('foo', { prefixes: ['+3319900', '+3363998'], min: 1000, max: 9999 })
-// => '+33639983457'
+// => '+33639987662'
 ```
 
 **note** The strings _resemble_ phone numbers, but will not always be valid. For example, the country dialing code may not exist, or for a particular country, the number of digits may be incorrect. Please let us know if you need valid
@@ -377,6 +377,90 @@ copycat.username('foo')
 #### `options`
 - **`limit`:** Constrain generated values to be less than or equal to `limit` number of chars
 
+### `copycat.unique(input, method, store, options)`
+
+The `unique` function is tailored to maintain uniqueness of values after they have undergone a specific transformation.
+This method is especially useful when the transformed values need to be unique, regardless of whether the input values are identical.
+It will do so by trying to generate a new value multiples times (up to attempts time) until it finds a unique one.
+
+**note** This method will try its best to generate unique values, but be aware of these limitations:
+1. The uniqueness is not guaranteed, but the probability of generating a duplicate is lower as the number of attempts increases.
+2. On the contrary of the other methods, the `unique` method is not stateless. It will store the generated values in the `store` object to ensure uniqueness.
+Meaning that the deterministic property over input is not guaranteed anymore. Now the determinism is based over a combination of:
+  - the `input` value
+  - the state of the `store` object
+  - the number of `attempts`
+3. The `unique` method as it alter the global copycat hashKey between attemps before restoring the original one, it is not thread safe.
+4. If duplicates exists in the passed `input` accross calls, the method might hide those duplicates by generating a unique value for each of them.
+If you want to ensure duplicate value for duplicate input you should use the `uniqueByInput` method.
+
+#### `parameters`
+
+- **`input`** (_Input_): The seed input for the generation method.
+- **`method`** (_Function_): A deterministic function that takes `input` and returns a value of type `T`.
+- **`store`** (_Store<T>_): A store object to track generated values and ensure uniqueness. It must have `has(value: T): boolean` and `add(value: T): void` methods.
+- **`options`** (_UniqueOptions_): An optional configuration object for additional control.
+
+#### `options`
+
+- **`attempts`** (_number_): The maximum number of attempts to generate a unique value. Defaults to 10.
+- **`attemptsReached`** (_Function_): An optional callback function that is called when the maximum number of attempts is reached.
+
+```js
+// Define a method to generate a value
+const generateValue = (seed) => {
+  return copycat.int(seed, { max: 3 });
+};
+// Create a store to track unique values
+const store = new Set();
+// Use the unique method to generate a unique number
+copycat.unique('exampleSeed', generateValue, store);
+// => 3
+copycat.unique('exampleSeed1', generateValue, store);
+// => 1
+copycat.unique('exampleSeed', generateValue, store);
+// => 0
+```
+
+### `copycat.uniqueByInput(input, method, inputStore, resultStore, options)`
+
+The `uniqueByInput` function is designed to generate unique values while preserving duplicates for identical inputs.
+It is particularly useful in scenarios where input consistency needs to be maintained alongside the uniqueness of the transformed values.
+- **Preserving Input Duplication**: If the same input is provided multiple times, `uniqueByInput` ensures that the transformed value is consistently the same for each occurrence of that input.
+- **Uniqueness Preservation**: For new and unique inputs, `uniqueByInput` employs the `unique` method to generate distinct values, avoiding duplicates in the `resultStore`.
+
+#### `parameters`
+
+- **`input`** (_Input_): The seed input for the generation method.
+- **`method`** (_Function_): A deterministic function that takes `input` and returns a value of type `T`.
+- **`inputStore`** (_Store_): A store object to track the inputs and ensure consistent output for duplicate inputs.
+- **`resultStore`** (_Store_): A store object to track the generated values and ensure their uniqueness.
+- **`options`** (_UniqueOptions_): An optional configuration object for additional control.
+
+#### `options`
+
+- **`attempts`** (_number_): The maximum number of attempts to generate a unique value after transformation. Defaults to 10.
+- **`attemptsReached`** (_Function_): An optional callback function that is invoked when the maximum number of attempts is reached.
+
+```js
+// Define a method to generate a value
+const method = (seed) => {
+  return copycat.int(seed, { max: 3 });
+};
+
+// Create stores to track unique values and inputs
+const resultStore = new Set();
+const inputStore = new Set();
+
+// Generate a unique number or retrieve the existing one for duplicate input
+copycat.uniqueByInput('exampleSeed', method, inputStore, resultStore);
+// => 3
+copycat.uniqueByInput('exampleSeed1', method, inputStore, resultStore);
+// => 1
+copycat.uniqueByInput('exampleSeed', method, inputStore, resultStore);
+// => 3
+```
+
 ### `copycat.password(input)`
 
 Takes in an [`input`](#input) value and returns a string value resembling a password.

src/copycat.ts

@@ -19,5 +19,7 @@ export * from './ipv4'
 export * from './mac'
 export * from './userAgent'
 export * from './scramble'
-export * from './hash'
 export * from './oneOfString'
+export { generateHashKey, setHashKey } from './hash'
+export { unique } from './unique'
+export { uniqueByInput } from './uniqueByInput'

src/hash.ts

@@ -1,4 +1,18 @@
-import { hash } from 'fictional'
+import { HashKey, hash } from 'fictional'
+
+// We need to be able to get and set the hash key used by fictional from outside of fictional.
+// for the copycat.unique method to work.
+const hashKey = {
+  value: hash.generateKey('chinochinochino!') as string | HashKey,
+}
+export function getHashKey() {
+  return hashKey.value
+}
+
+function setKey(key: string | HashKey) {
+  hashKey.value = key
+  return hash.setKey(key)
+}
 
 // We'll use this function to generate a hash key using fictional requirement
 // for a 16 character string from arbitrary long string input.
@@ -19,7 +33,7 @@ function derive16CharacterString(input: string) {
   return output.padEnd(16, '0')
 }
 
-export const setHashKey = hash.setKey
+export const setHashKey = setKey
 
 export const generateHashKey = (input: string) => {
   return input.length === 16

src/unique.test.ts

@@ -0,0 +1,256 @@
+import { copycat } from '.'
+import { randomUUID } from 'crypto'
+
+test('should be able to generate 5 unique numbers with low possibility space', () => {
+  const collisionsStore = new Set()
+  let numberOfCollisions = 0
+  const method = (seed): number => {
+    return copycat.int(seed, { min: 0, max: 5 })
+  }
+  const store = new Set<ReturnType<typeof method>>()
+  const results: Array<number> = []
+  for (let i = 0; i <= 5; i++) {
+    const result = copycat.unique(i, method, store, {
+      attempts: 100,
+    })
+    results.push(result)
+    if (collisionsStore.has(result)) {
+      numberOfCollisions++
+    } else {
+      collisionsStore.add(result)
+    }
+  }
+  results.sort()
+  // Without unique would be [1,1,1,2,2,4]
+  expect(results).toEqual([0, 1, 2, 3, 4, 5])
+  expect(numberOfCollisions).toBe(0)
+})
+
+test('should be able to generate 5 unique numbers with low possibility space based on random seed', () => {
+  const collisionsStore = new Set()
+  let numberOfCollisions = 0
+  const store = new Set<ReturnType<typeof method>>()
+  const method = (seed): number => {
+    return copycat.int(seed, { min: 0, max: 5 })
+  }
+  const results: Array<number> = []
+  for (let i = 0; i <= 5; i++) {
+    const result = copycat.unique(randomUUID(), method, store, {
+      attempts: 100,
+    })
+    results.push(result)
+    if (collisionsStore.has(result)) {
+      numberOfCollisions++
+    } else {
+      collisionsStore.add(result)
+    }
+  }
+  results.sort()
+  expect(results).toEqual([0, 1, 2, 3, 4, 5])
+  expect(numberOfCollisions).toBe(0)
+})
+
+test('should work with scramble method and not alter method input value', () => {
+  const collisionsStore = new Set()
+  let numberOfCollisions = 0
+  const store = new Set<ReturnType<typeof method>>()
+  const method = (seed): string => {
+    return copycat.scramble(seed)
+  }
+  const results: Array<string> = []
+  const textInputs = [
+    'hello world',
+    'hello world',
+    'this is another test',
+    'never gonna give you up',
+    'never gonna let you down',
+    'never gonna run around and desert you',
+  ]
+  for (let i = 0; i <= 5; i++) {
+    const result = copycat.unique(textInputs[i], method, store, {
+      attempts: 100,
+    })
+    results.push(result)
+    if (collisionsStore.has(result)) {
+      numberOfCollisions++
+    } else {
+      collisionsStore.add(result)
+    }
+  }
+  // Without unique the two first results would be the same
+  expect(results).toEqual([
+    'zmnmq ngcsx',
+    // Since we are using the same input, we should keep the same "shape"
+    'zvzkv uviju',
+    'wnzx dd tqjjomm jmnz',
+    'ugwfa zugvm xhky hbn fo',
+    'bxhyr wojeg cvi kcu untf',
+    'daylm ztnpp enf clrzkb toe bjhgzu yfu',
+  ])
+  expect(numberOfCollisions).toBe(0)
+})
+
+test('should call attempsReached when no more attempts are available', () => {
+  const store = new Set<ReturnType<typeof method>>()
+  const method = (seed): number => {
+    return copycat.int(seed, { min: 0, max: 5 })
+  }
+  let attemptReachedCalled = false
+  for (let i = 0; i <= 5; i++) {
+    copycat.unique(i, method, store, {
+      attempts: 1,
+      attemptsReached: () => {
+        attemptReachedCalled = true
+      },
+    })
+  }
+  expect(attemptReachedCalled).toBe(true)
+})
+
+test('should restore the same hashKey when done', () => {
+  const store = new Set<ReturnType<typeof method>>()
+  const originalResult = copycat.int(1)
+  const method = (seed): number => {
+    return copycat.int(seed, { min: 0, max: 5 })
+  }
+  for (let i = 0; i <= 5; i++) {
+    copycat.unique(i, method, store, {
+      attempts: 100,
+    })
+  }
+  // The hashKey should be restored to its original value
+  // so that the next call to copycat.int(1) returns the same result
+  // as if copycat.unique was never called.
+  expect(copycat.int(1)).toBe(originalResult)
+})
+
+test('should rethrow too much attempts error', () => {
+  const store = new Set<ReturnType<typeof method>>()
+  const method = (seed): number => {
+    return copycat.int(seed, { min: 0, max: 5 })
+  }
+  // Ensure the store is already full
+  store.add(0)
+  store.add(1)
+  store.add(2)
+  store.add(3)
+  store.add(4)
+  store.add(5)
+  expect(() =>
+    copycat.unique(1, method, store, {
+      attempts: 1,
+      attemptsReached: () => {
+        throw new Error('Too much attempts')
+      },
+    })
+  ).toThrowError('Too much attempts')
+})
+
+test('should not alter hash key if method throw an error', () => {
+  const store = new Set<ReturnType<typeof method>>()
+  const originalResult = copycat.int(1)
+  const method = (): number => {
+    throw new Error('Method error')
+  }
+  // Ensure the store is already full
+  store.add(0)
+  store.add(1)
+  store.add(2)
+  store.add(3)
+  store.add(4)
+  store.add(5)
+  expect(() =>
+    copycat.unique(1, method, store, {
+      attempts: 1,
+      attemptsReached: () => {
+        throw new Error('Too much attempts')
+      },
+    })
+  ).toThrowError('Method error')
+  // The hashKey should be restored to its original value
+  // so that the next call to copycat.int(1) returns the same result
+  // as if copycat.unique was never called.
+  expect(copycat.int(1)).toBe(originalResult)
+})
+
+test('should restore the same hashKey even if throwing error after too much attempts', () => {
+  const store = new Set<ReturnType<typeof method>>()
+  const originalResult = copycat.int(1)
+  const method = (seed): number => {
+    return copycat.int(seed, { min: 0, max: 5 })
+  }
+
+  // Ensure the store is already full
+  store.add(0)
+  store.add(1)
+  store.add(2)
+  store.add(3)
+  store.add(4)
+  store.add(5)
+  expect(() =>
+    copycat.unique(1, method, store, {
+      attempts: 1,
+      attemptsReached: () => {
+        throw new Error('Too much attempts')
+      },
+    })
+  ).toThrowError('Too much attempts')
+  // The hashKey should be restored to its original value
+  // so that the next call to copycat.int(1) returns the same result
+  // as if copycat.unique was never called.
+  expect(copycat.int(1)).toBe(originalResult)
+})
+
+test('should be able to generate 8999 unique fictional french phone numbers', () => {
+  const collisionsStore = new Set()
+  let numberOfCollisions = 0
+  const method = (seed): string => {
+    return copycat.phoneNumber(seed, {
+      prefixes: ['+3319900'],
+      min: 1000,
+      max: 9999,
+    })
+  }
+  const store = new Set<ReturnType<typeof method>>()
+  const results: Array<string> = []
+  for (let i = 0; i <= 8999; i++) {
+    const result = copycat.unique(i, method, store, {
+      // Bellow 2500 attempts, the test fails because of collisions
+      attempts: 2500,
+    })
+    results.push(result)
+    if (collisionsStore.has(result)) {
+      numberOfCollisions++
+    } else {
+      collisionsStore.add(result)
+    }
+  }
+  expect(numberOfCollisions).toBe(0)
+})
+
+test('should be able to generate 8999 unique fictional french phone numbers with uuid', () => {
+  const collisionsStore = new Set()
+  let numberOfCollisions = 0
+  const method = (seed): string => {
+    return copycat.phoneNumber(seed, {
+      prefixes: ['+3319900'],
+      min: 1000,
+      max: 9999,
+    })
+  }
+  const store = new Set<ReturnType<typeof method>>()
+  const results: Array<string> = []
+  for (let i = 0; i <= 8999; i++) {
+    const result = copycat.unique(randomUUID(), method, store, {
+      // Bellow 100k with random uuid there is still a 1/1000 chance of collision
+      attempts: 100000,
+    })
+    results.push(result)
+    if (collisionsStore.has(result)) {
+      numberOfCollisions++
+    } else {
+      collisionsStore.add(result)
+    }
+  }
+  expect(numberOfCollisions).toBe(0)
+})