feat: add UniqueEnforcer and UniqueFairy for unique value generation

Add fairy.unique() returning UniqueFairy (Person by email, Company by name,
IBAN/CreditCard by number) and UniqueEnforcer.of() for custom key extraction.
Throws UniqueGenerationException after max retries (default 10,000).

Closes #9

Author: mariuszs

src/main/java/com/devskiller/jfairy/Fairy.java

@@ -132,4 +132,24 @@ public CreditCard creditCard() {
 	public NetworkProducer networkProducer() {
 		return networkProducer;
 	}
+
+	/**
+	 * Returns a {@link UniqueFairy} that ensures generated objects are unique
+	 * by their natural key (email for Person, name for Company, etc.).
+	 *
+	 * @return A {@link UniqueFairy} instance
+	 */
+	public UniqueFairy unique() {
+		return new UniqueFairy(this, UniqueEnforcer.DEFAULT_MAX_RETRIES);
+	}
+
+	/**
+	 * Returns a {@link UniqueFairy} with custom max retries.
+	 *
+	 * @param maxRetries maximum generation attempts before throwing
+	 * @return A {@link UniqueFairy} instance
+	 */
+	public UniqueFairy unique(int maxRetries) {
+		return new UniqueFairy(this, maxRetries);
+	}
 }

src/main/java/com/devskiller/jfairy/UniqueEnforcer.java

@@ -0,0 +1,79 @@
+package com.devskiller.jfairy;
+
+import java.util.HashSet;
+import java.util.Objects;
+import java.util.Set;
+import java.util.function.Function;
+import java.util.function.Supplier;
+
+/**
+ * Wraps a generator to ensure unique values based on a key extractor.
+ * Throws {@link UniqueGenerationException} after max retries.
+ *
+ * <p>This class is not thread-safe. Each thread should use its own instance.</p>
+ *
+ * <pre>{@code
+ * Fairy fairy = Fairy.create();
+ * UniqueEnforcer<Person> unique = UniqueEnforcer.of(fairy::person, Person::getEmail);
+ * Person p1 = unique.next(); // guaranteed unique email
+ * Person p2 = unique.next(); // different email than p1
+ * unique.reset();            // clear history
+ * }</pre>
+ *
+ * @param <T> type of generated object
+ */
+public final class UniqueEnforcer<T> {
+
+	static final int DEFAULT_MAX_RETRIES = 10_000;
+
+	private final Supplier<T> defaultGenerator;
+	private final Function<T, ?> keyExtractor;
+	private final int maxRetries;
+	private final Set<Object> seen = new HashSet<>();
+
+	private UniqueEnforcer(Supplier<T> defaultGenerator, Function<T, ?> keyExtractor, int maxRetries) {
+		this.defaultGenerator = Objects.requireNonNull(defaultGenerator, "generator must not be null");
+		this.keyExtractor = Objects.requireNonNull(keyExtractor, "keyExtractor must not be null");
+		if (maxRetries < 1) {
+			throw new IllegalArgumentException("maxRetries must be positive, got: " + maxRetries);
+		}
+		this.maxRetries = maxRetries;
+	}
+
+	public static <T> UniqueEnforcer<T> of(Supplier<T> generator, Function<T, ?> keyExtractor) {
+		return new UniqueEnforcer<>(generator, keyExtractor, DEFAULT_MAX_RETRIES);
+	}
+
+	public static <T> UniqueEnforcer<T> of(Supplier<T> generator, Function<T, ?> keyExtractor, int maxRetries) {
+		return new UniqueEnforcer<>(generator, keyExtractor, maxRetries);
+	}
+
+	public T next() {
+		return next(defaultGenerator);
+	}
+
+	/**
+	 * Generate a unique value using a custom supplier, tracking uniqueness
+	 * in the same seen-set as {@link #next()}.
+	 */
+	public T next(Supplier<T> generator) {
+		for (int i = 0; i < maxRetries; i++) {
+			T value = generator.get();
+			Object key = keyExtractor.apply(value);
+			if (seen.add(key)) {
+				return value;
+			}
+		}
+		throw new UniqueGenerationException(
+				"Could not generate a unique value after " + maxRetries + " retries. "
+						+ seen.size() + " unique values were generated before exhaustion.");
+	}
+
+	public void reset() {
+		seen.clear();
+	}
+
+	public int size() {
+		return seen.size();
+	}
+}

src/main/java/com/devskiller/jfairy/UniqueFairy.java

@@ -0,0 +1,78 @@
+package com.devskiller.jfairy;
+
+import com.devskiller.jfairy.producer.company.Company;
+import com.devskiller.jfairy.producer.company.CompanyProperties;
+import com.devskiller.jfairy.producer.payment.CreditCard;
+import com.devskiller.jfairy.producer.payment.IBAN;
+import com.devskiller.jfairy.producer.payment.IBANProperties;
+import com.devskiller.jfairy.producer.person.Person;
+import com.devskiller.jfairy.producer.person.PersonProperties;
+
+/**
+ * Convenience wrapper that ensures generated objects are unique by their
+ * natural key (email for Person, name for Company, etc.).
+ *
+ * <p>Uniqueness is tracked per entity type. A person email will not conflict
+ * with a company name. Call {@link #reset()} to clear all tracked values.</p>
+ *
+ * <p>This class is not thread-safe. Store the reference and reuse it —
+ * calling {@code fairy.unique()} in a loop creates independent instances
+ * with no shared tracking.</p>
+ *
+ * <pre>{@code
+ * UniqueFairy unique = fairy.unique();
+ * Person p1 = unique.person();  // unique by email
+ * Person p2 = unique.person();  // different email than p1
+ * Company c = unique.company(); // unique by name
+ * unique.reset();
+ * }</pre>
+ */
+public final class UniqueFairy {
+
+	private final Fairy fairy;
+	private final UniqueEnforcer<Person> personEnforcer;
+	private final UniqueEnforcer<Company> companyEnforcer;
+	private final UniqueEnforcer<IBAN> ibanEnforcer;
+	private final UniqueEnforcer<CreditCard> creditCardEnforcer;
+
+	UniqueFairy(Fairy fairy, int maxRetries) {
+		this.fairy = fairy;
+		this.personEnforcer = UniqueEnforcer.of(fairy::person, Person::getEmail, maxRetries);
+		this.companyEnforcer = UniqueEnforcer.of(fairy::company, Company::getName, maxRetries);
+		// Lambda needed: fairy::iban is ambiguous (overloaded no-arg and vararg)
+		this.ibanEnforcer = UniqueEnforcer.of(() -> fairy.iban(), IBAN::getIbanNumber, maxRetries);
+		this.creditCardEnforcer = UniqueEnforcer.of(fairy::creditCard, CreditCard::getCardNumber, maxRetries);
+	}
+
+	public Person person(PersonProperties.PersonProperty... personProperties) {
+		if (personProperties.length == 0) {
+			return personEnforcer.next();
+		}
+		return personEnforcer.next(() -> fairy.person(personProperties));
+	}
+
+	public Company company(CompanyProperties.CompanyProperty... companyProperties) {
+		if (companyProperties.length == 0) {
+			return companyEnforcer.next();
+		}
+		return companyEnforcer.next(() -> fairy.company(companyProperties));
+	}
+
+	public IBAN iban(IBANProperties.Property... properties) {
+		if (properties.length == 0) {
+			return ibanEnforcer.next();
+		}
+		return ibanEnforcer.next(() -> fairy.iban(properties));
+	}
+
+	public CreditCard creditCard() {
+		return creditCardEnforcer.next();
+	}
+
+	public void reset() {
+		personEnforcer.reset();
+		companyEnforcer.reset();
+		ibanEnforcer.reset();
+		creditCardEnforcer.reset();
+	}
+}

src/main/java/com/devskiller/jfairy/UniqueGenerationException.java

@@ -0,0 +1,8 @@
+package com.devskiller.jfairy;
+
+public class UniqueGenerationException extends RuntimeException {
+
+	public UniqueGenerationException(String message) {
+		super(message);
+	}
+}

src/test/groovy/com/devskiller/jfairy/UniqueEnforcerSpec.groovy

@@ -0,0 +1,116 @@
+package com.devskiller.jfairy
+
+import com.devskiller.jfairy.producer.person.Person
+import com.devskiller.jfairy.producer.company.Company
+import spock.lang.Specification
+
+class UniqueEnforcerSpec extends Specification {
+
+	private Fairy fairy = Fairy.create()
+
+	def "should generate unique persons by email"() {
+		given:
+			def unique = UniqueEnforcer.of(fairy.&person, { Person p -> p.email })
+		when:
+			def persons = (1..50).collect { unique.next() }
+			def emails = persons.collect { it.email }
+		then:
+			emails.toSet().size() == 50
+	}
+
+	def "should generate unique companies by name"() {
+		given:
+			def unique = UniqueEnforcer.of(fairy.&company, { Company c -> c.name })
+		when:
+			def companies = (1..20).collect { unique.next() }
+			def names = companies.collect { it.name }
+		then:
+			names.toSet().size() == 20
+	}
+
+	def "should throw after max retries with small pool"() {
+		given:
+			int counter = 0
+			def unique = UniqueEnforcer.of({ -> counter++ % 3 }, { it }, 100)
+		when:
+			unique.next() // 0
+			unique.next() // 1
+			unique.next() // 2
+			unique.next() // should fail - only 3 unique values possible
+		then:
+			thrown(UniqueGenerationException)
+	}
+
+	def "should reset tracked values"() {
+		given:
+			int counter = 0
+			def unique = UniqueEnforcer.of({ -> counter++ % 2 }, { it }, 100)
+		when:
+			unique.next() // 0
+			unique.next() // 1
+			unique.reset()
+			unique.next() // 0 again - OK after reset
+		then:
+			unique.size() == 1
+	}
+
+	def "should track size"() {
+		given:
+			def unique = UniqueEnforcer.of(fairy.&person, { Person p -> p.email })
+		when:
+			(1..10).each { unique.next() }
+		then:
+			unique.size() == 10
+	}
+
+	def "should allow custom max retries"() {
+		given:
+			def unique = UniqueEnforcer.of({ -> "same" }, { it }, 5)
+		when:
+			unique.next() // OK first time
+			unique.next() // should fail after 5 retries
+		then:
+			def e = thrown(UniqueGenerationException)
+			e.message.contains("5 retries")
+	}
+
+	def "should share seen set between default and custom suppliers"() {
+		given:
+			int counter = 0
+			def unique = UniqueEnforcer.of({ -> counter++ }, { it }, 100)
+		when:
+			unique.next()                          // 0 via default
+			unique.next({ -> counter++ } as java.util.function.Supplier)  // 1 via custom
+			unique.next()                          // 2 via default
+		then:
+			unique.size() == 3
+	}
+
+	def "should reject zero maxRetries"() {
+		when:
+			UniqueEnforcer.of({ -> "x" }, { it }, 0)
+		then:
+			thrown(IllegalArgumentException)
+	}
+
+	def "should reject negative maxRetries"() {
+		when:
+			UniqueEnforcer.of({ -> "x" }, { it }, -1)
+		then:
+			thrown(IllegalArgumentException)
+	}
+
+	def "should reject null generator"() {
+		when:
+			UniqueEnforcer.of(null, { it })
+		then:
+			thrown(NullPointerException)
+	}
+
+	def "should reject null keyExtractor"() {
+		when:
+			UniqueEnforcer.of({ -> "x" }, null)
+		then:
+			thrown(NullPointerException)
+	}
+}