Async Support

/**
 * Installs async/await and Promise support for Jasmine functions
 * Enhances test functions, lifecycle hooks, and adds concurrent testing support
 * @param globalConfig - Jest global configuration
 * @param global - Global object to install async support into
 */
function jasmineAsyncInstall(
  globalConfig: Config.GlobalConfig,
  global: Global.Global,
): void;

/**
 * Test function types supporting async patterns
 */
type TestFn = 
  | ((done: DoneFn) => void)           // Callback-based
  | (() => Promise<void>)              // Promise-based  
  | (() => void)                       // Synchronous
  | GeneratorFunction;                 // Generator function

/**
 * Done callback for callback-based tests
 */
interface DoneFn {
  (): void;
  fail(error?: any): void;
}

/**
 * Concurrent test function interface
 * Tests marked as concurrent run in parallel up to maxConcurrency limit
 */
interface ItConcurrentBase {
  /** Define a concurrent test */
  (testName: Global.TestNameLike, fn: Global.ConcurrentTestFn, timeout?: number): Spec;
  
  /** Focused concurrent test (jest-circus only feature, throws in jasmine2) */
  failing: FailingFn;
  
  /** Parameterized concurrent tests (installed by jest-each) */
  each: () => () => void;
}

interface ItConcurrentExtended extends ItConcurrentBase {
  /** Only run this concurrent test */
  only: ItConcurrentBase;
  
  /** Skip this concurrent test */
  skip: ItConcurrentBase;
}

/**
 * Concurrent test function that must return a Promise
 */
type ConcurrentTestFn = () => Promise<unknown>;

/**
 * Lifecycle hook function types with async support
 */
type LifecycleHookFn =
  | ((done: DoneFn) => void)           // Callback-based
  | (() => Promise<void>)              // Promise-based
  | (() => void)                       // Synchronous  
  | GeneratorFunction;                 // Generator function

/**
 * Enhanced lifecycle hooks with async support
 */
interface AsyncLifecycleHooks {
  beforeEach(fn?: LifecycleHookFn, timeout?: number): void;
  afterEach(fn?: LifecycleHookFn, timeout?: number): void;
  beforeAll(fn?: LifecycleHookFn, timeout?: number): void;
  afterAll(fn?: LifecycleHookFn, timeout?: number): void;
}

/**
 * Generator function support via co library
 * Automatically wraps generator functions for async execution
 */
type GeneratorFunction = () => Generator<any, any, any>;

// Async/await test
it("should handle async operations", async () => {
  const result = await fetchData();
  expect(result).toBeDefined();
});

// Promise-based test
it("should handle promises", () => {
  return fetchData().then(result => {
    expect(result).toBeDefined();
  });
});

// Generator function test (with co)
it("should handle generators", function* () {
  const result = yield fetchData();
  expect(result).toBeDefined();
});

// Async beforeEach
beforeEach(async () => {
  await setupDatabase();
});

// Promise-based afterEach
afterEach(() => {
  return cleanupResources();
});

// Generator beforeAll
beforeAll(function* () {
  yield initializeApp();
});

// Concurrent test
it.concurrent("should run in parallel", async () => {
  const result = await expensiveOperation();
  expect(result).toBeDefined();
});

// Concurrent test with timeout
it.concurrent("should timeout appropriately", async () => {
  await longRunningOperation();
}, 10000);

// Concurrent test variations
it.concurrent.only("only this concurrent test", async () => {
  // Only this test runs
});

it.concurrent.skip("skip this concurrent test", async () => {
  // This test is skipped
});

/**
 * Error handling for async operations
 * Preserves stack traces and provides meaningful error messages
 */
interface AsyncErrorHandling {
  /** Handles Promise rejections with enhanced stack traces */
  handlePromiseRejection(error: Error, extraError: Error): void;
  
  /** Processes generator function errors */
  handleGeneratorError(error: Error): void;
  
  /** Validates return values from test functions */
  validateReturnValue(returnValue: any): void;
}

/**
 * Concurrency control configuration
 */
interface ConcurrencyControl {
  /** Maximum number of concurrent tests (from globalConfig.maxConcurrency) */
  maxConcurrency: number;
  
  /** Promise queue limiter for concurrent execution */
  mutex: ReturnType<typeof pLimit>;
}

// Configure concurrency in Jest config
module.exports = {
  maxConcurrency: 4, // Run up to 4 tests concurrently
  testRunner: "jest-jasmine2"
};

// Tests automatically respect concurrency limits
describe("Concurrent suite", () => {
  // These will run up to 4 at a time
  it.concurrent("test 1", async () => { /* ... */ });
  it.concurrent("test 2", async () => { /* ... */ });
  it.concurrent("test 3", async () => { /* ... */ });
  it.concurrent("test 4", async () => { /* ... */ });
  it.concurrent("test 5", async () => { /* ... */ }); // Waits for slot
});

// Traditional done callback
it("should work with done callback", (done) => {
  setTimeout(() => {
    expect(true).toBe(true);
    done();
  }, 100);
});

// Done callback with failure
it("should handle done.fail", (done) => {
  setTimeout(() => {
    try {
      expect(false).toBe(true);
      done();
    } catch (error) {
      done.fail(error);
    }
  }, 100);
});

/**
 * Failing test markers (jest-circus only)
 * These throw errors in jest-jasmine2
 */
interface FailingFn {
  (): never; // Always throws
  each(): never; // Always throws
}

// These will throw errors in jest-jasmine2
it.failing("this throws an error", () => {
  // Error: Jest: `failing` tests are only supported in `jest-circus`.
});

it.failing.each([1, 2, 3])("this also throws", (value) => {
  // Error: Jest: `failing` tests are only supported in `jest-circus`.
});