Core Assertions

interface Assertion {
  // Language chains for readability
  to: Assertion;
  be: Assertion;
  been: Assertion;
  is: Assertion;
  that: Assertion;
  which: Assertion;
  and: Assertion;
  has: Assertion;
  have: Assertion;
  with: Assertion;
  at: Assertion;
  of: Assertion;
  same: Assertion;
  but: Assertion;
  does: Assertion;
  still: Assertion;
  also: Assertion;
}

// Language chains make assertions more readable
expect(value).to.be.a("string");
expect(obj).to.have.property("name").that.is.a("string");
expect(array).to.be.an("array").and.have.lengthOf(3);

interface Assertion {
  /**
   * Negates all assertions that follow in the chain
   */
  not: Assertion;
  
  /**
   * Causes all .equal, .include, .members, .keys, and .property 
   * assertions to use deep equality instead of strict equality
   */
  deep: Assertion;
  
  /**
   * Enables use of dot- and bracket-notation for referencing 
   * nested properties
   */
  nested: Assertion;
  
  /**
   * Causes all .property and .include assertions to ignore 
   * inherited properties
   */
  own: Assertion;
  
  /**
   * Causes all .members assertions to require members be in 
   * the same order
   */
  ordered: Assertion;
  
  /**
   * Causes .keys assertion to only require that the target 
   * have at least one of the given keys
   */
  any: Assertion;
  
  /**
   * Causes .keys assertion to require that the target have 
   * all of the given keys
   */
  all: Assertion;
}

/**
 * Asserts that the target is strictly equal (===) to value
 * @param value - Expected value
 * @param message - Optional error message
 */
equal(value: any, message?: string): Assertion;

/**
 * Asserts that the target is deeply equal to value
 * @param value - Expected value  
 * @param message - Optional error message
 */
eql(value: any, message?: string): Assertion;
eqls(value: any, message?: string): Assertion; // Alias

/**
 * Asserts that the target is greater than value
 * @param value - Comparison value
 * @param message - Optional error message
 */
above(value: number, message?: string): Assertion;
greaterThan(value: number, message?: string): Assertion; // Alias
gt(value: number, message?: string): Assertion; // Alias

/**
 * Asserts that the target is greater than or equal to value
 * @param value - Comparison value
 * @param message - Optional error message
 */
least(value: number, message?: string): Assertion;
gte(value: number, message?: string): Assertion; // Alias

/**
 * Asserts that the target is less than value
 * @param value - Comparison value
 * @param message - Optional error message
 */
below(value: number, message?: string): Assertion;
lessThan(value: number, message?: string): Assertion; // Alias
lt(value: number, message?: string): Assertion; // Alias

/**
 * Asserts that the target is less than or equal to value
 * @param value - Comparison value
 * @param message - Optional error message
 */
most(value: number, message?: string): Assertion;
lte(value: number, message?: string): Assertion; // Alias

/**
 * Asserts that the target is within the range [start, finish]
 * @param start - Range start (inclusive)
 * @param finish - Range end (inclusive)
 * @param message - Optional error message
 */
within(start: number, finish: number, message?: string): Assertion;

/**
 * Asserts that the target is approximately equal to expected within delta
 * @param expected - Expected value
 * @param delta - Maximum difference allowed
 * @param message - Optional error message
 */
closeTo(expected: number, delta: number, message?: string): Assertion;
approximately(expected: number, delta: number, message?: string): Assertion; // Alias

/**
 * Asserts that the target's type is the given string
 * @param type - Expected type name
 * @param message - Optional error message
 */
a(type: string, message?: string): Assertion;
an(type: string, message?: string): Assertion; // Alias

/**
 * Asserts that the target is an instance of constructor
 * @param constructor - Constructor function
 * @param message - Optional error message
 */
instanceof(constructor: Function, message?: string): Assertion;
instanceOf(constructor: Function, message?: string): Assertion; // Alias

interface Assertion {
  /**
   * Asserts that the target is truthy
   */
  ok: Assertion;
  
  /**
   * Asserts that the target is strictly true
   */
  true: Assertion;
  
  /**
   * Asserts that the target is strictly false
   */
  false: Assertion;
  
  /**
   * Asserts that the target is null
   */
  null: Assertion;
  
  /**
   * Asserts that the target is undefined
   */
  undefined: Assertion;
  
  /**
   * Asserts that the target is NaN
   */
  NaN: Assertion;
  
  /**
   * Asserts that the target exists (not null or undefined)
   */
  exist: Assertion;
  
  /**
   * Asserts that the target is empty (length/size of 0)
   */
  empty: Assertion;
  
  /**
   * Asserts that the target is an arguments object
   */
  arguments: Assertion;
  
  /**
   * Asserts that the target is a finite number
   */
  finite: Assertion;
  
  /**
   * Asserts that the target is callable (function)
   */
  callable: Assertion;
}

interface Assertion {
  /**
   * Asserts that the target is extensible (can have properties added)
   */
  extensible: Assertion;
  
  /**
   * Asserts that the target is sealed (properties cannot be added/removed)
   */
  sealed: Assertion;
  
  /**
   * Asserts that the target is frozen (properties cannot be added/removed/modified)
   */
  frozen: Assertion;
}

/**
 * Asserts that the target has a property with the given key
 * @param name - Property name or nested path
 * @param value - Expected property value (optional)
 * @param message - Optional error message
 */
property(name: string | number | symbol, value?: any, message?: string): Assertion;

/**
 * Asserts that the target has a property descriptor matching the given descriptor
 * @param name - Property name
 * @param descriptor - Expected property descriptor
 * @param message - Optional error message
 */
propertyDescriptor(name: string | number | symbol, descriptor: PropertyDescriptor, message?: string): Assertion;

/**
 * Asserts that the target has an own property descriptor matching the given descriptor
 * @param name - Property name
 * @param descriptor - Expected property descriptor (optional)
 * @param message - Optional error message
 */
ownPropertyDescriptor(name: string | number | symbol, descriptor?: PropertyDescriptor, message?: string): Assertion;

/**
 * Asserts that the target's own property names/keys match the given keys
 * @param keys - Expected keys (variadic or array)
 */
keys(...keys: any[]): Assertion;
key(key: any): Assertion; // Alias for single key

/**
 * Asserts that the target's length property has the expected value
 * @param length - Expected length
 * @param message - Optional error message
 */
lengthOf(length: number, message?: string): Assertion;

/**
 * Property for asserting on the length property itself
 */
length: Assertion;

/**
 * Asserts that the target includes the given value
 * @param value - Value to search for
 * @param message - Optional error message
 */
include(value: any, message?: string): Assertion;
includes(value: any, message?: string): Assertion; // Alias
contain(value: any, message?: string): Assertion; // Alias
contains(value: any, message?: string): Assertion; // Alias

/**
 * Asserts that the target includes all of the given members
 * @param members - Expected members
 */
members(members: any[]): Assertion;

/**
 * Asserts that the target is one of the given values
 * @param list - Array of acceptable values
 * @param message - Optional error message
 */
oneOf(list: any[], message?: string): Assertion;

/**
 * Asserts that the target matches the given regular expression
 * @param regex - Regular expression to match
 * @param message - Optional error message
 */
match(regex: RegExp, message?: string): Assertion;
matches(regex: RegExp, message?: string): Assertion; // Alias

/**
 * Asserts that the target string contains the given substring
 * @param substring - Substring to search for
 * @param message - Optional error message
 */
string(substring: string, message?: string): Assertion;

/**
 * Asserts that the target function throws an error
 * @param errorLike - Expected error constructor or instance
 * @param errMsgMatcher - Expected error message (string or regex)
 * @param message - Optional error message
 */
throw(errorLike?: any, errMsgMatcher?: string | RegExp, message?: string): Assertion;
throws(errorLike?: any, errMsgMatcher?: string | RegExp, message?: string): Assertion; // Alias
Throw(errorLike?: any, errMsgMatcher?: string | RegExp, message?: string): Assertion; // Alias

/**
 * Asserts that the target function increases a numeric property
 * @param object - Object containing the property
 * @param property - Property name to check
 * @param message - Optional error message
 */
increase(object: object, property?: string, message?: string): Assertion;
increases(object: object, property?: string, message?: string): Assertion; // Alias

/**
 * Asserts that the target function decreases a numeric property
 * @param object - Object containing the property  
 * @param property - Property name to check
 * @param message - Optional error message
 */
decrease(object: object, property?: string, message?: string): Assertion;
decreases(object: object, property?: string, message?: string): Assertion; // Alias

/**
 * Asserts that the target function changes a property value
 * @param object - Object containing the property
 * @param property - Property name to check
 * @param message - Optional error message
 */
change(object: object, property?: string, message?: string): Assertion;
changes(object: object, property?: string, message?: string): Assertion; // Alias

/**
 * Modifies the change assertion to check for a specific delta
 * @param delta - Expected change amount
 * @param message - Optional error message
 */
by(delta: number, message?: string): Assertion;

/**
 * Asserts that the target function/object responds to a method
 * @param method - Method name to check
 * @param message - Optional error message
 */
respondTo(method: string, message?: string): Assertion;
respondsTo(method: string, message?: string): Assertion; // Alias

/**
 * Asserts that the target satisfies the given predicate function
 * @param matcher - Predicate function to test with
 * @param message - Optional error message
 */
satisfy(matcher: (value: any) => boolean, message?: string): Assertion;
satisfies(matcher: (value: any) => boolean, message?: string): Assertion; // Alias

interface Assertion {
  /**
   * Forces .respondTo to check the function/constructor itself rather than instances
   */
  itself: Assertion;
}

// Simple value testing
expect(42).to.equal(42);
expect("hello").to.be.a("string");
expect(true).to.be.true;
expect(null).to.be.null;
expect([]).to.be.empty;

// Negation
expect(42).to.not.equal(24);
expect("hello").to.not.be.a("number");
expect(true).to.not.be.false;

expect(5).to.be.above(3).and.below(10);
expect(Math.PI).to.be.closeTo(3.14, 0.01);
expect(7).to.be.within(5, 10);

const obj = { name: "Alice", age: 25, address: { city: "Boston" } };

expect(obj).to.have.property("name", "Alice");
expect(obj).to.have.keys("name", "age", "address");
expect(obj).to.have.nested.property("address.city", "Boston");
expect(obj).to.include({ name: "Alice" });
expect(obj).to.deep.include({ address: { city: "Boston" } });

const array = [1, 2, 3, 4, 5];

expect(array).to.have.lengthOf(5);
expect(array).to.include(3);
expect(array).to.include.members([2, 4]);
expect(array).to.have.ordered.members([1, 2, 3, 4, 5]);
expect(array).to.deep.include.members([1, 2, 3]);

function incrementCounter() {
  counter++;
}

function throwError() {
  throw new Error("Something went wrong");
}

let counter = 0;

expect(incrementCounter).to.increase(() => counter);
expect(throwError).to.throw(Error);
expect(throwError).to.throw("Something went wrong");
expect(throwError).to.throw(Error, /went wrong/);

// Method existence testing
class Cat {
  meow() { return "meow"; }
}

expect(new Cat()).to.respondTo('meow');
expect(Cat).itself.to.respondTo('meow');

// Custom predicate testing  
expect(42).to.satisfy(n => n > 40);
expect("hello").to.satisfy(s => s.startsWith("h"));

// Property descriptor testing
const obj = {};
Object.defineProperty(obj, 'foo', { value: 1, writable: false });
expect(obj).to.have.ownPropertyDescriptor('foo', { value: 1, writable: false });

expect(user)
  .to.be.an("object")
  .that.has.property("email")
  .that.is.a("string")
  .and.matches(/@/)
  .and.has.length.above(5);

expect(products)
  .to.be.an("array")
  .that.is.not.empty
  .and.has.length.at.least(1)
  .and.all.have.property("price")
  .that.is.a("number")
  .and.is.above(0);