@bgpworks/hid-barcode-scanner

A TypeScript library for handling HID barcode scanners in web applications.

Disclaimer

Important: This library is developed for internal use at BGPworks and may not be suitable for general use cases. It is subject to significant changes in the future without adherence to semantic versioning.

Features

• Detect and process input from HID barcode scanners
• Normalize key events across different browsers and devices
• Handle special sequences like GS (Group Separator) symbols
• Support for uppercase, lowercase, and special characters recognition
• Emit events for scan start, completion, and stop
• Configurable timeout for barcode buffer clearing
• Customizable key event observation

Installation

npm install @bgpworks/hid-barcode-scanner

Basic Usage

import { BarcodeScanner } from '@bgpworks/hid-barcode-scanner';

// Create a scanner instance with default settings
const scanner = new BarcodeScanner({
  clearTimeout: 500, // Time in ms to clear the barcode buffer (default: 500)
});

// Add event listeners
scanner.addEventListener('scanStart', () => {
  console.log('Barcode scanning started');
});

scanner.addEventListener('scanComplete', (event) => {
  console.log('Scanned barcode:', event.detail.barcode);
});

scanner.addEventListener('scanStop', () => {
  console.log('Barcode scanning stopped');
});

// Start scan mode
scanner.startScanMode();

// To stop scan mode
// scanner.stopScanMode();

API Reference

BarcodeScanner

The main class for handling barcode scanner input.

Constructor Options

• keyEventObserver - Custom key event observer (optional)
• clearTimeout - Time in ms to clear the barcode buffer (default: 500)
• gsSymbol - Custom Group Separator symbol (optional)

Methods

• startScanMode() - Begin capturing keyboard input as barcode data
• stopScanMode() - Stop capturing keyboard input
• addEventListener(event, callback) - Add event listener
• removeEventListener(event, callback) - Remove event listener

Events

• scanStart - Fired when scan mode begins
• scanComplete - Fired when a complete barcode is received
• scanStop - Fired when scan mode ends

KeyEventObserver

An abstract class for observing key events from different sources. The library includes:

• DocumentKeyEventObserver - Default observer that captures key events from the document
• MockKeyEventObserver - Observer for testing that allows simulating key events

Creating a Custom KeyEventObserver

To implement your own KeyEventObserver, you can use the DocumentKeyEventObserver as a reference:

import KeyEventObserver from './key_event_observer';
import NormalizedKeyEvent from './normalized_key_event';

class DocumentKeyEventObserver extends KeyEventObserver {
  private nativeListenerMap = new WeakMap<
    (event: NormalizedKeyEvent) => void,
    (event: KeyboardEvent) => void
  >();

  addEventListeners(listener: (event: NormalizedKeyEvent) => void): void {
    if (!this.nativeListenerMap.has(listener)) {
      this.nativeListenerMap.set(listener, (event) => {
        // Optionally filter events based on your requirements
        if (
          event.target instanceof HTMLElement &&
          (event.target.tagName === 'INPUT' ||
            event.target.tagName === 'TEXTAREA')
        ) {
          return;
        }

        listener(NormalizedKeyEvent.fromEvent(event));
      });
    }

    const nativeListener = this.nativeListenerMap.get(listener)!;

    // Attach to your event source here
    document.addEventListener('keydown', nativeListener);
  }

  removeEventListeners(listener: (event: NormalizedKeyEvent) => void): void {
    const nativeListener = this.nativeListenerMap.get(listener);

    if (!nativeListener) {
      return;
    }

    // Clean up your event listener
    document.removeEventListener('keydown', nativeListener);
  }
}

When implementing your own KeyEventObserver, make sure to:

1. Extend the abstract KeyEventObserver class
2. Implement addEventListeners and removeEventListeners methods
3. Convert your input events to NormalizedKeyEvent instances
4. Maintain a mapping between your listeners and native handlers if needed

NormalizedKeyEvent

A class that normalizes keyboard events across different browsers and platforms.

Properties

• code - Standard keyboard event code (e.g., 'KeyA', 'Digit1')
• value - The character value for the key (e.g., 'a', '1')
• shiftKey - Whether the Shift key was pressed
• ctrlKey - Whether the Ctrl key was pressed
• altKey - Whether the Alt key was pressed

License

MIT