semantic-typescript 0.0.1 → 0.0.2

package/readme.kr.md

@@ -0,0 +1,335 @@
+# 📘 semantic-typescript
+
+TypeScript에서 **의미론적 데이터 처리(Semantic Data Processing)** 를 위한 강력하고 타입 안전한 유틸리티 라이브러리입니다.  
+컬렉션, 스트림, 시퀀스를 함수형 스타일로 다룰 수 있는 구성 요소들을 제공하며, 정렬, 필터링, 그룹화, 통계 분석 등을 지원합니다.
+
+**정렬된 데이터든 정렬되지 않은 데이터든**, **통계 분석을 하든**, 혹은 단순히 **연산을 유창하게 연결(chain)하고 싶든**, 이 라이브러리가 도와드립니다.
+
+---
+
+## 🧩 주요 기능
+
+- ✅ 전체적으로 **타입 안전한 제네릭(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()` |
+
+#### 예제:
+
+```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
+```
+
+---
+
+### 2. `Semantic<E>` — 지연 평가 데이터 스트림
+
+요소들의 **지연 평가(Lazy), 구성 가능한 시퀀스**입니다. Java의 Streams나 Kotlin의 Sequences와 유사합니다.
+
+`from()`, `range()`, `iterate()`, `fill()` 같은 헬퍼 함수로 `Semantic` 스트림을 생성할 수 있습니다.
+
+#### 생성 방법:
+
+| 함수 | 설명 | 예제 |
+|------|------|------|
+| `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)` |
+
+#### 주요 연산자:
+
+| 메서드 | 설명 | 예제 |
+|--------|------|------|
+| `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)` |
+
+---
+
+### 3. `toUnordered()` — 🚀 가장 빠름, 정렬 없음
+
+**정렬이 필요 없고 최고의 성능을 원한다면** 아래와 같이 사용하세요:
+
+```typescript
+const fastest = semanticStream.toUnordered();
+```
+
+🔥 **어떠한 정렬 알고리즘도 적용되지 않습니다.**  
+순서가 중요하지 않고 속도가 최우선일 때 이 방법을 사용하세요.
+
+---
+
+### 4. `toOrdered()` 및 `sorted()` — 정렬된 출력
+
+**정렬된 결과가 필요한 경우** 다음을 사용할 수 있습니다:
+
+```typescript
+const ordered = semanticStream.sorted(); // 자연 정렬
+const customSorted = semanticStream.sorted((a, b) => a - b); // 커스텀 비교자
+const orderedCollectable = semanticStream.toOrdered(); // 정렬됨
+```
+
+⚠️ 이 메서드들은 **요소를 정렬**하며, 자연 정렬 또는 제공된 비교자를 사용합니다.
+
+---
+
+### 5. `Collector<E, A, R>` — 데이터 집계
+
+컬렉터를 사용하면 스트림을 **단일 값 또는 복잡한 구조로 축약**할 수 있습니다.
+
+내장된 정적 팩토리:
+
+```typescript
+Collector.full(identity, accumulator, finisher)
+Collector.shortable(identity, interruptor, accumulator, finisher)
+```
+
+하지만 보통은 `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>` — 정렬된 데이터
+
+요소들을 **자동으로 정렬**하고 싶다면 이 클래스를 사용하세요.
+
+**커스텀 비교자**를 받거나 자연 정렬을 사용할 수 있습니다.
+
+```typescript
+const sorted = new OrderedCollectable(stream);
+const customSorted = new OrderedCollectable(stream, (a, b) => b - a);
+```
+
+🔒 **정렬된 출력이 보장됩니다.**
+
+---
+
+### 8. `UnorderedCollectable<E>` — 정렬 없음 (🚀 가장 빠름)
+
+**순서가 중요하지 않고 최고의 성능이 필요한 경우** 다음을 사용하세요:
+
+```typescript
+const unordered = new UnorderedCollectable(stream);
+// 또는
+const fastest = semanticStream.toUnordered();
+```
+
+✅ **정렬 알고리즘이 실행되지 않음**  
+✅ **순서가 중요하지 않을 때 최고의 성능**
+
+---
+
+### 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()` |
+
+---
+
+## 🧪 전체 예제
+
+```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());
+```
+
+---
+
+## 🛠️ 유틸리티 함수
+
+다양한 **타입 가드(Type Guards)** 와 **비교 도구**도 제공됩니다:
+
+| 함수 | 용도 |
+|------|------|
+| `isString(x)` | `string` 타입 가드 |
+| `isNumber(x)` | `number` 타입 가드 |
+| `isBoolean(x)` | `boolean` 타입 가드 |
+| `isIterable(x)` | 객체가 반복 가능한지 확인 |
+| `useCompare(a, b)` | 범용 비교 함수 |
+| `useRandom(x)` | 의사 난수 생성기 (재미삼아) |
+
+---
+
+## 🧩 고급: 커스텀 생성기 & 윈도우
+
+무한 또는 제어된 데이터 스트림을 위한 **커스텀 생성기**를 만들 수 있습니다:
+
+```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);
+```
+
+또는 **슬라이딩 윈도우**를 사용할 수도 있습니다:
+
+```typescript
+const windowed = ordered.slide(3n, 2n); // 크기 3, 스텝 2
+```
+
+---
+
+## 📄 라이선스
+
+이 프로젝트는 **MIT 라이선스** 로 제공되며, 상업적·개인적 용도로 자유롭게 사용할 수 있습니다.
+
+---
+
+## 🙌 기여
+
+Pull Request, 이슈(Issue), 아이디어 제안 등 모두 환영합니다!
+
+---
+
+## 🚀 빠른 시작 요약
+
+| 작업 | 메서드 |
+|------|--------|
+| null/undefined 안전하게 처리 | `Optional<T>` |
+| 스트림 생성 | `from([...])`, `range()`, `fill()` |
+| 데이터 변환 | `map()`, `filter()` |
+| 데이터 정렬 | `sorted()`, `toOrdered()` |
+| 정렬 없음 (가장 빠름) | `toUnordered()` ✅ |
+| 그룹화 / 집계 | `toMap()`, `group()`, `Collector` |
+| 통계 | `NumericStatistics`, `mean()`, `median()` 등 |
+
+---
+
+## 🔗 링크
+
+- 📦 npm: https://www.npmjs.com/package/semantic-typescript
+- 🐙 GitHub: https://github.com/eloyhere/semantic-typescript
+- 📘 문서: 소스 코드 / 타입 정의 참조
+
+---
+
+**TypeScript에서 함수형, 타입 안전하고 구성 가능한 데이터 처리를 즐겨보세요.** 🚀
+
+--- 
+
+✅ **참고:**  
+- `toUnordered()` → **정렬 없음, 가장 빠름**  
+- 그 외 (`sorted()`, `toOrdered()` 등) → **데이터를 정렬함**

package/readme.md

@@ -0,0 +1,335 @@
+# 📘 semantic-typescript
+
+A powerful, type-safe utility library for **semantic data processing** in TypeScript.  
+Provides composable, functional-style constructs for working with collections, streams, and sequences — with support for sorting, filtering, grouping, statistics, and more.
+
+Whether you're processing **ordered or unordered data**, performing **statistical analysis**, or simply **chaining operations fluently**, this library has you covered.
+
+---
+
+## 🧩 Features
+
+- ✅ **Type-safe generics** throughout
+- ✅ **Functional programming** style (map, filter, reduce, etc.)
+- ✅ **Semantic data streams** (`Semantic<E>`) for lazy evaluation
+- ✅ **Collectors** for transforming streams into concrete structures
+- ✅ **Ordered & Unordered Collectables** — with `toUnordered()` being the **fastest** (no sorting)
+- ✅ **Sorting support** via `sorted()`, `toOrdered()`, comparators
+- ✅ **Statistical analysis** (`Statistics`, `NumericStatistics`, `BigIntStatistics`)
+- ✅ **Optional<T>** monad for safe nullable handling
+- ✅ **Iterators & Generators** based design — suitable for large or asynchronous data
+
+---
+
+## 📦 Installation
+
+```bash
+npm install semantic-typescript
+```
+
+---
+
+## 🧠 Core Concepts
+
+### 1. `Optional<T>` – Safe Nullable Handling
+
+A monadic container for values that may be `null` or `undefined`.
+
+#### Methods:
+
+| Method         | Description                                      | Example |
+|----------------|--------------------------------------------------|---------|
+| `of(value)`    | Wrap a value (may be nullish)                    | `Optional.of(null)` |
+| `ofNullable(v)`| Wrap, allowing nullish values                    | `Optional.ofNullable(someVar)` |
+| `ofNonNull(v)` | Wrap, throws if null/undefined                   | `Optional.ofNonNull(5)` |
+| `get()`        | Retrieve value or throw if empty                 | `opt.get()` |
+| `getOrDefault(d)`| Retrieve value or default                       | `opt.getOrDefault(0)` |
+| `ifPresent(fn)`| Execute side-effect if present                    | `opt.ifPresent(x => console.log(x))` |
+| `map(fn)`      | Transform value if present                       | `opt.map(x => x + 1)` |
+| `filter(fn)`   | Retain value only if predicate passes            | `opt.filter(x => x > 0)` |
+| `isEmpty()`    | Check if empty                                   | `opt.isEmpty()` |
+| `isPresent()`  | Check if contains a value                        | `opt.isPresent()` |
+
+#### Example:
+
+```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 or 0
+```
+
+---
+
+### 2. `Semantic<E>` – Lazy Data Stream
+
+A **lazy, composable sequence** of elements. Resembles functional streams such as Java Streams or Kotlin Sequences.
+
+Create a `Semantic` using helpers like `from()`, `range()`, `iterate()`, or `fill()`.
+
+#### Creators:
+
+| Function       | Description                                  | Example |
+|----------------|----------------------------------------------|---------|
+| `from(iterable)` | Create from Array/Set/Iterable               | `from([1, 2, 3])` |
+| `range(start, end, step?)` | Generate number range                | `range(0, 5)` → 0,1,2,3,4 |
+| `fill(element, count)` | Repeat an element N times                 | `fill('a', 3n)` |
+| `iterate(gen)`   | Use a custom generator function              | `iterate(genFn)` |
+
+#### Common Operators:
+
+| Method             | Description                                       | Example |
+|--------------------|---------------------------------------------------|---------|
+| `map(fn)`          | Transform each element                            | `.map(x => x * 2)` |
+| `filter(fn)`       | Retain elements passing predicate                 | `.filter(x => x > 10)` |
+| `limit(n)`         | Limit to first N elements                         | `.limit(5)` |
+| `skip(n)`          | Skip first N elements                             | `.skip(2)` |
+| `distinct()`       | Remove duplicates (uses Set by default)           | `.distinct()` |
+| `sorted()`         | Sort elements (natural ordering)                  | `.sorted()` |
+| `sorted(comparator)`| Custom sorting                                   | `.sorted((a, b) => a - b)` |
+| `toOrdered()`      | Sort and return `OrderedCollectable`              | `.toOrdered()` |
+| `toUnordered()`    | **No sorting** – fastest possible collectable     | `.toUnordered()` ✅ |
+| `collect(collector)`| Aggregate using a `Collector`                     | `.collect(Collector.full(...))` |
+| `toArray()`        | Convert to Array                                  | `.toArray()` |
+| `toSet()`          | Convert to Set                                    | `.toSet()` |
+| `toMap(keyFn, valFn)`| Convert to Map                                 | `.toMap(x => x.id, x => x)` |
+
+---
+
+### 3. `toUnordered()` – 🚀 Fastest, No Sorting
+
+If you **do not require ordering** and seek the **fastest possible performance**, use:
+
+```typescript
+const fastest = semanticStream.toUnordered();
+```
+
+🔥 **No sorting algorithm is applied.**  
+Ideal when order is irrelevant and maximum speed is desired.
+
+---
+
+### 4. `toOrdered()` and `sorted()` – Sorted Output
+
+If you need **sorted output**, use:
+
+```typescript
+const ordered = semanticStream.sorted(); // Natural ordering
+const customSorted = semanticStream.sorted((a, b) => a - b); // Custom comparator
+const orderedCollectable = semanticStream.toOrdered(); // Also sorted
+```
+
+⚠️ These methods **will sort** the elements using either natural or provided comparator.
+
+---
+
+### 5. `Collector<E, A, R>` – Aggregate Data
+
+Collectors enable you to **reduce streams into single or complex structures**.
+
+Built-in static factories:
+
+```typescript
+Collector.full(identity, accumulator, finisher)
+Collector.shortable(identity, interruptor, accumulator, finisher)
+```
+
+Typically used via higher-level helpers on `Collectable` classes.
+
+---
+
+### 6. `Collectable<E>` (Abstract)
+
+Base class for:
+
+- `OrderedCollectable<E>` – Sorted output
+- `UnorderedCollectable<E>` – No sorting, fastest
+- `WindowCollectable<E>` – Sliding windows
+- `Statistics<E, D>` – Statistical aggregations
+
+#### Common Methods (via inheritance):
+
+| Method         | Description                              | Example |
+|----------------|------------------------------------------|---------|
+| `count()`      | Count elements                           | `.count()` |
+| `toArray()`    | Convert to Array                         | `.toArray()` |
+| `toSet()`      | Convert to Set                           | `.toSet()` |
+| `toMap(k, v)`  | Convert to Map                           | `.toMap(x => x.id, x => x)` |
+| `group(k)`     | Group by key                             | `.group(x => x.category)` |
+| `findAny()`    | Any matching element (Optional)          | `.findAny()` |
+| `findFirst()`  | First element (Optional)                 | `.findFirst()` |
+| `reduce(...)`  | Custom reduction                         | `.reduce((a,b) => a + b, 0)` |
+
+---
+
+### 7. `OrderedCollectable<E>` – Sorted Data
+
+If you require elements to be **automatically sorted**, use this.
+
+Accepts a **custom comparator** or uses natural order.
+
+```typescript
+const sorted = new OrderedCollectable(stream);
+const customSorted = new OrderedCollectable(stream, (a, b) => b - a);
+```
+
+🔒 **Sorted output is guaranteed.**
+
+---
+
+### 8. `UnorderedCollectable<E>` – No Sorting (🚀 Fastest)
+
+If you **do not require ordering** and seek the **fastest performance**, use:
+
+```typescript
+const unordered = new UnorderedCollectable(stream);
+// OR
+const fastest = semanticStream.toUnordered();
+```
+
+✅ **No sorting algorithm executed**  
+✅ **Best performance** when order is irrelevant
+
+---
+
+### 9. `Statistics<E, D>` – Statistical Analysis
+
+Abstract base for analysing numeric data.
+
+#### Subclasses:
+
+- `NumericStatistics<E>` – For `number` values
+- `BigIntStatistics<E>` – For `bigint` values
+
+##### Common statistical methods:
+
+| Method            | Description                          | Example |
+|-------------------|--------------------------------------|---------|
+| `mean()`          | Arithmetic mean                      | `.mean()` |
+| `median()`        | Median value                         | `.median()` |
+| `mode()`          | Most frequent value                  | `.mode()` |
+| `minimum()`       | Smallest element                     | `.minimum()` |
+| `maximum()`       | Largest element                      | `.maximum()` |
+| `range()`         | Maximum − Minimum                    | `.range()` |
+| `variance()`      | Variance                             | `.variance()` |
+| `standardDeviation()` | Standard deviation               | `.standardDeviation()` |
+| `summate()`       | Sum of elements                      | `.summate()` |
+| `quantile(q)`     | Value at q-th percentile (0–1)       | `.quantile(0.5)` → median |
+| `frequency()`     | Frequency map                        | `.frequency()` |
+
+---
+
+## 🧪 Full Example
+
+```typescript
+import { from, toUnordered, toOrdered, sorted, NumericStatistics } from 'semantic-typescript';
+
+// Sample data
+const numbers = from([10, 2, 8, 4, 5, 6]);
+
+// 🚀 Fastest: no sorting
+const fastest = numbers.toUnordered();
+console.log(fastest.toArray()); // e.g. [10, 2, 8, 4, 5, 6] (original order)
+
+// 🔢 Naturally sorted
+const ordered = numbers.sorted();
+console.log(ordered.toArray()); // [2, 4, 5, 6, 8, 10]
+
+// 📊 Perform statistical analysis
+const stats = new NumericStatistics(numbers);
+console.log('Mean:', stats.mean());
+console.log('Median:', stats.median());
+console.log('Mode:', stats.mode());
+console.log('Range:', stats.range());
+console.log('Standard Deviation:', stats.standardDeviation());
+```
+
+---
+
+## 🛠️ Utility Functions
+
+The library also exports numerous **type guards** and **comparison utilities**:
+
+| Function         | Purpose                          |
+|------------------|----------------------------------|
+| `isString(x)`    | Type guard for `string`          |
+| `isNumber(x)`    | Type guard for `number`          |
+| `isBoolean(x)`   | Type guard for `boolean`         |
+| `isIterable(x)`  | Checks if object is iterable     |
+| `useCompare(a, b)`| Universal comparison function     |
+| `useRandom(x)`   | Pseudo-random generator (fun)    |
+
+---
+
+## 🧩 Advanced: Custom Generators & Windows
+
+You may create custom **generators** for infinite or controlled data streams:
+
+```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);
+```
+
+Or employ **sliding windows**:
+
+```typescript
+const windowed = ordered.slide(3n, 2n); // windows of 3, stepping by 2
+```
+
+---
+
+## 📄 License
+
+This project is licensed under the **MIT License** – free for commercial and personal use.
+
+---
+
+## 🙌 Contributing
+
+Pull requests, issues, and suggestions are most welcome!
+
+---
+
+## 🚀 Quick Start Summary
+
+| Task | Method |
+|------|--------|
+| Safely handle nulls | `Optional<T>` |
+| Create a stream | `from([...])`, `range()`, `fill()` |
+| Transform data | `map()`, `filter()` |
+| Sort data | `sorted()`, `toOrdered()` |
+| No sort (fastest) | `toUnordered()` ✅ |
+| Group / aggregate | `toMap()`, `group()`, `Collector` |
+| Statistics | `NumericStatistics`, `mean()`, `median()`, etc. |
+
+---
+
+## 🔗 Links
+
+- 📦 npm: https://www.npmjs.com/package/semantic-typescript
+- 🐙 GitHub: https://github.com/eloyhere/semantic-typescript
+- 📘 Documentation: See source code / type definitions
+
+---
+
+**Enjoy composable, type-safe, functional data processing in TypeScript.** 🚀
+
+--- 
+
+✅ **Remember:**  
+- `toUnordered()` → **No sort, fastest**  
+- All others (e.g. `sorted()`, `toOrdered()`) → **Sort data**