@freshpointcz/fresh-core 0.0.12 → 0.0.14

package/dist/index.d.mts

@@ -58,10 +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();
-    protected abstract onInit(): void;
+    /**
+     * 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;
+    /**
+     * 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";
@@ -323,23 +375,93 @@ 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>;
 }
 

package/dist/index.d.ts

@@ -58,10 +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();
-    protected abstract onInit(): void;
+    /**
+     * 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;
+    /**
+     * 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";
@@ -323,23 +375,93 @@ 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>;
 }