semantic-typescript 0.0.1 → 0.0.3

package/readme.jp.md

@@ -0,0 +1,335 @@
+# 📘 semantic-typescript
+
+TypeScript における**意味論的なデータ処理**のための、強力で型安全なユーティリティライブラリです。  
+コレクション、ストリーム、シーケンスを扱うための関数的スタイルの構成要素を提供し、ソート、フィルタリング、グループ化、統計分析などをサポートします。
+
+**順序付きまたは順序なしのデータ**を処理する場合でも、**統計分析**を行う場合でも、単に**演算を流れるようにチェーンしたい**場合でも、本ライブラリが対応します。
+
+---
+
+## 🧩 特徴
+
+- ✅ 全面的に**型安全なジェネリクス**
+- ✅ **関数型プログラミング**スタイル（map、filter、reduce など）
+- ✅ **意味論的データストリーム**（`Semantic<E>`）による遅延評価
+- ✅ ストリームを具体的な構造に変換するための**コレクター**
+- ✅ **順序付き＆順序なしコレクション** — `toUnordered()` は**最速**（ソートなし）
+- ✅ `sorted()`、`toOrdered()`、比較器による**ソート機能**
+- ✅ **統計分析**（`Statistics`、`NumericStatistics`、`BigIntStatistics`）
+- ✅ 安全な null 値処理のための **`Optional<T>` モナド**
+- ✅ **イテレータとジェネレーター**ベースの設計 — 大規模・非同期データにも適応
+
+---
+
+## 📦 インストール
+
+```bash
+npm install semantic-typescript
+```
+
+---
+
+## 🧠 コア概念
+
+### 1. `Optional<T>` – 安全な null 値処理
+
+`null` または `undefined` になり得る値を格納するモナディックコンテナです。
+
+#### メソッド：
+
+| メソッド | 説明 | 例 |
+|----------|------|-----|
+| `of(value)` | 値をラップ（nullish も可） | `Optional.of(null)` |
+| `ofNullable(v)` | ラップ（nullish を許容） | `Optional.ofNullable(someVar)` |
+| `ofNonNull(v)` | ラップ（null/undefined なら例外） | `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>` – 遅延データストリーム
+
+要素の**遅延評価可能な合成可能シーケンス**です。Java Streams や Kotlin Sequences のような関数的ストリームに似ています。
+
+`from()`、`range()`、`iterate()`、`fill()` などのヘルパーで `Semantic` を作成できます。
+
+#### 作成メソッド：
+
+| 関数 | 説明 | 例 |
+|------|------|-----|
+| `from(iterable)` | Array/Set/Iterable から作成 | `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());
+```
+
+---
+
+## 🛠️ ユーティリティ関数
+
+本ライブラリは多数の**型ガード**と**比較ユーティリティ**もエクスポートしています：
+
+| 関数 | 用途 |
+|------|------|
+| `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 ライセンス**の下で公開されており、商用および個人的利用が自由です。
+
+---
+
+## 🙌 貢献
+
+プルリクエスト、イシュー、提案を歓迎します！
+
+---
+
+## 🚀 クイックスタート概要
+
+| タスク | メソッド |
+|-------|----------|
+| null を安全に処理 | `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.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()` 등) → **데이터를 정렬함**