semantic-typescript 0.0.7 → 0.1.4

package/readme.kr.md

@@ -1,335 +1,427 @@
-# 📘 semantic-typescript
+# Semantic-TypeScript 스트림 처리 라이브러리
 
-TypeScript에서 **의미론적 데이터 처리(Semantic Data Processing)** 를 위한 강력하고 타입 안전한 유틸리티 라이브러리입니다.  
-컬렉션, 스트림, 시퀀스를 함수형 스타일로 다룰 수 있는 구성 요소들을 제공하며, 정렬, 필터링, 그룹화, 통계 분석 등을 지원합니다.
+## 소개
 
-**정렬된 데이터든 정렬되지 않은 데이터든**, **통계 분석을 하든**, 혹은 단순히 **연산을 유창하게 연결(chain)하고 싶든**, 이 라이브러리가 도와드립니다.
+Semantic-TypeScript는 JavaScript GeneratorFunction, Java Stream 및 MySQL Index에서 영감을 받은 현대적인 스트림 처리 라이브러리입니다. 이 라이브러리의 핵심 설계는 데이터 인덱스를 기반으로 효율적인 데이터 처리 파이프라인을 구축하여 프론트엔드 개발자에게 타입 안전성과 함수형 스타일의 스트림 조작 경험을 제공합니다.
 
----
+기존의 동기식 처리와 달리 Semantic은 비동기 처리 모드를 채택합니다. 데이터 스트림을 생성할 때, 터미널이 데이터를 수신하는 시점은 업스트림이 `accept` 및 `interrupt` 콜백 함수를 언제 호출하는지에 전적으로 의존합니다. 이 설계는 라이브러리가 실시간 데이터 스트림, 대규모 데이터 세트 및 비동기 데이터 소스를 우아하게 처리할 수 있도록 합니다.
 
-## 🧩 주요 기능
-
-- ✅ 전체적으로 **타입 안전한 제네릭(Type-safe Generics)**
-- ✅ **함수형 프로그래밍 스타일** (map, filter, reduce 등)
-- ✅ **의미론적 데이터 스트림(Semantic<E>)** - 지연 평가(Lazy Evaluation) 지원
-- ✅ 스트림을 구조화된 데이터로 변환하는 **컬렉터(Collectors)**
-- ✅ **정렬된(Sorted) 및 비정렬된(Unordered) 컬렉터** — `toUnordered()`는 **가장 빠르며 정렬하지 않음**
-- ✅ `sorted()`, `toOrdered()`, 비교자(Comparator)를 통한 **정렬 기능**
-- ✅ **통계 분석(Statistics)** (`NumericStatistics`, `BigIntStatistics` 등)
-- ✅ **Optional<T>** — null 또는 undefined 값을 안전하게 다루는 모나드(Monad)
-- ✅ **반복자(Iterator) & 생성기(Generator)** 기반 설계 — 대규모 또는 비동기 데이터에도 적합
-
----
-
-## 📦 설치
+## 설치
 
 ```bash
 npm install semantic-typescript
 ```
 
----
-
-## 🧠 핵심 개념
-
-### 1. `Optional<T>` — null/undefined 값 안전하게 처리
-
-값이 null 또는 undefined 일 수 있는 경우를 안전하게 처리할 수 있는 모나딕(Monadic) 컨테이너입니다.
-
-#### 메서드:
-
-| 메서드 | 설명 | 예제 |
-|--------|------|------|
-| `of(value)` | 값 감싸기 (null 가능) | `Optional.of(null)` |
-| `ofNullable(v)` | null 허용하여 감싸기 | `Optional.ofNullable(someVar)` |
-| `ofNonNull(v)` | null이면 예외 발생 | `Optional.ofNonNull(5)` |
-| `get()` | 값 가져오기 (없으면 예외) | `opt.get()` |
-| `getOrDefault(d)` | 값 가져오기 또는 기본값 | `opt.getOrDefault(0)` |
-| `ifPresent(fn)` | 값이 있으면 부작용 실행 | `opt.ifPresent(x => console.log(x))` |
-| `map(fn)` | 값이 있으면 변환 | `opt.map(x => x + 1)` |
-| `filter(fn)` | 조건을 만족하는 값만 유지 | `opt.filter(x => x > 0)` |
-| `isEmpty()` | 비어있는지 확인 | `opt.isEmpty()` |
-| `isPresent()` | 값이 있는지 확인 | `opt.isPresent()` |
+## 기본 타입
 
-#### 예제:
+| 타입 | 설명 |
+|------|------|
+| `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>` | 단일 매개변수 변환 함수 |
+| `Predicate<T>` | 단일 매개변수 조건 함수 |
+| `BiFunctional<T, U, R>` | 이중 매개변수 변환 함수 |
+| `BiPredicate<T, U>` | 이중 매개변수 조건 함수 |
+| `Comparator<T>` | 비교 함수 |
+| `TriFunctional<T, U, V, R>` | 삼중 매개변수 변환 함수 |
+| `Consumer<T>` | 단일 매개변수 소비 함수 |
+| `BiConsumer<T, U>` | 이중 매개변수 소비 함수 |
+| `TriConsumer<T, U, V>` | 삼중 매개변수 소비 함수 |
+| `Generator<T>` | 생성기 함수 |
 
 ```typescript
-import { Optional } from 'semantic-typescript';
-
-const value: number | null = Math.random() > 0.5 ? 10 : null;
-
-const opt = Optional.ofNullable(value);
-
-const result = opt
-  .filter(v => v > 5)
-  .map(v => v * 2)
-  .getOrDefault(0);
-
-console.log(result); // 20 또는 0
+// 타입 사용 예제
+const predicate: Predicate<number> = (n) => n > 0;
+const mapper: Functional<string, number> = (str) => str.length;
+const comparator: Comparator<number> = (a, b) => 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` | 불리언 여부 확인 | 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) |
 
-### 2. `Semantic<E>` — 지연 평가 데이터 스트림
+```typescript
+// 타입 가드 사용 예제
+const value: unknown = "hello";
 
-요소들의 **지연 평가(Lazy), 구성 가능한 시퀀스**입니다. Java의 Streams나 Kotlin의 Sequences와 유사합니다.
+if (isString(value)) {
+    console.log(value.length); // 타입 안전, value는 string으로 추론
+}
 
-`from()`, `range()`, `iterate()`, `fill()` 같은 헬퍼 함수로 `Semantic` 스트림을 생성할 수 있습니다.
+if (isOptional(someValue)) {
+    someValue.ifPresent(val => console.log(val));
+}
+```
 
-#### 생성 방법:
+## 유틸리티 함수
 
-| 함수 | 설명 | 예제 |
-|------|------|------|
-| `from(iterable)` | 배열, Set, 반복 가능한 객체로부터 생성 | `from([1, 2, 3])` |
-| `range(start, end, step?)` | 숫자 범위 생성 | `range(0, 5)` → 0,1,2,3,4 |
-| `fill(element, count)` | 요소를 N번 반복 | `fill('a', 3n)` |
-| `iterate(gen)` | 사용자 정의 생성기 함수 사용 | `iterate(genFn)` |
+| 함수 | 설명 | 시간 복잡도 | 공간 복잡도 |
+|------|------|------------|------------|
+| `useCompare<T>(t1: T, t2: T): number` | 범용 비교 함수 | O(1) | O(1) |
+| `useRandom<T = number \| bigint>(index: T): T` | 의사 난수 생성기 | O(log n) | O(1) |
 
-#### 주요 연산자:
+```typescript
+// 유틸리티 함수 사용 예제
+const numbers = [3, 1, 4, 1, 5];
+numbers.sort(useCompare); // [1, 1, 3, 4, 5]
 
-| 메서드 | 설명 | 예제 |
-|--------|------|------|
-| `map(fn)` | 각 요소 변환 | `.map(x => x * 2)` |
-| `filter(fn)` | 조건을 만족하는 요소만 유지 | `.filter(x => x > 10)` |
-| `limit(n)` | 처음 N개 요소로 제한 | `.limit(5)` |
-| `skip(n)` | 처음 N개 요소 건너뛰기 | `.skip(2)` |
-| `distinct()` | 중복 제거 (기본적으로 Set 사용) | `.distinct()` |
-| `sorted()` | 요소 정렬 (자연 순서) | `.sorted()` |
-| `sorted(comparator)` | 커스텀 정렬 | `.sorted((a, b) => a - b)` |
-| `toOrdered()` | 정렬 후 `OrderedCollectable` 반환 | `.toOrdered()` |
-| `toUnordered()` | **정렬 없음 – 가장 빠름** | `.toUnordered()` ✅ |
-| `collect(collector)` | 컬렉터로 집계 | `.collect(Collector.full(...))` |
-| `toArray()` | 배열로 변환 | `.toArray()` |
-| `toSet()` | Set으로 변환 | `.toSet()` |
-| `toMap(keyFn, valFn)` | Map으로 변환 | `.toMap(x => x.id, x => x)` |
+const randomNum = useRandom(42); // 시드 기반 난수
+const randomBigInt = useRandom(1000n); // BigInt 난수
+```
 
----
+## 팩토리 메서드
 
-### 3. `toUnordered()` — 🚀 가장 빠름, 정렬 없음
+### Optional 팩토리 메서드
 
-**정렬이 필요 없고 최고의 성능을 원한다면** 아래와 같이 사용하세요:
+| 메서드 | 설명 | 시간 복잡도 | 공간 복잡도 |
+|--------|------|------------|------------|
+| `Optional.empty<T>()` | 빈 Optional 생성 | O(1) | O(1) |
+| `Optional.of<T>(value)` | 값을 가진 Optional 생성 | O(1) | O(1) |
+| `Optional.ofNullable<T>(value)` | null 허용 Optional 생성 | O(1) | O(1) |
+| `Optional.ofNonNull<T>(value)` | null이 아닌 Optional 생성 | O(1) | O(1) |
 
 ```typescript
-const fastest = semanticStream.toUnordered();
+// Optional 사용 예제
+const emptyOpt = Optional.empty<number>();
+const presentOpt = Optional.of(42);
+const nullableOpt = Optional.ofNullable<string>(null);
+const nonNullOpt = Optional.ofNonNull("hello");
+
+presentOpt.ifPresent(val => console.log(val)); // 42 출력
+console.log(emptyOpt.orElse(100)); // 100 출력
 ```
 
-🔥 **어떠한 정렬 알고리즘도 적용되지 않습니다.**  
-순서가 중요하지 않고 속도가 최우선일 때 이 방법을 사용하세요.
-
----
+### Collector 팩토리 메서드
 
-### 4. `toOrdered()` 및 `sorted()` — 정렬된 출력
-
-**정렬된 결과가 필요한 경우** 다음을 사용할 수 있습니다:
+| 메서드 | 설명 | 시간 복잡도 | 공간 복잡도 |
+|--------|------|------------|------------|
+| `Collector.full(identity, accumulator, finisher)` | 완전한 수집기 생성 | O(1) | O(1) |
+| `Collector.shortable(identity, interruptor, accumulator, finisher)` | 중단 가능한 수집기 생성 | O(1) | O(1) |
 
 ```typescript
-const ordered = semanticStream.sorted(); // 자연 정렬
-const customSorted = semanticStream.sorted((a, b) => a - b); // 커스텀 비교자
-const orderedCollectable = semanticStream.toOrdered(); // 정렬됨
+// Collector 사용 예제
+const sumCollector = Collector.full(
+    () => 0,
+    (sum, num) => sum + num,
+    result => result
+);
+
+const numbers = from([1, 2, 3, 4, 5]);
+const total = numbers.toUnoredered().collect(sumCollector); // 15
 ```
 
-⚠️ 이 메서드들은 **요소를 정렬**하며, 자연 정렬 또는 제공된 비교자를 사용합니다.
-
----
+### Semantic 팩토리 메서드
 
-### 5. `Collector<E, A, R>` — 데이터 집계
-
-컬렉터를 사용하면 스트림을 **단일 값 또는 복잡한 구조로 축약**할 수 있습니다.
-
-내장된 정적 팩토리:
+| 메서드 | 설명 | 시간 복잡도 | 공간 복잡도 |
+|-------|------|-------------|-------------|
+| `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
-Collector.full(identity, accumulator, finisher)
-Collector.shortable(identity, interruptor, accumulator, finisher)
+// Semantic 팩토리 메서드 사용 예시
+
+// Blob으로부터 스트림 생성 (청크 읽기)
+blob(someBlob, 1024n)
+  .toUnordered()
+  .write(WritableStream)
+  .then(callback) // 스트림 쓰기 성공
+  .catch(writeFi); // 스트림 쓰기 실패
+
+// 다른 스트림과 연결될 때까지 실행되지 않는 빈 스트림 생성
+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)=> event.type === "message") // 메시지 이벤트만 모니터링
+  .toUnordered() // 이벤트는 일반적으로 정렬되지 않음
+  .forEach((event)=> receive(event)); // 메시지 수신
 ```
 
-하지만 보통은 `Collectable` 클래스의 고수준 메서드를 통해 사용하게 됩니다.
-
----
-
-### 6. `Collectable<E>` (추상 클래스)
-
-다음 클래스들의 기반 클래스입니다:
-
-- `OrderedCollectable<E>` — 정렬된 출력
-- `UnorderedCollectable<E>` — 정렬 없음, 가장 빠름
-- `WindowCollectable<E>` — 슬라이딩 윈도우
-- `Statistics<E, D>` — 통계 집계
-
-#### 공통 메서드 (상속을 통해):
-
-| 메서드 | 설명 | 예제 |
-|--------|------|------|
-| `count()` | 요소 개수 | `.count()` |
-| `toArray()` | 배열로 변환 | `.toArray()` |
-| `toSet()` | Set으로 변환 | `.toSet()` |
-| `toMap(k, v)` | Map으로 변환 | `.toMap(x => x.id, x => x)` |
-| `group(k)` | 키로 그룹화 | `.group(x => x.category)` |
-| `findAny()` | 임의의 요소 (Optional) | `.findAny()` |
-| `findFirst()` | 첫 번째 요소 (Optional) | `.findFirst()` |
-| `reduce(...)` | 커스텀 축약 | `.reduce((a,b) => a + b, 0)` |
-
----
-
-### 7. `OrderedCollectable<E>` — 정렬된 데이터
-
-요소들을 **자동으로 정렬**하고 싶다면 이 클래스를 사용하세요.
-
-**커스텀 비교자**를 받거나 자연 정렬을 사용할 수 있습니다.
+## Semantic 클래스 메서드
+
+| 메서드 | 설명 | 시간 복잡도 | 공간 복잡도 |
+|--------|------|------------|------------|
+| `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) |
 
 ```typescript
-const sorted = new OrderedCollectable(stream);
-const customSorted = new OrderedCollectable(stream, (a, b) => b - a);
+// Semantic 작업 예제
+const result = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+    .filter(n => n % 2 === 0)        // 짝수 필터링
+    .map(n => n * 2)                 // 2배 변환
+    .skip(1)                         // 첫 번째 요소 건너뛰기
+    .limit(3)                        // 3개 요소로 제한
+    .toArray();                      // 배열로 변환
+// 결과: [8, 12, 20]
+
+// 복잡한 작업 예제
+const complexResult = range(1, 100, 1)
+    .flatMap(n => from([n, n * 2])) // 각 요소를 2개 요소로 매핑
+    .distinct()                      // 중복 제거
+    .shuffle()                       // 무작위 셔플
+    .takeWhile(n => n < 50)         // 50 미만 요소 가져오기
+    .toOrdered()                     // 정렬된 수집기로 변환
+    .toArray();                      // 배열로 변환
 ```
 
-🔒 **정렬된 출력이 보장됩니다.**
+## 수집기 변환 메서드
 
----
-
-### 8. `UnorderedCollectable<E>` — 정렬 없음 (🚀 가장 빠름)
-
-**순서가 중요하지 않고 최고의 성능이 필요한 경우** 다음을 사용하세요:
+| 메서드 | 설명 | 시간 복잡도 | 공간 복잡도 |
+|--------|------|------------|------------|
+| `toUnoredered()` | 비정렬 수집기로 변환 (성능 우선) | O(1) | O(1) |
+| `toOrdered()` | 정렬된 수집기로 변환 | O(1) | O(1) |
+| `sorted()` | 정렬 후 정렬된 수집기로 변환 | O(n log n) | O(n) |
+| `toWindow()` | 윈도우 수집기로 변환 | O(1) | O(1) |
+| `toNumericStatistics()` | 숫자 통계로 변환 | O(1) | O(1) |
+| `toBigintStatistics()` | BigInt 통계로 변환 | O(1) | O(1) |
 
 ```typescript
-const unordered = new UnorderedCollectable(stream);
-// 또는
-const fastest = semanticStream.toUnordered();
+// 수집기 변환 예제
+const numbers = from([3, 1, 4, 1, 5, 9, 2, 6, 5]);
+
+// 성능 우선: 비정렬 수집기 사용
+const unordered = numbers
+    .filter(n => n > 3)
+    .toUnoredered();
+
+// 정렬 필요: 정렬된 수집기 사용  
+const ordered = numbers
+    .sorted()
+    .toOrdered();
+
+// 통계 분석: 통계 수집기 사용
+const stats = numbers
+    .toNumericStatistics();
+
+console.log(stats.mean());        // 평균값
+console.log(stats.median());      // 중앙값
+console.log(stats.standardDeviation()); // 표준편차
+
+// 윈도우 작업
+const windowed = numbers
+    .toWindow()
+    .tumble(3n); // 3개 요소 윈도우
+
+windowed.forEach(window => {
+    console.log(window.toArray()); // 각 윈도우 내용
+});
 ```
 
-✅ **정렬 알고리즘이 실행되지 않음**  
-✅ **순서가 중요하지 않을 때 최고의 성능**
-
----
-
-### 9. `Statistics<E, D>` — 통계 분석
-
-숫자 데이터를 분석하기 위한 추상 기반 클래스입니다.
-
-#### 서브 클래스:
-
-- `NumericStatistics<E>` — `number` 값용
-- `BigIntStatistics<E>` — `bigint` 값용
-
-##### 주요 통계 메서드:
-
-| 메서드 | 설명 | 예제 |
-|--------|------|------|
-| `mean()` | 평균 | `.mean()` |
-| `median()` | 중앙값 | `.median()` |
-| `mode()` | 최빈값 | `.mode()` |
-| `minimum()` | 최솟값 | `.minimum()` |
-| `maximum()` | 최댓값 | `.maximum()` |
-| `range()` | 최댓값 - 최솟값 | `.range()` |
-| `variance()` | 분산 | `.variance()` |
-| `standardDeviation()` | 표준 편차 | `.standardDeviation()` |
-| `summate()` | 합계 | `.summate()` |
-| `quantile(q)` | q분위수 (0~1) | `.quantile(0.5)` → 중앙값 |
-| `frequency()` | 빈도 맵 | `.frequency()` |
-
----
-
-## 🧪 전체 예제
+## 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)` | Map으로 변환 | O(n) | O(n) |
+| `toSet()` | Set으로 변환 | O(n) | O(n) |
+| `write(stream)` | 스트림에 쓰기 | O(n) | O(1) |
 
 ```typescript
-import { from, toUnordered, toOrdered, sorted, NumericStatistics } from 'semantic-typescript';
-
-// 샘플 데이터
-const numbers = from([10, 2, 8, 4, 5, 6]);
-
-// 🚀 가장 빠름: 정렬 없음
-const fastest = numbers.toUnordered();
-console.log(fastest.toArray()); // 예: [10, 2, 8, 4, 5, 6] (원래 순서)
-
-// 🔢 자연 정렬
-const ordered = numbers.sorted();
-console.log(ordered.toArray()); // [2, 4, 5, 6, 8, 10]
-
-// 📊 통계 분석
-const stats = new NumericStatistics(numbers);
-console.log('평균:', stats.mean());
-console.log('중앙값:', stats.median());
-console.log('최빈값:', stats.mode());
-console.log('범위:', stats.range());
-console.log('표준 편차:', stats.standardDeviation());
+// Collectable 작업 예제
+const data = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+    .filter(n => n % 2 === 0)
+    .toOrdered();
+
+// 일치 확인
+console.log(data.anyMatch(n => n > 5)); // true
+console.log(data.allMatch(n => n < 20)); // true
+
+// 검색 작업
+data.findFirst().ifPresent(n => console.log(n)); // 2
+data.findAny().ifPresent(n => console.log(n)); // 아무 요소
+
+// 그룹화 작업
+const grouped = data.groupBy(
+    n => n > 5 ? "large" : "small",
+    n => n * 2
+);
+// {small: [4, 8], large: [12, 16, 20]}
+
+// 축소 작업
+const sum = data.reduce(0, (acc, n) => acc + n); // 30
+
+// 출력 작업
+data.join(", "); // "2, 4, 6, 8, 10"
 ```
 
----
-
-## 🛠️ 유틸리티 함수
-
-다양한 **타입 가드(Type Guards)** 와 **비교 도구**도 제공됩니다:
-
-| 함수 | 용도 |
-|------|------|
-| `isString(x)` | `string` 타입 가드 |
-| `isNumber(x)` | `number` 타입 가드 |
-| `isBoolean(x)` | `boolean` 타입 가드 |
-| `isIterable(x)` | 객체가 반복 가능한지 확인 |
-| `useCompare(a, b)` | 범용 비교 함수 |
-| `useRandom(x)` | 의사 난수 생성기 (재미삼아) |
-
----
-
-## 🧩 고급: 커스텀 생성기 & 윈도우
-
-무한 또는 제어된 데이터 스트림을 위한 **커스텀 생성기**를 만들 수 있습니다:
+## 통계 분석 메서드
+
+### 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) |
 
 ```typescript
-const gen = (accept: BiConsumer<number, bigint>, interrupt: Predicate<number>) => {
-  for (let i = 0; i < 10; i++) {
-    accept(i, BigInt(i));
-    if (i === 5) interrupt(i);
-  }
-};
-
-const s = new Semantic(gen);
+// 통계 분석 예제
+const 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
 ```
 
-또는 **슬라이딩 윈도우**를 사용할 수도 있습니다:
+## 성능 선택 가이드
 
+### 비정렬 수집기 선택 (성능 우선)
 ```typescript
-const windowed = ordered.slide(3n, 2n); // 크기 3, 스텝 2
+// 순서 보장이 필요하지 않은 경우
+const highPerformance = data
+    .filter(predicate)
+    .map(mapper)
+    .toUnoredered(); // 최고 성능
 ```
 
----
-
-## 📄 라이선스
-
-이 프로젝트는 **MIT 라이선스** 로 제공되며, 상업적·개인적 용도로 자유롭게 사용할 수 있습니다.
-
----
-
-## 🙌 기여
-
-Pull Request, 이슈(Issue), 아이디어 제안 등 모두 환영합니다!
-
----
-
-## 🚀 빠른 시작 요약
-
-| 작업 | 메서드 |
-|------|--------|
-| null/undefined 안전하게 처리 | `Optional<T>` |
-| 스트림 생성 | `from([...])`, `range()`, `fill()` |
-| 데이터 변환 | `map()`, `filter()` |
-| 데이터 정렬 | `sorted()`, `toOrdered()` |
-| 정렬 없음 (가장 빠름) | `toUnordered()` ✅ |
-| 그룹화 / 집계 | `toMap()`, `group()`, `Collector` |
-| 통계 | `NumericStatistics`, `mean()`, `median()` 등 |
+### 정렬된 수집기 선택 (순서 필요)
+```typescript
+// 요소 순서를 유지해야 하는 경우
+const ordered = data.sorted(comparator);
+```
 
----
+### 윈도우 수집기 선택 (윈도우 작업)
+```typescript
+// 윈도우 작업이 필요한 경우
+const windowed = data
+    .toWindow()
+    .slide(5n, 2n); // 슬라이딩 윈도우
+```
 
-## 🔗 링크
+### 통계 분석 선택 (숫자 계산)
+```typescript
+// 통계 분석이 필요한 경우
+const stats = data
+    .toNumericStatistics(); // 숫자 통계
 
-- 📦 npm: https://www.npmjs.com/package/semantic-typescript
-- 🐙 GitHub: https://github.com/eloyhere/semantic-typescript
-- 📘 문서: 소스 코드 / 타입 정의 참조
+const bigIntStats = data
+    .toBigintStatistics(); // BigInt 통계
+```
 
----
+[GitHub](https://github.com/eloyhere/semantic-typescript)
+[NPMJS](https://www.npmjs.com/package/semantic-typescript)
 
-**TypeScript에서 함수형, 타입 안전하고 구성 가능한 데이터 처리를 즐겨보세요.** 🚀
+## 중요한 주의사항
 
---- 
+1. **정렬 작업의 영향**: 정렬된 수집기에서 `sorted()` 작업은 `redirect`, `translate`, `shuffle`, `reverse` 효과를 덮어씁니다
+2. **성능 고려사항**: 순서 보장이 필요하지 않으면 `toUnoredered()`를 우선하여 더 나은 성능을 얻으세요
+3. **메모리 사용량**: 정렬 작업에는 O(n)의 추가 공간이 필요합니다
+4. **실시간 데이터**: Semantic 스트림은 실시간 데이터에 적합하며 비동기 데이터 소스를 지원합니다
 
-✅ **참고:**  
-- `toUnordered()` → **정렬 없음, 가장 빠름**  
-- 그 외 (`sorted()`, `toOrdered()` 등) → **데이터를 정렬함**
+이 라이브러리는 TypeScript 개발자에게 강력하고 유연한 스트림 처리 기능을 제공하며 함수형 프로그래밍의 이점과 타입 안전성을 결합합니다.