ts-type 2.1.10 → 3.0.2

package/CHANGELOG.md

@@ -3,6 +3,78 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [3.0.2](https://github.com/bluelovers/ws-ts-type/compare/ts-type@3.0.1...ts-type@3.0.2) (2026-03-07)
+
+
+
+### 📦　Code Refactoring
+
+* **ts-type:** 移除不必要的建置工具配置與未使用的引入 ([dc65314](https://github.com/bluelovers/ws-ts-type/commit/dc65314333a9a04dfb3dd857d1617ab253dfeadc))
+
+
+### 📚　Documentation
+
+* **ts-type:** 為類型定義檔案新增雙語 JSDoc 註解 ([6969bbc](https://github.com/bluelovers/ws-ts-type/commit/6969bbcaf991b973d7e4687bfac2d8ae9ecc09ab))
+* **ts-type:** add iterator and proxy type documentation ([6d93ce4](https://github.com/bluelovers/ws-ts-type/commit/6d93ce49526c0081108a639c88c7e2c119fe10f4))
+* **ts-type:** add category guide to README ([26f5860](https://github.com/bluelovers/ws-ts-type/commit/26f586006064c55ef9f1fcf543e7f4c4208b39f8))
+* **ts-type:** 為類型定義檔案新增雙語 JSDoc 註解 ([93836f5](https://github.com/bluelovers/ws-ts-type/commit/93836f5e3b7e3efa949a91a52702d454a62b60ab))
+* **ts-type:** 更新 README 与 package.json 文档，增加双语说明 ([81d926d](https://github.com/bluelovers/ws-ts-type/commit/81d926da85ca492b6810fa20a0b574db75f4ece9))
+* **ts-type:** 新增 ts-type 類型工具庫的完整文檔 ([cba3d50](https://github.com/bluelovers/ws-ts-type/commit/cba3d50752dabbb106444bf060f7d00c176014cf))
+* **ts-type:** add bilingual JSDoc comments to helper and type definition files ([e96a0fd](https://github.com/bluelovers/ws-ts-type/commit/e96a0fd66457639e13d61d9a8926a64ca13b7548))
+* **ts-type:** add bilingual JSDoc comments to helper types and test files ([5893036](https://github.com/bluelovers/ws-ts-type/commit/58930369f50f454595241e5573bdcc03dea4654b))
+* **ts-type:** add bilingual JSDoc comments to type definitions ([8b34984](https://github.com/bluelovers/ws-ts-type/commit/8b349843c65ebf4bd3bb428119243129a07a07c8))
+
+
+### 🛠　Build System
+
+* 更新多個套件的 test 指令為 jest ([61ea53b](https://github.com/bluelovers/ws-ts-type/commit/61ea53bf15fc3ed0e216793200604ae5a52079c9))
+
+
+### ♻️　Chores
+
+* migrate from yarn to pnpm and enhance test infrastructure ([8a5daa2](https://github.com/bluelovers/ws-ts-type/commit/8a5daa2f2022eaf025c3349d4fe5dc8971f8c077))
+
+
+
+## [3.0.1](https://github.com/bluelovers/ws-ts-type/compare/ts-type@2.1.10...ts-type@3.0.1) (2022-10-10)
+
+
+### BREAKING CHANGES
+
+* remove `unpacked` , `bluebird`
+* .
+
+
+
+### ✨　Features
+
+* `ITSStringInferToType` ([cbc1788](https://github.com/bluelovers/ws-ts-type/commit/cbc1788d087a320d2dd837c42cd353d3a43a34f3))
+* ITSPickOne ([4f056cd](https://github.com/bluelovers/ws-ts-type/commit/4f056cdf4078ac06adea3c82bd000229714039d2))
+* remove `unpacked` , `bluebird` ([52247d9](https://github.com/bluelovers/ws-ts-type/commit/52247d98ca482f5d0dfe879d3c6d69936dcfa195))
+
+
+### 📦　Code Refactoring
+
+* . ([b656466](https://github.com/bluelovers/ws-ts-type/commit/b656466b216e331293acb9c77b36054cb0bd0c2b))
+
+
+### 🛠　Build System
+
+* update typescript ([eb59d89](https://github.com/bluelovers/ws-ts-type/commit/eb59d897c2888c7a45406ffcad4b9033608b0b66))
+
+
+### 📌　Dependencies
+
+* update deps ([ab5f3e4](https://github.com/bluelovers/ws-ts-type/commit/ab5f3e48da1f10ddd4445ba6dda9a0a68c5f656f))
+
+
+### 🔖　Miscellaneous
+
+* . ([6588a93](https://github.com/bluelovers/ws-ts-type/commit/6588a932156f6e44e746b3ae2452336a04833153))
+* . ([4eddd02](https://github.com/bluelovers/ws-ts-type/commit/4eddd023316693edd41fda4e2c6338bc507775a6))
+
+
+
 ## [2.1.10](https://github.com/bluelovers/ws-ts-type/compare/ts-type@2.1.9...ts-type@2.1.10) (2022-08-10)
 
 

package/README.md

@@ -1,16 +1,27 @@
-# README
+# ts-type
 
-    add some typescript type and re-export some build-in typescript type
+**TypeScript 類型工具庫** / **TypeScript Type Utility Library**
+
+提供豐富的 TypeScript 類型操作工具和重新導出的內建類型，支援雙語註解（繁體中文 + 英文）。
+
+Provides rich TypeScript type manipulation utilities and re-exported built-in types with bilingual comments (Traditional Chinese + English).
 
 see [index.d.ts](https://github.com/bluelovers/ws-ts-type/tree/master/packages/ts-type/index.d.ts)
 
-## install
+## 安裝 / Installation
 
-```nodemon
+```bash
+# npm
 npm install ts-type
+
+# yarn
+yarn add ts-type
+
+# pnpm
+pnpm add ts-type
 ```
 
-## demo
+## 範例 / Examples
 
 - [demo](https://github.com/bluelovers/ws-ts-type/tree/master/packages/ts-type/test/demo)
 - 
@@ -32,6 +43,8 @@ export declare let a2: A2;
 
 ### ITSOverwriteReturnType
 
+覆寫函數返回值類型 / Overwrite function return type
+
 ```ts
 import { ITSOverwriteReturnType } from '..';
 
@@ -44,6 +57,8 @@ declare let c: ITSOverwriteReturnType<typeof f, string>;
 
 ### Promise / Bluebird / PromiseLike
 
+Promise 相關類型操作 / Promise related type operations
+
 ```nodemon
 npm install @types/bluebird ts-type
 ```
@@ -64,7 +79,9 @@ p3(1).then(v => v.toFixed())
 p4(1).then(v => v.toFixed())
 ```
 
-### this
+### this 類型操作 / this Type Operations
+
+操作函數的 this 類型 / Manipulate function's this type
 
 ```ts
 export declare function t1(this: string, a: number): Promise<number>
@@ -110,19 +127,36 @@ t6 = function ()
 }
 ```
 
-## other
+## 文檔 / Documentation
+
+詳細的類型工具說明文件請參閱 [docs/](docs/) 目錄。
+
+For detailed type utility documentation, see the [docs/](docs/) directory.
+
+### 分類指南 / Category Guide
+
+- [基礎類型](docs/01-base-types.md) - 基礎類型別名與工具 / Base type aliases and utilities
+- [內建類型](docs/02-built-in-types.md) - 重新導出的內建類型 / Re-exported built-in types
+- [函數類型工具](docs/03-function-types.md) - 函數類型操作 / Function type operations
+- [Promise 類型工具](docs/04-promise-types.md) - Promise 相關類型 / Promise related types
+- [陣列與元組類型](docs/05-array-tuple-types.md) - 陣列與元組操作 / Array and tuple operations
+- [物件與記錄類型](docs/06-object-record-types.md) - 物件類型操作 / Object type operations
+- [字串與數字類型](docs/07-string-number-types.md) - 字串與數字類型操作 / String and number operations
+- [邏輯類型工具](docs/08-logic-types.md) - 類型層級邏輯判斷 / Type-level logic
+
+## 其他相關專案 / Related Projects
 
 - [callable-instance2](https://www.npmjs.com/package/callable-instance2) - create an ES6 class that is callable as a function
 - https://github.com/piotrwitek/utility-types
 - 
 
-## docs
+## 文件與教學 / Documentation & Tutorials
 
 - http://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-1.html
 - https://www.tslang.cn/docs/release-notes/typescript-3.1.html#toc-whats-new
 - https://www.logicbig.com/tutorials/misc/typescript.html
 
-## links
+## 相關連結 / Related Links
 
 - https://github.com/krzkaczor/ts-essentials
 - https://github.com/millsp/ts-toolbelt

package/docs/01-base-types.md

@@ -0,0 +1,218 @@
+# 基礎類型 / Base Types
+
+## 概述 / Overview
+
+提供常用的基礎類型別名和工具類型，這些類型是整個庫的建構基礎。
+
+Provides commonly used base type aliases and utility types that form the building blocks of the entire library.
+
+## 來源 / Source
+
+- [`lib/type/base.ts`](../lib/type/base.ts)
+- [`lib/generic.ts`](../lib/generic.ts)
+
+---
+
+## 類型列表 / Type List
+
+### ITSArrayListMaybeReadonly
+
+**陣列類型：可讀寫陣列或唯讀陣列**
+
+```typescript
+type StringList = ITSArrayListMaybeReadonly<string>;
+// type StringList = string[] | readonly string[]
+```
+
+---
+
+### ITSKeys
+
+**鍵的類型：符號、字串或數字**
+
+```typescript
+type Keys = ITSKeys;
+// type Keys = symbol | string | number
+```
+
+---
+
+### ITSConstructorLike
+
+**建構函數類型**
+
+```typescript
+type MyConstructor = ITSConstructorLike<MyClass>;
+// type MyConstructor = new (...args: any) => MyClass
+```
+
+---
+
+### ITSValueOrArray
+
+**值或陣列：單一值或其陣列**
+
+```typescript
+type StringOrArray = ITSValueOrArray<string>;
+// type StringOrArray = string | string[]
+```
+
+---
+
+### ITSValueOrArrayMaybeReadonly
+
+**值或可能唯讀的陣列**
+
+```typescript
+type StringOrList = ITSValueOrArrayMaybeReadonly<string>;
+// type StringOrList = string | string[] | readonly string[]
+```
+
+---
+
+### ITSPropertyKey
+
+**屬性鍵類型：字串或符號**
+
+```typescript
+type PropKey = ITSPropertyKey;
+// type PropKey = string | symbol
+```
+
+---
+
+### ITSAnyFunction
+
+**任意函數類型**
+
+```typescript
+type AnyFunc = ITSAnyFunction;
+// type AnyFunc = (...args: any[]) => any
+```
+
+---
+
+### ITSBasicPrimitive
+
+**基本原始類型：數字、字串或布林值**
+
+```typescript
+type Primitive = ITSBasicPrimitive;
+// type Primitive = number | string | boolean
+```
+
+---
+
+### ITSNullPrimitive
+
+**可為空的原始類型：null 或 undefined**
+
+```typescript
+type Nullish = ITSNullPrimitive;
+// type Nullish = null | undefined
+```
+
+---
+
+## 泛型工具 / Generic Utilities
+
+### ITSTypeFunction
+
+**類型函數：返回指定類型的函數**
+
+```typescript
+type MyTypeFunc = ITSTypeFunction<string>;
+// type MyTypeFunc = (...args: any[]) => string
+```
+
+---
+
+### ITSMapLike
+
+**類似 Map 的介面定義**
+
+```typescript
+interface MyMap extends ITSMapLike<string, number> {
+  get(key: string): number | undefined;
+  has(key: string): boolean;
+}
+```
+
+---
+
+### ITSSetLike
+
+**類似 Set 的介面定義**
+
+```typescript
+interface MySet extends ITSSetLike<string> {
+  has(value: string): boolean;
+}
+```
+
+---
+
+### ITSResolvable
+
+**可解析的類型：支援直接值或 PromiseLike**
+
+```typescript
+type AsyncValue = ITSResolvable<string>;
+// type AsyncValue = string | PromiseLike<string>
+```
+
+---
+
+### ITSArrayLikeWriteable
+
+**可寫入的類陣列介面**
+
+```typescript
+interface MyArrayLike extends ITSArrayLikeWriteable<string> {
+  readonly length: number;
+  [n: number]: string;
+}
+```
+
+---
+
+## 迭代器類型 / Iterator Types
+
+### ITSIterator
+
+**Iterator 類型**
+
+```typescript
+const iterator: ITSIterator<string> = {
+  next() { return { done: false, value: 'test' }; }
+};
+```
+
+---
+
+### ITSIteratorResult
+
+**IteratorResult 類型**
+
+```typescript
+const result: ITSIteratorResult<string> = { done: false, value: 'test' };
+```
+
+---
+
+## Proxy 類型 / Proxy Types
+
+### ITSProxify
+
+**將物件的屬性包裝為 Proxy**
+
+將每個屬性轉換為具有 getter 和 setter 的物件。
+
+```typescript
+interface User { name: string; age: number; }
+type ProxifiedUser = ITSProxify<User>;
+// type ProxifiedUser = {
+//   name: { get(): string; set(v: string): void };
+//   age: { get(): number; set(v: number): void };
+// }
+```

package/docs/02-built-in-types.md

@@ -0,0 +1,200 @@
+# 內建類型 / Built-in Types
+
+## 概述 / Overview
+
+重新導出 TypeScript 內建類型，並提供包裝類型以增強 IDE 識別能力。
+
+Re-exports TypeScript built-in types and provides wrapper types to enhance IDE recognition.
+
+## 來源 / Source
+
+- [`lib/_build-in.ts`](../lib/_build-in.ts)
+
+---
+
+## 類型列表 / Type List
+
+### ITSParameters
+
+**取得函數的參數類型**
+
+取得函數參數的元組類型。
+
+```typescript
+function greet(name: string, age: number): string {
+  return `Hello, ${name}! You are ${age} years old.`;
+}
+
+type GreetParams = ITSParameters<typeof greet>;
+// type GreetParams = [name: string, age: number]
+```
+
+---
+
+### ITSConstructorParameters
+
+**取得建構函數的參數類型**
+
+取得建構函數參數的元組類型。
+
+```typescript
+class User {
+  constructor(name: string, age: number) {}
+}
+
+type UserConstructorParams = ITSConstructorParameters<typeof User>;
+// type UserConstructorParams = [name: string, age: number]
+```
+
+---
+
+### ITSPartial
+
+**將類型的所有屬性設為可選**
+
+```typescript
+interface User {
+  name: string;
+  age: number;
+}
+
+type PartialUser = ITSPartial<User>;
+// type PartialUser = { name?: string; age?: number; }
+```
+
+---
+
+### ITSPick
+
+**從類型 T 中選取指定的屬性 K**
+
+```typescript
+interface User {
+  name: string;
+  age: number;
+  email: string;
+}
+
+type UserName = ITSPick<User, 'name'>;
+// type UserName = { name: string; }
+```
+
+---
+
+### ITSInstanceType
+
+**取得建構函數實例的類型**
+
+```typescript
+class User {
+  name: string;
+}
+
+type UserInstance = ITSInstanceType<typeof User>;
+// type UserInstance = User
+```
+
+---
+
+### ITSClassDecorator
+
+**類別裝飾器類型**
+
+```typescript
+type MyClassDecorator = ITSClassDecorator;
+// type MyClassDecorator = <TFunction extends Function>(target: TFunction) => TFunction | void;
+```
+
+---
+
+### ITSPropertyDecorator
+
+**屬性裝飾器類型**
+
+```typescript
+type MyPropertyDecorator = ITSPropertyDecorator;
+// type MyPropertyDecorator = (target: object, propertyKey: string | symbol) => void;
+```
+
+---
+
+### ITSMethodDecorator
+
+**方法裝飾器類型**
+
+```typescript
+type MyMethodDecorator = ITSMethodDecorator;
+// type MyMethodDecorator = <T>(target: object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T> | void;
+```
+
+---
+
+### ITSParameterDecorator
+
+**參數裝飾器類型**
+
+```typescript
+type MyParameterDecorator = ITSParameterDecorator;
+// type MyParameterDecorator = (target: object, propertyKey: string | symbol, parameterIndex: number) => void;
+```
+
+---
+
+### ITSNonNullable
+
+**從 T 中排除 null 和 undefined**
+
+```typescript
+type NullableString = string | null | undefined;
+type NonNullString = ITSNonNullable<NullableString>;
+// type NonNullString = string
+```
+
+---
+
+## 裝飾器使用範例 / Decorator Usage Examples
+
+### 類別裝飾器
+
+```typescript
+function LogClass(target: any): any {
+  console.log(`Class ${target.name} was defined`);
+  return target;
+}
+
+const MyDecorator: ITSClassDecorator = LogClass;
+
+@MyDecorator
+class MyClass {}
+```
+
+### 屬性裝飾器
+
+```typescript
+function LogProperty(target: any, propertyKey: string | symbol): void {
+  console.log(`Property ${String(propertyKey)} was accessed`);
+}
+
+class MyClass {
+  @LogProperty
+  myProperty: string;
+}
+```
+
+### 方法裝飾器
+
+```typescript
+function LogMethod(target: any, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<any>): TypedPropertyDescriptor<any> {
+  const originalMethod = descriptor.value;
+  descriptor.value = function(...args: any[]) {
+    console.log(`Method ${String(propertyKey)} called with args:`, args);
+    return originalMethod.apply(this, args);
+  };
+  return descriptor;
+}
+
+class MyClass {
+  @LogMethod
+  myMethod() {}
+}
+```