ts-type 3.0.1 → 3.0.2

package/docs/07-string-number-types.md

@@ -0,0 +1,325 @@
+# 字串與數字類型工具 / String & Number Type Utilities
+
+## 概述 / Overview
+
+提供字串和數字類型的操作工具，包括字面量類型轉換，大小寫轉換、類型推斷等。
+
+Provides string and number type manipulation utilities, including literal type conversion, case conversion, type inference, and more.
+
+## 來源 / Source
+
+- [`lib/helper/string.ts`](../lib/helper/string.ts)
+- [`lib/helper/string/infer.ts`](../lib/helper/string/infer.ts)
+- [`lib/helper/string/literal-string.ts`](../lib/helper/string/literal-string.ts)
+- [`lib/helper/number.ts`](../lib/helper/number.ts)
+
+---
+
+## 字串類型工具 / String Type Utilities
+
+### ITSToStringLiteral
+
+**將類型轉換為字面量類型**
+
+```typescript
+type Str = ITSToStringLiteral<'hello'>;
+// type Str = "hello"
+
+type Num = ITSToStringLiteral<42>;
+// type Num = "42"
+```
+
+---
+
+### ITSTypeAndStringLiteral
+
+**原始類型與其字面量類型的聯合**
+
+適合用在 enum 或 string literal union，可以接受 enum 的字面量或基底類型。
+
+```typescript
+// 應用於 string literal union
+type Status = 'active' | 'inactive' | 'pending';
+type IStatus = ITSTypeAndStringLiteral<Status>;
+// type IStatus = "active" | "inactive" | "pending" | string
+
+// 應用於 enum
+enum EnumPackageManager {
+  'yarn' = 'yarn',
+  'npm' = 'npm',
+  'pnpm' = 'pnpm',
+}
+
+type IPackageManager = ITSTypeAndStringLiteral<EnumPackageManager>;
+// type IPackageManager = EnumPackageManager | string
+
+// 應用於 number，可接受數字或數字字串
+type INumber = ITSTypeAndStringLiteral<number>;
+// type INumber = number | `${number}`
+```
+
+---
+
+### ITSAndStringLiteral
+
+**原始類型 S 與 T 的字面量類型的聯合**
+
+```typescript
+// 應用於數字字面量聯合
+type Result = ITSAndStringLiteral<1 | 2 | 3, number>;
+// type Result = number | "1" | "2" | "3"
+```
+
+---
+
+### ITSAndTypeAndStringLiteral
+
+**原始類型 S、T 與 T 的字面量類型的聯合**
+
+```typescript
+// 應用於數字字面量聯合
+type Result = ITSAndTypeAndStringLiteral<1 | 2 | 3, number>;
+// type Result = number | "1" | "2" | "3"
+```
+
+---
+
+### ITSPascalCase
+
+**將連字符命名字符串轉換為 PascalCase**
+
+```typescript
+type Pascal = ITSPascalCase<'foo-bar'>;
+// type Pascal = "FooBar"
+
+type Multiple = ITSPascalCase<'foo-bar-baz'>;
+// type Multiple = "FooBarBaz"
+```
+
+---
+
+### ITSCamelCase
+
+**將連字符命名字符串轉換為 camelCase**
+
+```typescript
+type Camel = ITSCamelCase<'foo-bar'>;
+// type Camel = "fooBar"
+
+type Multiple = ITSCamelCase<'foo-bar-baz'>;
+// type Multiple = "fooBarBaz"
+```
+
+---
+
+### ITSStringInferToNumber
+
+**從字串推斷數字類型**
+
+```typescript
+type Num = ITSStringInferToNumber<'123'>;
+// type Num = 123
+```
+
+---
+
+### ITSStringInferToBoolean
+
+**從字串推斷布林類型**
+
+```typescript
+type Bool = ITSStringInferToBoolean<'true'>;
+// type Bool = true
+```
+
+---
+
+### ITSStringInferToNull
+
+**從字串推斷 null 類型**
+
+```typescript
+type Null = ITSStringInferToNull<'null'>;
+// type Null = null
+```
+
+---
+
+### ITSStringInferToUndefined
+
+**從字串推斷 undefined 類型**
+
+```typescript
+type Undefined = ITSStringInferToUndefined<'undefined'>;
+// type Undefined = undefined
+```
+
+---
+
+## 數字類型工具 / Number Type Utilities
+
+### ITSNumberString
+
+**將數字轉換為字串字面量類型**
+
+```typescript
+type NumStr = ITSNumberString<42>;
+// type NumStr = "42"
+```
+
+---
+
+### ITSUnpackNumberString
+
+**從字串中解包出數字類型**
+
+```typescript
+type Test = ITSNumberString<123>;
+type Result = ITSUnpackNumberString<Test>;
+// type Result = 123
+```
+
+---
+
+### ITSNumberValue
+
+**數字值類型：數字或字串**
+
+```typescript
+type NumVal = ITSNumberValue;
+// type NumVal = number | string
+```
+
+---
+
+### ITSNumberValue2
+
+**數字值類型2：數字或數字字串**
+
+```typescript
+type NumVal2 = ITSNumberValue2;
+// type NumVal2 = number | "42" (字面量)
+```
+
+---
+
+## 使用範例 / Usage Examples
+
+### 字符串大小寫轉換
+
+```typescript
+import { ITSPascalCase, ITSCamelCase } from 'ts-type';
+
+// 轉為 PascalCase
+type ComponentName = ITSPascalCase<'my-component'>;
+// type ComponentName = "MyComponent"
+
+// 轉為 camelCase
+type variableName = ITSCamelCase<'my-variable'>;
+// type variableName = "myVariable"
+```
+
+### 字串推斷類型
+
+```typescript
+import { ITSStringInferToNumber, ITSStringInferToBoolean } from 'ts-type';
+
+// 從字面量推斷數字
+type Age = ITSStringInferToNumber<'25'>;
+// type Age = 25
+
+// 從字面量推斷布林
+type IsActive = ITSStringInferToBoolean<'true'>;
+// type IsActive = true
+```
+
+### 數字與字串互轉
+
+```typescript
+import { ITSNumberString, ITSUnpackNumberString } from 'ts-type';
+
+// 數字轉字串
+type StrNum = ITSNumberString<100>;
+// type StrNum = "100"
+
+// 字串轉數字
+type Num = ITSUnpackNumberString<'42'>;
+// type Num = 42
+```
+
+### 應用在 String Literal Union
+
+```typescript
+import { ITSTypeAndStringLiteral } from 'ts-type';
+
+// 定義 string literal union
+type OrderStatus = 'pending' | 'processing' | 'shipped' | 'delivered' | 'cancelled';
+
+// 可以接受 string literal 或 string 類型
+type IOrderStatus = ITSTypeAndStringLiteral<OrderStatus>;
+
+// 有效
+const status1: IOrderStatus = 'pending';
+const status2: IOrderStatus = 'processing';
+const status3: IOrderStatus = 'any-string-value'; // 接受任意字串
+
+// 這是有效的，因為 string 是基底類型
+function updateStatus(status: IOrderStatus): void {
+  console.log(`Status: ${status}`);
+}
+
+updateStatus('delivered');
+updateStatus('random-status'); // 合法
+```
+
+### 應用在 Enum
+
+```typescript
+import { ITSTypeAndStringLiteral } from 'ts-type';
+
+enum EnumPackageManager {
+  yarn = 'yarn',
+  npm = 'npm',
+  pnpm = 'pnpm',
+}
+
+// 可以接受 enum 的字面量或基底類型
+type IPackageManager = ITSTypeAndStringLiteral<EnumPackageManager>;
+
+// 有效
+const manager1: IPackageManager = 'yarn';
+const manager2: IPackageManager = 'npm';
+const manager3: IPackageManager = EnumPackageManager.yarn;
+
+// 這也是有效的，因為 string 是基底類型
+const manager4: IPackageManager = 'pnpm';
+
+// 不會接受其他未在 enum 中定義的字串
+// const invalid: IPackageManager = 'bun'; // Error!
+```
+
+### 應用在數字類型
+
+```typescript
+import { ITSTypeAndStringStringLiteral, ITSLiteral, ITSAndAndTypeAndStringLiteral } from 'ts-type';
+
+// 接受數字或數字字串
+type INumber = ITSTypeAndStringLiteral<number>;
+// type INumber = number | `${number}`
+
+const num1: INumber = 42;
+const num2: INumber = '42';
+
+// 數字字面量聯合
+type Result1 = ITSAndStringLiteral<1 | 2 | 3, number>;
+// type Result1 = number | "1" | "2" | "3"
+
+const val1: Result1 = 1;
+const val2: Result1 = '2';
+
+type Result2 = ITSAndTypeAndStringLiteral<1 | 2 | 3, number>;
+// type Result2 = number | "1" | "2" | "3"
+
+const val3: Result2 = 3;
+const val4: Result2 = '1';
+```

package/docs/08-logic-types.md

@@ -0,0 +1,154 @@
+# 邏輯類型工具 / Logic Type Utilities
+
+## 概述 / Overview
+
+提供類型層級的邏輯判斷工具，包括檢測 any、never、union 等特殊類型。
+
+Provides type-level logic detection utilities, including detecting special types like any, never, union, and more.
+
+## 來源 / Source
+
+- [`lib/logic/any.ts`](../lib/logic/any.ts)
+- [`lib/logic/never.ts`](../lib/logic/never.ts)
+- [`lib/logic/union/index.ts`](../lib/logic/union/index.ts)
+
+---
+
+## 類型列表 / Type List
+
+### ITSLogicIsAny
+
+**檢測類型是否為 any**
+
+利用 any 與任何類型交叉都會得到 any 的特性來檢測。
+
+```typescript
+type Test1 = ITSLogicIsAny<any>;
+// type Test1 = true
+
+type Test2 = ITSLogicIsAny<string>;
+// type Test2 = false
+```
+
+---
+
+### ITSLogicNotAny
+
+**檢測類型是否不為 any**
+
+```typescript
+type Test1 = ITSLogicNotAny<any>;
+// type Test1 = false
+
+type Test2 = ITSLogicNotAny<string>;
+// type Test2 = true
+```
+
+---
+
+### ITSLogicIsNever
+
+**檢測類型是否為 never**
+
+利用 never 是所有類型的子類型特性來檢測。
+
+```typescript
+type Test1 = ITSLogicIsNever<never>;
+// type Test1 = true
+
+type Test2 = ITSLogicIsNever<string>;
+// type Test2 = false
+```
+
+---
+
+### ITSLogicIsUnion
+
+**檢測類型是否為聯合類型**
+
+```typescript
+type Test1 = ITSLogicIsUnion<string | number>;
+// type Test1 = true
+
+type Test2 = ITSLogicIsUnion<string>;
+// type Test2 = false
+```
+
+---
+
+### ITSLogicIsSingleNonUnion
+
+**檢測類型是否為單一非聯合類型**
+
+```typescript
+type Test1 = ITSLogicIsSingleNonUnion01<string>;
+// type Test1 = true
+
+type Test2 = ITSLogicIsSingleNonUnion01<string | number>;
+// type Test2 = false
+
+type Test3 = ITSLogicIsSingleNonUnion01<any>;
+// type Test3 = false
+```
+
+---
+
+## 使用範例 / Usage Examples
+
+### 檢測 Any 類型
+
+```typescript
+import { ITSLogicIsAny, ITSLogicNotAny } from 'ts-type';
+
+// 檢測是否為 any
+function isAny<T>(value: T): ITSLogicIsAny<T> {
+  return true as any;
+}
+
+const anyResult = isAny('test');      // true
+const stringResult = isAny('hello');  // false
+
+// 檢測是否不為 any
+function isNotAny<T>(value: T): ITSLogicNotAny<T> {
+  return true as any;
+}
+
+const notAnyResult = isNotAny('test'); // true
+const anyCheck = isNotAny<any>('test'); // false
+```
+
+### 條件類型中的應用
+
+```typescript
+import { ITSLogicIsAny } from 'ts-type';
+
+type SafeReturn<T> = ITSLogicIsAny<T> extends true
+  ? unknown
+  : T;
+
+type Result1 = SafeReturn<any>;      // unknown
+type Result2 = SafeReturn<string>;   // string
+type Result3 = SafeReturn<number>;   // number
+```
+
+### 防止 Any 類型
+
+```typescript
+import { ITSLogicIsAny } from 'ts-type';
+
+function strictFunction<T extends string | number>(value: T): T {
+  // 如果傳入 any，則回傳 never，防止錯誤使用
+  type Check = ITSLogicIsAny<T>;
+  if (Check extends true) {
+    throw new Error('any type is not allowed');
+  }
+  return value;
+}
+
+// 正常工作
+strictFunction('hello'); // "hello"
+strictFunction(42);      // 42
+
+// 編譯錯誤
+// strictFunction(anyValue); // Error!
+```

package/docs/README.md

@@ -0,0 +1,155 @@
+# ts-type 文件索引 / ts-type Documentation Index
+
+## 概述 / Overview
+
+ts-type 是一個 TypeScript 類型工具庫，提供豐富的類型操作工具和重新導出的內建類型。
+
+ts-type is a TypeScript type utility library that provides rich type manipulation utilities and re-exported built-in types.
+
+---
+
+## 目錄 / Table of Contents
+
+### 1. [基礎類型 / Base Types](01-base-types.md)
+
+包含常用的基礎類型別名和工具類型，是整個庫的建構基礎。
+
+- `ITSArrayListMaybeReadonly` - 陣列類型
+- `ITSKeys` - 鍵的類型
+- `ITSConstructorLike` - 建構函數類型
+- `ITSValueOrArray` - 值或陣列
+- `ITSAnyFunction` - 任意函數類型
+- `ITSBasicPrimitive` - 基本原始類型
+- `ITSTypeFunction` - 類型函數
+- `ITSMapLike` / `ITSSetLike` - 類似 Map/Set 的介面
+- `ITSIterator` / `ITSIteratorResult` - 迭代器類型
+- `ITSProxify` - Proxy 類型
+
+---
+
+### 2. [內建類型 / Built-in Types](02-built-in-types.md)
+
+重新導出 TypeScript 內建類型，並提供包裝類型以增強 IDE 識別能力。
+
+- `ITSParameters` - 函數參數類型
+- `ITSConstructorParameters` - 建構函數參數類型
+- `ITSPartial` / `ITSPick` - 類型操作
+- `ITSInstanceType` - 實例類型
+- `ITSClassDecorator` / `ITSPropertyDecorator` - 裝飾器類型
+- `ITSNonNullable` - 排除 null/undefined
+
+---
+
+### 3. [函數類型工具 / Function Type Utilities](03-function-types.md)
+
+提供函數類型的操作工具。
+
+- `ITSOverwriteReturnType` - 覆寫返回值類型
+- `ITSWrapFunctionPromise` - 包裝為 Promise
+- `ITSOverwriteThisFunction` - 覆寫 this 類型
+- `ITSUnionToIntersection` - 聯集轉交集
+
+---
+
+### 4. [Promise 類型工具 / Promise Type Utilities](04-promise-types.md)
+
+提供 Promise 相關的類型操作工具。
+
+- `ITSAwaitedReturnType` - 解析 Promise 返回類型
+- `ITSDeferred` - 延遲物件類型
+- `ITSPromiseFulfilledResult` - 解決結果
+- `ITSPromiseRejectedResult` - 拒絕結果
+- `ITSPromiseSettledResult` - Settled 結果
+
+---
+
+### 5. [陣列與元組類型工具 / Array & Tuple Type Utilities](05-array-tuple-types.md)
+
+提供陣列和元組類型的操作工具。
+
+- `ITSValueOfArray` - 陣列元素類型
+- `ITSToReadonlyArray` / `ITSToWriteableArray` - 陣列互轉
+- `ITSTupleKeys` - 元組索引鍵
+- `ITSEmptyTuple` - 空元組
+
+---
+
+### 6. [物件與記錄類型工具 / Object & Record Type Utilities](06-object-record-types.md)
+
+提供物件類型的選擇、覆寫、合併等操作。
+
+- `ITSOverwrite` - 覆寫屬性
+- `ITSMergeBoth` - 合併物件
+- `ITSRequiredPick` / `ITSPartialPick` - 選擇並設定必填/可選
+- `ITSRequireAtLeastOne` / `ITSRequireOnlyOne` - 互斥鍵
+- `ITSReadonlyPartial` / `ITSWriteable` - 唯讀/可寫屬性
+- `ITSOmitIndexSignatures` - 移除索引簽名
+
+---
+
+### 7. [字串與數字類型工具 / String & Number Type Utilities](07-string-number-types.md)
+
+提供字串和數字類型的操作工具。
+
+- `ITSToStringLiteral` - 轉為字面量類型
+- `ITSTypeAndStringLiteral` - 原始類型與字面量聯合
+- `ITSPascalCase` / `ITSCamelCase` - 大小寫轉換
+- `ITSStringInferToNumber` / `ITSStringInferToBoolean` - 字串推斷類型
+- `ITSNumberString` - 數字轉字串
+
+---
+
+### 8. [邏輯類型工具 / Logic Type Utilities](08-logic-types.md)
+
+提供類型層級的邏輯判斷工具。
+
+- `ITSLogicIsAny` - 檢測 any 類型
+- `ITSLogicNotAny` - 檢測非 any 類型
+- `ITSLogicIsNever` - 檢測 never 類型
+- `ITSLogicIsUnion` - 檢測聯合類型
+- `ITSLogicIsSingleNonUnion` - 檢測單一非聯合類型
+
+---
+
+## 快速開始 / Quick Start
+
+### 安裝 / Installation
+
+```bash
+# npm
+npm install ts-type
+
+# yarn
+yarn add ts-type
+
+# pnpm
+pnpm add ts-type
+```
+
+### 使用 / Usage
+
+```typescript
+import { 
+  ITSOverwrite, 
+  ITSRequiredPick, 
+  ITSValueOfArray 
+} from 'ts-type';
+
+// 覆寫屬性
+type UpdatedConfig = ITSOverwrite<{ host: string; port: number }, { port: string }>;
+
+// 選擇必填鍵
+type RequiredUser = ITSRequiredPick<User, 'id'>;
+
+// 提取陣列元素類型
+type Element = ITSValueOfArray<string[]>;
+```
+
+---
+
+## 相關資源 / Related Resources
+
+- [TypeScript 官方文檔](https://www.typescriptlang.org/docs/)
+- [ts-toolbelt](https://github.com/millsp/ts-toolbelt)
+- [type-challenges](https://github.com/type-challenges/type-challenges)
+- [ts-essentials](https://github.com/krzkaczor/ts-essentials)

package/lib/_build-in.d.ts

@@ -1,18 +1,72 @@
 /**
- * re-export build-in type
- * for some time ide is stupid can't found types
+ * Created by user on 2019/6/11.
+ *
+ * 重新導出內建類型
+ * Re-export built-in types
+ *
+ * 在某些情況下 IDE 無法正確識別類型，此文件提供統一的類別導出
+ * In some cases IDE cannot correctly identify types, this file provides unified type exports
+ */
+/**
+ * 取得函數的參數類型
+ * Get the parameter types of a function
+ *
+ * @see Parameters
  */
 export type ITSParameters<T extends (...args: any[]) => any> = Parameters<T>;
+/**
+ * 取得建構函數的參數類型
+ * Get the constructor parameter types
+ *
+ * @see ConstructorParameters
+ */
 export type ITSConstructorParameters<T extends new (...args: any[]) => any> = ConstructorParameters<T>;
+/**
+ * 將類型的所有屬性設為可選
+ * Make all properties of T optional
+ *
+ * @see Partial
+ */
 export type ITSPartial<T> = Partial<T>;
+/**
+ * 從類型 T 中選取指定的屬性 K
+ * Pick a set of properties K from T
+ *
+ * @see Pick
+ */
 export type ITSPick<T, K extends keyof T = keyof T> = Pick<T, K>;
+/**
+ * 取得建構函數實例的類型
+ * Get the instance type created by a constructor
+ *
+ * @see InstanceType
+ */
 export type ITSInstanceType<T extends new (...args: any[]) => any> = InstanceType<T>;
+/**
+ * 類別裝飾器類型
+ * Class decorator type
+ */
 export type ITSClassDecorator = <TFunction extends Function>(target: TFunction) => TFunction | void;
+/**
+ * 屬性裝飾器類型
+ * Property decorator type
+ */
 export type ITSPropertyDecorator = (target: object, propertyKey: string | symbol) => void;
+/**
+ * 方法裝飾器類型
+ * Method decorator type
+ */
 export type ITSMethodDecorator = <T>(target: object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T> | void;
+/**
+ * 參數裝飾器類型
+ * Parameter decorator type
+ */
 export type ITSParameterDecorator = (target: object, propertyKey: string | symbol, parameterIndex: number) => void;
 /**
+ * 從 T 中排除 null 和 undefined
  * Exclude null and undefined from T
+ *
+ * @see NonNullable
  * @see https://devblogs.microsoft.com/typescript/announcing-typescript-4-8/#improved-intersection-reduction-union-compatibility-and-narrowing
  */
 export type ITSNonNullable<T> = NonNullable<T>;