refactor: Extract text searching out of TextField (#1054)

* refactor: Add SubstringMatcher class

This will be used to simplify TextField's implementation

* refactor: Adjust TextField to use SubstringMatcher

* refactor: Add RegexMatcher class

This will be used to simplify TextField's implementation

* refactor: TextField now uses RegexMatcher

* refactor: RegexMatcher now validates user input

* refactor: Better parameter name in SubstringMatcher

* refactor: Extract interface StringMatcher

* refactor: RegexMatcher implements StringMatcher

* refactor: Rename StringMatcher to IStringMatcher

* refactor: Fix typo in method name validateAndStruct()

* comment: Add JSDoc docs for new classes

* refactor: Add public keyword to make method visibility explicit

* refactor: Remove cyclic dependency between TextField and SubstringMatcher

by moving the implementation from TextField to SubstringMatcher,
but leaving the original in place as a thin wrapper around the
new one, to localise the change.

Author: claremacrae

src/Query/Filter/TextField.ts

@@ -1,4 +1,6 @@
 import type { Task } from '../../Task';
+import { SubstringMatcher } from '../Matchers/SubstringMatcher';
+import { RegexMatcher } from '../Matchers/RegexMatcher';
 import { Field } from './Field';
 import { FilterOrErrorMessage } from './Filter';
 
@@ -14,30 +16,24 @@ export abstract class TextField extends Field {
         if (match !== null) {
             const filterMethod = match[1];
             if (['includes', 'does not include'].includes(filterMethod)) {
-                result.filter = (task: Task) =>
-                    TextField.maybeNegate(
-                        TextField.stringIncludesCaseInsensitive(
-                            this.value(task),
-                            match[2],
-                        ),
+                const matcher = new SubstringMatcher(match[2]);
+                result.filter = (task: Task) => {
+                    return TextField.maybeNegate(
+                        matcher.matches(this.value(task)),
                         filterMethod,
                     );
+                };
             } else if (
                 ['regex matches', 'regex does not match'].includes(filterMethod)
             ) {
-                // Courtesy of https://stackoverflow.com/questions/17843691/javascript-regex-to-match-a-regex
-                const regexPattern =
-                    /\/((?![*+?])(?:[^\r\n[/\\]|\\.|\[(?:[^\r\n\]\\]|\\.)*])+)\/((?:g(?:im?|mi?)?|i(?:gm?|mg?)?|m(?:gi?|ig?)?)?)/;
-                const query = match[2].match(regexPattern);
-
-                if (query !== null) {
-                    result.filter = (task: Task) =>
-                        TextField.maybeNegate(
-                            this.value(task).match(
-                                new RegExp(query[1], query[2]),
-                            ) !== null,
+                const matcher = RegexMatcher.validateAndConstruct(match[2]);
+                if (matcher !== null) {
+                    result.filter = (task: Task) => {
+                        return TextField.maybeNegate(
+                            matcher.matches(this.value(task)),
                             filterMethod,
                         );
+                    };
                 } else {
                     result.error = `cannot parse regex (${this.fieldName()}); check your leading and trailing slashes for your query`;
                 }
@@ -54,9 +50,7 @@ export abstract class TextField extends Field {
         haystack: string,
         needle: string,
     ): boolean {
-        return haystack
-            .toLocaleLowerCase()
-            .includes(needle.toLocaleLowerCase());
+        return SubstringMatcher.stringIncludesCaseInsensitive(haystack, needle);
     }
 
     protected filterRegexp(): RegExp {

src/Query/Matchers/IStringMatcher.ts

@@ -0,0 +1,13 @@
+/**
+ * An interface for determining whether a string value matches a particular condition.
+ *
+ * This is used to hide away the details of various text searches, such as the
+ * simple inclusion of a sub-string, or the more complex regular expression searches.
+ */
+export interface IStringMatcher {
+    /**
+     * Return whether the given string matches this condition.
+     * @param stringToSearch
+     */
+    matches(stringToSearch: string): boolean;
+}

src/Query/Matchers/RegexMatcher.ts

@@ -0,0 +1,45 @@
+import type { IStringMatcher } from './IStringMatcher';
+
+/**
+ * Regular-expression-based implementation of IStringMatcher.
+ */
+export class RegexMatcher implements IStringMatcher {
+    private readonly regex: RegExp;
+
+    /**
+     * Construct a RegexMatcher object.
+     *
+     * @param regex {RegExp} - A valid regular expression
+     */
+    public constructor(regex: RegExp) {
+        this.regex = regex;
+    }
+
+    /**
+     * Construct a RegexMatcher object if the supplied string is a valid regular expression.
+     * and null if not.
+     *
+     * @param {string} regexInput - A string that can be converted to a regular expression.
+     *                              It must begin with a /, and end either with / and optionally any
+     *                              valid flags.
+     */
+    public static validateAndConstruct(
+        regexInput: string,
+    ): RegexMatcher | null {
+        // Courtesy of https://stackoverflow.com/questions/17843691/javascript-regex-to-match-a-regex
+        const regexPattern =
+            /\/((?![*+?])(?:[^\r\n[/\\]|\\.|\[(?:[^\r\n\]\\]|\\.)*])+)\/((?:g(?:im?|mi?)?|i(?:gm?|mg?)?|m(?:gi?|ig?)?)?)/;
+        const query = regexInput.match(regexPattern);
+
+        if (query !== null) {
+            const regExp = new RegExp(query[1], query[2]);
+            return new RegexMatcher(regExp);
+        } else {
+            return null;
+        }
+    }
+
+    public matches(stringToSearch: string): boolean {
+        return stringToSearch.match(this.regex) !== null;
+    }
+}

src/Query/Matchers/SubstringMatcher.ts

@@ -0,0 +1,36 @@
+import type { IStringMatcher } from './IStringMatcher';
+
+/**
+ * Substring-based implementation of IStringMatcher.
+ *
+ * This does a case-insensitive search for the given string.
+ */
+export class SubstringMatcher implements IStringMatcher {
+    private readonly stringToFind: string;
+
+    /**
+     * Construct a SubstringMatcher object
+     *
+     * @param {string} stringToFind - The string to search for.
+     *                                Searches will be case-insensitive.
+     */
+    public constructor(stringToFind: string) {
+        this.stringToFind = stringToFind;
+    }
+
+    public matches(stringToSearch: string): boolean {
+        return SubstringMatcher.stringIncludesCaseInsensitive(
+            stringToSearch,
+            this.stringToFind,
+        );
+    }
+
+    public static stringIncludesCaseInsensitive(
+        haystack: string,
+        needle: string,
+    ): boolean {
+        return haystack
+            .toLocaleLowerCase()
+            .includes(needle.toLocaleLowerCase());
+    }
+}

tests/Query/Matchers/RegexMatcher.test.ts

@@ -0,0 +1,24 @@
+import { RegexMatcher } from '../../../src/Query/Matchers/RegexMatcher';
+
+describe('RegexMatcher', () => {
+    it('should match simple regular expression', () => {
+        const regex: RegExp = /^hello world$/;
+        const matcher = new RegexMatcher(regex);
+        expect(matcher.matches('hello world')).toStrictEqual(true);
+        expect(matcher.matches('xx hello world yy')).toStrictEqual(false);
+        expect(matcher.matches('search me')).toStrictEqual(false);
+    });
+
+    it('should construct regex from a valid string', () => {
+        const matcher = RegexMatcher.validateAndConstruct('/hello world/i');
+        expect(matcher).not.toBeNull();
+        expect(matcher!.matches('hello world')).toStrictEqual(true);
+        expect(matcher!.matches('HELLO world')).toStrictEqual(true); // Confirm that the flag 'i' is retained
+        expect(matcher!.matches('Bye Bye')).toStrictEqual(false);
+    });
+
+    it('should not construct regex from an INvalid string', () => {
+        const matcher = RegexMatcher.validateAndConstruct('I have no slashes');
+        expect(matcher).toBeNull();
+    });
+});

tests/Query/Matchers/SubstringMatcher.test.ts

@@ -0,0 +1,10 @@
+import { SubstringMatcher } from '../../../src/Query/Matchers/SubstringMatcher';
+
+describe('SubstringMatcher', () => {
+    it('should match simple text', () => {
+        const matcher = new SubstringMatcher('find me');
+        expect(matcher.matches('find me')).toStrictEqual(true);
+        expect(matcher.matches('prefix find me suffix')).toStrictEqual(true);
+        expect(matcher.matches('FIND ME')).toStrictEqual(true);
+    });
+});