semantic-typescript 0.5.3 → 0.6.0

package/readme.kr.md

@@ -1,478 +1,209 @@
-# 시맨틱 타입스크립트 스트림 처리 라이브러리
+# Semantic-TypeScript: 패러다임을 바꾸는 스트림 처리 라이브러리
 
 ## 소개
+Semantic-TypeScript는 스트림 처리 기술의 중요한 발전을 나타내며, JavaScript GeneratorFunctions, Java Streams, 데이터베이스 인덱싱 패러다임의 가장 효과적인 개념들을 종합했습니다. 그 핵심 설계 원칙은 정교한 지연 평가(lazy evaluation)와 지능형 인덱싱을 통해 매우 효율적인 데이터 처리 파이프라인을 구축하는 데 중점을 두고 있습니다. 이 라이브러리는 현대적인 TypeScript 및 JavaScript 개발을 위해 특별히 설계된 엄격한 타입 안전성과 함수형 순수성을 갖춘 스트리밍 작업 경험을 제공합니다.
 
-시맨틱 타입스크립트는 자바스크립트의 제너레이터 함수, 자바 스트림, 그리고 MySQL 인덱스에서 영감을 받은 현대적인 스트림 처리 라이브러리입니다. 그 핵심 설계 철학은 데이터 인덱싱을 사용하여 효율적인 데이터 처리 파이프라인을 구축하는 것에 기반을 두고 있으며, 프론트엔드 개발을 위한 타입 안전하고 함수형 스타일의 스트리밍 작업 경험을 제공합니다.
+기존의 동기식 처리 아키텍처와 대조적으로, Semantic-TypeScript는 동기식(Iterable) 및 비동기식(AsyncIterable) 데이터 소스를 모두 우아하게 처리하는 통합 모델을 구현합니다. 스트림 생성 중 데이터의 흐름과 종료는 콜백 메커니즘에 의해 정밀하게 제어되어 라이브러리가 예외적인 우아함으로 다음을 처리할 수 있게 합니다:
+- 결정론적 제어가 가능한 실시간 데이터 스트림(DOM 이벤트, WebSockets, 간격)
+- 메모리 효율적이고 지연 평가되는 파이프라인을 통한 대규모 데이터셋
+- 유창하고 선언적인 API를 통한 복잡한 데이터 변환
 
-전통적인 동기 처리와 달리, 시맨틱은 비동기 처리 모델을 사용합니다. 데이터 스트림을 생성할 때, 터미널이 데이터를 수신하는 시간은 업스트림이 `accept`와 `interrupt` 콜백 함수를 호출하는 시점에 전적으로 의존합니다. 이러한 디자인은 라이브러리가 실시간 데이터 스트림, 대규모 데이터 세트 및 비동기 데이터 소스를 우아하게 처리할 수 있게 해줍니다.
+이 라이브러리의 혁신적인 접근 방식은 개발자가 데이터 시퀀스와 상호작용하는 방식을 근본적으로 재구상하며, 단일하고 응집력 있는 패키지 내에서 전례 없는 성능 특성과 개발자 인체공학을 모두 제공합니다.
 
-## 설치
-
-```bash
-npm install semantic-typescript
-```
+## 핵심 철학: 정의와 실행의 분리
+Semantic-TypeScript의 중요한 아키텍처적 통찰은 스트림의 정의와 실행을 명확하게 분리하는 것입니다:
+- **Semantic<E>**: 데이터 변환 파이프라인의 불변(immutable)하고 지연 평가(lazy)되는 설계도입니다. 어떤 연산(filter, map 등)이 수행될지 정의합니다.
+- **Collectable<E>**: 스트림의 구체화되고 실행 가능한 뷰입니다. Semantic에서 얻어지며, 파이프라인을 실행하고 결과를 생성하기 위한 모든 최종 연산(collect, forEach 등)을 제공합니다.
 
-## 기본 타입
-
-| 타입 | 설명 |
-|------|-------------|
-| `Invalid<T>` | `null` 또는 `undefined`에서 확장된 타입 |
-| `Valid<T>` | `null`과 `undefined`를 제외한 타입 |
-| `MaybeInvalid<T>` | `null` 또는 `undefined`일 수 있는 타입 |
-| `Primitive` | 기본 타입의 집합 |
-| `MaybePrimitive<T>` | 기본 타입일 수 있는 타입 |
-| `OptionalSymbol` | `Optional` 클래스의 심볼 식별자 |
-| `SemanticSymbol` | `Semantic` 클래스의 심볼 식별자 |
-| `CollectorsSymbol` | `Collector` 클래스의 심볼 식별자 |
-| `CollectableSymbol` | `Collectable` 클래스의 심볼 식별자 |
-| `OrderedCollectableSymbol` | `OrderedCollectable` 클래스의 심볼 식별자 |
-| `WindowCollectableSymbol` | `WindowCollectable` 클래스의 심볼 식별자 |
-| `StatisticsSymbol` | `Statistics` 클래스의 심볼 식별자 |
-| `NumericStatisticsSymbol` | `NumericStatistics` 클래스의 심볼 식별자 |
-| `BigIntStatisticsSymbol` | `BigIntStatistics` 클래스의 심볼 식별자 |
-| `UnorderedCollectableSymbol` | `UnorderedCollectable` 클래스의 심볼 식별자 |
-
-## 함수 지향 인터페이스
-
-| 인터페이스 | 설명 |
-|-----------|-------------|
-| `Runnable` | 매개변수가 없고 반환값도 없는 함수 |  
-| `Supplier<R>` | 매개변수가 없고 `R`을 반환하는 함수 |  
-| `Functional<T, R>` | 단일 매개변수 변환 함수 |
-| `BiFunctional<T, U, R>` | 두 개의 매개변수 변환 함수 |
-| `TriFunctional<T, U, V, R>` | 세 개의 매개변수 변환 함수 |
-| `Predicate<T>` | 단일 매개변수 조건 함수 |
-| `BiPredicate<T, U>` | 두 개의 매개변수 조건 함수 |
-| `TriPredicate<T, U, V>` | 세 개의 매개변수 조건 함수 |
-| `Consumer<T>` | 단일 매개변수 소비자 함수 |
-| `BiConsumer<T, U>` | 두 개의 매개변수 소비자 함수 |
-| `TriConsumer<T, U, V>` | 세 개의 매개변수 소비자 함수 |
-| `Comparator<T>` | 두 개의 매개변수 비교 함수 |
-| `Generator<T>` | 생성자 함수(핵심 및 기반) |
+이러한 분리는 깔끔한 멘탈 모델을 강제하고, 불필요한 정렬을 건너뛰어 최대 속도를 내는 UnorderedCollectable을 선택하는 것과 같은 강력한 최적화를 가능하게 합니다.
 
-```typescript
-// 타입 사용 예
-let predicate: Predicate<number> = (n: number): boolean => n > 0;
-let mapper: Functional<string, number> = (text: string): number => text.length;
-let comparator: Comparator<number> = (a: number, b: number): number => a - b;
-```
-
-## 타입 가드
-
-| 함수 | 설명 | 시간 복잡도 | 공간 복잡도 |
-|------|------|------------|------------|
-| `validate<T>(t: MaybeInvalid<T>): t is T` | 값이 null이나 undefined가 아닌지 검증 | O(1) | O(1) |
-| `invalidate<T>(t: MaybeInvalid<T>): t is null \| undefined` | 값이 null이나 undefined인지 검증 | O(1) | O(1) |
-| `isBoolean(t: unknown): t is boolean` | boolean인지 확인 | O(1) | O(1) |
-| `isString(t: unknown): t is string` | 문자열인지 확인 | O(1) | O(1) |
-| `isNumber(t: unknown): t is number` | 숫자인지 확인 | O(1) | O(1) |
-| `isFunction(t: unknown): t is Function` | 함수인지 확인 | O(1) | O(1) |
-| `isObject(t: unknown): t is object` | 객체인지 확인 | O(1) | O(1) |
-| `isSymbol(t: unknown): t is symbol` | 심볼인지 확인 | O(1) | O(1) |
-| `isBigint(t: unknown): t is bigint` | BigInt인지 확인 | O(1) | O(1) |
-| `isPrimitive(t: unknown): t is Primitive` | 기본 타입인지 확인 | O(1) | O(1) |
-| `isIterable(t: unknown): t is Iterable<unknown>` | 반복 가능한 객체인지 확인 | O(1) | O(1) |
-| `isOptional(t: unknown): t is Optional<unknown>` | Optional 인스턴스인지 확인 | O(1) | O(1) |
-| `isSemantic(t: unknown): t is Semantic<unknown>` | Semantic 인스턴스인지 확인 | O(1) | O(1) |
-| `isCollector(t: unknown): t is Collector<unknown, unknown, unknown>` | Collector 인스턴스인지 확인 | O(1) | O(1) |
-| `isCollectable(t: unknown): t is Collectable<unknown>` | Collectable 인스턴스인지 확인 | O(1) | O(1) |
-| `isOrderedCollectable(t: unknown): t is OrderedCollectable<unknown>` | OrderedCollectable 인스턴스인지 확인 | O(1) | O(1) |
-| `isWindowCollectable(t: unknown): t is WindowCollectable<unknown>` | WindowCollectable 인스턴스인지 확인 | O(1) | O(1) |
-| `isUnorderedCollectable(t: unknown): t is UnorderedCollectable<unknown>` | UnorderedCollectable 인스턴스인지 확인 | O(1) | O(1) |
-| `isStatistics(t: unknown): t is Statistics<unknown, number \| bigint>` | Statistics 인스턴스인지 확인 | O(1) | O(1) |
-| `isNumericStatistics(t: unknown): t is NumericStatistics<unknown>` | NumericStatistics 인스턴스인지 확인 | O(1) | O(1) |
-| `isBigIntStatistics(t: unknown): t is BigIntStatistics<unknown>` | BigIntStatistics 인스턴스인지 확인 | O(1) | O(1) |
-| `isPromise(t: unknown): t is Promise<unknown>` | Promise 객체인지 확인 | O(1) | O(1) |
-| `isAsync(t: unknown): t is AsyncFunction` | AsyncFunction인지 확인 | O(1) | O(1) |
-
-```typescript
-// 타입 가드 사용 예
-let value: unknown = "hello";
+## Semantic-TypeScript를 선택해야 하는 이유
+데이터 스트림 처리를 위한 적절한 라이브러리를 선택하는 것은 성능, 타입 안전성, 표현력 사이의 균형을 맞추는 것을 포함합니다. Semantic-TypeScript는 이러한 모든 차원에서 탁월한 성능을 발휘하도록 설계되었습니다.
 
-if (isString(value)) {
-    console.log(value.length); // 타입 안전, value는 문자열로 추론됩니다.
-}
+### 1. 모든 데이터 시퀀스를 위한 통일되고 타입 안전한 패러다임
+정적 배열, 실시간 이벤트, 비동기 청크 등 모든 데이터 시퀀스를 처리하기 위한 일관적이고 선언적인 API를 제공하며, TypeScript의 모든 기능을 활용하여 엔드-투-엔드 타입 안전성을 보장합니다. 이는 런타임 오류의 전체 범주를 제거하고 스트림 조작을 예측 가능하고 컴파일러 검증이 가능한 활동으로 전환합니다.
 
-if (isOptional(someValue)) {
-    someValue.ifPresent((value): void => console.log(val));
-}
+### 2. 지능형 지연 평가를 통한 타협 없는 성능
+핵심은 지연 평가에 기반합니다. filter, map, flatMap과 같은 연산은 단지 처리 파이프라인을 구성할 뿐이며, 최종 연산이 호출될 때까지 어떤 작업도 수행되지 않습니다. 이는 제한(limit), anyMatch 또는 사용자 정의 중단(interrupt) 콜백을 통한 단락 평가(short-circuiting) 기능과 결합되어 처리를 조기에 중지할 수 있게 하여, 크거나 무한한 스트림에 대한 효율성을 극적으로 향상시킵니다.
 
-if(isIterable(value)){
-    // 타입 안전, 이제 반복 가능한 객체입니다.
-    for(let item of value){
-        console.log(item);
-    }
-}
-```
+### 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()`
 
-| 함수 | 설명 | 시간 복잡도 | 공간 복잡도 |
-|------|------|------------|------------|
-| `useCompare<T>(t1: T, t2: T): number` | 일반 비교 함수 | O(1) | O(1) |
-| `useRandom<T = number \| bigint>(index: T): T` | 의사 난수 생성기 | O(log n) | O(1) |
+### 5. 기본 집계를 넘어선: 내장 통계 분석
+단순한 합계와 평균을 넘어서세요. 라이브러리는 전용 NumericStatistics 및 BigIntStatistics 인터페이스를 제공하며, 스트림에서 직접 고급 통계 측정값(분산, 표준 편차, 중앙값, 왜도, 첨도)에 즉시 액세스할 수 있습니다. 이는 복잡한 데이터 분석을 한 줄의 코드로 바꿉니다.
 
-```typescript
-// 유틸리티 함수 사용 예
-let numbers: Array<number> = [3, 1, 4, 1, 5];
-numbers.sort(useCompare); // [1, 1, 3, 4, 5]
+### 6. 개발자 인체공학을 위해 설계됨
+- **유창하고 연결 가능한 API**: 복잡한 데이터 파이프라인을 읽기 쉽고 순차적인 체인으로 작성
+- **포괄적인 유틸리티 모음**: 필수 가드(isFunction, isIterable), 유틸리티(useCompare, useTraverse) 및 함수형 인터페이스 포함
+- **Optional<T> 통합**: 값의 부재를 안전하게 모델링하여 널 포인터 문제 해결
+- **성능 가이드**: 순서 대 속도에 대해 언제 비정렬(unordered) 컬렉션을 사용하고 언제 정렬(ordered)을 사용할지에 대한 명확한 지침
 
-let randomNum = useRandom(42); // 시드 기반 난수
+## 설치
+```bash
+npm install semantic-typescript
 ```
 
-## 팩토리 메소드
+## 실제 적용에서의 핵심 개념
 
-### 옵셔널 팩토리 메소드
-
-| 메소드 | 설명 | 시간 복잡도 | 공간 복잡도 |
-|------|------|------------|------------|
-| `Optional.empty<T>()` | 빈 옵셔널을 생성 | O(1) | O(1) |
-| `Optional.of<T>(value)` | 값을 포함하는 옵셔널을 생성 | O(1) | O(1) |
-| `Optional.ofNullable<T>(value)` | 비어있을 수 있는 옵셔널을 생성 | O(1) | O(1) |
-| `Optional.ofNonNull<T>(value)` | 비어있지 않은 옵셔널을 생성 | O(1) | O(1) |
+### 1. 스트림 생성 (Semantic)
+팩토리 함수를 사용하여 다양한 소스로부터 스트림을 생성할 수 있습니다.
 
 ```typescript
-// 옵셔널 사용 예
-let empty: Optional<number> = Optional.empty();
-let present: Optional<number> = Optional.of(42);
-let nullable: Optional<string> = Optional.ofNullable<string>(null);
-let nonNull: Optional<string> = Optional.ofNonNull("hello");
-
-present.ifPresent((val: number): void => console.log(val)); // 42 출력
-console.log(emptyOpt.get(100)); // 100 출력
-```
+import { useFrom, useInterval, useDocument } from 'semantic-typescript';
 
-### 컬렉터 팩토리 메소드
+// 정적 배열로부터
+const staticStream = useFrom([1, 2, 3, 4, 5]);
 
-| 메소드 | 설명 | 시간 복잡도 | 공간 복잡도 |
-|------|------|------------|------------|
-| `Collector.full(identity, accumulator, finisher)` | 완전한 컬렉터를 생성 | O(1) | O(1) |
-| `Collector.shortable(identity, interruptor, accumulator, finisher)` | 중단 가능한 컬렉터를 생성 | O(1) | O(1) |
+// 비동기 제너레이터로부터
+const asyncStream = useFrom(async function*() {
+  yield 1;
+  yield 2;
+});
 
-```typescript
-// 컬렉터 변환 예
-let numbers = from([3, 1, 4, 1, 5, 9, 2, 6, 5]);
-
-// 성능 우선: 순서가 보장되지 않는 컬렉터 사용
-let unordered = numbers
-    .filter((n: number): boolean => n > 3)
-    .toUnordered(); // 최고의 성능
-
-// 정렬 필요: 순서가 보장되는 컬렉터 사용
-let ordered = numbers.sorted();
-
-// 요소 수 계산
-let count = Collector.full(
-    (): number => 0, // 초기값
-    (accumulator: number, element: number): number => accumulator + element, // 누적
-    (accumulator: number): number => accumulator // 완료
-);
-count.collect(from([1,2,3,4,5])); // 스트림에서 카운트
-count.collect([1,2,3,4,5]); // 반복 가능한 객체에서 카운트
-
-let find = Collector.shortable(
-    (): Optional<number> => Optional.empty(), // 초기값
-    (element: number, index: bigint, accumulator: Optional<number>): Optional<number> => accumulator.isPresent(), // 중단
-    (accumulator: Optional<number>, element: number, index: bigint): Optional<number> => Optional.of(element), // 누적
-    (accumulator: Optional<number>): Optional<number> => accumulator // 완료
-);
-find.collect(from([1,2,3,4,5])); // 첫 번째 요소 찾기
-find.collect([1,2,3,4,5]); // 첫 번째 요소 찾기
-```
-
-### 시맨틱 팩토리 메소드
+// 시간 기반 스트림
+const tickStream = useInterval(1000); // 매초마다 방출
 
-| 메소드 | 설명 | 시간 복잡도 | 공간 복잡도 |
-|------|------|------------|------------|
-| `animationFrame(period: number, delay: number = 0)` | 시간 기반 애니메이션 프레임 스트림을 생성 | O(1)* | O(1) |
-| `blob(blob, chunkSize)` | Blob에서 스트림을 생성 | O(n) | O(chunkSize) |
-| `empty<E>()` | 빈 스트림을 생성 | O(1) | O(1) |
-| `fill<E>(element, count)` | 채워진 스트림을 생성 | O(n) | O(1) |
-| `from<E>(iterable)` | 반복 가능한 객체에서 스트림을 생성 | O(1) | O(1) |
-| `interval(period, delay?)` | 시간 기반 인터벌 스트림을 생성 | O(1)* | O(1) |
-| `iterate<E>(generator)` | 생성자에서 스트림을 생성 | O(1) | O(1) |
-| `range(start, end, step)` | 숫자 범위 스트림을 생성 | O(n) | O(1) |
-| `websocket(websocket)` | WebSocket에서 스트림을 생성 | O(1) | O(1) |
-
-```typescript
-// 시맨틱 팩토리 메소드 사용 예
-
-// Blob에서 스트림을 생성(청크 읽기)
-blob(someBlob, 1024n)
-    .toUnordered()
-    .write(WritableStream)
-    .then(callback) // 스트림 쓰기 성공
-    .catch(callback); // 스트림 쓰기 실패
-
-// 빈 스트림을 생성, 다른 스트림과 연결될 때까지 실행되지 않음
-empty<string>()
-    .toUnordered()
-    .join(); // []
-
-// 채워진 스트림을 생성
-const filledStream = fill("hello", 3); // "hello", "hello", "hello"
-
-// 초기 지연 2초, 실행 주기 5초의 시간 기반 스트림을 생성, 타이머 메커니즘에 기반하여 구현됩니다. 시스템 스케줄링의 정확도 제한으로 인해 시간 드리프트가 발생할 수 있습니다.
-const intervalStream = interval(5000, 2000);
-
-// 반복 가능한 객체에서 스트림을 생성
-const numberStream = from([1, 2, 3, 4, 5]);
-const stringStream = from(new Set(["Alex", "Bob"]));
-
-// 숫자 범위 스트림을 생성
-const rangeStream = range(1, 10, 2); // 1, 3, 5, 7, 9
-
-// WebSocket 이벤트 스트림
-const ws = new WebSocket("ws://localhost:8080");
-websocket(ws)
-  .filter((event): boolean => event.type === "message") // 메시지 이벤트만 듣기
-  .toUnordered() // 이벤트는 일반적으로 순서가 없음
-  .forEach((event): void => receive(event)); // 메시지 받기
+// DOM 이벤트 스트림 (아래의 중요한 참고사항 참조)
+const clickStream = useDocument('click');
 ```
 
-## 시맨틱 클래스 메소드
-
-| 메소드 | 설명 | 시간 복잡도 | 공간 복잡도 |
-|------|------|------------|------------|
-| `concat(other)` | 두 개의 스트림을 연결 | O(n) | O(1) |
-| `distinct()` | 중복을 제거 | O(n) | O(n) |
-| `distinct(comparator)` | 비교자를 사용하여 중복을 제거 | O(n²) | O(n) |
-| `dropWhile(predicate)` | 조건을 만족하는 요소를 버림 | O(n) | O(1) |
-| `filter(predicate)` | 요소를 필터링 | O(n) | O(1) |
-| `flat(mapper)` | 평탄화 맵 | O(n × m) | O(1) |
-| `flatMap(mapper)` | 새로운 타입으로 평탄화 맵 | O(n × m) | O(1) |
-| `limit(n)` | 요소 수 제한 | O(n) | O(1) |
-| `map(mapper)` | 맵 변환 | O(n) | O(1) |
-| `peek(consumer)` | 요소를 엿보기 | O(n) | O(1) |
-| `redirect(redirector)` | 인덱스 리디렉션 | O(n) | O(1) |
-| `reverse()` | 스트림 반전 | O(n) | O(1) |
-| `shuffle()` | 무작위로 섞기 | O(n) | O(1) |
-| `shuffle(mapper)` | 매퍼를 사용하여 섞기 | O(n) | O(1) |
-| `skip(n)` | 처음 n개 요소 건너뛰기 | O(n) | O(1) |
-| `sorted()` | 정렬 | O(n log n) | O(n) |
-| `sorted(comparator)` | 비교자를 사용하여 정렬 | O(n log n) | O(n) |
-| `sub(start, end)` | 서브스트림 가져오기 | O(n) | O(1) |
-| `takeWhile(predicate)` | 조건을 만족하는 요소 가져오기 | O(n) | O(1) |
-| `translate(offset)` | 인덱스 변환 | O(n) | O(1) |
-| `translate(translator)` | 변환자를 사용하여 인덱스 변환 | O(n) | O(1) |
+### 2. 스트림 변환 (중간 연산)
+연산은 지연 평가되며 파이프라인을 정의하기 위해 체인으로 연결됩니다.
 
 ```typescript
-// 시맨틱 작업 예
-const result = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
-    .filter((n: number): boolean => n % 2 === 0) // 짝수 필터링
-    .map((n: number): number => n * 2) // 2배
-    .skip(1) // 첫 번째 건너뛰기
-    .limit(3) // 3개 요소 제한
-    .toUnordered() // 순서가 보장되지 않는 컬렉터로 변환
-    .toArray(); // 배열로 변환
-// 결과: [8, 12, 20]
-
-// 복잡한 작업 예
-const complexResult = range(1, 100, 1)
-    .flatMap((n: number): Semantics<number> => from([n, n * 2])) // 각 요소를 두 개로 매핑
-    .distinct() // 중복 제거
-    .shuffle() // 순서 섞기
-    .takeWhile((n: number): boolean => n < 50) // 50 미만 요소 가져오기
-    .toOrdered() // 순서가 보장되는 컬렉터로 변환
-    .toArray(); // 배열로 변환
-```
-
-## 시맨틱 변환 메소드
-
-| 메소드 | 설명 | 시간 복잡도 | 공간 복잡도 |
-|------------|------------|------------|------------|
-| `sorted()` | 순서가 보장되는 컬렉터로 변환 | O(n log n) | O(n) |
-| `toUnordered()` | 순서가 보장되지 않는 컬렉터로 변환 | O(1) | O(1) |
-| `toOrdered()` | 순서가 보장되는 컬렉터로 변환 | O(1) | O(1) |
-| `toNumericStatistics()` | 숫자 통계로 변환 | O(n) | O(1) |
-| `toBigintStatistics()` | BigInt 통계로 변환 | O(n) | O(1) |
-| `toWindow()` | 윈도우 컬렉터로 변환 | O(1) | O(1) |
-| `toCollectable()` | `UnorderdCollectable`로 변환 | O(n) | O(1) |
-| `toCollectable(mapper)` | 커스텀 컬렉터로 변환 | O(n) | O(1) |
+const processedStream = staticStream
+  .filter(x => x % 2 === 0) // 짝수만 유지
+  .map(x => x * 10) // 10 곱하기
+  .flatMap(x => [x, x + 1]) // 각 요소를 두 개로 변환
+  .distinct(); // 중복 제거
 
-```typescript
-// 오름차순으로 정렬된 배열로 변환
-from([6,4,3,5,2]) // 스트림 생성
-    .sorted() // 스트림을 오름차순으로 정렬
-    .toArray(); // [2, 3, 4, 5, 6]
-
-// 내림차순으로 정렬된 배열로 변환
-from([6,4,3,5,2]) // 스트림 생성
-    .soted((a: number, b: number): number => b - a) // 스트림을 내림차순으로 정렬
-    .toArray(); // [6, 5, 4, 3, 2]
-
-// 역순의 배열로 리다이렉트
-from([6,4,3,5,2])
-    .redirect((element, index): bigint => -index) // 역순으로 리다이렉트
-    .toOrderd() // 리다이렉트된 순서 유지
-    .toArray(); // [2, 5, 3, 4, 6]
-
-// 리다이렉션을 무시하고 역순의 배열을 얻음
-from([6,4,3,5,2])
-    .redirect((element: number, index: bigint) => -index) // 역순으로 리다이렉트
-    .toUnorderd() // 리다이렉션된 순서 무시. 이 작업은 `redirect`, `reverse`, `shuffle` 및 `translate` 작업을 무시합니다
-    .toArray(); // [2, 5, 3, 4, 6]
-
-// 스트림을 역순으로 배열로 변환
-from([6, 4, 3, 5, 2])
-    .reverse() // 스트림을 역순으로 함
-    .toOrdered() // 역순을 보장함
-    .toArray(); // [2, 5, 3, 4, 6]
-
-// 섞인 스트림을 배열로 덮어쓰기
-from([6, 4, 3, 5, 2])
-    .shuffle() // 스트림을 섞음
-    .sorted() // 섞인 순서를 덮어씀. 이 작업은 `redirect`, `reverse`, `shuffle` 및 `translate` 작업을 덮어씀
-    .toArray(); // [2, 5, 3, 4, 6]
-
-// 윈도우 컬렉터로 변환
-from([6, 4, 3, 5, 2]).toWindow();
-
-// 숫자 통계로 변환
-from([6, 4, 3, 5, 2]).toNumericStatistics();
-
-// BigInt 통계로 변환
-from([6n, 4n, 3n, 5n, 2n]).toBigintStatistics();
-
-// 데이터 수집을 위한 커스텀 컬렉터 정의
-let customizedCollector = from([1, 2, 3, 4, 5])
-    .toCollectable((generator: Generator<E>) => new CustomizedCollector(generator));
+// 아직 아무것도 실행되지 않았습니다
 ```
 
-## Collectable의 수집 메소드
-
-| 메소드 | 설명 | 시간 복잡도 | 공간 복잡도 |
-|------|------|------------|------------|
-| `anyMatch(predicate)` | 임의의 요소가 일치하는지 여부 | O(n) | O(1) |
-| `allMatch(predicate)` | 모든 요소가 일치하는지 여부 | O(n) | O(1) |
-| `count()` | 요소 수 | O(n) | O(1) |
-| `isEmpty()` | 비어 있는지 여부 | O(1) | O(1) |
-| `findAny()` | 임의의 요소 찾기 | O(n) | O(1) |
-| `findFirst()` | 첫 번째 요소 찾기 | O(n) | O(1) |
-| `findLast()` | 마지막 요소 찾기 | O(n) | O(1) |
-| `forEach(action)` | 모든 요소 반복 | O(n) | O(1) |
-| `group(classifier)` | 분류자로 그룹화 | O(n) | O(n) |
-| `groupBy(keyExtractor, valueExtractor)` | 키-값 추출자로 그룹화 | O(n) | O(n) |
-| `join()` | 문자열로 결합 | O(n) | O(n) |
-| `join(delimiter)` | 구분자를 사용하여 결합 | O(n) | O(n) |
-| `nonMatch(predicate)` | 일치하지 않는 요소가 있는지 여부 | O(n) | O(1) |
-| `partition(count)` | 수로 분할 | O(n) | O(n) |
-| `partitionBy(classifier)` | 분류자로 분할 | O(n) | O(n) |
-| `reduce(accumulator)` | 축소 작업 | O(n) | O(1) |
-| `reduce(identity, accumulator)` | 초기값을 가진 축소 | O(n) | O(1) |
-| `toArray()` | 배열로 변환 | O(n) | O(n) |
-| `toMap(keyExtractor, valueExtractor)` | 맵으로 변환 | O(n) | O(n) |
-| `toSet()` | 세트로 변환 | O(n) | O(n) |
-| `write(stream)` | 스트림에 쓰기 | O(n) | O(1) |
+### 3. 스트림 실행 (최종 연산)
+결과를 얻으려면 Collectable을 얻고 최종 연산을 호출해야 합니다.
 
 ```typescript
-// Collectable 작업 예
-const data = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
-    .filter((n: number): boolean => n % 2 === 0)
-    .toOrdered();
-
-// 일치 여부 확인
-console.log(data.anyMatch((n: number): boolean => n > 5)); // true
-console.log(data.allMatch((n: number): boolean => n < 20)); // true
-
-// 찾기 작업
-data.findFirst().ifPresent((n: number): void => console.log(n)); // 2
-data.findAny().ifPresent((n: number): void => console.log(n)); // 임의의 요소
-
-// 그룹화 작업
-const grouped = data.groupBy(
-    (n: number): string => (n > 5 ? "큰" : "작은"),
-    (n: number): number => n * 2
-); // {작은: [4, 8], 큰: [12, 16, 20]}
-
-// 축소 작업
-const sum = data.reduce(0, (acc, n) => acc + n); // 30
-
-// 출력 작업
-data.join(", "); // "[2, 4, 6, 8, 10]"
+// 성능을 위한 비정렬(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
+);
 ```
 
-## 통계 분석 메소드
-
-### NumericStatistics 메소드
-
-| 메소드 | 설명 | 시간 복잡도 | 공간 복잡도 |
-|------|------|------------|------------|
-| `range()` | 범위 | O(n) | O(1) |
-| `variance()` | 분산 | O(n) | O(1) |
-| `standardDeviation()` | 표준 편차 | O(n) | O(1) |
-| `mean()` | 평균 | O(n) | O(1) |
-| `median()` | 중앙값 | O(n log n) | O(n) |
-| `mode()` | 최빈값 | O(n) | O(n) |
-| `frequency()` | 빈도 분포 | O(n) | O(n) |
-| `summate()` | 합계 | O(n) | O(1) |
-| `quantile(quantile)` | 사분위수 | O(n log n) | O(n) |
-| `interquartileRange()` | 사분위수 범위 | O(n log n) | O(n) |
-| `skewness()` | 왜도 | O(n) | O(1) |
-| `kurtosis()` | 첨도 | O(n) | O(1) |
+### 4. 중요: 이벤트 스트림 작업
+이벤트 스트림(useDocument, useWindow, useHTMLElement, useWebSocket)은 본질적으로 무한합니다. 언제 이벤트 수집을 중지하고 스트림을 완료할지 정의하기 위해 sub, takeWhile 또는 limit과 같은 연산을 사용해야 합니다. 그렇지 않으면 최종 연산이 무기한 대기합니다.
 
 ```typescript
-// 통계 분석 예
-let numbers = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
-    .toNumericStatistics();
-
-console.log("평균:", numbers.mean()); // 5.5
-console.log("중앙값:", numbers.median()); // 5.5
-console.log("표준 편차:", numbers.standardDeviation()); // ~2.87
-console.log("합계:", numbers.summate()); // 55
-
-// 매퍼를 사용한 통계 분석
-const objects = from([
-    { value: 10 },
-    { value: 20 },
-    { value: 30 }
-]).toNumericStatistics();
-console.log("매핑된 평균:", objects.mean(obj => obj.value)); // 20
+import { useDocument } from 'semantic-typescript';
+
+// 처음 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();
 ```
 
-## 성능 선택 가이드
-
-### 순서 보장이 필요 없는 Collector 선택(성능 우선)
-```typescript
-// 순서 보장이 필요 없는 경우, 최고의 성능을 위해 순서가 보장되지 않는 Collector 사용
-let highPerformance = data
-    .filter(predicate)
-    .map(mapper)
-    .toUnoredered(); // 최고의 성능
-```
+**핵심 통찰**: 이벤트(예: MouseEvent)와 그 순차적 발생 인덱스(빅인트)는 `accept(event, index)` 콜백을 통해 파이프라인을 함께 전달됩니다.
 
-### 순서가 필요한 Collector 선택(순서 필요)
+### 5. 통계 활용
 ```typescript
-// 요소의 순서를 유지해야 하는 경우, 순서가 보장되는 Collector 사용
-let ordered = data.sorted(comparator);
+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}`);
 ```
 
-### 윈도우 작업이 필요한 Collector 선택(윈도우 작업)
+## 주요 기능
+- **이중 스트림 유형**: 동기식 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
-// 윈도우 작업이 필요한 경우
-let windowed: WindowCollectable<number> = data
-    .toWindow()
-    .slide(5n, 2n); // 슬라이딩 윈도우
-```
+import { useFrom, useSummate, useGroupBy } from 'semantic-typescript';
 
-### 수치 계산이 필요한 통계 분석 선택(수치 계산)
-```typescript
-// 통계 분석이 필요한 경우
-let statistics: NumericStatistics<number> = data
-    .toNumericStatistics(); // 수치 통계
+interface Transaction {
+  id: number;
+  amount: number;
+  category: string;
+}
 
-let bigIntStatistics: BigintStatistics<bigint> = data
-    .toBigintStatistics(); // 큰 정수 통계
+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 }
 ```
 
-[GitHub](https://github.com/eloyhere/semantic-typescript)
-[NPMJS](https://www.npmjs.com/package/semantic-typescript)
-
-## 중요한 참고 사항
-
-1. **정렬 작업의 영향**: 순서가 보장되는 컬렉터에서 `sorted()` 작업은 `redirect`, `translate`, `shuffle`, `reverse`의 효과를 무시합니다.
-2. **성능 고려 사항**: 순서 보장이 필요하지 않은 경우, `toUnordered()`를 사용하여 성능을 향상시키는 것이 좋습니다.
-3. **메모리 사용량**: 정렬 작업에는 추가적인 O(n)의 메모리가 필요합니다.
-4. **실시간 데이터**: 시맨틱 스트림은 실시간 데이터 처리에 적합하며 비동기 데이터 소스를 지원합니다.
+Semantic-TypeScript는 엄격하게 설계되고 타입 안전하며 고성능의 스트림 처리 라이브러리를 추구하는 개발자를 위해 구축되었습니다. 이는 엔터프라이즈 수준의 데이터 변환 패턴의 힘을 TypeScript 생태계에 가져오며, 데이터 중심의 프론트엔드 애플리케이션, Node.js 데이터 처리 및 시퀀스를 우아하고 효율적으로 처리해야 하는 모든 시나리오에 완벽하게 적합합니다.
 
-이 라이브러리는 타입스크립트 개발자에게 강력하고 유연한 스트리밍 기능을 제공하며, 함수형 프로그래밍의 이점과 타입 안전성 보장을 결합합니다.
+[![GitHub](./GitHub.png)](https://github.com/eloyhere/semantic-typescript)  [![NPM](./NPM.png)](https://www.npmjs.com/package/semantic-typescript)