/* Decoding the Ambiguity of TypeScript's `object` Type */

// Example 1: `object` can hold various non-primitive types
let myGenericObject: object;

myGenericObject = { name: "Alice", age: 30 }; // A plain object
console.log("Plain object assigned to object type:", myGenericObject);

myGenericObject = [1, 2, 3]; // An array
console.log("Array assigned to object type:", myGenericObject);

myGenericObject = new Date(); // A Date object
console.log("Date object assigned to object type:", myGenericObject);

// Example 2: The critical limitation of `object` - no property access
function processObject(data: object) {
    // ERROR: Property 'name' does not exist on type 'object'.
    // console.log(data.name); 
    // This line would cause a TypeScript compilation error, highlighting that 'object'
    // provides no structural information for property access.
    
    // To access properties, we'd need a type assertion (e.g., `data as { name: string }`).
    // This bypasses type safety, transferring responsibility to the developer at runtime.
    if (typeof data === 'object' && data !== null && 'name' in data) {
        console.log("Property 'name' found (with runtime check):", (data as { name: string }).name);
    } else {
        console.log("Cannot safely access 'name' property on provided object.");
    }
}

processObject({ name: "Bob", id: 123 });
processObject([4, 5, 6]);
// processObject("hello"); // ERROR: Argument of type 'string' is not assignable to parameter of type 'object'.
                          // 'object' correctly prevents primitive types.

// Example 3: When `object` might be considered (rarely and cautiously)
// A function that receives *any* non-primitive, where specific properties are not needed
function logNonPrimitive(item: object) {
    console.log("Received a non-primitive item:", item);
    // We only care that it's not a primitive, not its internal structure.
}

logNonPrimitive({ id: 1, value: "test" });
logNonPrimitive([10, 20]);
// logNonPrimitive("primitive"); // Correctly prevents primitives

// Conclusion: `object` is a type of last resort when no structural information is known or needed.
// It offers broad compatibility for non-primitives but sacrifices compile-time property access safety.

/* Engineering `Record<string, unknown>` for Explicit Dictionaries */

// Example 1: Basic declaration and usage of Record<string, unknown>
type MyDictionary = Record<string, unknown>;

const settings: MyDictionary = {
    theme: "dark",
    fontSize: 16,
    isActive: true,
    // 'unknown' allows diverse value types while maintaining safety
};

console.log("\nSettings dictionary:", settings);

// Example 2: Accessing properties with Record<string, unknown>
function displaySetting(key: string, dict: MyDictionary) {
    // Accessing properties by string key is explicitly permitted
    const value = dict[key];
    
    // With 'unknown', we MUST narrow the type before using it in specific ways.
    // This activates a safety check.
    if (typeof value === 'string') {
        console.log(`Setting '${key}' (string):`, value.toUpperCase());
    } else if (typeof value === 'number') {
        console.log(`Setting '${key}' (number):`, value * 2);
    } else if (typeof value === 'boolean') {
        console.log(`Setting '${key}' (boolean):`, !value);
    } else if (value === undefined) { // Explicitly check for undefined to handle non-existent keys
        console.log(`Setting '${key}': Key does not exist.`);
    } else {
        console.log(`Setting '${key}' (unhandled type):`, value);
    }
}

displaySetting("theme", settings);
displaySetting("fontSize", settings);
displaySetting("isActive", settings);
displaySetting("nonExistentKey", settings); // Accessing non-existent key returns `undefined`, which is still `unknown`.
                                            // No compile-time error, as per dictionary nature.

// Example 3: The power of `unknown` over `any`
type DataItem = Record<string, unknown>;
const data: DataItem = { id: 1, name: "Product A" };

// const idValue: number = data.id; // ERROR: Type 'unknown' is not assignable to type 'number'.
                                  // Forces explicit type checking/assertion for safety.
const idValue: number = data.id as number; // Requires assertion, but developers are aware of the risk.
console.log("ID value (with assertion):", idValue);

// Example 4: Refusing non-string keys (for clarity, though JS coerces)
// const invalidDictionary: MyDictionary = { 123: "value" }; 
// While JavaScript allows numeric keys (which are coerced to strings),
// `Record<string, unknown>` clarifies the *intent* for string-only keys in TypeScript.
// The type system ensures consistency if you were, for instance, iterating over `Object.keys()`.

// Conclusion: `Record<string, unknown>` provides a strong, explicit contract for dictionary-like objects,
// combining structural clarity with safe access facilitated by the `unknown` value type, promoting robust code.

/* Strategic Comparison: Flexibility, Strictness, and Optimal Use Cases */

// Define types for comparison
type GenericObject = object;
type ExplicitDictionary = Record<string, unknown>;

// --- Scenario 1: Handling Configuration Data ---
// Problem: Load configuration that might have varied properties, where structure is known at access.

console.log("\n--- Configuration Data Scenario ---");
// Using `object` (less ideal for structured config)
const configObject: GenericObject = {
    debugMode: true,
    apiEndpoint: "/api/v1",
    timeout: 5000
};

// Accessing properties on `object` necessitates unsafe type assertions or indirect methods
// console.log((configObject as { debugMode: boolean }).debugMode); // Requires assertion, bypasses safety
console.log("Config (object type):", configObject); // Outputting raw object

// Using `Record<string, unknown>` (preferable for structured config)
const configRecord: ExplicitDictionary = {
    debugMode: true,
    apiEndpoint: "/api/v1",
    timeout: 5000
};

// Accessing properties on `Record` is permitted, with `unknown` values requiring narrowing
function getDebugMode(config: ExplicitDictionary): boolean {
    const debug = config['debugMode'];
    if (typeof debug === 'boolean') {
        return debug;
    }
    console.warn("debugMode not found or not a boolean in Record, defaulting to false.");
    return false;
}

console.log("Debug mode from Record:", getDebugMode(configRecord));

// --- Scenario 2: Processing Dynamic API Responses ---
// Imagine an API endpoint returning dynamic JSON data where keys are strings, values are mixed.

console.log("\n--- API Response Processing Scenario ---");
// Using `object` for an API response (very loose, offers no compile-time structure)
function processApiResponseObject(response: object) {
    console.log("Processing API response with 'object' type:");
    // No compile-time safety for 'response.id' or 'response.name'.
    // We'd rely entirely on runtime checks or risky assertions for any property access.
    // const id = (response as { id: number }).id; // Unsafe assertion, prone to runtime errors.
    console.log("Raw object response:", response);
}

// Using `Record<string, unknown>` for an API response (stronger intent, safer access)
function processApiResponseRecord(response: Record<string, unknown>) {
    console.log("Processing API response with 'Record<string, unknown>' type:");
    const userId = response['id'];
    if (typeof userId === 'number') {
        console.log("User ID (numeric):", userId);
    } else {
        console.log("User ID not found or not a number.");
    }
    
    const userName = response['name'];
    if (typeof userName === 'string') {
        console.log("User Name (string):", userName.toUpperCase());
    } else {
        console.log("User Name not found or not a string.");
    }
}

const apiData = { id: 101, name: "Alice Smith", status: "active", preferences: { theme: 'light' } };
processApiResponseObject(apiData);
processApiResponseRecord(apiData);

// --- Alternative Syntax: Index Signature --- 
type IndexSignatureDictionary = { [key: string]: unknown };
const altDict: IndexSignatureDictionary = { propA: 1, propB: "two" };
console.log("\nIndex signature dictionary:", altDict);
// This is largely functionally equivalent to Record<string, unknown>.

// Conclusion: `Record<string, unknown>` explicitly signals a dictionary structure,
// enabling safer, string-keyed property access with enforced type narrowing for values.
// `object` is too broad for most practical dictionary use cases, offering minimal structural safety.

/* Activating Best Practices and Advanced Refinements */

// --- Best Practice 1: Refine `unknown` with More Specific Types ---
// Forge tighter type contracts by replacing `unknown` with precise types.
interface UserProfileDetail {
    name: string;
    email: string;
    country?: string;
}

// Instead of Record<string, unknown>, use a specific union type for values
type UserMetadata = Record<string, string | number | boolean | UserProfileDetail>;

const userSettings: UserMetadata = {
    id: 123,
    username: "dev_master",
    isActive: true,
    lastLogin: "2023-10-26T10:00:00Z",
    profile: {
        name: "Jane Doe",
        email: "jane@example.com",
        country: "USA"
    }
};

console.log("\nUser settings with refined types:", userSettings);

// Access and narrow more safely due to explicit types
const username = userSettings.username;
if (typeof username === 'string') {
    console.log("Username (refined):", username.toUpperCase());
}

const userProfile = userSettings.profile;
if (typeof userProfile === 'object' && userProfile !== null && !Array.isArray(userProfile) && 'name' in userProfile) {
    // Now TypeScript knows userProfile is { name: string, email: string, ... }
    console.log("User Profile Name (refined):", userProfile.name);
}

// --- Best Practice 2: Type Guards for `Record<string, unknown>` Values ---
// Engineer custom type guards to streamline value narrowing.
function isString(value: unknown): value is string {
    return typeof value === 'string';
}

function isNumber(value: unknown): value is number {
    return typeof value === 'number';
}

function isUserProfileDetail(value: unknown): value is UserProfileDetail {
    return typeof value === 'object' && value !== null && 'name' in value && 'email' in value;
}

function displayValueSafely(dict: Record<string, unknown>, key: string) {
    const value = dict[key];
    if (isString(value)) {
        console.log(`Value for '${key}' is a string: ${value}`);
    } else if (isNumber(value)) {
        console.log(`Value for '${key}' is a number: ${value}`);
    } else if (isUserProfileDetail(value)) {
        console.log(`Value for '${key}' is a UserProfileDetail: ${value.name}`);
    } else {
        console.log(`Value for '${key}' is of an unhandled type or undefined: ${value}`);
    }
}

console.log("\n--- Displaying Values Safely with Type Guards ---");
displayValueSafely(userSettings, "username");
displayValueSafely(userSettings, "id");
displayValueSafely(userSettings, "profile");
displayValueSafely(userSettings, "nonExistentKey");

// --- Advanced Pattern: `Record<string, never>` for Empty Dictionaries ---
// Use `Record<string, never>` to explicitly declare an object with no allowed properties.
type EmptyConfig = Record<string, never>;

const initialConfig: EmptyConfig = {}; // This is allowed.
// const invalidConfig: EmptyConfig = { prop: "value" }; // ERROR: Object literal may only specify known properties.

console.log("\nEmpty config (Record<string, never>):", initialConfig);

// --- Distinguishing from `Map` --- 
// While Record is for plain objects, `Map` provides true map behavior (e.g., non-string keys, ordered iteration)
const strictMap = new Map<string, unknown>();
strictMap.set("id", 456);
strictMap.set("name", "Charlie");
console.log("\nTypeScript Map object:", Array.from(strictMap.entries()));

// Conclusion: Optimize your dictionary typing by moving beyond 'unknown' when possible,
// leveraging type guards, and applying specific `Record` variations to enforce robust contracts.