feat: use exact matching for PressedKeys

[braden-w]

This PR changes the default behavior of the PressedKeys utility to use exact key matching instead of inclusive matching. This means has("k") will now only return true when ONLY the "k" key is pressed, not when "Cmd+K" is pressed.

Problem

The previous behavior was counterintuitive and didn't align with user expectations or industry best practices:

// Previous behavior - confusing!
// When Cmd+K is pressed:
keys.has("k") // returned true 
keys.has("meta", "k") // also returned true

This made it impossible to distinguish between a single key press and a key combination, leading to unexpected behavior in applications.

Solution Options Considered

Option 1: Add options parameter (backward compatible)

keys.has("k", { exact: true }) // Only "k" alone

Option 2: Add new methods

keys.hasExact("k") // Only "k" alone

Option 3: Change default behavior (breaking change) ✅

Make exact matching the default and add an option for inclusive matching.

Implementation (Option 3 - Simplified)

I implemented Option 3 with a simplified approach - exact matching is now the only behavior:

// New behavior - intuitive!
// When only "k" is pressed:
keys.has("k") // true
keys.has("k", "meta") // false

// When Cmd+K is pressed:
keys.has("k") // false (exact match)
keys.has("k", "meta") // true (exact match)

Changes Made

1. Updated has method to use exact matching only
2. Updated onKeys method to use exact matching only
3. Added comprehensive tests for exact matching behavior
4. Updated documentation with clear examples of exact matching

Breaking Changes

⚠️ This is a breaking change that will affect existing code:

• has("k") will no longer match when modifier keys are also pressed
• onKeys("k", callback) will no longer fire when modifier keys are also pressed

Migration Guide

The previous inclusive behavior can be achieved using keys.all.includes():

// Before (inclusive behavior)
keys.has("k") // true when "k" OR "Cmd+k" pressed

// After - Option 1: Exact matching (new default)
keys.has("k") // true only when "k" alone is pressed

// After - Option 2: Inclusive behavior (use .all.includes())
keys.all.includes("k") // true when "k" is pressed with or without modifiers

This gives users a clear migration path - they can simply replace keys.has("k") with keys.all.includes("k") to maintain the old behavior.

Benefits

1. More intuitive API: Single key checks behave as expected
2. Better distinction: Clear difference between "k" and "Cmd+K"
3. Industry alignment: Matches behavior of popular libraries like Mousetrap
4. Simpler API: One clear behavior without confusing options

Discussion

While I implemented Option 3 due to its superior ergonomics, this decision is open for discussion. The final implementation removes the inclusive option entirely to maintain a simpler, more focused API.

If users need to check whether a key is pressed regardless of modifiers, they can use keys.all.includes("k") directly.

I believe the benefits of the more intuitive API outweigh the breaking change, and the simplified implementation (without the inclusive option) makes the behavior clear and predictable.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 590fdbb

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[huntabyte]

I think this makes a lot of sense. @TGlide since this is your brain child, what do you think?

[github-actions]

built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

Name	Status	Preview	Last Commit
runed	✅ Ready (View Log)	Visit Preview	590fdbb

[TGlide]

Sorry for the huge wait! let me check

[TGlide]

I propose a different solution. A mix of 1 and something else.

const keys = new PressedKeys({ exact: true })
// When only "k" is pressed:
keys.has("k") // true
keys.has("k", "meta") // false

// When Cmd+K is pressed:
keys.has("k") // false (exact match)
keys.has("k", "meta") // true (exact match)


// Or... Old behaviour
const keys = new PressedKeys()
// When only "k" is pressed:
keys.has("k") // true
keys.has("k", "meta") // false

// When Cmd+K is pressed:
keys.has("k") // true
keys.has("k", { exact: true }) // true
keys.has("k", "meta") // true (exact match)

I do find it more intuitive that keys.has("k") represents that k is pressed no matter what. But I can see the value for exact matching!

[JoBurgard]

For me a version of Option 2 makes the most sense.
I suspect that when creating hotkeys for an app, exact and non-exact matching are both useful.
Sometimes hotkey actions build on each other (additive).

Having two functions makes them equally accessible.

const keys = new PressedKeys()

if (keys.matchOne("ArrowDown", "j")) {
  // Cursor down
}

if (keys.matchOne("ArrowUp", "k")) {
  // Cursor up
}

if (keys.match("Control", "z")) {
  // Undo
}

if (keys.has("w") {
  let speedZ = 1;
  if (keys.has("Shift") {
    // sneak
    speedZ = 0.5;
  }
  // move forward
}

Maybe the version with const keys = new PressedKeys({ exact: true }) would be hard to reason about when not seeing this part of the code and the rest says keys.has(...). It would be easy to mistake it for the non-exact version of keys.has().

// Edit: improved examples

[TGlide]

I wouldn't mind option 2 either, tbh!

[huntabyte]

100% agree the current behavior is counterintuitive. However, I'd ALSO like to propose a variation of Option 2 that I think gives us the best of all worlds:

keys.hasAny("k") // true if k is pressed (with or without modifiers)
keys.hasExact("k") // true only if k alone is pressed
keys.hasExact("meta", "z") // true only if cmd+z is pressed
keys.hasOne("j", "ArrowDown") // true if ANY of these keys are pressed

I feel comfortable breaking keys.has because it is not intuitive at all how it works and everyone will thank themselves for updating now. You shouldn't need to look at comments or docs to understand the behavior.

When someone reads keys.hasExact("k") six months from now, the intent is immediately clear without needing to remember any options or check docs. Each method has a clear, single responsibility.

Explicit > implicit in this case.

[braden-w]

@huntabyte +1, really like the explicitness of hasAny and hasExact!

[huntabyte]

Now that I think more about it, we'd probably also need like hasCombination(['ctrl', 'z'], ['meta', 'z']) ?

[braden-w]

Wouldn't that be covered by hasExact('ctrl', 'z') || hasExact('meta', 'z')? Although from a developer experience perspective, it might be nice to have hasCombination.

Also, was wondering if we could consider the semantics being keys.hasExact(["meta", "z"]) instead of keys.hasExact("meta", "z"). I feel like one parameter in the function that is explictly an array rather than spread would also be more explicit.

[TGlide]

Explicit > implicit in this case.

Agreed!

Now that I think more about it, we'd probably also need like hasCombination(['ctrl', 'z'], ['meta', 'z']) ?

Not sure to be honest. As @braden-w said, a || seems enough, no? Also what if you wanted the behaviour of hasAny(...) || hasExact(...)?

I feel like one parameter in the function that is explictly an array rather than spread would also be more explicit.

Agreed!

[Hema2-official]

@TGlide can we finalize @huntabyte's last proposal?
I assume the original changes are obsolete, should I implement the new version and open a new PR?
I'd really like these features.

[Hema2-official]

After further thought, my opinion is that in the aforementioned proposal, hasOne makes hasAny redundant.
For example:

hasAny('k') === hasOne('k') // always true

Also, while I agree with hasExact being a completely clear name, hasOne was explained with the emphasized word "any," which is inconveniently the distinguishing part of the third function's name, hasAny.

keys.hasOne("j", "ArrowDown") // true if ANY of these keys are pressed

This (at least for me) is a little confusing trying to tell the two apart.

My proposal

Let's just have a hasAny method with the functionality of the previous hasOne. This would make it clearer that the function matches any of the supplied keys, in any circumstance.
As for hasExact, I don't have any changes in mind.

Signatures:

// matches when any of the specified keys is amongst the pressed keys
hasAny(...keys: string[]): boolean {}

// needs an array of keys, matches when the set of pressed keys equals to the set of specified keys
hasExact(keys: string[]): boolean {}

Examples:

When Ctrl+Z is pressed:

hasAny('z') // true
hasAny('z', 'r', 'u', 'n', 'e', 'd') // true
hasExact(['z']) // false
hasExact(['ctrl', 'z']) // true

When Shift+W+Space is pressed (e.g. jumping while sneaking in a video game):

hasExact(['shift', 'w']) // false
hasAny('shift') && hasAny('w') // true
hasAny('space') // true

About onKeys

I would get rid of it and supply two new methods, corresponding to the changes above.
For names, probably onExactKeys and onAnyOf would be best.

Thoughts?

[TGlide]

@Hema2-official I like your suggestions, only thing I'd like to discuss is onKeys.

With the new API, pressed keys would be quite flexible. If we need some stricter combinations, e.g. keys.hasAny('meta', 'alt') && keys.hasExact('k') is possible.

But how would we check for that in onKeys? Splitting it into 2 methods won't solve the problem either, unfortunately.

option 1

We could keep the function but make it accept a getter for a condition. Pros: its simple. Cons: any condition is valid, seems a bit eh

---

option 2

We could change the whole API into a schema like validator.
e.g. PressedKeys.any('meta', 'alt') and PressedKeys.exact('k') which are validators.
Then:

const keys = new PressedKeys()
const schema = PressedKeys.combine([
	PressedKeys.any('meta', 'alt'),
	PressedKeys.exact('k')
])

const valid = keys.validate(schema)

Which would make onKeys easy to handle: onKeys(schema, () => {}). Also makes it re-usable
Cons: makes things a bit more complicated.

---

option 3

We accept combinations inside onKeys?

	onKeys([ { type: 'exact', keys: [ 'k' ] },  /*...*/ ], () => {})

Pros: simple
Cons: not reusable

pinging @huntabyte for thoughts

[Hema2-official]

Yeah, that's right...

...though, the current implementation for onKeys looks like this:

onKeys(keys: string | string[], callback: () => void) {
	this.#subscribe?.();

	const keysToMonitor = Array.isArray(keys) ? keys : [keys];

	watch(
		() => this.all,
		() => {
			if (this.has(...keysToMonitor)) {
				callback();
			}
		}
	);
}

Now, hear me out on this:

option 1

We could keep the function but make it accept a getter for a condition. Pros: its simple. Cons: any condition is valid, seems a bit eh

I think the cons might be the solution. This option would essentially just be a wrapper for watch. So then why bother? The following piece of code literally achieves the same function:

$effect(() => {
	if (keys.hasAny('j') && keys.hasAny('k')) {
		console.log("j and k both pressed");
	}
});

Holding the keys down also works, it spams the calls to console.log:

(TL;DR)

Instead of overcomplicating those functions, we could simply provide examples on how to use hasAny and hasExact logic with $effect or watch.

[TGlide]

$effect is generally not recommended, I actually think we should change how we use it internally and just call it inside the document event listener instead

[Hema2-official]

What do you think of this?

keys.onEvent(() => {
	if (keys.hasAny('j') && keys.hasAny('k')) {
		console.log("j and k both pressed");
	}
});

Implementation:

onEvent(callback: () => void) {
	this.#listeners.push(callback);
}

Each function in #listeners is run when a window event we're subscribed to fires (right next to update()). This solves the problem you mentioned by being independent from Svelte reactivity, and adds a little extensibility.

[TGlide]

What do you think of this?

keys.onEvent(() => {
	if (keys.hasAny('j') && keys.hasAny('k')) {
		console.log("j and k both pressed");
	}
});

Implementation:

onEvent(callback: () => void) {
	this.#listeners.push(callback);
}

Each function in #listeners is run when a window event we're subscribed to fires (right next to update()). This solves the problem you mentioned by being independent from Svelte reactivity, and adds a little extensibility.

tbh I'm not the biggest fan, as its just a fancy on(window, 'click') wrapper with no extra functionality

[Hema2-official]

tbh I'm not the biggest fan, as its just a fancy on(window, 'click') wrapper with no extra functionality

Well, for one, it ensures that only events that modify the pressed keys trigger the callback.
It's also really convenient to set up.