braille-codec 0.0.1-rc1

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "braille-codec",
+  "version": "0.0.1-rc1",
+  "description": "Braille encoding and decoding library",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "rollup -c",
+    "test": "vitest --run",
+    "lint": "eslint . --ext .ts",
+    "lint:fix": "eslint . --ext .ts --fix"
+  },
+  "bin": {
+    "braille-decode": "bin/braille-decode"
+  },
+  "keywords": [
+    "braille",
+    "BRL"
+  ],
+  "author": "Joseph Lee <joseph@jc-lab.net>",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@rollup/plugin-typescript": "^11.1.6",
+    "@types/node": "^20.14.10",
+    "@typescript-eslint/eslint-plugin": "^7.16.0",
+    "@typescript-eslint/parser": "^7.16.0",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.1.3",
+    "prettier": "^3.3.2",
+    "rollup": "^4.18.0",
+    "rollup-plugin-dts": "^6.1.1",
+    "tslib": "^2.6.3",
+    "typescript": "^5.5.3",
+    "vitest": "^1.6.0"
+  }
+}

package/rollup.config.js

@@ -0,0 +1,18 @@
+import typescript from '@rollup/plugin-typescript';
+import dts from 'rollup-plugin-dts';
+
+export default [
+  {
+    input: 'src/index.ts',
+    output: [
+      { file: 'dist/index.cjs', format: 'cjs' },
+      { file: 'dist/index.mjs', format: 'es' },
+    ],
+    plugins: [typescript()],
+  },
+  {
+    input: 'src/index.ts',
+    output: [{ file: 'dist/index.d.ts', format: 'es' }],
+    plugins: [dts()],
+  },
+];

package/src/decoder/constants/char_english.ts

@@ -0,0 +1,30 @@
+import { decodeUnicode } from './utils';
+
+export const ENGLISH_ALPHABET: Record<number, string> = {
+  [decodeUnicode('⠁')]: 'a',
+  [decodeUnicode('⠃')]: 'b',
+  [decodeUnicode('⠉')]: 'c',
+  [decodeUnicode('⠙')]: 'd',
+  [decodeUnicode('⠑')]: 'e',
+  [decodeUnicode('⠋')]: 'f',
+  [decodeUnicode('⠛')]: 'g',
+  [decodeUnicode('⠓')]: 'h',
+  [decodeUnicode('⠊')]: 'i',
+  [decodeUnicode('⠚')]: 'j',
+  [decodeUnicode('⠅')]: 'k',
+  [decodeUnicode('⠇')]: 'l',
+  [decodeUnicode('⠍')]: 'm',
+  [decodeUnicode('⠝')]: 'n',
+  [decodeUnicode('⠕')]: 'o',
+  [decodeUnicode('⠏')]: 'p',
+  [decodeUnicode('⠟')]: 'q',
+  [decodeUnicode('⠗')]: 'r',
+  [decodeUnicode('⠎')]: 's',
+  [decodeUnicode('⠞')]: 't',
+  [decodeUnicode('⠥')]: 'u',
+  [decodeUnicode('⠧')]: 'v',
+  [decodeUnicode('⠺')]: 'w',
+  [decodeUnicode('⠭')]: 'x',
+  [decodeUnicode('⠽')]: 'y',
+  [decodeUnicode('⠵')]: 'z',
+};

package/src/decoder/constants/char_shortcut.ts

@@ -0,0 +1,33 @@
+import { decodeUnicode } from './utils';
+
+export const KOREAN_SHORTCUTS: Record<string, string> = {
+  [`${decodeUnicode('⠫')}`]: '가',
+  [`${decodeUnicode('⠉')}`]: '나',
+  [`${decodeUnicode('⠊')}`]: '다',
+  [`${decodeUnicode('⠑')}`]: '마',
+  [`${decodeUnicode('⠘')}`]: '바',
+  [`${decodeUnicode('⠇')}`]: '사',
+  [`${decodeUnicode('⠨')}`]: '자',
+  [`${decodeUnicode('⠋')}`]: '카',
+  [`${decodeUnicode('⠓')}`]: '타',
+  [`${decodeUnicode('⠙')}`]: '파',
+  [`${decodeUnicode('⠚')}`]: '하',
+  [`${decodeUnicode('⠸')},${decodeUnicode('⠎')}`]: '것',
+  [`${decodeUnicode('⠹')}`]: '억',
+  [`${decodeUnicode('⠾')}`]: '언',
+  [`${decodeUnicode('⠞')}`]: '얼',
+  [`${decodeUnicode('⠡')}`]: '연',
+  [`${decodeUnicode('⠳')}`]: '열',
+  [`${decodeUnicode('⠻')}`]: '영',
+  [`${decodeUnicode('⠭')}`]: '옥',
+  [`${decodeUnicode('⠷')}`]: '온',
+  [`${decodeUnicode('⠿')}`]: '옹',
+  [`${decodeUnicode('⠛')}`]: '운',
+  [`${decodeUnicode('⠯')}`]: '울',
+  [`${decodeUnicode('⠵')}`]: '은',
+  [`${decodeUnicode('⠮')}`]: '을',
+  [`${decodeUnicode('⠟')}`]: '인',
+  [`${decodeUnicode('⠠')},${decodeUnicode('⠻')}`]: '성',
+  [`${decodeUnicode('⠨')},${decodeUnicode('⠻')}`]: '정',
+  [`${decodeUnicode('⠰')},${decodeUnicode('⠻')}`]: '청',
+};

package/src/decoder/constants/choseong.ts

@@ -0,0 +1,18 @@
+import { decodeUnicode } from './utils';
+
+export const KOREAN_CHOSEONG: Record<number, string> = {
+  [decodeUnicode('⠈')]: 'ㄱ',
+  [decodeUnicode('⠉')]: 'ㄴ',
+  [decodeUnicode('⠊')]: 'ㄷ',
+  [decodeUnicode('⠐')]: 'ㄹ',
+  [decodeUnicode('⠑')]: 'ㅁ',
+  [decodeUnicode('⠘')]: 'ㅂ',
+  [decodeUnicode('⠠')]: 'ㅅ',
+  // [decodeUnicode('')]: 'ㅇ', // skip ㅇ of choseong
+  [decodeUnicode('⠨')]: 'ㅈ',
+  [decodeUnicode('⠰')]: 'ㅊ',
+  [decodeUnicode('⠋')]: 'ㅋ',
+  [decodeUnicode('⠓')]: 'ㅌ',
+  [decodeUnicode('⠙')]: 'ㅍ',
+  [decodeUnicode('⠚')]: 'ㅎ',
+};

package/src/decoder/constants/index.ts

@@ -0,0 +1,110 @@
+export * from './utils';
+export * from './choseong';
+export * from './jungsong';
+export * from './jongseong';
+export * from './char_shortcut';
+export * from './char_english';
+export * from './number';
+export * from './symbol';
+export * from './indicators';
+
+import { decodeUnicode } from './utils'
+
+// ASCII Braille to Unicode mapping (Standard North American Braille ASCII)
+// Reference: https://en.wikipedia.org/wiki/Braille_ASCII
+export const ASCII_BRAILLE_MAP: Record<string, number> = {
+  ' ': decodeUnicode('⠀'),
+  '!': decodeUnicode('⠮'),
+  '"': decodeUnicode('⠐'),
+  '#': decodeUnicode('⠼'),
+  '$': decodeUnicode('⠫'),
+  '%': decodeUnicode('⠩'),
+  '&': decodeUnicode('⠯'),
+  '\'': decodeUnicode('⠄'),
+  '(': decodeUnicode('⠷'),
+  ')': decodeUnicode('⠾'),
+  '*': decodeUnicode('⠡'),
+  '+': decodeUnicode('⠬'),
+  ',': decodeUnicode('⠠'),
+  '-': decodeUnicode('⠤'),
+  '.': decodeUnicode('⠨'),
+  '/': decodeUnicode('⠌'),
+  '0': decodeUnicode('⠴'),
+  '1': decodeUnicode('⠂'),
+  '2': decodeUnicode('⠆'),
+  '3': decodeUnicode('⠒'),
+  '4': decodeUnicode('⠲'),
+  '5': decodeUnicode('⠢'),
+  '6': decodeUnicode('⠖'),
+  '7': decodeUnicode('⠶'),
+  '8': decodeUnicode('⠦'),
+  '9': decodeUnicode('⠔'),
+  ':': decodeUnicode('⠱'),
+  ';': decodeUnicode('⠰'),
+  '<': decodeUnicode('⠣'),
+  '=': decodeUnicode('⠿'),
+  '>': decodeUnicode('⠜'),
+  '?': decodeUnicode('⠹'),
+  '@': decodeUnicode('⠈'),
+  'A': decodeUnicode('⠁'),
+  'B': decodeUnicode('⠃'),
+  'C': decodeUnicode('⠉'),
+  'D': decodeUnicode('⠙'),
+  'E': decodeUnicode('⠑'),
+  'F': decodeUnicode('⠋'),
+  'G': decodeUnicode('⠛'),
+  'H': decodeUnicode('⠓'),
+  'I': decodeUnicode('⠊'),
+  'J': decodeUnicode('⠚'),
+  'K': decodeUnicode('⠅'),
+  'L': decodeUnicode('⠇'),
+  'M': decodeUnicode('⠍'),
+  'N': decodeUnicode('⠝'),
+  'O': decodeUnicode('⠕'),
+  'P': decodeUnicode('⠏'),
+  'Q': decodeUnicode('⠟'),
+  'R': decodeUnicode('⠗'),
+  'S': decodeUnicode('⠎'),
+  'T': decodeUnicode('⠞'),
+  'U': decodeUnicode('⠥'),
+  'V': decodeUnicode('⠧'),
+  'W': decodeUnicode('⠺'),
+  'X': decodeUnicode('⠭'),
+  'Y': decodeUnicode('⠽'),
+  'Z': decodeUnicode('⠵'),
+  '[': decodeUnicode('⠪'),
+  '\\': decodeUnicode('⠳'),
+  ']': decodeUnicode('⠻'),
+  '^': decodeUnicode('⠘'),
+  '_': decodeUnicode('⠸'),
+  a: decodeUnicode('⠁'),
+  b: decodeUnicode('⠃'),
+  c: decodeUnicode('⠉'),
+  d: decodeUnicode('⠙'),
+  e: decodeUnicode('⠑'),
+  f: decodeUnicode('⠋'),
+  g: decodeUnicode('⠛'),
+  h: decodeUnicode('⠓'),
+  i: decodeUnicode('⠊'),
+  j: decodeUnicode('⠚'),
+  k: decodeUnicode('⠅'),
+  l: decodeUnicode('⠇'),
+  m: decodeUnicode('⠍'),
+  n: decodeUnicode('⠝'),
+  o: decodeUnicode('⠕'),
+  p: decodeUnicode('⠏'),
+  q: decodeUnicode('⠟'),
+  r: decodeUnicode('⠗'),
+  s: decodeUnicode('⠎'),
+  t: decodeUnicode('⠞'),
+  u: decodeUnicode('⠥'),
+  v: decodeUnicode('⠧'),
+  w: decodeUnicode('⠺'),
+  x: decodeUnicode('⠭'),
+  y: decodeUnicode('⠽'),
+  z: decodeUnicode('⠵'),
+  '{': decodeUnicode('⠪'),
+  '|': decodeUnicode('⠳'),
+  '}': decodeUnicode('⠻'),
+  '~': decodeUnicode('⠘'),
+};

package/src/decoder/constants/indicators.ts

@@ -0,0 +1,8 @@
+import { decodeUnicode } from './utils';
+
+export const NUMBER_INDICATOR = decodeUnicode('⠼');
+export const ENGLISH_INDICATOR = decodeUnicode('⠴');
+export const ENGLISH_TERMINATOR = decodeUnicode('⠲');
+export const UPPERCASE_INDICATOR = decodeUnicode('⠠');
+export const KOREAN_PART_INDICATOR = decodeUnicode('⠿');
+export const KOREAN_CONSONANT_INDICATOR = decodeUnicode('⠸');

package/src/decoder/constants/jongseong.ts

@@ -0,0 +1,19 @@
+import { decodeUnicode } from './utils';
+
+export const KOREAN_JONGSEONG: Record<number, string> = {
+  [decodeUnicode('⠁')]: 'ㄱ',
+  [decodeUnicode('⠒')]: 'ㄴ',
+  [decodeUnicode('⠔')]: 'ㄷ',
+  [decodeUnicode('⠂')]: 'ㄹ',
+  [decodeUnicode('⠢')]: 'ㅁ',
+  [decodeUnicode('⠃')]: 'ㅂ',
+  [decodeUnicode('⠄')]: 'ㅅ',
+  [decodeUnicode('⠌')]: 'ㅆ',
+  [decodeUnicode('⠶')]: 'ㅇ',
+  [decodeUnicode('⠅')]: 'ㅈ',
+  [decodeUnicode('⠆')]: 'ㅊ',
+  [decodeUnicode('⠖')]: 'ㅋ',
+  [decodeUnicode('⠦')]: 'ㅌ',
+  [decodeUnicode('⠲')]: 'ㅍ',
+  [decodeUnicode('⠴')]: 'ㅎ',
+};

package/src/decoder/constants/jungsong.ts

@@ -0,0 +1,25 @@
+import { decodeUnicode } from './utils';
+
+export const KOREAN_JUNGSEONG: Record<string, string> = {
+  [`${decodeUnicode('⠣')}`]: 'ㅏ',
+  [`${decodeUnicode('⠜')}`]: 'ㅑ',
+  [`${decodeUnicode('⠎')}`]: 'ㅓ',
+  [`${decodeUnicode('⠱')}`]: 'ㅕ',
+  [`${decodeUnicode('⠥')}`]: 'ㅗ',
+  [`${decodeUnicode('⠬')}`]: 'ㅛ',
+  [`${decodeUnicode('⠍')}`]: 'ㅜ',
+  [`${decodeUnicode('⠩')}`]: 'ㅠ',
+  [`${decodeUnicode('⠪')}`]: 'ㅡ',
+  [`${decodeUnicode('⠕')}`]: 'ㅣ',
+  [`${decodeUnicode('⠗')}`]: 'ㅐ',
+  [`${decodeUnicode('⠝')}`]: 'ㅔ',
+  [`${decodeUnicode('⠽')}`]: 'ㅚ',
+  [`${decodeUnicode('⠧')}`]: 'ㅘ',
+  [`${decodeUnicode('⠏')}`]: 'ㅝ',
+  [`${decodeUnicode('⠺')}`]: 'ㅢ',
+  [`${decodeUnicode('⠌')}`]: 'ㅖ',
+  [`${decodeUnicode('⠍')},${decodeUnicode('⠗')}`]: 'ㅟ',
+  [`${decodeUnicode('⠜')},${decodeUnicode('⠗')}`]: 'ㅒ',
+  [`${decodeUnicode('⠧')},${decodeUnicode('⠗')}`]: 'ㅙ',
+  [`${decodeUnicode('⠏')},${decodeUnicode('⠗')}`]: 'ㅞ',
+};

package/src/decoder/constants/number.ts

@@ -0,0 +1,14 @@
+import { decodeUnicode } from './utils';
+
+export const NUMBERS: Record<number, string> = {
+  [decodeUnicode('⠁')]: '1',
+  [decodeUnicode('⠃')]: '2',
+  [decodeUnicode('⠉')]: '3',
+  [decodeUnicode('⠙')]: '4',
+  [decodeUnicode('⠑')]: '5',
+  [decodeUnicode('⠋')]: '6',
+  [decodeUnicode('⠛')]: '7',
+  [decodeUnicode('⠓')]: '8',
+  [decodeUnicode('⠊')]: '9',
+  [decodeUnicode('⠚')]: '0',
+};

package/src/decoder/constants/symbol.ts

@@ -0,0 +1,34 @@
+import { decodeUnicode } from './utils';
+
+export const SYMBOLS: Record<string, string> = {
+  [`${decodeUnicode('⠖')}`]: '!',
+  [`${decodeUnicode('⠲')}`]: '.',
+  [`${decodeUnicode('⠐')}`]: ',',
+  [`${decodeUnicode('⠦')}`]: '?',
+  [`${decodeUnicode('⠐')},${decodeUnicode('⠂')}`]: ':',
+  [`${decodeUnicode('⠰')},${decodeUnicode('⠆')}`]: ';',
+  [`${decodeUnicode('⠤')}`]: '-',
+  [`${decodeUnicode('⠤')},${decodeUnicode('⠤')}`]: '―',
+  [`${decodeUnicode('⠦')}`]: '"', // opening
+  [`${decodeUnicode('⠴')}`]: '"', // closing
+  [`${decodeUnicode('⠠')},${decodeUnicode('⠦')}`]: "'",
+  [`${decodeUnicode('⠈')},${decodeUnicode('⠔')}`]: '~',
+  [`${decodeUnicode('⠲')},${decodeUnicode('⠲')},${decodeUnicode('⠲')}`]: '…',
+  [`${decodeUnicode('⠠')},${decodeUnicode('⠠')},${decodeUnicode('⠠')}`]: '⋯',
+  [`${decodeUnicode('⠦')},${decodeUnicode('⠄')}`]: '(',
+  [`${decodeUnicode('⠠')},${decodeUnicode('⠴')}`]: ')',
+  [`${decodeUnicode('⠦')},${decodeUnicode('⠂')}`]: '{',
+  [`${decodeUnicode('⠐')},${decodeUnicode('⠴')}`]: '}',
+  [`${decodeUnicode('⠦')},${decodeUnicode('⠆')}`]: '[',
+  [`${decodeUnicode('⠰')},${decodeUnicode('⠴')}`]: ']',
+  [`${decodeUnicode('⠐')},${decodeUnicode('⠆')}`]: '·',
+  [`${decodeUnicode('⠐')},${decodeUnicode('⠦')}`]: '「',
+  [`${decodeUnicode('⠴')},${decodeUnicode('⠂')}`]: '」',
+  [`${decodeUnicode('⠰')},${decodeUnicode('⠦')}`]: '『',
+  [`${decodeUnicode('⠴')},${decodeUnicode('⠆')}`]: '』',
+  [`${decodeUnicode('⠸')},${decodeUnicode('⠌')}`]: '/',
+  [`${decodeUnicode('⠐')},${decodeUnicode('⠶')}`]: '〈',
+  [`${decodeUnicode('⠶')},${decodeUnicode('⠂')}`]: '〉',
+  [`${decodeUnicode('⠰')},${decodeUnicode('⠶')}`]: '《',
+  [`${decodeUnicode('⠶')},${decodeUnicode('⠆')}`]: '》',
+};

package/src/decoder/constants/utils.ts

@@ -0,0 +1,14 @@
+export const BRAILLE_UNICODE_START = 0x2800;
+
+export function decodeUnicode(char: string): number {
+  const code = char.charCodeAt(0);
+  if (code >= BRAILLE_UNICODE_START && code <= BRAILLE_UNICODE_START + 0x3f) {
+    return code - BRAILLE_UNICODE_START;
+  }
+  return -1;
+}
+
+export function encodeUnicode(dot: number): string {
+  if (dot === 255) return '\n';
+  return String.fromCharCode(BRAILLE_UNICODE_START + dot);
+}

package/src/decoder/index.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect } from 'vitest';
+import { Decoder } from './index';
+
+describe('Decoder', () => {
+  const decoder = new Decoder();
+
+  describe('asciiBrailleToUnicode', () => {
+    it('should convert basic letters', () => {
+      expect(decoder.asciiBrailleToUnicode('abcd')).toBe('⠁⠃⠉⠙');
+    });
+
+    it('should convert numbers (in ASCII Braille format)', () => {
+      // In Braille ASCII, '1' is ⠂, '2' is ⠆, etc.
+      expect(decoder.asciiBrailleToUnicode('1234')).toBe('⠂⠆⠒⠲');
+    });
+
+    it('should convert complex strings', () => {
+      expect(decoder.asciiBrailleToUnicode('<3c]j,n+')).toBe('⠣⠒⠉⠻⠚⠠⠝⠬');
+    });
+
+    it('ascii', () => {
+      // https://en.wikipedia.org/wiki/Braille_ASCII
+      expect(decoder.asciiBrailleToUnicode(' ')).toBe('⠀')
+      expect(decoder.asciiBrailleToUnicode('=')).toBe('⠿')
+    });
+
+
+    it('should convert complex korean strings 1', () => {
+      expect(decoder.asciiBrailleToUnicode(',ui{a@{5ra.{7e}8\'#bjbd c* @mr,x,0')).toBe('⠠⠥⠊⠪⠁⠈⠪⠢⠗⠁⠨⠪⠶⠑⠻⠦⠄⠼⠃⠚⠃⠙⠀⠉⠡⠀⠈⠍⠗⠠⠭⠠⠴');
+    });
+  });
+
+  describe('translateToText', () => {
+    it('should translate Korean "안녕하세요"', () => {
+      // 안: ⠣⠒ (ㅏ + ㄴ받침) -> Actually '안' is ⠣(ㅏ) + ⠒(ㄴ종성)
+      // 녕: ⠉⠻ (ㄴ초성 + 영약자)
+      // 하: ⠚ (하약자)
+      // 세: ⠠⠝ (ㅅ초성 + ㅔ)
+      // 요: ⠬ (ㅛ)
+      // Result: ⠣⠒⠉⠻⠚⠠⠝⠬
+      expect(decoder.translateToText('⠣⠒⠉⠻⠚⠠⠝⠬')).toBe('안녕하세요');
+      // Note: Full syllable composition is complex, for now we verify parts
+    });
+
+    it('should translate English with indicators', () => {
+      // ⠴ (English Indicator) + ⠁⠃⠉ (abc)
+      expect(decoder.translateToText('⠴⠁⠃⠉')).toBe('abc');
+    });
+
+    it('should translate Numbers with indicators', () => {
+      // ⠼ (Number Indicator) + ⠁⠃⠉ (123)
+      expect(decoder.translateToText('⠼⠁⠃⠉')).toBe('123');
+    });
+
+    it('should handle mixed content', () => {
+      // ⠼⠁⠀⠴⠁ (1 a)
+      expect(decoder.translateToText('⠼⠁⠀⠴⠁')).toBe('1 a');
+    });
+
+    it('should translate Korean sample 1', () => {
+      expect(decoder.translateToText('⠦⠄⠼⠃⠚⠃⠙⠀⠉⠡⠀⠈⠍⠗⠠⠭⠠⠴')).toBe('(2024년 귀속)');
+      expect(decoder.translateToText('⠘⠂⠈⠪⠃⠘⠾⠚⠥⠐⠂')).toBe('발급번호:');
+    });
+
+    it('should translate Korean sample 2', () => {
+      expect(decoder.translateToText('⠠⠥⠊⠪⠁⠈⠪⠢⠗⠁⠨⠪⠶⠑⠻⠦⠄⠼⠃⠚⠃⠙⠀⠉⠡⠀⠈⠍⠗⠠⠭⠠⠴')).toBe('소득금액증명(2024년 귀속)');
+    });
+
+    it('should translate Korean sample 3', () => {
+      expect(decoder.translateToText('⠰⠎⠐⠕⠈⠕⠫⠒⠐⠂⠀⠨⠪⠁⠠⠕')).toBe('처리기간: 즉시');
+    });
+
+    it('should translate Korean sample 4', () => {
+      expect(decoder.translateToText('⠨⠍⠑⠟⠊⠪⠶⠐⠭⠘⠾⠚⠥⠐⠂⠀⠼⠊⠊⠊⠊⠊⠊⠤⠸⠢⠢⠢⠢⠢⠢⠢⠇')).toBe('주민등록번호: 999999‐∗∗∗∗∗∗∗');
+    });
+  });
+});