@freshpointcz/fresh-core 0.0.13 → 0.0.14

package/dist/index.d.mts

@@ -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";
@@ -324,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,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";
@@ -324,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.js

@@ -746,14 +746,38 @@ __name(isValidCron, "isValidCron");
 
 // src/common/patterns/singleton.ts
 var _Singleton = class _Singleton {
-  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 = true) {
     const ctor = this.constructor;
     const existing = _Singleton.instances.get(ctor);
     if (existing) {
       return existing;
     }
     _Singleton.instances.set(ctor, this);
+    if (callOnInit) {
+      void this.onInit();
+    }
   }
+  /**
+   * 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.
+   */
   static getInstance(...args) {
     let instance = _Singleton.instances.get(this);
     if (!instance) {
@@ -764,6 +788,10 @@ var _Singleton = class _Singleton {
   }
 };
 __name(_Singleton, "Singleton");
+/**
+ * Internal registry of singleton instances.
+ * One instance per subclass constructor.
+ */
 __publicField(_Singleton, "instances", /* @__PURE__ */ new Map());
 var Singleton = _Singleton;
 
@@ -1299,13 +1327,34 @@ var DataHelper = _DataHelper;
 var import_node_schedule = require("node-schedule");
 var _FreshJob = class _FreshJob extends Singleton {
   /**
-   * @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, cronExpression, jobEnabled) {
-    super();
+    super(false);
+    /** Human-readable job identifier (used for logs and errors). */
     __publicField(this, "_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.
+     */
     __publicField(this, "_cronExpression");
+    /** Scheduled job instance, or `null` if the job is disabled. */
     __publicField(this, "_job", null);
     this._jobName = jobName;
     if (!isValidCron(cronExpression)) {
@@ -1325,28 +1374,68 @@ var _FreshJob = class _FreshJob extends Singleton {
     }
     this.onInit();
   }
-  /** 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.
+   */
   onInit(rescheduled) {
     console.log(`Job ${this.jobName} ${rescheduled ? "rescheduled" : "initialized"} with cron rule: "${this.cronExpression}"`);
   }
+  /** @returns The logical name of the job. */
   get jobName() {
     return this._jobName;
   }
+  /** Allows subclasses to rename the job if absolutely necessary. */
   set jobName(value) {
     this._jobName = value;
   }
+  /** @returns The cron expression used to schedule the job. */
   get cronExpression() {
     return this._cronExpression;
   }
+  /**
+   * Allows subclasses to update the cron expression internally.
+   * Does reschedule of job if exists
+   */
   set cronExpression(value) {
+    if (!isValidCron(value)) {
+      throw new Error(`Job ${this._jobName} cannot be re-scheduled with invalid cron: "${value}"`);
+    }
     this._cronExpression = value;
   }
+  /** @returns The underlying scheduled job instance, or `null` if disabled. */
   get job() {
     return this._job;
   }
+  /** Allows subclasses to manage the scheduled job instance. */
   set job(value) {
     this._job = value;
   }
+  reschedule(newCronExpression) {
+    let result = false;
+    if (!isValidCron(newCronExpression)) {
+      throw new Error(`Job ${this._jobName} cannot be re-scheduled with invalid cron: "${newCronExpression}"`);
+    }
+    this._cronExpression = newCronExpression;
+    if (this._job) {
+      const rescheduleSuccess = this._job.reschedule({
+        rule: this._cronExpression,
+        tz: "Europe/Prague"
+      });
+      if (!rescheduleSuccess) {
+        throw new Error(`Job ${this._jobName} could not be re-scheduled`);
+      } else {
+        this.onInit(true);
+      }
+      result = rescheduleSuccess;
+    }
+    return result;
+  }
 };
 __name(_FreshJob, "FreshJob");
 var FreshJob = _FreshJob;