@bagelink/vue 1.7.80 → 1.7.86

package/src/utils/queryFilter.ts

@@ -0,0 +1,366 @@
+/**
+ * SCIM 2.0 Query Builder
+ *
+ * Type-safe query builder for SCIM 2.0 filtering.
+ *
+ * @example
+ * ```typescript
+ * // Array-based (recommended for UI)
+ * const filters: QueryConditions<Person> = [
+ *   { field: 'first_name', op: 'eq', value: 'John' },
+ *   { field: 'age', op: 'gt', value: 18, connector: 'and' },
+ * ]
+ * buildQuery(filters) // → 'first_name eq "John" and age gt 18'
+ *
+ * // Range query (same field twice)
+ * const rangeFilters: QueryConditions<Donation> = [
+ *   { field: 'amount', op: 'ge', value: 100 },
+ *   { field: 'amount', op: 'le', value: 500, connector: 'and' },
+ * ]
+ * buildQuery(rangeFilters) // → 'amount ge 100 and amount le 500'
+ * ```
+ */
+
+type Primitive = string | number | boolean | null
+
+type DeepKeyOf<T> = T extends Primitive
+	? never
+	: {
+		[K in keyof T & string]: K | `${K}.${DeepKeyOf<T[K]>}`;
+	}[keyof T & string]
+
+/**
+ * SCIM 2.0 comparison operators
+ */
+export type ComparisonOperator =
+	| 'eq' // equal
+	| 'ne' // not equal
+	| 'gt' // greater than
+	| 'ge' // greater than or equal
+	| 'lt' // less than
+	| 'le' // less than or equal
+	| 'co' // contains
+	| 'sw' // starts with
+	| 'ew' // ends with
+	| 'pr' // present (has value)
+
+/**
+ * SCIM 2.0 logical operators
+ */
+export type LogicalOperator = 'and' | 'or'
+
+/**
+ * A single filter condition
+ */
+export interface FilterCondition<T extends Record<string, any> = Record<string, any>> {
+	field: DeepKeyOf<T> | string
+	op: ComparisonOperator
+	value?: Primitive // optional for 'pr' operator
+	connector?: LogicalOperator // before this condition, ignored for first
+}
+
+/**
+ * Array of filter conditions - the primary way to define queries
+ */
+export type QueryConditions<T extends Record<string, any> = Record<string, any>> = FilterCondition<T>[]
+
+/**
+ * Format a value for SCIM 2.0 query
+ */
+function formatValue(value: Primitive): string {
+	if (value === null) return 'null'
+	if (typeof value === 'string') {
+		const escaped = value.replace(/"/g, '\\"')
+		return `"${escaped}"`
+	}
+	if (typeof value === 'boolean') return value.toString()
+	return String(value)
+}
+
+/**
+ * Build a SCIM 2.0 query string from conditions array
+ *
+ * @example
+ * ```typescript
+ * buildQuery<Person>([
+ *   { field: 'name', op: 'eq', value: 'John' },
+ *   { field: 'age', op: 'gt', value: 18, connector: 'and' },
+ * ])
+ * // → 'name eq "John" and age gt 18'
+ * ```
+ */
+export function buildQuery<T extends Record<string, any>>(
+	conditions: QueryConditions<T>
+): string {
+	if (!conditions || conditions.length === 0) return ''
+
+	const parts: string[] = []
+
+	for (let i = 0; i < conditions.length; i++) {
+		const { field, op, value, connector } = conditions[i]
+
+		// Add connector (except for first condition)
+		if (i > 0 && connector) {
+			parts.push(connector)
+		}
+
+		// Build the condition
+		if (op === 'pr') {
+			parts.push(`${field} pr`)
+		} else {
+			parts.push(`${field} ${op} ${formatValue(value ?? null)}`)
+		}
+	}
+
+	return parts.join(' ')
+}
+
+/**
+ * Query Builder for SCIM 2.0 filtering
+ */
+export class QueryFilter<T extends Record<string, any>> {
+	private parts: string[] = []
+
+	/**
+	 * Equal comparison
+	 */
+	eq<K extends DeepKeyOf<T>>(field: K, value: Primitive): this {
+		this.parts.push(`${field as string} eq ${this.formatValue(value)}`)
+		return this
+	}
+
+	/**
+	 * Not equal comparison
+	 */
+	ne<K extends DeepKeyOf<T>>(field: K, value: Primitive): this {
+		this.parts.push(`${field as string} ne ${this.formatValue(value)}`)
+		return this
+	}
+
+	/**
+	 * Greater than comparison
+	 */
+	gt<K extends DeepKeyOf<T>>(field: K, value: number | string): this {
+		this.parts.push(`${field as string} gt ${this.formatValue(value)}`)
+		return this
+	}
+
+	/**
+	 * Greater than or equal comparison
+	 */
+	ge<K extends DeepKeyOf<T>>(field: K, value: number | string): this {
+		this.parts.push(`${field as string} ge ${this.formatValue(value)}`)
+		return this
+	}
+
+	/**
+	 * Less than comparison
+	 */
+	lt<K extends DeepKeyOf<T>>(field: K, value: number | string): this {
+		this.parts.push(`${field as string} lt ${this.formatValue(value)}`)
+		return this
+	}
+
+	/**
+	 * Less than or equal comparison
+	 */
+	le<K extends DeepKeyOf<T>>(field: K, value: number | string): this {
+		this.parts.push(`${field as string} le ${this.formatValue(value)}`)
+		return this
+	}
+
+	/**
+	 * Contains comparison (for strings)
+	 */
+	co<K extends DeepKeyOf<T>>(field: K, value: string): this {
+		this.parts.push(`${field as string} co ${this.formatValue(value)}`)
+		return this
+	}
+
+	/**
+	 * Starts with comparison (for strings)
+	 */
+	sw<K extends DeepKeyOf<T>>(field: K, value: string): this {
+		this.parts.push(`${field as string} sw ${this.formatValue(value)}`)
+		return this
+	}
+
+	/**
+	 * Ends with comparison (for strings)
+	 */
+	ew<K extends DeepKeyOf<T>>(field: K, value: string): this {
+		this.parts.push(`${field as string} ew ${this.formatValue(value)}`)
+		return this
+	}
+
+	/**
+	 * Present check (field has a value)
+	 */
+	pr<K extends DeepKeyOf<T>>(field: K): this {
+		this.parts.push(`${field as string} pr`)
+		return this
+	}
+
+	/**
+	 * AND logical operator
+	 */
+	and(): this {
+		this.parts.push('and')
+		return this
+	}
+
+	/**
+	 * OR logical operator
+	 */
+	or(): this {
+		this.parts.push('or')
+		return this
+	}
+
+	/**
+	 * NOT logical operator
+	 */
+	not(): this {
+		this.parts.push('not')
+		return this
+	}
+
+	/**
+	 * Group expressions with parentheses
+	 */
+	group(builderFn: (qb: QueryFilter<T>) => QueryFilter<T>): this {
+		const groupBuilder = new QueryFilter<T>()
+		builderFn(groupBuilder)
+		const groupQuery = groupBuilder.build()
+		if (groupQuery) {
+			this.parts.push(`(${groupQuery})`)
+		}
+		return this
+	}
+
+	/**
+	 * Add raw query string (use with caution)
+	 */
+	raw(query: string): this {
+		this.parts.push(query)
+		return this
+	}
+
+	/**
+	 * Clear the query
+	 */
+	clear(): this {
+		this.parts = []
+		return this
+	}
+
+	/**
+	 * Build the final query string
+	 */
+	build(): string {
+		return this.parts.join(' ')
+	}
+
+	/**
+	 * Convert to string automatically (allows using builder without .build())
+	 */
+	toString(): string {
+		return this.build()
+	}
+
+	/**
+	 * Allow implicit string conversion
+	 */
+	[Symbol.toPrimitive](hint: string): string | number {
+		if (hint === 'string') {
+			return this.build()
+		}
+		return this.parts.length
+	}
+
+	/**
+	 * Format value for SCIM 2.0 query
+	 */
+	private formatValue(value: Primitive): string {
+		if (value === null) {
+			return 'null'
+		}
+		if (typeof value === 'string') {
+			// Escape quotes in strings
+			const escaped = value.replace(/"/g, '\\"')
+			return `"${escaped}"`
+		}
+		if (typeof value === 'boolean') {
+			return value.toString()
+		}
+		return String(value)
+	}
+}
+
+/**
+ * Build a query string from conditions
+ *
+ * @example
+ * ```typescript
+ * // From conditions array
+ * query<Person>([
+ *   { field: 'first_name', op: 'eq', value: 'John' },
+ *   { field: 'age', op: 'gt', value: 18, connector: 'and' },
+ * ])
+ * // → 'first_name eq "John" and age gt 18'
+ *
+ * // Empty returns empty string
+ * query([]) // → ''
+ * ```
+ */
+export function query<T extends Record<string, any>>(
+	conditions: QueryConditions<T>
+): string {
+	return buildQuery(conditions)
+}
+
+/**
+ * Create a query that checks if any of the fields match the value
+ */
+export function anyOf<T extends Record<string, any>>(
+	fields: Array<DeepKeyOf<T> | string>,
+	value: Primitive
+): string {
+	const conditions: QueryConditions<T> = fields.map((field, i) => ({
+		field,
+		op: 'eq' as const,
+		value,
+		connector: i > 0 ? 'or' as const : undefined,
+	}))
+	return buildQuery(conditions)
+}
+
+/**
+ * Create a range query (field >= min and field <= max)
+ */
+export function range<T extends Record<string, any>>(
+	field: DeepKeyOf<T> | string,
+	min: number | string,
+	max: number | string
+): string {
+	return buildQuery<T>([
+		{ field, op: 'ge', value: min },
+		{ field, op: 'le', value: max, connector: 'and' },
+	])
+}
+
+/**
+ * Create a search query across multiple string fields (OR)
+ */
+export function search<T extends Record<string, any>>(
+	fields: Array<DeepKeyOf<T> | string>,
+	searchTerm: string
+): string {
+	const conditions: QueryConditions<T> = fields.map((field, i) => ({
+		field,
+		op: 'co' as const,
+		value: searchTerm,
+		connector: i > 0 ? 'or' as const : undefined,
+	}))
+	return buildQuery(conditions)
+}