init

enriched-qwen3-coder-next/DataPRO/DataPRO.Core/Settings.md

@@ -0,0 +1,205 @@
+---
+source_files:
+  - DataPRO/DataPRO.Core/Settings/SettingsChangedEventArgs.cs
+  - DataPRO/DataPRO.Core/Settings/SettingsCollection.cs
+generated_at: "2026-04-16T04:27:33.942396+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "d5502ead5db3d623"
+---
+
+# `SettingsCollection<TKey, TItem>` Module Documentation
+
+---
+
+## 1. Purpose
+
+The `SettingsCollection<TKey, TItem>` class provides a dictionary-based collection that notifies subscribers of changes (add, remove, modify, clear) via the `CollectionItemPropertyChanged` event. It extends `IDictionary<TKey, TItem>` to offer standard dictionary operations while adding reactive behavior for UI binding or state synchronization scenarios. This module exists to decouple state mutation from side-effect logic (e.g., persistence, UI updates) by enabling consumers to subscribe to change events rather than manually tracking mutations.
+
+---
+
+## 2. Public Interface
+
+### `SettingsCollection<TKey, TItem> : IDictionary<TKey, TItem>`
+
+#### Event
+
+- **`CollectionItemPropertyChanged`**  
+  `event EventHandler<SettingsChangedEventArgs<TKey, TItem>>`  
+  Fired whenever an item is added, removed, modified, or the collection is cleared.
+
+#### Properties (from `IDictionary<TKey, TItem>`)
+
+- **`this[TKey key]`**  
+  `TItem this[TKey key] { get; set; }`  
+  Gets or sets the value for the specified `key`. Setting a value fires a `Modified` event (note: *incorrectly* fires `Add` per implementation—see *Gotchas*).
+
+- **`Keys`**  
+  `ICollection<TKey> Keys { get; }`  
+  Returns the collection of keys.
+
+- **`Values`**  
+  `ICollection<TItem> Values { get; }`  
+  Returns the collection of values.
+
+- **`Count`**  
+  `int Count { get; }`  
+  Returns the number of key-value pairs.
+
+- **`IsReadOnly`**  
+  `bool IsReadOnly { get; }`  
+  Always `false`.
+
+#### Methods (from `IDictionary<TKey, TItem>`)
+
+- **`Add(TKey key, TItem value)`**  
+  Adds a key-value pair. Fires `CollectionItemPropertyChanged` with `ChangeSettingType.Add`.
+
+- **`Add(KeyValuePair<TKey, TItem> item)`**  
+  Adds a key-value pair. Fires `CollectionItemPropertyChanged` with `ChangeSettingType.Add`.
+
+- **`Remove(TKey key)`**  
+  Removes the entry with the specified `key`. Returns `true` if removed. Fires `CollectionItemPropertyChanged` with `ChangeSettingType.Remove`.
+
+- **`Remove(KeyValuePair<TKey, TItem> item)`**  
+  Removes the entry matching the key of `item`. Returns `true` if removed. Fires `CollectionItemPropertyChanged` with `ChangeSettingType.Remove`.
+
+- **`Clear()`**  
+  Removes all entries. Fires `CollectionItemPropertyChanged` with `ChangeSettingType.ClearAll`.
+
+- **`ContainsKey(TKey key)`**  
+  `bool ContainsKey(TKey key)`  
+  Returns `true` if `key` exists.
+
+- **`Contains(KeyValuePair<TKey, TItem> item)`**  
+  `bool Contains(KeyValuePair<TKey, TItem> item)`  
+  Returns `true` if both key and value exist in the collection.
+
+- **`TryGetValue(TKey key, out TItem value)`**  
+  `bool TryGetValue(TKey key, out TItem value)`  
+  Returns `true` and sets `value` if `key` exists.
+
+- **`CopyTo(KeyValuePair<TKey, TItem>[] array, int arrayIndex)`**  
+  Throws `NotImplementedException`.
+
+- **`GetEnumerator()`**  
+  `IEnumerator<KeyValuePair<TKey, TItem>> GetEnumerator()`  
+  Returns an enumerator over the collection.
+
+- **`IEnumerable.GetEnumerator()`**  
+  Explicit implementation of `IEnumerable.GetEnumerator()`.
+
+---
+
+### `SettingsChangedEventArgs<TKey, TItem> : EventArgs`
+
+#### Constructors
+
+- **`SettingsChangedEventArgs(ChangeSettingType changeType)`**  
+  Initializes with only the `ChangeType`.
+
+- **`SettingsChangedEventArgs(ChangeSettingType changeType, TKey key)`**  
+  Initializes with `ChangeType` and `Key`.
+
+- **`SettingsChangedEventArgs(ChangeSettingType changeType, TKey key, TItem item)`**  
+  Initializes with `ChangeType`, `Key`, and `Item`.
+
+#### Properties
+
+- **`ChangeType`**  
+  `ChangeSettingType ChangeType { get; }`  
+  Type of change (`Add`, `Remove`, `Modified`, or `ClearAll`).
+
+- **`Key`**  
+  `TKey Key { get; }`  
+  Key associated with the change (may be default if `ClearAll`).
+
+- **`Item`**  
+  `TItem Item { get; }`  
+  Value associated with the change (may be default if `Remove` or `ClearAll`).
+
+---
+
+### `ChangeSettingType` Enum
+
+- **`Add = 0`**  
+  A new item was added.
+
+- **`Remove = 1`**  
+  An item was removed.
+
+- **`Modified = 3`**  
+  An existing item’s value was updated.
+
+- **`ClearAll = 4`**  
+  The entire collection was cleared.
+
+---
+
+## 3. Invariants
+
+- **Event Firing**:  
+  - `Add`, `Remove`, and `ClearAll` always fire an event.  
+  - `this[key] = value` *always* fires an event (with `ChangeType.Add`, per implementation—see *Gotchas*).  
+  - Events are fired *after* the underlying dictionary is mutated (i.e., state is consistent at event time).
+
+- **Event Arguments**:  
+  - For `Add`/`Modified`: `Key` and `Item` are non-null/non-default (assuming `TKey`/`TItem` allow it); `ChangeType` is `Add`.  
+  - For `Remove`: `Item` is default (`default(TItem)`); `ChangeType` is `Remove`.  
+  - For `ClearAll`: `Key` and `Item` are default; `ChangeType` is `ClearAll`.
+
+- **No Partial Updates**:  
+  Only full additions, removals, or clears trigger events—no partial or batched updates.
+
+---
+
+## 4. Dependencies
+
+### Dependencies *of* this module:
+- **`System.Collections.Generic`**  
+  Provides `Dictionary<TKey, TItem>`, `ICollection<TKey>`, `ICollection<TItem>`, `IEnumerator<T>`, `IDictionary<TKey, TItem>`.
+- **`System`**  
+  Provides `EventArgs`, `EventHandler<T>`, `NotImplementedException`, `enum`.
+
+### Dependencies *on* this module:
+- **`DataPRO.Core.Settings` namespace**  
+  Used internally by consumers (e.g., `SettingsChangedEventArgs` and `ChangeSettingType` are public and likely used elsewhere in the codebase to handle settings changes).
+
+### Inferred Usage:
+- Likely consumed by UI layers or configuration managers that need to react to settings changes (e.g., saving to disk, updating UI controls).
+
+---
+
+## 5. Gotchas
+
+- **Incorrect `Modified` Event Type**:  
+  The indexer setter (`this[TKey key] { set { ... } }`) fires `ChangeSettingType.Add` instead of `ChangeSettingType.Modified`. This is inconsistent with the semantic meaning of "modify" and may mislead consumers expecting `Modified` for updates.  
+  **Example**:  
+  ```csharp
+  collection["foo"] = "bar"; // Fires Add, not Modified
+  ```
+
+- **`CopyTo` Not Implemented**:  
+  `CopyTo(KeyValuePair<TKey, TItem>[], int)` throws `NotImplementedException`. This violates the `ICollection<KeyValuePair<TKey, TItem>>` contract and may cause runtime failures if used (e.g., via LINQ’s `ToArray()` or `ToList()`).
+
+- **`Contains(KeyValuePair<TKey, TItem>)` Semantics**:  
+  Checks both key *and* value equality. This is stricter than typical dictionary `Contains` behavior (which usually checks only key), and may cause confusion.
+
+- **No Validation on Keys/Values**:  
+  No checks for `null` keys (if `TKey` is a reference type) or duplicate keys—relies on underlying `Dictionary<TKey, TItem>` to throw `ArgumentNullException`/`ArgumentException`.
+
+- **No Thread Safety**:  
+  No synchronization primitives are used. Concurrent access may corrupt state or cause race conditions in event firing.
+
+- **Event Subscribers May Receive Unexpected `Item` Values**:  
+  For `Remove` and `ClearAll`, `Item` is `default(TItem)`. Consumers must not assume `Item` is always meaningful.
+
+- **No `Modified` Event for Direct Assignment**:  
+  Since the indexer uses `Add` semantics, there is no way to distinguish between *adding a new key* and *updating an existing key* via the event—unless the consumer tracks state themselves.
+
+- **Historical Quirk**:  
+  The `ClearAll` event omits `Key` and `Item` (both `default`), while other operations populate them. This is consistent with the enum design but may require special handling in event handlers.
+
+--- 
+
+*Documentation generated from source files only. No external behavior or assumptions beyond the provided code.*