stenoky.js

A small, TypeScript-first JavaScript library that translates steno notation into human-readable language (English, German, and others) using an AST-based parsing architecture from the very beginning.

Vision

Stenoky treats steno not as a flat string-replacement problem, but as a structured language.

All input is parsed into an Abstract Syntax Tree (AST) first, enabling:

• Clean separation of parsing and translation
• Multiple languages and steno theories
• Future extensions (linting, transforms, reverse translation)
• Predictable, testable behavior

Installation

npm install stenoky

Or with yarn:

yarn add stenoky

Or with pnpm:

pnpm add stenoky

Quick Start

import { stenoky } from 'stenoky';

const result = stenoky('STKPWHRAOEU', {
  language: 'en',
  theory: 'plover'
});
// "Hello"

Usage

Basic Example

import { stenoky } from 'stenoky';

// Single stroke
stenoky('STKPWHRAOEU');
// "Hello"

// Multiple strokes
stenoky('STKPWHRAOEU/HRO', {
  language: 'en',
  theory: 'plover'
});
// "Hello world"

Mixed Text Support

Stenoky automatically handles mixed text where regular words are preserved and only steno strokes are translated:

// Mixed text with steno strokes
stenoky('Hello STKPWHRAOEU world', {
  language: 'en',
  theory: 'plover'
});
// "Hello hello world"

// Regular text only (preserved as-is)
stenoky('The cat sat', {
  language: 'en',
  theory: 'plover'
});
// "The cat sat"

// Mixed text preserves original casing
stenoky('The STKPWHRAOEU Cat', {
  language: 'en',
  theory: 'plover'
});
// "The hello Cat"

This is particularly useful for OCR-read steno documents where steno notation is interspersed with regular text.

Options

interface StenokyOptions {
  /** Output language */
  language?: "en" | "de" | string;

  /** Steno theory (ruleset) */
  theory?: "plover" | "dks" | string;

  /** Custom dictionary overrides */
  dictionary?: StenoDictionary;

  /** Behavior for unknown strokes */
  unknownStroke?: "keep" | "remove" | "mark";

  /** Output formatting options */
  format?: {
    capitalization?: "none" | "sentence" | "title";
    spacing?: boolean;
  };
}

Custom Dictionary

import { stenoky } from 'stenoky';

const result = stenoky('STKPWHRAOEU', {
  dictionary: {
    'STKPWHRAOEU': 'greetings'
  }
});
// "Greetings"

Unknown Stroke Handling

// Keep unknown strokes
stenoky('UNKNOWN', { unknownStroke: 'keep' });
// "[UNKNOWN]"

// Remove unknown strokes
stenoky('UNKNOWN', { unknownStroke: 'remove' });
// ""

// Mark unknown strokes with replacement character
stenoky('UNKNOWN', { unknownStroke: 'mark' });
// ""

Formatting Options

// Sentence capitalization (default)
stenoky('STKPWHRAOEU/HRO', {
  format: { capitalization: 'sentence' }
});
// "Hello world"

// Title capitalization
stenoky('STKPWHRAOEU/HRO', {
  format: { capitalization: 'title' }
});
// "Hello World"

// No capitalization
stenoky('STKPWHRAOEU/HRO', {
  format: { capitalization: 'none' }
});
// "hello world"

// No spacing
stenoky('STKPWHRAOEU/HRO', {
  format: { spacing: false }
});
// "Helloworld"

Architecture

Stenoky uses an AST-based parsing architecture:

Steno String
   ↓
Tokenizer
   ↓
Parser
   ↓
AST
   ↓
Theory Engine
   ↓
Dictionary Lookup
   ↓
Translator
   ↓
Formatter
   ↓
Human-readable Output

1. Tokenizer

Converts raw input into tokens, handling separators (/, space, newline) and normalizing input.

2. Parser (AST Builder)

Converts tokens into an Abstract Syntax Tree. The AST is language-, theory-, and dictionary-agnostic.

3. Theory Engine

Interprets AST nodes according to a steno theory (e.g., Plover for English, DKS for German). Validates and normalizes strokes.

4. Dictionary Layer

Maps normalized strokes to words or syllables. Supports built-in and user-provided dictionaries with override support.

5. Translator

Walks the AST, translates each stroke node into semantic output tokens, and handles unknown strokes based on configuration.

6. Formatter

Converts semantic tokens into a string, applying spacing, capitalization, and cleanup rules.

Supported Theories

• Plover - English steno theory (default)
• DKS - German steno theory (stub for future implementation)

TypeScript Support

Stenoky is written in TypeScript and provides full type definitions:

import { stenoky, type StenokyOptions, type StenoDictionary } from 'stenoky';

const options: StenokyOptions = {
  language: 'en',
  theory: 'plover',
  format: {
    capitalization: 'sentence'
  }
};

API Reference

stenoky(steno: string, options?: StenokyOptions): string

Translates steno notation to human-readable text.

Parameters:

• steno - Steno notation string to translate
• options - Optional translation options

Returns: Human-readable text output

Example:

const result = stenoky('STKPWHRAOEU', { language: 'en', theory: 'plover' });

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Roadmap

• [ ] Expose AST API (stenoky.parse)
• [ ] Streaming / incremental parsing
• [ ] CLI tool
• [ ] Dictionary tooling
• [ ] Reverse translation (text → steno)
• [ ] Editor / IDE integrations