vitest-pool-assemblyscript 0.3.0 → 0.4.0

package/README.md

@@ -141,7 +141,8 @@ npx vitest run
 - Suite and test definition using `describe()` and `test()` in AssemblyScript
 - Inline test option configuration for common vitest options: `timeout`, `retry`, `skip`, `only`, `fails`
 - Assertion matching API based on vitest/jest `expect()` API
-  - `.not`, `toBe`, `toBeCloseTo`, `toEqual` (with caveats*), `toStrictEqual`, `toHaveLength`, `toThrowError`, `toBeTruthy`, `toBeFalsy`, `toBeNull`, `toBeNullable`, `toBeNaN` - See [Matchers API](docs/matchers-api.md) for details and differences from JavaScript
+  - `.not`, `toBe`, `toBeCloseTo`, `toEqual` (with caveats*), `toStrictEqual`, `toBeGreaterThan`, `toBeGreaterThanOrEqual`, `toBeLessThan`, `toBeLessThanOrEqual`, `toHaveLength`, `toThrowError`, `toBeTruthy`, `toBeFalsy`, `toBeNull`, `toBeNullable`, `toBeNaN`
+  - See [Matchers API](docs/matchers-api.md) for details and differences from JavaScript
 - Highlighted diffs for assertion and runtime failures, which point to source code
 - Source-mapped WASM error stack traces (accurate AssemblyScript source `function file:line:column`)
 - AssemblyScript console output captured and provided to vitest for display
@@ -286,12 +287,13 @@ These are known limitations which are currently being worked on.
 - Lifecycle hooks (`beforeEach`, `afterEach`, `beforeAll`, `afterAll`)
 - Watch mode: re-run applicable tests on source file changes
 - `toEqual` reflection for deep equality inspection of user objects
+- `describe.for/each` and `test.for/each`
 - expect.soft to prevent fail-fast behavior
 - Allow delegating JS/TS to istanbul coverage provider in addition to v8
 - Maybe: Per-file compilation setting override
 
 **Epic: Expand expect matcher API**
-- Planned: `toBeDefined`, `toBeUndefined`, `toBeGreaterThan`, `toBeGreaterThanOrEqual`, `toBeLessThan`, `toBeLessThanOrEqual`, `toContain`, `toContainEqual`
+- Planned: `toBeDefined`, `toBeUndefined`, `toContain`, `toContainEqual`
 - Likely: `toBeOneOf`, `toBeTypeOf`, `toBeInstanceOf`, `toHaveProperty`, `toMatch`
 
 **Epic: Spy and Mock**
@@ -309,10 +311,10 @@ These are known limitations which are currently being worked on.
 ## Performance
 
 Efforts have been made to compile and run tests as quickly as possible:
-- Separate compile and test execution threads for quicker startup and respawn
+- Separate compile and test execution thread pools, workers, and runners for quicker startup and respawn
 - Compile threads tuned to take advantage of significant Node V8 engine warmup time savings on consecutive AssemblyScript compilations
 - In-memory compiled files and source maps to eliminate intermediate disk I/O
-- Enforced hard timeouts for long-running WASM via thread termination, with intelligent resume
+- Enforced hard timeouts for long-running WASM tests via thread termination, with intelligent resume
 
 As such, it is capable of compiling dozens of test files comprising hundreds of tests in a few seconds.
 

package/assembly/compare.ts

@@ -219,6 +219,133 @@ export function equals<T, U>(actual: T, expected: U): bool {
   );
 }
 
+export enum InequalityOperation {
+  LessThan,
+  LessThanOrEqual,
+  GreaterThan,
+  GreaterThanOrEqual,
+}
+
+/**
+ * Applies an inequality operation to two values of the same promoted type.
+ * Handles <, <=, >, >= for any type that supports these operators (numbers, strings).
+ */
+function applyInequalityOp<T>(a: T, b: T, op: InequalityOperation): bool {
+  if (op == InequalityOperation.LessThan) return a < b;
+  if (op == InequalityOperation.LessThanOrEqual) return a <= b;
+  if (op == InequalityOperation.GreaterThan) return a > b;
+  return a >= b; // GreaterThanOrEqual
+}
+
+/**
+ * Generic inequality comparison. Promotes both values to a common type and applies
+ * the requested inequality operation.
+ *
+ * Strings are compared lexicographically. Booleans are treated as integers (true=1, false=0).
+ * Non-string references are not comparable and throw an error.
+ *
+ * Cross-sign integer comparisons are supported (more permissive than AS's own operators)
+ * via signed-negative early return + u64 promotion. Float/integer combinations where the
+ * float's mantissa cannot losslessly represent the integer type's range are rejected,
+ * matching AS compiler behavior. See docs/matcher-research.md for details.
+ */
+export function compareInequality<T, U>(actual: T, compareTo: U, expectedOperation: InequalityOperation): bool {
+  // --- Strings: lexicographic comparison ---
+  if (isString<T>() && isString<U>()) {
+    // Guard against null before casting, mirroring identical()'s pattern
+    const actualIsNull = isNullable<T>() && actual == null;
+    const compareToIsNull = isNullable<U>() && compareTo == null;
+    if (actualIsNull || compareToIsNull) {
+      throw new Error(
+        "Cannot compare null string with inequality operators: the result is undefined."
+        + " Use toBeNull() to check for null values."
+      );
+    }
+    return applyInequalityOp(<string>actual, <string>compareTo, expectedOperation);
+  }
+
+  // --- Reject non-string references (objects, arrays, etc.) ---
+  if (isReference<T>() || isReference<U>()) {
+    throw new Error(
+      "Inequality comparison is not supported for " + nameof<T>() + " and " + nameof<U>()
+      + ". Only numeric types and strings can be compared with inequality matchers."
+    );
+  }
+
+  // --- Float/integer precision-loss rejection ---
+  // Reject combinations where the float's mantissa cannot losslessly represent
+  // the integer type's full range (sizeof(integer) >= sizeof(float)).
+  // This mirrors AS's own operator rejection (e.g. f32 > i32, f64 > i64).
+  if (isFloat<T>() && isInteger<U>()) {
+    if (sizeof<U>() >= sizeof<T>()) {
+      throw new Error(
+        "Cannot compare " + nameof<T>() + " with " + nameof<U>()
+        + ": float precision is insufficient for the integer type's range."
+        + " Cast both values to f64 before comparing, e.g. expect(f64(a)).toBeGreaterThan(f64(b))."
+        + " Note: large integer values may lose precision when cast to f64, which could cause false positives."
+      );
+    }
+  } else if (isInteger<T>() && isFloat<U>()) {
+    if (sizeof<T>() >= sizeof<U>()) {
+      throw new Error(
+        "Cannot compare " + nameof<T>() + " with " + nameof<U>()
+        + ": float precision is insufficient for the integer type's range."
+        + " Cast both values to f64 before comparing, e.g. expect(f64(a)).toBeGreaterThan(f64(b))."
+        + " Note: large integer values may lose precision when cast to f64, which could cause false positives."
+      );
+    }
+  }
+
+  // --- Numeric comparisons ---
+  // Booleans flow through here naturally (isInteger<bool>() is true in AS).
+
+  if (isInteger<T>() && isInteger<U>()) {
+    // Both signed → promote to i64
+    if (isSigned<T>() && isSigned<U>()) {
+      return applyInequalityOp(i64(actual), i64(compareTo), expectedOperation);
+    }
+
+    // Both unsigned → promote to u64
+    if (!isSigned<T>() && !isSigned<U>()) {
+      return applyInequalityOp(u64(actual), u64(compareTo), expectedOperation);
+    }
+
+    // Mixed sign — more permissive than AS, which rejects these at compile time.
+    // If the signed value is negative, the result is deterministic: signed < unsigned.
+    if (isSigned<T>() && !isSigned<U>()) {
+      if (i64(actual) < 0) {
+        // actual (signed negative) is always less than compareTo (unsigned)
+        return expectedOperation == InequalityOperation.LessThan
+            || expectedOperation == InequalityOperation.LessThanOrEqual;
+      }
+      return applyInequalityOp(u64(actual), u64(compareTo), expectedOperation);
+    } else {
+      // !isSigned<T>() && isSigned<U>()
+      if (i64(compareTo) < 0) {
+        // compareTo (signed negative) is always less than actual (unsigned)
+        return expectedOperation == InequalityOperation.GreaterThan
+            || expectedOperation == InequalityOperation.GreaterThanOrEqual;
+      }
+      return applyInequalityOp(u64(actual), u64(compareTo), expectedOperation);
+    }
+  }
+
+  // Both floats → promote to f64
+  if (isFloat<T>() && isFloat<U>()) {
+    return applyInequalityOp(f64(actual), f64(compareTo), expectedOperation);
+  }
+
+  // Supported float/integer combo (passed precision-loss check above) → promote to f64
+  if ( (isFloat<T>() && isInteger<U>()) || (isInteger<T>() && isFloat<U>()) ) {
+    return applyInequalityOp(f64(actual), f64(compareTo), expectedOperation);
+  }
+
+  // Unsupported type combination (e.g. vectors)
+  throw new Error(
+    "Inequality comparison is not supported for " + nameof<T>() + " and " + nameof<U>() + "."
+  );
+}
+
 export function truthyOrFalsey<T>(actual: T, expected: bool): bool {
   return actual ? expected == true : expected == false;
 }

package/assembly/expect.ts

@@ -1,7 +1,9 @@
 import {
   closeTo,
+  compareInequality,
   equals,
   identical,
+  InequalityOperation,
   isNull,
   nan,
   truthyOrFalsey
@@ -97,11 +99,12 @@ abstract class BaseExpectMatcher<T> {
    * objects, arrays, etc).
    *
    * Cross-type numeric comparisons are allowed where AssemblyScript's own `==` operator
-   * permits them (e.g. `f64` vs `i32`). Combinations where the float type lacks sufficient
-   * mantissa precision for the integer type's range are rejected with an error, mirroring
-   * the AS compiler's behavior (e.g. `f32` vs `i32`, `f64` vs `i64`).
+   * permits them (e.g. `f64` vs `i32`). `toBeCloseTo()` is safer for any comparison
+   * involving a float and allows all numeric types because it can still produce accurate
+   * results in precision-loss casting edge cases.
    *
-   * Don't use `toBe` to compare two floating-point numbers — see `toBeCloseTo` instead.
+   * @throws When comparing float/integer types where the float's mantissa cannot losslessly
+   * represent the integer type's range (e.g. `f32` vs `i32`, `f64` vs `i64`).
    *
    * @example
    * expect(1 + 1).toBe(2);
@@ -122,15 +125,17 @@ abstract class BaseExpectMatcher<T> {
   }
 
   /**
-   * Checks if a value is close to what you expect. Using exact equality with floating point
-   * numbers often doesn't work correctly, because small internal rounding occurs to be able
-   * to represent floats in binary. This rounding means intuitive comparisons will often fail.
+   * Checks if a value is close to what you expect, most useful for comparing floating point 
+   * numbers to any other numbers. Using exact equality with floating point numbers often doesn't 
+   * work correctly, because of internal rounding to represent floats in binary. This rounding 
+   * means intuitive comparisons will often fail, so this matcher checks if they are "close enough"
+   * to be considered equal.
    *
-   * Strings are compared by value equality. Non-numeric, non-string types return false.
+   * Strings are compared by value equality as with `toBe`. Non-numeric, non-string types return false.
    *
-   * @param precision - Specify an integer representing the number of decimal places
-   * that must match for values to be considered close. Defaults to 2 digits, meaning effectively
-   * that values must be within 0.005 of each other.
+   * @param precision - Specify the number of decimal places that must match for values to be 
+   * considered close. Defaults to 2 digits, meaning effectively that values must be within 0.005 of
+   * each other.
    *
    * @example
    * expect(0.1 + 0.2).toBeCloseTo(0.3);
@@ -139,7 +144,109 @@ abstract class BaseExpectMatcher<T> {
   toBeCloseTo<U>(val: U, precision: i32 = 2): void {
     this.assertComparison(closeTo(this.actual, val, precision), this.actual, val, "to be close to", true);
   }
-  
+
+  /**
+   * Checks that a value is greater than the expected value. Supports numeric types
+   * (integers, floats, booleans) and strings (lexicographic comparison).
+   *
+   * Cross-type numeric comparisons are allowed where safe, including cross-sign integers
+   * (more permissive than AS's own `>` operator). Booleans are treated as numeric
+   * (true=1, false=0).
+   *
+   * @throws When comparing float/integer types where the float's mantissa cannot losslessly
+   * represent the integer type's range (e.g. `f32` vs `i32`, `f64` vs `i64`).
+   * @throws When comparing nullable strings where either value is null. Use `toBeNull()`
+   * to check for null values.
+   * @throws When comparing non-string reference types (objects, arrays, etc).
+   *
+   * @example
+   * expect(10).toBeGreaterThan(5);
+   * expect(3.14).toBeGreaterThan(3);
+   * expect("banana").toBeGreaterThan("apple");
+   */
+  toBeGreaterThan<U>(val: U): void {
+    this.assertComparison(
+      compareInequality(this.actual, val, InequalityOperation.GreaterThan),
+      this.actual, val, "to be greater than", true
+    );
+  }
+
+  /**
+   * Checks that a value is greater than or equal to the expected value. Supports numeric
+   * types (integers, floats, booleans) and strings (lexicographic comparison).
+   *
+   * Cross-type numeric comparisons are allowed where safe, including cross-sign integers
+   * (more permissive than AS's own `>=` operator). Booleans are treated as numeric
+   * (true=1, false=0).
+   *
+   * @throws When comparing float/integer types where the float's mantissa cannot losslessly
+   * represent the integer type's range (e.g. `f32` vs `i32`, `f64` vs `i64`).
+   * @throws When comparing nullable strings where either value is null. Use `toBeNull()`
+   * to check for null values.
+   * @throws When comparing non-string reference types (objects, arrays, etc).
+   *
+   * @example
+   * expect(10).toBeGreaterThanOrEqual(10);
+   * expect(3.14).toBeGreaterThanOrEqual(3);
+   */
+  toBeGreaterThanOrEqual<U>(val: U): void {
+    this.assertComparison(
+      compareInequality(this.actual, val, InequalityOperation.GreaterThanOrEqual),
+      this.actual, val, "to be greater than or equal to", true
+    );
+  }
+
+  /**
+   * Checks that a value is less than the expected value. Supports numeric types
+   * (integers, floats, booleans) and strings (lexicographic comparison).
+   *
+   * Cross-type numeric comparisons are allowed where safe, including cross-sign integers
+   * (more permissive than AS's own `<` operator). Booleans are treated as numeric
+   * (true=1, false=0).
+   *
+   * @throws When comparing float/integer types where the float's mantissa cannot losslessly
+   * represent the integer type's range (e.g. `f32` vs `i32`, `f64` vs `i64`).
+   * @throws When comparing nullable strings where either value is null. Use `toBeNull()`
+   * to check for null values.
+   * @throws When comparing non-string reference types (objects, arrays, etc).
+   *
+   * @example
+   * expect(5).toBeLessThan(10);
+   * expect(3).toBeLessThan(3.14);
+   * expect("apple").toBeLessThan("banana");
+   */
+  toBeLessThan<U>(val: U): void {
+    this.assertComparison(
+      compareInequality(this.actual, val, InequalityOperation.LessThan),
+      this.actual, val, "to be less than", true
+    );
+  }
+
+  /**
+   * Checks that a value is less than or equal to the expected value. Supports numeric
+   * types (integers, floats, booleans) and strings (lexicographic comparison).
+   *
+   * Cross-type numeric comparisons are allowed where safe, including cross-sign integers
+   * (more permissive than AS's own `<=` operator). Booleans are treated as numeric
+   * (true=1, false=0).
+   *
+   * @throws When comparing float/integer types where the float's mantissa cannot losslessly
+   * represent the integer type's range (e.g. `f32` vs `i32`, `f64` vs `i64`).
+   * @throws When comparing nullable strings where either value is null. Use `toBeNull()`
+   * to check for null values.
+   * @throws When comparing non-string reference types (objects, arrays, etc).
+   *
+   * @example
+   * expect(5).toBeLessThanOrEqual(5);
+   * expect(3).toBeLessThanOrEqual(3.14);
+   */
+  toBeLessThanOrEqual<U>(val: U): void {
+    this.assertComparison(
+      compareInequality(this.actual, val, InequalityOperation.LessThanOrEqual),
+      this.actual, val, "to be less than or equal to", true
+    );
+  }
+
   /**
    * Checks that two values have the same value (deep equality). Currently supports
    * checking equality of Arrays, Sets, Maps, and nulls. Values inside arrays are
@@ -148,11 +255,13 @@ abstract class BaseExpectMatcher<T> {
    * `toBe()` rules.
    *
    * Like `toBe`, cross-type numeric comparisons follow AssemblyScript's own `==` operator
-   * restrictions. Combinations where the float type lacks sufficient mantissa precision
-   * for the integer type's range are rejected with an error (e.g. `f32` vs `i32`,
-   * `f64` vs `i64`).
+   * restrictions. `toBeCloseTo()` is safer for any comparison involving a float and
+   * accurately handles precision-loss edge cases.
+   *
+   * ⚠️ IMPORTANT: Does not yet support user-defined object deep equality checking.
    *
-   * Note: Does not yet support user-defined object deep equality checking.
+   * @throws When comparing float/integer types where the float's mantissa cannot losslessly
+   * represent the integer type's range (e.g. `f32` vs `i32`, `f64` vs `i64`).
    *
    * @example
    * expect([1, 2, 3]).toEqual([1, 2, 3]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitest-pool-assemblyscript",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "AssemblyScript testing with Vitest - Simple, fast, familiar, AS-native, with full coverage output",
   "author": "Matt Ritter <matthew.d.ritter@gmail.com>",
   "license": "MIT",