/*
 * TypeScript's native 'Readonly' utility is a powerful first step
 * towards immutability, but it operates only at the top level of an object.
 * This example demonstrates its limitation when dealing with nested properties.
 */

type UserProfile = {
  id: string;
  name: string;
  settings: {
    theme: string;
    notifications: boolean;
  };
  tags: string[];
};

// Apply the standard Readonly utility type
type ReadonlyUserProfile = Readonly<UserProfile>;

// We can't reassign top-level properties:
const user: ReadonlyUserProfile = {
  id: "usr-123",
  name: "Alice",
  settings: { theme: "dark", notifications: true },
  tags: ["developer", "typescript"]
};

// user.id = "new-id"; // Error: Cannot assign to 'id' because it is a read-only property.

// However, nested properties remain mutable:
user.settings.theme = "light"; // This is allowed and modifies the original object!
user.tags.push("frontend"); // This is also allowed and modifies the original array!

console.log(user.settings.theme); // Outputs: light
console.log(user.tags);          // Outputs: [ 'developer', 'typescript', 'frontend' ]

// This demonstrates the crucial gap: 'Readonly' is shallow. For deep protection,
// we require a more sophisticated, recursive approach.

/*
 * We engineer the DeepReadonly type using a recursive mapped type.
 * This involves iterating over an object's properties and conditionally
 * applying 'Readonly' at each level, recursing for object-like properties.
 */

// Step 1: Define the core recursive DeepReadonly type.
// It iterates over keys of T, making each property readonly.
// If a property is an object (excluding functions, which are often meant to be callable),
// it applies DeepReadonly recursively.

type DeepReadonly<T> = T extends Function // Base case: Functions are not deeply readonly in terms of their callable nature.
  ? T
  : T extends (infer R)[] // Handle arrays: make elements DeepReadonly and the array itself readonly.
    ? ReadonlyArray<DeepReadonly<R>>
    : T extends object // If it's an object (excluding functions and arrays, which are handled above)
      ? {
          readonly [P in keyof T]: DeepReadonly<T[P]>; // Recursively apply DeepReadonly to each property
        }
      : T; // Base case: primitive types (string, number, boolean, null, undefined) are already immutable.

// Step 2: Apply DeepReadonly to our UserProfile type.

type DeepReadonlyUserProfile = DeepReadonly<UserProfile>;

const deepUser: DeepReadonlyUserProfile = {
  id: "usr-123",
  name: "Alice",
  settings: { theme: "dark", notifications: true },
  tags: ["developer", "typescript"]
};

// Attempt to modify top-level properties - still an error (as with Readonly):
// deepUser.id = "new-id"; // Error: Cannot assign to 'id' because it is a read-only property.

// CRITICAL: Attempt to modify nested properties - now an error!
// deepUser.settings.theme = "light"; // Error: Cannot assign to 'theme' because it is a read-only property.
// deepUser.tags.push("frontend");    // Error: Property 'push' does not exist on type 'readonly string[]'.

// This confirms the DeepReadonly type successfully enforces immutability
// throughout the entire object structure, including nested objects and arrays.

// Example with a more complex nested structure:
type CompanyConfig = {
  name: string;
  departments: {
    [key: string]: {
      budget: number;
      employees: { name: string; age: number }[];
    };
  };
  contact: {
    email: string;
    phone?: string;
  };
};

type DeepReadonlyCompanyConfig = DeepReadonly<CompanyConfig>;

const config: DeepReadonlyCompanyConfig = {
  name: "TechCorp",
  departments: {
    engineering: { budget: 1000000, employees: [{ name: "Bob", age: 30 }] },
    marketing: { budget: 500000, employees: [{ name: "Carol", age: 25 }] }
  },
  contact: { email: "info@techcorp.com" }
};

// config.departments.engineering.budget = 1200000; // Error
// config.departments.engineering.employees.push({ name: "Dave", age: 35 }); // Error

console.log("DeepReadonly type successfully applied.");

/*
 * DeepReadonly must gracefully handle various data structures beyond simple objects,
 * including unions, optional properties, and even potentially circular references.
 * This section refines the type to ensure comprehensive coverage and explores its behavior.
 */

// Recall our DeepReadonly definition:
// We'll add an explicit check for `any` and `unknown` to ensure type safety,
// although TypeScript's default behavior often handles these reasonably.

type DeepReadonly<T> = T extends Function
  ? T
  : T extends (infer R)[]
    ? ReadonlyArray<DeepReadonly<R>>
    : T extends object
      ? { readonly [P in keyof T]: DeepReadonly<T[P]> }
      : T;

// Example 1: Handling Union Types with DeepReadonly

type StatusInfo = {
  message: string;
  code: number;
} | {
  error: string;
  details: string;
};

type DeepReadonlyStatusInfo = DeepReadonly<StatusInfo>;

const successStatus: DeepReadonlyStatusInfo = { message: "Operation successful", code: 200 };
const errorStatus: DeepReadonlyStatusInfo = { error: "Failed", details: "Network issue" };

// successStatus.message = "Updated"; // Error
// errorStatus.details = "Timeout";   // Error

console.log("Union types handled.");

// Example 2: Handling Optional Properties

type ConfigWithOptional = {
  logLevel: 'debug' | 'info' | 'error';
  settings?: {
    retryCount?: number;
    timeout: number;
  };
};

type DeepReadonlyConfig = DeepReadonly<ConfigWithOptional>;

const myConfig: DeepReadonlyConfig = {
  logLevel: 'info',
  settings: {
    timeout: 5000
  }
};

// myConfig.logLevel = 'error'; // Error
// if (myConfig.settings) {
//   myConfig.settings.timeout = 10000; // Error
//   myConfig.settings.retryCount = 3;  // Error, even for optional sub-property
// }

console.log("Optional properties handled.");

// Example 3: Considerations for Circular References (TypeScript's default behavior)
// TypeScript's type inference for recursive types handles circularity by deferring
// evaluation. For runtime circular objects, DeepReadonly will recursively apply
// immutability up to TypeScript's recursion depth limit (typically around 50 levels).
// Beyond that, it might default to 'any' or the base type.

interface Node {
  id: string;
  parent?: Node;
  children: Node[];
}

type DeepReadonlyNode = DeepReadonly<Node>;

const childNode: DeepReadonlyNode = { id: "child", children: [] };
const parentNode: DeepReadonlyNode = { id: "parent", children: [childNode] };
// childNode.parent = parentNode; // If you create a runtime circular reference, the *type* allows it,
                              // but DeepReadonly ensures its properties remain readonly.
                              // The type definition itself will resolve fine in TS.

// parentNode.children.push({ id: "grandchild", children: [] }); // Error
// parentNode.parent = { id: "grandparent", children: [] };     // Error

console.log("Circular references are type-checked within TS limits.");

// Example 4: DeepReadonly with Tuples

type Coordinate = [number, number, number];

type DeepReadonlyCoordinate = DeepReadonly<Coordinate>;

const coords: DeepReadonlyCoordinate = [10, 20, 30];

// coords[0] = 5; // Error: Index signature in type 'ReadonlyArray<number>' only permits reading.
// coords.push(40); // Error: Property 'push' does not exist on type 'readonly number[]'.

console.log("Tuples are treated as ReadonlyArrays.");

/*
 * Integrating DeepReadonly transforms development workflows by enforcing immutability
 * at compile-time, leading to more predictable and maintainable codebases.
 * This example demonstrates its practical application in API responses or state management.
 */

// Re-use our DeepReadonly type for demonstration

type DeepReadonly<T> = T extends Function
  ? T
  : T extends (infer R)[]
    ? ReadonlyArray<DeepReadonly<R>>
    : T extends object
      ? { readonly [P in keyof T]: DeepReadonly<T[P]> }
      : T;

// Define a typical data structure for an API response or application state
interface Product {
  id: string;
  name: string;
  price: number;
  details: {
    description: string;
    features: string[];
    dimensions?: { width: number; height: number };
  };
  reviews: {
    userId: string;
    rating: number;
    comment: string;
  }[];
}

// --- Scenario 1: Ensuring Immutability for API Responses ---
// When an API returns data, we want to ensure it's not accidentally modified downstream.

function fetchProductDetails(productId: string): DeepReadonly<Product> {
  // Simulate fetching data (e.g., from a database or external API)
  const rawProduct: Product = {
    id: productId,
    name: "SuperWidget",
    price: 99.99,
    details: {
      description: "A truly amazing product.",
      features: ["durable", "lightweight"],
      dimensions: { width: 10, height: 20 }
    },
    reviews: [
      { userId: "u1", rating: 5, comment: "Great!" },
      { userId: "u2", rating: 4, comment: "Good value." }
    ]
  };
  // We cast to DeepReadonly to enforce immutability on the returned object.
  // This tells TypeScript that this object, once returned, should not be modified.
  return rawProduct as DeepReadonly<Product>;
}

const productData = fetchProductDetails("prod-abc");

// Attempt to modify the returned data - Compilation Errors are our guardians!
// productData.price = 109.99; // Error: Cannot assign to 'price' because it is a read-only property.
// productData.details.features.push("waterproof"); // Error: Property 'push' does not exist on type 'readonly string[]'.
// if (productData.details.dimensions) {
//   productData.details.dimensions.width = 15; // Error: Cannot assign to 'width' because it is a read-only property.
// }

console.log("API response immutable guarantees enforced.");

// --- Scenario 2: State Management with DeepReadonly ---
// In frameworks like Redux or Zustand, state should always be immutable.
// DeepReadonly can define the shape of your state.

interface AppState {
  currentUser?: DeepReadonly<{
    id: string;
    permissions: string[];
  }>;
  isLoading: boolean;
  settings: DeepReadonly<{
    theme: 'dark' | 'light';
    notifications: boolean;
  }>;
}

// A reducer or state update function would return a *new* state object
// conforming to DeepReadonly<AppState>.

const initialAppState: DeepReadonly<AppState> = {
  isLoading: false,
  settings: {
    theme: 'dark',
    notifications: true
  }
};

// initialAppState.isLoading = true; // Error
// initialAppState.settings.theme = 'light'; // Error

console.log("State management benefits from DeepReadonly.");

// We must always create new objects for updates:
function updateSettings(currentState: DeepReadonly<AppState>, newTheme: 'dark' | 'light'): DeepReadonly<AppState> {
  return {
    ...currentState,
    settings: {
      ...currentState.settings,
      theme: newTheme // This creates a new settings object with the updated theme
    }
  };
}

const newState = updateSettings(initialAppState, 'light');
console.log(newState.settings.theme); // Outputs: light
// initialAppState.settings.theme is still 'dark'