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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/DataPRO.Core/Settings/SettingsChangedEventArgs.cs DataPRO/DataPRO.Core/Settings/SettingsCollection.cs	2026-04-16T04:27:33.942396+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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:

  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.