fix(client-core): return null instead of undefined when query is cancelled by mutex

[igorlukanin]

When multiple queries share the same mutexKey, newer queries invalidate older
ones. Previously, cancelled queries would resolve to undefined because
mutexPromise silently swallowed the MUTEX_ERROR without returning a value.

This caused issues in useCubeQuery where resultSet would unexpectedly reset
to undefined while isLoading remained false.

Changes:

• Add MutexCancelledError class for explicit mutex cancellation handling
• Update mutexPromise to throw MutexCancelledError instead of swallowing errors
• Catch MutexCancelledError in loadMethod and return null (a valid return type)

Check List

• Tests have been run in packages where changes have been made if available
• Linter has been run for changed code
• Tests for the changes have been added if not covered yet
• Docs have been added / updated if required

Issue Reference this PR resolves

Fixes #10261

Conversation with Claude

claude.txt

[johnhunter]

Thanks for looking into this @igorlukanin - I didn't have a good understanding of the mutex behaviour.

[johnhunter]

Solution makes sense to me. Just the type fallout to resolve.

[Copilot]

Pull request overview

This PR addresses an issue where queries cancelled by mutex operations were resolving to undefined, causing unexpected behavior in components like useCubeQuery. The fix introduces explicit error handling for mutex cancellations and returns null instead.

Key changes:

• Introduces MutexCancelledError class to explicitly represent mutex cancellation events
• Updates mutexPromise function to throw MutexCancelledError instead of silently swallowing errors
• Adds error handling in loadMethod to catch MutexCancelledError and return null

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The promise chain now returns null when MutexCancelledError is caught, but the public method signatures that call loadMethod (e.g., load, sql, meta, dryRun, cubeSql) don't include null in their return types. For example, the load method signature declares Promise<ResultSet<...>> but can now return Promise<ResultSet<...> | null>. This creates a type safety issue where consumers of the API may not handle the null case properly.

Consider updating all method signatures that use loadMethod to reflect that they can return null, or document this behavior explicitly.

Suggested change

	return null;
	// Propagate mutex cancellation as a rejected promise instead of resolving to null,
	// so that the promise's resolved type remains consistent with public method signatures.
	throw error;