@arkstack/common 0.17.11 → 0.17.13

package/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)`

package/dist/helpers-CC35u6ti.d.ts

@@ -0,0 +1,531 @@
+import { JitiOptions, JitiResolveOptions } from "jiti";
+import { TOTP } from "otpauth";
+import { ChalkInstance } from "chalk";
+import { Model, ModelStatic } from "arkormx";
+
+//#region src/Logger.d.ts
+declare class Console {
+  static log: (...args: any[]) => string | void;
+  static debug: (...args: any[]) => void;
+  static warn: (...args: any[]) => void[];
+  static info: (...args: any[]) => void[];
+  static error: (...args: any[]) => void[];
+}
+declare class Logger {
+  /**
+   * Global verbosity configuration
+   */
+  private static verbosity;
+  private static isQuiet;
+  private static isSilent;
+  /**
+   * Configure global verbosity levels
+   */
+  static configure(options?: {
+    verbosity?: number;
+    quiet?: boolean;
+    silent?: boolean;
+  }): void;
+  /**
+   * Check if output should be suppressed
+   */
+  private static shouldSuppressOutput;
+  /**
+   * Logs the message in two columns
+   *
+   * @param name
+   * @param value
+   * @param log If set to false, array of [name, dots, value] output will be returned and not logged
+   * @returns
+   */
+  static twoColumnDetail(name: string, value: string, log?: true, spacer?: string): void;
+  static twoColumnDetail(name: string, value: string, log?: false, spacer?: string): [string, string, string];
+  /**
+   * Logs the message in two columns
+   *
+   * @param name
+   * @param desc
+   * @param width
+   * @param log If set to false, array of [name, dots, value] output will be returned and not logged
+   * @returns
+   */
+  static describe(name: string, desc: string, width?: number, log?: true): void;
+  static describe(name: string, desc: string, width?: number, log?: false): [string, string, string];
+  /**
+   * Logs the message in two columns but allways passing status
+   *
+   * @param name
+   * @param value
+   * @param status
+   * @param exit
+   * @param preserveCol
+   */
+  static split(name: string, value: string, status?: 'success' | 'info' | 'error', exit?: boolean, preserveCol?: boolean, spacer?: string): void;
+  /**
+   * Wraps text with chalk
+   *
+   * @param txt
+   * @param color
+   * @param preserveCol
+   * @returns
+   */
+  static textFormat(txt: unknown | unknown[], color: (...text: unknown[]) => string, preserveCol?: boolean): string;
+  /**
+   * Logs a success message
+   *
+   * @param msg
+   * @param exit
+   * @param preserveCol
+   */
+  static success(msg: any, exit?: boolean, preserveCol?: boolean): void;
+  /**
+   * Logs an informational message
+   *
+   * @param msg
+   * @param exit
+   * @param preserveCol
+   */
+  static info(msg: any, exit?: boolean, preserveCol?: boolean): void;
+  /**
+   * Logs an error message
+   *
+   * @param msg
+   * @param exit
+   * @param preserveCol
+   */
+  static error(msg: any, exit?: boolean, preserveCol?: boolean): void;
+  /**
+   * Logs a warning message
+   *
+   * @param msg
+   * @param exit
+   * @param preserveCol
+   */
+  static warn(msg: any, exit?: boolean, preserveCol?: boolean): void;
+  /**
+   * Logs a debug message (only shown with verbosity >= 3)
+   *
+   * @param msg
+   * @param exit
+   * @param preserveCol
+   */
+  static debug<M = any>(msg: M | M[], exit?: boolean, preserveCol?: boolean): void;
+  /**
+   * Terminates the process
+   */
+  static quiet(): void;
+  static chalker(styles: LoggerChalk[]): (input: any) => string;
+  /**
+   * Parse an array formated message and logs it
+   *
+   * @param config
+   * @param joiner
+   * @param log If set to false, string output will be returned and not logged
+   * @param sc color to use ue on split text if : is found
+   */
+  static parse(config: LoggerParseSignature, joiner?: string, log?: true, sc?: LoggerChalk): void;
+  static parse(config: LoggerParseSignature, joiner?: string, log?: false, sc?: LoggerChalk): string;
+  /**
+   * Ouput formater object or format the output
+   *
+   * @returns
+   */
+  static log: LoggerLog;
+  /**
+   * A simple console like output logger
+   *
+   * @returns
+   */
+  static console(): typeof Console;
+}
+//#endregion
+//#region src/locales.d.ts
+declare const locales: readonly ["af_ZA", "ar", "az", "bn_BD", "cs_CZ", "cy", "da", "de", "de_AT", "de_CH", "dv", "el", "en", "en_AU", "en_AU_ocker", "en_BORK", "en_CA", "en_GB", "en_GH", "en_HK", "en_IE", "en_IN", "en_NG", "en_US", "en_ZA", "eo", "es", "es_MX", "fa", "fi", "fr", "fr_BE", "fr_CA", "fr_CH", "fr_LU", "fr_SN", "he", "hr", "hu", "hy", "id_ID", "it", "ja", "ka_GE", "ko", "ku_ckb", "ku_kmr_latin", "lv", "mk", "mn_MN_cyrl", "nb_NO", "ne", "nl", "nl_BE", "pl", "pt_BR", "pt_PT", "ro", "ro_MD", "ru", "sk", "sl_SI", "sr_RS_latin", "sv", "ta_IN", "th", "tr", "uk", "ur", "uz_UZ_latin", "vi", "yo_NG", "zh_CN", "zh_TW", "zu_ZA"];
+//#endregion
+//#region src/types.d.ts
+interface ConfigRegistry {}
+/**
+ * Map of known environment variables to their (coerced) value types.
+ *
+ * Used to give {@link GlobalEnv | env()} precise return types. Unknown keys fall
+ * back to `string`. Augment this interface (declaration merging) to register
+ * application-specific variables:
+ *
+ * ```ts
+ * declare module '@arkstack/common' {
+ *   interface EnvRegistry { MY_FLAG: boolean }
+ * }
+ * ```
+ */
+interface EnvRegistry {
+  APP_NAME: string;
+  APP_ENV: 'development' | 'production' | 'staging' | 'local';
+  APP_KEY: string;
+  APP_URL: string;
+  APP_HOST: string;
+  APP_PORT: number;
+  APP_DEBUG: boolean;
+  APP_TIMEZONE: string;
+  APP_LOCALE: typeof locales[number];
+  APP_FALLBACK_LOCALE: typeof locales[number];
+  APP_FAKER_LOCALE: typeof locales[number];
+  NODE_ENV: 'development' | 'production' | 'test';
+  PORT: number;
+  HOST: string;
+  FRONTEND_URL: string;
+  OUTPUT_DIR: string;
+  OUTPUT_DIR_DEV: string;
+  CONFIG_PATH: string;
+  TUNNEL: boolean;
+  NGROK_AUTHTOKEN: string;
+  NGROK_DOMAIN: string;
+  FILESYSTEM_DISK: string;
+  CACHE_STORE: string;
+  CACHE_PREFIX: string;
+  CACHE_TABLE: string;
+  QUEUE_CONNECTION: string;
+  QUEUE_TABLE: string;
+  QUEUE_NAME: string;
+  QUEUE_RETRY_AFTER: number;
+  REDIS_HOST: string;
+  REDIS_PORT: number;
+  REDIS_PASSWORD: string;
+  REDIS_CACHE_DB: number;
+  REDIS_QUEUE_DB: number;
+  JWT_EXPIRES_IN: string;
+  SESSION_LIFETIME: number;
+  TWO_FACTOR_SMS_TTL_MINUTES: number;
+  DATABASE_URL: string;
+  DB_CONNECTION: string;
+  DB_HOST: string;
+  DB_PORT: number;
+  DB_DATABASE: string;
+  DB_USERNAME: string;
+  DB_PASSWORD: string;
+  MAIL_HOST: string;
+  MAIL_PORT: number;
+  MAIL_SECURE: boolean;
+  MAIL_USERNAME: string;
+  MAIL_PASSWORD: string;
+  MAIL_FROM_ADDRESS: string;
+  MAIL_TEST_ADDRESS: string;
+  AWS_ACCESS_KEY_ID: string;
+  AWS_SECRET_ACCESS_KEY: string;
+  AWS_DEFAULT_REGION: string;
+  AWS_BUCKET: string;
+  AWS_URL: string;
+  AWS_ENDPOINT: string;
+}
+/**
+ * App Confifuration
+ */
+interface AppConfig {
+  [key: string]: any;
+  env: string;
+  key: string;
+  url: string;
+  host: string;
+  name: string;
+  frontend_url: string;
+  debug: boolean;
+  timezone: string;
+  locale: typeof locales[number];
+  fallback_locale: typeof locales[number];
+  faker_locale: typeof locales[number];
+}
+/**
+ * Known environment variable names.
+ */
+type EnvKey = keyof EnvRegistry & string;
+/** The registered type for a known key, or `string` for an unknown one. */
+type EnvLookup<K extends string> = [K] extends [EnvKey] ? EnvRegistry[K] : string;
+type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never;
+type MergedConfig<X> = UnionToIntersection<X>;
+type Primitive = string | number | boolean | null | undefined | Function;
+type LoggerChalk = keyof ChalkInstance | ChalkInstance | (keyof ChalkInstance)[];
+type LoggerParseSignature = [string, LoggerChalk][];
+type DotPathValue<T, P extends string> = P extends `${infer Head}.${infer Tail}` ? Head extends keyof T ? DotPathValue<T[Head], Tail> : never : P extends keyof T ? T[P] : never;
+type DotPath<T> = T extends Primitive ? never : T extends any[] ? never : { [K in keyof T & string]: T[K] extends Primitive ? `${K}` : T[K] extends any[] ? `${K}` : `${K}` | `${K}.${DotPath<T[K]>}` }[keyof T & string];
+/**
+ * Ouput formater object or format the output
+ *
+ * @param config
+ * @param joiner
+ * @param log If set to false, string output will be returned and not logged
+ * @param sc color to use ue on split text if : is found
+ *
+ * @returns
+ */
+interface LoggerLog {
+  (): typeof Logger;
+  <L extends boolean>(config: string, joiner: LoggerChalk, log?: L, sc?: LoggerChalk): L extends true ? void : string;
+  <L extends boolean>(config: LoggerParseSignature, joiner?: string, log?: L, sc?: LoggerChalk): L extends true ? void : string;
+  <L extends boolean>(config?: LoggerParseSignature, joiner?: string, log?: L, sc?: LoggerChalk): L extends true ? void : string | Logger;
+}
+/**
+ * Return type of {@link GlobalEnv | env()}.
+ *
+ * When an explicit value type `X` is given it wins (backward compatible with
+ * `env<boolean>('FLAG')`). Otherwise the type registered for the key `K` is used
+ * — falling back to `string` for unknown keys. A provided default `D` is unioned
+ * into the result.
+ */
+type EnvReturn<X, K extends string, D> = [X] extends [never] ? [D] extends [undefined] ? EnvLookup<K> : EnvLookup<K> | D : [D] extends [undefined] ? X : X | D;
+interface GlobalEnv {
+  <X = never, D = undefined, K extends (keyof EnvRegistry | (string & {})) = keyof EnvRegistry>(env: K, defaultValue?: D): EnvReturn<X, K, D>;
+}
+type ConfigShape = keyof ConfigRegistry extends never ? Record<string, any> : ConfigRegistry;
+interface GlobalConfig {
+  <X extends ConfigShape>(): X;
+  <X extends ConfigShape, P extends DotPath<X>>(key: P): DotPathValue<X, P>;
+  <X extends ConfigShape, P extends DotPath<X>>(key: Record<P, Partial<DotPathValue<X, P>>>): void;
+  <X extends ConfigShape, P extends DotPath<X>, D>(key: P, defaultValue: D): DotPathValue<X, P> | D;
+}
+interface FileImporter {
+  <T = unknown>(filePath: string): Promise<T>;
+  <T = unknown>(filePath: string, userOptions?: JitiOptions | undefined): Promise<T>;
+  <T = unknown>(filePath: string, userOptions?: JitiOptions | undefined, resolveOptions?: (JitiResolveOptions & {
+    default?: true;
+  })): Promise<T>;
+}
+type ArkstackErrorShape = Error & {
+  cause?: unknown;
+  code?: number | string;
+  errors?: unknown;
+  getModelName?: () => string;
+  status?: number;
+  statusCode?: number; /** Custom properties merged into the error response payload. */
+  body?: Record<string, unknown>;
+};
+interface ArkstackErrorPayload {
+  status: 'error';
+  code: number;
+  message: string;
+  errors?: unknown;
+  stack?: string;
+  /** Custom fields contributed by an exception's `body`. */
+  [key: string]: unknown;
+}
+interface HookRegistry {}
+type Position = 'before' | 'after' | (string & {});
+type IHook = { [P in Position]?: (...args: any[]) => void };
+type HookName = keyof HookRegistry extends never ? string : keyof HookRegistry | (string & {});
+type HookFor<N extends string> = N extends keyof HookRegistry ? HookRegistry[N] : IHook;
+type HookPos<N extends string, P extends string> = N extends keyof HookRegistry ? P extends keyof HookRegistry[N] ? HookRegistry[N][P] : (...args: any[]) => void : (...args: any[]) => void;
+type HookPositions<N extends string> = N extends keyof HookRegistry ? keyof HookRegistry[N] : Position;
+type HookArgs<N extends string, P extends string> = N extends keyof HookRegistry ? P extends keyof HookRegistry[N] ? HookRegistry[N][P] extends ((...args: infer A) => any) ? A : any[] : any[] : any[];
+type Choice<Value> = {
+  value: Value;
+  name?: string;
+  description?: string;
+  short?: string;
+  disabled?: boolean | string;
+  type?: never;
+};
+type Choices = readonly string[] | readonly Choice<string>[];
+type PaginationOptions = {
+  page: number;
+  perPage: number;
+};
+/**
+* A single source → destination mapping a package wants to publish into the
+* consuming application.
+*/
+interface PublishEntry {
+  /** Absolute path to the file or directory shipped by the package. */
+  from: string;
+  /**
+   * Destination path, relative to the application root, where the artifact is
+   * written when published.
+   */
+  to: string;
+}
+/**
+ * A group of publishable artifacts registered by a package.
+ */
+interface PublishGroup {
+  /**
+   * The package registering the artifacts, e.g. `@arkstack/cache`.
+   */
+  package: string;
+  /**
+   * Optional tag for selective publishing (`ark publish --tag <tag>`). A
+   * package may register several groups under different tags.
+   */
+  tag?: string;
+  /** The files/directories to publish. */
+  entries: PublishEntry[];
+}
+/** Optional filter applied when reading the registry. */
+interface PublishFilter {
+  package?: string;
+  tag?: string;
+}
+/** Optional filter applied when reading the registry. */
+interface PublishConfirmation {
+  /**
+   * The package registering the confirmation, e.g. `@arkstack/cache`.
+   */
+  package: string;
+  /**
+   * A message describing what the confirmation is
+   * for, e.g. "Are you sure you want to publish the cache migrations?"
+   */
+  message: string;
+  /**
+   * Options to choose from.
+   */
+  options: Choices;
+  /**
+   * A callback function to handle the selected choice and the stub file.
+   *
+   * @param choice
+   * @param stub
+   * @returns
+   */
+  callback?: (choice: Choice<string>['value'], stub: string) => string | Promise<string>;
+}
+//#endregion
+//#region src/utils/encryption.d.ts
+declare class Encryption {
+  private static readonly algorithm;
+  private static getKey;
+  static encrypt(value: string): string;
+  static decrypt(payload: string): string;
+}
+//#endregion
+//#region src/utils/hash.d.ts
+declare class Hash {
+  /**
+   * Hash a value using bcrypt
+   *
+   * @param value
+   * @returns
+   */
+  static make(value: string): Promise<string>;
+  /**
+   * Verify a value against a hashed value
+   *
+   * @param value
+   * @param hashedValue
+   * @returns
+   */
+  static verify(value: string, hashedValue: string): Promise<boolean>;
+  /**
+   * Generate a one-time password (OTP) using TOTP algorithm
+   *
+   * @param digits    The number of digits for the OTP, default is 6.
+   * @param label     A label to identify the OTP, can be an email or phone number.
+   * @param period    Interval of time for which a token is valid, in seconds.
+   * @returns
+   */
+  static otp(digits?: number, label?: string, period?: number): TOTP;
+  static totp(secret: string, label: string, issuer?: string, period?: number): TOTP;
+}
+//#endregion
+//#region src/utils/helpers.d.ts
+type AbstractModelConstructor<TModel = unknown> = abstract new (attributes?: Record<string, unknown>) => TModel;
+type ModelConstructor<TModel extends Model = Model> = AbstractModelConstructor<TModel> & Pick<ModelStatic<TModel>, keyof ModelStatic<TModel>>;
+interface ModelRegistry {}
+type ModelName = Extract<keyof ModelRegistry, string>;
+/**
+ * Checks and asserts if target is a class
+ *
+ * @param target
+ * @returns
+ */
+declare const isClass: <T = unknown>(target: unknown) => target is new (...args: any[]) => T;
+declare const normalizePositiveInteger: (value: unknown, fallback: number) => number;
+/**
+ * Extracts a safe pagination limit from a query object.
+ *
+ * @param query
+ * @param defaults
+ * @default const defaults = { pageSize: 25, maxPageSize: 50 }
+ * @returns
+ */
+declare const perPage: (query: {
+  limit?: number;
+  perPage?: number;
+  per_page?: number;
+  "per-page"?: number;
+}, defaults?: {
+  perPage?: number;
+  maxPerPage?: number;
+}) => number;
+/**
+ * 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
+ */
+declare const resolvePagination: (query: {
+  page?: number;
+  limit?: number;
+  perPage?: number;
+  per_page?: number;
+  "per-page"?: number;
+}, defaults?: {
+  page?: number;
+  perPage?: number;
+  maxPerPage?: number;
+}) => PaginationOptions;
+/**
+ * Import an application model by name.
+ *
+ * Apps can augment `ModelRegistry` to make `getModel('User')` return `typeof User`.
+ * Without a registry entry, pass the class type explicitly: `getModel<typeof User>('User')`.
+ *
+ * @param modelName
+ */
+declare function getModel<TName extends ModelName>(modelName: TName): Promise<ModelRegistry[TName]>;
+declare function getModel<TModel extends AbstractModelConstructor = ModelConstructor>(modelName: string): Promise<TModel>;
+/**
+ * Synchronously import an application model by name.
+ *
+ * Apps can augment `ModelRegistry` to make `getModel('User')` return `typeof User`.
+ * Without a registry entry, pass the class type explicitly: `getModel<typeof User>('User')`.
+ *
+ * @param modelName
+ */
+declare function getModelSync<TName extends ModelName>(modelName: TName): ModelRegistry[TName];
+declare function getModelSync<TModel extends AbstractModelConstructor = ModelConstructor>(modelName: string): TModel;
+declare const initializeGlobalContext: ({
+  Request,
+  Response,
+  Session
+}?: {
+  Request?: any;
+  Response?: any;
+  Session?: any;
+}) => Promise<void>;
+/**
+ * Thows to abort the current request
+ *
+ * @param message
+ * @param code
+ * @throws {RequestException}
+ */
+declare const abort: (message?: string, code?: number) => void;
+/**
+ * Asserts that a boolean condition is true.
+ *
+ * @param boolean
+ * @param message
+ * @param code
+ * @throws {RequestException} Throws if the boolean condition is true.
+ */
+declare const abortIf: <T>(boolean: T, message?: string, code?: number) => asserts boolean is T;
+/**
+ * Asserts that a value is not null or undefined.
+ *
+ * @param value
+ * @param message
+ * @param code
+ * @throws {RequestException} Throws if the value is null or undefined.
+ */
+declare const assertFound: <T>(value: T | null | undefined, message: string, code?: number) => asserts value is T;
+//#endregion
+export { GlobalConfig as A, LoggerLog as B, DotPath as C, EnvRegistry as D, EnvLookup as E, HookPos as F, PublishConfirmation as G, MergedConfig as H, HookPositions as I, PublishGroup as J, PublishEntry as K, HookRegistry as L, HookArgs as M, HookFor as N, EnvReturn as O, HookName as P, IHook as R, ConfigShape as S, EnvKey as T, PaginationOptions as U, LoggerParseSignature as V, Primitive as W, Logger as X, UnionToIntersection as Y, ArkstackErrorPayload as _, abortIf as a, Choices as b, getModelSync as c, normalizePositiveInteger as d, perPage as f, AppConfig as g, Encryption as h, abort as i, GlobalEnv as j, FileImporter as k, initializeGlobalContext as l, Hash as m, ModelConstructor as n, assertFound as o, resolvePagination as p, PublishFilter as q, ModelRegistry as r, getModel as s, AbstractModelConstructor as t, isClass as u, ArkstackErrorShape as v, DotPathValue as w, ConfigRegistry as x, Choice as y, LoggerChalk as z };

package/dist/index.d.ts

@@ -1,9 +1,7 @@
 /// <reference path="./app.d.ts" />
-import { a as abortIf, c as getModelSync, d as perPage, f as Hash, i as abort, l as initializeGlobalContext, n as ModelConstructor, o as assertFound, p as Encryption, r as ModelRegistry, s as getModel, t as AbstractModelConstructor, u as isClass } from "./helpers-Bn6dk-9j.js";
-import { JitiOptions, JitiResolveOptions } from "jiti";
+import { A as GlobalConfig, B as LoggerLog, C as DotPath, D as EnvRegistry, E as EnvLookup, F as HookPos, G as PublishConfirmation, H as MergedConfig, I as HookPositions, J as PublishGroup, K as PublishEntry, L as HookRegistry, M as HookArgs, N as HookFor, O as EnvReturn, P as HookName, R as IHook, S as ConfigShape, T as EnvKey, U as PaginationOptions, V as LoggerParseSignature, W as Primitive, X as Logger, Y as UnionToIntersection, _ as ArkstackErrorPayload, a as abortIf, b as Choices, c as getModelSync, d as normalizePositiveInteger, f as perPage, g as AppConfig, h as Encryption, i as abort, j as GlobalEnv, k as FileImporter, l as initializeGlobalContext, m as Hash, n as ModelConstructor, o as assertFound, p as resolvePagination, q as PublishFilter, r as ModelRegistry, s as getModel, t as AbstractModelConstructor, u as isClass, v as ArkstackErrorShape, w as DotPathValue, x as ConfigRegistry, y as Choice, z as LoggerChalk } from "./helpers-CC35u6ti.js";
 import { Arkstack } from "@arkstack/contract";
 import pino from "pino";
-import { ChalkInstance } from "chalk";
 
 //#region src/lifecycle.d.ts
 declare const bindGracefulShutdown: (shutdown: () => Promise<void> | void, defer?: boolean) => void;
@@ -34,385 +32,6 @@ declare const renderError: ({
 //#region src/prototypes.d.ts
 declare const loadPrototypes: () => void;
 //#endregion
-//#region src/Logger.d.ts
-declare class Console {
-  static log: (...args: any[]) => string | void;
-  static debug: (...args: any[]) => void;
-  static warn: (...args: any[]) => void[];
-  static info: (...args: any[]) => void[];
-  static error: (...args: any[]) => void[];
-}
-declare class Logger {
-  /**
-   * Global verbosity configuration
-   */
-  private static verbosity;
-  private static isQuiet;
-  private static isSilent;
-  /**
-   * Configure global verbosity levels
-   */
-  static configure(options?: {
-    verbosity?: number;
-    quiet?: boolean;
-    silent?: boolean;
-  }): void;
-  /**
-   * Check if output should be suppressed
-   */
-  private static shouldSuppressOutput;
-  /**
-   * Logs the message in two columns
-   *
-   * @param name
-   * @param value
-   * @param log If set to false, array of [name, dots, value] output will be returned and not logged
-   * @returns
-   */
-  static twoColumnDetail(name: string, value: string, log?: true, spacer?: string): void;
-  static twoColumnDetail(name: string, value: string, log?: false, spacer?: string): [string, string, string];
-  /**
-   * Logs the message in two columns
-   *
-   * @param name
-   * @param desc
-   * @param width
-   * @param log If set to false, array of [name, dots, value] output will be returned and not logged
-   * @returns
-   */
-  static describe(name: string, desc: string, width?: number, log?: true): void;
-  static describe(name: string, desc: string, width?: number, log?: false): [string, string, string];
-  /**
-   * Logs the message in two columns but allways passing status
-   *
-   * @param name
-   * @param value
-   * @param status
-   * @param exit
-   * @param preserveCol
-   */
-  static split(name: string, value: string, status?: 'success' | 'info' | 'error', exit?: boolean, preserveCol?: boolean, spacer?: string): void;
-  /**
-   * Wraps text with chalk
-   *
-   * @param txt
-   * @param color
-   * @param preserveCol
-   * @returns
-   */
-  static textFormat(txt: unknown | unknown[], color: (...text: unknown[]) => string, preserveCol?: boolean): string;
-  /**
-   * Logs a success message
-   *
-   * @param msg
-   * @param exit
-   * @param preserveCol
-   */
-  static success(msg: any, exit?: boolean, preserveCol?: boolean): void;
-  /**
-   * Logs an informational message
-   *
-   * @param msg
-   * @param exit
-   * @param preserveCol
-   */
-  static info(msg: any, exit?: boolean, preserveCol?: boolean): void;
-  /**
-   * Logs an error message
-   *
-   * @param msg
-   * @param exit
-   * @param preserveCol
-   */
-  static error(msg: any, exit?: boolean, preserveCol?: boolean): void;
-  /**
-   * Logs a warning message
-   *
-   * @param msg
-   * @param exit
-   * @param preserveCol
-   */
-  static warn(msg: any, exit?: boolean, preserveCol?: boolean): void;
-  /**
-   * Logs a debug message (only shown with verbosity >= 3)
-   *
-   * @param msg
-   * @param exit
-   * @param preserveCol
-   */
-  static debug<M = any>(msg: M | M[], exit?: boolean, preserveCol?: boolean): void;
-  /**
-   * Terminates the process
-   */
-  static quiet(): void;
-  static chalker(styles: LoggerChalk[]): (input: any) => string;
-  /**
-   * Parse an array formated message and logs it
-   *
-   * @param config
-   * @param joiner
-   * @param log If set to false, string output will be returned and not logged
-   * @param sc color to use ue on split text if : is found
-   */
-  static parse(config: LoggerParseSignature, joiner?: string, log?: true, sc?: LoggerChalk): void;
-  static parse(config: LoggerParseSignature, joiner?: string, log?: false, sc?: LoggerChalk): string;
-  /**
-   * Ouput formater object or format the output
-   *
-   * @returns
-   */
-  static log: LoggerLog;
-  /**
-   * A simple console like output logger
-   *
-   * @returns
-   */
-  static console(): typeof Console;
-}
-//#endregion
-//#region src/locales.d.ts
-declare const locales: readonly ["af_ZA", "ar", "az", "bn_BD", "cs_CZ", "cy", "da", "de", "de_AT", "de_CH", "dv", "el", "en", "en_AU", "en_AU_ocker", "en_BORK", "en_CA", "en_GB", "en_GH", "en_HK", "en_IE", "en_IN", "en_NG", "en_US", "en_ZA", "eo", "es", "es_MX", "fa", "fi", "fr", "fr_BE", "fr_CA", "fr_CH", "fr_LU", "fr_SN", "he", "hr", "hu", "hy", "id_ID", "it", "ja", "ka_GE", "ko", "ku_ckb", "ku_kmr_latin", "lv", "mk", "mn_MN_cyrl", "nb_NO", "ne", "nl", "nl_BE", "pl", "pt_BR", "pt_PT", "ro", "ro_MD", "ru", "sk", "sl_SI", "sr_RS_latin", "sv", "ta_IN", "th", "tr", "uk", "ur", "uz_UZ_latin", "vi", "yo_NG", "zh_CN", "zh_TW", "zu_ZA"];
-//#endregion
-//#region src/types.d.ts
-interface ConfigRegistry {}
-/**
- * Map of known environment variables to their (coerced) value types.
- *
- * Used to give {@link GlobalEnv | env()} precise return types. Unknown keys fall
- * back to `string`. Augment this interface (declaration merging) to register
- * application-specific variables:
- *
- * ```ts
- * declare module '@arkstack/common' {
- *   interface EnvRegistry { MY_FLAG: boolean }
- * }
- * ```
- */
-interface EnvRegistry {
-  APP_NAME: string;
-  APP_ENV: 'development' | 'production' | 'staging' | 'local';
-  APP_KEY: string;
-  APP_URL: string;
-  APP_HOST: string;
-  APP_PORT: number;
-  APP_DEBUG: boolean;
-  APP_TIMEZONE: string;
-  APP_LOCALE: typeof locales[number];
-  APP_FALLBACK_LOCALE: typeof locales[number];
-  APP_FAKER_LOCALE: typeof locales[number];
-  NODE_ENV: 'development' | 'production' | 'test';
-  PORT: number;
-  HOST: string;
-  FRONTEND_URL: string;
-  OUTPUT_DIR: string;
-  OUTPUT_DIR_DEV: string;
-  CONFIG_PATH: string;
-  TUNNEL: boolean;
-  NGROK_AUTHTOKEN: string;
-  NGROK_DOMAIN: string;
-  FILESYSTEM_DISK: string;
-  CACHE_STORE: string;
-  CACHE_PREFIX: string;
-  CACHE_TABLE: string;
-  QUEUE_CONNECTION: string;
-  QUEUE_TABLE: string;
-  QUEUE_NAME: string;
-  QUEUE_RETRY_AFTER: number;
-  REDIS_HOST: string;
-  REDIS_PORT: number;
-  REDIS_PASSWORD: string;
-  REDIS_CACHE_DB: number;
-  REDIS_QUEUE_DB: number;
-  JWT_EXPIRES_IN: string;
-  SESSION_LIFETIME: number;
-  TWO_FACTOR_SMS_TTL_MINUTES: number;
-  DATABASE_URL: string;
-  DB_CONNECTION: string;
-  DB_HOST: string;
-  DB_PORT: number;
-  DB_DATABASE: string;
-  DB_USERNAME: string;
-  DB_PASSWORD: string;
-  MAIL_HOST: string;
-  MAIL_PORT: number;
-  MAIL_SECURE: boolean;
-  MAIL_USERNAME: string;
-  MAIL_PASSWORD: string;
-  MAIL_FROM_ADDRESS: string;
-  MAIL_TEST_ADDRESS: string;
-  AWS_ACCESS_KEY_ID: string;
-  AWS_SECRET_ACCESS_KEY: string;
-  AWS_DEFAULT_REGION: string;
-  AWS_BUCKET: string;
-  AWS_URL: string;
-  AWS_ENDPOINT: string;
-}
-/**
- * App Confifuration
- */
-interface AppConfig {
-  [key: string]: any;
-  env: string;
-  key: string;
-  url: string;
-  host: string;
-  name: string;
-  frontend_url: string;
-  debug: boolean;
-  timezone: string;
-  locale: typeof locales[number];
-  fallback_locale: typeof locales[number];
-  faker_locale: typeof locales[number];
-}
-/**
- * Known environment variable names.
- */
-type EnvKey = keyof EnvRegistry & string;
-/** The registered type for a known key, or `string` for an unknown one. */
-type EnvLookup<K extends string> = [K] extends [EnvKey] ? EnvRegistry[K] : string;
-type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never;
-type MergedConfig<X> = UnionToIntersection<X>;
-type Primitive = string | number | boolean | null | undefined | Function;
-type LoggerChalk = keyof ChalkInstance | ChalkInstance | (keyof ChalkInstance)[];
-type LoggerParseSignature = [string, LoggerChalk][];
-type DotPathValue<T, P extends string> = P extends `${infer Head}.${infer Tail}` ? Head extends keyof T ? DotPathValue<T[Head], Tail> : never : P extends keyof T ? T[P] : never;
-type DotPath<T> = T extends Primitive ? never : T extends any[] ? never : { [K in keyof T & string]: T[K] extends Primitive ? `${K}` : T[K] extends any[] ? `${K}` : `${K}` | `${K}.${DotPath<T[K]>}` }[keyof T & string];
-/**
- * Ouput formater object or format the output
- *
- * @param config
- * @param joiner
- * @param log If set to false, string output will be returned and not logged
- * @param sc color to use ue on split text if : is found
- *
- * @returns
- */
-interface LoggerLog {
-  (): typeof Logger;
-  <L extends boolean>(config: string, joiner: LoggerChalk, log?: L, sc?: LoggerChalk): L extends true ? void : string;
-  <L extends boolean>(config: LoggerParseSignature, joiner?: string, log?: L, sc?: LoggerChalk): L extends true ? void : string;
-  <L extends boolean>(config?: LoggerParseSignature, joiner?: string, log?: L, sc?: LoggerChalk): L extends true ? void : string | Logger;
-}
-/**
- * Return type of {@link GlobalEnv | env()}.
- *
- * When an explicit value type `X` is given it wins (backward compatible with
- * `env<boolean>('FLAG')`). Otherwise the type registered for the key `K` is used
- * — falling back to `string` for unknown keys. A provided default `D` is unioned
- * into the result.
- */
-type EnvReturn<X, K extends string, D> = [X] extends [never] ? [D] extends [undefined] ? EnvLookup<K> : EnvLookup<K> | D : [D] extends [undefined] ? X : X | D;
-interface GlobalEnv {
-  <X = never, D = undefined, K extends (keyof EnvRegistry | (string & {})) = keyof EnvRegistry>(env: K, defaultValue?: D): EnvReturn<X, K, D>;
-}
-type ConfigShape = keyof ConfigRegistry extends never ? Record<string, any> : ConfigRegistry;
-interface GlobalConfig {
-  <X extends ConfigShape>(): X;
-  <X extends ConfigShape, P extends DotPath<X>>(key: P): DotPathValue<X, P>;
-  <X extends ConfigShape, P extends DotPath<X>>(key: Record<P, Partial<DotPathValue<X, P>>>): void;
-  <X extends ConfigShape, P extends DotPath<X>, D>(key: P, defaultValue: D): DotPathValue<X, P> | D;
-}
-interface FileImporter {
-  <T = unknown>(filePath: string): Promise<T>;
-  <T = unknown>(filePath: string, userOptions?: JitiOptions | undefined): Promise<T>;
-  <T = unknown>(filePath: string, userOptions?: JitiOptions | undefined, resolveOptions?: (JitiResolveOptions & {
-    default?: true;
-  })): Promise<T>;
-}
-type ArkstackErrorShape = Error & {
-  cause?: unknown;
-  code?: number | string;
-  errors?: unknown;
-  getModelName?: () => string;
-  status?: number;
-  statusCode?: number; /** Custom properties merged into the error response payload. */
-  body?: Record<string, unknown>;
-};
-interface ArkstackErrorPayload {
-  status: 'error';
-  code: number;
-  message: string;
-  errors?: unknown;
-  stack?: string;
-  /** Custom fields contributed by an exception's `body`. */
-  [key: string]: unknown;
-}
-interface HookRegistry {}
-type Position = 'before' | 'after' | (string & {});
-type IHook = { [P in Position]?: (...args: any[]) => void };
-type HookName = keyof HookRegistry extends never ? string : keyof HookRegistry | (string & {});
-type HookFor<N extends string> = N extends keyof HookRegistry ? HookRegistry[N] : IHook;
-type HookPos<N extends string, P extends string> = N extends keyof HookRegistry ? P extends keyof HookRegistry[N] ? HookRegistry[N][P] : (...args: any[]) => void : (...args: any[]) => void;
-type HookPositions<N extends string> = N extends keyof HookRegistry ? keyof HookRegistry[N] : Position;
-type HookArgs<N extends string, P extends string> = N extends keyof HookRegistry ? P extends keyof HookRegistry[N] ? HookRegistry[N][P] extends ((...args: infer A) => any) ? A : any[] : any[] : any[];
-type Choice<Value> = {
-  value: Value;
-  name?: string;
-  description?: string;
-  short?: string;
-  disabled?: boolean | string;
-  type?: never;
-};
-type Choices = readonly string[] | readonly Choice<string>[];
-/**
-* A single source → destination mapping a package wants to publish into the
-* consuming application.
-*/
-interface PublishEntry {
-  /** Absolute path to the file or directory shipped by the package. */
-  from: string;
-  /**
-   * Destination path, relative to the application root, where the artifact is
-   * written when published.
-   */
-  to: string;
-}
-/**
- * A group of publishable artifacts registered by a package.
- */
-interface PublishGroup {
-  /**
-   * The package registering the artifacts, e.g. `@arkstack/cache`.
-   */
-  package: string;
-  /**
-   * Optional tag for selective publishing (`ark publish --tag <tag>`). A
-   * package may register several groups under different tags.
-   */
-  tag?: string;
-  /** The files/directories to publish. */
-  entries: PublishEntry[];
-}
-/** Optional filter applied when reading the registry. */
-interface PublishFilter {
-  package?: string;
-  tag?: string;
-}
-/** Optional filter applied when reading the registry. */
-interface PublishConfirmation {
-  /**
-   * The package registering the confirmation, e.g. `@arkstack/cache`.
-   */
-  package: string;
-  /**
-   * A message describing what the confirmation is
-   * for, e.g. "Are you sure you want to publish the cache migrations?"
-   */
-  message: string;
-  /**
-   * Options to choose from.
-   */
-  options: Choices;
-  /**
-   * A callback function to handle the selected choice and the stub file.
-   *
-   * @param choice
-   * @param stub
-   * @returns
-   */
-  callback?: (choice: Choice<string>['value'], stub: string) => string | Promise<string>;
-}
-//#endregion
 //#region src/system.d.ts
 /**
  * Read the .env file
@@ -870,4 +489,4 @@ declare const devTlsCredentials: (host?: string) => Promise<TlsCredentials>;
  */
 declare const localNetworkAddress: () => string | undefined;
 //#endregion
-export { AbstractModelConstructor, AppConfig, AppException, ArkstackErrorPayload, ArkstackErrorShape, CONFIG_KEY, Choice, Choices, ConfigLoader, ConfigRegistry, ConfigShape, DotPath, DotPathValue, Encryption, EnvKey, EnvLoader, EnvLookup, EnvRegistry, EnvReturn, ErrorHandler, Exception, FileImporter, GlobalConfig, GlobalEnv, Hash, Hook, HookArgs, HookFor, HookName, HookPos, HookPositions, HookRegistry, IHook, Logger, LoggerChalk, LoggerLog, LoggerParseSignature, MergedConfig, ModelConstructor, ModelRegistry, Primitive, PublishConfirmation, PublishEntry, PublishFilter, PublishGroup, Publisher, RequestException, TlsCredentials, UnionToIntersection, abort, abortIf, appKey, appUrl, assertFound, bindGracefulShutdown, bootWithDetectedPort, config, configLoader, createErrorPayload, devTlsCredentials, discoverCommands, env, envLoader, getErrorLogger, getModel, getModelSync, getPrimaryError, getValidationErrors, importFile, initializeGlobalContext, interopDefault, isClass, isModelNotFoundError, isValidationError, loadPrototypes, localNetworkAddress, logUnhandledError, nodeEnv, normalizeStatusCode, outputDir, perPage, rebuildOutput, renderError, resolveRuntimeDir, resolveRuntimeModule, serializeError, shouldHideStack, shouldLogError, toErrorShape, toOutputPath };
+export { AbstractModelConstructor, AppConfig, AppException, ArkstackErrorPayload, ArkstackErrorShape, CONFIG_KEY, Choice, Choices, ConfigLoader, ConfigRegistry, ConfigShape, DotPath, DotPathValue, Encryption, EnvKey, EnvLoader, EnvLookup, EnvRegistry, EnvReturn, ErrorHandler, Exception, FileImporter, GlobalConfig, GlobalEnv, Hash, Hook, HookArgs, HookFor, HookName, HookPos, HookPositions, HookRegistry, IHook, Logger, LoggerChalk, LoggerLog, LoggerParseSignature, MergedConfig, ModelConstructor, ModelRegistry, PaginationOptions, Primitive, PublishConfirmation, PublishEntry, PublishFilter, PublishGroup, Publisher, RequestException, TlsCredentials, UnionToIntersection, abort, abortIf, appKey, appUrl, assertFound, bindGracefulShutdown, bootWithDetectedPort, config, configLoader, createErrorPayload, devTlsCredentials, discoverCommands, env, envLoader, getErrorLogger, getModel, getModelSync, getPrimaryError, getValidationErrors, importFile, initializeGlobalContext, interopDefault, isClass, isModelNotFoundError, isValidationError, loadPrototypes, localNetworkAddress, logUnhandledError, nodeEnv, normalizePositiveInteger, normalizeStatusCode, outputDir, perPage, rebuildOutput, renderError, resolvePagination, resolveRuntimeDir, resolveRuntimeModule, serializeError, shouldHideStack, shouldLogError, toErrorShape, toOutputPath };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { _ as EnvLoader, a as env, c as nodeEnv, d as resolveRuntimeDir, f as resolveRuntimeModule, g as configLoader, h as ConfigLoader, i as discoverCommands, l as outputDir, m as CONFIG_KEY, n as appUrl, o as importFile, p as toOutputPath, r as config, s as interopDefault, t as appKey, u as rebuildOutput, v as envLoader } from "./system-XvUhJFS0.js";
-import { _ as Exception, c as abortIf, d as getModelSync, f as initializeGlobalContext, g as AppException, h as RequestException, l as assertFound, m as perPage, p as isClass, s as abort, u as getModel, v as Hash, y as Encryption } from "./utils-C3mcZZMN.js";
+import { _ as RequestException, b as Hash, c as abortIf, d as getModelSync, f as initializeGlobalContext, g as resolvePagination, h as perPage, l as assertFound, m as normalizePositiveInteger, p as isClass, s as abort, u as getModel, v as AppException, x as Encryption, y as Exception } from "./utils-CaaL-9im.js";
 import { Hook as Hook$1 } from "@arkstack/foundry";
 import { Arkstack } from "@arkstack/contract";
 import { str } from "@h3ravel/support";
@@ -599,4 +599,4 @@ const localNetworkAddress = () => {
 	for (const list of Object.values(networkInterfaces())) for (const net of list ?? []) if (net.family === "IPv4" && !net.internal) return net.address;
 };
 //#endregion
-export { AppException, CONFIG_KEY, ConfigLoader, Encryption, EnvLoader, ErrorHandler, Exception, Hash, Hook, Logger, Publisher, RequestException, abort, abortIf, appKey, appUrl, assertFound, bindGracefulShutdown, bootWithDetectedPort, config, configLoader, createErrorPayload, devTlsCredentials, discoverCommands, env, envLoader, getErrorLogger, getModel, getModelSync, getPrimaryError, getValidationErrors, importFile, initializeGlobalContext, interopDefault, isClass, isModelNotFoundError, isValidationError, loadPrototypes, localNetworkAddress, logUnhandledError, nodeEnv, normalizeStatusCode, outputDir, perPage, rebuildOutput, renderError, resolveRuntimeDir, resolveRuntimeModule, serializeError, shouldHideStack, shouldLogError, toErrorShape, toOutputPath };
+export { AppException, CONFIG_KEY, ConfigLoader, Encryption, EnvLoader, ErrorHandler, Exception, Hash, Hook, Logger, Publisher, RequestException, abort, abortIf, appKey, appUrl, assertFound, bindGracefulShutdown, bootWithDetectedPort, config, configLoader, createErrorPayload, devTlsCredentials, discoverCommands, env, envLoader, getErrorLogger, getModel, getModelSync, getPrimaryError, getValidationErrors, importFile, initializeGlobalContext, interopDefault, isClass, isModelNotFoundError, isValidationError, loadPrototypes, localNetworkAddress, logUnhandledError, nodeEnv, normalizePositiveInteger, normalizeStatusCode, outputDir, perPage, rebuildOutput, renderError, resolvePagination, resolveRuntimeDir, resolveRuntimeModule, serializeError, shouldHideStack, shouldLogError, toErrorShape, toOutputPath };

package/dist/utils/index.d.ts

@@ -1,4 +1,4 @@
-import { a as abortIf, c as getModelSync, d as perPage, f as Hash, i as abort, l as initializeGlobalContext, n as ModelConstructor, o as assertFound, p as Encryption, r as ModelRegistry, s as getModel, t as AbstractModelConstructor, u as isClass } from "../helpers-Bn6dk-9j.js";
+import { a as abortIf, c as getModelSync, d as normalizePositiveInteger, f as perPage, h as Encryption, i as abort, l as initializeGlobalContext, m as Hash, n as ModelConstructor, o as assertFound, p as resolvePagination, r as ModelRegistry, s as getModel, t as AbstractModelConstructor, u as isClass } from "../helpers-CC35u6ti.js";
 import { Model } from "arkormx";
 
 //#region src/utils/traits.d.ts
@@ -185,4 +185,4 @@ type Derived<T extends (Trait | TypeFactory<Trait> | Cons)> = T extends TypeFact
  */
 declare function uses<T extends (Trait | TypeFactory<Trait> | Cons)>(instance: unknown, trait: T): instance is Derived<T>;
 //#endregion
-export { AbstractModelConstructor, Derived, Encryption, Hash, ModelConstructor, ModelRegistry, Trait, abort, abortIf, assertFound, callTraitMethods, crc32, getModel, getModelSync, getTraitMethods, initializeGlobalContext, isClass, perPage, trait, use, uses };
+export { AbstractModelConstructor, Derived, Encryption, Hash, ModelConstructor, ModelRegistry, Trait, abort, abortIf, assertFound, callTraitMethods, crc32, getModel, getModelSync, getTraitMethods, initializeGlobalContext, isClass, normalizePositiveInteger, perPage, resolvePagination, trait, use, uses };

package/dist/utils/index.js

@@ -1,2 +1,2 @@
-import { a as use, c as abortIf, d as getModelSync, f as initializeGlobalContext, i as trait, l as assertFound, m as perPage, n as crc32, o as uses, p as isClass, r as getTraitMethods, s as abort, t as callTraitMethods, u as getModel, v as Hash, y as Encryption } from "../utils-C3mcZZMN.js";
-export { Encryption, Hash, abort, abortIf, assertFound, callTraitMethods, crc32, getModel, getModelSync, getTraitMethods, initializeGlobalContext, isClass, perPage, trait, use, uses };
+import { a as use, b as Hash, c as abortIf, d as getModelSync, f as initializeGlobalContext, g as resolvePagination, h as perPage, i as trait, l as assertFound, m as normalizePositiveInteger, n as crc32, o as uses, p as isClass, r as getTraitMethods, s as abort, t as callTraitMethods, u as getModel, x as Encryption } from "../utils-CaaL-9im.js";
+export { Encryption, Hash, abort, abortIf, assertFound, callTraitMethods, crc32, getModel, getModelSync, getTraitMethods, initializeGlobalContext, isClass, normalizePositiveInteger, perPage, resolvePagination, trait, use, uses };

package/dist/{utils-C3mcZZMN.js → utils-CaaL-9im.js}

@@ -170,15 +170,36 @@ var RequestException = class RequestException extends AppException {
 const isClass = (target) => {
 	return typeof target === "function" && /^class\s/.test(Function.prototype.toString.call(target));
 };
+const normalizePositiveInteger = (value, fallback) => {
+	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 
 */
-const perPage = (query) => {
-	const requestedPerPage = Number(query.limit ?? query.perPage ?? query["per-page"] ?? query.per_page ?? 15);
-	return Number.isFinite(requestedPerPage) && requestedPerPage > 0 ? Math.min(requestedPerPage, 50) : 15;
+const perPage = (query, defaults) => {
+	const requestedPerPage = normalizePositiveInteger(query.limit ?? query.perPage ?? query["per-page"] ?? query.per_page, defaults?.perPage ?? 25);
+	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 
+*/
+const resolvePagination = (query, defaults) => {
+	return {
+		page: normalizePositiveInteger(query.page, defaults?.page ?? 1),
+		perPage: perPage(query, defaults)
+	};
 };
 async function getModel(modelName) {
 	const resolveModelExport = (module, modelName) => {
@@ -466,4 +487,4 @@ function uses(instance, trait) {
 	return false;
 }
 //#endregion
-export { Exception as _, use as a, abortIf as c, getModelSync as d, initializeGlobalContext as f, AppException as g, RequestException as h, trait as i, assertFound as l, perPage as m, crc32 as n, uses as o, isClass as p, getTraitMethods as r, abort as s, callTraitMethods as t, getModel as u, Hash as v, Encryption as y };
+export { RequestException as _, use as a, Hash as b, abortIf as c, getModelSync as d, initializeGlobalContext as f, resolvePagination as g, perPage as h, trait as i, assertFound as l, normalizePositiveInteger as m, crc32 as n, uses as o, isClass as p, getTraitMethods as r, abort as s, callTraitMethods as t, getModel as u, AppException as v, Encryption as x, Exception as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/common",
-  "version": "0.17.11",
+  "version": "0.17.13",
   "type": "module",
   "description": "Core utilities, primitives, and shared infrastructure for the Arkstack ecosystem.",
   "homepage": "https://arkstack.toneflix.net",
@@ -47,8 +47,8 @@
   "peerDependencies": {
     "@h3ravel/support": "^2.2.4",
     "arkormx": "^2.12.0",
-    "@arkstack/contract": "^0.17.11",
-    "@arkstack/foundry": "^0.17.11"
+    "@arkstack/contract": "^0.17.13",
+    "@arkstack/foundry": "^0.17.13"
   },
   "optionalDependencies": {
     "@faker-js/faker": "^10.4.0"

package/dist/helpers-Bn6dk-9j.d.ts

@@ -1,121 +0,0 @@
-import { TOTP } from "otpauth";
-import { Model, ModelStatic } from "arkormx";
-
-//#region src/utils/encryption.d.ts
-declare class Encryption {
-  private static readonly algorithm;
-  private static getKey;
-  static encrypt(value: string): string;
-  static decrypt(payload: string): string;
-}
-//#endregion
-//#region src/utils/hash.d.ts
-declare class Hash {
-  /**
-   * Hash a value using bcrypt
-   *
-   * @param value
-   * @returns
-   */
-  static make(value: string): Promise<string>;
-  /**
-   * Verify a value against a hashed value
-   *
-   * @param value
-   * @param hashedValue
-   * @returns
-   */
-  static verify(value: string, hashedValue: string): Promise<boolean>;
-  /**
-   * Generate a one-time password (OTP) using TOTP algorithm
-   *
-   * @param digits    The number of digits for the OTP, default is 6.
-   * @param label     A label to identify the OTP, can be an email or phone number.
-   * @param period    Interval of time for which a token is valid, in seconds.
-   * @returns
-   */
-  static otp(digits?: number, label?: string, period?: number): TOTP;
-  static totp(secret: string, label: string, issuer?: string, period?: number): TOTP;
-}
-//#endregion
-//#region src/utils/helpers.d.ts
-type AbstractModelConstructor<TModel = unknown> = abstract new (attributes?: Record<string, unknown>) => TModel;
-type ModelConstructor<TModel extends Model = Model> = AbstractModelConstructor<TModel> & Pick<ModelStatic<TModel>, keyof ModelStatic<TModel>>;
-interface ModelRegistry {}
-type ModelName = Extract<keyof ModelRegistry, string>;
-/**
- * Checks and asserts if target is a class
- *
- * @param target
- * @returns
- */
-declare const isClass: <T = unknown>(target: unknown) => target is new (...args: any[]) => T;
-/**
- * Resolves the number of items to return per page based on the provided query parameters.
- *
- * @param query
- * @returns
- */
-declare const perPage: (query: {
-  limit?: number;
-  perPage?: number;
-  per_page?: number;
-  "per-page"?: number;
-}) => number;
-/**
- * Import an application model by name.
- *
- * Apps can augment `ModelRegistry` to make `getModel('User')` return `typeof User`.
- * Without a registry entry, pass the class type explicitly: `getModel<typeof User>('User')`.
- *
- * @param modelName
- */
-declare function getModel<TName extends ModelName>(modelName: TName): Promise<ModelRegistry[TName]>;
-declare function getModel<TModel extends AbstractModelConstructor = ModelConstructor>(modelName: string): Promise<TModel>;
-/**
- * Synchronously import an application model by name.
- *
- * Apps can augment `ModelRegistry` to make `getModel('User')` return `typeof User`.
- * Without a registry entry, pass the class type explicitly: `getModel<typeof User>('User')`.
- *
- * @param modelName
- */
-declare function getModelSync<TName extends ModelName>(modelName: TName): ModelRegistry[TName];
-declare function getModelSync<TModel extends AbstractModelConstructor = ModelConstructor>(modelName: string): TModel;
-declare const initializeGlobalContext: ({
-  Request,
-  Response,
-  Session
-}?: {
-  Request?: any;
-  Response?: any;
-  Session?: any;
-}) => Promise<void>;
-/**
- * Thows to abort the current request
- *
- * @param message
- * @param code
- * @throws {RequestException}
- */
-declare const abort: (message?: string, code?: number) => void;
-/**
- * Asserts that a boolean condition is true.
- *
- * @param boolean
- * @param message
- * @param code
- * @throws {RequestException} Throws if the boolean condition is true.
- */
-declare const abortIf: <T>(boolean: T, message?: string, code?: number) => asserts boolean is T;
-/**
- * Asserts that a value is not null or undefined.
- *
- * @param value
- * @param message
- * @param code
- * @throws {RequestException} Throws if the value is null or undefined.
- */
-declare const assertFound: <T>(value: T | null | undefined, message: string, code?: number) => asserts value is T;
-//#endregion
-export { abortIf as a, getModelSync as c, perPage as d, Hash as f, abort as i, initializeGlobalContext as l, ModelConstructor as n, assertFound as o, Encryption as p, ModelRegistry as r, getModel as s, AbstractModelConstructor as t, isClass as u };