Utilities

/**
 * Compare two values with Ember's comparison semantics
 * Returns -1, 0, or 1 for use in sorting algorithms
 * @param a - First value to compare
 * @param b - Second value to compare
 * @returns -1 if a < b, 0 if a === b, 1 if a > b
 */
function compare(a: any, b: any): number;

/**
 * Test deep equality between two values
 * Handles objects, arrays, dates, and primitive values
 * @param a - First value to compare
 * @param b - Second value to compare
 * @returns Whether values are deeply equal
 */
function isEqual(a: any, b: any): boolean;

import { compare, isEqual } from "@ember/utils";

// Sorting with compare
const items = [
  { name: 'Charlie', age: 30 },
  { name: 'Alice', age: 25 },
  { name: 'Bob', age: 35 }
];

items.sort((a, b) => compare(a.name, b.name));
// Result: Alice, Bob, Charlie

// Deep equality testing
const obj1 = { user: { name: 'John', tags: ['admin', 'user'] } };
const obj2 = { user: { name: 'John', tags: ['admin', 'user'] } };
const obj3 = { user: { name: 'Jane', tags: ['user'] } };

console.log(isEqual(obj1, obj2)); // true
console.log(isEqual(obj1, obj3)); // false

// Primitive comparisons
console.log(compare(10, 20)); // -1
console.log(compare('apple', 'banana')); // -1
console.log(compare(new Date('2023-01-01'), new Date('2023-01-02'))); // -1

/**
 * Test if value is null or undefined
 * @param value - Value to test
 * @returns Whether value is null or undefined
 */
function isNone(value: any): boolean;

/**
 * Test if value is "blank" (empty, whitespace-only, null, or undefined)
 * @param value - Value to test
 * @returns Whether value is blank
 */
function isBlank(value: any): boolean;

/**
 * Test if value is empty (length === 0, size === 0, or no enumerable properties)
 * @param value - Value to test
 * @returns Whether value is empty
 */
function isEmpty(value: any): boolean;

/**
 * Test if value is present (not blank)
 * @param value - Value to test
 * @returns Whether value is present
 */
function isPresent(value: any): boolean;

import { isNone, isBlank, isEmpty, isPresent } from "@ember/utils";

// isNone tests
console.log(isNone(null)); // true
console.log(isNone(undefined)); // true
console.log(isNone(0)); // false
console.log(isNone('')); // false

// isBlank tests
console.log(isBlank(null)); // true
console.log(isBlank(undefined)); // true
console.log(isBlank('')); // true
console.log(isBlank('   ')); // true
console.log(isBlank('hello')); // false
console.log(isBlank(0)); // false

// isEmpty tests
console.log(isEmpty([])); // true
console.log(isEmpty({})); // true
console.log(isEmpty('')); // true
console.log(isEmpty([1, 2, 3])); // false
console.log(isEmpty({ name: 'John' })); // false

// isPresent tests
console.log(isPresent('hello')); // true
console.log(isPresent([1, 2, 3])); // true
console.log(isPresent({ name: 'John' })); // true
console.log(isPresent('')); // false
console.log(isPresent(null)); // false

// Practical usage in templates and components
export default class UserProfile extends Component {
  get hasContactInfo() {
    return isPresent(this.args.user.email) || isPresent(this.args.user.phone);
  }
  
  get displayName() {
    const { firstName, lastName } = this.args.user;
    
    if (isPresent(firstName) && isPresent(lastName)) {
      return `${firstName} ${lastName}`;
    } else if (isPresent(firstName)) {
      return firstName;
    } else if (isPresent(lastName)) {
      return lastName;
    } else {
      return 'Anonymous User';
    }
  }
}

/**
 * Get detailed type information for a value
 * More precise than JavaScript's typeof operator
 * @param obj - Value to get type for
 * @returns String describing the type
 */
function typeOf(obj: any): string;

import { typeOf } from "@ember/utils";

// Basic types
console.log(typeOf(null)); // 'null'
console.log(typeOf(undefined)); // 'undefined'
console.log(typeOf(true)); // 'boolean'
console.log(typeOf(42)); // 'number'
console.log(typeOf('hello')); // 'string'
console.log(typeOf(Symbol('test'))); // 'symbol'

// Objects and collections
console.log(typeOf({})); // 'object'
console.log(typeOf([])); // 'array'
console.log(typeOf(new Date())); // 'date'
console.log(typeOf(/regex/)); // 'regexp'
console.log(typeOf(new Error())); // 'error'

// Functions
console.log(typeOf(function() {})); // 'function'
console.log(typeOf(() => {})); // 'function'
console.log(typeOf(async function() {})); // 'function'

// Classes and instances
class MyClass {}
console.log(typeOf(MyClass)); // 'class'
console.log(typeOf(new MyClass())); // 'instance'

// Ember objects
import EmberObject from "@ember/object";
const MyEmberClass = EmberObject.extend({});
console.log(typeOf(MyEmberClass)); // 'class'
console.log(typeOf(MyEmberClass.create())); // 'instance'

// Practical usage
function processValue(value) {
  const type = typeOf(value);
  
  switch (type) {
    case 'string':
      return value.trim().toLowerCase();
    case 'number':
      return Math.round(value);
    case 'array':
      return value.filter(item => isPresent(item));
    case 'object':
      return Object.keys(value).length > 0 ? value : null;
    case 'date':
      return value.toISOString();
    default:
      return value;
  }
}

/**
 * Convert string to camelCase
 * @param str - String to convert
 * @returns camelCase string
 */
function camelize(str: string): string;

/**
 * Convert string to PascalCase/ClassCase
 * @param str - String to convert
 * @returns PascalCase string
 */
function classify(str: string): string;

/**
 * Convert string to dasherized format
 * @param str - String to convert
 * @returns dasherized-string
 */
function dasherize(str: string): string;

/**
 * Convert string to underscore_case
 * @param str - String to convert
 * @returns underscore_case string
 */
function underscore(str: string): string;

/**
 * Capitalize first letter of string
 * @param str - String to capitalize
 * @returns Capitalized string
 */
function capitalize(str: string): string;

/**
 * Convert string to human-readable format
 * @param str - String to humanize
 * @returns Human readable string
 */
function humanize(str: string): string;

import { 
  camelize, 
  classify, 
  dasherize, 
  underscore, 
  capitalize, 
  humanize 
} from "@ember/string";

// String transformations
console.log(camelize('my-component-name')); // 'myComponentName'
console.log(classify('my-component-name')); // 'MyComponentName'
console.log(dasherize('MyComponentName')); // 'my-component-name'
console.log(underscore('MyComponentName')); // 'my_component_name'
console.log(capitalize('hello world')); // 'Hello world'
console.log(humanize('first_name')); // 'First name'

// Practical usage for dynamic class/file names
function generateComponentName(userInput) {
  return classify(dasherize(userInput.trim()));
}

console.log(generateComponentName('User Profile Card')); // 'UserProfileCard'

/**
 * Test if object is an array or array-like
 * @param obj - Object to test
 * @returns Whether object is array-like
 */
function isArray(obj: any): boolean;

/**
 * Convert value to array
 * @param obj - Value to convert
 * @returns Array containing the value(s)
 */
function makeArray(obj: any): any[];

import { isArray, makeArray } from "@ember/array";

// Array testing
console.log(isArray([])); // true
console.log(isArray([1, 2, 3])); // true
console.log(isArray('string')); // false
console.log(isArray({ length: 3 })); // false (not array-like enough)

// Converting to arrays
console.log(makeArray(null)); // []
console.log(makeArray(undefined)); // []
console.log(makeArray('hello')); // ['hello']
console.log(makeArray([1, 2, 3])); // [1, 2, 3] (unchanged)
console.log(makeArray({ name: 'John' })); // [{ name: 'John' }]

// Practical usage
function processItems(items) {
  const itemArray = makeArray(items);
  return itemArray.filter(item => isPresent(item));
}

interface ComparisonResult {
  /** -1 if first value is less, 0 if equal, 1 if greater */
  value: -1 | 0 | 1;
}

interface TypeofResult {
  /** Detailed type string */
  type: 'null' | 'undefined' | 'boolean' | 'number' | 'string' | 'symbol' | 
        'object' | 'array' | 'date' | 'regexp' | 'error' | 'function' | 
        'class' | 'instance';
}