TypeScript Generics Deep Dive — Constraints, Inference, and Real-World Patterns

// TypeScript infers T from the argument — no explicit <string> needed
function wrapInArray<T>(value: T): T[] {
  return [value]; // T is locked in as soon as we call the function
}

const stringArray = wrapInArray('hello');     // inferred: string[]
const numberArray = wrapInArray(42);           // inferred: number[]
const dateArray   = wrapInArray(new Date());   // inferred: Date[]

// Inference FAILS when it's ambiguous — TypeScript widens to a union
function pickFirst<T>(a: T, b: T): T {
  return a;
}

// Both args must agree on T — TypeScript picks the wider type
const result = pickFirst('hello', 42);
//    ^ Error: Argument of type 'number' is not assignable to parameter of type 'string'
// Fix: be explicit when you WANT a union
function pickFirstUnion<T, U>(a: T, b: U): T | U {
  return a;
}
const safeResult = pickFirstUnion('hello', 42); // inferred: string | number ✓

// Contextual typing: inference works inline but NOT after assignment
const numbers = [1, 2, 3];

// ✓ TypeScript infers T = number from the array's element type
const doubled = numbers.map(n => n * 2);

// ✗ Context is lost — TypeScript can't infer T from a pre-assigned callback
const triple = (n: number) => n * 3;           // still fine because we typed it
const tripled = numbers.map(triple);            // works, but only because we annotated

// The tricky case: a generic callback loses inference when pre-assigned
function transform<T>(items: T[], fn: (item: T) => T): T[] {
  return items.map(fn);
}

// ✓ Inline: TypeScript infers T = number
const r1 = transform([1, 2, 3], n => n * 2);

// ✓ Pre-assigned BUT explicitly typed: still works
const double = (n: number): number => n * 2;
const r2 = transform([1, 2, 3], double);        // T = number, inferred from array

// ✗ Generic pre-assigned callback: inference breaks — T stays unresolved
// const genericDouble = <T>(n: T) => n;        // T can't be inferred from call site
// const r3 = transform([1,2,3], genericDouble); // Error: T is not assignable to T

console.log(stringArray);  // [ 'hello' ]
console.log(numberArray);  // [ 42 ]
console.log(doubled);      // [ 2, 4, 6 ]
console.log(r1);           // [ 2, 4, 6 ]

// ─────────────────────────────────────────────
// 1. Basic constraint: T must have a .length property
// ─────────────────────────────────────────────
interface HasLength {
  length: number;
}

function logLengthAndReturn<T extends HasLength>(item: T): T {
  console.log(`Length: ${item.length}`);
  return item; // we return T, not HasLength — the specific type is preserved
}

const sentence = logLengthAndReturn('TypeScript generics'); // T = string
const integers = logLengthAndReturn([1, 2, 3, 4, 5]);       // T = number[]
// sentence is still typed as string, not HasLength — T flows through intact

// ─────────────────────────────────────────────
// 2. keyof constraint: type-safe dynamic property access
// ─────────────────────────────────────────────
function getProperty<TObject, TKey extends keyof TObject>(
  obj: TObject,
  key: TKey
): TObject[TKey] {                      // return type is the EXACT type of that property
  return obj[key];
}

const userProfile = {
  id: 101,
  username: 'alice_dev',
  joinedAt: new Date('2021-03-15'),
  isVerified: true,
};

const userId       = getProperty(userProfile, 'id');         // type: number
const username     = getProperty(userProfile, 'username');   // type: string
const joinDate     = getProperty(userProfile, 'joinedAt');   // type: Date
// getProperty(userProfile, 'email');  // ✗ Error: 'email' is not a key of userProfile

// ─────────────────────────────────────────────
// 3. infer: extracting type components at compile time
// ─────────────────────────────────────────────

// Extract the resolved type from a Promise
type Awaited2<T> = T extends Promise<infer Resolved> ? Resolved : T;

type StringResult  = Awaited2<Promise<string>>;  // string
type NumberResult  = Awaited2<Promise<number>>;  // number
type AlreadyPlain  = Awaited2<boolean>;          // boolean (not a Promise, returns T)

// Extract parameter types from a function signature
type FirstParam<TFn extends (...args: any[]) => any> =
  TFn extends (first: infer P, ...rest: any[]) => any ? P : never;

type FetchFn       = (url: string, retries: number) => Promise<Response>;
type FetchFirstArg = FirstParam<FetchFn>;        // string ✓

// Extract element type from an array
type ArrayElement<TArr extends readonly unknown[]> =
  TArr extends readonly (infer Element)[] ? Element : never;

const statusCodes = [200, 201, 400, 404, 500] as const;
type StatusCode = ArrayElement<typeof statusCodes>; // 200 | 201 | 400 | 404 | 500

// ─────────────────────────────────────────────
// 4. Constraint preservation: T stays specific, not widened
// ─────────────────────────────────────────────
function mergeWithDefaults<T extends Record<string, unknown>>(
  defaults: T,
  overrides: Partial<T>   // Partial works because T is already constrained
): T {
  return { ...defaults, ...overrides };
}

const defaultConfig = { timeout: 3000, retries: 3, verbose: false };
const userConfig    = mergeWithDefaults(defaultConfig, { timeout: 5000 });
// userConfig is typed as { timeout: number; retries: number; verbose: boolean }
// — NOT as Record<string, unknown>. The specific shape is preserved.

console.log(userId);      // 101
console.log(username);    // alice_dev
console.log(userConfig);  // { timeout: 5000, retries: 3, verbose: false }

// ─────────────────────────────────────────────
// 1. Rebuilding Partial and Required from scratch
// ─────────────────────────────────────────────

// -? removes the optional modifier; +? adds it; ? is shorthand for +?
type DeepPartial<T> = {
  [K in keyof T]+?: T[K] extends object ? DeepPartial<T[K]> : T[K];
  //          ^^^ +? makes every key optional, recursing into nested objects
};

type StrictRequired<T> = {
  [K in keyof T]-?: T[K];  // -? strips the optional modifier from every key
};

interface AppConfig {
  server: {
    host: string;
    port: number;
    ssl: boolean;
  };
  database: {
    url: string;
    poolSize?: number;
  };
  featureFlags?: {
    darkMode: boolean;
    betaAccess: boolean;
  };
}

// Deep partial: every nested field is optional — useful for config patches
const configPatch: DeepPartial<AppConfig> = {
  server: { port: 8080 }  // host and ssl are now optional — valid ✓
};

// ─────────────────────────────────────────────
// 2. Distributive conditional types — and how to turn them off
// ─────────────────────────────────────────────

// Distributive: T is a naked type parameter, so this distributes over unions
type IsString<T> = T extends string ? true : false;

type TestA = IsString<string>;          // true
type TestB = IsString<number>;          // false
type TestC = IsString<string | number>; // true | false — distributes! ✓ (usually what you want)

// Non-distributive: wrapping in a tuple prevents distribution
type IsExactlyString<T> = [T] extends [string] ? true : false;

type TestD = IsExactlyString<string | number>; // false — the whole union is checked, not each member

// ─────────────────────────────────────────────
// 3. Filtering keys by value type — a practical mapped + conditional combo
// ─────────────────────────────────────────────

// Extract only the keys of T whose values are assignable to ValueType
type KeysOfType<T, ValueType> = {
  [K in keyof T]: T[K] extends ValueType ? K : never;
  //                                            ^^^^^ never keys are pruned
}[keyof T];  // index into the mapped type to get the union of non-never keys

interface UserRecord {
  id: number;
  name: string;
  email: string;
  age: number;
  isAdmin: boolean;
  createdAt: Date;
}

type StringKeys  = KeysOfType<UserRecord, string>;   // 'name' | 'email'
type NumberKeys  = KeysOfType<UserRecord, number>;   // 'id' | 'age'
type BooleanKeys = KeysOfType<UserRecord, boolean>;  // 'isAdmin'

// ─────────────────────────────────────────────
// 4. Key remapping with 'as' (TS 4.1+) — build a setter API from a type
// ─────────────────────────────────────────────

type Setters<T> = {
  [K in keyof T as `set${Capitalize<string & K>}`]: (value: T[K]) => void;
  // 'as' clause: remaps each key K to 'set' + capitalised key name
  // string & K: needed because K might not be a string (could be symbol)
};

type UserSetters = Setters<Pick<UserRecord, 'name' | 'email' | 'age'>>;
// Produces:
// {
//   setName:  (value: string) => void;
//   setEmail: (value: string) => void;
//   setAge:   (value: number) => void;
// }

// Verify it works with a real implementation
function createUserStore(initial: Pick<UserRecord, 'name' | 'email' | 'age'>) {
  const state = { ...initial };

  const setters: UserSetters = {
    setName:  (value) => { state.name  = value; },
    setEmail: (value) => { state.email = value; },
    setAge:   (value) => { state.age   = value; },
  };

  return { getState: () => ({ ...state }), ...setters };
}

const userStore = createUserStore({ name: 'alice', email: 'alice@dev.io', age: 28 });
userStore.setName('Alice Johnson');
userStore.setAge(29);
console.log(userStore.getState());
// { name: 'Alice Johnson', email: 'alice@dev.io', age: 29 }

// ─────────────────────────────────────────────
// 1. Generic Repository class — variance done right
// ─────────────────────────────────────────────

interface Entity {
  id: number;
}

interface ReadRepository<T extends Entity> {
  findById(id: number): Promise<T | null>;
  findAll(): Promise<T[]>;
}

interface WriteRepository<T extends Entity> {
  save(entity: T): Promise<T>;
  delete(id: number): Promise<void>;
}

// Splitting read/write enables covariant usage:
// ReadRepository<Dog> IS assignable to ReadRepository<Entity> safely
class InMemoryRepository<T extends Entity>
  implements ReadRepository<T>, WriteRepository<T>
{
  private store = new Map<number, T>();

  async findById(id: number): Promise<T | null> {
    return this.store.get(id) ?? null;
  }

  async findAll(): Promise<T[]> {
    return Array.from(this.store.values());
  }

  async save(entity: T): Promise<T> {
    this.store.set(entity.id, entity);
    return entity;
  }

  async delete(id: number): Promise<void> {
    this.store.delete(id);
  }
}

interface Product extends Entity {
  name: string;
  priceInCents: number;
  inStock: boolean;
}

const productRepo = new InMemoryRepository<Product>();

// ─────────────────────────────────────────────
// 2. Depth-limited recursive generic (avoids 'excessively deep' error)
// ─────────────────────────────────────────────

// Without depth limit this would crash tsc on deeply nested objects
type Depth = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ...0[]];
//            ^ The tuple index acts as a counter — Depth[5] = 4, Depth[1] = 0

type DeepReadonly<T, D extends number = 10> =
  [D] extends [0]
    ? T                                           // depth limit hit — stop recursing
    : T extends (infer U)[]
    ? ReadonlyArray<DeepReadonly<U, Depth[D]>>     // handle arrays
    : T extends object
    ? { readonly [K in keyof T]: DeepReadonly<T[K], Depth[D]> }  // handle objects
    : T;                                          // primitive — return as-is

type ImmutableConfig = DeepReadonly<AppConfig>;
// Every nested property is now readonly, recursively, up to 10 levels deep

// ─────────────────────────────────────────────
// 3. Builder pattern with generics — accumulate type state
// ─────────────────────────────────────────────

// The builder tracks which fields have been set at the TYPE level
// Only builds when all required fields are present
class QueryBuilder<T extends Record<string, unknown>, TSelected extends keyof T = never> {
  private filters: Partial<T> = {};
  private selectedKeys: TSelected[] = [];

  where<K extends keyof T>(key: K, value: T[K]): QueryBuilder<T, TSelected> {
    this.filters[key] = value;
    return this;
  }

  select<K extends keyof T>(
    ...keys: K[]
  ): QueryBuilder<T, TSelected | K> {    // TSelected grows with each call
    this.selectedKeys = [...this.selectedKeys, ...keys] as (TSelected | K)[];
    return this as unknown as QueryBuilder<T, TSelected | K>;
  }

  // build() returns only the selected fields — typed precisely
  build(): Pick<T, TSelected> {
    const result = {} as Pick<T, TSelected>;
    for (const key of this.selectedKeys) {
      if (key in this.filters) {
        (result as Record<string, unknown>)[key as string] = this.filters[key];
      }
    }
    return result;
  }
}

interface OrderRecord extends Entity {
  customerId: number;
  totalCents: number;
  status: 'pending' | 'shipped' | 'delivered';
  createdAt: Date;
}

const query = new QueryBuilder<OrderRecord>()
  .where('status', 'shipped')
  .select('id', 'customerId', 'totalCents')
  .build();
// query is typed as: Pick<OrderRecord, 'id' | 'customerId' | 'totalCents'>
// — accessing query.status would be a compile error ✓

async function runDemo() {
  await productRepo.save({ id: 1, name: 'TypeScript Handbook', priceInCents: 2999, inStock: true });
  await productRepo.save({ id: 2, name: 'Clean Code', priceInCents: 3499, inStock: false });

  const allProducts = await productRepo.findAll();
  console.log('All products:', allProducts.map(p => p.name));

  const found = await productRepo.findById(1);
  console.log('Found:', found?.name, '— Price:', found?.priceInCents);

  await productRepo.delete(2);
  const remaining = await productRepo.findAll();
  console.log('After delete:', remaining.map(p => p.name));
}

runDemo();

// TypeScript interface AppConfig (referenced in DeepReadonly example)
interface AppConfig {
  server: { host: string; port: number; ssl: boolean; };
  database: { url: string; poolSize?: number; };
  featureFlags?: { darkMode: boolean; betaAccess: boolean; };
}