feat: 한글 문장과 문자가 담긴 배열을 인자로 받아 규칙에 맞게 합성하는 assemble 함수 추가 (#64)

* feat: 인자로 받은 문자의 초성, 중성, 종성 위치 가능 여부를 파악하는 함수 추가

* feat: combineHangulCharacter 함수 추가

* feat: assembleHangul 함수 추가

* refactor: assembleHangul내 의미없는 익명 함수 제거

* chore: update test

* refactor: assert 추가

* refactor: export하지않을 함수들은 _internal 모듈로 이동

* chore: binaryAssembleHangul의 jsDoc 추가

* chore: assembleHangul jsDoc 추가

* fix: jsDoc 오타 수정

* refactor: 분해된 자모를 나타내는 변수를 복수형으로 변경

* Create great-yaks-deny.md

* refactor: hasSingleBatchim 내 early return 패턴 추가

.changeset/great-yaks-deny.md

@@ -0,0 +1,5 @@
+---
+"es-hangul": minor
+---
+
+feat: 한글 문장과 문자가 담긴 배열을 인자로 받아 규칙에 맞게 합성하는 `assemble` 함수 추가

src/_internal/hangul.spec.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect, assert } from 'vitest';
+import { binaryAssembleHangulCharacters, binaryAssembleHangul, isHangulAlphabet, isHangulCharacter } from './hangul';
+
+describe('isHangul*', () => {
+  it('isHangulCharacter는 완성된 한글 문자를 받으면 true를 반환한다', () => {
+    expect(isHangulCharacter('가')).toBe(true);
+    expect(isHangulCharacter('값')).toBe(true);
+    expect(isHangulCharacter('ㄱ')).toBe(false);
+    expect(isHangulCharacter('ㅏ')).toBe(false);
+    expect(isHangulCharacter('a')).toBe(false);
+  });
+  it('isHangulAlphabet은 조합되지않은 한글 문자를 받으면 true를 반환한다', () => {
+    expect(isHangulAlphabet('가')).toBe(false);
+    expect(isHangulAlphabet('값')).toBe(false);
+    expect(isHangulAlphabet('ㄱ')).toBe(true);
+    expect(isHangulAlphabet('ㅏ')).toBe(true);
+    expect(isHangulAlphabet('a')).toBe(false);
+  });
+});
+
+describe('binaryAssembleHangulCharacters', () => {
+  it('초성과 중성만 조합', () => {
+    expect(binaryAssembleHangulCharacters('ㄱ', 'ㅏ')).toEqual('가');
+  });
+
+  it('초성과 중성이 합쳐진 문자와 종성을 조합', () => {
+    expect(binaryAssembleHangulCharacters('가', 'ㅇ')).toEqual('강');
+  });
+
+  it('초성과 중성과 종성이 합쳐진 문자와 자음을 조합하여 겹받침 만들기', () => {
+    expect(binaryAssembleHangulCharacters('갑', 'ㅅ')).toEqual('값');
+  });
+
+  it('초성과 중성이 합쳐진 문자와 모음을 조립하여 겹모음 만들기', () => {
+    expect(binaryAssembleHangulCharacters('고', 'ㅏ')).toEqual('과');
+  });
+
+  it('모음만 있는 문자와 모음을 조합하여 겹모음 만들기', () => {
+    expect(binaryAssembleHangulCharacters('ㅗ', 'ㅏ')).toEqual('ㅘ');
+  });
+
+  it('초성과 중성과 종성이 합쳐진 문자의 연음 법칙', () => {
+    expect(binaryAssembleHangulCharacters('톳', 'ㅡ')).toEqual('토스');
+  });
+
+  it('초성과 중성과 종성(겹받침)이 합쳐진 문자의 연음 법칙', () => {
+    expect(binaryAssembleHangulCharacters('닭', 'ㅏ')).toEqual('달가');
+    expect(binaryAssembleHangulCharacters('깎', 'ㅏ')).toEqual('까까');
+  });
+
+  it('문법에 맞지 않는 문자를 조합하면 단순 Join 한다 (문법 순서 틀림)', () => {
+    expect(binaryAssembleHangulCharacters('ㅏ', 'ㄱ')).toEqual('ㅏㄱ');
+    expect(binaryAssembleHangulCharacters('까', 'ㅃ')).toEqual('까ㅃ');
+    expect(binaryAssembleHangulCharacters('ㅘ', 'ㅏ')).toEqual('ㅘㅏ');
+  });
+
+  it('순서대로 입력했을 때 조합이 불가능한 문자라면 단순 Join 한다', () => {
+    expect(binaryAssembleHangulCharacters('뼈', 'ㅣ')).toEqual('뼈ㅣ');
+  });
+
+  it('소스가 두 글자 이상이라면 Invalid source 에러를 발생시킨다.', () => {
+    assert.throws(
+      () => binaryAssembleHangulCharacters('가나', 'ㄴ'),
+      Error,
+      'Invalid source character: 가나. Source must be one character.'
+    );
+    assert.throws(
+      () => binaryAssembleHangulCharacters('ㄱㄴ', 'ㅏ'),
+      Error,
+      'Invalid source character: ㄱㄴ. Source must be one character.'
+    );
+  });
+
+  it('다음 문자가 한글 문자 한 글자가 아니라면 Invalid next character 에러를 발생시킨다.', () => {
+    assert.throws(
+      () => binaryAssembleHangulCharacters('ㄱ', 'a'),
+      Error,
+      'Invalid next character: a. Next character must be one of the chosung, jungsung, or jongsung.'
+    );
+    assert.throws(
+      () => binaryAssembleHangulCharacters('ㄱ', 'ㅡㅏ'),
+      Error,
+      'Invalid next character: ㅡㅏ. Next character must be one of the chosung, jungsung, or jongsung.'
+    );
+  });
+});
+
+describe('binaryAssembleHangul', () => {
+  it('문장과 모음을 조합하여 다음 글자를 생성한다', () => {
+    expect(binaryAssembleHangul('저는 고양이를 좋아합닏', 'ㅏ')).toEqual('저는 고양이를 좋아합니다');
+  });
+
+  it('문장과 자음을 조합하여 홑받침을 생성한다', () => {
+    expect(binaryAssembleHangul('저는 고양이를 좋아하', 'ㅂ')).toEqual('저는 고양이를 좋아합');
+  });
+
+  it('문장과 자음을 조합하여 겹받침을 생성한다', () => {
+    expect(binaryAssembleHangul('저는 고양이를 좋아합', 'ㅅ')).toEqual('저는 고양이를 좋아핪');
+  });
+
+  it('조합이 불가능한 자음이 입력되면 단순 Join 한다', () => {
+    expect(binaryAssembleHangul('저는 고양이를 좋아합', 'ㄲ')).toEqual('저는 고양이를 좋아합ㄲ');
+    expect(binaryAssembleHangul('저는 고양이를 좋아합', 'ㅂ')).toEqual('저는 고양이를 좋아합ㅂ');
+  });
+
+  it('조합이 불가능한 모음이 입력되면 단순 Join 한다', () => {
+    expect(binaryAssembleHangul('저는 고양이를 좋아하', 'ㅏ')).toEqual('저는 고양이를 좋아하ㅏ');
+    expect(binaryAssembleHangul('저는 고양이를 좋아합니다', 'ㅜ')).toEqual('저는 고양이를 좋아합니다ㅜ');
+  });
+});

src/_internal/hangul.ts

@@ -0,0 +1,143 @@
+import assert, { excludeLastElement, isBlank, joinString } from '.';
+import { combineHangulCharacter, combineVowels, curriedCombineHangulCharacter } from '../combineHangulCharacter';
+import { disassembleHangulToGroups } from '../disassemble';
+import { removeLastHangulCharacter } from '../removeLastHangulCharacter';
+import { canBeChosung, canBeJongsung, canBeJungsung, hasSingleBatchim } from '../utils';
+
+export function isHangulCharacter(character: string) {
+  return /^[가-힣]$/.test(character);
+}
+
+export function isHangulAlphabet(character: string) {
+  return /^[ㄱ-ㅣ]$/.test(character);
+}
+
+/**
+ * @name binaryAssembleHangulAlphabets
+ * @description
+ * 두 개의 한글 자모를 합칩니다. 완성된 한글 문자는 취급하지 않습니다.
+ * @example
+ * ```
+ * binaryAssembleHangulAlphabets('ㄱ', 'ㅏ') // 가
+ * binaryAssembleHangulAlphabets('ㅗ', 'ㅏ') // ㅘ
+ * ```
+ */
+export function binaryAssembleHangulAlphabets(source: string, nextCharacter: string) {
+  if (canBeJungsung(`${source}${nextCharacter}`)) {
+    return combineVowels(source, nextCharacter);
+  }
+
+  const isConsonantSource = canBeJungsung(source) === false;
+  if (isConsonantSource && canBeJungsung(nextCharacter)) {
+    return combineHangulCharacter(source, nextCharacter);
+  }
+
+  return joinString(source, nextCharacter);
+}
+
+/**
+ * @name linkHangulCharacters
+ * @description
+ * 연음 법칙을 적용하여 두 개의 한글 문자를 연결합니다.
+ */
+export function linkHangulCharacters(source: string, nextCharacter: string) {
+  const sourceJamo = disassembleHangulToGroups(source)[0];
+  const [, lastJamo] = excludeLastElement(sourceJamo);
+
+  return joinString(removeLastHangulCharacter(source), combineHangulCharacter(lastJamo, nextCharacter));
+}
+
+/**
+ * @name binaryAssembleHangulCharacters
+ * @description
+ * 인자로 받은 한글 문자 2개를 합성합니다.
+ * ```typescript
+ * binaryAssembleHangulCharacters(
+ *   // 소스 문자
+ *   source: string
+ *   // 다음 문자
+ *   nextCharacter: string
+ * ): string
+ * ```
+ * @example
+ * binaryAssembleHangulCharacters('ㄱ', 'ㅏ') // 가
+ * binaryAssembleHangulCharacters('가', 'ㅇ') // 강
+ * binaryAssembleHangulCharacters('갑', 'ㅅ') // 값
+ * binaryAssembleHangulCharacters('깎', 'ㅏ') // 까까
+ */
+export function binaryAssembleHangulCharacters(source: string, nextCharacter: string) {
+  assert(
+    isHangulCharacter(source) || isHangulAlphabet(source),
+    `Invalid source character: ${source}. Source must be one character.`
+  );
+  assert(
+    isHangulAlphabet(nextCharacter),
+    `Invalid next character: ${nextCharacter}. Next character must be one of the chosung, jungsung, or jongsung.`
+  );
+
+  const sourceJamos = disassembleHangulToGroups(source)[0];
+
+  const isSingleCharacter = sourceJamos.length === 1;
+  if (isSingleCharacter) {
+    const sourceCharacter = sourceJamos[0];
+    return binaryAssembleHangulAlphabets(sourceCharacter, nextCharacter);
+  }
+
+  const [restJamos, lastJamo] = excludeLastElement(sourceJamos);
+
+  const needLinking = canBeChosung(lastJamo) && canBeJungsung(nextCharacter);
+  if (needLinking) {
+    return linkHangulCharacters(source, nextCharacter);
+  }
+
+  const fixConsonant = curriedCombineHangulCharacter;
+  const combineJungsung = fixConsonant(restJamos[0]);
+
+  if (canBeJungsung(`${lastJamo}${nextCharacter}`)) {
+    return combineJungsung(`${lastJamo}${nextCharacter}`)();
+  }
+
+  if (canBeJungsung(lastJamo) && canBeJongsung(nextCharacter)) {
+    return combineJungsung(lastJamo)(nextCharacter);
+  }
+
+  const fixVowel = combineJungsung;
+  const combineJongsung = fixVowel(restJamos[1]);
+
+  const lastConsonant = lastJamo;
+
+  if (hasSingleBatchim(source) && canBeJongsung(`${lastConsonant}${nextCharacter}`)) {
+    return combineJongsung(`${lastConsonant}${nextCharacter}`);
+  }
+
+  return joinString(source, nextCharacter);
+}
+
+/**
+ * @name binaryAssembleHangul
+ * @description
+ * 인자로 받은 한글 문장과 한글 문자 하나를 합성합니다.
+ * ```typescript
+ * binaryAssembleHangul(
+ *   // 한글 문장
+ *   source: string
+ *   // 한글 문자
+ *   nextCharacter: string
+ * ): string
+ * ```
+ * @example
+ * binaryAssembleHangul('저는 고양이를 좋아합닏', 'ㅏ') // 저는 고양이를 좋아합니다
+ * binaryAssembleHangul('저는 고양이를 좋아합', 'ㅅ') // 저는 고양이를 좋아핪
+ * binaryAssembleHangul('저는 고양이를 좋아하', 'ㅏ') // 저는 고양이를 좋아하ㅏ
+ */
+export function binaryAssembleHangul(source: string, nextCharacter: string) {
+  const [rest, lastCharacter] = excludeLastElement(source.split(''));
+  const needJoinString = isBlank(lastCharacter) || isBlank(nextCharacter);
+
+  return joinString(
+    ...rest,
+    needJoinString
+      ? joinString(lastCharacter, nextCharacter)
+      : binaryAssembleHangulCharacters(lastCharacter, nextCharacter)
+  );
+}

src/_internal/index.ts

@@ -0,0 +1,18 @@
+export function excludeLastElement(array: string[]): [string[], string] {
+  const lastElement = array.at(-1);
+  return [array.slice(0, -1), lastElement ?? ''];
+}
+
+export function joinString(...args: string[]) {
+  return args.join('');
+}
+
+export function isBlank(character: string) {
+  return /^\s$/.test(character);
+}
+
+export default function assert(condition: boolean, errorMessage?: string): asserts condition {
+  if (condition === false) {
+    throw new Error(errorMessage ?? 'Invalid condition');
+  }
+}

src/assemble.spec.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+import { assembleHangul } from './assemble';
+
+describe('assembleHangul', () => {
+  it('온전한 한글과 한글 문자 조합', () => {
+    expect(assembleHangul(['아버지가', ' ', '방ㅇ', 'ㅔ ', '들ㅇ', 'ㅓ갑니다'])).toEqual('아버지가 방에 들어갑니다');
+  });
+  it('온전한 한글만 조합', () => {
+    expect(assembleHangul(['아버지가', ' ', '방에 ', '들어갑니다'])).toEqual('아버지가 방에 들어갑니다');
+  });
+  it('온전하지 않은 한글만 조합', () => {
+    expect(assembleHangul(['ㅇ', 'ㅏ', 'ㅂ', 'ㅓ', 'ㅈ', 'ㅣ'])).toEqual('아버지');
+  });
+});

src/assemble.ts

@@ -0,0 +1,22 @@
+import { disassembleHangul } from './disassemble';
+import { binaryAssembleHangul } from './_internal/hangul';
+
+/**
+ * @name assembleHangul
+ * @description
+ * 인자로 받은 배열에 담긴 한글 문장과 문자를 한글 규칙에 맞게 합성합니다.
+ * ```typescript
+ * assembleHangul(
+ *   // 한글 문자와 문장을 담고 있는 배열
+ *   words: string[]
+ * ): string
+ * ```
+ * @example
+ * assembleHangul(['아버지가', ' ', '방ㅇ', 'ㅔ ', '들ㅇ', 'ㅓ갑니다']) // 아버지가 방에 들어갑니다
+ * assembleHangul(['아버지가', ' ', '방에 ', '들어갑니다']) // 아버지가 방에 들어갑니다
+ * assembleHangul(['ㅇ', 'ㅏ', 'ㅂ', 'ㅓ', 'ㅈ', 'ㅣ']) // 아버지
+ */
+export function assembleHangul(words: string[]) {
+  const disassembled = disassembleHangul(words.join('')).split('');
+  return disassembled.reduce(binaryAssembleHangul);
+}

src/index.ts

@@ -3,3 +3,6 @@ export * from './disassemble';
 export * from './hangulIncludes';
 export * from './josa';
 export * from './utils';
+export * from './assemble';
+export * from './combineHangulCharacter';
+export * from './removeLastHangulCharacter';

src/utils.spec.ts

@@ -1,5 +1,14 @@
 import { describe, expect, expectTypeOf, it } from 'vitest';
-import { canBeChosung, canBeJongsung, canBeJungsung, getFirstConsonants, hasBatchim, hasProperty, hasValueInReadOnlyStringList } from './utils';
+import {
+  canBeChosung,
+  canBeJongsung,
+  canBeJungsung,
+  getFirstConsonants,
+  hasBatchim,
+  hasProperty,
+  hasSingleBatchim,
+  hasValueInReadOnlyStringList,
+} from './utils';
 
 describe('hasBatchim', () => {
   it('should return true for the character "값"', () => {
@@ -19,6 +28,24 @@ describe('hasBatchim', () => {
   });
 });
 
+describe('hasSingleBatchim', () => {
+  it('홑받침을 받으면 true를 반환한다.', () => {
+    expect(hasSingleBatchim('공')).toBe(true);
+    expect(hasSingleBatchim('핫')).toBe(true);
+    expect(hasSingleBatchim('양')).toBe(true);
+    expect(hasSingleBatchim('신')).toBe(true);
+  });
+  it('겹받침을 받으면 false를 반환한다.', () => {
+    expect(hasSingleBatchim('값')).toBe(false);
+    expect(hasSingleBatchim('읊')).toBe(false);
+  });
+
+  it('받침이 없는 문자를 받으면 false를 반환한다.', () => {
+    expect(hasSingleBatchim('토')).toBe(false);
+    expect(hasSingleBatchim('서')).toBe(false);
+  });
+});
+
 describe('getFirstConsonants', () => {
   it('should extract the initial consonants "ㅅㄱ" from the word "사과"', () => {
     expect(getFirstConsonants('사과')).toBe('ㅅㄱ');