feat: add resolvePagination helper and add defaults for perPage helper

Author: 3m1n3nc3

docs/api.md

@@ -404,7 +404,8 @@ Decorating a controller method with `@Bind()` enables typed injection of `Reques
 - `Hook` — process-local hook registry with `set`, `has`, `get`, `getAll`, `unset`, and `clear`.
 - `Publisher` — registry for `ark publish`: `publishes(group)`, `publishables(filter?)`, `confirm(confirmation)`, `confirmables(package | true)`, and `clear()`. See the [publish guide](/guide/cli#publish).
 - `getModel(name)` — typed app model resolver.
-- `perPage(query)` — pagination limit helper.
+- `perPage(query, defaults?)` — pagination limit helper.
+- `resolvePagination(query, defaults?)` — pagination limit,page helper.
 
 ### Custom error responses
 

docs/guide/utilities/helpers.md

@@ -2,15 +2,30 @@
 
 Small utility functions that can be used across the application for common tasks.
 
-## `perPage(query)`
+## `perPage(query, defaults?)`
 
-Extracts a safe pagination limit from a query object. Clamps the result between `1` and `50`, defaulting to `15`.
+Extracts a safe pagination limit from a query object. Clamps the result between `1` and `50` or the configured default `maxPerPage`, defaulting to `25` or the configured default `perPage`.
 
 ```ts
 import { perPage } from '@arkstack/common';
 
 const limit = perPage({ limit: 100 }); // 50 (clamped)
-const limit2 = perPage({}); // 15 (default)
+const limit2 = perPage({ limit: 100 }, { maxPerPage: 100 }); // 100
+const limit3 = perPage({}); // 25 (default)
+const limit3 = perPage({}, { perPage: 100 }); // 100
+```
+
+## `resolvePagination(query, defaults?)`
+
+Extracts the current page and a safe pagination limit from a query object. Clamps the resulting `perPage` between `1` and `50` or the configured default `maxPerPage`, defaulting to `25` or the configured default `perPage`.
+
+```ts
+import { resolvePagination } from '@arkstack/common';
+
+const limit = resolvePagination({ limit: 100 }); // {perPage: 50, page: 1} (clamped)
+const limi2 = resolvePagination({ limit: 100 }, { maxPerPage: 100 }); // {perPage: 100, page: 1}
+const limit3 = resolvePagination({}); // {perPage: 50, page: 1} (default)
+const limit4 = resolvePagination({}, { perPage: 100, page: 2 }); // {perPage: 100, page: 2}
 ```
 
 ## `getModel(modelName)`

packages/common/README.md

@@ -739,15 +739,30 @@ Key exported types from the package:
 
 **`src/utils/helpers.ts`**
 
-#### `perPage(query)`
+#### `perPage(query, defaults?)`
 
-Extracts a safe pagination limit from a query object. Clamps the result between `1` and `50`, defaulting to `15`.
+Extracts a safe pagination limit from a query object. Clamps the result between `1` and `50` or the configured default `maxPerPage`, defaulting to `25` or the configured default `perPage`.
 
 ```ts
 import { perPage } from '@arkstack/common';
 
 const limit = perPage({ limit: 100 }); // 50 (clamped)
-const limit2 = perPage({}); // 15 (default)
+const limit2 = perPage({ limit: 100 }, { maxPerPage: 100 }); // 100
+const limit3 = perPage({}); // 25 (default)
+const limit3 = perPage({}, { perPage: 100 }); // 100
+```
+
+#### `resolvePagination(query, defaults?)`
+
+Extracts the current page and a safe pagination limit from a query object. Clamps the resulting `perPage` between `1` and `50` or the configured default `maxPerPage`, defaulting to `25` or the configured default `perPage`.
+
+```ts
+import { resolvePagination } from '@arkstack/common';
+
+const limit = resolvePagination({ limit: 100 }); // {perPage: 50, page: 1} (clamped)
+const limi2 = resolvePagination({ limit: 100 }, { maxPerPage: 100 }); // {perPage: 100, page: 1}
+const limit3 = resolvePagination({}); // {perPage: 50, page: 1} (default)
+const limit4 = resolvePagination({}, { perPage: 100, page: 2 }); // {perPage: 100, page: 2}
 ```
 
 #### `getModel(modelName)`

packages/common/src/types.ts

@@ -293,6 +293,11 @@ export type Choice<Value> = {
 
 export type Choices = readonly string[] | readonly Choice<string>[];
 
+export type PaginationOptions = {
+    page: number
+    perPage: number
+}
+
 /**
 * A single source → destination mapping a package wants to publish into the
 * consuming application.

packages/common/src/utils/helpers.ts

@@ -5,6 +5,7 @@ import { Arkstack } from '@arkstack/contract'
 import { RequestException } from '../Exceptions/RequestException'
 
 import { createRequire } from 'node:module'
+import { PaginationOptions } from '../types'
 
 export type AbstractModelConstructor<TModel = unknown> =
     abstract new (attributes?: Record<string, unknown>) => TModel
@@ -34,29 +35,74 @@ export const isClass = <T = unknown>(
         && /^class\s/.test(Function.prototype.toString.call(target))
 }
 
+export const normalizePositiveInteger = (value: unknown, fallback: number) => {
+    const parsed = Number(value)
+
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        return fallback
+    }
+
+    return parsed
+}
+
 /**
- * Resolves the number of items to return per page based on the provided query parameters.
+ * Extracts a safe pagination limit from a query object.
  * 
  * @param query 
+ * @param defaults 
+ * @default const defaults = { pageSize: 25, maxPageSize: 50 }
  * @returns 
  */
-export const perPage = (query: {
-    limit?: number;
-    perPage?: number;
-    per_page?: number;
-    'per-page'?: number;
-}) => {
-
-    const requestedPerPage = Number(
+export const perPage = (
+    query: {
+        limit?: number;
+        perPage?: number;
+        per_page?: number;
+        'per-page'?: number;
+    },
+    defaults: {
+        perPage?: number;
+        maxPerPage?: number
+    }) => {
+
+    const requestedPerPage = normalizePositiveInteger(
         query.limit ??
         query.perPage ??
         query['per-page'] ??
-        query.per_page ?? 15
+        query.per_page,
+        defaults.perPage ?? 25
     )
 
-    return Number.isFinite(requestedPerPage) && requestedPerPage > 0
-        ? Math.min(requestedPerPage, 50)
-        : 15
+    return Math.min(requestedPerPage, defaults.maxPerPage ?? 50)
+}
+
+/**
+ * Extracts the current page and a safe pagination limit from a query object.
+ * 
+ * @param query 
+ * @param defaults 
+ * @default const defaults = { currentPage: 1, pageSize: 25, maxPageSize: 50 }
+ * @returns 
+ */
+export const resolvePagination = (
+    query: {
+        page?: number;
+        limit?: number;
+        perPage?: number;
+        per_page?: number;
+        'per-page'?: number;
+    },
+    defaults: {
+        page?: number;
+        perPage?: number;
+        maxPerPage?: number
+    }): PaginationOptions => {
+    const page = normalizePositiveInteger(query.page, defaults.page ?? 1)
+
+    return {
+        page,
+        perPage: perPage(query, defaults)
+    }
 }
 
 /**