Architecture Idea: Imperative shell, functional core using push-based stream

[nightscape]

Kanata is an amazing piece of work and achieves everything I've ever dreamed of from a keyboard remapper:

• Neo-like layers
• Mouse movements
• Chording (Zippy 🥳)

I would love to contribute more to it, even though at the moment I don't even know what else one could desire. 😉

One thing that might make future development easier is to isolate side effects from the key transformation logic.

In Scala, one design pattern that is often used is the "imperative shell + functional core". For Kanata, this would mean isolating the two main side effects "reading scancodes" and "emitting keyboard / mouse events" into one or two specific classes or modules. Then, all the transformation logic (mapping a scancode to a keycode, grouping multiple keycodes in a chord, etc.) could remain purely functional and side-effect-free (i.e., it would not directly invoke kb.press_key or kb.release_key).

The key transformation logic could be viewed as a push-based stream, where scancodes are pushed into a "source" and processed through a series of transformations before finally arriving at a "sink" that handles the actual side effects (e.g., kb.press_key).

The (very much simplified) resulting code would look something like this:

let keyboard_events = InputHandler::new().into_stream();

let transformed_events = keyboard_events
    .map(scancode_to_keycode)                    // Convert raw scancodes
    .scan(LayerState::default(), handle_layers);  // Handle layer switching

let (key_events, mouse_events) = transformed_events.partition(is_key_event);
let chord_key_events = key_events
    .buffer(Duration::from_millis(50))           // Group potential chord inputs
    .scan(ChordState::default(), detect_chords); // Detect and expand chords, adding backspace events to delete the original keys

let final_key_events = key_events.union(chord_key_events);

final_key_events.subscribe(KeyboardOutputHandler::new()); // Emit final keycodes
mouse_events.subscribe(MouseOutputHandler::new());

Stream operations

The following stream operations would probably be required:

1. Mapping: Transforming one stream element to another (e.g., initial scancode to keycode mapping).
2. Scan/Fold: Passing along some accumulated state with each new element, which would be useful for stateful operations like chording.
3. Filter: Filtering out certain scancodes based on conditions (e.g., ignoring repeated key presses when they shouldn't trigger further actions). partition can be seen as two filters based on a predicate and its negation.
4. Buffering: Accumulating a sequence of events before processing them, which might be useful for chords or multi-key combinations.

Advantages

1. Testability: Only the imperative shell would need simulated input/output, while transformation logic could be tested like any regular function. This makes unit tests faster and more reliable.
2. Separation of Concerns: Isolating side effects makes key mapping logic easier to understand and modify, reducing the cognitive load.
3. Extensibility: Adding new features would be simpler by extending the functional core without dealing with hardware-related side effects.
4. Composability: Stream operations are composable, allowing for new key transformations by combining smaller operations.
5. Error Isolation: Isolating side effects makes it easier to identify the source of bugs—either in the functional transformation or the imperative shell.

Disadvantages

1. Increased Complexity: Streams are a new concept in the codebase and might be unfamiliar to potential contributors.
2. Performance: The abstraction layer for streams would introduce some performance overhead, especially in high-frequency keypress scenarios where low latency is crucial.
3. Debugging: During debugging one would need to step through both the actual transformation logic and the stream library, possibly making it more cumbersome. This would hopefully be somewhat alleviated by less need for debugging through better separation of concerns and easier testability.

Implementation

rxRust is a Rust implementation of ReactiveX and seems to have implemented the required operations.

Alternatively there's a less actively maintained library called pushgen with a Generator trait which looks suitable for the use case and has some of the required stream operations already implemented.
There's nothing like buffer though, or any other time-based operation.

[jtroo]

There are some major components that could be pipeline-ized; for better organization, i.e.

• keyberon+custom actions
• sequences
• zippychord

The core design of the Kanata internals though is that it is a state machine with transitions being key input and 1-ms-ticks. I don't currently envision a way for something like:

let chord_key_events = key_events
    .buffer(Duration::from_millis(50))           // Group potential chord inputs
    .scan(ChordState::default(), detect_chords); // Detect and expand chords, adding backspace events to delete the original keys

to cleanly fit into this model.

Looking specifically at rxRust, my initial thought like it uses an async framework and would have too much overhead compared to the processing loop that currently runs in a single thread today. Looking at both libs, I don't see how the operations within either of rxRust or pushgen can help to implement an action like tap-hold-release that has both a duration as well as an input-interruptable component.

[nightscape]

@jtroo thank you for the explanation!
Maintaining a single thread makes absolute sense 👍
I had seen the state machine in the design docs, but not yet stumbled upon it in the code.
I'll try to familiarize myself more with the code 😃