reslib 1.0.0

package/build/resources/ResourcePaginationHelper.d.ts

@@ -0,0 +1,537 @@
+import { Dictionary } from '../types';
+import { NestedPaths, ResourcePaginationMeta, ResourceQueryOptions, ResourceQueryOrderBy } from './types';
+export declare class ResourcePaginationHelper {
+    /**
+     * Normalizes pagination parameters into a consistent format, calculating missing values and ensuring valid pagination state.
+     *
+     * This method takes pagination options and normalizes them by calculating the missing pagination parameters
+     * (`page`, `skip`, `limit`) based on the provided values. It handles the relationship between page-based
+     * and offset-based pagination, ensuring that all three parameters are consistent and valid.
+     *
+     * **Normalization Logic:**
+     * - If `limit` is not a valid number, returns an empty object (no pagination)
+     * - If `skip` is provided, calculates the corresponding `page` number
+     * - If `page` is provided, calculates the corresponding `skip` offset
+     * - If neither `skip` nor `page` are provided, defaults to page 1 with skip 0
+     * - Ensures all returned values are valid numbers
+     *
+     * **Parameter Relationships:**
+     * - `page`: 1-based page number (first page = 1)
+     * - `skip`: 0-based offset (number of records to skip)
+     * - `limit`: Maximum records per page
+     * - Formula: `skip = (page - 1) * limit`
+     *
+     * @template DataType - The resource data type (used for type consistency with ResourceQueryOptions)
+     * @param {ResourceQueryOptions<DataType>} [options] - Pagination options containing page, skip, and/or limit
+     * @param {number} [options.page] - The page number (1-based)
+     * @param {number} [options.skip] - The number of records to skip (0-based offset)
+     * @param {number} [options.limit] - The maximum number of records per page
+     * @returns {{page?: number, skip?: number, limit?: number}} Normalized pagination parameters:
+     *   - `page`: Calculated or provided page number
+     *   - `skip`: Calculated or provided skip offset
+     *   - `limit`: The limit value (unchanged if valid, omitted if invalid)
+     *
+     * @example
+     * ```typescript
+     * // Page-based pagination - calculates skip automatically
+     * const result = ResourcePaginationHelper.normalizePagination({
+     *   page: 3,
+     *   limit: 10
+     * });
+     * // Result: { page: 3, skip: 20, limit: 10 }
+     * // (skip = (3-1) * 10 = 20)
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Offset-based pagination - calculates page automatically
+     * const result = ResourcePaginationHelper.normalizePagination({
+     *   skip: 50,
+     *   limit: 25
+     * });
+     * // Result: { page: 3, skip: 50, limit: 25 }
+     * // (page = floor(50/25) + 1 = 3)
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Default pagination - no parameters provided
+     * const result = ResourcePaginationHelper.normalizePagination({
+     *   limit: 20
+     * });
+     * // Result: { page: 1, skip: 0, limit: 20 }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Invalid limit - returns empty object (no pagination)
+     * const result = ResourcePaginationHelper.normalizePagination({
+     *   page: 2,
+     *   limit: "invalid"
+     * });
+     * // Result: {}
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Zero or negative values - defaults to first page
+     * const result = ResourcePaginationHelper.normalizePagination({
+     *   page: 0,
+     *   limit: 15
+     * });
+     * // Result: { page: 1, skip: 0, limit: 15 }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Large skip values
+     * const result = ResourcePaginationHelper.normalizePagination({
+     *   skip: 1000,
+     *   limit: 50
+     * });
+     * // Result: { page: 21, skip: 1000, limit: 50 }
+     * // (page = floor(1000/50) + 1 = 21)
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Fractional skip values (floor operation)
+     * const result = ResourcePaginationHelper.normalizePagination({
+     *   skip: 37,
+     *   limit: 10
+     * });
+     * // Result: { page: 4, skip: 37, limit: 10 }
+     * // (page = floor(37/10) + 1 = 4)
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Mixed parameters - skip takes precedence over page
+     * const result = ResourcePaginationHelper.normalizePagination({
+     *   page: 2,
+     *   skip: 30,
+     *   limit: 15
+     * });
+     * // Result: { page: 3, skip: 30, limit: 15 }
+     * // (skip provided, so page is recalculated from skip)
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Database cursor scenario
+     * const result = ResourcePaginationHelper.normalizePagination({
+     *   skip: 500,
+     *   limit: 100
+     * });
+     * // Result: { page: 6, skip: 500, limit: 100 }
+     * // Useful for database queries with OFFSET
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // API pagination with user input
+     * const userOptions = { page: 5, limit: 20 };
+     * const result = ResourcePaginationHelper.normalizePagination(userOptions);
+     * // Result: { page: 5, skip: 80, limit: 20 }
+     * // Ready for database query: LIMIT 20 OFFSET 80
+     * ```
+     *
+     * @remarks
+     * - Page numbers are 1-based (first page = 1, not 0)
+     * - Skip values are 0-based (skip 0 = first record)
+     * - Invalid limit values disable pagination entirely
+     * - When both page and skip are provided, skip takes precedence for page calculation
+     * - Negative or zero page values default to page 1
+     * - Fractional skip values are floored when calculating page numbers
+     */
+    static normalizePagination<DataType = unknown>(options?: ResourceQueryOptions<DataType>): {
+        page?: undefined;
+        skip?: undefined;
+        limit?: undefined;
+    } | {
+        page: number;
+        skip: number;
+        limit: number;
+    };
+    /**
+     * Normalizes orderBy parameters into a structured object format.
+     *
+     * This method takes various input formats for sorting criteria and converts them into a consistent
+     * object where keys are valid nested property paths and values are sort directions ("asc" or "desc").
+     * It handles single strings, arrays of strings, and undefined inputs gracefully.
+     *
+     * @template T - The resource type to validate paths against
+     * @param orderBy - The orderBy specification in various formats:
+     *   - `string`: Single field like "name" (ascending) or "-name" (descending)
+     *   - `string[]`: Multiple fields like ["name", "-age", "createdAt"]
+     *   - `undefined`: No sorting specified
+     * @returns A partial record mapping valid nested paths to sort directions
+     *
+     * @example
+     * ```typescript
+     * interface User {
+     *   id: number;
+     *   name: string;
+     *   profile: { age: number; address: { city: string } };
+     * }
+     *
+     * // Single ascending field
+     * normalizeOrderBy<User>("name")
+     * // Returns: { "name": "asc" }
+     *
+     * // Single descending field
+     * normalizeOrderBy<User>("-profile.age")
+     * // Returns: { "profile.age": "desc" }
+     *
+     * // Multiple fields
+     * normalizeOrderBy<User>(["name", "-profile.age", "profile.address.city"])
+     * // Returns: { "name": "asc", "profile.age": "desc", "profile.address.city": "asc" }
+     *
+     * // Invalid input (filtered out)
+     * normalizeOrderBy<User>([null, "", "name", undefined])
+     * // Returns: { "name": "asc" }
+     * ```
+     *
+     * @remarks
+     * - Fields starting with "-" are treated as descending order
+     * - Invalid or empty strings are silently filtered out
+     * - Duplicate fields will log a warning and use the last occurrence
+     * - The method performs type assertion to `NestedPaths<T>` - ensure input paths are valid at call site
+     */
+    static normalizeOrderBy<T = unknown>(orderBy?: ResourceQueryOrderBy<T>): Partial<Record<NestedPaths<T>, SortOrder>>;
+    /***
+     * Determines if result can be paginated based on the provided query options.
+     * It checks if the query options have a `limit` property of type number.
+     * @template DataType The type of resource data.
+     * @param {ResourceQueryOptions} queryOptions - The query options.
+     * @returns {boolean} Whether the result can be paginated.
+     *
+     * @example
+     * canPaginateResult({ limit: undefined }); //false
+     * canPaginateResult({ limit: 10, skip: 20 }); // true
+     * canPaginateResult({ page: 3, limit: 10 }); // true
+     * canPaginateResult({ page: 3, skip: 20 }); // true
+     */
+    static canPaginateResult<DataType = unknown>(queryOptions: ResourceQueryOptions<DataType>): boolean;
+    static getPaginationMetaData<DataType = unknown>(count: number, queryOptions?: ResourceQueryOptions<DataType>): ResourcePaginationMeta;
+    /**
+     * Paginates an array of data based on the provided query options and total count.
+     *
+     * This method applies pagination logic to slice the data array according to the specified
+     * page size and current page, while also generating comprehensive pagination metadata.
+     * It's designed to work seamlessly with database query results and API responses.
+     *
+     * **Pagination Logic:**
+     * - Calculates the correct slice of data based on `page` and `limit` parameters
+     * - Generates metadata including total pages, current page, navigation flags, etc.
+     * - Handles edge cases like invalid page numbers or missing pagination parameters
+     *
+     * **Data Slicing:**
+     * - Uses zero-based indexing for array slicing
+     * - Ensures start/end indices are within array bounds
+     * - Returns empty array if pagination parameters are invalid
+     *
+     * @template DataType - The type of individual data items in the array
+     * @param {DataType[]} data - The complete array of data to be paginated
+     * @param {number} count - The total number of records available (may be different from data.length for database queries)
+     * @param {ResourceQueryOptions<DataType>} [options] - Pagination and query options
+     * @returns {{
+     *   data: DataType[],
+     *   total: number,
+     *   meta: ResourcePaginationMeta
+     * }} An object containing:
+     *   - `data`: The paginated slice of the original data array
+     *   - `total`: The total count of records (unchanged from input)
+     *   - `meta`: Comprehensive pagination metadata
+     *
+     * @example
+     * ```typescript
+     * // Basic pagination - page 1 with 10 items per page
+     * const users = [{id: 1}, {id: 2}, ..., {id: 25}]; // 25 total users
+     * const result = ResourcePaginationHelper.paginate(users, 25, {
+     *   page: 1,
+     *   limit: 10
+     * });
+     * // Result:
+     * // {
+     * //   data: [{id: 1}, {id: 2}, ..., {id: 10}], // First 10 users
+     * //   total: 25,
+     * //   meta: {
+     * //     total: 25,
+     * //     currentPage: 1,
+     * //     pageSize: 10,
+     * //     totalPages: 3,
+     * //     hasNextPage: true,
+     * //     hasPreviousPage: false,
+     * //     nextPage: 2,
+     * //     previousPage: undefined,
+     * //     lastPage: 3
+     * //   }
+     * // }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Middle page pagination
+     * const result = ResourcePaginationHelper.paginate(users, 25, {
+     *   page: 2,
+     *   limit: 10
+     * });
+     * // Result: data contains items 11-20, meta shows navigation to pages 1 and 3
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Last page with fewer items
+     * const result = ResourcePaginationHelper.paginate(users, 25, {
+     *   page: 3,
+     *   limit: 10
+     * });
+     * // Result: data contains items 21-25 (5 items), meta shows no next page
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Using skip instead of page
+     * const result = ResourcePaginationHelper.paginate(users, 25, {
+     *   skip: 15,
+     *   limit: 5
+     * });
+     * // Result: data contains items 16-20, meta shows currentPage: 4
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // No pagination options - returns all data
+     * const result = ResourcePaginationHelper.paginate(users, 25);
+     * // Result: data contains all 25 users, meta is minimal (only total)
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Invalid page number - clamps to valid range
+     * const result = ResourcePaginationHelper.paginate(users, 25, {
+     *   page: 999,
+     *   limit: 10
+     * });
+     * // Result: data is empty array, meta shows page: 999 but no valid data slice
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Database scenario - data array smaller than total count
+     * const dbResult = [{id: 101}, {id: 102}, {id: 103}]; // Only 3 records from DB
+     * const result = ResourcePaginationHelper.paginate(dbResult, 150, {
+     *   page: 34,
+     *   limit: 3
+     * });
+     * // Result: data contains the 3 DB records, total: 150, meta shows page 34 of ~50
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Empty data array
+     * const result = ResourcePaginationHelper.paginate([], 0, {
+     *   page: 1,
+     *   limit: 10
+     * });
+     * // Result: data is empty array, total: 0, meta shows single empty page
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Large dataset pagination
+     * const largeDataset = Array.from({length: 10000}, (_, i) => ({id: i + 1}));
+     * const result = ResourcePaginationHelper.paginate(largeDataset, 10000, {
+     *   page: 500,
+     *   limit: 20
+     * });
+     * // Result: data contains items 9981-10000, meta shows page 500 of 500
+     * ```
+     */
+    static paginate<DataType = unknown>(data: DataType[], count: number, options?: ResourceQueryOptions<DataType>): {
+        data: DataType[];
+        total: number;
+        meta: ResourcePaginationMeta;
+    };
+    /**
+     * Parses query options from HTTP request data, extracting and normalizing parameters from multiple sources.
+     *
+     * This method consolidates query parameters from URL query strings, request headers, route parameters,
+     * and custom filters into a standardized `ResourceQueryOptions` object. It's designed for REST API
+     * endpoints that need to handle complex query parameters for filtering, sorting, pagination, and more.
+     *
+     * **Parameter Sources (in precedence order):**
+     * 1. URL query parameters (`req.url`)
+     * 2. Route parameters (`req.params`)
+     * 3. X-Filters header (`req.headers['x-filters']`)
+     * 4. Custom filters (`req.filters`)
+     *
+     * **Supported Parameters:**
+     * - **Pagination**: `limit`, `skip`, `page`
+     * - **Sorting**: `orderBy` (string, array, or object)
+     * - **Filtering**: `where` (object, array, or string conditions)
+     * - **Relations**: `include`, `relations` (related data to load)
+     * - **Caching**: `cache`, `cacheTTL`
+     * - **Soft Deletes**: `includeDeleted`
+     * - **Distinct**: `distinct` (unique results)
+     *
+     * @template T - The resource data type for type-safe query options
+     * @param {Object} req - The request object containing query data from multiple sources
+     * @param {string} req.url - The request URL containing query parameters
+     * @param {Dictionary} req.headers - Request headers (may include 'x-filters')
+     * @param {Dictionary} [req.params] - Route parameters from URL path
+     * @param {Dictionary} [req.filters] - Custom filter object
+     * @returns {ResourceQueryOptions<T> & {queryParams: Dictionary}} Normalized query options with:
+     *   - All standard `ResourceQueryOptions<T>` properties
+     *   - `queryParams`: Raw parsed query parameters for reference
+     *
+     * @example
+     * ```typescript
+     * // Basic pagination from URL query
+     * const req = {
+     *   url: '/api/users?limit=10&page=2',
+     *   headers: {}
+     * };
+     * const options = ResourcePaginationHelper.parseQueryOptions(req);
+     * // Result: { limit: 10, page: 2, skip: 10, queryParams: { limit: '10', page: '2' } }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Complex query with multiple sources
+     * const req = {
+     *   url: '/api/users?limit=20&orderBy=name',
+     *   headers: {
+     *     'x-filters': {
+     *       where: { active: true },
+     *       include: ['profile', 'roles']
+     *     }
+     *   },
+     *   params: { userId: '123' },
+     *   filters: { cache: true }
+     * };
+     * const options = ResourcePaginationHelper.parseQueryOptions(req);
+     * // Result includes all merged parameters with proper precedence
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Sorting with multiple fields
+     * const req = {
+     *   url: '/api/users?orderBy[]=name&orderBy[]=-createdAt',
+     *   headers: {}
+     * };
+     * const options = ResourcePaginationHelper.parseQueryOptions(req);
+     * // Result: { orderBy: { name: 'asc', createdAt: 'desc' }, ... }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Filtering with complex where conditions
+     * const req = {
+     *   url: '/api/users',
+     *   headers: {
+     *     'x-filters': {
+     *       where: {
+     *         age: { $gte: 18 },
+     *         status: 'active',
+     *         $or: [{ role: 'admin' }, { role: 'moderator' }]
+     *       }
+     *     }
+     *   }
+     * };
+     * const options = ResourcePaginationHelper.parseQueryOptions(req);
+     * // Result includes complex where conditions for database queries
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Including related data
+     * const req = {
+     *   url: '/api/posts?include[]=author&include[]=comments',
+     *   headers: {
+     *     'x-filters': {
+     *       relations: ['tags', 'categories']
+     *     }
+     *   }
+     * };
+     * const options = ResourcePaginationHelper.parseQueryOptions(req);
+     * // Result: { include: ['author', 'comments'], relations: ['tags', 'categories'], ... }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Caching configuration
+     * const req = {
+     *   url: '/api/users?cache=1&cacheTTL=300',
+     *   headers: {}
+     * };
+     * const options = ResourcePaginationHelper.parseQueryOptions(req);
+     * // Result: { cache: true, cacheTTL: 300, ... }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Distinct results and soft deletes
+     * const req = {
+     *   url: '/api/users?distinct=1&includeDeleted=true',
+     *   headers: {}
+     * };
+     * const options = ResourcePaginationHelper.parseQueryOptions(req);
+     * // Result: { distinct: true, includeDeleted: true, ... }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Express.js style request object
+     * const expressReq = {
+     *   url: '/api/users?limit=5&page=1&orderBy=name',
+     *   headers: {
+     *     'x-filters': JSON.stringify({ where: { active: true } })
+     *   },
+     *   params: { tenantId: 'abc123' },
+     *   query: { search: 'john' } // Additional query params
+     * };
+     * const options = ResourcePaginationHelper.parseQueryOptions(expressReq);
+     * // Handles all Express.js request formats automatically
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Minimal request - only URL parameters
+     * const req = {
+     *   url: '/api/users',
+     *   headers: {}
+     * };
+     * const options = ResourcePaginationHelper.parseQueryOptions(req);
+     * // Result: { queryParams: {} } - minimal options, no pagination/sorting
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Mixed data types and type coercion
+     * const req = {
+     *   url: '/api/users?limit=10&page=2&cache=true&includeDeleted=0',
+     *   headers: {
+     *     'x-filters': {
+     *       distinct: '1',  // String '1' becomes boolean true
+     *       cacheTTL: '600' // String '600' becomes number 600
+     *     }
+     *   }
+     * };
+     * const options = ResourcePaginationHelper.parseQueryOptions(req);
+     * // Result: proper type coercion for all parameters
+     * ```
+     */
+    static parseQueryOptions<T = unknown>(req: {
+        url: string;
+        headers: Dictionary;
+        params?: Dictionary;
+        filters?: Dictionary;
+    }): ResourceQueryOptions<T> & {
+        queryParams: Dictionary;
+    };
+}
+type SortOrder = 'asc' | 'desc';
+export {};

package/build/resources/ResourcePaginationHelper.js

@@ -0,0 +1,2 @@
+'use strict';var _=require('qs');function _interopDefault(e){return e&&e.__esModule?e:{default:e}}var ___default=/*#__PURE__*/_interopDefault(_);var Q=Object.defineProperty,W=Object.defineProperties;var K=Object.getOwnPropertyDescriptors;var M=Object.getOwnPropertySymbols;var v=Object.prototype.hasOwnProperty,F=Object.prototype.propertyIsEnumerable;var U=(t,e,n)=>e in t?Q(t,e,{enumerable:true,configurable:true,writable:true,value:n}):t[e]=n,A=(t,e)=>{for(var n in e||(e={}))v.call(e,n)&&U(t,n,e[n]);if(M)for(var n of M(e))F.call(e,n)&&U(t,n,e[n]);return t},k=(t,e)=>W(t,K(e));function w(...t){if(t.length===1)return Array.isArray(t[0])?t[0]:[];let e=null;for(var n in t){let r=t[n];if(Array.isArray(r)){if(r.length)return r;e||(e=r);}}return e||[]}function u(t){return !!(t&&typeof t=="string")}function O(t){return typeof t=="number"&&!isNaN(t)&&isFinite(t)}function R(t){return !t||typeof t!="object"?false:t instanceof Date?true:typeof t.getTime!="function"?false:!(Object.prototype.toString.call(t)!=="[object Date]"||isNaN(t.getTime()))}function N(t){return typeof window!="object"||!window||typeof document=="undefined"||typeof HTMLElement=="undefined"||!HTMLElement?false:t===document?true:"HTMLElement"in window?!!t&&t instanceof HTMLElement:!!t&&typeof t=="object"&&t.nodeType===1&&!!t.nodeName}function D(t){return t==null||typeof t=="string"||typeof t=="number"||typeof t=="boolean"}function j(t){if(t instanceof RegExp)return  true;if(!t||typeof t!="object"||!Object.prototype.toString.call(t).includes("RegExp"))return  false;try{return new RegExp(t),!0}catch(e){return  false}}function y(t){if(t===null||typeof t!="object"||N(t)||R(t)||j(t)||D(t))return  false;let e=Object.getPrototypeOf(t);if(e===null)return  true;let n=e.constructor;if(typeof n!="function")return  false;if(n===Object)return  true;let r=n.prototype;return typeof r!="object"?false:r===Object.prototype?true:typeof e.hasOwnProperty=="function"&&Object.prototype.hasOwnProperty.call(e,"isPrototypeOf")&&typeof e.isPrototypeOf=="function"}function C(t){if(Array.isArray(t)){let r=[];for(var e=0;e<t.length;e++)r[e]=C(t[e]);return r}else if(y(t)&&t){let r={};for(var n in t)t.hasOwnProperty(n)&&(r[n]=C(t[n]));return r}else return t}Object.getSize=function(t,e=false){if(!t||typeof t!="object")return 0;if(Array.isArray(t))return t.length;typeof e!="boolean"&&(e=false);let n=0;for(let r in t)if(Object.prototype.hasOwnProperty.call(t,r)&&(n++,e===true))return n;return n};function x(t,...e){let n=Array.isArray(t),r=y(t);(t==null||!n&&!r)&&(t={});for(let i=0;i<e.length;i++){let s=e[i];if(s==null)continue;let o=y(s),c=Array.isArray(s);if(!(!o&&!c)){if(n){c&&L(t,s);continue}else if(c)continue;for(let a in s){let f=s[a];if(f==null)continue;if(f===s){t[a]=t;continue}let p=t[a],m=Array.isArray(p),h=Array.isArray(f);if(m){h?L(t[a],f):t[a]=f;continue}else if(!y(p)){t[a]=f;continue}if(h||!y(f)){t[a]=f;continue}t[a]=x({},p,f);}}}return t}var L=(t,e)=>{let n=e.length,r=0;for(let i=0;i<t.length;i++){let s=t[i],o=e[i];if(i<n){let c=Array.isArray(s),a=Array.isArray(o),f=y(s),p=y(o);c&&a||f&&p?(t[r]=x(c?[]:{},s,o),r++):o!=null?(t[r]=o,r++):s!=null&&(t[r]=s,r++);}}for(let i=t.length;i<n;i++)e[i]!==void 0&&e[i]!==null&&t.push(e[i]);return t};function Z(t,e){return P(t,"",{},e)}function P(t,e="",n={},r){if(n=y(n)?n:{},D(t)||R(t)||j(t)||Array.isArray(t)&&(r!=null&&r.skipArrays))return e&&(n[e]=t),n;if(typeof t=="function"||typeof t=="object"&&!y(t)&&!H(t))return n;if(t instanceof Map||t instanceof WeakMap)return Array.from(t.entries()).forEach(([i,s])=>{let o=e?`${e}[${String(i)}]`:String(i);P(s,o,n,r);}),n;if(Array.isArray(t)||t instanceof Set||t instanceof WeakSet)return (Array.isArray(t)?t:Array.from(t)).forEach((s,o)=>{let c=e?`${e}[${o}]`:String(o);P(s,c,n,r);}),n;if(y(t))for(let i in t){if(!Object.prototype.hasOwnProperty.call(t,i))continue;let s=t[i],o=e?e.endsWith("]")?`${e}.${i}`:`${e}.${i}`:i;P(s,o,n,r);}return n}function H(t){return Array.isArray(t)||t instanceof Set||t instanceof Map||t instanceof WeakMap||t instanceof WeakSet}function V(t){return Object.entries(t)}Object.typedEntries=V;Object.flatten=Z;Object.clone=C;var S=function(t,e=""){if(!t||typeof t!="string")return "";if(!e||typeof e!="string")return t.trim();let n=t.length;for(;t.startsWith(e)&&n>=0;)t=t.slice(e.length),--n;return t.toString()},$=function(t,e=""){if(!t||typeof t!="string")return "";if(!e||typeof e!="string")return t.trim();let n=t.length;for(;t.endsWith(e)&&n>=0;)t=t.slice(0,-e.length),--n;return t.toString()},I=(t,e=true)=>typeof t!="string"?false:e!==false?/^\d*\.?\d+$/.test(t):/^\d+$/.test(t);String.prototype.ltrim=function(t){return S(this.toString(),t)};String.prototype.rtrim=function(t){return $(this.toString(),t)};String.prototype.isNumber=function(t=true){return I(this.toString(),t)};String.prototype.replaceAll=function(t,e){return !u(t)||!u(e)?this.toString():this.toString().split(t).join(e)};var G=t=>u(t)?(t=t.trim(),t.replace(/(.)([A-Z][a-z]+)/,"$1_$2").replace(/([a-z0-9])([A-Z])/,"$1_$2").toUpperCase()):"";String.prototype.toSnakeCase=function(){return G(this.toString())};var J=t=>u(t)?(t=t.trim(),t.charAt(0)+t.replace(/(_\w)/g,e=>e[1].toUpperCase()).substring(1)):"";String.prototype.toCamelCase=function(){return J(this.toString())};var X=function(t){return !t||typeof t!="string"?"":(t=t.trim(),t.charAt(0).toUpperCase()+t.slice(1))};String.prototype.upperFirst=function(){return X(this.toString())};var Y=function(t){return !t||typeof t!="string"?"":(t=t.trim(),t.charAt(0).toLowerCase()+t.slice(1))};String.prototype.lowerFirst=function(){return Y(this.toString())};var q=(t,e=true)=>{if(typeof t!="string")return "";let n=tt(t);return t=typeof n.search=="string"?n.search:"",e&&t?"?"+S(t,"?"):(t=$(S(t.trim(),"?"),"?"),t)},E=function(t,e={}){return typeof t!="string"?{}:___default.default.parse(q(t,false),A({allowSparse:true,decoder:n=>decodeURIComponent(n.replace(/\+/g," "))},Object.assign({},e)))};var tt=t=>{if(typeof t!="string")return {};if(typeof URL!="undefined"&&URL&&et(t))try{return new URL(t)}catch(r){}t=nt(t)?decodeURIComponent(t):t;var e=t.match(/^(([^:\\/?#]+:)?(?:\/\/((?:([^\\/?#:]*):([^\\/?#:]*)@)?([^\\/?#:]*)(?::([^\\/?#:]*))?)))?([^?#]*)(\?[^#]*)?(#.*)?$/);let n=e?{hash:e[10]||"",host:e[3]||"",hostname:e[6]||"",href:e[0]||"",origin:e[1]||"",pathname:e[8]||(e[1]?"/":""),port:e[7]||"",protocol:e[2]||"",search:e[9]||"",username:e[4]||"",password:e[5]||""}:{};return n.protocol&&n.protocol.length==2&&(n.protocol="file:///"+n.protocol.toUpperCase(),n.origin=n.protocol+"//"+n.host),n.protocol&&(n.href=n.origin+n.pathname+n.search+n.hash),n};function et(t,e={}){let{requireHost:n=true,allowedProtocols:r}=Object.assign({},e);if(!u(t)||!u(t.trim()))return  false;let i=t;if(typeof URL!="undefined"&&URL)try{let s=new URL(i);if(!s.protocol||s.protocol===":")return !1;let o=s.protocol.slice(0,-1);if(r&&r.length>0&&!r.includes(o))return !1;if(n)if(["http","https","ftp","ftps","ws","wss"].includes(o)){if(!u(s.hostname)||!s.hostname.trim()||!u(s.host)||!s.host.trim())return !1;let a=`${o}://`;if(!i.startsWith(a)||i.slice(a.length).startsWith("/"))return !1;let p=/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/,m=s.hostname.match(p);if(m&&!m.slice(1,5).map(Number).every(l=>l>=0&&l<=255))return !1}else return !1;return !0}catch(s){return  false}if(n){let s=i.indexOf("://");if(s===-1)return  false;let o=i.slice(0,s);if(!o||r&&r.length>0&&!r.includes(o))return  false;let c=i.slice(s+3);if(c==="")return  false;let a=c.indexOf("@"),f=a>=0?c.slice(a+1):c;if(f===""||f.startsWith("/"))return  false;let p=f.indexOf("/"),m=f.indexOf("?"),h=f.indexOf("#"),T=Math.min(p>=0?p:f.length,m>=0?m:f.length,h>=0?h:f.length),l=f.slice(0,T);if(!l)return  false;let d=l;if(l.startsWith("[")){let g=l.indexOf("]");if(g===-1)return  false;d=l.slice(0,g+1);let b=l.slice(g+1);if(b&&!b.startsWith(":"))return  false}else {let g=l.indexOf(":");g>=0&&(d=l.slice(0,g));}if(!d)return  false;if(d==="localhost")return  true;if(/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(d))return !d.split(".").map(Number).some(b=>b>255||b<0);if(/^\[.*\]$/.test(d)){let g=d.slice(1,-1);return !(!g||g.includes(":::"))}return !!(/^[a-zA-Z\d-]*(\.[a-zA-Z\d-]+)*$/.test(d)&&d!=="")}else {let s="[a-zA-Z][a-zA-Z\\d+\\-.]*";return r&&r.length>0&&(s=`(?:${r.join("|")})`),new RegExp(`^(${s}):.+$`).test(i)}}var nt=t=>{if(!u(t)||!t.includes("%"))return  false;let e=/%[0-9A-Fa-f]{2}/g;if(!t.match(e))return  false;try{let r=decodeURIComponent(t);if(r!==t)return !0;try{if(decodeURIComponent(r)!==r)return !0}catch(i){return !0}}catch(r){return  false}return  false};var B=class t{static normalizePagination(e){let{page:n,skip:r,limit:i}=Object.assign({},e);return O(i)?(O(r)&&r>0?n=Math.floor(r/i)+1:O(n)&&n>0?r=(n-1)*i:(n=1,r=0),{page:n,skip:r,limit:i}):{}}static normalizeOrderBy(e){let n=Array.isArray(e)?e:u(e)?[e]:[],r={};return n.forEach(i=>{if(!u(i)||String(i).trim()==="")return;let s=String(i).startsWith("-"),o=s?"desc":"asc",c=s?String(i).slice(1):i,a=c;r[a]!==void 0&&console.warn(`Duplicate orderBy field: ${c}. Using last occurrence.`),r[a]=o;}),r}static canPaginateResult(e){return y(e)?O(e.limit):false}static getPaginationMetaData(e,n){let{limit:r,page:i,skip:s}=t.normalizePagination(n);e=O(e)?e:0;let o={total:e};return typeof r=="number"&&r>0&&typeof i=="number"&&i>=0&&(o.currentPage=i,o.pageSize=r,o.totalPages=Math.ceil(e/r),o.hasNextPage=o.currentPage<o.totalPages,o.hasPreviousPage=o.currentPage>1,o.nextPage=o.hasNextPage?o.currentPage+1:void 0,o.previousPage=o.hasPreviousPage?o.currentPage-1:void 0,o.lastPage=o.totalPages),o}static paginate(e,n,r){let i=t.getPaginationMetaData(n,r),{currentPage:s,pageSize:o,totalPages:c}=i;if(Array.isArray(e)&&O(s)&&O(o)&&O(c)){let a=Math.max(0,s-1)*o,f=a+o;e=e.slice(a,f);}return {data:e,total:n,meta:i}}static parseQueryOptions(e){var b;let n=x({},e==null?void 0:e.params,E(e==null?void 0:e.url)),r=x({},n,(b=e==null?void 0:e.headers)==null?void 0:b["x-filters"],e==null?void 0:e.filters),i=z(r.limit),s=z(r.skip),o=z(r.page),c=t.normalizePagination({limit:i,skip:s,page:o}),a=r.distinct;typeof a=="number"&&(a=!!a),(typeof a=="boolean"||Array.isArray(a)&&a.length)&&(c.distinct=a);let f=r.orderBy,p=t.normalizeOrderBy(f);p&&Object.getSize(p,true)>0&&(c.orderBy=p);let m=w(r.include);m.length&&(c.include=m);let h=r.cache;h!==void 0&&(c.cache=!!h);let T=r.cacheTTL;T!==void 0&&(c.cacheTTL=T);let l=rt(r.where);y(l)&&Object.getSize(l,true)&&(c.where=l);let d=r.includeDeleted;typeof d=="boolean"&&(c.includeDeleted=d);let g=w(r.relations);return g.length&&(c.relations=g),k(A({},c),{queryParams:n})}},rt=(...t)=>{for(let e of t)if(Array.isArray(e)&&e.length||u(e)||y(e)&&Object.getSize(e,true))return e},z=t=>{if(I(t))return Number(t);if(typeof t=="number")return t};
+exports.ResourcePaginationHelper=B;

package/build/resources/decorators/create.decorator.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Creates a decorator that can be applied to class properties or methods.
+ *
+ * This function takes a key of type KeyType (defaulting to any) and returns a function that takes a value of type ValueType (defaulting to any).
+ * The returned function is a decorator that can be applied to class properties or methods.
+ *
+ * @template KeyType - The type of the key used to store metadata.
+ * @template ValueType - The type of the value associated with the key.
+ * @param {KeyType} key - The key under which the metadata will be stored.
+ * @returns {(value: ValueType) => (target: Object, propertyKey: string) => void} A function that takes a value and returns the decorator function.
+ * @example
+ * ```typescript
+ * const myDecorator = createDecorator('myKey')('myValue');
+ * class MyClass {
+ *   @myDecorator
+ *   myProperty: string;
+ * }
+ * ```
+ */
+export declare function createDecorator<ValueType = unknown, KeyType = unknown>(key: KeyType): (value: ValueType) => (target: object, propertyKey: string | symbol) => void;

package/build/resources/decorators/create.decorator.js

@@ -0,0 +1 @@
+'use strict';function o(e){return t=>(n,r)=>{Reflect.defineMetadata(e,t,n,r);}}exports.createDecorator=o;

package/build/resources/decorators/index.d.ts

@@ -0,0 +1,41 @@
+import 'reflect-metadata';
+import { ClassConstructor } from '../../types';
+/**
+ * Creates a property decorator that stores metadata without making the property readonly
+   @template MetadataType - The type of the metadata
+   @template PropertyKeyType - The type of the property key
+ * @param metadataKey - The key to store the metadata under
+   @param metadata - The metadata to store, or a function that returns the metadata
+ * @returns PropertyDecorator
+ */
+export declare function buildPropertyDecorator<MetadataType = unknown, PropertyKeyType extends MetadataPropertyKey = MetadataPropertyKey>(metadataKey: any, 
+/**
+    Retrieves the metadata for a property
+    @param {Object} target - The class constructor
+    @param {PropertyKeyType} propertyKey - The property key
+    @param {MetadataType} existingMetaData - The existing metadata for the property
+    @param {Record<PropertyKeyType, MetadataType>} allExistingMetadata - All existing metadata for the class
+    @returns {MetadataType} The metadata for the property
+    
+*/
+metadata: ((existingMetaData: MetadataType, allExistingMetadata: Record<PropertyKeyType, MetadataType>, target: object, propertyKey: MetadataPropertyKey) => MetadataType) | MetadataType): PropertyDecorator;
+/**
+ * Retrieves all properties of a class that have been decorated with a specific metadata key.
+   @template MetaDataType - The type of the metadata
+   @template PropertyKeyType - The type of the property key
+ * @param target The class to retrieve decorated properties from.
+ * @param metadataKey The metadata key.
+ * @returns Record of property names and their metadata
+ */
+export declare function getDecoratedProperties<MetaDataType = any, PropertyKeyType extends MetadataPropertyKey = MetadataPropertyKey>(target: ClassConstructor, metadataKey: any): Record<PropertyKeyType, MetaDataType>;
+/**
+ * Retrieves metadata for a specific property.
+ * @template MetaDataType - The type of the metadata
+ * @param target - target The class or object containing the property.
+ * @param metadataKey - The key to retrieve metadata for
+ *@param propertyKey - The name of the propertyfor which metadata is being retrieved.
+ * @returns {MetaDataType} The metadata value for the property.
+ */
+export declare function getDecoratedProperty<MetaDataType = unknown>(target: ClassConstructor, metadataKey: MetadataPropertyKey, propertyKey: MetadataPropertyKey): MetaDataType;
+type MetadataPropertyKey = string | symbol | number;
+export {};

package/build/resources/decorators/index.js

@@ -0,0 +1 @@
+'use strict';require('reflect-metadata');function d(t,e){return (a,o)=>{let y=a==null?void 0:a.constructor,r=Object.assign({},Reflect.getMetadata(t,y)),n=r[o],p=typeof e=="function"?e(n,r,a,o):e;r[o]=p,Reflect.defineMetadata(t,r,y),Reflect.defineMetadata(t,e,a,o);}}function s(t,e){return Object.assign({},Object.assign({},Reflect.getMetadata(e,t)),Object.assign({},Reflect.getMetadata(e,t.prototype)))}function M(t,e,a){return s(t,e)[a]}exports.buildPropertyDecorator=d;exports.getDecoratedProperties=s;exports.getDecoratedProperty=M;

package/build/resources/fields/index.d.ts

@@ -0,0 +1,33 @@
+import { ClassConstructor } from '../../types';
+import 'reflect-metadata';
+import { Field, FieldType } from '../types';
+export declare const fieldsMetaData: unique symbol;
+export declare function FieldMeta<T extends FieldType = FieldType>(options: Field<T>): PropertyDecorator;
+/**
+ * Retrieves the fields metadata from a class target.
+ *
+ * This function uses reflection to access the metadata associated with the given target class.
+ * It returns an object where the keys are property names, and the values are objects containing the type, name, and any additional options defined in the field metadata.
+ *
+ * @param {any} target - The target class or instance from which to retrieve the metadata.
+ * @returns {Record<string, ({ name: string } & Field)>} An object mapping property names to their corresponding metadata, which includes the type and other options.
+ * @example
+ * ```typescript
+ * class MyClass {
+ *   @FieldMeta({ type: 'string' }) myField: string;
+ * }
+ * const fields = getFieldsFromTarget(MyClass);
+ * console.log(fields); // Output: { myField: { name: 'myField', type: 'string' } }
+ * ```
+ */
+export declare function getFieldsFromTarget(target: ClassConstructor): Record<string, {
+    name: string;
+} & Field>;
+/***
+ * Retrieves the fields metadata from a class instance.
+ * @param {T} instance - The instance of the class from which to retrieve the metadata.
+ * @returns {Record<string, ({ name: string } & Field)>} An object mapping property names to their corresponding metadata, which includes the type and other options.
+ */
+export declare function getFields<T extends ClassConstructor>(instance: InstanceType<T>): Record<string, {
+    name: string;
+} & Field>;

package/build/resources/fields/index.js

@@ -0,0 +1 @@
+'use strict';require('reflect-metadata');var l=Object.defineProperty;var r=Object.getOwnPropertySymbols;var f=Object.prototype.hasOwnProperty,g=Object.prototype.propertyIsEnumerable;var d=(t,e,s)=>e in t?l(t,e,{enumerable:true,configurable:true,writable:true,value:s}):t[e]=s,c=(t,e)=>{for(var s in e||(e={}))f.call(e,s)&&d(t,s,e[s]);if(r)for(var s of r(e))g.call(e,s)&&d(t,s,e[s]);return t};var n=Symbol("fieldsResourcesMetadata");function p(t){return function(e,s){var o;let a=Object.assign({},Reflect.getMetadata(n,e)||{}),i=String((o=Reflect.getMetadata("design:type",e,s))==null?void 0:o.name).toLowerCase();t.type===void 0&&(t.type=["string","number","boolean","date"].includes(i)?i:"text"),a[s]=c({name:s},Object.assign({},t)),Reflect.defineMetadata(n,a,e);}}function F(t){let e=Reflect.getMetadata(n,t.prototype);return Object.assign({},e)}function y(t){let e=Reflect.getMetadata(n,Object.getPrototypeOf(t).constructor);return Object.assign({},e)}exports.FieldMeta=p;exports.fieldsMetaData=n;exports.getFields=y;exports.getFieldsFromTarget=F;