feat: add request utils

Author: cyber-hari

src/utils/request.utils.ts

@@ -0,0 +1,206 @@
+/**
+ * Options for parsing and validating request parameters.
+ */
+export interface ValidationOptions {
+  /** Whether to throw an error on validation failure */
+  throwOnError?: boolean;
+
+  /** Custom error message for validation failures */
+  errorMessage?: string;
+
+  /** Default value to use if parameter is missing */
+  defaultValue?: any;
+
+  /** Whether the parameter is required */
+  required?: boolean;
+}
+
+/**
+ * Result of a parameter validation operation.
+ */
+export interface ValidationResult<T> {
+  /** Whether validation was successful */
+  isValid: boolean;
+
+  /** The validated and potentially transformed value */
+  value: T | null;
+
+  /** Error message if validation failed */
+  error?: string;
+}
+
+/**
+ * Safely parses a string parameter to a number.
+ *
+ * @param value - String value to parse
+ * @param options - Validation options
+ * @returns Validation result containing the parsed number or error
+ */
+export function parseNumberParam(value: string | undefined, options: ValidationOptions = {}): ValidationResult<number> {
+  const { throwOnError = false, errorMessage = 'Invalid number parameter', defaultValue, required = false } = options;
+
+  // Handle undefined case
+  if (value === undefined) {
+    if (required) {
+      const error = `Required number parameter is missing`;
+      if (throwOnError) throw new Error(error);
+      return { isValid: false, value: null, error };
+    }
+
+    return {
+      isValid: defaultValue !== undefined,
+      value: defaultValue !== undefined ? defaultValue : null,
+      error: defaultValue === undefined ? 'Missing parameter with no default' : undefined
+    };
+  }
+
+  // Parse and validate the number
+  const num = Number(value);
+  if (isNaN(num)) {
+    if (throwOnError) throw new Error(errorMessage);
+    return { isValid: false, value: null, error: errorMessage };
+  }
+
+  return { isValid: true, value: num };
+}
+
+/**
+ * Safely parses a string parameter to a boolean.
+ *
+ * @param value - String value to parse
+ * @param options - Validation options
+ * @returns Validation result containing the parsed boolean or error
+ */
+export function parseBooleanParam(
+  value: string | undefined,
+  options: ValidationOptions = {}
+): ValidationResult<boolean> {
+  const { throwOnError = false, errorMessage = 'Invalid boolean parameter', defaultValue, required = false } = options;
+
+  // Handle undefined case
+  if (value === undefined) {
+    if (required) {
+      const error = `Required boolean parameter is missing`;
+      if (throwOnError) throw new Error(error);
+      return { isValid: false, value: null, error };
+    }
+
+    return {
+      isValid: defaultValue !== undefined,
+      value: defaultValue !== undefined ? defaultValue : null,
+      error: defaultValue === undefined ? 'Missing parameter with no default' : undefined
+    };
+  }
+
+  // Parse the boolean value with various allowed formats
+  const lowercaseValue = value.toLowerCase();
+  if (['true', 't', 'yes', 'y', '1'].includes(lowercaseValue)) {
+    return { isValid: true, value: true };
+  }
+
+  if (['false', 'f', 'no', 'n', '0'].includes(lowercaseValue)) {
+    return { isValid: true, value: false };
+  }
+
+  if (throwOnError) throw new Error(errorMessage);
+  return { isValid: false, value: null, error: errorMessage };
+}
+
+/**
+ * Extracts pagination parameters from request query parameters.
+ *
+ * @param query - Query parameters object
+ * @param defaultPage - Default page number if not specified (defaults to 1)
+ * @param defaultLimit - Default per page size if not specified (defaults to 20)
+ * @param maxLimitSize - Maximum allowed per page size (defaults to 100)
+ * @returns Object containing validated page and limit
+ */
+export function extractPaginationParams(
+  query: Record<string, string | string[]>,
+  defaultPage: number = 1,
+  defaultLimit: number = 20,
+  maxLimitSize: number = 100
+): { page: number; limit: number } {
+  // Parse page parameter
+  const pageParam = typeof query.page === 'string' ? query.page : undefined;
+  const pageResult = parseNumberParam(pageParam, { defaultValue: defaultPage });
+
+  // Parse limit parameter
+  const limitParam = typeof query.limit === 'string' ? query.limit : undefined;
+  const limitResult = parseNumberParam(limitParam, { defaultValue: defaultLimit });
+
+  // Ensure valid values (handle 0 → fallback to default)
+  const page = pageResult.value && pageResult.value > 0 ? pageResult.value : defaultPage;
+
+  const limit = limitResult.value && limitResult.value > 0 ? Math.min(limitResult.value, maxLimitSize) : defaultLimit;
+
+  return { page, limit };
+}
+
+/**
+ * Extracts sorting parameters from request query parameters.
+ *
+ * @param query - Query parameters object
+ * @param allowedFields - Array of field names that are allowed to be sorted
+ * @param defaultSort - Default sort configuration if not specified
+ * @returns Object containing sort field and direction
+ */
+export function extractSortParams(
+  query: Record<string, string | string[]>,
+  allowedFields: string[],
+  defaultSort: { sortBy: string; sortOrder: 'asc' | 'desc' } = { sortBy: 'createdAt', sortOrder: 'desc' }
+): { sortBy: string; sortOrder: 'asc' | 'desc' } {
+  let sortBy = defaultSort.sortBy;
+  let sortOrder: 'asc' | 'desc' = defaultSort.sortOrder;
+
+  // Extract from `sortBy` or `sort`
+  if (typeof query.sortBy === 'string') {
+    sortBy = query.sortBy;
+  } else if (Array.isArray(query.sortBy)) {
+    sortBy = query.sortBy[0];
+  } else if (typeof query.sort === 'string') {
+    sortBy = query.sort.startsWith('-') ? query.sort.slice(1) : query.sort;
+    sortOrder = query.sort.startsWith('-') ? 'desc' : 'asc';
+  } else if (Array.isArray(query.sort)) {
+    sortBy = query.sort[0].startsWith('-') ? query.sort[0].slice(1) : query.sort[0];
+    sortOrder = query.sort[0].startsWith('-') ? 'desc' : 'asc';
+  }
+
+  // Explicit sortOrder (overrides inferred one if valid)
+  if (typeof query.sortOrder === 'string') {
+    const order = query.sortOrder.toLowerCase();
+    if (order === 'asc' || order === 'desc') {
+      sortOrder = order;
+    }
+  }
+
+  // Validate field
+  if (!allowedFields.includes(sortBy)) {
+    sortBy = defaultSort.sortBy;
+  }
+
+  return { sortBy, sortOrder };
+}
+
+/**
+ * Extracts filter parameters from query parameters based on allowed filter fields.
+ *
+ * @param query - Query parameters object
+ * @param allowedFilters - Array of field names that are allowed to be used as filters
+ * @returns Object containing the filters as key-value pairs
+ */
+export function extractFilterParams(
+  query: Record<string, string | string[]>,
+  allowedFilters: string[]
+): Record<string, string | string[]> {
+  const filters: Record<string, string | string[]> = {};
+
+  // Find filter parameters in the query
+  for (const field of allowedFilters) {
+    if (field in query) {
+      filters[field] = query[field];
+    }
+  }
+
+  return filters;
+}

tests/utils/request.utils.test.ts

@@ -0,0 +1,165 @@
+import {
+  parseNumberParam,
+  parseBooleanParam,
+  extractPaginationParams,
+  extractSortParams,
+  extractFilterParams
+} from '../../src/utils/request.utils';
+
+describe('parseNumberParam', () => {
+  it('parses valid number', () => {
+    expect(parseNumberParam('42')).toEqual({ isValid: true, value: 42 });
+  });
+
+  it('returns defaultValue if missing', () => {
+    expect(parseNumberParam(undefined, { defaultValue: 5 })).toEqual({
+      isValid: true,
+      value: 5
+    });
+  });
+
+  it('fails if required and missing', () => {
+    expect(parseNumberParam(undefined, { required: true })).toEqual({
+      isValid: false,
+      value: null,
+      error: 'Required number parameter is missing'
+    });
+  });
+
+  it('throws if required and throwOnError', () => {
+    expect(() => parseNumberParam(undefined, { required: true, throwOnError: true })).toThrow(
+      'Required number parameter is missing'
+    );
+  });
+
+  it('returns error for NaN', () => {
+    expect(parseNumberParam('abc')).toEqual({
+      isValid: false,
+      value: null,
+      error: 'Invalid number parameter'
+    });
+  });
+});
+
+describe('parseBooleanParam', () => {
+  it('parses true values', () => {
+    ['true', 't', 'yes', 'y', '1'].forEach(v => {
+      expect(parseBooleanParam(v)).toEqual({ isValid: true, value: true });
+    });
+  });
+
+  it('parses false values', () => {
+    ['false', 'f', 'no', 'n', '0'].forEach(v => {
+      expect(parseBooleanParam(v)).toEqual({ isValid: true, value: false });
+    });
+  });
+
+  it('returns defaultValue if missing', () => {
+    expect(parseBooleanParam(undefined, { defaultValue: false })).toEqual({
+      isValid: true,
+      value: false
+    });
+  });
+
+  it('fails if required and missing', () => {
+    expect(parseBooleanParam(undefined, { required: true })).toEqual({
+      isValid: false,
+      value: null,
+      error: 'Required boolean parameter is missing'
+    });
+  });
+
+  it('throws on invalid input when throwOnError', () => {
+    expect(() => parseBooleanParam('maybe', { throwOnError: true })).toThrow('Invalid boolean parameter');
+  });
+
+  it('returns error on invalid input', () => {
+    expect(parseBooleanParam('maybe')).toEqual({
+      isValid: false,
+      value: null,
+      error: 'Invalid boolean parameter'
+    });
+  });
+});
+
+describe('extractPaginationParams', () => {
+  it('uses defaults if no params', () => {
+    expect(extractPaginationParams({})).toEqual({ page: 1, limit: 20 });
+  });
+
+  it('parses valid page and limit', () => {
+    expect(extractPaginationParams({ page: '3', limit: '15' })).toEqual({
+      page: 3,
+      limit: 15
+    });
+  });
+
+  it('enforces min page and limit', () => {
+    expect(extractPaginationParams({ page: '0', limit: '0' })).toEqual({
+      page: 1,
+      limit: 20
+    });
+  });
+
+  it('caps limit at maxLimitSize', () => {
+    expect(extractPaginationParams({ limit: '999' }, 1, 20, 100)).toEqual({
+      page: 1,
+      limit: 100
+    });
+  });
+});
+
+describe('extractSortParams', () => {
+  const allowedFields = ['name', 'createdAt', 'updatedAt'];
+
+  it('uses defaults when no params', () => {
+    expect(extractSortParams({}, allowedFields)).toEqual({
+      sortBy: 'createdAt',
+      sortOrder: 'desc'
+    });
+  });
+
+  it('parses sortBy field', () => {
+    expect(extractSortParams({ sortBy: 'name' }, allowedFields)).toEqual({
+      sortBy: 'name',
+      sortOrder: 'desc'
+    });
+  });
+
+  it('parses sort with prefix "-"', () => {
+    expect(extractSortParams({ sort: '-updatedAt' }, allowedFields)).toEqual({
+      sortBy: 'updatedAt',
+      sortOrder: 'desc'
+    });
+  });
+
+  it('overrides with explicit sortOrder', () => {
+    expect(extractSortParams({ sort: '-name', sortOrder: 'asc' }, allowedFields)).toEqual({
+      sortBy: 'name',
+      sortOrder: 'asc'
+    });
+  });
+
+  it('falls back to default if field not allowed', () => {
+    expect(extractSortParams({ sortBy: 'invalid' }, allowedFields)).toEqual({
+      sortBy: 'createdAt',
+      sortOrder: 'desc'
+    });
+  });
+});
+
+describe('extractFilterParams', () => {
+  const allowedFilters = ['status', 'type'];
+
+  it('extracts allowed filters', () => {
+    expect(extractFilterParams({ status: 'active', foo: 'bar' }, allowedFilters)).toEqual({ status: 'active' });
+  });
+
+  it('returns empty object if no allowed filters', () => {
+    expect(extractFilterParams({ foo: 'bar' }, allowedFilters)).toEqual({});
+  });
+
+  it('handles array values in filters', () => {
+    expect(extractFilterParams({ type: ['a', 'b'] }, allowedFilters)).toEqual({ type: ['a', 'b'] });
+  });
+});