or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-keypress

Make any Node ReadableStream emit keypress events

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/keypress@0.2.x

To install, run

npx @tessl/cli install tessl/npm-keypress@0.2.0

index.mddocs/

keypress

The keypress module provides functionality to make any Node.js ReadableStream emit "keypress" events. It extracts the internal keypress logic from Node.js core's readline module and extends it with mouse event support, enabling developers to build interactive terminal applications.

Package Information

  • Package Name: keypress
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install keypress

Core Imports

const keypress = require('keypress');

For individual functions:

const { enableMouse, disableMouse } = require('keypress');

Basic Usage

const keypress = require('keypress');

// Make process.stdin emit keypress events
keypress(process.stdin);

// Listen for keypress events
process.stdin.on('keypress', function (ch, key) {
  console.log('Key pressed:', key);
  if (key && key.ctrl && key.name == 'c') {
    process.stdin.pause();
  }
});

// Enable raw mode to capture individual keystrokes
process.stdin.setRawMode(true);
process.stdin.resume();

Capabilities

Stream Enhancement

Enable keypress and mousepress event emission on any readable stream.

/**
 * Make a readable stream emit "keypress" events
 * @param {ReadableStream} stream - A readable stream instance to enhance (e.g. process.stdin)
 * @returns {undefined}
 */
function keypress(stream);

Usage Example:

const keypress = require('keypress');

// Enhance process.stdin
keypress(process.stdin);

// Listen for keypress events
process.stdin.on('keypress', function (ch, key) {
  console.log('Character:', ch);
  console.log('Key object:', key);
});

process.stdin.setRawMode(true);
process.stdin.resume();

Mouse Event Control

Enable and disable mouse event tracking for terminal applications.

/**
 * Enable mousepress events on the input stream
 * @param {WritableStream} stream - A writable stream instance (typically process.stdout)
 * @returns {undefined}
 */
function enableMouse(stream);

/**
 * Disable mousepress events from being sent to the input stream
 * @param {WritableStream} stream - A writable stream instance (typically process.stdout)
 * @returns {undefined}
 */
function disableMouse(stream);

Usage Example:

const keypress = require('keypress');

// Enable keypress events
keypress(process.stdin);

// Enable mouse tracking
keypress.enableMouse(process.stdout);

// Listen for mouse events
process.stdin.on('mousepress', function (mouse) {
  console.log('Mouse event at', mouse.x, mouse.y);
  console.log('Button:', mouse.button);
  if (mouse.release) {
    console.log('Mouse button released');
  }
});

// Cleanup on exit
process.on('exit', function () {
  keypress.disableMouse(process.stdout);
});

process.stdin.setRawMode(true);
process.stdin.resume();

Events

keypress Event

Emitted when a key is pressed after calling the keypress function on a stream.

/**
 * Keypress event handler
 * @param {string|undefined} ch - The character pressed (undefined for special keys)
 * @param {KeyInfo} key - Key information object
 */
stream.on('keypress', function(ch, key) { });

interface KeyInfo {
  /** Key name (e.g., 'a', 'return', 'escape', 'up', 'f1') */
  name: string;
  /** Whether Ctrl key was held */
  ctrl: boolean;
  /** Whether Meta/Alt key was held */
  meta: boolean;
  /** Whether Shift key was held */
  shift: boolean;
  /** Raw escape sequence */
  sequence: string;
  /** ANSI code for function keys */
  code?: string;
}

Key Names:

  • Standard keys: a-z, 0-9
  • Special keys: return, enter, tab, backspace, escape, space
  • Arrow keys: up, down, left, right
  • Function keys: f1-f12
  • Navigation: home, end, pageup, pagedown, insert, delete

mousepress Event

Emitted when mouse events are enabled and a mouse action occurs.

/**
 * Mousepress event handler
 * @param {MouseInfo} mouse - Mouse event information
 */
stream.on('mousepress', function(mouse) { });

interface MouseInfo {
  /** Always 'mouse' */
  name: string;
  /** X coordinate */
  x: number;
  /** Y coordinate */
  y: number;
  /** Mouse button (0=left, 1=middle, 2=right), undefined for release/scroll events */
  button?: number;
  /** Whether Ctrl key was held */
  ctrl: boolean;
  /** Whether Meta/Alt key was held */
  meta: boolean;
  /** Whether Shift key was held */
  shift: boolean;
  /** Whether this is a button release event */
  release: boolean;
  /** Scroll direction (1=up, -1=down, 0=none) */
  scroll: number;
  /** Raw escape sequence */
  sequence: string;
}

Complete Example

const keypress = require('keypress');

// Make stdin emit keypress events
keypress(process.stdin);

// Enable mouse tracking
keypress.enableMouse(process.stdout);

// Handle keyboard input
process.stdin.on('keypress', function (ch, key) {
  if (key) {
    console.log('Key pressed:', {
      name: key.name,
      char: ch,
      ctrl: key.ctrl,
      meta: key.meta,
      shift: key.shift
    });

    // Exit on Ctrl+C
    if (key.ctrl && key.name === 'c') {
      console.log('Exiting...');
      process.stdin.pause();
    }
  }
});

// Handle mouse input
process.stdin.on('mousepress', function (mouse) {
  console.log('Mouse event:', {
    x: mouse.x,
    y: mouse.y,
    button: mouse.button,
    release: mouse.release,
    scroll: mouse.scroll
  });
});

// Cleanup on exit
process.on('exit', function () {
  keypress.disableMouse(process.stdout);
});

// Start listening
process.stdin.setRawMode(true);
process.stdin.resume();

console.log('Press any key or move the mouse. Press Ctrl+C to exit.');