feat: 한글 문자열에 대한 검증, assert, parsing 함수를 구현합니다. (#136)

* feat: 한글 문자열인지 boolean 반환 함수

* feat: 한글 문자열인지 assert 함수

* feat: stringify

* test: isHangulString, assertHangulString 테스트 코드

* feat: parse 함수

* test: parse 함수 테스트

* refactor: naming 통일

src/_internal/hangul.spec.ts

@@ -1,4 +1,13 @@
-import { binaryAssembleHangulCharacters, binaryAssembleHangul, isHangulAlphabet, isHangulCharacter } from './hangul';
+import {
+  binaryAssembleHangulCharacters,
+  binaryAssembleHangul,
+  isHangulAlphabet,
+  isHangulCharacter,
+  isHangul,
+  assertHangul,
+  parseHangul,
+  safeParseHangul,
+} from './hangul';
 
 describe('isHangul*', () => {
   it('isHangulCharacter는 완성된 한글 문자를 받으면 true를 반환한다.', () => {
@@ -16,6 +25,51 @@ describe('isHangul*', () => {
     expect(isHangulAlphabet('ㅏ')).toBe(true);
     expect(isHangulAlphabet('a')).toBe(false);
   });
+
+  it('isHangul은 한글 문자열을 받으면 true를 반환한다.', () => {
+    expect(isHangul('값')).toBe(true);
+    expect(isHangul('ㄱ')).toBe(true);
+    expect(isHangul('ㅏ')).toBe(true);
+    expect(isHangul('저는 고양이를 좋아합니다')).toBe(true);
+    expect(isHangul('a')).toBe(false);
+    expect(isHangul(111)).toBe(false);
+    expect(isHangul([111, 111])).toBe(false);
+    expect(isHangul({ a: 111 })).toBe(false);
+  });
+});
+
+describe('parse', () => {
+  it('parseHangul은 한글 문자열을 받으면 그대로 반환한다.', () => {
+    expect(parseHangul('값')).toBe('값');
+    expect(parseHangul('ㄱ')).toBe('ㄱ');
+    expect(parseHangul('ㅏ')).toBe('ㅏ');
+    expect(parseHangul('저는 고양이를 좋아합니다')).toBe('저는 고양이를 좋아합니다');
+  });
+
+  it('parseHangul은 한글 문자열이 아닌 값을 받으면 에러를 발생시킨다.', () => {
+    expect(() => parseHangul(111)).toThrowError('111 is not a valid hangul string');
+    expect(() => parseHangul([111, 111])).toThrowError('[111,111] is not a valid hangul string');
+    expect(() => parseHangul({ a: 111 })).toThrowError('{"a":111} is not a valid hangul string');
+  });
+
+  it('safeParseHangul은 한글 문자열을 받으면 성공 객체를 반환한다.', () => {
+    expect(safeParseHangul('값')).toEqual({ success: true, data: '값' });
+    expect(safeParseHangul('ㄱ')).toEqual({ success: true, data: 'ㄱ' });
+    expect(safeParseHangul('ㅏ')).toEqual({ success: true, data: 'ㅏ' });
+    expect(safeParseHangul('저는 고양이를 좋아합니다')).toEqual({ success: true, data: '저는 고양이를 좋아합니다' });
+  });
+
+  it('safeParseHangul은 한글 문자열이 아닌 값을 받으면 실패 객체를 반환한다.', () => {
+    expect(safeParseHangul(111)).toEqual({ success: false, error: Error('111 is not a valid hangul string') });
+    expect(safeParseHangul([111, 111])).toEqual({
+      success: false,
+      error: Error('[111,111] is not a valid hangul string'),
+    });
+    expect(safeParseHangul({ a: 111 })).toEqual({
+      success: false,
+      error: Error('{"a":111} is not a valid hangul string'),
+    });
+  });
 });
 
 describe('binaryAssembleHangulCharacters', () => {
@@ -107,4 +161,20 @@ describe('binaryAssembleHangul', () => {
     expect(binaryAssembleHangul('저는 고양이를 좋아하', 'ㅏ')).toEqual('저는 고양이를 좋아하ㅏ');
     expect(binaryAssembleHangul('저는 고양이를 좋아합니다', 'ㅜ')).toEqual('저는 고양이를 좋아합니다ㅜ');
   });
+
+  describe('assertHangul', () => {
+    it('한글 문자열을 받으면 에러를 발생시키지 않는다.', () => {
+      expect(() => assertHangul('ㄱ')).not.toThrow();
+      expect(() => assertHangul('고양이')).not.toThrow();
+      expect(() => assertHangul('저는 고양이를 좋아합니다')).not.toThrow();
+      expect(() => assertHangul('저는 고양이를 좋아합니ㄷ')).not.toThrow();
+    });
+
+    it("한글 문자열이 아닌 값을 받으면 '___ is not a valid hangul string' 에러를 발생시킨다.", () => {
+      expect(() => assertHangul('aaaaaa')).toThrowError('"aaaaaa" is not a valid hangul string');
+      expect(() => assertHangul(111)).toThrowError('111 is not a valid hangul string');
+      expect(() => assertHangul([111, 111])).toThrowError('[111,111] is not a valid hangul string');
+      expect(() => assertHangul({ a: 111 })).toThrowError('{"a":111} is not a valid hangul string');
+    });
+  });
 });

src/_internal/hangul.ts

@@ -12,6 +12,40 @@ export function isHangulAlphabet(character: string) {
   return /^[ㄱ-ㅣ]$/.test(character);
 }
 
+export function isHangul(actual: unknown): actual is string {
+  return typeof actual === 'string' && /^[가-힣ㄱ-ㅣ\s]+$/.test(actual);
+}
+
+export function assertHangul(actual: unknown, message?: string): asserts actual is string {
+  assert(isHangul(actual), message || `${JSON.stringify(actual)} is not a valid hangul string`);
+}
+
+export function parseHangul(actual: unknown): string {
+  assertHangul(actual);
+  return actual;
+}
+
+type SafeParseSuccess = {
+  success: true;
+  data: string;
+  error?: never;
+};
+
+type SafeParseError = {
+  success: false;
+  error: unknown;
+  data?: never;
+};
+
+export function safeParseHangul(actual: unknown): SafeParseSuccess | SafeParseError {
+  try {
+    const parsedHangul = parseHangul(actual);
+    return { success: true, data: parsedHangul };
+  } catch (error) {
+    return { success: false, error };
+  }
+}
+
 /**
  * @name binaryAssembleHangulAlphabets
  * @description