ts-type 3.0.15 → 3.0.16

package/CHANGELOG.md

@@ -3,6 +3,31 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [3.0.16](https://github.com/bluelovers/ws-ts-type/compare/ts-type@3.0.15...ts-type@3.0.16) (2026-09-27)
+
+
+
+### ✨　Features
+
+* **ts-type:** 新增字串字面量組合工具類型 ([f57467d](https://github.com/bluelovers/ws-ts-type/commit/f57467de62ed6b3404388e8a620d0e2c73a4aeb2))
+
+
+### 📚　Documentation
+
+* **ts-type:** 重構聯集轉可選/必填類型的實作方式 ([27cbfb6](https://github.com/bluelovers/ws-ts-type/commit/27cbfb6886a85fc7be426189212828a6fc8baeb3))
+
+
+### 🛠　Build System
+
+* **release:** publish ([988ac2f](https://github.com/bluelovers/ws-ts-type/commit/988ac2f81a6a0d2ad797c9874c2fd25e7987749b))
+
+
+### ♻️　Chores
+
+* **package:** 更新發布後的 Git 提交訊息內容 ([2f37128](https://github.com/bluelovers/ws-ts-type/commit/2f3712864caea40047a04f72391ba92948b86ac1))
+
+
+
 ## [3.0.15](https://github.com/bluelovers/ws-ts-type/compare/ts-type@3.0.14...ts-type@3.0.15) (2026-09-25)
 
 

package/lib/helper/string/string-composition.d.ts

@@ -0,0 +1,115 @@
+import { ITSTemplateLiteralAllowedType, ITSToStringLiteral } from "../string";
+/**
+ * 將字串字面量加上前綴，組合成新的字串字面量
+ * Combines a prefix with a name into a new string literal.
+ *
+ * 當 Name 為聯集時，結果會對應展開為聯集
+ * When Name is a union, the result expands to a union accordingly.
+ *
+ * @example
+ * type A = ITSStringLiteralPrefixed<"Up", "STR">;
+ * // type A = "UpSTR"
+ *
+ * @example
+ * type B = ITSStringLiteralPrefixed<"Up", "STR" | "INT">;
+ * // type B = "UpSTR" | "UpINT"
+ */
+export type ITSStringLiteralPrefixed<Prefix extends ITSTemplateLiteralAllowedType, Name extends ITSTemplateLiteralAllowedType> = `${Prefix}${Name}`;
+/**
+ * 將字串字面量加上後綴，組合成新的字串字面量
+ * Combines a name with a suffix into a new string literal.
+ *
+ * 當 Name 為聯集時，結果會對應展開為聯集
+ * When Name is a union, the result expands to a union accordingly.
+ *
+ * @example
+ * type A = ITSStringLiteralSuffixed<"STR", "Status">;
+ * // type A = "STRStatus"
+ *
+ * @example
+ * type B = ITSStringLiteralSuffixed<"STR" | "INT", "Status">;
+ * // type B = "STRStatus" | "INTStatus"
+ */
+export type ITSStringLiteralSuffixed<Name extends ITSTemplateLiteralAllowedType, Suffix extends ITSTemplateLiteralAllowedType> = `${Name}${Suffix}`;
+/**
+ * 以 Name 聯集的每個成員為鍵，建立其值為「前綴 + 鍵名」的對應記錄型別
+ * Builds a record whose keys are the members of the Name union and
+ * whose values are the prefixed string literal of each key.
+ *
+ * @example
+ * type T = ITSStringLiteralPrefixedRecord<"Up", "STR" | "INT" | "DEX">;
+ * // type T = {
+ * //   STR: "UpSTR";
+ * //   INT: "UpINT";
+ * //   DEX: "UpDEX";
+ * // }
+ */
+export type ITSStringLiteralPrefixedRecord<Prefix extends ITSTemplateLiteralAllowedType, Name extends ITSTemplateLiteralAllowedType> = {
+    [K in ITSToStringLiteral<Name>]: ITSStringLiteralPrefixed<Prefix, K>;
+};
+/**
+ * 以 Name 聯集的每個成員為鍵，建立其值為「鍵名 + 後綴」的對應記錄型別
+ * Builds a record whose keys are the members of the Name union and
+ * whose values are the suffixed string literal of each key.
+ *
+ * @example
+ * type T = ITSStringLiteralSuffixedRecord<"STR" | "INT", "Status">;
+ * // type T = {
+ * //   STR: "STRStatus";
+ * //   INT: "INTStatus";
+ * // }
+ */
+export type ITSStringLiteralSuffixedRecord<Name extends ITSTemplateLiteralAllowedType, Suffix extends ITSTemplateLiteralAllowedType> = {
+    [K in ITSToStringLiteral<Name>]: ITSStringLiteralSuffixed<K, Suffix>;
+};
+/**
+ * 以 Name 聯集為基礎，透過 KeyMap 重新映射鍵名、並以 ValueMap 指定
+ * 對應的值型別，建立一組自訂的對應記錄型別
+ * Builds a custom mapped record from the Name union, remapping each
+ * key via KeyMap and assigning the value type from ValueMap.
+ *
+ * @example
+ * type Name = "STR" | "INT" | "DEX";
+ * type KeyMap = { STR: "str"; INT: "int"; DEX: "dex" };
+ * type ValueMap = { STR: number; INT: number; DEX: number };
+ *
+ * type T = ITSRecordMap<Name, KeyMap, ValueMap>;
+ * // type T = {
+ * //   str: number;
+ * //   int: number;
+ * //   dex: number;
+ * // }
+ *
+ * @example
+ * 當 ValueMap 的值型別為 string 時:
+ * type Name = "STR" | "INT" | "DEX";
+ * type KeyMap = { STR: "str"; INT: "int"; DEX: "dex" };
+ * type ValueMap = { STR: string; INT: string; DEX: string };
+ *
+ * type T = ITSRecordMap<Name, KeyMap, ValueMap>;
+ * // type T = {
+ * //   str: string;
+ * //   int: string;
+ * //   dex: string;
+ * // }
+ *
+ * @example
+ * 當 ValueMap 的值型別為物件型別時:
+ * type Name = "STR" | "INT" | "DEX";
+ * type KeyMap = { STR: "str"; INT: "int"; DEX: "dex" };
+ * type ValueMap = {
+ *   STR: { label: string; value: number };
+ *   INT: { label: string; value: number };
+ *   DEX: { label: string; value: number };
+ * };
+ *
+ * type T = ITSRecordMap<Name, KeyMap, ValueMap>;
+ * // type T = {
+ * //   str: { label: string; value: number };
+ * //   int: { label: string; value: number };
+ * //   dex: { label: string; value: number };
+ * // }
+ */
+export type ITSRecordMap<Name extends ITSTemplateLiteralAllowedType, KeyMap extends Record<ITSToStringLiteral<Name>, PropertyKey>, ValueMap extends Record<ITSToStringLiteral<Name>, unknown>> = {
+    [K in ITSToStringLiteral<Name> as KeyMap[K]]: ValueMap[K];
+};

package/lib/helper/string/string-composition.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=string-composition.js.map

package/lib/helper/string/string-composition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"string-composition.js","sourceRoot":"","sources":["string-composition.ts"],"names":[],"mappings":"","sourcesContent":["/*\n * 字串字面量組合工具\n * String Literal Composition Utilities\n *\n * 以 EnumStatusAttr（枚舉狀態屬性）為例的組合流程 / composition flow:\n *\n * EnumStatusAttr\n *       │\n *       ├──────────────┐\n *       │              │\n *       ▼              ▼\n *  Name Union      PrefixedRecord\n *       │              │\n *       │              └── STR → UpSTR\n *       │                  INT → UpINT\n *       │                  DEX → UpDEX\n *       │\n *       ▼\n * PrefixedUnion\n *       │\n *       └── 'UpSTR' | 'UpINT' | 'UpDEX' | ...\n */\nimport { ITSTemplateLiteralAllowedType, ITSToStringLiteral } from \"../string\";\n\n/**\n * 將字串字面量加上前綴，組合成新的字串字面量\n * Combines a prefix with a name into a new string literal.\n *\n * 當 Name 為聯集時，結果會對應展開為聯集\n * When Name is a union, the result expands to a union accordingly.\n *\n * @example\n * type A = ITSStringLiteralPrefixed<\"Up\", \"STR\">;\n * // type A = \"UpSTR\"\n *\n * @example\n * type B = ITSStringLiteralPrefixed<\"Up\", \"STR\" | \"INT\">;\n * // type B = \"UpSTR\" | \"UpINT\"\n */\nexport type ITSStringLiteralPrefixed<\n\tPrefix extends ITSTemplateLiteralAllowedType,\n\tName extends ITSTemplateLiteralAllowedType,\n> = `${Prefix}${Name}`;\n\n/**\n * 將字串字面量加上後綴，組合成新的字串字面量\n * Combines a name with a suffix into a new string literal.\n *\n * 當 Name 為聯集時，結果會對應展開為聯集\n * When Name is a union, the result expands to a union accordingly.\n *\n * @example\n * type A = ITSStringLiteralSuffixed<\"STR\", \"Status\">;\n * // type A = \"STRStatus\"\n *\n * @example\n * type B = ITSStringLiteralSuffixed<\"STR\" | \"INT\", \"Status\">;\n * // type B = \"STRStatus\" | \"INTStatus\"\n */\nexport type ITSStringLiteralSuffixed<\n\tName extends ITSTemplateLiteralAllowedType,\n\tSuffix extends ITSTemplateLiteralAllowedType,\n> = `${Name}${Suffix}`;\n\n/**\n * 以 Name 聯集的每個成員為鍵，建立其值為「前綴 + 鍵名」的對應記錄型別\n * Builds a record whose keys are the members of the Name union and\n * whose values are the prefixed string literal of each key.\n *\n * @example\n * type T = ITSStringLiteralPrefixedRecord<\"Up\", \"STR\" | \"INT\" | \"DEX\">;\n * // type T = {\n * //   STR: \"UpSTR\";\n * //   INT: \"UpINT\";\n * //   DEX: \"UpDEX\";\n * // }\n */\nexport type ITSStringLiteralPrefixedRecord<\n\tPrefix extends ITSTemplateLiteralAllowedType,\n\tName extends ITSTemplateLiteralAllowedType,\n> = {\n\t[K in ITSToStringLiteral<Name>]:\n\t\tITSStringLiteralPrefixed<Prefix, K>;\n};\n\n/**\n * 以 Name 聯集的每個成員為鍵，建立其值為「鍵名 + 後綴」的對應記錄型別\n * Builds a record whose keys are the members of the Name union and\n * whose values are the suffixed string literal of each key.\n *\n * @example\n * type T = ITSStringLiteralSuffixedRecord<\"STR\" | \"INT\", \"Status\">;\n * // type T = {\n * //   STR: \"STRStatus\";\n * //   INT: \"INTStatus\";\n * // }\n */\nexport type ITSStringLiteralSuffixedRecord<\n\tName extends ITSTemplateLiteralAllowedType,\n\tSuffix extends ITSTemplateLiteralAllowedType,\n> = {\n\t[K in ITSToStringLiteral<Name>]:\n\t\tITSStringLiteralSuffixed<K, Suffix>;\n};\n\n/**\n * 以 Name 聯集為基礎，透過 KeyMap 重新映射鍵名、並以 ValueMap 指定\n * 對應的值型別，建立一組自訂的對應記錄型別\n * Builds a custom mapped record from the Name union, remapping each\n * key via KeyMap and assigning the value type from ValueMap.\n *\n * @example\n * type Name = \"STR\" | \"INT\" | \"DEX\";\n * type KeyMap = { STR: \"str\"; INT: \"int\"; DEX: \"dex\" };\n * type ValueMap = { STR: number; INT: number; DEX: number };\n *\n * type T = ITSRecordMap<Name, KeyMap, ValueMap>;\n * // type T = {\n * //   str: number;\n * //   int: number;\n * //   dex: number;\n * // }\n *\n * @example\n * 當 ValueMap 的值型別為 string 時:\n * type Name = \"STR\" | \"INT\" | \"DEX\";\n * type KeyMap = { STR: \"str\"; INT: \"int\"; DEX: \"dex\" };\n * type ValueMap = { STR: string; INT: string; DEX: string };\n *\n * type T = ITSRecordMap<Name, KeyMap, ValueMap>;\n * // type T = {\n * //   str: string;\n * //   int: string;\n * //   dex: string;\n * // }\n *\n * @example\n * 當 ValueMap 的值型別為物件型別時:\n * type Name = \"STR\" | \"INT\" | \"DEX\";\n * type KeyMap = { STR: \"str\"; INT: \"int\"; DEX: \"dex\" };\n * type ValueMap = {\n *   STR: { label: string; value: number };\n *   INT: { label: string; value: number };\n *   DEX: { label: string; value: number };\n * };\n *\n * type T = ITSRecordMap<Name, KeyMap, ValueMap>;\n * // type T = {\n * //   str: { label: string; value: number };\n * //   int: { label: string; value: number };\n * //   dex: { label: string; value: number };\n * // }\n */\nexport type ITSRecordMap<\n\tName extends ITSTemplateLiteralAllowedType,\n\tKeyMap extends Record<ITSToStringLiteral<Name>, PropertyKey>,\n\tValueMap extends Record<ITSToStringLiteral<Name>, unknown>,\n> = {\n\t[K in ITSToStringLiteral<Name> as KeyMap[K]]:\n\t\tValueMap[K];\n};\n"]}

package/lib/helper/string.d.ts

@@ -6,7 +6,12 @@
  * Provides utilities for converting strings, numbers, booleans to literal types
  */
 /** 允許轉換為字面量類型的基礎類型 / Base types allowed to convert to literal types */
-export type ITSToStringLiteralAllowedType = string | number | boolean | bigint;
+export type ITSTemplateLiteralAllowedType = string | number | boolean | bigint;
+/**
+ * @alias {@link ITSTemplateLiteralAllowedType}
+ * @deprecated Use {@link ITSTemplateLiteralAllowedType} instead
+ */
+export type ITSToStringLiteralAllowedType = ITSTemplateLiteralAllowedType;
 /**
  * 將類型轉換為字面量類型 `${T}`
  * Convert type to literal type `${T}`

package/lib/helper/string.js.map

@@ -1 +1 @@
-{"version":3,"file":"string.js","sourceRoot":"","sources":["string.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG","sourcesContent":["/**\n * 字面量類型工具\n * Literal Type Utilities\n *\n * 提供字串、數字、布林值轉換為字面量類型的工具\n * Provides utilities for converting strings, numbers, booleans to literal types\n */\n\n/** 允許轉換為字面量類型的基礎類型 / Base types allowed to convert to literal types */\nexport type ITSToStringLiteralAllowedType = string | number | boolean | bigint;\n\n/**\n * 將類型轉換為字面量類型 `${T}`\n * Convert type to literal type `${T}`\n *\n * @example\n * type Str = ITSToStringLiteral<'hello'>;\n * // type Str = \"hello\"\n *\n * @example\n * type Num = ITSToStringLiteral<42>;\n * // type Num = \"42\"\n */\nexport type ITSToStringLiteral<T extends ITSToStringLiteralAllowedType> = `${T}`\n\n/**\n * 原始類型與其字面量類型的聯合\n * Union of original type and its literal type\n *\n * T & `${T}`\n *\n * 適合用在 enum 或 string literal union，可以接受 enum 的字面量或基底類型\n * Suitable for enum or string literal union, can accept enum literal or base type\n *\n * @example\n * // 應用於 string literal union\n * type Status = 'active' | 'inactive' | 'pending';\n * type IStatus = ITSTypeAndStringLiteral<Status>;\n * // type IStatus = \"active\" | \"inactive\" | \"pending\" | string\n *\n * @example\n * // 應用於 enum\n * enum EnumPackageManager {\n *   'yarn' = 'yarn',\n *   'npm' = 'npm',\n *   'pnpm' = 'pnpm',\n * }\n * type IPackageManager = ITSTypeAndStringLiteral<EnumPackageManager>;\n * // type IPackageManager = EnumPackageManager | string\n *\n * @example\n * // 應用於 number，可接受數字或數字字串\n * type INumber = ITSTypeAndStringLiteral<number>;\n * // type INumber = number | `${number}`\n */\nexport type ITSTypeAndStringLiteral<T extends ITSToStringLiteralAllowedType> = T | ITSToStringLiteral<T>\n\n/**\n * 原始類型 S 與 T 的字面量類型的聯合\n * Union of original type S and literal type of T\n *\n * S & `${T}`\n *\n * @example\n * type Result = ITSAndStringLiteral<1 | 2 | 3, number>;\n * // type Result = number | \"1\" | \"2\" | \"3\"\n */\nexport type ITSAndStringLiteral<T extends ITSToStringLiteralAllowedType, S = string> = S | ITSToStringLiteral<T>\n\n/**\n * 原始類型 S、T 與 T 的字面量類型的聯合\n * Union of original types S, T and literal type of T\n *\n * S & T & `${T}`\n *\n * @example\n * type Result = ITSAndTypeAndStringLiteral<1 | 2 | 3, number>;\n * // type Result = number | \"1\" | \"2\" | \"3\"\n */\nexport type ITSAndTypeAndStringLiteral<T extends ITSToStringLiteralAllowedType, S = string> =\n\tS\n\t| ITSTypeAndStringLiteral<T>\n"]}
+{"version":3,"file":"string.js","sourceRoot":"","sources":["string.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG","sourcesContent":["/**\n * 字面量類型工具\n * Literal Type Utilities\n *\n * 提供字串、數字、布林值轉換為字面量類型的工具\n * Provides utilities for converting strings, numbers, booleans to literal types\n */\n\n/** 允許轉換為字面量類型的基礎類型 / Base types allowed to convert to literal types */\nexport type ITSTemplateLiteralAllowedType = string | number | boolean | bigint;\n\n/**\n * @alias {@link ITSTemplateLiteralAllowedType}\n * @deprecated Use {@link ITSTemplateLiteralAllowedType} instead\n */\nexport type ITSToStringLiteralAllowedType = ITSTemplateLiteralAllowedType;\n\n/**\n * 將類型轉換為字面量類型 `${T}`\n * Convert type to literal type `${T}`\n *\n * @example\n * type Str = ITSToStringLiteral<'hello'>;\n * // type Str = \"hello\"\n *\n * @example\n * type Num = ITSToStringLiteral<42>;\n * // type Num = \"42\"\n */\nexport type ITSToStringLiteral<T extends ITSToStringLiteralAllowedType> = `${T}`\n\n/**\n * 原始類型與其字面量類型的聯合\n * Union of original type and its literal type\n *\n * T & `${T}`\n *\n * 適合用在 enum 或 string literal union，可以接受 enum 的字面量或基底類型\n * Suitable for enum or string literal union, can accept enum literal or base type\n *\n * @example\n * // 應用於 string literal union\n * type Status = 'active' | 'inactive' | 'pending';\n * type IStatus = ITSTypeAndStringLiteral<Status>;\n * // type IStatus = \"active\" | \"inactive\" | \"pending\" | string\n *\n * @example\n * // 應用於 enum\n * enum EnumPackageManager {\n *   'yarn' = 'yarn',\n *   'npm' = 'npm',\n *   'pnpm' = 'pnpm',\n * }\n * type IPackageManager = ITSTypeAndStringLiteral<EnumPackageManager>;\n * // type IPackageManager = EnumPackageManager | string\n *\n * @example\n * // 應用於 number，可接受數字或數字字串\n * type INumber = ITSTypeAndStringLiteral<number>;\n * // type INumber = number | `${number}`\n */\nexport type ITSTypeAndStringLiteral<T extends ITSToStringLiteralAllowedType> = T | ITSToStringLiteral<T>\n\n/**\n * 原始類型 S 與 T 的字面量類型的聯合\n * Union of original type S and literal type of T\n *\n * S & `${T}`\n *\n * @example\n * type Result = ITSAndStringLiteral<1 | 2 | 3, number>;\n * // type Result = number | \"1\" | \"2\" | \"3\"\n */\nexport type ITSAndStringLiteral<T extends ITSToStringLiteralAllowedType, S = string> = S | ITSToStringLiteral<T>\n\n/**\n * 原始類型 S、T 與 T 的字面量類型的聯合\n * Union of original types S, T and literal type of T\n *\n * S & T & `${T}`\n *\n * @example\n * type Result = ITSAndTypeAndStringLiteral<1 | 2 | 3, number>;\n * // type Result = number | \"1\" | \"2\" | \"3\"\n */\nexport type ITSAndTypeAndStringLiteral<T extends ITSToStringLiteralAllowedType, S = string> =\n\tS\n\t| ITSTypeAndStringLiteral<T>\n"]}

package/lib/index.d.ts

@@ -22,6 +22,7 @@ export * from './helper/string';
 export * from './helper/string/infer';
 export * from './helper/string/literal-string';
 export * from './helper/string/operations';
+export * from './helper/string/string-composition';
 export * from './helper/tuple';
 export * from './helper/typeof';
 export * from './internal/filter';

package/lib/type/record/union.d.ts

@@ -1,10 +1,14 @@
 import { ITSKeyOfUnion, ITSValueOfUnion } from "../../helper/key-value";
 import { ITSPartialPick, ITSRequiredPick } from "../record";
 /**
+ * 在保留每個聯集成員結構的前提下，將選取的屬性設為可選
  * Makes the selected properties optional while preserving
  * the structure of each union member.
  *
- * This is the distributive Union version.
+ * 這是分配式 (distributive) 的 Union 版本，會對聯集的每個成員
+ * 分別套用 `Partial<Pick<T, K>>`
+ * This is the distributive Union version: it applies
+ * `Partial<Pick<T, K>>` to each union member individually.
  *
  * @example
  * type T =
@@ -24,10 +28,14 @@ export type ITSPartialPickUnion<T, K extends ITSKeyOfUnion<T> = ITSKeyOfUnion<T>
     [P in K & keyof T]?: T[P];
 } : never;
 /**
+ * 在保留每個聯集成員結構的前提下，將選取的屬性設為必填
  * Makes the selected properties required while preserving
  * the structure of each union member.
  *
- * This is the distributive Union version.
+ * 這是分配式 (distributive) 的 Union 版本，會對聯集的每個成員
+ * 分別套用 `Required<Pick<T, K>>`
+ * This is the distributive Union version: it applies
+ * `Required<Pick<T, K>>` to each union member individually.
  *
  * @example
  * type T =
@@ -47,11 +55,15 @@ export type ITSRequiredPickUnion<T, K extends ITSKeyOfUnion<T> = ITSKeyOfUnion<T
     [P in K & keyof T]-?: T[P];
 } : never;
 /**
+ * 將選取的屬性設為可選，並把聯集中所有成員的屬性扁平化為單一物件型別
  * Makes the selected properties optional and flattens
  * all properties from every union member into a single object type.
  *
+ * 與 ITSPartialPickUnion 不同，此工具不保留各聯集成員的個別結構，
+ * 而是將所有鍵合併到同一個物件中
  * Unlike ITSPartialPickUnion, this does not preserve the
- * individual union-member structure.
+ * individual union-member structure; instead it merges all keys
+ * into a single object.
  *
  * @example
  * type T =
@@ -69,71 +81,240 @@ export type ITSPartialPickUnionFlat<T, K extends ITSKeyOfUnion<T> = ITSKeyOfUnio
     [P in K]?: ITSValueOfUnion<T, P>;
 };
 /**
+ * 將選取的屬性設為必填，並把聯集中所有成員扁平化為單一物件型別
  * Makes the selected properties required and flattens
  * all members of a union into a single object type.
  *
+ * 注意：此工具會刻意將所有選取的屬性設為必填。若需要更自然地保留
+ * 「屬性是否於每個成員中都存在」的語意，請改用 ITSUnionFlat 等
+ * 以扁平化為基礎的工具。
  * Note: this utility intentionally makes every selected property
  * required. For a natural flattened representation that preserves
  * whether a property exists in every member, use a dedicated
- * flat-base utility.
+ * flat-base utility such as ITSUnionFlat.
+ *
+ * @example
+ * type T =
+ *   | { type: "a"; value: number }
+ *   | { type: "b"; text: string };
+ *
+ * type Result = ITSRequiredPickUnionFlat<T>;
+ * // {
+ * //   type: "a" | "b";
+ * //   value: number;
+ * //   text: string;
+ * // }
  */
 export type ITSRequiredPickUnionFlat<T, K extends ITSKeyOfUnion<T> = ITSKeyOfUnion<T>> = {
     [P in K]-?: ITSValueOfUnion<T, P>;
 };
 /**
+ * 在保留聯集成員結構的前提下，將指定屬性設為必填
  * Makes the specified properties required for each member
  * of a union while preserving the union-member structure.
  *
+ * 其餘屬性保持不變（未被選取的屬性原樣保留）
  * Other properties are preserved unchanged.
+ *
+ * @example
+ * type T =
+ *   | { type: "a"; value?: number }
+ *   | { type: "b"; text?: string };
+ *
+ * type Result = ITSRequiredWithUnion<T, "value" | "text">;
+ * // {
+ * //   type: "a";
+ * //   value: number;
+ * // } | {
+ * //   type: "b";
+ * //   text: string;
+ * // }
  */
 export type ITSRequiredWithUnion<T, K extends ITSKeyOfUnion<T>> = T extends any ? K extends keyof T ? Omit<T, K> & ITSRequiredPick<T, K> : T : never;
 /**
+ * 在保留聯集成員結構的前提下，將指定屬性設為可選
  * Makes the specified properties optional for each member
  * of a union while preserving the union-member structure.
  *
+ * 其餘屬性保持不變（未被選取的屬性原樣保留）
  * Other properties are preserved unchanged.
+ *
+ * @example
+ * type T =
+ *   | { type: "a"; value: number }
+ *   | { type: "b"; text: string };
+ *
+ * type Result = ITSPartialWithUnion<T, "value" | "text">;
+ * // {
+ * //   type: "a";
+ * //   value?: number;
+ * // } | {
+ * //   type: "b";
+ * //   text?: string;
+ * // }
  */
 export type ITSPartialWithUnion<T, K extends ITSKeyOfUnion<T>> = T extends any ? K extends keyof T ? Omit<T, K> & ITSPartialPick<T, K> : T : never;
+/**
+ * 將聯集扁平化為單一物件型別，並依各屬性在聯集中的存在情況
+ * 決定其為必填或可選
+ * Flattens a union into a single object type, marking each
+ * property as required or optional based on whether it exists
+ * in every union member.
+ *
+ * 在每個成員都必填的鍵會被設為必填；否則設為可選
+ * Keys required in every member become required; the rest optional.
+ *
+ * @example
+ * type T =
+ *   | { type: "a"; value: number }
+ *   | { type: "b"; value?: string };
+ *
+ * type Result = ITSUnionFlat<T>;
+ * // {
+ * //   type: "a" | "b";
+ * //   value?: number | string;
+ * // }
+ */
 export type ITSUnionFlat<T> = {
     [P in ITSKeyOfUnionRequired<T>]-?: ITSValueOfUnion<T, P>;
 } & {
     [P in ITSKeyOfUnionOptional<T>]?: ITSValueOfUnion<T, P>;
 };
 /**
+ * 判斷鍵 K 是否在聯集 T 的每個成員中都為必填
  * Checks whether K is required in every member of T.
+ *
+ * @example
+ * type T =
+ *   | { type: "a"; value: number }
+ *   | { type: "b"; value?: string };
+ *
+ * type A = ITSIsRequiredInUnion<T, "type">;  // true
+ * type B = ITSIsRequiredInUnion<T, "value">; // false
  */
 export type ITSIsRequiredInUnion<T, K extends ITSKeyOfUnion<T>> = false extends (T extends unknown ? K extends keyof T ? {} extends Pick<T, K> ? false : true : false : never) ? false : true;
 /**
+ * 取得在聯集 T 每個成員中都為必填的鍵集合
  * Gets keys that are required in every member of T.
+ *
+ * @example
+ * type T =
+ *   | { type: "a"; value: number }
+ *   | { type: "b"; value?: string };
+ *
+ * type RequiredKeys = ITSKeyOfUnionRequired<T>;
+ * // "type"
  */
 export type ITSKeyOfUnionRequired<T> = {
     [K in ITSKeyOfUnion<T>]: ITSIsRequiredInUnion<T, K> extends true ? K : never;
 }[ITSKeyOfUnion<T>];
 /**
+ * 取得在聯集 T 中並非於每個成員都必填的鍵集合
  * Gets keys that are not required in every member of T.
+ *
+ * @example
+ * type T =
+ *   | { type: "a"; value: number }
+ *   | { type: "b"; value?: string };
+ *
+ * type OptionalKeys = ITSKeyOfUnionOptional<T>;
+ * // "value"
  */
 export type ITSKeyOfUnionOptional<T> = Exclude<ITSKeyOfUnion<T>, ITSKeyOfUnionRequired<T>>;
 /**
- * Makes the specified properties required and flattens
+ * 將聯集扁平化為單一物件型別，並將指定屬性設為可選
+ * Makes the specified properties optional and flattens
  * all members of a union into a single object type.
  *
+ * 其餘來自各聯集成員的屬性會以可選屬性保留，因為它們不一定
+ * 存在於每個成員之中
  * Other properties from all union members are preserved as
  * optional properties because they may not exist in every member.
+ *
+ * @example
+ * type T =
+ *   | { type: "a"; value: number }
+ *   | { type: "b"; value?: string };
+ *
+ * type Result = ITSPartialWithUnionFlat<T, "value">;
+ * // {
+ * //   type?: "a" | "b";
+ * //   value?: number | string;
+ * // }
  */
 export type ITSPartialWithUnionFlat<T, K extends ITSKeyOfUnion<T>> = Omit<ITSUnionFlat<T>, K> & {
     [P in K]?: ITSValueOfUnion<T, P>;
 };
 /**
- * Makes the specified properties optional and flattens
+ * 將聯集扁平化為單一物件型別，並將指定屬性設為必填
+ * Makes the specified properties required and flattens
  * all members of a union into a single object type.
  *
+ * 其餘來自各聯集成員的屬性會以可選屬性保留，因為它們不一定
+ * 存在於每個成員之中
  * Other properties from all union members are preserved as
  * optional properties because they may not exist in every member.
+ *
+ * @example
+ * type T =
+ *   | { type: "a"; value: number }
+ *   | { type: "b"; value?: string };
+ *
+ * type Result = ITSRequiredWithUnionFlat<T, "value">;
+ * // {
+ * //   type?: "a" | "b";
+ * //   value: number | string;
+ * // }
  */
 export type ITSRequiredWithUnionFlat<T, K extends ITSKeyOfUnion<T>> = Omit<ITSUnionFlat<T>, K> & {
     [P in K]-?: ITSValueOfUnion<T, P>;
 };
+/**
+ * 將聯集 T 扁平化為單一物件型別，並把所有鍵設為可選
+ * Flattens a union T into a single object type and makes
+ * all keys optional.
+ *
+ * 僅保留那些在成員中存在、且型別為該成員對應屬性類型的屬性
+ * Only members that actually contain the key contribute their
+ * property type.
+ *
+ * @example
+ * type T =
+ *   | { type: "a"; value: number }
+ *   | { type: "b"; text: string };
+ *
+ * type Result = ITSUnionToOptional<T>;
+ * // {
+ * //   type?: "a" | "b";
+ * //   value?: number;
+ * //   text?: string;
+ * // }
+ */
 export type ITSUnionToOptional<T> = [T] extends [infer U] ? {
     [K in ITSKeyOfUnion<U>]?: U extends Record<K, any> ? U[K] : never;
 } : never;
+/**
+ * 取得聯集 T 在「所有鍵皆為可選」版本與原聯集型別的交集
+ * Gets the intersection of T with its all-optional flattened form.
+ *
+ * 可同時接受「完全可選」的物件，也能精確匹配原本的聯集成員
+ * Accepts a fully-optional object while still matching the
+ * original union members exactly.
+ *
+ * @example
+ * type T =
+ *   | { type: "a"; value: number }
+ *   | { type: "b"; text: string };
+ *
+ * type Result = ITSAnyOfUnion<T>;
+ * // {
+ * //   type?: "a" | "b";
+ * //   value?: number;
+ * //   text?: string;
+ * // } & ({
+ * //   type: "a"; value: number;
+ * // } | {
+ * //   type: "b"; text: string;
+ * // })
+ */
 export type ITSAnyOfUnion<T> = ITSUnionToOptional<T> & T;

package/lib/type/record/union.js

@@ -1,27 +1,30 @@
 "use strict";
 /*
-ITSPartialPick / ITSRequiredPick
-└─ 一般 Object
-   └─ keyof T
-
-ITSPartialPickUnion / ITSRequiredPickUnion
-└─ Union
-   └─ 保留 A | B 結構
-      └─ distributive conditional type
-
-ITSPartialPickUnionFlat / ITSRequiredPickUnionFlat
-└─ UnionFlat
-   └─ A | B → 單一 Object
-      └─ ITSKeyOfUnion + ITSValueOfUnion
-
-PartialWith
-    → 修改 K，保留 Object
-
-PartialWithUnion
-    → 修改 K，保留 A | B
-
-PartialWithUnionFlat
-    → Flatten A | B，再只修改 K
-*/
+ * 聯集 (Union) 型別的鍵選取工具總覽
+ * Overview of Union key-selection utilities
+ *
+ * ITSPartialPick / ITSRequiredPick
+ * └─ 一般 Object / 一般物件
+ *    └─ keyof T
+ *
+ * ITSPartialPickUnion / ITSRequiredPickUnion
+ * └─ Union 聯集
+ *    └─ 保留 A | B 結構 / preserve A | B structure
+ *       └─ distributive conditional type / 分配式條件型別
+ *
+ * ITSPartialPickUnionFlat / ITSRequiredPickUnionFlat
+ * └─ UnionFlat 扁平聯集
+ *    └─ A | B → 單一 Object / A | B → single object
+ *       └─ ITSKeyOfUnion + ITSValueOfUnion
+ *
+ * PartialWith
+ * 	→ 修改 K，保留 Object / modify K, preserve object
+ *
+ * PartialWithUnion
+ * 	→ 修改 K，保留 A | B / modify K, preserve A | B
+ *
+ * PartialWithUnionFlat
+ * 	→ Flatten A | B，再只修改 K / flatten A | B, then modify only K
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 //# sourceMappingURL=union.js.map

package/lib/type/record/union.js.map

@@ -1 +1 @@
-{"version":3,"file":"union.js","sourceRoot":"","sources":["union.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;EAuBE","sourcesContent":["/*\r\nITSPartialPick / ITSRequiredPick\r\n└─ 一般 Object\r\n   └─ keyof T\r\n\r\nITSPartialPickUnion / ITSRequiredPickUnion\r\n└─ Union\r\n   └─ 保留 A | B 結構\r\n      └─ distributive conditional type\r\n\r\nITSPartialPickUnionFlat / ITSRequiredPickUnionFlat\r\n└─ UnionFlat\r\n   └─ A | B → 單一 Object\r\n      └─ ITSKeyOfUnion + ITSValueOfUnion\r\n\r\nPartialWith\r\n\t→ 修改 K，保留 Object\r\n\r\nPartialWithUnion\r\n\t→ 修改 K，保留 A | B\r\n\r\nPartialWithUnionFlat\r\n\t→ Flatten A | B，再只修改 K\r\n*/\r\n\r\nimport { ITSKeyOfUnion, ITSValueOfUnion } from \"../../helper/key-value\";\r\nimport { ITSPartialPick, ITSPartialWith, ITSRequiredPick, ITSRequiredWith } from \"../record\";\r\n\r\n/**\r\n * Makes the selected properties optional while preserving\r\n * the structure of each union member.\r\n *\r\n * This is the distributive Union version.\r\n *\r\n * @example\r\n * type T =\r\n *   | { type: \"a\"; value: number }\r\n *   | { type: \"b\"; text: string };\r\n *\r\n * type Result = ITSPartialPickUnion<T>;\r\n * // {\r\n * //   type?: \"a\";\r\n * //   value?: number;\r\n * // } | {\r\n * //   type?: \"b\";\r\n * //   text?: string;\r\n * // }\r\n */\r\nexport type ITSPartialPickUnion<\r\n\tT,\r\n\tK extends ITSKeyOfUnion<T> = ITSKeyOfUnion<T>\r\n> = T extends any\r\n\t? {\r\n\t\t[P in K & keyof T]?: T[P];\r\n\t}\r\n\t: never;\r\n\r\n/**\r\n * Makes the selected properties required while preserving\r\n * the structure of each union member.\r\n *\r\n * This is the distributive Union version.\r\n *\r\n * @example\r\n * type T =\r\n *   | { type: \"a\"; value?: number }\r\n *   | { type: \"b\"; text?: string };\r\n *\r\n * type Result = ITSRequiredPickUnion<T>;\r\n * // {\r\n * //   type: \"a\";\r\n * //   value: number;\r\n * // } | {\r\n * //   type: \"b\";\r\n * //   text: string;\r\n * // }\r\n */\r\nexport type ITSRequiredPickUnion<\r\n\tT,\r\n\tK extends ITSKeyOfUnion<T> = ITSKeyOfUnion<T>\r\n> = T extends any\r\n\t? {\r\n\t\t[P in K & keyof T]-?: T[P];\r\n\t}\r\n\t: never;\r\n\r\n/**\r\n * Makes the selected properties optional and flattens\r\n * all properties from every union member into a single object type.\r\n *\r\n * Unlike ITSPartialPickUnion, this does not preserve the\r\n * individual union-member structure.\r\n *\r\n * @example\r\n * type T =\r\n *   | { type: \"a\"; value: number }\r\n *   | { type: \"b\"; text: string };\r\n *\r\n * type Result = ITSPartialPickUnionFlat<T>;\r\n * // {\r\n * //   type?: \"a\" | \"b\";\r\n * //   value?: number;\r\n * //   text?: string;\r\n * // }\r\n */\r\nexport type ITSPartialPickUnionFlat<\r\n\tT,\r\n\tK extends ITSKeyOfUnion<T> = ITSKeyOfUnion<T>\r\n> = {\r\n\t[P in K]?: ITSValueOfUnion<T, P>;\r\n};\r\n\r\n/**\r\n * Makes the selected properties required and flattens\r\n * all members of a union into a single object type.\r\n *\r\n * Note: this utility intentionally makes every selected property\r\n * required. For a natural flattened representation that preserves\r\n * whether a property exists in every member, use a dedicated\r\n * flat-base utility.\r\n */\r\nexport type ITSRequiredPickUnionFlat<\r\n\tT,\r\n\tK extends ITSKeyOfUnion<T> = ITSKeyOfUnion<T>\r\n> = {\r\n\t[P in K]-?: ITSValueOfUnion<T, P>;\r\n};\r\n\r\n// ---------------\r\n\r\n/**\r\n * Makes the specified properties required for each member\r\n * of a union while preserving the union-member structure.\r\n *\r\n * Other properties are preserved unchanged.\r\n */\r\nexport type ITSRequiredWithUnion<\r\n\tT,\r\n\tK extends ITSKeyOfUnion<T>\r\n> = T extends any\r\n\t? K extends keyof T\r\n\t\t? Omit<T, K> & ITSRequiredPick<T, K>\r\n\t\t: T\r\n\t: never;\r\n\r\n/**\r\n * Makes the specified properties optional for each member\r\n * of a union while preserving the union-member structure.\r\n *\r\n * Other properties are preserved unchanged.\r\n */\r\nexport type ITSPartialWithUnion<\r\n\tT,\r\n\tK extends ITSKeyOfUnion<T>\r\n> = T extends any\r\n\t? K extends keyof T\r\n\t\t? Omit<T, K> & ITSPartialPick<T, K>\r\n\t\t: T\r\n\t: never;\r\n\r\nexport type ITSUnionFlat<T> = {\r\n\t[P in ITSKeyOfUnionRequired<T>]-?: ITSValueOfUnion<T, P>;\r\n} & {\r\n\t[P in ITSKeyOfUnionOptional<T>]?: ITSValueOfUnion<T, P>;\r\n};\r\n\r\n/**\r\n * Checks whether K is required in every member of T.\r\n */\r\nexport type ITSIsRequiredInUnion<\r\n\tT,\r\n\tK extends ITSKeyOfUnion<T>\r\n> = false extends (\r\n\t\tT extends unknown\r\n\t\t\t? K extends keyof T\r\n\t\t\t\t? {} extends Pick<T, K>\r\n\t\t\t\t\t? false\r\n\t\t\t\t\t: true\r\n\t\t\t\t: false\r\n\t\t\t: never\r\n\t\t)\r\n\t? false\r\n\t: true;\r\n\r\n/**\r\n * Gets keys that are required in every member of T.\r\n */\r\nexport type ITSKeyOfUnionRequired<T> = {\r\n\t[K in ITSKeyOfUnion<T>]:\r\n\tITSIsRequiredInUnion<T, K> extends true\r\n\t\t? K\r\n\t\t: never;\r\n}[ITSKeyOfUnion<T>];\r\n\r\n/**\r\n * Gets keys that are not required in every member of T.\r\n */\r\nexport type ITSKeyOfUnionOptional<T> =\r\n\tExclude<\r\n\t\tITSKeyOfUnion<T>,\r\n\t\tITSKeyOfUnionRequired<T>\r\n\t>;\r\n\r\n/**\r\n * Makes the specified properties required and flattens\r\n * all members of a union into a single object type.\r\n *\r\n * Other properties from all union members are preserved as\r\n * optional properties because they may not exist in every member.\r\n */\r\nexport type ITSPartialWithUnionFlat<\r\n\tT,\r\n\tK extends ITSKeyOfUnion<T>\r\n> = Omit<ITSUnionFlat<T>, K>\r\n\t& {\r\n\t[P in K]?: ITSValueOfUnion<T, P>;\r\n};\r\n\r\n/**\r\n * Makes the specified properties optional and flattens\r\n * all members of a union into a single object type.\r\n *\r\n * Other properties from all union members are preserved as\r\n * optional properties because they may not exist in every member.\r\n */\r\nexport type ITSRequiredWithUnionFlat<\r\n\tT,\r\n\tK extends ITSKeyOfUnion<T>\r\n> = Omit<ITSUnionFlat<T>, K>\r\n\t& {\r\n\t[P in K]-?: ITSValueOfUnion<T, P>;\r\n};\r\n\r\n// ----------------\r\n\r\nexport type ITSUnionToOptional<T> = [T] extends [infer U]\r\n\t? { [K in ITSKeyOfUnion<U>]?: U extends Record<K, any> ? U[K] : never }\r\n\t: never;\r\n\r\nexport type ITSAnyOfUnion<T> = ITSUnionToOptional<T> & T;\r\n"]}
+{"version":3,"file":"union.js","sourceRoot":"","sources":["union.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG","sourcesContent":["/*\n * 聯集 (Union) 型別的鍵選取工具總覽\n * Overview of Union key-selection utilities\n *\n * ITSPartialPick / ITSRequiredPick\n * └─ 一般 Object / 一般物件\n *    └─ keyof T\n *\n * ITSPartialPickUnion / ITSRequiredPickUnion\n * └─ Union 聯集\n *    └─ 保留 A | B 結構 / preserve A | B structure\n *       └─ distributive conditional type / 分配式條件型別\n *\n * ITSPartialPickUnionFlat / ITSRequiredPickUnionFlat\n * └─ UnionFlat 扁平聯集\n *    └─ A | B → 單一 Object / A | B → single object\n *       └─ ITSKeyOfUnion + ITSValueOfUnion\n *\n * PartialWith\n * \t→ 修改 K，保留 Object / modify K, preserve object\n *\n * PartialWithUnion\n * \t→ 修改 K，保留 A | B / modify K, preserve A | B\n *\n * PartialWithUnionFlat\n * \t→ Flatten A | B，再只修改 K / flatten A | B, then modify only K\n */\n\nimport { ITSKeyOfUnion, ITSValueOfUnion } from \"../../helper/key-value\";\nimport { ITSPartialPick, ITSPartialWith, ITSRequiredPick, ITSRequiredWith } from \"../record\";\n\n/**\n * 在保留每個聯集成員結構的前提下，將選取的屬性設為可選\n * Makes the selected properties optional while preserving\n * the structure of each union member.\n *\n * 這是分配式 (distributive) 的 Union 版本，會對聯集的每個成員\n * 分別套用 `Partial<Pick<T, K>>`\n * This is the distributive Union version: it applies\n * `Partial<Pick<T, K>>` to each union member individually.\n *\n * @example\n * type T =\n *   | { type: \"a\"; value: number }\n *   | { type: \"b\"; text: string };\n *\n * type Result = ITSPartialPickUnion<T>;\n * // {\n * //   type?: \"a\";\n * //   value?: number;\n * // } | {\n * //   type?: \"b\";\n * //   text?: string;\n * // }\n */\nexport type ITSPartialPickUnion<\n\tT,\n\tK extends ITSKeyOfUnion<T> = ITSKeyOfUnion<T>\n> = T extends any\n\t? {\n\t\t[P in K & keyof T]?: T[P];\n\t}\n\t: never;\n\n/**\n * 在保留每個聯集成員結構的前提下，將選取的屬性設為必填\n * Makes the selected properties required while preserving\n * the structure of each union member.\n *\n * 這是分配式 (distributive) 的 Union 版本，會對聯集的每個成員\n * 分別套用 `Required<Pick<T, K>>`\n * This is the distributive Union version: it applies\n * `Required<Pick<T, K>>` to each union member individually.\n *\n * @example\n * type T =\n *   | { type: \"a\"; value?: number }\n *   | { type: \"b\"; text?: string };\n *\n * type Result = ITSRequiredPickUnion<T>;\n * // {\n * //   type: \"a\";\n * //   value: number;\n * // } | {\n * //   type: \"b\";\n * //   text: string;\n * // }\n */\nexport type ITSRequiredPickUnion<\n\tT,\n\tK extends ITSKeyOfUnion<T> = ITSKeyOfUnion<T>\n> = T extends any\n\t? {\n\t\t[P in K & keyof T]-?: T[P];\n\t}\n\t: never;\n\n/**\n * 將選取的屬性設為可選，並把聯集中所有成員的屬性扁平化為單一物件型別\n * Makes the selected properties optional and flattens\n * all properties from every union member into a single object type.\n *\n * 與 ITSPartialPickUnion 不同，此工具不保留各聯集成員的個別結構，\n * 而是將所有鍵合併到同一個物件中\n * Unlike ITSPartialPickUnion, this does not preserve the\n * individual union-member structure; instead it merges all keys\n * into a single object.\n *\n * @example\n * type T =\n *   | { type: \"a\"; value: number }\n *   | { type: \"b\"; text: string };\n *\n * type Result = ITSPartialPickUnionFlat<T>;\n * // {\n * //   type?: \"a\" | \"b\";\n * //   value?: number;\n * //   text?: string;\n * // }\n */\nexport type ITSPartialPickUnionFlat<\n\tT,\n\tK extends ITSKeyOfUnion<T> = ITSKeyOfUnion<T>\n> = {\n\t[P in K]?: ITSValueOfUnion<T, P>;\n};\n\n/**\n * 將選取的屬性設為必填，並把聯集中所有成員扁平化為單一物件型別\n * Makes the selected properties required and flattens\n * all members of a union into a single object type.\n *\n * 注意：此工具會刻意將所有選取的屬性設為必填。若需要更自然地保留\n * 「屬性是否於每個成員中都存在」的語意，請改用 ITSUnionFlat 等\n * 以扁平化為基礎的工具。\n * Note: this utility intentionally makes every selected property\n * required. For a natural flattened representation that preserves\n * whether a property exists in every member, use a dedicated\n * flat-base utility such as ITSUnionFlat.\n *\n * @example\n * type T =\n *   | { type: \"a\"; value: number }\n *   | { type: \"b\"; text: string };\n *\n * type Result = ITSRequiredPickUnionFlat<T>;\n * // {\n * //   type: \"a\" | \"b\";\n * //   value: number;\n * //   text: string;\n * // }\n */\nexport type ITSRequiredPickUnionFlat<\n\tT,\n\tK extends ITSKeyOfUnion<T> = ITSKeyOfUnion<T>\n> = {\n\t[P in K]-?: ITSValueOfUnion<T, P>;\n};\n\n// ---------------\n\n/**\n * 在保留聯集成員結構的前提下，將指定屬性設為必填\n * Makes the specified properties required for each member\n * of a union while preserving the union-member structure.\n *\n * 其餘屬性保持不變（未被選取的屬性原樣保留）\n * Other properties are preserved unchanged.\n *\n * @example\n * type T =\n *   | { type: \"a\"; value?: number }\n *   | { type: \"b\"; text?: string };\n *\n * type Result = ITSRequiredWithUnion<T, \"value\" | \"text\">;\n * // {\n * //   type: \"a\";\n * //   value: number;\n * // } | {\n * //   type: \"b\";\n * //   text: string;\n * // }\n */\nexport type ITSRequiredWithUnion<\n\tT,\n\tK extends ITSKeyOfUnion<T>\n> = T extends any\n\t? K extends keyof T\n\t\t? Omit<T, K> & ITSRequiredPick<T, K>\n\t\t: T\n\t: never;\n\n/**\n * 在保留聯集成員結構的前提下，將指定屬性設為可選\n * Makes the specified properties optional for each member\n * of a union while preserving the union-member structure.\n *\n * 其餘屬性保持不變（未被選取的屬性原樣保留）\n * Other properties are preserved unchanged.\n *\n * @example\n * type T =\n *   | { type: \"a\"; value: number }\n *   | { type: \"b\"; text: string };\n *\n * type Result = ITSPartialWithUnion<T, \"value\" | \"text\">;\n * // {\n * //   type: \"a\";\n * //   value?: number;\n * // } | {\n * //   type: \"b\";\n * //   text?: string;\n * // }\n */\nexport type ITSPartialWithUnion<\n\tT,\n\tK extends ITSKeyOfUnion<T>\n> = T extends any\n\t? K extends keyof T\n\t\t? Omit<T, K> & ITSPartialPick<T, K>\n\t\t: T\n\t: never;\n\n/**\n * 將聯集扁平化為單一物件型別，並依各屬性在聯集中的存在情況\n * 決定其為必填或可選\n * Flattens a union into a single object type, marking each\n * property as required or optional based on whether it exists\n * in every union member.\n *\n * 在每個成員都必填的鍵會被設為必填；否則設為可選\n * Keys required in every member become required; the rest optional.\n *\n * @example\n * type T =\n *   | { type: \"a\"; value: number }\n *   | { type: \"b\"; value?: string };\n *\n * type Result = ITSUnionFlat<T>;\n * // {\n * //   type: \"a\" | \"b\";\n * //   value?: number | string;\n * // }\n */\nexport type ITSUnionFlat<T> = {\n\t[P in ITSKeyOfUnionRequired<T>]-?: ITSValueOfUnion<T, P>;\n} & {\n\t[P in ITSKeyOfUnionOptional<T>]?: ITSValueOfUnion<T, P>;\n};\n\n/**\n * 判斷鍵 K 是否在聯集 T 的每個成員中都為必填\n * Checks whether K is required in every member of T.\n *\n * @example\n * type T =\n *   | { type: \"a\"; value: number }\n *   | { type: \"b\"; value?: string };\n *\n * type A = ITSIsRequiredInUnion<T, \"type\">;  // true\n * type B = ITSIsRequiredInUnion<T, \"value\">; // false\n */\nexport type ITSIsRequiredInUnion<\n\tT,\n\tK extends ITSKeyOfUnion<T>\n> = false extends (\n\tT extends unknown\n\t\t? K extends keyof T\n\t\t\t? {} extends Pick<T, K>\n\t\t\t\t? false\n\t\t\t\t: true\n\t\t\t: false\n\t\t: never\n\t)\n\t? false\n\t: true;\n\n/**\n * 取得在聯集 T 每個成員中都為必填的鍵集合\n * Gets keys that are required in every member of T.\n *\n * @example\n * type T =\n *   | { type: \"a\"; value: number }\n *   | { type: \"b\"; value?: string };\n *\n * type RequiredKeys = ITSKeyOfUnionRequired<T>;\n * // \"type\"\n */\nexport type ITSKeyOfUnionRequired<T> = {\n\t[K in ITSKeyOfUnion<T>]:\n\tITSIsRequiredInUnion<T, K> extends true\n\t\t? K\n\t\t: never;\n}[ITSKeyOfUnion<T>];\n\n/**\n * 取得在聯集 T 中並非於每個成員都必填的鍵集合\n * Gets keys that are not required in every member of T.\n *\n * @example\n * type T =\n *   | { type: \"a\"; value: number }\n *   | { type: \"b\"; value?: string };\n *\n * type OptionalKeys = ITSKeyOfUnionOptional<T>;\n * // \"value\"\n */\nexport type ITSKeyOfUnionOptional<T> =\n\tExclude<\n\t\tITSKeyOfUnion<T>,\n\t\tITSKeyOfUnionRequired<T>\n\t>;\n\n/**\n * 將聯集扁平化為單一物件型別，並將指定屬性設為可選\n * Makes the specified properties optional and flattens\n * all members of a union into a single object type.\n *\n * 其餘來自各聯集成員的屬性會以可選屬性保留，因為它們不一定\n * 存在於每個成員之中\n * Other properties from all union members are preserved as\n * optional properties because they may not exist in every member.\n *\n * @example\n * type T =\n *   | { type: \"a\"; value: number }\n *   | { type: \"b\"; value?: string };\n *\n * type Result = ITSPartialWithUnionFlat<T, \"value\">;\n * // {\n * //   type?: \"a\" | \"b\";\n * //   value?: number | string;\n * // }\n */\nexport type ITSPartialWithUnionFlat<\n\tT,\n\tK extends ITSKeyOfUnion<T>\n> = Omit<ITSUnionFlat<T>, K>\n\t& {\n\t[P in K]?: ITSValueOfUnion<T, P>;\n};\n\n/**\n * 將聯集扁平化為單一物件型別，並將指定屬性設為必填\n * Makes the specified properties required and flattens\n * all members of a union into a single object type.\n *\n * 其餘來自各聯集成員的屬性會以可選屬性保留，因為它們不一定\n * 存在於每個成員之中\n * Other properties from all union members are preserved as\n * optional properties because they may not exist in every member.\n *\n * @example\n * type T =\n *   | { type: \"a\"; value: number }\n *   | { type: \"b\"; value?: string };\n *\n * type Result = ITSRequiredWithUnionFlat<T, \"value\">;\n * // {\n * //   type?: \"a\" | \"b\";\n * //   value: number | string;\n * // }\n */\nexport type ITSRequiredWithUnionFlat<\n\tT,\n\tK extends ITSKeyOfUnion<T>\n> = Omit<ITSUnionFlat<T>, K>\n\t& {\n\t[P in K]-?: ITSValueOfUnion<T, P>;\n};\n\n// ----------------\n\n/**\n * 將聯集 T 扁平化為單一物件型別，並把所有鍵設為可選\n * Flattens a union T into a single object type and makes\n * all keys optional.\n *\n * 僅保留那些在成員中存在、且型別為該成員對應屬性類型的屬性\n * Only members that actually contain the key contribute their\n * property type.\n *\n * @example\n * type T =\n *   | { type: \"a\"; value: number }\n *   | { type: \"b\"; text: string };\n *\n * type Result = ITSUnionToOptional<T>;\n * // {\n * //   type?: \"a\" | \"b\";\n * //   value?: number;\n * //   text?: string;\n * // }\n */\nexport type ITSUnionToOptional<T> = [T] extends [infer U]\n\t? { [K in ITSKeyOfUnion<U>]?: U extends Record<K, any> ? U[K] : never }\n\t: never;\n\n/**\n * 取得聯集 T 在「所有鍵皆為可選」版本與原聯集型別的交集\n * Gets the intersection of T with its all-optional flattened form.\n *\n * 可同時接受「完全可選」的物件，也能精確匹配原本的聯集成員\n * Accepts a fully-optional object while still matching the\n * original union members exactly.\n *\n * @example\n * type T =\n *   | { type: \"a\"; value: number }\n *   | { type: \"b\"; text: string };\n *\n * type Result = ITSAnyOfUnion<T>;\n * // {\n * //   type?: \"a\" | \"b\";\n * //   value?: number;\n * //   text?: string;\n * // } & ({\n * //   type: \"a\"; value: number;\n * // } | {\n * //   type: \"b\"; text: string;\n * // })\n */\nexport type ITSAnyOfUnion<T> = ITSUnionToOptional<T> & T;\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-type",
-  "version": "3.0.15",
+  "version": "3.0.16",
   "description": "TypeScript 類型工具庫：提供豐富的類型操作工具和重新導出的內建類型 / TypeScript type utility library: provides rich type manipulation utilities and re-exported built-in types",
   "keywords": [
     ".d.ts",
@@ -69,7 +69,7 @@
     "build:toc": "tsc --skipLibCheck & echo build:toc",
     "preversion": "pnpm run test && pnpm run postpublish:git:commit",
     "prepublishOnly": "echo prepublishOnly",
-    "postpublish:git:commit": "git commit -m \"build(release): publish\" ./lib/index.d.ts ./lib & echo postpublish:git:commit",
+    "postpublish:git:commit": "git commit -m \"build(release): update generated files\" ./lib/index.d.ts ./lib & echo postpublish:git:commit",
     "ncu": "yarn-tool ncu -u",
     "sort-package-json": "yarn-tool sort",
     "ts:check": "tsc -p tsconfig.check.json --emitDeclarationOnly --skipLibCheck",
@@ -95,10 +95,10 @@
     "typedarray-dts": "^1.0.0"
   },
   "devDependencies": {
-    "@ts-type/object-freeze": "^1.0.15"
+    "@ts-type/object-freeze": "^1.0.16"
   },
   "peerDependencies": {
     "ts-toolbelt": "^9.6.0"
   },
-  "gitHead": "b1febe34d831268743202cf8176775b35ec0bd05"
+  "gitHead": "6411b1f4cf689345537ab348e19e7e7dfd3bdfef"
 }