@remotex-labs/xjet 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -33,17 +33,31 @@ import type { PromiseRejectType, PromiseResolveType } from '@remotex-labs/xjet-e
  */
 declare global {
     namespace xJet {
+        /**
+         * Mock
+         */
         const fn: typeof fnImplementation;
         const mock: typeof mockImplementation;
         const spyOn: typeof spyOnImplementation;
+        const clearAllMocks: () => void;
+        const resetAllMocks: () => void;
+        const restoreAllMocks: () => void;
+        /**
+         * Logs
+         */
         const log: typeof console.log;
         const info: typeof console.info;
         const warn: typeof console.warn;
         const error: typeof console.error;
         const debug: typeof console.error;
-        const clearAllMocks: () => void;
-        const resetAllMocks: () => void;
-        const restoreAllMocks: () => void;
+        /**
+         * Timers
+         */
+        const runAllTimers: typeof FakeTimer.runAllTimers;
+        const useFakeTimers: typeof FakeTimer.useFakeTimers;
+        const useRealTimers: typeof FakeTimer.useRealTimers;
+        const advanceTimersByTime: typeof FakeTimer.advanceTimersByTime;
+        const runOnlyPendingTimers: typeof FakeTimer.runOnlyPendingTimers;
     }
     const it: TestDirectiveInterface;
     const test: TestDirectiveInterface;
@@ -210,7 +224,6 @@ export declare class MockState<ReturnType = unknown, Args extends Array<unknown>
     /**
      * Flag to detect mock functions
      */
-    readonly isMock: boolean;
     readonly xJetMock: boolean;
     /**
      * The `state` property holds the detailed state of the mock invocations.
@@ -1192,6 +1205,430 @@ type ConstructorKeysType<T> = RemoveIndexType<keyof PropertiesWithConstructorsTy
  */
 type KeysExtendingConstructorType<T> = T extends ConstructorType ? keyof RemoveIndexType<T> : never;
 
+/**
+ * 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;
+}
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Marks a class as injectable and stores its configuration metadata.
+ *
+ * @template T - The type of the class instance
+ * @template Args - The types of arguments accepted by the constructor, defaults to `unknown[]`
+ *
+ * @param options - Optional configuration for the injectable, including scope and factory
+ *
+ * @example
+ * ```ts
+ * @Injectable({ scope: 'singleton' })
+ * class MyService {}
+ * ```
+ *
+ * @see InjectableOptionsInterface
+ * @since 1.0.0
+ */
+declare function Injectable<T = unknown, Args extends Array<unknown> = unknown[]>(options?: InjectableOptionsInterface): (target: new (...args: Args) => T) => void;
+/**
+ * Resolves and returns an instance of the given injectable token.
+ *
+ * @template T - The type of the instance to return
+ * @template Args - The types of arguments passed to the constructor or factory
+ *
+ * @param token - The injectable class or token to resolve
+ * @param args - Arguments to pass to the constructor or factory
+ *
+ * @returns The resolved instance of type `T`
+ *
+ * @throws Error - If the token is not registered as injectable via `@Injectable`
+ *
+ * @remarks
+ * If the injectable is marked with scope `'singleton'`, the same instance will be returned
+ * on the following calls. Otherwise, a new instance is created for each call.
+ *
+ * @example
+ * ```ts
+ * const service = inject(MyService);
+ * ```
+ *
+ * @see TokenElementType
+ * @since 1.0.0
+ */
+declare function inject<T, Args extends Array<unknown>>(token: TokenElementType<T, Args>, ...args: Args): T;
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Represents a constructor type for a given element.
+ *
+ * @template T - The type of the instance created by the constructor
+ * @template Args - The types of arguments accepted by the constructor, defaults to `unknown[]`
+ *
+ * @see FunctionType
+ * @since 1.0.0
+ */
+type TokenElementType<T, Args extends Array<unknown> = unknown[]> = new (...args: Args) => T;
+/**
+ * Options for configuring an injectable service.
+ *
+ * @remarks
+ * Used by the {@link Injectable} decorator to specify lifecycle scope
+ * and custom factory function for service instantiation.
+ *
+ * @since 1.0.0
+ */
+interface InjectableOptionsInterface {
+    /**
+     * Lifecycle scope of the service.
+     * - `'singleton'` - Only one instance is created and shared
+     * - `'transient'` - A new instance is created each time it is requested
+     *
+     * @default 'singleton'
+     * @since 1.0.0
+     */
+    scope?: 'singleton' | 'transient';
+    /**
+     * Custom factory function used to create the service instance.
+     * @since 1.0.0
+     */
+    factory?: FunctionType;
+}
+
 /**
  * Import will remove at compile time
  */
@@ -2102,93 +2539,6 @@ interface ContextInterface {
     afterAllErrors: Array<unknown>;
 }
 
-/**
- * Import will remove at compile time
- */
-/**
- * Marks a class as injectable and stores its configuration metadata.
- *
- * @template T - The type of the class instance
- * @template Args - The types of arguments accepted by the constructor, defaults to `unknown[]`
- *
- * @param options - Optional configuration for the injectable, including scope and factory
- *
- * @example
- * ```ts
- * @Injectable({ scope: 'singleton' })
- * class MyService {}
- * ```
- *
- * @see InjectableOptionsInterface
- * @since 1.0.0
- */
-declare function Injectable<T = unknown, Args extends Array<unknown> = unknown[]>(options?: InjectableOptionsInterface): (target: new (...args: Args) => T) => void;
-/**
- * Resolves and returns an instance of the given injectable token.
- *
- * @template T - The type of the instance to return
- * @template Args - The types of arguments passed to the constructor or factory
- *
- * @param token - The injectable class or token to resolve
- * @param args - Arguments to pass to the constructor or factory
- *
- * @returns The resolved instance of type `T`
- *
- * @throws Error - If the token is not registered as injectable via `@Injectable`
- *
- * @remarks
- * If the injectable is marked with scope `'singleton'`, the same instance will be returned
- * on the following calls. Otherwise, a new instance is created for each call.
- *
- * @example
- * ```ts
- * const service = inject(MyService);
- * ```
- *
- * @see TokenElementType
- * @since 1.0.0
- */
-declare function inject<T, Args extends Array<unknown>>(token: TokenElementType<T, Args>, ...args: Args): T;
-
-/**
- * Import will remove at compile time
- */
-/**
- * Represents a constructor type for a given element.
- *
- * @template T - The type of the instance created by the constructor
- * @template Args - The types of arguments accepted by the constructor, defaults to `unknown[]`
- *
- * @see FunctionType
- * @since 1.0.0
- */
-type TokenElementType<T, Args extends Array<unknown> = unknown[]> = new (...args: Args) => T;
-/**
- * Options for configuring an injectable service.
- *
- * @remarks
- * Used by the {@link Injectable} decorator to specify lifecycle scope
- * and custom factory function for service instantiation.
- *
- * @since 1.0.0
- */
-interface InjectableOptionsInterface {
-    /**
-     * Lifecycle scope of the service.
-     * - `'singleton'` - Only one instance is created and shared
-     * - `'transient'` - A new instance is created each time it is requested
-     *
-     * @default 'singleton'
-     * @since 1.0.0
-     */
-    scope?: 'singleton' | 'transient';
-    /**
-     * Custom factory function used to create the service instance.
-     * @since 1.0.0
-     */
-    factory?: FunctionType;
-}
-
 /**
  * Imports
  */