Flop Javascript helpers

[axekan]

I'm using Flop in my Phoenix API, and have a frontend in Svelte. I quickly found a need for some helper functions in Javascript that allow creating the query parameters needed by Flop more easily.

I started from the source code of map_to_filter_params/2 and ported it to TypeScript. I also wrote some tests that cover all my use cases, but there could definitely be more of them. This implementation gives me full vscode autocomplete and type safety for an object of an any custom type. See usage in examples and tests below.

I hope someone finds this useful, and figured if you wanted to distribute this as flop-js on npm in the future, you could use this as a starting point.

const validOperators = [
	'==', '!=', '=~', '<', '<=', '>', '>=', 'in', 'not_in', 'empty', 'not_empty',
	'contains', 'not_contains', 'like', 'not_like', 'ilike', 'not_ilike', 'like_and',
	'like_or', 'ilike_and', 'ilike_or'
] as const;

const sortingOrders = [
	'asc',
	'asc_nulls_first',
	'asc_nulls_last',
	'desc',
	'desc_nulls_first',
	'desc_nulls_last'
] as const;

type ValidOperator = typeof validOperators[number];
type Filter<T> = { field: keyof T; op: ValidOperator; value: string | number | Array<string|number> };
export type FilterParams<T> = Parameters<typeof Flop.filter<T>>;
export type SortParams<T> = Parameters<typeof Flop.sort<T>>;

/**
 * This class provides methods for translating filter objects into
 * query strings accepted by Flop on the server.
 */
export class Flop {
	/**
	 * Converts a map of filter conditions into a list of Flop filter params.
	 *
	 * The default operator is ==. null values are excluded from the result.
	 * @param map
	 * @param opts
	 * @returns a query string that can be used with Flop.
	 * @see ported to TypeScript from Elixir https://github.com/woylie/flop/blob/0.24.1/lib/flop.ex#L2435
	 * @see original docs https://hexdocs.pm/flop/Flop.html#map_to_filter_params/2
	 * @example
	 * const query = Flop.filter({
	 *   name: "George", age: 8
	 * });
	 * console.log(query); // filters[0][field]=name&filters[0][op]==&filters[0][value]=George&filters[1][field]=age&filters[1][op]==&filters[1][value]=8
	 *
	 * // The default operator for all fields is ==
	 * // You can specify different operators for each field
	 * const query = Flop.filter(
	 *   { name: "George", age: 8 },
	 *   { operators: { name: 'ilike', age: '>' }
	 * );
	 * console.log(query); // filters[0][field]=name&filters[0][op]=ilike&filters[0][value]=George&filters[1][field]=age&filters[1][op]=>&filters[1][value]=8
	 */
	static filter<T>(
		map: Partial<T>,
		opts: {
			operators?: Partial<Record<keyof T, ValidOperator>>;
			rename?: Partial<Record<keyof T, string>>;
		} = {}
	): string {
		const {
			operators = {} as Record<keyof T, ValidOperator>,
			rename = {} as Record<keyof T, string>
		} = opts;

		const filters = Object.entries(map)
			.filter(([_, value]) => value !== null && value !== undefined)
			.map(([field, value]) => {
				const fieldName = rename[field as keyof T] || field;
				const fieldStr = String(fieldName);
				const op = opFromMapping(fieldStr, operators[field as keyof T]);

				return {
					field: field as keyof T,
					op,
					value,
				};
			});

		return filtersToURLParams(filters);
	};

	static sort<T>(
		orderBy: Array<keyof T>,
		orderDirections: Array<typeof sortingOrders[number]> = []
	): string {
		const sortingParams = orderBy.map((field, index) => {
			const direction = orderDirections[index] || 'asc';
			return `order_by[]=${String(field)}&order_directions[]=${String(direction)}`;
		});

		return sortingParams.length ? sortingParams.join('&') : '';
	};

	static limit(limit: number, offset = 0): string {
		return `limit=${limit}&offset=${offset}`;
	};

	static page(page: number, pageSize: number): string {
		return `page=${page}&page_size=${pageSize}`;
	};
}

function opFromMapping(field: string, operator?: ValidOperator): ValidOperator {
	if (!operator || !validOperators.includes(operator)) {
		return '==';
	}

	return operator;
}

function filtersToURLParams<T>(filters: Array<Filter<T>>): string {
	return filters
	  .map(
			(filter, index) => {
				const base = `filters[${index}][field]=${filter.field as string}&filters[${index}][op]=${filter.op}`;
				if (Array.isArray(filter.value)) {
					return `${base}${filter.value.map((value) => `&filters[${index}][value][]=${value}`).join('')}`;
				}
				return `${base}&filters[${index}][value]=${filter.value}`;
			}
	  )
	  .join('&');
}

Tests:

import { describe, expect, it } from 'vitest';
import { Flop } from './flop';

describe('Flop', () => {
	describe('filter', () => {
		it('should return an empty string when no filters are provided', () => {
			const filters = {};
			const result = Flop.filter(filters);
			expect(result).toBe('');
		});

		it('should build the filter query string correctly', () => {
			const result = Flop.filter({
				field1: 'value1',
				field2: 10,
				field3: null,
			}, {
				operators: {
					field2: '>'
				},
			});
			expect(result).toBe(
				'filters[0][field]=field1&filters[0][op]===&filters[0][value]=value1' +
                '&filters[1][field]=field2&filters[1][op]=>&filters[1][value]=10'
			);
		});

		it('should ignore null and undefined values', () => {
			const result = Flop.filter({
				field1: 'value1',
				field2: null,
				field3: undefined,
			});
			expect(result).toBe(
				'filters[0][field]=field1&filters[0][op]===&filters[0][value]=value1'
			);
		});

		it('should support ilike operator', () => {
			const result = Flop.filter({
				field1: 'value1'
			}, {
				operators: {
					field1: 'ilike'
				}
			});
			expect(result).toBe(
				'filters[0][field]=field1&filters[0][op]=ilike&filters[0][value]=value1'
			);
		});

		it('should encode uri correctly', () => {
			const result = Flop.filter({
				field1: 'ööö äää aaa'
			}, {
				operators: {
					field1: 'ilike'
				}
			});
			expect(result).toBe(
				'filters[0][field]=field1&filters[0][op]=ilike&filters[0][value]=ööö äää aaa'
			);
		});

		it('should support array values', () => {
			const result = Flop.filter({
				field1: ['value1', 'value2'],
			}, { operators: { field1: 'in' } });

			expect(result).toBe(
				'filters[0][field]=field1&filters[0][op]=in&filters[0][value][]=value1&filters[0][value][]=value2'
			);
		});

		it('should support non-ascii array values', () => {
			const result = Flop.filter({
				field1: ['Håkan', 'bråkan'],
			}, { operators: { field1: 'in' } });

			expect(result).toBe(
				'filters[0][field]=field1&filters[0][op]=in&filters[0][value][]=Håkan&filters[0][value][]=bråkan'
			);
		});
	});

	describe('sort', () => {
		it('should return an empty string when no sorting is provided', () => {
			const result = Flop.sort([]);
			expect(result).toBe('');
		});

		it('should build the sort query string correctly', () => {
			const result = Flop.sort(['field1', 'field2'], ['asc', 'desc']);
			expect(result).toBe(
				'order_by[]=field1&order_directions[]=asc&order_by[]=field2&order_directions[]=desc'
			);
		});

		it('should default to asc if no direction is provided', () => {
			const result = Flop.sort(['field1']);
			expect(result).toBe(
				'order_by[]=field1&order_directions[]=asc'
			);
		});

		it('should default to asc when only one direction is provided', () => {
			const result = Flop.sort(['field1', 'field2'], ['asc']);
			expect(result).toBe(
				'order_by[]=field1&order_directions[]=asc&order_by[]=field2&order_directions[]=asc'
			);
		});
	});

	describe('limit', () => {
		it('should return the limit query string correctly', () => {
			const result = Flop.limit(10, 20);
			expect(result).toBe('limit=10&offset=20');
		});

		it('should default to offset 0', () => {
			const result = Flop.limit(10);
			expect(result).toBe('limit=10&offset=0');
		});

		it('should handle negative offset', () => {
			const result = Flop.limit(10, -20);
			expect(result).toBe('limit=10&offset=-20');
		});
	});

	describe('page', () => {
		it('should return the page query string correctly', () => {
			const result = Flop.page(10, 20);
			expect(result).toBe('page=10&page_size=20');
		});
	});
});

[woylie]

This is very helpful, thank you for sharing!