@freshpointcz/fresh-core 0.0.13 → 0.0.15

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import dayjs, { Dayjs } from 'dayjs';
 import { Logger } from 'winston';
-import { BaseEntity, ColumnOptions, Repository, DataSourceOptions } from 'typeorm';
+import { BaseEntity, ColumnOptions, Repository, EntityTarget, EntityManager, DataSourceOptions } from 'typeorm';
 import { Job } from 'node-schedule';
 import * as eslint from 'eslint';
 import * as typescript_eslint_dist_compatibility_types from 'typescript-eslint/dist/compatibility-types';
@@ -58,11 +58,62 @@ declare const logger: Logger;
 
 declare function isValidCron(expr: string): boolean;
 
+/**
+ * Abstract base class implementing a per-subclass Singleton pattern.
+ *
+ * Each subclass of `Singleton` can have exactly one instance.
+ * Instantiation is guarded at runtime: calling `new` multiple times
+ * will always return the first created instance for that subclass.
+ *
+ * Instances are stored internally in a static map keyed by constructor
+ * function, allowing independent singleton instances per subclass.
+ *
+ * ⚠️ Important:
+ * - Subclasses MUST NOT override the constructor unless they fully
+ *   understand the consequences.
+ * - Initialization logic must be placed in {@link onInit}, not the constructor.
+ * - The constructor may return an existing instance, which is legal in JS
+ *   but mildly unsettling.
+ */
 declare abstract class Singleton {
+    /**
+     * Internal registry of singleton instances.
+     * One instance per subclass constructor.
+     */
     private static instances;
-    constructor();
+    /**
+     * Creates or returns the singleton instance for the subclass.
+     *
+     * If an instance already exists for the subclass, that instance is
+     * returned instead of creating a new one.
+     *
+     * @param callOnInit - Whether to call {@link onInit} for a newly
+     * created instance. Ignored if the instance already exists.
+     */
+    constructor(callOnInit?: boolean);
+    /**
+     * Retrieves the singleton instance for the calling subclass.
+     *
+     * If no instance exists, a new one is created using the provided
+     * constructor arguments.
+     *
+     * Intended to be used by subclasses as a protected factory method.
+     *
+     * @typeParam T - The concrete subclass type.
+     * @param args - Arguments forwarded to the subclass constructor.
+     * @returns The singleton instance of the subclass.
+     */
     protected static getInstance<T>(this: new (...args: any[]) => T, ...args: ConstructorParameters<any>): T;
-    protected abstract onInit(): void;
+    /**
+     * Lifecycle hook called once when the singleton instance is first created.
+     *
+     * Subclasses must implement this method instead of relying on the
+     * constructor for initialization logic.
+     *
+     * This method is guaranteed to be called at most once per subclass
+     * instance.
+     */
+    protected abstract onInit(): void | Promise<void>;
 }
 
 type Status = "ok" | "error" | "not-authorized" | "not-authenticated" | "internal-server-error" | "validation-error";
@@ -240,7 +291,8 @@ declare enum LanguageCode {
 declare enum PaymentMethod {
     CODE = 0,
     CARD = 1,
-    NONE = 2
+    NONE = 2,
+    CREDIT = 3
 }
 
 declare enum TransactionType {
@@ -292,6 +344,8 @@ declare function TimestampColumn(options?: ColumnOptions): PropertyDecorator;
 
 declare abstract class FreshDao<T extends BaseEntity> {
     protected abstract repo: Repository<T>;
+    protected abstract entity: EntityTarget<T>;
+    protected getRepo(manager?: EntityManager, entity?: EntityTarget<T>): Repository<T>;
 }
 
 declare class Category extends FreshEntity {
@@ -309,7 +363,93 @@ declare class Product extends FreshEntity {
 declare class Subcategory extends FreshEntity {
 }
 
+/**
+ * Runtime validation for enum values.
+ * If a runtime enum object is provided, the value must match one of its values
+ * If no enum object is provided, this falls back to accepting `string | number`
+ *
+ * @example
+ * isEnumValue(TransactionType, 0) // true
+ * isEnumValue(TransactionType, 99) // false
+ * isEnumValue(undefined, 99) // true
+ * isEnumValue(undefined, "99") // true
+ */
+declare function isEnumValue<E extends Record<string, string | number>>(enumObj: E | undefined, v: unknown): v is E[keyof E];
+
+/**
+ * Non-null object typeguard
+ * @usage Use for narrowing `unknown` type and to check that a value is a non-null object
+ * @description
+ * WARNING: Arrays and functions are technically objects in JS,
+ * but this guard intentionally allows them only as plain objects
+ * via structural usage.
+ */
+declare function isObject(v: unknown): v is Record<string, unknown>;
+/**
+ * Wrapper around `Object.prototype.hasOwnProperty`.
+ * @usage Use this instead of `key in obj`
+ */
+declare function hasOwn(obj: Record<string, unknown>, key: string): boolean;
+
+/**
+ * Checks that a value is a finite number
+ *
+ * Rejects numbers like:
+ * - NaN
+ * - Infinity / -Infinity
+ *
+ * @usage numeric fields validation
+ */
+declare function isNumber(v: unknown): v is number;
+/**
+ * Checks that a value is a string
+ */
+declare function isString(v: unknown): v is string;
+/**
+ * Validates a numeric boolean flag represented as 0 or 1
+ */
+declare function isFlag01(v: unknown): v is 0 | 1;
+/**
+ * Checks that a value is a finite number within a given range
+ * By default, the range is inclusive on both ends
+ *
+ * @param v - Value to validate
+ * @param min - Minimum allowed value
+ * @param max - Maximum allowed value
+ * @param options - Range behavior configuration
+ * @param options.includeMin - Whether `min` is allowed (default: true)
+ * @param options.includeMax - Whether `max` is allowed (default: true)
+ *
+ * @returns `true` if the value is a finite number within the range
+ * @example
+ * isNumberInRange(5, 1, 10); // true
+ * isNumberInRange(1, 1, 10); // true
+ * isNumberInRange(1, 1, 10, { includeMin: false }); // false
+ * isNumberInRange(10, 1, 10, { includeMax: false }); // false
+ * isNumberInRange("5", 1, 10); // false
+ * isNumberInRange(NaN, 1, 10); // false
+ */
+declare function isNumberInRange(v: unknown, min: number, max: number, options?: {
+    includeMin?: boolean;
+    includeMax?: boolean;
+}): v is number;
+
 type Maybe<T> = T | null;
+/**
+ * Validates a value that may be `null` or given type
+ *
+ * WARNING:
+ * `undefined` is NOT accepted by this function.
+ * If you need `undefined` support, it must be handled
+ * before calling this guard or explicitly allowed elsewhere.
+ *
+ * @typeParam T - The underlying non-nullable type
+ * @param v - Value to validate
+ * @param inner - Typeguard function for the underlying type `T`
+ *
+ * @returns `true` if the value is `null` or satisfies the inner typeguard
+ */
+declare function isMaybe<T>(v: unknown, inner: (x: unknown) => x is T): v is Maybe<T>;
 
 declare abstract class DataHelper<T> {
     private _data?;
@@ -324,26 +464,98 @@ declare abstract class DataHelper<T> {
     abstract startDataRetrieval(): Promise<Maybe<T>>;
 }
 
+/**
+ * Abstract base class for scheduled singleton jobs.
+ *
+ * Combines:
+ * - a per-subclass Singleton lifecycle
+ * - cron-based scheduling via `node-schedule`
+ * - a predictable execution entry point via {@link invoke}
+ *
+ * Each concrete job:
+ * - exists exactly once per process
+ * - may or may not be scheduled (depending on `jobEnabled`)
+ * - is responsible only for business logic, not scheduling mechanics
+ *
+ * The job is scheduled immediately during construction if enabled.
+ * Initialization logging is handled internally.
+ *
+ * @typeParam T - Return type of the job execution.
+ *
+ * ⚠️ Design notes for future maintainers:
+ * - Do NOT override the constructor unless you enjoy debugging time-based bugs.
+ * - All job logic belongs in {@link invoke}.
+ * - Rescheduling requires calling {@link reschedule} with valid cron.
+ */
 declare abstract class FreshJob<T = void> extends Singleton {
+    /** Human-readable job identifier (used for logs and errors). */
     private _jobName;
+    /**
+     * Cron expression defining when the job runs.
+     *
+     * Must contain numeric cron fields only.
+     * Example: `0 5 * * 4`
+     *
+     * Timezone is always forced to `"Europe/Prague"`.
+     * If you need another timezone, this class is not your friend.
+     */
     private _cronExpression;
+    /** Scheduled job instance, or `null` if the job is disabled. */
     private _job;
     /**
-     * @param cronExpression must be cron of just numbers ex.: `0 5 * * 4`
-     * By default timezone is added " Europe/Prague"
+     * Creates and optionally schedules a singleton cron job.
+     *
+     * @param jobName - Logical name of the job (used in logs and errors).
+     * @param cronExpression - Cron expression consisting of numeric fields only.
+     * Example: `0 5 * * 4`
+     * The timezone `"Europe/Prague"` is applied automatically.
+     *
+     * @param jobEnabled - Whether the job should be scheduled immediately.
+     * If `false`, the instance exists but no cron trigger is registered.
+     *
+     * @throws Error If the cron expression is invalid.
+     * @throws Error If the job cannot be scheduled.
      */
     constructor(jobName: string, cronExpression: string, jobEnabled: boolean);
-    /** Just logging */
+    /**
+     * Initialization hook.
+     *
+     * Called once during construction and used primarily for logging.
+     * Can also be reused by subclasses if manual rescheduling is implemented.
+     *
+     * @param rescheduled - Indicates whether the job was reconfigured
+     * after initial creation.
+     */
     protected onInit(rescheduled?: boolean): void;
+    /** @returns The logical name of the job. */
     get jobName(): string;
+    /** Allows subclasses to rename the job if absolutely necessary. */
     protected set jobName(value: string);
+    /** @returns The cron expression used to schedule the job. */
     get cronExpression(): string;
+    /**
+     * Allows subclasses to update the cron expression internally.
+     * Does reschedule of job if exists
+     */
     protected set cronExpression(value: string);
+    /** @returns The underlying scheduled job instance, or `null` if disabled. */
     protected get job(): Job | null;
+    /** Allows subclasses to manage the scheduled job instance. */
     protected set job(value: Job | null);
+    protected reschedule(newCronExpression: string): boolean;
+    /**
+     * Job execution entry point.
+     *
+     * This method is called by the scheduler when the cron rule matches.
+     * All business logic belongs here.
+     *
+     * @returns The result of the job execution, optionally wrapped in a Promise.
+     */
     abstract invoke(): T | Promise<T>;
 }
 
+type CardNumber = `${number}${number}${number}${number}`;
+
 declare class ApiError extends Error {
     private _statusCode;
     get statusCode(): number;
@@ -429,4 +641,4 @@ interface HealthCheckResult {
     };
 }
 
-export { AMOUNT_UNIT, ActionCommandCode, ApiError, Category, DataHelper, DateUtils, type Deferred, DepotPoolStatus, Device, 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, isValidCron, logger };
+export { AMOUNT_UNIT, ActionCommandCode, ApiError, type CardNumber, Category, DataHelper, DateUtils, type Deferred, DepotPoolStatus, Device, 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, logger };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import dayjs, { Dayjs } from 'dayjs';
 import { Logger } from 'winston';
-import { BaseEntity, ColumnOptions, Repository, DataSourceOptions } from 'typeorm';
+import { BaseEntity, ColumnOptions, Repository, EntityTarget, EntityManager, DataSourceOptions } from 'typeorm';
 import { Job } from 'node-schedule';
 import * as eslint from 'eslint';
 import * as typescript_eslint_dist_compatibility_types from 'typescript-eslint/dist/compatibility-types';
@@ -58,11 +58,62 @@ declare const logger: Logger;
 
 declare function isValidCron(expr: string): boolean;
 
+/**
+ * Abstract base class implementing a per-subclass Singleton pattern.
+ *
+ * Each subclass of `Singleton` can have exactly one instance.
+ * Instantiation is guarded at runtime: calling `new` multiple times
+ * will always return the first created instance for that subclass.
+ *
+ * Instances are stored internally in a static map keyed by constructor
+ * function, allowing independent singleton instances per subclass.
+ *
+ * ⚠️ Important:
+ * - Subclasses MUST NOT override the constructor unless they fully
+ *   understand the consequences.
+ * - Initialization logic must be placed in {@link onInit}, not the constructor.
+ * - The constructor may return an existing instance, which is legal in JS
+ *   but mildly unsettling.
+ */
 declare abstract class Singleton {
+    /**
+     * Internal registry of singleton instances.
+     * One instance per subclass constructor.
+     */
     private static instances;
-    constructor();
+    /**
+     * Creates or returns the singleton instance for the subclass.
+     *
+     * If an instance already exists for the subclass, that instance is
+     * returned instead of creating a new one.
+     *
+     * @param callOnInit - Whether to call {@link onInit} for a newly
+     * created instance. Ignored if the instance already exists.
+     */
+    constructor(callOnInit?: boolean);
+    /**
+     * Retrieves the singleton instance for the calling subclass.
+     *
+     * If no instance exists, a new one is created using the provided
+     * constructor arguments.
+     *
+     * Intended to be used by subclasses as a protected factory method.
+     *
+     * @typeParam T - The concrete subclass type.
+     * @param args - Arguments forwarded to the subclass constructor.
+     * @returns The singleton instance of the subclass.
+     */
     protected static getInstance<T>(this: new (...args: any[]) => T, ...args: ConstructorParameters<any>): T;
-    protected abstract onInit(): void;
+    /**
+     * Lifecycle hook called once when the singleton instance is first created.
+     *
+     * Subclasses must implement this method instead of relying on the
+     * constructor for initialization logic.
+     *
+     * This method is guaranteed to be called at most once per subclass
+     * instance.
+     */
+    protected abstract onInit(): void | Promise<void>;
 }
 
 type Status = "ok" | "error" | "not-authorized" | "not-authenticated" | "internal-server-error" | "validation-error";
@@ -240,7 +291,8 @@ declare enum LanguageCode {
 declare enum PaymentMethod {
     CODE = 0,
     CARD = 1,
-    NONE = 2
+    NONE = 2,
+    CREDIT = 3
 }
 
 declare enum TransactionType {
@@ -292,6 +344,8 @@ declare function TimestampColumn(options?: ColumnOptions): PropertyDecorator;
 
 declare abstract class FreshDao<T extends BaseEntity> {
     protected abstract repo: Repository<T>;
+    protected abstract entity: EntityTarget<T>;
+    protected getRepo(manager?: EntityManager, entity?: EntityTarget<T>): Repository<T>;
 }
 
 declare class Category extends FreshEntity {
@@ -309,7 +363,93 @@ declare class Product extends FreshEntity {
 declare class Subcategory extends FreshEntity {
 }
 
+/**
+ * Runtime validation for enum values.
+ * If a runtime enum object is provided, the value must match one of its values
+ * If no enum object is provided, this falls back to accepting `string | number`
+ *
+ * @example
+ * isEnumValue(TransactionType, 0) // true
+ * isEnumValue(TransactionType, 99) // false
+ * isEnumValue(undefined, 99) // true
+ * isEnumValue(undefined, "99") // true
+ */
+declare function isEnumValue<E extends Record<string, string | number>>(enumObj: E | undefined, v: unknown): v is E[keyof E];
+
+/**
+ * Non-null object typeguard
+ * @usage Use for narrowing `unknown` type and to check that a value is a non-null object
+ * @description
+ * WARNING: Arrays and functions are technically objects in JS,
+ * but this guard intentionally allows them only as plain objects
+ * via structural usage.
+ */
+declare function isObject(v: unknown): v is Record<string, unknown>;
+/**
+ * Wrapper around `Object.prototype.hasOwnProperty`.
+ * @usage Use this instead of `key in obj`
+ */
+declare function hasOwn(obj: Record<string, unknown>, key: string): boolean;
+
+/**
+ * Checks that a value is a finite number
+ *
+ * Rejects numbers like:
+ * - NaN
+ * - Infinity / -Infinity
+ *
+ * @usage numeric fields validation
+ */
+declare function isNumber(v: unknown): v is number;
+/**
+ * Checks that a value is a string
+ */
+declare function isString(v: unknown): v is string;
+/**
+ * Validates a numeric boolean flag represented as 0 or 1
+ */
+declare function isFlag01(v: unknown): v is 0 | 1;
+/**
+ * Checks that a value is a finite number within a given range
+ * By default, the range is inclusive on both ends
+ *
+ * @param v - Value to validate
+ * @param min - Minimum allowed value
+ * @param max - Maximum allowed value
+ * @param options - Range behavior configuration
+ * @param options.includeMin - Whether `min` is allowed (default: true)
+ * @param options.includeMax - Whether `max` is allowed (default: true)
+ *
+ * @returns `true` if the value is a finite number within the range
+ * @example
+ * isNumberInRange(5, 1, 10); // true
+ * isNumberInRange(1, 1, 10); // true
+ * isNumberInRange(1, 1, 10, { includeMin: false }); // false
+ * isNumberInRange(10, 1, 10, { includeMax: false }); // false
+ * isNumberInRange("5", 1, 10); // false
+ * isNumberInRange(NaN, 1, 10); // false
+ */
+declare function isNumberInRange(v: unknown, min: number, max: number, options?: {
+    includeMin?: boolean;
+    includeMax?: boolean;
+}): v is number;
+
 type Maybe<T> = T | null;
+/**
+ * Validates a value that may be `null` or given type
+ *
+ * WARNING:
+ * `undefined` is NOT accepted by this function.
+ * If you need `undefined` support, it must be handled
+ * before calling this guard or explicitly allowed elsewhere.
+ *
+ * @typeParam T - The underlying non-nullable type
+ * @param v - Value to validate
+ * @param inner - Typeguard function for the underlying type `T`
+ *
+ * @returns `true` if the value is `null` or satisfies the inner typeguard
+ */
+declare function isMaybe<T>(v: unknown, inner: (x: unknown) => x is T): v is Maybe<T>;
 
 declare abstract class DataHelper<T> {
     private _data?;
@@ -324,26 +464,98 @@ declare abstract class DataHelper<T> {
     abstract startDataRetrieval(): Promise<Maybe<T>>;
 }
 
+/**
+ * Abstract base class for scheduled singleton jobs.
+ *
+ * Combines:
+ * - a per-subclass Singleton lifecycle
+ * - cron-based scheduling via `node-schedule`
+ * - a predictable execution entry point via {@link invoke}
+ *
+ * Each concrete job:
+ * - exists exactly once per process
+ * - may or may not be scheduled (depending on `jobEnabled`)
+ * - is responsible only for business logic, not scheduling mechanics
+ *
+ * The job is scheduled immediately during construction if enabled.
+ * Initialization logging is handled internally.
+ *
+ * @typeParam T - Return type of the job execution.
+ *
+ * ⚠️ Design notes for future maintainers:
+ * - Do NOT override the constructor unless you enjoy debugging time-based bugs.
+ * - All job logic belongs in {@link invoke}.
+ * - Rescheduling requires calling {@link reschedule} with valid cron.
+ */
 declare abstract class FreshJob<T = void> extends Singleton {
+    /** Human-readable job identifier (used for logs and errors). */
     private _jobName;
+    /**
+     * Cron expression defining when the job runs.
+     *
+     * Must contain numeric cron fields only.
+     * Example: `0 5 * * 4`
+     *
+     * Timezone is always forced to `"Europe/Prague"`.
+     * If you need another timezone, this class is not your friend.
+     */
     private _cronExpression;
+    /** Scheduled job instance, or `null` if the job is disabled. */
     private _job;
     /**
-     * @param cronExpression must be cron of just numbers ex.: `0 5 * * 4`
-     * By default timezone is added " Europe/Prague"
+     * Creates and optionally schedules a singleton cron job.
+     *
+     * @param jobName - Logical name of the job (used in logs and errors).
+     * @param cronExpression - Cron expression consisting of numeric fields only.
+     * Example: `0 5 * * 4`
+     * The timezone `"Europe/Prague"` is applied automatically.
+     *
+     * @param jobEnabled - Whether the job should be scheduled immediately.
+     * If `false`, the instance exists but no cron trigger is registered.
+     *
+     * @throws Error If the cron expression is invalid.
+     * @throws Error If the job cannot be scheduled.
      */
     constructor(jobName: string, cronExpression: string, jobEnabled: boolean);
-    /** Just logging */
+    /**
+     * Initialization hook.
+     *
+     * Called once during construction and used primarily for logging.
+     * Can also be reused by subclasses if manual rescheduling is implemented.
+     *
+     * @param rescheduled - Indicates whether the job was reconfigured
+     * after initial creation.
+     */
     protected onInit(rescheduled?: boolean): void;
+    /** @returns The logical name of the job. */
     get jobName(): string;
+    /** Allows subclasses to rename the job if absolutely necessary. */
     protected set jobName(value: string);
+    /** @returns The cron expression used to schedule the job. */
     get cronExpression(): string;
+    /**
+     * Allows subclasses to update the cron expression internally.
+     * Does reschedule of job if exists
+     */
     protected set cronExpression(value: string);
+    /** @returns The underlying scheduled job instance, or `null` if disabled. */
     protected get job(): Job | null;
+    /** Allows subclasses to manage the scheduled job instance. */
     protected set job(value: Job | null);
+    protected reschedule(newCronExpression: string): boolean;
+    /**
+     * Job execution entry point.
+     *
+     * This method is called by the scheduler when the cron rule matches.
+     * All business logic belongs here.
+     *
+     * @returns The result of the job execution, optionally wrapped in a Promise.
+     */
     abstract invoke(): T | Promise<T>;
 }
 
+type CardNumber = `${number}${number}${number}${number}`;
+
 declare class ApiError extends Error {
     private _statusCode;
     get statusCode(): number;
@@ -429,4 +641,4 @@ interface HealthCheckResult {
     };
 }
 
-export { AMOUNT_UNIT, ActionCommandCode, ApiError, Category, DataHelper, DateUtils, type Deferred, DepotPoolStatus, Device, 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, isValidCron, logger };
+export { AMOUNT_UNIT, ActionCommandCode, ApiError, type CardNumber, Category, DataHelper, DateUtils, type Deferred, DepotPoolStatus, Device, 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, logger };