feat(db): enhance queryModifiers with comprehensive documentation and robust testing

Improved the queryModifiers utility with:
- Detailed JSDoc documentation for QueryModifier type, composeQueryModifiers, and createStandardQueryModifier
- Enhanced type safety and flexibility for query modification functions
- Comprehensive test suite using pg-mem for in-memory database simulation
- Added graceful handling of undefined modifier returns
- Verified modifier composition order and individual modifier behaviors

Author: bitbeckers

src/lib/db/queryModifiers/queryModifiers.ts

@@ -7,7 +7,24 @@ import { applySort } from "./applySort.js";
 import { applyWhere } from "./applyWhere.js";
 
 /**
- * Type definition for a query modifier function
+ * Type definition for a query modifier function.
+ * Query modifiers are functions that take a query and arguments and return a modified query.
+ * They are used to compose complex queries from simpler, reusable parts.
+ *
+ * @typeParam DB - The database type extending SupportedDatabases
+ * @typeParam T - The table name type (must be a key of DB and a string)
+ * @typeParam Args - The arguments type containing query modification parameters
+ *
+ * @param query - The Kysely SelectQueryBuilder instance to modify
+ * @param args - The arguments containing modification parameters
+ * @returns The modified SelectQueryBuilder instance
+ *
+ * @example
+ * ```typescript
+ * const sortModifier: QueryModifier<DB, "users", SortArgs> = (query, args) => {
+ *   return args.sortBy ? query.orderBy(args.sortBy) : query;
+ * };
+ * ```
  */
 export type QueryModifier<
   DB extends SupportedDatabases,
@@ -19,29 +36,78 @@ export type QueryModifier<
 ) => SelectQueryBuilder<DB, T, Selectable<DB[T]>>;
 
 /**
- * Composes multiple query modifiers into a single function
- * @param modifiers The query modifiers to compose
+ * Composes multiple query modifiers into a single function.
+ * The modifiers are applied in sequence, with each modifier receiving the query
+ * produced by the previous modifier.
+ *
+ * @typeParam DB - The database type extending SupportedDatabases
+ * @typeParam T - The table name type (must be a key of DB and a string)
+ * @typeParam Args - The arguments type containing query modification parameters
+ *
+ * @param modifiers - The query modifiers to compose, applied in order
  * @returns A function that applies all modifiers in sequence
+ *
+ * @remarks
+ * - Modifiers are applied left to right
+ * - Each modifier receives the query produced by the previous modifier
+ * - If a modifier returns undefined or null, the original query is used
+ * - The args object is passed unchanged to each modifier
+ *
+ * @example
+ * ```typescript
+ * const fullModifier = composeQueryModifiers(
+ *   applyWhere,
+ *   applySort,
+ *   applyPagination
+ * );
+ * const result = fullModifier(query, { where: {...}, sortBy: {...} });
+ * ```
  */
 export function composeQueryModifiers<
   DB extends SupportedDatabases,
   T extends keyof DB & string,
   Args,
 >(...modifiers: QueryModifier<DB, T, Args>[]) {
   return (query: SelectQueryBuilder<DB, T, Selectable<DB[T]>>, args: Args) =>
-    modifiers.reduce((q, modifier) => modifier(q, args), query);
+    modifiers.reduce((q, modifier) => {
+      const result = modifier(q, args);
+      return result ?? q; // Fall back to previous query if modifier returns null/undefined
+    }, query);
 }
 
 /**
- * Creates a composed query modifier that applies where, sort, and pagination
- * @param tableName The name of the table to query
- * @returns A function that applies where, sort, and pagination modifiers
+ * Creates a composed query modifier that applies where, sort, and pagination in a standard order.
+ * This is a convenience function that combines the most commonly used query modifiers.
+ *
+ * @typeParam DB - The database type extending SupportedDatabases
+ * @typeParam T - The table name type (must be a key of DB and a string)
+ * @typeParam Args - The arguments type extending BaseQueryArgsType
+ *
+ * @param tableName - The name of the table to query
+ * @returns A function that applies where, sort, and pagination modifiers in sequence
+ *
+ * @remarks
+ * - Modifiers are applied in this order: where → sort → pagination
+ * - Where conditions are applied first to filter the dataset
+ * - Sort is applied next to order the filtered results
+ * - Pagination is applied last to limit the final result set
+ * - Each modifier is optional and will be skipped if its args are not provided
+ *
+ * @example
+ * ```typescript
+ * const usersModifier = createStandardQueryModifier<DB, "users", UserQueryArgs>("users");
+ * const result = usersModifier(query, {
+ *   where: { active: true },
+ *   sortBy: { created_at: SortOrder.descending },
+ *   first: 10,
+ *   offset: 0
+ * });
+ * ```
  */
 export function createStandardQueryModifier<
   DB extends SupportedDatabases,
   T extends keyof DB & string,
   Args extends BaseQueryArgsType<
-    // TODO better type definition than object
     object,
     { [K in keyof DB[T]]?: SortOrder | null | undefined }
   >,