@hoge1e3/key-stream

A library for programmatically emulating and dispatching keyboard events — useful for screen keyboards, macro systems, and testing.

Installation

npm install @hoge1e3/key-stream

Overview

@hoge1e3/key-stream synthesizes KeyboardEvent instances and dispatches them without requiring real keyboard input. It automatically tracks the state of modifier keys (Shift / Ctrl / Alt / Meta) and reflects them in every emitted event.

API

push(arg)

Fires a key down or up event.

push({ type: "down" | "up", key?: string, code?: string, keyCode?: number })

• type — "down" to press, "up" to release.
• key / code / keyCode — specify any one to identify the key. For keys not in the built-in table, provide all three fields to define a custom key.

import { push } from "@hoge1e3/key-stream";

// Press Shift + A
push({ type: "down", key: "Shift" });
push({ type: "down", key: "A" });
push({ type: "up",   key: "A" });
push({ type: "up",   key: "Shift" });

// Identify by keyCode
push({ type: "down", keyCode: 13 }); // Enter

addEventListener(...)

Listen for key events. Accepts the same signature as EventTarget.addEventListener.

import { addEventListener } from "@hoge1e3/key-stream";

addEventListener("down", (e) => {
  console.log(e.key, e.shiftKey, e.ctrlKey);
});
addEventListener("up", (e) => { /* ... */ });

modifierState

An object reflecting the current state of all modifier keys. Updated automatically by push() whenever a modifier key is pressed or released.

modifierState: {
  shiftKey: boolean | undefined;
  ctrlKey:  boolean | undefined;
  altKey:   boolean | undefined;
  metaKey:  boolean | undefined;
}

sync(to)

Brings the current modifierState in line with the target state by automatically firing the necessary down / up events.

import { sync } from "@hoge1e3/key-stream";

sync({ ctrlKey: true });                   // press Ctrl
sync({ ctrlKey: false, shiftKey: true });  // release Ctrl, press Shift

modifierStateToInt(e?)

Converts a modifier state object to an integer bitmask. Defaults to the current modifierState when called with no argument.

| Bit | Key | |:---:|-------| | 1 | Ctrl | | 2 | Alt | | 4 | Shift | | 8 | Meta |

import { modifierStateToInt } from "@hoge1e3/key-stream";

// Ctrl + Shift held → 5 (= 1 | 4)
const flags = modifierStateToInt();

setTarget(eventTarget)

Redirects event dispatching to a custom EventTarget. The default target is an internal instance created by the library.

import { setTarget } from "@hoge1e3/key-stream";

const myTarget = new EventTarget();
setTarget(myTarget);

myTarget.addEventListener("down", (e) => { /* ... */ });

Supported Keys (excerpt)

The library ships with a built-in keymap covering a Japanese JIS keyboard layout, including function keys, arrows, modifiers, alphanumerics, and symbols. Each key can be addressed by key, code, or keyCode.

| key | code | keyCode | |------------|----------------|----------| | Escape | Escape | 27 | | Enter | Enter | 13 | | Backspace | Backspace | 8 | | Tab | Tab | 9 | | Shift | ShiftLeft | 16 | | Control | ControlLeft | 17 | | Alt | AltLeft | 18 | | Meta | MetaLeft | 91 | | ArrowUp | ArrowUp | 38 | | ArrowDown | ArrowDown | 40 | | ArrowLeft | ArrowLeft | 37 | | ArrowRight | ArrowRight | 39 | | F1 – F12 | F1 – F12 | 112–123 | | a – z | KeyA – KeyZ | 65–90 | | 0 – 9 | Digit0–Digit9 | 48–57 |

License

MIT Lincense.