/*
  STRING LITERAL TYPES
  Define exact string values permitted for a property.
  This is invaluable for API statuses, event names, or fixed enumerations.
*/
type UserStatus = "active" | "inactive" | "pending" | "deleted";

interface UserProfile {
  id: string;
  name: string;
  status: UserStatus; // Enforces specific string values
}

const activeUser: UserProfile = {
  id: "user-123",
  name: "Alice",
  status: "active",
};

// const invalidUser: UserProfile = { // TypeScript will error here
//   id: "user-456",
//   name: "Bob",
//   status: "blocked", // Type error: 'blocked' is not assignable to type 'UserStatus'
// };

/*
  NUMERIC LITERAL TYPES
  Constrain numeric values to specific integers or floats.
  Perfect for API versioning, fixed error codes, or predefined quantities.
*/
type APIVersion = 1 | 2 | 3;

type HttpStatusCode = 200 | 201 | 400 | 404 | 500;

interface ApiResponse {
  version: APIVersion;
  code: HttpStatusCode;
  data: any;
}

const successResponse: ApiResponse = {
  version: 2,
  code: 200,
  data: { message: "Operation successful" },
};

// const invalidResponse: ApiResponse = { // TypeScript will error here
//   version: 4, // Type error: 4 is not assignable to type 'APIVersion'
//   code: 202, // Type error: 202 is not assignable to type 'HttpStatusCode'
//   data: null,
// };

/*
  BOOLEAN LITERAL TYPES
  Though less common as standalone types, they can be part of union types
  to express very specific state combinations, like 'isReady: true' always being paired
  with specific data.
*/
type ToggleState = true | false; // Equivalent to boolean, but useful in specific union contexts

interface FeatureToggle {
  name: string;
  enabled: ToggleState;
}

const featureA: FeatureToggle = {
  name: "NewDashboard",
  enabled: true,
};

/*
  Scenario: Defining a request payload for a task management API.
  Tasks can have specific priorities and states.
*/

// 1. Define Literal Type Unions for fixed enumerations
type TaskPriority = "low" | "medium" | "high" | "urgent";
type TaskStatus = "todo" | "in_progress" | "done" | "blocked";
type TaskType = "feature" | "bug" | "refactor" | "documentation";

// 2. Define the Request Payload Interface using these literal types
interface CreateTaskRequest {
  title: string;
  description?: string; // Optional description
  priority: TaskPriority;
  status: TaskStatus;
  type: TaskType;
  dueDate: string; // ISO date string, e.g., "2026-03-30"
  assigneeId: string;
}

// 3. Example of a valid request payload
const newTaskPayload: CreateTaskRequest = {
  title: "Implement user authentication",
  priority: "high",
  status: "todo",
  type: "feature",
  dueDate: "2026-04-15",
  assigneeId: "dev-001",
};

console.log("Valid Task Payload:", newTaskPayload);

// 4. Example of an invalid request payload (TypeScript will flag errors)
// const invalidTaskPayload: CreateTaskRequest = {
//   title: "Fix login bug",
//   priority: "critical", // Type error: 'critical' is not assignable to type 'TaskPriority'
//   status: "pending",   // Type error: 'pending' is not assignable to type 'TaskStatus'
//   type: "bug",
//   dueDate: "2026-03-01",
//   assigneeId: "dev-002",
// };

// 5. Another example for updating a task, possibly allowing a subset of statuses
//    Here, we can reuse the literal types, demonstrating their reusability.
interface UpdateTaskStatusRequest {
  taskId: string;
  newStatus: TaskStatus; // Can be any defined TaskStatus
  updatedBy: string;
}

const updatePayload: UpdateTaskStatusRequest = {
  taskId: "task-987",
  newStatus: "in_progress",
  updatedBy: "admin",
};

console.log("Valid Update Payload:", updatePayload);

/*
  TEMPLATE LITERAL TYPES FOR API PATHS
  Enforce specific URL path structures at compile time.
  This is critical for RESTful APIs where resource identifiers are part of the path.
*/

// 1. Define base literal types for identifiers or fixed segments
type UserId = `user-${string}`;
type PostId = `post-${string}`;
type CommentId = `comment-${string}`;
type ResourceSegment = 'users' | 'posts' | 'comments';

// 2. Combine them using template literal types for full API paths
type UserApiPath = `/api/${ResourceSegment}/${UserId}`;
type PostApiPath = `/api/${ResourceSegment}/${PostId}`;
type CommentApiPath = `/api/${ResourceSegment}/${CommentId}`;

type CombinedApiPath = UserApiPath | PostApiPath | CommentApiPath;

// 3. Example of valid API paths
const validUserPath: UserApiPath = `/api/users/user-123`;
const validPostPath: PostApiPath = `/api/posts/post-abc`;
const validCommentPath: CommentApiPath = `/api/comments/comment-xyz`;

console.log("Valid User Path:", validUserPath);
console.log("Valid Post Path:", validPostPath);

// 4. Example of invalid API paths (TypeScript will flag errors)
// const invalidUserPath: UserApiPath = `/api/customers/user-123`; // Error: 'customers' is not 'users'
// const invalidPostPath: PostApiPath = `/api/posts/user-abc`;   // Error: 'user-abc' is not 'post-${string}'


/*
  TEMPLATE LITERAL TYPES FOR HEADERS
  Enforce specific header formats, common for authentication tokens or content types.
*/

// 1. Define a type for a bearer token
type BearerToken = `Bearer ${string}`;

interface RequestHeaders {
  Authorization: BearerToken;
  "Content-Type": "application/json" | "application/x-www-form-urlencoded";
  "X-Request-Id"?: `req-${string}`;
}

// 2. Example of valid request headers
const headers: RequestHeaders = {
  Authorization: "Bearer abcdef12345",
  "Content-Type": "application/json",
  "X-Request-Id": "req-uuid-456",
};

console.log("Valid Request Headers:", headers);

// 3. Example of invalid request headers (TypeScript will flag errors)
// const invalidHeaders: RequestHeaders = {
//   Authorization: "Token xyz", // Error: 'Token xyz' is not 'Bearer ${string}'
//   "Content-Type": "text/plain", // Error: 'text/plain' is not 'application/json' | 'application/x-www-form-urlencoded'
// };

/*
  ENGINEERING API RESPONSE CONTRACTS
  Use literal types to define predictable and self-documenting API responses,
  especially for success/failure states and error messages.
*/

// 1. Define Literal Types for common response properties
type ResponseStatus = "success" | "error" | "warning";
type ErrorCode = "INVALID_INPUT" | "UNAUTHORIZED" | "NOT_FOUND" | "SERVER_ERROR";
type SuccessMessage = "Operation successful." | "Data retrieved.";

// 2. Define a generic base response interface
interface BaseApiResponse {
  timestamp: string;
  status: ResponseStatus;
}

// 3. Define specific success response interfaces using literal types
interface SuccessResponse<T> extends BaseApiResponse {
  status: "success"; // Literal type for success status
  message: SuccessMessage;
  data: T;
}

// 4. Define specific error response interfaces using literal types
interface ErrorResponse extends BaseApiResponse {
  status: "error"; // Literal type for error status
  code: ErrorCode; // Specific error codes
  message: string; // Error message can be dynamic but code is fixed
}

// 5. Union of possible API responses for a specific endpoint (e.g., fetching a user)
interface User {
  id: string;
  name: string;
  email: string;
}
type FetchUserApiResponse = SuccessResponse<User> | ErrorResponse;

// 6. Example of a valid success response
const userSuccess: FetchUserApiResponse = {
  timestamp: new Date().toISOString(),
  status: "success",
  message: "Data retrieved.",
  data: {
    id: "user-789",
    name: "Charlie",
    email: "charlie@example.com",
  },
};

console.log("Successful User Response:", userSuccess);

// 7. Example of a valid error response
const userError: FetchUserApiResponse = {
  timestamp: new Date().toISOString(),
  status: "error",
  code: "NOT_FOUND",
  message: "User with ID 'user-000' not found.",
};

console.log("Error User Response:", userError);

// 8. Example of an invalid response (TypeScript will flag errors)
// const invalidResponse: FetchUserApiResponse = {
//   timestamp: new Date().toISOString(),
//   status: "success",
//   message: "Something went wrong.", // Error: 'Something went wrong.' is not 'Operation successful.' | 'Data retrieved.'
//   data: null,
// };

/*
  ADVANCED STRATEGIES & BEST PRACTICES
  Combining literal types with other TypeScript features for optimal API contract definition.
*/

// 1. Combining with Generics for Flexible but Strict Payloads
//    Define a generic command type that mandates a specific 'command' literal.
interface Command<TCommand extends string, TPayload> {
  command: TCommand;
  payload: TPayload;
}

interface CreateUserPayload {
  name: string;
  email: string;
}
type CreateUserCommand = Command<"createUser", CreateUserPayload>;

interface DeleteUserPayload {
  id: string;
}
type DeleteUserCommand = Command<"deleteUser", DeleteUserPayload>;

// Union of all possible commands
type AllCommands = CreateUserCommand | DeleteUserCommand;

const userCreationRequest: AllCommands = {
  command: "createUser",
  payload: { name: "Jane Doe", email: "jane@example.com" },
};

// const invalidCommand: AllCommands = { // Error: 'updateUser' is not 'createUser' | 'deleteUser'
//   command: "updateUser",
//   payload: { id: "123", name: "Jane" },
// };

/*
  2. Leveraging `as const` for Deep Immutability and Literal Type Inference
  The `as const` assertion tells TypeScript to infer the narrowest possible type (literal types)
  for all properties within an object or array.
*/
const API_ROUTES = {
  USERS: '/api/users' as const,
  PRODUCTS: '/api/products' as const,
  ORDERS: '/api/orders' as const,
};

type ApiRoute = typeof API_ROUTES[keyof typeof API_ROUTES]; // "/api/users" | "/api/products" | "/api/orders"

function fetchResource(route: ApiRoute) {
  console.log(`Fetching from: ${route}`);
}

fetchResource(API_ROUTES.USERS);
// fetchResource('/api/settings'); // Error: Argument of type '/api/settings' is not assignable to type 'ApiRoute'

/*
  3. Avoiding Over-Engineering: When not to use Literal Types
  Use literal types judiciously. For truly dynamic data, a simple 'string' or 'number' is appropriate.
  Over-engineering can lead to brittle types that require frequent updates.
*/
interface LogEntry {
  id: string; // Likely a UUID, not a fixed literal
  message: string; // Free-form text
  level: "info" | "warn" | "error" | "debug"; // Good use of literal type
  timestamp: string; // ISO date string
}

const log: LogEntry = {
  id: "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  message: "User 'test' logged in successfully from IP 192.168.1.10",
  level: "info",
  timestamp: new Date().toISOString(),
};

/*
  4. Integration with External Tools (OpenAPI/Swagger)
  Many tools can generate TypeScript types from OpenAPI schemas. Ensure your manual
  type definitions align or complement these generated types.
  OpenAPI can define enums which translate directly to TypeScript literal unions.
*/
// Example: OpenAPI definition for a 'status' enum:
// status:
//   type: string
//   enum:
//     - active
//     - inactive
//     - pending
// This will typically generate: type Status = "active" | "inactive" | "pending";