String Type Validation

/**
 * Returns whether the payload is a string
 * @param payload - Value to check
 * @returns Type guard indicating if payload is string
 */
function isString(payload: unknown): payload is string;

import { isString } from "is-what";

isString("hello"); // true
isString(""); // true (empty string is still a string)
isString(`template ${1}`); // true
isString(String(123)); // true (converts to primitive string)
isString(new String("hello")); // false (String object, not primitive)
isString(123); // false
isString(null); // false

if (isString(input)) {
  // TypeScript knows input is string
  console.log(input.toUpperCase());
  console.log(input.length);
}

/**
 * Returns whether the payload is an empty string
 * @param payload - Value to check
 * @returns Type guard indicating if payload is empty string
 */
function isEmptyString(payload: unknown): payload is "";

import { isEmptyString } from "is-what";

isEmptyString(""); // true
isEmptyString("hello"); // false
isEmptyString(" "); // false (space is not empty)
isEmptyString(null); // false
isEmptyString(undefined); // false

// Validation pattern
function validateRequiredField(value: unknown, fieldName: string) {
  if (isEmptyString(value)) {
    throw new Error(`${fieldName} cannot be empty`);
  }
  
  if (!isString(value)) {
    throw new Error(`${fieldName} must be a string`);
  }
  
  return value; // TypeScript knows this is a non-empty string
}

/**
 * Returns whether the payload is a non-empty string
 * @param payload - Value to check
 * @returns Type guard indicating if payload is non-empty string
 */
function isFullString(payload: unknown): payload is string;

import { isFullString } from "is-what";

isFullString("hello"); // true
isFullString("a"); // true
isFullString(" "); // true (space counts as content)
isFullString(""); // false
isFullString(null); // false
isFullString(123); // false

// Safe string operations
function processText(input: unknown) {
  if (isFullString(input)) {
    // Safe to perform string operations
    return input.trim().toLowerCase();
  }
  return null;
}

// Form validation
function validateInput(userInput: unknown) {
  if (!isFullString(userInput)) {
    return { valid: false, error: "Input must be a non-empty string" };
  }
  
  return { valid: true, value: userInput };
}

/**
 * Checks if a string is a valid hexadecimal string. If a length is provided, 
 * it also checks that the string has that length.
 * @param payload - Value to check
 * @param length - Optional expected length of the hexadecimal string
 * @returns Type guard indicating if payload is hexadecimal string
 */
function isHexDecimal(payload: unknown, length?: number): payload is string;

import { isHexDecimal } from "is-what";

// Valid hexadecimal strings
isHexDecimal("FF"); // true
isHexDecimal("123ABC"); // true
isHexDecimal("deadbeef"); // true
isHexDecimal("ff00cc", 6); // true (length matches)

// Invalid hexadecimal strings
isHexDecimal("123G"); // false (G is not a hex digit)
isHexDecimal("hello"); // false
isHexDecimal(""); // false
isHexDecimal("ff00cc", 4); // false (length doesn't match)
isHexDecimal(255); // false (number, not string)

// Note: This function does NOT accept 0x prefix
isHexDecimal("0xFF"); // false (0x prefix not supported)
isHexDecimal("xFF"); // false (x prefix not supported)

// Practical usage
function parseHexColor(color: unknown) {
  if (isHexDecimal(color)) {
    // Safe to parse as hexadecimal
    const normalized = color.startsWith('0x') 
      ? color.slice(2) 
      : color.startsWith('#') 
        ? color.slice(1) 
        : color;
    
    return parseInt(normalized, 16);
  }
  
  throw new Error("Invalid hexadecimal color format");
}

// Validation for hex input
function validateHexInput(input: unknown) {
  if (isHexDecimal(input)) {
    return {
      valid: true,
      value: input,
      decimal: parseInt(input.replace(/^0x/i, ''), 16)
    };
  }
  
  return { valid: false, error: "Must be a valid hexadecimal string" };
}

import { 
  isString, 
  isEmptyString, 
  isFullString, 
  isHexDecimal 
} from "is-what";

function analyzeString(value: unknown) {
  if (!isString(value)) {
    return "Not a string";
  }
  
  if (isEmptyString(value)) {
    return "Empty string";
  }
  
  const analysis = [`String with ${value.length} characters`];
  
  if (isHexDecimal(value)) {
    analysis.push("valid hexadecimal");
  }
  
  return analysis.join(", ");
}

// String processing pipeline
function processStringInput(input: unknown) {
  // Basic string validation
  if (!isString(input)) {
    throw new Error("Input must be a string");
  }
  
  // Handle empty string
  if (isEmptyString(input)) {
    return { processed: "", warnings: ["Empty string provided"] };
  }
  
  // Process non-empty strings
  const processed = input.trim();
  const warnings = [];
  
  if (processed !== input) {
    warnings.push("Whitespace was trimmed");
  }
  
  // Check for special formats
  const metadata: any = {};
  if (isHexDecimal(processed)) {
    metadata.hexValue = parseInt(processed.replace(/^0x/i, ''), 16);
    metadata.format = "hexadecimal";
  }
  
  return {
    processed,
    original: input,
    warnings,
    metadata
  };
}

// Safe string utilities
function safeStringOperations(text: unknown) {
  if (isFullString(text)) {
    return {
      uppercase: text.toUpperCase(),
      lowercase: text.toLowerCase(),
      length: text.length,
      words: text.split(/\s+/).filter(word => word.length > 0),
      isEmpty: false
    };
  }
  
  if (isEmptyString(text)) {
    return {
      uppercase: "",
      lowercase: "",
      length: 0,
      words: [],
      isEmpty: true
    };
  }
  
  return null; // Not a string
}

// Example usage
analyzeString("ff00cc"); // "String with 6 characters, valid hexadecimal"
analyzeString(""); // "Empty string"
analyzeString("hello world"); // "String with 11 characters"
analyzeString(123); // "Not a string"

const result = processStringInput("  0xFF  ");
// Returns: {
//   processed: "0xFF",
//   original: "  0xFF  ",
//   warnings: ["Whitespace was trimmed"],
//   metadata: { hexValue: 255, format: "hexadecimal" }
// }