Type Checking & Validation

/**
 * Type guard to check if value is Promise-like
 * @param candidate - Value to test for Promise-like behavior
 * @returns Type predicate indicating if value has .then() method
 */
function isPromise<T = unknown>(candidate: unknown): candidate is PromiseLike<T>;

import { isPromise } from "jest-util";

// Type-safe Promise detection
async function handlePotentialPromise(value: unknown) {
  if (isPromise(value)) {
    // TypeScript knows 'value' is PromiseLike<unknown> here
    const result = await value;
    return result;
  } else {
    // TypeScript knows 'value' is not a Promise here
    return value;
  }
}

// Jest test helper usage
function processTestResult(result: any) {
  if (isPromise(result)) {
    return result.then(processTestResult);
  }
  
  // Handle synchronous result
  return validateResult(result);
}

// Generic type parameter usage
interface TestData {
  id: number;
  name: string;
}

function processTestData(data: unknown): Promise<TestData> | TestData {
  if (isPromise<TestData>(data)) {
    // TypeScript knows data is PromiseLike<TestData>
    return data.then(validateTestData);
  }
  
  // TypeScript knows data is not a Promise
  return validateTestData(data as TestData);
}

/**
 * Type guard to check if value is not null or undefined
 * @param value - Value to test
 * @returns Type predicate indicating if value is non-nullable
 */
function isNonNullable<T>(value: T): value is NonNullable<T>;

import { isNonNullable } from "jest-util";

// Filter out null/undefined values with type safety
const testCases: Array<string | null | undefined> = [
  "test1", 
  null, 
  "test2", 
  undefined, 
  "test3"
];

const validTestCases: string[] = testCases.filter(isNonNullable);
// TypeScript knows validTestCases is string[], not (string | null | undefined)[]

// Safe property access
function processTestConfig(config: { name?: string; timeout?: number }) {
  if (isNonNullable(config.name)) {
    // TypeScript knows config.name is string, not string | undefined
    console.log(`Running test: ${config.name.toUpperCase()}`);
  }
  
  if (isNonNullable(config.timeout)) {
    // TypeScript knows config.timeout is number, not number | undefined
    setTimeout(() => {}, config.timeout);
  }
}

// Array processing with type narrowing
function collectValidItems<T>(items: Array<T | null | undefined>): T[] {
  return items.filter(isNonNullable);
  // Return type is automatically inferred as T[]
}

/**
 * Assertion function that throws if condition is falsy
 * @param condition - Condition to assert
 * @param message - Optional error message (default: empty string)
 * @throws Error if condition is falsy
 */
function invariant(condition: unknown, message = ''): asserts condition;

import { invariant } from "jest-util";

// Basic assertions
function processTestSuite(suite: any) {
  invariant(suite, "Test suite is required");
  invariant(suite.name, "Test suite must have a name");
  
  // TypeScript knows suite and suite.name are truthy here
  console.log(`Running suite: ${suite.name}`);
}

// Type narrowing with custom messages
function validateTestConfig(config: unknown): asserts config is TestConfig {
  invariant(config, "Configuration is required");
  invariant(typeof config === "object", "Configuration must be an object");
  invariant("testPattern" in config, "Configuration must include testPattern");
  
  // TypeScript knows config has the required properties after these assertions
}

// Runtime type validation
interface User {
  id: number;
  name: string;
  email: string;
}

function processUser(data: any): User {
  invariant(data, "User data is required");
  invariant(typeof data.id === "number", "User ID must be a number");
  invariant(typeof data.name === "string", "User name must be a string");
  invariant(typeof data.email === "string", "User email must be a string");
  
  // TypeScript understands that data conforms to User interface
  return data as User;
}

// Test helper usage
function expectNotNull<T>(value: T | null | undefined, message?: string): T {
  invariant(value != null, message || "Expected non-null value");
  return value; // TypeScript knows this is T, not T | null | undefined
}

// invariant throws Error with provided message
try {
  invariant(false, "This will always fail");
} catch (error) {
  console.log(error.message); // "This will always fail"
}

// Default message is empty string
try {
  invariant(false);
} catch (error) {
  console.log(error.message); // ""
}

// PromiseLike interface (built-in TypeScript)
interface PromiseLike<T> {
  then<TResult1 = T, TResult2 = never>(
    onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null,
    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null
  ): PromiseLike<TResult1 | TResult2>;
}

// NonNullable utility type (built-in TypeScript)
type NonNullable<T> = T extends null | undefined ? never : T;