@remotex-labs/xjet 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,4790 @@
+
+/**
+ * This file was automatically generated by xBuild.
+ * DO NOT EDIT MANUALLY.
+ */
+ import type { xExpect } from '@remotex-labs/xjet-expect';
+import type { ConstructorLikeType, FunctionLikeType } from '@remotex-labs/xjet-expect';
+import type { FunctionLikeType, RejectedValueType, ResolvedValueType } from '@remotex-labs/xjet-expect';
+import type { ConstructorLikeType, FunctionType } from '@remotex-labs/xjet-expect';
+import type { ConstructorType } from '@remotex-labs/xjet-expect';
+import type { FunctionType } from '@remotex-labs/xjet-expect';
+import type { ContextType } from '@remotex-labs/xjet-expect';
+import type { FunctionLikeType } from '@remotex-labs/xjet-expect';
+import type { ContextType, FunctionType } from '@remotex-labs/xjet-expect';
+import { type ContextType, type FunctionLikeType, type FunctionType } from '@remotex-labs/xjet-expect';
+import type { Struct } from '@remotex-labs/xstruct';
+import { Struct } from '@remotex-labs/xstruct';
+import type { Options } from 'yargs';
+import type { BuildOptions } from 'esbuild';
+import type { PromiseRejectType, PromiseResolveType } from '@remotex-labs/xjet-expect';
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Exports types
+ */
+/**
+ * Exports modules
+ */
+/**
+ * Export global variables
+ */
+declare global {
+    namespace xJet {
+        const fn: typeof fnImplementation;
+        const mock: typeof mockImplementation;
+        const spyOn: typeof spyOnImplementation;
+        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;
+    }
+    const it: TestDirectiveInterface;
+    const test: TestDirectiveInterface;
+    const expect: typeof xExpect;
+    const describe: DescribeDirectiveInterface;
+    const afterAll: typeof afterAllDirective;
+    const beforeAll: typeof beforeAllDirective;
+    const afterEach: typeof afterEachDirective;
+    const beforeEach: typeof beforeEachDirective;
+}
+export {};
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Imports
+ */
+/**
+ * Retrieves the parent object of the specified function if it exists within the global context.
+ *
+ * @template FunctionLikeType - The type representing the input function.
+ *
+ * @param fn - The function whose parent object is to be retrieved.
+ * @returns The parent object containing the function, or `undefined` if no such object is found.
+ *
+ * @remarks
+ * This method searches for the parent object of a given function within the global context
+ * by checking if the function name exists as a key of an object in the global scope.
+ * If the function exists directly in the global scope, the global object itself is returned.
+ *
+ * @since 1.0.0
+ */
+declare function getParentObject(fn: FunctionLikeType): Record<string, unknown> | undefined;
+/**
+ * Creates a mock function interface with the specified implementation and optional restore function.
+ *
+ * @template ReturnType - The return type of the mocked function.
+ * @template Context - The context type that the mocked function binds to.
+ * @template Args - The argument type of the mocked function. Defaults to an array of unknown values.
+ *
+ * @param implementation - An optional implementation of the mocked function.
+ * @param restore - An optional restore function used to reset the mock.
+ * @returns A mocked function interface with the specified behaviors.
+ *
+ * @remarks
+ * This function creates a mock function handler, typically used in testing scenarios.
+ * You can provide an implementation for the mock behavior or specify a restore
+ * handler for resetting the mock's state.
+ *
+ * @example
+ * ```ts
+ * // Creating a mock with a custom implementation
+ * const mock = xJet.fn((x: number) => x * 2);
+ * console.log(mock(5)); // 10
+ *
+ * // Creating a mock with a restore function
+ * const mockWithRestore = xJet.fnImplementation(undefined, () => { console.log('Restored!'); });
+ * mockWithRestore.restore(); // "Restored!"
+ * ```
+ *
+ * @see MockState
+ *
+ * @since 1.0.0
+ */
+declare function fnImplementation<ReturnType, Args extends Array<unknown>, Context>(implementation?: FunctionLikeType<ReturnType, Args, Context>, restore?: FunctionLikeType<void>): FnMockInterface<ReturnType, Args, Context>;
+/**
+ * Creates a mock instance for the given method or constructor.
+ *
+ * @template Method - The type of the method being mocked.
+ * @template Context - The `this` context type of the method.
+ * @template Args - The types of the arguments accepted by the method.
+ *
+ * @param method - The method or constructor to mock. This can either be a function-like type or a
+ * constructor-like type.
+ * @returns A `MockState` instance associated with the provided method, allowing for capturing
+ * interactions and controlling behavior during testing.
+ *
+ * @remarks
+ * This method identifies whether the provided method is a function or constructor and creates
+ * a suitable mock state. If the method is already mocked, the existing mock state is returned.
+ * Throws an error if the method does not belong to an object or if it has an invalid type.
+ *
+ * @example
+ * ```ts
+ * // Mocking a regular method
+ * function greet(name: string) {
+ *     return `Hello, ${ name }`;
+ * }
+ *
+ * const greetMock = xJet.mock(greet);
+ * greetMock.mockImplementation(() => 'Hi!');
+ * console.log(greet('World')); // "Hi!"
+ *
+ * // Mocking a constructor
+ * class Person {
+ *     constructor(public name: string) {}
+ * }
+ * const personMock = xJet.mock(Person);
+ * personMock.mockImplementation((name: string) => ({ name: `${name} (mocked)` }));
+ * const person = new Person('Alice');
+ * console.log(person.name); // "Alice (mocked)"
+ *
+ * // Restoring the original method
+ * greetMock.mockRestore();
+ * console.log(greet('World')); // "Hello, World"
+ * ```
+ *
+ * @since 1.0.0
+ */
+declare function mockImplementation<Method, Args extends Array<unknown>, Context>(method: FunctionLikeType<Method, Args, Context> | ConstructorLikeType<Method, Args>): MockState<Method, Args, Context>;
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Represents a mockable function interface with a customizable return type, context,
+ * and argument list. This interface extends `MockState` to facilitate tracking
+ * and testing of function behaviors and states.
+ *
+ * @template ReturnType - Specifies the return type of the function. Defaults to `unknown`.
+ * @template Context - Defines the function's "this" context type. Defaults to `unknown`.
+ * @template Args - Sets the argument type(s) for the function, represented as an array. Defaults to `unknown[]`.
+ *
+ * @remarks
+ * This interface is useful for creating test doubles or mock implementations that simulate
+ * complex behaviors (allows for both `function-like` behavior and `constructor-like` behavior)
+ * while tracking interactions and state information.
+ *
+ * @see MockState
+ *
+ * @since 1.0.0
+ */
+interface FnMockInterface<ReturnType = unknown, Args extends Array<unknown> = any, Context = any> extends MockState<ReturnType, Args, Context> {
+    new (...args: Args): ReturnType;
+    (this: Context, ...args: Args): ReturnType;
+}
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * A class representing the mock state for tracking and managing the behavior of mocked functions or classes.
+ *
+ * @template ReturnType - The type of value returned by the mock function.
+ * @template Context - The type representing the context (`this` value) used in the mock function.
+ * @template Args - The types of arguments for the mocked function.
+ *
+ * @remarks
+ * This class provides mechanisms to customize and manage the behavior of mocked functions or constructors.
+ * It tracks invocation details, allows for behavior customization, and enables resetting or restoring the mock to its original state.
+ *
+ * @since v1.0.0
+ */
+export declare class MockState<ReturnType = unknown, Args extends Array<unknown> = unknown[], Context = unknown> extends Function {
+    /**
+     * List of all mocks that created
+     */
+    static mocks: Array<MockState>;
+    /**
+     * The `name` property represents the name of the mock function.
+     */
+    name: string;
+    /**
+     * Flag to detect mock functions
+     */
+    readonly isMock: boolean;
+    readonly xJetMock: boolean;
+    /**
+     * The `state` property holds the detailed state of the mock invocations.
+     * It tracks information such as the arguments passed, the results returned, the context (`this` value) used,
+     * the instances created, and the order of invocations.
+     * This data is automatically updated after each call to the mock.
+     *
+     * @template ReturnType - The type of value returned by the mock function.
+     * @template Context - The type representing the context (`this` value) used in the mock function.
+     * @template Args - The types of arguments for the mocked function.
+     *
+     * @see MocksStateInterface
+     *
+     * @since v1.0.0
+     */
+    private state;
+    /**
+     * A private function that restores the mocks original implementation.
+     * It resets the mock to its initial state, typically used when restoring
+     * the mock after a call to `mockReset` or `mockRestore`.
+     *
+     * This function is invoked internally to ensure that the mock behaves as
+     * originally defined before any changes were made to its behavior or implementation.
+     *
+     * @since v1.0.0
+     */
+    private readonly restore;
+    /**
+     * A private array that stores the implementations queued to be executed
+     * for future invocations of the mock.
+     * Each function in this array is invoked in sequence when the mock function is called,
+     * with the first queued implementation being used on the first call, the second on the second call, and so on.
+     *
+     * This property is used in conjunction with methods like `mockImplementationOnce`
+     * to specify different behaviors for consecutive calls to the mock.
+     *
+     * @since v1.0.0
+     */
+    private queuedImplementations;
+    /**
+     * A private property that holds the current implementation of the mock function.
+     * This function is executed whenever the mock is invoked, and can be changed
+     * using methods like `mockImplementation` or `mockImplementationOnce`.
+     *
+     * The `implementation` allows for customizing the behavior of the mock,
+     * such as returning specific values, throwing errors, or performing actions.
+     *
+     * @since v1.0.0
+     */
+    private implementation;
+    /**
+     * A private property that holds the original implementation of the mock function.
+     * This is the initial function passed to the constructor that defines the mock's default behavior
+     * before any customization.
+     *
+     * @template ReturnType - The type of value returned by the original function.
+     * @template Args - The types of arguments for the original function.
+     * @template Context - The type representing the context (`this` value) used in the original function.
+     *
+     * @remarks
+     * This property stores the initial implementation provided when creating the mock.
+     * If no implementation is provided during construction, it defaults to a function
+     * that returns `undefined` cast to the appropriate return type.
+     * Unlike `implementation` which can be modified, this property maintains a reference
+     * to the original function for scenarios where the original behavior needs to be preserved
+     * or restored.
+     *
+     * @see FunctionLikeType
+     * @see MockState.original
+     *
+     * @since 1.0.0
+     */
+    private readonly originalImplementation;
+    /**
+     * Constructs a mock object that allows custom implementation, restore capability,
+     * and optional naming functionality. This mock is proxied to handle function invocation
+     * and class instantiation.
+     *
+     * @template ReturnType - The type of the value returned by the mock function.
+     * @template Context - The type of the context (`this`) for the mock function.
+     * @template Args - The type of arguments accepted by the mock function.
+     *
+     * @param implementation - Optional implementation for the mock function.
+     * @param restore - Optional function to restore the mock to its initial state. Defaults to resetting to the provided implementation.
+     * @param name - Optional name for the mock instance. Default to a predefined mock name if not provided.
+     *
+     * @returns A proxied mock object capable of behaving as a callable function or a constructible class.
+     *
+     * @remarks
+     * The mock object can work as both a function and a class, using JavaScript's Proxy API. The restore functionality
+     * allows resetting to the original state or implementation. If no implementation is provided, the mock remains uninitialized
+     * but still functional.
+     *
+     * @see FunctionLikeType
+     * @see VoidFunctionType
+     *
+     * @since 1.0.0
+     */
+    constructor(implementation?: FunctionLikeType<ReturnType, Args, Context>, restore?: FunctionLikeType<void>, name?: string);
+    /**
+     * todo remove it
+     * only for jest expect will support this mock
+     */
+    getMockName(): string;
+    /**
+     * Retrieves the current state of mocks.
+     *
+     * @return The current state of the mocks.
+     * @see MocksStateInterface
+     *
+     * @since 1.0.0
+     */
+    get mock(): Readonly<MocksStateInterface<ReturnType, Args, Context>>;
+    /**
+     * Returns the original implementation of the function that was instrumented
+     *
+     * @returns The original function implementation that was wrapped or modified
+     *
+     * @remarks
+     * This getter provides access to the unmodified function that was originally passed
+     * to the instrumentation system. Useful for debugging, testing, or when you need
+     * to bypass the instrumented behavior temporarily.
+     *
+     * @example
+     * ```ts
+     * const mockFn = jest.fn(x => x * 2);
+     * // Later in test
+     * const originalImplementation = mockFn.original;
+     * expect(originalImplementation(5)).toBe(10);
+     * ```
+     *
+     * @see FunctionLikeType
+     *
+     * @since 1.0.0
+     */
+    get original(): FunctionLikeType<ReturnType, Args, Context>;
+    /**
+     * Clears the `mock.calls`, `mock.results`, `mock.contexts`, `mock.instances`, and `mock.invocationCallOrder` properties.
+     *
+     * @returns The current instance of the mock, allowing for method chaining.
+     *
+     * @remarks
+     * This method resets the state of the mock function, clearing all invocation data and results,
+     * ensuring that previous mock states do not affect the following tests.
+     * Equivalent to calling `.mockClear()` on every mocked function.
+     *
+     * @see MockState.initState
+     *
+     * @since v1.0.0
+     */
+    mockClear(): this;
+    /**
+     * Resets the mock function to its initial state.
+     *
+     * @returns The current instance of the mock, allowing for method chaining.
+     *
+     * @remarks
+     * The `mockReset` method clears all invocation data and results by calling `mockClear()`, and also resets
+     * the queued implementations,
+     * removing any previously queued behavior set by methods like `mockImplementationOnce`.
+     * This ensures that the mock is in a clean state and ready for new invocations or configurations.
+     *
+     * @see MockState.mockClear
+     *
+     * @since v1.0.0
+     */
+    mockReset(): this;
+    /**
+     * Restores the mock function to its original implementation and resets its state.
+     *
+     * @returns The current instance of the mock, allowing for method chaining.
+     *
+     * @remarks
+     * The `mockRestore` method does two things:
+     * 1. It restores the mock to its initial implementation, which was set during the mocks creation or
+     *    via the `mockImplementation` method.
+     * 2. It clears all tracking data, such as calls, results, contexts, instances, and invocation call order
+     *    by calling `mockReset()`, ensuring the mock is fully reset and ready for new invocations.
+     *
+     * This method is useful for ensuring that the mock is completely restored and cleared, making it behave as it did
+     * when it was first created or last restored.
+     *
+     * @see MockState.restore
+     * @see MockState.mockReset
+     *
+     * @since v1.0.0
+     */
+    mockRestore(): this;
+    /**
+     * Retrieves the mock implementation for a function, if available.
+     *
+     * @template ReturnType The type of the return value of the function.
+     * @template Context The type of the `this` context for the function.
+     * @template Args The type of the argument(s) of the function.
+     *
+     * @return A function matching `FunctionLikeType` that represents the mock implementation,
+     * or `undefined` if no implementation is set.
+     *
+     * @remarks
+     * This method returns the mock implementation associated with the instance.
+     * If no mock implementation exists, it returns `undefined`.
+     *
+     * @since 1.0.0
+     */
+    getMockImplementation(): FunctionLikeType<ReturnType, Args, Context> | undefined;
+    /**
+     * Retrieves the next implementation from the queued implementations or defaults to the current implementation.
+     *
+     * @template ReturnType The return type of the function-like implementation.
+     * @template Context     The context in which the implementation executes.
+     * @template Args        The argument types expected by the implementation.
+     *
+     * @return The next implementation from the queue if available, or the current implementation.
+     * Returns are `undefined` if no implementation is found.
+     *
+     * @remarks
+     * This method first checks if there are any queued implementations available.
+     * If a queued implementation exists, it will be removed from the queue and returned.
+     * If the queue is empty, the primary current implementation is returned.
+     * Returns are `undefined` if there is no implementation available.
+     *
+     * @since 1.0.0
+     */
+    getNextImplementation(): FunctionLikeType<ReturnType, Args, Context> | undefined;
+    /**
+     * Replaces the default implementation of a mock function with the provided function.
+     *
+     * @template ReturnType - The type of the value returned by the implementation function.
+     * @template Context - The context (`this`) expected by the implementation function.
+     * @template Args - The types of the arguments expected by the implementation function.
+     *
+     * @param fn - The function to be used as the mock implementation. It defines
+     * the behavior of the mock when called.
+     *
+     * @return Returns the instance of the current object for method chaining.
+     *
+     * @remarks
+     * This method is useful when you need to mock the behavior of a function
+     * dynamically during tests or in controlled scenarios.
+     *
+     * @since 1.0.0
+     */
+    mockImplementation(fn: FunctionLikeType<ReturnType, Args, Context>): this;
+    /**
+     * Sets a mock implementation that will be used once for the next call to the mocked function.
+     *
+     * @template ReturnType The type of the value that the mock function will return.
+     * @template Context The type of the `this` context for the mock function.
+     * @template Args The type of arguments that the mock function will receive.
+     *
+     * @param fn - The function to be used as the mock implementation for the next call.
+     * @returns The current instance, allowing for chaining of mock configurations.
+     *
+     * @remarks
+     * The provided mock implementation will only be executed once. Further calls will fall back
+     * to a different implementation, if provided, or the default behavior of the mock function.
+     *
+     * @example
+     * ```ts
+     * const mockFn = new MockState();
+     *
+     * // Set default implementation
+     * mockFn.mockImplementation(() => 'default');
+     *
+     * // Set one-time behavior for the next call
+     * mockFn.mockImplementationOnce(() => 'first call');
+     *
+     * console.log(mockFn()); // Output: 'first call' (from mockImplementationOnce)
+     * console.log(mockFn()); // Output: 'default' (from mockImplementation)
+     * ```
+     *
+     * @see FunctionLikeType
+     *
+     * @since 1.0.0
+     */
+    mockImplementationOnce(fn: FunctionLikeType<ReturnType, Args, Context>): this;
+    /**
+     * Sets a mock implementation to always return a specified value when invoked.
+     *
+     * @template ReturnType The type of the value returned by the mock implementation.
+     *
+     * @param value - The value to always return when the mock function is called.
+     * @return The current instance for chaining.
+     *
+     * @remarks
+     * This method overrides any previous mock implementation configured for the function.
+     *
+     * @example
+     * ```ts
+     * const mockFn = new MockState();
+     *
+     * // Set mock to return 'Hello World' on each call
+     * mockFn.mockReturnValue('Hello World');
+     *
+     * console.log(mockFn()); // Output: 'Hello World'
+     * console.log(mockFn()); // Output: 'Hello World'
+     * ```
+     *
+     * @since 1.0.0
+     */
+    mockReturnValue(value: ReturnType): this;
+    /**
+     * Sets up a mock function to always resolve a promise with the specified value when called.
+     *
+     * @template ResolvedValueType - The type of the value to be resolved by the promise.
+     * @template ReturnType - The return type of the function, which should include a Promise of the specified resolved value type.
+     *
+     * @param value - The value to be returned as the resolved value of the promise.
+     * @returns The mock function instance, enabling method chaining.
+     *
+     * @remarks
+     * This method is particularly useful for mocking asynchronous functions that return promises.
+     * It ensures that the mock function resolves with the provided value every time it is called.
+     *
+     * @example
+     * ```ts
+     * const mockFn = new MockState<Promise<string>>();
+     *
+     * // Set mock to return a resolved promise with the value 'Success'
+     * mockFn.mockResolvedValue('Success');
+     *
+     * mockFn().then((result: string) => {
+     *     console.log(result); // Output: 'Success'
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
+    mockResolvedValue(value: ResolvedValueType<ReturnType>): this;
+    /**
+     * Sets a mock implementation for a single call that resolves to the specified value.
+     *
+     * @template ReturnType The type of the resolved value.
+     * @template ResolvedValueType The type of the input value to be resolved.
+     *
+     * @param value - The value that the promise should resolve with when the mock is called once.
+     * @return The current mock object instance, enabling method chaining.
+     *
+     * @remarks
+     * This method is useful for defining custom behavior for a specific invocation of a mocked function,
+     * returning a resolved promise with the provided value.
+     *
+     * @example
+     * ```ts
+     * const mockFn = new MockState(async () => {
+     *     return 'end';
+     * });
+     *
+     * // Set mock to return a resolved promise with the value 'Success'
+     * mockFn.mockResolvedValueOnce('Success');
+     *
+     * mockFn().then((result: string) => {
+     *     console.log(result); // Output: 'Success'
+     * });
+     *
+     * mockFn().then((result: string) => {
+     *     console.log(result); // Output: 'end'
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
+    mockResolvedValueOnce(value: ResolvedValueType<ReturnType>): this;
+    /**
+     * Sets the return value of the mock function for a single call.
+     *
+     * @template ReturnType The type of the value to be returned.
+     *
+     * @param value - The value to be returned by the mock function for the next call.
+     * @return The mock function instance, allowing for method chaining.
+     *
+     * @remarks
+     * This method only affects the return value for the next call to the mock function.
+     * All further calls will use the usual mock implementation or other specified behaviors.
+     *
+     * @example
+     * ```ts
+     * const mockFn = new MockState();
+     *
+     * // Set default return value
+     * mockFn.mockReturnValue('Default Value');
+     *
+     * // Set one-time return value for the next call
+     * mockFn.mockReturnValueOnce('First Call');
+     * mockFn.mockReturnValueOnce('Second Call');
+     *
+     * console.log(mockFn()); // Output: 'First Call' (from mockReturnValueOnce)
+     * console.log(mockFn()); // Output: 'Second Call' (from mockReturnValueOnce)
+     * console.log(mockFn()); // Output: 'Default Value' (from mockReturnValue)
+     * ```
+     *
+     * @since 1.0.0
+     */
+    mockReturnValueOnce(value: ReturnType): this;
+    /**
+     * Mocks the method to always return a rejected Promise with the specified value.
+     *
+     * @template ReturnType - The expected type of the return value for the mocked method.
+     * @template RejectedValueType - The type of the value used to reject the Promise.
+     *
+     * @param value - The value with which the mocked Promise will be rejected.
+     *
+     * @return The current instance of the mock for chaining purposes.
+     *
+     * @remarks
+     * This method is useful for testing scenarios where the function being mocked
+     * is expected to reject with a specific value.
+     *
+     * @example
+     * ```ts
+     * const mockFn = new MockState<Promise<string>>();
+     *
+     * // Set mock to return a rejected promise with the value 'Error'
+     * mockFn.mockRejectedValue('Error');
+     *
+     * mockFn().catch(error => {
+     *     console.log(error); // Output: 'Error'
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
+    mockRejectedValue(value: RejectedValueType<ReturnType>): this;
+    /**
+     * Adds a one-time rejection with the provided value to the mock function.
+     *
+     * @template ReturnType - The type of the value the mock function would return.
+     *
+     * @param value - The value to reject the promise with in the mock function.
+     * @return The current instance of the mock function, allowing for method chaining.
+     *
+     * @remarks
+     * This method configures a mock function to return a rejected promise with the
+     * specified value the next time it is called. After the rejection occurs, the
+     * mock function's behavior will revert to the next defined mock behavior, or
+     * to the default behavior if no behaviors are defined.
+     *
+     * @example
+     * ```ts
+     * const mockFn = new MockState<Promise<string>>();
+     *
+     * // Set default rejected value
+     * mockFn.mockRejectedValue('Default Error');
+     *
+     * // Set one-time rejected value for the next call
+     * mockFn.mockRejectedValueOnce('First Call Error');
+     *
+     * mockFn().catch(error => {
+     *     console.log(error); // Output: 'First Call Error' (from mockRejectedValueOnce)
+     * });
+     *
+     * mockFn().catch(error => {
+     *     console.log(error); // Output: 'Default Error' (from mockRejectedValue)
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
+    mockRejectedValueOnce(value: RejectedValueType<ReturnType>): this;
+    /**
+     * Initializes and returns the state object for mock function tracking.
+     *
+     * @return An object containing the initialized mock function state.
+     *
+     * @remarks
+     * The state object contains the structure necessary to keep track of
+     * calls, results, contexts, instances, and invocation orders of the function.
+     *
+     * @see MocksStateInterface
+     *
+     * @since v1.0.0
+     */
+    private initState;
+    /**
+     * Invokes the next implementation of a mock function with the provided context and arguments.
+     *
+     * @template Context The type of `this` context in which the function is invoked.
+     * @template Args The type of the arguments passed to the function.
+     * @template ReturnType The type of the return value, of the function being invoked.
+     *
+     * @param thisArg - The context (`this`) in which the function is executed.
+     * @param args - The arguments to be passed to the function.
+     *
+     * @returns The result of the function invocation, which is either the return value, the thrown error, or undefined.
+     *
+     * @remarks
+     * This method simulates the function call for a mocked implementation. It tracks all invocations,
+     * including the call order, the provided arguments, and the context. It handles binding, default
+     * arguments, and maintains a record of results (either successful returns or thrown errors).
+     *
+     * @since 1.0.0
+     */
+    private invoke;
+    /**
+     * Invokes a function within a specific context and with provided arguments.
+     *
+     * @template Context The type of the context in which the function is invoked.
+     * @template Args The type of the arguments passed to the function.
+     * @template ReturnType The type of the value that the invoked function returns.
+     *
+     * @param target - The instance of the class containing the method to be invoked.
+     * @param thisArg - The context object that will be bound to the invoked function.
+     * @param argumentsList - The list of arguments to pass to the invoked function.
+     * @returns The result of the invoked function or `undefined` if no value is returned.
+     *
+     * @remarks
+     * This method modifies the state of the `target` instance by adding the `thisArg`
+     * to the `target.state.instances` array before invoking the function.
+     *
+     * @since 1.0.0
+     */
+    private invokeFunction;
+    /**
+     * Invokes a class method on the provided target with specified arguments and a new target.
+     *
+     * @template Args - The type of arguments to be passed to the invoked method.
+     *
+     * @param target - The object on which the class method is invoked.
+     * @param argArray - The array of arguments to pass to the invoked method.
+     * @param newTarget - The new object used as the invocation context.
+     * @returns The result of the invocation, typically an object. If the result is not an object,
+     *          the `newTarget` is returned instead.
+     *
+     * @remarks
+     * This method ensures that the result is stored in the `instances` array of the target's state
+     * if it is detected as a proper class instance. Otherwise, the `newTarget` is registered.
+     *
+     * @since 1.0.0
+     */
+    private invokeClass;
+}
+
+/**
+ * Represents an interface for defining bound context and arguments.
+ *
+ * @template Context - The type of the bound `this` context, which can be an object, null, or undefined.
+ * @template Args - The type of the array representing bound arguments.
+ *
+ * @remarks
+ * This interface is designed to store binding metadata, specifically a reference to the bound `this` context
+ * and any arguments that are pre-applied during function binding. It is often used in scenarios involving
+ * dynamic contexts or partial application of functions.
+ *
+ * @see ContextType
+ *
+ * @since 1.0.0
+ */
+interface BoundInterface<Context = unknown | null | undefined, Args = Array<unknown>> {
+    __boundThis?: Context;
+    __boundArgs?: Args;
+}
+
+/**
+ * Represents the possible result types of a mock function invocation.
+ *
+ * @template 'return' | 'throw' | 'incomplete'
+ *
+ * @since 1.0.0
+ */
+type MockInvocationResultType = 'return' | 'throw' | 'incomplete';
+/**
+ * Represents the result of a mock function invocation, providing details regarding the outcome,
+ * such as whether the function returned a value, threw an error, or did not complete its execution.
+ *
+ * @template T - Specifies the expected return type of the mock function when the result is of type `'return'`.
+ *
+ * @remarks
+ * This interface is useful in mock testing frameworks to analyze the behavior of mocked functions
+ * and their respective invocation outcomes.
+ *
+ * @since 1.0.0
+ */
+interface MockInvocationResultInterface<T> {
+    /**
+     * Indicates the result type:
+     * - `'return'`: The mock function successfully returned a value.
+     * - `'throw'`: The mock function threw an error or exception.
+     * - `'incomplete'`: The mock function invocation has not been completed (rare case).
+     *
+     * @see MockInvocationResultType
+     *
+     * @since 1.0.0
+     */
+    type: MockInvocationResultType;
+    /**
+     * The value associated with the invocation result:
+     * - If `type` is `'return'`, this is the mocks return value (`T`).
+     * - If `type` is `'throw'`, this is the thrown error (`unknown`).
+     * - If `type` is `'incomplete'`, this is `undefined`.
+     *
+     * @since 1.0.0
+     */
+    value: T | (unknown & {
+        type?: never;
+    }) | undefined | unknown;
+}
+/**
+ * Interface representing the internal state of a mock function, tracking details of its invocations,
+ * such as arguments, contexts, return values, and more.
+ *
+ * @template ReturnType - The type of value returned by the mock function.
+ * @template Context - The type of the `this` context used during the mocks execution. Defaults to `DefaultContextType`.
+ * @template Args - The type of arguments passed to the mock function. Default to an array of unknown values (`Array<unknown>`).
+ *
+ * @remarks
+ * This interface is designed to provide detailed tracking of mocks behavior,
+ * including call arguments, contexts, instances, invocation order, and results.
+ * Useful for testing and debugging in scenarios that require precise information about mock execution.
+ *
+ * @since 1.0.0
+ */
+interface MocksStateInterface<ReturnType, Args extends Array<unknown> = [], Context = unknown> {
+    /**
+     * An array that holds the arguments for each invocation made to the mock.
+     * Each entry corresponds to the arguments passed during a single call to the mock function.
+     *
+     * @since 1.0.0
+     */
+    calls: Array<Args>;
+    /**
+     * The arguments passed to the mock during its most recent invocation.
+     * Returns `undefined` if the mock has not been called yet.
+     *
+     * @since 1.0.0
+     */
+    lastCall?: Args;
+    /**
+     * An array of contexts (`this` values) for each invocation made to the mock.
+     * Each entry corresponds to the context in which the mock was called.
+     *
+     * @since 1.0.0
+     */
+    contexts: Array<Context>;
+    /**
+     * An array of all object instances created by the mock.
+     * Each entry represents an instance was instantiated during the mocks invocations.
+     *
+     * @since 1.0.0
+     */
+    instances: Array<Context>;
+    /**
+     * An array of invocation order indices for the mock.
+     * xJet assigns an index to each call, starting from 1, to track the order in which mocks are invoked within a test file.
+     *
+     * @since 1.0.0
+     */
+    invocationCallOrder: Array<number>;
+    /**
+     * An array of results for each invocation made to the mock.
+     * Each entry represents the outcome of a single call, including the return value or any error thrown.
+     *
+     * @since 1.0.0
+     */
+    results: Array<MockInvocationResultInterface<ReturnType>>;
+}
+
+/**
+ * A base error class that extends the standard Error class with enhanced JSON serialization and location tracking
+ *
+ * @param message - The error message describing what went wrong
+ * @param location - The precise source code location where the error occurred
+ * @returns The constructed ExecutionError instance
+ *
+ * @remarks
+ * Serves as a foundation for custom error types in the application.
+ * It enhances the native Error object by adding JSON serialization capabilities
+ * and source code location information, allowing for better error reporting,
+ * debugging, and troubleshooting. The location tracking feature helps pinpoint
+ * exactly where in the codebase an error originated.
+ *
+ * @example
+ * ```ts
+ * // Creating a basic execution error with location information
+ * const error = new ExecutionError(
+ *   'Failed to process data',
+ *   { line: 42, column: 10 }
+ * );
+ *
+ * // The error can be thrown or used in promise rejection
+ * throw error;
+ * ```
+ *
+ * @see InvocationLocationType
+ *
+ * @since 1.0.0
+ */
+declare class ExecutionError extends Error {
+    /**
+     * Creates a new ExecutionError instance with the specified error message and source code location
+     *
+     * @param message - The error message describing what went wrong
+     *
+     * @remarks
+     * This constructor initializes both the standard Error message property and the location
+     * information that helps pinpoint exactly where in the codebase the error originated. The
+     * location parameter follows the InvocationLocationType structure, typically containing
+     * line and column information.
+     *
+     * @example
+     * ```ts
+     * const error = new ExecutionError(
+     *   'Failed to process input data',
+     *   { line: 42, column: 8 }
+     * );
+     * ```
+     *
+     * @since 1.0.0
+     */
+    constructor(message: string);
+    /**
+     * Converts the error instance to a plain JavaScript object for JSON serialization.
+     *
+     * @returns A plain object containing all properties of the error.
+     *
+     * @remarks
+     * This method enhances error serialization by ensuring all properties from the error
+     * instance are properly included in the resulting JSON representation. The standard
+     * `JSON.stringify()` method doesn't properly serialize Error objects by default, as
+     * their properties are typically not enumerable.
+     *
+     * @example
+     * ```ts
+     * const error = new ExecutionError('Something went wrong');
+     * error.code = 'ERR_INVALID_INPUT';
+     *
+     * // Convert to JSON
+     * const serialized = JSON.stringify(error);
+     * // Result includes all properties: message, name, stack, code, etc.
+     * ```
+     *
+     * @since 1.0.0
+     */
+    toJSON(): Record<string, unknown>;
+}
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Imports
+ */
+/**
+ * Intercepts and mocks the property descriptor of a specified property on a target object.
+ *
+ * @template Target - The target object type.
+ * @template Key - The key of the property to be mocked.
+ *
+ * @param target - The object whose property descriptor is being intercepted and mocked.
+ * @param key - The property key on the target object to spy on.
+ * @return A `MockState` instance that provides control over the mocked property and its interactions.
+ *
+ * @remarks
+ * This function replaces the property's getter and setter to allow interception and testing of their behavior.
+ * A `MockState` instance is returned to control and observes mocked behavior.
+ *
+ * @since 1.0.0
+ */
+declare function spyOnDescriptorProperty<Target, Key extends keyof Target>(target: Target, key: Key): MockState<Target[Key], []>;
+/**
+ * Creates a spy on a specified static method or static property of a target class (not a class instance).
+ * Useful for mocking behavior during testing.
+ *
+ * @template Target - The type of the target class.
+ * @template Key - The static method or static property key on the target object to spy on.
+ *
+ * @param target - The object on which to spy.
+ * @param key - The key of the method or property of the target to spy on.
+ * @returns If the spied-on property is a function, returns a `MockState` object for the function,
+ * allowing tracking of calls and modifying the return value or behavior.
+ * Otherwise, returns a `MockState` object for the property, enabling tracking and manipulation of its value.
+ *
+ * @throws Error Throws an error if the `target` is a primitive value.
+ * @throws Error Throws an error if `key` is null or undefined.
+ * @throws Error Throws an error if the specified property does not exist on the target object.
+ *
+ * @remarks
+ * This function is commonly used in testing environments to replace or monitor functionality without
+ * altering the actual logic in the source code. It provides fine-grained control over target behavior.
+ *
+ * @example
+ * ```ts
+ * class ClassTest {
+ *     static name: string = 'ClassTest';
+ *
+ *     static x(param: string) {
+ *         console.log(`original static x ${ param }`);
+ *     }
+ * }
+ *
+ * const spy1 = xJet.spyOn(ClassTest, 'name');
+ * const spy2 = xJet.spyOn(ClassTest, 'x');
+ *
+ * spy1.mockReturnValueOnce('Mock name');
+ * spy2.mockImplementationOnce((param: string) => {
+ *     console.log(`Mock x ${ param }`);
+ * });
+ *
+ * console.log(ClassTest.name); // Mock name
+ * console.log(ClassTest.name); // ClassTest
+ *
+ * ClassTest.x('test1'); // Mock x test1
+ * ClassTest.x('test2'); // original static x test2
+ * ```
+ *
+ * @see FunctionType
+ * @see KeysExtendingConstructorType
+ *
+ * @since 1.0.0
+ */
+declare function spyOnImplementation<Target, Key extends KeysExtendingConstructorType<Target>>(target: Target, key: Key): Target[Key] extends FunctionType ? MockState<ReturnType<Target[Key]>, Parameters<Target[Key]>, Target> : MockState<Target[Key], [], Target>;
+/**
+ * Creates a mock spy on the specified method or constructor of the target object.
+ *
+ * @template Target The type of the target object.
+ * @template Key The type of the method or constructor key on the target object.
+ *
+ * @param target - The object whose method or constructor needs to be spied on.
+ * @param key - The property key of the method or constructor to spy on.
+ * @return A mock state representing the spied method or constructor if the key corresponds to a constructor type;
+ * otherwise, throws a type error.
+ *
+ * @throws Error Throws an error if the `target` is a primitive value.
+ * @throws Error Throws an error if `key` is null or undefined.
+ * @throws Error Throws an error if the specified property does not exist on the target object.
+ *
+ * @remarks
+ * This method is typically used for testing purposes to observe or manipulate calls to the method or constructor of an object.
+ * The returned mock state may allow additional configuration, such as altering its behavior or tracking calls.
+ *
+ * @example
+ * ```ts
+ * const coolObject = {
+ *     ClassTest: class {
+ *         constructor(param: number) {
+ *             console.log('original Constructor');
+ *         }
+ *
+ *         justAnFunction() {
+ *             console.log('original justAnFunction');
+ *         }
+ *     }
+ * };
+ *
+ * const spy = xJet.spyOn(coolObject, 'ClassTest');
+ * spy.mockImplementationOnce((param: number) => {
+ *     console.log(`mock Constructor with param: ${ param }`);
+ *
+ *     return <any> {
+ *         justAnFunction() {
+ *             console.log('mock justAnFunction');
+ *         }
+ *     };
+ * });
+ *
+ * const instance = new coolObject.ClassTest(1); // mock Constructor with param: 1
+ * instance.justAnFunction(); // mock justAnFunction
+ *
+ * const instance2 = new coolObject.ClassTest(2); // original Constructor
+ * instance2.justAnFunction(); // original justAnFunction
+ * ```
+ *
+ * @see ConstructorType
+ * @see ConstructorKeysType
+ *
+ * @since 1.0.0
+ */
+declare function spyOnImplementation<Target, Key extends ConstructorKeysType<Target>>(target: Target, key: Key): Target[Key] extends ConstructorLikeType ? MockState<InstanceType<Target[Key]>, ConstructorParameters<Target[Key]>, Target> : never;
+/**
+ * Creates a spy on a specific method or property of the given target object.
+ *
+ * @template Target - The type of the target object to spy on.
+ * @template Key - The key of the property or method to spy on within the target object.
+ *
+ * @param target - The target object containing the property or method to be spied upon.
+ * @param key - The name of the property or method on the target object to spy on.
+ * @returns If the spied target is a function, it returns a `MockState` object to observe calls and arguments of the function.
+ *          Otherwise, it returns a `MockState` object to observe the value or state of the property.
+ *
+ * @throws Error Throws an error if the `target` is a primitive value.
+ * @throws Error Throws an error if `key` is null or undefined.
+ * @throws Error Throws an error if the specified property does not exist on the target object.
+ *
+ * @remarks This method is commonly used in test environments to monitor and assert interactions with a specific property
+ *          or method on an object. The returned `MockState` can be used to retrieve call history or observe mutations.
+ *
+ * @example
+ * ```ts
+ * const coolObject = {
+ *     myMethod() {
+ *         return 'Original myMethod';
+ *     },
+ *     coolString: 'Original coolString'
+ * };
+ *
+ * const spy = xJet.spyOn(coolObject, 'coolString');
+ * const spy2 = xJet.spyOn(coolObject, 'myMethod');
+ *
+ * spy.mockImplementationOnce(() => 'mock coolString');
+ * spy2.mockImplementationOnce(() => 'mock myMethod string');
+ *
+ * console.log(coolObject.coolString); // mock coolString
+ * console.log(coolObject.coolString); // Original coolString
+ * console.log(coolObject.myMethod()); // mock myMethod string
+ * console.log(coolObject.myMethod()); // Original myMethod
+ * ```
+ *
+ * @see FunctionType
+ *
+ * @since 1.0.0
+ */
+declare function spyOnImplementation<Target, Key extends keyof Target>(target: Target, key: Key): Target[Key] extends FunctionType ? MockState<ReturnType<Target[Key]>, Parameters<Target[Key]>, ThisParameterType<Target[Key]>> : MockState<Target[Key] | void, [Target[Key]], ThisParameterType<Target[Key]>>;
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * A utility type that removes all index signatures (string and number keys) from the given type `T`.
+ * This results in a new type that retains only explicitly defined properties.
+ *
+ * @template T - The type from which index signatures are to be removed.
+ *
+ * @remarks
+ * This type is useful for filtering out index signatures from types, especially when working
+ * with mapped or dynamic types where indexable properties are not desired.
+ * When an object has an index signature (e.g., `[key: string]: any`), TypeScript assumes that all
+ * possible string or number keys exist on the object. This utility type filters out such keys,
+ * leaving only explicitly defined properties.
+ *
+ * @see https://stackoverflow.com/a/66252656/4536543
+ *
+ * @since 1.0.0
+ */
+type RemoveIndexType<T> = {
+    [P in keyof T as string extends P ? never : number extends P ? never : P]: T[P];
+};
+/**
+ * A utility type that maps the keys of a given type `T` whose properties are constructor types.
+ *
+ * This type iterates over the properties of `RemoveIndexType<T>`,
+ * retaining only those keys where the value matches a constructor type.
+ *
+ * @template T - The target type from which constructor-like properties are to be extracted.
+ *
+ * @remarks
+ * This type is designed to filter out keys of a given type `T` to include only those that are associated with constructor functions.
+ * It leverages mapped types along with conditional type checks to achieve this functionality.
+ *
+ * @since 1.0.0
+ */
+type PropertiesWithConstructorsType<T> = {
+    [Key in keyof RemoveIndexType<T> as RemoveIndexType<T>[Key] extends ConstructorType ? Key : never]: RemoveIndexType<T>[Key];
+};
+/**
+ * A utility type that extracts the keys of the provided type `T` that correspond
+ * to properties with constructor types, removing any index signatures.
+ *
+ * @template T - The object type from which constructor property keys are extracted.
+ *
+ * @remarks
+ * This type is useful for narrowing down a type to only the keys representing
+ * properties with constructor functions (e.g., classes) while excluding index signatures.
+ *
+ * @since 1.0.0
+ */
+type ConstructorKeysType<T> = RemoveIndexType<keyof PropertiesWithConstructorsType<T>>;
+/**
+ * A utility type that extracts the keys of a type `T` if `T` extends a constructor type.
+ * If `T` does not extend a constructor type, it resolves to `never`.
+ *
+ * @template T - The type to check and extract keys from.
+ *
+ * @param T - The generic type parameter which is evaluated against a constructor type.
+ *
+ * @remarks
+ * This type is particularly useful when working with class-like or constructor-based types.
+ * It further applies `RemoveIndexType` to exclude index signatures from the resulting keys.
+ *
+ * @since 1.0.0
+ */
+type KeysExtendingConstructorType<T> = T extends ConstructorType ? keyof RemoveIndexType<T> : never;
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Creates and registers a hook with the current test suite
+ *
+ * @param hookType - Type of hook to register
+ * @param callback - Function to execute for this hook
+ * @param location - The precise source code location where the error occurred
+ * @param timeout - Maximum execution time in milliseconds
+ * @returns void
+ *
+ * @example
+ * ```ts
+ * createHook(HookType.BEFORE_EACH, () => {
+ *   // Setup code to run before each test
+ *   resetTestDatabase();
+ * }, 10000);
+ * ```
+ *
+ * @see HookType
+ * @see HookModel
+ * @see SuiteState
+ *
+ * @since 1.0.0
+ */
+declare function createHook(hookType: HookType, callback: FunctionType, location: string, timeout?: number): void;
+/**
+ * Registers an after-all hook to be executed once after all tests in a suite have completed
+ *
+ * @param callback - Function to execute after all tests in the suite
+ * @param timeout - Maximum execution time in milliseconds
+ * @returns void
+ *
+ * @throws Error - If called outside a test suite context
+ *
+ * @remarks
+ * This function is a wrapper around the createHook function, specifically for creating AFTER_ALL hooks.
+ * After-all hooks are useful for cleanup operations that should occur once after all tests complete.
+ *
+ * @example
+ * ```ts
+ * afterAllDirective(() => {
+ *   // Teardown code to run after all tests
+ *   disconnectFromDatabase();
+ * }, 10000);
+ * ```
+ *
+ * @see createHook
+ * @see HookType.AFTER_ALL
+ *
+ * @since 1.0.0
+ */
+declare function afterAllDirective(callback: FunctionType, timeout?: number): void;
+/**
+ * Registers a before-all hook to be executed once before any tests in a suite run
+ *
+ * @param callback - Function to execute before any tests in the suite
+ * @param timeout - Maximum execution time in milliseconds
+ * @returns void
+ *
+ * @throws Error - If called outside a test suite context
+ *
+ * @remarks
+ * This function is a wrapper around the createHook function, specifically for creating BEFORE_ALL hooks.
+ * Before-all hooks are useful for setup operations that should occur once before any tests run.
+ *
+ * @default timeout 5000
+ *
+ * @example
+ * ```ts
+ * beforeAllDirective(() => {
+ *   // Setup code to run before any tests
+ *   initializeTestDatabase();
+ * }, 10000);
+ * ```
+ *
+ * @see createHook
+ * @see HookType.BEFORE_ALL
+ *
+ * @since 1.0.0
+ */
+declare function beforeAllDirective(callback: FunctionType, timeout?: number): void;
+/**
+ * Registers an after-each hook to be executed after each test in a suite completes
+ *
+ * @param callback - Function to execute after each test
+ * @param timeout - Maximum execution time in milliseconds
+ * @returns void
+ *
+ * @throws Error - If called outside a test suite context
+ *
+ * @remarks
+ * This function is a wrapper around the createHook function, specifically for creating AFTER_EACH hooks.
+ * After-each hooks run after each test case and are useful for cleanup operations that should occur
+ * after every individual test.
+ *
+ * @default timeout 5000
+ *
+ * @example
+ * ```ts
+ * afterEachDirective(() => {
+ *   // Cleanup code to run after each test
+ *   resetTestState();
+ * }, 8000);
+ * ```
+ *
+ * @see createHook
+ * @see HookType.AFTER_EACH
+ *
+ * @since 1.0.0
+ */
+declare function afterEachDirective(callback: FunctionType, timeout?: number): void;
+/**
+ * Registers a before-each hook to be executed before each test in a suite runs
+ *
+ * @param callback - Function to execute before each test
+ * @param timeout - Maximum execution time in milliseconds
+ *
+ * @returns void
+ *
+ * @throws Error - If called outside a test suite context
+ *
+ * @remarks
+ * This function is a wrapper around the createHook function, specifically for creating BEFORE_EACH hooks.
+ * Before-each hooks run before each test case and are useful for setup operations that should occur
+ * before every individual test.
+ *
+ * @default timeout 5000
+ *
+ * @example
+ * ```ts
+ * beforeEachDirective(() => {
+ *   // Setup code to run before each test
+ *   prepareTestEnvironment();
+ * }, 8000);
+ * ```
+ *
+ * @see createHook
+ * @see HookType.BEFORE_EACH
+ *
+ * @since 1.0.0
+ */
+declare function beforeEachDirective(callback: FunctionType, timeout?: number): void;
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Represents a model for managing and executing hook functions with a specified timeout.
+ * Provides functionality for associating invocation locations and handling errors during execution.
+ *
+ * @remarks
+ * This class ensures that hooks are executed with proper timeout enforcement
+ * and supports both synchronous and asynchronous hook functions.
+ * It throws an error if an asynchronous hook
+ * incorrectly uses a "done" callback or if it fails to complete execution within the specified timeout.
+ *
+ * @since 1.0.0
+ */
+declare class HookModel {
+    private readonly hookFunction;
+    private readonly timeout;
+    /**
+     * Represents the current location of an invocation within the application or a fallback to undefined.
+     *
+     * @remarks
+     * This variable is designed
+     * to hold the interface representing the invocation's location for tracking.
+     * If no invocation location is available, it defaults to undefined.
+     *
+     * @since 1.0.0
+     */
+    private location;
+    /**
+     * Constructs an instance of the class.
+     *
+     * @param hookFunction - The callback function that will be executed based on specific conditions.
+     * @param timeout - The time in milliseconds before the callback function is triggered.
+     * @throws Will throw an error if the provided timeout value is negative or invalid.
+     *
+     * @remarks This constructor sets up the necessary callback function and timeout configuration for the instance.
+     *
+     * @since 1.0.0
+     */
+    constructor(hookFunction: CallbackHandlerType, timeout: number);
+    /**
+     * Sets the location of the invocation based on the provided location object.
+     *
+     * @param location - An object implementing the `InvocationLocationType` or `undefined`
+     *                   to reset the location.
+     *
+     * @remarks
+     * This method assigns a new location value to the current location of the invocation.
+     * Passing `undefined` will clear the current location.
+     *
+     * @since 1.0.0
+     */
+    setLocation(location: string): void;
+    /**
+     * Executes a hook function with a timeout mechanism.
+     *
+     * @param context - The context object passed to the hook function, containing execution-specific information.
+     * @return A promise that resolves when the hook function completes its execution successfully.
+     *
+     * @throws TimeoutError - If the hook function does not call `done()` within the specified timeout duration.
+     *
+     * @remarks This method concurrently runs the hook function and a timeout check, ensuring that execution does not
+     * exceed the predefined timeout.
+     * If the timeout is reached without the hook function completing, an ` TimeoutError ` is thrown.
+     *
+     * @since 1.0.0
+     */
+    run(context: ContextType<unknown>): Promise<void>;
+    /**
+     * Executes a given hook function, handling both synchronous and asynchronous hooks,
+     * with or without a callback mechanism.
+     *
+     * @param hook - The function representing the hook to be executed.
+     * It Can be a synchronous or asynchronous function.
+     * @param context - An object to be used as the `this` context
+     *                  when invoking the hook function.
+     * @remarks This method ensures correct execution and error handling
+     *          for both callback-based and promise-based hooks.
+     *
+     * @since 1.0.0
+     */
+    private executeHook;
+    /**
+     * Executes a callback-style hook by wrapping it in a Promise
+     *
+     * @param hook - The callback hook function to execute
+     * @param context - Execution context to bind to the hook function
+     * @returns A Promise that resolves when the hook completes or rejects when it fails
+     *
+     * @throws Error - When the hook callback is invoked with an error parameter
+     *
+     * @remarks This method converts traditional Node.js-style callback patterns (error-first callbacks)
+     * into Promise-based async/await compatible functions. The hook function receives a done callback
+     * as its argument and must call it to signal completion.
+     *
+     * @example
+     * ```ts
+     * const callbackHook = (done) => {
+     *   setTimeout(() => done(), 100);
+     * };
+     *
+     * await executeCallbackHook(callbackHook, this);
+     * ```
+     *
+     * @see isPromise
+     * @since 1.0.0
+     */
+    private executeCallbackHook;
+}
+
+/**
+ * Represents a callback function type used to signal the completion of an operation.
+ * Typically used in asynchronous functions to convey success or error states.
+ *
+ * @param error - An optional parameter indicating the error details.
+ * Pass a string or an object with a `message` property to specify the error reason.
+ * If no error occurs, this parameter may be omitted or set to `undefined`.
+ *
+ * @remarks
+ * This type is designed for scenarios requiring explicit error signaling.
+ * Consumers of this callback should handle both error and non-error cases appropriately.
+ *
+ * @since 1.0.0
+ */
+type DoneCallbackType = (error?: string | {
+    message: string;
+}) => void;
+/**
+ * Represents a type definition for a callback handler function.
+ *
+ * @remarks
+ * This type can either be:
+ * - A synchronous function taking a `done` callback of type `DoneCallbackType`
+ * as an argument and optionally returning `undefined`.
+ * - An asynchronous function that returns a `Promise<void>`.
+ * This type is designed to provide flexibility for synchronous functions operating with a `done` callback
+ * or asynchronous functions using `Promise<void>`.
+ *
+ * @since 1.0.0
+ */
+type CallbackHandlerType = ((done: DoneCallbackType) => void | undefined) | (() => Promise<void>);
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Executes a given asynchronous or synchronous task with an optional timeout constraint.
+ *
+ * @typeParam T - The resolved value type.
+ *
+ * @param task - Either a function that returns a value or promise, or a promise itself.
+ * @param delay - Timeout in milliseconds, or `-1` to disable the timeout.
+ * @param at - A contextual label (e.g., method name or operation name) to aid debugging.
+ * @param stack - Optional stack trace to provide more detailed error context.
+ *
+ * @throws {@link TimeoutError} If the task does not complete within the specified `delay`
+ * (only when `delay` is not `-1`).
+ *
+ * @remarks
+ * The function accepts either:
+ * - a function returning a value or a promise, or
+ * - a promise directly.
+ *
+ * If `delay` is `-1`, no timeout is applied. Otherwise the task is raced against
+ * a timer and a {@link TimeoutError} is thrown on expiry.
+ *
+ * @example
+ * ```ts
+ * // Passing a function
+ * await withTimeout(
+ *   () => fetchData(),
+ *   5000,
+ *   'fetchData'
+ * );
+ *
+ * // Passing a promise directly
+ * await withTimeout(
+ *   fetchData(),
+ *   5000,
+ *   'fetchDataDirect'
+ * );
+ *
+ * // No timeout
+ * await withTimeout(fetchData(), -1, 'fetchDataNoTimeout');
+ * ```
+ *
+ * @since 1.1.0
+ */
+declare function withTimeout<T>(task: FunctionLikeType<T | Promise<T>> | Promise<T> | T, delay: number, at: string, stack?: string): Promise<T>;
+
+declare class TimeoutError extends Error {
+    constructor(timeout: number, at: string, stack?: string);
+}
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Manages the state of test suites within the testing framework, tracking the hierarchy of describe blocks and test cases.
+ * Implemented as a singleton to ensure a single source of truth for the test suite structure.
+ *
+ * @template TestModel - The model type representing individual test cases
+ * @template FunctionType - The function type for describe block implementations
+ * @template DescribeModel - The model type representing test suite describe blocks
+ * @template DescribeOptionsInterface - Configuration options for describe blocks
+ *
+ * @throws Error - If you attempt to instantiate this class directly instead of using getInstance()
+ *
+ * @remarks
+ * The singleton pattern ensures that all test registration operations work with the same
+ * state instance, properly maintaining the hierarchical structure of tests.
+ * Use the static getInstance() method to access the singleton instance.
+ *
+ * @example
+ * ```ts
+ * // Get the singleton instance
+ * const suiteState = SuiteState.getInstance();
+ *
+ * // Add a describe block
+ * suiteState.addDescribe('My test suite', () => {
+ *   // Test suite implementation
+ * }, { only: true });
+ *
+ * // Add a test case to the current describe block
+ * suiteState.addTest(new TestModel('should work', () => {}, { skip: false }));
+ * ```
+ *
+ * @see TestModel
+ * @see DescribeModel
+ *
+ * @since 1.0.0
+ */
+declare class SuiteState {
+    /**
+     * Tracks whether any test or describe block has the 'only' flag set
+     *
+     * @since 1.0.0
+     */
+    private onlyMode;
+    /**
+     * Reference to the currently active describe block in the test hierarchy
+     *
+     * @see DescribeModel
+     * @since 1.0.0
+     */
+    private currentDescribe;
+    /**
+     * Reference to the test currently being defined or executed
+     *
+     * @see TestModel
+     * @since 1.0.0
+     */
+    private currentTest?;
+    /**
+     * Suite has at least one test
+     * @since 1.0.0
+     */
+    private hasTests;
+    /**
+     * The top-level describe block that contains all tests and nested describe blocks
+     *
+     * @see DescribeModel
+     * @since 1.0.0
+     */
+    private readonly rootDescribe;
+    /**
+     * Array of regular expressions used for filtering test paths
+     *
+     * @remarks
+     * This array stores regular expressions created from filter strings specified in runtime configuration.
+     * Used to determine which tests should be executed when filtering is enabled.
+     *
+     * @see SuiteState.matchesFilter - Method that uses these regex patterns for test filtering
+     * @since 1.0.0
+     */
+    private readonly filterRegexChain;
+    /**
+     * Checks if a test path matches the provided regular expression filter patterns
+     *
+     * This method compares a test's full path (including ancestry and description) against one or more
+     * regular expression patterns to determine if the test should be included in execution.
+     *
+     * @param path - Array of path segments representing test ancestry and description
+     * @param filter - Array of RegExp objects to test against the path
+     * @returns Boolean indicating whether the path matches the filter patterns
+     *
+     * @throws Error - When invalid regular expressions are provided
+     *
+     * @remarks
+     * The method aligns the filter from the end of the path, allowing partial matching of nested test structures.
+     * This is particularly useful for selecting specific test cases within a larger test hierarchy.
+     *
+     * @example
+     * ```ts
+     * // Match tests with description containing "login"
+     * const matches = SuiteState.matchesFilter(
+     *   ['Auth', 'User', 'should handle login correctly'],
+     *   [/login/i]
+     * );
+     * // Returns: true
+     *
+     * // Match specific test path structure
+     * const matches = SuiteState.matchesFilter(
+     *   ['API', 'GET', 'should return 200 status'],
+     *   [/API/, /GET/, /status/]
+     * );
+     * // Returns: true
+     * ```
+     *
+     * @see filterChain - String-based alternative for exact matching
+     * @see addTest - Method that uses matchesFilter to determine which tests to run
+     *
+     * @since 1.0.0
+     */
+    static matchesFilter(path: string[], filter: RegExp[]): boolean;
+    /**
+     * Indicates whether the test suite is running in "only" mode
+     *
+     * @returns True if only specifically marked tests should run
+     *
+     * @since 1.0.0
+     */
+    get isOnlyMode(): boolean;
+    /**
+     * Gets the root describe block of the test suite
+     *
+     * @returns The top-level describe block
+     *
+     * @see DescribeModel
+     * @since 1.0.0
+     */
+    get root(): DescribeModel;
+    /**
+     * Gets the current describe block being defined
+     *
+     * @returns The active describe block
+     *
+     * @see DescribeModel
+     * @since 1.0.0
+     */
+    get describe(): DescribeModel;
+    /**
+     * Gets the test currently being defined or executed
+     *
+     * @returns The current test or null if no test is active
+     *
+     * @see TestModel
+     * @since 1.0.0
+     */
+    get test(): TestModel | undefined;
+    /**
+     * Sets the current test being defined or executed
+     *
+     * @param test - The test to set as current
+     *
+     * @see TestModel
+     * @since 1.0.0
+     */
+    set test(test: TestModel | undefined);
+    /**
+     * Executes the entire test suite from the root describe block
+     *
+     * @param context - The execution context containing runtime information
+     *
+     * @throws Error - When test execution fails, the error is encoded and dispatched
+     *
+     * @remarks
+     * This method initiates the test execution flow by calling run() on the root describe block
+     * and emits an END status notification when all tests complete successfully. If an error
+     * occurs during execution, it's captured, encoded, and dispatched through the error schema.
+     *
+     * @example
+     * ```ts
+     * const suiteState = SuiteState.getInstance();
+     * await suiteState.run({
+     *   timeout: 5000,
+     *   currentPath: '/tests',
+     *   skipAfterFailure: true
+     * });
+     * ```
+     *
+     * @see emitStatus
+     * @see DescribeModel
+     *
+     * @since 1.0.0
+     */
+    run(context: ContextType<ContextInterface>): Promise<void>;
+    /**
+     * Adds a new describe block to the test suite hierarchy
+     *
+     * @param description - The textual description of the describe block
+     * @param describeFn - The function containing the tests and nested describes
+     * @param flags - Configuration options for the describe block
+     * @param describeArgs - Arguments to pass to the describe function
+     *
+     * @throws Error - If the describe function throws any exceptions
+     *
+     * @remarks
+     * This method temporarily changes the current describe context while executing
+     * the describeFn, then restores it afterward, ensuring proper nesting of test blocks.
+     * If the 'only' flag is set, it enables only-mode for the entire test suite.
+     *
+     * @example
+     * ```ts
+     * suiteState.addDescribe(
+     *   'my test group',
+     *   () => {
+     *     // test definitions here
+     *   },
+     *   { only: true }
+     * );
+     * ```
+     *
+     * @see FunctionType
+     * @see DescribeModel
+     * @see DescribeOptionsInterface
+     *
+     * @since 1.0.0
+     */
+    addDescribe(description: string, describeFn: FunctionType, flags?: DescribeOptionsInterface, describeArgs?: Array<unknown>): void;
+    /**
+     * Adds a test to the current describe block
+     *
+     * @param test - The test model to add
+     *
+     * @remarks
+     * If the test has the 'only' option set, it enables only-mode for the entire test suite.
+     *
+     * @see TestModel
+     * @since 1.0.0
+     */
+    addTest(test: TestModel): void;
+}
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Represents a test case within the testing framework that manages execution,
+ * timing, and reporting of individual tests.
+ *
+ * @example
+ * ```ts
+ * const test = new TestModel(
+ *   'should validate user input correctly',
+ *   async () => {
+ *     const result = await validateInput('test@example.com');
+ *     expect(result.isValid).toBe(true);
+ *   },
+ *   2000
+ * );
+ *
+ * // Set ancestry to show the test's location in the test hierarchy
+ * test.ancestry = ['Authentication', 'Input Validation'];
+ *
+ * // Execute the test
+ * await test.execute();
+ * ```
+ *
+ * @remarks
+ * The TestModel is responsible for tracking test execution time, handling timeouts,
+ * managing test context, and reporting test status through the emit service.
+ * It supports both synchronous and promise-based test implementations.
+ *
+ * @throws FailingError - When a test fails due to assertions or errors
+ *
+ * @see ContextInterface
+ * @see EmitActionEventType
+ * @see EmitStatusEventType
+ * @see InvocationLocationType
+ *
+ * @since 1.0.0
+ */
+declare class TestModel {
+    readonly description: string;
+    private readonly testImplementation;
+    private readonly timeoutDuration;
+    private readonly testParameters;
+    private readonly testOptions;
+    /**
+     * Stores the hierarchical path of parent test descriptions that contain this test
+     *
+     * @default []
+     * @since 1.0.0
+     */
+    readonly ancestry: Array<string>;
+    /**
+     * Stores information about where this test is being executed in the source code
+     *
+     * @see InvocationLocationType
+     * @since 1.0.0
+     */
+    private executionLocation;
+    /**
+     * Timestamp when test execution started, measured in milliseconds
+     *
+     * @default 0
+     * @since 1.0.0
+     */
+    private executionStartTime;
+    /**
+     * Creates a new instance of the TestModel to represent an executable test.
+     *
+     * @param description - The test description that explains the purpose of the test
+     * @param testImplementation - The function containing the actual test code to be executed
+     * @param timeoutDuration - The maximum time in milliseconds that the test is allowed to run
+     * @param testParameters - An array of parameters to be passed to the test implementation
+     * @param testOptions - Configuration options that control test execution behavior
+     *
+     * @example
+     * ```ts
+     * const test = new TestModel(
+     *   'should calculate the correct sum',
+     *   () => expect(sum(2, 2)).toBe(4),
+     *   5000
+     * );
+     * ```
+     *
+     * @since 1.0.0
+     */
+    constructor(description: string, testImplementation: FunctionType, timeoutDuration: number, testParameters?: unknown[], testOptions?: TestFlagsType);
+    /**
+     * Provides access to the test configuration options.
+     *
+     * @returns The test configuration options that control test execution behavior
+     *
+     * @since 1.0.0
+     */
+    get options(): TestFlagsType;
+    /**
+     * Sets the location where the test is being executed.
+     *
+     * @param location - The execution location information containing position details
+     *
+     * @see InvocationLocationType
+     * @since 1.0.0
+     */
+    setExecutionLocation(location: string): void;
+    /**
+     * Applies execution control options to the test, allowing it to be skipped or run exclusively.
+     *
+     * @param skip - Flag indicating whether the test should be skipped during execution
+     * @param only - Flag indicating whether only this test should be executed
+     *
+     * @remarks
+     * This method uses logical OR assignment (||=) to ensure options are only set to true and
+     * never reset from true to false. Existing flag values take precedence.
+     *
+     * @example
+     * ```ts
+     * testInstance.applyExecutionFlags(true, false); // Will mark test to be skipped
+     * testInstance.applyExecutionFlags(false, true); // Will mark test to run exclusively
+     * ```
+     *
+     * @see TestFlagsType
+     * @since 1.0.0
+     */
+    applyExecutionFlags(skip?: boolean, only?: boolean): void;
+    /**
+     * Sets the ancestry for this test by adding parent test descriptions to the ancestry chain.
+     *
+     * @param parentTests - Array of parent test description strings representing the test hierarchy
+     *
+     * @example
+     * ```ts
+     * const childTest = new TestModel("should work", () => {}, 5000);
+     * childTest.setAncestry(["describe block A", "describe block B"]);
+     * ```
+     *
+     * @since 1.0.0
+     */
+    setAncestry(parentTests: string[]): void;
+    /**
+     * Executes the test within the specified context, managing test lifecycle and status reporting.
+     *
+     * @param context - The test execution context containing shared state and utilities
+     * @param runLifecycleHooks - Function that runs before/after hooks at appropriate times
+     * @param isExclusiveMode - Flag indicating if tests are running in exclusive mode (only marked tests)
+     * @returns Promise that resolves when the test execution completes
+     *
+     * @throws Error - If any unhandled exceptions occur during test execution that aren't captured
+     *
+     * @remarks
+     * The method tracks execution time, manages test lifecycle, handles skipping logic, and processes
+     * test results. It also notifies about test status changes through observer pattern implementation.
+     *
+     * @example
+     * ```ts
+     * // Running a test with context and lifecycle hooks
+     * await testInstance.run(
+     *   testContext,
+     *   async (hookType, ctx) => {
+     *     await runHooks(hookType, ctx);
+     *   },
+     *   false
+     * );
+     * ```
+     *
+     * @see HookType
+     * @see ActionType
+     * @see ContextInterface
+     *
+     * @since 1.0.0
+     */
+    run(context: ContextType<ContextInterface>, runLifecycleHooks: FunctionLikeType<Promise<void>, [HookType, ContextType<ContextInterface>]>, isExclusiveMode?: boolean): Promise<void>;
+    private determineSkipAction;
+    private getExecutionStrategy;
+    private notifyTestStatus;
+}
+
+/**
+ * Represents a collection of optional options used for test configuration.
+ *
+ * @property skip - Indicates whether the test should be skipped during execution.
+ * @property only - Ensures that only this specific test or set of tests will be run.
+ * @property todo - Marks the test as a work-in-progress or not yet implemented.
+ * @property failing - Denotes that the test is expected to fail as part of the workflow.
+ *
+ * @remarks
+ * The `TestFlagsType` type is commonly used to specify various states or behaviors for a test case.
+ * Each property is optional, and the combination of these options can influence how a test suite operates.
+ *
+ * @since 1.0.0
+ */
+type TestFlagsType = {
+    skip?: boolean;
+    only?: boolean;
+    todo?: boolean;
+    failing?: boolean;
+};
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Represents options that control the execution behavior of a `describe` block.
+ *
+ * @remarks
+ * This interface is used to configure specific conditions for a `describe` block,
+ * such as skipping the execution (`skip`) or running it exclusively (`only`).
+ * Both properties are optional and allow flexible test suite configuration.
+ *
+ * @example
+ * ```ts
+ * const options: DescribeOptionsInterface = {
+ *   skip: true, // This described block will be skipped
+ *   only: false // Not marked as exclusive; can be omitted
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ */
+interface DescribeOptionsInterface {
+    /**
+     * If true, the `describe` block will be skipped.
+     * @since 1.0.0
+     */
+    skip?: boolean;
+    /**
+     * If true, the `describe` block will run exclusively, ignoring other blocks.
+     * @since 1.0.0
+     */
+    only?: boolean;
+}
+/**
+ * Represents the collection of hooks for a `describe` block.
+ *
+ * @remarks
+ * Each `describe` block can define multiple lifecycle hooks:
+ * - `beforeAll` → Runs once before all tests in the block.
+ * - `afterAll` → Runs once after all tests in the block.
+ * - `beforeEach` → Runs before each test in the block.
+ * - `afterEach` → Runs after each test in the block.
+ *
+ * These hooks are stored as arrays of {@link HookModel} instances.
+ *
+ * @example
+ * ```ts
+ * const hooks: DescribeHooksInterface = {
+ *   beforeAll: [new HookModel(() => {}, 5000)],
+ *   afterAll: [new HookModel(() => {}, 5000)],
+ *   beforeEach: [new HookModel(() => {}, 5000)],
+ *   afterEach: [new HookModel(() => {}, 5000)]
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ */
+interface DescribeHooksInterface {
+    /**
+     * Hooks to execute once after all tests in the `describe` block.
+     *
+     * @see HookModel
+     * @since 1.0.0
+     */
+    afterAll: Array<HookModel>;
+    /**
+     * Hooks to execute once before all tests in the `describe` block.
+     *
+     * @see HookModel
+     * @since 1.0.0
+     */
+    beforeAll: Array<HookModel>;
+    /**
+     * Hooks to execute before each test in the `describe` block.
+     *
+     * @see HookModel
+     * @since 1.0.0
+     */
+    beforeEach: Array<HookModel>;
+    /**
+     * Hooks to execute after each test in the `describe` block.
+     *
+     * @see HookModel
+     * @since 1.0.0
+     */
+    afterEach: Array<HookModel>;
+}
+/**
+ * Represents the execution context for a test suite, tracking errors and overall status.
+ *
+ * @remarks
+ * - `hasError` is `true` if any test or suite has failed, indicating that bail mode is active
+ *   and the runner should not execute the remaining tests or describe blocks in the current suites.
+ * - `beforeAllErrors` collects errors thrown during `beforeAll` hooks.
+ * - `afterAllErrors` collects errors thrown during `afterAll` hooks.
+ *
+ * @example
+ * ```ts
+ * const context: ContextInterface = {
+ *   hasError: false,
+ *   beforeAllErrors: [],
+ *   afterAllErrors: []
+ * };
+ *
+ * if (context.hasError) {
+ *   console.log("Bail is active. Skipping remaining tests.");
+ * }
+ * ```
+ *
+ * @since 1.0.0
+ */
+interface ContextInterface {
+    /**
+     * Indicates whether any test or suite has failed. When `true`, bail mode is active,
+     * and the runner should skip the remaining tests or describe blocks.
+     *
+     * @since 1.0.0
+     */
+    hasError: boolean;
+    /**
+     * Errors thrown during `beforeAll` hooks.
+     *
+     * @since 1.0.0
+     */
+    beforeAllErrors: Array<unknown>;
+    /**
+     * Errors thrown during `afterAll` hooks.
+     *
+     * @since 1.0.0
+     */
+    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
+ */
+declare class FailingError extends ExecutionError {
+    constructor(stack: string);
+}
+
+/**
+ * Defines the log verbosity levels for reporters and test execution.
+ *
+ * @remarks
+ * Each level represents the minimum severity of messages that should be
+ * captured or displayed. Higher levels include all messages from lower levels.
+ *
+ * @example
+ * ```ts
+ * if (log.level >= LogLevel.Warn) {
+ *   console.warn(log.message);
+ * }
+ * ```
+ *
+ * @since 1.0.0
+ */
+export declare enum LogLevel {
+    Silent = 0,
+    Error = 1,
+    Warn = 2,
+    Info = 3,
+    Debug = 4
+}
+/**
+ * Defines the types of messages emitted during test execution.
+ *
+ * @remarks
+ * These message types are used internally by reporters, runners,
+ * and event emitters to categorize test events. Each type corresponds
+ * to a specific stage or element of the test lifecycle.
+ *
+ * @example
+ * ```ts
+ * if (message.type === MessageType.Test) {
+ *   console.log('Test event received');
+ * }
+ * ```
+ *
+ * @since 1.0.0
+ */
+declare const enum MessageType {
+    Test = 1,
+    Describe = 2,
+    EndSuite = 3,
+    StartSuite = 4
+}
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Emits a status update packet to the dispatcher.
+ *
+ * @param type - The {@link MessageType} representing the kind of status (e.g., suite start, suite end).
+ * @param notification - The {@link EmitStatusInterface} containing ancestry and description details.
+ *
+ * @remarks
+ * This function encodes the notification into a `PacketKind.Status` packet
+ * and sends it via the global `dispatch` mechanism.
+ *
+ * @see MessageType
+ * @see encodePacket
+ * @see PacketKind.Status
+ * @see EmitStatusInterface
+ *
+ * @since 1.0.0
+ */
+declare function emitStatus(type: MessageType, notification?: EmitStatusInterface): void;
+/**
+ * Emits an action (event) packet to the dispatcher.
+ *
+ * @param type - The {@link MessageType} representing the kind of action (e.g., test end, describe end).
+ * @param notification - The {@link EmitEventInterface} containing ancestry, description,
+ *                       duration, and possible test errors.
+ *
+ * @remarks
+ * - Errors are serialized with {@link serializeError} before being encoded.
+ * - The function encodes the notification into a `PacketKind.Events` packet
+ *   and sends it via the global `dispatch` mechanism.
+ *
+ * @see MessageType
+ * @see encodePacket
+ * @see serializeError
+ * @see PacketKind.Events
+ * @see EmitEventInterface
+ *
+ * @since 1.0.0
+ */
+declare function emitEvent(type: MessageType, notification: EmitEventInterface): void;
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Represents the payload for emitting an event (e.g., test or describe completion).
+ *
+ * @remarks
+ * Extends {@link PacketEventsInterface} but replaces:
+ * - `errors` with a raw {@link Error} array (to be serialized before dispatch).
+ * - `ancestry` with a string array for hierarchical test path tracking.
+ * - `type` is omitted since it is explicitly provided when emitting.
+ *
+ * @example
+ * ```ts
+ * const event: EmitEventInterface = {
+ *   ancestry: ['MySuite', 'MyTest'],
+ *   description: 'should add numbers correctly',
+ *   duration: 42,
+ *   errors: [new Error('Expected 2 but got 3')]
+ * };
+ * emitEvent(MessageType.Test, event);
+ * ```
+ *
+ * @see emitAction
+ * @see PacketEventsInterface
+ *
+ * @since 1.0.0
+ */
+interface EmitEventInterface extends Omit<Partial<PacketEventsInterface>, 'errors' | 'ancestry' | 'type'> {
+    errors?: Array<Error>;
+    ancestry: Array<string>;
+}
+/**
+ * Represents the payload for emitting a status update (e.g., suite start or end).
+ *
+ * @remarks
+ * Extends {@link PacketStatusInterface} but replaces:
+ * - `ancestry` with a string array for hierarchical test path tracking.
+ * - `type` is omitted since it is explicitly provided when emitting.
+ *
+ * @example
+ * ```ts
+ * const status: EmitStatusInterface = {
+ *   ancestry: ['MySuite'],
+ *   description: 'Suite execution started'
+ * };
+ * emitStatus(MessageType.StartSuite, status);
+ * ```
+ *
+ * @see emitStatus
+ * @see PacketStatusInterface
+ *
+ * @since 1.0.0
+ */
+interface EmitStatusInterface extends Omit<Partial<PacketStatusInterface>, 'ancestry' | 'type'> {
+    ancestry?: Array<string>;
+}
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Represents the position of an invocation within a bundle file.
+ *
+ * @since 1.0.0
+ */
+interface PacketInvocationInterface {
+    /**
+     * The line number where the invocation occurs (0-based).
+     * @since 1.0.0
+     */
+    line: number;
+    /**
+     * The column number where the invocation occurs (0-based).
+     * @since 1.0.0
+     */
+    column: number;
+    /**
+     * Source file
+     * @since 1.0.0
+     */
+    source: string;
+}
+/**
+ * Represents the header information for a packet sent.
+ * @since 1.0.0
+ */
+interface PacketHeaderInterface {
+    /**
+     * The type of packet being sent.
+     *
+     * @see PacketKind
+     * @since 1.0.0
+     */
+    kind: PacketKind;
+    /**
+     * The unique identifier of the test suite.
+     *
+     * @since 1.0.0
+     */
+    suiteId: string;
+    /**
+     * The unique identifier of the runner sending the packet.
+     *
+     * @since 1.0.0
+     */
+    runnerId: string;
+    /**
+     * The timestamp when the packet was created, in ISO string format.
+     *
+     * @since 1.0.0
+     */
+    timestamp: string;
+}
+/**
+ * Represents a log entry generated during test execution, similar to console output.
+ *
+ * @remarks
+ * Used to capture messages like `console.log`, `console.error`, `console.info`, etc.,
+ * along with metadata about where in the test hierarchy and source code the log originated.
+ *
+ * @since 1.0.0
+ */
+interface PacketLogInterface {
+    /**
+     * The severity level of the log entry.
+     * Typically maps to console levels such as info, warn, debug, or error.
+     *
+     * @since 1.0.0
+     */
+    level: number;
+    /**
+     * The content of the log message.
+     * @since 1.0.0
+     */
+    message: string;
+    /**
+     * The ancestry path of the test or describe block that generated this log.
+     * @since 1.0.0
+     */
+    ancestry: string;
+    /**
+     * The location in the source code where the log was generated.
+     *
+     * @see PacketInvocationInterface
+     * @since 1.0.0
+     */
+    invocation: PacketInvocationInterface;
+}
+/**
+ * Represents a fatal error in a test suite.
+ *
+ * @remarks
+ * This error occurs at the suite level and is **not** associated with any individual test,
+ * describe block, or hook (e.g., before/after hooks). It indicates a failure
+ * that prevents the suite from running normally.
+ *
+ * @since 1.0.0
+ */
+interface PacketErrorInterface {
+    /**
+     * The serialized error describing the fatal issue in the suite.
+     * @since 1.0.0
+     */
+    error: string;
+}
+/**
+ * Represents an event emitted when a test or describe block starts or updates during execution.
+ *
+ * @remarks
+ * Used to track the lifecycle of individual tests or describe blocks, including
+ * whether they are skipped, marked TODO, or have errors.
+ * This does **not** include suite-level fatal errors.
+ *
+ * @since 1.0.0
+ */
+interface PacketStatusInterface {
+    /**
+     * Indicates whether the status is for a test or a describe block.
+     * @since 1.0.0
+     */
+    type: number;
+    /**
+     * Indicates if the test or describe block is marked as TODO.
+     * @since 1.0.0
+     */
+    todo: boolean;
+    /**
+     * Indicates if the test or describe block was skipped.
+     * @since 1.0.0
+     */
+    skipped: boolean;
+    /**
+     * Duration of the test or describe block in milliseconds, if available.
+     * @since 1.0.0
+     */
+    duration: number;
+    /**
+     * The ancestry path of the test or describe block.
+     * @since 1.0.0
+     */
+    ancestry: string;
+    /**
+     * Human-readable description of the test or describe block.
+     * @since 1.0.0
+     */
+    description: string;
+}
+/**
+ * Represents an event emitted for a test or describe block during execution.
+ *
+ * @remarks
+ * Used to track the lifecycle of individual tests or describe blocks, such as finish.
+ * This interface is **not** for suite-level fatal errors.
+ *
+ * @since 1.0.0
+ */
+interface PacketEventsInterface {
+    /**
+     * Indicates the type of event and whether it corresponds to a test or a describe block.
+     * @since 1.0.0
+     */
+    type: number;
+    /**
+     * Error message associated with the test or describe block, if any.
+     * @since 1.0.0
+     */
+    errors: string;
+    /**
+     * Duration of the test or describe block in milliseconds.
+     * @since 1.0.0
+     */
+    duration: number;
+    /**
+     * The ancestry path of the test or describe block.
+     * @since 1.0.0
+     */
+    ancestry: string;
+    /**
+     * Human-readable description of the test or describe block.
+     * @since 1.0.0
+     */
+    description: string;
+}
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Defines the different kinds of packets that can be transmitted or received.
+ *
+ * @remarks
+ * Each packet kind corresponds to a specific type of event or message in the test framework:
+ * - `Log`: Console or logging messages
+ * - `Error`: Suite-level fatal errors
+ * - `Status`: Test or describe start events, including `skipped` and `todo` flags
+ * - `Events`: Test or describe end events, only for completed tests/describes (no skipped or TODO)
+ *
+ * @since 1.0.0
+ */
+declare const enum PacketKind {
+    /**
+     * Represents a log message packet, e.g., `console.log`, `console.error`.
+     * @since 1.0.0
+     */
+    Log = 1,
+    /**
+     * Represents a fatal suite-level error.
+     * Not associated with any test, describe, or hook.
+     * @since 1.0.0
+     */
+    Error = 2,
+    /**
+     * Represents a status packet for test or describe start events.
+     *
+     * @remarks
+     * Includes flags for:
+     * - `skipped`: Whether the test or describe was skipped
+     * - `todo`: Whether the test is marked as TODO
+     *
+     * @since 1.0.0
+     */
+    Status = 3,
+    /**
+     * Represents an event packet for test or describe end events.
+     *
+     * @remarks
+     * Only includes completed tests/describes; skipped or TODO tests are not included.
+     * Contains information such as `passed` and `duration`.
+     *
+     * @since 1.0.0
+     */
+    Events = 4
+}
+/**
+ * Maps each {@link PacketKind} to its corresponding {@link Struct} schema for serialization/deserialization.
+ *
+ * @remarks
+ * This object allows encoding and decoding packets of different kinds using
+ * their respective `xStruct` schemas. Use `PacketSchemas[PacketKind.Log]` to
+ * get the schema for log packets, etc.
+ *
+ * @see PacketKind
+ * @see Struct
+ *
+ * @since 1.0.0
+ */
+declare const PacketSchemas: Record<PacketKind, Struct>;
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Imports
+ */
+/**
+ * Schema for serializing and deserializing {@link PacketInvocationInterface} data.
+ *
+ * @remarks
+ * Represents the location in source code where a test, describe, or log originates.
+ *
+ * @since 1.0.0
+ */
+declare const invocationSchema: Struct<PacketInvocationInterface>;
+/**
+ * Schema for serializing and deserializing {@link PacketHeaderInterface} data.
+ *
+ * @remarks
+ * Contains metadata for each packet, including kind, suite and runner identifiers, and timestamp.
+ *
+ * @since 1.0.0
+ */
+declare const headerSchema: Struct<PacketHeaderInterface>;
+/**
+ * Schema for serializing and deserializing {@link PacketLogInterface} data.
+ *
+ * @remarks
+ * Used for console-like logs emitted by tests or describes, including message, level, ancestry, and invocation.
+ *
+ * @since 1.0.0
+ */
+declare const logSchema: Struct<PacketLogInterface>;
+/**
+ * Schema for serializing and deserializing {@link PacketErrorInterface} data.
+ *
+ * @remarks
+ * Represents suite-level fatal errors that are not tied to specific tests or describes.
+ *
+ * @since 1.0.0
+ */
+declare const errorSchema: Struct<PacketErrorInterface>;
+/**
+ * Schema for serializing and deserializing {@link PacketStatusInterface} data.
+ *
+ * @remarks
+ * Represents status updates for individual tests or describe blocks,
+ * including whether it is TODO, skipped, and its ancestry and description.
+ *
+ * @since 1.0.0
+ */
+declare const statusSchema: Struct<PacketStatusInterface>;
+/**
+ * Schema for serializing and deserializing {@link PacketEventsInterface} data.
+ *
+ * @remarks
+ * Represents events emitted during the test or describe execution,
+ * including pass/fail status, duration, error messages, ancestry, and invocation.
+ *
+ * @since 1.0.0
+ */
+declare const eventsSchema: Struct<PacketEventsInterface>;
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Exports constants
+ */
+/**
+ * Exports interfaces
+ */
+/**
+ * Encodes a packet of a given kind into a `Buffer`.
+ *
+ * @template T - The packet kind (`PacketKind.Log`, `PacketKind.Error`, `PacketKind.Status`, or `PacketKind.Events`)
+ *
+ * @param kind - The type of packet to encode
+ * @param data - Partial data matching the packet type; will be combined with header information
+ *
+ * @returns A `Buffer` containing the serialized packet
+ *
+ * @throws Error if the provided `kind` does not correspond to a known packet schema
+ *
+ * @remarks
+ * This function combines a header and the payload according to the packet kind.
+ * The header includes the suite ID, runner ID, and a timestamp.
+ *
+ * @since 1.0.0
+ */
+declare function encodePacket<T extends PacketKind>(kind: T, data: Partial<PacketPayloadMapType[T]>): Buffer;
+/**
+ * Decodes a packet from a `Buffer` into its corresponding object representation.
+ *
+ * @template T - The expected packet kind (`PacketKind.Log`, `PacketKind.Error`, `PacketKind.Status`, or `PacketKind.Events`)
+ *
+ * @param buffer - The buffer containing the encoded packet
+ * @returns The decoded packet object, combining the header and payload fields
+ *
+ * @throws Error if the packet kind is unknown or invalid
+ *
+ * @remarks
+ * Decodes both the header and payload based on the packet kind.
+ *
+ * @since 1.0.0
+ */
+declare function decodePacket<T extends PacketKind>(buffer: Buffer): DecodedPacketType<T>;
+/**
+ * Encodes an {@link Error} instance into a binary buffer following the packet schema.
+ *
+ * @param error - The error object to be serialized and encoded.
+ * @param suiteId - Identifier of the suite where the error occurred.
+ * @param runnerId - Identifier of the runner reporting the error.
+ *
+ * @returns A {@link Buffer} containing the encoded error packet, ready for transmission.
+ *
+ * @remarks
+ * The function creates two binary sections:
+ * - A **header**, describing the packet kind (`Error`), suite ID, runner ID, and timestamp.
+ * - A **data buffer**, holding the serialized error details in JSON format.
+ *
+ * These two sections are concatenated into a single buffer.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   throw new Error("Test failed");
+ * } catch (err) {
+ *   const buffer = encodeErrorSchema(err, "suite-123", "runner-456");
+ *   socket.send(buffer); // transmit over a transport channel
+ * }
+ * ```
+ *
+ * @see serializeError
+ * @see PacketKind.Error
+ *
+ * @since 1.0.0
+ */
+export declare function encodeErrorSchema(error: Error, suiteId: string, runnerId: string): Buffer;
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Maps each {@link PacketKind} to its corresponding packet payload interface.
+ *
+ * @remarks
+ * This type is used internally to associate packet kinds with their structured payloads.
+ * For example, a `PacketKind.Log` corresponds to a {@link PacketLogInterface} payload.
+ *
+ * @since 1.0.0
+ */
+type PacketPayloadMapType = {
+    [PacketKind.Log]: PacketLogInterface;
+    [PacketKind.Error]: PacketErrorInterface;
+    [PacketKind.Status]: PacketStatusInterface;
+    [PacketKind.Events]: PacketEventsInterface;
+};
+/**
+ * Represents a fully decoded packet, combining its payload and the standard packet header.
+ *
+ * @template T - The {@link PacketKind} indicating the type of payload
+ *
+ * @remarks
+ * This type merges the payload interface corresponding to `T` from {@link PacketPayloadMapType}
+ * with {@link PacketHeaderInterface}, so every decoded packet contains both its header and payload.
+ *
+ * @example
+ * ```ts
+ * const decodedLog: DecodedPacketType<PacketKind.Log> = {
+ *   kind: PacketKind.Log,
+ *   suiteId: 'suite1',
+ *   runnerId: 'runner1',
+ *   timestamp: '2025-09-02T08:00:00Z',
+ *   level: 1,
+ *   message: 'Test log message',
+ *   ancestry: 'root.describe.test',
+ *   invocation: { line: 12, column: 5 }
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ */
+type DecodedPacketType<T extends PacketKind> = PacketPayloadMapType[T] & PacketHeaderInterface;
+
+/**
+ * Represents the types of lifecycle hooks that can be used in testing frameworks or similar systems.
+ *
+ * @remarks
+ * The `HookType` enum defines constants for various lifecycle stages
+ * that are commonly used to implement setup and teardown logic
+ * in testing or other procedural workflows.
+ *
+ * @since 1.0.0
+ */
+declare const enum HookType {
+    AFTER_ALL = "afterAll",
+    BEFORE_ALL = "beforeAll",
+    AFTER_EACH = "afterEach",
+    BEFORE_EACH = "beforeEach"
+}
+
+/**
+ * Enum representing the types of test execution methods available.
+ *
+ * @remarks
+ * This enum defines three different modes of executing tests:
+ * - `SYNC`: Synchronous execution, where tests are executed in sequence.
+ * - `ASYNC`: Asynchronous execution, where tests are executed using asynchronous logic.
+ * - `CALLBACK`: Callback-based execution, where a callback function is used to signal completion.
+ *
+ * @since 1.0.0
+ */
+declare const enum TestExecutionType {
+    SYNC = "SYNC",
+    ASYNC = "ASYNC",
+    CALLBACK = "CALLBACK"
+}
+
+/**
+ * Exports
+ */
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Represents a test suite container that manages test execution flow and hierarchy
+ *
+ * @template T - Context type for test execution
+ * @param description - The description of the test suite
+ * @param describeFlags - Configuration options for the test suite
+ * @returns A new DescribeModel instance that can contain tests and nested suites
+ *
+ * @remarks
+ * The DescribeModel manages the execution lifecycle of tests, including
+ * - Maintaining parent-child relationships between test suites
+ * - Executing hooks in the correct order (beforeAll, beforeEach, afterEach, afterAll)
+ * - Tracking test execution status and reporting results
+ * - Supporting test filtering with skip/only options
+ *
+ * @example
+ * ```ts
+ * const rootSuite = new DescribeModel('Root suite');
+ * const testCase = new TestModel('should work', () => {
+ *   expect(true).toBe(true);
+ * });
+ * rootSuite.addTest(testCase);
+ * await rootSuite.run({});
+ * ```
+ *
+ * @see TestModel
+ * @see HookModel
+ * @see DescribeHooksInterface
+ *
+ * @since 1.0.0
+ */
+declare class DescribeModel {
+    readonly description: string;
+    private readonly describeOptions;
+    /**
+     * Array containing the hierarchical path of parent describe blocks for this test suite
+     *
+     * @since 1.0.0
+     */
+    readonly ancestry: string[];
+    /**
+     * Creates a new test suite with the specified description and options
+     *
+     * @param description - Human-readable description of the test suite
+     * @param describeOptions - Configuration options to control test suite execution
+     *
+     * @since 1.0.0
+     */
+    constructor(description?: string, describeOptions?: DescribeOptionsInterface);
+    /**
+     * Retrieves the execution configuration options for this test suite
+     *
+     * @returns Test suite configuration options
+     *
+     * @since 1.0.0
+     */
+    get options(): DescribeOptionsInterface;
+    /**
+     * Gets all tests in this suite, including tests from nested suites
+     *
+     * @returns Flattened array of all tests in this suite and its children
+     *
+     * @remarks
+     * Recursively collects and flattens all test cases from this suite and any nested suites
+     *
+     * @since 1.0.0
+     */
+    get tests(): TestModel[];
+    /**
+     * Registers a hook function to be executed at a specific point in the test lifecycle
+     *
+     * @param type - The lifecycle point at which to execute the hook
+     * @param hook - The hook function model to register
+     *
+     * @throws Error - If an invalid hook type is provided
+     *
+     * @since 1.0.0
+     */
+    addHook(type: HookType, hook: HookModel): void;
+    /**
+     * Adds a test case to this test suite
+     *
+     * @param test - The test model to add to the suite
+     *
+     * @remarks
+     * When adding a test, this method automatically:
+     * - Updates the test's ancestry to include this suite
+     * - Propagates execution options (skip/only) from the suite to the test
+     *
+     * @since 1.0.0
+     */
+    addTest(test: TestModel): void;
+    /**
+     * Adds a nested test describe to this test describe
+     *
+     * @param describe - The child test describe to add
+     *
+     * @remarks
+     * When adding nested describe, this method automatically:
+     * - Sets up the parent-child relationship
+     * - Propagates execution options and ancestry information from parent to child
+     *
+     * @since 1.0.0
+     */
+    addDescribe(describe: DescribeModel): void;
+    /**
+     * Executes the test suite and all contained tests
+     *
+     * @param context - The test execution context containing shared state
+     * @returns Promise that resolves when all tests in the suite complete
+     *
+     * @remarks
+     * Execution follows this order:
+     * 1. Check if the suite is marked as skipped
+     * 2. Execute all beforeAll hooks
+     * 3. Run all tests in this suite
+     * 4. Run all nested test suites
+     * 5. Execute all afterAll hooks
+     * If any step fails, the entire suite is marked as failed
+     *
+     * @example
+     * ```ts
+     * const suite = new DescribeModel('My test suite');
+     * const context = createTestContext();
+     * await suite.run(context);
+     * ```
+     *
+     * @since 1.0.0
+     */
+    run(context: ContextType<ContextInterface>): Promise<void>;
+    /**
+     * Inherits properties from a parent test suite
+     *
+     * @param parent - The parent test describe to inherit from
+     *
+     * @remarks
+     * This method performs the following inheritance operations:
+     * - Adds parent's ancestry chain to this suite's ancestry
+     * - Propagates the 'skip' flag (if parent is skipped, child is skipped)
+     * - Propagates the 'only' flag if the parent has it set
+     *
+     * @since 1.0.0
+     */
+    inheritFromParentDescribe(parent: DescribeModel): void;
+    private notifyDescribeStatus;
+    private notifyDescribeAction;
+}
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Retrieves the location in the source code where this function was invoked.
+ *
+ * @param position - The stack frame index to inspect (default is 3). This allows skipping
+ *                   internal frames to reach the actual caller.
+ * @returns A {@link PacketInvocationInterface} containing `line`, `column`, and `source` file
+ *          of the invocation, or `undefined` if the location could not be determined.
+ *
+ * @remarks
+ * This function generates a new `Error` to capture the stack trace, parses it using
+ * {@link parseErrorStack}, and returns the requested frame as a structured object.
+ * It is useful for logging or reporting the exact location of a call within test suites
+ * or framework code.
+ *
+ * @see parseErrorStack
+ * @see PacketInvocationInterface
+ *
+ * @since 1.0.0
+ */
+declare function getInvocationLocation(position?: number): PacketInvocationInterface | undefined;
+/**
+ * Returns a native-style stack trace string,
+ * trimmed to start at the specified frame index.
+ *
+ * @remarks
+ * The first line (error name/message) is preserved,
+ * while the following lines are sliced starting from `position`.
+ *
+ * @param position - Index of the first stack frame to include.
+ *                   Defaults to `2` to skip this helper and its caller.
+ *
+ * @returns A string identical in format to `Error.stack`,
+ *          or an empty string if the stack is unavailable.
+ *
+ * @example
+ * ```ts
+ * console.log(getTrimmedStackString(2));
+ * ```
+ *
+ * @since 3.1.0
+ */
+declare function getTrimmedStackString(position?: number): string;
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Represents a test callback function that registers a named test with arguments and optional done callback
+ *
+ * @template T - The type of arguments passed to the test function
+ *
+ * @param name - The descriptive name of the test
+ * @param fn - The test implementation function that either accepts arguments and a done callback, or returns a Promise
+ * @returns A void function that registers the test in the testing framework
+ *
+ * @example
+ * ```ts
+ * const testEach: TestCallbackType<{value: number}> = (name, fn) => {
+ *   test(`Test ${name}`, (done) => {
+ *     fn({value: 42}, done);
+ *   });
+ * };
+ * ```
+ *
+ * @see TestDirectiveInterface - The interface that utilizes this callback type
+ * @since 1.0.0
+ */
+type TestCallbackType<T> = (name: string, fn: (args: T, done: DoneCallbackType) => void | ((args: T) => Promise<void>)) => void;
+interface TestDirectiveInterface {
+    /**
+     * Registers a test case with the given name and optional callback function
+     *
+     * @param name - The descriptive name of the test case
+     * @param fn - The callback function containing the test implementation
+     * @param timeout - The maximum time in milliseconds the test is allowed to run before timing out
+     * @returns Nothing
+     *
+     * @example
+     * ```ts
+     * test('should validate user input', () => {
+     *   const result = validateInput('test@example.com');
+     *   expect(result).toBe(true);
+     * });
+     *
+     * test('should handle async operations', async () => {
+     *   const data = await fetchUserData(1);
+     *   expect(data.name).toBe('John');
+     * }, 5000);
+     * ```
+     *
+     * @see CallbackHandlerType - The type definition for the test callback function
+     * @since 1.0.0
+     */
+    (name: string, fn?: CallbackHandlerType, timeout?: number): void;
+    /**
+     * Creates a skipped test that will be recognized but not executed during test runs
+     *
+     * @override
+     * @returns The same TestDirectiveInterface instance with skip flag enabled, allowing for method chaining
+     * @throws Error - When attempting to combine with 'only' flag which would create conflicting test behavior
+     *
+     * @remarks
+     * When applied, the test will be marked as skipped in test reports but won't be executed.
+     * Cannot be combined with the 'only' modifier due to conflicting behavior.
+     *
+     * @example
+     * ```ts
+     * test.skip('temporarily disabled test', () => {
+     *   expect(result).toBe(true);
+     * });
+     * ```
+     *
+     * @see TestDirectiveInterface
+     * @since 1.0.0
+     */
+    get skip(): TestDirectiveInterface;
+    /**
+     * Creates an exclusive test that will run while other non-exclusive tests are skipped
+     *
+     * @override
+     * @returns The same TestDirectiveInterface instance with only flag enabled, allowing for method chaining
+     * @throws Error - When attempting to combine with 'skip' flag which would create conflicting test behavior
+     *
+     * @remarks
+     * When applied, only this test and other tests marked with 'only' will be executed.
+     * This is useful for focusing on specific tests during development or debugging.
+     * Cannot be combined with the 'skip' modifier due to conflicting behavior.
+     *
+     * @example
+     * ```ts
+     * test.only('focus on this test', () => {
+     *   const result = performOperation();
+     *   expect(result).toBe(expectedValue);
+     * });
+     * ```
+     *
+     * @see TestDirectiveInterface
+     * @since 1.0.0
+     */
+    get only(): TestDirectiveInterface;
+    /**
+     * Marks a test as planned but not yet implemented or currently incomplete
+     *
+     * @override
+     * @returns The same TestDirectiveInterface instance with todo flag enabled, allowing for method chaining
+     * @throws Error - When attempting to combine with 'skip' flag which would create redundant test configuration
+     *
+     * @remarks
+     * Tests marked as todo will be reported in test results as pending or incomplete.
+     * This is useful for planning test cases before implementing them or for documenting
+     * tests that need to be written in the future.
+     *
+     * @example
+     * ```ts
+     * test.todo('implement validation test for email addresses');
+     *
+     * // Or with empty implementation
+     * test.todo('handle error cases', () => {
+     *   // To be implemented
+     * });
+     * ```
+     *
+     * @see TestDirectiveInterface
+     * @since 1.0.0
+     */
+    get todo(): TestDirectiveInterface;
+    /**
+     * Marks a test that is expected to fail, allowing tests to be committed even with known failures
+     *
+     * @override
+     * @returns The same TestDirectiveInterface instance with failing flag enabled, allowing for method chaining
+     * @throws Error - When attempting to combine with incompatible directives that would create ambiguous test behavior
+     *
+     * @remarks
+     * The failing directive is useful when you want to document a bug that currently makes a test fail.
+     * Tests marked as failing will be reported as passed when they fail, and failed when they pass.
+     * This helps maintain test suites that contain tests for known issues or bugs that haven't been fixed yet.
+     *
+     * @example
+     * ```ts
+     * test.failing('this bug is not fixed yet', () => {
+     *   const result = buggyFunction();
+     *   expect(result).toBe(expectedValue); // This will fail as expected
+     * });
+     * ```
+     *
+     * @see TestDirectiveInterface
+     * @since 1.0.0
+     */
+    get failing(): TestDirectiveInterface;
+    /**
+     * Creates a parameterized test suite with table data defined using template literals
+     *
+     * @template T - Array type containing the values for parameterized tests
+     * @param string - Template strings array containing the table header and row structure
+     * @param placeholders - Values to be inserted into the template strings to form the test data table
+     * @returns A function that accepts a title template and callback to define the test suite
+     * @throws Error - When the template format is invalid or doesn't match the provided values
+     *
+     * @remarks
+     * This method allows creating data-driven tests with a table-like syntax using template literals.
+     * Each row in the provided table represents a separate test case with different inputs.
+     * The values from each row will be mapped to named parameters in the test callback.
+     *
+     * The description supports parameter formatting with the following placeholders:
+     * - %p - pretty-format output
+     * - %s - String value
+     * - %d, %i - Number as integer
+     * - %f - Floating point value
+     * - %j - JSON string
+     * - %o - Object representation
+     * - %# - Index of the test case
+     * - %% - Single percent sign (doesn't consume an argument)
+     *
+     * Alternatively, you can inject object properties using $variable notation:
+     * - $variable - Injects the property value
+     * - $variable.path.to.value - Injects nested property values (works only with own properties)
+     * - $# - Injects the index of the test case
+     * - Note: $variable cannot be combined with printf formatting except for %%
+     *
+     * @example
+     * ```ts
+     * test.each`
+     *   a    | b    | expected
+     *   ${1} | ${1} | ${2}
+     *   ${2} | ${2} | ${4}
+     *   ${3} | ${3} | ${6}
+     * `('$a + $b should be $expected', ({a, b, expected}) => {
+     *   expect(a + b).toBe(expected);
+     * });
+     * ```
+     * @see each
+     * @see TestCallbackType
+     *
+     * @since 1.0.0
+     */
+    each<T extends ReadonlyArray<unknown>>(string: TemplateStringsArray, ...placeholders: T): TestCallbackType<Record<string, T[number]>>;
+    /**
+     * Creates a parameterized test suite with an array of test cases
+     *
+     * @template T - Array type representing the structure of each test case
+     * @param cases - One or more test cases, where each case is an array of values
+     * @returns A function that accepts a title template and callback to define the test suite
+     * @throws Error - When invalid test cases are provided or parameter count doesn't match the callback
+     *
+     * @remarks
+     * This method allows creating data-driven tests by providing an array of test cases.
+     * Each case array represents a separate test run with different parameters.
+     * The values from each array will be passed as arguments to the test callback function.
+     *
+     * The description supports parameter formatting with the following placeholders:
+     * - %p - pretty-format output
+     * - %s - String value
+     * - %d, %i - Number as integer
+     * - %f - Floating point value
+     * - %j - JSON string
+     * - %o - Object representation
+     * - %# - Index of the test case
+     * - %% - Single percent sign (doesn't consume an argument)
+     *
+     * Alternatively, you can inject object properties using $variable notation:
+     * - $variable - Injects the property value
+     * - $variable.path.to.value - Injects nested property values (works only with own properties)
+     * - $# - Injects the index of the test case
+     * - Note: $variable cannot be combined with printf formatting except for %%
+     *
+     * @example
+     * ```ts
+     * test.each(
+     *   [1, 1, 2],
+     *   [2, 2, 4],
+     *   [3, 3, 6]
+     * )('adds %i + %i to equal %i', (a, b, expected) => {
+     *   expect(a + b).toBe(expected);
+     * });
+     * ```
+     * @see each
+     * @see TestCallbackType
+     *
+     * @since 1.0.0
+     */
+    each<T extends Array<unknown> | [unknown]>(...cases: T[]): TestCallbackType<T>;
+    /**
+     * Creates a parameterized test suite with an array of generic test cases
+     *
+     * @template T - Type representing the structure of each test case
+     * @param args - One or more test cases of type T to be used as parameters
+     * @returns A function that accepts a title template and callback to define the test suite
+     * @throws Error - When invalid test cases are provided or parameter format doesn't match the callback expectations
+     *
+     * @remarks
+     * This method provides a flexible way to create data-driven tests using a variety of case types.
+     * The test callback will be executed once for each provided test case.
+     * Parameter values from each case will be passed to the test callback function.
+     *
+     * The description supports parameter formatting with the following placeholders:
+     * - %p - pretty-format output
+     * - %s - String value
+     * - %d, %i - Number as integer
+     * - %f - Floating point value
+     * - %j - JSON string
+     * - %o - Object representation
+     * - %# - Index of the test case
+     * - %% - Single percent sign (doesn't consume an argument)
+     *
+     * Alternatively, you can inject object properties using $variable notation:
+     * - $variable - Injects the property value
+     * - $variable.path.to.value - Injects nested property values (works only with own properties)
+     * - $# - Injects the index of the test case
+     * - Note: $variable cannot be combined with printf formatting except for %%
+     *
+     * @example
+     * ```ts
+     * // Using objects as test cases
+     * test.each(
+     *   { a: 1, b: 1, expected: 2 },
+     *   { a: 2, b: 2, expected: 4 },
+     *   { a: 3, b: 3, expected: 6 }
+     * )('adds $a + $b to equal $expected', ({a, b, expected}) => {
+     *   expect(a + b).toBe(expected);
+     * });
+     * ```
+     *
+     * @see each
+     * @see TestCallbackType
+     * @since 1.0.0
+     */
+    each<T>(...args: readonly T[]): TestCallbackType<T>;
+    /**
+     * Creates a parameterized test suite by spreading an array of test cases
+     *
+     * @template T - Array type containing the individual test cases
+     * @param args - Individual test cases spread from an array
+     * @returns A function that accepts a title template and callback to define the test suite
+     * @throws Error - When invalid test cases are provided or case format is incompatible with the test callback
+     *
+     * @remarks
+     * This method enables data-driven testing by spreading an array of test cases into individual parameters.
+     * Each element in the array represents a separate test case that will be executed individually.
+     * The test callback will be invoked once for each test case in the array.
+     *
+     * The description supports parameter formatting with the following placeholders:
+     * - %p - pretty-format output
+     * - %s - String value
+     * - %d, %i - Number as integer
+     * - %f - Floating point value
+     * - %j - JSON string
+     * - %o - Object representation
+     * - %# - Index of the test case
+     * - %% - Single percent sign (doesn't consume an argument)
+     *
+     * Alternatively, you can inject object properties using $variable notation:
+     * - $variable - Injects the property value
+     * - $variable.path.to.value - Injects nested property values (works only with own properties)
+     * - $# - Injects the index of the test case
+     * - Note: $variable cannot be combined with printf formatting except for %%
+     *
+     * @example
+     * ```ts
+     * const testCases = [
+     *   [1, 1, 2],
+     *   [2, 2, 4],
+     *   [3, 3, 6]
+     * ];
+     *
+     * test.each(...testCases)('adds %i + %i to equal %i', (a, b, expected) => {
+     *   expect(a + b).toBe(expected);
+     * });
+     * ```
+     * @see each
+     * @see TestCallbackType
+     *
+     * @since 1.0.0
+     */
+    each<T extends Array<unknown>>(...args: T): TestCallbackType<T[number]>;
+    /**
+     * Executes a function block as a test case with the specified description
+     *
+     * @param description - Human-readable description of what this test case is verifying
+     * @param block - Function to be executed as the test case implementation
+     * @param args - Optional array of arguments to pass to the test function
+     * @param timeout - Optional timeout in milliseconds for this specific test case
+     * @returns void
+     * @throws Error - When the test function throws an exception or an assertion fails
+     *
+     * @remarks
+     * This method provides a way to directly invoke a test function with optional arguments.
+     * It registers the test with the test runner and executes it during the test run phase.
+     * The provided description will be used for test reporting and identification.
+     *
+     * @example
+     * ```ts
+     * test.invoke('should add two numbers correctly', (a, b) => {
+     *   expect(a + b).toBe(3);
+     * }, [1, 2], 1000);
+     * ```
+     *
+     * @see FunctionType
+     * @since 1.0.0
+     */
+    invoke(description: string, block: FunctionType, args?: Array<unknown>, timeout?: number): void;
+}
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Represents a callback function type used for parameterized test suite definitions.
+ *
+ * @template T - The type of arguments passed to the test function
+ *
+ * @param name - The title of the describe block, which can include parameter placeholders
+ * @param fn - The function containing the tests to be run, which receives the test parameters
+ *
+ * @returns void
+ *
+ * @remarks
+ * This type definition is used for creating parameterized test suites where test data
+ * is passed to the test function. The name parameter supports various placeholder formats
+ * to incorporate test data into the test suite title.
+ *
+ * @since 1.0.0
+ */
+type DescribeCallbackType<T> = (name: string, fn: (args: T) => void) => void;
+/**
+ * Interface defining the describe directive functionality for test organization.
+ *
+ * The describe directive creates a block that groups together related tests.
+ * It serves as the primary organizational structure for test suites, allowing
+ * developers to group related test cases and create a hierarchy of test blocks.
+ *
+ * @template T - The type parameter for the describe directive
+ *
+ * @remarks
+ * Describe blocks can be nested within each other to create logical groupings of tests.
+ * They can also have before/after hooks attached to them for setup and teardown code.
+ *
+ * @example
+ * ```ts
+ * describe('Calculator', () => {
+ *   describe('add method', () => {
+ *     test('adds two positive numbers', () => {
+ *       expect(calculator.add(1, 2)).toBe(3);
+ *     });
+ *
+ *     test('adds a positive and negative number', () => {
+ *       expect(calculator.add(1, -2)).toBe(-1);
+ *     });
+ *   });
+ * });
+ * ```
+ *
+ * @see TestCase
+ * @see TestDirectiveInterface
+ *
+ * @since 1.0.0
+ */
+interface DescribeDirectiveInterface {
+    /**
+     * Executes a test suite block with the given name and test function.
+     *
+     * @param name - The title of the test suite
+     * @param fn - The function containing the tests to be run within this suite
+     *
+     * @returns void
+     *
+     * @example
+     * ```ts
+     * describe('User authentication', () => {
+     *   test('should log in with valid credentials', () => {
+     *     // Test implementation
+     *     expect(login('user', 'password')).toBe(true);
+     *   });
+     *
+     *   test('should fail with invalid credentials', () => {
+     *     // Test implementation
+     *     expect(login('user', 'wrong')).toBe(false);
+     *   });
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
+    (name: string, fn: () => void): void;
+    /**
+     * Marks this describe to be skipped during test execution.
+     *
+     * @returns this - The current instance for method chaining
+     *
+     * @example
+     * ```ts
+     * describe.skip('Features under development', () => {
+     *   test('new feature', () => {
+     *     // This test will be skipped
+     *   });
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
+    get skip(): this;
+    /**
+     * Marks this test suite to be the only one executed in the current context.
+     *
+     * @returns this - The current instance for method chaining
+     *
+     * @example
+     * ```ts
+     * describe.only('Critical functionality', () => {
+     *   test('core feature', () => {
+     *     // Only this suite will run
+     *   });
+     * });
+     * ```
+     *
+     * @since 1.0.0
+     */
+    get only(): this;
+    /**
+     * Creates parameterized test suites using template literals with placeholders.
+     *
+     * @template T - Array type representing the test case data
+     *
+     * @param string - Template string with placeholders for test data
+     * @param placeholders - Values to be substituted into the template string placeholders
+     *
+     * @returns A callback function that accepts a test name pattern and implementation function
+     *
+     * @remarks
+     * The name parameter can include formatters:
+     * - Generate unique test titles by positionally injecting parameters with printf formatting:
+     *   - %p - pretty-format
+     *   - %s - String
+     *   - %d - Number
+     *   - %i - Integer
+     *   - %f - Floating point value
+     *   - %j - JSON
+     *   - %o - Object
+     *   - %# - Index of the test case
+     *   - %% - Single percent sign ('%'). This does not consume an argument
+     * - Or generate unique test titles by injecting properties of test case object with $variable:
+     *   - To inject nested object values supply a keyPath i.e. $variable.path.to.value (only works for "own" properties)
+     *   - Use $# to inject the index of the test case
+     *   - You cannot use $variable with printf formatting except for %%
+     *
+     * The fn parameter is the function that will receive the parameters in each row as function arguments.
+     * Optionally, you can provide a timeout (in milliseconds) for specifying how long to wait for each row before aborting. The default timeout is 5 seconds.
+     *
+     * @example
+     * ```ts
+     * describe.each`
+     *   a    | b    | expected
+     *   ${1} | ${1} | ${2}
+     *   ${2} | ${3} | ${5}
+     * `('$a + $b = $expected', ({ a, b, expected }) => {
+     *   test('adds correctly', () => {
+     *     expect(a + b).toBe(expected);
+     *   });
+     * });
+     * ```
+     *
+     * @see DescribeCallbackType
+     * @since 1.0.0
+     */
+    each<T extends ReadonlyArray<unknown>>(string: TemplateStringsArray, ...placeholders: T): DescribeCallbackType<Record<string, T[number]>>;
+    /**
+     * Creates parameterized test suites from arrays of test case values.
+     *
+     * @template T - Type representing arrays of test cases
+     *
+     * @param cases - Arrays containing the test case data
+     *
+     * @returns A callback function that accepts a test name pattern and implementation function
+     *
+     * @remarks
+     * The name parameter can include formatters:
+     * - Generate unique test titles by positionally injecting parameters with printf formatting:
+     *   - %p - pretty-format
+     *   - %s - String
+     *   - %d - Number
+     *   - %i - Integer
+     *   - %f - Floating point value
+     *   - %j - JSON
+     *   - %o - Object
+     *   - %# - Index of the test case
+     *   - %% - Single percent sign ('%'). This does not consume an argument
+     * - Or generate unique test titles by injecting properties of test case object with $variable:
+     *   - To inject nested object values supply a keyPath i.e. $variable.path.to.value (only works for "own" properties)
+     *   - Use $# to inject the index of the test case
+     *   - You cannot use $variable with printf formatting except for %%
+     *
+     * The fn parameter is the function that will receive the parameters in each row as function arguments.
+     * Optionally, you can provide a timeout (in milliseconds) for specifying how long to wait for each row before aborting. The default timeout is 5 seconds.
+     *
+     * @example
+     * ```ts
+     * describe.each([
+     *   [1, 1, 2],
+     *   [2, 3, 5]
+     * ])('add(%i, %i) = %i', (a, b, expected) => {
+     *   test('adds correctly', () => {
+     *     expect(a + b).toBe(expected);
+     *   });
+     * });
+     * ```
+     *
+     * @see DescribeCallbackType
+     * @since 1.0.0
+     */
+    each<T extends Array<unknown> | [unknown]>(...cases: T[]): DescribeCallbackType<T>;
+    /**
+     * Creates parameterized test suites from individual test case values.
+     *
+     * @template T - Type representing the test case data
+     *
+     * @param args - Individual test case values
+     *
+     * @returns A callback function that accepts a test name pattern and implementation function
+     *
+     * @remarks
+     * The name parameter can include formatters:
+     * - Generate unique test titles by positionally injecting parameters with printf formatting:
+     *   - %p - pretty-format
+     *   - %s - String
+     *   - %d - Number
+     *   - %i - Integer
+     *   - %f - Floating point value
+     *   - %j - JSON
+     *   - %o - Object
+     *   - %# - Index of the test case
+     *   - %% - Single percent sign ('%'). This does not consume an argument
+     * - Or generate unique test titles by injecting properties of test case object with $variable:
+     *   - To inject nested object values supply a keyPath i.e. $variable.path.to.value (only works for "own" properties)
+     *   - Use $# to inject the index of the test case
+     *   - You cannot use $variable with printf formatting except for %%
+     *
+     * The fn parameter is the function that will receive the parameters in each row as function arguments.
+     * Optionally, you can provide a timeout (in milliseconds) for specifying how long to wait for each row before aborting. The default timeout is 5 seconds.
+     *
+     * @example
+     * ```ts
+     * describe.each(
+     *   { name: 'John', age: 30 },
+     *   { name: 'Jane', age: 25 }
+     * )('Testing $name', (person) => {
+     *   test('age check', () => {
+     *     expect(person.age).toBeGreaterThan(18);
+     *   });
+     * });
+     * ```
+     *
+     * @see DescribeCallbackType
+     * @since 1.0.0
+     */
+    each<T>(...args: readonly T[]): DescribeCallbackType<T>;
+    /**
+     * Creates parameterized test suites from individual objects or primitive values.
+     *
+     * @template T - Array type representing the test case data
+     *
+     * @param args - Individual test case values in an array
+     *
+     * @returns A callback function that accepts a test name pattern and implementation function
+     *
+     * @remarks
+     * The name parameter can include formatters:
+     * - Generate unique test titles by positionally injecting parameters with printf formatting:
+     *   - %p - pretty-format
+     *   - %s - String
+     *   - %d - Number
+     *   - %i - Integer
+     *   - %f - Floating point value
+     *   - %j - JSON
+     *   - %o - Object
+     *   - %# - Index of the test case
+     *   - %% - Single percent sign ('%'). This does not consume an argument
+     * - Or generate unique test titles by injecting properties of test case object with $variable:
+     *   - To inject nested object values supply a keyPath i.e. $variable.path.to.value (only works for "own" properties)
+     *   - Use $# to inject the index of the test case
+     *   - You cannot use $variable with printf formatting except for %%
+     *
+     * The fn parameter is the function that will receive the parameters in each row as function arguments.
+     * Optionally, you can provide a timeout (in milliseconds) for specifying how long to wait for each row before aborting. The default timeout is 5 seconds.
+     *
+     * @example
+     * ```ts
+     * describe.each(
+     *   1, 2, 3, 4
+     * )('Testing with value %i', (value) => {
+     *   test('is positive', () => {
+     *     expect(value).toBeGreaterThan(0);
+     *   });
+     * });
+     * ```
+     *
+     * @see DescribeCallbackType
+     *
+     * @since 1.0.0
+     */
+    each<T extends Array<unknown>>(...args: T): DescribeCallbackType<T[number]>;
+    /**
+     * Invokes a test block with the specified description and function.
+     *
+     * @param description - String for the title of the test block
+     * @param block - Function that contains the test logic to be executed
+     * @param args - Optional array of arguments to pass to the test function
+     *
+     * @remarks
+     * The description parameter can include formatters:
+     * - Generate unique test titles by positionally injecting parameters with printf formatting:
+     *   - %p - pretty-format
+     *   - %s - String
+     *   - %d - Number
+     *   - %i - Integer
+     *   - %f - Floating point value
+     *   - %j - JSON
+     *   - %o - Object
+     *   - %# - Index of the test case
+     *   - %% - Single percent sign ('%'). This does not consume an argument
+     * - Or generate unique test titles by injecting properties of test case object with $variable:
+     *   - To inject nested object values supply a keyPath i.e. $variable.path.to.value (only works for "own" properties)
+     *   - Use $# to inject the index of the test case
+     *   - You cannot use $variable with printf formatting except for %%
+     *
+     * The block parameter is the function that will receive the parameters in each row as function arguments.
+     * Optionally, you can provide a timeout (in milliseconds) for specifying how long to wait for each row before aborting. The default timeout is 5 seconds.
+     *
+     * @returns void
+     */
+    invoke(description: string, block: FunctionType, args?: Array<unknown>): void;
+}
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Represents a test runner engine responsible for executing bundled test files.
+ *
+ * @remarks
+ * A `TestRunnerInterface` abstracts the underlying JavaScript engine
+ * that runs the test bundles produced by xJet.
+ *
+ * Its responsibilities include:
+ * - Receiving a bundled test suite and executing it.
+ * - Establishing a communication channel with xJet to stream results and test events.
+ * - Handling timeouts, disconnections, and cleanup.
+ *
+ * Custom runners can be implemented to run tests in different environments
+ * (e.g., Node.js, browser, Deno, or even remote workers).
+ *
+ * @since 1.0.0
+ */
+export interface TestRunnerInterface {
+    /**
+     * Optional unique identifier for this runner instance.
+     *
+     * If not provided, xJet will automatically generate and assign
+     * a runner ID when the runner is registered.
+     *
+     * @since 1.0.0
+     */
+    id?: string;
+    /**
+     * Human-readable name of the test runner (e.g., `"NodeRunner"`, `"BrowserRunner"`).
+     *
+     * @since 1.0.0
+     */
+    name: string;
+    /**
+     * Maximum time (in milliseconds) allowed for establishing a connection
+     * between xJet and the runner.
+     *
+     * @since 1.0.0
+     */
+    connectionTimeout?: number;
+    /**
+     * Maximum time (in milliseconds) allowed for a test suite execution.
+     * @since 1.0.0
+     */
+    dispatchTimeout?: number;
+    /**
+     * Sends a compiled/bundled test suite to the runner for execution.
+     *
+     * @param suite - The compiled JavaScript test suite as a binary buffer.
+     * @param suiteId - A unique identifier for the test suite.
+     * @returns A promise that resolves once the suite has been successfully dispatched.
+     *
+     * @since 1.0.0
+     */
+    dispatch(suite: Buffer, suiteId: string): Promise<void> | void;
+    /**
+     * Establishes a communication channel with the runner to receive results.
+     *
+     * @param resolve - Callback invoked whenever the runner sends results back.
+     * @param runnerId - A unique identifier for this runner instance.
+     * @param argv - Optional arguments to pass throw the cli.
+     *
+     * @returns A promise that resolves once the connection is active.
+     *
+     * @since 1.0.0
+     */
+    connect(resolve: (data: Buffer) => void, runnerId: string, argv: Record<string, unknown>): Promise<void> | void;
+    /**
+     * Disconnects the runner and cleans up resources.
+     *
+     * @returns A promise that resolves once the disconnection is complete.
+     *
+     * @since 1.0.0
+     */
+    disconnect?(): Promise<void> | void;
+}
+/**
+ * Defines the configuration options available for the xJet test runner.
+ *
+ * @remarks
+ * The configuration controls test discovery, filtering, reporting, execution
+ * behavior, and build options.
+ *
+ * @since 1.0.0
+ */
+interface ConfigurationInterface {
+    /**
+     * Positional arguments passed to xJet that are not recognized as flags.
+     * @since 1.0.0
+     */
+    _: Array<string>;
+    /**
+     * If `true`, stop running tests after the first failure.
+     * @since 1.0.0
+     */
+    bail: boolean;
+    /**
+     * If `true`, watch files for changes and re-run tests automatically.
+     * @since 1.0.0
+     */
+    watch: boolean;
+    /**
+     * Glob patterns or file paths used to discover test files.
+     *
+     * @example
+     * ```ts
+     * files: ["**\/*.test.ts", "**\/*.spec.ts", "src/specific/file.test.ts"]
+     * ```
+     *
+     * @since 1.0.0
+     */
+    files: Array<string | RegExp>;
+    /**
+     * A subset of test files (by path or glob) selected from {@link files}.
+     *
+     * @remarks
+     * - Supports glob syntax (e.g., `"tests/unit/**\/*.test.ts"`).
+     * - Can also include explicit absolute or relative file paths.
+     * - Entries must resolve to files already discovered in {@link files},
+     *   or be parent directories of such files.
+     * - Acts as a filter on top of {@link files}: only the matching files will run.
+     * - If not set, all files from {@link files} will run.
+     *
+     * @example
+     * ```ts
+     * files: ["**\/*.test.ts"],
+     * suites: ["tests/unit/**\/*.test.ts"] // runs only tests in `tests/unit`
+     *
+     * files: ["**\/*.test.ts"],
+     * suites: ["tests/math/add.test.ts"] // runs only this file
+     * ```
+     *
+     * @since 1.0.0
+     */
+    suites: Array<string>;
+    /**
+     * A list of test names (`it`, `test`) or suite names (`describe`) to run.
+     *
+     * @remarks
+     * - If set, only the tests or suites listed here will be executed.
+     * - If not set, all tests in the discovered files will run.
+     *
+     * @since 1.0.0
+     */
+    filter: Array<string>;
+    /**
+     * Logging verbosity level for test execution.
+     *
+     * @remarks
+     * Determines which messages are shown during test runs.
+     * Controlled via {@link LogLevel}, which includes levels such as
+     * `Silent`, `Error`, `Warn`, `Info`, `Trace`, and `Debug`.
+     *
+     * This provides finer control than the `silent` flag,
+     * allowing reporters or console output to show only the
+     * desired level of detail.
+     *
+     * @since 1.0.0
+     */
+    logLevel: keyof typeof LogLevel;
+    /**
+     * Maximum time (in milliseconds) a single test can run before being marked as failed.
+     * @since 1.0.0
+     */
+    timeout: number;
+    /**
+     * If true, include both xJet internal and native stack traces in error output.
+     *
+     * @remarks
+     * - When `false`, stack traces are minimized to user code only.
+     * - When `true`, full stack traces are printed, including internal frames.
+     *
+     * @since 1.0.0
+     */
+    verbose: boolean;
+    /**
+     * A list of files or patterns to exclude from the test run.
+     *
+     * @since 1.0.0
+     */
+    exclude: Array<string | RegExp>;
+    /**
+     * The reporter to use for test results.
+     *
+     * @remarks
+     * - Accepts either a built-in reporter name or a path to a custom reporter module.
+     * - Built-in reporters: `"spec"` (default), `"json"`, `"junit"`.
+     * - If a file path is provided, it must resolve to a JavaScript module
+     *   that exports a reporter implementation.
+     *
+     * @example
+     * ```ts
+     * reporter: "spec"              // Use a built-in spec reporter.
+     * reporter: "json"              // Output results as JSON
+     * reporter: "junit"             // Output results in JUnit XML format
+     * reporter: "./my-reporter.ts"  // Use a custom reporter from a local file
+     * ```
+     *
+     * @since 1.0.0
+     */
+    reporter: string | 'spec' | 'junit' | 'json';
+    /**
+     * Number of test files to run in parallel.
+     * @since 1.0.0
+     */
+    parallel: number;
+    /**
+     * If `true`, randomize the order of test execution.
+     * @since 1.0.0
+     */
+    randomize: boolean;
+    /**
+     * If `true`, omit stack traces entirely from error output.
+     * @since 1.0.0
+     */
+    noStackTrace: boolean;
+    /**
+     * Optional list of custom test runners to use instead of the default Node.js runner.
+     * @since 1.0.0
+     */
+    testRunners?: Array<TestRunnerInterface>;
+    /**
+     * Optional file path to write reporter output.
+     *
+     * @remarks
+     * - If set, results will be printed to `stdout` and also written to this file.
+     * - Useful for CI/CD pipelines that require machine-readable results
+     *   (e.g., `junit.xml` or `results.json`).
+     *
+     * @example
+     * ```ts
+     * reporter: "junit",
+     * outputFile: "reports/junit.xml"
+     * ```
+     *
+     * @since 1.1.0
+     */
+    outputFile?: string;
+    /**
+     * Optional object containing user-defined CLI options parsed by `yargs`.
+     *
+     * @remarks
+     * - This allows users to define custom CLI options dynamically at runtime.
+     * - Keys are option names, values are typed according to `yargs` parsing rules.
+     * - Supports strings, numbers, booleans, arrays, and nested options.
+     *
+     * @example
+     * ```ts
+     * userArgv: {
+     *   host: "localhost",
+     *   port: 8080,
+     *   debug: true
+     * }
+     * ```
+     *
+     * @since 1.0.0
+     */
+    userArgv?: Record<string, Options>;
+    /**
+     * Build configuration applied when transpiling or bundling test files.
+     * @since 1.0.0
+     */
+    build: {
+        /**
+         * ECMAScript target(s) for build output (e.g., `"esnext"`, `"es2019"`).
+         * @since 1.0.0
+         */
+        target?: BuildOptions['target'];
+        /**
+         * External dependencies to exclude from the test bundle.
+         * @since 1.0.0
+         */
+        external?: BuildOptions['external'];
+        /**
+         * Platform target for execution:
+         * - `"browser"`
+         * - `"node"`
+         * - `"neutral"`
+         *
+         * @since 1.0.0
+         */
+        platform?: BuildOptions['platform'];
+        /**
+         * Defines how packages are resolved:
+         * - `"bundle"` → include them in the output bundle
+         * - `"external"` → require them at runtime
+         *
+         * @since 1.0.0
+         */
+        packages?: BuildOptions['packages'];
+    };
+}
+/**
+ * Represents a configuration object specific to xJet, allowing for partial and deeply nested properties to be defined.
+ *
+ * This type is a partial deep version of the `ConfigurationInterface`, enabling flexible configuration by only requiring
+ * the properties that need to be customized, while other properties can take their default values.
+ *
+ * @remarks
+ * The `xJetConfig` type is useful when working with extensive configuration objects where only a subset of properties
+ * needs to be overridden. It enables better maintainability and cleaner code by avoiding the need to specify the entire
+ * structure of the `ConfigurationInterface`.
+ *
+ * @see ConfigurationInterface
+ *
+ * @since 1.0.0
+ */
+export type xJetConfig = Partial<ConfigurationInterface>;
+
+/**
+ * Export interfaces
+ */
+/**
+ * Export constants
+ */
+/**
+ * Export abstract
+ */
+
+/**
+ * Represents the result of a single assertion within a test.
+ *
+ * @remarks
+ * This interface captures the outcome of an assertion and allows
+ * for extensible additional properties.
+ *
+ * @example
+ * ```ts
+ * const result: AssertionResultInterface = {
+ *   name: 'should add numbers correctly',
+ *   pass: true,
+ *   expected: 4,
+ *   received: 4
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ */
+export interface AssertionResultInterface {
+    /**
+     * Optional name or description of the assertion.
+     * @since 1.0.0
+     */
+    name?: string;
+    /**
+     * Indicates whether the assertion passed (`true`) or failed (`false`).
+     * @since 1.0.0
+     */
+    pass?: boolean;
+    /**
+     * Optional message describing the assertion result or reason for failure.
+     * @since 1.0.0
+     */
+    message?: string;
+    /**
+     * Optional value that was expected in the assertion.
+     * @since 1.0.0
+     */
+    expected?: unknown;
+    /**
+     * Optional actual value received in the assertion.
+     * @since 1.0.0
+     */
+    received?: unknown;
+    /**
+     * Additional arbitrary properties relevant to the assertion result.
+     * @since 1.0.0
+     */
+    [key: string]: unknown;
+}
+/**
+ * Represents the invocation point of a test suite in the source code.
+ *
+ * @remarks
+ * This interface captures the location and source of a suite definition,
+ * useful for reporting, debugging, or mapping transpiled code back to
+ * the original source.
+ *
+ * @example
+ * ```ts
+ * const suiteInvocation: SuiteInvocationInterface = {
+ *   code: 'describe("MySuite", () => {})',
+ *   line: 10,
+ *   column: 5,
+ *   source: '/path/to/test.spec.ts'
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ */
+export interface SuiteInvocationInterface {
+    /**
+     * The code string representing the suite invocation.
+     * @since 1.0.0
+     */
+    code: string;
+    /**
+     * The line number in the source file where the suite is defined.
+     * @since 1.0.0
+     */
+    line: number;
+    /**
+     * The column number in the source file where the suite starts.
+     * @since 1.0.0
+     */
+    column: number;
+    /**
+     * The absolute or relative path to the source file containing the suite.
+     * @since 1.0.0
+     */
+    source: string;
+}
+/**
+ * Represents an error that occurred within a test suite.
+ *
+ * @remarks
+ * This interface captures the essential information about a suite-level
+ * error, including its location, message, stack trace, and optional
+ * assertion result if the error originated from a failed expectation.
+ *
+ * @example
+ * ```ts
+ * const error: SuiteErrorInterface = {
+ *   code: 'expect(value).toBe(4)',
+ *   name: 'AssertionError',
+ *   line: 12,
+ *   column: 5,
+ *   stack: 'Error: ...',
+ *   message: 'Expected 3 to be 4',
+ *   matcherResult: {
+ *     pass: false,
+ *     expected: 4,
+ *     received: 3
+ *   }
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ */
+export interface SuiteErrorInterface {
+    /**
+     * The code snippet that caused the error.
+     * @since 1.0.0
+     */
+    code: string;
+    /**
+     * The format code snippet that caused the error.
+     * @since 1.0.0
+     */
+    formatCode: string;
+    /**
+     * The type or name of the error (e.g., 'AssertionError').
+     * @since 1.0.0
+     */
+    name: string;
+    /**
+     * The line number in the source file where the error occurred.
+     * @since 1.0.0
+     */
+    line: number;
+    /**
+     * The column number in the source file where the error occurred.
+     * @since 1.0.0
+     */
+    column: number;
+    /**
+     * The stack trace of the error.
+     * @since 1.0.0
+     */
+    stack: string;
+    /**
+     * The human-readable error message.
+     * @since 1.0.0
+     */
+    message: string;
+    /**
+     * Optional assertion result if the error originated from a failed expectation.
+     *
+     * @see AssertionResultInterface
+     * @since 1.0.0
+     */
+    matcherResult?: AssertionResultInterface;
+}
+/**
+ * Represents an error that occurs within a test suite.
+ *
+ * @remarks
+ * Provides detailed information about the error, including location in the
+ * source file, stack trace, and optionally the result of a failed assertion.
+ *
+ * @example
+ * ```ts
+ * const error: SuiteErrorInterface = {
+ *   code: 'expect(value).toBe(4)',
+ *   name: 'AssertionError',
+ *   line: 12,
+ *   column: 5,
+ *   stack: 'Error: ...',
+ *   message: 'Expected 3 to be 4',
+ *   matcherResult: {
+ *     pass: false,
+ *     expected: 4,
+ *     received: 3
+ *   }
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ */
+export interface SuiteErrorInterface {
+    /**
+     * The source code snippet that caused the error.
+     * @since 1.0.0
+     */
+    code: string;
+    /**
+     * The type or name of the error (e.g., 'AssertionError').
+     * @since 1.0.0
+     */
+    name: string;
+    /**
+     * The line number in the source file where the error occurred.
+     * @since 1.0.0
+     */
+    line: number;
+    /**
+     * The column number in the source file where the error occurred.
+     * @since 1.0.0
+     */
+    column: number;
+    /**
+     * The stack trace of the error.
+     * @since 1.0.0
+     */
+    stack: string;
+    /**
+     * The human-readable error message.
+     * @since 1.0.0
+     */
+    message: string;
+    /**
+     * Optional result of the assertion that caused the error if applicable.
+     * @since 1.0.0
+     */
+    matcherResult?: AssertionResultInterface;
+}
+/**
+ * Represents a structured log message emitted during test execution.
+ *
+ * @remarks
+ * Log messages are used by reporters to capture runtime information,
+ * including standard logs, warnings, errors, and contextual metadata.
+ *
+ * @example
+ * ```ts
+ * const log: LogMessageInterface = {
+ *   level: 'info',
+ *   levelId: 3,
+ *   suite: 'loginTests',
+ *   runner: 'chrome',
+ *   message: 'Test started',
+ *   ancestry: ['a', 'b', 'c']
+ *   timestamp: new Date(),
+ *   invocation: {
+ *     code: 'describe("Login", ...)',
+ *     line: 10,
+ *     column: 5,
+ *     source: '/path/to/login.spec.ts'
+ *   }
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ */
+export interface LogMessageInterface {
+    /**
+     * The log level as a string (e.g., 'info', 'error').
+     * @since 1.0.0
+     */
+    level: string;
+    /**
+     * The name or ID of the suite associated with this log.
+     * @since 1.0.0
+     */
+    suite: string;
+    /**
+     * The name or ID of the runner that emitted this log.
+     * @since 1.0.0
+     */
+    runner: string;
+    /**
+     * The numeric representation of the log level.
+     * @since 1.0.0
+     */
+    levelId: number;
+    /**
+     * The human-readable log message.
+     * @since 1.0.0
+     */
+    message: string;
+    /**
+     * The timestamp when the log was created.
+     * @since 1.0.0
+     */
+    timestamp: Date;
+    /**
+     * The hierarchy of parent suites or `describes` or `test` blocks for this assertion.
+     * @since 1.0.0
+     */
+    ancestry: Array<string>;
+    /**
+     * Optional information about the suite invocation that generated this log.
+     *
+     * @see SuiteInvocationInterface
+     * @since 1.0.0
+     */
+    invocation?: SuiteInvocationInterface;
+}
+/**
+ * Represents the event emitted when a test suite starts execution.
+ *
+ * @remarks
+ * Reporters can use this event to initialize suite-level logging,
+ * display headers, or track suite execution timing.
+ *
+ * @example
+ * ```ts
+ * const startEvent: StartMessageInterface = {
+ *   suite: 'loginTests',
+ *   runner: 'chrome',
+ *   timestamp: new Date()
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ */
+export interface StartMessageInterface {
+    /**
+     * The name or ID of the suite that is starting.
+     * @since 1.0.0
+     */
+    suite: string;
+    /**
+     * The name or ID of the runner executing this suite.
+     * @since 1.0.0
+     */
+    runner: string;
+    /**
+     * The timestamp when the suite started execution.
+     * @since 1.0.0
+     */
+    timestamp: Date;
+}
+/**
+ * Represents the event emitted when a test suite finishes execution.
+ *
+ * @remarks
+ * Extends {@link StartMessageInterface} with additional information
+ * such as the duration of the suite and any errors encountered.
+ * Reporters can use this event to summarize results and handle
+ * suite-level failures.
+ *
+ * @example
+ * ```ts
+ * const endEvent: EndMessageInterface = {
+ *   suite: 'loginTests',
+ *   runner: 'chrome',
+ *   timestamp: new Date(),
+ *   duration: 120,
+ *   error: {
+ *     code: 'expect(value).toBe(4)',
+ *     name: 'AssertionError',
+ *     line: 12,
+ *     column: 5,
+ *     stack: 'Error: ...',
+ *     message: 'Expected 3 to be 4'
+ *   }
+ * };
+ * ```
+ *
+ * @see StartMessageInterface
+ * @see SuiteErrorInterface
+ *
+ * @since 1.0.0
+ */
+export interface EndMessageInterface extends StartMessageInterface {
+    /**
+     * The duration of the suite execution in milliseconds.
+     * @since 1.0.0
+     */
+    duration: number;
+    /**
+     * Optional error that occurred during the suite execution.
+     * @since 1.0.0
+     */
+    error?: SuiteErrorInterface;
+}
+/**
+ * Represents the event emitted when an individual assertion or `describe` or `test` block starts execution.
+ *
+ * @remarks
+ * Extends {@link StartMessageInterface} with additional information specific
+ * to assertions, such as ancestry, description, and optional flags for skipped or todo tests.
+ * Reporters can use this event to track assertion execution and organize output hierarchically.
+ *
+ * @example
+ * ```ts
+ * const startAssertion: StartAssertionMessageInterface = {
+ *   suite: 'loginTests',
+ *   runner: 'chrome',
+ *   timestamp: new Date(),
+ *   ancestry: ['Login Suite', 'User Authentication'],
+ *   description: 'should log in successfully',
+ *   skipped: false
+ * };
+ * ```
+ *
+ * @see StartMessageInterface
+ *
+ * @since 1.0.0
+ */
+export interface StartAssertionMessageInterface extends StartMessageInterface {
+    /**
+     * Indicates if the assertion is marked as "todo".
+     * @since 1.0.0
+     */
+    todo?: boolean;
+    /**
+     * Indicates if the assertion is skipped.
+     * @since 1.0.0
+     */
+    skipped?: boolean;
+    /**
+     * The hierarchy of parent suites or `describes` blocks for this assertion.
+     * @since 1.0.0
+     */
+    ancestry: Array<string>;
+    /**
+     * The human-readable description of the assertion.
+     * @since 1.0.0
+     */
+    description: string;
+}
+/**
+ * Represents the event emitted when an individual assertion or `describes` or `test` block finishes execution.
+ *
+ * @remarks
+ * Extends {@link StartMessageInterface} with assertion-specific details
+ * such as pass/fail status, errors, ancestry, duration, and description.
+ * Reporters can use this event to track results and generate detailed output.
+ *
+ * @example
+ * ```ts
+ * const endAssertion: EndAssertionMessageInterface = {
+ *   suite: 'loginTests',
+ *   runner: 'chrome',
+ *   timestamp: new Date(),
+ *   passed: false,
+ *   errors: [
+ *     {
+ *       code: 'expect(value).toBe(4)',
+ *       name: 'AssertionError',
+ *       line: 12,
+ *       column: 5,
+ *       stack: 'Error: ...',
+ *       message: 'Expected 3 to be 4'
+ *     }
+ *   ],
+ *   ancestry: ['Login Suite', 'User Authentication'],
+ *   duration: 50,
+ *   description: 'should log in successfully'
+ * };
+ * ```
+ *
+ * @see StartMessageInterface
+ * @see SuiteErrorInterface
+ *
+ * @since 1.0.0
+ */
+export interface EndAssertionMessageInterface extends StartMessageInterface {
+    /**
+     * Indicates whether the assertion passed (`true`) or failed (`false`).
+     * @since 1.0.0
+     */
+    passed: boolean;
+    /**
+     * Optional array of errors that occurred during this assertion.
+     *
+     * @see SuiteErrorInterface
+     * @since 1.0.0
+     */
+    errors?: Array<SuiteErrorInterface>;
+    /**
+     * The hierarchy of parent suites or `describe` blocks for this assertion.
+     * @since 1.0.0
+     */
+    ancestry: Array<string>;
+    /**
+     * The duration of the assertion execution in milliseconds.
+     * @since 1.0.0
+     */
+    duration: number;
+    /**
+     * The human-readable description of the assertion.
+     * @since 1.0.0
+     */
+    description: string;
+}
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Base class for implementing custom reporters.
+ *
+ * @remarks
+ * The `AbstractReporter` defines lifecycle hooks that can be implemented
+ * by concrete reporter classes to customize how test results are reported.
+ *
+ * Reporters receive structured event messages during test execution,
+ * including suite start/end, describe/test assertions, logs, and finalization.
+ *
+ * Each method is optional (`?`) and may be implemented depending on
+ * the reporter’s needs (e.g., console logging, file output, JSON reporting).
+ *
+ * @example
+ * ```ts
+ * class ConsoleReporter extends AbstractReporter {
+ *   log(log: LogMessageInterface): void {
+ *     console.log(`[LOG] ${log.message}`);
+ *   }
+ *
+ *   suiteStart(event: StartMessageInterface): void {
+ *     console.log(`Suite started: ${event.suiteName}`);
+ *   }
+ * }
+ * ```
+ *
+ * @see RunnerInterface
+ * @see LogMessageInterface
+ * @see StartMessageInterface
+ * @see EndMessageInterface
+ *
+ * @since 1.0.0
+ */
+export declare abstract class AbstractReporter {
+    protected readonly logLevel: LogLevel;
+    protected readonly outFilePath?: string | undefined;
+    /**
+     * Creates a new reporter.
+     *
+     * @param logLevel - The minimum log level this reporter should handle.
+     * @param outFilePath - Optional file path where logs or reports should be written.
+     */
+    constructor(logLevel: LogLevel, outFilePath?: string | undefined);
+    /**
+     * Initializes the reporter before test execution starts.
+     *
+     * @remarks
+     * This method is called at the beginning of each test session.
+     * In **watch mode**, it will be invoked for every new session restart.
+     * Reporters can use this hook to reset the internal state, prepare output files,
+     * or print session headers.
+     *
+     * @param suites - A list of suite names to be executed in this session.
+     * @param runners - A list of configured runners available in this session.
+     *
+     * @since 1.0.0
+     */
+    init?(suites: Array<string>, runners: Array<RunnerInterface>): void;
+    /**
+     * Handles log messages emitted during test execution.
+     *
+     * @param log - The structured log message including level, text,
+     *              and optional metadata.
+     *
+     * @remarks
+     * This method is triggered whenever the test code calls
+     * `xJet.log()`, `xJet.error()`, or similar logging helpers.
+     * Reporters can use this hook to capture, format, and
+     * output logs to the console, files, or custom UIs.
+     *
+     * @see LogMessageInterface
+     * @since 1.0.0
+     */
+    log?(log: LogMessageInterface): void;
+    /**
+     * Signals the start of a test suite execution.
+     *
+     * @param event - The structured event containing suite metadata
+     *                such as its ID, name, and runner.
+     *
+     * @remarks
+     * Called when a suite begins running. Reporters can use this
+     * hook to display suite headers, initialize timers, or log
+     * contextual information about the suite.
+     *
+     * @see StartMessageInterface
+     * @since 1.0.0
+     */
+    suiteStart?(event: StartMessageInterface): void;
+    /**
+     * Signals the completion of a test suite execution.
+     *
+     * @param event - The structured event containing final suite
+     *                metadata such as its ID, name, duration, and
+     *                aggregated results.
+     *
+     * @remarks
+     * Called after a suite has finished running. Reporters can use
+     * this hook to display summary information, update progress,
+     * or finalize suite-level reporting.
+     *
+     * @see EndMessageInterface
+     * @since 1.0.0
+     */
+    suiteEnd?(event: EndMessageInterface): void;
+    /**
+     * Signals the start of a `describe` block execution.
+     *
+     * @param event - The structured event containing metadata
+     *                about the `describe` block, including its
+     *                ID, name, and parent context.
+     *
+     * @remarks
+     * Called when a `describe` block begins running. Reporters
+     * can use this hook to display section headers, indent logs,
+     * or prepare contextual grouping in the output.
+     *
+     * @see StartAssertionMessageInterface
+     * @since 1.0.0
+     */
+    describeStart?(event: StartAssertionMessageInterface): void;
+    /**
+     * Signals the completion of a `describe` block execution.
+     *
+     * @param event - The structured event containing metadata
+     *                about the `describe` block, including its
+     *                ID, name, duration, and results.
+     *
+     * @remarks
+     * Called after a `describe` block has finished running.
+     * Reporters can use this hook to close sections, summarize
+     * grouped tests, or adjust indentation and formatting.
+     *
+     * @see EndAssertionMessageInterface
+     * @since 1.0.0
+     */
+    describeEnd?(event: EndAssertionMessageInterface): void;
+    /**
+     * Signals the start of an individual test execution.
+     *
+     * @param event - The structured event containing metadata
+     *                about the test, including its ID, name,
+     *                and parent suite or `describe` block.
+     *
+     * @remarks
+     * Called when a test begins running. Reporters can use this
+     * hook to display test-level headers, start timers, or
+     * track progress.
+     *
+     * @see StartAssertionMessageInterface
+     * @since 1.0.0
+     */
+    testStart?(event: StartAssertionMessageInterface): void;
+    /**
+     * Signals the completion of an individual test execution.
+     *
+     * @param event - The structured event containing metadata
+     *                about the test, including its ID, name,
+     *                duration, and result status.
+     *
+     * @remarks
+     * Called after a test has finished running. Reporters can use
+     * this hook to display test results, update progress bars,
+     * or log assertion summaries.
+     *
+     * @see EndAssertionMessageInterface
+     * @since 1.0.0
+     */
+    testEnd?(event: EndAssertionMessageInterface): void;
+    /**
+     * Called when all suites have finished executing.
+     *
+     * @remarks
+     * This method is invoked at the **end of each test session**.
+     * In watch mode, it will be called after every session completes,
+     * allowing reporters to finalize logs, write summary files, or
+     * perform cleanup for that session.
+     *
+     * @since 1.0.0
+     */
+    finish?(): void;
+}
+
+/**
+ * Import will remove at compile time
+ */
+/**
+ * Represents a test runner.
+ *
+ * @property id - Unique identifier of the runner
+ * @property name - Name of the runner
+ *
+ * @since 1.0.0
+ */
+interface RunnerInterface {
+    id: string;
+    name: string;
+}
+/**
+ * Configuration settings for the test runtime environment
+ *
+ * @since 1.0.0
+ */
+interface RuntimeConfigInterface {
+    /**
+     * Whether to stop test execution after the first failure
+     *
+     * @since 1.0.0
+     */
+    bail: boolean;
+    /**
+     * List of test patterns to filter which tests are executed
+     *
+     * @since 1.0.0
+     */
+    filter: Array<string>;
+    /**
+     * Maximum time in milliseconds allowed for test execution before timeout
+     *
+     * @since 1.0.0
+     */
+    timeout: number;
+    /**
+     * Unique identifier for the test suite being executed
+     *
+     * @since 1.0.0
+     */
+    suiteId: string;
+    /**
+     * Unique identifier for the test runner instance
+     *
+     * @since 1.0.0
+     */
+    runnerId: string;
+    /**
+     * Path to the test file being executed
+     *
+     * @since 1.0.0
+     */
+    path: string;
+    /**
+     * Random test determinism
+     *
+     * @since 1.0.0
+     */
+    randomize: boolean;
+}
+/**
+ * Represents an interface for managing running test suites with promise control functions
+ *
+ * @see PromiseRejectType
+ * @see PromiseResolveType
+ *
+ * @since 1.0.0
+ */
+interface RunningSuitesInterface {
+    /**
+     * Function to reject the promise associated with the running suite
+     *
+     * @since 1.0.0
+     */
+    resolve: PromiseRejectType<void>;
+    /**
+     * Function to resolve the promise associated with the running suite
+     *
+     * @since 1.0.0
+     */
+    reject: PromiseResolveType<void>;
+}