ts-type-predicates 1.0.9 → 1.0.12

package/CHANGELOG.md

@@ -3,6 +3,51 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.0.12](https://github.com/bluelovers/ws-ts-type/compare/ts-type-predicates@1.0.10...ts-type-predicates@1.0.12) (2026-03-15)
+
+
+
+### ✨　Features
+
+* **is-array:** 新增唯讀陣列類型斷言支援及完善文檔說明 ([4f0d97d](https://github.com/bluelovers/ws-ts-type/commit/4f0d97d86c93c5a82a66712695fa69cd5a78344a))
+
+
+### 📚　Documentation
+
+* **ts-type-predicates:** 新增 typePredicates 強化 Narrowing 用法說明 ([a0eeb18](https://github.com/bluelovers/ws-ts-type/commit/a0eeb188a5d67f3983d8986955bcab70eaf52497))
+
+
+### 🛠　Build System
+
+* 優化類型定義輸出流程並移除 snapshot 更新標誌 ([5b9aeca](https://github.com/bluelovers/ws-ts-type/commit/5b9aeca2434e581f818d8872ffde43236f203e57))
+
+
+### 🔖　Miscellaneous
+
+* . ([43bb6af](https://github.com/bluelovers/ws-ts-type/commit/43bb6afdf390a090c87bdb872e5b6f9fd9932669))
+
+
+
+## [1.0.10](https://github.com/bluelovers/ws-ts-type/compare/ts-type-predicates@1.0.9...ts-type-predicates@1.0.10) (2026-03-07)
+
+
+
+### 📚　Documentation
+
+* enhance documentation and JSDoc comments across multiple packages ([88ee99b](https://github.com/bluelovers/ws-ts-type/commit/88ee99b3a489645ca53093357cc3523dbe7996e0))
+
+
+### 🛠　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))
+
+
+
 ## [1.0.9](https://github.com/bluelovers/ws-ts-type/compare/ts-type-predicates@1.0.8...ts-type-predicates@1.0.9) (2022-10-10)
 
 

package/README.md

@@ -1,8 +1,27 @@
-# README.md
+# ts-type-predicates
 
-    use asserts for make type predicates work
+使用斷言（assert）讓類型斷言（type predicates）運作的實用工具函式
 
-## install
+Use asserts to make type predicates work with better runtime validation
+
+---
+
+## 功能特點 / Features
+
+- 結合 TypeScript 斷言函式與類型斷言功能
+- Combine TypeScript assertion functions with type predicate functionality
+- 支援運行時驗證與編譯時類型縮小
+- Support runtime validation and compile-time type narrowing
+- 可自訂錯誤訊息
+- Customizable error messages
+- 可選擇只做類型收窄不拋出錯誤
+- Optional type narrowing without throwing errors
+- 可用於強化替代 Narrowing
+- Can be used to enhance or replace Narrowing
+
+---
+
+## 安裝 / Install
 
 ```bash
 yarn add ts-type-predicates
@@ -10,3 +29,96 @@ yarn-tool add ts-type-predicates
 yt add ts-type-predicates
 ```
 
+---
+
+## 使用範例 / Usage Examples
+
+### 基本用法
+
+```typescript
+import { typePredicates, typeNarrowed } from 'ts-type-predicates';
+
+// 使用斷言函式 - 失敗時拋出錯誤
+function processValue(value: string | number) {
+    typePredicates<string>(value, typeof value === 'string');
+    // 現在 TypeScript 知道 value 是 string
+    console.log(value.toUpperCase());
+}
+
+// 使用類型收窄 - 回傳布林值
+function checkValue(value: unknown) {
+    if (typeNarrowed<string>(value, typeof value === 'string')) {
+        console.log(value.length);
+    }
+}
+```
+
+### 參數省略
+
+參數除了第一個以外都能省略：
+
+```typescript
+import { typePredicates } from 'ts-type-predicates';
+
+// 只有第一個參數是必需的
+typePredicates<string>(value);
+```
+
+### 強化替代 Narrowing
+
+當標準的 Narrowing 無法正確收窄類型時，可以使用 `typePredicates` 強制收窄：
+
+```typescript
+import { typePredicates } from 'ts-type-predicates';
+
+// Narrowing 無法處理的情況
+type Mixed = { type: 'a'; value: string } | { type: 'b'; value: number };
+
+function process(data: Mixed) {
+    // ❌ Narrowing 無法正確收窄 value 的類型
+    if (data.type === 'a') {
+        // data.value 仍然是 string | number
+        console.log(data.value.toUpperCase()); // 錯誤
+    }
+
+    // ✅ 使用 typePredicates 強制收窄 - 更精簡的寫法 (需要配合使用 @ts-ignore 註釋)
+    if (typePredicates<string>(data.value, data.type === 'a')) {
+        // data.value 現在正確收窄為 string
+        console.log(data.value.toUpperCase()); // 正確
+    }
+}
+```
+
+### 忽略表達式結果
+
+當只需要類型收窄，不需要運行時驗證時：
+
+```typescript
+import { typePredicates } from 'ts-type-predicates';
+
+// 只做類型收窄，不拋出錯誤
+function narrowValue(value: unknown) {
+    typePredicates<string>(value, typeof value === 'string', undefined, true);
+    // value 現在被收窄為 string（但運行時不驗證）
+    console.log(value.toUpperCase());
+}
+```
+
+---
+
+## 與標準 Narrowing 的比較
+
+| 特性 | Narrowing（內建） | typePredicates |
+|------|-------------------|----------------|
+| 語法 | `if (typeof x === "string")` | `typePredicates<string>(x)` |
+| 彈性 | 有限 | 可自訂任意邏輯 |
+| 錯誤處理 | 無 | 可拋出自訂錯誤 |
+| 強制收窄 | 無法 | 可以 |
+| 複雜類型 | 需多重檢查 | 可一次完成 |
+
+---
+
+## 相關資源
+
+- [TypeScript 官方文件 - Type Predicates](https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates)
+- [TypeScript 官方文件 - Assertion Functions](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions)

package/dist/index.cjs

@@ -1,8 +1,8 @@
 
 'use strict'
 
-if (typeof process !== 'undefined' && process.env.NODE_ENV === 'production') {
-  module.exports = require('./index.cjs.production.min.cjs')
-} else {
+if (typeof process !== 'undefined' && process.env.NODE_ENV !== 'production') {
   module.exports = require('./index.cjs.development.cjs')
+} else {
+  module.exports = require('./index.cjs.production.min.cjs')
 }

package/dist/index.cjs.development.cjs

@@ -4,20 +4,60 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 var assert = require('assert');
 
+/// <reference types="node" />
+/**
+ * 處理表達式，回傳布林值結果
+ * Handle expression and return boolean result
+ *
+ * @param actual - 實際值 / Actual value
+ * @param expression - 表達式，可為布林值或函式 / Expression, can be boolean or function
+ * @returns 布林值結果 / Boolean result
+ */
 function _handleExpression(actual, expression = true) {
-  var _expression;
-
-  (_expression = expression) !== null && _expression !== void 0 ? _expression : expression = true;
-
+  expression !== null && expression !== void 0 ? expression : expression = true;
   if (typeof expression === 'function') {
     expression = !!expression(actual);
   }
-
   return expression;
 }
+/**
+ * 使用斷言（assert）讓類型斷言（type predicates）運作
+ * Use asserts for make type predicates work
+ *
+ * 此函式結合了 TypeScript 的斷言函式與類型斷言功能，
+ * 允許在運行時驗證類型並在編譯時縮小類型範圍
+ *
+ * @param T - 預期的類型 / Expected type
+ * @param actual - 實際值 / Actual value
+ * @param expression - 斷言條件，可為布林值或函式（可選）/ Assertion condition, can be boolean or function (optional)
+ * @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)
+ * @param ignoreExpression - 是否忽略表達式結果，設為 true 時只做類型收窄不拋出錯誤（可選）/ Whether to ignore expression result (optional)
+ * @throws 當表達式結果為 false 時拋出 AssertionError / Throws AssertionError when expression is false
+ *
+ * @see https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates
+ * @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions
+ *
+ * @example
+ * // 基本用法：失敗時拋出錯誤
+ * typePredicates<string>(value, typeof value === 'string');
+ *
+ * @example
+ * // 參數除了第一個以外都能省略
+ * typePredicates<string>(value);
+ *
+ * @example
+ * // 使用於 if 條件中 - 強制類型收窄 (需要配合使用 @ts-ignore 註釋)
+ * if (typePredicates<string>(data.value, data.type === 'a')) {
+ *     // data.value 現在正確收窄為 string
+ *     console.log(data.value.toUpperCase());
+ * }
+ *
+ * @example
+ * // 忽略表達式結果，只做類型收窄，不拋出錯誤
+ * typePredicates<string>(value, typeof value === 'string', undefined, true);
+ */
 function typePredicates(actual, expression = true, message, ignoreExpression) {
   expression = _handleExpression(actual, expression);
-
   if (expression !== true && ignoreExpression !== true) {
     throw new assert.AssertionError({
       message: message !== null && message !== void 0 ? message : `actual ${actual} not as expected`,
@@ -26,19 +66,38 @@ function typePredicates(actual, expression = true, message, ignoreExpression) {
       operator: 'typePredicates'
     });
   }
+  // @ts-ignore
+  return expression;
 }
+/**
+ * 類型收窄函式，回傳類型斷言結果
+ * Type narrowing function, returns type predicate result
+ *
+ * 此函式不會拋出錯誤，而是回傳布林值表示是否符合預期類型
+ * 可用於需要條件邏輯而非斷言的場景
+ *
+ * @param T - 預期的類型 / Expected type
+ * @param actual - 實際值 / Actual value
+ * @param expression - 驗證條件，可為布林值或函式（可選）/ Validation condition, can be boolean or function (optional)
+ * @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)
+ * @returns 是否符合預期類型 / Whether it matches the expected type
+ *
+ * @example
+ * // 使用 typeNarrowed - 回傳布林值
+ * if (typeNarrowed<string>(value, typeof value === 'string')) {
+ *     console.log(value.length);
+ * }
+ */
 function typeNarrowed(actual, expression = true, message) {
   expression = _handleExpression(actual, expression);
-
   if (expression !== true) {
     expression = false;
   }
-
   return expression;
 }
 
 exports._handleExpression = _handleExpression;
-exports["default"] = typePredicates;
+exports.default = typePredicates;
 exports.typeNarrowed = typeNarrowed;
 exports.typePredicates = typePredicates;
 //# sourceMappingURL=index.cjs.development.cjs.map

package/dist/index.cjs.development.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs.development.cjs","sources":["../src/index.ts"],"sourcesContent":["import { AssertionError } from 'assert';\n\nexport function _handleExpression<T, P = any>(actual: T | P, expression: boolean | ((actual: T | P) => any) = true)\n{\n\texpression ??= true;\n\n\tif (typeof expression === 'function')\n\t{\n\t\texpression = !!expression(actual);\n\t}\n\n\treturn expression\n}\n\n/**\n * use asserts for make type predicates work\n *\n * @see https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates\n * @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions\n */\nexport function typePredicates<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string, ignoreExpression?: boolean): asserts actual is T\n{\n\texpression = _handleExpression(actual, expression);\n\n\tif (expression !== true && ignoreExpression !== true)\n\t{\n\t\tthrow new AssertionError({\n\t\t\tmessage: message ?? `actual ${actual} not as expected`,\n\t\t\tactual,\n\t\t\texpected: expression,\n\t\t\toperator: 'typePredicates',\n\t\t})\n\t}\n}\n\nexport function typeNarrowed<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string): actual is T\n{\n\texpression = _handleExpression(actual, expression);\n\n\tif (expression !== true)\n\t{\n\t\texpression = false;\n\t}\n\n\treturn expression\n}\n\nexport default typePredicates;\n"],"names":["expression","message","typeNarrowed","actual"],"mappings":";;;;;;;;;;;EAAA,IAAwC,OAAA,UAAA,KAAA,UAAA,EAAA;cAI7B,eAAU;AAInB,GAAA;;AAGD,EAAA,OAAAA,UAAA,CAAA;;AAWA,SAAA,cAAA,CAAA,MAAA,EAAA,UAAA,GAAA,IAAA,EAAA,OAAA,EAAA,gBAAA,EAAA;YAIC,oBAAU;;AACT,EAAA,IAAA,UAAA,KAAA,IAAA,IAAA,gBAAA,KAAA,IAAA,EAAA;;MAEAC;;;;;AAMG,GAAA;AAEL,CAAA;SAIWC,aAAAC,QAASH,UAAA,SAAAC,SAAA;AAGpBD,EAAAA,UAAA,oBAAiB,CAAjB,MAAA,EAAA,UAAA,CAAA,CAAA;;MAGDA,UAAA,KAAA,IAAA,EAAA;;;;;;;;;;;;"}
+{"version":3,"file":"index.cjs.development.cjs","sources":["../src/index.ts"],"sourcesContent":["/// <reference types=\"node\" />\nimport { AssertionError } from 'assert';\n\n/**\n * 處理表達式，回傳布林值結果\n * Handle expression and return boolean result\n *\n * @param actual - 實際值 / Actual value\n * @param expression - 表達式，可為布林值或函式 / Expression, can be boolean or function\n * @returns 布林值結果 / Boolean result\n */\nexport function _handleExpression<T, P = any>(actual: T | P, expression: boolean | ((actual: T | P) => any) = true)\n{\n\texpression ??= true;\n\n\tif (typeof expression === 'function')\n\t{\n\t\texpression = !!expression(actual);\n\t}\n\n\treturn expression\n}\n\n/**\n * 使用斷言（assert）讓類型斷言（type predicates）運作\n * Use asserts for make type predicates work\n *\n * 此函式結合了 TypeScript 的斷言函式與類型斷言功能，\n * 允許在運行時驗證類型並在編譯時縮小類型範圍\n *\n * @param T - 預期的類型 / Expected type\n * @param actual - 實際值 / Actual value\n * @param expression - 斷言條件，可為布林值或函式（可選）/ Assertion condition, can be boolean or function (optional)\n * @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)\n * @param ignoreExpression - 是否忽略表達式結果，設為 true 時只做類型收窄不拋出錯誤（可選）/ Whether to ignore expression result (optional)\n * @throws 當表達式結果為 false 時拋出 AssertionError / Throws AssertionError when expression is false\n *\n * @see https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates\n * @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions\n *\n * @example\n * // 基本用法：失敗時拋出錯誤\n * typePredicates<string>(value, typeof value === 'string');\n *\n * @example\n * // 參數除了第一個以外都能省略\n * typePredicates<string>(value);\n *\n * @example\n * // 使用於 if 條件中 - 強制類型收窄 (需要配合使用 @ts-ignore 註釋)\n * if (typePredicates<string>(data.value, data.type === 'a')) {\n *     // data.value 現在正確收窄為 string\n *     console.log(data.value.toUpperCase());\n * }\n *\n * @example\n * // 忽略表達式結果，只做類型收窄，不拋出錯誤\n * typePredicates<string>(value, typeof value === 'string', undefined, true);\n */\nexport function typePredicates<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string, ignoreExpression?: boolean): asserts actual is T\n{\n\texpression = _handleExpression(actual, expression);\n\n\tif (expression !== true && ignoreExpression !== true)\n\t{\n\t\tthrow new AssertionError({\n\t\t\tmessage: message ?? `actual ${actual} not as expected`,\n\t\t\tactual,\n\t\t\texpected: expression,\n\t\t\toperator: 'typePredicates',\n\t\t})\n\t}\n\n\t// @ts-ignore\n\treturn expression\n}\n\n/**\n * 類型收窄函式，回傳類型斷言結果\n * Type narrowing function, returns type predicate result\n *\n * 此函式不會拋出錯誤，而是回傳布林值表示是否符合預期類型\n * 可用於需要條件邏輯而非斷言的場景\n *\n * @param T - 預期的類型 / Expected type\n * @param actual - 實際值 / Actual value\n * @param expression - 驗證條件，可為布林值或函式（可選）/ Validation condition, can be boolean or function (optional)\n * @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)\n * @returns 是否符合預期類型 / Whether it matches the expected type\n *\n * @example\n * // 使用 typeNarrowed - 回傳布林值\n * if (typeNarrowed<string>(value, typeof value === 'string')) {\n *     console.log(value.length);\n * }\n */\nexport function typeNarrowed<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string): actual is T\n{\n\texpression = _handleExpression(actual, expression);\n\n\tif (expression !== true)\n\t{\n\t\texpression = false;\n\t}\n\n\treturn expression\n}\n\nexport default typePredicates;\n"],"names":["expression","actual","expected","operator"],"mappings":";;;;;;;;AAoEG;;AApEH;AACA;;;;;;;;AAUA,GAAA;SAEWA,UAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAuDRC,MAAA;AAEAC,MAAAA,QAAC,EAAAF,UAAA;MAGUG,QAAA,EAAA,gBAAA;AAEb,KAAA,CAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/index.cjs.production.min.cjs

@@ -1,2 +1,27 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e=require("assert");function _handleExpression(e,r=!0){var t;return null!==(t=r)&&void 0!==t||(r=!0),"function"==typeof r&&(r=!!r(e)),r}function typePredicates(r,t=!0,s,n){if(!0!==(t=_handleExpression(r,t))&&!0!==n)throw new e.AssertionError({message:null!=s?s:`actual ${r} not as expected`,actual:r,expected:t,operator:"typePredicates"})}exports._handleExpression=_handleExpression,exports.default=typePredicates,exports.typeNarrowed=function typeNarrowed(e,r=!0,t){return!0!==(r=_handleExpression(e,r))&&(r=!1),r},exports.typePredicates=typePredicates;
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: !0
+});
+
+var e = require("assert");
+
+function _handleExpression(e, r = !0) {
+  return null != r || (r = !0), "function" == typeof r && (r = !!r(e)), r;
+}
+
+function typePredicates(r, t = !0, s, n) {
+  if (!0 !== (t = _handleExpression(r, t)) && !0 !== n) throw new e.AssertionError({
+    message: null != s ? s : `actual ${r} not as expected`,
+    actual: r,
+    expected: t,
+    operator: "typePredicates"
+  });
+  return t;
+}
+
+exports._handleExpression = _handleExpression, exports.default = typePredicates, 
+exports.typeNarrowed = function typeNarrowed(e, r = !0, t) {
+  return !0 !== (r = _handleExpression(e, r)) && (r = !1), r;
+}, exports.typePredicates = typePredicates;
 //# sourceMappingURL=index.cjs.production.min.cjs.map

package/dist/index.cjs.production.min.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs.production.min.cjs","sources":["../src/index.ts"],"sourcesContent":["import { AssertionError } from 'assert';\n\nexport function _handleExpression<T, P = any>(actual: T | P, expression: boolean | ((actual: T | P) => any) = true)\n{\n\texpression ??= true;\n\n\tif (typeof expression === 'function')\n\t{\n\t\texpression = !!expression(actual);\n\t}\n\n\treturn expression\n}\n\n/**\n * use asserts for make type predicates work\n *\n * @see https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates\n * @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions\n */\nexport function typePredicates<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string, ignoreExpression?: boolean): asserts actual is T\n{\n\texpression = _handleExpression(actual, expression);\n\n\tif (expression !== true && ignoreExpression !== true)\n\t{\n\t\tthrow new AssertionError({\n\t\t\tmessage: message ?? `actual ${actual} not as expected`,\n\t\t\tactual,\n\t\t\texpected: expression,\n\t\t\toperator: 'typePredicates',\n\t\t})\n\t}\n}\n\nexport function typeNarrowed<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string): actual is T\n{\n\texpression = _handleExpression(actual, expression);\n\n\tif (expression !== true)\n\t{\n\t\texpression = false;\n\t}\n\n\treturn expression\n}\n\nexport default typePredicates;\n"],"names":["expression","typePredicates","actual","message","ignoreExpression","typeNarrowed"],"mappings":"qIAWC,wCAXuC,mBAAAA,cAWvCA,EAWA,SAAAC,eAAAC,EAAAF,GAAA,EAAAG,EAAAC,GAKE,IAAA,iCAAA,IAAAA,8BAEAD,+FAQF,0GAIWE,aAAAH,EAASF,KAAAG,UAMrB,KAHCH,oBAAAE,EAAAF"}
+{"version":3,"file":"index.cjs.production.min.cjs","sources":["../src/index.ts"],"sourcesContent":["/// <reference types=\"node\" />\nimport { AssertionError } from 'assert';\n\n/**\n * 處理表達式，回傳布林值結果\n * Handle expression and return boolean result\n *\n * @param actual - 實際值 / Actual value\n * @param expression - 表達式，可為布林值或函式 / Expression, can be boolean or function\n * @returns 布林值結果 / Boolean result\n */\nexport function _handleExpression<T, P = any>(actual: T | P, expression: boolean | ((actual: T | P) => any) = true)\n{\n\texpression ??= true;\n\n\tif (typeof expression === 'function')\n\t{\n\t\texpression = !!expression(actual);\n\t}\n\n\treturn expression\n}\n\n/**\n * 使用斷言（assert）讓類型斷言（type predicates）運作\n * Use asserts for make type predicates work\n *\n * 此函式結合了 TypeScript 的斷言函式與類型斷言功能，\n * 允許在運行時驗證類型並在編譯時縮小類型範圍\n *\n * @param T - 預期的類型 / Expected type\n * @param actual - 實際值 / Actual value\n * @param expression - 斷言條件，可為布林值或函式（可選）/ Assertion condition, can be boolean or function (optional)\n * @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)\n * @param ignoreExpression - 是否忽略表達式結果，設為 true 時只做類型收窄不拋出錯誤（可選）/ Whether to ignore expression result (optional)\n * @throws 當表達式結果為 false 時拋出 AssertionError / Throws AssertionError when expression is false\n *\n * @see https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates\n * @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions\n *\n * @example\n * // 基本用法：失敗時拋出錯誤\n * typePredicates<string>(value, typeof value === 'string');\n *\n * @example\n * // 參數除了第一個以外都能省略\n * typePredicates<string>(value);\n *\n * @example\n * // 使用於 if 條件中 - 強制類型收窄 (需要配合使用 @ts-ignore 註釋)\n * if (typePredicates<string>(data.value, data.type === 'a')) {\n *     // data.value 現在正確收窄為 string\n *     console.log(data.value.toUpperCase());\n * }\n *\n * @example\n * // 忽略表達式結果，只做類型收窄，不拋出錯誤\n * typePredicates<string>(value, typeof value === 'string', undefined, true);\n */\nexport function typePredicates<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string, ignoreExpression?: boolean): asserts actual is T\n{\n\texpression = _handleExpression(actual, expression);\n\n\tif (expression !== true && ignoreExpression !== true)\n\t{\n\t\tthrow new AssertionError({\n\t\t\tmessage: message ?? `actual ${actual} not as expected`,\n\t\t\tactual,\n\t\t\texpected: expression,\n\t\t\toperator: 'typePredicates',\n\t\t})\n\t}\n\n\t// @ts-ignore\n\treturn expression\n}\n\n/**\n * 類型收窄函式，回傳類型斷言結果\n * Type narrowing function, returns type predicate result\n *\n * 此函式不會拋出錯誤，而是回傳布林值表示是否符合預期類型\n * 可用於需要條件邏輯而非斷言的場景\n *\n * @param T - 預期的類型 / Expected type\n * @param actual - 實際值 / Actual value\n * @param expression - 驗證條件，可為布林值或函式（可選）/ Validation condition, can be boolean or function (optional)\n * @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)\n * @returns 是否符合預期類型 / Whether it matches the expected type\n *\n * @example\n * // 使用 typeNarrowed - 回傳布林值\n * if (typeNarrowed<string>(value, typeof value === 'string')) {\n *     console.log(value.length);\n * }\n */\nexport function typeNarrowed<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string): actual is T\n{\n\texpression = _handleExpression(actual, expression);\n\n\tif (expression !== true)\n\t{\n\t\texpression = false;\n\t}\n\n\treturn expression\n}\n\nexport default typePredicates;\n"],"names":["expression","actual","expected","operator"],"mappings":";;;;;;;;;wEAaWA;;;;;;IAuDRC;IAEAC,UAACF;IAGUG,UAAA;;;;;;;;"}

package/dist/index.d.ts

@@ -1,15 +1,67 @@
+/**
+ * 處理表達式，回傳布林值結果
+ * Handle expression and return boolean result
+ *
+ * @param actual - 實際值 / Actual value
+ * @param expression - 表達式，可為布林值或函式 / Expression, can be boolean or function
+ * @returns 布林值結果 / Boolean result
+ */
 export declare function _handleExpression<T, P = any>(actual: T | P, expression?: boolean | ((actual: T | P) => any)): boolean;
 /**
- * use asserts for make type predicates work
+ * 使用斷言（assert）讓類型斷言（type predicates）運作
+ * Use asserts for make type predicates work
+ *
+ * 此函式結合了 TypeScript 的斷言函式與類型斷言功能，
+ * 允許在運行時驗證類型並在編譯時縮小類型範圍
+ *
+ * @param T - 預期的類型 / Expected type
+ * @param actual - 實際值 / Actual value
+ * @param expression - 斷言條件，可為布林值或函式（可選）/ Assertion condition, can be boolean or function (optional)
+ * @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)
+ * @param ignoreExpression - 是否忽略表達式結果，設為 true 時只做類型收窄不拋出錯誤（可選）/ Whether to ignore expression result (optional)
+ * @throws 當表達式結果為 false 時拋出 AssertionError / Throws AssertionError when expression is false
  *
  * @see https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates
  * @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions
+ *
+ * @example
+ * // 基本用法：失敗時拋出錯誤
+ * typePredicates<string>(value, typeof value === 'string');
+ *
+ * @example
+ * // 參數除了第一個以外都能省略
+ * typePredicates<string>(value);
+ *
+ * @example
+ * // 使用於 if 條件中 - 強制類型收窄 (需要配合使用 @ts-ignore 註釋)
+ * if (typePredicates<string>(data.value, data.type === 'a')) {
+ *     // data.value 現在正確收窄為 string
+ *     console.log(data.value.toUpperCase());
+ * }
+ *
+ * @example
+ * // 忽略表達式結果，只做類型收窄，不拋出錯誤
+ * typePredicates<string>(value, typeof value === 'string', undefined, true);
  */
 export declare function typePredicates<T, P = any>(actual: T | P, expression?: boolean | ((actual: T | P) => any), message?: string, ignoreExpression?: boolean): asserts actual is T;
+/**
+ * 類型收窄函式，回傳類型斷言結果
+ * Type narrowing function, returns type predicate result
+ *
+ * 此函式不會拋出錯誤，而是回傳布林值表示是否符合預期類型
+ * 可用於需要條件邏輯而非斷言的場景
+ *
+ * @param T - 預期的類型 / Expected type
+ * @param actual - 實際值 / Actual value
+ * @param expression - 驗證條件，可為布林值或函式（可選）/ Validation condition, can be boolean or function (optional)
+ * @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)
+ * @returns 是否符合預期類型 / Whether it matches the expected type
+ *
+ * @example
+ * // 使用 typeNarrowed - 回傳布林值
+ * if (typeNarrowed<string>(value, typeof value === 'string')) {
+ *     console.log(value.length);
+ * }
+ */
 export declare function typeNarrowed<T, P = any>(actual: T | P, expression?: boolean | ((actual: T | P) => any), message?: string): actual is T;
-
-export {
-	typePredicates as default,
-};
-
-export {};
+export default typePredicates;

package/dist/index.esm.mjs

@@ -1,9 +1,7 @@
 import { AssertionError as e } from "assert";
 
 function _handleExpression(e, t = !0) {
-  var r;
-  return null !== (r = t) && void 0 !== r || (t = !0), "function" == typeof t && (t = !!t(e)), 
-  t;
+  return null != t || (t = !0), "function" == typeof t && (t = !!t(e)), t;
 }
 
 function typePredicates(t, r = !0, n, a) {
@@ -13,6 +11,7 @@ function typePredicates(t, r = !0, n, a) {
     expected: r,
     operator: "typePredicates"
   });
+  return r;
 }
 
 function typeNarrowed(e, t = !0, r) {

package/dist/index.esm.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.esm.mjs","sources":["../src/index.ts"],"sourcesContent":["import { AssertionError } from 'assert';\n\nexport function _handleExpression<T, P = any>(actual: T | P, expression: boolean | ((actual: T | P) => any) = true)\n{\n\texpression ??= true;\n\n\tif (typeof expression === 'function')\n\t{\n\t\texpression = !!expression(actual);\n\t}\n\n\treturn expression\n}\n\n/**\n * use asserts for make type predicates work\n *\n * @see https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates\n * @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions\n */\nexport function typePredicates<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string, ignoreExpression?: boolean): asserts actual is T\n{\n\texpression = _handleExpression(actual, expression);\n\n\tif (expression !== true && ignoreExpression !== true)\n\t{\n\t\tthrow new AssertionError({\n\t\t\tmessage: message ?? `actual ${actual} not as expected`,\n\t\t\tactual,\n\t\t\texpected: expression,\n\t\t\toperator: 'typePredicates',\n\t\t})\n\t}\n}\n\nexport function typeNarrowed<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string): actual is T\n{\n\texpression = _handleExpression(actual, expression);\n\n\tif (expression !== true)\n\t{\n\t\texpression = false;\n\t}\n\n\treturn expression\n}\n\nexport default typePredicates;\n"],"names":["expression","typePredicates","actual","message","ignoreExpression","typeNarrowed"],"mappings":";;;;EAWC,qDAXuC,qBAAAA;EAWvCA;;;AAWA,SAAAC,eAAAC,GAAAF,KAAA,GAAAG,GAAAC;EAKE,KAAA,wCAAA,MAAAA;IAEAD;;;;;AAQF;;SAIWE,aAAAH,GAASF,QAAAG;UAMrB,OAHCH,sBAAAE,GAAAF;;;"}
+{"version":3,"file":"index.esm.mjs","sources":["../src/index.ts"],"sourcesContent":["/// <reference types=\"node\" />\nimport { AssertionError } from 'assert';\n\n/**\n * 處理表達式，回傳布林值結果\n * Handle expression and return boolean result\n *\n * @param actual - 實際值 / Actual value\n * @param expression - 表達式，可為布林值或函式 / Expression, can be boolean or function\n * @returns 布林值結果 / Boolean result\n */\nexport function _handleExpression<T, P = any>(actual: T | P, expression: boolean | ((actual: T | P) => any) = true)\n{\n\texpression ??= true;\n\n\tif (typeof expression === 'function')\n\t{\n\t\texpression = !!expression(actual);\n\t}\n\n\treturn expression\n}\n\n/**\n * 使用斷言（assert）讓類型斷言（type predicates）運作\n * Use asserts for make type predicates work\n *\n * 此函式結合了 TypeScript 的斷言函式與類型斷言功能，\n * 允許在運行時驗證類型並在編譯時縮小類型範圍\n *\n * @param T - 預期的類型 / Expected type\n * @param actual - 實際值 / Actual value\n * @param expression - 斷言條件，可為布林值或函式（可選）/ Assertion condition, can be boolean or function (optional)\n * @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)\n * @param ignoreExpression - 是否忽略表達式結果，設為 true 時只做類型收窄不拋出錯誤（可選）/ Whether to ignore expression result (optional)\n * @throws 當表達式結果為 false 時拋出 AssertionError / Throws AssertionError when expression is false\n *\n * @see https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates\n * @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions\n *\n * @example\n * // 基本用法：失敗時拋出錯誤\n * typePredicates<string>(value, typeof value === 'string');\n *\n * @example\n * // 參數除了第一個以外都能省略\n * typePredicates<string>(value);\n *\n * @example\n * // 使用於 if 條件中 - 強制類型收窄 (需要配合使用 @ts-ignore 註釋)\n * if (typePredicates<string>(data.value, data.type === 'a')) {\n *     // data.value 現在正確收窄為 string\n *     console.log(data.value.toUpperCase());\n * }\n *\n * @example\n * // 忽略表達式結果，只做類型收窄，不拋出錯誤\n * typePredicates<string>(value, typeof value === 'string', undefined, true);\n */\nexport function typePredicates<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string, ignoreExpression?: boolean): asserts actual is T\n{\n\texpression = _handleExpression(actual, expression);\n\n\tif (expression !== true && ignoreExpression !== true)\n\t{\n\t\tthrow new AssertionError({\n\t\t\tmessage: message ?? `actual ${actual} not as expected`,\n\t\t\tactual,\n\t\t\texpected: expression,\n\t\t\toperator: 'typePredicates',\n\t\t})\n\t}\n\n\t// @ts-ignore\n\treturn expression\n}\n\n/**\n * 類型收窄函式，回傳類型斷言結果\n * Type narrowing function, returns type predicate result\n *\n * 此函式不會拋出錯誤，而是回傳布林值表示是否符合預期類型\n * 可用於需要條件邏輯而非斷言的場景\n *\n * @param T - 預期的類型 / Expected type\n * @param actual - 實際值 / Actual value\n * @param expression - 驗證條件，可為布林值或函式（可選）/ Validation condition, can be boolean or function (optional)\n * @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)\n * @returns 是否符合預期類型 / Whether it matches the expected type\n *\n * @example\n * // 使用 typeNarrowed - 回傳布林值\n * if (typeNarrowed<string>(value, typeof value === 'string')) {\n *     console.log(value.length);\n * }\n */\nexport function typeNarrowed<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string): actual is T\n{\n\texpression = _handleExpression(actual, expression);\n\n\tif (expression !== true)\n\t{\n\t\texpression = false;\n\t}\n\n\treturn expression\n}\n\nexport default typePredicates;\n"],"names":["expression","actual","expected","operator"],"mappings":";;;wEAaWA;;;;;;IAuDRC;IAEAC,UAACF;IAGUG,UAAA;;;;;;;;;"}

package/dist/index.umd.development.cjs

@@ -4,20 +4,60 @@
 	(global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.TsTypePredicates = {}, global.assert));
 })(this, (function (exports, assert) { 'use strict';
 
+	/// <reference types="node" />
+	/**
+	 * 處理表達式，回傳布林值結果
+	 * Handle expression and return boolean result
+	 *
+	 * @param actual - 實際值 / Actual value
+	 * @param expression - 表達式，可為布林值或函式 / Expression, can be boolean or function
+	 * @returns 布林值結果 / Boolean result
+	 */
 	function _handleExpression(actual, expression = true) {
-	  var _expression;
-
-	  (_expression = expression) !== null && _expression !== void 0 ? _expression : expression = true;
-
+	  expression !== null && expression !== void 0 ? expression : expression = true;
 	  if (typeof expression === 'function') {
 	    expression = !!expression(actual);
 	  }
-
 	  return expression;
 	}
+	/**
+	 * 使用斷言（assert）讓類型斷言（type predicates）運作
+	 * Use asserts for make type predicates work
+	 *
+	 * 此函式結合了 TypeScript 的斷言函式與類型斷言功能，
+	 * 允許在運行時驗證類型並在編譯時縮小類型範圍
+	 *
+	 * @param T - 預期的類型 / Expected type
+	 * @param actual - 實際值 / Actual value
+	 * @param expression - 斷言條件，可為布林值或函式（可選）/ Assertion condition, can be boolean or function (optional)
+	 * @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)
+	 * @param ignoreExpression - 是否忽略表達式結果，設為 true 時只做類型收窄不拋出錯誤（可選）/ Whether to ignore expression result (optional)
+	 * @throws 當表達式結果為 false 時拋出 AssertionError / Throws AssertionError when expression is false
+	 *
+	 * @see https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates
+	 * @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions
+	 *
+	 * @example
+	 * // 基本用法：失敗時拋出錯誤
+	 * typePredicates<string>(value, typeof value === 'string');
+	 *
+	 * @example
+	 * // 參數除了第一個以外都能省略
+	 * typePredicates<string>(value);
+	 *
+	 * @example
+	 * // 使用於 if 條件中 - 強制類型收窄 (需要配合使用 @ts-ignore 註釋)
+	 * if (typePredicates<string>(data.value, data.type === 'a')) {
+	 *     // data.value 現在正確收窄為 string
+	 *     console.log(data.value.toUpperCase());
+	 * }
+	 *
+	 * @example
+	 * // 忽略表達式結果，只做類型收窄，不拋出錯誤
+	 * typePredicates<string>(value, typeof value === 'string', undefined, true);
+	 */
 	function typePredicates(actual, expression = true, message, ignoreExpression) {
 	  expression = _handleExpression(actual, expression);
-
 	  if (expression !== true && ignoreExpression !== true) {
 	    throw new assert.AssertionError({
 	      message: message !== null && message !== void 0 ? message : `actual ${actual} not as expected`,
@@ -26,19 +66,38 @@
 	      operator: 'typePredicates'
 	    });
 	  }
+	  // @ts-ignore
+	  return expression;
 	}
+	/**
+	 * 類型收窄函式，回傳類型斷言結果
+	 * Type narrowing function, returns type predicate result
+	 *
+	 * 此函式不會拋出錯誤，而是回傳布林值表示是否符合預期類型
+	 * 可用於需要條件邏輯而非斷言的場景
+	 *
+	 * @param T - 預期的類型 / Expected type
+	 * @param actual - 實際值 / Actual value
+	 * @param expression - 驗證條件，可為布林值或函式（可選）/ Validation condition, can be boolean or function (optional)
+	 * @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)
+	 * @returns 是否符合預期類型 / Whether it matches the expected type
+	 *
+	 * @example
+	 * // 使用 typeNarrowed - 回傳布林值
+	 * if (typeNarrowed<string>(value, typeof value === 'string')) {
+	 *     console.log(value.length);
+	 * }
+	 */
 	function typeNarrowed(actual, expression = true, message) {
 	  expression = _handleExpression(actual, expression);
-
 	  if (expression !== true) {
 	    expression = false;
 	  }
-
 	  return expression;
 	}
 
 	exports._handleExpression = _handleExpression;
-	exports["default"] = typePredicates;
+	exports.default = typePredicates;
 	exports.typeNarrowed = typeNarrowed;
 	exports.typePredicates = typePredicates;
 

package/dist/index.umd.development.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.umd.development.cjs","sources":["../src/index.ts"],"sourcesContent":["import { AssertionError } from 'assert';\n\nexport function _handleExpression<T, P = any>(actual: T | P, expression: boolean | ((actual: T | P) => any) = true)\n{\n\texpression ??= true;\n\n\tif (typeof expression === 'function')\n\t{\n\t\texpression = !!expression(actual);\n\t}\n\n\treturn expression\n}\n\n/**\n * use asserts for make type predicates work\n *\n * @see https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates\n * @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions\n */\nexport function typePredicates<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string, ignoreExpression?: boolean): asserts actual is T\n{\n\texpression = _handleExpression(actual, expression);\n\n\tif (expression !== true && ignoreExpression !== true)\n\t{\n\t\tthrow new AssertionError({\n\t\t\tmessage: message ?? `actual ${actual} not as expected`,\n\t\t\tactual,\n\t\t\texpected: expression,\n\t\t\toperator: 'typePredicates',\n\t\t})\n\t}\n}\n\nexport function typeNarrowed<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string): actual is T\n{\n\texpression = _handleExpression(actual, expression);\n\n\tif (expression !== true)\n\t{\n\t\texpression = false;\n\t}\n\n\treturn expression\n}\n\nexport default typePredicates;\n"],"names":["expression","message","typeNarrowed","actual"],"mappings":";;;;;;;;;;;GAAA,IAAwC,OAAA,UAAA,KAAA,UAAA,EAAA;eAI7B,eAAU;CAInB,GAAA;;CAGD,EAAA,OAAAA,UAAA,CAAA;;CAWA,SAAA,cAAA,CAAA,MAAA,EAAA,UAAA,GAAA,IAAA,EAAA,OAAA,EAAA,gBAAA,EAAA;aAIC,oBAAU;;CACT,EAAA,IAAA,UAAA,KAAA,IAAA,IAAA,gBAAA,KAAA,IAAA,EAAA;;OAEAC;;;;;CAMG,GAAA;CAEL,CAAA;UAIWC,aAAAC,QAASH,UAAA,SAAAC,SAAA;CAGpBD,EAAAA,UAAA,oBAAiB,CAAjB,MAAA,EAAA,UAAA,CAAA,CAAA;;OAGDA,UAAA,KAAA,IAAA,EAAA;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.umd.development.cjs","sources":["../src/index.ts"],"sourcesContent":["/// <reference types=\"node\" />\nimport { AssertionError } from 'assert';\n\n/**\n * 處理表達式，回傳布林值結果\n * Handle expression and return boolean result\n *\n * @param actual - 實際值 / Actual value\n * @param expression - 表達式，可為布林值或函式 / Expression, can be boolean or function\n * @returns 布林值結果 / Boolean result\n */\nexport function _handleExpression<T, P = any>(actual: T | P, expression: boolean | ((actual: T | P) => any) = true)\n{\n\texpression ??= true;\n\n\tif (typeof expression === 'function')\n\t{\n\t\texpression = !!expression(actual);\n\t}\n\n\treturn expression\n}\n\n/**\n * 使用斷言（assert）讓類型斷言（type predicates）運作\n * Use asserts for make type predicates work\n *\n * 此函式結合了 TypeScript 的斷言函式與類型斷言功能，\n * 允許在運行時驗證類型並在編譯時縮小類型範圍\n *\n * @param T - 預期的類型 / Expected type\n * @param actual - 實際值 / Actual value\n * @param expression - 斷言條件，可為布林值或函式（可選）/ Assertion condition, can be boolean or function (optional)\n * @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)\n * @param ignoreExpression - 是否忽略表達式結果，設為 true 時只做類型收窄不拋出錯誤（可選）/ Whether to ignore expression result (optional)\n * @throws 當表達式結果為 false 時拋出 AssertionError / Throws AssertionError when expression is false\n *\n * @see https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates\n * @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions\n *\n * @example\n * // 基本用法：失敗時拋出錯誤\n * typePredicates<string>(value, typeof value === 'string');\n *\n * @example\n * // 參數除了第一個以外都能省略\n * typePredicates<string>(value);\n *\n * @example\n * // 使用於 if 條件中 - 強制類型收窄 (需要配合使用 @ts-ignore 註釋)\n * if (typePredicates<string>(data.value, data.type === 'a')) {\n *     // data.value 現在正確收窄為 string\n *     console.log(data.value.toUpperCase());\n * }\n *\n * @example\n * // 忽略表達式結果，只做類型收窄，不拋出錯誤\n * typePredicates<string>(value, typeof value === 'string', undefined, true);\n */\nexport function typePredicates<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string, ignoreExpression?: boolean): asserts actual is T\n{\n\texpression = _handleExpression(actual, expression);\n\n\tif (expression !== true && ignoreExpression !== true)\n\t{\n\t\tthrow new AssertionError({\n\t\t\tmessage: message ?? `actual ${actual} not as expected`,\n\t\t\tactual,\n\t\t\texpected: expression,\n\t\t\toperator: 'typePredicates',\n\t\t})\n\t}\n\n\t// @ts-ignore\n\treturn expression\n}\n\n/**\n * 類型收窄函式，回傳類型斷言結果\n * Type narrowing function, returns type predicate result\n *\n * 此函式不會拋出錯誤，而是回傳布林值表示是否符合預期類型\n * 可用於需要條件邏輯而非斷言的場景\n *\n * @param T - 預期的類型 / Expected type\n * @param actual - 實際值 / Actual value\n * @param expression - 驗證條件，可為布林值或函式（可選）/ Validation condition, can be boolean or function (optional)\n * @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)\n * @returns 是否符合預期類型 / Whether it matches the expected type\n *\n * @example\n * // 使用 typeNarrowed - 回傳布林值\n * if (typeNarrowed<string>(value, typeof value === 'string')) {\n *     console.log(value.length);\n * }\n */\nexport function typeNarrowed<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string): actual is T\n{\n\texpression = _handleExpression(actual, expression);\n\n\tif (expression !== true)\n\t{\n\t\texpression = false;\n\t}\n\n\treturn expression\n}\n\nexport default typePredicates;\n"],"names":["expression","actual","expected","operator"],"mappings":";;;;;;;;CAoEG;;CApEH;CACA;;;;;;;;CAUA,GAAA;UAEWA,UAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuDRC,MAAA;CAEAC,MAAAA,QAAC,EAAAF,UAAA;OAGUG,QAAA,EAAA,gBAAA;CAEb,KAAA,CAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/index.umd.production.min.cjs

@@ -1,2 +1,23 @@
-!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?t(exports,require("assert")):"function"==typeof define&&define.amd?define(["exports","assert"],t):t((e="undefined"!=typeof globalThis?globalThis:e||self).TsTypePredicates={},e.assert)}(this,(function(e,t){"use strict";function _handleExpression(e,t=!0){var n;return null!==(n=t)&&void 0!==n||(t=!0),"function"==typeof t&&(t=!!t(e)),t}function typePredicates(e,n=!0,r,s){if(!0!==(n=_handleExpression(e,n))&&!0!==s)throw new t.AssertionError({message:null!=r?r:`actual ${e} not as expected`,actual:e,expected:n,operator:"typePredicates"})}e._handleExpression=_handleExpression,e.default=typePredicates,e.typeNarrowed=function typeNarrowed(e,t=!0,n){return!0!==(t=_handleExpression(e,t))&&(t=!1),t},e.typePredicates=typePredicates,Object.defineProperty(e,"__esModule",{value:!0})}));
+!function(e, t) {
+  "object" == typeof exports && "undefined" != typeof module ? t(exports, require("assert")) : "function" == typeof define && define.amd ? define([ "exports", "assert" ], t) : t((e = "undefined" != typeof globalThis ? globalThis : e || self).TsTypePredicates = {}, e.assert);
+}(this, function(e, t) {
+  "use strict";
+  function _handleExpression(e, t = !0) {
+    return null != t || (t = !0), "function" == typeof t && (t = !!t(e)), t;
+  }
+  function typePredicates(e, n = !0, r, s) {
+    if (!0 !== (n = _handleExpression(e, n)) && !0 !== s) throw new t.AssertionError({
+      message: null != r ? r : `actual ${e} not as expected`,
+      actual: e,
+      expected: n,
+      operator: "typePredicates"
+    });
+    return n;
+  }
+  e._handleExpression = _handleExpression, e.default = typePredicates, e.typeNarrowed = function typeNarrowed(e, t = !0, n) {
+    return !0 !== (t = _handleExpression(e, t)) && (t = !1), t;
+  }, e.typePredicates = typePredicates, Object.defineProperty(e, "__esModule", {
+    value: !0
+  });
+});
 //# sourceMappingURL=index.umd.production.min.cjs.map

package/dist/index.umd.production.min.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.umd.production.min.cjs","sources":["../src/index.ts"],"sourcesContent":["import { AssertionError } from 'assert';\n\nexport function _handleExpression<T, P = any>(actual: T | P, expression: boolean | ((actual: T | P) => any) = true)\n{\n\texpression ??= true;\n\n\tif (typeof expression === 'function')\n\t{\n\t\texpression = !!expression(actual);\n\t}\n\n\treturn expression\n}\n\n/**\n * use asserts for make type predicates work\n *\n * @see https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates\n * @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions\n */\nexport function typePredicates<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string, ignoreExpression?: boolean): asserts actual is T\n{\n\texpression = _handleExpression(actual, expression);\n\n\tif (expression !== true && ignoreExpression !== true)\n\t{\n\t\tthrow new AssertionError({\n\t\t\tmessage: message ?? `actual ${actual} not as expected`,\n\t\t\tactual,\n\t\t\texpected: expression,\n\t\t\toperator: 'typePredicates',\n\t\t})\n\t}\n}\n\nexport function typeNarrowed<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string): actual is T\n{\n\texpression = _handleExpression(actual, expression);\n\n\tif (expression !== true)\n\t{\n\t\texpression = false;\n\t}\n\n\treturn expression\n}\n\nexport default typePredicates;\n"],"names":["expression","typePredicates","actual","message","ignoreExpression","typeNarrowed"],"mappings":"uUAWC,wCAXuC,mBAAAA,cAWvCA,EAWA,SAAAC,eAAAC,EAAAF,GAAA,EAAAG,EAAAC,GAKE,IAAA,iCAAA,IAAAA,8BAEAD,+FAQF,wFAIWE,aAAAH,EAASF,KAAAG,UAMrB,KAHCH,oBAAAE,EAAAF"}
+{"version":3,"file":"index.umd.production.min.cjs","sources":["../src/index.ts"],"sourcesContent":["/// <reference types=\"node\" />\nimport { AssertionError } from 'assert';\n\n/**\n * 處理表達式，回傳布林值結果\n * Handle expression and return boolean result\n *\n * @param actual - 實際值 / Actual value\n * @param expression - 表達式，可為布林值或函式 / Expression, can be boolean or function\n * @returns 布林值結果 / Boolean result\n */\nexport function _handleExpression<T, P = any>(actual: T | P, expression: boolean | ((actual: T | P) => any) = true)\n{\n\texpression ??= true;\n\n\tif (typeof expression === 'function')\n\t{\n\t\texpression = !!expression(actual);\n\t}\n\n\treturn expression\n}\n\n/**\n * 使用斷言（assert）讓類型斷言（type predicates）運作\n * Use asserts for make type predicates work\n *\n * 此函式結合了 TypeScript 的斷言函式與類型斷言功能，\n * 允許在運行時驗證類型並在編譯時縮小類型範圍\n *\n * @param T - 預期的類型 / Expected type\n * @param actual - 實際值 / Actual value\n * @param expression - 斷言條件，可為布林值或函式（可選）/ Assertion condition, can be boolean or function (optional)\n * @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)\n * @param ignoreExpression - 是否忽略表達式結果，設為 true 時只做類型收窄不拋出錯誤（可選）/ Whether to ignore expression result (optional)\n * @throws 當表達式結果為 false 時拋出 AssertionError / Throws AssertionError when expression is false\n *\n * @see https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates\n * @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions\n *\n * @example\n * // 基本用法：失敗時拋出錯誤\n * typePredicates<string>(value, typeof value === 'string');\n *\n * @example\n * // 參數除了第一個以外都能省略\n * typePredicates<string>(value);\n *\n * @example\n * // 使用於 if 條件中 - 強制類型收窄 (需要配合使用 @ts-ignore 註釋)\n * if (typePredicates<string>(data.value, data.type === 'a')) {\n *     // data.value 現在正確收窄為 string\n *     console.log(data.value.toUpperCase());\n * }\n *\n * @example\n * // 忽略表達式結果，只做類型收窄，不拋出錯誤\n * typePredicates<string>(value, typeof value === 'string', undefined, true);\n */\nexport function typePredicates<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string, ignoreExpression?: boolean): asserts actual is T\n{\n\texpression = _handleExpression(actual, expression);\n\n\tif (expression !== true && ignoreExpression !== true)\n\t{\n\t\tthrow new AssertionError({\n\t\t\tmessage: message ?? `actual ${actual} not as expected`,\n\t\t\tactual,\n\t\t\texpected: expression,\n\t\t\toperator: 'typePredicates',\n\t\t})\n\t}\n\n\t// @ts-ignore\n\treturn expression\n}\n\n/**\n * 類型收窄函式，回傳類型斷言結果\n * Type narrowing function, returns type predicate result\n *\n * 此函式不會拋出錯誤，而是回傳布林值表示是否符合預期類型\n * 可用於需要條件邏輯而非斷言的場景\n *\n * @param T - 預期的類型 / Expected type\n * @param actual - 實際值 / Actual value\n * @param expression - 驗證條件，可為布林值或函式（可選）/ Validation condition, can be boolean or function (optional)\n * @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)\n * @returns 是否符合預期類型 / Whether it matches the expected type\n *\n * @example\n * // 使用 typeNarrowed - 回傳布林值\n * if (typeNarrowed<string>(value, typeof value === 'string')) {\n *     console.log(value.length);\n * }\n */\nexport function typeNarrowed<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string): actual is T\n{\n\texpression = _handleExpression(actual, expression);\n\n\tif (expression !== true)\n\t{\n\t\texpression = false;\n\t}\n\n\treturn expression\n}\n\nexport default typePredicates;\n"],"names":["expression","actual","expected","operator"],"mappings":";;;;;0EAaWA;;;;;MAuDRC;MAEAC,UAACF;MAGUG,UAAA;;;;;;;;;"}

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "ts-type-predicates",
-  "version": "1.0.9",
-  "description": "use asserts for make type predicates work",
+  "version": "1.0.12",
+  "description": "使用斷言（assert）讓類型斷言（type predicates）運作的實用工具函式 | Use asserts to make type predicates work with better runtime validation",
   "keywords": [
     ".d.ts",
     "@types",
+    "assert",
+    "asserts",
+    "assertion-function",
     "declaration",
     "dev",
     "develop",
@@ -17,7 +20,10 @@
     "runtime",
     "ts",
     "type",
+    "type-assertion",
     "type-level",
+    "type-narrowing",
+    "type-predicates",
     "typelevel",
     "types",
     "typescript",
@@ -43,8 +49,8 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.esm.mjs",
-      "require": "./dist/index.cjs"
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.esm.mjs"
     },
     "./package.json": "./package.json"
   },
@@ -56,17 +62,22 @@
     "test": "test"
   },
   "scripts": {
+    "coverage": "yarn run test -- --coverage",
     "lint": "ynpx --quiet eslint -- **/*.ts",
-    "test": "echo \"Error: no test specified\"",
+    "test": "jest --passWithNoTests",
     "test:jest": "ynpx --quiet jest -- --coverage",
+    "test:jest:coverage": "node --run test:jest -- --coverage",
     "test:jest:snapshot": "yarn run test:jest -- -u",
     "test:mocha": "ynpx --quiet -p ts-node -p mocha mocha -- --require ts-node/register \"!(node_modules)/**/*.{test,spec}.{ts,tsx}\"",
     "test:snapshot": "yarn run test -- -u",
     "test:tsd": "ynpx tsd",
     "posttest": "yarn run build",
-    "build": "yarn run build:tsdx && yarn run build:dts",
+    "build": "yarn run build:tsdx && yarn run build:dts:tsc",
     "build:dts": "ynpx dts-bundle-generator -o ./dist/index.d.ts ./src/index.ts --no-banner & echo build:dts",
-    "build:tsdx": "ynpx @bluelovers/tsdx build --target node --name index",
+    "build:tsdx": "tsdx build --target node --name index",
+    "build:dts:copy": "copy .\\src\\index.d.ts .\\dist\\index.d.ts & echo build:dts",
+    "build:dts:tsc": "yarn run build:dts:tsc:emit && yarn run build:dts:copy",
+    "build:dts:tsc:emit": "tsc --emitDeclarationOnly --declaration --noEmit false",
     "preversion": "echo preversion && yarn run test",
     "version": "echo version",
     "postversion": "echo postversion",
@@ -82,6 +93,8 @@
     "sort-package-json": "ynpx --quiet yarn-tool -- sort",
     "tsc:showConfig": "ynpx get-current-tsconfig -p"
   },
-  "packageManager": "yarn@^1.22.11",
-  "gitHead": "fa34eea119b9bcbb363061ddffcfe9d78c2d0ddd"
+  "devDependencies": {
+    "@types/node": "^25.5.0"
+  },
+  "gitHead": "c87f657dc8050a9b9c3ed646262f6c497a867f05"
 }

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;;AAAA,mCAAwC;AAExC,SAAgB,iBAAiB,CAAa,MAAa,EAAE,aAAiD,IAAI;IAEjH,UAAU,aAAV,UAAU,cAAV,UAAU,IAAV,UAAU,GAAK,IAAI,EAAC;IAEpB,IAAI,OAAO,UAAU,KAAK,UAAU,EACpC;QACC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;KAClC;IAED,OAAO,UAAU,CAAA;AAClB,CAAC;AAVD,8CAUC;AAED;;;;;GAKG;AACH,SAAgB,cAAc,CAAa,MAAa,EAAE,aAAkD,IAAI,EAAE,OAAgB,EAAE,gBAA0B;IAE7J,UAAU,GAAG,iBAAiB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAEnD,IAAI,UAAU,KAAK,IAAI,IAAI,gBAAgB,KAAK,IAAI,EACpD;QACC,MAAM,IAAI,uBAAc,CAAC;YACxB,OAAO,EAAE,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,UAAU,MAAM,kBAAkB;YACtD,MAAM;YACN,QAAQ,EAAE,UAAU;YACpB,QAAQ,EAAE,gBAAgB;SAC1B,CAAC,CAAA;KACF;AACF,CAAC;AAbD,wCAaC;AAED,SAAgB,YAAY,CAAa,MAAa,EAAE,aAAkD,IAAI,EAAE,OAAgB;IAE/H,UAAU,GAAG,iBAAiB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAEnD,IAAI,UAAU,KAAK,IAAI,EACvB;QACC,UAAU,GAAG,KAAK,CAAC;KACnB;IAED,OAAO,UAAU,CAAA;AAClB,CAAC;AAVD,oCAUC;AAED,kBAAe,cAAc,CAAC","sourcesContent":["import { AssertionError } from 'assert';\n\nexport function _handleExpression<T, P = any>(actual: T | P, expression: boolean | ((actual: T | P) => any) = true)\n{\n\texpression ??= true;\n\n\tif (typeof expression === 'function')\n\t{\n\t\texpression = !!expression(actual);\n\t}\n\n\treturn expression\n}\n\n/**\n * use asserts for make type predicates work\n *\n * @see https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates\n * @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions\n */\nexport function typePredicates<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string, ignoreExpression?: boolean): asserts actual is T\n{\n\texpression = _handleExpression(actual, expression);\n\n\tif (expression !== true && ignoreExpression !== true)\n\t{\n\t\tthrow new AssertionError({\n\t\t\tmessage: message ?? `actual ${actual} not as expected`,\n\t\t\tactual,\n\t\t\texpected: expression,\n\t\t\toperator: 'typePredicates',\n\t\t})\n\t}\n}\n\nexport function typeNarrowed<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string): actual is T\n{\n\texpression = _handleExpression(actual, expression);\n\n\tif (expression !== true)\n\t{\n\t\texpression = false;\n\t}\n\n\treturn expression\n}\n\nexport default typePredicates;\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;AAWA,8CAUC;AAsCD,wCAgBC;AAqBD,oCAUC;AA1GD,8BAA8B;AAC9B,mCAAwC;AAExC;;;;;;;GAOG;AACH,SAAgB,iBAAiB,CAAa,MAAa,EAAE,aAAiD,IAAI;IAEjH,UAAU,aAAV,UAAU,cAAV,UAAU,IAAV,UAAU,GAAK,IAAI,EAAC;IAEpB,IAAI,OAAO,UAAU,KAAK,UAAU,EACpC,CAAC;QACA,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC;IAED,OAAO,UAAU,CAAA;AAClB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,SAAgB,cAAc,CAAa,MAAa,EAAE,aAAkD,IAAI,EAAE,OAAgB,EAAE,gBAA0B;IAE7J,UAAU,GAAG,iBAAiB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAEnD,IAAI,UAAU,KAAK,IAAI,IAAI,gBAAgB,KAAK,IAAI,EACpD,CAAC;QACA,MAAM,IAAI,uBAAc,CAAC;YACxB,OAAO,EAAE,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,UAAU,MAAM,kBAAkB;YACtD,MAAM;YACN,QAAQ,EAAE,UAAU;YACpB,QAAQ,EAAE,gBAAgB;SAC1B,CAAC,CAAA;IACH,CAAC;IAED,aAAa;IACb,OAAO,UAAU,CAAA;AAClB,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,YAAY,CAAa,MAAa,EAAE,aAAkD,IAAI,EAAE,OAAgB;IAE/H,UAAU,GAAG,iBAAiB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAEnD,IAAI,UAAU,KAAK,IAAI,EACvB,CAAC;QACA,UAAU,GAAG,KAAK,CAAC;IACpB,CAAC;IAED,OAAO,UAAU,CAAA;AAClB,CAAC;AAED,kBAAe,cAAc,CAAC","sourcesContent":["/// <reference types=\"node\" />\nimport { AssertionError } from 'assert';\n\n/**\n * 處理表達式，回傳布林值結果\n * Handle expression and return boolean result\n *\n * @param actual - 實際值 / Actual value\n * @param expression - 表達式，可為布林值或函式 / Expression, can be boolean or function\n * @returns 布林值結果 / Boolean result\n */\nexport function _handleExpression<T, P = any>(actual: T | P, expression: boolean | ((actual: T | P) => any) = true)\n{\n\texpression ??= true;\n\n\tif (typeof expression === 'function')\n\t{\n\t\texpression = !!expression(actual);\n\t}\n\n\treturn expression\n}\n\n/**\n * 使用斷言（assert）讓類型斷言（type predicates）運作\n * Use asserts for make type predicates work\n *\n * 此函式結合了 TypeScript 的斷言函式與類型斷言功能，\n * 允許在運行時驗證類型並在編譯時縮小類型範圍\n *\n * @param T - 預期的類型 / Expected type\n * @param actual - 實際值 / Actual value\n * @param expression - 斷言條件，可為布林值或函式（可選）/ Assertion condition, can be boolean or function (optional)\n * @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)\n * @param ignoreExpression - 是否忽略表達式結果，設為 true 時只做類型收窄不拋出錯誤（可選）/ Whether to ignore expression result (optional)\n * @throws 當表達式結果為 false 時拋出 AssertionError / Throws AssertionError when expression is false\n *\n * @see https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates\n * @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions\n *\n * @example\n * // 基本用法：失敗時拋出錯誤\n * typePredicates<string>(value, typeof value === 'string');\n *\n * @example\n * // 參數除了第一個以外都能省略\n * typePredicates<string>(value);\n *\n * @example\n * // 使用於 if 條件中 - 強制類型收窄 (需要配合使用 @ts-ignore 註釋)\n * if (typePredicates<string>(data.value, data.type === 'a')) {\n *     // data.value 現在正確收窄為 string\n *     console.log(data.value.toUpperCase());\n * }\n *\n * @example\n * // 忽略表達式結果，只做類型收窄，不拋出錯誤\n * typePredicates<string>(value, typeof value === 'string', undefined, true);\n */\nexport function typePredicates<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string, ignoreExpression?: boolean): asserts actual is T\n{\n\texpression = _handleExpression(actual, expression);\n\n\tif (expression !== true && ignoreExpression !== true)\n\t{\n\t\tthrow new AssertionError({\n\t\t\tmessage: message ?? `actual ${actual} not as expected`,\n\t\t\tactual,\n\t\t\texpected: expression,\n\t\t\toperator: 'typePredicates',\n\t\t})\n\t}\n\n\t// @ts-ignore\n\treturn expression\n}\n\n/**\n * 類型收窄函式，回傳類型斷言結果\n * Type narrowing function, returns type predicate result\n *\n * 此函式不會拋出錯誤，而是回傳布林值表示是否符合預期類型\n * 可用於需要條件邏輯而非斷言的場景\n *\n * @param T - 預期的類型 / Expected type\n * @param actual - 實際值 / Actual value\n * @param expression - 驗證條件，可為布林值或函式（可選）/ Validation condition, can be boolean or function (optional)\n * @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)\n * @returns 是否符合預期類型 / Whether it matches the expected type\n *\n * @example\n * // 使用 typeNarrowed - 回傳布林值\n * if (typeNarrowed<string>(value, typeof value === 'string')) {\n *     console.log(value.length);\n * }\n */\nexport function typeNarrowed<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string): actual is T\n{\n\texpression = _handleExpression(actual, expression);\n\n\tif (expression !== true)\n\t{\n\t\texpression = false;\n\t}\n\n\treturn expression\n}\n\nexport default typePredicates;\n"]}

package/src/index.ts

@@ -1,5 +1,14 @@
+/// <reference types="node" />
 import { AssertionError } from 'assert';
 
+/**
+ * 處理表達式，回傳布林值結果
+ * Handle expression and return boolean result
+ *
+ * @param actual - 實際值 / Actual value
+ * @param expression - 表達式，可為布林值或函式 / Expression, can be boolean or function
+ * @returns 布林值結果 / Boolean result
+ */
 export function _handleExpression<T, P = any>(actual: T | P, expression: boolean | ((actual: T | P) => any) = true)
 {
 	expression ??= true;
@@ -13,10 +22,40 @@ export function _handleExpression<T, P = any>(actual: T | P, expression: boolean
 }
 
 /**
- * use asserts for make type predicates work
+ * 使用斷言（assert）讓類型斷言（type predicates）運作
+ * Use asserts for make type predicates work
+ *
+ * 此函式結合了 TypeScript 的斷言函式與類型斷言功能，
+ * 允許在運行時驗證類型並在編譯時縮小類型範圍
+ *
+ * @param T - 預期的類型 / Expected type
+ * @param actual - 實際值 / Actual value
+ * @param expression - 斷言條件，可為布林值或函式（可選）/ Assertion condition, can be boolean or function (optional)
+ * @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)
+ * @param ignoreExpression - 是否忽略表達式結果，設為 true 時只做類型收窄不拋出錯誤（可選）/ Whether to ignore expression result (optional)
+ * @throws 當表達式結果為 false 時拋出 AssertionError / Throws AssertionError when expression is false
  *
  * @see https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates
  * @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions
+ *
+ * @example
+ * // 基本用法：失敗時拋出錯誤
+ * typePredicates<string>(value, typeof value === 'string');
+ *
+ * @example
+ * // 參數除了第一個以外都能省略
+ * typePredicates<string>(value);
+ *
+ * @example
+ * // 使用於 if 條件中 - 強制類型收窄 (需要配合使用 @ts-ignore 註釋)
+ * if (typePredicates<string>(data.value, data.type === 'a')) {
+ *     // data.value 現在正確收窄為 string
+ *     console.log(data.value.toUpperCase());
+ * }
+ *
+ * @example
+ * // 忽略表達式結果，只做類型收窄，不拋出錯誤
+ * typePredicates<string>(value, typeof value === 'string', undefined, true);
  */
 export function typePredicates<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string, ignoreExpression?: boolean): asserts actual is T
 {
@@ -31,8 +70,30 @@ export function typePredicates<T, P = any>(actual: T | P, expression : boolean |
 			operator: 'typePredicates',
 		})
 	}
+
+	// @ts-ignore
+	return expression
 }
 
+/**
+ * 類型收窄函式，回傳類型斷言結果
+ * Type narrowing function, returns type predicate result
+ *
+ * 此函式不會拋出錯誤，而是回傳布林值表示是否符合預期類型
+ * 可用於需要條件邏輯而非斷言的場景
+ *
+ * @param T - 預期的類型 / Expected type
+ * @param actual - 實際值 / Actual value
+ * @param expression - 驗證條件，可為布林值或函式（可選）/ Validation condition, can be boolean or function (optional)
+ * @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)
+ * @returns 是否符合預期類型 / Whether it matches the expected type
+ *
+ * @example
+ * // 使用 typeNarrowed - 回傳布林值
+ * if (typeNarrowed<string>(value, typeof value === 'string')) {
+ *     console.log(value.length);
+ * }
+ */
 export function typeNarrowed<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string): actual is T
 {
 	expression = _handleExpression(actual, expression);