/*
 * Pitfall Example: Premature Abstraction Leading to Complexity
 * 
 * We initially aim for maximum reusability, but without careful constraints,
 * 'any' or 'unknown' types proliferate, leading to ambiguous generic parameters.
 * This function attempts to handle various data transformation, but its type signature
 * quickly becomes unmanageable if we try to precisely define all transformations.
 */

interface DataItem {
  id: string;
  value: unknown;
}

// Initial attempt: overly broad generic, forcing us to use 'any' or 'unknown' internally
// or to cast aggressively, undermining type safety.
function processDataBad<TInput, TOutput>(data: TInput[], transformFn: (item: TInput) => TOutput): TOutput[] {
  console.log('Processing data with a potentially ambiguous generic signature...');
  // Without stricter constraints on TInput, we might struggle here.
  // e.g., if TInput is just 'unknown', we cannot access 'item.id'.
  return data.map(item => transformFn(item));
}

// Example usage: type safety is immediately lost without explicit casting or stricter types
const rawItems: DataItem[] = [
  { id: 'a', value: 10 },
  { id: 'b', value: 'hello' }
];

// This will compile, but 'item' inside the lambda is 'DataItem' due to contextual typing,
// not the 'TInput' we might expect if we want to narrow it further based on the transformFn.
const processedNumbers = processDataBad(rawItems, item => {
  if (typeof item.value === 'number') {
    return item.value * 2;
  }
  return 0; // Forced to return a default or handle 'unknown'
});
console.log(processedNumbers); // Expected: [20, 0]

/*
 * Best Practice Example: Constrain Generics Precisely
 * 
 * We activate targeted constraints to guide the type system.
 * By enforcing specific properties or structures, we maintain strong type safety
 * and improve readability, preventing 'type soup' from the outset.
 */

interface HasId {
  id: string;
}

// Improved function: Constrain TInput to 'HasId', making operations on 'id' safe.
function processDataGood<TInput extends HasId, TOutput>(data: TInput[], transformFn: (item: TInput) => TOutput): TOutput[] {
  console.log(`Processing ${data.length} items with IDs: ${data.map(i => i.id).join(', ')}`);
  return data.map(item => transformFn(item));
}

// Example usage with better type safety:
interface Product extends HasId {
  name: string;
  price: number;
}

const products: Product[] = [
  { id: 'p1', name: 'Laptop', price: 1200 },
  { id: 'p2', name: 'Mouse', price: 25 }
];

const productPrices = processDataGood(products, product => product.price * 1.05); // 5% markup
console.log(productPrices); // Expected: [1260, 26.25]

// The generic constraint now ensures 'product.price' is accessible and typed correctly.
const productNames = processDataGood(products, product => product.name.toUpperCase());
console.log(productNames); // Expected: ['LAPTOP', 'MOUSE']

/*
 * Pitfall Example: Deeply Nested & Overly Complex Conditional Types
 * 
 * We attempt to create a single, highly polymorphic type that handles too many conditions
 * and transformations, resulting in 'type soup'. This becomes extremely difficult to read,
 * debug, and extend. The 'infer' keyword, while powerful, can lead to unmanageable nesting.
 */

// Imagine an API response that can be a single item, an array of items, or an error.
// We want a generic utility type that can extract the 'data' part, if present and successful.

interface ApiResponse<TData> {
  status: 'success' | 'error';
  data?: TData;
  message?: string;
}

interface ItemA { id: string; value: number; }
interface ItemB { id: number; name: string; }

// BAD: Overly complex and nested conditional type to extract data from various API responses.
// This type tries to handle single items, arrays, and even nested structures within TData.
// We quickly lose track of what 'infer' is actually doing at each step.
type ExtractDataBad<T> = T extends ApiResponse<infer R> // Is it an API response?
  ? R extends (infer U)[] // Is the data an array?
    ? U extends { nested?: infer N } // Does the array item have a nested property?
      ? N // If so, extract the nested part
      : U // Otherwise, extract the array item
    : R extends { complexData?: infer CD } // Is it a single item with complexData?
      ? CD // If so, extract complexData
      : R // Otherwise, extract the data itself
  : T; // Not an API response, return original type (this path is often a source of confusion)

// We observe the cognitive load immediately.
type DataFromApiResponseA = ExtractDataBad<ApiResponse<ItemA>>; // Expected: ItemA
type DataFromApiResponseBArray = ExtractDataBad<ApiResponse<ItemB[]>>; // Expected: ItemB

interface ComplexApiResponse {
  status: 'success';
  data?: { complexData: { id: string; status: boolean; } };
}
type DataFromComplexResponse = ExtractDataBad<ComplexApiResponse>; // Expected: { id: string; status: boolean; }

// What if we pass something unexpected? The type system struggles to guide us.
type NonApiResponse = ExtractDataBad<number>; // Returns 'number', but was this the intention?

console.log("Complex generic types significantly increase cognitive load.");

/*
 * Best Practice Example: Decompose Complex Generics into Smaller, Readable Helper Types
 * 
 * We activate modular design for our type system, breaking down complex logic into
 * self-contained, atomic helper types. This enhances readability, debuggability,
 * and makes each part's purpose transparent.
 */

// GOOD: Decomposed and explicit helper types.

// 1. Helper to extract data from a base API response.
type ExtractApiResponseData<T> = T extends ApiResponse<infer R> ? R : never;

// 2. Helper to handle array types.
type ExtractArrayItem<T> = T extends (infer U)[] ? U : T;

// 3. Helper to handle specific nested properties.
type ExtractNestedProperty<T> = T extends { nested?: infer N } ? N : T;
type ExtractComplexProperty<T> = T extends { complexData?: infer CD } ? CD : T;

// Now, compose these smaller types to build the final logic.
type ExtractDataGood<T> = ExtractArrayItem<
  ExtractComplexProperty<
    ExtractNestedProperty<
      ExtractApiResponseData<T>
    >
  >
>;

// We immediately observe improved clarity and traceability.
type GoodDataFromApiResponseA = ExtractDataGood<ApiResponse<ItemA>>; // Expected: ItemA
type GoodDataFromApiResponseBArray = ExtractDataGood<ApiResponse<ItemB[]>>; // Expected: ItemB
type GoodDataFromComplexResponse = ExtractDataGood<ComplexApiResponse>; // Expected: { id: string; status: boolean; }

// Non-API response now correctly resolves to 'never' or original type based on design, not ambiguity.
type GoodNonApiResponse = ExtractDataGood<number>; // Expected: never (or number, depending on first helper's 'else' branch)

console.log("Decomposing Generics enhances clarity and maintainability.");

/*
 * Pitfall Example: Generic Recursion & Large Union Types Impacting Compiler Performance
 * 
 * While TypeScript generics are typically resolved at compile-time, extremely complex
 * recursive generic types or those generating massive union types can strain the compiler.
 * This can manifest as slower build times, increased IDE memory usage, and degraded IntelliSense performance.
 */

// BAD: Recursive generic type creating deep nesting or large unions
// This type might aim to deeply unwrap a structure, but if applied carelessly,
// it can cause a 'TypeScript depth limit exceeded' error or very slow compilation.

type DeeplyNestedObject = {
  a: { b: { c: { d: { e: string } } } };
  x: number;
};

// An example of a recursive type that could be problematic if not carefully managed.
// This type aims to flatten objects or access deep paths, but its recursive nature
// can lead to performance issues or depth limits for excessively deep objects.
type DeepFlatten<T> = T extends object
  ? { [K in keyof T]: DeepFlatten<T[K]> } extends infer U
    ? { [K2 in keyof U]: U[K2] } // This part can grow very large if T is complex
    : never
  : T;

// Activating this type on very deep or broad objects can cause slowdowns.
// type FlattenedDeepObject = DeepFlatten<DeeplyNestedObject>; // Might hit depth limit or slow down.

console.log("Complex generic types can impact compiler performance and developer tooling.");

/*
 * Best Practice Example: Limiting Recursive Depth & Using Concrete Types When Possible
 * 
 * We engineer solutions to mitigate performance bottlenecks by limiting recursive depth,
 * employing helper types to break down complexity, and opting for more concrete types
 * when generic flexibility isn't strictly necessary. This balances powerful abstraction
 * with compiler efficiency and developer clarity.
 */

// GOOD: Limiting recursive depth for safety and performance.

// Helper to limit the depth of recursion (e.g., up to 3 levels)
type MaxDepth<T, Depth extends number> = [
  never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16 // Max depth 16 for safety
][Depth] extends never
  ? T // Stop recursion if depth limit reached
  : T extends object
    ? { [K in keyof T]: MaxDepth<T[K], [
        never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16
      ][Depth]> } // Recurse with decremented depth
    : T;

// Define a type for a deeply nested property extraction, but with a depth limit
type SafeDeepValue<T, K extends keyof T, Depth extends number = 5> = K extends keyof T
  ? MaxDepth<T[K], Depth> // Apply MaxDepth to prevent infinite recursion or extreme depth
  : never;

interface Config {
  settings: {
    app: {
      theme: string;
      version: number;
    };
    db: {
      host: string;
      port: number;
    };
  };
  logging: {
    level: 'info' | 'debug';
  };
}

// We can safely extract values without risking a compiler depth limit.
type AppTheme = SafeDeepValue<Config['settings'], 'app'>; // This is { theme: string; version: number; }

interface TooDeep {
  a: { b: { c: { d: { e: { f: { g: string } } } } } };
}

// Applying SafeDeepValue with default depth (5) to a very deep type. The type will be resolved
// up to the specified depth, then stop, preventing compiler overload.
type LimitedDeepValue = SafeDeepValue<TooDeep, 'a'>; 
// Expected: { b: { c: { d: { e: { f: string | { g: string; } } } } } } - type 'g' might be a union if it hits the limit.

console.log("Limiting generic depth ensures compiler efficiency and predictable type resolution.");

/*
 * Pitfall Example: Unclear Constraints and Lack of Documentation
 * 
 * We often create generic utilities with implicit assumptions about type parameters,
 * leading to unexpected behavior or difficult-to-diagnose errors when consumed.
 * A lack of clear documentation exacerbates this, making the generic hard to use correctly.
 */

// BAD: Generic that isn't clear about what T is expected to be.
// What does 'T' need to provide for this function to work correctly?
// The error message for an incorrect usage might be confusing.
function mergeObjectsBad<T>(obj1: T, obj2: T): T {
  // Assumes T is an object type, but doesn't enforce it.
  // If T is 'string', this would lead to runtime error or unexpected concatenation.
  return { ...obj1, ...obj2 }; // This only works correctly if T is an object.
}

// Usage where T is inferred as a union of object types, or even a primitive.
// If T is { a: number } | { b: string }, then obj1 and obj2 must match.
// This merges two distinct object types by creating a union of their properties.
const resultBad = mergeObjectsBad({ a: 1 }, { b: 'hello' }); 
// Type of resultBad is { a: number; } & { b: string; } which is fine here.
// But what if we passed two strings? mergeObjectsBad("hello", "world") -> runtime error.

console.log("Generics without clear constraints invite misuse.");

/*
 * Best Practice Example: Explicit Constraints, JSDoc, and Unit Testing for Generics
 * 
 * We engineer resilience by activating explicit generic constraints, comprehensive JSDoc
 * documentation, and dedicated unit tests. This clarifies the contract of our generics,
 * guides their correct usage, and guarantees their behavior across various type parameters.
 */

// GOOD: Generic with explicit constraints, JSDoc, and careful implementation.

/**
 * @template T - The base type of the objects to merge. Must be an object.
 * @param {T} obj1 - The first object to merge.
 * @param {Partial<T>} obj2 - The second object, representing partial updates to T.
 * @returns {T} A new object with properties from obj1 overridden by obj2.
 * @description Merges two objects, creating a new object. It's designed for applying partial updates
 * while ensuring the resulting object conforms to the original base type T.
 */
function mergeObjectsGood<T extends object>(obj1: T, obj2: Partial<T>): T {
  // We know T is an object now, so spread syntax is safe.
  return { ...obj1, ...obj2 };
}

interface UserConfig {
  theme: 'dark' | 'light';
  fontSize: number;
  notifications: boolean;
}

const defaultConfig: UserConfig = {
  theme: 'dark',
  fontSize: 14,
  notifications: true,
};

const userPreference: Partial<UserConfig> = {
  fontSize: 16,
  notifications: false,
};

const mergedConfig = mergeObjectsGood(defaultConfig, userPreference);
console.log(mergedConfig); 
// Expected: { theme: 'dark', fontSize: 16, notifications: false }

// Type of mergedConfig is UserConfig, guaranteed by the generic signature.
// Attempting to pass a non-object type now results in a clear compile-time error.
// mergeObjectsGood("string1", "string2"); // TS Error: Argument of type 'string' is not assignable to parameter of type 'object'.


// We also engineer unit tests to validate generic behavior across various type parameters.
// Example (conceptual, using a test framework like Jest):
/*
describe('mergeObjectsGood', () => {
  it('should merge properties correctly for simple objects', () => {
    const objA = { a: 1, b: 'hello' };
    const objB = { b: 'world', c: true };
    const result = mergeObjectsGood(objA, objB);
    expect(result).toEqual({ a: 1, b: 'world', c: true }); // Type should be { a: number; b: string; c: boolean; }
  });

  it('should maintain original type for partial updates', () => {
    interface WidgetConfig { id: string; active: boolean; data: string[]; }
    const initial: WidgetConfig = { id: 'w1', active: true, data: ['a', 'b'] };
    const update: Partial<WidgetConfig> = { active: false, data: ['c'] };
    const result = mergeObjectsGood(initial, update);
    expect(result).toEqual({ id: 'w1', active: false, data: ['c'] });
    // Ensure type of 'result' is WidgetConfig
    const _checkType: WidgetConfig = result; // Compile-time check
  });

  it('should throw compile-time error for non-object types', () => {
    // This test is conceptual; it asserts that the following line FAILS to compile.
    // @ts-expect-error - Expects a type error here
    // mergeObjectsGood('str1', 'str2'); 
  });
});
*/
console.log("Robust generics require explicit contracts, documentation, and thorough validation.");