Collection and String Matchers

/**
 * Checks if iterable contains item using indexOf comparison
 * @param item - Item to search for in the collection
 */
ExpectationObject.toContain(item: any): void;

// Array containment
expect(['apple', 'banana', 'cherry']).toContain('banana');
expect([1, 2, 3, 4, 5]).toContain(3);

// String containment
expect('Hello World').toContain('World');
expect('JavaScript').toContain('Script');

// Works with any iterable that has indexOf
const set = new Set(['a', 'b', 'c']);
expect([...set]).toContain('b');

/**
 * Checks if iterable contains item using deep equality comparison
 * @param item - Item to search for using deep equality
 */
ExpectationObject.toContainEqual(item: any): void;

// Object containment with deep equality
expect([
  {name: 'John', age: 30},
  {name: 'Jane', age: 25}
]).toContainEqual({name: 'John', age: 30});

// Array containment with deep equality
expect([[1, 2], [3, 4], [5, 6]]).toContainEqual([3, 4]);

// Date objects
expect([
  new Date('2023-01-01'),
  new Date('2023-01-02')
]).toContainEqual(new Date('2023-01-01'));

/**
 * Checks if object has specific length property value
 * @param length - Expected length value
 */
ExpectationObject.toHaveLength(length: number): void;

// Array length
expect([1, 2, 3]).toHaveLength(3);
expect([]).toHaveLength(0);

// String length
expect('hello').toHaveLength(5);
expect('').toHaveLength(0);

// Custom objects with length property
const customArray = {0: 'a', 1: 'b', length: 2};
expect(customArray).toHaveLength(2);

// Function arguments
function testArgs() {
  expect(arguments).toHaveLength(3);
}
testArgs('a', 'b', 'c');

/**
 * Checks if object has property at path, optionally with specific value
 * @param path - Property path (dot notation supported)
 * @param value - Optional expected value for the property
 */
ExpectationObject.toHaveProperty(path: string, value?: any): void;

const user = {
  name: 'John',
  address: {
    street: '123 Main St',
    city: 'Anytown'
  },
  preferences: {
    theme: 'dark',
    notifications: true
  }
};

// Check property exists
expect(user).toHaveProperty('name');
expect(user).toHaveProperty('address');

// Check property with specific value
expect(user).toHaveProperty('name', 'John');
expect(user).toHaveProperty('preferences.theme', 'dark');

// Nested property paths
expect(user).toHaveProperty('address.street');
expect(user).toHaveProperty('address.street', '123 Main St');
expect(user).toHaveProperty('preferences.notifications', true);

// Array indexing in paths
const data = {items: ['a', 'b', 'c']};
expect(data).toHaveProperty('items.0', 'a');
expect(data).toHaveProperty('items.2', 'c');

/**
 * Checks if string matches regex pattern or contains substring
 * @param pattern - RegExp pattern or string to match
 */
ExpectationObject.toMatch(pattern: string | RegExp): void;

// String substring matching
expect('Hello World').toMatch('World');
expect('JavaScript is awesome').toMatch('Script');

// Regular expression matching
expect('hello@example.com').toMatch(/^[\w\.-]+@[\w\.-]+\.\w+$/);
expect('2023-12-25').toMatch(/^\d{4}-\d{2}-\d{2}$/);
expect('Phone: (555) 123-4567').toMatch(/\(\d{3}\) \d{3}-\d{4}/);

// Case-insensitive matching
expect('Hello World').toMatch(/hello/i);

// Testing user input validation
const phoneNumber = getUserPhoneNumber();
expect(phoneNumber).toMatch(/^\(\d{3}\) \d{3}-\d{4}$/);

/**
 * Checks if object is instance of given constructor
 * @param constructor - Constructor function or class to check against
 */
ExpectationObject.toBeInstanceOf(constructor: Function): void;

// Built-in types
expect(new Date()).toBeInstanceOf(Date);
expect([1, 2, 3]).toBeInstanceOf(Array);
expect(new RegExp('test')).toBeInstanceOf(RegExp);
expect(new Error('test')).toBeInstanceOf(Error);

// Custom classes
class User {
  constructor(name) {
    this.name = name;
  }
}

class AdminUser extends User {
  constructor(name) {
    super(name);
    this.isAdmin = true;
  }
}

const user = new User('John');
const admin = new AdminUser('Jane');

expect(user).toBeInstanceOf(User);
expect(admin).toBeInstanceOf(AdminUser);
expect(admin).toBeInstanceOf(User);  // inheritance works

// Testing API responses
const response = await fetchUserData();
expect(response.createdAt).toBeInstanceOf(Date);
expect(response.errors).toBeInstanceOf(Array);

const apiResponse = {
  users: [
    {id: 1, name: 'John', emails: ['john@example.com']},
    {id: 2, name: 'Jane', emails: ['jane@example.com']}
  ],
  pagination: {
    total: 2,
    page: 1
  }
};

// Test array length and content
expect(apiResponse.users).toHaveLength(2);
expect(apiResponse.users).toContainEqual({
  id: 1, 
  name: 'John', 
  emails: ['john@example.com']
});

// Test nested properties
expect(apiResponse).toHaveProperty('pagination.total', 2);
expect(apiResponse).toHaveProperty('users.0.name', 'John');

// Email validation
const email = 'user@example.com';
expect(email).toMatch(/^[^\s@]+@[^\s@]+\.[^\s@]+$/);

// URL validation
const url = 'https://example.com/path';
expect(url).toMatch(/^https?:\/\/.+/);

// Phone number formats
const phone = '(555) 123-4567';
expect(phone).toMatch(/^\(\d{3}\) \d{3}-\d{4}$/);

const products = [
  {name: 'Laptop', category: 'Electronics', price: 999},
  {name: 'Book', category: 'Education', price: 29},
  {name: 'Phone', category: 'Electronics', price: 699}
];

// Check if specific product exists
expect(products).toContainEqual({
  name: 'Laptop', 
  category: 'Electronics', 
  price: 999
});

// Check collection size
expect(products).toHaveLength(3);
expect(products.filter(p => p.category === 'Electronics')).toHaveLength(2);

expect(['a', 'b', 'c']).not.toContain('d');
expect([1, 2, 3]).not.toContainEqual({id: 1});
expect('hello').not.toHaveLength(10);
expect({}).not.toHaveProperty('nonexistent');
expect('hello').not.toMatch(/\d+/);
expect('string').not.toBeInstanceOf(Number);

await expect(Promise.resolve(['a', 'b'])).resolves.toContain('a');
await expect(Promise.resolve('hello')).resolves.toMatch(/hello/);
await expect(Promise.resolve(new Date())).resolves.toBeInstanceOf(Date);