@remotex-labs/xjet 1.0.1 → 1.1.0

package/dist/shared.d.ts

@@ -1556,6 +1556,343 @@ interface InjectableOptionsInterface {
     factory?: FunctionType;
 }
 
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Provides a virtual timer system that mimics native `setTimeout`/`setInterval`
+ * while allowing controlled execution for deterministic tests.
+ *
+ * @remarks
+ * This service replaces the global timing functions with fake timers so that
+ * time can be manually advanced and callbacks triggered predictably.
+ * It is intended for unit testing scenarios where you need full control over
+ * asynchronous timing without waiting in real time.
+ *
+ * @example
+ * ```ts
+ * useFakeTimers();
+ * setTimeout(() => console.log('done'), 1000);
+ * advanceTimersByTime(1000); // logs 'done' immediately
+ * useRealTimers();
+ * ```
+ *
+ * @since 1.1.0
+ */
+declare class TimerService {
+    /**
+     * Active timers managed by the fake timer engine.
+     * @since 1.1.0
+     */
+    readonly timers: Map<number, TimerInterface>;
+    /**
+     * Stores original `Date.now` to restore when real timers are re-enabled.
+     * @since 1.1.0
+     */
+    readonly originalDateNow: () => number;
+    /**
+     * Stores original global `setTimeout`.
+     * @since 1.1.0
+     */
+    readonly originalSetTimeout: typeof setTimeout;
+    /**
+     * Stores original global `setInterval`.
+     * @since 1.1.0
+     */
+    readonly originalSetInterval: typeof setInterval;
+    /**
+     * Stores original global `clearTimeout`.
+     * @since 1.1.0
+     */
+    readonly originalClearTimeout: typeof clearTimeout;
+    /**
+     * Stores original global `clearInterval`.
+     * @since 1.1.0
+     */
+    readonly originalClearInterval: typeof clearInterval;
+    /**
+     * Simulated current timestamp for the fake timers.
+     * @since 1.1.0
+     */
+    private now;
+    /**
+     * Incremental id used to register timers uniquely.
+     * @since 1.1.0
+     */
+    private nextId;
+    /**
+     * Replaces the global timer functions with in-memory fakes.
+     *
+     * @remarks
+     * After calling this method, any calls to `setTimeout`, `setInterval`,
+     * `clearTimeout`, or `clearInterval` will be intercepted and stored in the
+     * {@link timers} map instead of scheduling real OS timers.
+     * This allows tests to control time progression manually using
+     * {@link advanceTimersByTime}, {@link runAllTimers}, or
+     * {@link runOnlyPendingTimers}.
+     *
+     * @example
+     * ```ts
+     * timerService.useFakeTimers();
+     * const id = setTimeout(() => console.log('done'), 1000);
+     * timerService.advanceTimersByTime(1000); // logs "done" immediately
+     * ```
+     *
+     * @since 1.1.0
+     */
+    useFakeTimers(): void;
+    /**
+     * Restores the original global timer APIs and `Date.now`.
+     *
+     * @remarks
+     * This method undoes the effects of {@link useFakeTimers}, re-binding
+     * the native implementations of `setTimeout`, `setInterval`,
+     * `clearTimeout`, `clearInterval`, and `Date.now`.
+     * After calling this, timers once again behave according to real system
+     * time and manual advancement methods such as
+     * {@link advanceTimersByTime} no longer apply.
+     *
+     * @example
+     * ```ts
+     * timerService.useFakeTimers();
+     * // ...run tests with controlled time...
+     * timerService.useRealTimers(); // restore native timers
+     * ```
+     *
+     * @since 1.1.0
+     */
+    useRealTimers(): void;
+    /**
+     * Advances the simulated clock by a specific number of milliseconds and
+     * executes all timers whose scheduled time has elapsed.
+     *
+     * @remarks
+     * Use this method after calling {@link useFakeTimers} to fast-forward the
+     * internal clock without waiting in real time.
+     * Any `setTimeout` or `setInterval` callbacks scheduled within the
+     * advanced period will run immediately in order of their scheduled time.
+     *
+     * @param ms - The number of milliseconds to move the simulated time forward.
+     *
+     * @example
+     * ```ts
+     * timerService.useFakeTimers();
+     * setTimeout(() => console.log('done'), 500);
+     * timerService.advanceTimersByTime(500); // logs "done"
+     * ```
+     *
+     * @since 1.1.0
+     */
+    advanceTimersByTime(ms: number): void;
+    /**
+     * Executes every scheduled timer until none remain.
+     *
+     * @remarks
+     * This method repeatedly advances the simulated clock to the next
+     * scheduled timer and runs its callback until the {@link timers} map
+     * is empty.
+     * It is useful when you want to immediately flush **all** pending
+     * `setTimeout` or `setInterval` callbacks regardless of their delay,
+     * without specifying a time increment.
+     *
+     * @example
+     * ```ts
+     * timerService.useFakeTimers();
+     * setTimeout(() => console.log('A'), 100);
+     * setTimeout(() => console.log('B'), 200);
+     * timerService.runAllTimers(); // logs "A" then "B"
+     * ```
+     *
+     * @since 1.1.0
+     */
+    runAllTimers(): void;
+    /**
+     * Executes only the timers that are currently pending at the time of call,
+     * without running any new timers that may be scheduled by those callbacks.
+     *
+     * @remarks
+     * Unlike {@link runAllTimers}, this method captures the set of timers
+     * that exist when the method is invoked and restricts execution to that
+     * initial set.
+     * If any of those timers schedule additional timers while running,
+     * the newly scheduled ones will **not** be executed during this call.
+     *
+     * @example
+     * ```ts
+     * timerService.useFakeTimers();
+     * setTimeout(() => {
+     *   console.log('first');
+     *   setTimeout(() => console.log('second'), 100);
+     * }, 100);
+     *
+     * timerService.runOnlyPendingTimers();
+     * // Logs only "first" because "second" was created afterward.
+     * ```
+     *
+     * @since 1.1.0
+     */
+    runOnlyPendingTimers(): void;
+}
+/**
+ * Globally enables fake timers using the shared {@link TimerService}.
+ *
+ * @remarks
+ * After calling this function, all calls to `setTimeout`, `setInterval`,
+ * `clearTimeout`, and `clearInterval` will be intercepted by the
+ * {@link TimerService} and stored in-memory instead of executing in real time.
+ * This allows deterministic testing by manually advancing time with
+ * {@link advanceTimersByTime}, {@link runAllTimers}, or
+ * {@link runOnlyPendingTimers}.
+ *
+ * @example
+ * ```ts
+ * useFakeTimers();
+ * setTimeout(() => console.log('done'), 1000);
+ * advanceTimersByTime(1000); // logs "done" immediately
+ * ```
+ *
+ * @since 1.1.0
+ */
+declare function useFakeTimers(): void;
+/**
+ * Restores real timers globally using the shared {@link TimerService}.
+ *
+ * @remarks
+ * This function undoes the effects of {@link useFakeTimers}, restoring the
+ * native implementations of `setTimeout`, `setInterval`, `clearTimeout`,
+ * `clearInterval`, and `Date.now`.
+ * After calling this, timers once again behave according to real system time,
+ * and manual advancement methods like {@link advanceTimersByTime} no longer apply.
+ *
+ * @example
+ * ```ts
+ * useFakeTimers();
+ * // ...run tests with controlled time...
+ * useRealTimers(); // restore native timers
+ * ```
+ *
+ * @since 1.1.0
+ */
+declare function useRealTimers(): void;
+/**
+ * Executes all timers currently registered in the {@link TimerService}.
+ *
+ * @remarks
+ * This function repeatedly runs all pending `setTimeout` and `setInterval`
+ * callbacks until no timers remain.
+ * It is equivalent to calling {@link TimerService.runAllTimers} on the
+ * injected service instance and is useful for immediately flushing
+ * all scheduled timers in tests.
+ *
+ * @example
+ * ```ts
+ * useFakeTimers();
+ * setTimeout(() => console.log('A'), 100);
+ * setTimeout(() => console.log('B'), 200);
+ * runAllTimers(); // logs "A" then "B"
+ * ```
+ *
+ * @since 1.1.0
+ */
+declare function runAllTimers(): void;
+/**
+ * Executes only the timers that are pending at the time of invocation.
+ *
+ * @remarks
+ * This function runs the callbacks of timers that exist when the function
+ * is called, without executing any new timers that may be scheduled
+ * during their execution.
+ * It delegates to {@link TimerService.runOnlyPendingTimers} on the injected
+ * service instance.
+ *
+ * @example
+ * ```ts
+ * useFakeTimers();
+ * setTimeout(() => {
+ *   console.log('first');
+ *   setTimeout(() => console.log('second'), 100);
+ * }, 100);
+ *
+ * runOnlyPendingTimers();
+ * // Logs only "first"; "second" is not executed yet
+ * ```
+ *
+ * @since 1.1.0
+ */
+declare function runOnlyPendingTimers(): void;
+/**
+ * Advances the simulated time by a specified number of milliseconds and
+ * executes all timers that are due.
+ *
+ * @remarks
+ * This function delegates to {@link TimerService.advanceTimersByTime}
+ * on the injected service instance.
+ * It is intended to be used after {@link useFakeTimers} to fast-forward
+ * time in tests without waiting for real timers.
+ *
+ * @param ms - The number of milliseconds to advance (default is `0`).
+ *
+ * @example
+ * ```ts
+ * useFakeTimers();
+ * setTimeout(() => console.log('done'), 500);
+ * advanceTimersByTime(500); // logs "done"
+ * ```
+ *
+ * @since 1.1.0
+ */
+declare function advanceTimersByTime(ms?: number): void;
+
+/**
+ * Interface representing a single timer stored and executed by the {@link TimerService}.
+ *
+ * @remarks
+ * This interface tracks all properties needed to manage both one-time
+ * and repeating timers within the fake timer system.
+ *
+ * @example
+ * ```ts
+ * const timer: TimerInterface = {
+ *   id: 1,
+ *   time: 1000,
+ *   args: [],
+ *   callback: () => console.log('done'),
+ *   interval: null,
+ * };
+ * ```
+ *
+ * @since 1.1.0
+ */
+interface TimerInterface {
+    /**
+     * Unique identifier for the timer.
+     * @since 1.1.0
+     */
+    id: number;
+    /**
+     * The simulated timestamp (in milliseconds) when the timer is next due to run.
+     * @since 1.1.0
+     */
+    time: number;
+    /**
+     * Arguments passed to the timer's callback function.
+     * @since 1.1.0
+     */
+    args: Array<unknown>;
+    /**
+     * Callback function to execute when the timer triggers.
+     * @since 1.1.0
+     */
+    callback: () => void;
+    /**
+     * Interval in milliseconds for repeating timers.
+     * `null` indicates a one-time timer (like `setTimeout`), otherwise behaves like `setInterval`.
+     *
+     * @since 1.1.0
+     */
+    interval: number | null;
+}
+
 /**
  * Imports
  */