feat: implement deep keys assertions for Maps/Sets

Add deep equality key comparison for Maps and Sets with object keys.
Implements anyDeepKeysFunc, allDeepKeysFunc, and six assert methods
(hasAnyDeepKeys, hasAllDeepKeys, and their negations).

Addresses Chai v5.x compatibility for deep keys operations.

Author: nev21

.github/copilot-instructions.md

@@ -98,6 +98,13 @@ grunt lint lint-fix            # Lint with auto-fix
 - Use `@nevware21/ts-utils` for cross-platform utilities
 - No non-null assertions (`!` operator) - use proper null checks
 
+### Versioning for New Features
+- **@since tags**: Check `core/package.json` version before adding new features
+- Current version in package.json is the **last published** version
+- Use the **next minor version** for @since tags on new features
+- Example: If package.json shows `0.1.4`, use `@since 0.1.5` for new features
+- This follows semver: new features increment the minor version
+
 ## Testing Patterns
 
 ### Test Structure

core/README.md

@@ -63,6 +63,7 @@ expect({ a: 1 }).to.deep.equal({ a: 1 });
 - **Comparisons** - `above`, `below`, `within`, `atLeast`, `atMost`
 - **Properties** - `property`, `ownProperty`, `deepProperty`, `nestedProperty` with value validation
 - **Collections** - `include`, `keys`, `members` with deep equality and ordered comparison
+- **Deep Keys** - `hasAnyDeepKeys`, `hasAllDeepKeys` for Maps/Sets with object keys using deep equality
 - **Size/Length** - `lengthOf`, `sizeOf` for arrays, strings, maps, sets
 - **Array Operations** - `subsequence`, `endsWith`, `oneOf` matching
 - **Change Tracking** - Monitor value `changes`, `increases`, `decreases` with delta validation

core/src/assert/assertClass.ts

@@ -339,7 +339,15 @@ export function createAssert(): IAssertClass {
         subsequence: { scopeFn: subsequenceFunc, nArgs: 2 },
         notSubsequence: { scopeFn: createExprAdapter("not", subsequenceFunc), nArgs: 2 },
         deepSubsequence: { scopeFn: deepSubsequenceFunc, nArgs: 2 },
-        notDeepSubsequence: { scopeFn: createExprAdapter("not", deepSubsequenceFunc), nArgs: 2 }
+        notDeepSubsequence: { scopeFn: createExprAdapter("not", deepSubsequenceFunc), nArgs: 2 },
+
+        // Deep keys operations
+        hasAnyDeepKeys: { scopeFn: createExprAdapter("has.any.deep.keys"), nArgs: -1 },
+        hasAllDeepKeys: { scopeFn: createExprAdapter("has.all.deep.keys"), nArgs: -1 },
+        notHaveAnyDeepKeys: { scopeFn: createExprAdapter("not.has.any.deep.keys"), nArgs: -1 },
+        doesNotHaveAnyDeepKeys: { alias: "notHaveAnyDeepKeys" },
+        notHaveAllDeepKeys: { scopeFn: createExprAdapter("not.has.all.deep.keys"), nArgs: -1 },
+        doesNotHaveAllDeepKeys: { alias: "notHaveAllDeepKeys" }
     };
 
     addAssertFuncs(assert, assertFuncs);

core/src/assert/funcs/keysFunc.ts

@@ -2,14 +2,15 @@
  * @nevware21/tripwire
  * https://github.com/nevware21/tripwire
  *
- * Copyright (c) 2024-2025 NevWare21 Solutions LLC
+ * Copyright (c) 2024-2026 NevWare21 Solutions LLC
  * Licensed under the MIT license.
  */
 
-import { arrForEach, arrSlice, asString, isArray, isObject, isStrictNullOrUndefined, isString, objGetOwnPropertyDescriptor, objGetOwnPropertySymbols, objKeys } from "@nevware21/ts-utils";
+import { arrForEach, arrFrom, arrSlice, asString, dumpObj, isArray, isObject, isStrictNullOrUndefined, isString, objGetOwnPropertyDescriptor, objGetOwnPropertySymbols, objKeys } from "@nevware21/ts-utils";
 import { IAssertScope } from "../interface/IAssertScope";
 import { KeysFn } from "../interface/funcs/KeysFn";
 import { EMPTY_STRING } from "../internal/const";
+import { _deepEqual } from "./equal";
 
 function _objKeys(value: any): any[] {
     let keys: any[] = [];
@@ -27,16 +28,25 @@ function _objKeys(value: any): any[] {
     return keys;
 }
 
-function _formatKeys(keys: string[]): string {
+function _formatKeys(keys: any[]): string {
     let formattedKeys: string = EMPTY_STRING;
     arrForEach(keys, (key) => {
         if (formattedKeys.length > 0) {
             formattedKeys += ",";
         }
         if (key || isStrictNullOrUndefined(key)) {
-            formattedKeys += asString(key);
+            try {
+                formattedKeys += asString(key);
+            } catch (e) {
+                // Handle objects that can't be converted to string (e.g., null prototype)
+                formattedKeys += dumpObj(key);
+            }
         } else if (!isString(key)) {
-            formattedKeys += asString(key);
+            try {
+                formattedKeys += asString(key);
+            } catch (e) {
+                formattedKeys += dumpObj(key);
+            }
         } else {
             // special case for empty string keys
             formattedKeys += "\"\"";
@@ -55,6 +65,22 @@ function _getValueKeys(scope: IAssertScope, value: any): string[] {
     return theKeys;
 }
 
+function _getValueKeysForMap(value: any): any[] {
+    let theKeys: any[] = [];
+    if (!isStrictNullOrUndefined(value)) {
+        // Check if it's a Map or Set
+        if (value instanceof Map || value instanceof Set) {
+            // For Maps and Sets, use the keys() iterator
+            theKeys = arrFrom(value.keys());
+        } else {
+            // For regular objects, use _objKeys
+            theKeys = _objKeys(value);
+        }
+    }
+
+    return theKeys;
+}
+
 function _getArgKeys(scope: IAssertScope, theArgs: any[]): string[] {
     let theKeys: string[] = theArgs;
     if (theArgs && (isArray(theArgs[0]) || isObject(theArgs[0])) && !isString(theArgs[0])) {
@@ -73,6 +99,17 @@ function _getArgKeys(scope: IAssertScope, theArgs: any[]): string[] {
     return theKeys;
 }
 
+function _getArgKeysForDeep(scope: IAssertScope, theArgs: any[]): any[] {
+    // For deep keys, if a single array argument is provided, unwrap it to get multiple keys
+    // This matches Chai behavior: .keys([a, b, c]) checks for keys a, b, c
+    // Otherwise, treat all arguments as individual keys
+    if (theArgs && theArgs.length === 1 && isArray(theArgs[0])) {
+        return theArgs[0];
+    }
+
+    return theArgs;
+}
+
 export function anyKeysFunc<R>(_scope: IAssertScope): KeysFn<R> {
 
     function _keys(this: IAssertScope, _argKeys: Array<string|number|symbol> | Object | readonly any[]): R {
@@ -133,3 +170,88 @@ export function allKeysFunc<R>(_scope: IAssertScope): KeysFn<R> {
     return _keys;
 }
 
+/**
+ * Creates a KeysFn function that checks if any of the provided keys exist in the value using deep equality comparison.
+ * This is used for deep key matching where keys are compared using deep equality instead of strict equality.
+ * @param _scope - The assert scope.
+ * @returns A KeysFn function.
+ */
+export function anyDeepKeysFunc<R>(_scope: IAssertScope): KeysFn<R> {
+
+    function _keys(this: IAssertScope, _argKeys: Array<string|number|symbol> | Object | readonly any[]): R {
+        let scope = this;
+        let context = scope.context;
+        let args = arrSlice(arguments);
+        let expectedKeys = _getArgKeysForDeep(scope, args);
+        let valueKeys = _getValueKeysForMap(context.value);
+
+        if (expectedKeys.length === 0) {
+            scope.context.set("expectedKeys", expectedKeys);
+            scope.fatal("expected at least one key to be provided {expectedKeys}");
+        }
+
+        let found = false;
+        arrForEach(expectedKeys, (expKey) => {
+            arrForEach(valueKeys, (valKey) => {
+                if (_deepEqual(valKey, expKey)) {
+                    // Found at least one key using deep equality
+                    found = true;
+                    return -1;
+                }
+            });
+
+            if (found) {
+                return -1;
+            }
+        });
+
+        context.eval(found, `expected any deep key: [${_formatKeys(expectedKeys)}], found: [${_formatKeys(valueKeys)}] (${valueKeys.length} keys)`);
+
+        return scope.that;
+    }
+
+    return _keys;
+}
+
+/**
+ * Creates a KeysFn function that checks if all of the provided keys exist in the value using deep equality comparison.
+ * This is used for deep key matching where keys are compared using deep equality instead of strict equality.
+ * @param _scope - The assert scope.
+ * @returns A KeysFn function.
+ */
+export function allDeepKeysFunc<R>(_scope: IAssertScope): KeysFn<R> {
+
+    function _keys(this: IAssertScope, argKeys: string[] | Object | readonly any[]): R {
+        let scope = this;
+        let context = scope.context;
+        let args = arrSlice(arguments);
+        let theKeys = _getArgKeysForDeep(scope, args);
+        let valueKeys = _getValueKeysForMap(context.value);
+
+        if (theKeys.length === 0) {
+            scope.context.set("theKeys", theKeys);
+            scope.fatal("expected at least one key to be provided {theKeys}");
+        }
+
+        let missingKeys: string[] = [];
+        arrForEach(theKeys, (expKey) => {
+            let found = false;
+            arrForEach(valueKeys, (valKey) => {
+                if (_deepEqual(valKey, expKey)) {
+                    found = true;
+                    return -1;
+                }
+            });
+
+            if (!found) {
+                missingKeys.push(expKey);
+            }
+        });
+
+        context.eval(missingKeys.length === 0, `expected all deep keys: [${_formatKeys(theKeys)}], missing: [${_formatKeys(missingKeys)}], found: [${_formatKeys(valueKeys)}]`);
+
+        return scope.that;
+    }
+
+    return _keys;
+}

core/src/assert/interface/IAssertClass.ts

@@ -3354,6 +3354,147 @@ export interface IAssertClass<AssertInst extends IAssertInst = IAssertInst> {
      * ```
      */
     decreasesButNotBy<T>(fn: () => void, target: T, prop: keyof T, delta: number, initMsg?: MsgSource): AssertInst;
+
+    /**
+     * Asserts that the target has any of the specified keys using deep equality comparison.
+     * This method checks if at least one of the given keys exists in the target using deep equality
+     * for key comparison. Particularly useful for Maps and Sets where keys may be objects.
+     *
+     * @param target - The object, Map, or Set to check for keys.
+     * @param keys - The keys to search for (can be individual arguments or an array of keys).
+     * @param initMsg - The message to display if the assertion fails.
+     * @asserts That the `target` has at least one of the specified keys and throws {@link AssertionFailure} if it does not.
+     * @since 0.1.5
+     * @example
+     * ```typescript
+     * const obj = { greeting: "hello", subject: "friend" };
+     * assert.hasAnyDeepKeys(obj, "greeting", "message");  // Passes - has "greeting"
+     * assert.hasAnyDeepKeys(obj, ["greeting", "message"]);  // Passes - has "greeting"
+     *
+     * const map = new Map([[{ id: 1 }, "value1"], [{ id: 2 }, "value2"]]);
+     * assert.hasAnyDeepKeys(map, { id: 1 });  // Passes - deep key match
+     * assert.hasAnyDeepKeys(map, { id: 1 }, { id: 3 });  // Passes - has { id: 1 }
+     * assert.hasAnyDeepKeys(obj, "unknown", "missing");  // Throws AssertionFailure
+     * ```
+     */
+    hasAnyDeepKeys(target: any, ...keys: any[]): AssertInst;
+
+    /**
+     * Asserts that the target has all of the specified keys using deep equality comparison.
+     * This method checks if all of the given keys exist in the target using deep equality
+     * for key comparison. Particularly useful for Maps and Sets where keys may be objects.
+     *
+     * @param target - The object, Map, or Set to check for keys.
+     * @param keys - The keys to search for (can be individual arguments or an array of keys).
+     * @param initMsg - The message to display if the assertion fails.
+     * @asserts That the `target` has all of the specified keys and throws {@link AssertionFailure} if it does not.
+     * @since 0.1.5
+     * @example
+     * ```typescript
+     * const obj = { greeting: "hello", subject: "friend", message: "darkness" };
+     * assert.hasAllDeepKeys(obj, "greeting", "subject");  // Passes - has both keys
+     * assert.hasAllDeepKeys(obj, ["greeting", "subject"]);  // Passes - has both keys
+     *
+     * const map = new Map([[{ id: 1 }, "value1"], [{ id: 2 }, "value2"]]);
+     * assert.hasAllDeepKeys(map, { id: 1 }, { id: 2 });  // Passes - has both keys
+     * assert.hasAllDeepKeys(obj, "greeting", "unknown");  // Throws AssertionFailure - missing "unknown"
+     * ```
+     */
+    hasAllDeepKeys(target: any, ...keys: any[]): AssertInst;
+
+    /**
+     * Asserts that the target does NOT have any of the specified keys using deep equality comparison.
+     * This method checks that none of the given keys exist in the target using deep equality
+     * for key comparison. This is the inverse of {@link hasAnyDeepKeys}.
+     *
+     * @param target - The object, Map, or Set to check for keys.
+     * @param keys - The keys to search for (can be individual arguments or an array of keys).
+     * @param initMsg - The message to display if the assertion fails.
+     * @asserts That the `target` does not have any of the specified keys and throws {@link AssertionFailure} if it does.
+     * @since 0.1.5
+     * @example
+     * ```typescript
+     * const obj = { greeting: "hello", subject: "friend" };
+     * assert.notHaveAnyDeepKeys(obj, "unknown", "missing");  // Passes - has neither key
+     * assert.notHaveAnyDeepKeys(obj, ["unknown", "missing"]);  // Passes - has neither key
+     *
+     * const map = new Map([[{ id: 1 }, "value1"]]);
+     * assert.notHaveAnyDeepKeys(map, { id: 3 }, { id: 4 });  // Passes - has neither key
+     * assert.notHaveAnyDeepKeys(obj, "greeting", "unknown");  // Throws AssertionFailure - has "greeting"
+     * ```
+     */
+    notHaveAnyDeepKeys(target: any, ...keys: any[]): AssertInst;
+
+    /**
+     * Asserts that the target does NOT have any of the specified keys using deep equality comparison.
+     * This method checks that none of the given keys exist in the target using deep equality
+     * for key comparison. This is the inverse of {@link hasAnyDeepKeys}.
+     *
+     * @param target - The object, Map, or Set to check for keys.
+     * @param keys - The keys to search for (can be individual arguments or an array of keys).
+     * @param initMsg - The message to display if the assertion fails.
+     * @asserts That the `target` does not have any of the specified keys and throws {@link AssertionFailure} if it does.
+     * @alias notHaveAnyDeepKeys
+     * @since 0.1.5
+     * @example
+     * ```typescript
+     * const obj = { greeting: "hello", subject: "friend" };
+     * assert.doesNotHaveAnyDeepKeys(obj, "unknown", "missing");  // Passes - has neither key
+     * assert.doesNotHaveAnyDeepKeys(obj, ["unknown", "missing"]);  // Passes - has neither key
+     *
+     * const map = new Map([[{ id: 1 }, "value1"]]);
+     * assert.doesNotHaveAnyDeepKeys(map, { id: 3 }, { id: 4 });  // Passes - has neither key
+     * assert.doesNotHaveAnyDeepKeys(obj, "greeting", "unknown");  // Throws AssertionFailure - has "greeting"
+     * ```
+     */
+    doesNotHaveAnyDeepKeys(target: any, ...keys: any[]): AssertInst;
+
+    /**
+     * Asserts that the target does NOT have all of the specified keys using deep equality comparison.
+     * This method checks that at least one of the given keys does not exist in the target using deep equality
+     * for key comparison. This is the inverse of {@link hasAllDeepKeys}.
+     *
+     * @param target - The object, Map, or Set to check for keys.
+     * @param keys - The keys to search for (can be individual arguments or an array of keys).
+     * @param initMsg - The message to display if the assertion fails.
+     * @asserts That the `target` does not have all of the specified keys and throws {@link AssertionFailure} if it does.
+     * @since 0.1.5
+     * @example
+     * ```typescript
+     * const obj = { greeting: "hello", subject: "friend" };
+     * assert.notHaveAllDeepKeys(obj, "greeting", "unknown");  // Passes - missing "unknown"
+     * assert.notHaveAllDeepKeys(obj, ["greeting", "unknown"]);  // Passes - missing "unknown"
+     *
+     * const map = new Map([[{ id: 1 }, "value1"]]);
+     * assert.notHaveAllDeepKeys(map, { id: 1 }, { id: 2 });  // Passes - missing { id: 2 }
+     * assert.notHaveAllDeepKeys(obj, "greeting", "subject");  // Throws AssertionFailure - has both keys
+     * ```
+     */
+    notHaveAllDeepKeys(target: any, ...keys: any[]): AssertInst;
+
+    /**
+     * Asserts that the target does NOT have all of the specified keys using deep equality comparison.
+     * This method checks that at least one of the given keys does not exist in the target using deep equality
+     * for key comparison. This is the inverse of {@link hasAllDeepKeys}.
+     *
+     * @param target - The object, Map, or Set to check for keys.
+     * @param keys - The keys to search for (can be individual arguments or an array of keys).
+     * @param initMsg - The message to display if the assertion fails.
+     * @asserts That the `target` does not have all of the specified keys and throws {@link AssertionFailure} if it does.
+     * @alias notHaveAllDeepKeys
+     * @since 0.1.5
+     * @example
+     * ```typescript
+     * const obj = { greeting: "hello", subject: "friend" };
+     * assert.doesNotHaveAllDeepKeys(obj, "greeting", "unknown");  // Passes - missing "unknown"
+     * assert.doesNotHaveAllDeepKeys(obj, ["greeting", "unknown"]);  // Passes - missing "unknown"
+     *
+     * const map = new Map([[{ id: 1 }, "value1"]]);
+     * assert.doesNotHaveAllDeepKeys(map, { id: 1 }, { id: 2 });  // Passes - missing { id: 2 }
+     * assert.doesNotHaveAllDeepKeys(obj, "greeting", "subject");  // Throws AssertionFailure - has both keys
+     * ```
+     */
+    doesNotHaveAllDeepKeys(target: any, ...keys: any[]): AssertInst;
 }
 
 export type IExtendedAssert<T = any> = IAssertClass<IAssertInst & T> & T;

core/src/assert/interface/ops/IAllOp.ts

@@ -2,7 +2,7 @@
  * @nevware21/tripwire
  * https://github.com/nevware21/tripwire
  *
- * Copyright (c) 2024-2025 NevWare21 Solutions LLC
+ * Copyright (c) 2024-2026 NevWare21 Solutions LLC
  * Licensed under the MIT license.
  */
 
@@ -14,4 +14,14 @@ import { IKeysOp } from "./IKeysOp";
  * @template R - The type of the result of the operation.
  */
 export interface IAllOp<R> extends ValuesFn<R>, IKeysOp<R> {
+    /**
+     * Provides deep equality operations for keys.
+     * @example
+     * ```typescript
+     * const map = new Map();
+     * map.set({ a: 1 }, "value");
+     * expect(map).has.all.deep.keys({ a: 1 });
+     * ```
+     */
+    deep: IKeysOp<R>;
 }