Bump version to v1.1.0: add shouldExecuteFinalRun flag for final execution on stop

Author: ori88c

README.md

@@ -2,7 +2,7 @@
 
 The `NonOverlappingRecurringTask` class provides a modern `setInterval` substitute tailored for asynchronous tasks, ensuring non-overlapping executions by **skipping** attempts if a previous execution is still in progress.
 
-Special emphasis is given to **graceful teardown**: The ability to await the completion of an ongoing execution - particularly during application shutdown - makes it ideal for production environments requiring **seamless resource cleanup**.
+Special emphasis is given to **graceful teardown**: The ability to await the completion of an ongoing execution - particularly during application shutdown - makes it ideal for production environments requiring seamless resource cleanup.
 
 ## Table of Contents
 
@@ -20,11 +20,12 @@ Special emphasis is given to **graceful teardown**: The ability to await the com
 ## Key Features :sparkles:<a id="key-features"></a>
 
 * __Guaranteed Non-Overlapping Executions :lock:__: Prevents race conditions ([Race Conditions: How Are They Possible in Single-Threaded JavaScript?](https://www.npmjs.com/package/zero-overhead-promise-lock#race-conditions)) and provides precise control over resource usage. Ideal for batch processing tasks that must run exclusively to manage network bandwidth efficiently.
-* __Graceful and Deterministic Teardown :hourglass_flowing_sand:__: When the `stop()` method is invoked during task execution, it resolves only **after** the execution is complete. This guarantees **smooth resource cleanup**, making it well-suited for production environments (e.g., `onModuleDestroy()` in NestJS) and maintaining a **clean state** between unit tests.
+* __Graceful and Deterministic Teardown :hourglass_flowing_sand:__: When the `stop` method is invoked during task execution, it resolves only **after** the execution is complete. This guarantees **smooth resource cleanup**, making it well-suited for production environments (e.g., `onModuleDestroy` in NestJS) and maintaining a **clean state** between unit tests.
 * __Fixed Delay Between Executions :repeat:__: Functions similarly to JavaScript's built-in `setInterval`, but skips executions if a previous one is still in progress.
-- __Flexible First Execution Policy :level_slider:__: The `immediateFirstRun` option lets you control whether execution begins immediately upon `start()` or only after the first interval. Particularly useful when the task is part of an **application’s bootstrap phase** (e.g., `onModuleInit()` in NestJS). If the bootstrap phase requires the first execution to complete before proceeding (e.g., before accepting HTTP requests), pair this with `waitUntilCurrentExecutionCompletes()`.
+- __Flexible First Execution Policy :level_slider:__: The `immediateFirstRun` option lets you control whether execution begins immediately upon `start` or only after the first interval. Particularly useful when the task is part of an **application’s bootstrap phase** (e.g., `onModuleInit` in NestJS). If the bootstrap phase requires the first execution to complete before proceeding (e.g., before accepting HTTP requests), pair this with `waitUntilCurrentExecutionCompletes`.
+- __Optional Final Digest Run :broom:__: The optional `shouldExecuteFinalRun` flag allows a final execution to be performed as part of the `stop` process. This is especially useful for tasks that accumulate state between executions and need a final flush to persistent storage to avoid leaving unprocessed data. Examples include delayed publishing of batched Kafka messages and upserting accumulated data into a database.
 - __Error Handling :warning:__: If a periodic task throws an error, it is passed to an optional error handler callback, if provided. This component does **not** perform any logging, as it is designed to be **agnostic of user preferences**, such as specific loggers or logging styles. A typical `_onTaskError` implementation logs errors based on the user's logging strategy. If the periodic task already handles its own errors, this handler can be omitted.
-- __Execution State Metrics :bar_chart:__: The `status` and `isCurrentlyExecuting` getters offer real-time insights into the scheduler's state, helping users make informed decisions, such as awaiting `waitUntilCurrentExecutionCompletes()` when specific operations must not overlap the recurring task.
+- __Execution State Metrics :bar_chart:__: The `status` and `isCurrentlyExecuting` getters offer real-time insights into the scheduler's state, helping users make informed decisions, such as awaiting `waitUntilCurrentExecutionCompletes` when specific operations must not overlap the recurring task.
 - __Comprehensive documentation :books:__: Fully documented, enabling IDEs to provide intelligent **tooltips** for an enhanced development experience.
 - __Thoroughly Tested :test_tube:__: Backed by extensive unit tests, covering even rare edge cases, to ensure reliability in production.
 - __Zero Runtime Dependencies :dove:__: Only development dependencies are included.

dist/non-overlapping-recurring-task.d.ts

@@ -181,7 +181,8 @@ export declare class NonOverlappingRecurringTask<UncaughtErrorType = Error> {
      * ### Graceful Teardown
      * If this method is invoked during an ongoing execution, it resolves only after the
      * current execution completes. This guarantee ensures **determinism** and allows for
-     * a **graceful teardown**.
+     * a **graceful teardown**. If the `shouldExecuteFinalRun` flag is enabled, the method
+     * also waits for the final (digest) run to complete.
      * Use cases where it is essential to complete any ongoing execution before proceeding include:
      * - **Application Shutdowns**: In cases like `onModuleDestroy` in NestJS applications, where
      *   tasks should complete before termination. For instance, ensuring a bulk-write to a database
@@ -195,12 +196,32 @@ export declare class NonOverlappingRecurringTask<UncaughtErrorType = Error> {
      * In case the instance is in a termination status (i.e., awaiting completion of the last execution),
      * a redundant call will wait for the ongoing execution to complete before resolving.
      *
+     * ### Optional: Force an Additional Final Run
+     * Enabling the `shouldExecuteFinalRun` flag triggers **one final execution** before resolving.
+     * This is particularly useful for tasks that accumulate state between executions and require
+     * a final flush (write operation) to **ensure no unprocessed data remains**.
+     * #### When This is Relevant
+     * - Flushing Batched Writes: A log aggregator that periodically writes accumulated logs to a
+     *   database should execute a final flush before stopping to prevent data loss.
+     * - Committing Transactions: A system that batches updates should perform one last batch
+     *   before stopping to ensure all changes are committed.
+     * #### When This is Less Relevant
+     * - Periodic Data Fetches: If the task refreshes external configurations at regular intervals,
+     *   such as feature flags, an additional fetch before stopping provides no meaningful benefit.
+     *
+     * @param shouldExecuteFinalRun - If `true`, ensures that one final execution occurs as part of the
+     *                                stop process. This is particularly useful for tasks that **accumulate
+     *                                state between executions** and require a final flush to avoid leaving
+     *                                unprocessed data. To eliminate any ambiguity, when this flag is enabled,
+     *                                the `stop` method resolves only **after** the final execution completes.
      * @returns `true` if recurring executions were stopped by this invocation (i.e., the instance's
-     *          status changed from active to inactive);
+     *          status changed from 'active' to 'inactive');
      *          `false` if the instance was already inactive or in termination status, and the
-     *          invocation had no effect.
+     *          invocation had no effect. Note that even when `false` is returned, the call
+     *          still waits for the last run to complete if invoked while the instance is in a
+     *          'terminating' status.
      */
-    stop(): Promise<boolean>;
+    stop(shouldExecuteFinalRun?: boolean): Promise<boolean>;
     /**
      * Executes the task in a controlled manner:
      * - Triggers the optional error handler (if provided) when the task rejects with an error.