@catbee/utils 1.0.5 → 2.0.0-next.0

package/request/index.cjs

@@ -0,0 +1,202 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+'use strict';
+
+var exception = require('@catbee/utils/exception');
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var getPaginationParams = /* @__PURE__ */ __name((req) => {
+  const query = req.query;
+  const { page, limit } = extractPaginationParams(query, 1, 20, 100);
+  const { sortBy, sortOrder } = extractSortParams(query, []);
+  const search = typeof query.search === "string" ? query.search : void 0;
+  return {
+    ...query,
+    page,
+    limit,
+    sortBy,
+    sortOrder,
+    search
+  };
+}, "getPaginationParams");
+function parseNumberParam(value, options = {}) {
+  const { throwOnError = false, errorMessage = "Invalid number parameter", defaultValue, required = false } = options;
+  if (value === void 0) {
+    if (required) {
+      const error = `Required number parameter is missing`;
+      if (throwOnError) throw new exception.BadRequestException(error);
+      return {
+        isValid: false,
+        value: null,
+        error
+      };
+    }
+    return {
+      isValid: defaultValue !== void 0,
+      value: defaultValue !== void 0 ? defaultValue : null,
+      error: defaultValue === void 0 ? "Missing parameter with no default" : void 0
+    };
+  }
+  const num = Number(value);
+  if (isNaN(num)) {
+    if (throwOnError) throw new exception.BadRequestException(errorMessage);
+    return {
+      isValid: false,
+      value: null,
+      error: errorMessage
+    };
+  }
+  return {
+    isValid: true,
+    value: num
+  };
+}
+__name(parseNumberParam, "parseNumberParam");
+function parseBooleanParam(value, options = {}) {
+  const { throwOnError = false, errorMessage = "Invalid boolean parameter", defaultValue, required = false } = options;
+  if (value === void 0) {
+    if (required) {
+      const error = `Required boolean parameter is missing`;
+      if (throwOnError) throw new exception.BadRequestException(error);
+      return {
+        isValid: false,
+        value: null,
+        error
+      };
+    }
+    return {
+      isValid: defaultValue !== void 0,
+      value: defaultValue !== void 0 ? defaultValue : null,
+      error: defaultValue === void 0 ? "Missing parameter with no default" : void 0
+    };
+  }
+  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 exception.BadRequestException(errorMessage);
+  return {
+    isValid: false,
+    value: null,
+    error: errorMessage
+  };
+}
+__name(parseBooleanParam, "parseBooleanParam");
+function extractPaginationParams(query, defaultPage = 1, defaultLimit = 20, maxLimitSize = 100) {
+  const pageParam = typeof query.page === "string" ? query.page : void 0;
+  const pageResult = parseNumberParam(pageParam, {
+    defaultValue: defaultPage
+  });
+  const limitParam = typeof query.limit === "string" ? query.limit : void 0;
+  const limitResult = parseNumberParam(limitParam, {
+    defaultValue: defaultLimit
+  });
+  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
+  };
+}
+__name(extractPaginationParams, "extractPaginationParams");
+function extractSortParams(query, allowedFields, defaultSort = {
+  sortBy: "createdAt",
+  sortOrder: "desc"
+}) {
+  let sortBy = defaultSort.sortBy;
+  let sortOrder = defaultSort.sortOrder;
+  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";
+  }
+  if (typeof query.sortOrder === "string") {
+    const order = query.sortOrder.toLowerCase();
+    if (order === "asc" || order === "desc") {
+      sortOrder = order;
+    }
+  }
+  if (allowedFields.length && !allowedFields.includes(sortBy)) {
+    sortBy = defaultSort.sortBy;
+  }
+  return {
+    sortBy,
+    sortOrder
+  };
+}
+__name(extractSortParams, "extractSortParams");
+function extractFilterParams(query, allowedFilters) {
+  const filters = {};
+  for (const field of allowedFilters) {
+    if (field in query) {
+      filters[field] = query[field];
+    }
+  }
+  return filters;
+}
+__name(extractFilterParams, "extractFilterParams");
+
+// src/types/api-response.ts
+var SortDirection = /* @__PURE__ */ (function(SortDirection2) {
+  SortDirection2["ASC"] = "asc";
+  SortDirection2["DESC"] = "desc";
+  return SortDirection2;
+})({});
+
+exports.SortDirection = SortDirection;
+exports.extractFilterParams = extractFilterParams;
+exports.extractPaginationParams = extractPaginationParams;
+exports.extractSortParams = extractSortParams;
+exports.getPaginationParams = getPaginationParams;
+exports.parseBooleanParam = parseBooleanParam;
+exports.parseNumberParam = parseNumberParam;

package/request/index.d.ts

@@ -0,0 +1,26 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+export * from './request.utils';
+export * from '../types/api-response';

package/request/index.mjs

@@ -0,0 +1,194 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { BadRequestException } from '@catbee/utils/exception';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var getPaginationParams = /* @__PURE__ */ __name((req) => {
+  const query = req.query;
+  const { page, limit } = extractPaginationParams(query, 1, 20, 100);
+  const { sortBy, sortOrder } = extractSortParams(query, []);
+  const search = typeof query.search === "string" ? query.search : void 0;
+  return {
+    ...query,
+    page,
+    limit,
+    sortBy,
+    sortOrder,
+    search
+  };
+}, "getPaginationParams");
+function parseNumberParam(value, options = {}) {
+  const { throwOnError = false, errorMessage = "Invalid number parameter", defaultValue, required = false } = options;
+  if (value === void 0) {
+    if (required) {
+      const error = `Required number parameter is missing`;
+      if (throwOnError) throw new BadRequestException(error);
+      return {
+        isValid: false,
+        value: null,
+        error
+      };
+    }
+    return {
+      isValid: defaultValue !== void 0,
+      value: defaultValue !== void 0 ? defaultValue : null,
+      error: defaultValue === void 0 ? "Missing parameter with no default" : void 0
+    };
+  }
+  const num = Number(value);
+  if (isNaN(num)) {
+    if (throwOnError) throw new BadRequestException(errorMessage);
+    return {
+      isValid: false,
+      value: null,
+      error: errorMessage
+    };
+  }
+  return {
+    isValid: true,
+    value: num
+  };
+}
+__name(parseNumberParam, "parseNumberParam");
+function parseBooleanParam(value, options = {}) {
+  const { throwOnError = false, errorMessage = "Invalid boolean parameter", defaultValue, required = false } = options;
+  if (value === void 0) {
+    if (required) {
+      const error = `Required boolean parameter is missing`;
+      if (throwOnError) throw new BadRequestException(error);
+      return {
+        isValid: false,
+        value: null,
+        error
+      };
+    }
+    return {
+      isValid: defaultValue !== void 0,
+      value: defaultValue !== void 0 ? defaultValue : null,
+      error: defaultValue === void 0 ? "Missing parameter with no default" : void 0
+    };
+  }
+  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 BadRequestException(errorMessage);
+  return {
+    isValid: false,
+    value: null,
+    error: errorMessage
+  };
+}
+__name(parseBooleanParam, "parseBooleanParam");
+function extractPaginationParams(query, defaultPage = 1, defaultLimit = 20, maxLimitSize = 100) {
+  const pageParam = typeof query.page === "string" ? query.page : void 0;
+  const pageResult = parseNumberParam(pageParam, {
+    defaultValue: defaultPage
+  });
+  const limitParam = typeof query.limit === "string" ? query.limit : void 0;
+  const limitResult = parseNumberParam(limitParam, {
+    defaultValue: defaultLimit
+  });
+  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
+  };
+}
+__name(extractPaginationParams, "extractPaginationParams");
+function extractSortParams(query, allowedFields, defaultSort = {
+  sortBy: "createdAt",
+  sortOrder: "desc"
+}) {
+  let sortBy = defaultSort.sortBy;
+  let sortOrder = defaultSort.sortOrder;
+  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";
+  }
+  if (typeof query.sortOrder === "string") {
+    const order = query.sortOrder.toLowerCase();
+    if (order === "asc" || order === "desc") {
+      sortOrder = order;
+    }
+  }
+  if (allowedFields.length && !allowedFields.includes(sortBy)) {
+    sortBy = defaultSort.sortBy;
+  }
+  return {
+    sortBy,
+    sortOrder
+  };
+}
+__name(extractSortParams, "extractSortParams");
+function extractFilterParams(query, allowedFilters) {
+  const filters = {};
+  for (const field of allowedFilters) {
+    if (field in query) {
+      filters[field] = query[field];
+    }
+  }
+  return filters;
+}
+__name(extractFilterParams, "extractFilterParams");
+
+// src/types/api-response.ts
+var SortDirection = /* @__PURE__ */ (function(SortDirection2) {
+  SortDirection2["ASC"] = "asc";
+  SortDirection2["DESC"] = "desc";
+  return SortDirection2;
+})({});
+
+export { SortDirection, extractFilterParams, extractPaginationParams, extractSortParams, getPaginationParams, parseBooleanParam, parseNumberParam };

package/request/request.utils.d.ts

@@ -0,0 +1,109 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { Request } from 'express';
+import type { WithPagination } from '@catbee/utils/response';
+/**
+ * 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;
+}
+/**
+ * Extracts pagination, sorting, and optional search params from a request.
+ *
+ * @param req - Express request
+ * @returns Object containing validated pagination, sorting, and additional query params
+ */
+export declare const getPaginationParams: <T = {}>(req: Request) => WithPagination<T>;
+/**
+ * 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 declare function parseNumberParam(value: string | undefined, options?: ValidationOptions): ValidationResult<number>;
+/**
+ * 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 declare function parseBooleanParam(value: string | undefined, options?: ValidationOptions): ValidationResult<boolean>;
+/**
+ * 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 declare function extractPaginationParams(query: Record<string, string | string[]>, defaultPage?: number, defaultLimit?: number, maxLimitSize?: number): {
+    page: number;
+    limit: number;
+};
+/**
+ * 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 declare function extractSortParams(query: Record<string, string | string[]>, allowedFields: string[], defaultSort?: {
+    sortBy: string;
+    sortOrder: 'asc' | 'desc';
+}): {
+    sortBy: string;
+    sortOrder: 'asc' | 'desc';
+};
+/**
+ * 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 declare function extractFilterParams(query: Record<string, string | string[]>, allowedFilters: string[]): Record<string, string | string[]>;