semantic-typescript 0.0.8 → 0.2.5

package/readme.kr.md

@@ -1,529 +1,472 @@
-# Semantic-TypeScript 스트림 처리 프레임워크
+# Semantic-TypeScript 스트림 처리 라이브러리
 
 ## 소개
 
-Semantic-TypeScript는 JavaScript GeneratorFunction, Java Stream 및 MySQL Index에서 영감을 받은 현대적인 스트림 처리 라이브러리입니다. 핵심 설계 철학은 데이터 인덱싱을 통해 효율적인 데이터 처리 파이프라인을 구축하는 데 있으며, 프론트엔드 개발을 위해 타입 안전적이고 함수형 스타일의 스트리밍 작업 경험을 제공합니다.
+Semantic-TypeScript는 JavaScript GeneratorFunction, Java Stream 및 MySQL Index에서 영감을 받은 현대적인 스트림 처리 라이브러리입니다. 이 라이브러리의 핵심 설계는 데이터 인덱스를 기반으로 효율적인 데이터 처리 파이프라인을 구축하여 프론트엔드 개발자에게 타입 안전성과 함수형 스타일의 스트림 조작 경험을 제공합니다.
 
-기존의 동기식 처리와 달리 Semantic은 비동기 처리 모델을 채택합니다. 데이터 스트림을 생성할 때 최종 데이터 수신 시점은 전적으로 업스트림이 `accept` 및 `interrupt` 콜백 함수를 호출하는 시점에 따라 결정됩니다. 이 설계는 라이브러리가 실시간 데이터 스트림, 대용량 데이터 세트 및 비동기 데이터 소스를 우아하게 처리할 수 있게 합니다.
+기존의 동기식 처리와 달리 Semantic은 비동기 처리 모드를 채택합니다. 데이터 스트림을 생성할 때, 터미널이 데이터를 수신하는 시점은 업스트림이 `accept` 및 `interrupt` 콜백 함수를 언제 호출하는지에 전적으로 의존합니다. 이 설계는 라이브러리가 실시간 데이터 스트림, 대규모 데이터 세트 및 비동기 데이터 소스를 우아하게 처리할 수 있도록 합니다.
 
-## 핵심 기능
+## 설치
 
-| 기능 | 설명 | 장점 |
-|------|------|------|
-| **타입 안전 제네릭** | 완전한 TypeScript 타입 지원 | 컴파일 타임 오류 감지, 더 나은 개발 경험 |
-| **함수형 프로그래밍** | 불변 데이터 구조 및 순수 함수 | 예측 가능한 코드, 쉬운 테스트 및 유지보수 |
-| **지연 평가** | 주문형 계산, 성능 최적화 | 대용량 데이터 처리 시 높은 메모리 효율 |
-| **비동기 스트림 처리** | 제너레이터 기반 비동기 데이터 스트림 | 실시간 데이터 및 이벤트 기반 시나리오에 적합 |
-| **다중 패러다임 수집기** | 정렬, 비정렬, 통계적 수집 전략 | 다양한 시나리오에 따른 최적 전략 선택 |
-| **통계 분석** | 내장된 완전한 통계 계산 함수 | 통합 데이터 분석 및 보고서 생성 |
-
-## 성능 고려 사항
-
-**중요 참고**: 다음 메서드들은 데이터를 수집하고 정렬하기 위해 성능을 희생합니다:
-- `toOrdered()`
-- `toWindow()`
-- `toNumericStatistics()`
-- `toBigIntStatistics()`
-- `sorted()`
-- `sorted(comparator)`
-
-특히 중요: `sorted()` 및 `sorted(comparator)`는 다음 메서드들의 결과를 재정의합니다:
-- `redirect(redirector)`
-- `translate(translator)`
-- `shuffle(mapper)`
-
-## 팩토리 메서드
-
-### 스트림 생성 팩토리
+```bash
+npm install semantic-typescript
+```
 
-| 메서드 | 시그니처 | 설명 | 예시 |
-|------|------|------|------|
-| `blob` | `(blob: Blob, chunk?: bigint) => Semantic<Uint8Array>` | Blob을 바이트 스트림으로 변환 | `blob(fileBlob, 1024n)` |
-| `empty` | `<E>() => Semantic<E>` | 빈 스트림 생성 | `empty<number>()` |
-| `fill` | `<E>(element: E, count: bigint) => Semantic<E>` | 지정된 수의 요소로 채움 | `fill("hello", 5n)` |
-| `from` | `<E>(iterable: Iterable<E>) => Semantic<E>` | 반복 가능 객체로부터 스트림 생성 | `from([1, 2, 3])` |
-| `range` | `<N extends number\|bigint>(start: N, end: N, step?: N) => Semantic<N>` | 숫자 범위 스트림 생성 | `range(1, 10, 2)` |
-| `iterate` | `<E>(generator: Generator<E>) => Semantic<E>` | 제너레이터 함수로부터 스트림 생성 | `iterate(myGenerator)` |
-| `websocket` | `(websocket: WebSocket) => Semantic<MessageEvent>` | WebSocket으로부터 이벤트 스트림 생성 | `websocket(socket)` |
+## 기본 타입
+
+| 타입 | 설명 |
+|------|-------------|
+| `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>` | 제너레이터 함수 (핵심 및 기반) |
 
-**코드 예시 보충:**
 ```typescript
-import { from, range, fill, empty } from 'semantic-typescript';
-
-// 배열로부터 스트림 생성
-const numberStream = from([1, 2, 3, 4, 5]);
-
-// 숫자 범위 스트림 생성
-const rangeStream = range(1, 10, 2); // 1, 3, 5, 7, 9
-
-// 반복 요소로 채움
-const filledStream = fill("hello", 3n); // "hello", "hello", "hello"
-
-// 빈 스트림 생성
-const emptyStream = empty<number>();
+// 타입 사용 예제
+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) |
 
-| 메서드 | 시그니처 | 설명 | 예시 |
-|------|------|------|------|
-| `validate` | `<T>(t: MaybeInvalid<T>) => t is T` | 값이 유효한지 검증 | `validate(null)` → `false` |
-| `invalidate` | `<T>(t: MaybeInvalid<T>) => t is null\|undefined` | 값이 무효한지 검증 | `invalidate(0)` → `false` |
-| `useCompare` | `<T>(t1: T, t2: T) => number` | 일반 비교 함수 | `useCompare("a", "b")` → `-1` |
-| `useRandom` | `<T = number\|bigint>(index: T) => T` | 의사 난수 생성기 | `useRandom(5)` → 난수 |
-
-**코드 예시 보충:**
 ```typescript
-import { validate, invalidate, useCompare, useRandom } from 'semantic-typescript';
+// 타입 가드 사용 예제
+const value: unknown = "hello";
 
-// 데이터 유효성 검증
-const data: string | null = "hello";
-if (validate(data)) {
-    console.log(data.toUpperCase()); // validate가 데이터가 null이 아님을 보장하므로 안전한 호출
+if (isString(value)) {
+    console.log(value.length); // 타입 안전, value는 string으로 추론
 }
 
-const nullData: string | null = null;
-if (invalidate(nullData)) {
-    console.log("데이터 무효"); // invalidate가 null을 감지했으므로 실행됨
+if (isOptional(someValue)) {
+    someValue.ifPresent(val => console.log(val));
 }
-
-// 값 비교
-const comparison = useCompare("apple", "banana"); // -1
-
-// 난수 생성
-const randomNum = useRandom(42); // 시드 42 기반 난수
 ```
 
-## 핵심 클래스 상세
-
-### Optional<T> - 안전한 Null 값 처리
+## 유틸리티 함수
 
-Optional 클래스는 null 또는 undefined일 수 있는 값을 안전하게 처리하기 위한 함수형 접근 방식을 제공합니다.
+| 함수 | 설명 | 시간 복잡도 | 공간 복잡도 |
+|------|------|------------|------------|
+| `useCompare<T>(t1: T, t2: T): number` | 범용 비교 함수 | O(1) | O(1) |
+| `useRandom<T = number \| bigint>(index: T): T` | 의사 난수 생성기 | O(log n) | O(1) |
 
-| 메서드 | 반환 타입 | 설명 | 시간 복잡도 |
-|------|----------|------|------------|
-| `filter(predicate: Predicate<T>)` | `Optional<T>` | 조건을 만족하는 값 필터링 | O(1) |
-| `get()` | `T` | 값 가져오기, 비어있으면 오류 발생 | O(1) |
-| `getOrDefault(defaultValue: T)` | `T` | 값 또는 기본값 가져오기 | O(1) |
-| `ifPresent(action: Consumer<T>)` | `void` | 값이 존재하면 액션 실행 | O(1) |
-| `isEmpty()` | `boolean` | 비어있는지 확인 | O(1) |
-| `isPresent()` | `boolean` | 값이 존재하는지 확인 | O(1) |
-| `map<R>(mapper: Functional<T, R>)` | `Optional<R>` | 값 매핑 및 변환 | O(1) |
-| `static of<T>(value: MaybeInvalid<T>)` | `Optional<T>` | Optional 인스턴스 생성 | O(1) |
-| `static ofNullable<T>(value?)` | `Optional<T>` | nullable Optional 생성 | O(1) |
-| `static ofNonNull<T>(value: T)` | `Optional<T>` | non-null Optional 생성 | O(1) |
-
-**코드 예시 보충:**
 ```typescript
-import { Optional } from 'semantic-typescript';
-
-// Optional 인스턴스 생성
-const optionalValue = Optional.ofNullable<string>(Math.random() > 0.5 ? "hello" : null);
+// 유틸리티 함수 사용 예제
+const numbers = [3, 1, 4, 1, 5];
+numbers.sort(useCompare); // [1, 1, 3, 4, 5]
 
-// 연쇄 연산
-const result = optionalValue
-    .filter(val => val.length > 3) // 길이가 3보다 큰 값 필터링
-    .map(val => val.toUpperCase()) // 대문자로 변환
-    .getOrDefault("default"); // 값 또는 기본값 가져오기
+const randomNum = useRandom(42); // 시드 기반 난수
+const randomBigInt = useRandom(1000n); // BigInt 난수
+```
 
-console.log(result); // "HELLO" 또는 "default"
+## 팩토리 메서드
 
-// 안전한 연산
-optionalValue.ifPresent(val => {
-    console.log(`값 존재: ${val}`);
-});
+### Optional 팩토리 메서드
 
-// 상태 확인
-if (optionalValue.isPresent()) {
-    console.log("값 있음");
-} else if (optionalValue.isEmpty()) {
-    console.log("비어 있음");
-}
-```
+| 메서드 | 설명 | 시간 복잡도 | 공간 복잡도 |
+|--------|------|------------|------------|
+| `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) |
 
-### Semantic<E> - 지연 데이터 스트림
-
-Semantic은 풍부한 스트림 연산자를 제공하는 핵심 스트림 처리 클래스입니다.
-
-#### 스트림 변환 연산
-
-| 메서드 | 반환 타입 | 설명 | 성능 영향 |
-|------|----------|------|----------|
-| `concat(other: Semantic<E>)` | `Semantic<E>` | 두 스트림 연결 | O(n+m) |
-| `distinct()` | `Semantic<E>` | 중복 제거 (Set 사용) | O(n) |
-| `distinct(comparator)` | `Semantic<E>` | 사용자 정의 비교자 중복 제거 | O(n²) |
-| `dropWhile(predicate)` | `Semantic<E>` | 조건을 만족하는 시작 요소 버림 | O(n) |
-| `filter(predicate)` | `Semantic<E>` | 요소 필터링 | O(n) |
-| `flat(mapper)` | `Semantic<E>` | 중첩 스트림 평탄화 | O(n×m) |
-| `flatMap(mapper)` | `Semantic<R>` | 매핑 및 평탄화 | O(n×m) |
-| `limit(n)` | `Semantic<E>` | 요소 수 제한 | O(n) |
-| `map(mapper)` | `Semantic<R>` | 요소 매핑 및 변환 | O(n) |
-| `peek(consumer)` | `Semantic<E>` | 요소 확인 (수정 없음) | O(n) |
-| `redirect(redirector)` | `Semantic<E>` | 인덱스 재지정 | O(n) |
-| `reverse()` | `Semantic<E>` | 스트림 순서 반전 | O(n) |
-| `shuffle()` | `Semantic<E>` | 무작위 셔플 | O(n) |
-| `shuffle(mapper)` | `Semantic<E>` | 사용자 정의 셔플 로직 | O(n) |
-| `skip(n)` | `Semantic<E>` | 처음 n개 요소 건너뜀 | O(n) |
-| `sub(start, end)` | `Semantic<E>` | 부분 스트림 가져오기 | O(n) |
-| `takeWhile(predicate)` | `Semantic<E>` | 조건을 만족하는 시작 요소 가져오기 | O(n) |
-| `translate(offset)` | `Semantic<E>` | 인덱스 변환 | O(n) |
-| `translate(translator)` | `Semantic<E>` | 사용자 정의 인덱스 변환 | O(n) |
-
-**코드 예시 보충:**
 ```typescript
-import { from } from 'semantic-typescript';
+// 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 출력
+```
 
-const stream = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+### Collector 팩토리 메서드
 
-// 스트림 변환 연산 예시
-const processedStream = stream
-    .filter(x => x % 2 === 0) // 짝수 필터링
-    .map(x => x * 2) // 각 요소에 2 곱하기
-    .distinct() // 중복 제거
-    .limit(3) // 처음 3개 요소로 제한
-    .peek((val, index) => console.log(`인덱스 ${index}의 요소 ${val}`)); // 요소 확인
+| 메서드 | 설명 | 시간 복잡도 | 공간 복잡도 |
+|--------|------|------------|------------|
+| `Collector.full(identity, accumulator, finisher)` | 완전한 수집기 생성 | O(1) | O(1) |
+| `Collector.shortable(identity, interruptor, accumulator, finisher)` | 중단 가능한 수집기 생성 | O(1) | O(1) |
 
-// 참고: 스트림은 아직 실행되지 않음, 터미널 연산을 위해 Collectable로 변환 필요
+```typescript
+// 컬렉터 변환 예제
+const numbers = from([3, 1, 4, 1, 5, 9, 2, 6, 5]);
+
+// 성능 우선: 비정렬 컬렉터 사용
+const unordered = numbers
+    .filter(n => n > 3)
+    .toUnoredered();
+
+// 정렬 필요: 정렬 컬렉터 사용  
+const ordered = numbers.sorted();
+
+// 요소 개수 세기
+let count = Collector.full(
+    () => 0, // 초기값
+    (accumulator, element) => accumulator + element, // 누적
+    (accumulator) => accumulator // 완료
+);
+count.collect(from([1,2,3,4,5])); // 스트림에서 카운트
+count.collect([1,2,3,4,5]); // 이터러블 객체에서 카운트
+
+let find = Collector.shortable(
+    () => Optional.empty(), // 초기값
+    (element, index, accumulator) => accumulator.isPresent(), // 중단
+    (accumulator, element, index) => Optional.of(element), // 누적
+    (accumulator) => accumulator // 완료
+);
+find.collect(from([1,2,3,4,5])); // 첫 번째 요소 찾기
+find.collect([1,2,3,4,5]); // 첫 번째 요소 찾기
 ```
 
-#### 스트림 터미널 연산
+### Semantic 팩토리 메서드
 
-| 메서드 | 반환 타입 | 설명 | 성능 특성 |
-|------|----------|------|----------|
-| `toOrdered()` | `OrderedCollectable<E>` | 정렬된 컬렉션으로 변환 | 정렬 연산, 낮은 성능 |
-| `toUnordered()` | `UnorderedCollectable<E>` | 비정렬 컬렉션으로 변환 | 가장 빠름, 정렬 없음 |
-| `toWindow()` | `WindowCollectable<E>` | 윈도우 컬렉션으로 변환 | 정렬 연산, 낮은 성능 |
-| `toNumericStatistics()` | `Statistics<E, number>` | 숫자 통계 분석 | 정렬 연산, 낮은 성능 |
-| `toBigintStatistics()` | `Statistics<E, bigint>` | Big integer 통계 분석 | 정렬 연산, 낮은 성능 |
-| `sorted()` | `OrderedCollectable<E>` | 자연 정렬 | 재지정 결과 재정의 |
-| `sorted(comparator)` | `OrderedCollectable<E>` | 사용자 정의 정렬 | 재지정 결과 재정의 |
+| 메서드 | 설명 | 시간 복잡도 | 공간 복잡도 |
+|-------|------|-------------|-------------|
+| `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) |
+| `generate<E>(element, interrupt)` | 생성기를 사용한 스트림 생성 | 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
-import { from } from 'semantic-typescript';
+// Semantic 팩토리 메서드 사용 예시
 
-const semanticStream = from([5, 2, 8, 1, 9, 3, 7, 4, 6]);
+// Blob으로부터 스트림 생성 (청크 읽기)
+blob(someBlob, 1024n)
+  .toUnordered()
+  .write(WritableStream)
+  .then(callback) // 스트림 쓰기 성공
+  .catch(writeFi); // 스트림 쓰기 실패
 
-// 정렬된 컬렉션으로 변환 (낮은 성능)
-const ordered = semanticStream.toOrdered();
+// 다른 스트림과 연결될 때까지 실행되지 않는 빈 스트림 생성
+empty<string>()
+  .toUnordered()
+  .join(); //[]
 
-// 비정렬 컬렉션으로 변환 (가장 빠름)
-const unordered = semanticStream.toUnordered();
+// 채워진 스트림 생성
+const filledStream = fill("hello", 3); // "hello", "hello", "hello"
 
-// 자연 정렬
-const sortedNatural = semanticStream.sorted();
+// 초기 지연 2초, 실행 주기 5초의 시계열 스트림 생성
+// 타이머 메커니즘으로 구현, 시스템 스케줄링 제한으로 인한 시간 변동 가능성 있음
+const intervalStream = interval(5000, 2000);
 
-// 사용자 정의 정렬
-const sortedCustom = semanticStream.sorted((a, b) => b - a); // 내림차순 정렬
+// 반복 가능 객체로부터 스트림 생성
+const numberStream = from([1, 2, 3, 4, 5]);
+const stringStream = from(new Set(["Alex", "Bob"]));
 
-// 통계 객체로 변환
-const stats = semanticStream.toNumericStatistics();
+// 범위 스트림 생성
+const rangeStream = range(1, 10, 2); // 1, 3, 5, 7, 9
 
-// 참고: 위 메서드들은 Semantic 인스턴스를 통해 호출하여 Collectable을 얻은 후 터미널 메서드 사용 필요
+// WebSocket 이벤트 스트림
+const ws = new WebSocket("ws://localhost:8080");
+websocket(ws)
+  .filter((event)=> event.type === "message") // 메시지 이벤트만 모니터링
+  .toUnordered() // 이벤트는 일반적으로 정렬되지 않음
+  .forEach((event)=> receive(event)); // 메시지 수신
 ```
 
-### Collector<E, A, R> - 데이터 수집기
+## 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) |
 
-수집기는 스트림 데이터를 특정 구조로 집계하는 데 사용됩니다.
-
-| 메서드 | 설명 | 사용 시나리오 |
-|------|------|----------|
-| `collect(generator)` | 데이터 수집 실행 | 스트림 터미널 연산 |
-| `static full(identity, accumulator, finisher)` | 완전한 수집기 생성 | 완전한 처리 필요 |
-| `static shortable(identity, interruptor, accumulator, finisher)` | 중단 가능 수집기 생성 | 조기 종료 가능 |
-
-**코드 예시 보충:**
 ```typescript
-import { Collector } from 'semantic-typescript';
-
-// 사용자 정의 수집기 생성
-const sumCollector = Collector.full(
-    () => 0, // 초기 값
-    (acc, value) => acc + value, // 누산기
-    result => result // 완료 함수
-);
-
-// 수집기 사용 (Semantic에서 Collectable로 변환 필요)
-const numbers = from([1, 2, 3, 4, 5]);
-const sum = numbers.toUnordered().collect(sumCollector); // 15
+// 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개 요소로 제한
+    .toUnordered()                    // 비정렬 수집기로 변환
+    .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();                      // 배열로 변환
 ```
 
-### Collectable<E> - 수집 가능 데이터 추상 클래스
-
-풍부한 데이터 집계 및 변환 메서드를 제공합니다. **참고: 반드시 Semantic 인스턴스를 통해 sorted(), toOrdered() 등을 먼저 호출하여 Collectable 인스턴스를 얻은 후 다음 메서드들을 사용해야 합니다.**
+## 意味論的変換メソッド
 
-#### 데이터 쿼리 연산
+| メソッド | 説明 | 時間計算量 | 空間計算量 |
+|------------|------------|------------|------------|
+| `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) |
 
-| 메서드 | 반환 타입 | 설명 | 예시 |
-|------|----------|------|------|
-| `anyMatch(predicate)` | `boolean` | 어떤 요소라도 일치하는지 여부 | `anyMatch(x => x > 0)` |
-| `allMatch(predicate)` | `boolean` | 모든 요소가 일치하는지 여부 | `allMatch(x => x > 0)` |
-| `count()` | `bigint` | 요소 수 통계 | `count()` → `5n` |
-| `isEmpty()` | `boolean` | 스트림이 비어 있는지 여부 | `isEmpty()` |
-| `findAny()` | `Optional<E>` | 아무 요소 찾기 | `findAny()` |
-| `findFirst()` | `Optional<E>` | 첫 번째 요소 찾기 | `findFirst>` |
-| `findLast()` | `Optional<E>` | 마지막 요소 찾기 | `findLast>` |
-
-**코드 예시 보충:**
 ```typescript
-import { from } from 'semantic-typescript';
-
-const numbers = from([1, 2, 3, 4, 5]);
-
-// 터미널 메서드 사용 전 반드시 Collectable로 변환
-const collectable = numbers.toUnordered();
-
-// 데이터 쿼리 연산
-const hasEven = collectable.anyMatch(x => x % 2 === 0); // true
-const allPositive = collectable.allMatch(x => x > 0); // true
-const count = collectable.count(); // 5n
-const isEmpty = collectable.isEmpty(); // false
-const firstElement = collectable.findFirst(); // Optional.of(1)
-const anyElement = collectable.findAny(); // 아무 요소
+// 昇順ソート配列に変換
+from([6,4,3,5,2]) // ストリーム作成
+    .sorted() // ストリームを昇順でソート
+    .toArray(); // [2, 3, 4, 5, 6]
+
+// 降順ソート配列に変換
+from([6,4,3,5,2]) // ストリーム作成
+    .soted((a, b) => b - a) // ストリームを降順でソート
+    .toArray(); // [6, 5, 4, 3, 2]
+
+// 反転配列へリダイレクト
+from([6,4,3,5,2])
+    .redirect((element, index) => -index) // 反転順にリダイレクト
+    .toOrderd() // リダイレクト後の順序を保持
+    .toArray(); // [2, 5, 3, 4, 6]
+
+// 反転配列へのリダイレクトを無視
+from([6,4,3,5,2])
+    .redirect((element, index) => -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));
 ```
 
-#### 데이터 집계 연산
-
-| 메서드 | 반환 타입 | 설명 | 복잡도 |
-|------|----------|------|--------|
-| `group(classifier)` | `Map<K, E[]>` | 분류자에 따른 그룹화 | O(n) |
-| `groupBy(keyExtractor, valueExtractor)` | `Map<K, V[]>` | 키-값 추출기에 따른 그룹화 | O(n) |
-| `join()` | `string` | 문자열로 결합 | O(n) |
-| `join(delimiter)` | `string` | 구분자로 결합 | O(n) |
-| `partition(count)` | `E[][]` | 개수에 따른 분할 | O(n) |
-| `partitionBy(classifier)` | `E[][]` | 분류자에 따른 분할 | O(n) |
-| `reduce(accumulator)` | `Optional<E>` | 축소 연산 | O(n) |
-| `reduce(identity, accumulator)` | `E` | 식별자를 사용한 축소 | O(n) |
-| `toArray()` | `E[]` | 배열로 변환 | O(n) |
-| `toMap(keyExtractor, valueExtractor)` | `Map<K, V>` | Map으로 변환 | O(n) |
-| `toSet()` | `Set<E>` | Set으로 변환 | O(n) |
-
-**코드 예시 보충:**
-```typescript
-import { from } from 'semantic-typescript';
-
-const people = from([
-    { name: "Alice", age: 25, city: "New York" },
-    { name: "Bob", age: 30, city: "London" },
-    { name: "Charlie", age: 25, city: "New York" }
-]);
+## 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) |
 
-// 집계 연산 사용 전 반드시 Collectable로 변환
-const collectable = people.toUnordered();
-
-// 그룹화 연산
-const byCity = collectable.group(person => person.city);
-// Map { "New York" => [{name: "Alice", ...}, {name: "Charlie", ...}], "London" => [{name: "Bob", ...}] }
-
-const byAge = collectable.groupBy(
-    person => person.age,
-    person => person.name
+```typescript
+// 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
 );
-// Map { 25 => ["Alice", "Charlie"], 30 => ["Bob"] }
-
-// 컬렉션으로 변환
-const array = collectable.toArray(); // 원본 배열
-const set = collectable.toSet(); // Set 컬렉션
-const map = collectable.toMap(
-    person => person.name,
-    person => person.age
-); // Map { "Alice" => 25, "Bob" => 30, "Charlie" => 25 }
-
-// 축소 연산
-const totalAge = collectable.reduce(0, (acc, person) => acc + person.age); // 80
-const oldest = collectable.reduce((a, b) => a.age > b.age ? a : b); // Optional.of({name: "Bob", age: 30, ...})
-```
+// {small: [4, 8], large: [12, 16, 20]}
 
-### 특정 수집기 구현
+// 축소 작업
+const sum = data.reduce(0, (acc, n) => acc + n); // 30
 
-#### UnorderedCollectable<E>
-- **특징**: 가장 빠른 수집기, 정렬 없음
-- **사용 시나리오**: 순서 중요하지 않음, 최대 성능 원할 때
-- **메서드**: 모든 Collectable 메서드 상속
-
-#### OrderedCollectable<E>
-- **특징**: 요소 순서 보장, 낮은 성능
-- **사용 시나리오**: 정렬된 결과 필요
-- **특별 메서드**: 모든 메서드 상속, 내부 정렬 상태 유지
+// 출력 작업
+data.join(", "); // "2, 4, 6, 8, 10"
+```
 
-#### WindowCollectable<E>
-- **특징**: 슬라이딩 윈도우 연산 지원
-- **사용 시나리오**: 시계열 데이터 분석
-- **특별 메서드**:
-  - `slide(size, step)` - 슬라이딩 윈도우
-  - `tumble(size)` - 텀블링 윈도우
+## 통계 분석 메서드
+
+### 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
-import { from } from 'semantic-typescript';
-
-const data = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
-
-// 비정렬 수집기 (가장 빠름)
-const unordered = data.toUnordered();
-const unorderedArray = unordered.toArray(); // 원본 순서 유지 가능 [1, 2, 3, ...]
-
-// 정렬 수집기
-const ordered = data.toOrdered();
-const orderedArray = ordered.toArray(); // 정렬 보장 [1, 2, 3, ...]
+// 통계 분석 예제
+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
+```
 
-// 윈도우 수집기
-const windowed = data.toWindow();
-const slidingWindows = windowed.slide(3n, 2n); // 윈도우 크기 3, 단계 2
-// 윈도우 1: [1, 2, 3], 윈도우 2: [3, 4, 5], 윈도우 3: [5, 6, 7], ...
+## 성능 선택 가이드
 
-const tumblingWindows = windowed.tumble(4n); // 텀블링 윈도우 크기 4
-// 윈도우 1: [1, 2, 3, 4], 윈도우 2: [5, 6, 7, 8], ...
+### 비정렬 수집기 선택 (성능 우선)
+```typescript
+// 순서 보장이 필요하지 않은 경우
+const highPerformance = data
+    .filter(predicate)
+    .map(mapper)
+    .toUnoredered(); // 최고 성능
 ```
 
-### Statistics<E, D> - 통계 분석
-
-통계 분석 기본 클래스로 풍부한 통계 계산 메서드를 제공합니다. **참고: 반드시 Semantic 인스턴스를 통해 toNumericStatistics() 또는 toBigIntStatistics()를 호출하여 Statistics 인스턴스를 얻은 후 다음 메서드들을 사용해야 합니다.**
-
-#### 통계 계산 연산
-
-| 메서드 | 반환 타입 | 설명 | 알고리즘 복잡도 |
-|------|----------|------|------------|
-| `maximum()` | `Optional<E>` | 최대값 | O(n) |
-| `minimum()` | `Optional<E>` | 최소값 | O(n) |
-| `range()` | `D` | 범위 (최대-최소) | O(n) |
-| `variance()` | `D` | 분산 | O(n) |
-| `standardDeviation()` | `D` | 표준 편차 | O(n) |
-| `mean()` | `D` | 평균값 | O(n) |
-| `median()` | `D` | 중앙값 | O(n log n) |
-| `mode()` | `D` | 최빈값 | O(n) |
-| `frequency()` | `Map<D, bigint>` | 빈도 분포 | O(n) |
-| `summate()` | `D` | 합계 | O(n) |
-| `quantile(quantile)` | `D` | 분위수 | O(n log n) |
-| `interquartileRange()` | `D` | 사분위 범위 | O(n log n) |
-| `skewness()` | `D` | 왜도 | O(n) |
-| `kurtosis()` | `D` | 첨도 | O(n) |
-
-**코드 예시 보충:**
+### 정렬된 수집기 선택 (순서 필요)
 ```typescript
-import { from } from 'semantic-typescript';
-
-const numbers = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
-
-// 통계 메서드 사용 전 반드시 통계 객체로 변환
-const stats = numbers.toNumericStatistics();
-
-// 기본 통계
-const count = stats.count(); // 10n
-const max = stats.maximum(); // Optional.of(10)
-const min = stats.minimum(); // Optional.of(1)
-const range = stats.range(); // 9
-const mean = stats.mean(); // 5.5
-const median = stats.median(); // 5.5
-const sum = stats.summate(); // 55
-
-// 고급 통계
-const variance = stats.variance(); // 8.25
-const stdDev = stats.standardDeviation(); // 2.872
-const mode = stats.mode(); // 어떤 값 (모두 한 번씩 나타나므로)
-const q1 = stats.quantile(0.25); // 3.25
-const q3 = stats.quantile(0.75); // 7.75
-const iqr = stats.interquartileRange(); // 4.5
-
-// 빈도 분포
-const freq = stats.frequency(); // Map {1 => 1n, 2 => 1n, ...}
+// 요소 순서를 유지해야 하는 경우
+const ordered = data.sorted(comparator);
 ```
 
-#### 특정 통계 구현 클래스
-
-**NumericStatistics<E>**
-- number 타입 통계 분석 처리
-- 모든 통계 계산이 number 타입 반환
-
-**BigIntStatistics<E>**
-- bigint 타입 통계 분석 처리
-- 모든 통계 계산이 bigint 타입 반환
-
-**코드 예시 보충:**
+### 윈도우 수집기 선택 (윈도우 작업)
 ```typescript
-import { from } from 'semantic-typescript';
-
-// 숫자 통계
-const numberData = from([10, 20, 30, 40, 50]);
-const numericStats = numberData.toNumericStatistics();
-
-console.log(numericStats.mean()); // 30
-console.log(numericStats.summate()); // 150
-
-// Big integer 통계
-const bigintData = from([100n, 200n, 300n, 400n, 500n]);
-const bigintStats = bigintData.toBigIntStatistics();
-
-console.log(bigintStats.mean()); // 300n
-console.log(bigintStats.summate()); // 1500n
+// 윈도우 작업이 필요한 경우
+const windowed = data
+    .toWindow()
+    .slide(5n, 2n); // 슬라이딩 윈도우
+```
 
-// 매퍼 함수를 사용한 통계
-const objectData = from([
-    { value: 15 },
-    { value: 25 },
-    { value: 35 },
-    { value: 45 }
-]);
+### 통계 분석 선택 (숫자 계산)
+```typescript
+// 통계 분석이 필요한 경우
+const stats = data
+    .toNumericStatistics(); // 숫자 통계
 
-const objectStats = objectData.toNumericStatistics();
-const meanWithMapper = objectStats.mean(obj => obj.value); // 30
-const sumWithMapper = objectStats.summate(obj => obj.value); // 120
+const bigIntStats = data
+    .toBigintStatistics(); // BigInt 통계
 ```
 
-## 완전한 사용 예시
+[GitHub](https://github.com/eloyhere/semantic-typescript)
+[NPMJS](https://www.npmjs.com/package/semantic-typescript)
 
-```typescript
-import { from, validate, invalidate } from 'semantic-typescript';
-
-// 1. 데이터 스트림 생성
-const rawData = [5, 2, 8, 1, null, 9, 3, undefined, 7, 4, 6];
-const semanticStream = from(rawData);
-
-// 2. 스트림 처리 파이프라인
-const processedStream = semanticStream
-    .filter(val => validate(val)) // null 및 undefined 필터링
-    .map(val => val! * 2) // 각 값에 2 곱하기 (validate가 비어있지 않음을 보장하므로 ! 사용)
-    .distinct(); // 중복 제거
-
-// 3. Collectable로 변환 및 터미널 연산 사용
-const collectable = processedStream.toUnordered();
-
-// 4. 데이터 검증 및 사용
-if (!collectable.isEmpty()) {
-    const results = collectable
-        .filter(x => x > 5) // 다시 필터링
-        .toArray(); // 배열로 변환
-    
-    console.log("처리 결과:", results); // [16, 18, 14, 8, 12]
-    
-    // 통계 정보
-    const stats = processedStream.toNumericStatistics();
-    console.log("평균값:", stats.mean()); // 11.2
-    console.log("총합:", stats.summate()); // 56
-}
+## 중요한 주의사항
 
-// 5. 잠재적으로 무효한 데이터 처리
-const potentiallyInvalidData: Array<number | null> = [1, null, 3, 4, null];
-const validData = potentiallyInvalidData.filter(validate);
-const invalidData = potentiallyInvalidData.filter(invalidate);
-
-console.log("유효한 데이터:", validData); // [1, 3, 4]
-console.log("무효한 데이터:", invalidData); // [null, null]
-```
+1. **정렬 작업의 영향**: 정렬된 수집기에서 `sorted()` 작업은 `redirect`, `translate`, `shuffle`, `reverse` 효과를 덮어씁니다
+2. **성능 고려사항**: 순서 보장이 필요하지 않으면 `toUnoredered()`를 우선하여 더 나은 성능을 얻으세요
+3. **메모리 사용량**: 정렬 작업에는 O(n)의 추가 공간이 필요합니다
+4. **실시간 데이터**: Semantic 스트림은 실시간 데이터에 적합하며 비동기 데이터 소스를 지원합니다
 
-## 중요한 사용 규칙 요약
-
-1. **스트림 생성**: `from()`, `range()`, `fill()` 등 팩토리 메서드를 사용하여 Semantic 인스턴스 생성
-2. **스트림 변환**: Semantic 인스턴스에서 `map()`, `filter()`, `distinct()` 등 메서드 호출
-3. **Collectable로 변환**: 반드시 Semantic 인스턴스를 통해 다음 메서드 중 하나 호출:
-   - `toOrdered()` - 정렬 수집기
-   - `toUnordered()` - 비정렬 수집기 (가장 빠름)
-   - `toWindow()` - 윈도우 수집기
-   - `toNumericStatistics()` - 숫자 통계
-   - `toBigIntStatistics()` - Big integer 통계
-   - `sorted()` - 자연 정렬
-   - `sorted(comparator)` - 사용자 정의 정렬
-4. **터미널 연산**: Collectable 인스턴스에서 `toArray()`, `count()`, `summate()` 등 터미널 메서드 호출
-5. **데이터 검증**: `validate()`를 사용하여 데이터가 null/undefined가 아님을 보장, `invalidate()`를 사용하여 무효한 데이터 확인
-
-이 설계는 타입 안전성과 성능 최적화를 보장하면서 풍부한 스트림 처리 기능을 제공합니다.
+이 라이브러리는 TypeScript 개발자에게 강력하고 유연한 스트림 처리 기능을 제공하며 함수형 프로그래밍의 이점과 타입 안전성을 결합합니다.