// SPDX-FileCopyrightText: © 2024 LEDGER SAS
// SPDX-License-Identifier: Apache-2.0

/**
 * Recursively makes all properties optional.
 * Arrays keep their element type (but each element is deeply partial).
 * Primitives and built-in value types (Date, RegExp) are preserved as-is.
 */
export type DeepPartial<T> = T extends (infer U)[]
  ? DeepPartial<U>[]
  : T extends Date | RegExp
    ? T
    : T extends object
      ? { [K in keyof T]?: DeepPartial<T[K]> }
      : T

/**
 * Re-types a function so its return value is `DeepPartial<ReturnType<F>>` (sync)
 * or `Promise<DeepPartial<Awaited<ReturnType<F>>>>` (async), while keeping the
 * original parameter types intact.
 *
 * Use with `jest.mocked<DeepPartialReturn<F>>(spy)` to let `mockReturnValue` /
 * `mockResolvedValue` accept partial stubs - no cast, no `any` at call sites.
 *
 * Works for both synchronous and asynchronous functions.
 *
 * @example
 * // Async: network module function mocked via jest.mock
 * import { broadcastTransaction } from './network'
 * jest.mock('./network', () => ({ broadcastTransaction: jest.fn() }))
 *
 * jest
 *   .mocked<DeepPartialReturn<typeof broadcastTransaction>>(broadcastTransaction)
 *   .mockResolvedValue({ hash: 'abc123' }) // ✓ partial BroadcastResult accepted
 *
 * @example
 * // Sync: SDK client prototype method returning a fluent builder
 * // spyOn installs the spy; mocked re-types it - they cannot be combined
 * import { SdkClient } from './sdk'
 *
 * jest.spyOn(SdkClient.prototype, 'transactions')
 * const spy = jest.mocked<DeepPartialReturn<typeof SdkClient.prototype.transactions>>(
 *   SdkClient.prototype.transactions
 * )
 * spy.mockReturnValue({ forAccount: jest.fn().mockReturnThis(), call: jest.fn() }) // ✓
 */
export type DeepPartialReturn<F extends (...args: never[]) => unknown> =
  ReturnType<F> extends Promise<infer R>
    ? (...args: Parameters<F>) => Promise<DeepPartial<R>>
    : (...args: Parameters<F>) => DeepPartial<ReturnType<F>>

/**
 * Re-types a class constructor so that `mockImplementation` accepts a factory
 * returning a partial instance - `DeepPartial<InstanceType<C>>` instead of the
 * full class - while keeping the original constructor parameter types.
 *
 * Use with `jest.mocked<DeepPartialCtor<typeof MyClass>>(MyClass)` after
 * `jest.mock('./sdk')`.
 *
 * @example
 * import { SdkClient } from './sdk'
 * jest.mock('./sdk')
 *
 * jest.mocked<DeepPartialCtor<typeof SdkClient>>(SdkClient)
 *   .mockImplementation(() => ({
 *     getBalance: jest.fn(),
 *     getTransactions: jest.fn(),
 *   })) // ✓ partial SdkClient instance accepted
 */
export type DeepPartialCtor<C extends new (...args: never[]) => unknown> = new (
  ...args: ConstructorParameters<C>
) => DeepPartial<InstanceType<C>>