ts-type-predicates 1.0.10 → 1.0.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +25 -0
- package/README.md +84 -3
- package/dist/index.cjs.development.cjs +37 -6
- package/dist/index.cjs.development.cjs.map +1 -1
- package/dist/index.cjs.production.min.cjs +10 -9
- package/dist/index.cjs.production.min.cjs.map +1 -1
- package/dist/index.d.ts +35 -12
- package/dist/index.esm.mjs +1 -0
- package/dist/index.esm.mjs.map +1 -1
- package/dist/index.umd.development.cjs +37 -6
- package/dist/index.umd.development.cjs.map +1 -1
- package/dist/index.umd.production.min.cjs +4 -3
- package/dist/index.umd.production.min.cjs.map +1 -1
- package/package.json +15 -3
- package/src/index.js.map +1 -1
- package/src/index.ts +38 -6
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,31 @@
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
|
|
5
5
|
|
|
6
|
+
## [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)
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
### ✨ Features
|
|
11
|
+
|
|
12
|
+
* **is-array:** 新增唯讀陣列類型斷言支援及完善文檔說明 ([4f0d97d](https://github.com/bluelovers/ws-ts-type/commit/4f0d97d86c93c5a82a66712695fa69cd5a78344a))
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
### 📚 Documentation
|
|
16
|
+
|
|
17
|
+
* **ts-type-predicates:** 新增 typePredicates 強化 Narrowing 用法說明 ([a0eeb18](https://github.com/bluelovers/ws-ts-type/commit/a0eeb188a5d67f3983d8986955bcab70eaf52497))
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
### 🛠 Build System
|
|
21
|
+
|
|
22
|
+
* 優化類型定義輸出流程並移除 snapshot 更新標誌 ([5b9aeca](https://github.com/bluelovers/ws-ts-type/commit/5b9aeca2434e581f818d8872ffde43236f203e57))
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
### 🔖 Miscellaneous
|
|
26
|
+
|
|
27
|
+
* . ([43bb6af](https://github.com/bluelovers/ws-ts-type/commit/43bb6afdf390a090c87bdb872e5b6f9fd9932669))
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
|
|
6
31
|
## [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)
|
|
7
32
|
|
|
8
33
|
|
package/README.md
CHANGED
|
@@ -4,6 +4,8 @@
|
|
|
4
4
|
|
|
5
5
|
Use asserts to make type predicates work with better runtime validation
|
|
6
6
|
|
|
7
|
+
---
|
|
8
|
+
|
|
7
9
|
## 功能特點 / Features
|
|
8
10
|
|
|
9
11
|
- 結合 TypeScript 斷言函式與類型斷言功能
|
|
@@ -12,6 +14,12 @@ Use asserts to make type predicates work with better runtime validation
|
|
|
12
14
|
- Support runtime validation and compile-time type narrowing
|
|
13
15
|
- 可自訂錯誤訊息
|
|
14
16
|
- Customizable error messages
|
|
17
|
+
- 可選擇只做類型收窄不拋出錯誤
|
|
18
|
+
- Optional type narrowing without throwing errors
|
|
19
|
+
- 可用於強化替代 Narrowing
|
|
20
|
+
- Can be used to enhance or replace Narrowing
|
|
21
|
+
|
|
22
|
+
---
|
|
15
23
|
|
|
16
24
|
## 安裝 / Install
|
|
17
25
|
|
|
@@ -21,19 +29,23 @@ yarn-tool add ts-type-predicates
|
|
|
21
29
|
yt add ts-type-predicates
|
|
22
30
|
```
|
|
23
31
|
|
|
24
|
-
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## 使用範例 / Usage Examples
|
|
35
|
+
|
|
36
|
+
### 基本用法
|
|
25
37
|
|
|
26
38
|
```typescript
|
|
27
39
|
import { typePredicates, typeNarrowed } from 'ts-type-predicates';
|
|
28
40
|
|
|
29
|
-
// 使用斷言函式
|
|
41
|
+
// 使用斷言函式 - 失敗時拋出錯誤
|
|
30
42
|
function processValue(value: string | number) {
|
|
31
43
|
typePredicates<string>(value, typeof value === 'string');
|
|
32
44
|
// 現在 TypeScript 知道 value 是 string
|
|
33
45
|
console.log(value.toUpperCase());
|
|
34
46
|
}
|
|
35
47
|
|
|
36
|
-
// 使用類型收窄
|
|
48
|
+
// 使用類型收窄 - 回傳布林值
|
|
37
49
|
function checkValue(value: unknown) {
|
|
38
50
|
if (typeNarrowed<string>(value, typeof value === 'string')) {
|
|
39
51
|
console.log(value.length);
|
|
@@ -41,3 +53,72 @@ function checkValue(value: unknown) {
|
|
|
41
53
|
}
|
|
42
54
|
```
|
|
43
55
|
|
|
56
|
+
### 參數省略
|
|
57
|
+
|
|
58
|
+
參數除了第一個以外都能省略：
|
|
59
|
+
|
|
60
|
+
```typescript
|
|
61
|
+
import { typePredicates } from 'ts-type-predicates';
|
|
62
|
+
|
|
63
|
+
// 只有第一個參數是必需的
|
|
64
|
+
typePredicates<string>(value);
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### 強化替代 Narrowing
|
|
68
|
+
|
|
69
|
+
當標準的 Narrowing 無法正確收窄類型時，可以使用 `typePredicates` 強制收窄：
|
|
70
|
+
|
|
71
|
+
```typescript
|
|
72
|
+
import { typePredicates } from 'ts-type-predicates';
|
|
73
|
+
|
|
74
|
+
// Narrowing 無法處理的情況
|
|
75
|
+
type Mixed = { type: 'a'; value: string } | { type: 'b'; value: number };
|
|
76
|
+
|
|
77
|
+
function process(data: Mixed) {
|
|
78
|
+
// ❌ Narrowing 無法正確收窄 value 的類型
|
|
79
|
+
if (data.type === 'a') {
|
|
80
|
+
// data.value 仍然是 string | number
|
|
81
|
+
console.log(data.value.toUpperCase()); // 錯誤
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
// ✅ 使用 typePredicates 強制收窄 - 更精簡的寫法 (需要配合使用 @ts-ignore 註釋)
|
|
85
|
+
if (typePredicates<string>(data.value, data.type === 'a')) {
|
|
86
|
+
// data.value 現在正確收窄為 string
|
|
87
|
+
console.log(data.value.toUpperCase()); // 正確
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### 忽略表達式結果
|
|
93
|
+
|
|
94
|
+
當只需要類型收窄，不需要運行時驗證時：
|
|
95
|
+
|
|
96
|
+
```typescript
|
|
97
|
+
import { typePredicates } from 'ts-type-predicates';
|
|
98
|
+
|
|
99
|
+
// 只做類型收窄，不拋出錯誤
|
|
100
|
+
function narrowValue(value: unknown) {
|
|
101
|
+
typePredicates<string>(value, typeof value === 'string', undefined, true);
|
|
102
|
+
// value 現在被收窄為 string（但運行時不驗證）
|
|
103
|
+
console.log(value.toUpperCase());
|
|
104
|
+
}
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## 與標準 Narrowing 的比較
|
|
110
|
+
|
|
111
|
+
| 特性 | Narrowing（內建） | typePredicates |
|
|
112
|
+
|------|-------------------|----------------|
|
|
113
|
+
| 語法 | `if (typeof x === "string")` | `typePredicates<string>(x)` |
|
|
114
|
+
| 彈性 | 有限 | 可自訂任意邏輯 |
|
|
115
|
+
| 錯誤處理 | 無 | 可拋出自訂錯誤 |
|
|
116
|
+
| 強制收窄 | 無法 | 可以 |
|
|
117
|
+
| 複雜類型 | 需多重檢查 | 可一次完成 |
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## 相關資源
|
|
122
|
+
|
|
123
|
+
- [TypeScript 官方文件 - Type Predicates](https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates)
|
|
124
|
+
- [TypeScript 官方文件 - Assertion Functions](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions)
|
|
@@ -4,12 +4,13 @@ Object.defineProperty(exports, '__esModule', { value: true });
|
|
|
4
4
|
|
|
5
5
|
var assert = require('assert');
|
|
6
6
|
|
|
7
|
+
/// <reference types="node" />
|
|
7
8
|
/**
|
|
8
|
-
*
|
|
9
|
+
* 處理表達式，回傳布林值結果
|
|
9
10
|
* Handle expression and return boolean result
|
|
10
11
|
*
|
|
11
12
|
* @param actual - 實際值 / Actual value
|
|
12
|
-
* @param expression -
|
|
13
|
+
* @param expression - 表達式，可為布林值或函式 / Expression, can be boolean or function
|
|
13
14
|
* @returns 布林值結果 / Boolean result
|
|
14
15
|
*/
|
|
15
16
|
function _handleExpression(actual, expression = true) {
|
|
@@ -26,13 +27,34 @@ function _handleExpression(actual, expression = true) {
|
|
|
26
27
|
* 此函式結合了 TypeScript 的斷言函式與類型斷言功能，
|
|
27
28
|
* 允許在運行時驗證類型並在編譯時縮小類型範圍
|
|
28
29
|
*
|
|
30
|
+
* @param T - 預期的類型 / Expected type
|
|
29
31
|
* @param actual - 實際值 / Actual value
|
|
30
|
-
* @param expression -
|
|
32
|
+
* @param expression - 斷言條件，可為布林值或函式（可選）/ Assertion condition, can be boolean or function (optional)
|
|
31
33
|
* @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)
|
|
32
|
-
* @param ignoreExpression -
|
|
33
|
-
* @throws
|
|
34
|
+
* @param ignoreExpression - 是否忽略表達式結果，設為 true 時只做類型收窄不拋出錯誤（可選）/ Whether to ignore expression result (optional)
|
|
35
|
+
* @throws 當表達式結果為 false 時拋出 AssertionError / Throws AssertionError when expression is false
|
|
36
|
+
*
|
|
34
37
|
* @see https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates
|
|
35
38
|
* @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions
|
|
39
|
+
*
|
|
40
|
+
* @example
|
|
41
|
+
* // 基本用法：失敗時拋出錯誤
|
|
42
|
+
* typePredicates<string>(value, typeof value === 'string');
|
|
43
|
+
*
|
|
44
|
+
* @example
|
|
45
|
+
* // 參數除了第一個以外都能省略
|
|
46
|
+
* typePredicates<string>(value);
|
|
47
|
+
*
|
|
48
|
+
* @example
|
|
49
|
+
* // 使用於 if 條件中 - 強制類型收窄 (需要配合使用 @ts-ignore 註釋)
|
|
50
|
+
* if (typePredicates<string>(data.value, data.type === 'a')) {
|
|
51
|
+
* // data.value 現在正確收窄為 string
|
|
52
|
+
* console.log(data.value.toUpperCase());
|
|
53
|
+
* }
|
|
54
|
+
*
|
|
55
|
+
* @example
|
|
56
|
+
* // 忽略表達式結果，只做類型收窄，不拋出錯誤
|
|
57
|
+
* typePredicates<string>(value, typeof value === 'string', undefined, true);
|
|
36
58
|
*/
|
|
37
59
|
function typePredicates(actual, expression = true, message, ignoreExpression) {
|
|
38
60
|
expression = _handleExpression(actual, expression);
|
|
@@ -44,6 +66,8 @@ function typePredicates(actual, expression = true, message, ignoreExpression) {
|
|
|
44
66
|
operator: 'typePredicates'
|
|
45
67
|
});
|
|
46
68
|
}
|
|
69
|
+
// @ts-ignore
|
|
70
|
+
return expression;
|
|
47
71
|
}
|
|
48
72
|
/**
|
|
49
73
|
* 類型收窄函式，回傳類型斷言結果
|
|
@@ -52,10 +76,17 @@ function typePredicates(actual, expression = true, message, ignoreExpression) {
|
|
|
52
76
|
* 此函式不會拋出錯誤，而是回傳布林值表示是否符合預期類型
|
|
53
77
|
* 可用於需要條件邏輯而非斷言的場景
|
|
54
78
|
*
|
|
79
|
+
* @param T - 預期的類型 / Expected type
|
|
55
80
|
* @param actual - 實際值 / Actual value
|
|
56
|
-
* @param expression -
|
|
81
|
+
* @param expression - 驗證條件，可為布林值或函式（可選）/ Validation condition, can be boolean or function (optional)
|
|
57
82
|
* @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)
|
|
58
83
|
* @returns 是否符合預期類型 / Whether it matches the expected type
|
|
84
|
+
*
|
|
85
|
+
* @example
|
|
86
|
+
* // 使用 typeNarrowed - 回傳布林值
|
|
87
|
+
* if (typeNarrowed<string>(value, typeof value === 'string')) {
|
|
88
|
+
* console.log(value.length);
|
|
89
|
+
* }
|
|
59
90
|
*/
|
|
60
91
|
function typeNarrowed(actual, expression = true, message) {
|
|
61
92
|
expression = _handleExpression(actual, expression);
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.cjs.development.cjs","sources":["../src/index.ts"],"sourcesContent":["
|
|
1
|
+
{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
|
|
@@ -6,21 +6,22 @@ Object.defineProperty(exports, "__esModule", {
|
|
|
6
6
|
|
|
7
7
|
var e = require("assert");
|
|
8
8
|
|
|
9
|
-
function _handleExpression(e,
|
|
10
|
-
return null !=
|
|
9
|
+
function _handleExpression(e, r = !0) {
|
|
10
|
+
return null != r || (r = !0), "function" == typeof r && (r = !!r(e)), r;
|
|
11
11
|
}
|
|
12
12
|
|
|
13
|
-
function typePredicates(
|
|
14
|
-
if (!0 !== (
|
|
15
|
-
message: null != s ? s : `actual ${
|
|
16
|
-
actual:
|
|
17
|
-
expected:
|
|
13
|
+
function typePredicates(r, t = !0, s, n) {
|
|
14
|
+
if (!0 !== (t = _handleExpression(r, t)) && !0 !== n) throw new e.AssertionError({
|
|
15
|
+
message: null != s ? s : `actual ${r} not as expected`,
|
|
16
|
+
actual: r,
|
|
17
|
+
expected: t,
|
|
18
18
|
operator: "typePredicates"
|
|
19
19
|
});
|
|
20
|
+
return t;
|
|
20
21
|
}
|
|
21
22
|
|
|
22
23
|
exports._handleExpression = _handleExpression, exports.default = typePredicates,
|
|
23
|
-
exports.typeNarrowed = function typeNarrowed(e,
|
|
24
|
-
return !0 !== (
|
|
24
|
+
exports.typeNarrowed = function typeNarrowed(e, r = !0, t) {
|
|
25
|
+
return !0 !== (r = _handleExpression(e, r)) && (r = !1), r;
|
|
25
26
|
}, exports.typePredicates = typePredicates;
|
|
26
27
|
//# sourceMappingURL=index.cjs.production.min.cjs.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.cjs.production.min.cjs","sources":["../src/index.ts"],"sourcesContent":["
|
|
1
|
+
{"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
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
2
|
+
* 處理表達式，回傳布林值結果
|
|
3
3
|
* Handle expression and return boolean result
|
|
4
4
|
*
|
|
5
5
|
* @param actual - 實際值 / Actual value
|
|
6
|
-
* @param expression -
|
|
6
|
+
* @param expression - 表達式，可為布林值或函式 / Expression, can be boolean or function
|
|
7
7
|
* @returns 布林值結果 / Boolean result
|
|
8
8
|
*/
|
|
9
9
|
export declare function _handleExpression<T, P = any>(actual: T | P, expression?: boolean | ((actual: T | P) => any)): boolean;
|
|
@@ -14,13 +14,34 @@ export declare function _handleExpression<T, P = any>(actual: T | P, expression?
|
|
|
14
14
|
* 此函式結合了 TypeScript 的斷言函式與類型斷言功能，
|
|
15
15
|
* 允許在運行時驗證類型並在編譯時縮小類型範圍
|
|
16
16
|
*
|
|
17
|
+
* @param T - 預期的類型 / Expected type
|
|
17
18
|
* @param actual - 實際值 / Actual value
|
|
18
|
-
* @param expression -
|
|
19
|
+
* @param expression - 斷言條件，可為布林值或函式（可選）/ Assertion condition, can be boolean or function (optional)
|
|
19
20
|
* @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)
|
|
20
|
-
* @param ignoreExpression -
|
|
21
|
-
* @throws
|
|
21
|
+
* @param ignoreExpression - 是否忽略表達式結果，設為 true 時只做類型收窄不拋出錯誤（可選）/ Whether to ignore expression result (optional)
|
|
22
|
+
* @throws 當表達式結果為 false 時拋出 AssertionError / Throws AssertionError when expression is false
|
|
23
|
+
*
|
|
22
24
|
* @see https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates
|
|
23
25
|
* @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions
|
|
26
|
+
*
|
|
27
|
+
* @example
|
|
28
|
+
* // 基本用法：失敗時拋出錯誤
|
|
29
|
+
* typePredicates<string>(value, typeof value === 'string');
|
|
30
|
+
*
|
|
31
|
+
* @example
|
|
32
|
+
* // 參數除了第一個以外都能省略
|
|
33
|
+
* typePredicates<string>(value);
|
|
34
|
+
*
|
|
35
|
+
* @example
|
|
36
|
+
* // 使用於 if 條件中 - 強制類型收窄 (需要配合使用 @ts-ignore 註釋)
|
|
37
|
+
* if (typePredicates<string>(data.value, data.type === 'a')) {
|
|
38
|
+
* // data.value 現在正確收窄為 string
|
|
39
|
+
* console.log(data.value.toUpperCase());
|
|
40
|
+
* }
|
|
41
|
+
*
|
|
42
|
+
* @example
|
|
43
|
+
* // 忽略表達式結果，只做類型收窄，不拋出錯誤
|
|
44
|
+
* typePredicates<string>(value, typeof value === 'string', undefined, true);
|
|
24
45
|
*/
|
|
25
46
|
export declare function typePredicates<T, P = any>(actual: T | P, expression?: boolean | ((actual: T | P) => any), message?: string, ignoreExpression?: boolean): asserts actual is T;
|
|
26
47
|
/**
|
|
@@ -30,15 +51,17 @@ export declare function typePredicates<T, P = any>(actual: T | P, expression?: b
|
|
|
30
51
|
* 此函式不會拋出錯誤，而是回傳布林值表示是否符合預期類型
|
|
31
52
|
* 可用於需要條件邏輯而非斷言的場景
|
|
32
53
|
*
|
|
54
|
+
* @param T - 預期的類型 / Expected type
|
|
33
55
|
* @param actual - 實際值 / Actual value
|
|
34
|
-
* @param expression -
|
|
56
|
+
* @param expression - 驗證條件，可為布林值或函式（可選）/ Validation condition, can be boolean or function (optional)
|
|
35
57
|
* @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)
|
|
36
58
|
* @returns 是否符合預期類型 / Whether it matches the expected type
|
|
59
|
+
*
|
|
60
|
+
* @example
|
|
61
|
+
* // 使用 typeNarrowed - 回傳布林值
|
|
62
|
+
* if (typeNarrowed<string>(value, typeof value === 'string')) {
|
|
63
|
+
* console.log(value.length);
|
|
64
|
+
* }
|
|
37
65
|
*/
|
|
38
66
|
export declare function typeNarrowed<T, P = any>(actual: T | P, expression?: boolean | ((actual: T | P) => any), message?: string): actual is T;
|
|
39
|
-
|
|
40
|
-
export {
|
|
41
|
-
typePredicates as default,
|
|
42
|
-
};
|
|
43
|
-
|
|
44
|
-
export {};
|
|
67
|
+
export default typePredicates;
|
package/dist/index.esm.mjs
CHANGED
package/dist/index.esm.mjs.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.esm.mjs","sources":["../src/index.ts"],"sourcesContent":["
|
|
1
|
+
{"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;;;;;;;;;"}
|
|
@@ -4,12 +4,13 @@
|
|
|
4
4
|
(global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.TsTypePredicates = {}, global.assert));
|
|
5
5
|
})(this, (function (exports, assert) { 'use strict';
|
|
6
6
|
|
|
7
|
+
/// <reference types="node" />
|
|
7
8
|
/**
|
|
8
|
-
*
|
|
9
|
+
* 處理表達式，回傳布林值結果
|
|
9
10
|
* Handle expression and return boolean result
|
|
10
11
|
*
|
|
11
12
|
* @param actual - 實際值 / Actual value
|
|
12
|
-
* @param expression -
|
|
13
|
+
* @param expression - 表達式，可為布林值或函式 / Expression, can be boolean or function
|
|
13
14
|
* @returns 布林值結果 / Boolean result
|
|
14
15
|
*/
|
|
15
16
|
function _handleExpression(actual, expression = true) {
|
|
@@ -26,13 +27,34 @@
|
|
|
26
27
|
* 此函式結合了 TypeScript 的斷言函式與類型斷言功能，
|
|
27
28
|
* 允許在運行時驗證類型並在編譯時縮小類型範圍
|
|
28
29
|
*
|
|
30
|
+
* @param T - 預期的類型 / Expected type
|
|
29
31
|
* @param actual - 實際值 / Actual value
|
|
30
|
-
* @param expression -
|
|
32
|
+
* @param expression - 斷言條件，可為布林值或函式（可選）/ Assertion condition, can be boolean or function (optional)
|
|
31
33
|
* @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)
|
|
32
|
-
* @param ignoreExpression -
|
|
33
|
-
* @throws
|
|
34
|
+
* @param ignoreExpression - 是否忽略表達式結果，設為 true 時只做類型收窄不拋出錯誤（可選）/ Whether to ignore expression result (optional)
|
|
35
|
+
* @throws 當表達式結果為 false 時拋出 AssertionError / Throws AssertionError when expression is false
|
|
36
|
+
*
|
|
34
37
|
* @see https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates
|
|
35
38
|
* @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions
|
|
39
|
+
*
|
|
40
|
+
* @example
|
|
41
|
+
* // 基本用法：失敗時拋出錯誤
|
|
42
|
+
* typePredicates<string>(value, typeof value === 'string');
|
|
43
|
+
*
|
|
44
|
+
* @example
|
|
45
|
+
* // 參數除了第一個以外都能省略
|
|
46
|
+
* typePredicates<string>(value);
|
|
47
|
+
*
|
|
48
|
+
* @example
|
|
49
|
+
* // 使用於 if 條件中 - 強制類型收窄 (需要配合使用 @ts-ignore 註釋)
|
|
50
|
+
* if (typePredicates<string>(data.value, data.type === 'a')) {
|
|
51
|
+
* // data.value 現在正確收窄為 string
|
|
52
|
+
* console.log(data.value.toUpperCase());
|
|
53
|
+
* }
|
|
54
|
+
*
|
|
55
|
+
* @example
|
|
56
|
+
* // 忽略表達式結果，只做類型收窄，不拋出錯誤
|
|
57
|
+
* typePredicates<string>(value, typeof value === 'string', undefined, true);
|
|
36
58
|
*/
|
|
37
59
|
function typePredicates(actual, expression = true, message, ignoreExpression) {
|
|
38
60
|
expression = _handleExpression(actual, expression);
|
|
@@ -44,6 +66,8 @@
|
|
|
44
66
|
operator: 'typePredicates'
|
|
45
67
|
});
|
|
46
68
|
}
|
|
69
|
+
// @ts-ignore
|
|
70
|
+
return expression;
|
|
47
71
|
}
|
|
48
72
|
/**
|
|
49
73
|
* 類型收窄函式，回傳類型斷言結果
|
|
@@ -52,10 +76,17 @@
|
|
|
52
76
|
* 此函式不會拋出錯誤，而是回傳布林值表示是否符合預期類型
|
|
53
77
|
* 可用於需要條件邏輯而非斷言的場景
|
|
54
78
|
*
|
|
79
|
+
* @param T - 預期的類型 / Expected type
|
|
55
80
|
* @param actual - 實際值 / Actual value
|
|
56
|
-
* @param expression -
|
|
81
|
+
* @param expression - 驗證條件，可為布林值或函式（可選）/ Validation condition, can be boolean or function (optional)
|
|
57
82
|
* @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)
|
|
58
83
|
* @returns 是否符合預期類型 / Whether it matches the expected type
|
|
84
|
+
*
|
|
85
|
+
* @example
|
|
86
|
+
* // 使用 typeNarrowed - 回傳布林值
|
|
87
|
+
* if (typeNarrowed<string>(value, typeof value === 'string')) {
|
|
88
|
+
* console.log(value.length);
|
|
89
|
+
* }
|
|
59
90
|
*/
|
|
60
91
|
function typeNarrowed(actual, expression = true, message) {
|
|
61
92
|
expression = _handleExpression(actual, expression);
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.umd.development.cjs","sources":["../src/index.ts"],"sourcesContent":["
|
|
1
|
+
{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
|
|
@@ -5,13 +5,14 @@
|
|
|
5
5
|
function _handleExpression(e, t = !0) {
|
|
6
6
|
return null != t || (t = !0), "function" == typeof t && (t = !!t(e)), t;
|
|
7
7
|
}
|
|
8
|
-
function typePredicates(e, n = !0,
|
|
9
|
-
if (!0 !== (n = _handleExpression(e, n)) && !0 !==
|
|
10
|
-
message: null !=
|
|
8
|
+
function typePredicates(e, n = !0, r, s) {
|
|
9
|
+
if (!0 !== (n = _handleExpression(e, n)) && !0 !== s) throw new t.AssertionError({
|
|
10
|
+
message: null != r ? r : `actual ${e} not as expected`,
|
|
11
11
|
actual: e,
|
|
12
12
|
expected: n,
|
|
13
13
|
operator: "typePredicates"
|
|
14
14
|
});
|
|
15
|
+
return n;
|
|
15
16
|
}
|
|
16
17
|
e._handleExpression = _handleExpression, e.default = typePredicates, e.typeNarrowed = function typeNarrowed(e, t = !0, n) {
|
|
17
18
|
return !0 !== (t = _handleExpression(e, t)) && (t = !1), t;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.umd.production.min.cjs","sources":["../src/index.ts"],"sourcesContent":["
|
|
1
|
+
{"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
CHANGED
|
@@ -1,10 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ts-type-predicates",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.12",
|
|
4
4
|
"description": "使用斷言（assert）讓類型斷言（type predicates）運作的實用工具函式 | Use asserts to make type predicates work with better runtime validation",
|
|
5
5
|
"keywords": [
|
|
6
6
|
".d.ts",
|
|
7
7
|
"@types",
|
|
8
|
+
"assert",
|
|
9
|
+
"asserts",
|
|
10
|
+
"assertion-function",
|
|
8
11
|
"declaration",
|
|
9
12
|
"dev",
|
|
10
13
|
"develop",
|
|
@@ -17,7 +20,10 @@
|
|
|
17
20
|
"runtime",
|
|
18
21
|
"ts",
|
|
19
22
|
"type",
|
|
23
|
+
"type-assertion",
|
|
20
24
|
"type-level",
|
|
25
|
+
"type-narrowing",
|
|
26
|
+
"type-predicates",
|
|
21
27
|
"typelevel",
|
|
22
28
|
"types",
|
|
23
29
|
"typescript",
|
|
@@ -66,9 +72,12 @@
|
|
|
66
72
|
"test:snapshot": "yarn run test -- -u",
|
|
67
73
|
"test:tsd": "ynpx tsd",
|
|
68
74
|
"posttest": "yarn run build",
|
|
69
|
-
"build": "yarn run build:tsdx && yarn run build:dts",
|
|
75
|
+
"build": "yarn run build:tsdx && yarn run build:dts:tsc",
|
|
70
76
|
"build:dts": "ynpx dts-bundle-generator -o ./dist/index.d.ts ./src/index.ts --no-banner & echo build:dts",
|
|
71
77
|
"build:tsdx": "tsdx build --target node --name index",
|
|
78
|
+
"build:dts:copy": "copy .\\src\\index.d.ts .\\dist\\index.d.ts & echo build:dts",
|
|
79
|
+
"build:dts:tsc": "yarn run build:dts:tsc:emit && yarn run build:dts:copy",
|
|
80
|
+
"build:dts:tsc:emit": "tsc --emitDeclarationOnly --declaration --noEmit false",
|
|
72
81
|
"preversion": "echo preversion && yarn run test",
|
|
73
82
|
"version": "echo version",
|
|
74
83
|
"postversion": "echo postversion",
|
|
@@ -84,5 +93,8 @@
|
|
|
84
93
|
"sort-package-json": "ynpx --quiet yarn-tool -- sort",
|
|
85
94
|
"tsc:showConfig": "ynpx get-current-tsconfig -p"
|
|
86
95
|
},
|
|
87
|
-
"
|
|
96
|
+
"devDependencies": {
|
|
97
|
+
"@types/node": "^25.5.0"
|
|
98
|
+
},
|
|
99
|
+
"gitHead": "c87f657dc8050a9b9c3ed646262f6c497a867f05"
|
|
88
100
|
}
|
package/src/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;
|
|
1
|
+
{"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
CHANGED
|
@@ -1,11 +1,12 @@
|
|
|
1
|
+
/// <reference types="node" />
|
|
1
2
|
import { AssertionError } from 'assert';
|
|
2
3
|
|
|
3
4
|
/**
|
|
4
|
-
*
|
|
5
|
+
* 處理表達式，回傳布林值結果
|
|
5
6
|
* Handle expression and return boolean result
|
|
6
7
|
*
|
|
7
8
|
* @param actual - 實際值 / Actual value
|
|
8
|
-
* @param expression -
|
|
9
|
+
* @param expression - 表達式，可為布林值或函式 / Expression, can be boolean or function
|
|
9
10
|
* @returns 布林值結果 / Boolean result
|
|
10
11
|
*/
|
|
11
12
|
export function _handleExpression<T, P = any>(actual: T | P, expression: boolean | ((actual: T | P) => any) = true)
|
|
@@ -27,13 +28,34 @@ export function _handleExpression<T, P = any>(actual: T | P, expression: boolean
|
|
|
27
28
|
* 此函式結合了 TypeScript 的斷言函式與類型斷言功能，
|
|
28
29
|
* 允許在運行時驗證類型並在編譯時縮小類型範圍
|
|
29
30
|
*
|
|
31
|
+
* @param T - 預期的類型 / Expected type
|
|
30
32
|
* @param actual - 實際值 / Actual value
|
|
31
|
-
* @param expression -
|
|
33
|
+
* @param expression - 斷言條件，可為布林值或函式（可選）/ Assertion condition, can be boolean or function (optional)
|
|
32
34
|
* @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)
|
|
33
|
-
* @param ignoreExpression -
|
|
34
|
-
* @throws
|
|
35
|
+
* @param ignoreExpression - 是否忽略表達式結果，設為 true 時只做類型收窄不拋出錯誤（可選）/ Whether to ignore expression result (optional)
|
|
36
|
+
* @throws 當表達式結果為 false 時拋出 AssertionError / Throws AssertionError when expression is false
|
|
37
|
+
*
|
|
35
38
|
* @see https://www.typescriptlang.org/docs/handbook/advanced-types.html#using-type-predicates
|
|
36
39
|
* @see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions
|
|
40
|
+
*
|
|
41
|
+
* @example
|
|
42
|
+
* // 基本用法：失敗時拋出錯誤
|
|
43
|
+
* typePredicates<string>(value, typeof value === 'string');
|
|
44
|
+
*
|
|
45
|
+
* @example
|
|
46
|
+
* // 參數除了第一個以外都能省略
|
|
47
|
+
* typePredicates<string>(value);
|
|
48
|
+
*
|
|
49
|
+
* @example
|
|
50
|
+
* // 使用於 if 條件中 - 強制類型收窄 (需要配合使用 @ts-ignore 註釋)
|
|
51
|
+
* if (typePredicates<string>(data.value, data.type === 'a')) {
|
|
52
|
+
* // data.value 現在正確收窄為 string
|
|
53
|
+
* console.log(data.value.toUpperCase());
|
|
54
|
+
* }
|
|
55
|
+
*
|
|
56
|
+
* @example
|
|
57
|
+
* // 忽略表達式結果，只做類型收窄，不拋出錯誤
|
|
58
|
+
* typePredicates<string>(value, typeof value === 'string', undefined, true);
|
|
37
59
|
*/
|
|
38
60
|
export function typePredicates<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string, ignoreExpression?: boolean): asserts actual is T
|
|
39
61
|
{
|
|
@@ -48,6 +70,9 @@ export function typePredicates<T, P = any>(actual: T | P, expression : boolean |
|
|
|
48
70
|
operator: 'typePredicates',
|
|
49
71
|
})
|
|
50
72
|
}
|
|
73
|
+
|
|
74
|
+
// @ts-ignore
|
|
75
|
+
return expression
|
|
51
76
|
}
|
|
52
77
|
|
|
53
78
|
/**
|
|
@@ -57,10 +82,17 @@ export function typePredicates<T, P = any>(actual: T | P, expression : boolean |
|
|
|
57
82
|
* 此函式不會拋出錯誤，而是回傳布林值表示是否符合預期類型
|
|
58
83
|
* 可用於需要條件邏輯而非斷言的場景
|
|
59
84
|
*
|
|
85
|
+
* @param T - 預期的類型 / Expected type
|
|
60
86
|
* @param actual - 實際值 / Actual value
|
|
61
|
-
* @param expression -
|
|
87
|
+
* @param expression - 驗證條件，可為布林值或函式（可選）/ Validation condition, can be boolean or function (optional)
|
|
62
88
|
* @param message - 自訂錯誤訊息（可選）/ Custom error message (optional)
|
|
63
89
|
* @returns 是否符合預期類型 / Whether it matches the expected type
|
|
90
|
+
*
|
|
91
|
+
* @example
|
|
92
|
+
* // 使用 typeNarrowed - 回傳布林值
|
|
93
|
+
* if (typeNarrowed<string>(value, typeof value === 'string')) {
|
|
94
|
+
* console.log(value.length);
|
|
95
|
+
* }
|
|
64
96
|
*/
|
|
65
97
|
export function typeNarrowed<T, P = any>(actual: T | P, expression : boolean | ((actual: T | P) => any) = true, message?: string): actual is T
|
|
66
98
|
{
|