DP44/enriched-partialglm/Common/DTS.Common.Core/Settings.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.Core/Settings/SettingsChangedEventArgs.cs Common/DTS.Common.Core/Settings/SettingsCollection.cs	2026-04-16T11:41:07.381293+00:00	zai-org/GLM-5-FP8	1	e48bcdd1082dba01

Documentation: DTS.Common.Core.Settings

1. Purpose

This module provides an observable dictionary implementation that notifies subscribers when settings change. It consists of SettingsCollection<TKey, TItem>, a generic dictionary wrapper that implements IDictionary<TKey, TItem> and fires events on modifications, and SettingsChangedEventArgs<TKey, TItem>, the event payload describing what changed. This enables reactive patterns where consumers can respond to configuration or settings changes without polling.

---

2. Public Interface

SettingsCollection<TKey, TItem>

A generic dictionary implementation that raises events on mutation.

Event:

• event EventHandler<SettingsChangedEventArgs<TKey, TItem>> CollectionItemPropertyChanged — Fired after any add, remove, modify, or clear operation.

Constructors:

• None explicitly defined; uses default constructor.

Properties:

• ICollection<TKey> Keys { get; } — Returns all keys in the collection. Delegates to internal dictionary.
• ICollection<TItem> Values { get; } — Returns all values in the collection. Delegates to internal dictionary.
• TItem this[TKey key] { get; set; } — Indexer. Getter returns value for key; setter assigns value and fires ChangeSettingType.Add event.
• int Count { get; } — Returns count of items.
• bool IsReadOnly { get; } — Always returns false.

Methods:

• void Add(TKey key, TItem value) — Adds key-value pair; fires ChangeSettingType.Add event.
• void Add(KeyValuePair<TKey, TItem> item) — Adds key-value pair; fires ChangeSettingType.Add event.
• bool ContainsKey(TKey key) — Returns true if key exists.
• bool Contains(KeyValuePair<TKey, TItem> item) — Returns true if both key and value match an entry.
• bool Remove(TKey key) — Removes by key; fires ChangeSettingType.Remove event if successful. Returns success boolean.
• bool Remove(KeyValuePair<TKey, TItem> item) — Removes by key (ignores value); fires ChangeSettingType.Remove event if successful. Returns success boolean.
• bool TryGetValue(TKey key, out TItem value) — Attempts to retrieve value for key.
• void Clear() — Clears all items; fires ChangeSettingType.ClearAll event.
• void CopyTo(KeyValuePair<TKey, TItem>[] array, int arrayIndex) — Throws NotImplementedException.
• IEnumerator<KeyValuePair<TKey, TItem>> GetEnumerator() — Returns enumerator.
• IEnumerator IEnumerable.GetEnumerator() — Returns non-generic enumerator.

---

SettingsChangedEventArgs<TKey, TItem>

Event arguments describing a settings change.

Constructors:

• SettingsChangedEventArgs(ChangeSettingType changeType) — Initializes with change type only.
• SettingsChangedEventArgs(ChangeSettingType changeType, TKey key) — Initializes with change type and key.
• SettingsChangedEventArgs(ChangeSettingType changeType, TKey key, TItem item) — Initializes with change type, key, and item.

Properties:

• ChangeSettingType ChangeType { get; } — The type of change (read-only).
• TKey Key { get; } — The key associated with the change (read-only).
• TItem Item { get; } — The value associated with the change (read-only).

---

ChangeSettingType (enum)

Defines the type of settings change.

Value	Name	Numeric Value
Add	Item added	0
Remove	Item removed	1
Modified	Item modified	3
ClearAll	Collection cleared	4

---

3. Invariants

• Event firing occurs after mutation: Events are fired only after the underlying dictionary has been successfully modified (e.g., Remove fires only if removal succeeded).
• Key and Item properties may be default/uninitialized: Depending on which constructor is used, Key and Item may be default(TKey) or default(TItem) respectively. Consumers should check ChangeType to determine which properties are meaningful.
• IsReadOnly always returns false.
• The internal _items dictionary is never null (initialized at declaration).

---

4. Dependencies

This module depends on:

• System (for EventArgs, EventHandler<T>)
• System.Collections (for IEnumerable)
• System.Collections.Generic (for IDictionary<TKey, TItem>, Dictionary<TKey, TItem>, ICollection<T>, KeyValuePair<TKey, TItem>)

Consumers (inferred):

• Any module requiring observable settings/configuration storage.
• Cannot determine specific consumers from source alone.

---

5. Gotchas

1. Indexer setter uses ChangeSettingType.Add, not Modified: The indexer this[TKey key] setter always fires ChangeSettingType.Add, even when overwriting an existing key. The Modified enum value (3) is never used in this implementation.

2. CopyTo is not implemented: Calling CopyTo(KeyValuePair<TKey, TItem>[] array, int arrayIndex) throws NotImplementedException. This will cause runtime failures if the collection is used with APIs that call CopyTo.

3. Remove(KeyValuePair<TKey, TItem>) ignores the value: The Remove(KeyValuePair<TKey, TItem> item) method only checks and removes by key, ignoring item.Value. This differs from typical IDictionary implementations that verify the value matches before removal.

4. Enum has a gap: ChangeSettingType has values 0, 1, 3, 4 — value 2 is skipped. This may indicate a removed/renamed value or historical artifact.

5. No validation on constructor arguments: SettingsChangedEventArgs constructors do not validate that Key and Item are provided when ChangeType would logically require them (e.g., Add without a key/item).