feat(core): enhance Developer Experience with fail-fast guards and convenience methods

- Prevented meaningless regex generation by throwing IllegalArgumentException on between(0,0) and atMost(0).
- Added anyOf(List) overload to support dynamic regex generation, optimizing single-element lists.
- Exposed andNothingElse() to VariableConnectorStep and VariableCharacterClassConnectorStep interfaces to avoid spurious .then() calls.
- Introduced a zero-cost default matches(CharSequence) method in SiftPattern for immediate validation without verbose matcher chaining.

Author: Mirkoddd

sift-core/src/main/java/com/mirkoddd/sift/core/SiftPatterns.java

@@ -73,6 +73,35 @@ public static SiftPattern anyOf(SiftPattern option1, SiftPattern option2, SiftPa
         });
     }
 
+    /**
+     * Creates a non-capturing group matching any of the provided patterns dynamically.
+     *
+     * @param patterns A list of SiftPatterns.
+     * @return A SiftPattern combining the provided options.
+     * @throws IllegalArgumentException if the list is null or empty.
+     */
+    public static SiftPattern anyOf(java.util.List<? extends SiftPattern> patterns) {
+        if (patterns == null || patterns.isEmpty()) {
+            throw new IllegalArgumentException("anyOf() requires at least one pattern in the list.");
+        }
+        if (patterns.size() == 1) {
+            return patterns.get(0); // QoL Optimization: no need to wrap a single element
+        }
+
+        return () -> {
+            StringBuilder sb = new StringBuilder();
+            sb.append(RegexSyntax.NON_CAPTURING_GROUP_OPEN);
+            for (int i = 0; i < patterns.size(); i++) {
+                sb.append(patterns.get(i).shake());
+                if (i < patterns.size() - 1) {
+                    sb.append(RegexSyntax.OR);
+                }
+            }
+            sb.append(RegexSyntax.GROUP_CLOSE);
+            return sb.toString();
+        };
+    }
+
     /**
      * Wraps a pattern in a <b>Capturing Group</b> {@code (...)}.
      * <p>

sift-core/src/main/java/com/mirkoddd/sift/core/SiftQuantifier.java

@@ -69,14 +69,16 @@ public TypeStep<VariableConnectorStep, VariableCharacterClassConnectorStep> opti
 
     @Override
     public TypeStep<VariableConnectorStep, VariableCharacterClassConnectorStep> atMost(int max) {
-        if (max <= 0) throw new IllegalArgumentException("Max quantity must be strictly positive: " + max);
+        if (max == 0) throw new IllegalArgumentException("atMost(0) is invalid as it always matches an empty string.");
+        if (max < 0) throw new IllegalArgumentException("Max quantity cannot be negative: " + max);
         PatternAssembler next = assembler.copy();
         next.setQuantifier(RegexSyntax.QUANTIFIER_OPEN + "0" + RegexSyntax.COMMA + max + RegexSyntax.QUANTIFIER_CLOSE);
         return new SiftVariableType(next);
     }
 
     @Override
     public TypeStep<VariableConnectorStep, VariableCharacterClassConnectorStep> between(int min, int max) {
+        if (min == 0 && max == 0) throw new IllegalArgumentException("between(0, 0) is invalid as it always matches an empty string.");
         if (min < 0) throw new IllegalArgumentException("Min quantity cannot be negative: " + min);
         if (max <= 0) throw new IllegalArgumentException("Max quantity must be strictly positive: " + max);
         if (min > max) throw new IllegalArgumentException("Min cannot be greater than max");

sift-core/src/main/java/com/mirkoddd/sift/core/dsl/SiftPattern.java

@@ -100,4 +100,18 @@ public Pattern sieve() {
     default Pattern sieve() {
         return Pattern.compile(this.shake());
     }
+
+    /**
+     * Convenience method to quickly test if a given input matches this pattern completely.
+     * Under the hood, this compiles the regex (or uses the cached one) and evaluates it.
+     *
+     * @param input The text to evaluate.
+     * @return true if the entire input matches the pattern, false otherwise or if input is null.
+     */
+    default boolean matches(CharSequence input) {
+        if (input == null) {
+            return false;
+        }
+        return sieve().matcher(input).matches();
+    }
 }

sift-core/src/main/java/com/mirkoddd/sift/core/dsl/VariableCharacterClassConnectorStep.java

@@ -30,4 +30,16 @@ public interface VariableCharacterClassConnectorStep extends VariableConnectorSt
 
     @Override
     VariableCharacterClassConnectorStep excluding(char excluded, char... additionalExcluded);
+
+    /**
+     * Anchors the pattern to the end of the input string using {@code $}.
+     * <p>
+     * Use this terminal operation when you want to ensure that there are no trailing
+     * characters after the matched sequence. Calling this method immediately concludes
+     * the fluent chain and returns the final executable pattern.
+     *
+     * @return The final {@link SiftPattern} ready for evaluation.
+     */
+    @Override
+    SiftPattern andNothingElse();
 }

sift-core/src/main/java/com/mirkoddd/sift/core/dsl/VariableConnectorStep.java

@@ -51,4 +51,16 @@ public interface VariableConnectorStep extends ConnectorStep {
      * @return A standard {@link ConnectorStep}, as lazy modifiers cannot be stacked.
      */
     ConnectorStep asFewAsPossible();
+
+    /**
+     * Anchors the pattern to the end of the input string using {@code $}.
+     * <p>
+     * Use this terminal operation when you want to ensure that there are no trailing
+     * characters after the matched sequence. Calling this method immediately concludes
+     * the fluent chain and returns the final executable pattern.
+     *
+     * @return The final {@link SiftPattern} ready for evaluation.
+     */
+    @Override
+    SiftPattern andNothingElse();
 }

sift-core/src/test/java/com/mirkoddd/sift/core/SiftPatternsTest.java

@@ -266,4 +266,65 @@ void shouldMemoizeShakeAndSieveResults() {
         assertEquals("cache-test", firstSieve.pattern());
         assertSame(firstSieve, secondSieve, "sieve() should return the exact same Pattern instance from cache.");
     }
+
+    @Test
+    @DisplayName("anyOf(List) should throw IllegalArgumentException for null or empty lists")
+    void testAnyOfListNullOrEmpty() {
+        IllegalArgumentException nullEx = assertThrows(IllegalArgumentException.class,
+                () -> SiftPatterns.anyOf((java.util.List<SiftPattern>) null));
+        assertTrue(nullEx.getMessage().contains("requires at least one pattern"));
+
+        IllegalArgumentException emptyEx = assertThrows(IllegalArgumentException.class,
+                () -> SiftPatterns.anyOf(java.util.Collections.emptyList()));
+        assertTrue(emptyEx.getMessage().contains("requires at least one pattern"));
+    }
+
+    @Test
+    @DisplayName("anyOf(List) should optimize single-element lists by avoiding unnecessary grouping")
+    void testAnyOfListSingleElementOptimization() {
+        SiftPattern singlePattern = Sift.fromStart().digits();
+
+        SiftPattern result = SiftPatterns.anyOf(java.util.Collections.singletonList(singlePattern));
+
+        assertEquals("^[0-9]", result.shake(),
+                "Should return the exact pattern without the (?:...) wrapper overhead");
+    }
+
+    @Test
+    @DisplayName("anyOf(List) should wrap multiple elements in a non-capturing OR group")
+    void testAnyOfListMultipleElements() {
+        SiftPattern p1 = Sift.fromAnywhere().letters();
+        SiftPattern p2 = Sift.fromAnywhere().digits();
+        SiftPattern p3 = Sift.fromAnywhere().character('-');
+
+        SiftPattern result = SiftPatterns.anyOf(java.util.Arrays.asList(p1, p2, p3));
+
+        assertEquals("(?:[a-zA-Z]|[0-9]|-)", result.shake(),
+                "Should accurately wrap multiple patterns separated by the OR operator");
+    }
+
+    @Test
+    @DisplayName("matches(CharSequence) should correctly evaluate inputs, handle nulls, and support StringBuilders")
+    void testPatternMatchesConvenienceMethod() {
+        SiftPattern pattern = Sift.fromStart().exactly(3).digits().andNothingElse();
+
+        // Branch 1: Null safety
+        assertFalse(pattern.matches(null),
+                "Should gracefully return false when the input is null, avoiding NullPointerException");
+
+        // Branch 2: Valid match (Standard String)
+        assertTrue(pattern.matches("123"),
+                "Should return true for a string that perfectly matches the pattern");
+
+        // Branch 3: Invalid match
+        assertFalse(pattern.matches("12a"),
+                "Should return false for a string with invalid characters");
+        assertFalse(pattern.matches("1234"),
+                "Should return false for a string that exceeds the exact length bounds");
+
+        // Branch 4: CharSequence polymorphism (Zero-cost abstraction)
+        StringBuilder sbInput = new StringBuilder("987");
+        assertTrue(pattern.matches(sbInput),
+                "Should natively support other CharSequence implementations like StringBuilder without allocations");
+    }
 }

sift-core/src/test/java/com/mirkoddd/sift/core/SiftTest.java

@@ -257,6 +257,35 @@ void testQuantifierExceptions() {
             assertThrows(IllegalArgumentException.class, () -> fromAnywhere().between(5, 2)); // min > max
         }
 
+        @Test
+        @DisplayName("atMost() and between() should exhaustively validate boundaries and throw IllegalArgumentException")
+        void testQuantifierBoundaryGuards() {
+            // --- atMost() exhaustive branches ---
+            assertThrows(IllegalArgumentException.class, () -> Sift.fromStart().atMost(0),
+                    "Should block atMost(0)");
+            assertThrows(IllegalArgumentException.class, () -> Sift.fromStart().atMost(-1),
+                    "Should block negative max values in atMost()");
+
+            // --- between() exhaustive branches ---
+            assertThrows(IllegalArgumentException.class, () -> Sift.fromStart().between(0, 0),
+                    "Should block between(0, 0) specifically");
+
+            assertThrows(IllegalArgumentException.class, () -> Sift.fromStart().between(-1, 5),
+                    "Should block negative min values");
+
+            assertThrows(IllegalArgumentException.class, () -> Sift.fromStart().between(2, 0),
+                    "Should block max <= 0 (e.g., 0 with a valid min)");
+
+            assertThrows(IllegalArgumentException.class, () -> Sift.fromStart().between(2, -1),
+                    "Should block max <= 0 (e.g., negative max with a valid min)");
+
+            assertThrows(IllegalArgumentException.class, () -> Sift.fromStart().between(5, 2),
+                    "Should block when min is strictly greater than max");
+
+            assertDoesNotThrow(() -> Sift.fromStart().between(0, 5),
+                    "Should successfully allow min=0 as long as max > 0 (e.g., {0,5})");
+        }
+
         @Test
         @DisplayName("Should correctly generate regex for wordChars, whitespace, optionally, and andNothingElse")
         void testNewTypesAndTerminals() {