@wcstack/state 1.3.14 → 1.3.16

package/README.ja.md

@@ -1,7 +1,12 @@
 # @wcstack/state
 
-Web Components のための宣言的リアクティブ状態管理。  
-`<wcs-state>` カスタム要素と `data-wcs` 属性バインディング — ランタイム依存ゼロ。
+**もしHTMLにリアクティブなデータバインディングがあったら？**
+
+ブラウザが状態をネイティブに理解する未来を妄想してみる。データをインラインで宣言し、属性でDOMにバインドすれば、すべてが自動で同期する。仮想DOMもコンパイルも不要。ただのHTMLが、勝手にリアクティブになる。
+
+それが `<wcs-state>` と `data-wcs` の探求するもの。CDN一発、依存ゼロ、構文はHTML。
+
+CDNスクリプトはカスタム要素の定義を登録するだけ — ロード時にはそれ以外何も起きない。`<wcs-state>` 要素がDOMに接続されたとき、状態ソースを読み取り、兄弟要素の `data-wcs` バインディングを走査し、リアクティビティを構築する。すべての初期化は要素のライフサイクルが駆動する。あなたのコードではなく。
 
 ## 特徴
 
@@ -144,27 +149,33 @@ Web Components のための宣言的リアクティブ状態管理。
 
 ## 状態の更新
 
-状態の変更は**プロパティへの代入**（Proxy の `set` トラップ）で検知されます。リアクティブな DOM 更新をトリガーするには、状態プロパティに値を**代入**する必要があります。
+`@wcstack/state` では、すべての状態は**パス**を持ちます — `count`、`user.name`、`items` のように。状態をリアクティブに更新するには、**パスに代入**します:
+
+```javascript
+this.count = 10;               // パス "count"
+this["user.name"] = "Bob";     // パス "user.name"
+```
+
+ルールはひとつ: **パスに代入すれば、DOMは自動的に更新される。**
 
-### プリミティブ・オブジェクトプロパティ
+### なぜ `this.user.name = "Bob"` では動かないのか
 
-代入は**ドットパス記法**（ブラケット構文）を使用する必要があります。リアクティブ Proxy はトップレベルの `set` トラップのみを捕捉するため、通常のネストされたプロパティアクセスでは変更が検知されません：
+`this.user.name` は、まず `this.user` で `user` オブジェクトを読み取り（パスの読み取り）、そのプレーンオブジェクトの `.name` に設定します — これはパスへの代入ではないため、変更は検知されません:
 
 ```javascript
-// ✅ パス代入 — 変更が検知される
-this.count = 10;
+// ✅ パスへの代入 — 変更が検知される
 this["user.name"] = "Bob";
 
-// ❌ 直接のネストアクセス — 変更が検知されない
-this.user.name = "Bob";     // Proxy の set トラップをバイパスする
+// ❌ パスへの代入ではない — 変更は検知されない
+this.user.name = "Bob";
 ```
 
 ### 配列
 
-配列の破壊的メソッド（`push`, `splice`, `sort`, `reverse` 等）はその場で配列を変更するだけで**プロパティ代入を発生させない**ため、リアクティブシステムは変更を検知しません。代わりに、新しい配列を返す**非破壊的メソッド**を使用し、結果を代入してください：
+同じルールです: パスに新しい配列を代入します。破壊的メソッド（`push`, `splice`, `sort` 等）はパスへの代入なしに配列をその場で変更するため、非破壊的な代替メソッドを使用します:
 
 ```javascript
-// ✅ 非破壊的 + 代入 — 変更が検知される
+// ✅ 新しい配列をパスに代入 — 変更が検知される
 this.items = this.items.concat({ id: 4, text: "New" });
 this.items = this.items.toSpliced(index, 1);
 this.items = this.items.filter(item => !item.done);
@@ -172,7 +183,7 @@ this.items = this.items.toSorted((a, b) => a.id - b.id);
 this.items = this.items.toReversed();
 this.items = this.items.with(index, newValue);
 
-// ❌ 破壊的 — 代入なし、変更は検知されない
+// ❌ その場での変更 — パスへの代入なし、変更は検知されない
 this.items.push({ id: 4, text: "New" });
 this.items.splice(index, 1);
 this.items.sort((a, b) => a.id - b.id);
@@ -300,6 +311,8 @@ property[#modifier]: path[@state][|filter[|filter(args)...]]
 </template>
 ```
 
+`for:` ディレクティブは**値ベースの差分アルゴリズム**を使用します。配列の各要素の値そのものが識別キーとして機能するため、React の `key` や Vue の `:key` のような明示的なキー属性は不要です。配列が再代入されると、差分アルゴリズムが新旧の要素を値で照合し、変更のない要素の DOM ノードを再利用しつつ、追加・削除・並び替えを効率的に処理します。
+
 #### ドット省略記法
 
 `for` ループ内では、`.` で始まるパスがループの配列パスを基準に展開されます：
@@ -543,7 +556,7 @@ export default {
 };
 ```
 
-3階層のネスト、5つの仮想プロパティ — すべてが1つのフラットなオブジェクト内に並んで定義されています。各レベルは任意の深さの値を参照でき、`$getAll` による集約は下位から上位へ自然に流れます。コンポーネントベースのフレームワーク（React、Vue）で同じことを実現するには、各ネストレベルに個別のコンポーネントを作成し、算出値をツリーの上位に渡すための props バケツリレーや状態管理が必要になります。
+3階層のネスト、5つの仮想プロパティ — すべてが1つのフラットなオブジェクト内に並んで定義されています。各レベルは任意の深さの値を参照でき、`$getAll` による集約は下位から上位へ自然に流れます。コンポーネントベースのフレームワークでは、一般的に各ネストレベルに個別のコンポーネントを作成し、算出値をツリーの上位に渡す方法が採られます。パス getter は、すべての定義を1箇所にまとめるという異なるトレードオフを提供します。
 
 ### getter の戻り値のサブプロパティへのアクセス
 
@@ -827,6 +840,15 @@ export default {
 
 `@wcstack/state` は Shadow DOM または Light DOM を使用したカスタム要素との双方向状態バインディングに対応しています。
 
+多くのフレームワークでは、コンポーネント間の状態共有に props バケツリレー、Context Provider、外部ストア（Redux, Pinia）といったパターンが用いられます。`@wcstack/state` は異なるアプローチを採ります。親子コンポーネントは**パスの契約**で接続されます。親は `data-wcs` で外部の状態パスを子コンポーネントのプロパティにバインドし、子は自身の状態を通常どおり読み書きするだけです：
+
+1. 子コンポーネントは自身の状態プロキシを通じて親の状態を参照・更新します — props もイベントも親の存在を意識する必要もありません。
+2. 親の状態が変更されると、Proxy の `set` トラップが影響するパスを参照している子のバインディングへ自動的に通知します。
+3. 結合点は**パス名のみ**であるため、双方とも疎結合を保ち、独立してテスト可能です。
+4. コストはパス解決（初回アクセス後はキャッシュにより O(1)）と依存グラフを通じた変更伝播のみです。
+
+これは、コンポーネントレベルの抽象化ではなくパス解決に基づく、コンポーネント間状態管理への軽量なアプローチです。
+
 ### コンポーネント定義（Shadow DOM）
 
 ```javascript
@@ -982,6 +1004,8 @@ customElements.define("my-component", MyComponent);
 | `$disconnectedCallback` | 要素が DOM から削除された時 | 不可（同期のみ） |
 | `$updatedCallback(paths, indexesListByPath)` | 状態変更が適用された後に呼び出し | 戻り値は未使用（待機されない） |
 
+リアクティブ Proxy は全てのプロパティ代入を変更として検知するため、標準の `async/await` とプロパティへの直接代入だけで非同期処理は完結します。ローディングフラグ、取得データ、エラーメッセージの更新は全てプロパティ代入であり、非同期状態管理のための追加の抽象化を必要としません。
+
 - フック内の `this` は読み書き可能な状態プロキシです
 - `$connectedCallback` は要素が接続される**たびに**呼ばれます（削除後の再接続を含む）。再確立が必要なセットアップ処理に適しています
 - `$disconnectedCallback` は同期的に呼び出されます — タイマーのクリア、イベントリスナーの削除、リソースの解放などのクリーンアップに使用します

package/README.md

@@ -1,7 +1,12 @@
 # @wcstack/state
 
-Declarative reactive state management for Web Components.  
-`<wcs-state>` custom element and `data-wcs` attribute binding — zero runtime dependencies.
+**What if HTML had reactive data binding?**
+
+Imagine a future where the browser natively understands state — you declare data inline, bind it to the DOM with attributes, and everything stays in sync. No virtual DOM, no compilation, no framework. Just HTML that reacts.
+
+That's what `<wcs-state>` and `data-wcs` explore. One CDN import, zero dependencies, pure HTML syntax.
+
+The CDN script only registers the custom element definition — nothing else happens at load time. When a `<wcs-state>` element connects to the DOM, it reads its state source, scans sibling elements for `data-wcs` bindings, and wires up reactivity. All initialization is driven by the element's lifecycle, not by your code.
 
 ## Features
 
@@ -144,27 +149,33 @@ Default name is `"default"` (no `@` needed).
 
 ## Updating State
 
-State changes are detected through **property assignment** (the Proxy `set` trap). To trigger reactive DOM updates, a value must be **assigned** to a state property.
+In `@wcstack/state`, every piece of state has a **path** — like `count`, `user.name`, or `items`. To update state reactively, **assign to the path**:
+
+```javascript
+this.count = 10;               // path "count"
+this["user.name"] = "Bob";     // path "user.name"
+```
+
+That's the one rule: **assign to the path, and the DOM updates automatically.**
 
-### Primitive and Object Properties
+### Why `this.user.name = "Bob"` Doesn't Work
 
-Assignment must use **dot-path notation** (bracket syntax). The reactive proxy intercepts only top-level `set` traps, so standard nested property access bypasses change detection:
+`this.user.name` first reads the `user` object via `this.user` (a path read), then sets `.name` on that plain object — this is not a path assignment, so the change is not detected:
 
 ```javascript
 // ✅ Path assignment — change detected
-this.count = 10;
 this["user.name"] = "Bob";
 
-// ❌ Direct nested access — change NOT detected
-this.user.name = "Bob";     // bypasses the Proxy set trap
+// ❌ Not a path assignment — change NOT detected
+this.user.name = "Bob";
 ```
 
 ### Arrays
 
-Array mutating methods (`push`, `splice`, `sort`, `reverse`, …) modify the array in place **without triggering a property assignment**, so the reactive system does not detect the change. Instead, use **non-destructive** methods that return a new array and assign the result:
+The same rule applies: assign a new array to the path. Mutating methods (`push`, `splice`, `sort`, ...) modify the array in place without path assignment, so use non-destructive alternatives:
 
 ```javascript
-// ✅ Non-destructive + assignment — change detected
+// ✅ New array assigned to path — change detected
 this.items = this.items.concat({ id: 4, text: "New" });
 this.items = this.items.toSpliced(index, 1);
 this.items = this.items.filter(item => !item.done);
@@ -172,7 +183,7 @@ this.items = this.items.toSorted((a, b) => a.id - b.id);
 this.items = this.items.toReversed();
 this.items = this.items.with(index, newValue);
 
-// ❌ Mutating — no assignment, change NOT detected
+// ❌ In-place mutation — no path assignment, change NOT detected
 this.items.push({ id: 4, text: "New" });
 this.items.splice(index, 1);
 this.items.sort((a, b) => a.id - b.id);
@@ -300,6 +311,8 @@ Structural directives use `<template>` elements:
 </template>
 ```
 
+The `for:` directive uses a **value-based diff algorithm** — each array element's value itself serves as the identity key. There is no need for an explicit `key` attribute (like React's `key` or Vue's `:key`). When the array is reassigned, the differ matches old and new elements by value, reusing existing DOM nodes for unchanged items and efficiently adding, removing, or reordering the rest.
+
 #### Dot Shorthand
 
 Inside a `for` loop, paths starting with `.` are expanded relative to the loop's array path:
@@ -543,7 +556,7 @@ export default {
 };
 ```
 
-Three levels of nesting, five virtual properties — all defined side by side in a single flat object. Each level can reference values from any depth, and aggregation flows naturally from bottom to top via `$getAll`. In component-based frameworks (React, Vue), achieving the same requires creating a separate component for each nesting level, with props drilling or state management to pass computed values up the tree.
+Three levels of nesting, five virtual properties — all defined side by side in a single flat object. Each level can reference values from any depth, and aggregation flows naturally from bottom to top via `$getAll`. In component-based frameworks, the typical approach is to create a separate component for each nesting level and pass computed values through the tree. Path getters offer a different trade-off by keeping all definitions in one place.
 
 ### Accessing Sub-Properties of Getter Results
 
@@ -827,6 +840,15 @@ Filters can be chained with `|`:
 
 `@wcstack/state` supports bidirectional state binding with custom elements using Shadow DOM or Light DOM.
 
+Many frameworks use patterns like prop drilling, context providers, or external stores (Redux, Pinia) to share state across components. `@wcstack/state` takes a different approach: parent and child components are connected through **path contracts** — the parent binds an outer state path to an inner component property via `data-wcs`, and the child simply reads and writes its own state as usual:
+
+1. The child references and updates the parent's state through its own state proxy — no props, no events, no awareness of the parent.
+2. When the parent's state changes, the Proxy `set` trap automatically notifies any child bindings that reference the affected path.
+3. Because the only coupling is the **path name**, both sides remain loosely coupled and independently testable.
+4. The cost is path resolution (cached at O(1) after first access) plus change propagation through the dependency graph.
+
+This provides a lightweight approach to cross-component state management based on path resolution rather than component-level abstractions.
+
 ### Component Definition (Shadow DOM)
 
 ```javascript
@@ -982,6 +1004,8 @@ State objects can define `$connectedCallback`, `$disconnectedCallback`, and `$up
 | `$disconnectedCallback` | When the element is removed from the DOM | No (sync only) |
 | `$updatedCallback(paths, indexesListByPath)` | After state updates are applied | Return value is ignored (not awaited) |
 
+Since the reactive proxy detects every property assignment as a change, standard `async/await` with direct property updates is sufficient for asynchronous operations — loading flags, fetched data, and error messages are all just property assignments, without requiring additional abstractions for async state management.
+
 - `this` inside hooks is the state proxy with full read/write access
 - `$connectedCallback` is called **every time** the element is connected (including re-insertion after removal), making it suitable for setup that should be re-established
 - `$disconnectedCallback` is called synchronously — use it for cleanup such as clearing timers, removing event listeners, or releasing resources

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wcstack/state",
-  "version": "1.3.14",
+  "version": "1.3.16",
   "description": "Reactive state management with declarative data binding for Web Components. Zero dependencies, buildless.",
   "type": "module",
   "main": "./dist/index.esm.js",
@@ -10,14 +10,15 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.esm.js"
-    }
+    },
+    "./auto": "./dist/auto.min.js"
   },
   "files": [
     "dist"
   ],
   "scripts": {
-    "clean": "rimraf dist",
-    "build": "rimraf dist && tsc && rollup -c",
+    "clean": "rimraf dist .tsc-out",
+    "build": "rimraf dist .tsc-out && tsc && rollup -c",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",

package/dist/address/AbsolutePathInfo.d.ts

@@ -1,4 +0,0 @@
-import { IStateElement } from "../components/types";
-import { IAbsolutePathInfo, IPathInfo } from "./types";
-export declare function getAbsolutePathInfo(stateElement: IStateElement, pathInfo: IPathInfo): IAbsolutePathInfo;
-//# sourceMappingURL=AbsolutePathInfo.d.ts.map

package/dist/address/AbsolutePathInfo.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"AbsolutePathInfo.d.ts","sourceRoot":"","sources":["../../src/address/AbsolutePathInfo.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAIvD,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,SAAS,GAAG,iBAAiB,CAYvG"}

package/dist/address/AbsolutePathInfo.js

@@ -1,33 +0,0 @@
-const _cache = new WeakMap();
-export function getAbsolutePathInfo(stateElement, pathInfo) {
-    if (_cache.has(stateElement)) {
-        const pathMap = _cache.get(stateElement);
-        if (pathMap.has(pathInfo)) {
-            return pathMap.get(pathInfo);
-        }
-    }
-    else {
-        _cache.set(stateElement, new WeakMap());
-    }
-    const absolutePathInfo = Object.freeze(new AbsolutePathInfo(stateElement, pathInfo));
-    _cache.get(stateElement).set(pathInfo, absolutePathInfo);
-    return absolutePathInfo;
-}
-class AbsolutePathInfo {
-    pathInfo;
-    stateName;
-    stateElement;
-    parentAbsolutePathInfo;
-    constructor(stateElement, pathInfo) {
-        this.pathInfo = pathInfo;
-        this.stateName = stateElement.name;
-        this.stateElement = stateElement;
-        if (pathInfo.parentPathInfo === null) {
-            this.parentAbsolutePathInfo = null;
-        }
-        else {
-            this.parentAbsolutePathInfo = getAbsolutePathInfo(stateElement, pathInfo.parentPathInfo);
-        }
-    }
-}
-//# sourceMappingURL=AbsolutePathInfo.js.map

package/dist/address/AbsolutePathInfo.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"AbsolutePathInfo.js","sourceRoot":"","sources":["../../src/address/AbsolutePathInfo.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,GAAkE,IAAI,OAAO,EAAE,CAAC;AAE5F,MAAM,UAAU,mBAAmB,CAAC,YAA2B,EAAE,QAAmB;IAClF,IAAI,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,YAAY,CAAE,CAAC;QAC1C,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1B,OAAO,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAE,CAAC;QAChC,CAAC;IACH,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,OAAO,EAAE,CAAC,CAAC;IAC1C,CAAC;IACD,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,gBAAgB,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC;IACrF,MAAM,CAAC,GAAG,CAAC,YAAY,CAAE,CAAC,GAAG,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC;IAC1D,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED,MAAM,gBAAgB;IACX,QAAQ,CAAY;IACpB,SAAS,CAAS;IAClB,YAAY,CAAgB;IAC5B,sBAAsB,CAA2B;IAC1D,YAAY,YAA2B,EAAE,QAAmB;QAC1D,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,SAAS,GAAG,YAAY,CAAC,IAAI,CAAC;QACnC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,QAAQ,CAAC,cAAc,KAAK,IAAI,EAAE,CAAC;YACrC,IAAI,CAAC,sBAAsB,GAAG,IAAI,CAAC;QACrC,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,sBAAsB,GAAG,mBAAmB,CAAC,YAAY,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;QAC3F,CAAC;IACH,CAAC;CACF"}

package/dist/address/AbsoluteStateAddress.d.ts

@@ -1,4 +0,0 @@
-import { IListIndex } from "../list/types";
-import { IAbsolutePathInfo, IAbsoluteStateAddress } from "./types";
-export declare function createAbsoluteStateAddress(absolutePathInfo: IAbsolutePathInfo, listIndex: IListIndex | null): IAbsoluteStateAddress;
-//# sourceMappingURL=AbsoluteStateAddress.d.ts.map

package/dist/address/AbsoluteStateAddress.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"AbsoluteStateAddress.d.ts","sourceRoot":"","sources":["../../src/address/AbsoluteStateAddress.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAqCnE,wBAAgB,0BAA0B,CAAC,gBAAgB,EAAE,iBAAiB,EAAE,SAAS,EAAE,UAAU,GAAG,IAAI,GAAG,qBAAqB,CAuBnI"}

package/dist/address/AbsoluteStateAddress.js

@@ -1,56 +0,0 @@
-import { WILDCARD } from "../define";
-const _cache = new WeakMap();
-const _cacheNullListIndex = new WeakMap();
-class AbsoluteStateAddress {
-    absolutePathInfo;
-    listIndex;
-    _parentAbsoluteAddress;
-    constructor(absolutePathInfo, listIndex) {
-        this.absolutePathInfo = absolutePathInfo;
-        this.listIndex = listIndex;
-    }
-    get parentAbsoluteAddress() {
-        if (typeof this._parentAbsoluteAddress !== 'undefined') {
-            return this._parentAbsoluteAddress;
-        }
-        const parentAbsolutePathInfo = this.absolutePathInfo.parentAbsolutePathInfo;
-        if (parentAbsolutePathInfo === null) {
-            return null;
-        }
-        const lastSegment = this.absolutePathInfo.pathInfo.segments[this.absolutePathInfo.pathInfo.segments.length - 1];
-        let parentListIndex = null;
-        if (lastSegment === WILDCARD) {
-            parentListIndex = this.listIndex?.parentListIndex ?? null;
-        }
-        else {
-            parentListIndex = this.listIndex;
-        }
-        return this._parentAbsoluteAddress = createAbsoluteStateAddress(parentAbsolutePathInfo, parentListIndex);
-    }
-}
-export function createAbsoluteStateAddress(absolutePathInfo, listIndex) {
-    if (listIndex === null) {
-        let cached = _cacheNullListIndex.get(absolutePathInfo);
-        if (typeof cached !== "undefined") {
-            return cached;
-        }
-        cached = new AbsoluteStateAddress(absolutePathInfo, null);
-        _cacheNullListIndex.set(absolutePathInfo, cached);
-        return cached;
-    }
-    else {
-        let cacheByAbsolutePathInfo = _cache.get(listIndex);
-        if (typeof cacheByAbsolutePathInfo === "undefined") {
-            cacheByAbsolutePathInfo = new WeakMap();
-            _cache.set(listIndex, cacheByAbsolutePathInfo);
-        }
-        let cached = cacheByAbsolutePathInfo.get(absolutePathInfo);
-        if (typeof cached !== "undefined") {
-            return cached;
-        }
-        cached = new AbsoluteStateAddress(absolutePathInfo, listIndex);
-        cacheByAbsolutePathInfo.set(absolutePathInfo, cached);
-        return cached;
-    }
-}
-//# sourceMappingURL=AbsoluteStateAddress.js.map

package/dist/address/AbsoluteStateAddress.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"AbsoluteStateAddress.js","sourceRoot":"","sources":["../../src/address/AbsoluteStateAddress.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAIrC,MAAM,MAAM,GAA2E,IAAI,OAAO,EAAE,CAAC;AACrG,MAAM,mBAAmB,GAAsD,IAAI,OAAO,EAAE,CAAC;AAE7F,MAAM,oBAAoB;IACf,gBAAgB,CAAoB;IACpC,SAAS,CAAoB;IAC9B,sBAAsB,CAA2C;IAEzE,YAAY,gBAAmC,EAAE,SAA4B;QAC3E,IAAI,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;QACzC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED,IAAI,qBAAqB;QACvB,IAAI,OAAO,IAAI,CAAC,sBAAsB,KAAK,WAAW,EAAE,CAAC;YACvD,OAAO,IAAI,CAAC,sBAAsB,CAAC;QACrC,CAAC;QACD,MAAM,sBAAsB,GAAG,IAAI,CAAC,gBAAgB,CAAC,sBAAsB,CAAC;QAC5E,IAAI,sBAAsB,KAAK,IAAI,EAAE,CAAC;YACpC,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,WAAW,GAAG,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAChH,IAAI,eAAe,GAAsB,IAAI,CAAC;QAC9C,IAAI,WAAW,KAAK,QAAQ,EAAE,CAAC;YAC7B,eAAe,GAAG,IAAI,CAAC,SAAS,EAAE,eAAe,IAAI,IAAI,CAAC;QAC5D,CAAC;aAAM,CAAC;YACN,eAAe,GAAG,IAAI,CAAC,SAAS,CAAC;QACnC,CAAC;QACD,OAAO,IAAI,CAAC,sBAAsB,GAAG,0BAA0B,CAC7D,sBAAsB,EACtB,eAAe,CAChB,CAAC;IACJ,CAAC;CACF;AAED,MAAM,UAAU,0BAA0B,CAAC,gBAAmC,EAAE,SAA4B;IAC1G,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACvB,IAAI,MAAM,GAAG,mBAAmB,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;QACvD,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;YAClC,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,MAAM,GAAG,IAAI,oBAAoB,CAAC,gBAAgB,EAAE,IAAI,CAAC,CAAC;QAC1D,mBAAmB,CAAC,GAAG,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;QAClD,OAAO,MAAM,CAAC;IAChB,CAAC;SAAM,CAAC;QACN,IAAI,uBAAuB,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACpD,IAAI,OAAO,uBAAuB,KAAK,WAAW,EAAE,CAAC;YACnD,uBAAuB,GAAG,IAAI,OAAO,EAA4C,CAAC;YAClF,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,uBAAuB,CAAC,CAAC;QACjD,CAAC;QACD,IAAI,MAAM,GAAG,uBAAuB,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;QAC3D,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;YAClC,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,MAAM,GAAG,IAAI,oBAAoB,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAC;QAC/D,uBAAuB,CAAC,GAAG,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;QACtD,OAAO,MAAM,CAAC;IAChB,CAAC;AACH,CAAC"}

package/dist/address/PathInfo.d.ts

@@ -1,3 +0,0 @@
-import { IPathInfo } from "./types.js";
-export declare function getPathInfo(path: string): IPathInfo;
-//# sourceMappingURL=PathInfo.d.ts.map

package/dist/address/PathInfo.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"PathInfo.d.ts","sourceRoot":"","sources":["../../src/address/PathInfo.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAKvC,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAQnD"}

package/dist/address/PathInfo.js

@@ -1,104 +0,0 @@
-import { WILDCARD } from "../define.js";
-const _cache = new Map();
-let id = 0;
-export function getPathInfo(path) {
-    let pathInfo = _cache.get(path);
-    if (typeof pathInfo !== "undefined") {
-        return pathInfo;
-    }
-    pathInfo = Object.freeze(new PathInfo(path));
-    _cache.set(path, pathInfo);
-    return pathInfo;
-}
-class PathInfo {
-    id = ++id;
-    path;
-    segments;
-    lastSegment;
-    cumulativePaths;
-    cumulativePathSet;
-    cumulativePathInfos;
-    cumulativePathInfoSet;
-    parentPath;
-    wildcardPaths;
-    wildcardPathSet;
-    indexByWildcardPath;
-    wildcardPathInfos;
-    wildcardPathInfoSet;
-    wildcardParentPaths;
-    wildcardParentPathSet;
-    wildcardParentPathInfos;
-    wildcardParentPathInfoSet;
-    wildcardPositions;
-    lastWildcardPath;
-    lastWildcardInfo;
-    wildcardCount;
-    parentPathInfo;
-    constructor(path) {
-        // Helper to get or create StructuredPathInfo instances, avoiding redundant creation for self-reference
-        const getPattern = (_path) => {
-            return (path === _path) ? this : getPathInfo(_path);
-        };
-        // Split the pattern into individual path segments (e.g., "items.*.name" → ["items", "*", "name"])
-        const segments = path.split(".");
-        // Arrays to track all cumulative paths from root to each segment
-        const cumulativePaths = [];
-        const cumulativePathInfos = [];
-        // Arrays to track wildcard-specific information
-        const wildcardPaths = [];
-        const indexByWildcardPath = {}; // Maps wildcard path to its index position
-        const wildcardPathInfos = [];
-        const wildcardParentPaths = []; // Paths of parent segments for each wildcard
-        const wildcardParentPathInfos = [];
-        const wildcardPositions = [];
-        let currentPatternPath = "", prevPatternPath = "";
-        let wildcardCount = 0;
-        // Iterate through each segment to build cumulative paths and identify wildcards
-        for (let i = 0; i < segments.length; i++) {
-            currentPatternPath += segments[i];
-            // If this segment is a wildcard, track it with all wildcard-specific metadata
-            if (segments[i] === WILDCARD) {
-                wildcardPaths.push(currentPatternPath);
-                indexByWildcardPath[currentPatternPath] = wildcardCount; // Store wildcard's ordinal position
-                wildcardPathInfos.push(getPattern(currentPatternPath));
-                wildcardParentPaths.push(prevPatternPath); // Parent path is the previous cumulative path
-                wildcardParentPathInfos.push(getPattern(prevPatternPath));
-                wildcardPositions.push(i);
-                wildcardCount++;
-            }
-            // Track all cumulative paths for hierarchical navigation (e.g., "items", "items.*", "items.*.name")
-            cumulativePaths.push(currentPatternPath);
-            cumulativePathInfos.push(getPattern(currentPatternPath));
-            // Save current path as previous for next iteration, then add separator
-            prevPatternPath = currentPatternPath;
-            currentPatternPath += ".";
-        }
-        // Determine the deepest (last) wildcard path and the parent path of the entire pattern
-        const lastWildcardPath = wildcardPaths.length > 0 ? wildcardPaths[wildcardPaths.length - 1] : null;
-        const parentPath = cumulativePaths.length > 1 ? cumulativePaths[cumulativePaths.length - 2] : null;
-        // Assign all analyzed data to readonly properties
-        this.path = path;
-        this.segments = segments;
-        this.lastSegment = segments[segments.length - 1];
-        this.cumulativePaths = cumulativePaths;
-        this.cumulativePathSet = new Set(cumulativePaths); // Set for fast lookup
-        this.cumulativePathInfos = cumulativePathInfos;
-        this.cumulativePathInfoSet = new Set(cumulativePathInfos);
-        this.wildcardPaths = wildcardPaths;
-        this.wildcardPathSet = new Set(wildcardPaths);
-        this.indexByWildcardPath = indexByWildcardPath;
-        this.wildcardPathInfos = wildcardPathInfos;
-        this.wildcardPathInfoSet = new Set(wildcardPathInfos);
-        this.wildcardParentPaths = wildcardParentPaths;
-        this.wildcardParentPathSet = new Set(wildcardParentPaths);
-        this.wildcardParentPathInfos = wildcardParentPathInfos;
-        this.wildcardParentPathInfoSet = new Set(wildcardParentPathInfos);
-        this.wildcardPositions = wildcardPositions;
-        this.lastWildcardPath = lastWildcardPath;
-        this.lastWildcardInfo = lastWildcardPath ? getPattern(lastWildcardPath) : null;
-        this.parentPath = parentPath;
-        this.parentPathInfo = parentPath ? getPattern(parentPath) : null;
-        this.wildcardCount = wildcardCount;
-    }
-}
-//# sourceMappingURL=PathInfo.js.map

package/dist/address/PathInfo.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"PathInfo.js","sourceRoot":"","sources":["../../src/address/PathInfo.ts"],"names":[],"mappings":"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"}

package/dist/address/ResolvedAddress.d.ts

@@ -1,31 +0,0 @@
-/**
- * getResolvedPathInfo.ts
- *
- * Utility for parsing and generating detailed path information (IResolvedPathInfo)
- * from State property names (path strings), including wildcard and index information.
- *
- * Main responsibilities:
- * - Breaks down property names to determine presence and type of wildcards and indexes
- * - Automatically determines wildcard type: context/all/partial/none
- * - Caches by path for reusability and performance
- * - Retrieves structured path information via getStructuredPathInfo
- *
- * Design points:
- * - Caches using Map to handle reserved words like "constructor" and "toString"
- * - Flexibly determines wildcards (*) and numeric indexes, storing them in wildcardIndexes
- * - context type indicates unresolved indexes, all type indicates all resolved indexes, partial type indicates mixed
- * - ResolvedPathInfo class centralizes path parsing and information management
- */
-import { IResolvedAddress } from './types';
-/**
- * Retrieves or creates resolved path information for a property path.
- *
- * This function caches resolved path information for performance.
- * On first access, it parses the path and creates a ResolvedPathInfo instance.
- * Subsequent accesses return the cached result.
- *
- * @param name - Property path string (e.g., "items.*.name", "data.0.value")
- * @returns Resolved path information containing segments, wildcards, and type classification
- */
-export declare function getResolvedAddress(name: string): IResolvedAddress;
-//# sourceMappingURL=ResolvedAddress.d.ts.map

package/dist/address/ResolvedAddress.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ResolvedAddress.d.ts","sourceRoot":"","sources":["../../src/address/ResolvedAddress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,gBAAgB,EAAgB,MAAM,SAAS,CAAC;AAkGzD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAC,MAAM,GAAE,gBAAgB,CAI/D"}

package/dist/address/ResolvedAddress.js

@@ -1,110 +0,0 @@
-import { getPathInfo } from './PathInfo';
-/**
- * Cache for resolved path information.
- * Uses Map to safely handle property names including reserved words like "constructor" and "toString".
- */
-const _cache = new Map();
-/**
- * Class that parses and stores resolved path information.
- *
- * Analyzes property path strings to extract:
- * - Path segments and their hierarchy
- * - Wildcard locations and types
- * - Numeric indexes vs unresolved wildcards
- * - Wildcard type classification (none/context/all/partial)
- */
-class ResolvedAddress {
-    path;
-    segments;
-    paths;
-    wildcardCount;
-    wildcardType;
-    wildcardIndexes;
-    pathInfo;
-    /**
-     * Constructs resolved path information from a property path string.
-     *
-     * Parses the path to identify wildcards (*) and numeric indexes,
-     * classifies the wildcard type, and generates structured path information.
-     *
-     * @param name - Property path string (e.g., "items.*.name" or "data.0.value")
-     */
-    constructor(path) {
-        // Split path into individual segments
-        const segments = path.split(".");
-        const tmpPatternSegments = segments.slice();
-        const paths = [];
-        let incompleteCount = 0; // Count of unresolved wildcards (*)
-        let completeCount = 0; // Count of resolved wildcards (numeric indexes)
-        let lastPath = "";
-        let wildcardCount = 0;
-        let wildcardType = "none";
-        const wildcardIndexes = [];
-        // Process each segment to identify wildcards and indexes
-        for (let i = 0; i < segments.length; i++) {
-            const segment = segments[i];
-            if (segment === "*") {
-                // Unresolved wildcard
-                tmpPatternSegments[i] = "*";
-                wildcardIndexes.push(null);
-                incompleteCount++;
-                wildcardCount++;
-            }
-            else {
-                const number = Number(segment);
-                if (!Number.isNaN(number)) {
-                    // Numeric index - treat as resolved wildcard
-                    tmpPatternSegments[i] = "*";
-                    wildcardIndexes.push(number);
-                    completeCount++;
-                    wildcardCount++;
-                }
-            }
-            // Build cumulative path array
-            lastPath += segment;
-            paths.push(lastPath);
-            lastPath += (i < segment.length - 1 ? "." : "");
-        }
-        // Generate pattern string with wildcards normalized
-        const structuredPath = tmpPatternSegments.join(".");
-        const pathInfo = getPathInfo(structuredPath);
-        // Classify wildcard type based on resolved vs unresolved counts
-        if (incompleteCount > 0 || completeCount > 0) {
-            if (incompleteCount === wildcardCount) {
-                // All wildcards are unresolved - need context to resolve
-                wildcardType = "context";
-            }
-            else if (completeCount === wildcardCount) {
-                // All wildcards are resolved with numeric indexes
-                wildcardType = "all";
-            }
-            else {
-                // Mix of resolved and unresolved wildcards
-                wildcardType = "partial";
-            }
-        }
-        this.path = path;
-        this.segments = segments;
-        this.paths = paths;
-        this.wildcardCount = wildcardCount;
-        this.wildcardType = wildcardType;
-        this.wildcardIndexes = wildcardIndexes;
-        this.pathInfo = pathInfo;
-    }
-}
-/**
- * Retrieves or creates resolved path information for a property path.
- *
- * This function caches resolved path information for performance.
- * On first access, it parses the path and creates a ResolvedPathInfo instance.
- * Subsequent accesses return the cached result.
- *
- * @param name - Property path string (e.g., "items.*.name", "data.0.value")
- * @returns Resolved path information containing segments, wildcards, and type classification
- */
-export function getResolvedAddress(name) {
-    let nameInfo;
-    // Return cached value or create, cache, and return new instance
-    return _cache.get(name) ?? (_cache.set(name, nameInfo = new ResolvedAddress(name)), nameInfo);
-}
-//# sourceMappingURL=ResolvedAddress.js.map