@freshpointcz/fresh-core 0.0.17 → 0.0.19

package/dist/index.d.mts

@@ -132,6 +132,236 @@ declare class StatusDto {
     constructor(status: Status, details?: string, timestamp?: string);
 }
 
+/**
+ * Pagination parameters used to describe the current page slice of a query.
+ *
+ * Construct this object manually or via {@link getPaginationParams} to ensure
+ * defaults are applied consistently. Pass it into {@link constructTypeormPagination}
+ * when building a TypeORM `findAndCount` call.
+ *
+ * @example
+ * const pagination: PaginationParams = {
+ *   page: 2,
+ *   limit: 25,
+ *   skip: 25, // (page - 1) * limit
+ * };
+ */
+interface PaginationParams {
+    /** 1-based page number. */
+    page: number;
+    /**
+     * Maximum number of items to return in a single page.
+     *
+     * @remarks Do NOT exceed 1000 — large limits can cause memory pressure and
+     * slow queries. Use {@link listAll} for bulk data retrieval instead.
+     */
+    limit: number;
+    /**
+     * Number of records to skip before returning results.
+     *
+     * @remarks Always derived as `(page - 1) * limit`. Do not set this
+     * independently; keep it in sync with `page` and `limit`.
+     */
+    skip: number;
+}
+/**
+ * Merges caller-supplied pagination overrides with {@link DEFAULT_PAGINATION_PARAMS}.
+ *
+ * Use this at the DAO or service layer to normalize an optional `PaginationParams`
+ * argument before passing it to {@link constructTypeormPagination}.
+ *
+ * @param params - Partial pagination parameters to merge. Any omitted fields
+ *   fall back to the defaults defined in {@link DEFAULT_PAGINATION_PARAMS}.
+ * @returns A complete {@link PaginationParams} object with all fields populated.
+ *
+ * @example
+ * // No args — returns the default params
+ * getPaginationParams();
+ * // → { page: 1, limit: 1000, skip: 0 }
+ *
+ * // Partial override — only limit is customized
+ * getPaginationParams({ page: 3, limit: 50, skip: 100 });
+ * // → { page: 3, limit: 50, skip: 100 }
+ */
+declare function getPaginationParams(params?: Partial<PaginationParams>): PaginationParams;
+/**
+ * Default pagination parameters applied when no overrides are provided.
+ *
+ * - `page`: `1` (first page)
+ * - `limit`: `1000` (fetch-all default; suited for internal batch operations)
+ * - `skip`: `0`
+ *
+ * @remarks
+ * This high default limit is intentional for internal/service-layer usage.
+ * Controller layer endpoints should always supply explicit, lower limits
+ * (e.g. 20–100) to avoid returning unbounded result sets to API consumers.
+ *
+ * @see {@link getPaginationParams} for applying these defaults with optional overrides.
+ */
+declare const DEFAULT_PAGINATION_PARAMS: PaginationParams;
+
+/**
+ * Converts {@link PaginationParams} into the `take`/`skip` shape expected by
+ * TypeORM's `find`, `findAndCount`, and `findOne` options.
+ *
+ * @param params - A fully-populated {@link PaginationParams} object (use
+ *   {@link getPaginationParams} to guarantee all fields are set).
+ * @returns An object with `take` and `skip` keys ready to spread into a TypeORM
+ *   `FindManyOptions`.
+ *
+ * @example
+ * const pagination = getPaginationParams({ page: 2, limit: 25, skip: 25 });
+ *
+ * const [data, total] = await repo.findAndCount({
+ *   where: { isActive: true },
+ *   ...constructTypeormPagination(pagination),
+ * });
+ *
+ * @see {@link https://typeorm.io/find-options | TypeORM Find Options}
+ */
+declare function constructTypeormPagination(params: PaginationParams): {
+    take: number;
+    skip: number;
+};
+/**
+ * Parses pagination parameters from a {@link URLSearchParams} instance.
+ *
+ * Intended for use in contexts where query parameters arrive as a raw URL
+ * string (e.g. middleware, edge functions, or fetch-based handlers) rather
+ * than through a framework that deserialises them automatically.
+ *
+ * **Clamping rules applied automatically:**
+ * - `page` is clamped to a minimum of `1`.
+ * - `limit` is clamped between `1` and `100` (inclusive).
+ * - `skip` is derived as `(page - 1) * limit`.
+ *
+ * @param searchParams - A `URLSearchParams` instance, typically obtained from
+ *   `new URL(request.url).searchParams`.
+ * @returns A fully-populated {@link PaginationParams} object.
+ *
+ * @example
+ * const url = new URL("https://api.example.com/items?page=3&limit=50");
+ * const pagination = parsePaginationFromURL(url.searchParams);
+ * // → { page: 3, limit: 50, skip: 100 }
+ *
+ * @example
+ * // Missing params fall back to sensible defaults
+ * const url = new URL("https://api.example.com/items");
+ * const pagination = parsePaginationFromURL(url.searchParams);
+ * // → { page: 1, limit: 20, skip: 0 }
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams | MDN: URLSearchParams}
+ */
+declare function parsePaginationFromURL(searchParams: URLSearchParams): PaginationParams;
+
+/**
+ * Metadata returned alongside a paginated result set.
+ *
+ * Populated automatically by {@link getPaginationMeta}.
+ *
+ * @example
+ * // Example meta for page 2 of 3, 25 items per page, 70 total items:
+ * const meta: PaginationMeta = {
+ *   total: 70,
+ *   page: 2,
+ *   limit: 25,
+ *   totalPages: 3,
+ * };
+ */
+interface PaginationMeta {
+    /** Total number of records across all pages. */
+    total: number;
+    /** Current 1-based page number. */
+    page: number;
+    /** Maximum number of items per page that was requested. */
+    limit: number;
+    /**
+     * Total number of pages available given the current `limit`.
+     *
+     * Computed as `Math.ceil(total / limit)`. Returns `0` when `total` is `0`.
+     */
+    totalPages: number;
+}
+/**
+ * Constructs a {@link PaginationMeta} object from raw query result data.
+ *
+ * Call this after a `findAndCount` (or equivalent) to build the `meta` field
+ * of a {@link PaginatedList} response.
+ *
+ * @param total - Total number of records matching the query (the second element
+ *   returned by TypeORM's `findAndCount`).
+ * @param page - The 1-based page number that was requested.
+ * @param limit - The page size that was requested.
+ * @returns A {@link PaginationMeta} object ready to include in a {@link PaginatedList}.
+ *
+ * @example
+ * const [data, total] = await repo.findAndCount({ take: 25, skip: 25 });
+ *
+ * return {
+ *   data,
+ *   meta: getPaginationMeta(total, 2, 25),
+ *   // → { total: 70, page: 2, limit: 25, totalPages: 3 }
+ * };
+ */
+declare function getPaginationMeta(total: number, page: number, limit: number): PaginationMeta;
+
+/**
+ * A generic wrapper for a single page of query results combined with its
+ * pagination metadata.
+ *
+ * Returned by DAO `findMany` methods and exposed directly from API endpoints.
+ *
+ * @typeParam T - The entity or DTO type contained in the `data` array.
+ *
+ * @example
+ * const result: PaginatedList<UserEntity> = {
+ *   data: [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }],
+ *   meta: { total: 42, page: 1, limit: 20, totalPages: 3 },
+ * };
+ */
+interface PaginatedList<T> {
+    /** The records for the current page. */
+    data: T[];
+    /** Pagination metadata describing the full result set. */
+    meta: PaginationMeta;
+}
+
+/**
+ * Exhaustively fetches all records by iterating through pages until the last
+ * page is reached.
+ *
+ * Use this utility when you need the full result set for an operation that
+ * does not support streaming (e.g. bulk exports, aggregations, seeding).
+ * For large datasets, prefer a streaming or cursor-based approach where possible.
+ *
+ * @typeParam T - The entity or DTO type returned by `fetchPage`.
+ *
+ * @param fetchPage - An async function that accepts a {@link PaginationParams}
+ *   and returns a {@link PaginatedList}. Typically, a bound DAO method.
+ * @param batchSize - Number of records to fetch per page. Defaults to `1000`.
+ *   Do not exceed `1000` to avoid memory pressure.
+ * @returns A promise resolving to a flat array of all matching records.
+ *
+ * @remarks
+ * - Iteration stops when `page >= meta.totalPages`.
+ * - If the underlying data changes during iteration, results may be inconsistent.
+ *   For consistency guarantees, wrap the call in a database transaction.
+ *
+ * @example
+ * // Fetch all active users without worrying about pagination
+ * const allUsers = await listAll(
+ *   (pagination) => userDao.findMany({ where: { isActive: true }, pagination }),
+ * );
+ *
+ * @example
+ * // Use a smaller batch size to reduce memory footprint
+ * const allOrders = await listAll(
+ *   (pagination) => orderDao.findMany({ pagination }),
+ *   200,
+ * );
+ */
+declare function listAll<T>(fetchPage: (pagination: PaginationParams) => Promise<PaginatedList<T>>, batchSize?: number): Promise<T[]>;
+
 declare const AMOUNT_UNIT: {
     readonly 1: {
         readonly symbol: "g";
@@ -404,6 +634,137 @@ declare class Product extends FreshEntity {
 declare class Subcategory extends FreshEntity {
 }
 
+/**
+ * Formats a number to a database-safe decimal string.
+ * @param num - The number to format
+ * @param precision - Total number of significant digits allowed (e.g., 9)
+ * @param scale - Number of digits after the decimal point (e.g., 2)
+ * @returns string formatted for database insertion of decimal type
+ */
+declare function toDecimal(num: number, precision?: number, scale?: number): string;
+/**
+ * Options for {@link isDecimal}.
+ */
+interface IsDecimalOptions {
+    /**
+     * Restrict accepted JavaScript type.
+     *
+     * - `"number"` — only JS `number` values pass (strings are rejected).
+     * - `"string"` — only JS `string` values pass (numbers are rejected).
+     * - omitted — both `number` and `string` are accepted.
+     *
+     * @example
+     * isDecimal("3.14", { allowedType: "number" }); // false — wrong JS type
+     * isDecimal(3.14,   { allowedType: "number" }); // true
+     * isDecimal(3.14,   { allowedType: "string" }); // false — wrong JS type
+     * isDecimal("3.14", { allowedType: "string" }); // true
+     */
+    allowedType?: "number" | "string";
+    /**
+     * The decimal separator character to accept for string values.
+     * Has no effect on `number` inputs (JS numbers always use `.` internally).
+     *
+     * Defaults to `"."`.
+     *
+     * @example
+     * isDecimal("3,14", { decimalPoint: "," }); // true
+     * isDecimal("3.14", { decimalPoint: "," }); // false — wrong separator
+     */
+    decimalPoint?: "." | ",";
+    /**
+     * Maximum total number of significant digits (integer digits + fractional digits combined).
+     *
+     * @example
+     * isDecimal("12345.67", { precision: 7 }); // true  — 5 + 2 = 7 digits
+     * isDecimal("12345.67", { precision: 6 }); // false — 5 + 2 = 7 > 6
+     */
+    precision?: number;
+    /**
+     * Maximum number of digits allowed after the decimal point.
+     *
+     * @example
+     * isDecimal("3.14",  { scale: 2 }); // true
+     * isDecimal("3.145", { scale: 2 }); // false — 3 fractional digits > 2
+     * isDecimal("3",     { scale: 2 }); // true  — 0 fractional digits ≤ 2
+     */
+    scale?: number;
+}
+/**
+ * Narrows `v` to `number` when `allowedType` is `"number"`.
+ * @param v - Value to test.
+ * @param options - Must include `allowedType: "number"`.
+ */
+declare function isDecimal(v: unknown, options: IsDecimalOptions & {
+    allowedType: "number";
+}): v is number;
+/**
+ * Narrows `v` to `string` when `allowedType` is `"string"`.
+ * @param v - Value to test.
+ * @param options - Must include `allowedType: "string"`.
+ */
+declare function isDecimal(v: unknown, options: IsDecimalOptions & {
+    allowedType: "string";
+}): v is string;
+/**
+ * Returns `true` when `v` is a valid decimal value (number or string).
+ *
+ * Validates that the input represents a finite decimal number. Accepts both
+ * JS `number` primitives and decimal strings. Optionally restricts the accepted
+ * JS type, the decimal separator character, and enforces precision/scale bounds.
+ *
+ * **Type narrowing via overloads:**
+ * When `allowedType` is specified the return type is narrowed accordingly —
+ * `v is number` for `"number"` and `v is string` for `"string"`.
+ *
+ * **Behaviour per input type:**
+ * - `number` — must be finite and non-NaN. Scientific notation (e.g. `1e20`) is
+ *   rejected because it has no standard decimal representation.
+ * - `string` — must match `^-?\d+([.,]\d+)?$` using the configured separator.
+ *   Leading/trailing whitespace is not trimmed; pass `.trim()` yourself if needed.
+ *
+ * @param v - Value to test. Anything other than `number` or `string` returns `false`.
+ * @param options - Optional validation constraints.
+ * @returns `true` when `v` is a valid decimal within the specified constraints.
+ *
+ * @example
+ * // Basic usage — accepts both number and string
+ * isDecimal(3.14);      // true
+ * isDecimal("3.14");    // true
+ * isDecimal("abc");     // false
+ * isDecimal(Infinity);  // false
+ * isDecimal(NaN);       // false
+ * isDecimal(null);      // false
+ *
+ * @example
+ * // Restrict to a single JS type
+ * isDecimal(3.14,   { allowedType: "number" }); // true
+ * isDecimal("3.14", { allowedType: "number" }); // false — string rejected
+ * isDecimal("3.14", { allowedType: "string" }); // true
+ * isDecimal(3.14,   { allowedType: "string" }); // false — number rejected
+ *
+ * @example
+ * // Comma as decimal separator (e.g. European locale strings)
+ * isDecimal("3,14", { decimalPoint: "," }); // true
+ * isDecimal("3.14", { decimalPoint: "," }); // false
+ *
+ * @example
+ * // Precision and scale constraints (matching SQL decimal(9, 2))
+ * isDecimal("1234567.89", { precision: 9, scale: 2 }); // true  — 7+2=9 digits
+ * isDecimal("12345678.9", { precision: 9, scale: 2 }); // false — 8+1=9 but scale violated? no — true, 1≤2
+ * isDecimal("3.145",      { scale: 2 });                // false — 3 fractional digits
+ * isDecimal("3",          { scale: 2 });                // true  — 0 fractional digits
+ *
+ * @example
+ * // Type narrowing in practice
+ * function process(raw: unknown) {
+ *     if (isDecimal(raw, { allowedType: "string" })) {
+ *         raw; // narrowed to string here
+ *         console.log(raw.toUpperCase());
+ *     }
+ * }
+ */
+declare function isDecimal(v: unknown, options?: IsDecimalOptions): v is number | string;
+
 /**
  * Runtime validation for enum values.
  * If a runtime enum object is provided, the value must match one of its values
@@ -474,6 +835,46 @@ declare function isNumberInRange(v: unknown, min: number, max: number, options?:
     includeMin?: boolean;
     includeMax?: boolean;
 }): v is number;
+/**
+ * Numeric boolean flag type — either 0 or 1
+ */
+type BinaryFlag = 0 | 1;
+/**
+ * Converts a number, boolean, null, or undefined to a BinaryFlag (0 or 1)
+ *
+ * @example
+ * TO_BINARY_FLAG(true)  // 1
+ * TO_BINARY_FLAG(1)     // 1
+ * TO_BINARY_FLAG(false) // 0
+ * TO_BINARY_FLAG(null)  // 0
+ */
+declare const TO_BINARY_FLAG: (v: number | boolean | null | undefined) => BinaryFlag;
+
+/**
+ * Runs async worker functions over items with a concurrency limit.
+ *
+ * @param items - Array of items to process
+ * @param concurrency - Maximum number of concurrent workers
+ * @param worker - Async function to run for each item
+ *
+ * @example
+ * await runWithConcurrency(productIds, 5, async (id) => {
+ *     await processProduct(id);
+ * });
+ */
+declare function runWithConcurrency<T>(items: T[], concurrency: number, worker: (item: T) => Promise<void>): Promise<void>;
+
+type TransformMap<TIn, TOut, K extends keyof TIn & keyof TOut> = Partial<{
+    [P in K]: (val: TIn[P]) => TOut[P];
+}>;
+/**
+ * Builds a partial patch object from an input DTO, only including keys that are defined.
+ * Optionally applies transform functions to specific keys.
+ *
+ * @example
+ * const patch = buildPatch(data, ["name", "active"], { active: (v) => v ? 1 : 0 });
+ */
+declare function buildPatch<TOut extends Record<string, any>, TIn extends Record<string, any>, K extends keyof TIn & keyof TOut = keyof TIn & keyof TOut>(data: Partial<TIn>, keys: readonly K[], transforms?: TransformMap<TIn, TOut, K>): Partial<Pick<TOut, K>>;
 
 type Maybe<T> = T | null;
 /**
@@ -605,6 +1006,18 @@ declare class ApiError extends Error {
     constructor(statusCode: number, status: Status, detail?: string);
 }
 
+/**
+ * Represents a non-fatal business rule violation that should be
+ * communicated to the caller without being treated as a system error.
+ *
+ * @example
+ * throw new BusinessWarning("ORDER_ALREADY_SENT", "Tato objednávka již byla odeslána.");
+ */
+declare class BusinessWarning extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+
 declare const FRESH_ESLINT_CONFIG: {
     files: string[];
     ignores: string[];
@@ -682,4 +1095,4 @@ interface HealthCheckResult {
     };
 }
 
-export { AMOUNT_UNIT, ActionCommandCode, ApiError, BaseEntityChangeSubscriber, type CardNumber, Category, DataHelper, DateUtils, type Deferred, DepotPoolStatus, Device, type EntityChangeEvent, FreshDao, FreshEntity, FreshHyperEntity, FreshJob, FreshTranslationBase, type HealthCheckResult, HttpStatus, LanguageCode, Manufacturer, type Maybe, PaymentMethod, PG_DATA_SOURCE_OPTIONS as PgDataSourceOptions, Product, SinglePromiseWaiter, Singleton, type Status, StatusDto, Subcategory, TimestampColumn, TransactionType, createDeferred, FRESH_ESLINT_CONFIG as freshEslintConfig, hasOwn, isEnumValue, isFlag01, isMaybe, isNumber, isNumberInRange, isObject, isString, isValidCron };
+export { AMOUNT_UNIT, ActionCommandCode, ApiError, BaseEntityChangeSubscriber, type BinaryFlag, BusinessWarning, type CardNumber, Category, DEFAULT_PAGINATION_PARAMS, DataHelper, DateUtils, type Deferred, DepotPoolStatus, Device, type EntityChangeEvent, FreshDao, FreshEntity, FreshHyperEntity, FreshJob, FreshTranslationBase, type HealthCheckResult, HttpStatus, type IsDecimalOptions, LanguageCode, Manufacturer, type Maybe, type PaginatedList, type PaginationMeta, type PaginationParams, PaymentMethod, PG_DATA_SOURCE_OPTIONS as PgDataSourceOptions, Product, SinglePromiseWaiter, Singleton, type Status, StatusDto, Subcategory, TO_BINARY_FLAG, TimestampColumn, TransactionType, buildPatch, constructTypeormPagination, createDeferred, FRESH_ESLINT_CONFIG as freshEslintConfig, getPaginationMeta, getPaginationParams, hasOwn, isDecimal, isEnumValue, isFlag01, isMaybe, isNumber, isNumberInRange, isObject, isString, isValidCron, listAll, parsePaginationFromURL, runWithConcurrency, toDecimal };