[doc/feat] ArrayOf/ib-writer

1. ArrayOf
1-1. Added support for native-typed arrays: Native::string, Native::int, Native::float, Native::bool, validating PHP scalar values without requiring SingleValueObject.
1-2. Documentation updated to clarify that Native enums are valid targets for ArrayOf.
2. Writer / ib-writer
2-1. Updated class-level descriptions and usage examples to include TypeScript output support.
2-2. TypeScript (.ts) generation now produces: declare namespace blocks, DTO/VO interfaces, SVO type aliases, and enum/union types for referenced PHP enums.
3. InvalidArrayOfItemException
3-1. Fixed @param count and names to match constructor signature.
3-2. Improved message clarity, distinguishing ImmutableBase class resolution failures from primitive type mismatches.
4. InvalidPropertyTypeException
4-1. Added standalone null to the forbidden property type list.
4-2. Updated message to list allowed types and provide guidance for nullable declarations (?Type or Type|null).
5. InvalidArrayOfTargetException
5-1. Documentation updated to indicate Native can be used as a valid ArrayOf target type.
6. ImmutableBase
6-1. scanNamedType(): clarified that null passes through as a builtin type.
6-2. arrayOfInitialize(): removed phantom @param $propertyName.

Author: ReallifeKip

CHANGELOG.md

@@ -1,8 +1,22 @@
 # CHANGELOG
 
-## [4.1.1] - 2025-03-07
+## [v4.2.0] - 2026-03-12
+
+### Added
+
+- **`Native` enum — Primitive typed arrays via `#[ArrayOf]`.** `#[ArrayOf]` now accepts `Native::string`, `Native::int`, `Native::float`, and `Native::bool` to declare arrays of validated PHP scalar values without wrapping them in a SingleValueObject.
+- **`ib-writer` TypeScript output.** `vendor/bin/ib-writer` now supports `.ts` generation, producing `declare namespace` blocks with interfaces for DTO/VO, type aliases for SVO, and enum/union types for referenced PHP enums.
+
+### Changed
+
+- **Standalone `null` property type is now forbidden.** Declaring a property typed as `null` alone throws `InvalidPropertyTypeException` at scan time. Use `?Type` or `Type|null` for nullable properties.
+- **`InvalidPropertyTypeException` message updated.** Now explicitly lists allowed types and provides nullable usage guidance.
+- **`InvalidArrayOfItemException` message updated.** Now distinguishes between ImmutableBase class resolution failures and primitive type mismatches.
+
+## [v4.1.1] - 2025-03-07
 
 ### Fixed
+
 #### ib-writer
 - Property tables now include a `default` column displaying default
   values from `#[Defaults]` attributes and `defaultValues()` overrides

README.md

@@ -38,7 +38,7 @@ readonly class Order extends DataTransferObject
     public string $date;
     public string $time;
 }
-Order::fromArray($data); // $data can be an array or JSON
+Order::fromArray($data); // $data must be an array (use fromJson() for JSON strings)
 
 // 🫤 The conventional approach requires writing constructors manually, cannot directly accept external array or JSON data for construction.
 class Order extends DataTransferObject
@@ -115,7 +115,7 @@ SomeException: {error message}
 
 ### 📃 Documentation as Code, Code as Documentation
 
-🥳 ImmutableBase can scan all subclasses in your project via `vendor/bin/ib-writer`, generating Mermaid class diagrams and Markdown property tables to keep documentation in sync with code.
+🥳 ImmutableBase can scan all subclasses in your project via `vendor/bin/ib-writer`, generating Mermaid class diagrams, Markdown property tables, and TypeScript declarations to keep documentation in sync with code.
 
 🫤 The conventional approach cannot guarantee consistency between code and documentation.
 
@@ -298,7 +298,7 @@ readonly class ValidAge extends SingleValueObject
 ```php
 $age = ValidAge::from(18);
 
-echo $age;          // 18 (via __toString, only available when $value is a string)
+echo $age;          // 18 (via __toString, string-casts $value)
 echo $age();        // 18 (via __invoke)
 echo $age->value;   // 18
 ```
@@ -485,16 +485,32 @@ CreateUserDTO::fromArray(['name' => 'Kip']); // role = 'member'
 
 ### `#[ArrayOf]` - Typed Array
 
-Marks an array property as a typed collection of ImmutableBase instances. Each element is automatically instantiated from arrays, JSON strings, or pre-built objects. The target class must be a subclass of DTO, VO, or SVO.
+Marks an array property as a typed collection of ImmutableBase instances or primitive scalar values. Each element is automatically validated or instantiated. The target must be a subclass of DTO, VO, or SVO, or a `Native` enum case for scalar arrays.
+
+**Primitive scalar arrays** can be declared using `Native` enum cases instead of a class name:
+
+| Case             | PHP type |
+| ---------------- | -------- |
+| `Native::string` | `string` |
+| `Native::int`    | `int`    |
+| `Native::float`  | `float`  |
+| `Native::bool`   | `bool`   |
 
 ```php
 use ReallifeKip\ImmutableBase\Attributes\ArrayOf;
 
 readonly class SignUpUsersDTO extends DataTransferObject
 {
+
+    // ImmutableBase subclass
     #[ArrayOf(User::class)]
     public array $users;
-    public int $userCount;
+
+    // Primitive scalar array
+    #[ArrayOf(Native::string)]
+    public array $tags;
+    #[ArrayOf(Native::int)]
+    public array $scores;
 }
 ```
 
@@ -637,7 +653,7 @@ vendor/bin/ib-cacher --clear
 
 ### `writer` - Documentation Generator
 
-Generates documentation for all ImmutableBase subclasses in the project. Supports Mermaid class diagrams and Markdown property tables.
+Generates documentation for all ImmutableBase subclasses in the project. Supports Mermaid class diagrams, Markdown property tables, and TypeScript declarations.
 
 ```bash
 vendor/bin/ib-writer
@@ -720,7 +736,7 @@ This section is provided for v3 migration reference only.
 ## Notes
 
 1. All subclass properties must be public. Since ImmutableBase is declared as a readonly class, the entire inheritance chain must also be readonly at the PHP language level.
-2. Forbidden property types: `iterable`, `object`, non-ImmutableBase/non-Enum classes such as `DateTime`, `Closure`.
+2. Forbidden property types: `null`, `iterable`, `object`, non-ImmutableBase/non-Enum classes such as `DateTime`, `Closure`.
 3. Enum properties accept case names (`"HIGH"`) or backed values (`3`). The resolved property value is always an Enum instance.
 4. `mixed` type is supported, but values will not be validated.
 

README_TW.md

@@ -38,7 +38,7 @@ readonly class Order extends DataTransferObject
     public string $date;
     public string $time;
 }
-Order::fromArray($data); // $data 可以是陣列、JSON
+Order::fromArray($data); // $data 必須是陣列（JSON 字串請改用 fromJson()）
 
 // 🫤 一般常見做法需要重複撰寫建構子，也常因順序不正確而無法建構，且無法直接使用外部傳入資料進行建構。
 class Order extends DataTransferObject
@@ -115,7 +115,7 @@ SomeException: {錯誤訊息}
 
 ### 📃文件即代碼，代碼即文件
 
-🥳 ImmutableBase 可以透過 `vendor/bin/ib-writer` 對專案進行 ImmutableBase 子類物件掃描，力求避免文件與代碼不一致、需要花費額外人力的窘境，快速產出 Mermaid、Markdown 等技術文件。
+🥳 ImmutableBase 可以透過 `vendor/bin/ib-writer` 對專案進行 ImmutableBase 子類物件掃描，力求避免文件與代碼不一致、需要花費額外人力的窘境，快速產出 Mermaid 類別圖、Markdown 屬性表及 TypeScript 型別宣告等技術文件。
 
 🫤 一般常見做法無法保障代碼與文件一致。
 
@@ -298,7 +298,7 @@ readonly class ValidAge extends SingleValueObject
 ```php
 $age = ValidAge::from(18);
 
-echo $age;          // 18（透過 __toString，僅 $value 為字串時可用）
+echo $age;          // 18（透過 __toString，會將 $value 轉為字串）
 echo $age();        // 18（透過 __invoke）
 echo $age->value;   // 18
 ```
@@ -485,16 +485,31 @@ CreateUserDTO::fromArray(['name' => 'Kip']); // role = 'member'
 
 ### `#[ArrayOf]` - 型別陣列
 
-將陣列屬性標記為 ImmutableBase 實例的型別集合。每個元素會自動從陣列、JSON 字串或已建構物件進行實例化，目標類必須是 DTO、VO 或 SVO 的子類。
+將陣列屬性標記為 ImmutableBase 實例或純量值的型別集合。每個元素會自動驗證或實例化。目標必須是 DTO、VO 或 SVO 的子類，或純量陣列可使用 `Native` enum case。
+
+**純量型別陣列**可使用 `Native` enum case 取代類別名稱：
+
+| Case             | PHP 型別 |
+| ---------------- | -------- |
+| `Native::string` | `string` |
+| `Native::int`    | `int`    |
+| `Native::float`  | `float`  |
+| `Native::bool`   | `bool`   |
 
 ```php
 use ReallifeKip\ImmutableBase\Attributes\ArrayOf;
 
 readonly class SignUpUsersDTO extends DataTransferObject
 {
+    // ImmutableBase 子類
     #[ArrayOf(User::class)]
     public array $users;
-    public int $userCount;
+
+    // 純量型別陣列
+    #[ArrayOf(Native::string)]
+    public array $tags;
+    #[ArrayOf(Native::int)]
+    public array $scores;
 }
 ```
 
@@ -637,7 +652,7 @@ vendor/bin/ib-cacher --clear
 
 ### `writer` - 文件產生器
 
-為專案所有 ImmutableBase 子類物件產生文件，可產生 Mermaid 類別圖及 Markdown 屬性表。
+為專案所有 ImmutableBase 子類物件產生文件，可產生 Mermaid 類別圖、Markdown 屬性表及 TypeScript 型別宣告。
 
 ```bash
 vendor/bin/ib-writer
@@ -720,7 +735,7 @@ vendor/bin/ib-writer
 ## 注意事項
 
 1. 所有子類屬性必須為 public；由於 ImmutableBase 為 readonly class，整條繼承鏈在 PHP 語言層級也必須是 readonly。
-2. 此體系子物件所有屬性型別禁止設為：`iterable`、`object`、非 ImmutableBase 子類或非 Enum 的類，如：`DateTime`、`Closure`。
+2. 此體系子物件所有屬性型別禁止設為：`null`、`iterable`、`object`、非 ImmutableBase 子類或非 Enum 的類，如：`DateTime`、`Closure`。
 3. Enum 屬性接受 case 名稱（`"HIGH"`）或 backed 值（`3`），解析後的屬性值始終為 Enum 實例。
 4. 支援 `mixed` 型別，但值不會被進行驗證。
 

bin/ib-writer

@@ -57,6 +57,7 @@ if (
             [
                 'mmd' => 'mermaid',
                 'md'  => 'markdown',
+                'ts'  => 'typescript',
             ],
         )
     ) &&

src/Attributes/ArrayOf.php

@@ -1,21 +1,32 @@
 <?php
 
+declare (strict_types = 1);
+
 namespace ReallifeKip\ImmutableBase\Attributes;
 
+use ReallifeKip\ImmutableBase\Enums\Native;
+
 /**
  * Declares that an array property contains typed elements of a specific
- * ImmutableBase subclass. The target class is passed as the first
- * constructor argument of the attribute.
+ * ImmutableBase subclass, or validated PHP scalar values via Native.
+ *
+ * Accepts either a class-string of an ImmutableBase subclass, or a
+ * Native enum case (Native::string, Native::int, Native::float, Native::bool)
+ * for primitive typed arrays.
  *
  * Must be applied to properties typed exactly as `array`. Union types
  * or non-array types will trigger InvalidArrayOfUsageException at scan time.
  *
  * @example #[ArrayOf(OrderItemDTO::class)] public array $items
+ * @example #[ArrayOf(Native::string)]      public array $tags
+ * @example #[ArrayOf(Native::int)]         public array $scores
  */
 #[\Attribute(\Attribute::TARGET_PROPERTY)]
 final class ArrayOf
 {
-    /** @param class-string $class */
+    /**
+     * @param class-string|Native $class FQCN of an ImmutableBase subclass, or a Native enum case for primitive typed arrays.
+     */
     private function __construct(
         public string $class
     ) {}

src/Attributes/Defaults.php

@@ -1,5 +1,7 @@
 <?php
 
+declare (strict_types = 1);
+
 namespace ReallifeKip\ImmutableBase\Attributes;
 
 /**

src/Attributes/Spec.php

@@ -1,5 +1,7 @@
 <?php
 
+declare (strict_types = 1);
+
 namespace ReallifeKip\ImmutableBase\Attributes;
 
 /**

src/Attributes/ValidateFromSelf.php

@@ -1,5 +1,7 @@
 <?php
 
+declare (strict_types = 1);
+
 namespace ReallifeKip\ImmutableBase\Attributes;
 
 /**

src/BasicTrait.php

@@ -25,9 +25,9 @@ trait BasicTrait
      * @param ReflectionClass|ReflectionProperty $target Reflection target to inspect.
      * @param class-string $name Fully-qualified attribute class name.
      * @param bool $getFirst Whether to return only the first argument.
-     * @return mixed|null
+     * @return mixed
      */
-    public static function getAttributeArgument(ReflectionClass | ReflectionProperty $target, string $name, bool $getFirst = true)
+    public static function getAttributeArgument(ReflectionClass | ReflectionProperty $target, string $name, bool $getFirst = true): mixed
     {
         if ($value = $target->getAttributes($name)) {
             $value = $value[0];

src/CLI/Cacher.php

@@ -1,5 +1,7 @@
 <?php
 
+declare (strict_types = 1);
+
 namespace ReallifeKip\ImmutableBase\CLI;
 
 use Composer\Autoload\ClassLoader;
@@ -132,7 +134,7 @@ private function indexDirectory(string $dir): void
      * its source. Resolves namespace and class name from T_NAMESPACE and
      * T_CLASS tokens respectively.
      *
-     * @param string $path Absolute file path.
+     * @param string $content Full PHP file content.
      * @return list<class-string>
      */
     private static function parseFullClassname(string $content): array
@@ -187,7 +189,7 @@ private static function parseFullClassname(string $content): array
      * @param ReflectionProperty[] $properties The name of the property being validated.
      * @return void
      */
-    private static function defaultValueValidate(string $classname, array $defaults, array $properties)
+    private static function defaultValueValidate(string $classname, array $defaults, array $properties): void
     {
         foreach ($properties as $property) {
             $name    = $property->name;