refactor(helpers)!: remove v8 deprecated unique (#2661)

Co-authored-by: Eric Cheng <ericcheng9316@gmail.com>
Co-authored-by: Matt Mayer <matt@matthewmayer.co.uk>

docs/.vitepress/config.ts

@@ -213,6 +213,10 @@ const config: UserConfig<DefaultTheme.Config> = {
             text: 'Randomizer',
             link: '/guide/randomizer',
           },
+          {
+            text: 'Unique Values',
+            link: '/guide/unique',
+          },
           {
             text: 'Upgrading to v9',
             link: '/guide/upgrading',

docs/guide/unique.md

@@ -0,0 +1,58 @@
+# Unique Values
+
+In general, Faker methods do not return unique values.
+
+```ts
+faker.seed(55);
+faker.animal.type(); //'cat'
+faker.animal.type(); //'bird'
+faker.animal.type(); //'horse'
+faker.animal.type(); //'horse'
+```
+
+Some methods and locales use much smaller data sets than others. For example, `faker.animal.type` has only 13 possible animals to choose from. In contrast, `faker.person.fullName()` pulls from a list of hundreds of first names, surnames, and prefixes/suffixes, so it can generate hundreds of thousands of unique names. Even then, the [birthday paradox](https://en.wikipedia.org/wiki/Birthday_Paradox) means that duplicate values will quickly be generated.
+
+Sometimes, you want to generate unique values. For example, you may wish to have unique values in a database email column.  
+There are a few possible strategies for this:
+
+1. Use `faker.helpers.uniqueArray()` if you want to generate all the values at one time. For example:
+
+```ts
+faker.helpers.uniqueArray(faker.internet.email, 1000); // will generate 1000 unique email addresses
+```
+
+2. If there are insufficient values for your needs, consider prefixing or suffixing values with your own sequential values, for example you could prefix `1.`, `2.` to each generated email in turn.
+
+3. Build your own logic to keep track of a set of previously generated values and regenerate values as necessary if a duplicate is generated
+
+4. Use a third party package to enforce uniqueness such as [enforce-unique](https://github.com/MansurAliKoroglu/enforce-unique)
+
+Note you can supply a maximum time (in milliseconds) or maximum number of retries.
+
+```js
+import { EnforceUniqueError, UniqueEnforcer } from 'enforce-unique';
+
+const uniqueEnforcerEmail = new UniqueEnforcer();
+
+function createRandomUser() {
+  const firstName = faker.person.firstName();
+  const lastName = faker.person.lastName();
+  const email = uniqueEnforcerEmail.enforce(
+    () =>
+      faker.internet.email({
+        firstName,
+        lastName,
+      }),
+    {
+      maxTime: 50,
+      maxRetries: 50,
+    }
+  );
+
+  return {
+    firstName,
+    lastName,
+    email,
+  };
+}
+```

docs/guide/upgrading_v9/2661.md

@@ -0,0 +1,65 @@
+### Remove helpers.unique
+
+Prior to v9, Faker provided a [`faker.helpers.unique()`](https://v8.fakerjs.dev/api/helpers.html#unique) method which had a global store to keep track of duplicates. This was removed in v9.
+
+Please see the [unique values guide](/guide/unique) for alternatives.
+
+For example, many simple use cases can use [`faker.helpers.uniqueArray`](https://v8.fakerjs.dev/api/helpers.html#uniqueArray). Or you can migrate to a third party package such as `enforce-unique`:
+
+Basic example:
+
+```js
+// OLD
+const name = faker.helpers.unique(faker.person.firstName);
+
+// NEW
+import { UniqueEnforcer } from 'enforce-unique';
+//const { UniqueEnforcer } = require("enforce-unique") // CJS
+
+const enforcerName = new UniqueEnforcer();
+const name = enforcerName.enforce(faker.person.firstName);
+```
+
+With parameters:
+
+```js
+// OLD
+const stateCode = faker.helpers.unique(faker.location.state, [
+  {
+    abbreviated: true,
+  },
+]);
+
+// NEW
+import { UniqueEnforcer } from 'enforce-unique';
+
+const enforcerState = new UniqueEnforcer();
+const stateCode = enforcerState.enforce(() =>
+  faker.location.state({
+    abbreviated: true,
+  })
+);
+```
+
+With options:
+
+```js
+// OLD
+const city = faker.helpers.unique(faker.location.city, [], {
+  maxRetries: 100,
+  maxTime: 1000,
+});
+
+// NEW
+import { UniqueEnforcer } from 'enforce-unique';
+
+const enforcer = new UniqueEnforcer();
+const city = enforcer.enforce(faker.location.city, {
+  maxRetries: 100,
+  maxTime: 1000,
+});
+```
+
+::: tip Note
+`enforce-unique` does not support the `exclude` or `store` options. If you were previously using these, you may wish to build your own unique logic instead.
+:::

docs/guide/usage.md

@@ -233,45 +233,6 @@ Here, we could also pass in the `sex` value as argument, but in our use-case the
 By doing this first, we are able to pass both names into the `email` generation function.
 This allows the value to be more reasonable based on the provided arguments.
 
-But we can take this even another step further.
-Opposite to the `_id` property that uses an `uuid` implementation, which is unique by design, the `email` property potentially isn't.
-But, in most use-cases, this would be desirable.
-
-Faker has your back, with another helper method:
-
-```ts {7-10}
-import { faker } from '@faker-js/faker';
-
-function createRandomUser(): User {
-  const sex = faker.person.sexType();
-  const firstName = faker.person.firstName(sex);
-  const lastName = faker.person.lastName();
-  const email = faker.helpers.unique(faker.internet.email, [
-    firstName,
-    lastName,
-  ]);
-
-  return {
-    _id: faker.string.uuid(),
-    avatar: faker.image.avatar(),
-    birthday: faker.date.birthdate(),
-    email,
-    firstName,
-    lastName,
-    sex,
-    subscriptionTier: faker.helpers.arrayElement(['free', 'basic', 'business']),
-  };
-}
-
-const user = createRandomUser();
-```
-
-By wrapping Faker's `email` function with the [`unique`](../api/helpers.md#unique) helper function, we ensure that the return value of `email` is always unique.
-
-::: warning
-The `faker.helpers.unique` is targeted to be removed from Faker in the future.  
-Please have a look at the issue [#1785](https://github.com/faker-js/faker/issues/1785).  
-We will update these docs once a replacement is available.
-:::
+Unlike the `_id` property that uses an `uuid` implementation, which has a low chance of duplicates, the `email` function is more likely to produce duplicates, especially if the call arguments are similar. We have a dedicated guide page on generating [unique values](unique).
 
 Congratulations, you should now be able to create any complex object you desire. Happy faking 🥳.

src/modules/helpers/index.ts

@@ -4,8 +4,6 @@ import { deprecated } from '../../internal/deprecated';
 import { SimpleModuleBase } from '../../internal/module-base';
 import { fakeEval } from './eval';
 import { luhnCheckValue } from './luhn-check';
-import type { RecordKey } from './unique';
-import * as uniqueExec from './unique';
 
 /**
  * Returns a number based on given RegEx-based quantifier symbol or quantifier values.
@@ -204,14 +202,6 @@ export function legacyReplaceSymbolWithNumber(
  * Module with various helper methods providing basic (seed-dependent) operations useful for implementing faker methods (without methods requiring localized data).
  */
 export class SimpleHelpersModule extends SimpleModuleBase {
-  /**
-   * Global store of unique values.
-   * This means that faker should *never* return duplicate values across all API methods when using `faker.helpers.unique` without passing `options.store`.
-   *
-   * @internal
-   */
-  private readonly uniqueStore: Record<RecordKey, RecordKey> = {};
-
   /**
    * Slugifies the given string.
    * For that all spaces (` `) are replaced by hyphens (`-`)
@@ -1129,114 +1119,6 @@ export class SimpleHelpersModule extends SimpleModuleBase {
     return this.faker.number.int(numberOrRange);
   }
 
-  /**
-   * Generates a unique result using the results of the given method.
-   * Used unique entries will be stored internally and filtered from subsequent calls.
-   *
-   * @template TMethod The type of the method to execute.
-   *
-   * @param method The method used to generate the values.
-   * @param args The arguments used to call the method. Defaults to `[]`.
-   * @param options The optional options used to configure this method.
-   * @param options.startTime This parameter does nothing.
-   * @param options.maxTime The time in milliseconds this method may take before throwing an error. Defaults to `50`.
-   * @param options.maxRetries The total number of attempts to try before throwing an error. Defaults to `50`.
-   * @param options.currentIterations This parameter does nothing.
-   * @param options.exclude The value or values that should be excluded/skipped. Defaults to `[]`.
-   * @param options.compare The function used to determine whether a value was already returned. Defaults to check the existence of the key.
-   * @param options.store The store of unique entries. Defaults to a global store.
-   *
-   * @see https://github.com/faker-js/faker/issues/1785#issuecomment-1407773744
-   *
-   * @example
-   * faker.helpers.unique(faker.person.firstName) // 'Corbin'
-   *
-   * @since 7.5.0
-   *
-   * @deprecated Please find a dedicated npm package instead, or even create one on your own if you want to.
-   * More info can be found in issue [faker-js/faker #1785](https://github.com/faker-js/faker/issues/1785).
-   */
-  unique<
-    TMethod extends (
-      // TODO @Shinigami92 2023-02-14: This `any` type can be fixed by anyone if they want to.
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      ...parameters: any[]
-    ) => RecordKey,
-  >(
-    method: TMethod,
-    args: Parameters<TMethod> = [] as unknown as Parameters<TMethod>,
-    options: {
-      /**
-       * This parameter does nothing.
-       *
-       * @default new Date().getTime()
-       */
-      startTime?: number;
-      /**
-       * The time in milliseconds this method may take before throwing an error.
-       *
-       * @default 50
-       */
-      maxTime?: number;
-      /**
-       * The total number of attempts to try before throwing an error.
-       *
-       * @default 50
-       */
-      maxRetries?: number;
-      /**
-       * This parameter does nothing.
-       *
-       * @default 0
-       */
-      currentIterations?: number;
-      /**
-       * The value or values that should be excluded/skipped.
-       *
-       * @default []
-       */
-      exclude?: RecordKey | RecordKey[];
-      /**
-       * The function used to determine whether a value was already returned.
-       *
-       * Defaults to check the existence of the key.
-       *
-       * @default (obj, key) => (obj[key] === undefined ? -1 : 0)
-       */
-      compare?: (obj: Record<RecordKey, RecordKey>, key: RecordKey) => 0 | -1;
-      /**
-       * The store of unique entries.
-       *
-       * Defaults to a global store.
-       */
-      store?: Record<RecordKey, RecordKey>;
-    } = {}
-  ): ReturnType<TMethod> {
-    deprecated({
-      deprecated: 'faker.helpers.unique',
-      proposed:
-        'https://github.com/faker-js/faker/issues/1785#issuecomment-1407773744',
-      since: '8.0',
-      until: '9.0',
-    });
-
-    const {
-      maxTime = 50,
-      maxRetries = 50,
-      exclude = [],
-      store = this.uniqueStore,
-    } = options;
-    return uniqueExec.exec(method, args, {
-      ...options,
-      startTime: Date.now(),
-      maxTime,
-      maxRetries,
-      currentIterations: 0,
-      exclude,
-      store,
-    });
-  }
-
   /**
    * Generates an array containing values returned by the given method.
    *