Replaced regex search flag with regex operator and added unique/distinct/duplicate functions

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ztimson/utils",
-	"version": "0.29.7",
+	"version": "0.30.0",
 	"description": "Utility library",
 	"author": "Zak Timson",
 	"license": "MIT",

src/search.ts

@@ -1,44 +1,122 @@
 import {JSONAttemptParse, JSONSerialize} from './json.ts';
 import {dotNotation} from './objects.ts';
 
-/**
- * Filters an array of objects based on a search term and optional regex checking.
- *
- * @param {Array} rows Array of objects to filter
- * @param {string} search The logic string or regext to filter on
- * @param {boolean} [regex=false] Treat search expression as regex
- * @param {Function} [transform=(r) => r] - Transform rows before filtering
- * @return {Array} The filtered array of objects that matched search
- */
-export function search(rows: any[], search: string, regex?: boolean, transform: Function = (r: any) => r) {
-	if(!rows) return [];
-	return rows.filter(r => {
-		// Empty search
-		if(!search) return true;
-		const value = transform(r);
-		// Regex search
-		if(regex) {
-			return !!Object.values(value).filter((v: any) => {
-				try { return RegExp(search, 'gm').test(v.toString()); }
-				catch { return false; }
-			}).length
-		} else {
-			return logicTest(value, search);
-		}
-	});
+const VALID_FLAGS = new Set([...'dgimsuvy']);
+
+function toRegex(pattern: string, defaultFlags = 'gm'): RegExp | null {
+	const lit = /^\/(.+)\/([a-zA-Z]*)$/.exec(pattern);
+	try { return lit ? new RegExp(lit[1], lit[2]) : new RegExp(pattern, defaultFlags); }
+	catch { return null; }
 }
 
 /**
- * Test an object against a logic condition. By default values are checked
- * @param {string} condition
- * @param {object} target
- * @return {boolean}
+ * Filters an array of objects based on a query string.
+ *
+ * Supports plain text, regex, boolean/logical operators, and dataset helpers.
+ *
+ * **Examples**
+ * ```js
+ * search(rows: T[], 'alice'): T[] // Case-Insensitive
+ * search(rows: T[], 'Alice'): T[] // Case-Sensitive
+ *
+ * search(rows: T[], 'name = Alice'): T[] // loose equality
+ * search(rows: T[], 'name != Alice'): T[] // loose inequality
+ * search(rows: T[], 'role += admin'): T[] // Contains
+ * search(rows: T[], 'status -= archived'): T[] // Not Contain
+ * search(rows: T[], 'age > 18'): T[] // Greater Than
+ * search(rows: T[], 'age >= 18'): T[] // Greater Than or Equal
+ * search(rows: T[], 'age < 18'): T[] // Less Than
+ * search(rows: T[], 'age <= 18'): T[] // Less Than or Equal
+ *
+ * search(rows: T[], '/^alice/gi'): T[] // Global Regex
+ * search(rows: T[], 'name =~ ^Al'): T[] // Regex Match (shorthand)
+ * search(rows: T[], 'name =~ /^al/i'): T[] // Regex Match (with flags)
+ * search(rows: T[], 'email !~ /@test\.com$/i'): T[] // Regex Not Match
+ *
+ * search(rows: T[], 'unique(email)'): T[] // Unique property values
+ * search(rows: T[], 'duplicate(email)'): T[] // Duplicate property values
+ * search(rows: T[], 'distinct(type)'): T[] // Distinct property values
+ *
+ * search(rows: T[], 'active && role != admin'): T[] // ANDs
+ * search(rows: T[], 'email != null || distinct(email)'): T[] // ORs
+ * ```
+ *
+ * @param rows - Array of objects to filter
+ * @param query - Query string; see supported syntax above
+ * @param transform - Optional transform applied to each row before matching
+ * @returns The filtered array of rows
+ */
+export function search(rows: any[], query: string, transform: (r: any) => any = r => r): any[] {
+	if (!rows || !query?.trim()) return rows ?? [];
+
+	const q = query.trim();
+
+	// Global regex: /pattern/flags — strict, whole string, at least one valid flag
+	const globalRegex = /^\/(.+)\/([a-zA-Z]+)$/.exec(q);
+	if (globalRegex && [...globalRegex[2]].every(f => VALID_FLAGS.has(f))) {
+		const re = toRegex(q);
+		return rows.filter(r => re && Object.values(transform(r)).some((v: any) => {
+			try { return re.test(v?.toString() ?? ''); } catch { return false; }
+		}));
+	}
+
+	// Split top-level && into predicates and dataset helpers
+	const parts = q.split('&&').map(p => p.trim());
+	const helpers = parts.filter(p => /^(unique|duplicate|distinct)\(\w+\)$/.test(p));
+	const predicate = parts.filter(p => !helpers.includes(p)).join(' && ');
+
+	let filtered = predicate
+		? rows.filter(r => logicTest(transform(r), predicate))
+		: [...rows];
+
+	for (const h of helpers) {
+		const [, fn, field] = /^(\w+)\((\w+)\)$/.exec(h)!;
+		if (fn === 'distinct') continue; // run last
+		const freq = new Map<any, number>();
+		filtered.forEach(r => { const v = dotNotation(transform(r), field); freq.set(v, (freq.get(v) ?? 0) + 1); });
+		filtered = filtered.filter(r => fn === 'unique' ? freq.get(dotNotation(transform(r), field)) === 1 : (freq.get(dotNotation(transform(r), field)) ?? 0) > 1);
+	}
+
+	for (const h of helpers.filter(h => h.startsWith('distinct'))) {
+		const field = /\((\w+)\)/.exec(h)![1];
+		const seen = new Set();
+		filtered = filtered.filter(r => { const v = dotNotation(transform(r), field); return seen.has(v) ? false : !!seen.add(v); });
+	}
+
+	return filtered;
+}
+
+/**
+ * Tests object against a logic string.
+ *
+ * **Property operators**
+ * ```
+ * 'alice'                    // case-insensitive
+ * 'Alice'                    // case-sensitive
+ * 'name = Alice'             // loose equality (==)
+ * 'name == Alice'            // loose equality
+ * 'name != Alice'            // loose inequality
+ * 'role += admin'            // field contains value
+ * 'status -= archived'       // field does not contain value
+ * 'age > 21'                 // greater than
+ * 'age >= 21'                // greater than or equal
+ * 'age < 21'                 // less than
+ * 'age <= 21'                // less than or equal
+ * 'name =~ ^Al'              // regex match (shorthand)
+ * 'name =~ /^al/i'           // regex match (with flags)
+ * 'email !~ /@test\.com$/i'  // regex not match
+ * 'status = active && role != admin'    // ANDs
+ * 'status = active || status = pending' // ORs
+ * ```
+ *
+ * @param target - The object to test
+ * @param condition - The condition string; see supported syntax above
+ * @returns Whether the object satisfies the condition
  */
 export function logicTest(target: object, condition: string): boolean {
 	const evalBoolean = (a: any, op: string, b: any): boolean => {
-		switch(op) {
-			case '=':
-			case '==': return a == b;
+		switch (op) {
+			case '=': case '==': return a == b;
 			case '!=': return a != b;
 			case '+=': return a?.toString().includes(b);
 			case '-=': return !a?.toString().includes(b);
@@ -46,26 +124,23 @@ export function logicTest(target: object, condition: string): boolean {
 			case '>=': return a >= b;
 			case '<': return a < b;
 			case '<=': return a <= b;
+			case '~=': try { return !!toRegex(b)?.test(a?.toString() ?? ''); } catch { return false; }
+			case '!~': try { return !toRegex(b)?.test(a?.toString() ?? ''); } catch { return false; }
 			default: return false;
 		}
-	}
+	};
 
-	const or = condition.split('||').map(p => p.trim()).filter(p => !!p);
-	return -1 != or.findIndex(p => {
-		// Make sure all ANDs pass
-		const and = p.split('&&').map(p => p.trim()).filter(p => !!p);
-		return and.filter(p => {
-			// Boolean operator
-			const prop = /(\S+)\s*(==?|!=|\+=|-=|>=|>|<=|<)\s*(\S+)/g.exec(p);
-			if(prop) {
-				const key = Object.keys(target).find(k => k.toLowerCase() == prop[1].toLowerCase());
-				return evalBoolean(dotNotation<any>(target, key || prop[1]),  prop[2], JSONAttemptParse(prop[3]));
-			}
-			// Case-sensitive
-			const v = Object.values(target).map(JSONSerialize).join('');
-			if(/[A-Z]/g.test(condition)) return v.includes(p);
-			// Case-insensitive
-			return v.toLowerCase().includes(p);
-		}).length == and.length;
-	});
+	const resolve = (key: string) => dotNotation<any>(target, Object.keys(target).find(k => k.toLowerCase() === key.toLowerCase()) ?? key);
+
+	const evalExpr = (expr: string): boolean => {
+		const e = expr.trim();
+		const prop = /^(\S+)\s*(==?|!=|~=|!~|\+=|-=|>=|>|<=|<)\s*(.+)$/.exec(e);
+		if (prop) return evalBoolean(resolve(prop[1]), prop[2], JSONAttemptParse(prop[3].trim()));
+		const v = Object.values(target).map(JSONSerialize).join('');
+		return /[A-Z]/.test(e) ? v.includes(e) : v.toLowerCase().includes(e.toLowerCase());
+	};
+
+	return condition.split('||').map(p => p.trim()).filter(Boolean).some(group =>
+		group.split('&&').map(p => p.trim()).filter(Boolean).every(evalExpr)
+	);
 }

tests/search.spec.ts

@@ -17,55 +17,130 @@ describe('Search Utilities', () => {
 			expect(search(rows, '')).toEqual(rows);
 		});
 
-		it('filters based on a simple property string', () => {
-			expect(search(rows, 'Alice')).toEqual([rows[0]]);
-		});
-
-		it('filters using regex when regex=true', () => {
-			expect(search(rows, '^B', true)).toEqual([rows[1]]);
-		});
-
-		it('applies the transform function before filtering', () => {
-			const transform = (r: any) => ({...r, name: r.name.toLowerCase()});
-			expect(search(rows, 'alice', false, transform)).toEqual([rows[0]]);
-		});
-
-		it('uses logicTest for non-regex search', () => {
-			expect(search(rows, 'age == 30')).toEqual([rows[0], rows[2]]);
-			expect(search(rows, 'id = 2')).toEqual([rows[1]]);
-		});
-
-		it('returns all if search is falsy and regex enabled', () => {
-			expect(search(rows, '', true)).toEqual(rows);
-		});
-
-		it('handles regex search with special characters', () => {
-			expect(search(rows, '^[AC]', true)).toEqual([rows[0], rows[2]]);
-		});
-
-		it('ignores case when regex is applied', () => {
-			expect(search(rows, 'ALICE', true)).toEqual([]);
-		});
-
-		it('performs partial matches for properties when regex=false', () => {
-			expect(search(rows, 'Da')).toEqual([rows[3]]);
-		});
-
 		it('handles empty array input gracefully', () => {
 			expect(search([], 'test')).toEqual([]);
 		});
 
-		it('handles numeric values with comparison logic in strings', () => {
-			expect(search(rows, 'age < 31')).toEqual([rows[0], rows[1], rows[2]]);
+		it('applies transform before filtering', () => {
+			const transform = (r: any) => ({...r, name: r.name.toLowerCase()});
+			expect(search(rows, 'alice', transform)).toEqual([rows[0]]);
 		});
 
-		// New test cases for `+` and `-` operators
-		it('filters rows using the + operator', () => {
-			expect(search(rows, 'name += Al')).toEqual([rows[0]]);
+		describe('plain text', () => {
+			it('matches case-insensitively when lowercase', () => {
+				expect(search(rows, 'alice')).toEqual([rows[0]]);
+			});
+
+			it('matches case-sensitively when uppercase present', () => {
+				expect(search(rows, 'Alice')).toEqual([rows[0]]);
+				expect(search(rows, 'ALICE')).toEqual([]);
+			});
+
+			it('performs partial matches', () => {
+				expect(search(rows, 'Da')).toEqual([rows[3]]);
+			});
 		});
 
-		it('filters rows using the - operator', () => {
-			expect(search(rows, 'name -= Al')).toEqual([rows[1], rows[2], rows[3]]);
+		describe('global regex', () => {
+			it('matches with valid /pattern/flags syntax', () => {
+				expect(search(rows, '/^B/g')).toEqual([rows[1]]);
+			});
+
+			it('matches multiple rows', () => {
+				expect(search(rows, '/^[AC]/g')).toEqual([rows[0], rows[2]]);
+			});
+
+			it('respects flags', () => {
+				expect(search(rows, '/alice/i')).toEqual([rows[0]]);
+				expect(search(rows, '/alice/g')).toEqual([]);
+			});
+
+			it('does not treat /pattern/ without flags as regex', () => {
+				expect(search(rows, '/Alice/')).toEqual([]);
+			});
+
+			it('does not treat paths as regex', () => {
+				const pathRows = [{url: 'users/alice'}];
+				expect(search(pathRows, 'users/alice')).toEqual(pathRows);
+			});
+		});
+
+		describe('property operators', () => {
+			it('filters with equality', () => {
+				expect(search(rows, 'age == 30')).toEqual([rows[0], rows[2]]);
+				expect(search(rows, 'id = 2')).toEqual([rows[1]]);
+			});
+
+			it('filters with inequality', () => {
+				expect(search(rows, 'name != Alice')).toEqual([rows[1], rows[2], rows[3]]);
+			});
+
+			it('filters with contains', () => {
+				expect(search(rows, 'name += Al')).toEqual([rows[0]]);
+			});
+
+			it('filters with not-contains', () => {
+				expect(search(rows, 'name -= Al')).toEqual([rows[1], rows[2], rows[3]]);
+			});
+
+			it('filters with numeric comparisons', () => {
+				expect(search(rows, 'age < 31')).toEqual([rows[0], rows[1], rows[2]]);
+				expect(search(rows, 'age > 30')).toEqual([rows[3]]);
+				expect(search(rows, 'age >= 30')).toEqual([rows[0], rows[2], rows[3]]);
+			});
+		});
+
+		describe('property regex', () => {
+			it('matches with ~= shorthand', () => {
+				expect(search(rows, 'name ~= ^Al')).toEqual([rows[0]]);
+			});
+
+			it('matches with ~= /pattern/flags', () => {
+				expect(search(rows, 'name ~= /^al/i')).toEqual([rows[0]]);
+			});
+
+			it('excludes with !~', () => {
+				expect(search(rows, 'name !~ ^[AB]')).toEqual([rows[2], rows[3]]);
+			});
+		});
+
+		describe('logical operators', () => {
+			it('supports &&', () => {
+				expect(search(rows, 'age == 30 && name != Alice')).toEqual([rows[2]]);
+			});
+
+			it('supports ||', () => {
+				expect(search(rows, 'name = Alice || name = Bob')).toEqual([rows[0], rows[1]]);
+			});
+		});
+
+		describe('dataset helpers', () => {
+			const dupeRows = [
+				{id: 1, email: 'a@a.com', type: 'admin'},
+				{id: 2, email: 'b@b.com', type: 'user'},
+				{id: 3, email: 'a@a.com', type: 'user'},
+				{id: 4, email: 'c@c.com', type: 'admin'},
+			];
+
+			it('unique() returns rows where field appears once', () => {
+				expect(search(dupeRows, 'unique(email)')).toEqual([dupeRows[1], dupeRows[3]]);
+			});
+
+			it('duplicate() returns rows where field appears more than once', () => {
+				expect(search(dupeRows, 'duplicate(email)')).toEqual([dupeRows[0], dupeRows[2]]);
+			});
+
+			it('distinct() returns one row per field value', () => {
+				expect(search(dupeRows, 'distinct(type)')).toEqual([dupeRows[0], dupeRows[1]]);
+			});
+
+			it('composes helpers with predicates', () => {
+				expect(search(dupeRows, 'type = user && duplicate(email)')).toEqual([]);
+			});
+
+			it('applies distinct last', () => {
+				expect(search(dupeRows, 'duplicate(email) && distinct(type)')).toEqual([dupeRows[0], dupeRows[2]]);
+			});
 		});
 	});
 
@@ -83,60 +158,63 @@ describe('Search Utilities', () => {
 			expect(logicTest(obj, 'x < 5')).toBe(false);
 		});
 
-		it('supports case insensitive property search', () => {
-			expect(logicTest(obj, 'alpha')).toBeTruthy();
-			expect(logicTest(obj, 'ALPHA')).toBeFalsy();
+		it('handles contains and not-contains', () => {
+			expect(logicTest(obj, 'name += Alpha')).toBe(true);
+			expect(logicTest(obj, 'name += Alp')).toBe(true);
+			expect(logicTest(obj, 'name += Bet')).toBe(false);
+			expect(logicTest(obj, 'name -= Alpha')).toBe(false);
+			expect(logicTest(obj, 'name -= Bet')).toBe(true);
+			expect(logicTest(obj, 'name += lph')).toBe(true);
+			expect(logicTest(obj, 'name -= lph')).toBe(false);
 		});
 
-		it('handles logical AND/OR expressions', () => {
+		it('handles property regex ~=', () => {
+			expect(logicTest(obj, 'name ~= ^Alp')).toBe(true);
+			expect(logicTest(obj, 'name ~= /^alp/i')).toBe(true);
+			expect(logicTest(obj, 'name ~= ^Bet')).toBe(false);
+		});
+
+		it('handles property regex !~', () => {
+			expect(logicTest(obj, 'name !~ ^Bet')).toBe(true);
+			expect(logicTest(obj, 'name !~ ^Alp')).toBe(false);
+		});
+
+		it('handles invalid regex gracefully', () => {
+			expect(logicTest(obj, 'name ~= [invalid')).toBe(false);
+		});
+
+		it('supports plain text case-insensitive search', () => {
+			expect(logicTest(obj, 'alpha')).toBe(true);
+		});
+
+		it('supports plain text case-sensitive search', () => {
+			expect(logicTest(obj, 'Alpha')).toBe(true);
+			expect(logicTest(obj, 'ALPHA')).toBe(false);
+		});
+
+		it('handles logical AND/OR', () => {
 			expect(logicTest(obj, 'x == 10 && y == 5')).toBe(true);
 			expect(logicTest(obj, 'x == 10 || y == 100')).toBe(true);
 			expect(logicTest(obj, 'x == 1 && y == 5')).toBe(false);
 		});
 
+		it('handles numeric ranges', () => {
+			expect(logicTest(obj, 'x > 5 && x < 15')).toBe(true);
+			expect(logicTest(obj, 'x > 15')).toBe(false);
+		});
+
+		it('matches keys case-insensitively', () => {
+			const mixedCaseObj = {TestKey: 123};
+			expect(logicTest(mixedCaseObj, 'TestKey == 123')).toBe(true);
+			expect(logicTest(mixedCaseObj, 'testkey == 123')).toBe(true);
+		});
+
 		it('returns false for unsupported operators', () => {
 			expect(logicTest(obj, 'x === 10')).toBe(false);
 		});
 
-		it('handles invalid condition strings gracefully', () => {
-			expect(logicTest(obj, 'invalid condition')).toBe(false);
-		});
-
-		it('supports numeric operations with ranges', () => {
-			expect(logicTest(obj, 'x > 5 && x < 15')).toBe(true);
-			expect(logicTest(obj, 'x > 15')).toBe(false);
-		});
-
-		it('handles mixed case keys gracefully', () => {
-			const mixedCaseObj = {TestKey: 123};
-			expect(logicTest(mixedCaseObj, 'TestKey == 123')).toBe(true);
-			expect(logicTest(mixedCaseObj, 'testkey == 123')).toBe(true);
-		});
-
-		it('returns false if condition operators are missing', () => {
+		it('returns false for missing operators', () => {
 			expect(logicTest(obj, 'x 10')).toBe(false);
 		});
-
-		// New test cases for `+` and `-` operators
-		it('handles the + operator for inclusion', () => {
-			expect(logicTest(obj, 'name += Alpha')).toBe(true);
-			expect(logicTest(obj, 'name += Alp')).toBe(true);
-			expect(logicTest(obj, 'name += Bet')).toBe(false);
-		});
-
-		it('handles the - operator for exclusion', () => {
-			expect(logicTest(obj, 'name -= Alpha')).toBe(false);
-			expect(logicTest(obj, 'name -= Alp')).toBe(false);
-			expect(logicTest(obj, 'name -= Bet')).toBe(true);
-		});
-
-		it('includes partial matches correctly with +', () => {
-			expect(logicTest(obj, 'name += lph')).toBe(true);
-		});
-
-		it('excludes partial matches correctly with -', () => {
-			expect(logicTest(obj, 'name -= lph')).toBe(false);
-			expect(logicTest(obj, 'name -= xyz')).toBe(true);
-		});
 	});
 });