semantic-typescript 0.6.0 → 0.7.0

package/readme.kr.md

@@ -1,209 +1,222 @@
-# Semantic-TypeScript: 패러다임을 바꾸는 스트림 처리 라이브러리
+# Semantic-TypeScript
+Flow, Indexed. 당신의 데이터, 정밀한 제어 아래에.
 
-## 소개
-Semantic-TypeScript는 스트림 처리 기술의 중요한 발전을 나타내며, JavaScript GeneratorFunctions, Java Streams, 데이터베이스 인덱싱 패러다임의 가장 효과적인 개념들을 종합했습니다. 그 핵심 설계 원칙은 정교한 지연 평가(lazy evaluation)와 지능형 인덱싱을 통해 매우 효율적인 데이터 처리 파이프라인을 구축하는 데 중점을 두고 있습니다. 이 라이브러리는 현대적인 TypeScript 및 JavaScript 개발을 위해 특별히 설계된 엄격한 타입 안전성과 함수형 순수성을 갖춘 스트리밍 작업 경험을 제공합니다.
+---
 
-기존의 동기식 처리 아키텍처와 대조적으로, Semantic-TypeScript는 동기식(Iterable) 및 비동기식(AsyncIterable) 데이터 소스를 모두 우아하게 처리하는 통합 모델을 구현합니다. 스트림 생성 중 데이터의 흐름과 종료는 콜백 메커니즘에 의해 정밀하게 제어되어 라이브러리가 예외적인 우아함으로 다음을 처리할 수 있게 합니다:
-- 결정론적 제어가 가능한 실시간 데이터 스트림(DOM 이벤트, WebSockets, 간격)
-- 메모리 효율적이고 지연 평가되는 파이프라인을 통한 대규모 데이터셋
-- 유창하고 선언적인 API를 통한 복잡한 데이터 변환
+### 개요
 
-이 라이브러리의 혁신적인 접근 방식은 개발자가 데이터 시퀀스와 상호작용하는 방식을 근본적으로 재구상하며, 단일하고 응집력 있는 패키지 내에서 전례 없는 성능 특성과 개발자 인체공학을 모두 제공합니다.
+Semantic-TypeScript는 스트림 처리 기술의 중요한 도약을 의미하며, JavaScript `GeneratorFunction`, Java Streams, 그리고 MySQL 스타일 인덱싱에서 가장 효과적인 개념들을 종합합니다. 그 핵심 철학은 단순하면서도 강력합니다: 무차별 반복이 아닌, 지능적인 인덱싱을 통해 매우 효율적인 데이터 처리 파이프라인을 구축하는 것입니다.
 
-## 핵심 철학: 정의와 실행의 분리
-Semantic-TypeScript의 중요한 아키텍처적 통찰은 스트림의 정의와 실행을 명확하게 분리하는 것입니다:
-- **Semantic<E>**: 데이터 변환 파이프라인의 불변(immutable)하고 지연 평가(lazy)되는 설계도입니다. 어떤 연산(filter, map 등)이 수행될지 정의합니다.
-- **Collectable<E>**: 스트림의 구체화되고 실행 가능한 뷰입니다. Semantic에서 얻어지며, 파이프라인을 실행하고 결과를 생성하기 위한 모든 최종 연산(collect, forEach 등)을 제공합니다.
+기존 라이브러리들이 동기 루프나 다루기 힘든 프로미스 체인을 부과하는 곳에서, Semantic-TypeScript는 완전히 비동기적이고, 순수 함수형이며, 엄격한 타입 안전성을 제공하는 경험을 제공합니다. 이것은 현대 프론트엔드 개발의 요구에 맞게 설계되었습니다.
 
-이러한 분리는 깔끔한 멘탈 모델을 강제하고, 불필요한 정렬을 건너뛰어 최대 속도를 내는 UnorderedCollectable을 선택하는 것과 같은 강력한 최적화를 가능하게 합니다.
+우아한 이 모델에서, 데이터는 업스트림 파이프라인이 명시적으로 `accept` (그리고 선택적으로 `interrupt`) 콜백을 호출할 때만 소비자에게 전달됩니다. 당신은 데이터가 필요한 정확한 순간, 즉 타이밍을 완벽히 제어할 수 있습니다.
 
-## Semantic-TypeScript를 선택해야 하는 이유
-데이터 스트림 처리를 위한 적절한 라이브러리를 선택하는 것은 성능, 타입 안전성, 표현력 사이의 균형을 맞추는 것을 포함합니다. Semantic-TypeScript는 이러한 모든 차원에서 탁월한 성능을 발휘하도록 설계되었습니다.
+---
 
-### 1. 모든 데이터 시퀀스를 위한 통일되고 타입 안전한 패러다임
-정적 배열, 실시간 이벤트, 비동기 청크 등 모든 데이터 시퀀스를 처리하기 위한 일관적이고 선언적인 API를 제공하며, TypeScript의 모든 기능을 활용하여 엔드-투-엔드 타입 안전성을 보장합니다. 이는 런타임 오류의 전체 범주를 제거하고 스트림 조작을 예측 가능하고 컴파일러 검증이 가능한 활동으로 전환합니다.
+### 개발자들이 선호하는 이유
 
-### 2. 지능형 지연 평가를 통한 타협 없는 성능
-핵심은 지연 평가에 기반합니다. filter, map, flatMap과 같은 연산은 단지 처리 파이프라인을 구성할 뿐이며, 최종 연산이 호출될 때까지 어떤 작업도 수행되지 않습니다. 이는 제한(limit), anyMatch 또는 사용자 정의 중단(interrupt) 콜백을 통한 단락 평가(short-circuiting) 기능과 결합되어 처리를 조기에 중지할 수 있게 하여, 크거나 무한한 스트림에 대한 효율성을 극적으로 향상시킵니다.
+• **보일러플레이트 없는 인덱싱** — 모든 요소가 고유 또는 맞춤형 인덱스를 가지고 있습니다.
 
-### 3. `Collector<E, A, R>` 패턴의 힘
-Java에서 영감을 받은 Collector 패턴은 유연성의 엔진입니다. 이는 스트림 요소를 누적하는 방법의 사양을 스트림 자체의 실행으로부터 분리합니다. 라이브러리는 일상 작업을 위한 다양한 내장 컬렉터(toArray, groupBy, summate 등)를 제공하면서도, 복잡하고 재사용 가능한 축소(reduction) 로직을 직접 구현하는 것을 간단하게 만듭니다. 이는 고정된 최종 메서드 세트보다 훨씬 더 강력하고 구성 가능합니다.
+• **순수 함수형 스타일** — 완전한 타입스크립트 타입 추론과 함께.
 
-### 4. 현대 웹 및 비동기 데이터에 대한 1급 지원
-Semantic-TypeScript는 현대적 개발을 위해 설계되었습니다. 최신 웹 소스에 대한 기본(native) 팩토리 메서드를 제공합니다:
-- 정적 데이터: `useFrom(iterable)`, `useRange()`
-- 시간 기반 스트림: `useInterval()`, `useAnimationFrame()`
-- 청크 처리된 이진 데이터: `useBlob()`
-- 실시간 이벤트 스트림: `useWebSocket()`, `useDocument()`, `useWindow()`
+• **메모리 누수 방지 이벤트 스트림** — `useWindow`, `useDocument`, `useHTMLElement`, `useWebSocket`은 안전을 염두에 두고 구축되었습니다. `limit(n)`, `sub(start, end)`, `takeWhile(predicate)`를 사용해 경계를 정의하면, 라이브러리가 정리를 관리합니다. 잔여 리스너나 메모리 누수 없음.
 
-### 5. 기본 집계를 넘어선: 내장 통계 분석
-단순한 합계와 평균을 넘어서세요. 라이브러리는 전용 NumericStatistics 및 BigIntStatistics 인터페이스를 제공하며, 스트림에서 직접 고급 통계 측정값(분산, 표준 편차, 중앙값, 왜도, 첨도)에 즉시 액세스할 수 있습니다. 이는 복잡한 데이터 분석을 한 줄의 코드로 바꿉니다.
+• **내장 통계 분석** — 평균, 중앙값, 최빈값, 분산, 왜도, 첨도를 포함한 포괄적인 number 및 bigint 분석.
 
-### 6. 개발자 인체공학을 위해 설계됨
-- **유창하고 연결 가능한 API**: 복잡한 데이터 파이프라인을 읽기 쉽고 순차적인 체인으로 작성
-- **포괄적인 유틸리티 모음**: 필수 가드(isFunction, isIterable), 유틸리티(useCompare, useTraverse) 및 함수형 인터페이스 포함
-- **Optional<T> 통합**: 값의 부재를 안전하게 모델링하여 널 포인터 문제 해결
-- **성능 가이드**: 순서 대 속도에 대해 언제 비정렬(unordered) 컬렉션을 사용하고 언제 정렬(ordered)을 사용할지에 대한 명확한 지침
+• **예측 가능한 성능** — 요구사항에 따라 정렬된 또는 비정렬 수집기(collector) 중 선택 가능.
+
+• **메모리 효율적** — 스트림은 지연 평가(Lazy Evaluation) 방식으로 처리되며, 메모리 문제를 완화합니다.
+
+• **정의되지 않은 동작 없음** — 타입스크립트가 타입 안전성과 null 가능성을 보장합니다. 콜백 함수 내에서 명시적으로 변경하지 않는 한, 입력 데이터는 수정되지 않습니다.
+
+---
+
+### 설치
 
-## 설치
 ```bash
 npm install semantic-typescript
 ```
+또는
+```bash
+yarn add semantic-typescript
+```
 
-## 실제 적용에서의 핵심 개념
+---
 
-### 1. 스트림 생성 (Semantic)
-팩토리 함수를 사용하여 다양한 소스로부터 스트림을 생성할 수 있습니다.
+### 빠른 시작
 
 ```typescript
-import { useFrom, useInterval, useDocument } from 'semantic-typescript';
+import { useOf, useFrom, useRange, useWindow, useHTMLElement, useWebSocket, useText, useStringify } from "semantic-typescript";
+
+// 숫자 통계
+let summate: number = useOf(10, 20, 30, 40)
+  .map((n: number): number => n * 2)
+  .toNumericStatistics()  // 최종 연산 전 필수 호출
+  .summate();             // 200
+
+// Bigint 통계
+let summate: bigint = useOf(10n, 20n, 30n, 40n)
+  .map((n: bigint): bigint => n * 2)
+  .toBigIntStatistics()   // 최종 연산 전 필수 호출
+  .summate();             // 200n
+
+// 인덱스로 스트림 뒤집기
+useFrom([1, 2, 3, 4, 5])
+  .redirect((element: E, index: bigint): bigint => -index) // 뒤집기를 위한 음수 인덱스
+  .toOrdered() // 인덱스 순서를 유지하려면 toOrdered() 호출
+  .toArray(); // [5, 4, 3, 2, 1]
+
+// 스트림 섞기(Shuffle)
+useFrom([1, 2, 3, 4, 5])
+  .shuffle()
+  .toOrdered()
+  .toArray(); // 예: [2, 5, 1, 4, 3]
+
+// 스트림 내 요소 이동(Translate)
+useFrom([1, 2, 3, 4, 5])
+  .translate(2)  // 요소를 오른쪽으로 2칸 이동
+  .toOrdered()
+  .toArray(); // [4, 5, 1, 2, 3]
+
+useFrom([1, 2, 3, 4, 5])
+  .translate(-2) // 요소를 왼쪽으로 2칸 이동
+  .toOrdered()
+  .toArray(); // [3, 4, 5, 1, 2]
+
+// 조기 종료와 함께하는 무한 범위
+useRange(0n, 1_000_000n)
+  .filter(n => n % 17n === 0n)
+  .limit(10n)          // 10개 요소 후 중지
+  .toUnordered()
+  .toArray();
 
-// 정적 배열로부터
-const staticStream = useFrom([1, 2, 3, 4, 5]);
+// 실시간 윈도우 크기 조정 이벤트 (5번 이벤트 후 자동 중지)
+useWindow("resize")
+  .limit(5n)          // 이벤트 스트림에 필수적
+  .toUnordered()
+  .forEach((ev, idx) => console.log(`Resize #${idx}`));
 
-// 비동기 제너레이터로부터
-const asyncStream = useFrom(async function*() {
-  yield 1;
-  yield 2;
-});
+// HTML 요소 청취
+// <input id="input" type="text"/>
+useHTMLElement("#input", "change")
+  .limit(1)
+  .toUnordered()
+  .forEach((event: Event) => submit(event));
 
-// 시간 기반 스트림
-const tickStream = useInterval(1000); // 매초마다 방출
+// 여러 요소 및 이벤트 청취
+useHTMLElement("input", ["change", "keyup"])
+  .takeWhile((event: Event): boolean => validate(event))
+  .toUnordered()
+  .forEach((event: Event) => submit(event));
 
-// DOM 이벤트 스트림 (아래의 중요한 참고사항 참조)
-const clickStream = useDocument('click');
+// WebSocket 청취
+let webSocket = new WebSocket("ws://localhost:8080");
+webSocket.addEventListener("close", (): void => {
+  webSocket.close();  // WebSocket 생명주기를 수동으로 관리
+});
+useWebSocket(webSocket, "message")
+  .limit(1)
+  .toUnordered()
+  .forEach((message: MessageEvent) => console.log(message.data));
+
+// 문자열을 코드 포트(code point) 단위로 순회
+useText("My emotion now is: 😊, and semantic is 👍")
+  .toUnordered()
+  .log(); // 문자열을 출력
+
+// 순환 참조가 있는 객체를 안전하게 문자열로 변환(Stringify)
+let o = {
+  a: 1,
+  b: "text",
+  c: [o.a, o.b, o.c] // 순환 참조
+};
+// let text: string = JSON.stringify(o); // 오류 발생
+let text: string = useStringify(o); // 안전하게 `{a: 1, b: "text", c: []}` 반환
 ```
 
-### 2. 스트림 변환 (중간 연산)
-연산은 지연 평가되며 파이프라인을 정의하기 위해 체인으로 연결됩니다.
+---
 
-```typescript
-const processedStream = staticStream
-  .filter(x => x % 2 === 0) // 짝수만 유지
-  .map(x => x * 10) // 10 곱하기
-  .flatMap(x => [x, x + 1]) // 각 요소를 두 개로 변환
-  .distinct(); // 중복 제거
+### 핵심 개념
 
-// 아직 아무것도 실행되지 않았습니다
-```
+| 개념 | 목적 | 언제 사용하는가 |
+| :--- | :--- | :--- |
+| `AsynchronousSemantic` | 비동기 스트림, 이벤트, 지연 평가 파이프라인을 위한 핵심 빌더. | 실시간 이벤트, WebSocket, DOM 리스너, 장기 실행 또는 무한 스트림. |
+| `SynchronousSemantic` | 동기식, 메모리 내 또는 루프 기반 스트림을 위한 빌더. | 정적 데이터, 범위, 즉시 반복. |
+| `toUnordered()` | 가장 빠른 최종 수집기 (맵 기반 인덱싱). | 성능이 중요한 경로 (O(n) 시간 및 공간 복잡도, 정렬 없음). |
+| `toOrdered()` | 정렬된, 인덱스 안정적인 수집기. | 안정적인 순서 또는 인덱싱된 접근이 필요할 때. |
+| `toNumericStatistics()` | 풍부한 숫자 통계 분석 (평균, 중앙값, 분산, 왜도, 첨도 등). | 데이터 분석 및 통계 계산. |
+| `toBigIntStatistics()` | 풍부한 bigint 통계 분석. | 큰 정수에 대한 데이터 분석 및 통계 계산. |
+| `toWindow()` | 슬라이딩 및 텀블링 윈도우 지원. | 시계열 처리, 배치 처리, 윈도우 기반 연산. |
 
-### 3. 스트림 실행 (최종 연산)
-결과를 얻으려면 Collectable을 얻고 최종 연산을 호출해야 합니다.
+---
 
-```typescript
-// 성능을 위한 비정렬(unordered) collectable 얻기
-const resultArray = await processedStream.toUnordered().toArray();
-console.log(resultArray); // 예: [20, 21, 40, 41]
-
-// 내장 컬렉터 사용
-const sum = await processedStream.toUnordered().collect(useSummate());
-console.log(sum);
-
-// 또는 일반 collect 메서드 사용
-const customResult = await processedStream.toOrdered().collect(
-  () => new Map<number, number>(),
-  (map, element, index) => map.set(index, element),
-  map => map
-);
-```
+중요 사용 규칙
 
-### 4. 중요: 이벤트 스트림 작업
-이벤트 스트림(useDocument, useWindow, useHTMLElement, useWebSocket)은 본질적으로 무한합니다. 언제 이벤트 수집을 중지하고 스트림을 완료할지 정의하기 위해 sub, takeWhile 또는 limit과 같은 연산을 사용해야 합니다. 그렇지 않으면 최종 연산이 무기한 대기합니다.
+1.  이벤트 스트림 (`useWindow`, `useDocument`, `useHTMLElement`, `useWebSocket`, …)은 `AsynchronousSemantic`을 반환합니다.
+    → 청취를 중지하려면 `.limit(n)`, `.sub(start, end)`, 또는 `.takeWhile()`을 **반드시 호출해야 합니다.** 그렇지 않으면 리스너가 계속 활성 상태로 유지됩니다.
 
-```typescript
-import { useDocument } from 'semantic-typescript';
+2.  최종 연산 (`.toArray()`, `.count()`, `.average()`, `.reduce()`, `.findFirst()` 등)은 수집기로 변환한 후에만 사용 가능합니다:
+    ```typescript
+    .toUnordered()   // O(n) 시간 및 공간 복잡도, 정렬 없음
+    // 또는
+    .toOrdered()     // 정렬됨, 순서 유지
+    ```
 
-// 처음 5번의 클릭만 수집
-const first5Clicks = await useDocument('click')
-  .limit(5) // <- 필수: 스트림을 5개의 이벤트로 제한
-  .toUnordered()
-  .toArray();
+---
 
-// 10초 동안의 클릭 수집
-const clicksIn10s = await useDocument('click')
-  .takeWhile((_, index, startTime = Date.now()) => Date.now() - startTime < 10000)
-  .toUnordered()
-  .toArray();
+### 성능 특성
 
-// 인덱스 2부터 5까지(0 기준)의 클릭 수집
-const specificClicks = await useDocument('click')
-  .sub(2n, 6n) // <- 인덱스 2, 3, 4, 5의 요소를 취함
-  .toUnordered()
-  .toArray();
-```
+| 수집기 | 시간 복잡도 | 공간 복잡도 | 정렬 여부 | 최적 용도 |
+| :--- | :--- | :--- | :--- | :--- |
+| `toUnordered()` | O(n) | O(n) | 아니요 | 원시 속도, 순서가 필요하지 않은 경우. |
+| `toOrdered()` | O(2n) | O(n) | 예 | 안정적인 순서, 인덱싱된 접근, 분석. |
+| `toNumericStatistics()` | O(2n) | O(n) | 예 | 정렬된 데이터가 필요한 통계 연산. |
+| `toBigIntStatistics()` | O(2n) | O(n) | 예 | bigint에 대한 통계 연산. |
+| `toWindow()` | O(2n) | O(n) | 예 | 시간 기반 윈도우 연산. |
 
-**핵심 통찰**: 이벤트(예: MouseEvent)와 그 순차적 발생 인덱스(빅인트)는 `accept(event, index)` 콜백을 통해 파이프라인을 함께 전달됩니다.
+속도가 가장 중요할 때는 `toUnordered()`를 선택하세요. 안정적인 순서나 정렬된 데이터에 의존하는 통계 메서드가 필요할 때만 `toOrdered()`를 사용하세요.
 
-### 5. 통계 활용
-```typescript
-const numericStream = useFrom([10, 20, 30, 40, 50]).toNumeric();
-const average = await numericStream.average();
-const median = await numericStream.median();
-const standardDeviation = await numericStream.standardDeviation();
-const skewness = await numericStream.skewness();
-console.log(`평균: ${average}, 중앙값: ${median}, 표준편차: ${standardDeviation}`);
-```
+---
 
-## 주요 기능
-- **이중 스트림 유형**: 동기식 Semantic(Iterable용) 및 비동기식 Semantic(AsyncIterable 및 이벤트용) 모두에 대한 완전한 지원
-- **풍부한 연산 집합**: filter, map, flatMap, concat, distinct, sorted, limit, skip, peek, reverse, shuffle
-- **유연한 최종 연산**: collect(사용자 정의 컬렉터 포함), toArray, toSet, toMap, forEach, reduce, findFirst, anyMatch, allMatch, count
-- **고급 컬렉터**: 결합(joining), 그룹화(groupingBy), 분할(partitioningBy), 합계(summation), 평균(averaging), 최대(maxBy), 최소(minBy)를 위한 내장 컬렉터
-- **통계 모듈**: 숫자/빅인트 스트림에 대한 평균(mean), 중앙값(median), 최빈값(mode), 분산(variance), 표준 편차(standardDeviation), 범위(range), 사분위수(quantiles), 왜도(skewness), 첨도(kurtosis)를 위한 즉시 사용 가능한 메서드
-- **유틸리티 함수**: 타입 가드(isPromise, isAsyncIterable), 비교자(useCompare), 탐색(useTraverse) 및 변환 훅
-- **Optional<T>**: 널 가능(nullable) 값을 위한 모나딕 컨테이너, 찾기(find) 연산과 통합됨
-
-## API 개요
-### 핵심 클래스 및 인터페이스
-- `Semantic<E>` / `AsynchronousSemantic<E>`: 추상적인 스트림 정의
-- `Collectable<E>` / `AsynchronousCollectable<E>`: 최종 연산을 포함한 실행 가능한 스트림
-- `OrderedCollectable<E>` / `UnorderedCollectable<E>`: 순서에 민감하거나 순서에 민감하지 않은 연산에 최적화된 구체화된 버전
-- `Collector<E, A, R>`: 가변 축소(mutable reduction) 연산을 위한 추상화
-
-### 팩토리 함수 (use*)
-- **소스로부터**: useFrom, useRange, useFill, useEmpty
-- **시간으로부터**: useInterval, useAnimationFrame
-- **Web API로부터**: useBlob, useDocument, useWindow, useHTMLElement, useWebSocket
-- **컬렉터**: useToArray, useGroupBy, useSummate, useJoin 등
-
-## 성능 참고사항
-- **지연 평가**: 파이프라인은 최종 연산이 호출될 때까지 실행 없이 구성됩니다.
-- **단락 평가**: limit, anyMatch, findFirst와 같은 연산은 결과가 결정되는 즉시 요소 처리를 중지합니다.
-- **정렬(Ordered) vs 비정렬(Unordered)**:
-  - 소스 요소의 순서가 결과에 중요하지 않은 경우(예: 합계, 최댓값 또는 toSet) 최종 연산에 `.toUnordered()`를 사용하십시오. 이는 비용이 많이 드는 정렬 단계를 건너뛰는 내부 최적화를 허용할 수 있습니다.
-  - 순서가 중요한 경우(예: 순서를 유지해야 하는 toArray) `.toOrdered()`를 사용하십시오.
-
-## 시작하기 예제
-```typescript
-import { useFrom, useSummate, useGroupBy } from 'semantic-typescript';
-
-interface Transaction {
-  id: number;
-  amount: number;
-  category: string;
-}
-
-const transactions: Transaction[] = [
-  { id: 1, amount: 100, category: 'Food' },
-  { id: 2, amount: 200, category: 'Electronics' },
-  { id: 3, amount: 50, category: 'Food' },
-  { id: 4, amount: 300, category: 'Electronics' },
-];
-
-// 카테고리별 총액 계산
-const totalsByCategory = await useFrom(transactions)
-  .toUnordered()
-  .collect(
-    useGroupBy(
-      t => t.category,
-      t => t.amount,
-      useSummate() // 값에 대한 컬렉터
-    )
-  );
-
-console.log(totalsByCategory); // Map { 'Food' => 150, 'Electronics' => 500 }
-```
+다른 프론트엔드 스트림 프로세서와의 비교
+
+| 기능 | Semantic-TypeScript | RxJS | 네이티브 Async Iterators / Generators | Most.js |
+| :--- | :--- | :--- | :--- | :--- |
+| 타입스크립트 통합 | 일급, 네이티브 인덱스 인식과 함께 깊은 타입 지원. | 뛰어나나, 복잡한 제네릭이 포함됨. | 좋음, 수동 타이핑 필요. | 강함, 함수형 우선 스타일. |
+| 내장 통계 분석 | `number` 및 `bigint`에 대한 포괄적인 네이티브 지원. | 네이티브로 사용 불가 (사용자 정의 연산자 필요). | 없음. | 없음. |
+| 인덱싱 & 위치 인식 | 네이티브, 모든 요소에 강력한 bigint 인덱싱. | 사용자 정의 연산자 필요 (`scan`, `withLatestFrom`). | 수동 카운터 필요. | 기본적, 내장 인덱스 없음. |
+| 이벤트 스트림 관리 | 명시적인 조기 중단 제어와 함께 전용, 타입 안전 팩토리. | 강력하지만 수동 구독 관리 필요. | 수동 이벤트 리스너 + 취소. | 좋은 `fromEvent`, 경량. |
+| 성능 & 메모리 효율성 | 뛰어남 – 최적화된 `toUnordered()` 및 `toOrdered()` 수집기. | 매우 좋음, 하지만 연산자 체인이 오버헤드 추가. | 탁월함 (오버헤드 없음). | 탁월함. |
+| 번들 크기 | 매우 가벼움. | 큼 (트리 쉐이킹 사용 시에도). | 제로 (네이티브). | 작음. |
+| API 설계 철학 | 명시적 인덱싱을 가진 함수형 수집기 패턴. | 반응형 Observable 패턴. | Iterator / Generator 패턴. | 함수형, 포인트 프리(Point-free). |
+| 조기 종료 및 제어 | 명시적 (`interrupt`, `.limit()`, `.takeWhile()`, `.sub()`). | 좋음 (`take`, `takeUntil`, `first`). | 수동 (`for await…of` 안의 `break`). | 좋음 (`take`, `until`). |
+| 동기 및 비동기 지원 | 통합 API – 양쪽 모두에 대한 일급 지원. | 주로 비동기. | 둘 다, 그러나 수동. | 주로 비동기. |
+| 학습 곡선 | 함수형 및 인덱싱된 파이프라인에 익숙한 개발자에게 완만함. | 가파름 (많은 연산자, 핫/콜드 Observable). | 낮음. | 중간. |
+
+Semantic-TypeScript의 주요 장점
+
+•   고유한 내장 통계 및 인덱싱 기능으로, 수동 `reduce` 또는 외부 라이브러리의 필요성을 없앱니다.
+
+•   이벤트 스트림에 대한 명시적 제어로 RxJS에서 흔히 발생하는 메모리 누수를 방지합니다.
+
+•   통합된 동기/비동기 설계로 다양한 사용 사례에 대해 단일하고 일관된 API를 제공합니다.
+
+이 비교는 Semantic-TypeScript가 기존의 반응형 라이브러리의 번잡함 없이도 성능, 타입 안전성, 풍부한 분석 기능을 요구하는 현대 타입스크립트 프론트엔드 애플리케이션에 특히 적합한 이유를 보여줍니다.
+
+---
+
+### 탐구할 준비가 되셨나요?
+
+Semantic-TypeScript는 복잡한 데이터 흐름을 가독성 있고 구성 가능하며 고성능 파이프라인으로 변환합니다. 실시간 UI 이벤트를 처리하든, 대규모 데이터 세트를 처리하든, 분석 대시보드를 구축하든, 데이터베이스 수준의 인덱싱의 힘과 함수형 프로그래밍의 우아함을 동시에 제공합니다.
+
+다음 단계:
+
+•   IDE에서 완전한 타이핑된 API를 탐색하세요 (모든 내보내기는 메인 패키지에서 제공됩니다).
+
+•   복잡한 비동기 이터레이터를 깨끗한 Semantic 파이프라인으로 대체한 개발자 커뮤니티에 합류하세요.
+
+Semantic-TypeScript — 스트림이 구조를 만나는 곳.
 
-Semantic-TypeScript는 엄격하게 설계되고 타입 안전하며 고성능의 스트림 처리 라이브러리를 추구하는 개발자를 위해 구축되었습니다. 이는 엔터프라이즈 수준의 데이터 변환 패턴의 힘을 TypeScript 생태계에 가져오며, 데이터 중심의 프론트엔드 애플리케이션, Node.js 데이터 처리 및 시퀀스를 우아하고 효율적으로 처리해야 하는 모든 시나리오에 완벽하게 적합합니다.
+오늘부터 구축을 시작하고 사려 깊은 인덱싱이 제공하는 차이를 경험해 보세요.
 
-[![GitHub](./GitHub.png)](https://github.com/eloyhere/semantic-typescript)  [![NPM](./NPM.png)](https://www.npmjs.com/package/semantic-typescript) 
+명확하게 구축하고, 자신 있게 나아가며, 의도를 가지고 데이터를 변형하세요.