npm package: @hoge1e3/key-stream
Description: Emulate dispatching KeyEvent (from something like screen keyboard).
Latest version: 1.0.0

# @hoge1e3/key-stream

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

## Installation

```bash
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.

```ts
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.

```js
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`.

```js
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.

```ts
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.

```js
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  |

```js
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.

```js
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.